Referencia de la API de seguimiento de ingresos por publicidad

Realiza el 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 server-to-server como alternativa a la implementación del SDK.

Descripción general

Caso de uso server-to-server

La API de ingresos por publicidad permite el seguimiento de la monetización de anuncios a nivel de impresión, donde las apps reenvían los datos de ingresos desde las plataformas de mediación a tu backend, que los transmite a los servidores de Singular para el análisis y la generación de informes de ingresos por publicidad.

Funcionalidades admitidas:

• Ingresos por monetización de anuncios: Realiza el seguimiento de los ingresos a nivel de impresión desde las plataformas de mediación
• Atribución de plataforma: Conecta los ingresos por publicidad con las campañas de adquisición de usuarios
• Integración de mediación: Compatibilidad con todas las principales plataformas de mediación de anuncios
• Conversión de moneda: Conversión de moneda automática alineada con la configuración de la organización

Arquitectura del flujo de datos

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

1. Recopilación en el cliente: La app recopila los datos de ingresos a nivel de impresión desde el SDK de la plataforma de mediación
2. Transmisión al servidor: La app reenvía los datos de ingresos por publicidad a tu servidor backend
3. Consulta al 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 __ADMON_USER_LEVEL_REVENUE__ al endpoint de la API REST de Singular

Requisitos críticos

Selección del endpoint de la API

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

Endpoint de eventos V1

Casos de uso de V1

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

Recomendado para:

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

URL del endpoint:

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

Endpoint de eventos V2

Casos de uso de V2

Usa el endpoint de eventos V2 para integraciones híbridas donde el SDK de Singular realiza el seguimiento de sesiones mediante el SDID y el servidor envía los eventos usando el mismo SDID.

Recomendado para:

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

URL del endpoint:

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

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 la plataforma a continuación.

Identificadores del endpoint V1

Identificadores específicos de la plataforma

El endpoint de eventos 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 que se definen una sola vez en Fundamentos de S2S .

Identificadores del endpoint V2

Requisito de solo SDID

El endpoint de eventos 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 que se definen una sola vez en Fundamentos de S2S .

Parámetros del dispositivo

Estos son parámetros S2S compartidos que se definen una sola vez en Fundamentos de S2S .

Parámetros de la aplicación

Estos son parámetros S2S compartidos que se definen una sola vez en Fundamentos de S2S .

Parámetros del evento

__ADMON_USER_LEVEL_REVENUE__

{
  "ad_platform": "AdMob",
  "ad_mediation_platform": "admob.AdMobAdapter",
  "ad_unit_id": "ca-app-pub-6325336052/44923540"
}

%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

Parámetros opcionales

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

Parámetros de red

Estos son parámetros S2S compartidos que se definen una sola vez en Fundamentos de S2S .

Privacidad de los datos

Estos son parámetros S2S compartidos que se definen una sola vez en Fundamentos de S2S .

Compatibilidad con múltiples dispositivos

Estos son parámetros S2S compartidos que se definen una sola vez en Fundamentos de S2S .

Ejemplos de solicitud

El código de muestra demuestra la integración del endpoint EVENT de ingresos por publicidad 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',
    '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())

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"

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

// 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 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 ingresos por publicidad S2S antes de la implementación en producción usando la Consola del SDK 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 Consola del SDK de Singular
2. Habilitar el registro de la consola: Agrega el identificador del dispositivo en la Consola del SDK para capturar los datos de prueba
3. Usar el ID de app 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 e iniciar: Compila o abre la app desde el estado cerrado
5. Validar los datos del cliente: Confirma que la app envía todos los puntos de datos de Singular requeridos a tu servidor
6. Verificar la sesión: Confirma que tu servidor envía la solicitud SESSION a https://s2s.singular.net/api/v1/launch con todos los parámetros requeridos
7. Comprobar la Consola del SDK (sesión): En cuestión de segundos, el evento SESSION debería aparecer en la Consola del SDK

Prueba del evento de ingresos por publicidad

1. Activar impresión de anuncio: Genera una impresión de anuncio en la app para disparar el callback de la plataforma de mediación
2. Validar los datos de mediación: Confirma que los datos de la impresión se enviaron a tu servidor con todos los atributos requeridos de la plataforma de mediación
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. Comprobar la Consola del SDK (evento): En cuestión de segundos, el evento __ADMON_USER_LEVEL_REVENUE__ debería aparecer en la Consola del SDK
5. Repetir las pruebas: Valida que todas las impresiones de anuncios se enviaron con los valores esperados y los importes de ingresos correctos

Recursos adicionales

Documentación de pruebas

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