Servidor-a-Servidor - Guía de Integración

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

Visión general

Caso de uso de servidor a servidor

La integración de servidor a servidor (S2S) proporciona puntos finales de API REST para construir soluciones completas de atribución y análisis que se ejecutan desde su infraestructura de backend sin incrustar Singular SDK 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: Singular SDK gestiona las sesiones mientras que el servidor se encarga del seguimiento de eventos.

Patrón de integración híbrida

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

Métodos de recuperación de datos de dispositivos:

1. Flujo gestionado por el cliente: captura los puntos de datos necesarios en el cliente y los reenvía al servidor a través de la API interna para su uso con el punto final Singular EVENT
2. Devolución interna de BI: Configurar el postback de Singular Internal BI para recibir en tiempo real la carga JSON con los identificadores de dispositivo después de la instalación, la reconexión o los eventos(Guía de configuración).

Recursos de implementación:

• Parámetros obligatorios del punto final EVENT
• Guía de recuperación de datos de dispositivos(ejemplos de código iOS/Android)

Principios clave de integración

Requisitos de integración

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

1. Recopilación de datos: Recopilación de los puntos de datos necesarios de las aplicaciones cliente
2. Gráfico de dispositivos: Transmisión de datos al servidor y almacenamiento del identificador del dispositivo.
3. Solicitudes de sesión: Envío de notificaciones de sesión a través de SESSION API
4. Gestión de respuestas: Procesar y retransmitir las respuestas de Singular a la aplicación cliente
5. Solicitudes de eventos: Envío de eventos a través de la API EVENT

Puntos finales de la API REST

Singular proporciona dos puntos finales principales de la API REST para el seguimiento de sesiones y eventos de servidor a servidor.

Punto final de sesión

API de seguimiento de sesión

El punto final SESSION notifica a Singular los eventos de apertura de aplicaciones para inicializar las sesiones de usuario para el seguimiento de atribución y retención.

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

Referenciacompleta: SESSION Endpoint API Reference

Punto final de eventos

API de seguimiento de eventos

El punto final EVENT rastrea eventos e ingresos dentro de la aplicación 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 de punto final EVENT

Fases de implementación

La integración satisfactoria de S2S requiere cuatro fases de implementación clave ejecutadas secuencialmente para obtener una calidad de datos y una precisión de atribución óptimas.

Fase 1: Recopilación de datos

Puntos de datos necesarios

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

Recursos de implementación:

• SESSION Endpoint Parámetros requeridos
• Parámetros obligatorios del punto final EVENT
• Guía de recuperación de datos de dispositivos(ejemplos 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 sincronización

La transmisión de datos en tiempo real mantiene la precisión de la atribución y permite funciones sensibles al tiempo como las actualizaciones del valor de conversión de SKAdNetwork.

Mejores prácticas:

• Implemente escuchadores de eventos en el servidor para el inicio de sesión de la aplicación.
• Reenvíe inmediatamente los datos de sesióncon todos los parámetros necesarios
• Implementar escuchadores de eventos del lado del servidor para eventos dentro de la aplicación
• Reenvíe inmediatamente los datos de eventoscon todos los parámetros necesarios
• Utilizar la arquitectura webhook para una transmisión de datos fiable
• Implementación de mecanismos de reintento para solicitudes fallidas
• Supervisar el flujo de datos para garantizar la calidad

Fase 3: Gestión de respuestas

Comunicación bidireccional

La gestión de respuestas sirve de puente entre las interacciones de la API del lado del servidor y la funcionalidad del lado del cliente, permitiendo la vinculación profunda diferida y las actualizaciones de los valores de conversión.

Tipos de respuesta clave:

• Enlaces profundos diferidos: La respuesta de la API contiene datos de enlaces profundos pendientes que requieren una transmisión inmediata a la aplicación para el enrutamiento y la personalización del usuario.
• Valores de conversión: los valores de conversión de iOS SKAdNetwork deben enviarse inmediatamente a la aplicación para una medición precisa de la campaña.

Mejores prácticas:

• Implementar la gestión de respuestas en la infraestructura del servidor
• Analizar y validar las respuestas de Singular API
• Enviar los datos de respuesta relevantes a la aplicación cliente (esencial para iOS SKAdNetwork)
• Implementar el procesamiento de respuestas del lado del cliente
• Gestión de errores con códigos de estado HTTP adecuados
• Registrar 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 flujo de datos y la precisión de la atribución antes de la implantación 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 Qualified: Singular activa el proceso de atribución de reconexión(Preguntas frecuentes sobre reconexión).
• Sesión estándar: Singular registra la sesión para la actividad del usuario y las métricas de retención.

Lista de comprobación de validación:

• Probar el flujo de datos de la sesión-validar que la primera sesión y las siguientes tengan puntos de datos y valores correctos
• Confirmar que los eventos se reciben sólo después de la sesión comunicada a Singular (los eventos anteriores a la sesión crean una atribución orgánica).
• Confirme que la respuesta de la sesión se gestiona y se transmite a la aplicación del cliente (fundamental para los enlaces profundos diferidos).

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

Funciones avanzadas

Mejore la integración de S2S con el manejo avanzado de atribución, vinculación profunda, seguimiento entre dispositivos y capacidades específicas de la plataforma.

Atribución de anuncios de búsqueda de Apple

Integración de iOS Search Ads

Apple Search Ads es una red de autoatribución (SAN) que requiere una implementación de atribución específica de la plataforma a través de los marcos de Apple.

Compatibilidad con marcos:

• iOS 14.2 e inferiores: framework iAd
• iOS 14.3 y superior: AdServices framework(recomendado)

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

Implementación del marco iAd

Recupere y envíe datos de atribución de Apple Search Ads a través de iAd Framework para iOS 14.2 y versiones inferiores.

Paso 1: Recuperar 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

Notificar 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 de AdServices Framework

Recuperación y envío del token de atribución a través del marco de AdServices para iOS 14.3 y versiones posteriores.

Paso 1: Recuperación del 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

URL-codificar token y añadir a SESSION endpointcomo parámetro attribution_token en la primera sesión después de cada instalación y reinstalación.

Referencia de instalación de Google Play

Atribución de instalaciones de Android

Google Play Install Referrer proporciona la atribución de instalación de Android más precisa, ya que contiene información sobre el origen del usuario antes de su llegada a Play Store.

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

Pasos de implementación:

1. Recuperación de la referencia de instalación en la primera apertura de la aplicación mediante la API de referencia de instalación de Play
2. Informar de la sesión a través del endpoint SESSIONincluyendo el parámetro JSON install_ref con los atributos requeridos

install_ref Atributos:

Meta Referencia de instalación

Mejora de la atribución de Facebook

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

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

Pasos de implementación:

1. Recuperar Meta Install Referrer en la primera aplicación abierta según la documentación de Meta.
2. Informar de la sesión a través del endpoint SESSIONincluyendo el parámetro meta_ref JSON con los atributos requeridos

Atributos meta_ref:

Enlaces singulares y enlaces profundos

Implemente el soporte de enlaces profundos y enlaces profundos diferidos para los enlaces de seguimiento Singular para permitir experiencias de usuario fluidas desde las campañas hasta el contenido específico de la aplicación.

Los enlaces profundos son enlaces en los que se puede hacer clic y que llevan a los usuarios a contenidos específicos dentro de las aplicaciones. Cuando el usuario hace clic en un enlace profundo en un dispositivo con una aplicación instalada, la aplicación se abre y muestra un producto o experiencia específicos.

Recursos: Preguntas frecuentes sobre enlaces profundos| Preguntas frecuentes sobre enlaces singulares

Requisitos previos

Configuración de la plataforma

La aplicación cliente debe reconocer Singular Links como iOS Universal Links o Android App Links.

Guía de configuración: Requisitos previos de Singular Links

Implementación de Deep Links

Captura de enlaces profundos

Cuando la aplicación se abre a través de un enlace profundo, captura y añade openURL a la solicitud de SESSION añadiendo el valor de la URL al parámetro openuri. Es necesario cuando se utilizan enlaces singulares.

Parámetrosde enlacessingulares:

• _ios_dl y _android_dl: Presente cuando el enlace se genera con diferentes valores de enlace profundo por plataforma.
• _dl Presente cuando los valores del enlace profundo son los mismos para iOS y Android
• _p Presente cuando se incluye el parámetro passthrough

Código Deep Link Handler

La aplicación debe tener un código de gestión que analice openURL y gestione adecuadamente los parámetros de enlace singular.

class DeepLinkHandler {
    func handleURL(_ url: URL) {
        guard let components = URLComponents(url: url, resolvingAgainstBaseURL: true) else {
            return
        }

        var params: [String: String] = [:]

        // Parse query parameters
        if let queryItems = components.queryItems {
            for item in queryItems {
                switch item.name {
                case "_dl":
                    params["deeplink"] = item.value
                case "_ios_dl":
                    params["ios_deeplink"] = item.value
                case "_p":
                    params["passthrough"] = item.value
                default:
                    break
                }
            }
        }

        // Handle the parsed parameters
        processDeepLinkParameters(params)
    }

    private func processDeepLinkParameters(_ params: [String: String]) {
        // Process the parameters as needed
        print("Processed parameters: \(params)")
    }
}

// In SceneDelegate or AppDelegate
func scene(_ scene: UIScene, openURLContexts URLContexts: Set<UIOpenURLContext>) {
    guard let url = URLContexts.first?.url else { return }
    let handler = DeepLinkHandler()
    handler.handleURL(url)
}

class DeepLinkHandler {
    fun handleDeepLink(intent: Intent) {
        val data: Uri? = intent.data

        data?.let { uri ->
            val params = mutableMapOf<String, String>()

            // Parse query parameters
            uri.queryParameterNames?.forEach { name ->
                when (name) {
                    "_dl" -> params["deeplink"] = uri.getQueryParameter(name) ?: ""
                    "_android_dl" -> params["android_deeplink"] = uri.getQueryParameter(name) ?: ""
                    "_p" -> params["passthrough"] = uri.getQueryParameter(name) ?: ""
                }
            }

            processDeepLinkParameters(params)
        }
    }

    private fun processDeepLinkParameters(params: Map<String, String>) {
        // Process the parameters as needed
        println("Processed parameters: $params")
    }
}

// In your Activity
class MainActivity : AppCompatActivity() {
    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        setContentView(R.layout.activity_main)

        // Handle deep link if activity was launched from a deep link
        intent?.let { DeepLinkHandler().handleDeepLink(it) }
    }

    override fun onNewIntent(intent: Intent?) {
        super.onNewIntent(intent)
        // Handle deep link if app was already running
        intent?.let { DeepLinkHandler().handleDeepLink(it) }
    }
}

Enlaces profundos diferidos

Enlaces profundos de primera instalación

Cuando la aplicación se abre por primera vez desde la instalación, active la vinculación profunda diferida añadiendo parámetros al informar de la sesión a Singular.

Parámetros obligatorios:

• install=true
• ddl_enabled=true

Singular comprueba si la aplicación se instaló a través de un enlace de seguimiento con enlace profundo diferido. Si es así, devuelve la solicitud SESSION:

• deferred_deeplink La dirección del enlace profundo se analiza para mostrar a los usuarios el producto o la experiencia correctos.
• deferred_passthrough Parámetros Passthrough añadidos al enlace profundo

Respuesta de ejemplo:

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

Parámetros passthrough dinámicos

Los enlaces de seguimiento singulares pueden incluir parámetros passthrough dinámicos para experiencias de usuario personalizadas.

Si la organización configuró el passthrough dinámico para el enlace, la URL del enlace profundo incluye el parámetro _p con un valor de cadena JSON codificado en la URL o una cadena no estructurada para el enrutamiento del contenido/experiencia.

Más información: Parámetros de traspaso dinámico

Resolución de enlaces cortos

Cuando la aplicación se abre desde un enlace singular acortado, incluya el parámetro en la solicitud de SESIÓN para resolver el enlace corto y convertirlo en enlace largo.

Parámetro obligatorio: singular_link_resolve_required=true

Singular devuelve el enlace largo no acortado para analizar el enlace profundo y los parámetros passthrough en el gestor de enlaces.

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"
}

Funciones adicionales

Implemente el seguimiento entre dispositivos, el seguimiento de los ingresos, la supervisión de la desinstalación y el cumplimiento de la privacidad de los datos para un análisis exhaustivo.

Seguimiento entre dispositivos

Implementación de ID de usuario personalizados

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

Permite la elaboración de informes completos entre dispositivos, la exportación de datos a nivel de usuario y las devoluciones internas de BI, al tiempo que se mantiene la privacidad del usuario.

Más información: Parámetro de ID de usuario personalizado

Seguimiento de ingresos

Informes de compras dentro de la aplicación

Realice un seguimiento de los ingresos procedentes de las compras dentro de la aplicación para el análisis del rendimiento de la inversión, la medición del rendimiento de la campaña y el enriquecimiento de las exportaciones y las devoluciones.

Utilice el punto final EVENTcon parámetros de ingresos:

• is_revenue_event: Marca el evento como evento de ingresos (se omite si el nombre del evento es __iap__ o el importe > 0)
• purchase_receipt Objeto In-App Purchase de Android/iOS: muy recomendado para detalles de transacciones y enriquecimiento de informes.
• receipt_signature (Android): Muy recomendado para la validación de transacciones y la prevención del fraude
• amt Importe de ingresos como doble (por ejemplo, "amt=1,99")
• cur Código de moneda ISO 4217 (por ejemplo, "cur=USD")

Guía de implantación: Gestión del estado de suscripción

Seguimiento de la desinstalación

Configuración de notificaciones push silenciosas

Realice un seguimiento de las desinstalaciones mediante notificaciones push silenciosas del dispositivo enviando un token push con cada notificación de sesión.

Requisitos de configuración:

1. Siga la configuración de seguimiento de desinstalaciones específica de la plataforma:
   • Configuración del seguimiento de desinstalaciones de iOS
   • Configuración del seguimiento de desinstalaciones de Android
2. Añada un token específico de la plataforma a la solicitud de SESIÓN:
   • iOS: apns_token (token de dispositivo APNs)
   • Android: fcm (token de dispositivo FCM)

Recibo de instalación de iOS

Validación del recibo

Pase el recibo de instalación de iOS en el parámetro install_receipt al informar de la 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

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

Utilice data_sharing_options para comunicar la elección del usuario:

• {"limit_data_sharing":false}: El usuario consintió (opted-in) compartir información
• {"limit_data_sharing":true} El usuario se negó a compartir información

Singular utiliza limit_data_sharing en User Privacy Postbacksy pasa la información a los socios que exigen el cumplimiento.

Más información: Privacidad del usuario y Limitar el uso compartido de datos