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.
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 |
|
| Método HTTP | POST |
| Tipo de conteúdo aceito | application/json |
| Autorização |
|
| Incluir servidores na lista de permissões para receber mensagens de resposta | |
| 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 |
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 de seu controle, como, por exemplo, porque o usuário tem rastreamento limitado de anúncios (LAT) ou usa o iOS 14 e não deu seu consentimento à ATT. Se o IDFV estiver disponível, envie-o.
- Não enviar um ID de anúncio/identificador de dispositivo pode causar:
- Problemas de postback: a fonte de mídia receberá o postback, mas sem um identificador de dispositivo. Consequentemente, a fonte de mídia não consegue associá-lo a um usuário.
- Segmentação de públicos e falha de regra. Os conjuntos de regras de públicos exigem identificadores. Envie um ID de dispositivo ou ID de usuário do cliente de acordo com o tipo de ID que seu conjunto de regras usa.
| Sistema operacional | Nome do identificador | Descrição |
|---|---|---|
|
iOS
|
idfa |
Onde disponível, preencha com o IDFA do dispositivo. Formato: sequência Exemplo: |
| idfv |
Onde disponível, preencha com o IDFV do dispositivo. Formato: String |
|
|
Android
|
advertising_id |
Quando disponível, preencha com o dispositivo GAID (código de publicidade) Formato: sequência Exemplo: |
| oaid |
Formato: sequência Exemplo: |
|
| amazon_aid |
Formato: sequência |
|
| imei |
Formato: sequência Exemplo: |
| Nome do parâmetro | Obrigatório | Descrição | |||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|
|
appsflyer_id |
Sim |
Um identificador exclusivo, gerado pela AppsFlyer, quando o aplicativo é iniciado pela primeira vez.
|
|||||||||
|
customer_user_id |
Não |
ID do usuário cliente, um identificador de usuário configurado pelo proprietário do aplicativo.
|
|||||||||
|
att |
Não |
iOS ATTrackingManager authorization status
Atenção! Recomendamos que você preencha |
|||||||||
|
ip |
Não |
O endereço de IP do dispositivo móvel durante a ocorrência do evento.
|
|||||||||
| Descontinuado |
|
||||||||||
|
eventName |
Sim |
Especifique o nome do evento. Certifique-se de que os nomes dos eventos estejam alinhados com os requisitos do profissional de marketing.
|
|||||||||
|
Valor do evento |
Sim |
Se você enviar um evento sem um valor, envie:
|
|||||||||
|
app_version_name |
Não |
A versão ou o identificador do seu aplicativo.
|
|||||||||
|
app_store |
Não |
Equivalente a AF_STORE em aplicativos Android. A store da qual o aplicativo foi baixado.
|
|||||||||
|
Data/hora do evento |
Não |
A hora em que o evento ocorreu usando o fuso usário UTC.
Fim do dia:
Exemplo
|
|||||||||
|
eventCurrency |
Não |
Código de moeda usando códigos de 3 caracteres ISO 4217 e BCN (Bitcoin)
|
|||||||||
|
bundleIdentifier |
Não* |
Um identificador único de aplicativo. Nos dados brutos, o parâmetro preenche o Bundle ID. [Prática recomendada] Sempre preencha esse parâmetro. Muitas redes de anúncios o solicitam para a otimização das campanhas.
|
|||||||||
|
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:
Para uma lista de IDs de parceiros, entre em contato com o seu gerente de atendimento ao cliente ou com o suporte da AppsFlyer. |
|||||||||
|
custom_dimension |
Não |
Reservado para uso futuro da AppsFlyer |
|||||||||
|
app_type |
Não |
Para aplicativos iOS. Valor permitido: Se o evento do usuário ocorrer em um app_clip, envie o parâmetro. Em todos os outros casos, não envie o parâmetro. |
|||||||||
|
custom_data |
Não |
Envie dados personalizados para a plataforma da AppsFlyer. Esse processo é semelhante ao envio de dados do SDK usando Em dados brutos: preenche o campo Formato: JSON, ilustrado no exemplo a seguir. Exemplo: |
|||||||||
| * Solicitado por muitas redes de anúncios para fins de otimização | |||||||||||
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:
|
| 400 | Falha ao autenticar | Certifique-se de que a chave de autenticação está correta. |
| 400 | appsflyer_id é um campo obrigatório |
|
| 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 |
|
| 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:
- Prepare um link de atribuição personalizado para testar mensagens S2S. Defina o parâmetro de fonte de mídia no link como s2s_test e defina o id de anúncio (GAID, IDFA, etc) no link, conforme ilustrado nos trechos de link de atribuição de exemplo.
- Registre o dispositivo de teste
- Desinstale o aplicativo do dispositivo de teste.
- Envie o link para o dispositivo de teste.
- Clique no link.
- Instale e inicie o aplicativo.
- No painel, verifique se a instalação está atribuída.
- Busque a ID da AppsFlyer para usar na sua mensagem S2S.
Para enviar a mensagem S2S de teste:
- Prepare uma mensagem S2S usando a ID da AppsFlyer designada. Veja exemplos de código a seguir.
- Envie a mensagem.
- Siga um destes procedimentos para ver como a mensagem é gravada na AppsFlyer:
- Faça o download do relatório de dados brutos de eventos in-app. Aguarde até 15 minutos após o envio do evento para que ele apareça no relatório de dados brutos.
- Push API (Considere usar ferramentas como Postman e o Webhook site.
- 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.
Exemplo de link de atribuição
Android
https://app.appsflyer.com/<app_id>?pid=s2s_test&c=test&advertising_id=<GAID>iOS
https://app.appsflyer.com/<app_id>?pid=s2s_test&c=test&idfa=<IDFA>Código de exemplo para o envio de mensagens S2S
/* 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();
}
}
}
''' using the requests python package, install using pip install requests '''
import requests
url = "https://api2.appsflyer.com/inappevent/[Insert app ID here]"
payload = "{\r\n \"appsflyer_id\": \"9999999999999999999999\",\r\n\t\"IDFA\":\"999999999999999999999999\",\r\n\t\"customer_user_id\" : \"14mar\",\r\n\t\"ip\": \"10.0.0.1\",\r\n\t\"app_version_name\" : \"example_version_name\",\r\n\t\"eventTime\" : \"2020-04-25 08:59:01.23\",\r\n\t\"eventName\": \"gaf_purchase\",\r\n\t\"eventCurrency\": \"ZAR\",\r\n\t\"eventValue\": \r\n\t\"{\r\n\t\t\\\"af_revenue\\\": \\\"1000\\\",\r\n\t\t\\\"af_content_type\\\": \\\"wallets\\\",\r\n\t\t\\\"af_content_id\\\": \\\"15854\\\",\r\n\t\t\\\"af_quantity\\\" :\\\"1\\\"\r\n }\"\r\n}"
headers = {
'authentication': '[Insert web dev key]',
'Content-Type': 'application/json'
}
response = requests.request("POST", url, headers=headers, data = payload)
print(response.text.encode('utf8'))
/* using the request npm package, install using npm install request */
var request = require("request");
var options = { method: 'POST',
url: 'https://api2.appsflyer.com/inappevent/<APP_ID>',
headers:
{
"authentication": '<YOUR_DEV_KEY>',
'Content-Type': 'application/json'
},
body:
{ appsflyer_id: '<APPS_FLYER_ID>',
customer_user_id: '123456',
eventName: 'node_js',
eventValue: '{"node_js":"6" ,"af_content_id":"15854"}',
eventCurrency: 'USD',
ip: '1.0.0.0',
eventTime: '2018-07-09 4:17:00.000'
},
json: true };
request(options, function (error, response, body) {
if (error) throw new Error(error);
console.log(body);
});/* using the RestSharp package, install using NuGet */
using System;
using RestSharp;
namespace CS
{
class Event
{
static void Main(string[] args)
{
var client = new RestClient("https://api2.appsflyer.com/inappevent/<APP_ID>");
var request = new RestRequest(Method.POST);
request.AddHeader("authentication", "<YOUR_DEV_KEY>");
request.AddHeader("Content-Type", "application/json");
var body = "{\"appsflyer_id\": \"<APPS_FLYER_ID>\"," +
"\"customer_user_id\": \"123456\"," +
"\"eventName\": \"af_purchase\"," +
"\"eventValue\": \"{\\\"af_revenue\\\":\\\"6\\\" ,\\\"af_content_id\\\":\\\"15854\\\"}\"," +
"\"eventCurrency\": \"USD\"," +
"\"eventTime\": \"2018-07-08 4:17:00.000\"
}";
request.AddParameter("undefined", body, ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
// handle response by reading response.StatusCode
Console.WriteLine(response.Content);
}
}
}
$purchase_event = array(
'appsflyer_id' => <APPS_FLYER_DEVICE_ID>,
'idfa' => <IDFA>,
'eventCurrency' => <PURCHASE_CURRENCY>,
'ip' => <DEVICE_ID_ADDRESS>,
'eventTime' => date("Y-m-d H:i:s.000", time())
);
$purchase_event['eventName'] = 'af_purchase';
$purchase_event['eventValue'] = json_encode(array('af_revenue' => <PURCHASE_REVENUE>,
'af_price' => <PURCHASE_PRICE>,
'af_order_id' => <PURCHASE_ORDER_ID>,
'af_currency' => <PURCHASE_CURRENCY>,
'af_content_type' => <PURCHASE_TYPE>,
'af_quantity' => <PURCHASE_QUANTITY>,
'af_content' => <PRODUCT_NAME>,
'af_content_id' => <PRODUCT_ID>)
);
$data_string = json_encode($purchase_event);
$ch = curl_init('https://api2.appsflyer.com/inappevent/<YOUR_APP_ID>');
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, "POST");
curl_setopt($ch, CURLOPT_HEADER, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, $data_string);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, array(
'Content-Type: application/json',
'authentication: <YOUR_APPS_FLYER_DEV_TOKEN>',
'Content-Length: ' . strlen($data_string))
);
$result = curl_exec($ch);
$curl = curl_init();
Script Go no Github da AppsFlyer
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:
- No dispositivo móvel, chame a API do SDK da AppsFlyer: Android, iOS.
- Na plataforma da AppsFlyer, use um dos seguintes: Pull API Push API,Exportar instalação de dados brutos.
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.45,123.456 - Exemplo de valores ilegais:
1,234.56,1,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