Documento

Referencia de puntos finales de API para PC y consola

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

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

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

Punto final de notificación de sesión

Informe de los inicios de juego y las sesiones a Singular para la atribución de instalaciones, el seguimiento de la reactivación y el análisis de la retención de usuarios.

Especificaciones del punto final

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

Finalidad

Utilice el punto final de notificación de sesión para informar de todos los inicios de juego (primera y repetidas sesiones) casi en tiempo real. El primer inicio de juego recibido por Singular para la instalación identificado por el ID de dispositivo de Singular activa el proceso de atribución.

Flujo de trabajo de atribución:

Primera sesión: activa la atribución de la instalación comparando con los clics de la campaña web
Sesiones posteriores: se realiza un seguimiento de la actividad del usuario, la retención y los análisis de reenganche
Informes en tiempo real: se envían notificaciones de sesión lo más cerca posible del inicio real del juego

Parámetros de sesión

Parámetros obligatorios

Parámetro	Descripción	Restricciones	Ejemplo
`a`	Clave SDK única para la autenticación de la API. Ubicación: Panel de control → Herramientas para desarrolladores → Integración del SDK → Claves del SDK Importante: utilice la clave SDK, no la clave API de informes .	Requerido 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 único de tu juego. Critical: Debe coincidir exactamente con el ID del producto del SDK web para que la atribución funcione. Utilice el mismo valor en todas las plataformas para el mismo juego.	Obligatorio Se recomienda la notación DNS inversa Distingue entre mayúsculas y minúsculas	`com.singular.game`
`sdid`	Identificador de dispositivo único que identifica la instalación única del juego y la actividad del usuario. Generación: Creado por el juego/servidor en el primer inicio, persiste durante toda la vida útil 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 los siguientes valores según la 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	Requerido 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 inicio del juego. Alternativa: Utilice `use_ip=true` para extraer la IP del encabezado de la solicitud HTTP en lugar de pasarla explícitamente.	Obligatorio Formato IPv4 o IPv6 No es necesario si se utiliza `use_ip=true`	`172.58.29.235`

Parámetros opcionales

Parámetro	Descripción	Restricciones	Ejemplo
`install_ref`	Información de referencia de instalación de Google codificada en JSON URL. Proporciona la atribución más precisa para los juegos nativos para PC distribuidos a través de la tienda Google Play Games. Requisitos: Requiere implementar el SDK de Play Games para PC para pasar la Debe enviarse solo en el primer inicio del juego Consulte la documentaciónde Google Play para referencias de instalación de PC nativas para obtener detalles sobre la implementación.	Opcional Cadena Solo en el primer inicio	`%7B%22install_time_epoch_seconds%22%3A%221568939453%22` `%2C%22install_referrer%22%3A%22utm_source%3Dgoogle-play%26utm_medium%3Dorganic%22%7D`
`match_id`	Identificador para la atribución determinista que relaciona los clics web con las instalaciones del juego . Requisitos: Debe enviarse solo en el primer inicio del juego Debe coincidir con el valor de la implementación del SDK web Si se trata de información de identificación personal (PII), debe hasharse utilizando SHA-256 Consulte Atribución de ID coincidente para obtener detalles sobre la implementación.	Opcional Cadena Solo en el primer inicio	`matchid_12345`
`ve`	Versión del sistema operativo.	Opcional Cadena	`22H2`
`av`	Versión de la aplicación o identificador de la compilación del juego.	Opcional Cadena	`1.1.5.581823a`
`use_ip`	Extrae la dirección IP del encabezado de la solicitud HTTP en lugar de requerir explícitamente el parámetro `ip`. Si se establece en `true`, no proporcione el parámetro `ip` .	Opcional Booleano Predeterminado: false	`true`
`ua`	Cadena del 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 que persisten en todas las solicitudes posteriores. Si no se envía el valor establecido previamente, este se desactiva. Formato: objeto JSON codificado en URL	Opcional Hasta 5 propiedades 200 caracteres como 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 con fines de cumplimiento de la normativa de privacidad. Debe persistir y transmitirse en cada solicitud posterior si se establece. Valores: `"limit_data_sharing":false` - El usuario ha dado su consentimiento (ha aceptado) `"limit_data_sharing":true` - El usuario ha optado por no participar (rechazado) Consulte Privacidad del usuario para obtener orientación sobre la implementación.	Opcional JSON codificado en URL	`%7B%22limit_data_sharing%22%3Atrue%7D`
`install`	Indicador de instalación que señala la primera sesión tras la instalación del juego. Necesario para las capacidades de seguimiento de reinstalación.	Opcional Booleano	`true`
`utime`	Marca de tiempo del inicio del juego en tiempo UNIX (segundos).	Opcional Entero (marca de tiempo UNIX)	`1483228800`
`umilisec`	Marca de tiempo del inicio del juego en tiempo UNIX (milisegundos).	Opcional Entero (marca de tiempo UNIX ms)	`1483228800000`
`custom_user_id`	Identificador de usuario personalizado de su sistema.	Opcional Cadena	`123456789abcd`

Ejemplos de solicitud

Implementaciones de ejemplo

Sesión básica Solicitud

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 inicio con ID de coincidencia

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 inicio con ID de coincidencia

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 inicio con ID de coincidencia

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();
}

Punto final de notificación de eventos

Notifica los eventos del juego a Singular para su análisis, optimización de campañas y reenvío a socios. Especificación del punto final

Especificación del punto final

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

Finalidad

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

Prácticas recomendadas para eventos:

Eventos estándar: utilice nombres de eventos estándar únicos para la asignación automática de socios
Informes en tiempo real: envíe los 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 obligatorios

Parámetro	Descripción	Restricciones	Ejemplo
`a`	Clave SDK singular para la autenticación de la API. Ubicación: Panel de control → Herramientas para desarrolladores → Integración del SDK → Claves del SDK	Requerido 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 único de su juego. Debe coincidir con el valor utilizado en las notificaciones de sesión y el ID de producto del SDK web.	Obligatorio Se recomienda la notación DNS inversa Distinción entre mayúsculas y minúsculas	`com.singular.game`
`sdid`	Identificador de dispositivo singular que identifica la instalación única del juego. 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 un hito dentro del juego. Recomendado: Utilice nombres de eventos estándar de Singular para la integración automática de socios.	Obligatorio Cadena 32 caracteres ASCII como 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 Se admiten valores personalizados	`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 Se admiten valores personalizados	`steam`
`ip`	Dirección IP del dispositivo en el momento del evento.	Obligatorio Formato IPv4 o IPv6 No es necesario si se trata de un `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: Utilice nombres de atributos estándar singulares para garantizar la 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. Se puede omitir si se proporciona un nombre de evento `__iap__` o un `amt` distinto de cero.	Requerido para eventos de ingresos Booleano	`true`
`amt`	Importe en moneda del evento de ingresos. Se utiliza con el parámetro « `cur` ».	Requerido para eventos de ingresos Número decimal	`2.51`
`cur`	Código de moneda de tres letras ISO-4217 para el evento de ingresos. Úselo con el parámetro « `amt` ». Referencia: Códigos de moneda ISO-4217	Requerido para 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 la compilación del juego.	Opcional Cadena	`1.1.5.581823a`
`use_ip`	Extrae la dirección IP del encabezado de la solicitud HTTP.	Opcional Booleano Predeterminado: falso	`true`
`ua`	Cadena del 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. Si se establece, debe persistir en todas las solicitudes posteriores.	Opcional Hasta 5 propiedades 200 caracteres como 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 (marca de tiempo UNIX)	`1483228800`
`umilisec`	Marca de tiempo del evento en tiempo UNIX (milisegundos).	Opcional Entero (marca de tiempo UNIX ms)	`1483228800000`
`custom_user_id`	Identificador de usuario personalizado de su sistema.	Opcional Cadena	`123456789abcd`

Ejemplos de solicitud

Implementaciones de ejemplo

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 si se ha producido un éxito o un 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 si ha habido éxito (ok) o fallo (error).

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

Recursos adicionales

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

PC y consola: referencia de puntos finales de API

Referencia de puntos finales de API para PC y consola

Punto final de notificación de sesión

Especificaciones del punto final

Finalidad

Parámetros de sesión

Parámetros obligatorios

Parámetros opcionales

Ejemplos de solicitud

Implementaciones de ejemplo

Sesión básica Solicitud

Primer inicio con ID de coincidencia

Solicitud de sesión básica

Primer inicio con ID de coincidencia

Solicitud de sesión básica

Primer inicio con ID de coincidencia

Punto final de notificación de eventos

Especificación del punto final

Finalidad

Parámetros de eventos

Parámetros obligatorios

Parámetros opcionales

Ejemplos de solicitud

Implementaciones de ejemplo

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