Eventos avançados dentro do aplicativo—Visão geral

Visão geral: grave eventos avançados in-app após a instalação (como login, cadastro ou compra no aplicativo) atribuídos a fontes de mídia e campanhas.

 Leitura relacionada

Para obter uma visão completa do seu trabalho com eventos in-app, leia os seguintes artigos:

Por que gravar eventos in-app?

Os eventos in-app oferecem informações sobre o que está acontecendo em seu aplicativo e são a ferramenta ideal para determinar o valor dos usuários do app e a qualidade do tráfego proveniente de diferentes fontes de mídia. O registro de eventos in-app ajuda a mensurar KPIs como ROI (retorno sobre o investimento) e LTV (Lifetime Value).

Quando os usuários realizam cadastros, concluem tutoriais, adicionam itens ao carrinho de compras ou finalizam compras, os dados de eventos in-app podem gravar os eventos detalhadamente. A implementação de eventos in-app é obrigatória para todos os fins de análise pós-instalação.

Sobre eventos in-app

Um evento in-app inclui um nome de evento e pode incluir parâmetros de evento. Quando você adiciona parâmetros de evento a um evento in-app, ele é denominado como um evento avançado no aplicativo. Os parâmetros do evento oferecem mais contexto e informações sobre o evento que ocorre. Por exemplo, embora ele seja útil para saber que um usuário fez uma reserva de hotel, por exemplo, os parâmetros do evento podem oferecer detalhes como o tipo de compra, destino e receita.

travel.png

Eventos predefinidos e personalizados

Os eventos in-app que você deseja enviar exigem que o desenvolvedor implemente o código quando aplicável em seu aplicativo. Os nomes de eventos e os parâmetros de eventos são classificados da seguinte forma:

  • Predefinido: são nomes de eventos e parâmetros de eventos que costumam ser usados entre aplicativos diferentes. É altamente recomendável usar nomes de eventos predefinidos e parâmetros de eventos tanto quanto possível, pelos seguintes motivos:
    • A nomeação predefinida permite o mapeamento automático de eventos para parceiros. 
    • Se a AppsFlyer decidir alterar o nome de qualquer parâmetro de evento ou evento, sua implementação será compatível com versões anteriores.
  • Personalizado: são nomes de eventos e parâmetros que você define para cenários de usuário específicos que ocorrem no aplicativo. Você pode usar qualquer nome de evento personalizado ou string de nome de parâmetro, mas lembre-se de que eventos personalizados precisam de manutenção por parte do desenvolvedor. Consulte Dicas e Limitações.

Eventos de receita

Sempre que você envia eventos in-app, como uma compra ou reserva de voo, você o envia com sua receita associada. O único parâmetro que carrega receita em eventos in-app é af_revenue

Você também pode registrar receita negativa caso um usuário cancele uma compra ou se você emitir um reembolso. Para registrar a receita negativa, basta anexar o sinal negativo (-) ao valor da receita que você envia paraaf_revenue

af_revenue é o único parâmetro que acumula a receita dos seus usuários. Sempre o use com eventos in-app que representam a geração de receita real em sua lógica de negócios.

O intervalo desse valor deve ser de US$-10.000 a US$+10.000 ou o valor equivalente em moeda original. Valores fora dessa faixa estão incluídos em relatórios de dados brutos, mas não em relatórios agregados. 

af_revenue também pode apresentar valores de receita negativos se você precisar registrar eventos como transações canceladas ou reembolsos.

Observação:

  • Não formate de forma alguma o valor da receita. Ele não deve conter separadores de vírgulas, moeda, caracteres especiais ou texto. Por exemplo, um valor de receita deve ser semelhante a 1234,56. A AppsFlyer fornece um valor de receita com precisão de até cinco casas decimais.
  • A AppsFlyer exibe a receita exata enviada do SDK. Isso não inclui nenhum cálculo de IVA ou comissões de loja app, etc, a menos que o mesmo tenha sido incluído pelo desenvolvedor do lado do SDK antes de ser enviado à AppsFlyer.

af_currency representa a moeda que é declarada em af_revenue (ou af_price). Se af_currency estiver faltando nos parâmetros do evento, a AppsFlyer a envia com o valor padrão "USD".

Você pode usar af_price como um parâmetro monetário que não é contado como receita (como em um evento "Add to Cart"). Esse parâmetro se refere ao preço do item individual. O valor total de todas as compras aparece sob o parâmetro af_revenue.

Moeda da receita

É importante entender como a AppsFlyer lida com configurações de moeda e conversões de moeda.

A AppsFlyer lida com a diferença entre a moeda definida nas configurações do aplicativo e a moeda de eventos in-app usando a conversão de moedas.

revenue_normalization_flow.png

O diagrama acima demonstra o seguinte processo:

  1. Os eventos in-app são enviados - moedas diferentes para cada evento
  2. A AppsFlyer padroniza todas as moedas para USD
  3. A AppsFlyer processa os dados de receita
  4. Os dados de receita no dashboard são exibidos nas configurações de moeda no aplicativo
  5. A AppsFlyer preenche os dados de receita em relatórios de dados brutos tanto na moeda do evento como na moeda da configuração do aplicativo

A AppsFlyer usa Open Exchange Rates, ou taxas de câmbio abertas, para conversão de moeda. A taxa de câmbio é atualizada de hora em hora. Sempre que a AppsFlyer realiza a conversão de moeda, ela usa a taxa de câmbio da última atualização.

Conversão de moedas

 Exemplo

Nas suas configurações do aplicativo, você define a moeda para GBP. Um usuário da França compra um produto usando seu aplicativo. O preço é cotado em EUR (€). O evento in-app que você envia para a AppsFlyer tem essa aparência:

Map<String, Object> eventValue = new HashMap<String, Object>();
eventValue.put(AFInAppEventParameterName.REVENUE,200);
eventValue.put(AFInAppEventParameterName.CONTENT_TYPE,"category_a");
eventValue.put(AFInAppEventParameterName.CONTENT_ID,"1234567");
eventValue.put(AFInAppEventParameterName.CURRENCY,"EUR");
AppsFlyerLib.getInstance().trackEvent(getApplicationContext() , AFInAppEventType.PURCHASE , eventValue);

Nesse caso, a AppsFlyer converte a receita de EUR para USD e, em seguida, para GBP. Vamos assumir que a taxa de câmbio é de 1 euro = 1,13 dólares. Assim, 200 euros se transformam em 226,85 dólares. Em seguida, a AppsFlyer faz a conversão de USD para GBP. Vamos supor que a taxa de câmbio é US$1 = £0,78. Assim, US$226,85 passam a £176,92.

Exibição da moeda

A moeda é definida nas configurações do aplicativo. A moeda que você define nas configurações do aplicativo é a moeda que aparece no dashboard. Não importa em qual moeda você envia eventos in-app, a receita no dashboard sempre aparece na moeda que você definiu nas configurações do aplicativo.

 Exemplo

Vamos supor que você enviou eventos in-app com moedas diferentes daquela definida nas configurações do aplicativo, ou sem nenhuma moeda. Nesse exemplo, a moeda nas configurações do aplicativo está definida para GBP.

Você envia três eventos in-app para a AppsFlyer.

  1. O evento A tem receita de 234 e GBP como moeda
  2. O evento B tem receita de 171 e EUR como moeda
  3. O evento C tem receita de 171 mas sem moeda especificada

Dados de receita no dashboard

A receita que aparece no dashboard é o valor convertido da moeda do evento in-app para USD e depois para a moeda das configurações do aplicativo.

Se nenhuma moeda for especificada no evento, a AppsFlyer usa USD como padrão. O dashboard exibe o evento e a receita da seguinte forma:

Eventos In-Apps Usuários Únicos Número De Ações Receita
A 1 1 £234
B 1 1 £149,4 - convertido de EUR para USD e depois para GBP.
C 1 1 £132,9 - por padrão, o valor é definido como USD, já que nenhuma moeda foi especificada. Convertido diretamente de USD para GBP.

Dados de receita em relatórios de dados brutos

Se você definir a moeda para GBP nas configurações do aplicativo, mas enviar eventos in-app com moedas diferentes, o relatório de dados brutos mostra a receita tanto na moeda das configurações do aplicativo quanto na moeda do evento in-app.

Se você definir a moeda para GBP nas configurações do aplicativo, mas enviar eventos in-app sem moeda, o relatório de dados brutos mostra a receita tanto na moeda de configuração do aplicativo quanto em USD.

O relatório de dados brutos dos eventos in-app exibe o evento e a receita da seguinte forma:

Evento Receita do evento Moeda da receita do evento Receita do evento em GBP
A 234 GBP 234
B 171 EUR 149,4 - convertido de EUR para USD e, em seguida, para GBP.
C 171 USD 132,9 é padronizado para dólar, já que nenhuma moeda foi especificada. Convertido diretamente de USD para GBP.

Enviando eventos

Existem várias maneiras de enviar eventos in-app para a AppsFlyer:

  • SDK da AppsFlyer: essa é a forma mais comum de enviar eventos. Você pode enviar eventos avançados in-app que gravam ações do usuário no aplicativo usando a API de eventos in-app da AppsFlyer no nível do SDK.
  • API de servidor para servidor: use a API de servidor para servidor para enviar eventos que ocorrem fora do aplicativo mobile diretamente para a AppsFlyer. Por exemplo, se você tiver um usuário ativo na web e em outras plataformas mobile, pode gravar os eventos nas duas fontes e atribuí-los ao mesmo usuário na AppsFlyer. Pode ser um evento in-app ou outros eventos, como eventos de site, eventos de call center ou compras em sua loja física.
  • Validação de recibos: este é um mecanismo seguro em que a plataforma de pagamento, por exemplo, a Apple e o Google, validam que a compra no aplicativo ocorreu conforme relatado. A validação de compras é a principal ferramenta para evitar eventos de receita fraudulentos. Ela também ajuda na visualização de qual é a receita real e filtra compras incompletas no aplicativo.
  • Aplicativos híbridos: esses aplicativos combinam visualizações nativas e conteúdo HTML e também podem registrar eventos in-app. No entanto, como o SDK só pode enviar eventos do lado nativo, os desenvolvedores precisam encaminhar todos os dados do evento para o código nativo.

Configurando eventos in-app

O processo de configuração de eventos in-app requer que o profissional de marketing e o desenvolvedor trabalhem juntos da seguinte forma:

Etapa Função Tarefa Detalhes

1

Profissional de marketing

Determine os eventos in-app que você deseja mensurar. Defina e comunique os nomes do evento e os parâmetros do evento ao seu desenvolvedor.  

É recomendado começar com 3 a 5 eventos que podem ser usados como KPIs para mensurar a qualidade de seus usuários (por exemplo, compras, cadastro e compartilhamento). Os parâmetros de evento são opcionais e você pode usar qualquer parâmetro de evento com qualquer nome de evento.

Consulte Eventos recomendados por verticais de negócios para eventos in-app típicos.

2 desenvolvedor

Implemente o código no seu app, quando aplicável. 

A documentação do desenvolvedor está aqui.

3 [Opcional] Profissional de marketing Trabalhe com seu desenvolvedor para definir o campo de ID de usuário do cliente (CUID)

Esse campo ajuda a enriquecer os dados de eventos in-app, fazendo referência cruzada entre os dados de atribuição da AppsFlyer e seus outros dados, usando o CUID como chave.

4 [Opcional] Profissional de marketing Mapeie eventos para parceiros relevantes no dashboard.  Essa é uma tarefa contínua, dependendo dos parceiros com os quais você possui integração.

Definindo um evento in-app

Depois de determinar os eventos in-app que você deseja mensurar, use nosso gerador de eventos in-app para definir os eventos e parâmetros da seguinte forma:

  1. Selecione o nome de evento mais adequado ao cenário que você deseja registrar.
  2. Selecione os parâmetros do evento que você deseja associar ao evento. Escolha parâmetros que oferecerão contexto adicional ao evento e enriquecerão os dados.
  3. Faça download do arquivo completo do gerador de eventos in-app e compartilhe-o com seu desenvolvedor.

 Exemplo

Um profissional de marketing de um aplicativo de eCommerce quer registrar o tipo de conteúdo que os usuários visualizam para entender melhor quais categorias são as mais populares, conectando as visualizações de produtos com as vendas de produtos.

A tabela a seguir mostra um exemplo da estrutura de eventos que o profissional de marketing passa para o desenvolvedor:
Nome do evento Parâmetros do evento Valores de parâmetros Quando o evento é acionado?
af_content_view af_price Preço do produto

Quando um usuário visualiza uma determinada página de detalhes de um produto

af_content_type Nome da categoria de produto, por exemplo: sapatos
af_content_id

ID do produto, por exemplo: SKU

Visualizar dados de eventos in-app

Eventos in-app são atribuídos à fonte de mídia responsável pela instalação ao longo da vida útil do usuário. Os dados de eventos são apresentados como dados de Lifetime Value ou de Atividade

Você pode visualizar os dados de eventos in-app nestes locais:

  • Página de visão geral do dashboard: exibe a performance do LTV da aquisição de usuários (UA) em tempo real. Observação: isto inclui a receita dividida igualmente entre usuários orgânicos e não-orgânicos reportados através de eventos in-app, e a receita de retargeting que é duplamente atribuída.
  • Página de eventos: exibe a performance do LTV de eventos in-app entre fontes de mídia
  • Página de atividades: exibe as atividades in-app para o intervalo de datas selecionada.
  • Relatório de eventos in-app de dados brutosexibe dados de atividade, ou seja, uma lista cronológica das ações executadas por toda a sua base de usuários. Esse relatório inclui valores de parâmetros de evento, por exemplo:
    {
      "af_level":"10",
      "af_score":"3387",
      "arena":"7",
      "char_type":"paladin"
    }

    Observação: o relatório de dados brutos é um recurso premium.

Dicas

Ao definir nomes e parâmetros de eventos no aplicativo, lembre-se:

  • Para obter consistência de dados em relatórios de dados brutos, recomendamos que você defina e utilize os mesmos nomes e estruturas de eventos in-app em todas as plataformas.
  • Use um número mínimo de eventos para facilitar a comparação da qualidade dos usuários vindos de diferentes fontes.
  • É importante garantir a privacidade de seus usuários. Não preencha valores de eventos in-app com dados restritos que possam identificá-los diretamente. Por exemplo, endereço de e-mail, nome, número de identidade e, em alguns locais, código postal. Para obter mais informações sobre dados restritos, leia a política de privacidade dos serviços.
  • Observe que a AppsFlyer coleta o endereço de IP dos dispositivos durante os engajamentos. Em algumas jurisdições ou cenários de uso, o endereço de IP pode ser considerado uma PII. Usamos o endereço de IP para derivar a ampla localização geográfica (cidade, bairro) do dispositivo, mas não o endereço específico. Se necessário, você pode selecionar mascarar endereços de IP para que eles não apareçam nos relatórios de dados brutos. 
  • Eventos in-app são a única fonte de dados de receita na AppsFlyer. Você pode anexar um valor de receita específico a cada evento e visualizá-lo no dashboard do seu aplicativo.  Saiba mais sobre os parâmetros de monetização.

    revenue_data.png

Limitações

Ao definir nomes e parâmetros de eventos no aplicativo, lembre-se:

  • Recomendamos usar apenas caracteres alfa-numéricos minúsculos (a-z e 0-9) para seus nomes de eventos in-app. Os nomes de eventos diferenciam maiúsculas de minúsculas, o que significa que af_purchase e af_PURCHASE são dois eventos diferentes nos dados brutos. Entretanto, em relatórios agregados (por exemplo, Visão Geral, ou Eventos) eles podem ser exibidos como um único evento.
  • Há um limite de 300 eventos exclusivos por dia. Saiba mais
  • Os usuários exclusivos são contados somente para os primeiros 100 eventos após a instalação do aplicativo.
  • Os nomes dos eventos não podem começar com esses caracteres: " = + - 
  • Os nomes de eventos não podem conter espaços vazios. Você pode usar espaços sublinhados (underline, ou traços baixos) antes ou depois do nome do evento.
  • Os valores do evento não devem exceder 1000 caracteres. 
  • Se você incluir a URL de referência como um valor de evento, ele deverá ser codificado por URL.
  • O Facebook tem algumas limitações em relação aos nomes e parâmetros de eventos. Leia sobre as limitações aqui.

FAQ

A seção a seguir inclui várias perguntas frequentes sobre eventos in-app.

Como faço para usar o parâmetro de receita?

Você pode enviar valores de receitas com qualquer nome de parâmetro e evento. No entanto, para registrar a receita (incluindo receita negativa) nos dados brutos e agregados da AppsFlyer, o parâmetro af_revenue DEVE ser usado. Sempre use ele com eventos in-app que representam a geração de receita real em sua lógica de negócios.

af_currency representa a moeda que é indicada emaf_revenue (ou af_price). Se af_currency estiver ausente nos parâmetros do evento, a AppsFlyer o enviará com o valor padrão "USD".


Para obter mais informações sobre o parâmetro af_revenue, consulte o Guia de Atribuição de Receita.

Como a AppsFlyer atribui eventos?

Os eventos in-app são atribuídos ao canal original da mídia da instalação do aplicativo.

Após a instalação de um aplicativo (primeira abertura do aplicativo), a AppsFlyer utiliza vários métodos de atribuição para determinar a atribuição da instalação. Ao mesmo tempo, o SDK da AppsFlyer cria um novo e exclusivo ID da AppsFlyer, que está associado com os detalhes de atribuição.

Cada evento in-app posterior, realizado pelo mesmo dispositivo no aplicativo, tem esse ID. Isso permite que a AppsFlyer atribua o evento ao canal original da mídia. Os anunciantes podem usar esse recurso para acompanhar a jornada completa do usuário no aplicativo.

Eventos de usuários que recentemente passaram por retargeting podem ter dupla atribuição.

A AppsFlyer atribui eventos de instalações atribuídas como orgânicos quando:

Os eventos são registrados se um dispositivo estiver offline?

Se um usuário iniciar um evento quando a conexão à internet estiver indisponível, a Appsflyer ainda pode realizar o registro do evento. Confira como funciona:

  1. O SDK envia os eventos para os servidores da AppsFlyer e aguarda uma resposta bem-sucedida.
  2. Se o SDK não receber uma resposta bem-sucedida, o evento será armazenado no cache.
  3. Uma vez que a próxima resposta bem-sucedida é recebida, o evento armazenado é enviado para o servidor novamente.
  4. Se houver vários eventos no cache, eles serão enviados para o servidor, um após o outro.

 Observação

O cache do SDK pode armazenar até 40 eventos, o que significa que apenas os primeiros 40 eventos que ocorrem offline são salvos. Tudo o que se segue, até a próxima resposta bem-sucedida, é descartado.

A hora do evento que aparece nos dados brutos é a hora em que o evento é enviado à AppsFlyer após o dispositivo ficar online novamente. Não é a hora real do evento.

O que são eventos complexos in-app e como faço para configurá-los?

Eventos complexos in-app permitem o envio de vários eventos em uma única chamada de API.

Eles são úteis quando você deseja ver várias ações de usuários intimamente relacionadas agrupadas, por exemplo adicionar vários produtos à cesta em uma única sessão.
Exemplo:

{
  "af_revenue":"50.87",
  "af_currency":"USD",
  "af_receipt_id":"57601333",
  "product":[ 
   { 
	 "af_content_id":"1164_8186",
	 "af_price":"8.97",
	 "af_quantity":"1"
   },
   { 
	 "af_content_id":"1164_8186",
	 "af_price":"8.97",
	 "af_quantity":"1"
   },
   { 
	 "af_content_id":"1164_8186",
	 "af_price":"8.97",
	 "af_quantity":"1"
   },
   { 
	 "af_content_id":"1177_8185",
	 "af_price":"8.97",
	 "af_quantity":"1"
   },
   { 
	 "af_content_id":"0153_9077",
	 "af_price":"14.99",
	 "af_quantity":"1"
   }
  ]
}

 Atenção

Eventos complexos in-app causam problemas de postback com o Facebook e Criteo. Se você precisar que o evento seja totalmente mapeado com o Facebook e Criteo, envie eventos separados por ação do usuário (por exemplo, envie um evento Adicionar ao carrinho por cada item adicionado). Use os dados brutos de eventos in-app para agrupar esses eventos.

Posso adicionar vários itens a uma única transação?

Você pode adicionar vários itens a uma única transação. Em vez de valores únicos por parâmetro de evento, você pode ter vários itens descrevendo a transação, separados por vírgulas.  O formato deve ser uma string JSON.

 Exemplo

Na mesma transação, o Sr. Smith compra duas camisas idênticas, um par de sapatos e um chapéu de uma loja online dos EUA. A sequência em que cada item é listado deve ser idêntica para cada parâmetro.


"{\"af_content_id\": [\"123\",\"988\",\"399\"], \"af_quantity\": [\"2\",\"1\",\"1\"], \"af_price\": [\"25\",\"50\",\"10\"], \"af_revenue\": \"110\", \"af_currency\": \"USD\"}"

Múltiplos itens são enviados como um vetor (array) em postbacks. No momento, o Facebook e o Twitter não conseguem processar parâmetros de vetor corretamente. Para auxiliar nesse problema, a AppsFlyer faz uma síntese do número de itens (af_quantity) em vez de enviá-los para essas SRNs como um vetor. No nosso exemplo, o Facebook receberia af_quantity=4.

 Observação

Múltiplos itens podem ser usados com os seguintes eventos no aplicativo:

af_add_to_cart, af_add_to_wishlist, af_tutorial_completion, af_initiated_checkout, af_purchase, af_rate, af_spent_credits, af_content_view, af_travel_booking, af_update 

Como a AppsFlyer lida com a deduplicação de eventos?

Temos um mecanismo de deduplicação de eventos in-app. Ele verifica todos os eventos in-app para ver se há um evento in-app idêntico que veio do mesmo appsflyer_id anteriormente, há menos de 10 segundos. Se tal evento for encontrado, o mecanismo remove a duplicação.

Dois eventos são considerados idênticos se os seguintes campos em ambos eventos forem iguais:

  • Nome do evento
  • Valor do evento
  • ID do aplicativo
  • ID da AppsFlyer

 Observação

A desduplicação funciona somente para eventos in-app que forem enviados do SDK.

Os eventos in-app S2S não são desduplicados.

Por quanto tempo a AppsFlyer retém dados a nível do usuário e quais são as obrigações de exclusão?

A AppsFlyer retém dados a nível de usuário (dados brutos) por 24 meses, exceto quando indicado, exigido ou permitido por lei. Algumas SRNs/parceiros exigem que os provedores de atribuição, incluindo a AppsFlyer, excluam os dados a nível de usuário relacionados a SRN/parceiros antes da expiração do período de 24 meses.

Após a exclusão, os eventos relacionados a usuários excluídos são exibidos como orgânicos. Dados agregados antigos não são alterados. Para obter mais informações, consulte Obrigações de retenção e exclusão de dados.

Preciso adicionar o parâmetro OS (sistema operacional) aos meus eventos?

  • O SDK do Android e o SDK do iOS adicionam automaticamente o parâmetro OS (sistema operacional).
  • Para a API S2S, desde 1 de julho de 2021, você deve enviar o parâmetro OS (sistema operacional) para aplicativos iOS. Se você não enviar esse parâmetro, os dados serão considerados como tendo vindo de um usuário do iOS 14.5, e isso afeta a forma como os dados brutos são disponibilizados.