Documento

Referencia de puntos finales de la API para PC y consola

Referencia completa de la API para los puntos finales de servidor a servidor de PC y consola, que proporciona especificaciones detalladas de parámetros y ejemplos de implementación para el seguimiento de sesiones y la notificación de eventos.

Función para empresas: La atribución de juegos de PC y consola es una función para empresas. Para obtener más información, lea las preguntas frecuentes sobre la atribución de juegos para PC y consolao póngase en contacto con su gestor de éxito de clientes.

Guía de integración: Para obtener instrucciones completas de implementación y mejores prácticas, consulte la Guía de integración de S2S para PC y consola.

Punto final de notificación de sesiones

Notifique lanzamientos de juegos y sesiones a Singular para la atribución de instalaciones, seguimiento del reenganche y análisis de retención de usuarios.

Especificación del punto final

Método	URL
`GET`	`https://s2s.singular.net/api/v1/launch`

Propósito

Utilice el punto final de notificación de sesión para informar de todos los lanzamientos de juegos (primeras sesiones y sesiones repetidas) casi en tiempo real. El primer lanzamiento de un juego recibido por Singular para una instalación identificada por Singular Device ID activa el proceso de atribución.

Flujo de trabajo de atribución:

Primera sesión: Activa la atribución de la instalación comparándola con los clics de la campaña web.
Sesiones posteriores: Seguimiento de la actividad de los usuarios, retención, y análisis del reenganche.
Informes en tiempo real: Envío de notificaciones de sesión lo más cerca posible del lanzamiento real del juego.

Parámetros de sesión

Parámetros obligatorios

Parámetro	Descripción	Restricciones	Ejemplo
`a`	Clave SDK singular para la autenticación de la API. Ubicación: Panel → Herramientas de desarrollador → Integración SDK → Claves SDK. Importante: utilice SDK Key, no Reporting API Key.	Obligatorio Cadena	`your_org_name_sh868sdjv`
`p`	Plataforma en la que el usuario juega. Valores admitidos: `pc` `xbox` `playstation` `nintendo` `metaquest`	Obligatorio Cadena Distingue mayúsculas de minúsculas	`pc`
`i`	Identificador de juego único para tu juego. Crítico: Debe coincidir exactamente con el ID de producto del SDK web para que funcione la atribución. Utilice el mismo valor en todas las plataformas para el mismo juego.	Requerido Se recomienda la notación DNS inversa Distingue entre mayúsculas y minúsculas	`com.singular.game`
`sdid`	ID de dispositivo singular que identifica la instalación única del juego y la actividad del usuario. Generación: Creado por el juego/servidor en el primer lanzamiento, persiste durante toda la vida de la instalación del juego.	Requerido Se recomienda el formato UUID versión 4	`49c2d3a6-326e-4ec5-a16b-0a47e34ed953`
`os`	Sistema operativo o sistema de juego. Se admiten valores personalizados, pero se recomiendan valores por plataforma: PC: windows, linux, macOS, steamos Xbox: xbox_one, xbox_360, xbox_series_s, xbox_series_x PlayStation: playstation_3, playstation_4, playstation_5 Nintendo : nintendo_switch Meta Quest: metaquest, metaquest_2, metaquest_pro	Obligatorio Valores personalizados admitidos	`windows`
`install_source`	Tienda de juegos o método de distribución. Valores recomendados: `steam` `epicgamestore` `microsoftstore` `gog` `humblestore` `xbox` `playstation` `nintendo` `metaquest` `selfdistributed` Valores personalizados admitidos	Obligatorio Valores personalizados admitidos	`steam`
`ip`	Dirección IP del dispositivo en el momento del lanzamiento del juego. Alternativa: Utiliza `use_ip=true`para extraer la IP de la cabecera de la petición HTTP en lugar de pasarla explícitamente.	Obligatorio Formato IPv4 o IPv6 No se requiere si `use_ip=true`	`172.58.29.235`

Parámetros opcionales

Parámetro	Descripción	Restricciones	Ejemplo
`match_id`	Identificador para la atribución determinista que relaciona los clics web con las instalaciones de juegos. Requisitos: Debe enviarse sólo en el primer lanzamiento del juego Debe coincidir con el valor de la implementación del SDK web Si se trata de PII, debe estar cifrado con SHA-256 Consulte Match ID Attributionpara obtener detalles sobre la implementación.	Opcional Cadena Sólo primer lanzamiento	`matchid_12345`
`ve`	Versión del sistema operativo.	Opcional Cadena	`22H2`
`av`	Versión de la aplicación o identificador de compilación del juego.	Opcional Cadena	`1.1.5.581823a`
`use_ip`	Extrae la dirección IP de la cabecera de la petición HTTP en lugar de requerir el parámetro `ip` explícito. Si se establece en `true`, no se proporciona el parámetro `ip`.	Opcional Booleano Por defecto: false	`true`
`ua`	Cadena de agente de usuario del dispositivo.	Opcional Cadena	`Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36`
`global_properties`	Pares clave-valor guardados para el usuario y conservados en todas las solicitudes posteriores. Si no se envía el valor establecido previamente, se anula. Formato: Objeto JSON codificado en URL	Opcional Hasta 5 propiedades 200 caracteres máximo cada una JSON codificado en URL	`%7B%22key1%22%3A%22value1%22%7D`
`data_sharing_options`	Consentimiento del usuario para compartir información para el cumplimiento de la privacidad. Debe persistir y transmitirse en cada solicitud posterior si se establece. Valores: `"limit_data_sharing":false` - User opted in (consentimiento) `"limit_data_sharing":true` - User opted out (rechazado) Consulte Privacidad del usuariopara obtener instrucciones de implementación.	Opcional JSON codificado en URL	`%7B%22limit_data_sharing%22%3Atrue%7D`
`install`	Indicador de instalación que indica la primera sesión tras la instalación del juego. Necesario para el seguimiento de la reinstalación.	Opcional Booleano	`true`
`utime`	Marca de tiempo del lanzamiento del juego en tiempo UNIX (segundos).	Opcional Entero (UNIX timestamp)	`1483228800`
`umilisec`	Hora de inicio del juego en tiempo UNIX (milisegundos).	Opcional Entero (UNIX timestamp ms)	`1483228800000`
`custom_user_id`	Identificador de usuario personalizado de tu sistema.	Opcional Cadena	`123456789abcd`

Ejemplos de solicitud

Ejemplos de implementación

Solicitud de sesión básica

curl -G "https://s2s.singular.net/api/v1/launch" \
  --data-urlencode "a=your_sdk_key" \
  --data-urlencode "i=com.singular.game" \
  --data-urlencode "sdid=49c2d3a6-326e-4ec5-a16b-0a47e34ed953" \
  --data-urlencode "p=pc" \
  --data-urlencode "os=windows" \
  --data-urlencode "install_source=steam" \
  --data-urlencode "ip=172.58.29.235"

Primer lanzamiento con ID de partido

curl -G "https://s2s.singular.net/api/v1/launch" \
  --data-urlencode "a=your_sdk_key" \
  --data-urlencode "i=com.singular.game" \
  --data-urlencode "sdid=49c2d3a6-326e-4ec5-a16b-0a47e34ed953" \
  --data-urlencode "p=pc" \
  --data-urlencode "os=windows" \
  --data-urlencode "install_source=steam" \
  --data-urlencode "ip=172.58.29.235" \
  --data-urlencode "match_id=abc123def456" \
  --data-urlencode "install=true"

Solicitud de sesión básica

import requests

def report_session(config):
    url = "https://s2s.singular.net/api/v1/launch"
    
    params = {
        'a': config['sdk_key'],
        'i': config['game_id'],
        'sdid': config['device_id'],
        'p': config['platform'],
        'os': config['os_version'],
        'install_source': config['store'],
        'ip': config['ip_address']
    }
    
    response = requests.get(url, params=params)
    return response.json()

# Example usage
report_session({
    'sdk_key': 'your_sdk_key',
    'game_id': 'com.singular.game',
    'device_id': '49c2d3a6-326e-4ec5-a16b-0a47e34ed953',
    'platform': 'pc',
    'os_version': 'windows',
    'store': 'steam',
    'ip_address': '172.58.29.235'
})

Primer lanzamiento con ID de partido

def report_first_launch(config):
    url = "https://s2s.singular.net/api/v1/launch"
    
    params = {
        'a': config['sdk_key'],
        'i': config['game_id'],
        'sdid': config['device_id'],
        'p': config['platform'],
        'os': config['os_version'],
        'install_source': config['store'],
        'ip': config['ip_address'],
        'match_id': config['match_id'],
        'install': 'true'
    }
    
    response = requests.get(url, params=params)
    return response.json()

Solicitud de sesión básica

async function reportSession(config) {
    const url = 'https://s2s.singular.net/api/v1/launch';
    
    const params = new URLSearchParams({
        'a': config.sdkKey,
        'i': config.gameId,
        'sdid': config.deviceId,
        'p': config.platform,
        'os': config.osVersion,
        'install_source': config.store,
        'ip': config.ipAddress
    });
    
    const response = await fetch(`${url}?${params.toString()}`);
    return await response.json();
}

// Example usage
reportSession({
    sdkKey: 'your_sdk_key',
    gameId: 'com.singular.game',
    deviceId: '49c2d3a6-326e-4ec5-a16b-0a47e34ed953',
    platform: 'pc',
    osVersion: 'windows',
    store: 'steam',
    ipAddress: '172.58.29.235'
});

Primer lanzamiento con ID de partido

async function reportFirstLaunch(config) {
    const url = 'https://s2s.singular.net/api/v1/launch';
    
    const params = new URLSearchParams({
        'a': config.sdkKey,
        'i': config.gameId,
        'sdid': config.deviceId,
        'p': config.platform,
        'os': config.osVersion,
        'install_source': config.store,
        'ip': config.ipAddress,
        'match_id': config.matchId,
        'install': 'true'
    });
    
    const response = await fetch(`${url}?${params.toString()}`);
    return await response.json();
}

Notificación de eventos

Notificación de eventos del juego a Singular para análisis, optimización de campañas y reenvío a socios.

Especificación del punto final

Método	URL
`GET`	`https://s2s.singular.net/api/v1/evt`

Propósito

Utilice el punto final de notificación de eventos para informar de todos los eventos del juego deseados casi en tiempo real. Los datos de eventos se utilizan para análisis, informes, optimización de socios y medición del rendimiento de campañas.

Mejores prácticas de eventos:

Eventos estándar: Utilice nombres de eventos estándar Singularpara la asignación automática de socios.
Informes en tiempo real: Enviar eventos lo más cerca posible de su ocurrencia real
Eventos de ingresos: Incluya parámetros de ingresos para el seguimiento de las compras y el análisis del ROI

Parámetros de eventos

Parámetros requeridos

Parámetro	Descripción	Restricciones	Ejemplo
`a`	Clave SDK singular para la autenticación de la API. Ubicación: Panel → Herramientas de desarrollador → Integración SDK → Claves SDK.	Obligatorio Cadena	`your_org_name_sh868sdjv`
`p`	Plataforma en la que el usuario juega. Valores admitidos: pc, xbox, playstation, nintendo, metaquest.	Obligatorio Cadena Distingue entre mayúsculas y minúsculas	`pc`
`i`	Identificador de juego único para su juego. Debe coincidir con el valor utilizado en las notificaciones de sesión y el ID de producto del SDK web.	Obligatorio Notación DNS inversa recomendada Se distingue entre mayúsculas y minúsculas	`com.singular.game`
`sdid`	ID de dispositivo singular que identifica una instalación de juego única. Debe coincidir con el SDID utilizado en las notificaciones de sesión.	Obligatorio Formato UUID	`49c2d3a6-326e-4ec5-a16b-0a47e34ed953`
`n`	Nombre del evento que identifica una acción o hito del juego. Recomendado: Utiliza los nombres de evento estándar de Singularpara la integración automática de socios.	Requerido Cadena 32 caracteres ASCII máximo	`sng_achievement_unlocked`
`os`	Sistema operativo o sistema de juego. Debe coincidir con el valor utilizado en las notificaciones de sesión.	Obligatorio Valores personalizados admitidos	`windows`
`install_source`	Tienda de juegos o método de distribución. Debe coincidir con el valor utilizado en las notificaciones de sesión.	Obligatorio Valores personalizados admitidos	`steam`
`ip`	Dirección IP del dispositivo en el momento del evento.	Obligatorio Formato IPv4 o IPv6 No se requiere si `use_ip=true`	`172.58.29.235`

Parámetros opcionales

Parámetro	Descripción	Restricciones	Ejemplo
`e`	Atributos de evento personalizados que proporcionan información detallada sobre el evento. Recomendado: Utilizar nombres de atributos estándar Singularpor compatibilidad con los socios.	Opcional JSON codificado en URL 500 caracteres ASCII como máximo por atributo	`%7B%22sng_attr_content_id%22%3A5581%7D`
`is_revenue_event`	Marca el evento como evento de ingresos. Puede omitirse si el nombre del evento es `__iap__`o si se proporciona un `amt`distinto de cero.	Obligatorio para los eventos con ingresos Booleano	`true`
`amt`	Importe en divisa del evento de ingresos. Se utiliza con el parámetro `cur`.	Obligatorio para eventos de ingresos Número decimal	`2.51`
`cur`	Código de moneda de tres letras ISO-4217 para el evento de ingresos. Se utiliza con el parámetro `amt`. Referencia: Códigos de divisa ISO-4217	Obligatorio para los eventos de ingresos Código ISO-4217	`EUR`
`ve`	Versión del sistema operativo.	Opcional Cadena	`22H2`
`av`	Versión de la aplicación o identificador de compilación del juego.	Opcional Cadena	`1.1.5.581823a`
`use_ip`	Extraer la dirección IP de la cabecera de la petición HTTP.	Opcional Booleano Por defecto: false	`true`
`ua`	Cadena Agente de usuario del dispositivo.	Opcional Cadena	`Mozilla/5.0 (Windows NT 10.0; Win64; x64)`
`global_properties`	Pares clave-valor guardados para el usuario. Debe persistir en todas las solicitudes posteriores si se establece.	Opcional Hasta 5 propiedades 200 caracteres máximo cada una JSON codificado en URL	`%7B%22key1%22%3A%22value1%22%7D`
`data_sharing_options`	Consentimiento del usuario para compartir información. Debe persistir en todas las solicitudes posteriores si se establece.	Opcional JSON codificado en URL	`%7B%22limit_data_sharing%22%3Atrue%7D`
`utime`	Marca de tiempo del evento en tiempo UNIX (segundos).	Opcional Entero (UNIX timestamp)	`1483228800`
`umilisec`	Timestamp del evento en tiempo UNIX (milisegundos).	Opcional Entero (UNIX timestamp ms)	`1483228800000`
`custom_user_id`	Identificador de usuario personalizado de su sistema.	Opcional Cadena	`123456789abcd`

Ejemplos de solicitud

Ejemplos de implementación

Evento estándar

curl -G "https://s2s.singular.net/api/v1/evt" \
  --data-urlencode "a=your_sdk_key" \
  --data-urlencode "i=com.singular.game" \
  --data-urlencode "sdid=49c2d3a6-326e-4ec5-a16b-0a47e34ed953" \
  --data-urlencode "p=pc" \
  --data-urlencode "os=windows" \
  --data-urlencode "install_source=steam" \
  --data-urlencode "n=sng_level_achieved" \
  --data-urlencode 'e={"sng_attr_level":"5","sng_attr_score":"1250"}' \
  --data-urlencode "ip=172.58.29.235"

Evento de ingresos

curl -G "https://s2s.singular.net/api/v1/evt" \
  --data-urlencode "a=your_sdk_key" \
  --data-urlencode "i=com.singular.game" \
  --data-urlencode "sdid=49c2d3a6-326e-4ec5-a16b-0a47e34ed953" \
  --data-urlencode "p=pc" \
  --data-urlencode "os=windows" \
  --data-urlencode "install_source=steam" \
  --data-urlencode "n=__iap__" \
  --data-urlencode "is_revenue_event=true" \
  --data-urlencode "amt=9.99" \
  --data-urlencode "cur=USD" \
  --data-urlencode "ip=172.58.29.235"

Evento estándar

import requests
import json

def report_event(config):
    url = "https://s2s.singular.net/api/v1/evt"
    
    params = {
        'a': config['sdk_key'],
        'i': config['game_id'],
        'sdid': config['device_id'],
        'p': config['platform'],
        'os': config['os_version'],
        'install_source': config['store'],
        'n': config['event_name'],
        'ip': config['ip_address']
    }
    
    if 'attributes' in config:
        params['e'] = json.dumps(config['attributes'])
    
    response = requests.get(url, params=params)
    return response.json()

# Example usage
report_event({
    'sdk_key': 'your_sdk_key',
    'game_id': 'com.singular.game',
    'device_id': '49c2d3a6-326e-4ec5-a16b-0a47e34ed953',
    'platform': 'pc',
    'os_version': 'windows',
    'store': 'steam',
    'event_name': 'sng_level_achieved',
    'attributes': {
        'sng_attr_level': '5',
        'sng_attr_score': '1250'
    },
    'ip_address': '172.58.29.235'
})

Evento de ingresos

def report_revenue(config):
    url = "https://s2s.singular.net/api/v1/evt"
    
    params = {
        'a': config['sdk_key'],
        'i': config['game_id'],
        'sdid': config['device_id'],
        'p': config['platform'],
        'os': config['os_version'],
        'install_source': config['store'],
        'n': '__iap__',
        'is_revenue_event': 'true',
        'amt': config['amount'],
        'cur': config['currency'],
        'ip': config['ip_address']
    }
    
    response = requests.get(url, params=params)
    return response.json()

# Example usage
report_revenue({
    'sdk_key': 'your_sdk_key',
    'game_id': 'com.singular.game',
    'device_id': '49c2d3a6-326e-4ec5-a16b-0a47e34ed953',
    'platform': 'pc',
    'os_version': 'windows',
    'store': 'steam',
    'amount': 9.99,
    'currency': 'USD',
    'ip_address': '172.58.29.235'
})

Evento estándar

async function reportEvent(config) {
    const url = 'https://s2s.singular.net/api/v1/evt';
    
    const params = new URLSearchParams({
        'a': config.sdkKey,
        'i': config.gameId,
        'sdid': config.deviceId,
        'p': config.platform,
        'os': config.osVersion,
        'install_source': config.store,
        'n': config.eventName,
        'ip': config.ipAddress
    });
    
    if (config.attributes) {
        params.append('e', JSON.stringify(config.attributes));
    }
    
    const response = await fetch(`${url}?${params.toString()}`);
    return await response.json();
}

// Example usage
reportEvent({
    sdkKey: 'your_sdk_key',
    gameId: 'com.singular.game',
    deviceId: '49c2d3a6-326e-4ec5-a16b-0a47e34ed953',
    platform: 'pc',
    osVersion: 'windows',
    store: 'steam',
    eventName: 'sng_level_achieved',
    attributes: {
        'sng_attr_level': '5',
        'sng_attr_score': '1250'
    },
    ipAddress: '172.58.29.235'
});

Evento de ingresos

async function reportRevenue(config) {
    const url = 'https://s2s.singular.net/api/v1/evt';
    
    const params = new URLSearchParams({
        'a': config.sdkKey,
        'i': config.gameId,
        'sdid': config.deviceId,
        'p': config.platform,
        'os': config.osVersion,
        'install_source': config.store,
        'n': '__iap__',
        'is_revenue_event': 'true',
        'amt': config.amount,
        'cur': config.currency,
        'ip': config.ipAddress
    });
    
    const response = await fetch(`${url}?${params.toString()}`);
    return await response.json();
}

// Example usage
reportRevenue({
    sdkKey: 'your_sdk_key',
    gameId: 'com.singular.game',
    deviceId: '49c2d3a6-326e-4ec5-a16b-0a47e34ed953',
    platform: 'pc',
    osVersion: 'windows',
    store: 'steam',
    amount: 9.99,
    currency: 'USD',
    ipAddress: '172.58.29.235'
});

Gestión de respuestas

Ambos puntos finales devuelven respuestas JSON coherentes que requieren la validación del campo de estado para determinar el éxito o el error.

Formato de respuesta

Importante: Todas las respuestas devuelven códigos de estado HTTP 200. Valide siempre el campo status del cuerpo de la respuesta para determinar el éxito (ok) o el error (error).

Para obtener documentación completa sobre códigos de respuesta y estrategias de gestión de errores, consulte Códigos de respuesta y gestión de errores de S2S.

Recursos adicionales

Guía de integración:Guía de integración de S2S en PC y consola
Web SDK:Descripción general y primeros pasos del Web SDK
Preguntas frecuentes sobre atribución:Preguntas frecuentes sobre atribución de juegos en PC y consola
Eventos estándar:Referencia de eventos estándar singulares

PC y consola - Referencia de puntos finales de la API

Referencia de puntos finales de la API para PC y consola

Punto final de notificación de sesiones

Especificación del punto final

Propósito

Parámetros de sesión

Parámetros obligatorios

Parámetros opcionales

Ejemplos de solicitud

Ejemplos de implementación

Solicitud de sesión básica

Primer lanzamiento con ID de partido

Solicitud de sesión básica

Primer lanzamiento con ID de partido

Solicitud de sesión básica

Primer lanzamiento con ID de partido

Notificación de eventos

Especificación del punto final

Propósito

Parámetros de eventos

Parámetros requeridos

Parámetros opcionales

Ejemplos de solicitud

Ejemplos de implementación

Evento estándar

Evento de ingresos

Evento estándar

Evento de ingresos

Evento estándar

Evento de ingresos

Gestión de respuestas

Formato de respuesta

Recursos adicionales