Server-to-Server - Fundamentos

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

Elegir tu integración: ¿SDK o S2S? Si puedes incorporar un SDK de cliente, comienza con la documentación de integración del SDK . Usa Server-to-Server cuando necesites la entrega 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 abarca la ruta S2S y es la referencia compartida para las guías S2S de Mobile, 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 incorporar el SDK de Singular en las aplicaciones del cliente.

Enfoques de integración:

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

Integración S2S pura

El S2S puro es una implementación completamente del lado del servidor: tu backend recopila los datos requeridos, mantiene el grafo de dispositivos y entrega tanto las sesiones como los eventos a Singular. Consulta las Fases de implementación a continuación para conocer el flujo paso a paso.

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 seguimiento de eventos de backend, equilibrando la facilidad de implementación con la flexibilidad del lado del servidor.

Beneficios del enfoque híbrido:

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
No se requiere el endpoint SESSION: el SDK gestiona el ciclo de vida de la sesión

Flujo de datos S2S híbrido

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

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

Mantenimiento del grafo de dispositivos: Ambos métodos requieren lógica del lado del servidor para mantener el grafo de dispositivos. Cuando el SDK detecta cambios en el identificador del dispositivo, actualiza el servidor en consecuencia para garantizar un seguimiento preciso.

Recursos relacionados:

Guía para obtener datos del dispositivo (ejemplos de código para iOS/Android)

Principios clave de integración

Estos principios se aplican a todas las integraciones S2S, sea cual sea tu plataforma o enfoque:

Principio	Descripción
Flexibilidad	Control total sobre la recopilación de datos y el momento de 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 cronológicamente
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 la ingesta: valídalos antes de enviarlos

Fases de implementación

Una integración S2S completa avanza a través de cuatro fases, ejecutadas en orden, cada una construida sobre la anterior.

Fase 1: Recopilación de datos

Puntos de datos requeridos

Configura una recopilación de datos que capture cada parámetro requerido, de modo que Singular tenga todo lo que necesita para atribuir e informar con precisión.

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.

Gestión de funciones asíncronas: Al recopilar datos del lado del cliente para su transmisión 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:

Parámetros requeridos del endpoint SESSION
Parámetros requeridos del endpoint EVENT
Guía para obtener datos del dispositivo (ejemplos de código para iOS/Android)
Guía de implementación de SKAdNetwork 4 (puntos de datos específicos de iOS)

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 la asociación de 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 llamadas a la API del lado del servidor de vuelta a la aplicación del cliente, que es lo que habilita 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 un reenvío inmediato a la app para el enrutamiento y la personalización del usuario
Conversion Values: Los conversion values de SKAdNetwork de iOS deben reenviarse rápidamente 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 aplicación del cliente (esencial para SKAdNetwork de iOS)
Implementa el procesamiento de respuestas del lado del cliente
Gestiona los errores de forma controlada con códigos de estado HTTP adecuados
Registra las respuestas fallidas para los mecanismos de reintento

Fase 4: Pruebas y validación

Verificación del flujo de datos

Antes de desplegar a producción, valida todo el pipeline de datos de extremo a extremo y confirma que la atribución sea precisa.

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 la instalación
Re-engagement calificado: Singular activa el proceso de atribución de re-engagement ( FAQ de re-engagement )
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:

Sesión antes de los eventos: Se debe recibir 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. Después de 1 minuto o más en segundo plano, la sesión expira. Se envía una nueva sesión cuando la app vuelve a primer plano. Usa los eventos del ciclo de vida de la app y temporizadores para la gestión de sesiones
Eventos en tiempo real: Los eventos que ocurren en la app deben enviarse en tiempo real después de su respectiva sesión

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 reciban solo después de que la sesión se reporte a Singular (los eventos antes de la sesión crean atribución orgánica)
Confirma que la respuesta de la sesión se gestione y se pase a la aplicación del cliente (crítico para los deferred deep links)

Integración completada:

✓ Recopilación y almacenamiento de datos validados
✓ Streaming en tiempo real a 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 S2S

Funciones adicionales

Implementa el seguimiento entre dispositivos, el seguimiento de ingresos, la monitorización de desinstalaciones y el cumplimiento de la privacidad de datos para una analítica integral.

Seguimiento entre dispositivos

Implementación de Custom User ID

Aprovecha el parámetro custom_user_id para asociar usuarios con sesiones a nivel de dispositivo para informes entre dispositivos y analítica a nivel de usuario.

Cumplimiento de 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, correo electrónico hasheado o una cadena generada aleatoriamente como identificador único de usuario.

Habilita informes completos entre dispositivos, 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

Seguimiento de ingresos

Informes de compras dentro de la app

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

Usa el endpoint EVENT con parámetros de ingresos :

is_revenue_event: Establécelo en true para un evento de ingresos; false en caso contrario.
purchase_receipt : Objeto de compra dentro de la app de Android/iOS: muy recomendado para los detalles de la transacción y el enriquecimiento de informes
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

Gestión del consentimiento del usuario

Notifica a Singular el consentimiento del usuario final para el intercambio de datos con el fin de 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 consintió (opted-in) en 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 transmite 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 dado su consentimiento (opted-in) explícito.

Más información: Privacidad del usuario y limitación del intercambio de datos

Referencia de endpoints

Cada referencia de endpoint documenta en línea sus parámetros completos requeridos y opcionales. Para consultar las tablas completas de parámetros, revisa lo siguiente:

Este artículo es la referencia compartida para el conjunto S2S. Usa la guía que corresponda a tu plataforma y las referencias de endpoints para el detalle completo de parámetros.

Guías por plataforma

Guías de funciones