Referencia de la API del endpoint SESSION
Realiza el seguimiento de las sesiones de los usuarios y habilita la atribución de instalaciones de la app, reinteracción 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
El endpoint SESSION notifica a Singular cuando un usuario abre tu app, lo que impulsa la atribución de instalaciones y reinteracción y las métricas de retención. ¿Es tu primera vez con Server-to-Server? Consulta la guía de fundamentos de S2S para conocer los conceptos básicos y la configuración compartida.
Capacidades compatibles:
- Atribución de instalaciones: Atribución de primer contacto a campañas de marketing
- Atribución de reinteracción: Atribución multicontacto para usuarios que regresan
- Métricas de retención: Seguimiento de interacción basado en sesiones
Gestión 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.
Cuándo enviar sesiones
Desencadenadores 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 vuelve a primer plano después del período de tiempo de espera (recomendado: 60 segundos)
Lógica del tiempo de espera de la sesión
Implementa un tiempo de espera de sesión para evitar solicitudes SESSION excesivas cuando la app pasa brevemente 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 vuelve a primer plano dentro del período de tiempo de espera
- Primer plano > tiempo de espera: Envía SESSION si la app permanece en segundo plano más allá del período 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
Compatibilidad con deep links:
Envía siempre SESSION para las aperturas de la app
mediante deep links, Universal Links o App Links con el parámetro
openuri
completado, independientemente del estado del tiempo de espera.
Procesamiento de la 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 correspondientes.
| Tipo de sesión | Procesamiento de Singular | Resultado de la atribución |
|---|---|---|
| Primera sesión (instalación nueva) | Se activa el proceso de atribución de instalación | Atribuye la instalación a una campaña de marketing |
| Apta para reinteracción | Se activa el proceso de atribución de reinteracción | Atribuye el regreso del usuario a una campaña o deep link |
| Sesión estándar | Se registra la sesión para el seguimiento de retención | Cuenta para las métricas de actividad e interacción del usuario |
Más información: Preguntas frecuentes sobre atribución de reinteracción
Requisitos de orden de los eventos
El momento de las sesiones y los eventos afecta directamente la precisión de la atribución y la calidad de los datos.
Reglas críticas de orden:
- Sesión antes de los eventos: Se debe recibir una única SESSION antes de cualquier evento de esa sesión
- Transmisión de eventos en tiempo real: Los eventos in-app deben enviarse en tiempo real después de su respectiva sesión
- Procesamiento secuencial: Un orden de sesión no válido produce inconsistencias en los datos y errores de atribución
Especificación del endpoint de la API
El endpoint SESSION acepta solicitudes POST con los parámetros enviados como
application/x-www-form-urlencoded
.
Endpoint
URL base y método
POST https://s2s.singular.net/api/v1/launchEncabezado obligatorio:
Content-Type: application/x-www-form-urlencodedFormato de la solicitud:
POST /api/v1/launch HTTP/1.1
Host: s2s.singular.net
Content-Type: application/x-www-form-urlencoded
param1=value1¶m2=value2Parámetros obligatorios
Todas las solicitudes SESSION deben incluir estos parámetros obligatorios con los valores y el formato correctos.
Autenticación de la API
SDK Key
| Parámetro | Detalles |
|---|---|
a
|
Tipo:
String
Importante: No uses la Reporting API Key. Las solicitudes se rechazarán.
Ejemplo:
|
Identificadores del dispositivo
Identificadores específicos de la plataforma
| Parámetro | Detalles |
|---|---|
idfa
|
Plataforma:
iOS
|
idfv
|
Plataforma:
iOS
|
aifa
|
Plataforma:
Android
|
asid
|
Plataforma:
Android
|
amid
|
Plataforma:
Android
|
oaid
|
Plataforma:
Android
|
andi
|
Plataforma:
Android
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:
|
sdid
|
Plataforma:
iOS, Android, PC, Xbox, PlayStation, Nintendo, MetaQuest, CTV
|
Parámetros del dispositivo
Información del dispositivo
| Parámetro | Detalles |
|---|---|
p
|
Tipo:
String
|
ip
|
Tipo:
String
|
ve
|
Tipo:
String
|
ma
|
Plataforma:
iOS, Android
|
mo
|
Plataforma:
iOS, Android
|
lc
|
Plataforma:
iOS, Android
|
bd
|
Plataforma:
iOS, Android
|
Parámetros de la aplicación
Información de la app
| Parámetro | Detalles |
|---|---|
i
|
Tipo:
String
|
app_v
|
Tipo:
String
|
att_authorization_status
|
Plataforma:
iOS
Siempre obligatorio:
Aunque ATT no esté implementado, envía
Ejemplo:
|
| Parámetro | Detalles |
|---|---|
install
|
Tipo:
Boolean
|
install_time
|
Plataforma:
iOS, Android
Esta es la hora de instalación del dispositivo, no la hora de instalación de la atribución
de Singular. La atribución usa la marca de tiempo de la sesión (
Consulta la Guía de obtención de datos del dispositivo para saber cómo obtener este valor en iOS y Android. |
update_time
|
Plataforma:
iOS, Android
Consulta la Guía de obtención de datos del dispositivo para saber cómo obtener este valor en iOS y Android. |
Parámetros de prevención de fraude
Validación de la fuente de instalación
| Parámetro | Detalles |
|---|---|
install_source
|
Plataforma:
Android, PC
|
install_receipt
|
Plataforma:
iOS
|
Parámetros de deep linking
Compatibilidad con deep links
| Parámetro | Detalles |
|---|---|
openuri
|
Plataforma:
iOS, Android
|
ddl_enabled
|
Plataforma:
iOS, Android
|
singular_link_resolve_required
|
Plataforma:
iOS, Android
|
Parámetros de atribución avanzada
Mejora de la atribución por plataforma
| Parámetro | Detalles |
|---|---|
install_ref
Native PC (Google Play Games)
|
Plataforma:
Android (Google Play)
|
meta_ref
|
Plataforma:
Android (Google Play)
A partir del 18 de junio de 2025: Meta Advanced Mobile Measurement (AMM) elimina la necesidad de implementar Meta Install Referrer. No se recomienda si AMM está habilitado.
Meta Install Referrer codificado en URL en formato JSON para datos de atribución
granulares a nivel de usuario.
|
attribution_token
|
Plataforma:
iOS
|
Parámetros opcionales
Los parámetros opcionales mejoran las funciones de seguimiento y admiten funciones avanzadas.
Parámetros de marca de tiempo
| Parámetro | Detalles |
|---|---|
utime
|
Tipo:
Integer
|
umilisec
|
Tipo:
Integer
|
Parámetros de red y ubicación
| Parámetro | Detalles |
|---|---|
use_ip
|
Tipo:
Boolean
Limitaciones:
Ejemplo:
|
country
|
Tipo:
String
|
ua
|
Tipo:
String
|
c
|
Plataforma:
iOS, Android
|
cn
|
Plataforma:
iOS, Android
|
Propiedades personalizadas
| Parámetro | Detalles |
|---|---|
global_properties
|
Tipo:
JSON
|
Compatibilidad con el seguimiento de desinstalaciones
| Parámetro | Detalles |
|---|---|
apns_token
|
Plataforma:
iOS
|
fcm
|
Plataforma:
Android
|
Parámetros de privacidad de datos
| Parámetro | Detalles |
|---|---|
data_sharing_options
|
Tipo:
JSON
|
dnt
|
Plataforma:
iOS, Android
|
dntoff
|
Plataforma:
iOS, Android
|
Compatibilidad entre dispositivos
| Parámetro | Detalles |
|---|---|
custom_user_id
|
Tipo:
String
Sin PII: No envíes información de identificación personal. Usa un identificador interno con hash u anonimizado de otra forma, no direcciones de correo electrónico, números de teléfono ni nombres sin procesar.
Ejemplo:
|
Compatibilidad con SKAdNetwork
| Parámetro | Detalles |
|---|---|
skan_conversion_value
|
Plataforma:
iOS
|
skan_first_call_timestamp
|
Plataforma:
iOS
|
skan_last_call_timestamp
|
Plataforma:
iOS
|
Compatibilidad con Google Ads ICM (Beta)
| Parámetro | Detalles |
|---|---|
odm_info
|
Plataforma:
iOS
|
odm_error
|
Plataforma:
iOS
|
Ejemplos de solicitud
El código de muestra demuestra la integración del endpoint SESSION en varios lenguajes de programación.
Aviso sobre los ejemplos:
Es posible que las muestras de código no incluyan
todos los parámetros obligatorios. Valida la lista completa de parámetros antes de la
implementación en producción. Usa un
i
(identificador de la app)
único para el desarrollo/las pruebas.
Ejemplo en Python
import requests
url = 'https://s2s.singular.net/api/v1/launch'
headers = {'Content-Type': 'application/x-www-form-urlencoded'}
data = {
'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.post(url, data=data, headers=headers)
print(response.json())Ejemplo en cURL
curl -X POST "https://s2s.singular.net/api/v1/launch" \
-H "Content-Type: application/x-www-form-urlencoded" \
--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"Ejemplo en HTTP
POST /api/v1/launch HTTP/1.1
Host: s2s.singular.net
Content-Type: application/x-www-form-urlencoded
Accept: application/json
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=1510090877Ejemplo en Java
// Endpoint
String endpoint = "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 form-urlencoded body
StringBuilder form = new StringBuilder();
for (Map.Entry<String, String> entry : params.entrySet()) {
if (form.length() > 0) form.append('&');
form.append(URLEncoder.encode(entry.getKey(), StandardCharsets.UTF_8))
.append('=')
.append(URLEncoder.encode(entry.getValue(), StandardCharsets.UTF_8));
}
byte[] body = form.toString().getBytes(StandardCharsets.UTF_8);
// Create connection
URL url = new URL(endpoint);
HttpURLConnection conn = (HttpURLConnection) url.openConnection();
conn.setRequestMethod("POST");
conn.setDoOutput(true);
conn.setRequestProperty("Content-Type", "application/x-www-form-urlencoded");
conn.setRequestProperty("Accept", "application/json");
// Write body
try (OutputStream os = conn.getOutputStream()) {
os.write(body);
}
// 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();
System.out.println("HTTP Status Code: " + responseCode);
System.out.println("Response: " + response.toString());
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 fracaso de la solicitud.
Documentación completa de errores: Códigos de respuesta y gestión de errores de S2S
Pruebas y validación
Verifica la integración S2S antes de la implementación en producción usando la consola del SDK de Singular para la validación de datos en tiempo real.
Procedimiento de prueba
Validación de extremo a extremo
- Registra un dispositivo de prueba: Obtén el ID publicitario del dispositivo y agrégalo a la consola del SDK de Singular
- Habilita el registro en la consola: Agrega el identificador del dispositivo en la consola del SDK para capturar los datos de prueba
-
Usa un ID de app de desarrollo:
Sustituye el identificador de la app
por la versión de desarrollo (por ejemplo,
com.singular.app.dev) para separar los datos de prueba de los de producción - Inicia la app: Abre la app desde un estado terminado para activar una sesión
- Valida los datos del cliente: Confirma que la app envía todos los datos de Singular obligatorios a tu servidor
-
Verifica la solicitud del servidor:
Confirma que tu servidor envía la
solicitud SESSION a
https://s2s.singular.net/api/v1/launchcon todos los parámetros obligatorios - Revisa la consola del SDK: En cuestión de segundos, el evento SESSION debería aparecer en la consola del SDK
- Repite las pruebas: Valida que SESSION se active en cada entrada a la app y operación en primer plano
Verificación crítica: Confirma que el evento SESSION se produzca al abrir la app o pasar a primer plano ANTES de cualquier solicitud EVENT. Un orden no válido provoca errores de atribución.
Indicador de éxito: Si SESSION aparece en la consola del SDK, ¡has completado con éxito la prueba de integración de extremo a extremo!
Recursos adicionales
Documentación de pruebas
Guía de pruebas completa: Guía de pruebas de integración S2S