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 Cordova habilita SKAdNetwork por defecto en modo gestionado, donde Singular actualiza automáticamente los valores de conversión basados en el modelo de conversión configurado en el panel de control.

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 configurado en el 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.

// Create configuration
var singularConfig = new cordova.plugins.SingularCordovaSdk.SingularConfig(
  "YOUR_SDK_KEY",
  "YOUR_SDK_SECRET"
);

// Disable SKAdNetwork
singularConfig.withSkAdNetworkEnabled(false);

// Initialize SDK
cordova.plugins.SingularCordovaSdk.init(singularConfig);

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.

// Create configuration with manual SKAN mode
var singularConfig = new cordova.plugins.SingularCordovaSdk.SingularConfig(
  "YOUR_SDK_KEY",
  "YOUR_SDK_SECRET"
);

// Enable manual SKAN conversion management
singularConfig.withManualSkanConversionManagement();

// Initialize SDK
cordova.plugins.SingularCordovaSdk.init(singularConfig);

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.

// Check if running on iOS
if (device.platform === 'iOS') {
  // User completed signup - update conversion value to 7
  function onUserSignUp() {
    // Track the sign-up event
    cordova.plugins.SingularCordovaSdk.event('SignUp');

    // Update SKAN conversion value
    cordova.plugins.SingularCordovaSdk.skanUpdateConversionValue(7, function(success) {
      if (success) {
        console.log('Conversion value updated successfully');
      } else {
        console.warn('Failed to update conversion value');
      }
    });
  }

  // User completed purchase - update based on purchase amount
  function onPurchaseComplete(purchaseAmount) {
    // Track revenue event
    cordova.plugins.SingularCordovaSdk.revenue('USD', purchaseAmount);

    // Calculate conversion value based on purchase tier
    var conversionValue = calculateConversionValue(purchaseAmount);
    cordova.plugins.SingularCordovaSdk.skanUpdateConversionValue(conversionValue, function(success) {
      if (success) {
        console.log('Conversion value updated to: ' + 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 valor fino, valor grueso y parámetros de bloqueo. Esto proporciona un control más granular sobre las actualizaciones de los valores de conversión.

// Check if running on iOS
if (device.platform === 'iOS') {
  function updateSKAN4ConversionValue(fineValue, coarseValue, shouldLock) {
    // Map coarse value string to number
    var coarseMap = { low: 0, medium: 1, high: 2 };

    // Update SKAdNetwork 4.0 conversion values
    cordova.plugins.SingularCordovaSdk.skanUpdateConversionValues(
      fineValue,
      coarseMap[coarseValue],
      shouldLock,
      function(success) {
        if (success) {
          console.log('SKAN 4.0 updated: fine=' + fineValue + ', coarse=' + coarseValue + ', lock=' + shouldLock);
        }
      }
    );
  }

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

  // Example: Premium purchase - lock the value
  function onPremiumPurchase() {
    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.

// Check if running on iOS
if (device.platform === 'iOS') {
  function checkAndUpdateConversionValue() {
    cordova.plugins.SingularCordovaSdk.skanGetConversionValue(function(currentValue) {
      if (currentValue !== null) {
        console.log('Current conversion value: ' + currentValue);

        // Only update if current value is below threshold
        if (currentValue < 30) {
          cordova.plugins.SingularCordovaSdk.skanUpdateConversionValue(30, function(success) {
            if (success) {
              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.

// Create configuration with conversion value handler
var singularConfig = new cordova.plugins.SingularCordovaSdk.SingularConfig(
  "YOUR_SDK_KEY",
  "YOUR_SDK_SECRET"
);

// Set up conversion value update handler
singularConfig.withConversionValueUpdatedHandler(function(conversionValue) {
  console.log('Conversion value updated to: ' + conversionValue);

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

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

// Initialize SDK
cordova.plugins.SingularCordovaSdk.init(singularConfig);

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');
}

Soporte de 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. Añadir a Info.plist: Incluya la clave NSUserTrackingUsageDescription en el archivo Info.plist de su proyecto iOS (ubicado en platforms/ios/[YourAppName]/[YourAppName]-Info.plist).
2. Proporcione una descripción clara: Añade una explicación clara de por qué tu aplicación necesita el permiso de rastreo que se mostrará a los usuarios en el indicador ATT.

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

Paso 2: Instalar el plugin de soporte de la ATT

Instale un plugin Cordova de terceros para habilitar la funcionalidad ATT en su aplicación. El plugin cordova-plugin-tracking-transparency proporciona una interfaz JavaScript para el ATTrackingManager de Apple.

cordova plugin add cordova-plugin-tracking-transparency

Paso 3: Configuración del 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.

// Create configuration with ATT wait timeout
var singularConfig = new cordova.plugins.SingularCordovaSdk.SingularConfig(
  "YOUR_SDK_KEY",
  "YOUR_SDK_SECRET"
);

// Wait up to 5 minutes for ATT consent
singularConfig.withWaitForTrackingAuthorizationWithTimeoutInterval(300);

// Initialize SDK
cordova.plugins.SingularCordovaSdk.init(singularConfig);

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.

document.addEventListener('deviceready', initializeApp, false);

function initializeApp() {
  // Check if running on iOS
  if (device.platform === 'iOS') {
    // Request ATT authorization
    cordova.plugins.idfa.requestPermission().then(function(response) {
      var status = response.tracking;
      console.log('ATT Status:', status);
      // Possible values: 'authorized', 'denied', 'restricted', 'notDetermined'

      // Initialize Singular after ATT prompt
      initializeSingular();
    }).catch(function(error) {
      console.error('ATT Error:', error);
      // Initialize Singular even if ATT fails
      initializeSingular();
    });
  } else {
    // Android - initialize immediately
    initializeSingular();
  }
}

function initializeSingular() {
  // Create configuration with wait timeout
  var singularConfig = new cordova.plugins.SingularCordovaSdk.SingularConfig(
    "YOUR_SDK_KEY",
    "YOUR_SDK_SECRET"
  );

  singularConfig.withWaitForTrackingAuthorizationWithTimeoutInterval(300);
  singularConfig.withLoggingEnabled();

  // Initialize SDK
  cordova.plugins.SingularCordovaSdk.init(singularConfig);
  console.log('Singular SDK initialized');
}

Comprender el flujo

Cuando se establece un retraso en la inicialización, el flujo de la aplicación funciona de la siguiente manera:

1. Se inicia la grabación de la sesión: Cuando se abre la aplicación, Singular SDK comienza a grabar una sesión y los eventos del usuario, pero aún no los envía al servidor de Singular.
2. Espera del consentimiento: El SDK espera a que se conceda/deniegue el consentimiento de App Tracking Transparency, o a que transcurra el tiempo establecido.
3. Transmisión de datos: Una vez resuelto el consentimiento o transcurrido el tiempo establecido, el SDK envía la sesión y cualquier evento en cola al servidor Singular (con o sin el IDFA).
4. Comienza la atribución: Singular inicia entonces el proceso de atribución, aprovechando el IDFA si está disponible.

Escenarios ATT

La siguiente tabla resume los posibles escenarios y la disponibilidad del IDFA:

Buenas prácticas de la ATT

• Mensajes previos: 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 aceptación.
• 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).
• Pruebe a fondo: 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 notDetermined y regístrelo para análisis.
• Integración de SKAN 4.0: Asegúrese de que las actualizaciones de los valores de conversión coinciden con el consentimiento de ATT para optimizar las devoluciones de SKAN (por ejemplo, utilice el panel de Singular para asignar eventos a los valores 0-63).

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