Documento

Referencia de la API de seguimiento de ingresos publicitarios

Caso de uso de servidor a servidor

Singular permite el seguimiento de los ingresos publicitarios a través de la API EVENT. Al reenviar los detalles de los ingresos a nivel de impresión desde su(s) plataforma(s) de mediación a su servidor utilizando controladores de eventos de pago, Singular procesa estos datos para una integración perfecta en informes, registros de exportación y devoluciones. La plataforma también admite la conversión automática de divisas de acuerdo con la configuración preferida de su organización.

La API REST de Singular permite la integración directa de servidor a servidor como alternativa al SDK. Mientras que el SDK recopila automáticamente los datos del dispositivo y de la aplicación, el enfoque S2S requiere que usted:

Recopilar los puntos de datos necesarios de la API EVENT de su aplicación.
Recopilar los puntos de datos relevantes de la plataforma de mediación
Reenvíe estos datos a su servidor
Enviar el evento'__ADMON_USER_LEVEL_REVENUE__' a Singular a través de REST API.

Puntos clave

Flexibilidad: Control total sobre la recopilación y transmisión de datos
Paridad de funciones: Soporta todas las funcionalidades del SDK cuando se proporcionan los datos adecuados
Ruta de integración: Cliente → Su servidor → API singular
Procesamiento en tiempo real: Una solicitud cada vez, sin procesamiento por lotes
Flujo de datos secuencial: Los eventos deben procesarse en orden cronológico
Deduplicación de datos: Singular no deduplica los datos recibidos. Se recomienda enviar una (1) solicitud con éxito y guardar los registros en caso de que deba repetirse una solicitud.
Validación de datos: Los datos a nivel de dispositivo son permanentes y no pueden borrarse una vez introducidos. Realice una validación exhaustiva de los datos antes de enviarlos a Singular para garantizar su exactitud.

Requisitos previos

Debe establecerse una sesión antes de recibir cualquier seguimiento de eventos.
Un orden de sesión no válido provocará incoherencias en los datos.
Recopile los atributos de datos de la Plataforma de Mediación directamente desde el SDK de Mediación. Para detalles de implementación y puntos de datos requeridos, consulte nuestra Guía SDK y la documentación de Mediación específica de la plataforma.

Primeros pasos

La documentación del punto final EVENT proporciona:

Parámetros obligatorios
Parámetros opcionales
Ejemplos de solicitud
Códigos de respuesta y errores
Pruebas de eventos

Este enfoque del lado del servidor le ofrece un mayor control sobre su integración al tiempo que mantiene todas las capacidades del SDK.

Punto final de la API de eventos

Método HTTP y punto final de eventos

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

Parámetros requeridos

En la tabla siguiente se enumeran los parámetros necesarios para enviar eventos de ingresos por monetización de anuncios a través de la API de eventos. Estos parámetros deben incluirse como parámetros de consulta.

GET /api/v1/evt?param1=value1&param2=value2

Todos los parámetros obligatorios deben incluirse en las solicitudes de la API de eventos.
Los parámetros deben seguir el formato y los tipos de datos especificados

Parámetros obligatorios
Clave API
Parámetro	Descripción
`a`	`string` El parámetro a especifica la clave Singular SDK Key. Obtenga la clave SDK en la interfaz de Singular, en Herramientas de desarrollo del menú principal. Nota: No utilice la clave de la API de generación de informes, ya que se rechazarán los datos. Valor de ejemplo: `sdkKey_afdadsf7asf56`
Parámetros del identificador del dispositivo
Parámetro	Descripción
`idfa` Plataformas soportadas: iOS	`string` El parámetro idfa especifica el Identificador para Anunciantes (IDFA) que ayuda a los anunciantes a rastrear y atribuir las acciones de los usuarios (por ejemplo, clics en anuncios, instalaciones de aplicaciones) a campañas específicas, lo que permite una orientación precisa de los anuncios y la optimización de las campañas. A partir de iOS 14.5, los usuarios deben optar por el marco App Tracking Transparency (ATT) para que las aplicaciones puedan acceder al IDFA. Si los usuarios no optan por el IDFA, este no estará disponible, lo que limitará las capacidades de seguimiento. Si el IDFA no está disponible, omita el parámetro de la solicitud. No pase NULL o una cadena vacía en la petición. Cómo recuperar el Identificador IDFA Valor de ejemplo: `DFC5A647-9043-4699-B2A5-76F03A97064B`
Parámetro	Descripción
`idfv` Plataformas soportadas: iOS	`string` El parámetro idfv especifica el Identificador de Vendedores (IDFV), un identificador único asignado por Apple a un dispositivo, que es específico de un vendedor o desarrollador concreto. Permanece constante en todas las aplicaciones del mismo proveedor en un dispositivo determinado, lo que permite al proveedor realizar un seguimiento del comportamiento y las interacciones del usuario en todo su ecosistema de aplicaciones sin identificar al usuario personalmente. El IDFV es obligatorio en todas las solicitudes, independientemente del estado de ATT o de la presencia del IDFA. Cómo recuperar el identificador IDFV Valor de ejemplo: `21DB6612-09B3-4ECC-84AC-B353B0AF1334`
Parámetro	Descripción
`aifa` Plataformas soportadas: Android (Dispositivos Google Play)	`string` El parámetro aifa especifica el identificador de publicidad de Google (GAID), también conocido como AIFA en singular o Android Advertising ID (AAID). Este identificador es un identificador único y reajustable por el usuario asignado a los dispositivos Android. Ayuda a los anunciantes y a los desarrolladores de aplicaciones a rastrear y atribuir las acciones de los usuarios (por ejemplo, clics en anuncios, instalaciones de aplicaciones) en las aplicaciones a campañas específicas, lo que permite una orientación precisa de los anuncios y la optimización de las campañas, al tiempo que se mantiene la privacidad del usuario. Si la AIFA no está disponible, omita el parámetro de la solicitud. Solo se requiere en dispositivos Google Play. Omita el parámetro en dispositivos que no sean de Google Play. No pase NULL o una cadena vacía en la solicitud. Cómo recuperar el identificador AIFA Valor de ejemplo: `8ecd7512-2864-440c-93f3-a3cabe62525b`
Parámetro	Descripción
`asid` Plataformas soportadas: Android (Dispositivos Google Play)	`string` El parámetro asid especifica el Android App Set ID. El ASID permite a los desarrolladores realizar un seguimiento de los usuarios en sus propias aplicaciones respetando su privacidad. Es especialmente útil para el análisis y la prevención del fraude, pero no puede utilizarse con fines publicitarios, como anuncios personalizados o mediciones. El ASID es obligatorio en todas las solicitudes de dispositivos Google Play, independientemente de la presencia de GAID/AIFA. Omita el parámetro en dispositivos que no sean de Google Play. No pase NULL o una cadena vacía en la solicitud. Cómo recuperar el identificador ASID Valor de ejemplo: `edee92a2-7b2f-45f4-a509-840f170fc6d9`
Parámetro	Descripción
`amid` Plataformas soportadas: Android (Dispositivos Amazon sin Google Play Services)	`string` El parámetro amid especifica que el ID de publicidad es un identificador único y reajustable por el usuario que ayuda a proteger su privacidad. Si recopilas información sobre el comportamiento de un usuario para mostrar anuncios basados en intereses o para generar análisis, debes utilizar el ID de publicidad; no se puede utilizar ningún otro identificador o método de seguimiento. Los usuarios pueden restablecer el identificador de publicidad o excluirse totalmente de los anuncios basados en intereses. El AMID es obligatorio en todas las solicitudes de dispositivos de Amazon sin Google Play Services. Omita el parámetro si el AMID no está disponible. No pase NULL o una cadena vacía en la solicitud. Cómo recuperar el identificador AMID Valor de ejemplo: `df07c7dc-cea7-4a89-b328-810ff5acb15d`
Parámetro	Descripción
`oaid` Plataformas soportadas: Android (Dispositivos fabricados en China sin Google Play Services)	`string` El parámetro oaid especifica Open Advertising Identifier (OAID). El OAID es un identificador único y anónimo utilizado con fines publicitarios en dispositivos Android, especialmente los fabricados en China. Fue introducido por la Mobile Security Alliance (MSA) como alternativa al identificador de publicidad de Google (GAID) para dispositivos en los que los servicios de Google Play no están disponibles o no son compatibles, como en el mercado chino. El OAID se utiliza principalmente para la atribución de publicidad y el seguimiento de usuarios en entornos en los que los servicios de Google Play están restringidos, lo que permite a los anunciantes y desarrolladores rastrear el comportamiento de los usuarios manteniendo el anonimato. El OAID está disponible en la mayoría de los dispositivos Android fabricados en China, incluidos los de marcas como Huawei, Xiaomi y otras. Se puede acceder a él mediante el SDK MSA o Huawei Mobile Services (HMS). El OAID es necesario en los dispositivos Android fabricados en China sin Google Play Services. Omita el parámetro si el OAID no está disponible. No pase NULL o una cadena vacía en la solicitud. Cómo recuperar el identificador OAID Valor de ejemplo: `01234567-89abc-defe-dcba-987654321012`
Parámetro	Descripción
`andi` Plataformas soportadas: Android (Dispositivos sin Google Play)	`string` El parámetro andi especifica el ID de Android, que es un identificador único de 64 bits generado por el sistema operativo Android cuando se configura un dispositivo por primera vez. Está diseñado para ser persistente durante toda la vida útil del dispositivo, pero puede restablecerse en determinadas condiciones, como un restablecimiento de fábrica. El Android ID es único para cada dispositivo y, a partir de Android 8.0 (Oreo), tiene un alcance por app y por usuario. Esto significa que diferentes aplicaciones en el mismo dispositivo recibirán diferentes Android ID a menos que compartan la misma clave de firma. El Android ID permanece constante a menos que el dispositivo se restablezca de fábrica o si se desinstala y se vuelve a instalar una aplicación tras una actualización OTA (over-the-air). Está prohibido utilizar el ANDI en dispositivos Google Play. Utilice los identificadores AIFA y ASID mencionados anteriormente. El ANDI sólo puede enviarse a Singular si no se dispone de otros identificadores y la aplicación no está alojada en Google Play Store. Omita el parámetro si hay otros identificadores disponibles. No pase NULL o una cadena vacía en la solicitud. Cómo recuperar el identificador ANDI Valor de ejemplo: `fc8d449516de0dfb`
Parámetros del dispositivo
Parámetro	Descripción
`p`	`string` El parámetro p especifica la plataforma de la App. La siguiente lista contiene los valores permitidos del parámetro que distinguen entre mayúsculas y minúsculas : Android iOS Valor de ejemplo: `Android`
Parámetro	Descripción
`ip`	`string` El parámetro ip especifica la dirección IP pública (IPV4) del dispositivo. No se admite IPV6. Valor de ejemplo: `172.58.29.235`
Parámetro	Descripción
`ve`	`string` El parámetro ve especifica la versión del sistema operativo del dispositivo en el momento del evento. Valor de ejemplo: `9.2`
Parámetros de aplicación
Parámetro	Descripción
`i`	`string` El parámetro i especifica el identificador de la aplicación. Este valor distingue entre mayúsculas y minúsculas : Nombre del paquete para Android ID de paquete para iOS Valor de ejemplo: `com.singular.app`
Parámetro	Descripción
`att_authorization_status` Plataformas soportadas: iOS	`int` El parámetro att_authorization_status especifica el código de estado de App Tracking Transparency(ATT). A partir de iOS 14.5, se requiere el indicador App Tracking Transparency (ATT) para acceder al identificador IDFA. Nota: Aunque no implemente el indicador ATT, es necesario que pase el estado de autorización ATT con el valor'0', que indica "indeterminado". Los valores soportados son: 0 - Indeterminado. 1 - Restringido, el usuario ha deshabilitado el seguimiento de la aplicación. 2 - Denegado, el usuario denegó la autorización. 3 - Autorizado, el usuario concedió la autorización. Ejemplos: `3`
Parámetros de evento
Parámetro	Descripción
`n`	`string` El parámetro n especifica el Nombre del evento que se está rastreando. El soporte de AdMon Revenue requiere que el Nombre del Evento sea un valor específico. El Nombre del Evento debe ser TODO EN MAYÚSCULAS con guiones bajos. Utilice el siguiente Nombre de Evento: `__ADMON_USER_LEVEL_REVENUE__`
Parámetro	Descripción
`e`	`JSON URL-encoded string` El parámetro e especifica atributos de evento personalizados en formato JSON. El único atributo obligatorio es 'ad_platform'. Todos los demás atributos son opcionales. Los atributos posibles son ad_platform -- REQUERIDO ad_platform_mediación 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 Nota: Los atributos sin valores deben omitirse. `{ "ad_platform":"AdMob", "ad_mediation_platform":"admob.AdMobAdapter", "ad_unit_id":"ca-app-pub-6325336052\/44923540" }` Valor de ejemplo: `%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ámetro	Descripción
`is_admon_revenue`	`string` El parámetro is_admon_revenue especifica si el evento es un evento de ingresos por monetización de anuncios y si debe utilizarse para las métricas de ingresos por anuncios. Pase 'true' para este evento. Ejemplo de valor: `true`
Parámetro	Descripción
`is_revenue_event`	`string` El parámetro is_revenue_event especifica si el evento es un evento de ingresos y debe utilizarse para las métricas de ingresos. Pase 'true' para este evento. Ejemplo de Valor: `true`
Parámetro	Descripción
`amt`	`double` El parámetro amt especifica el importe en moneda. Debe utilizarse junto con el parámetro 'cur'. Valor de ejemplo: `0.00782`
Parámetro	Descripción
`cur`	`string` El parámetro cur especifica el código de moneda ISO 4217 de tres letras en mayúsculas. Debe utilizarse junto con el parámetro "amt". Valor de ejemplo: `USD`

Cuerpo de la solicitud

No proporcione un cuerpo de solicitud cuando llame a este método. La solicitud debe enviarse utilizando el método GET con parámetros de consulta.

Ejemplos de solicitud

Es posible que los siguientes ejemplos de código no representen todos los parámetros admitidos. Cuando implemente la petición asegúrese de incluir todos los parámetros requeridos como se indica arriba, y valide que se están pasando los valores correctos antes de enviar datos desde una instancia de producción. Se recomienda utilizar un identificador de aplicación único para el desarrollo y las pruebas.

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

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"

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

JAVA Ejemplo

// 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 application-level status

System.out.println("HTTP Status Code: " + responseCode);
System.out.println("Response: " + response.toString());

// Disconnect

conn.disconnect();

Parámetros opcionales

En la siguiente tabla se enumeran los parámetros opcionales que admite este endpoint. Todos los parámetros enumerados son parámetros de consulta.

Parámetros opcionales
Parámetros de dispositivo y red
Parámetro	Descripción
`use_ip`	`string` El parámetro use_ip indica a Singular que extraiga la dirección IP de la solicitud HTTP en lugar del parámetro 'ip'. Pase'true' para utilizar esta función. El uso de este parámetro impide que Singular geolocalice el dispositivo basándose en la dirección IP. Puede proporcionar el código de país de dos letras del usuario en el parámetro opcional 'country'. Este parámetro es mutuamente excluyente con el parámetro 'ip'. NO lo utilice con el parámetro "ip". Para evitar que se rechacen los datos, debe proporcionar el parámetro "ip" o el parámetro "use_ip" en la solicitud. Valor de ejemplo: `true`
Parámetro	Descripción
`country`	`string` El parámetro country debe contener el código de país de dos letras ISO 3166-1 alpha-2 del usuario en el momento de la ejecución del evento. Este parámetro sólo es necesario cuando El parámetro "ip" no está disponible Si el parámetro 'ip' está disponible, el país se determinará automáticamente a partir de la dirección IP, y el parámetro 'country' no es necesario. Valor de ejemplo: `US`
Privacidad de datos
Parámetro	Descripción
`data_sharing_options`	`JSON URL-encoded string` El parámetro data_sharing_options especifica el consentimiento del usuario final para compartir información. Si se establece, este valor debe persistir y pasarse en cada solicitud posterior de "SESSION" y "EVENT" para el usuario. Para indicar que el usuario ha dado su consentimiento (opted-in) para compartir su información pase 'false': `{"limit_data_sharing":false}` Si el usuario se negó, introduzca "true": `{"limit_data_sharing":true}` El valor debe ser una cadena JSON codificada en URL. Valor de ejemplo: `%7B%22limit_data_sharing%22%3Atrue%7D`
Soporte entre dispositivos
Parámetro	Descripción
`custom_user_id`	`string` El parámetro custom_user_id especifica su ID de usuario interno. Valor de ejemplo: `123456789abcd`

Prueba de eventos

Tras la integración de servidor a servidor, es esencial verificar que Singular recibe datos antes de poner en marcha una instancia de producción. Consulte nuestra guía de pruebas para obtener más información. A grandes rasgos, deben seguirse los siguientes pasos:

Obtenga el ID de publicidad de su dispositivo de prueba y añádalo a la consola de Singular SDK.
Abra la consola de Singular SDK y añada el identificador del dispositivo para empezar a capturar datos.
Anule el identificador de la App con un identificador de App de desarrollo(com.singular.app.dev) para mantener los datos y eventos de prueba separados de los datos de producción.
Cree o abra la aplicación desde un estado finalizado
Compruebe que la apertura de la aplicación se envía al servidor con todos los puntos de datos de Singular necesarios.
Compruebe que el servidor envía la notificación de sesión al punto final"launch" de Singular con todos los datos necesarios.
Después de unos segundos, el evento de sesión debería aparecer en la consola de Singular SDK.
Proceda a activar un evento en la aplicación.
Compruebe que el evento se envía al servidor con todos los datos necesarios de Singular.
Compruebe que su servidor envía la notificación de evento al punto final'evt' de Singular con todos los datos necesarios.
Después de unos segundos, el evento debería aparecer en la consola de Singular SDK.
Repita la prueba para validar que todos los eventos se envían según lo previsto y con los valores esperados.

Verificaciones importantes

Confirme que el Evento de Sesión se produce al Abrir la Aplicación o en Primer Plano y antes de que se reciba el Evento.
Confirme que los puntos de datos requeridos del evento coinciden con los puntos de datos de la sesión.
Confirme que los detalles correctos de la Plataforma de Mediación son pasados en los Argumentos del Evento.
Confirme que el Importe de Ingresos y la Moneda son correctos

Si ve sus Eventos en la Consola SDK, habrá completado una prueba de extremo a extremo del manejo de Eventos.

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

Referencia de la API de seguimiento de ingresos publicitarios

Caso de uso de servidor a servidor

Puntos clave

Requisitos previos

Primeros pasos

Punto final de la API de eventos

Parámetros requeridos

Cuerpo de la solicitud

Ejemplos de solicitud

PYTHON

CURL

HTTP

JAVA Ejemplo

Parámetros opcionales

Prueba de eventos