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.
- Recopilación de clientes: La aplicación recopila datos de eventos e identificadores de dispositivos
- Transmisión al servidor: La aplicación envía los datos de los eventos a su servidor backend.
- Consulta del gráfico de dispositivos: El servidor recupera o actualiza los detalles del dispositivo desde el gráfico de dispositivos de Singular
- Llamada a la API de eventos: El servidor envía el evento al punto final de la API REST de Singular
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:
- Eventos estándar: Utilice la convención de nomenclatura de eventos estándar de Singularpara agilizar el mapeo de integración de socios.
- Idioma inglés: Pase los nombres de eventos en inglés para compatibilidad con socios de terceros y soluciones analíticas
- Atributos estándar: Utilice nombres de atributosde eventos estándarpara las propiedades de los eventos
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.
Ejemplo: |
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: |
aifa
|
Android (Google Play) |
El ID de publicidad de Google (GAID)permite el seguimiento publicitario restablecible por el usuario.
Ejemplo: |
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: |
amid
|
Android (Amazon) |
ID de publicidad de Amazonpara dispositivos Amazon Fire sin Google Play Services.
Ejemplo: |
oaid
|
Android (OEM chinos) |
Open Advertising Identifier (OAID) para dispositivos fabricados en China sin Google Play Services.
Ejemplo: |
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: |
sdid
|
Web, PC, Consola, CTV |
Identificador de dispositivo singular para plataformas sin identificadores de publicidad nativa.
Ejemplo: |
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: |
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.
Ejemplo: |
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: |
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: |
ip
|
Dirección IPv4 pública del dispositivo. Se admite IPv6, pero se recomienda IPv4 por compatibilidad de atribución.
Ejemplo: |
ve
|
Versión del sistema operativo del dispositivo en el momento del evento.
Ejemplo: |
maiOS, Android |
Marca del dispositivo (nombre del fabricante). Debe utilizarse con Recuperar marca del dispositivo
Ejemplos: |
moiOS, Android |
Modelo de dispositivo. Debe utilizarse con Recuperar modelo de dispositivo
Ejemplos: |
lciOS, 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: |
bdiOS, Android |
Identificador de construcción del dispositivo, codificado en URL. Recuperar compilación de dispositivo
Ejemplo: |
Parámetros de aplicación
| Parámetro | Descripción |
|---|---|
i
|
Identificador de la aplicación (distingue mayúsculas de minúsculas).
Ejemplo: |
att_authorization_statusiOS |
Código de estado de App Tracking Transparency (ATT) (iOS 14.5+). Valores de estado:
Siempre obligatorio: Incluso si ATT no está implementado, pase
Ejemplo: |
Parámetros de evento
| Parámetro | Descripción |
|---|---|
n
|
Nombre del evento rastreado.
Ejemplo: |
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: |
umilisec
|
int
|
Marca de tiempo Unix de 13 dígitos con milisegundos.
Ejemplo: |
Atributos del evento
| Parámetro | Descripción |
|---|---|
e
|
Cadena JSON codificada en URL que especifica los atributos de evento personalizados. Estructura JSON:
Ejemplo de URL codificada:
|
global_properties
|
Objeto JSON codificado en URL que contiene pares clave-valor personalizados aplicados globalmente al evento. Límites:
JSON:
URL codificado: |
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 Limitaciones:
Ejemplo: |
country
|
Código de país de dos letras ISO 3166-1 alfa-2.
Obligatorio cuando: Dirección IP no disponible o
Ejemplo: |
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):
Usuario rechazado (Opted-Out):
URL codificada Ejemplo: |
Compatibilidad entre dispositivos
| Parámetro | Descripción |
|---|---|
custom_user_id
|
Su ID de usuario interno para el seguimiento entre dispositivos.
Ejemplo |
Soporte SKAdNetwork
| Parámetro | Descripción |
|---|---|
skan_conversion_valueiOS |
Último valor de conversión de SKAdNetwork en el momento del evento. Más información: Implementación de SKAdNetwork
Ejemplo: |
skan_first_call_timestampiOS |
Marca de tiempo Unix de la primera llamada a la API SKAdNetwork.
Ejemplo: |
skan_last_call_timestampiOS |
Unix timestamp de la llamada más reciente a la API de SKAdNetwork en el momento del evento.
Ejemplo: |
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.
Ejemplo: |
amt
|
double
|
Importe en divisas de la transacción.
Ejemplo: |
cur
|
string
|
Código de moneda ISO 4217de tres letras mayúsculas.
Ejemplo: |
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_receiptiOS, Android |
Recibo recibido de la transacción de compra.
Ejemplo (iOS):
Ejemplo (Android, codificado con URL):
|
receipt_signatureAndroid |
Firma utilizada para firmar el recibo de compra (solo Android). Ejemplo:
|
purchase_product_id
|
Identificador SKU del producto.
Ejemplo: |
purchase_transaction_id
|
Identificador de transacción.
Ejemplo (iOS):
Ejemplo (Android): |
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.
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())
Ejemplo de cURL
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"
Ejemplo HTTP
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
Ejemplo Java
// 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 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
- Registre el dispositivo de prueba: Obtenga el ID de publicidad del dispositivo y añádalo a Singular SDK Console
- Habilitar registro en consola: Añadir identificador de dispositivo en SDK Console para capturar datos de prueba
-
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. - Crear e iniciar: Cree o abra la aplicación desde el estado finalizado
- Validar datos del cliente: Confirme que la aplicación envía todos los puntos de datos Singular necesarios a su servidor.
-
Verificar sesión: Confirme que su servidor envía una solicitud de SESIÓN a
https://s2s.singular.net/api/v1/launchcon todos los parámetros requeridos. - Compruebe la consola SDK (sesión): En cuestión de segundos, el evento SESSION debería aparecer en la consola SDK.
Prueba de eventos
- Activar Evento: Proceda a activar un evento en la aplicación
- Validar Datos de Evento: Confirme el evento enviado a su servidor con todos los puntos de datos Singular requeridos
-
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 - Compruebe la consola SDK (Evento): En cuestión de segundos, el evento debería aparecer en la consola SDK.
- Repita las pruebas: Valide todos los eventos enviados con los valores esperados
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