Referencia de la API del endpoint EVENT

Registra eventos in-app e ingresos para el análisis de atribución y la optimización de campañas usando la API REST de Singular mediante una integración server-to-server como alternativa a la implementación del SDK.

Descripción general

Caso de uso server-to-server

La API EVENT permite el seguimiento de eventos in-app en el que las apps reenvían los datos de interacción del usuario a tu backend, que los transmite a los servidores de Singular para la atribución de eventos y los reportes de análisis de ingresos.

Capacidades compatibles:

• Atribución de eventos: Conecta las acciones del usuario con las campañas de marketing
• Seguimiento de ingresos: Mide y atribuye las compras in-app y las transacciones
• Eventos personalizados: Registra cualquier interacción del usuario, desde registros hasta finalizaciones de nivel
• Propiedades de eventos: Adjunta datos contextuales a los eventos para un análisis más profundo

Arquitectura del flujo de datos

El seguimiento de eventos server-to-server sigue un proceso de transmisión de datos de cuatro pasos.

1. Recolección en el cliente: La app recopila los datos del evento y los identificadores del dispositivo
2. Transmisión al servidor: La app reenvía los datos del evento a tu servidor backend
3. Consulta al device graph: El servidor recupera o actualiza los detalles del dispositivo desde el device graph de Singular
4. Llamada a la API de eventos: El servidor envía el evento al endpoint de la API REST de Singular

Requisitos críticos

Directrices para el seguimiento de eventos

Implementa el seguimiento de eventos siguiendo las prácticas recomendadas de Singular para las convenciones de nombres y la estructura de datos.

Definición de eventos

Definir eventos

Antes de implementar la integración S2S, define la lista completa de eventos que tu organización quiere registrar para el análisis del rendimiento de las campañas.

Guía de planificación de eventos: Definir eventos in-app

Impacto del nombre del evento: Los nombres de eventos enviados a Singular determinan directamente cómo aparecen los eventos en los reportes, las exportaciones y los postbacks.

Nomenclatura estándar de eventos

Limitaciones de caracteres

Selección del endpoint de la API

Singular ofrece dos versiones del endpoint EVENT optimizadas para diferentes arquitecturas de integración.

Event Endpoint V1

Casos de uso de V1

Usa el Event Endpoint V1 para integraciones que dependen de identificadores de dispositivo específicos de la plataforma (IDFA, IDFV, AIFA, ASID, etc.).

Recomendado para:

• Puramente del lado del servidor: Integraciones del lado del servidor sin implementación del SDK de Singular
• Híbrido (sin SDID): Integraciones híbridas en las que el SDK de Singular no usa el Singular Device ID (SDID)

URL del endpoint:

GET https://s2s.singular.net/api/v1/evt

Event Endpoint V2

Casos de uso de V2

Usa el Event Endpoint V2 para integraciones híbridas en las que el SDK de Singular registra las sesiones usando el SDID y el servidor envía los eventos usando el mismo SDID.

Recomendado para:

• Híbrido (basado en SDID): El SDK de Singular registra las sesiones con SDID y los eventos del lado del servidor usan el mismo SDID
• Identificadores simplificados: Implementaciones que evitan identificadores de dispositivo específicos de la plataforma (IDFA, AIFA, etc.)

URL del endpoint:

GET https://s2s.singular.net/api/v2/evt

Variante Web (p=Web)

Las integraciones web usan este mismo endpoint EVENT con p=Web . No hay llamada de SESSION web: el primer __PAGE_VISIT__ evento con conversion_event=true establece el touchpoint de atribución en lugar de un lanzamiento.

Parámetros específicos de Web

Estos parámetros aplican cuando p=Web . Los parámetros compartidos ( a , i , ip , sdid , custom_user_id ) se definen en Fundamentos de S2S .

Click IDs web: envía los click IDs de los partners ( ScCid , ttclid , gclid / gbraid / wbraid , dclid , fbclid , rdt_uuid ) dentro del parámetro de evento e .

Identificadores de dispositivo requeridos

Los requisitos de identificadores de dispositivo varían según la versión del endpoint y la plataforma. Revisa los requisitos específicos de cada plataforma a continuación.

Identificadores del endpoint V1

Identificadores específicos de la plataforma

El Event Endpoint V1 requiere identificadores de publicidad específicos de la plataforma según el sistema operativo del dispositivo y el método de distribución de la app.

Estos son parámetros S2S compartidos definidos una sola vez en Fundamentos de S2S .

Identificadores del endpoint V2

Requisito de solo SDID

El Event Endpoint V2 requiere únicamente el Singular Device ID (SDID) para todas las plataformas, lo que simplifica la identificación del dispositivo.

Parámetros requeridos

Todas las solicitudes EVENT deben incluir estos parámetros requeridos además de los identificadores de dispositivo.

Autenticación de la API

Estos son parámetros S2S compartidos definidos una sola vez en Fundamentos de S2S .

Parámetros del dispositivo

Estos son parámetros S2S compartidos definidos una sola vez en Fundamentos de S2S .

Parámetros de la aplicación

Estos son parámetros S2S compartidos definidos una sola vez en Fundamentos de S2S .

Parámetros del evento

Parámetros opcionales

Los parámetros opcionales enriquecen el seguimiento de eventos con contexto y funcionalidad adicionales.

Parámetros de timestamp

Atributos del evento

{
  "sng_attr_content_id": 5581,
  "sng_attr_content": "XBox",
  "sng_attr_content_type": "electronics"
}

%7B%22sng_attr_content_id%22%3A5581%2C%22sng_attr_content%22%3A%22XBox%22%2C%22sng_attr_content_type%22%3A%22electronics%22%7D

Parámetros de red

Estos son parámetros S2S compartidos definidos una sola vez en Fundamentos de S2S .

Privacidad de datos

Estos son parámetros S2S compartidos definidos una sola vez en Fundamentos de S2S .

Soporte cross-device

Estos son parámetros S2S compartidos definidos una sola vez en Fundamentos de S2S .

Soporte de SKAdNetwork

Seguimiento de ingresos

Registra las compras in-app y los eventos de ingresos con la validación adecuada y el manejo correcto de la moneda.

Parámetros de ingresos requeridos

Seguimiento básico de ingresos

Parámetros mínimos requeridos para el seguimiento de eventos de ingresos cuando realizas tu propia validación de ingresos.

Parámetros de validación de ingresos

Ingresos validados por Singular

Parámetros opcionales para que Singular realice la validación de ingresos del lado del servidor con las App Stores.

MIISqwYJKoZI...cNqts0jvcNvPcK7yuj0KhJ9nTTQ54kDKfReihzc6aw==

%7B%22orderId%22%3A%22GPA.1234%22%2C%22packageName%22%3A%22com.example%22%2C%22productId%22%3A%22com.example.product%22...

TyVJfHg8OAoW7W4wuJt...5agEDMnNXvhfrw==

Ejemplos de solicitudes

El código de muestra demuestra la integración del endpoint EVENT en varios lenguajes de programación.

import requests

params = {
    'a': 'sdk_key_here',
    'p': 'Android',
    'i': 'com.singular.app',
    'ip': '10.1.2.3',
    've': '9.2',
    'ma': 'samsung',
    'mo': 'SM-G935F',
    'lc': 'en_US',
    'bd': 'Build/13D15',
    'aifa': '8ecd7512-2864-440c-93f3-a3cabe62525b',
    'asid': 'edee92a2-7b2f-45f4-a509-840f170fc6d9',
    'n': 'sng_add_to_cart'
}

response = requests.get('https://s2s.singular.net/api/v1/evt', params=params)
print(response.json())

curl -G "https://s2s.singular.net/api/v1/evt" \
  --data-urlencode "a=sdk_key_here" \
  --data-urlencode "p=Android" \
  --data-urlencode "i=com.singular.app" \
  --data-urlencode "ip=10.1.2.3" \
  --data-urlencode "ve=9.2" \
  --data-urlencode "ma=samsung" \
  --data-urlencode "mo=SM-G935F" \
  --data-urlencode "lc=en_US" \
  --data-urlencode "bd=Build/13D15" \
  --data-urlencode "aifa=8ecd7512-2864-440c-93f3-a3cabe62525b" \
  --data-urlencode "asid=edee92a2-7b2f-45f4-a509-840f170fc6d9" \
  --data-urlencode "n=sng_add_to_cart"

GET /api/v1/evt
    ?a=sdk_key_here
    &p=Android
    &i=com.singular.app
    &ip=10.1.2.3
    &ve=9.2
    &ma=samsung
    &mo=SM-G935F
    &lc=en_US
    &bd=Build%2F13D15
    &aifa=8ecd7512-2864-440c-93f3-a3cabe62525b
    &asid=edee92a2-7b2f-45f4-a509-840f170fc6d9
    &n=sng_add_to_cart HTTP/1.1
Host: s2s.singular.net
Accept: application/json

// Base URL
String baseUrl = "https://s2s.singular.net/api/v1/evt";

// Parameters
Map<String, String> params = new HashMap<>();
params.put("a", "sdk_key_here");
params.put("p", "Android");
params.put("i", "com.singular.app");
params.put("ip", "10.1.2.3");
params.put("ve", "9.2");
params.put("ma", "samsung");
params.put("mo", "SM-G935F");
params.put("lc", "en_US");
params.put("bd", "Build/13D15");
params.put("aifa", "8ecd7512-2864-440c-93f3-a3cabe62525b");
params.put("asid", "edee92a2-7b2f-45f4-a509-840f170fc6d9");
params.put("n", "sng_add_to_cart");

// Build URL with encoded parameters
StringBuilder urlBuilder = new StringBuilder(baseUrl);
urlBuilder.append('?');

for (Map.Entry<String, String> entry : params.entrySet()) {
    if (urlBuilder.length() > baseUrl.length() + 1) {
        urlBuilder.append('&');
    }
    urlBuilder.append(URLEncoder.encode(entry.getKey(), StandardCharsets.UTF_8))
        .append('=')
        .append(URLEncoder.encode(entry.getValue(), StandardCharsets.UTF_8));
}

// Create connection
URL url = new URL(urlBuilder.toString());
HttpURLConnection conn = (HttpURLConnection) url.openConnection();
conn.setRequestMethod("GET");
conn.setRequestProperty("Accept", "application/json");

// Get response
int responseCode = conn.getResponseCode();
BufferedReader in = new BufferedReader(
    new InputStreamReader(conn.getInputStream())
);

String inputLine;
StringBuilder response = new StringBuilder();
while ((inputLine = in.readLine()) != null) {
    response.append(inputLine);
}
in.close();

// Check status
System.out.println("HTTP Status Code: " + responseCode);
System.out.println("Response: " + response.toString());

// Disconnect
conn.disconnect();

Códigos de respuesta y errores

El endpoint EVENT devuelve códigos de estado HTTP y respuestas JSON que indican el éxito o el fallo de la solicitud.

Documentación completa de errores: Códigos de respuesta S2S y manejo de errores

Pruebas y validación

Verifica la integración de eventos S2S antes del despliegue en producción usando la SDK Console de Singular para la validación de datos en tiempo real.

Procedimiento de prueba

Validación de extremo a extremo

1. Registrar dispositivo de prueba: Obtén el ID de publicidad del dispositivo y agrégalo a la SDK Console de Singular
2. Habilitar el logging en la consola: Agrega el identificador del dispositivo en la SDK Console para capturar los datos de prueba
3. Usar un App ID de desarrollo: Sobrescribe el identificador de la app con la versión de desarrollo (p. ej., com.singular.app.dev ) para separar los datos de prueba de los de producción
4. Compilar y lanzar: Compila o abre la app desde un estado terminado
5. Validar los datos del cliente: Confirma que la app envía todos los data points requeridos de Singular a tu servidor
6. Verificar la SESSION: Confirma que tu servidor envía la solicitud de SESSION a https://s2s.singular.net/api/v1/launch con todos los parámetros requeridos
7. Revisar la SDK Console (Session): En cuestión de segundos, el evento de SESSION debería aparecer en la SDK Console

Prueba de eventos

1. Disparar el evento: Procede a disparar un evento en la app
2. Validar los datos del evento: Confirma que el evento se envió a tu servidor con todos los data points requeridos de Singular
3. Verificar la solicitud del servidor: Confirma que tu servidor envía la solicitud EVENT a https://s2s.singular.net/api/v1/evt con todos los parámetros requeridos
4. Revisar la SDK Console (Event): En cuestión de segundos, el EVENT debería aparecer en la SDK Console
5. Repetir las pruebas: Valida que todos los eventos se envíen con los valores esperados

Recursos adicionales

Documentación de pruebas

Guía completa de pruebas: Guía de pruebas de integración S2S