Integração básica do SDK

Visão geral: trabalhe com seu desenvolvedor de aplicativo mobile ou CTV para integrar e instalar o SDK em aplicativos Android ou iOS. Depois que as tarefas básicas de integração forem concluídas, seu aplicativo estará pronto para atribuição de instalação e métrica de eventos in-app.   

 Leitura relacionada

Para uma visão completa do planejamento da integração do SDK com seu aplicativo, leia estes artigos:

Recuperando a chave do desenvolvedor

Antes que seu desenvolvedor possa instalar e integrar o SDK, você deve recuperar a chave do desenvolvedor. A AppsFlyer usa a chave do desenvolvedor para identificar exclusivamente sua conta. A chave do desenvolvedor é obrigatória porque permite que o SDK envie e recupere de maneira segura os dados que pertencem à sua conta.

Para recuperar sua chave do desenvolvedor:

  1. Na AppsFlyer, acesse Configurações > Configurações do aplicativo
  2. Copie sua chave do desenvolvedor e envie-a para o desenvolvedor mobile.

    af_devkey.png

  3. Forneça ao seu desenvolvedor mobile as instruções para instalar e integrar o SDK.

Por onde começar o SDK?

Ao planejar a integração do SDK da AppsFlyer, a primeira decisão que você deve tomar é onde iniciar e começar o SDK no fluxo de inicialização do aplicativo.

A regra básica é fazer com que o SDK comece a enviar dados o mais rápido possível após inicializar o aplicativo.Isso garante que o SDK capture o evento de instalação e todos os outros eventos in-app que ocorrem na sessão.

No entanto, para cumprir os regulamentos de privacidade, como GDPR e CCPA, muitas vezes é necessário atrasar o envio de dados para a AppsFlyer até que os usuários consintam em compartilhar suas informações.

Iniciando o SDK no Android

Selecione em qual classe iniciar o SDK

Selecione se deseja iniciar o SDK na classe Application global ou na classe Activity:

  • Comece o SDK na classe Application global: Geralmente, inicializar o SDK na classe/subclasse Application global é uma boa prática porque a classe Application é carregada e inicializada antes de qualquer interface do usuário do aplicativo ser exibida. Isso garante que o SDK possa começar em qualquer cenário, incluindo deep linking.
  • Comece o SDK em uma classe Activity (início adiado) para permitir que os usuários aceitem o compartilhamento de dados. Isso ocorre porque a obtenção do consentimento do usuário requer uma interface do usuário (IU) renderizada em uma classe Activity.

Selecione o cenário optar por participar/não participar

Selecione um cenário de optar por não participar descrevendo como chamar start de maneira que esteja em conformidade com os regulamentos de privacidade, como GDPR e CCPA. Por exemplo, selecione entre um cenário de optar por não participar na instalação, um cenário de optar por não participar único ou um cenário de prevenção de compartilhamento de dados com terceiros.

Para obter mais informações sobre os cenários de optar por não participar disponíveis, incluindo exemplos de código, consulte Cenários de optar por participar/não participar.

Instruções para o desenvolvedor Android

Começando o SDK no iOS

Atrase o início do SDK no iOS

Uma consideração importante ao planejar como começar o SDK é atrasar start até que o consentimento do usuário seja concedido.

O SDK fornece o método waitForATTUserAuthorization , que permite configurar quanto tempo o SDK deve esperar pelo consentimento do usuário antes de enviar dados para os servidores da AppsFlyer.

Para obter mais informações sobre o fluxo de dados do método e sua interação com a estrutura ATT do iOS, consulte a seção de suporte Configurar o App Tracking Transparency (ATT).

Selecione o cenário optar por participar/não participar

Selecione um cenário de optar por não participar descrevendo como chamar start de maneira que esteja em conformidade com os regulamentos de privacidade, como GDPR e CCPA. Por exemplo, selecione entre o cenário de optar por não participar na instalação, o cenário de optar por não participar único ou o cenário de prevenção de compartilhamento de dados com terceiros.

Para obter mais informações sobre os diferentes cenários de exclusão disponíveis, consulte Cenários de optar por participar/não participar.

Instruções para o desenvolvedor iOS

Compartilhe com seu desenvolvedor as seguintes informações:

Atribuição

O SDK coleta identificadores para fins de atribuição.Para garantir que as instalações sejam registradas e atribuídas corretamente, analise e siga estas diretrizes. 

Todas as plataformas

Identificador exclusivo para instalações 

Um ID da AppsFlyer é criado automaticamente para cada nova instalação de aplicativo. Nenhuma ação é exigida pelo profissional de marketing.

Você pode usar esse identificador para realizar as seguintes ações:

Integre identificadores exclusivos de seu sistema de BI com a AppsFlyer

Defina seu próprio ID de usuário do cliente (CUID) no SDK da AppsFlyer para fazer referência cruzada do ID exclusivo do seu sistema de BI com o ID da AppsFlyer e outros identificadores. O CUID está disponível nos relatórios de dados brutos da AppsFlyer. Você também pode usá-lo em APIs de postback para fazer referência cruzada com seus IDs internos. 

Consulte as instruções do desenvolvedor para implementar o CUID.

Somente Android

As seções a seguir descrevem considerações de atribuição para a Google Play Store ou lojas de aplicativos de terceiros.

Aplicativos de atributo publicados no Google Play 

Referenciador de instalação do Google Play

A API do Referenciador da instalações do Google Play melhora a precisão da atribuição, protege contra fraudes de instalação e permite a recuperação segura de dados de referência do Google Play (por exemplo, a versão do aplicativo no momento em que o aplicativo foi instalado pela primeira vez). 

É recomendável que você forneça ao desenvolvedor instruções para adicionar a API do Referenciador da instalação do Google Play

GAID

A partir do SDK V4.8.0, a AppsFlyer coleta automaticamente esse identificador de dispositivo.

Atribuir aplicativos em lojas de aplicativos de terceiros

Com a AppsFlyer, você pode atribuir instalações originadas de lojas de aplicativos de terceiros, como Amazon, Opera, GetJar, Baidu e Huawei. Isso permite que você promova seus aplicativos e alcance públicos maiores em mercados onde a Google Play Store não está disponível.

A AppsFlyer é compatível com a atribuição no contexto de lojas de aplicativos de terceiros da seguinte forma:

  • IMEI ou Android ID: O SDK não coleta automaticamente o IMEI ou ID do Android. No entanto, se houver necessidade de coletar esses identificadores (por exemplo, para aplicativos no mercado doméstico chinês), seu desenvolvedor poderá implementar um dos seguintes tipos de coleção:
    • Coleção manual: o aplicativo passa o IMEI ou o ID do Android para o SDK (usando a API setImeiData ou setAndroidData). O SDK envia os dados para servidores da AppsFlyer. 
    • Aceitar coleta de ID do dispositivo: força o SDK a coletar o IMEI ou o ID do Android
  • OAID: atribui instalações de lojas de aplicativos de terceiros Android. Para mais informações, veja o guia de implementação do OAID.
  • Referenciadores de instalação: o SDK é compatível com a recuperação de dados de referência da Samsung Gallery e da Huawei AppGallery.

Somente iOS

As seções a seguir incluem informações importantes sobre o suporte para dispositivos iOS 14+.

Configurar o suporte para transparência de rastreamento de aplicativos (ATT)

Fundo

A partir do iOS 14.5, a coleta do IDFA requer o consentimento do usuário. Praticamente, isso significa que o acesso ao IDFA é regido pela estrutura de transparência de rastreamento de aplicativos (ATT). Em dispositivos iOS 14+, o SDK usa a estrutura ATT para obter acesso ao IDFA do dispositivo. 

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

Quando a atribuição ocorre usando o IDFA, é importante que o IDFA seja enviado no primeiro lançamento. Por esse motivo, o SDK fornece o utilitário WaitForATTUserAuthorization.

Visão geral do waitForATTUserAuthorization

 Importante!

Não chame waitForAttUserAuthorization se você não pretende invocar o prompt ATT.

waitForATTUserAuthorization permite configurar quanto tempo o SDK deve adiar e aguardar o status ATT antes de enviar dados para os servidores da AppsFlyer.

ATT-flowchart_en-us.png

Quando um usuário inicia o aplicativo, o status do ATT é notDetermined. Durante o tempo limite waitForATTUserAuthorization, o SDK enfileira o evento de inicialização e os eventos in-app consecutivos na memória, semelhante à maneira como os eventos off-line são registrados:

  • 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 o prompt ATT: o SDK inicia e envia eventos em cache sem IDFA (sem aguardar o tempo limite terminar).
  • Se o tempo limite terminar e o status ATT permanecer notDetermined: o SDK inicia e envia eventos em cache sem o 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, ele será eliminado durante o tempo limite:
    • O temporizador é reiniciado na próxima abertura do aplicativo.
    • Os eventos armazenados em cache são perdidos.

Personalizar caixa de diálogo de consentimento à ATT

Você pode personalizar o prompt da ATT. Uma mensagem que indica claramente o propósito da solicitação pode ajudar a aumentar as taxas de aceitação para os usuários.

Considere o seguinte ao criar sua mensagem:

Quando sua mensagem estiver concluída, forneça ao desenvolvedor o texto e as instruções de implementação.

Veja alguns exemplos externos de prompts da ATT.

Suporte para atribuição SKAN

 Observação

Para oferecer suporte total à atribuição da SKAN, atualize para o iOS SDK V6.2.3+.

SKAN é uma classe usada pelo iOS para validar instalações de aplicativos orientadas por anunciantes. O processo de validação da instalação do aplicativo envolve o aplicativo de origem e o aplicativo anunciado. 

Um aplicativo de origem é um aplicativo que participa de campanhas publicitárias exibindo anúncios de 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 para a SKAN da Appsflyer usa a SKAN 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 sobre como definir o valor de conversão da SKAN.

Para usar a solução da SKAN:

  • O profissional de marketing precisa configurar a mensuração da SKAN na AppsFlyer. O desenvolvedor não precisa realizar nenhuma tarefa.
  • O SDK da AppsFlyer automaticamente chama as APIs de SKAN necessárias.
  • Certifique-se de desativar as chamadas SKAN em outros SDKs se você confiar na AppsFlyer para atribuição SKAN.
  • 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 da SKAN, instrua o desenvolvedor a desativá-la no SDK

Gravação de eventos in-app

Eventos in-app (IAE) oferecem insights sobre o que está acontecendo em seu aplicativo. A gravação de eventos in-app ajuda a medir KPIs como retorno sobre o investimento (ROI) e Lifetime Value (LTV). Recomendamos que você separe um momento para definir os eventos que deseja gravar.

Depois de determinar os eventos no aplicativo que você deseja medir, envie os nomes e parâmetros do evento para o desenvolvedor e inclua um link para as instruções de implementação

Para saber mais sobre eventos in-app, consulte nosso Guia de eventos avançados dentro do aplicativo.

Todas as plataformas

Gravação de receita

É 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 no painel e em relatórios de dados brutos. Saiba mais.

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

Valide compras in-app

O SDK da AppsFlyer oferece verificação do servidor para compras in-app. A validação da compra in-app envia automaticamente um evento de compra in-app à AppsFlyer. Ao enviar este evento você mesmo cria relatórios de eventos duplicados.

Verticais da indústria

Veja nossa lista de eventos in-app recomendados por vertical, por exemplo, viagens, jogos ou e-commerce.

Links diretos com OneLink

O OneLink é a solução da AppsFlyer para atribuição em várias plataformas, redirecionamento e links diretos.

Todas as plataformas

Detecção e redirecionamento de dispositivos

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

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 nosso guia sobre como configurar deep links e deferred deep linking.

Deferred Deep Linking

Para usuários sem o aplicativo instalado, o OneLink detecta o tipo de dispositivo e os redireciona para o destino correto: 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 seu desenvolvedor implemente deferred deep linking estendidos.

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 nosso guia sobre como configurar deep links e deferred deep linking.

Acessando dados de atribuição e deep linking

A tabela a seguir descreve os métodos disponíveis para recuperar dados de atribuição e deep linking:

Método Quem está envolvido? Resultados do retorno Método de recuperação Dados de atribuição Dados de links diretos Disponibilidade
API de push
  • Profissional de marketing
  • Desenvolvedor back-end
Normalmente em minutos Back-end S N Premium
Pull API
  • Profissional de marketing
  • Desenvolvedor back-end
  • Periódico (não em tempo real).
  • Você pode agendar downloads de relatórios de dados brutos. 
Back-end S S Premium para relatórios de dados brutos
Data Locker
  • Profissional de marketing
  • Desenvolvedor back-end

Os relatórios por hora estão disponíveis dentro de 1 a 3 horas

Armazenamento na nuvem através de uma das seguintes opções:

  • Bucket próprio da AppsFlyer no AWS
  • Armazenamento de sua propriedade (AWS ou GCS)
S S Premium
Obter dados de conversão (GCD) 
  • Profissional de marketing
  • Desenvolvedor mobile

Veja a documentação do desenvolvedor

Até 5 segundos  SDK S S Todas as contas
Unified Deep Linking (UDL)
  • Profissional de marketing
  • Desenvolvedor de dispositivos mobile

Veja a documentação do desenvolvedor

Até 1 segundo SDK N S Todas as contas

Observe o seguinte para usuários que não deram o consentimento do iOS 14.5+:

  • Ao usar UDL para mídias pagas e próprias, os dados de deep linking estão disponíveis.
  • Ao usar o GCD para mídias pagas, os dados são limitados e não incluem detalhes de atribuição e deep linking.

 Dica

Recomendamos o seguinte:

  • Use a Push API para recuperar dados de atribuição e enviá-los para seus servidores para processamento posterior. Esse método aguarda que os dados se tornem disponíveis e, portanto, é muito preciso e próximo do tempo real. O GCD retorna dados em tempo real, mas pode ser impreciso quando as decisões finais de atribuição são determinadas após mais de 5 segundos.
  • Use a Pull API para complementar periodicamente (por exemplo, diariamente) dados de atribuição em tempo real e para compensar quaisquer erros de comunicação que possam ocorrer.

testar sua integração com o SDK

Quando a integração do SDK estiver concluída, você poderá acessar o painel da AppsFlyer e, na página Testes de Integração do SDK, testar instalações orgânicas e não orgânicas, eventos in-app e deep links (retargeting). Isso garante que as instalações e os eventos in-app sejam registrados e atribuídos corretamente.

Se você precisar que seu desenvolvedor teste a integração do SDK, adicione o desenvolvedor como um usuário na sua conta para que ele possa acessar o painel. 

Para cenários e instruções de teste, consulte Testando a integração com o SDK.