Server-to-Server - Guía de integración

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

Descripción general

Caso de uso de Server-to-Server

La integración server-to-server (S2S) proporciona endpoints de API REST para crear soluciones completas de atribución y análisis que se ejecutan desde tu infraestructura backend sin incorporar 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 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

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

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 una carga útil JSON en tiempo real con los identificadores de dispositivo tras una instalación, re-engagement o eventos ( Guía de configuración )

Recursos de implementación:

• Parámetros requeridos del endpoint EVENT
• Guía de obtención de datos del dispositivo (muestras de código iOS/Android)

Principios clave de integración

Requisitos de integración

La integración S2S pura requiere la implementación de un pipeline de datos completo para el seguimiento de sesiones y eventos.

1. Recopilación de datos: Recopila los puntos de datos requeridos de las aplicaciones cliente
2. Grafo de dispositivos: Reenvía los datos al servidor y mantén el almacenamiento de identificadores de 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 reenvía 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

Endpoints de la API REST

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

Endpoint de sesión

API de seguimiento 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 seguimiento de retención.

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

Referencia completa: Referencia de la API del endpoint SESSION

Endpoint de eventos

API de seguimiento de eventos

El endpoint EVENT rastrea los eventos in-app y los 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

Fases de implementación

Una integración S2S exitosa requiere cuatro fases clave de implementación ejecutadas secuencialmente para una calidad de datos y 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 el funcionamiento de la plataforma Singular.

Recursos de implementación:

• Parámetros requeridos del endpoint SESSION
• Parámetros requeridos del endpoint EVENT
• Guía de obtención de datos del dispositivo (muestras de código 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 tiempo

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

Mejores prácticas:

• 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 garantizar la calidad

Fase 3: Gestión de respuestas

Comunicación bidireccional

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

Tipos clave de respuesta:

• 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 del usuario y la personalización
• Conversion values: Los conversion values de SKAdNetwork de iOS deben reenviarse rápidamente a la app para una medición precisa de las campañas

Mejores prácticas:

• 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
• Gestiona los errores de forma adecuada con los códigos de estado HTTP correctos
• 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 del pipeline 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-engagement calificado: Singular activa el proceso de atribución de re-engagement ( Preguntas frecuentes sobre re-engagement )
• Sesión estándar: Singular registra la sesión para las métricas de actividad del usuario y de retenció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 reciben solo después de que la sesión haya sido reportada a Singular (los eventos anteriores a la sesión generan atribución orgánica)
• Confirma que la respuesta de sesión se gestiona y se pasa a la app cliente (crítico para los deferred deep links)

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

Funciones avanzadas

Mejora la integración S2S con gestión avanzada de atribución, deep linking, seguimiento entre dispositivos y capacidades específicas de cada plataforma.

Atribución de Apple Search Ads

Integración de iOS Search Ads

Apple Search Ads es una Self-Attributing Network (SAN) que requiere una implementación de atribución específica de la plataforma a través de los frameworks de Apple.

Soporte de frameworks:

• iOS 14.2 y anteriores: Framework iAd
• iOS 14.3 y posteriores: Framework AdServices (recomendado)

Guía completa: Documentación de integración de Apple Search Ads

Implementación del framework iAd

Obtén y envía los datos de atribución de Apple Search Ads a través del framework iAd para iOS 14.2 y anteriores.

Paso 1: Obtener los datos de atribución

#import <iAd/iAd.h>

Class ADClientClass = NSClassFromString(@"ADClient");

if (ADClientClass) {
    id sharedClient = [ADClientClass performSelector:@selector(sharedClient)];

    if ([sharedClient respondsToSelector:@selector(requestAttributionDetailsWithBlock:)]) {
        [sharedClient requestAttributionDetailsWithBlock:^(NSDictionary *attributionDetails, NSError *error) {
            if (attributionDetails && attributionDetails.count  0) {
                // REPORT attributionDetails FROM YOUR APP TO YOUR SERVER
            }
        }];
    }
}

Paso 2: Enviar a Singular

Reporta el evento con el nombre reservado __iAd_Attribution__ a través del endpoint EVENT , pasando el JSON de atribución como parámetro e .

Implementación del framework AdServices

Obtén y envía el token de atribución a través del framework AdServices para iOS 14.3 y posteriores.

Paso 1: Obtener el token de atribución

#import <AdServices/AdServices.h>

NSError *error = nil;
Class AAAttributionClass = NSClassFromString(@"AAAttribution");
if (AAAttributionClass) {
    NSString *attributionToken = [AAAttributionClass attributionTokenWithError:&error];
    if (!error && attributionToken) {
        // Handle attributionToken
    }
}

Paso 2: Enviar a Singular

Codifica el token en URL y añádelo al endpoint SESSION como parámetro attribution_token en la primera sesión después de cada instalación y reinstalación.

Google Play Install Referrer

Atribución de instalación de Android

Google Play Install Referrer proporciona la atribución de instalación de Android más precisa, conteniendo información sobre el origen del usuario antes de llegar a la Play Store.

Más información: Documentación de Google Install Referrer

Pasos de implementación:

1. Obtén el install referrer en la primera apertura de la app usando la Play Install Referrer API
2. Reporta la sesión a través del endpoint SESSION incluyendo el parámetro JSON install_ref con los atributos requeridos

Atributos de install_ref:

Meta Install Referrer

Mejora de la atribución de Facebook

Meta Referrer es una solución de medición específica de Android que proporciona datos de atribución granulares a nivel de usuario para las instalaciones de apps, combinando las tecnologías de Google Play Install Referrer y Meta Install Referrer.

Más información: Preguntas frecuentes sobre Meta Referrer

Pasos de implementación:

1. Obtén el Meta install referrer en la primera apertura de la app según la documentación de Meta
2. Reporta la sesión a través del endpoint SESSION incluyendo el parámetro JSON meta_ref con los atributos requeridos

Atributos de meta_ref:

Singular Links y deep linking

Implementa el deep linking y el deferred deep linking para los tracking links de Singular de modo que los usuarios pasen sin problemas de una campaña a una pantalla específica de tu app.

Un deep link es un enlace en el que se puede hacer clic que abre contenido específico dentro de una app. Hay dos escenarios que debes admitir:

• Deep link (directo): el usuario ya tiene la app instalada. Toca un Singular Link y la app se abre directamente en el contenido correcto.
• Deferred deep link (DDL): el usuario aún no tiene la app. Toca el enlace, instala desde la tienda y, en la primera apertura, la app igualmente lo dirige al contenido previsto.

Con una integración del SDK, Singular gestiona la mayor parte de esto automáticamente. En una integración server-to-server (S2S) no hay SDK en el dispositivo, por lo que tu equipo es responsable de dos tareas adicionales: pasar a Singular el deep link que recibió tu app y leer el deferred deep link que Singular devuelve para enrutar al usuario. Ambas pasan por el endpoint SESSION:

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

Recursos: Preguntas frecuentes sobre deep linking | Preguntas frecuentes sobre Singular Links

Las tres configuraciones de un vistazo

Paso 1: Configuración a nivel de app

Antes de que cualquier deep link pueda funcionar, los Singular Links deben ser reconocidos por el sistema operativo como iOS Universal Links y Android App Links para que al tocar un enlace se abra tu app en lugar de un navegador. Los esquemas URI de app tradicionales se admiten como respaldo.

Sigue las guías de configuración canónicas para los pasos detallados de cada plataforma y luego confirma que cada elemento a continuación esté completo. Los pasos detallados están en Requisitos previos de Singular Links y Cómo configurar deep links. La lista de verificación aquí te da el orden requerido y los puntos que los equipos suelen pasar por alto.

Lista de verificación de configuración:

1. Agrega un subdominio de enlace en Attribution > Manage Links > Manage Link Domains (por ejemplo yourbrand.sng.link). Este es el host que usan tus Singular Links.
2. iOS — Universal Links: habilita la capacidad Associated Domains para applinks:yourbrand.sng.link, luego copia tu App Prefix / Team ID del Apple Developer Portal en Settings > Apps > [iOS app] > Show Advanced Settings. Opcionalmente, registra un respaldo de esquema de app como URL Type en Xcode.
3. Android — App Links: genera tus huellas digitales de firma SHA-256 (Play Console para producción, keytool para depuración), agrega un filtro de intent autoVerify para tu dominio de Singular en AndroidManifest.xml, luego pega la huella digital en Settings > Apps > [Android app] > Show Advanced Settings > App Links SHA256 fingerprints.
4. Define los deep links en Attribution > Manage Links > Create Link (consulta el mapeo de campos a continuación).

Mapeo de los campos de redirección de Manage Links

Cuando creas el enlace, tres campos de redirección se mapean directamente a los tres conceptos de deep link que se usan más adelante en la API:

Traspaso al equipo de desarrollo: ingeniería debe proporcionar el o los esquemas de deep link por plataforma y la lista de URLs de destino (por ejemplo myapp://autumnfashion).

Paso 2: SESSION (entrante) — enviar el deep link a Singular

Cuando la app se abre desde un Singular Link, captura la URL de apertura completa y envíala a Singular en la solicitud SESSION en el parámetro openuri (codificado en URL). Así es como Singular atribuye la sesión al enlace y reporta el resultado del deep link. Requerido cuando se usan Singular Links.

Parámetros del Singular Link transportados en la URL

Capturar la URL de apertura en la app

La app necesita código de handler que reciba la URL de apertura y la reenvíe a tu servidor para incluirla en la solicitud SESSION.

iOS (Swift):

// Custom scheme / direct opens
func scene(_ scene: UIScene,
           openURLContexts URLContexts: Set<UIOpenURLContext>) {
    guard let url = URLContexts.first?.url else { return }
    SessionReporter.report(openURL: url.absoluteString)
}

// Universal Links arrive via:
func scene(_ scene: UIScene,
           continue userActivity: NSUserActivity) {
    if let url = userActivity.webpageURL {
        SessionReporter.report(openURL: url.absoluteString)
    }
}

Android (Kotlin):

override fun onCreate(savedInstanceState: Bundle?) {
    super.onCreate(savedInstanceState)
    intent?.data?.let { uri ->
        SessionReporter.report(uri.toString())
    }
}

override fun onNewIntent(intent: Intent?) {
    super.onNewIntent(intent)
    intent?.data?.let { SessionReporter.report(it.toString()) }
}

Enviar la solicitud SESSION con openuri

Desde tu servidor, incluye la URL capturada (codificada en URL) como openuri:

curl -G https://s2s.singular.net/api/v1/launch \
  --data-urlencode "a=<SDK key>" \
  --data-urlencode "p=Android" \
  --data-urlencode "i=com.yourcompany.app" \
  --data-urlencode "aifa=<GAID>" \
  --data-urlencode "n=YourAppName" \
  --data-urlencode "openuri=myapp://home/page?queryparam1=value1"

Resolución de enlaces cortos

Si el usuario abrió un Singular Link acortado, envía también singular_link_resolve_required=true. Singular devuelve el enlace largo expandido para que puedas analizar el deep link y los valores de passthrough.

Respuesta de ejemplo:

{
  "status": "ok",
  "resolved_singular_link": "https://myapp.sng.link/A59c0/nha7?_dl=myapp%3A%2F%2Fdeeplink&_ddl=myapp%3A%2F%2Fdeferred-deeplink&_p=passthroughvalue"
}

Parámetros de passthrough dinámicos

Si tu organización configuró un passthrough dinámico para un enlace, la URL del deep link incluye el parámetro _p con una cadena JSON codificada en URL o una cadena no estructurada para el enrutamiento de contenido. Consulta Parámetros de passthrough dinámicos.

Referencia: Referencia de la API del endpoint SESSION (Parámetros de deep linking).

Paso 3: SESSION (saliente) — reenviar el deferred deep link a la app

Para un usuario que instala la app después de tocar el enlace, Singular devuelve el deferred deep link en la respuesta SESSION de la primera sesión tras la instalación. Tu servidor debe reenviar ese valor de vuelta a la app para que pueda enrutar al usuario.

Solicitar el DDL en la primera sesión

En la primera solicitud SESSION después de una instalación, agrega estos dos parámetros:

Solicitud SESSION de ejemplo (install + DDL habilitado):

curl -G https://s2s.singular.net/api/v1/launch \
  --data-urlencode "a=<SDK key>" \
  --data-urlencode "p=Android" \
  --data-urlencode "i=com.yourcompany.app" \
  --data-urlencode "aifa=<GAID>" \
  --data-urlencode "n=YourAppName" \
  --data-urlencode "install=true" \
  --data-urlencode "ddl_enabled=true"

Leer la respuesta y reenviarla a la app

Si la instalación provino de un tracking link que transporta un deferred deep link, Singular devuelve:

Respuesta SESSION de ejemplo:

{
  "deferred_deeplink": "myapp://deferred-deeplink",
  "status": "ok",
  "deferred_passthrough": "passthroughvalue"
}

Pruebas y validación

• Deferred deep link: en un dispositivo sin la app, toca el enlace y confirma que llegas a la tienda. Instala y abre, y la app debería mostrar el contenido previsto.
• Deep link directo: con la app instalada, toca el enlace y confirma que la app se abre directamente en el contenido previsto.
• Orden de SESSION: confirma que se recibe una única SESSION antes de cualquier evento, y que la respuesta SESSION se analiza y se pasa al cliente (crítico para los deferred deep links).
• openuri poblado: verifica que las aperturas por deep link envíen una SESSION con openuri establecido, sin importar la ventana de timeout.

Guías de pruebas: Prueba tu integración | Prueba un tracking link

Funciones adicionales

Implementa el seguimiento entre dispositivos, el seguimiento de ingresos, el monitoreo de desinstalaciones y el cumplimiento de privacidad de datos para obtener análisis integrales.

Seguimiento entre dispositivos

Implementación del Custom User ID

Aprovecha el parámetro custom_user_id para asociar a los usuarios con las sesiones a nivel de dispositivo para los informes entre dispositivos y los análisis a nivel de usuario.

Habilita informes integrales entre dispositivos, exportaciones de datos a nivel de usuario y postbacks de BI interno manteniendo la privacidad del usuario.

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

Seguimiento de ingresos

Reporte de compras in-app

Rastrea 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 los parámetros de ingresos :

• is_revenue_event : Marca el evento como evento de ingresos (omítelo si el nombre del evento es __iap__ o el monto > 0)
• purchase_receipt : Objeto de compra in-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 los ingresos como Double (por ejemplo, "amt=1.99")
• cur : Código de moneda ISO 4217 (por ejemplo, "cur=USD")

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

Seguimiento de desinstalaciones

Configuración de notificaciones push silenciosas

Rastrea las desinstalaciones usando notificaciones push silenciosas del dispositivo enviando el token de push con cada notificación de sesión.

Requisitos de configuración:

1. Sigue la configuración de seguimiento de desinstalaciones específica de cada plataforma:
   • Configuración del seguimiento de desinstalaciones de iOS
   • Configuración del seguimiento de desinstalaciones de Android
2. Añade el token específico de la plataforma a la solicitud SESSION:
   • iOS: apns_token (token de dispositivo APNs)
   • Android: fcm (token de dispositivo FCM)

Recibo de instalación de iOS

Validación del recibo

Pasa el recibo de instalación de iOS en el parámetro install_receipt al reportar una sesión de iOS.

import Foundation
import StoreKit

class ReceiptManager {
    static func getInstallReceipt() - String? {
        if #available(iOS 18.0, *) {
            let semaphore = DispatchSemaphore(value: 0)
            var result: String?

            Task {
                do {
                    let transaction = try await AppTransaction.shared
                    result = transaction.jwsRepresentation
                    semaphore.signal()
                } catch {
                    debugPrint("Failed to get app transaction: \(error.localizedDescription)")
                    semaphore.signal()
                }
            }

            semaphore.wait()
            return result

        } else {
            guard let receiptURL = Bundle.main.appStoreReceiptURL else {
                debugPrint("Receipt URL not found")
                return nil
            }

            do {
                let receiptData = try Data(contentsOf: receiptURL, options: .uncached)
                return receiptData.base64EncodedString(options: [])
            } catch {
                debugPrint("Failed to read receipt: \(error.localizedDescription)")
                return nil
            }
        }
    }
}

Cumplimiento de privacidad de datos

Gestión del consentimiento del usuario

Notifica a Singular el consentimiento del usuario final para compartir datos a 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 dio su consentimiento (opted-in) para compartir información
• {"limit_data_sharing":true} : El usuario se negó a 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.

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