Transmissão de dados brutos da Push API

Premium

Resumo: envie dados brutos de eventos de atribuição para seus endpoints do lado do servidor. 

6970_Push_API_image.png

Push API

A Push API transmite dados brutos gerados pela atribuição da AppsFlyer e pela atribuição da SKAdNetwork na forma de mensagens para seus servidores. Você pode selecionar os tipos de mensagens e o conteúdo, além de definir os endpoints de destino.

Os tipos de mensagem disponíveis, a atualização dos dados e os campos dependem da estrutura de atribuição (AppsFlyer ou SKAN), conforme descrito nas seções a seguir.  

Mensagens de atribuição da AppsFlyer

Características da mensagem

Características Detalhes
Separação por tipo de mensagem
  • As mensagens podem ser separadas por endpoint (máximo de 6 endpoints por aplicativo) ou você pode determinar o tipo de mensagem, a depender do valor dos campos listados:
    • event_name
    • conversion_type
    • campaign_type 
  • Os valores dos campos, por tipo de mensagem, estão indicados na tabela a seguir.

Exemplo:

Uma mensagem contém o seguinte:

  • conversion_type=install
  • campaign_type=organic
  • event_name=install

Use a tabela para determinar se esse evento é o evento de instalação de um usuário orgânico.  

Atualização dos dados As mensagens são enviadas logo após o evento ser registrado na plataforma da AppsFlyer. Isso geralmente ocorre em poucos minutos. 
Conteúdo da mensagem (campos)
  • As mensagens têm uma estrutura key:value.
  • Veja os campos disponíveis de Push API na atribuição da AppsFlyer.
  • Cada chave representa um campo de dados brutos. Veja a descrição dos campos de dados brutos na AppsFlyer
  • Chaves em branco ou nulas não são enviadas.
  • O exemplo contém campos nulos e vazios. Postbacks reais não têm campos vazios ou nulos. O exemplo fornecido tem um formato JSON.
Formato dos campos de carimbo de data/hora
  • Carimbos de data/hora UTC: yyyy-mm-dd hh:mm:ss.sss. Por exemplo, aparece como 2019-09-17 00:09:00.123. Um evento ocorreu às 18:00 no horário de Tóquio. A hora do evento é convertida em UTC, que é 09:00. A hora registrada é a hora em UTC. 
  • Carimbos de data/hora do fuso horário selecionado (específico do aplicativo): yyyy-mm-dd hh:mm:ss.sss±th:tm. Por exemplo 2019-09-17 18:00:16.000+0900. Um evento ocorreu às 18:00 no horário de Tóquio. O horário do evento mostrado é registrado como 18:00+09:00. 09:00 é o fuso horário de Tóquio. 

Tipos de mensagens disponíveis

Contexto de atribuição Tipo de mensagem campo conversion_type campo campaign_type campo event_name campo event_type
Aquisição de usuários Instalação* install

Non-organic: UA

Organic: organic

install
  • install
  • organic-install
Aquisição de usuários  Eventos in-app de instalação install

Non-organic: UA

Organic: organic

Advertiser-defined event names
  • install-in-app-event
  • organic-install-in-app-event
Retargeting Reengajamento re-engagement retargeting re-engagement re-attribution
Retargeting  Eventos in-app de reengajamento re-engagement retargeting Advertiser-defined event names re-engagement-in-app-event
Retargeting  Re-atribuição  reinstall retargeting re-attribution re-attribution
Aquisição de usuários  Reinstalação reinstall

Non-organic: UA

Organic: organic

reinstall
  • reinstall
  • organic-reinstall
Retargeting Eventos in-app de reatribuição reinstall retargeting Advertiser-defined event names re-attribution-in-app-event
* Algumas instalações relacionadas à atribuição de view-through são atribuídas a uma fonte de mídia restrita.

Campos exclusivos

Nome exibido Nome na Push API
Moeda selecionada* selected_currency
Receita na moeda selecionada revenue_in_selected_
currency
Custo na moeda selecionada cost_in_selected_
currency
Fuso horário selecionado para o download do dispositivo device_download_time_selected_timezone
Fuso horário selecionado por hora de atribuição do toque attributed_touch_time_selected_timezone
Hora de instalação no fuso horário selecionado install_time_selected_
timezone
Hora do evento no fuso horário selecionado event_time_selected_
timezone
Fuso horário selecionado(*) selected_timezone
* Essa é a configuração no nível do aplicativo em vigor no momento em que a mensagem da API é enviada.

Mensagens de atribuição da SKAN

Essa seção descreve as mensagens (tipos de relatório) disponíveis para SKAN e como identificá-las. Leia o conteúdo e, em seguida, configure o endpoint de atribuição da SKAN.

Leitura adicional: campos de dados brutos da SKAN. As mensagens da Push API têm estrutura e campos equivalentes. 

Características da mensagem:

Características Detalhes
Separação por tipo de mensagem
  • Todas as mensagens são enviadas para 1 endpoint definido por você.
  • Para determinar o tipo de mensagem, use o campo event_type.
    Atenção: usando o campo event_type, você também pode determinar o campo event_name e o campo skad_redownload.
  • Os valores do campo event_type estão indicados na tabela a seguir.

Exemplo:

Uma mensagem contém o seguinte:

  • event_type: skad-re-download

A partir disso, podemos determinar que:

  • Esse é um evento de re-download
  • event_name: install
  • skad_redownload: true
Atualização dos dados
  • Instalações, redownloads e eventos in-app:
    • Processados diariamente
    • Enviados para seu endpoint no dia seguinte ao recebimento do postback do iOS pela AppsFlyer
    • Espere receber mensagens de eventos entre 08:00 e 11:00 UTC (a hora exata varia)
    • Exemplo: postbacks recebidos na segunda-feira são enviados a partir de terça às 08:00 UTC
  • Postbacks do iOS e cópia de postbacks: As mensagens são enviadas logo após chegarem à AppsFlyer
Exemplos de mensagens A planilha contém exemplos de mensagens. O exemplo fornecido tem um formato JSON. Exemplos de mensagens SKAN.

Tipos de mensagens para atribuição da SKAN

Tipo de mensagem  campo event_name campo skad_redownload campo event_type
Instalações  install
  • Valores possíveis: false, blank, null. 
  • Se o campo não estiver na mensagem, considere o valor como false. 
skad-install
Re-downloads   install True skad-re-download
Eventos in-app  O nome do evento definido pelo anunciante O nome do evento definido pelo anunciante skad-in-app-event
Postbacks do iOS Nunca disponíveis nessa mensagem Às vezes disponíveis skad-postback
Cópia de postbacks Nunca disponível nessa mensagem Às vezes disponível skad-postback-copy

 

Configurar endpoints da Push API

 Atenção

Você não deve usar a Push API para enviar dados atribuídos da AppsFlyer a terceiros pelos seguintes motivos:

  • Você pode violar regulamentos de privacidade, como a CCPA, se o usuário optar por não enviar seus dados a terceiros.
  • Algumas fontes de mídia restringem a forma como os dados a nível do usuário fornecidos por elas são usados, compartilhados com terceiros ou ambos. Certifique-se de cumprir os termos de uso da fonte de mídia.
    Por exemplo, X Ads, Snapchat, Pinterest.

Atenção:  isso não se aplica aos dados SKAN. Use a Push API para enviar dados SKAN para endpoints de terceiros.

Para configurar a Push API, preencha a lista de ações abaixo.

Checklist de configuração da Push API

Etapa  Atribuição da AppsFlyer Atribuição na SKAdNetwork  
1

Se você já possui um endpoint ativo da Push API, pode pular essa etapa. 

Complete os requisitos do lado do servidor.

2 Para atribuição da AppsFlyer, planeje as configurações do endpoint usando a checklist da Push API. Não aplicável
3 Configure o endpoint de atribuição da AppsFlyer Configure o endpoint de atribuição da SKAdNetwork

Requisitos do lado do servidor (seu servidor)

Verifique se o seu servidor cumpre com os requisitos listados aqui: 

Requisitos do lado do servidor

URL do endpoint
  • Nome de domínio válido
  • Número máximo de endpoints exclusivos por aplicativo: 
    • AppsFlyer: 6 endpoints
    • SKAdNetwork: 3 endpoints
Código de retorno do endpoint Ao receber uma mensagem, seu endpoint deve retornar um código de status HTTP 200.
Incluir servidores da AppsFlyer na lista de permissões Inclua os endereços IP do servidor da AppsFlyer na lista de permissões dos seus sistemas de firewall e segurança para garantir a comunicação com o endpoint.
Versões TLS
Portas  Portas: 80, 443

Atenção! Um mecanismo de tempo limite, com duração de 4 segundos, é usado. Se a AppsFlyer não receber uma mensagem de OK durante esse período, isso será considerado uma falha no envio da mensagem. 

Checklist para o planejamento da Push API para atribuição na AppsFlyer

  • Use essa checklist para planejar suas configurações de endpoint de atribuição na AppsFlyer. Os números na figura correspondem aos números de linha no checklist.
  • Essa seção não é relevante para a atribuição na SKAdNetwork. Consulte o artigo configurar a atribuição da SKAdNetwork.  

Endpoint 

PushAPI_us-en.png

Tabela de planejamento do endpoint

Não. Configuração Detalhes Use essa coluna para registrar suas configurações planejadas
1 Método POST ou GET  
2 URL do endpoint -  
3 Tipos de mensagem de evento
  • Selecione pelo menos um tipo de mensagem de evento.
  • Para selecionar mensagens de eventos in-app, é necessário gravar um evento no aplicativo. Até você fazer isso, não poderá selecionar mensagens de evento in-app. 
InappSelectionDisabled_us-en.png 
 
4
  • Campos 
  • A lista de campos é comum a todos os tipos de mensagens

Aviso

Se você marcar Selecionar tudo, os arquivos recém-adicionados também serão selecionados automaticamente. Certifique-se de que você pode oferecer suporte a todos os novos campos adicionados automaticamente ao esquema para evitar problemas.

Selecione os campos obrigatórios.
  • Os campos mais comuns são pré-selecionados por padrão.
  • Não enviamos campos vazios/nulos
 
5

Tipo de evento in-app

 

Filtre por evento in-app para reduzir o tráfego enviado ao seu endpoint.
  • Selecione um ou mais eventos ou todos os eventos in-app. Atenção! Se o evento não for exibido na lista, procure por ele. 
  • Se você selecionar tudo, novos eventos in-app serão adicionados automaticamente. 
  • Você só pode selecionar um evento in-app após ele ter sido gravado pelo menos uma vez. Se necessário, use o S2S para acionar o evento.
  • mceclip1.png
 

Configure o endpoint de atribuição da AppsFlyer

Atenção: Somente o proprietário da conta da AppsFlyer pode fazer alterações nas configurações da Push API. Outros usuários da conta podem visualizar as configurações.

Adicione um endpoint de atribuição da AppsFlyer

  1. Acesse relatórios > acesso à API. Vá até a seção da Push API.
  2. Clique em Adicionar Endpoint.
     
  3. Selecione um método HTTP: POST ou GET
  4. Insira a URL do Endpoint/strong>.  Se você receber a mensagem "essa URL não é segura", entre em contato com o suporte da AppsFlyer.
  5. Selecione um ou mais tipos de evento. Atenção: se as mensagens de evento in-app estiverem desativadas, isso significa que nenhum evento in-app foi gravado até o momento.  
  6. Selecione os campos para preencher a mensagem da Push API. Atenção:
     
    • campos obrigatórios sempre enviados: App ID, nome do evento, horário do evento, IDFA (iOS) ou Advertising ID (Android)
    • Use os controles representados na figura a seguir para selecionar campos opcionais. PushAPIFieldSelect1.jpg
      • Os campos mais comuns são pré-selecionados por padrão. Você pode cancelar as seleções.
      • Selecione os campos opcionais conforme necessário.
      • Use Limpar tudo para limpar todos os campos opcionais.
      • Não enviamos campos vazios/nulos e a chave associada. Leve isso em conta ao planejar seus processos de importação/análise.
  7. Selecione um ou mais (até 52 eventos) ou Todos os eventos in-app.
     
    • A lista é preenchida por tipos de eventos que já foram gravados. Se estiver faltando um evento, envie um evento desse tipo usando um dispositivo de teste.  
  8. Clique em Salvar.
    A Push API agora está ativa. Os dados de conversão são enviados para o endpoint.
  9. Teste o endpoint usando o procedimento a seguir.

Para testar o endpoint:

  1. Clique Enviar teste.
    Uma mensagem de resultado do teste é exibida abaixo do botão Enviar teste
    Uma mensagem de teste é enviada para o endpoint. Se o teste falhar, certifique-se de que você incluiu os endereços de IP da AppsFlyer na lista de permissões
    Atenção! Um mecanismo de tempo limite, com duração de 2 segundos, é usado. Se a AppsFlyer não receber uma mensagem de OK durante esse período, isso será considerado uma falha no envio da mensagem. 
  2. Verifique se o endpoint recebeu a mensagem de teste.
    Veja uma cópia da mensagem enviada.  

Configure o endpoint de atribuição da SKAdNetwork

Atenção: Somente o proprietário da conta da AppsFlyer pode fazer alterações nas configurações da Push API. Outros usuários da conta podem visualizar as configurações.

Para adicionar um endpoint da Push API da SKAdNetwork:

  1. Acesse relatórios > acesso à API. Vá até a seção da Push API.
  2. Selecione SKAdNetwork como a entidade de atribuição.  
  3. Clique em Adicionar endpoint.
    Atenção: Você pode definir de 1 a 3 endpoints da SKAdNetwork por aplicativo. 
  4. Selecione um método HTTP: POST ou GET
  5. Insira a URL doEndpoint.   Se você receber a mensagem "essa URL não é segura", entre em contato com o suporte da AppsFlyer.
  6. Não enviamos campos vazios/nulos e a chave associada. Leve isso em conta ao planejar seus processos de importação/análise.
  7. Clique em Salvar.
    A Push API agora está ativa. Os dados são enviados para o endpoint. 

Configurar token de autenticação

Usando o token de autenticação da Push API, os clientes podem integrar e proteger suas mensagens da Push-API de forma contínua, adicionando um header de autorização personalizável com um token solicitado.
Você pode personalizar um header de autorização que será enviado com suas mensagens da Push-API, definindo o nome do token e o valor associado a cada app ID. Isso garante que suas mensagens não sejam apenas seguras, mas também adaptadas às suas necessidades específicas.

Procedimentos adicionais — gerenciando endpoints

Alterar um endpoint

Atenção: somente o proprietário da conta da AppsFlyer pode fazer alterações nas configurações da Push API. Outros usuários da conta podem visualizar as configurações.

Para modificar as configurações do endpoint: 

  1. Vá para Relatório > Acesso à API. Vá até a seção da Push API.
  2. Localize o endpoint a ser modificado.
  3. Faça as alterações.
  4. Clique em Salvar.

Excluir um endpoint

Atenção: somente o proprietário da conta da AppsFlyer pode fazer alterações nas configurações da Push API. Outros usuários da conta podem visualizar as configurações.

Para excluir um endpoint:

  1. acesse relatórios > acesso à API. Vá até a seção da Push API.
  2. Clique em excluir endpoint.
  3. Clique em salvar.
    O endpoint é removido.  

Solução de problemas, características e limitações

Falha nas mensagens de teste

Se você não receber a mensagem de teste e restringir o acesso aos seus servidores por endereço IP: certifique-se de que você incluiu todos os endereços IP da AppsFlyer na lista de permissões.  

Duplicar eventos in-app de retargeting

Os eventos de retargeting in-app são duplicados quando um evento de compra ocorre como parte da campanha de retargeting durante uma janela de reengajamento de UA. Isso é feito para atribuir receita à fonte de mídia de UA e à fonte de mídia de retargeting. 

Você só receberá eventos duplicados se ambos estiverem ativos:

  • Eventos in-app à instalação
  • Eventos in-app relacionados ao retargeting 

Identificar e desduplicar eventos in-app

 

A seleção de mensagens de eventos in-app está desativada

InappSelectionDisabled_us-en.png

  • Mensagens de eventos in-app só podem ser selecionadas após a gravação de um evento in-app.
  • Use um dispositivo de teste para gerar um evento in-app ou use a API S2S para fazer isso manualmente.  

Mensagens de push e CloudFront ausentes

Você está usando Amazon CloudFront como seu endpoint? Nesse caso, verifique se o CloudFront está rejeitando a mensagem com o código 421. Se sim, consulte o artigo Como o CloudFront atende solicitações de HTTPS.

Mensagens de erro de endpoint

Sintoma: a mensagem essa URL não é segura  é exibida quando você configura a URL do endpoint.

Ação necessária: entre em contato com o suporte da AppsFlyer, inclua o App ID, a URL do endpoint e uma captura de tela da mensagem de erro.

Características e limitações

Caraterística Observações 
Ad networks Indisponível. 
Agências Indisponível.
Fuso horário específico do aplicativo Disponível
Moeda específica do aplicativo  Disponível
Limitações de tamanho Não aplicável
Orgânico  Sim
Não orgânico Sim
Atualização dos dados Contínuo 
Histórico de dados Indisponível. Se faltarem dados, use a Pull API para obter os dados. No caso da SKAN, você pode obter alguns históricos de dados por meio do Data Locker (limitado pela janela de disponibilidade do Data Locker). 
Acesso do proprietário da conta/usuário

Somente o proprietário da conta da AppsFlyer pode fazer alterações nas configurações da Push API.

  • Cada conta da AppsFlyer tem apenas um proprietário da conta. Esse é o primeiro usuário da AppsFlyer (criado no momento em que a conta foi aberta).

Outros usuários de conta podem visualizar as configurações da Push API, mas não podem fazer mudanças.

Token de autenticação em mensagens de teste Os headers de mensagem de teste não incluem o token de autenticação.

Posso incluir headers personalizados com a solicitação da Push API?

Não. A Push API é compatível com o uso do header Authorization apenas para tokens de autenticação. Headers personalizados adicionais — como consumer-key — não são compatíveis.

Se você precisar enviar parâmetros extras, inclua-os na URL. Por exemplo:

https://your.server.com?consumer_key=abc456