Guia de integração do SDK do iOS para profissionais de marketing

Fundo

A partir do iOS 14.5, a coleta do IDFA requer o consentimento do usuário. Na prática, isso significa que o acesso ao IDFA depende do framework de App Tracking Transparency (ATT). Em dispositivos iOS 14+, o SDK usa o framework de ATT para obter acesso ao IDFA do dispositivo. 

Para uma introdução à ATT, consulte princípios da ATT.

Quando a atribuição ocorre usando IDFA, é importante que o IDFA seja enviado na primeira inicialização. Por esse motivo, o SDK fornece outilitáriowaitForATTUserAuthorization.

Visão geral do waitForATTUserAuthorization

waitForATTUserAuthorization permite configurar por quanto tempo o SDK deve adiar o envio de dados para os servidores da AppsFlyer e aguardar o consentimento à ATT.

Quando um usuário inicia o aplicativo, o status do ATT é indeterminado. Durante o timeout waitForATTUserAuthorization:

• O SDK enfileira o evento de abertura do app e eventos in-app consecutivos na memória, semelhante à forma como os eventos offline são gravados.
• Se o usuário der o consentimento na notificação da ATT (coleta de IDFA):
  • O SDK adiciona o IDFA a eventos em cache.
  • O SDK inicia e envia eventos armazenados em cache com IDFA (sem esperar que o tempo limite termine).
• Se o usuário recusar a notificação da ATT:
  • O SDK inicia e envia eventos armazenados em cache sem IDFA (sem esperar que o tempo limite termine).
• Se o tempo limite terminar e o status ATT permanecer not Determined:
  • O SDK inicia e envia eventos armazenados em cache sem IDFA.

considerações

• Chamar requestTrackingAuthorization sem definir waitForAttUserAuthorization resultará em aberturas do app e eventos sendo enviados sem IDFA para dispositivos iOS 14+.
• Se o usuário mover o aplicativo para o background durante o timeout:
  • O temporizador pausa até que o aplicativo volte para o primeiro plano.
  • Os eventos são armazenados em cache na memória.
• Se o usuário desligar o aplicativo/o aplicativo é morto durante o timeout:
  • O temporizador é reiniciado na próxima abertura do aplicativo.
  • Os eventos armazenados em cache são perdidos.

Você pode optar por personalizar o prompt da ATT. Uma mensagem que indica claramente o propósito da solicitação de permissão pode ajudar a aumentar as taxas de opt-in dos usuários.

Observe o seguinte ao criar sua mensagem:

• Use a sequência de palavras que melhor explica aos usuários por que o aplicativo está pedindo o consentimento do usuário.
• Informe aos usuários sobre como seus dados serão usados. Para saber mais sobre privacidade do usuário e uso de dados, clique aqui.

Quando sua mensagem estiver concluída, consulte seu desenvolvedor sobre o texto e sobre essas instruções.

Para ver alguns exemplos externos de prompts de ATT, clique aqui.

A SKADNetwork é uma classe usada pelo iOS que valida instalações de aplicativos impulsionadas por anunciantes. O processo de validação de instalação do aplicativo envolve o aplicativo de origem e o aplicativo anunciado. 

Um aplicativo de fonte é um aplicativo que participa de campanhas publicitárias exibindo anúncios assinados por uma ad network. Configurar seu aplicativo para exibir anúncios não está dentro do escopo do SDK da AppsFlyer. Para configurar, siga as instruções da Apple.

Para o aplicativo anunciado (o aplicativo com o SDK da AppsFlyer) a solução de SKAdNetwork da AppsFlyer usa a SKAdNetwork para fornecer o postback de atribuição enquanto a AppsFlyer coleta, traduz e agrega os dados, mantendo a privacidade do usuário. Quando o aplicativo é iniciado pela primeira vez, a plataforma da AppsFlyer usa a configuração definida pelo profissional de marketing para instruir o SDK como definir o valor de conversão da SKAdNetwork.

Para usar a solução de SKAdNetwork:

• O profissional de marketing precisa configurar a mensuração de SKAdNetwork na AppsFlyer. O desenvolvedor não precisa executar nenhuma tarefa.
• O SDK da AppsFlyer chama automaticamente as APIs de SKAdNetwork necessárias.
• Certifique-se de desativar as chamadas de SKAdNetwork em outros SDKs quando utilizar a AppsFlyer para a atribuição de SKAdNetwork.
• Não há outra ação ou processo de registro exigido pelo desenvolvedor ou pelo profissional de marketing na App Store. 

Para desativar a atribuição de SKAdNetwork, instrua o desenvolvedor a desativá-la no SDK. 

É possível enviar receita com qualquer evento in-app. Certifique-se de usar o parâmetro af_revenue para incluir receita. É o único parâmetro de evento que a AppsFlyer conta como receita real nos dados brutos e no painel. Para obter mais detalhes, clique aqui. 

Para obter instruções de desenvolvedor, consulte Registrar receita.

O SDK da AppsFlyer fornece verificação do servidor para compras in-app. A validação da compra in-app envia automaticamente um evento de compra in-app à AppsFlyer. O envio desse evento cria relatórios de eventos duplicados.

Se seu aplicativo pertence a uma vertical, como viagens, jogos ou e-commerce consulte nossa lista de eventos in-app recomendados por vertical.

Para usuários sem o aplicativo instalado, o OneLink detecta o tipo de dispositivo e o redireciona para o destino correto (por exemplo, Google Play, Apple App Store, loja de aplicativos de terceiros ou página da web). Isso se baseia nas configurações do template do OneLink. Saiba mais

Nota: a detecção e o redirecionamento do dispositivo não exigem o SDK da AppsFlyer. No entanto, o SDK é necessário para deep linking.

Para usuários com o aplicativo instalado, o OneLink abre o aplicativo. Além de abrir o aplicativo, você também pode fazer um deep link com usuários para uma atividade ou página específica dentro do aplicativo. Isso exige que seu desenvolvedor implemente o Unified Deep Linking (UDL).

Observação:

• O UDL requer SDK V6.1+
• Os clientes que já usam o OneLink para deep link podem estar usando o método legado, ao invés do UDL.

Consulte o nosso guia sobre configuração de links diretos com o OneLink.

Para usuários sem o aplicativo instalado, o OneLink detecta o tipo de dispositivo e o redireciona para o destino correto (por exemplo, Google Play, Apple App Store, loja de aplicativos de terceiros ou página da web). Depois que o usuário iniciar o aplicativo, você poderá usar deferred deep linking para redirecioná-los para uma atividade ou página específica dentro do aplicativo.

Isso requer que o desenvolvedor implemente o Unified Deep Linking (UDL).

Observação:

• O UDL requer SDK V6.1+
• Os clientes que já usam o OneLink para deferred deep linking podem estar usando o método legado, ao invés do UDL

Consulte o nosso guia sobre ligação direta adiada para saber mais.

A AppsFlyer suporta a medição de campanhas de notificação por push de todos os fornecedores e também pode oferecer suporte a desenvolvedores que usam o Google Cloud Messaging ou os serviços de notificação por push da Apple diretamente. As conversões, definidas como aberturas de aplicativo originadas de mensagens de notificação por push, são exibidas no painel Retargeting.

Você pode usar o OneLink para medir o reengajamento do usuário por meio de notificações push. Veja nosso guia sobre como medir campanhas de reengajamento por notificação por push.

Para saber como configurar a métrica de desinstalação, leia aqui.

Se você deseja receber uma confirmação de que o SDK foi iniciado com sucesso e notificou os servidores da AppsFlyer, implemente o manipulador startWithCompletionHandler. Você pode aplicar a lógica para lidar com o sucesso ou a falha da inicialização do SDK.

Exemplo de implementação

[[AppsFlyerLib shared] startWithCompletionHandler:^(NSDictionary<NSString *,id> *dictionary, NSError *error) {
        if (error) {
            NSLog(@"%@", error);
            return;
        }
        if (dictionary) {
            NSLog(@"%@", dictionary);
            return;
        }
    }];

 AppsFlyerLib.shared()?.start(completionHandler: { (dictionnary, error) in
            if (error != nil){
                print(error ?? "")
                return
            } else {
                print(dictionnary ?? "")
                return
            }
        })

Se ocorrer um erro durante o ouvinte de solicitação, um código de erro e uma descrição de string são fornecidos, conforme indicado na tabela a seguir.

A API setAdditionalData permite adicionar dados personalizados a eventos enviados pelo SDK. Normalmente, ela é usada para integrar no nível do SDK com várias plataformas externas de parceiros, como Segment, Adobe e Airship.

Exemplo de código setAdditionalData:

NSDictionary* customDataMap = [[NSDictionary alloc] initWithObjectsAndKeys:@"value_of_param_1", @"custom_param_1", nil];
[[AppsFlyerLib shared] setAdditionalData:customDataMap];

let customDataMap: [AnyHashable: Any] = [
  "custom_param_1" : "value_of_param_1"
]
AppsFlyerLib.shared().customData = customDataMap

Os proprietários de aplicativos que usam links universais para links diretos (sem OneLink) e têm um domínio associado ao aplicativo podem atribuir sessões iniciadas por meio desse domínio usando o método appendParametersToDeepLinkingUrl .

Por exemplo, um usuário faz uma pesquisa no Google e clica no seu domínio, www.exemplo.com:

• Se o usuário não tiver o aplicativo instalado, ele será direcionado para o site (www.example.com).
• Se o usuário tiver o aplicativo instalado no seu dispositivo, haverá um link direto para o aplicativo associado com www.exemplo.com. A sessão é atribuída à fonte de mídia (parâmetro pid ) especificada em appendParametersToDeeplinkingUrl.

Consulte a referência do SDK do iOS para obter informações adicionais.

Observação: Smart Banners ajudam os proprietários de aplicativos a converter visitantes do site em usuários do aplicativo.

Por padrão, deve haver um intervalo mínimo de 5 segundos entre duas inicializações de aplicativos para que essas duas sessões sejam contabilizadas separadamente (saiba mais sobre contabilização de sessões).

Use a seguinte API para definir o tempo mínimo entre sessões:

[AppsFlyerLib shared].minTimeBetweenSessions = <your_custom_time_in_seconds>;

AppsFlyerLib.shared().minTimeBetweenSessions = <your_custom_time_in_seconds>

Definir um valor alto para o tempo personalizado entre inicializações pode gerar um impacto negativo nas APIs que dependem dos dados das sessões, como links diretos.

Indisponível no iOS. 

Alguns serviços de terceiros, como provedores de serviços de e-mail, envolvem links em e-mails com seus próprios domínios de gravação de links. Alguns até permitem que você defina seus próprios domínios de gravação de links. Se o OneLink estiver agrupado nesses domínios, poderá limitar sua funcionalidade.

Para superar esse problema, você pode usar a API setResolveDeepLinkURLs. Use esta API para obter o OneLink de domínios de clique que iniciam o aplicativo.  Certifique-se de chamar essa API antes da inicialização do SDK.

Por exemplo, você tem três domínios de clique que redirecionam para o OneLink, que é https://mysubdomain.onelink.me/abCD. Use esta API para obter o OneLink ao qual seus domínios de clique redirecionam.  Este método de API recebe uma lista de domínios que o SDK resolve.

[AppsFlyerLib shared].resolveDeepLinkURLs = @[@"example.com",@"click.example.com"];

AppsFlyerLib.shared().resolveDeepLinkURLs = ["example.com", "click.example.com"]

O código acima permite usar seu domínio de clique, preservando a funcionalidade do OneLink. Os domínios de clique são responsáveis pela inicialização do aplicativo. A API, por sua vez, recebe o Onelink destes domínios de clique e, depois, é possível usar os dados deste Onelink para aplicar links diretos e personalizar o conteúdo do usuário.

Com a AppsFlyer, você pode medir as notificações push como parte de campanhas de redirecionamento.

Para ativar esse recurso, chame o método handlePushNotificationData dentro de AppDelegate.m.

-(void)application:(UIApplication *)application didReceiveRemoteNotification:(NSDictionary *)userInfo fetchCompletionHandler:(void (^)(UIBackgroundFetchResult))completionHandler {
[[AppsFlyerLib shared] handlePushNotification:userInfo];
}

func application(_ application: UIApplication, didReceiveRemoteNotification userInfo: [AnyHashable : Any], fetchCompletionHandler completionHandler: @escaping (UIBackgroundFetchResult) -> Void) {
    AppsFlyerLib.shared().handlePushNotification(userInfo)
}

Para mais informações sobre medição de notificações por push, leia aqui.

Permitir que os usuários existentes convidem seus amigos e contatos como novos usuários para seu aplicativo pode ser um fator de crescimento importante para seu aplicativo. Com a AppsFlyer, você pode atribuir e registrar instalações originadas de convites do usuário em seu aplicativo.

Para obter detalhes, consulte o artigo de atribuição de convite do usuário.

Observação! Promoção cruzada pelo IDFV requer SDK 6.0.2+. O IDFV é coletado automaticamente e nenhuma ação adicional é exigida pelo desenvolvedor.

Uma ID exclusiva da AppsFlyer é criada para cada nova instalação de um aplicativo. Você pode usar esse ID para vários fins:

• Enviar eventos in-app de servidor para servidor.
• Combine-a com os registros de usuário em seus sistemas de back-end.
• Mapear entradas ao mesclar dados das APIs pull e push .

Use a seguinte API para obter a ID exclusiva:

NSString *appsflyerId = [AppsFlyerLib shared].getAppsFlyerUID;

let appsflyerId = AppsFlyerLib.shared().getAppsFlyerUID()

Para definir sua identificação de usuário cliente:

[AppsFlyerLib shared].customerUserID = @"my user id";

AppsFlyerLib.shared().customerUserID = "my user id"

No iOS, o ID de usuário cliente precisa ser definido a cada inicialização do aplicativo. Recomendamos definir o ID de usuário cliente no início do fluxo do aplicativo, pois ele está associado apenas aos eventos relatados após sua configuração:

• Se setCustomerUserID for chamado antes de chamar start, a ID de usuário cliente aparecerá nos relatórios de dados brutos para instalações e eventos.
• Se for definida depois, a ID de usuário cliente será associada apenas a eventos registrados após a configuração da ID de usuário cliente.

Para evitar definir o valor do ID de usuário cliente novamente após a primeira inicialização e reduzir as chamadas para o servidor a fim de obter o ID de usuário cliente, você pode verificar se o valor está vazio ou não, usando:

NSString *customerUserID = [AppsFlyerLib shared].customerUserID;

let customerUserID = AppsFlyerLib.shared().customerUserID

Para mais informações sobre ID de usuário cliente, clique aqui .

É possível atrasar a inicialização do SDK até que o Customer User ID esteja definido. Isso é útil se para você for importante que os dados de instalação e evento contenham seu ID de usuário do cliente.

Implemente o seguinte código:

- (void)applicationDidBecomeActive:(UIApplication *)application {
    NSString *customUserId = [[NSUserDefaults standardUserDefaults] stringForKey:@"customerUserId"]; // Your custom logic of retrieving CUID
    if (customUserId != nil && ![customUserId  isEqual: @""]) {
        [AppsFlyerLib shared].customerUserID = customUserId; // Set CUID in AppsFlyer SDK for this session
        [[AppsFlyerLib shared] start]; // Start
    }
}

func applicationDidBecomeActive(_ application: UIApplication) {
        let customUserId = UserDefaults.standard.string(forKey: "customUserId")  //  your logic to retrieve CUID
        if(customUserId != nil && customUserId != ""){
            AppsFlyerLib.shared().customerUserID = customUserId // Set CUID in AppsFlyer SDK for this session
            AppsFlyerLib.shared().start() // Start
        }
    }

Para saber mais sobre como adiar a inicialização do SDK até que o ID de usuário cliente esteja disponível, acesse aqui.

Você pode querer atrasar a inicialização do SDK e o envio de dados até que o usuário dê consentimento (por exemplo, consentimento do GDPR ou COPPA).

Observação: isso não está relacionado ao ATT introduzido no iOS 14. 

Para atrasar a inicialização do SDK:

1. Impeça que a sessão seja enviada na transição em segundo plano. Em um método sendLaunch() (que é chamado em cada applicationDidBecomeActive, conforme a seção 3.3), quebre a chamada para começar com uma verificação de condição. Por exemplo:
   
   

   -(void)sendLaunch:(UIApplication *)application {
       if (consent_given) { // check the condition
           [[AppsFlyerLib shared] start]; // Start
       }
   }

2. Envie a sessão assim que o motivo do atraso não for mais relevante (logo após alterações da condição). Chame start quando tudo estiver pronto para enviar dados da primeira sessão. Por exemplo:
   
   

   ...
   consent_given = YES; // change the condition
   [[AppsFlyerLib shared] start]; // Start
   ...

Em alguns casos extremos, talvez seja necessário encerrar todos os registros de dados do SDK devido à conformidade legal e de privacidade. Isso pode ser alcançado com a propriedade isStopped. Depois que essa API é definida como verdadeira, o SDK para de funcionar e não se comunica mais com os servidores da AppsFlyer.

Há vários cenários diferentes para a exclusão (opt-out) de usuários. É altamente recomendado seguir as instruções exatas do cenário relevante para seu aplicativo.

[AppsFlyerLib shared].isStopped = true;

AppsFlyerLib.shared().isStopped = true

Em qualquer evento, o SDK pode ser reativado chamando a mesma API passando o valor "false".

Use esta API durante a inicialização do SDK para anonimizar explicitamente as instalações, eventos e sessões de um usuário:

[AppsFlyer shared].anonymizeUser = YES;

AppsFlyerLib.shared().anonymizeUser = true

O registro de dados pode ser reiniciado definindo AnonymizeUser como false.

Use o SDK no modo estrito para remover completamente a funcionalidade de coleta IDFA e as dependências do framework do AdSupport (por exemplo, ao desenvolver aplicativos infantis).

Nota: IDFV permanece disponível.

No seu Podfile, substitua a dependência AppsFlyerLibpor:

pod 'AppsFlyerFramework/Strict','6.2.3'

Para desativar AdSupport e iAd frameworks, o SDK fornece os seguintes configuradores:

• disableCollectASA = true. Saiba mais
• disableAdvertisingIdentifier = true. Saiba mais

Para desabilitar estruturas de anúncio:

[AppsFlyerLib shared].disableCollectASA = YES
[AppsFlyerLib shared].disableAdvertisingIdentifier = YES;

AppsFlyerLib.shared().disableCollectASA = true
AppsFlyerLib.shared().disableAdvertisingIdentifier = true

Em alguns casos, os anunciantes podem querer parar de compartilhar dados no nível do usuário com ad networks/parceiros para determinados usuários. Os motivos para isso incluem: 

• Políticas de privacidade como CCPA ou GDPR
• Mecanismos para o usuário optar por não participar
• Concorrência com alguns parceiros (ad networks, terceiros)

A AppsFlyer fornece dois métodos de API para interromper o compartilhamento de dados com alguns ou todos os parceiros:

• setSharingFilter: usado por anunciantes para impedir o compartilhamento de dados com algumas (uma ou mais) redes/parceiros integrados .
• SetSharingFilterForAllPartners: usado por anunciantes para evitar o compartilhamento de dados com todas as redes/parceiros integrados.

Esses métodos de filtragem possuem suporte a partir do SDK V5.4.1.

O método de filtragem deve ser chamado sempre que o SDK é inicializado e afeta a sessão toda. Se demorar para determinar se você precisa definir os filtros de compartilhamento, atrase a inicialização do SDK. 

Quando o método for ativado antes do primeiro start chame:

• Os usuários de SRNs são atribuídos como orgânicos e seus dados não são compartilhados com parceiros integrados.
• Os usuários de ad networks de cliques (não-SRNs) são atribuídos corretamente na AppsFlyer, mas não são compartilhados com as ad networks por meio de postbacks, APIs, relatórios de dados brutos ou por qualquer outro método.

Atualmente, os dados de desinstalação não podem ser filtrados usando esses métodos. No entanto, você pode parar de enviar eventos de desinstalação para parceiros usando suas páginas de configuraçãona AppsFlyer.