Server-to-Server - Fundamentos

Seguir
Avatar
Jared Ornstead
Updated

Server-to-Server - Fundamentos

Implementa la REST API de Singular para un tracking completo del lado del servidor como alternativa a la integración con SDK, lo que te da control total sobre la recopilación, la transmisión de datos y los flujos de trabajo de atribución.

¿Cómo elegir tu integración: SDK o S2S? Si puedes incrustar un SDK de cliente, comienza con la documentación de integración de SDK . Usa Server-to-Server cuando necesites envío de eventos del lado del servidor, estés en una plataforma sin SDK o quieras control total sobre la recopilación de datos. Este conjunto cubre la ruta S2S y es la referencia compartida para las guías de S2S de móvil, web y PC/consola.

Descripción general

Caso de uso de Server-to-Server

La integración server-to-server (S2S) proporciona endpoints de REST API para crear soluciones completas de atribución y analítica que se ejecutan desde tu infraestructura de backend sin incrustar el SDK de Singular en las aplicaciones cliente.

Enfoques de integración:

  • S2S puro: Implementación 100% del lado del servidor que gestiona tanto el tracking de sesiones como el de eventos
  • Híbrida: El SDK de Singular gestiona las sesiones mientras que el lado del servidor gestiona el tracking de eventos

Patrón de integración híbrida

La integración híbrida combina el SDK de Singular para la gestión de sesiones con la EVENT API del lado del servidor para el tracking de eventos en el backend, equilibrando la facilidad de implementación con la flexibilidad del lado del servidor.

Beneficios de la integración híbrida:

  • El SDK gestiona automáticamente la lógica compleja de sesiones, el deep linking y la recopilación de datos del dispositivo
  • El servidor envía eventos para las transacciones procesadas en los sistemas de backend
  • Menor complejidad de implementación del lado del cliente
  • El endpoint SESSION no es necesario: el SDK gestiona el ciclo de vida de la sesión

Flujo de datos de S2S híbrido

Métodos de obtención de datos del dispositivo:

  1. Flujo gestionado por el cliente: Captura los puntos de datos requeridos en el cliente y reenvíalos al servidor a través de una API interna para usarlos con el endpoint EVENT de Singular
  2. Postback de BI interno: Configura el postback de BI interno de Singular para recibir un payload JSON en tiempo real con los identificadores del dispositivo después de una instalación, una re-interacción o eventos ( Guía de configuración )

Mantenimiento del gráfico de dispositivos: Ambos métodos requieren lógica del lado del servidor para mantener el gráfico de dispositivos. Cuando el SDK detecte cambios en el identificador del dispositivo, actualiza el servidor en consecuencia para garantizar un tracking preciso.

Recursos de implementación:

Principios clave de la integración

Principio Descripción
Flexibilidad Control total sobre la recopilación de datos y el momento de la transmisión
Paridad de funciones Admite toda la funcionalidad del SDK cuando se proporcionan los datos adecuados
Ruta de integración Cliente → Tu servidor → API de Singular
Procesamiento en tiempo real Una solicitud a la vez: no se admite el procesamiento por lotes
Flujo secuencial Los eventos deben procesarse en orden cronológico
Sin deduplicación Singular no deduplica: implementa la deduplicación del lado del servidor
Permanencia de los datos Los datos a nivel de dispositivo no se pueden eliminar después de su ingesta: valídalos antes de enviarlos

Requisitos de integración

La integración de S2S puro requiere la implementación de una canalización de datos completa para el tracking de sesiones y eventos.

  1. Recopilación de datos: Recopila los puntos de datos requeridos de las aplicaciones cliente
  2. Gráfico de dispositivos: Reenvía los datos al servidor y mantén el almacenamiento de identificadores del dispositivo
  3. Solicitudes de sesión: Envía notificaciones de sesión a través de la SESSION API
  4. Gestión de respuestas: Procesa y retransmite las respuestas de Singular de vuelta a la aplicación cliente
  5. Solicitudes de eventos: Reenvía los eventos a través de la EVENT API

Guías de S2S relacionadas

Este artículo es la referencia compartida para el conjunto de S2S. Usa la guía que coincida con tu plataforma y las referencias de endpoints para ver todos los detalles de los parámetros.

Guías por plataforma

Referencias de endpoints

Guías de funciones

Endpoints de la REST API

Singular proporciona dos endpoints principales de REST API para el tracking de sesiones y eventos de server-to-server.

Endpoint de sesión

API de tracking de sesiones

El endpoint SESSION notifica a Singular los eventos de apertura de la app para inicializar las sesiones de usuario con fines de atribución y tracking de retención. 

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

Referencia completa: Referencia de la API del endpoint SESSION

Endpoint de evento

API de tracking de eventos

El endpoint EVENT hace tracking de eventos in-app e ingresos para el análisis de atribución y la optimización de campañas. 

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

Referencia completa: Referencia de la API del endpoint EVENT

Parámetros comunes

Estos parámetros se comparten entre los endpoints SESSION y EVENT de la REST API de S2S de Singular. Esta sección contiene sus definiciones canónicas; otros artículos de S2S enlazan aquí en lugar de redefinirlos.

Autenticación

Parámetro Detalles
a

string

SDK Key de Singular para la autenticación de la API.

Obténla desde: Singular UI → Menú principal → Developer Tools .

Importante: No uses la Reporting API Key. Las solicitudes serán rechazadas.

Ejemplo: sdkKey_afdadsf7asf56

Identificadores de dispositivo

Los identificadores de dispositivo varían según la plataforma y su disponibilidad. Incluye todos los identificadores aplicables a tu plataforma. Omite cualquier identificador que no esté disponible: nunca pases NULL ni una cadena vacía.

Parámetro Detalles
idfa

Plataforma: iOS

Identifier for Advertisers (IDFA) habilita el tracking de anuncios y la atribución de campañas.

Requisito de ATT: iOS 14.5+ requiere el opt-in del usuario a través del framework App Tracking Transparency.

  • Omite el parámetro si el IDFA no está disponible (el usuario rechazó el aviso de ATT).
  • Nunca pases NULL ni una cadena vacía.
  • Obtener el IDFA

Ejemplo: DFC5A647-9043-4699-B2A5-76F03A97064B

idfv

Plataforma: iOS

Identifier for Vendors (IDFV) se mantiene consistente en todas las apps del mismo proveedor.

Siempre requerido: Debe incluirse independientemente del estado de ATT o de la disponibilidad del IDFA.

Ejemplo: 21DB6612-09B3-4ECC-84AC-B353B0AF1334

aifa

Plataforma: Android
(Google Play)

Google Advertising ID (GAID) habilita el tracking publicitario reiniciable por el usuario en Android.

  • Requerido en dispositivos con Google Play.
  • Omite en dispositivos sin Google Play.
  • Omite si no está disponible: nunca pases NULL ni una cadena vacía.
  • Obtener el AIFA

Ejemplo: 8ecd7512-2864-440c-93f3-a3cabe62525b

asid

Plataforma: Android
(Google Play)

Android App Set ID proporciona un tracking entre apps del mismo desarrollador respetuoso con la privacidad.

Siempre requerido: Debe incluirse en los dispositivos con Google Play independientemente de la disponibilidad del GAID.

Ejemplo: edee92a2-7b2f-45f4-a509-840f170fc6d9

amid

Plataforma: Android
(Amazon)

Amazon Advertising ID para dispositivos Amazon sin Google Play Services.

  • Requerido para dispositivos Amazon Fire.
  • Omite si no está disponible.
  • Obtener el AMID

Ejemplo: df07c7dc-cea7-4a89-b328-810ff5acb15d

oaid

Plataforma: Android
(OEM chinos)

Open Advertising Identifier (OAID) para dispositivos de fabricación china sin Google Play Services (Huawei, Xiaomi, OPPO, etc.).

  • Requerido para dispositivos de OEM chinos sin Google Play.
  • Omite si no está disponible.
  • Obtener el OAID

Ejemplo: 01234567-89abc-defe-dcba-987654321012

andi

Plataforma: Android
(sin Google Play)

Android ID es un identificador de 64 bits generado por el dispositivo.

Uso restringido: Prohibido en dispositivos con Google Play: usa AIFA y ASID en su lugar. Envíalo solo si no hay otros identificadores disponibles y la app no se distribuye a través de Google Play.

Ejemplo: fc8d449516de0dfb

sdid

Plataforma: iOS, Android, PC, Xbox, PlayStation, Nintendo, MetaQuest, CTV

El Singular Device ID es un UUIDv4 anonimizado generado por el cliente que representa una instalación única de la app.

Identificador principal: Es el único identificador de dispositivo relevante para aplicaciones de PC y consola.

Ejemplo: 40009df0-d618-4d81-9da1-cbb3337b8dec

Parámetros del dispositivo

Parámetro Detalles
p

string

Plataforma de la aplicación.

Valores permitidos (distinguen mayúsculas y minúsculas):

  • Android
  • iOS
  • PC
  • Xbox
  • Playstation
  • Nintendo
  • MetaQuest
  • CTV

Ejemplo: Android

ip

string

Dirección IPv4 pública del dispositivo. Se admite IPv6, pero se recomienda IPv4 para la compatibilidad de atribución con las redes de anuncios.

Ejemplo: 172.58.29.235

ve

string

Versión del OS del dispositivo en el momento de la sesión.

Ejemplo: 9.2

ma
iOS, Android

string

Marca del dispositivo (nombre del fabricante). Debe usarse con mo (modelo).

Obtener la marca del dispositivo

Ejemplo: Samsung , LG , Apple

mo
iOS, Android

string

Modelo del dispositivo. Debe usarse con ma (marca).

Obtener el modelo del dispositivo

Ejemplo: iPhone 4S , Galaxy SIII

lc
iOS, Android

string

Etiqueta de configuración regional IETF: código de idioma y país de dos letras separados por un guion bajo.

Obtener la configuración regional del dispositivo

Ejemplo: en_US

bd
iOS, Android

string

Identificador de compilación del dispositivo, codificado en URL.

Obtener la compilación del dispositivo

Ejemplo: Build%2F13D15

Parámetros de la aplicación

Parámetro Detalles
i

string

Identificador de la app (distingue mayúsculas y minúsculas).

  • Android: Package Name (p. ej., com.singular.app )
  • iOS: Bundle ID (p. ej., com.singular.app )
  • PC/consola: Tu identificador designado

Ejemplo: com.singular.app

app_v

string

Versión de la aplicación.

Ejemplo: 1.2.3

att_authorization_status
iOS

integer

Código de estado de App Tracking Transparency (ATT) (iOS 14.5+).

Valores de estado:

  • 0 - Indeterminado (el aviso no se mostró)
  • 1 - Restringido (tracking a nivel de dispositivo deshabilitado)
  • 2 - Denegado (el usuario denegó la autorización)
  • 3 - Autorizado (el usuario concedió la autorización)

Siempre requerido: Incluso si ATT no está implementado, pasa 0 (indeterminado).

Ejemplo: 3

Parámetros de red y ubicación

Parámetro Detalles
use_ip

boolean

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.
  • Proporciona un código de país de dos letras a través del parámetro country .
  • Mutuamente excluyente con el parámetro ip : no uses ambos.
  • Debes proporcionar ip o use_ip para evitar el rechazo de datos.

Ejemplo: true

country

string

Código de país de dos letras ISO 3166-1 alpha-2 .

Requerido cuando: la dirección IP no está disponible o use_ip=true .

Ejemplo: US

ua

string

Cadena de User Agent codificada en URL.

Sin procesar: Mozilla/5.0 (iPhone; CPU iPhone OS 14_0 like Mac OS X) AppleWebKit/605.1.15...

Ejemplo: Mozilla%2F5.0%20(iPhone%3B%20CPU%20iPhone%20OS%2014_0...

c
iOS, Android

string

Tipo de conexión de red.

Valores permitidos: wifi , carrier

Ejemplo: wifi

cn
iOS, Android

string

Nombre del operador del proveedor de internet.

Ejemplo: Comcast

Parámetros de privacidad de datos

Parámetro Detalles
data_sharing_options

JSON

Consentimiento del usuario final para compartir datos, en JSON codificado en URL. Debe persistir y pasarse en todas las solicitudes SESSION y EVENT posteriores.

El usuario dio su consentimiento (opt-in): 

{"limit_data_sharing":false}

El usuario rechazó (opt-out): 

{"limit_data_sharing":true}

Ejemplo: %7B%22limit_data_sharing%22%3Atrue%7D

dnt
iOS, Android

integer

Estado de Do Not Track.

  • 1 - Do Not Track habilitado
  • 0 - Do Not Track deshabilitado

Ejemplo: 0

dntoff
iOS, Android

integer

Indica si Do Not Track está DESACTIVADO.

  • 0 - Do Not Track habilitado (OFF=false)
  • 1 - Do Not Track deshabilitado (OFF=true)

Ejemplo: 1

Compatibilidad multidispositivo

Parámetro Detalles
custom_user_id

string

Tu ID de usuario interno para el tracking multidispositivo.

Sin PII: No pases información de identificación personal. Usa un identificador interno con hash u otro tipo de anonimización, no direcciones de correo electrónico, números de teléfono ni nombres sin procesar.

Ejemplo: 123456789abcd

Fases de implementación

Una integración S2S exitosa requiere cuatro fases clave de implementación ejecutadas de forma secuencial para lograr una calidad de datos y una precisión de atribución óptimas.

Fase 1: Recopilación de datos

Puntos de datos requeridos

Establece una estrategia sólida de recopilación de datos que capture todos los parámetros requeridos para la funcionalidad de la plataforma Singular.

Todos los parámetros requeridos son obligatorios: Omitir parámetros requeridos genera discrepancias de datos y errores de atribución. Ningún parámetro es opcional.

Manejo de funciones asíncronas: Al recopilar datos del lado del cliente para transmitirlos al servidor, espera a que las funciones asíncronas se completen y gestiona los casos límite. Es un problema común que causa datos faltantes y atribución parcial.

Recursos de implementación:

Fase 2: Streaming en tiempo real

Requisitos críticos de temporización

El streaming de datos en tiempo real mantiene la precisión de la atribución y habilita funciones sensibles al tiempo como las actualizaciones de conversion value de SKAdNetwork.

Impacto en la atribución:

  • Sesiones retrasadas: Afectan gravemente la precisión de la atribución: el sistema requiere datos temporales precisos para asociar campañas
  • Temporizador de SKAdNetwork: La estricta ventana del temporizador en el dispositivo para los conversion values hace que el streaming en tiempo real sea crítico. Los retrasos provocan actualizaciones de conversion value perdidas y datos de campaña incompletos

Prácticas recomendadas:

  • Implementa listeners de eventos del lado del servidor para los inicios de sesión de la app
  • Reenvía los datos de sesión de inmediato con todos los parámetros requeridos
  • Implementa listeners de eventos del lado del servidor para los eventos in-app
  • Reenvía los datos de eventos de inmediato con todos los parámetros requeridos
  • Usa una arquitectura de webhooks para una transmisión de datos confiable
  • Implementa mecanismos de reintento para las solicitudes fallidas
  • Monitorea el flujo de datos para el control de calidad

Fase 3: Gestión de respuestas

Comunicación bidireccional

La gestión de respuestas conecta las interacciones de API del lado del servidor con la funcionalidad del lado del cliente, habilitando el deferred deep linking y las actualizaciones de conversion value.

Tipos de respuesta clave:

  • Deferred deep links: La respuesta de la API contiene datos de deep link pendientes que requieren retransmisión inmediata a la app para el enrutamiento y la personalización del usuario
  • Conversion values: Los conversion values de SKAdNetwork de iOS deben reenviarse de inmediato a la app para una medición precisa de la campaña

Prácticas recomendadas:

  • Implementa la gestión de respuestas en la infraestructura del servidor
  • Analiza y valida las respuestas de la API de Singular
  • Reenvía los datos de respuesta relevantes a la app cliente (esencial para SKAdNetwork de iOS)
  • Implementa el procesamiento de respuestas del lado del cliente
  • Maneja los errores de forma adecuada con los códigos de estado HTTP correspondientes
  • Registra las respuestas fallidas para los mecanismos de reintento

Fase 4: Pruebas y validación

Verificación del flujo de datos

La fase de pruebas valida la funcionalidad completa de la canalización de datos y la precisión de la atribución antes del despliegue en producción.

Procesos de atribución de sesiones:

  • Primera sesión (nueva instalación): Singular reconoce la nueva instalación y activa el proceso de atribución de instalación
  • Re-interacción calificada: Singular activa el proceso de atribución de re-interacción ( Preguntas frecuentes sobre re-interacción )
  • Sesión estándar: Singular registra la sesión para las métricas de actividad y retención del usuario

Requisitos críticos de temporización:

  1. Sesión antes de los eventos: Debe recibirse una única SESSION antes de cualquier evento. El SDK activa la sesión al abrir la app, y luego envía los eventos in-app. Tras 1+ minuto en segundo plano, la sesión expira. Se envía una nueva sesión cuando la app vuelve al primer plano. Usa los eventos del ciclo de vida de la app y temporizadores para gestionar las sesiones
  2. Eventos en tiempo real: Los eventos que ocurren en la app deben enviarse en tiempo real después de su sesión correspondiente

Lista de verificación de validación:

  • Prueba el flujo de datos de sesión: valida que la primera sesión y las siguientes tengan los puntos de datos y valores correctos
  • Confirma que los eventos se reciben solo después de reportar la sesión a Singular (los eventos antes de la sesión crean atribución orgánica)
  • Confirma que la respuesta de la sesión se gestiona y se pasa a la app cliente (crítico para los deferred deep links)

Integración completa:

  • ✓ Recopilación y almacenamiento de datos validados
  • ✓ Streaming en tiempo real hacia Singular validado
  • ✓ Gestión de respuestas y registro validados
  • ✓ Todos los flujos de datos de prueba validados

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

Funciones adicionales

Implementa el tracking multidispositivo, el tracking de ingresos, el monitoreo de desinstalaciones y el cumplimiento de la privacidad de datos para obtener una analítica integral.

Tracking multidispositivo

Implementación de Custom User ID

Aprovecha el parámetro custom_user_id para asociar usuarios con sesiones a nivel de dispositivo para los reportes multidispositivo y la analítica a nivel de usuario.

Cumplimiento de la privacidad: Cumple con las políticas de privacidad de datos evitando la información de identificación personal (PII) en custom_user_id . Usa un nombre de usuario con hash, un correo electrónico o una cadena generada aleatoriamente como identificador único de usuario.

Habilita reportes multidispositivo integrales, exportaciones de datos a nivel de usuario y postbacks de BI interno, manteniendo al mismo tiempo la privacidad del usuario.

Más información: Parámetro Custom User ID

Tracking de ingresos

Reporte de compras in-app

Haz tracking de los ingresos de las compras in-app para el análisis de ROI, la medición del rendimiento de las campañas y el enriquecimiento de exportaciones/postbacks.

Usa el endpoint EVENT con parámetros de ingresos :

  • is_revenue_event : Marca el evento como evento de ingresos (omite si el nombre del evento es __iap__ o el monto es > 0)
  • purchase_receipt : Objeto de compra in-app de Android/iOS: muy recomendado para los detalles de la transacción y el enriquecimiento de reportes
  • receipt_signature (Android): Muy recomendado para la validación de transacciones y la prevención de fraude
  • amt : Monto de ingresos como Double (p. ej., "amt=1.99")
  • cur : Código de moneda ISO 4217 (p. ej., "cur=USD")

Guía de implementación: Gestión del estado de suscripciones

Cumplimiento de la privacidad de datos

Manejo del consentimiento del usuario

Notifica a Singular el consentimiento del usuario final para compartir datos y cumplir con el GDPR, la CCPA y otras regulaciones de privacidad.

Usa el parámetro data_sharing_options para comunicar la elección del usuario:

  • {"limit_data_sharing":false} : El usuario dio su consentimiento (opt-in) para compartir información
  • {"limit_data_sharing":true} : El usuario rechazó compartir información

Singular usa limit_data_sharing en los postbacks de privacidad del usuario y pasa la información a los partners que requieren cumplimiento.

Opcional pero recomendado: El parámetro es opcional, pero cierta información de atribución solo la comparten los partners cuando el usuario ha hecho opt-in de forma explícita.

Más información: Privacidad del usuario y Limit Data Sharing