Servidor a servidor - Referencia de la API del punto final EVENT

Documento

Referencia de la API EVENT Endpoint

Realice un seguimiento de los eventos y los ingresos dentro de la aplicación para el análisis de atribución y la optimización de campañas mediante la API REST de Singular a través de la integración de servidor a servidor como alternativa a la implementación de SDK.


Visión general

Caso de uso de servidor a servidor

EVENT API permite el seguimiento de eventos dentro de la aplicación donde las aplicaciones envían los datos de interacción del usuario a su backend, que los transmite a los servidores de Singular para la atribución de eventos y la generación de informes de análisis de ingresos.

Capacidades soportadas:

  • Atribución de eventos: Conectar las acciones del usuario a las campañas de marketing
  • Seguimiento de ingresos: Mide y atribuye las compras y transacciones dentro de la aplicación
  • Eventos personalizados: Realice el seguimiento de cualquier interacción del usuario, desde registros hasta finalización de niveles
  • Propiedades de eventos: Adjunte datos contextuales a los eventos para un análisis más profundo

Arquitectura de flujo de datos

El seguimiento de eventos de servidor a servidor sigue un proceso de transmisión de datos de cuatro pasos.

  1. Recopilación de clientes: La aplicación recopila datos de eventos e identificadores de dispositivos
  2. Transmisión al servidor: La aplicación envía los datos de los eventos a su servidor backend.
  3. Consulta del gráfico de dispositivos: El servidor recupera o actualiza los detalles del dispositivo desde el gráfico de dispositivos de Singular
  4. Llamada a la API de eventos: El servidor envía el evento al punto final de la API REST de Singular

Event Data Flow Diagram


Requisitos críticos

Requisitos previos:

  • Sesión antes de eventos: La SESIÓN debe establecerse antes de cualquier seguimiento de eventos
  • Orden secuencial: Un orden de sesión no válido provoca incoherencias en los datos y errores de atribución

Restricciones de integración:

  • Procesamiento en tiempo real: Las solicitudes se procesan individualmente, sin soporte de lotes
  • Eventos cronológicos: Los eventos deben enviarse en el orden en que se produjeron
  • Sin deduplicación: Singular no deduplica los datos; implemente la deduplicación en el servidor para evitar duplicados.
  • Permanencia de datos: Los datos a nivel de dispositivo no se pueden eliminar después de la ingestión; valídelos antes de enviarlos.

Directrices para el seguimiento de eventos

Implemente el seguimiento de eventos siguiendo las mejores prácticas de Singular en cuanto a convenciones de nomenclatura y estructura de datos.

Definición de Eventos

Definición de eventos

Antes de implementar la integración S2S, defina la lista completa de eventos que su organización desea rastrear para el análisis del rendimiento de la campaña.

Guía de planificación de eventos: Definición de Eventos In-App

Impacto de la denominación de eventos: Los nombres de eventos pasados a Singular determinan directamente cómo aparecen los eventos en los informes, exportaciones y postbacks.


Nombres de eventos estándar

Mejores prácticas:


Limitaciones de caracteres

Restricciones de longitud:

  • Nombres de eventos: Máximo 32 caracteres ASCII (32 bytes cuando se convierten a UTF-8 para no ASCII).
  • Atributos de eventos: Máximo 500 caracteres ASCII por clave y valor de atributo

Selección del punto final de la API

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

Selección de punto final: Elija el punto final en función de su arquitectura de integración y estrategia de identificador de dispositivo. El caso de uso determina el punto final correcto.

Punto final de eventos V1

Casos de uso de V1

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

Recomendado para:

  • Pure Server-Side: Integraciones del lado del servidor sin implementación de Singular SDK.
  • Híbrido (sin SDID): Integraciones híbridas en las que Singular SDK no utiliza Singular Device ID (SDID).

URL del punto final:

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

Endpoint de eventos V2

Casos de uso de V2

Use Event Endpoint V2 para integraciones híbridas donde Singular SDK rastrea sesiones usando SDID y el servidor envía eventos usando el mismo SDID.

Recomendado para:

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

URL de punto final:

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

Habilitación de cuenta: El punto final V2 requiere una configuración de cuenta Singular para el uso de SDID. Póngase en contacto con su ingeniero de soluciones o CSM para la habilitación.


Identificadores de dispositivo necesarios

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

Identificadores de terminales V1

Identificadores específicos de plataforma

Event Endpoint V1 requiere identificadores de publicidad específicos de la plataforma basados en el sistema operativo del dispositivo y el método de distribución de la aplicación.

Parámetro Plataforma Descripción
idfa iOS

El identificador para anunciantes (IDFA) permite el seguimiento de anuncios y la atribución de campañas.

Requisito ATT: iOS 14.5+ requiere la aceptación del usuario a través de App Tracking Transparency.

  • Omita el parámetro si IDFA no está disponible (el usuario denegó ATT)
  • Nunca pase NULL o una cadena vacía
  • Recuperar IDFA

Ejemplo: DFC5A647-9043-4699-B2A5-76F03A97064B

idfv iOS

El identificador para proveedores (IDFV)es coherente para todas las aplicaciones del mismo proveedor.

Siempre obligatorio: Debe incluirse independientemente del estado de ATT o de la disponibilidad de IDFA.

Ejemplo: 21DB6612-09B3-4ECC-84AC-B353B0AF1334

aifa Android
(Google Play)

El ID de publicidad de Google (GAID)permite el seguimiento publicitario restablecible por el usuario.

  • Obligatorio en dispositivos Google Play
  • Omitir en dispositivos que no sean de Google Play
  • Nunca pasar NULL o una cadena vacía
  • Recuperar AIFA

Ejemplo: 8ecd7512-2864-440c-93f3-a3cabe62525b

asid Android
(Google Play)

El ID de conjunto de aplicaciones de Androidproporciona un seguimiento de aplicaciones cruzadas con privacidad para el mismo desarrollador.

Siempre obligatorio: Debe incluirse en los dispositivos Google Play independientemente de la disponibilidad del GAID.

Ejemplo: edee92a2-7b2f-45f4-a509-840f170fc6d9

amid Android
(Amazon)

ID de publicidad de Amazonpara dispositivos Amazon Fire sin Google Play Services.

Ejemplo: df07c7dc-cea7-4a89-b328-810ff5acb15d

oaid Android
(OEM chinos)

Open Advertising Identifier (OAID) para dispositivos fabricados en China sin Google Play Services.

  • Necesario para dispositivos Huawei, Xiaomi, OPPO, Vivo sin Google Play
  • Recuperar OAID

Ejemplo: 01234567-89abc-defe-dcba-987654321012

andi Android
(Sin Google Play)

Android ID es un identificador de 64 bits generado por el dispositivo.

Uso restringido: Prohibido en dispositivos Google Play. Utilizar sólo si no hay otros identificadores disponibles y la aplicación no se distribuye a través de Google Play.

Ejemplo: fc8d449516de0dfb

sdid Web, PC, Consola, CTV

Identificador de dispositivo singular para plataformas sin identificadores de publicidad nativa.

  • Web: Obtenido de Singular Web SDK
  • PC/Consola: UUIDv4 generado por el cliente que representa la instalación única de la aplicación
  • Recuperar SDID

Ejemplo: 40009df0-d618-4d81-9da1-cbb3337b8dec

sing Sólo para empresas

Identificador definido por el cliente para casos de uso especiales en los que los identificadores estándar no están disponibles.

Restringido: Sólo para clientes empresariales: debe ser habilitado por el ingeniero de soluciones de Singular para cada aplicación.

Ejemplo: da534a95-1b1b-47d4-94b6-07955ec85177


Identificadores de punto final V2

Requisito de sólo SDID

Event Endpoint V2 sólo requiere Singular Device ID (SDID) para todas las plataformas, lo que simplifica la identificación de dispositivos.

Parámetro Descripción
sdid

Plataformas: iOS, Android, Web, PC, Xbox, PlayStation, Nintendo, MetaQuest, CTV

Singular Device ID obtenido de Singular SDK o generado por el cliente para PC/Console/CTV.

  • iOS/Android: Requiere habilitación de cuenta para uso de SDID-Método de devolución de llamada SDK proporciona SDID después de la inicialización.
  • Simplificación del identificador: Elimina la necesidad de parámetros AIFA, ASID, IDFA, IDFV.
  • Web: Obtenido de Singular Web SDK
  • PC/Consola/CTV: UUIDv4 generado por el cliente que representa la instalación única de la aplicación
  • Recuperar SDID

Ejemplo: 40009df0-d618-4d81-9da1-cbb3337b8dec


Parámetros obligatorios

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

Formato de los parámetros: Todos los parámetros deben pasarse como parámetros de consulta URL utilizando el método GET. No envíe parámetros en el cuerpo de la solicitud JSON.

Autenticación de API

Parámetro Tipo Descripción
a string

Clave SDK singular para la autenticación de la API.

Recuperar de: Singular UI → Menú principal → Herramientas para desarrolladores.

Importante: No utilice Reporting API Key-las solicitudes serán rechazadas.

Ejemplo: sdkKey_afdadsf7asf56


Parámetros del dispositivo

Parámetro Descripción
p

Plataforma de la aplicación (distingue mayúsculas de minúsculas).

Valores permitidos: Android, iOS, Web, PC, Xbox, Playstation, Nintendo, MetaQuest, CTV

Ejemplo: Android

ip

Dirección IPv4 pública del dispositivo. Se admite IPv6, pero se recomienda IPv4 por compatibilidad de atribución.

Ejemplo: 172.58.29.235

ve

Versión del sistema operativo del dispositivo en el momento del evento.

Ejemplo: 9.2

ma
iOS, Android

Marca del dispositivo (nombre del fabricante). Debe utilizarse con mo(modelo).

Recuperar marca del dispositivo

Ejemplos: Samsung, LG, Apple

mo
iOS, Android

Modelo de dispositivo. Debe utilizarse con ma (make).

Recuperar modelo de dispositivo

Ejemplos: iPhone 4S, Galaxy SIII

lc
iOS, Android

Etiqueta de configuración regional IETF: código de idioma y país de dos letras separado por un guión bajo.

Recuperar configuración regional del dispositivo

Ejemplo: en_US

bd
iOS, Android

Identificador de construcción del dispositivo, codificado en URL.

Recuperar compilación de dispositivo

Ejemplo: Build%2F13D15


Parámetros de aplicación

Parámetro Descripción
i

Identificador de la aplicación (distingue mayúsculas de minúsculas).

  • Android: Nombre del paquete (por ejemplo, com.singular.app)
  • iOS: ID del paquete (por ejemplo, com.singular.app)
  • Web: ID del producto
  • PC/Consola/CTV: Su identificador designado

Ejemplo: com.singular.app

att_authorization_status
iOS

Código de estado de App Tracking Transparency (ATT) (iOS 14.5+).

Valores de estado:

  • 0 - Indeterminado (no se muestra la indicación)
  • 1 - Restringido (seguimiento a nivel de dispositivo desactivado)
  • 2 - Denegado (autorización denegada al usuario)
  • 3 - Autorizado (usuario con autorización concedida)

Siempre obligatorio: Incluso si ATT no está implementado, pase 0 (indeterminado).

Ejemplo: 3


Parámetros de evento

Parámetro Descripción
n

Nombre del evento rastreado.

Ejemplo: sng_add_to_cart


Parámetros opcionales

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

Parámetros de marca de tiempo

Parámetro Tipo Descripción
utime int

Marca de tiempo Unix de 10 dígitos del evento.

Ejemplo: 1483228800

umilisec int

Marca de tiempo Unix de 13 dígitos con milisegundos.

Ejemplo: 1483228800000


Atributos del evento

Parámetro Descripción
e

Cadena JSON codificada en URL que especifica los atributos de evento personalizados.

Estructura JSON:

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

Ejemplo de URL codificada:

%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
global_properties

Objeto JSON codificado en URL que contiene pares clave-valor personalizados aplicados globalmente al evento.

Límites:

  • Máximo 5 pares clave-valor
  • Máximo 200 caracteres por clave y valor

JSON: {"key1":"value1","key2":"value2"}

URL codificado: %7B%22key1%22%3A%22value1%22%2C%22key2%22%3A%22value2%22%7D


Parámetros de red

Parámetro Descripción
use_ip

Indica a Singular que extraiga la dirección IP de la petición HTTP en lugar del parámetro ip.

Limitaciones:

  • Impide la geolocalización basada en IP por parte de Singular.
  • Proporcione el código de país de dos letras a través del parámetro country
  • Mutuamente excluyente con el parámetro ip
  • Debe proporcionar ip o use_ip

Ejemplo: true

country

Código de país de dos letras ISO 3166-1 alfa-2.

Obligatorio cuando: Dirección IP no disponible o use_ip=true

Ejemplo: US


Privacidad de datos

Parámetro Descripción
data_sharing_options

Consentimiento del usuario final codificado en URL JSON para compartir datos. Debe persistir y transmitirse en todas las solicitudes EVENT posteriores.

El usuario ha dado su consentimiento (Opted-In):

{"limit_data_sharing":false}

Usuario rechazado (Opted-Out):

{"limit_data_sharing":true}

URL codificada Ejemplo: %7B%22limit_data_sharing%22%3Atrue%7D


Compatibilidad entre dispositivos

Parámetro Descripción
custom_user_id

Su ID de usuario interno para el seguimiento entre dispositivos.

Ejemplo 123456789abcd


Soporte SKAdNetwork

Parámetro Descripción
skan_conversion_value
iOS

Último valor de conversión de SKAdNetwork en el momento del evento.

Más información: Implementación de SKAdNetwork

Ejemplo: 7

skan_first_call_timestamp
iOS

Marca de tiempo Unix de la primera llamada a la API SKAdNetwork.

Ejemplo: 1483228800

skan_last_call_timestamp
iOS

Unix timestamp de la llamada más reciente a la API de SKAdNetwork en el momento del evento.

Ejemplo: 1483228800


Seguimiento de ingresos

Realice un seguimiento de las compras dentro de la aplicación y de los eventos de ingresos con la validación y el manejo de divisas adecuados.

Parámetros de ingresos requeridos

Seguimiento básico de ingresos

Parámetros mínimos requeridos para el seguimiento de eventos de ingresos al realizar su propia validación de ingresos.

Práctica recomendada: Valide los eventos de ingresos con App Stores en su servidor antes de enviar la solicitud de evento a Singular. Si realiza su propia validación, sólo se requieren estos parámetros.

Parámetro Tipo Descripción
is_revenue_event string

Especifica si el evento es un evento de ingresos.

  • Puede omitirse si el nombre del evento es __iap__o se proporciona un valor distinto de cero amt

Ejemplo: true

amt double

Importe en divisas de la transacción.

  • Utilizar junto con el parámetro cur

Ejemplo: 2.51

cur string

Código de moneda ISO 4217de tres letras mayúsculas.

  • Utilizar junto con el parámetro amt

Ejemplo: USD


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 App Stores.

Requisitos de validación:

  • Obligatorio si se confía en Singular para la validación de ingresos con App Stores
  • Confirme la sintaxis correcta de los valores de recibo de compra y firma
  • Un formato incorrecto hace que Singular bloquee los ingresos y genere el evento __iapinvalid__
Parámetro Descripción
purchase_receipt
iOS, Android

Recibo recibido de la transacción de compra.

Ejemplo (iOS):

MIISqwYJKoZI...cNqts0jvcNvPcK7yuj0KhJ9nTTQ54kDKfReihzc6aw==

Ejemplo (Android, codificado con URL):

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

Firma utilizada para firmar el recibo de compra (solo Android).

Ejemplo:

TyVJfHg8OAoW7W4wuJt...5agEDMnNXvhfrw==
purchase_product_id

Identificador SKU del producto.

Ejemplo: com.example.product

purchase_transaction_id

Identificador de transacción.

Ejemplo (iOS): 380000123004321

Ejemplo (Android): GPA.1234-1234-1234-12345


Ejemplos de solicitud

El código de ejemplo demuestra la integración del punto final EVENT en varios lenguajes de programación.

Ejemplo Descargo de responsabilidad: Es posible que los ejemplos de código no incluyan todos los parámetros necesarios. Valide la lista completa de parámetros antes de la implementación en producción. Utilice un único i (identificador de aplicación) para el desarrollo/pruebas.

PYTHONCURLHTTPJAVA

Ejemplo de Python

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())

Códigos de respuesta y errores

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

Documentación completa sobre errores: S2S Response Codes & Error Handling


Pruebas y validación

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

Procedimiento de prueba

Validación de extremo a extremo

  1. Registre el dispositivo de prueba: Obtenga el ID de publicidad del dispositivo y añádalo a Singular SDK Console
  2. Habilitar registro en consola: Añadir identificador de dispositivo en SDK Console para capturar datos de prueba
  3. Usar ID de aplicación de desarrollo: Sustituya el identificador de la aplicación con la versión de desarrollo (por ejemplo, com.singular.app.dev) para separar los datos de prueba de los de producción.
  4. Crear e iniciar: Cree o abra la aplicación desde el estado finalizado
  5. Validar datos del cliente: Confirme que la aplicación envía todos los puntos de datos Singular necesarios a su servidor.
  6. Verificar sesión: Confirme que su servidor envía una solicitud de SESIÓN a https://s2s.singular.net/api/v1/launch con todos los parámetros requeridos.
  7. Compruebe la consola SDK (sesión): En cuestión de segundos, el evento SESSION debería aparecer en la consola SDK.

SDK Console Session Event


Prueba de eventos

  1. Activar Evento: Proceda a activar un evento en la aplicación
  2. Validar Datos de Evento: Confirme el evento enviado a su servidor con todos los puntos de datos Singular requeridos
  3. Verifique la solicitud del servidor: Confirme que su servidor envía la petición de EVENTO a https://s2s.singular.net/api/v1/evtcon todos los parámetros requeridos
  4. Compruebe la consola SDK (Evento): En cuestión de segundos, el evento debería aparecer en la consola SDK.
  5. Repita las pruebas: Valide todos los eventos enviados con los valores esperados

SDK Console Event

Verificaciones críticas:

  • Confirme que el evento SESSION se produce al abrir la aplicación/en primer plano ANTES de que se reciba el EVENTO
  • Confirmar que los puntos de datos requeridos por el EVENTO coinciden con los puntos de datos de la SESIÓN

Indicador de éxito: Si los eventos aparecen en la consola SDK, habrá completado con éxito la prueba de integración de eventos de extremo a extremo.


Recursos adicionales

Documentación de pruebas

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