Usando dados brutos em tempo real da Push API V2.0

Visão geral: envie dados de eventos de atribuição para os pontos finais do servidor em tempo real. Use os dados de seus sistemas de TI.

4409_Push_API_V2-01.pngPush API V2.0

Sobre a Push API

A Push API envia mensagens de eventos de atribuição em tempo real para os pontos finais do lado do servidor. Isso permite que você siga as jornadas do usuário por meio de vários ambientes e pontos de contato.

O volume de dados enviados aos pontos finais podem ser reduzidos ao limitar:

  • O tópico de mensagem e os tipos de eventos in-app selecionados.
  • Os campos selecionados.

Outras soluções de envio de dados da AppsFlyer que podem lhe interessar:

Tipos de mensagem de evento

Tipos de mensagem de eventos disponíveis
(✓ = disponível, - não aplicável)

Tipo de atribuição

Tópico

campo conversion_type

Não orgânica

(campo campaign_type)

Orgânico (campo campaign_type)
Aquisição de usuário Instalação(*) não relacionada UA Orgânico
Aquisição de usuário  Instalar eventos in-app não relacionada UA Orgânico

Redirecionamento

REENGAJAMENTO REENGAJAMENTO Redirecionamento -
Retargeting  Eventos in-app de reengajamento REENGAJAMENTO Redirecionamento -
Retargeting  Reatribuição  Reinstalação Redirecionamento -
Aquisição de usuário  Reinstalação Reinstalação UA Orgânico
Redirecionamento Eventos in-app de reatribuição Reinstalação Redirecionamento -
* Algumas instalações relacionadas à atribuição de exibição são atribuídas à fonte de mídia restrita.

Estrutura de mensagem e campos exclusivos

A mensagem da Push API depende do método HTTP:

  • GET: parâmetros de dados são anexados à string da URL
  • POST: parâmetros de dados estão contidos no corpo da mensagem no formato JSON
  • Os exemplos a seguir contêm campos nulos/vazios. No futuro, planejamos parar de enviar campos vazios/nulos. 

Campos disponíveis

  • As mensagens da Push API contêm os campos descritos aqui.
  • Campos adicionais serão adicionados periodicamente, à medida que são adicionados à plataforma da AppsFlyer. Seus mecanismos de importação/análise devem levar isso em consideração. 

Formato dos campos de carimbo de data/hora:

  • Para campos do carimbo de data/hora em UTC: formato  aaaa-mm-dd hh:mm:ss.sss. Por exemplo, um evento que ocorreu às 14:00, horário de Tóquio, é exibido como 2019-09-17 00: 09: 25.123. A hora do evento é convertida em UTC, que é 05:00. A hora registrada é a hora em UTC. 
  • Para campos de carimbo de data/hora em fuso horário selecionado: formato aaaa-mm-dd hh:mm:ss.±th:tm. Por exemplo,  2019-01-20 04:51:16.000+0000. Um evento ocorreu às 14:00, horário de Tóquio. O horário do evento mostrado é registrado como 14:00+09:00. 09:00 é o fuso horário de Tóquio. 
Campos exclusivos da Push API (em relação a outras ferramentas de transmissão de dados)
Nome para exibição Nome V2.0 Observações 
A moeda selecionada selected_currency Essa é a configuração no nível do aplicativo em vigor no momento em que a mensagem da API é enviada.
Receita na moeda selecionada moeda
revenue_in_selected_
 
Custo na moeda selecionada moeda
cost_in_selected_
 
Hora de download do dispositivo em fuso horário selecionado device_download_time_selected_
timezone
 
Fuso horário selecionado para toque atribuído attributed_touch_time_
selected_timezone
 
Fuso horário selecionado para hora da instalação fuso horário
install_time_selected_
 
Fuso horário selecionado para hora do evento 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.

Como configurar a Push API

 Atenção

Não use a Push API para enviar dados a terceiros porque:

  • Ao fazê-lo, você pode estar violando regulamentos de privacidade, como CCPA, se o usuário optou 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 oferecidos por elas são usados, compartilhados com terceiros ou ambos. Certifique-se de cumprir com os termos de uso da fonte de mídia.
    Por exemplo, Facebook, Twitter, Snapchat, Pinterest.

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

Lista de ações da Push API
Nº da ação  Para configurar um novo ponto final
1

Preencha a lista de verificação de requisitos do lado do servidor

2

Planeje as configurações do ponto final usando a lista de verificação de requisitos

3

Configure o ponto final

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
  • O mesmo endpoint pode ser usado uma vez por aplicativo. 
  • Número máximo de pontos finais por aplicativo: 6
Código de retorno do ponto final Ao receber uma mensagem, o 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

Lista de verificação de planejamento da Push API

  • Use a lista de verificação a seguir para planejar as configurações do ponto final. Os números na figura correspondem aos números de linha na lista de verificação.

Ponto final 

PushAPI_us-en.png

Tabela de planejamento do ponto final

Não.

Configuração

Detalhes Sua configuração
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

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. 
  • mceclip1.png
 
Facebook Você pretende enviar dados de usuários atribuídos ao Facebook? 
  • Para receber dados do Facebook, certifique-se de que você aceitou os termos de serviço do Facebook. 
  •  

 

Como configurar e gerenciar pontos finais

  • Esta seção contém procedimentos para adicionar, testar, modificar e excluir pontos finais. 
  • Somente o administrador pode fazer alterações nas definições da API. Os membros da equipe podem visualizar as definições da Push API.
AppsFlyerAdmin_us-en.pngPara adicionar um endpoint de Push API:
  1. Acesse Integração > Acesso à API.
    Role para baixo até a seção da Push API.
    A seção da Push API será exibida.
  2. Clique em Adicionar Ponto Final 
  3. Selecione um método HTTP: POSTou GET
  4. Insira a URL do 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.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. 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 selecionados com mais frequência são pré-selecionados. Você pode limpar a seleção.
      • 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.
  10. Se você quiser receber eventos atribuídos ao Facebook, primeiro deve aceitar os Termos de serviço do Facebook. 

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.
  2. Verifique se o endpoint recebeu a mensagem de teste.
    Uma cópia da mensagem enviada vem em seguida.

Teste as mensagens da API POST e GET

A seguinte mensagem POST é enviada como uma mensagem de teste

{                  
  "idfv": "123456789",
  "device_category": "phone",
  "af_sub1": "sub1-12345",
  "customer_user_id": "Customer User ID",
  "is_lat": null,
  "contributor_2_af_prt": "attributionagency",
  "bundle_id": "bundleIdentifier_test",
  "gp_broadcastreferrer": "",
  "contributor_2_touch_time": "2019-12-31 00:05:42.805",
  "contributor_3_touch_type": "click",
  "event_source": "SDK",
  "af_cost_value": "10",
  "contributor_1_match_type": "id_matching",
  "app_version": "app_version",
  "contributor_3_af_prt": "attributionagency",
  "custom_data": null,
  "contributor_2_touch_type": "click",
  "gp_install_begin": "2019-12-31 00:07:14.000",
  "city": "Redmond",
  "amazon_aid": "9173fe74-0578-4658-a461-ebb0b4fce6d6",
  "gp_referrer": "af_tranid=000712-31122019254604&pid=pdsagency_int&c=pushapi_v2",
  "af_cost_model": "CPI",
  "af_c_id": "cid12345",
  "attributed_touch_time_selected_timezone": "2019-12-31 00:06:32.891+0000",
  "selected_currency": "EUR",
  "app_name": "com.pds.pushapi2.v2.transparent.com",
  "install_time_selected_timezone": "2019-12-31 00:07:14.961+0000",
  "postal_code": "98052",
  "wifi": false,
  "install_time": "2019-12-31 00:07:14.961",
  "operator": "ORANGE",
  "attributed_touch_type": "click",
  "af_attribution_lookback": "25d",
  "keyword_match_type": null,
  "af_adset_id": "adset12345",
  "device_download_time_selected_timezone": "2019-12-31 00:07:14.961+0000",
  "contributor_2_media_source": "contrib2",
  "contributor_2_match_type": "id_matching",
  "api_version": "2.0",
  "attributed_touch_time": "2019-12-31 00:06:32.891",
  "revenue_in_selected_currency": null,
  "is_retargeting": false,
  "country_code": "US",
  "gp_click_time": "2019-12-31 00:07:12.000",
  "contributor_1_af_prt": "attributionagency",
  "match_type": "id_matching",
  "appsflyer_id": "e126a3b3-3406-4196-a964-563c9ae44ff8",
  "dma": "819",
  "http_referrer": "https://www.amazon.com/gp/bestsellers/gift-cards/ref=sv_gc_0",
  "af_sub5": "sub5-12345",
  "af_prt": "attributionagency",
  "event_revenue_currency": null,
  "store_reinstall": null,
  "install_app_store": null,
  "media_source": "pdsagency_int",
  "deeplink_url": null,
  "campaign": "pushapi_v2",
  "af_keywords": "keywords12345",
  "region": "NA",
  "cost_in_selected_currency": "1000",
  "event_value": null,
  "ip": "20.168.174.166",
  "oaid": null,
  "event_time": "2019-12-31 00:07:14.961",
  "is_receipt_validated": null,
  "contributor_1_campaign": "camp1",
  "af_sub4": "sub4-12345",
  "imei": null,
  "contributor_3_campaign": "camp3",
  "event_revenue_usd": null,
  "af_sub2": "sub2-12345",
  "original_url": "https://app.appsflyer.com/com.pds.pushapi2.v2.transparent.com?c=pushapi_v2&pid=pdsagency_int&clickid=click12345&af_ref=000632-31122019&advertiserId=9173fe74-0578-4658-a461-ebb0b4fce6d6&android_id=3e06b4caebc19356&sha1_android_id=sha12345&af_siteid=136396&af_sub_siteid=sub_siteid12345&af_c_id=cid12345&af_adset=adset12345&af_adset_id=adset12345&af_ad=ad12345&af_ad_id=adid12345&af_ad_type=adtype12345&af_channel=channel12345&af_keywords=keywords12345&is_retargeting=False&af_dp=ebay%3A%2F%2Fshoppingcart&af_web_dp=www.dp.com&af_sub1=sub1-12345&af_sub2=sub2-12345&af_sub3=sub3-12345&af_sub4=sub4-12345&af_sub5=sub5-12345&af_cost_model=CPI&af_cost_value=10&af_cost_currency=EUR&sha1_advertising_id=sha12345&sha1_el=sha12345&af_installpostback=false&af_force_dp=true&af_chrome_lp=true&af_ec=1&af_click_lookback=25d&af_viewthrough_lookback=1h&af_reengagement_window=2d&af_prt=attributionagency",
  "contributor_2_campaign": "camp2",
  "android_id": "3e06b4caebc19356",
  "contributor_3_media_source": "contrib3",
  "af_adset": "adset12345",
  "af_ad": "ad12345",
  "state": "WA",
  "network_account_id": null,
  "device_type": "Samsung::SH-220",
  "idfa": null,
  "retargeting_conversion_type": null,
  "af_channel": "channel12345",
  "af_cost_currency": "EUR",
  "contributor_1_media_source": "contrib1",
  "keyword_id": null,
  "device_download_time": "2019-12-31 00:07:14.961",
  "contributor_1_touch_type": "click",
  "af_reengagement_window": "2d",
  "af_siteid": "136396",
  "language": "English",
  "app_id": "com.pds.pushapi2.v2.transparent.com",
  "contributor_1_touch_time": "2019-12-31 00:06:07.847",
  "event_revenue": null,
  "af_ad_type": "adtype12345",
  "carrier": "carrier",
  "event_name": "install",
  "af_sub_siteid": "sub_siteid12345",
  "advertising_id": "9173fe74-0578-4658-a461-ebb0b4fce6d6",
  "os_version": "6.0",
  "platform": "android",
  "af_sub3": "sub3-12345",
  "contributor_3_match_type": "id_matching",
  "selected_timezone": "UTC",
  "af_ad_id": "adid12345",
  "contributor_3_touch_time": "2019-12-31 00:05:17.757",
  "user_agent": "Dalvik/1.6.0 (Linux; U; Android 6.0; Redmi Note 4 Build/KOT49I.F320S22g",
  "is_primary_attribution": null,
  "sdk_version": "v4.8.0",
  "event_time_selected_timezone": "2019-12-31 00:07:14.961+0000"
}

Mudando um ponto final

AppsFlyerAdmin_us-en.png Para modificar as definições do ponto final: 

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

Excluindo um ponto final

 AppsFlyerAdmin_us-en.pngPara excluir um endpoint:

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

Migrando um ponto final da V1.0 para V2.0

AppsFlyerAdmin_us-en.pngPara migrar um ponto final da V1.0 para V2.0:

  1. Acesse Integração > Acesso à API.
    Role para baixo até a seção da Push API.
    A seção da Push API será exibida.
  2. Localize o ponto final a ser migrado.
  3. Selecione os campos para preencher a mensagem da Push API.
    • 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 selecionados com mais frequência são pré-selecionados. Você pode limpar a seleção.
      • Selecione os campos opcionais conforme necessário.
      • Use Limpar tudo para limpar todos os campos opcionais.
      • Em um futuro próximo, vamos parar de enviar campos nulos/vazios e a chave associada. Leve isso em conta ao planejar seus processos de importação/análise.
  4. 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. 
  5. Clique em Salvar
    • A Push API foi migrada. 
    • Os dados de conversão continuam sendo enviados para o ponto final.

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 a ID do aplicativo, a URL do endpoint e uma captura de tela da mensagem de erro.  

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

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á um evento duplicado se tiver ativado os dois:

  • Instalar eventos in-app
  • eventos de retargeting in-app 

Eventos in-app atribuídos à fonte de mídia de UA (instalar eventos in-app) como parte de uma campanha de retargeting têm o campo is_primary_attribtuion=false. 

 Exemplo

  • Um usuário instala exemplo_app, que é atribuído a ua_network
  • Posteriormente, o usuário volta a participar da campanha de retargeting de example_app em retar_network e faz uma compra.

O evento de compra in-app é enviado duas vezes com os seguintes detalhes:

campos do evento de retargeting in-app
Tipo de evento Fonte de mídia is_retargeting re_targeting conversion_type is_primary_
attribution 
Instalar evento in-app ua_network verdadeiro reengajamento ou reatribuição  Falso
Eventos in-app de retargeting retar_network verdadeiro reengajamento ou reatribuição  verdadeiro


Como identificar eventos de retargeting duplicados?

O campo booleanois_primary_attribution identifica as fontes de mídia primárias e secundárias nas campanhas de retargeting:

  • Falso: identifica a fonte de mídia original de UA. Observação: esse é o único cenário em que o valor é falso. 
  • Verdadeiro: identifica a fonte de mídia de reengajamento 

O motivo disso é o seguinte: se um usuário, como resultado de uma campanha de retargeting, se envolver com a campanha, uma janela de reengajamento será aberta. A fonte de mídia de reengajamento é considerada a fonte de mídia primária quando a janela de reengajamento é aberta e a fonte de UA é secundária. Depois que a janela é fechada, a fonte de mídia original de UA volta a ser primária. 

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. 

Dados do Facebook ausentes

Por padrão, o Facebook não libera dados brutos a nível do usuário até que você aceite os Termos de Serviço do Facebook
Depois de aceitar os termos, dados a nível do usuário vindos do Facebook e de outras fontes de dados brutos serão enviados pela Push API.

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

Limitações e características

Características
Característica Observações 
Ad Networks Não deve ser usado por ad networks. 
Agências Não deve ser usado por agências
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 em tempo real
Dados históricos Não suportado. Os dados do evento são enviados após a configuração da Push API. Se você precisar do histórico de dados brutos, use a Pull API. 
Acesso de membro da equipe Os membros da equipe podem visualizar as configurações da Push API, mas não podem fazer alterações. 
Este artigo foi útil?