Suporte a SKAdNetwork

SKAdNetwork é a estrutura de atribuição focada na privacidade da Apple para campanhas de instalação de aplicativos iOS. O Singular SDK do Cordova habilita a SKAdNetwork por padrão no Modo Gerenciado, onde o Singular atualiza automaticamente os valores de conversão com base no modelo de conversão configurado no painel.

Entendendo os modos SKAN

Modo gerenciado (padrão)

No Managed Mode, o Singular lida automaticamente com as atualizações do valor de conversão com base no modelo de conversão configurado no painel. Esta é a abordagem recomendada para a maioria das aplicações, uma vez que requer um código mínimo e fornece um rastreamento de conversão ideal.

• Atualizações automáticas: O Singular gerencia todas as atualizações de valores de conversão com base nos eventos do usuário e no seu modelo configurado.
• Configuração do painel: Projete seu modelo de conversão no dashboard do Singular sem alterações de código.
• Otimização: Beneficie-se da experiência da Singular em maximizar as atualizações do valor de conversão dentro das restrições da Apple.
• Gestão de janelas 24 horas: A Singular gere de forma inteligente a janela de atualização de 24 horas da SKAdNetwork para maximizar a recolha de dados.

Modo manual (avançado)

O Modo manual oferece controle total sobre as atualizações de valores de conversão, permitindo implementar uma lógica personalizada para determinar quando e como atualizar os valores de conversão do SKAN. Utilize este modo apenas se tiver requisitos específicos que o Modo Gerido não possa cumprir.

Desativar o suporte de SKAdNetwork

O rastreio de SKAdNetwork está ativado por predefinição. Para o desativar, defina a propriedade de configuração skAdNetworkEnabled como false ao criar o 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);

Configurando o modo manual

Para implementar uma lógica de valor de conversão personalizada, active o Modo manual e utilize os métodos SDK fornecidos para atualizar e monitorizar os valores de conversão ao longo do ciclo de vida da aplicação.

Ativar o Modo manual

Defina a propriedade de configuração manualSkanConversionManagement como true ao criar seu objeto SingularConfig para assumir o controle das atualizações de valores de conversão.

// 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);

Atualizar valor de conversão (SKAN 2.0-3.0)

Utilize o método skanUpdateConversionValue para atualizar manualmente o valor de conversão SKAdNetwork com base na sua lógica personalizada. O valor de conversão deve ser um número inteiro entre 0 e 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
  }
}

Atualizar valores de conversão (SKAN 4.0)

Para iOS 16.1+, utilize o método skanUpdateConversionValues para atualizar os valores de conversão SKAdNetwork 4.0 com parâmetros de valor fino, valor grosso e bloqueio. Isto proporciona um controlo mais granular sobre as actualizações dos valores de conversão.

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

Obter valor de conversão atual

Recupera o valor de conversão atual monitorizado pelo Singular SDK. Isso é útil para implementar a lógica condicional com base no estado atual e funciona nos modos Gerenciado e 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');
      }
    });
  }
}

Monitorar atualizações de valor de conversão

Configure um manipulador para receber notificações em tempo real sempre que o valor de conversão for alterado. Isto permite-lhe reagir às actualizações do valor de conversão e registar análises ou desencadear outros comportamentos da aplicação.

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

Suporte ao App Tracking Transparency (ATT)

O App Tracking Transparency (ATT) é a estrutura de privacidade da Apple que exige o consentimento do usuário antes de acessar o IDFA (Identificador para Anunciantes) do dispositivo e compartilhar dados do usuário. A implementação correta da ATT é fundamental para a atribuição do iOS e para maximizar a precisão das suas campanhas de aquisição de utilizadores.

Por que a ATT é importante para a atribuição

A partir do iOS 14.5, os aplicativos devem solicitar permissão do usuário por meio da estrutura ATT antes de acessar o IDFA. Embora a atribuição ainda seja possível sem o IDFA usando impressão digital e métodos probabilísticos, ter o IDFA melhora significativamente a precisão da atribuição e fornece correspondência determinística.

• Atribuição determinística: O IDFA permite uma atribuição precisa, ao nível do dispositivo, que liga as impressões de anúncios diretamente às instalações.
• Otimização da rede de anúncios: As redes de anúncios podem otimizar melhor as campanhas e fornecer relatórios mais precisos com o acesso ao IDFA.
• Informações ao nível do utilizador: O acesso ao IDFA permite uma análise mais granular do comportamento do utilizador e um acompanhamento de coortes.

Requisitos de implementação

Para iOS 14.5+ (incluindo iOS 18), use a estrutura ATTrackingManager para solicitar o consentimento do usuário antes de acessar o IDFA para rastreamento. O SDK Singular é compatível com ATT, permitindo a inicialização antes do consentimento e atrasando eventos até que o consentimento seja concedido ou ocorra um tempo limite.

Etapa 1: Adicionar configuração de estrutura ATT

Configure seu aplicativo iOS para oferecer suporte à estrutura ATT atualizando seu arquivo Info.plist com uma descrição de uso voltada para o usuário.

1. Adicionar a Info.plist: Inclua a chave NSUserTrackingUsageDescription no ficheiro Info.plist do seu projeto iOS (localizado em platforms/ios/[YourAppName]/[YourAppName]-Info.plist).
2. Fornecer uma descrição clara: Adicione uma explicação clara do motivo pelo qual a sua aplicação necessita de permissão de rastreio que será apresentada aos utilizadores no prompt ATT.

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

Etapa 2: instalar o plug-in de suporte da ATT

Instale um plug-in Cordova de terceiros para ativar a funcionalidade ATT na sua aplicação. O plug-in cordova-plugin-tracking-transparency fornece uma interface JavaScript para o ATTrackingManager da Apple.

cordova plugin add cordova-plugin-tracking-transparency

Etapa 3: Configurar o tempo limite de espera do SDK

Configure o SDK Singular para aguardar a resposta ATT do usuário antes de inicializar, definindo a propriedade waitForTrackingAuthorizationWithTimeoutInterval. Esse atraso garante que o IDFA seja capturado se o usuário conceder permissão.

// 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);

Passo 4: Pedir o consentimento da ATT

Implemente o fluxo de pedido ATT na sua aplicação, solicitando aos utilizadores a permissão de rastreio num momento adequado da sua experiência de utilizador.

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

Compreender o fluxo

Quando você define um atraso de inicialização, o fluxo do aplicativo funciona da seguinte maneira:

1. A gravação da sessão é iniciada: Quando o aplicativo é aberto, o Singular SDK começa a gravar uma sessão e os eventos do usuário, mas ainda não os envia para o servidor Singular.
2. Aguardando consentimento: O SDK aguarda que o consentimento do App Tracking Transparency seja concedido/negado ou que o tempo definido termine.
3. Transmissão de dados: Depois que o consentimento é resolvido ou o tempo limite ocorre, o SDK envia a sessão e todos os eventos em fila para o servidor Singular (com ou sem o IDFA).
4. Início da atribuição: O Singular inicia então o processo de atribuição, aproveitando o IDFA, se estiver disponível.

Cenários ATT

A tabela a seguir resume os cenários possíveis e a disponibilidade do IDFA:

Melhores práticas da ATT

• Mensagens de pré-prompt: Mostre aos utilizadores um ecrã pré-ATT que explique por que razão necessita de permissão de rastreio e como isso os beneficia (melhores anúncios, melhor experiência). Isto pode aumentar significativamente as taxas de aceitação.
• O momento é importante: Mostre o aviso de ATT num momento natural do fluxo da aplicação, e não imediatamente no primeiro lançamento. Deixe que os utilizadores experimentem a sua aplicação primeiro para criar confiança.
• Configuração do tempo limite: Defina waitForTrackingAuthorizationWithTimeoutInterval para 30-300 segundos. Após o tempo limite, o Singular prossegue com a atribuição SKAN 4.0 (sem IDFA).
• Teste minuciosamente: Teste cenários autorizados e negados para garantir que seu aplicativo funcione corretamente, independentemente da escolha do usuário.
• Respeitar a escolha do utilizador: Nunca solicite repetidamente aos utilizadores que tenham negado o rastreio ou mostre mensagens agressivas que os pressionem a aceitar.
• Tratamento de erros: Verifique o estado do rastreio para restricted (por exemplo, controlos parentais) ou notDetermined e registe para análise.
• Integração do SKAN 4.0: Certifique-se de que as actualizações do valor de conversão estão alinhadas com o consentimento da ATT para otimizar os postbacks do SKAN (por exemplo, utilize o dashboard da Singular para mapear eventos para os valores 0-63).

Recursos adicionais

• Documentação da estrutura de transparência de rastreamento de aplicativos da Apple
• Práticas de ativação e desativação do SDK da Singular
• Diretrizes de privacidade do usuário e uso de dados da Apple
• Guia SKAdNetwork da Singular