Transmissão de dados brutos da Push API

Premium
Para:
Profissionais de marketing Desenvolvedores
Última atualização:

Visão geral: transmita eventos de atribuição de dados brutos para seus endpoints do lado do servidor. 

6970_Push_API_image.png

API de push

A Push API transmite dados brutos gerados pela atribuição da AppsFlyer e pela atribuição do SKAdNetwork como mensagens para seus servidores. Você pode selecionar os tipos de mensagens e o conteúdo e definir os pontos finais 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ística Detalhes
Separação de tipo de mensagem
  • As mensagens podem ser separadas por ponto final (máximo de 6 endpoints por aplicativo) ou você pode determinar o tipo de mensagem, examinando o 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 de 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 de 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
  • Carimbo de data/hora em UTC: aaaa-mm-dd hh:mm:ss.sss. Por exemplo, aparece como2019-09-17 00:09:00,123. Um evento ocorreu às 18:00, 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 selecionados (específicos do aplicativo): aaaa-mm-dd hh:mm:ss.sss±th:tm. Por exemplo 2019-09-17 18:00:16 .000+0900. Um evento ocorreu às 18:00, 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ário Instalação* não relacionada

Não orgânico: UA

Orgânico: organic

não relacionada

  • não relacionada

  • organic-install
Aquisição de usuário  Instalar eventos in-app não relacionada

Não orgânico: UA

Orgânico: organic

Nomes de eventos definidos pelo anunciante

  • install-in-app-event

  • organic-install-in-app-event

Redirecionamento

 REENGAJAMENTO REENGAJAMENTO retargeting REENGAJAMENTO

REENGAJAMENTO
Retargeting  Eventos in-app de reengajamento REENGAJAMENTO retargeting Nomes de eventos definidos pelo anunciante

re-engagement-in-app-event
Retargeting  Reatribuição  Reinstalação retargeting Reatribuição

Reatribuição
Aquisição de usuário  Reinstalação Reinstalação

Não orgânico: UA

Orgânico: organic

Reinstalação

  • Reinstalação

  • organic-reinstall
Redirecionamento Eventos in-app de reatribuição Reinstalação retargeting Nomes de eventos definidos pelo anunciante

re-attribution-in-app-event
* Algumas instalações relacionadas à atribuição de exibição são atribuídas à fonte de mídia restrita.

Campos exclusivos

Nome para exibição Nome da Push API
Moeda selecionada* selected_currency
Receita na moeda selecionada moeda
revenue_in_selected_
Custo na moeda selecionada moeda
cost_in_selected_
Fuso horário selecionado para download do dispositivo device_download_time_selected_timezone
Fuso horário selecionado por tempo de toque atribuído attributed_touch_time_selected_timezone
Hora de instalação no fuso horário selecionado fuso horário
install_time_selected_
Hora do evento no fuso horário selecionado fuso horário
event_time_selected_

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

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

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

Características da mensagem:

Característica Detalhes
Separação de tipo de mensagem
  • Todas as mensagens são enviadas para 1 endpoint definido por você.
  • Para determinar o tipo de mensagem, use os seguintes campos:
    • event_name
    • skad_redownload
  • Os valores dos campos, por tipo de mensagem, são indicados na tabela a seguir

Exemplo:

Uma mensagem contém o seguinte:

  • event_name: install
  • skad_redownload: true

Como skad_redownload: true, você define que este é um evento de redownload. 
Atualização de dados
  • Instalações, redownloads e eventos in-app:
    • Processado diariamente
    • Enviado para seu endpoint no dia seguinte ao recebimento do postback do iOS pela AppsFlyer
    • Espere receber mensagens de eventos entre 05:00 e 08:00 UTC (a hora exata varia)
    • Exemplo: postbacks recebidos na segunda-feira são enviados a partir de terça às 05:00 UTC
  • Cópia de postbacks do iOS e 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.  Mensagens de exemplo SKAN.

Tipos de mensagens para atribuição da SKAN

Tipo de mensagem 

campo event_name

campo skad_redownload

campo event_type
Instalações  não relacionada
  • Valores possíveis: false, blank, null. 
  • Se o campo não estiver na mensagem, considere o valor como falso. 

skad-installs
Redownloads  não relacionada verdadeiro

skad-re-downloads
Eventos in-app 

O nome do evento definido pelo anunciante

 O nome do evento definido pelo anunciante

skad-in-app-events
Postbacks do iOS

Nunca disponível nesta mensagem

 Às vezes disponível

skad-postbacks
Cópia de postbacks

Nunca disponível nesta mensagem

 Às vezes disponível

skad-postbacks-copy


Determine o tipo de mensagem de atribuição da SKAN

Observação: isso não se aplica a mensagens de cópia de postbacks, que chegam diretamente do iOS.

PushAPI-2_en-us.png

Configurar endpoints da Push API

 Atenção

Não use 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, Twitter, Snapchat, Pinterest.

Observação:  esse cuidado não se aplica aos dados SKAN. Use a Push API para enviar dados SKAN para pontos finais de terceiros.

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

Checklist de configuração da Push API

Nº da etapa  Atribuição da AppsFlyer Atribuição na SKAdNetwork 
1

Se você já tiver um endpoint ativo da Push API, poderá pular esta 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 (o seu servidor)

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

Requisitos do lado do servidor

URL do ponto final
  • Nome de domínio válido
  • Número máximo de endpoints exclusivos por aplicativo: 
    • AppsFlyer: 6 pontos finais
    • SKAdNetwork: 3 pontos finais
Código de retorno do ponto final Ao receber uma mensagem, seu ponto final 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

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 na linha da checklist.
  • Esta seção não é relevante para a atribuição na SKAdNetwork. Consulte Configurar atribuição da SKAdNetwork. 

Ponto final 

PushAPI_us-en.png

Tabela de planejamento do ponto final

Não.

Configuração

 Detalhes Use esta coluna para registrar suas configurações planejadas
1

Método

POST ou GET

  

2

URL do ponto final

 -  
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 no aplicativo. 

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 ponto final.

  • 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

Observação: apenas o titular da conta da AppsFlyer pode fazer alterações nas configurações da Push API. Outros usuários de conta podem visualizar as configurações.

Para adicionar um endpoint de atribuição da AppsFlyer:
  1. Acesse Integração > Acesso à API.Role para baixo até a seção da Push API.
  2. Clique em Adicionar Ponto Final 
  3. Selecione um método HTTP: POSTou GET
  4. Insira a URL de endpoint. Se você receber a mensagem esta URL não é segura, entre em contato com o suporte da AppsFlyer.
  5. Selecione um ou mais tipos de evento. Observaçã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. Observação:
    • Campos obrigatórios sempre enviados: ID do aplicativo, Nome do evento, IDFA (iOS) ou ID de publicidade (Android)
    • Use os controles representados na figura a seguir para selecionar os campos adicionais. 

      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 ponto final usando o procedimento a seguir.

Para testar o ponto final:

  1. Clique em 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

Observação: apenas o titular da conta da AppsFlyer pode fazer alterações nas configurações da Push API. Outros usuários de conta podem visualizar as configurações.

Para adicionar um endpoint da Push API do SKAdNetwork:
  1. Acesse Integração > Acesso à API.Role para baixo até a seção da Push API.
  2. Selecione SKAdNetwork como a entidade atribuidora. 
  3. Clique em Adicionar endpoint. 
    Observação    : você pode definir de 1 a 3 pontos finais do SKAdNetwork por aplicativo. 
  4. Selecione um método HTTP: POSTou GET
  5. Insira a URL do endpoint. Se você receber a mensagem esta 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 ponto final. 

Procedimentos adicionais—gerenciando endpoints

Alterar um endpoint

Observação: apenas o titular da conta da AppsFlyer pode fazer alterações nas configurações da Push API. Outros usuários de conta podem visualizar as configurações.

Para modificar as configurações do endpoint: 

  1. Acesse Integração > Acesso à API.Role para baixo até a seção da Push API.
  2. Localize o ponto final a ser modificado.
  3. Faça as modificações.
  4. Clique em Salvar.

Excluir um endpoint

Observação: apenas o titular da conta da AppsFlyer pode fazer alterações nas configurações da Push API. Outros usuários de conta podem visualizar as configurações.

Para excluir um ponto final:

  1. Acesse Integração > Acesso à API.
    Role para baixo até a seção Acesso à Push API.
  2. Clique em Excluir ponto final.
  3. Clique em Salvar.
    O ponto final é removido. 

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

Falha nas mensagens de falha

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:

  • Instalar eventos in-app
  • Eventos in-app de 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 de rejeição 421. Se sim, consulte Escolhendo como o CloudFront atende a solicitações de HTTPS.

Mensagens de erro de ponto final

Sintoma: a mensagem esta URL não é segura  é exibida quando você configura a URL do ponto final.

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

Especificações e limitações

Especificação Observações 
Ad Networks Não disponível 
Agências Não disponível
Fuso horário específico do aplicativo Suportado
Moeda específica do aplicativo  Suportado
Limitações de tamanho Não aplicável
Orgânico  Sim
Não orgânica Sim
Atualização de dados Contínua 
Dados históricos Não compatível. Se faltarem dados, use a Pull API para obter os dados. No caso do SKAN, você pode obter alguns dados históricos 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 AppsFlyer pode fazer alterações nas configurações da Push API.

  • Cada conta da AppsFlyer tem apenas um proprietário da conta. É 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.

Veja também