Documento

Referencia de la API de seguimiento de ingresos publicitarios

Realice un seguimiento de los ingresos por monetización de anuncios a nivel de impresió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

Ad Revenue API permite el seguimiento de la monetización de anuncios a nivel de impresión, donde las aplicaciones envían los datos de ingresos desde las plataformas de mediación a su backend, que los transmite a los servidores de Singular para el análisis y la generación de informes de ingresos publicitarios.

Funciones compatibles:

Ingresos por monetización de anuncios: Seguimiento de los ingresos a nivel de impresión de las plataformas de mediación
Atribución de plataformas: Conecte los ingresos publicitarios a las campañas de adquisición de usuarios
Integración de mediación: Compatibilidad con las principales plataformas de mediación publicitaria
Conversión de divisas: Conversión automática de divisas adaptada a la configuración de la organización

Arquitectura de flujo de datos

El seguimiento de ingresos publicitarios 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 ingresos a nivel de impresión del SDK de la plataforma de mediación.
Transmisión al servidor: La aplicación envía los datos de ingresos publicitarios 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 __ADMON_USER_LEVEL_REVENUE__ 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 ingresos publicitarios
Orden secuencial: Un orden de sesión no válido provoca incoherencias en los datos y errores de atribución
Datos de la plataforma de mediación: Recopile los atributos necesarios directamente del SDK de mediación: consulte la guía del SDKpara obtener más detalles sobre la implementació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.

Selección del punto final de la API

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

Selección de punto final: Elija el endpoint 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. Recuperar IDFV 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 conciencia de la privacidad para el mismo desarrollador. Siempre obligatorio: Debe incluirse en los dispositivos Google Play independientemente de la disponibilidad del GAID. Recuperar ASID Ejemplo: `edee92a2-7b2f-45f4-a509-840f170fc6d9`
`amid`	Android (Amazon)	ID de publicidad de Amazonpara dispositivos Amazon Fire sin Google Play Services. Necesario para dispositivos Amazon Recuperar AMID 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. Recuperar ANDI Ejemplo: `fc8d449516de0dfb`

Identificadores de punto final V2

Requisito de solo 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

ID de dispositivo singular obtenido de Singular SDK o generado en el cliente.

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

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

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)

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 que se está siguiendo. Nombre de evento requerido para ingresos por publicidad: `__ADMON_USER_LEVEL_REVENUE__` El nombre del evento debe ser TODO EN MAYÚSCULAS con guiones bajos. Máximo 32 caracteres ASCII
`e`	Cadena codificada con URL JSON que especifica atributos de evento personalizados de la plataforma de mediación. Atributos obligatorios: `ad_platform` - (OBLIGATORIO) Nombre de la red publicitaria Atributos opcionales: `ad_mediation_platform` `ad_type` `ad_group_type` `ad_impression_id` `ad_placement_name` `ad_unit_id` `ad_unit_name` `ad_group_id` `ad_group_name` `ad_group_priority` `ad_placement_id` Estructura JSON: `{ "ad_platform": "AdMob", "ad_mediation_platform": "admob.AdMobAdapter", "ad_unit_id": "ca-app-pub-6325336052/44923540" }` Ejemplo de URL codificada: `%7B%22ad_platform%22%3A%22AdMob%22%2C%22ad_mediation_platform%22%3A%22admob.AdMobAdapter%22%2C%22ad_unit_id%22%3A%22ca-app-pub-6325336052%5C%2F44923540%22%7D` Nota: Omitir atributos sin valores.
`is_admon_revenue`	Especifica si el evento es un evento de ingresos por monetización de anuncios para las métricas de ingresos por anuncios. Pase `true` para este evento Ejemplo: `true`
`is_revenue_event`	Especifica si el evento es un evento de ingresos para Revenue Metrics. Introduzca `true` para este evento Ejemplo: `true`
`amt`	Importe en divisa de los ingresos por impresión. Utilizar junto con el parámetro `cur` Ejemplo: `0.00782`
`cur`	Código de moneda ISO 4217de tres letras mayúsculas. Utilizar junto con el parámetro `amt` Ejemplo: `USD`

Parámetros opcionales

Los parámetros opcionales mejoran el seguimiento de los ingresos publicitarios con contexto y funcionalidad adicionales.

Parámetros de red

Parámetro Descripción

use_ip

Indica a Singular que extraiga la dirección IP de la solicitud 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

Ejemplos de solicitud

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

Descargo de responsabilidad del ejemplo: 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 de producción. Utilice i (identificador de aplicación) único 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',
    'aifa': '8ecd7512-2864-440c-93f3-a3cabe62525b',
    'asid': 'edee92a2-7b2f-45f4-a509-840f170fc6d9',
    'n': '__ADMON_USER_LEVEL_REVENUE__',
    'e': '{"ad_platform":"AdMob","ad_mediation_platform":"admob.AdMobAdapter","ad_unit_id":"ca-app-pub-6325336052/44923540"}',
    'is_admon_revenue': 'true',
    'is_revenue_event': 'true',
    'amt': 0.00782,
    'cur': 'USD'
}

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 "aifa=8ecd7512-2864-440c-93f3-a3cabe62525b" \
  --data-urlencode "asid=edee92a2-7b2f-45f4-a509-840f170fc6d9" \
  --data-urlencode "n=__ADMON_USER_LEVEL_REVENUE__" \
  --data-urlencode 'e={"ad_platform":"AdMob","ad_mediation_platform":"admob.AdMobAdapter","ad_unit_id":"ca-app-pub-6325336052/44923540"}' \
  --data-urlencode "is_admon_revenue=true" \
  --data-urlencode "is_revenue_event=true" \
  --data-urlencode "amt=0.00782" \
  --data-urlencode "cur=USD"

Ejemplo HTTP

GET /api/v1/evt
    ?a=sdk_key_here
    &p=Android
    &i=com.singular.app
    &ip=10.1.2.3
    &ve=9.2
    &aifa=8ecd7512-2864-440c-93f3-a3cabe62525b
    &asid=edee92a2-7b2f-45f4-a509-840f170fc6d9
    &n=__ADMON_USER_LEVEL_REVENUE__
    &e=%7B%22ad_platform%22%3A%22AdMob%22%2C%22ad_mediation_platform%22%3A%22admob.AdMobAdapter%22%2C%22ad_unit_id%22%3A%22ca-app-pub-6325336052%2F44923540%22%7D
    &is_admon_revenue=true
    &is_revenue_event=true
    &amt=0.00782
    &cur=USD 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("aifa", "8ecd7512-2864-440c-93f3-a3cabe62525b");
params.put("asid", "edee92a2-7b2f-45f4-a509-840f170fc6d9");
params.put("n", "__ADMON_USER_LEVEL_REVENUE__");
params.put("e", "{\"ad_platform\":\"AdMob\",\"ad_mediation_platform\":\"admob.AdMobAdapter\",\"ad_unit_id\":\"ca-app-pub-6325336052/44923540\"}");
params.put("is_admon_revenue", "true");
params.put("is_revenue_event", "true");
params.put("amt", "0.00782");
params.put("cur", "USD");

// 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 ingresos publicitarios de S2S antes de la implementación 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/launch con todos los parámetros requeridos.
Compruebe la consola SDK (sesión): En cuestión de segundos, el evento SESSION debería aparecer en SDK Console

SDK Console Session Event

Prueba de eventos de ingresos publicitarios

Activar impresión de anuncio: Genere una impresión publicitaria en la aplicación para activar la devolución de llamada de la plataforma de mediación.
Validar datos de mediación: Confirme que los datos de impresión enviados a su servidor contienen todos los atributos necesarios de la plataforma de mediación.
Verificar solicitud del servidor: Confirme que su servidor envía la solicitud EVENT a https://s2s.singular.net/api/v1/evt con todos los parámetros requeridos.
Compruebe la consola SDK (evento): En unos segundos, debería aparecer el evento __ADMON_USER_LEVEL_REVENUE__ en la consola SDK.
Repita las pruebas: Valide todas las impresiones de anuncios enviadas con los valores esperados y los importes de ingresos correctos

SDK Console Ad Revenue 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
Confirme que los detalles de la plataforma de mediación pasados en los argumentos del evento son correctos
Confirmar que el importe de los ingresos y la divisa son correctos

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

Recursos adicionales

Documentación de pruebas

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

Referencia de la API de seguimiento de ingresos publicitarios de servidor a servidor

Referencia de la API de seguimiento de ingresos publicitarios

Visión general

Caso de uso de servidor a servidor

Arquitectura de flujo de datos

Requisitos críticos

Selección del punto final de la API

Punto final de eventos V1

Casos de uso de V1

Endpoint de eventos V2

Casos de uso de V2

Identificadores de dispositivo necesarios

Identificadores de terminales V1

Identificadores específicos de plataforma

Identificadores de punto final V2

Requisito de solo SDID

Parámetros obligatorios

Autenticación de API

Parámetros del dispositivo

Parámetros de aplicación

Parámetros de evento

Parámetros opcionales

Parámetros de red

Privacidad de datos

Compatibilidad entre dispositivos

Ejemplos de solicitud

Ejemplo de Python

Ejemplo de cURL

Ejemplo HTTP

Ejemplo Java

Códigos de respuesta y errores

Pruebas y validación

Procedimiento de prueba

Validación de extremo a extremo

Prueba de eventos de ingresos publicitarios

Recursos adicionales

Documentación de pruebas