Referencia de la API del endpoint SESSION

Registra las sesiones de los usuarios y habilita la atribución para instalaciones de apps, reengagement y métricas de retención a través de la API REST de Singular usando la integración server-to-server como alternativa a la implementación con SDK.

Descripción general

Caso de uso server-to-server

La API REST de Singular permite una integración server-to-server directa en la que las apps envían datos específicos del dispositivo a tu backend, que los transmite a los servidores de Singular para el procesamiento de atribución y los reportes de analytics.

Capacidades soportadas:

• Atribución de instalación: Atribución de primer contacto a campañas de marketing
• Atribución de reengagement: Atribución multitáctil para usuarios que regresan
• Métricas de retención: Seguimiento del engagement basado en sesiones
• Seguimiento de eventos: Medición de eventos personalizados dentro de la app

Arquitectura del flujo de datos

La integración server-to-server sigue un proceso de transmisión de datos de cuatro pasos.

1. Recopilación en el cliente: La app recopila los datos requeridos del dispositivo y de la aplicación
2. Transmisión al servidor: La app envía los datos recopilados a tu servidor backend
3. Llamada a la API de Singular: Tu servidor envía los datos al endpoint de la API REST de Singular
4. Gestión de la respuesta: Tu servidor recibe y procesa la respuesta de Singular

Consideraciones clave

Beneficios de la integración:

• Flexibilidad: Control total sobre la recopilación de datos y el momento de la transmisión
• Paridad de funcionalidades: Soporta toda la funcionalidad del SDK cuando se proporcionan los datos adecuados
• Implementación personalizada: Adapta la integración a la arquitectura específica de tu backend

Gestión de sesiones

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

Cuándo enviar sesiones

Disparadores de sesión

Envía solicitudes SESSION para estos eventos del ciclo de vida de la app:

• Instalaciones nuevas: Primer inicio de la app después de la instalación
• Inicio desde estado terminado: La app se abre desde un estado completamente cerrado
• De segundo plano a primer plano: La app regresa a primer plano después de un periodo de tiempo de espera (recomendado: 60 segundos)

Lógica de tiempo de espera de la sesión

Implementa un tiempo de espera de sesión para evitar solicitudes SESSION excesivas durante breves pasos de la app a segundo plano.

Implementación recomendada:

• Duración del tiempo de espera: 60 segundos (1 minuto)
• Primer plano < tiempo de espera: No envíes SESSION si la app regresa a primer plano dentro del periodo de tiempo de espera
• Primer plano > tiempo de espera: Envía SESSION si la app permanece en segundo plano más allá del periodo de tiempo de espera
• Seguimiento del ciclo de vida de la app: Usa los eventos del ciclo de vida de la app y temporizadores para gestionar el estado de la sesión

Procesamiento de atribución

Atribución basada en sesiones

Singular procesa las solicitudes SESSION para determinar el tipo de atribución y activar los flujos de trabajo apropiados.

Más información: Preguntas frecuentes sobre atribución de reengagement

Requisitos de orden de eventos

El momento de las sesiones y los eventos afecta directamente la precisión de la atribución y la calidad de los datos.

Opciones avanzadas

Funcionalidad extendida

La integración S2S de Singular soporta capacidades avanzadas que requieren parámetros SESSION adicionales.

Especificación del endpoint de la API

El endpoint SESSION acepta solicitudes GET con parámetros de consulta que contienen datos del dispositivo, de la aplicación y de atribución.

URL del endpoint

URL base y método

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

Formato de la solicitud:

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

Parámetros requeridos

Todas las solicitudes SESSION deben incluir estos parámetros requeridos con los valores y el formato adecuados.

Autenticación de la API

SDK Key

Estos son parámetros S2S compartidos que se definen una sola vez en Fundamentos de S2S .

Identificadores de dispositivo

Identificadores específicos de la plataforma

Estos son parámetros S2S compartidos que se definen una sola vez en Fundamentos de S2S .

Parámetros del dispositivo

Información del dispositivo

Estos son parámetros S2S compartidos que se definen una sola vez en Fundamentos de S2S .

Parámetros de la aplicación

Información de la app

El identificador de la app ( i ), app_v y att_authorization_status son parámetros compartidos. Consulta Parámetros de la aplicación en Fundamentos de S2S .

Parámetros de prevención de fraude

Validación de la fuente de instalación

Parámetros de deep linking

Soporte para deep links

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

{
  "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 avanzados de atribución

Mejora de la atribución por plataforma

{
   "installBeginTimestampSeconds":"1568939453",
   "referrer":"utm_source=google-play&utm_medium=organic",
   "clickTimestampSeconds":"0",
   "referrer_source":"service",
   "current_device_time":"1568944524"
}

{
   "install_time_epoch_seconds":"1568939453",
   "install_referrer":"utm_source=google-play&utm_medium=organic"
}

{
  "install_referrer": {
    "utm_source":"apps.facebook.com",
    "utm_campaign": "fb4a",
    "utm_content": {
      "source":{
        "data":"c7e6b890bf18a059c2185650bdb1af3dced7...",
        "nonce":"24859720343e2381daee9f39ae61"
        },
      "app":533744218636280,
      "t":1731181327
      },
    "is_ct":1,
    "actual_timestamp":1731181444
  }
}

Parámetros opcionales

Los parámetros opcionales mejoran las capacidades de seguimiento y soportan funcionalidades avanzadas.

Parámetros de timestamp

Parámetros de red y ubicación

Estos son parámetros S2S compartidos que se definen una sola vez en Fundamentos de S2S .

Propiedades personalizadas

Soporte para seguimiento de desinstalaciones

Parámetros de privacidad de datos

Estos son parámetros S2S compartidos que se definen una sola vez en Fundamentos de S2S .

Soporte entre dispositivos

Estos son parámetros S2S compartidos que se definen una sola vez en Fundamentos de S2S .

Soporte para SKAdNetwork

Soporte para Google Ads ICM (Beta)

Ejemplos de solicitud

El código de muestra ilustra la integración del endpoint SESSION en múltiples lenguajes de programación.

import requests

params = {
    'a': 'sdk_key_here',
    'p': 'Android',
    'i': 'com.singular.app',
    'ip': '10.1.2.3',
    've': '9.2',
    'ma': 'samsung',
    'mo': 'SM-G935F',
    'lc': 'en_US',
    'aifa': '8ecd7512-2864-440c-93f3-a3cabe62525b',
    'asid': 'edee92a2-7b2f-45f4-a509-840f170fc6d9',
    'install': 'true',
    'n': 'MyCoolAppName',
    'bd': 'Build/13D15',
    'app_v': '1.2.3',
    'openuri': 'myapp://home/page?queryparam1=value1',
    'ddl_enabled': 'true',
    'install_source': 'com.android.vending',
    'install_time': 1510040127,
    'update_time': 1510090877
}

response = requests.get('https://s2s.singular.net/api/v1/launch', params=params)
print(response.json())

curl -G "https://s2s.singular.net/api/v1/launch" \
  --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 "ma=samsung" \
  --data-urlencode "mo=SM-G935F" \
  --data-urlencode "lc=en_US" \
  --data-urlencode "aifa=8ecd7512-2864-440c-93f3-a3cabe62525b" \
  --data-urlencode "asid=edee92a2-7b2f-45f4-a509-840f170fc6d9" \
  --data-urlencode "install=true" \
  --data-urlencode "n=MyCoolAppName" \
  --data-urlencode "bd=Build/13D15" \
  --data-urlencode "app_v=1.2.3" \
  --data-urlencode "openuri=myapp://home/page?queryparam1=value1" \
  --data-urlencode "ddl_enabled=true" \
  --data-urlencode "install_source=com.android.vending" \
  --data-urlencode "install_time=1510040127" \
  --data-urlencode "update_time=1510090877"

GET /api/v1/launch
    ?a=sdk_key_here
    &p=Android
    &i=com.singular.app
    &ip=10.1.2.3
    &ve=9.2
    &ma=samsung
    &mo=SM-G935F
    &lc=en_US
    &aifa=8ecd7512-2864-440c-93f3-a3cabe62525b
    &asid=edee92a2-7b2f-45f4-a509-840f170fc6d9
    &install=true
    &n=MyCoolAppName
    &bd=Build%2F13D15
    &app_v=1.2.3
    &openuri=myapp%3A%2F%2Fhome%2Fpage%3Fqueryparam1%3Dvalue1
    &ddl_enabled=true
    &install_source=com.android.vending
    &install_time=1510040127
    &update_time=1510090877 HTTP/1.1
Host: s2s.singular.net
Accept: application/json

// Base URL
String baseUrl = "https://s2s.singular.net/api/v1/launch";

// 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("ma", "samsung");
params.put("mo", "SM-G935F");
params.put("lc", "en_US");
params.put("aifa", "8ecd7512-2864-440c-93f3-a3cabe62525b");
params.put("asid", "edee92a2-7b2f-45f4-a509-840f170fc6d9");
params.put("install", "true");
params.put("n", "MyCoolAppName");
params.put("bd", "Build/13D15");
params.put("app_v", "1.2.3");
params.put("openuri", "myapp://home/page?queryparam1=value1");
params.put("ddl_enabled", "true");
params.put("install_source", "com.android.vending");
params.put("install_time", "1510040127");
params.put("update_time", "1510090877");

// 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 status
System.out.println("HTTP Status Code: " + responseCode);
System.out.println("Response: " + response.toString());

// Disconnect
conn.disconnect();

Códigos de respuesta y errores

El endpoint SESSION devuelve códigos de estado HTTP y respuestas JSON que indican el éxito o el fallo de la solicitud.

Documentación completa de errores: Códigos de respuesta S2S y gestión de errores

Pruebas y validación

Verifica la integración S2S antes del despliegue en producción usando la SDK Console de Singular para la validación de datos en tiempo real.

Procedimiento de prueba

Validación de extremo a extremo

1. Registra un dispositivo de prueba: Obtén el ID de publicidad del dispositivo y añádelo a la SDK Console de Singular
2. Habilita el registro en la Console: Añade el identificador del dispositivo en la SDK Console para capturar los datos de prueba
3. Usa un ID de app de desarrollo: Anula el identificador de la app con la versión de desarrollo (por ejemplo, com.singular.app.dev ) para separar los datos de prueba de los de producción
4. Inicia la app: Abre la app desde el estado terminado para activar una sesión
5. Valida los datos del cliente: Confirma que la app envía todos los puntos de datos de Singular requeridos a tu servidor
6. Verifica la solicitud del servidor: Confirma que tu servidor envía la solicitud SESSION a https://s2s.singular.net/api/v1/launch con todos los parámetros requeridos
7. Revisa la SDK Console: En cuestión de segundos, el evento SESSION debería aparecer en la SDK Console
8. Repite las pruebas: Valida que SESSION se active en cada entrada a la app y en cada operación de primer plano

Recursos adicionales

Documentación de pruebas

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