De un vistazo: Envía eventos de tus servidores a AppsFlyer para medir los eventos móviles que ocurren fuera de la aplicación.
API de eventos de servidor a servidor para móviles
Para las aplicaciones de iOS, a partir de iOS 14 debes enviar el parámetro os (sistema operativo).
La plataforma de AppsFlyer atribuye y registra los eventos de aplicaciones móviles enviados por el SDK de AppsFlyer y por las API. Utiliza la API de S2S para reportar eventos que tienen lugar fuera de la aplicación; por ejemplo, un usuario renueva su suscripción usando tu interfaz web. Los eventos de S2S, una vez registrados, están disponibles a través de la plataforma, incluidos los paneles de control, el raw data y el análisis. Para los eventos web de la PBA, consulta S2S web para la PBA.
AppsFlyer rellena los eventos de S2S con:
- Los valores enviados en el mensaje S2S
- Algunos valores de atribución de la instalación de AppsFlyer, como la fecha y hora de instalación y la fuente de medios.
Instrucciones de uso de la API
Crea tu llamada de API usando la información contenida en las secciones a continuación.
Datos de la API de S2S
Punto de conexión API |
|
Método HTTP | POST |
Tipo de contenido aceptado | application/json |
Autorización |
|
Agregar servidores a la lista de permitidos para obtener mensajes de respuesta |
Si tus servidores están ubicados detrás de un firewall, debes incluir en la lista de permitidos el dominio appsflyer.com para recibir mensajes de respuesta. |
Limitación de la carga útil de JSON |
Tamaño de la carga útil de JSON: hasta 1 KB |
Limitación de velocidad |
Volumen de limitación de POST: 60 000 POST por minuto. Para aumentar este límite, contacta a tu CSM. |
Instrucciones de codificación |
|
Codificar las URL |
Codifica (porcentaje) los caracteres reservados para código (https://tools.ietf.org/html/rfc3986#section-2.1) antes de formar la URL del método. |
TLS |
Usa TLS 1.2 o superior. Cifrados compatibles |
Parámetros de la carga útil
- Los parámetros de la carga útil consisten en uno o más identificadores de dispositivo (dependiendo del sistema operativo).
-
¿Qué sucede si no puedo enviar un identificador de dispositivo?
- Es posible que no puedas enviar el identificador por una razón fuera de tu control, por ejemplo, porque el usuario tiene el rastreo de anuncios limitado (LAT) o porque utiliza el iOS 14 y no dio su consentimiento para ATT. Si el identificador de proveedor (IDFV) está disponible, envíalo.
- No enviar un ID de publicidad/identificador de dispositivo puede causar:
- Problemas de postback: La fuente de medios recibirá el postback pero sin un identificador de dispositivo; en consecuencia, la fuente de medios no puede asociarlo con un usuario.
- Segmentación de audiencias y fracaso de la regla. Los conjuntos de reglas de las audiencias requieren identificadores. Envía un ID de dispositivo o un ID de usuario de cliente de acuerdo con el tipo de ID que utiliza tu conjunto de reglas.
Sistema operativo | Nombre del identificador | Descripción |
---|---|---|
iOS
|
idfa |
Donde esté disponible, rellénalo con el identificador de anunciante (IDFA) del dispositivo. Formato: Secuencia Ejemplo: |
idfv |
Donde esté disponible, rellénalo con el identificador de anunciante (IDFA) del dispositivo. Formato: cadena |
|
Android |
advertising_id |
Donde esté disponible, rellénalo con el ID de publicidad de Google (GAID) del dispositivo (ID de publicidad). Formato: Secuencia Ejemplo: |
oaid |
Formato: Secuencia Ejemplo: |
|
amazon_aid |
Formato: Secuencia |
|
imei |
Formato: Secuencia Ejemplo: |
Parámetro | Obligatorio | Descripción | |||||||||
---|---|---|---|---|---|---|---|---|---|---|---|
appsflyer_id |
Sí |
Un identificador único generado por AppsFlyer cuando la aplicación se inicia por primera vez.
|
|||||||||
customer_user_id |
No |
ID de usuario de cliente, un identificador de usuario único establecido por el propietario de la aplicación.
|
|||||||||
att |
No |
Estado de autorización de ATTrackingManager de iOS
Nota: Te recomendamos que completes |
|||||||||
ip |
No |
La dirección IP del dispositivo móvil durante la ocurrencia del evento.
|
|||||||||
En desuso |
|
||||||||||
eventName |
Sí |
Especifica el nombre del evento. Asegúrate de que los nombres de los eventos estén alineados con los requisitos del marketer.
|
|||||||||
valor del evento |
Sí |
Si envías un evento sin ningún valor, entonces envía:
|
|||||||||
app_version_name |
No |
El identificador o la versión de tu aplicación.
|
|||||||||
app_store |
No |
Equivalente a AF_STORE en las aplicaciones para Android. La tienda desde la que se descargó la aplicación.
|
|||||||||
Hora del evento |
No |
La fecha y hora en que ocurrió el evento usando la zona horaria UTC.
Cierre del día:
Ejemplo
|
|||||||||
eventCurrency |
No |
Código de divisa usando códigos de 3 caracteres ISO 4217 y BCN (Bitcoin)
|
|||||||||
bundleIdentifier |
No* |
Un identificador único de la aplicación. En los raw data, el parámetro completa el Bundle ID. [Práctica recomendada] Completa siempre este parámetro. Muchas redes publicitarias lo requieren para la optimización de la campaña.
|
|||||||||
sharing_filter |
No |
El filtro de intercambio bloquea el intercambio de eventos S2S a través de postbacks/API con partners integrados y otras integraciones de terceros. Usa el filtro para cumplir con los requisitos normativos, como el RGPD y la CCPA, para cumplir con los mecanismos de exclusión opcional del usuario y por otros motivos comerciales lógicos. El filtro de intercambio sharing_filter tiene las siguientes opciones:
Para obtener una lista de ID de partners, comunícate con el soporte de AppsFlyer o con tu CSM. |
|||||||||
custom_dimension |
No |
Reservado para uso futuro de AppsFlyer |
|||||||||
app_type |
No |
Para aplicaciones de iOS. Valor permitido: Si el evento del usuario tiene lugar en un app_clip, envía el parámetro. En todos los demás casos, no se debe enviar el parámetro. |
|||||||||
custom_data |
No |
Envía datos personalizados a la plataforma de AppsFlyer. Similar al envío de datos desde el SDK usando En raw data: se completa el campo Formato: JSON, ilustrado en el siguiente ejemplo. Ejemplo:
|
|||||||||
os |
No** |
La versión del sistema operativo del dispositivo. Considera este parámetro como obligatorio para todas las plataformas. Formato: Secuencia Ejemplo: Nota: A partir del 1 de julio de 2021, para las aplicaciones de iOS, si no envías este parámetro, consideramos que los datos provienen de un dispositivo con iOS 14.5. |
|||||||||
aie |
No |
Utiliza este indicador para señalar si el usuario optó por no compartir su ID de anunciante. Utiliza este campo para los dispositivos que ejecutan Android (todas las versiones) o versiones de iOS anteriores a la 14. ¡Nota! Para iOS 14.5+, utiliza el parámetro att. Completa este campo de la siguiente manera:
|
|||||||||
* Requerido por muchas redes publicitarias con fines de optimización ** Para habilitar el procesamiento de datos correcto, debes enviar este parámetro. Por razones de compatibilidad con versiones anteriores, no aplicamos esto, por lo que no está marcado como obligatorio. |
Ejemplo de curl
curl --location --request POST 'https://api2.appsflyer.com/inappevent/<app_id_placeholder>' \
--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",
"os" : "14.6",
"att" : 3,
"eventValue":
"{
\"af_revenue\": \"1006\",
\"af_content_type\": \"wallets\",
\"af_content_id\": \"15854\",
\"af_quantity\" :\"1\"
}"
}
'
Códigos de respuesta
Código de respuesta | Mensaje | Cómo manejarlo |
---|---|---|
200 | OK |
Al recibir un mensaje, se realiza una validación mínima de los datos. Como tal, puedes obtener una respuesta OK aunque el evento no se registre completamente en AppsFlyer. Para depurar los eventos:
|
400 | Error de autenticación | Asegúrate de que la clave de autenticación sea correcta. |
400 | appsflyer_id es un campo obligatorio |
|
401 | No autorizado | Cuando la clave proporcionada en el encabezado de autenticación no es la <dev_key> de esta aplicación. |
400 | Solicitud incorrecta |
Cuando la solicitud no cumplió al menos uno de los criterios de validación. |
400 | Falta la carga de datos o no se la pudo analizar |
|
500 | Error interno del servidor | Verifica que el JSON se haya pasado a secuencia () y formateado correctamente. |
Pruebas
Ten en cuenta lo siguiente:
- Para las pruebas, usa el ID de AppsFlyer de una instalación no orgánica para que el evento de prueba se atribuya en tiempo real. Los eventos orgánicos se atribuyen con un retraso de unas pocas horas.
- Algunos campos de eventos se rellenan con el evento de atribución de la instalación del usuario. Por ejemplo, la fecha y hora de instalación y la fuente de medios.
Para atribuir el dispositivo de prueba como una instalación no orgánica:
- Prepara un enlace de atribución personalizado para probar los mensajes S2S. Configura el parámetro de la fuente de medios en el enlace como s2s_test y configura el ID de publicidad (GAID, IDFA, etc.) en el enlace como se ilustra en los fragmentos de enlace de atribución de ejemplo.
- Registrar el dispositivo de prueba
- Desinstala la aplicación del dispositivo de prueba.
- Envía el enlace al dispositivo de prueba.
- Haz clic en el enlace.
- Instala y luego inicia la aplicación.
- En el panel de control, comprueba que la instalación se haya atribuido.
- Obtén el ID de AppsFlyer para usarlo en tu mensaje de S2S.
Para enviar el mensaje de prueba de S2S:
- Prepara un mensaje de S2S usando el ID de AppsFlyer asignado. Consulta los siguientes ejemplos de código.
- Envía el mensaje.
- Haz una de las siguientes cosas para ver cómo se registra el mensaje en AppsFlyer:
- Descarga el reporte de raw data de eventos in-app. Espera hasta 15 minutos luego de enviar el evento para que aparezca en el reporte de raw data.
- Push API (considera el uso de herramientas como Postman y el sitio Webhook.)
- Comprueba lo siguiente:
- Los valores enviados en el mensaje de S2S rellenan correctamente el reporte. Presta especial atención a los campos Fecha del evento, Divisa del evento, Ingresos del evento y Valor del evento.
- AppsFlyer rellena la fuente de atribución y la fecha y hora de instalación.
- Los valores proporcionados por el propio SDK, como la versión del SDK, no están rellenados.
Enlace de atribución de ejemplo
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 ejemplo para enviar mensajes de 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\" +
"af_currency\": \"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 = "{\n\"appsflyer_id\": \"9999999999999999999999\",\n\"eventName\": \"test_purchase_cancel\",\n\"eventCurrency\": \"KRW\",\n\"eventValue\": \"{\\\"af_revenue\\\": \\\"-33000\\\"}\"\n}\n"
headers = {
'authentication': '[Insert 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>),
JSON_UNESCAPED_UNICODE);
$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();
Para AppsFlyer, ir al script de Github
El envío del ID de publicidad/identificador del dispositivo es importante
- El ID de publicidad/identificador del dispositivo es obligatorio para asegurar los postbacks a las SRN como Facebook y Google Ads. Si no puedes enviar el ID, ten en cuenta que los postbacks no se pueden enviar.
- Si solo envías el ID de AppsFlyer, los eventos in-app se registrarán y atribuirán correctamente.
Rellenar parámetros
Diferencia entre orgánicos y no orgánicos
Cuando AppsFlyer procesa los eventos in-app de S2S, los campos de atribución se rellenan usando el ID de AppsFlyer para identificar el evento de instalación asociado que precedió a los eventos in-app.
Esto significa que algunos datos que AppsFlyer asocia con eventos in-app S2S no orgánicos no se asocian con eventos in-app S2S orgánicos.
Ejemplo
Por ejemplo, si se comparan los reportes de datos sin procesar de eventos in-app S2S orgánicos y no orgánicos, se observa que los eventos no orgánicos contienen datos que no los orgánicos no.
Los eventos in-app no orgánicos incluyen datos sobre la fuente de medios, la campaña, el tipo de toque atribuido y la hora del toque atribuido.
Por otra parte, los eventos in-app orgánicos siguen una instalación orgánica. Las instalaciones orgánicas no tienen datos asociados a la campaña, la fuente de medios o el tipo de toque atribuido y la fecha y hora de instalación.
Asignación de ID de AppsFlyer con ID de usuario de cliente (CUID)
Se requiere lógica de backend para obtener valores para rellenar el parámetro. A continuación, se describe cómo se puede obtener el ID de AppsFlyer:
- El ID de AppsFlyer es obligatorio y se usa para atribuir eventos.
- Se genera cuando un usuario instala por primera vez la aplicación móvil.
- Para que puedas asignar tu CUID al ID de AppsFlyer, debes configurar el CUID en la aplicación.
Para que te sea más fácil saber qué usuario ejecutó qué evento, implementa el siguiente flujo:
- Configure el ID de usuario de cliente cuando el usuario instala la aplicación.
- Los reportes de raw data de AppsFlyer contienen el CUID y el ID de AppsFlyer. Usa una de las herramientas de entrega de datos para obtenerlo o la Push API de AppsFlyer.
- Usa los reportes de raw data para hacer coincidir el CUID con el ID de AppsFlyer.
- El ID de AppsFlyer está disponible en el SDK integrado en tu aplicación (Android/iOS).
- Asigna el ID de AppsFlyer al ID de usuario de cliente en tus sistemas internos (importante para uso futuro).
Una vez que asignas el ID de AppsFlyer con tu CUID, puedes hacer coincidir al usuario con los eventos realizados. Así, podrás obtener los demás valores (valor del evento, divisa del evento, fecha y hora del evento, etc.) y enviar el evento in-app de servidor a servidor.
Ejemplo de mensaje de solicitud
{
"appsflyer_id": "1415211453000-6513894",
"advertising_id": "38412345-8cf0-aa78-b23e-10b96e40000d",
"eventName": "af_purchase",
"eventValue":
"{
\"af_revenue\": \"6\",
\"af_currency\" \"USD"\",
\"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"
}
En este caso, AppsFlyer recibe un evento in-app S2S que representa un evento de compra con ingresos, así como propiedades adicionales tales como tipo de contenido, etc.
Obtener el ID de AppsFlyer
appsflyer_id
es un parámetro obligatorio en los mensajes de eventos de servidor a servidor. AppsFlyer usa este parámetro para atribuir el evento al dispositivo original y a la fuente de medios atribuida. Puedes obtener el ID usando uno de los siguientes métodos:
- Desde el dispositivo móvil llamando a la API SDK de AppsFlyer: Android, iOS.
- Desde la plataforma de AppsFlyer, usando uno de los siguientes: Pull API, Push API, Exportar raw data de instalación.
Consejo
Cuando pruebes mensajes S2S, si estás usando raw data, busca el registro con la fuente de medios "s2s_test". Este es tu dispositivo de prueba y su ID de dispositivo de AppsFlyer es el ID que necesitas.
Envío de ingresos negativos
Se pueden enviar los eventos que tienen un valor de ingresos negativo. Por ejemplo, si una compra se canceló. El parámetro af_revenue
puede tener valores negativos para registrar esto.
Si rellenas af_quantity
, es posible que quieras rellenarlo con un valor negativo dependiendo de la lógica de tu sistema. AppsFlyer no hace uso de af_quantity
.
Ejemplo con ingresos negativos
{
"eventName": "cancel_purchase",
"eventValue":
"{
\"af_revenue\": \"-6\",
\"af_content_type\": \"wallets\",
\"af_content_id\": \"15854\",
\"af_quantity\" :\"1\"
}",
"eventCurrency": "USD",
}
Resolución de Problemas
Los eventos no se muestran en el panel de control
- Punto de conexión: verifica que el punto de conexión utilizado sea el correcto.
- Verifica que la carga útil contiene los parámetros obligatorios. Ver aquí.
- Asegúrate de que el ID de AppsFlyer que estás usando para disparar el evento sea un appsflyer_id real que esté realmente instalado en la aplicación específica, y no un ID de prueba proporcionado en la documentación. Ver aquí.
- Los eventos de S2S no admiten múltiples eventos en una solicitud de S2S. Cada evento debe ser enviado como un evento separado.
- En el panel de control de información general, el intervalo de fechas se refiere a la fecha de instalación de la aplicación (LTV) y no a la fecha del evento.
- Asegúrate de seleccionar el intervalo de fechas correcto.
- Asegúrate de que el intervalo de fechas del panel de control corresponda a la fecha de instalación del dispositivo (appsflyer_id) y no a la fecha del evento.
- Reportes de raw data de eventos: el intervalo de fechas se refiere a la fecha del evento y no a la fecha de instalación.
Los eventos no contienen ingresos
Si envías eventos de S2S cuyos ingresos no se registran, asegúrate de que el JSON que envíes esté en formato de secuencia. Lo más importante es el parámetro de valor del evento en el JSON. Debe estar en formato de secuencia, como se muestra en el ejemplo que sigue.
"{\"af_revenue\":\"6\" ,\"af_content_type\":\"wallets\"}"
Si no tiene formato de secuencia, el valor del evento no se procesará correctamente y no se podrán registrar los ingresos.
Los valores de los ingresos no deben ser formateados de ninguna manera. Pueden contener un punto decimal. No incluyas signos o códigos de divisa ni delimitadores ,
. Los ingresos pueden tener un prefijo -
- Ejemplos de valores válidos:
123
,-123.45
,123.456
- Ejemplos de valores inválidos:
1,234.56
,1,234
No se rellenan todos los campos en los eventos de S2S
Los campos de raw data se rellenan con el valor enviado en la llamada de S2S y algunos campos se rellenan con el evento de instalación. Se observa un comportamiento similar pero no idéntico para los eventos in-app reportados usando el SDK de AppsFlyer. Hay algunas diferencias; específicamente, los siguientes campos no se rellenan para los eventos de S2S:
- WIFI
- Operator
- language
- Tipo de dispositivo
- Categoría de dispositivo
- Versión de la aplicación: Puedes usar
app_version_name
- Nombre de aplicación