Referencia de la API del endpoint EVENT
Rastree 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 servidor a servidor, como alternativa a la implementación del SDK.
Descripción general
Caso de uso servidor a servidor
El endpoint EVENT rastrea eventos in-app e ingresos para el análisis de atribución y la optimización de campañas. ¿Es nuevo en servidor a servidor? Consulte la guía de fundamentos de S2S para conocer los conceptos básicos y la configuración común.
Capacidades admitidas:
- Atribución de eventos: Conecte las acciones de los usuarios con las campañas de marketing
- Seguimiento de ingresos: Mida y atribuya las compras in-app y las transacciones
- Eventos personalizados: Rastree cualquier interacción del usuario, desde registros hasta niveles completados
- Propiedades de eventos: Adjunte datos contextuales a los eventos para un análisis más profundo
Caso de uso híbrido: En una integración híbrida, el SDK de Singular es obligatorio y gestiona el seguimiento de sesiones, por lo que no se usa el endpoint SESSION. Su servidor envía eventos al endpoint EVENT V2 usando el Singular Device ID (SDID) proporcionado por el SDK.
Requisitos críticos
Requisitos previos:
- Sesión antes que los eventos: La SESSION debe establecerse antes de rastrear cualquier evento
- Orden secuencial: Un orden de sesión inválido genera inconsistencias en los datos y errores de atribución
Lineamientos para el seguimiento de eventos
Implemente el seguimiento de eventos siguiendo las mejores prácticas de Singular para convenciones de nomenclatura y estructura de datos.
Definición de eventos
Definir 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 las campañas.
Guía de planificación de eventos: Definir eventos in-app
Impacto de la nomenclatura de eventos: Los nombres de eventos que se envían a Singular determinan directamente cómo aparecen los eventos en los informes, las exportaciones y los postbacks.
Nomenclatura estándar de eventos
Mejores prácticas:
- Eventos estándar: Use la convención de nomenclatura de eventos estándar de Singular para agilizar la asignación en las integraciones con partners
- Idioma inglés: Envíe los nombres de eventos en inglés para garantizar la compatibilidad con partners externos y soluciones de análisis
- Atributos estándar: Use los nombres de atributos de eventos estándar para las propiedades de eventos
Limitaciones de caracteres
Restricciones de longitud:
- Nombres de eventos: Máximo 32 caracteres ASCII (32 bytes al convertirse a UTF-8 en caso de caracteres no ASCII)
- Atributos de eventos: Máximo 500 caracteres ASCII por clave y valor de atributo
Elección del endpoint
El endpoint EVENT tiene dos versiones. Use los acordeones a continuación para ver la URL del endpoint y el identificador de dispositivo obligatorio de cada una. Todos los demás parámetros son compartidos y se documentan una sola vez en Parámetros obligatorios y Parámetros opcionales más abajo.
V2 obligatorio a partir del 15 de julio de 2026. Las cuentas creadas a partir del 15 de julio de 2026 deben usar Event Endpoint V2 (basado en SDID); V1 no está disponible para cuentas nuevas. Los clientes existentes ya integrados con V1 no se ven afectados. Comuníquese con su Customer Success Manager de Singular si desea migrar a V2.
Use V2 para integraciones híbridas en las que el SDK de Singular rastrea las sesiones con el Singular Device ID (SDID) y su servidor envía los eventos usando ese mismo SDID. V2 evita el uso de identificadores de dispositivo específicos de cada plataforma.
POST https://s2s.singular.net/api/v2/evtIdentificador obligatorio:
| Parámetro | Detalles |
|---|---|
sdid
|
Plataformas:
iOS, Android, Web, PC, Xbox, PlayStation, Nintendo, MetaQuest, CTV
|
Use V1 para integraciones puramente del lado del servidor, o para integraciones híbridas en las que el SDK de Singular no usa el SDID y que dependen de identificadores de dispositivo específicos de cada plataforma (IDFA, IDFV, AIFA, ASID, etc.).
POST https://s2s.singular.net/api/v1/evtIdentificadores obligatorios (al menos uno):
| Parámetro | Detalles |
|---|---|
idfa
|
Plataforma:
iOS
|
idfv
|
Plataforma:
iOS
|
aifa
|
Plataforma:
Android
|
asid
|
Plataforma:
Android
|
amid
|
Plataforma:
Android
|
oaid
|
Plataforma:
Android
|
andi
|
Plataforma:
Android
Uso restringido: Prohibido en dispositivos con Google Play; use AIFA y ASID en su lugar. Envíelo únicamente si no hay ningún otro identificador disponible y la app no se distribuye a través de Google Play.
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 enviarse como datos
application/x-www-form-urlencoded
en el cuerpo de la solicitud usando el método POST. Las solicitudes deben incluir el encabezado
Content-Type: application/x-www-form-urlencoded
. No envíe los parámetros en un cuerpo de solicitud JSON.
Autenticación de la API
| Parámetro | Detalles |
|---|---|
a
|
Tipo:
String
Importante: No use la Reporting API Key. Las solicitudes serán rechazadas.
Ejemplo:
|
Parámetros del dispositivo
| Parámetro | Detalles |
|---|---|
p
|
Tipo:
String
|
ip
|
Tipo:
String
|
ve
|
Tipo:
String
|
ma
|
Plataforma:
iOS, Android
|
mo
|
Plataforma:
iOS, Android
|
lc
|
Plataforma:
iOS, Android
|
bd
|
Plataforma:
iOS, Android
|
Parámetros de la aplicación
| Parámetro | Detalles |
|---|---|
i
|
Tipo:
String
|
app_v
|
Tipo:
String
|
att_authorization_status
|
Plataforma:
iOS
Siempre obligatorio:
Aunque no implemente ATT, envíe
Ejemplo:
|
Parámetros del evento
| Parámetro | Detalles |
|---|---|
n
|
Tipo:
String
|
Parámetros opcionales
Los parámetros opcionales enriquecen el seguimiento de eventos con contexto y funcionalidades adicionales.
Parámetros de marca de tiempo
| Parámetro | Detalles |
|---|---|
utime
|
Tipo:
Integer
|
umilisec
|
Tipo:
Integer
|
Atributos de eventos
Compatibilidad con la Conversion API de partners:
Para reenviar estos eventos a partners de redes publicitarias mediante las integraciones de la Conversion API de Singular, incluya los atributos de evento opcionales estándar (datos propios con hash, como
eventId
y
ehash
). Consulte
Atributos de evento estándar para integraciones de la Conversion API
.
| Parámetro | Detalles |
|---|---|
e
|
Tipo:
JSON
|
global_properties
|
Tipo:
JSON
|
Parámetros de red
| Parámetro | Detalles |
|---|---|
use_ip
|
Tipo:
Boolean
Limitaciones:
Ejemplo:
|
country
|
Tipo:
String
|
ua
|
Tipo:
String
|
c
|
Plataforma:
iOS, Android
|
cn
|
Plataforma:
iOS, Android
|
Privacidad de los datos
| Parámetro | Detalles |
|---|---|
data_sharing_options
|
Tipo:
JSON
|
dnt
|
Plataforma:
iOS, Android
|
dntoff
|
Plataforma:
iOS, Android
|
Compatibilidad entre dispositivos
| Parámetro | Detalles |
|---|---|
custom_user_id
|
Tipo:
String
Sin PII: No envíe información de identificación personal. Use un identificador interno con hash o anonimizado de otra forma, no direcciones de correo electrónico, números de teléfono ni nombres sin procesar.
Ejemplo:
|
Compatibilidad con SKAdNetwork
| Parámetro | Detalles |
|---|---|
skan_conversion_value
|
Plataforma:
iOS
|
skan_first_call_timestamp
|
Plataforma:
iOS
|
skan_last_call_timestamp
|
Plataforma:
iOS
|
Seguimiento de ingresos
Rastree compras in-app y eventos de ingresos con la validación y el manejo de moneda adecuados.
Parámetros de ingresos obligatorios
Seguimiento básico de ingresos
Parámetros mínimos necesarios para el seguimiento de eventos de ingresos cuando usted realiza su propia validación de ingresos.
Mejor práctica: Valide los eventos de ingresos con las App Stores del lado de su servidor antes de enviar la solicitud del evento a Singular. Si realiza su propia validación, solo se requieren estos parámetros.
| Parámetro | Detalles |
|---|---|
is_revenue_event
|
Tipo:
Boolean
|
amt
|
Tipo:
Number
|
cur
|
Tipo:
String
|
Nota:
Enviar el parámetro
amt
hace que el evento se procese como un evento de ingresos independientemente del valor de
is_revenue_event
, incluido
is_revenue_event=false
. Si no desea que un evento se trate como de ingresos, omita el parámetro
amt
. Para marcar un evento de ingresos sin importe, envíe
is_revenue_event=true
.
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.
Requisitos de validación:
- Obligatorios si depende de Singular para la validación de ingresos con las App Stores
- Confirme la sintaxis correcta de los valores del recibo de compra y de la firma
-
Un formato incorrecto hace que Singular bloquee los ingresos y genere un evento
__iapinvalid__
| Parámetro | Detalles |
|---|---|
purchase_receipt
|
Plataforma:
iOS, Android
|
receipt_signature
|
Plataforma:
Android
|
purchase_product_id
|
Tipo:
String
|
purchase_transaction_id
|
Tipo:
String
|
Seguimiento de ingresos por publicidad
Rastree los ingresos por monetización publicitaria a nivel de impresión provenientes de plataformas de mediación (por ejemplo, AdMob, AppLovin MAX o ironSource) enviando un EVENT estándar con un nombre de evento fijo y atributos de monetización publicitaria. Los ingresos por publicidad usan el mismo endpoint EVENT documentado más arriba.
Datos de la plataforma de mediación: Recopile los atributos de ingresos por publicidad requeridos directamente desde el SDK de su plataforma de mediación. Consulte la Guía del SDK de ingresos por publicidad para conocer los atributos que proporciona cada plataforma de mediación.
Ingresos por monetización publicitaria
Además de los parámetros obligatorios estándar (autenticación, dispositivo y aplicación), los eventos de ingresos por publicidad requieren lo siguiente.
| Parámetro | Detalles |
|---|---|
n
|
Tipo:
String
|
is_admon_revenue
|
Tipo:
Boolean
|
is_revenue_event
|
Tipo:
Boolean
|
amt
|
Tipo:
Number
|
cur
|
Tipo:
String
|
e
|
Tipo:
JSON
Atributos opcionales:
Estructura JSON: Ejemplo codificado en URL: Nota: Omita los atributos que no tengan valor. |
Ejemplos de solicitudes
El código de muestra ilustra la integración del endpoint EVENT en varios lenguajes de programación.
Aviso sobre los ejemplos:
Es posible que las muestras de código no incluyan todos los parámetros obligatorios. Valide la lista completa de parámetros antes de la implementación en producción. Use un
i
(identificador de app) único para desarrollo y pruebas.
Ejemplo en Python
import requests
url = 'https://s2s.singular.net/api/v1/evt'
headers = {'Content-Type': 'application/x-www-form-urlencoded'}
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.post(url, data=params, headers=headers)
print(response.json())Ejemplo con cURL
curl -X POST "https://s2s.singular.net/api/v1/evt" \
-H "Content-Type: application/x-www-form-urlencoded" \
--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
POST /api/v1/evt HTTP/1.1
Host: s2s.singular.net
Content-Type: application/x-www-form-urlencoded
Accept: application/json
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_cartEjemplo en Java
// Endpoint
String endpoint = "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 form-urlencoded body
StringBuilder form = new StringBuilder();
for (Map.Entry<String, String> entry : params.entrySet()) {
if (form.length() > 0) form.append('&');
form.append(URLEncoder.encode(entry.getKey(), StandardCharsets.UTF_8))
.append('=')
.append(URLEncoder.encode(entry.getValue(), StandardCharsets.UTF_8));
}
byte[] body = form.toString().getBytes(StandardCharsets.UTF_8);
// Create connection
URL url = new URL(endpoint);
HttpURLConnection conn = (HttpURLConnection) url.openConnection();
conn.setRequestMethod("POST");
conn.setDoOutput(true);
conn.setRequestProperty("Content-Type", "application/x-www-form-urlencoded");
conn.setRequestProperty("Accept", "application/json");
// Write body
try (OutputStream os = conn.getOutputStream()) {
os.write(body);
}
// 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();
System.out.println("HTTP Status Code: " + responseCode);
System.out.println("Response: " + response.toString());
conn.disconnect();Códigos de respuesta y errores
El endpoint EVENT devuelve códigos de estado HTTP y respuestas JSON que indican si la solicitud fue exitosa o falló.
Documentación completa de errores: Códigos de respuesta S2S y manejo de errores
Pruebas y validación
Verifique 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
- Registre el dispositivo de prueba: Obtenga el ID publicitario del dispositivo y agréguelo a la SDK Console de Singular
- Habilite el registro en la consola: Agregue el identificador del dispositivo en la SDK Console para capturar los datos de prueba
-
Use un App ID de desarrollo:
Reemplace el identificador de la app por la versión de desarrollo (por ejemplo,
com.singular.app.dev) para separar los datos de prueba de los de producción - Compile e inicie: Compile o abra la app desde el estado cerrado
- Valide los datos del cliente: Confirme que la app envía a su servidor todos los datos requeridos por Singular
-
Verifique la sesión:
Confirme que su servidor envía la solicitud SESSION a
https://s2s.singular.net/api/v1/launchcon todos los parámetros obligatorios - Revise la SDK Console (sesión): En cuestión de segundos, el evento SESSION debería aparecer en la SDK Console
Pruebas de eventos
- Active un evento: Proceda a activar un evento en la app
- Valide los datos del evento: Confirme que el evento se envió a su servidor con todos los datos requeridos por Singular
-
Verifique la solicitud del servidor:
Confirme que su servidor envía la solicitud EVENT a su endpoint (V2
https://s2s.singular.net/api/v2/evto V1https://s2s.singular.net/api/v1/evt) con todos los parámetros obligatorios. - Revise la SDK Console (evento): En cuestión de segundos, el EVENT debería aparecer en la SDK Console
- Repita las pruebas: Valide que todos los eventos se envíen con los valores esperados
Verificaciones críticas:
- Confirme que el evento SESSION ocurre al abrir la app o pasarla a primer plano ANTES de recibir el EVENT
- Confirme que los datos obligatorios del EVENT coinciden con los datos de la SESSION
Indicador de éxito: Si los eventos aparecen en la SDK Console, ha completado con éxito la prueba de integración de eventos de extremo a extremo.
Recursos adicionales
Documentación de pruebas
Guía completa de pruebas: Guía de pruebas de integración S2S