Apoyo a SKAdNetwork

SKAdNetwork es el marco de atribución centrado en la privacidad de Apple para campañas de instalación de aplicaciones iOS. El SDK de Singular React Native habilita SKAdNetwork por defecto en el Modo Administrado, donde Singular actualiza automáticamente los valores de conversión basados en su modelo de conversión configurado en el tablero.

Entendiendo los modos de SKAN

Modo Gestionado (por defecto)

En el modo gestionado, Singular gestiona automáticamente las actualizaciones de los valores de conversión basándose en el modelo de conversión que configure en su panel de control. Este es el enfoque recomendado para la mayoría de las aplicaciones, ya que requiere un código mínimo y proporciona un seguimiento óptimo de las conversiones.

• Actualizaciones automáticas: Singular gestiona todas las actualizaciones de los valores de conversión en función de los eventos del usuario y del modelo configurado.
• Configuración del cuadro de mando: Diseñe su modelo de conversión en el cuadro de mandos de Singular sin cambios en el código.
• Optimización: Benefíciese de la experiencia de Singular para maximizar las actualizaciones del valor de conversión dentro de las restricciones de Apple.
• Gestión de ventanas 24 horas: Singular gestiona la ventana de actualización de 24 horas de SKAdNetwork de forma inteligente para maximizar la recogida de datos.

Modo Manual (Avanzado)

El modo manual le ofrece un control total sobre las actualizaciones de los valores de conversión, permitiéndole implementar una lógica personalizada para determinar cuándo y cómo actualizar los valores de conversión de SKAN. Utilice este modo sólo si tiene requisitos específicos que el Modo Manual no puede cumplir.

Desactivación del soporte SKAdNetwork

El seguimiento de SKAdNetwork está activado por defecto. Para desactivarlo, establezca la propiedad de configuración skAdNetworkEnabled en false cuando construya su objeto SingularConfig.

// TurboModule direct API (React Native 0.76+ New Architecture)
import NativeSingular from 'singular-react-native/jsNativeSingular';

const config: SingularConfig = {
apikey: 'API_KEY',
secret: 'SECRET',
skAdNetworkEnabled: false // Disable SKAdNetwork
};

import { SingularConfig } from 'singular-react-native';

const config = new SingularConfig('API_KEY', 'SECRET')
  .withSkAdNetworkEnabled(false); // Disable SKAdNetwork

Configuración del modo manual

Para implementar una lógica de valores de conversión personalizada, active el modo manual y utilice los métodos del SDK proporcionados para actualizar y supervisar los valores de conversión a lo largo del ciclo de vida de su aplicación.

Activación del modo manual

Establezca la propiedad de configuración manualSkanConversionManagement en true al crear el objeto SingularConfig para tomar el control de las actualizaciones de los valores de conversión.

// TurboModule direct API (React Native 0.76+ New Architecture)
import NativeSingular from 'singular-react-native/jsNativeSingular';

const config: SingularConfig = {
apikey: 'API_KEY',
secret: 'SECRET',
manualSkanConversionManagement: true // Enable manual SKAN conversion mode
};

import { SingularConfig } from 'singular-react-native';

const config = new SingularConfig('API_KEY', 'SECRET')
  .withManualSkanConversionManagement(); // Enable manual mode

Actualizar valor de conversión (SKAN 2.0-3.0)

Utilice el método skanUpdateConversionValue para actualizar manualmente el valor de conversión de SKAdNetwork basándose en su lógica personalizada. El valor de conversión debe ser un número entero comprendido entre 0 y 63.

Firma del método

static skanUpdateConversionValue(conversionValue)

Ejemplo de uso

// TurboModule direct API (React Native 0.76+ New Architecture)
import NativeSingular from 'singular-react-native/jsNativeSingular';
import { Platform } from 'react-native';

// User completed signup - update conversion value to 7
async function onUserSignUp() {
  if (Platform.OS === 'ios') {
    // Track the sign-up event
    NativeSingular.event('SignUp');

    // Update SKAN conversion value
    const success = await NativeSingular.skanUpdateConversionValue(7);

    if (success) {
      console.log('Conversion value updated successfully');
    } else {
      console.warn('Failed to update conversion value');
    }
  }
}

// User completed purchase - update based on purchase amount
async function onPurchaseComplete(purchaseAmount) {
  if (Platform.OS === 'ios') {
    // Track revenue event
    NativeSingular.revenue('USD', purchaseAmount);

    // Calculate conversion value based on purchase tier
    const conversionValue = calculateConversionValue(purchaseAmount);
    await NativeSingular.skanUpdateConversionValue(conversionValue);
  }
}

function calculateConversionValue(amount) {
  // Your custom logic to determine conversion value
  if (amount >= 100) return 63;  // High value
  if (amount >= 50) return 40;   // Medium value
  if (amount >= 10) return 20;   // Low value
  return 10;                      // Minimal value
}

import { Singular } from 'singular-react-native';
import { Platform } from 'react-native';

// User completed signup - update conversion value to 7
async function onUserSignUp() {
  if (Platform.OS === 'ios') {
    // Track the sign-up event
    Singular.event('SignUp');

    // Update SKAN conversion value
    const success = await Singular.skanUpdateConversionValue(7);

    if (success) {
      console.log('Conversion value updated successfully');
    } else {
      console.warn('Failed to update conversion value');
    }
  }
}

// User completed purchase - update based on purchase amount
async function onPurchaseComplete(purchaseAmount) {
  if (Platform.OS === 'ios') {
    // Track revenue event
    Singular.revenue('USD', purchaseAmount);

    // Calculate conversion value based on purchase tier
    const conversionValue = calculateConversionValue(purchaseAmount);
    await Singular.skanUpdateConversionValue(conversionValue);
  }
}

function calculateConversionValue(amount) {
  // Your custom logic to determine conversion value
  if (amount >= 100) return 63;  // High value
  if (amount >= 50) return 40;   // Medium value
  if (amount >= 10) return 20;   // Low value
  return 10;                      // Minimal value
}

Actualizar valores de conversión (SKAN 4.0)

Para iOS 16.1+, utilice el método skanUpdateConversionValues para actualizar los valores de conversión de SKAdNetwork 4.0 con parámetros de valor fino, valor grueso y bloqueo. Esto proporciona un control más granular sobre las actualizaciones de los valores de conversión.

Firma

static skanUpdateConversionValues(
  conversionValue,  // Fine value (0-63)
  coarse,           // Coarse value (0=low, 1=medium, 2=high)
  lock              // Lock status
)

Ejemplo de uso

// TurboModule direct API (React Native 0.76+ New Architecture)
import NativeSingular from 'singular-react-native/jsNativeSingular';
import { Platform } from 'react-native';

async function updateSKAN4ConversionValue(fineValue, coarseValue, shouldLock) {
  if (Platform.OS === 'ios') {
    // Map coarse value string to number
    const coarseMap = { low: 0, medium: 1, high: 2 };

    // Update SKAdNetwork 4.0 conversion values
    await NativeSingular.skanUpdateConversionValues(
      fineValue,
      coarseMap[coarseValue],
      shouldLock
    );

    console.log(`SKAN 4.0 updated: fine=${fineValue}, coarse=${coarseValue}, lock=${shouldLock}`);
  }
}

// Example: High-value user completes tutorial
async function onTutorialComplete() {
  await updateSKAN4ConversionValue(15, 'medium', false);
}

// Example: Premium purchase - lock the value
async function onPremiumPurchase() {
  await updateSKAN4ConversionValue(63, 'high', true);
}

import { Singular } from 'singular-react-native';
import { Platform } from 'react-native';

async function updateSKAN4ConversionValue(fineValue, coarseValue, shouldLock) {
  if (Platform.OS === 'ios') {
    // Map coarse value string to number
    const coarseMap = { low: 0, medium: 1, high: 2 };

    // Update SKAdNetwork 4.0 conversion values
    Singular.skanUpdateConversionValues(
      fineValue,
      coarseMap[coarseValue],
      shouldLock
    );

    console.log(`SKAN 4.0 updated: fine=${fineValue}, coarse=${coarseValue}, lock=${shouldLock}`);
  }
}

// Example: High-value user completes tutorial
async function onTutorialComplete() {
  await updateSKAN4ConversionValue(15, 'medium', false);
}

// Example: Premium purchase - lock the value
async function onPremiumPurchase() {
  await updateSKAN4ConversionValue(63, 'high', true);
}

Obtener valor de conversión actual

Recupera el valor de conversión actual rastreado por Singular SDK. Esto es útil para implementar lógica condicional basada en el estado actual y funciona tanto en modo Gestionado como Manual.

Firma

static skanGetConversionValue()

Ejemplo de uso

// TurboModule direct API (React Native 0.76+ New Architecture)
import NativeSingular from 'singular-react-native/jsNativeSingular';
import { Platform } from 'react-native';

async function checkAndUpdateConversionValue() {
  if (Platform.OS === 'ios') {
    const currentValue = await NativeSingular.skanGetConversionValue();

    if (currentValue !== null) {
      console.log(`Current conversion value: ${currentValue}`);

      // Only update if current value is below threshold
      if (currentValue < 30) {
        await NativeSingular.skanUpdateConversionValue(30);
        console.log('Updated conversion value to 30');
      }
    } else {
      console.warn('Conversion value not available');
    }
  }
}

import { Singular } from 'singular-react-native';
import { Platform } from 'react-native';

async function checkAndUpdateConversionValue() {
  if (Platform.OS === 'ios') {
    const currentValue = await Singular.skanGetConversionValue();

    if (currentValue !== null) {
      console.log(`Current conversion value: ${currentValue}`);

      // Only update if current value is below threshold
      if (currentValue < 30) {
        await Singular.skanUpdateConversionValue(30);
        console.log('Updated conversion value to 30');
      }
    } else {
      console.warn('Conversion value not available');
    }
  }
}

Supervisar actualizaciones del valor de conversión

Configure un controlador para recibir notificaciones en tiempo real cada vez que cambie el valor de conversión. Esto le permite reaccionar a las actualizaciones del valor de conversión y registrar análisis o activar otros comportamientos de la aplicación.

Configuración

Configure el controlador de actualización del valor de conversión utilizando el método withConversionValueUpdatedHandler al inicializar el SDK.

// TurboModule direct API (React Native 0.76+ New Architecture)
import NativeSingular from 'singular-react-native/jsNativeSingular';
import { NativeEventEmitter } from 'react-native';

const config: SingularConfig = {
  apikey: 'API_KEY',
  secret: 'SECRET'
};

NativeSingular.init(config);

const emitter = new NativeEventEmitter(NativeSingular);

// Listen for conversion value updates
emitter.addListener('ConversionValueUpdatedHandler', (conversionValue) => {
  console.log(`Conversion value updated to: ${conversionValue}`);

  // Log the update to your analytics
  logConversionValueUpdate(conversionValue);

  // Trigger app-specific behavior
  if (conversionValue >= 50) {
    unlockPremiumFeature();
  }
});

function logConversionValueUpdate(value) {
  // Your analytics logging logic
  console.log(`Analytics: SKAN CV = ${value}`);
}

function unlockPremiumFeature() {
  // Your custom logic
  console.log('Premium feature unlocked based on high conversion value');
}

import { Singular, SingularConfig } from 'singular-react-native';

const config = new SingularConfig('API_KEY', 'SECRET')
  .withConversionValueUpdatedHandler((conversionValue) => {
    console.log(`Conversion value updated to: ${conversionValue}`);

    // Log the update to your analytics
    logConversionValueUpdate(conversionValue);

    // Trigger app-specific behavior
    if (conversionValue >= 50) {
      unlockPremiumFeature();
    }
  });

Singular.init(config);

function logConversionValueUpdate(value) {
  // Your analytics logging logic
  console.log(`Analytics: SKAN CV = ${value}`);
}

function unlockPremiumFeature() {
  // Your custom logic
  console.log('Premium feature unlocked based on high conversion value');
}

Compatibilidad con App Tracking Transparency (ATT)

App Tracking Transparency (ATT) es el marco de privacidad de Apple que requiere el consentimiento del usuario antes de acceder al IDFA (identificador para anunciantes) del dispositivo y compartir los datos del usuario. Implementar ATT correctamente es fundamental para la atribución de iOS y maximizar la precisión de sus campañas de adquisición de usuarios.

Por qué la ATT es importante para la atribución

A partir de iOS 14.5, las apps deben solicitar permiso al usuario a través del marco ATT antes de acceder al IDFA. Aunque la atribución sigue siendo posible sin el IDFA utilizando métodos de huella digital y probabilísticos, disponer del IDFA mejora significativamente la precisión de la atribución y proporciona una correspondencia determinista.

• Atribución determinista: El IDFA permite una atribución precisa a nivel de dispositivo que conecta directamente las impresiones publicitarias con las instalaciones.
• Optimización de la red publicitaria: Las redes publicitarias pueden optimizar mejor las campañas y proporcionar informes más precisos con el acceso al IDFA.
• Información a nivel de usuario: El acceso al IDFA permite un análisis más granular del comportamiento del usuario y el seguimiento de cohortes.

Requisitos de implementación

Para iOS 14.5+ (incluido iOS 18), utilice el framework ATTrackingManager para solicitar el consentimiento del usuario antes de acceder al IDFA para el seguimiento. El SDK de Singular es compatible con ATT, permitiendo la inicialización antes del consentimiento y retrasando los eventos hasta que se concede el consentimiento o se produce un tiempo de espera.

Paso 1: Añadir configuración del marco ATT

Configure su aplicación iOS para que admita el marco ATT actualizando su archivo Info.plist con una descripción de uso orientada al usuario.

1. Abra Info.plist: Vaya al archivo Info.plist de su proyecto iOS (ubicado en ios/[YourAppName]/Info.plist).
2. Añade la descripción de uso: Añade la clave NSUserTrackingUsageDescription con una explicación clara de por qué tu aplicación necesita el permiso de seguimiento.

<key>NSUserTrackingUsageDescription</key>
<string>This app uses tracking to provide personalized ads and improve your experience.</string>

Paso 2: Instalar el paquete de soporte de la ATT

Instale el paquete de soporte ATT de React Native para habilitar la funcionalidad ATT en su aplicación.

npm install react-native-tracking-transparency --save

Después de la instalación, ejecute pod install desde su directorio iOS para vincular las dependencias nativas.

cd ios && pod install && cd ..

Paso 3: Configurar el tiempo de espera del SDK

Configure el SDK Singular para esperar la respuesta ATT del usuario antes de inicializar estableciendo la propiedad waitForTrackingAuthorizationWithTimeoutInterval. Este retraso asegura que el IDFA es capturado si el usuario concede el permiso.

// TurboModule direct API (React Native 0.76+ New Architecture)
import NativeSingular from 'singular-react-native/jsNativeSingular';

const config: SingularConfig = {
  apikey: 'API_KEY',
  secret: 'SECRET',
  waitForTrackingAuthorizationWithTimeoutInterval: 300 // Wait up to 5 minutes
};

import { SingularConfig } from 'singular-react-native';

const config = new SingularConfig('API_KEY', 'SECRET')
  .withWaitForTrackingAuthorizationWithTimeoutInterval(300); // Wait up to 5 minutes

Paso 4: Solicitar el consentimiento ATT

Implemente el flujo de solicitud de ATT en su aplicación, solicitando a los usuarios el permiso de seguimiento en el momento adecuado de su experiencia de usuario.

// TurboModule direct API (React Native 0.76+ New Architecture)
import React, { useEffect } from 'react';
import { Platform } from 'react-native';
import NativeSingular from 'singular-react-native/jsNativeSingular';
import { requestTrackingPermission } from 'react-native-tracking-transparency';

export default function App() {
  useEffect(() => {
    initializeApp();
  }, []);

  async function initializeApp() {
    if (Platform.OS === 'ios') {
      // Request ATT authorization
      const trackingStatus = await requestTrackingPermission();

      // Log the user's response
      console.log('ATT Status:', trackingStatus);
      // Possible values: 'authorized', 'denied', 'restricted', 'unavailable'
    }

    // Initialize Singular SDK (configured with wait timeout)
    const config: SingularConfig = {
      apikey: 'API_KEY',
      secret: 'SECRET',
      waitForTrackingAuthorizationWithTimeoutInterval: 300,
      loggingEnabled: true,
    };

    NativeSingular.init(config);
  }

  return (
    // Your app components go here
    null
  );
}

import React, { useEffect } from 'react';
import { Platform } from 'react-native';
import { Singular, SingularConfig } from 'singular-react-native';
import { requestTrackingPermission, getTrackingStatus } from 'react-native-tracking-transparency';

export default function App() {
  useEffect(() => {
    initializeApp();
  }, []);

  async function initializeApp() {
    if (Platform.OS === 'ios') {
      // Request ATT authorization
      const trackingStatus = await requestTrackingPermission();

      // Log the user's response
      console.log('ATT Status:', trackingStatus);
      // Possible values: 'authorized', 'denied', 'restricted', 'unavailable'
    }

    // Initialize Singular SDK (configured with wait timeout)
    const config = new SingularConfig('API_KEY', 'SECRET')
      .withWaitForTrackingAuthorizationWithTimeoutInterval(300)
      .withLoggingEnabled();

    Singular.init(config);
  }

  return (
    // Your app components
  );
}

Mejores prácticas de la ATT

• Mensajes previos a la solicitud: Muestre a los usuarios una pantalla previa a la ATT en la que se explique por qué necesita el permiso de seguimiento y en qué les beneficia (mejores anuncios, mejor experiencia). Esto puede aumentar significativamente las tasas de opt-in.
• El momento es importante: Muestre la solicitud de TCA en un momento natural del flujo de la aplicación, no inmediatamente después del lanzamiento. Deje que los usuarios experimenten primero su aplicación para generar confianza.
• Configuración del tiempo de espera: Configure waitForTrackingAuthorizationWithTimeoutInterval entre 30 y 300 segundos. Una vez transcurrido el tiempo de espera, Singular procede con la atribución SKAN 4.0 (sin IDFA).
• Realice pruebas exhaustivas: Pruebe tanto las situaciones autorizadas como las denegadas para asegurarse de que su aplicación funciona correctamente independientemente de la elección del usuario.
• Respete la elección del usuario: Nunca pregunte repetidamente a los usuarios que han denegado el seguimiento ni muestre mensajes agresivos que les presionen para que acepten.
• Gestión de errores: Compruebe el estado del seguimiento en restricted (por ejemplo, controles parentales) o en unavailable y regístrelo para su análisis.

Recursos adicionales

• Documentación del marco de transparencia de seguimiento de aplicaciones de Apple
• Prácticas de Opt-In y Opt-Out del SDK de Singular
• Directrices de Apple sobre privacidad del usuario y uso de datos
• Guía SKAdNetwork de Singular