API de eventos de servidor para servidor (S2S mobile) para mobile

Visão geral: A API de eventos de servidor para servidor (S2S) para mobile envia eventos que ocorrem fora do aplicativo para a AppsFlyer. Eventos S2S são atribuídos de maneira semelhante aos eventos do SDK e estão disponíveis na plataforma. 

S2S_us-en.png

API de eventos de servidor para servidor para mobile

A plataforma da AppsFlyer atribui e grava eventos de aplicativos móveis pelo SDK da AppsFlyer e pelas APIs. Use a API S2S para reportar eventos que ocorrem fora do aplicativo. Por exemplo, um usuário renova a assinatura usando sua interface da web. Eventos S2S, uma vez gravados, estão disponíveis em toda a plataforma, incluindo painéis, dados brutos e analytics. Para eventos da web PBA, veja S2S Web para PBA.

A AppsFlyer preenche eventos S2S com:

  • Valores enviados na mensagem S2S
  • Alguns valores de atribuição da instalação da AppsFlyer, como hora de instalação e fonte de mídia

Instruções de uso da API

Crie sua chamada de API usando as informações contidas nas seções a seguir. 

Fatos da API S2S

Ponto final da API

https://api2.appsflyer.com/inappevent/app_id

  • app_id: O identificador do aplicativo usado no painel da AppsFlyer. Insira-o exatamente como aparece no painel.
  • Aplicativos iOS: certifique-se de que o prefixo é id.  Não fazer isso resulta em um código de retorno 200 OK válido, sem gravar o evento.
  • Windows: obtenha a ID do aplicativo na Microsoft App Store.
  • Exemplo Android: https://api2.appsflyer.com/inappevent/com.appsflyer.myapp
    iOS:https://api2.appsflyer.com/inappevent/id123456789
    Windows:https://api2.appsflyer.com/inappevent/a1b2c3d4e5f6
Método HTTP POST
Tipo de conteúdo aceito application/json
Autorização

--header 'authentication: dev_key'

  • dev_key é o token de autenticação no cabeçalho. 
  • Para obter a chave do desenvolvedor, na AppsFlyer vá para Definições do aplicativo > Chave do desenvolvedor
Incluir servidores na lista de permissões para receber mensagens de resposta

Incluir listas de endereços de IP AWS na lista de permissões para obter mensagens de resposta se seus servidores estiverem localizados atrás de uma firewall. 

Limitação de payload do JSON 

Tamanho do payload do JSON: até 1KB

Limitação de taxa

Volume de limitação do POST: 60.000 POSTs por minuto. Para aumentar esse limite, entre em contato com seu CSM.

Instruções de codificação
Codificar URLS

Codificar (porcentagem) caracteres reservados por código (https://tools.ietf.org/html/rfc3986#section-2.1) antes de formar a URL do método. 

TLS

Use TLS 1.2 ou superior. Cifras suportadas

Fatos da API S2S

Parâmetros do payload

  • Os parâmetros de payload consistem em um ou mais identificadores de dispositivo (dependendo do sistema operacional).
  • E se eu não conseguir enviar um identificador de dispositivo?
    • É possível que você não consiga enviar o identificador por um motivo fora do seu controle, como por exemplo no caso de o usuário possuir rastreamento de anúncios limitado (LAT) ou usar o iOS 14 sem dar o consentimento de ATT (sem IDFA).
    • Nesse caso, saiba que não  enviar uma ID de anúncios/identificador de dispositivo pode causar falha na atribuição,  o que significa que a AppsFlyer não pode atribuir o evento à fonte de mídia. Os eventos são registrados e exibidos em relatórios e dashboards. 
Sistema operacional Nome do identificador Descrição

iOS

iconAFios.png

 

idfa 

Onde disponível, preencha com o IDFA do dispositivo.

Formato: sequência

Exemplo: "idfa": "9876F1SS-2983-3855-27RR-2R626772VFNB"

idfv

Onde disponível, preencha com o IDFV do dispositivo.

Formato: String
Exemplo: "idfv":"95C9BD22-4A4C-41C8-9548-ED07C5C8C145"

Android

iconAFand.png

advertising_id

Quando disponível, preencha com o dispositivo GAID (código de publicidade)

Formato: sequência

Exemplo: "advertising_id": "9c9a82fb-d5de-4cd1-90c3-527441c11828"

oaid

Formato: sequência

Exemplo: "oaid": "1fe9a970-efbb-29e0-0bdd-f5dbbf751ab5"

amazon_aid

Formato: sequência

imei

Formato: sequência

Exemplo: "imei": "AA-BBBBBB-CCCCCC-D"

Identificadores de dispositivo
Nome do parâmetro Obrigatório Descrição

appsflyer_id

Sim

Um identificador exclusivo, gerado pela AppsFlyer, quando o aplicativo é iniciado pela primeira vez. 

  • Formato: sequência
  • Exemplo: "appsflyer_id ": " 1415211453000-6513894"

customer_user_id

Não

ID do usuário cliente, um identificador de usuário configurado pelo proprietário do aplicativo.

  • Formato: sequência. 
  • Exemplo: "customer_user_id ": "my_customer_number1234"

att

Não

iOS ATTrackingManager authorization status

  • Se a versão do sistema operacional do dispositivo for iOS 14 ou posterior, preencha att com AtTrackingManager.
    • Formato: Inteiro de um dígito 
    • Exemplo:  1
  • Os valores do iOS para AtTrackingManager são:
    • 0: Não determinado
    • 1: Restrito
    • 2: Negado
    • 3: Autorizado

Atenção! 

  • Como parte das políticas de privacidade da Apple, recomendamos que você preencha att com o valor AtTrackingManager. 
  • Você pode enviar esse parâmetro antes do lançamento oficial do iOS14. Começaremos a processá-lo após o lançamento oficial. 

 

ip

Não

O endereço de IP do dispositivo móvel durante a ocorrência do evento.

  • Se enviado, o endereço de IP é usado para preencher campos de geolocalização.
  • Se não for enviado, a AppsFlyer preenche o endereço de IP e os campos de geolocalização usando os valores do evento de atribuição de instalação. 
  • Formato: sequência contendo o endereço IPV4 ou IPV6
  • Exemplo: "ip": "192.0.2.1
af_events_api Descontinuado
  • Descontinuado a partir de 6 de julho de 2020.
  • Esse parâmetro não é necessário, você pode parar de enviá-lo. Isso não afeta a atribuição de forma alguma. 

eventName

Sim

Especifique o nome do evento. Certifique-se de que os nomes dos eventos estejam alinhados com os requisitos do profissional de marketing.

  • Formato: sequência
  • Exemplo: "eventName": "af_purchase"

Valor do evento

Sim

Se você enviar um evento sem um valor, envie: " event_value ":""

  • Os valores do evento precisam ser enviados sem símbolos ou formatação adicionais. 
  • Para af_revenue pode ser usada uma vírgula decimal. Valores negativos devem ser precedidos por um  -.
  • Formato: sequência em um JSON
  • Exemplo: "eventValue": "{ \"af_revenue\": \"6\", \"af_content_type\": \"wallets\", \"af_content_id\": \"15854\", \"af_quantity\" :\"1\" }"

app_version_name

Não

A versão ou o identificador do seu aplicativo.

  • Formato: sequência
  • Exemplo: "app_version_name": "my_app_version"

app_store

Não

Equivalente a AF_STORE em aplicativos Android. A store da qual o aplicativo foi baixado. 

  • Campo de dados brutos: Instalar App Store
  • Formato: sequência
  • Exemplo: my_android_store_is_best

Data/hora do evento

Não

A hora em que o evento ocorreu usando o fuso usário UTC.

  • Padrão: se nenhum eventTime for enviado, o horário será definido como o horário de chegada da mensagem HTTP.
  • Formato: na sequência aaaa-mm-dd hh:mm:ss.sss a hora deve estar no fuso horário UTC.
  • Exemplo: "eventTime":"2019-05-15 12:17:01.123" significa 12:17:01 UTC. 

Fim do dia:

  • Se você implementar eventTime o evento deverá ser recebido pela AppsFlyer até as 02:00 do dia seguinte. Ou seja, se o evento ocorreu na segunda-feira às 17:00 UTC, ele deve chegar aos servidores da AppsFlyer até a terça-feira 02:00 UTC. 
  • Os eventos recebidos após o fim do dia são carimbados com a hora de chegada real.
  • Eventos com horário futuro, ou seja, após o horário de chegada, são carimbados com o horário de chegada. 

Exemplo

  • Os horários estão em UTC
  • Um evento é enviado com eventTime = Segunda-feira 21:00.
Hora de chegada Hora gravada pela AppsFlyer Observação
Terça-feira 01:00 Segunda-feira 21:00 Chegou antes do fechamento do negócio.
Quarta-feira 09:00  Quarta-feira 09:00 Chegou após o fechamento do negócio. A hora é definida para a hora de chegada. 

eventCurrency

Não

Código de moeda usando códigos de 3 caracteres ISO 4217 e BCN (Bitcoin)

  • Padrão: USD
  • Exemplo: "eventCurrency": "ZAR"

bundleIdentifier

Não

Um identificador de aplicativo exclusivo. Nos dados brutos, o parâmetro preenche a ID do pacote.

  • Formato: sequência
  • Exemplo: "bundleIdentifer":"com.myapp"

sharing_filter

Não

O filtro de compartilhamento bloqueia o compartilhamento de eventos S2S via postbacks/API com parceiros integrados e outras integrações de terceiros. 

Use o filtro para atender a requisitos normativos como GDPR e CCPA, para cumprir com os mecanismos da opção do usuário por não participar e por outros motivos de lógica comercial. 

O sharing_filter tem as seguintes opções:

  • all: Todos os parceiros são bloqueados. Não compartilhe o evento com ninguém.  Exemplo: "sharing_filter": "all"
  • Lista de ids de parceiros em uma matriz. Formato ["partnerid_1", "partnerid_2", "partnerid_n"]  Exemplo: "sharing_filter": ["googleadwords_int","adcolony_int"]

Para uma lista de IDs de parceiros, entre em contato com o seu gerente de atendimento ao cliente ou com o suporte da AppsFlyer. 

Exemplo de ondulação

curl --location --request POST 'https://api2.appsflyer.com/inappevent/' \
--header 'authentication: <dev_key_placeholder>
' \
--header 'Content-Type: application/json' \
--data-raw '{
  "appsflyer_id": "9999999999999-9999999999999999999",
	"advertising_id": "aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa",
	"customer_user_id" : "example_customer_id_123",
	"ip": "199.0.2.1",
	"app_version_name" : "example_version_name",
	"eventTime" : "2020-02-25 12:00.000",
	"eventName": "af_purchase",
	"eventCurrency": "ZAR",
	"eventValue": 
	"{
		\"af_revenue\": \"1006\",
		\"af_content_type\": \"wallets\",
		\"af_content_id\": \"15854\",
		\"af_quantity\" :\"1\"
   }"
}}
'

Códigos de resposta

Código de resposta  Mensagem O que fazer
200 OK

Ao receber uma mensagem, a validação mínima de dados é realizada. Dessa forma, você pode obter um OK como resposta, mesmo que o evento não seja totalmente gravado na AppsFlyer. Para depurar eventos:

  • Usando o exemplo CURL neste artigo
    • Atualize a ID do aplicativo e os detalhes da chave do desenvolvedor.
    • Altere os parâmetros appsflyer_id e eventTime. Use o horário atual e um appsflyer_id recentemente atribuído como não orgânico.
  • Envie a chamada.
    • Ela deve retornar com uma mensagem 200 OK.
    • Verifique se o evento foi registrado corretamente, incluindo a receita
    • Faça alterações adicionais conforme necessário e teste novamente.
400 Falha ao autenticar Certifique-se de que a chave de autenticação está correta.
400  appsflyer_id é um campo obrigatório
  •  Certifique-se de passar o ID da AppsFlyer correto no JSON.
  • JOSN é stringified() e formatado corretamente
401 Não autorizado Quando a chave fornecida no cabeçalho de autenticação não é a <dev_key> para este aplicativo.
400 Erro na solicitação

Quando a solicitação falhou, pelo menos um dos critérios de validação.

400  Payload faltando ou que falhou no processamento
  • Certifique-se de que o JSON esteja em formato de string e formatado corretamente.
  • Se mais de um evento for incluído no payload do JSON. Certifique-se de enviar um evento por solicitação.
500  Erro interno do servidor  Verifique se o JSON está stringified() e formatado corretamente.
 

Testes

Considere: 

  • Para testar, use a IDA da AppsFlyer de uma instalação não orgânica para que o evento teste seja atribuído em tempo real. Eventos orgânicos são atribuídos com um atraso de algumas horas.
  • Alguns campos de eventos são preenchidos usando o evento de atribuição de instalação do usuário. Por exemplo, hora de instalação e a fonte de mídia. 

Para atribuir o dispositivo de teste como uma instalação não orgânica:

  1. Prepare um link de atribuição personalizado para testar mensagens S2S. Defina o parâmetro da fonte de mídia no link como s2s_test. Exemplo: &pid=s2s_test 
  2. Registre o dispositivo de teste
  3. Desinstale o aplicativo do dispositivo de teste.
  4. Envie o link para o dispositivo de teste.
  5. Clique no link.
  6. Instale e inicie o aplicativo.
  7. No painel, verifique se a instalação está atribuída.
  8. Busque a ID da AppsFlyer para usar na sua mensagem S2S.

Para enviar a mensagem S2S de teste:

  1. Prepare uma mensagem S2S usando a ID da AppsFlyer designada. Veja exemplos de código a seguir.
  2. Envie a mensagem.
  3. Siga um destes procedimentos para ver como a mensagem é gravada na AppsFlyer:
  4. Verifique e veja que:
    • Os valores enviados na mensagem S2S preenchem corretamente o relatório. Preste especial atenção aos campos Data do evento, Moeda do evento, Receita do evento e Valor do evento.
    • A fonte de atribuição e o tempo de instalação são preenchidos pela AppsFlyer.
    • Os valores fornecidos pelo próprio SDK, como a versão do SDK, não são preenchidos.

Código de exemplo para o envio de mensagens S2S

JavaPythonNode JSC#PHPGo
/* using the okhttp package 
install from maven https://mvnrepository.com/artifact/com.squareup.okhttp3/okhttp */
import okhttp3.*;
import java.io.IOException;

public class SendRequest {
  public static void main(String[] args) {

    OkHttpClient client = new OkHttpClient();
    MediaType mediaType = MediaType.parse("application/json");

    RequestBody body = RequestBody.create(mediaType, "" +
        "{\r\n\t\"appsflyer_id\": \"<APPS_FLYER_ID>\"," +
        "\r\n\t\"customer_user_id\": \"123456\",\r\n\t\"eventName\": \"af_purchase\",\r\n\t\"" +
        "eventValue\": \"{\\\"af_revenue\\\":\\\"6\\\" ,\\\"af_content_id\\\":\\\"15854\\\"}\",\r\n\t\"" +
        "eventCurrency\": \"USD\",\r\n\t\"" +
        "eventTime\": \"2018-08-10 4:17:00.000\",\r\n\t\"");

    Request request = new Request.Builder()
        .url("https://api2.appsflyer.com/inappevent/<APP_ID>")
        .post(body)
        .addHeader("Content-Type", "application/json")
        .addHeader("authentication", "<YOUR_DEV_KEY>")
        .build();

    try {
      Response response = client.newCall(request).execute();
      System.out.println(response.code());
      System.out.println(response.body().string());
    } catch (IOException e) {
      e.printStackTrace();
    }
  }
}

Enviar a ID de publicidade/identificador do dispositivo é importante

  • A ID de publicidade/identificador do dispositivo é obrigatória para garantir postbacks para SRNs, como Facebook e Google Ads. Se você não conseguir enviar a ID, leve em consideração que os postbacks não podem ser enviados.
  • Se você enviar apenas a ID da AppsFlyer, os eventos in-app serão gravados e atribuídos corretamente.

Como preencher parâmetros

Diferença entre orgânico e não orgânico

Quando a AppsFlyer processa eventos in-app S2S, os campos de atribuição são preenchidos usando a ID da AppsFlyer para identificar o evento de instalação associado que precedeu os eventos in-app.

O que isso significa é que alguns dados que a AppsFlyer associa a eventos in-app S2S não orgânicos não estão associados a eventos in-app S2S orgânicos.

 Exemplo

Por exemplo, se você comparar relatórios de dados brutos de eventos in-app S2S não orgânicos e orgânicos, os eventos não orgânicos contêm dados que os eventos in-app não orgânicos não contêm.

Eventos in-app não orgânicos incluem dados sobre a fonte de mídia, campanha, tipo de toque atribuído e hora do toque atribuído.

Eventos in-app orgânicos, por outro lado, seguem uma instalação orgânica. Instalações orgânicas não possuem dados relacionados a campanhas, fonte de mídia, tipo do toque atribuído e hora de instalação.

Mapeamento da ID da AppsFlyer com a ID de usuário cliente (CUID)

A lógica do back-end é necessária para obter valores para preencher o parâmetro. Veja a seguir como você pode obter a ID da AppsFlyer:

  • A ID da AppsFlyer é obrigatória e é usada para atribuir eventos.
  • É gerada quando um usuário instala o aplicativo móvel pela primeira vez.
  • Para que você possa mapear sua CUID para a ID da AppsFlyer, é necessário definir a CUID no aplicativo. 

Para que seja mais fácil saber qual usuário executou qual evento, implemente o fluxo abaixo:

  • Defina a ID de usuário cliente quando o usuário instalar o aplicativo.
  • Os relatórios de dados brutos da AppsFlyer contêm a CUID e a ID da AppsFlyer. Use uma das ferramentas de entrega de dados para obter essa API ou a Push API da AppsFlyer. 
  • Use os relatórios de dados brutos para combinar a CUID com a ID da AppsFlyer. 
  • A ID da AppsFlyer está disponível no SDK integrado ao seu aplicativo (Android/iOS).
  • Mapeie a ID da AppsFlyer para a ID de usuário cliente em seus sistemas internos (importante para uso futuro).

Depois de mapear a ID da AppsFlyer com sua CUID, você pode associar o usuário aos eventos realizados. Você pode obter os outros valores (valor do evento, moeda do evento, horário do evento etc.) e enviar o evento in-app servidor para servidor.  

 Exemplo de corpo de solicitação

{
  "appsflyer_id": "1415211453000-6513894",
	"advertising_id": "38412345-8cf0-aa78-b23e-10b96e40000d",
	"eventName": "af_purchase",
	"eventValue": 
	"{
		\"af_revenue\": \"6\",
		\"af_content_type\": \"wallets\",
		\"af_content_id\": \"15854\",
		\"af_quantity\" :\"1\"
   }",
	"eventCurrency": "USD",
	"ip": "1.2.3.4",
	"eventTime": "2014-05-15 12:17:00.000"
}


Neste caso, o AppsFlyer recebe um evento no aplicativo S2S que representa um evento de compra com receita, bem como propriedades adicionais, tais como tipo de conteúdo, etc.

Como buscar a ID da AppsFlyer

appsflyer_id é um parâmetro obrigatório em mensagens de evento de servidor para servidor. A AppsFlyer usa esse parâmetro para atribuir o evento ao dispositivo original e à fonte de mídia atribuída. Você pode obter a ID usando um dos seguintes métodos:

 Dica

Ao testar mensagens S2S, se você estiver usando dados brutos, procure o registro com a fonte de mídia "s2s_test". Esse é o seu dispositivo de teste e essa ID de dispositivo AppsFlyer é a ID que você precisa.

Envio de receitas negativas

Eventos com um valor negativo de receita podem ser enviados. Por exemplo, se uma compra foi cancelada. O parâmetro af_revenue pode ter valores negativos para registrar isso. 

Se você preencher uma af_quantity, poderá preenchê-la com um valor negativo, dependendo da lógica do sistema. A AppsFlyer não utiliza af_quantity .

Exemplo com receita negativa

{
	"eventName": "cancel_purchase",
	"eventValue": 
	"{
		\"af_revenue\": \"-6\",
		\"af_content_type\": \"wallets\",
		\"af_content_id\": \"15854\",
		\"af_quantity\" :\"1\"
   }",
	"eventCurrency": "USD",
	
}

Envio de eventos sem o valor do evento

Se você quiser enviar eventos sem um valor de evento, basta deixar uma string vazia no valor do evento: "eventValue":""

Em seguida, o AppsFlyer é capaz, de acordo com a configuração do anunciante, de enviar esses eventos avançados no aplicativo para fontes de mídia para fins de direcionamento avançado, otimização e criação de público.

Solução de problemas

Eventos não são exibidos no painel

  • Ponto final: verifique se o ponto final usado está correto.
  • Verifique se o payload contém os parâmetros obrigatórios. Veja aqui.
  • Certifique-se de que a ID da AppsFlyer que você está usando para disparar o evento é uma appsflyer_id real e que está realmente instalada no aplicativo específico. Não é uma ID de teste fornecida na documentação. Veja aqui.
  • Os eventos S2S não oferecem suporte a vários eventos em uma solicitação S2S. Cada evento deve ser enviado como um evento separado.
  • No painel de visão geral, o período está relacionado à data de instalação do aplicativo (LTV) e não à data do evento.
    • Certifique-se de selecionar o período correto.
    • Certifique-se de que o período do painel corresponde à data de instalação do dispositivo (appsflyer_id) e não à data do evento.
  • Relatórios de dados brutos do evento: o período está relacionado à data do evento e não à data da instalação.

Eventos não contêm receita

Se você enviar eventos S2S, mas sua receita não for registrada: certifique-se de que o JSON que você envia está em formato de sequência. A parte mais importante é o parâmetro do valor do evento no JSON. Deve estar em sequência como mostrado no exemplo a seguir.

"{\"af_revenue\":\"6\" ,\"af_content_type\":\"wallets\"}"

Se não estiver em sequência, o valor do evento não será processado corretamente e a receita não será gravada.

Os valores da receita não devem ser formatados de forma alguma. Eles podem conter uma vírgula decimal, mas isso não é obrigatório. Não inclua sinais de moeda ou códigos nem delimitadores como ,. A receita pode ser prefixada por um -

  • Os exemplos de valores válidos são: 123, -123.45123.456 
  • Exemplo de valores ilegais: 1,234.561,234

Nem todos os campos são preenchidos nos eventos S2S

Os campos de dados brutos são preenchidos usando o valor enviado na chamada S2S e alguns campos são preenchidos usando o evento de instalação.  Comportamento semelhante, mas não idêntico, é observado para eventos no aplicativo relatados usando o SDK da AppsFlyer. Existem algumas diferenças, como os seguintes campos, que não são preenchidos para eventos S2S:

  • WiFi
  • Operator
  • language
  • Tipo do dispositivo
  • Categoria de dispositivo
  • Versão do aplicativo: você pode usar app_version_name
  • Nome do aplicativo
Este artigo foi útil?