Referencia de endpoints de API para PC y consola

Referencia completa de API para los endpoints server-to-server de PC y consola, con especificaciones detalladas de parámetros y ejemplos de implementación para el seguimiento de sesiones y el reporte de eventos.

Parámetros S2S compartidos: Los endpoints, la autenticación y los parámetros de solicitud comunes se definen una sola vez en el hub de fundamentos de S2S . Esta referencia cubre únicamente los aspectos específicos de PC y consola.

Función enterprise: La atribución de juegos de PC y consola es una función enterprise. Para obtener más información, lee las preguntas frecuentes sobre atribución de juegos de PC y consola o comunícate con tu Customer Success Manager.

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

Endpoint de notificación de sesión

Reporta los inicios y las sesiones del juego a Singular para la atribución de instalaciones, el seguimiento de re-engagement y las analíticas de retención de usuarios.

Especificación del endpoint

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

Propósito

Usa el endpoint de notificación de sesión para reportar todos los inicios del juego (sesiones iniciales y repetidas) casi en tiempo real. El primer inicio del juego que Singular recibe para una instalación identificada por el Singular Device ID activa el proceso de atribución.

Flujo de atribución:

Primera sesión: Activa la coincidencia de atribución de instalación con los clics de campañas web
Sesiones posteriores: Se registran para las analíticas de actividad, retención y re-engagement de usuarios
Reporte en tiempo real: Envía las notificaciones de sesión lo más cerca posible del inicio real del juego

Parámetros de sesión

Parámetros obligatorios

La autenticación usa el parámetro compartido a (SDK Key). Consulta Autenticación en el hub de fundamentos de S2S.

Parámetro	Detalles
`p`	`string` Obligatorio. Distingue mayúsculas y minúsculas. Plataforma donde el usuario juega. Valores admitidos: `pc` `xbox` `playstation` `nintendo` `metaquest` Ejemplo: `pc`
`i`	`string` Obligatorio. Distingue mayúsculas y minúsculas. Se recomienda la notación DNS inversa. Identificador de juego único para tu juego. Crítico: Debe coincidir exactamente con el Product ID del Web SDK para que funcione la atribución. Usa el mismo valor en todas las plataformas para el mismo juego. Ejemplo: `com.singular.game`
`sdid`	`UUID` Obligatorio. Se recomienda el formato UUID versión 4. Singular Device ID que identifica una instalación de juego única y la actividad del usuario. Generación: Lo crea el juego o el servidor en el primer inicio, y persiste durante toda la vida útil de la instalación del juego. Ejemplo: `49c2d3a6-326e-4ec5-a16b-0a47e34ed953`
`os`	`string` Obligatorio. Se admiten valores personalizados. Sistema operativo o sistema de juego. Valores recomendados 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 Ejemplo: `windows`
`install_source`	`string` Obligatorio. Se admiten valores personalizados. Tienda del juego o método de distribución. Valores recomendados: `steam` `epicgamestore` `microsoftstore` `gog` `humblestore` `xbox` `playstation` `nintendo` `metaquest` `selfdistributed` Se admiten valores personalizados. Ejemplo: `steam`
`ip`	`string` Obligatorio. Formato IPv4 o IPv6. No es obligatorio si `use_ip=true` . Dirección IP del dispositivo en el momento del inicio del juego. Alternativa: Usa `use_ip=true` para extraer la IP del encabezado de la solicitud HTTP en lugar de pasarla explícitamente. Consulta Red y ubicación en el hub de fundamentos de S2S. Ejemplo: `172.58.29.235`

Parámetros opcionales

Las propiedades genéricas del dispositivo ( ve , ua ), los parámetros de red ( use_ip ), la privacidad de datos ( data_sharing_options ) y el multidispositivo ( custom_user_id ) se comparten en todos los endpoints S2S. Consulta Parámetros del dispositivo , Red y ubicación , Privacidad de datos y Multidispositivo en el hub de fundamentos de S2S. Los parámetros a continuación son específicos de PC y consola.

Parámetro	Detalles
`install_ref`	`string` Opcional. Solo en el primer inicio. Información de Google Install Referrer en JSON codificado en URL. Ofrece la atribución más precisa para juegos nativos de PC distribuidos a través de la tienda Google Play Games. Requisitos: Requiere implementar el Play Games PC SDK para pasarlo Debe enviarse únicamente en el primer inicio del juego Consulta la documentación de Google Play sobre el Install Referrer para PC nativo para conocer los detalles de implementación. Ejemplo: `%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`	`string` Opcional. Solo en el primer inicio. Identificador para la coincidencia de atribución determinista entre los clics web y las instalaciones del juego. Requisitos: Debe enviarse únicamente en el primer inicio del juego Debe coincidir con el valor de la implementación del Web SDK Si es PII, debe estar cifrado con SHA-256 Consulta Atribución con Match ID para conocer los detalles de implementación. Ejemplo: `matchid_12345`
`av`	`string` Opcional. Versión de la aplicación o identificador de compilación del juego. Ejemplo: `1.1.5.581823a`
`global_properties`	`JSON` Opcional. JSON codificado en URL. Hasta 5 propiedades, 200 caracteres máximo cada una. Pares clave-valor guardados para el usuario y persistidos en todas las solicitudes posteriores. No enviar un valor previamente establecido lo anula. Ejemplo: `%7B%22key1%22%3A%22value1%22%7D`
`install`	`boolean` Opcional. Indicador de instalación que señala la primera sesión después de instalar el juego. Obligatorio para las capacidades de seguimiento de reinstalaciones. Ejemplo: `true`
`utime`	`integer` Opcional. Timestamp UNIX (segundos). Timestamp del inicio del juego en tiempo UNIX. Ejemplo: `1483228800`
`umilisec`	`integer` Opcional. Timestamp UNIX (milisegundos). Timestamp del inicio del juego en tiempo UNIX. Ejemplo: `1483228800000`

Ejemplos de solicitud

Implementaciones de ejemplo

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 inicio con Match ID

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 Match ID

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 Match ID

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

Endpoint de notificación de eventos

Compatibilidad con Conversion API de partners: Para reenviar estos eventos a los partners de redes publicitarias mediante las integraciones de Conversion API de Singular, incluye los atributos de evento opcionales estándar (datos propios con hash, como eventId y ehash). Consulta Atributos de evento estándar para integraciones de Conversion API.

Reporta los eventos dentro del juego a Singular para analíticas, optimización de campañas y reenvío a partners.

Especificación del endpoint

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

Propósito

Usa el endpoint de notificación de eventos para reportar todos los eventos deseados dentro del juego casi en tiempo real. Los datos de eventos se usan para analíticas, reportes, optimización de partners y medición del rendimiento de campañas.

Mejores prácticas para eventos:

Eventos estándar: Usa los nombres de eventos estándar de Singular para el mapeo automático de partners
Reporte en tiempo real: Envía los eventos lo más cerca posible del momento real de ocurrencia
Eventos de ingresos: Incluye los parámetros de ingresos para el seguimiento de compras y el análisis de ROI

Parámetros de eventos

Parámetros obligatorios

La autenticación usa el parámetro compartido a (SDK Key). Consulta Autenticación en el hub de fundamentos de S2S.

Parámetro	Detalles
`p`	`string` Obligatorio. Distingue mayúsculas y minúsculas. Plataforma donde el usuario juega. Valores admitidos: pc, xbox, playstation, nintendo, metaquest Ejemplo: `pc`
`i`	`string` Obligatorio. Distingue mayúsculas y minúsculas. Se recomienda la notación DNS inversa. Identificador de juego único para tu juego. Debe coincidir con el valor usado en las notificaciones de sesión y con el Product ID del Web SDK. Ejemplo: `com.singular.game`
`sdid`	`UUID` Obligatorio. Singular Device ID que identifica una instalación de juego única. Debe coincidir con el SDID usado en las notificaciones de sesión. Ejemplo: `49c2d3a6-326e-4ec5-a16b-0a47e34ed953`
`n`	`string` Obligatorio. 32 caracteres ASCII máximo. Nombre del evento que identifica una acción o un hito dentro del juego. Recomendado: Usa los nombres de eventos estándar de Singular para la integración automática de partners. Ejemplo: `sng_achievement_unlocked`
`os`	`string` Obligatorio. Se admiten valores personalizados. Sistema operativo o sistema de juego. Debe coincidir con el valor usado en las notificaciones de sesión. Ejemplo: `windows`
`install_source`	`string` Obligatorio. Se admiten valores personalizados. Tienda del juego o método de distribución. Debe coincidir con el valor usado en las notificaciones de sesión. Ejemplo: `steam`
`ip`	`string` Obligatorio. Formato IPv4 o IPv6. No es obligatorio si `use_ip=true` . Dirección IP del dispositivo en el momento del evento. Ejemplo: `172.58.29.235`

Parámetros opcionales

Parámetro	Detalles
`e`	`JSON` Opcional. JSON codificado en URL, 500 caracteres ASCII máximo por atributo. Atributos de evento personalizados que aportan información detallada sobre el evento. Recomendado: Usa los nombres de atributos estándar de Singular para la compatibilidad con partners. Ejemplo: `%7B%22sng_attr_content_id%22%3A5581%7D`
`is_revenue_event`	`boolean` Obligatorio para eventos de ingresos. Marca el evento como evento de ingresos. Se puede omitir si el nombre del evento es `__iap__` o si se proporciona un valor distinto de cero en `amt` . Ejemplo: `true`
`amt`	`number` Obligatorio para eventos de ingresos. Monto de la moneda para el evento de ingresos. Úsalo con el parámetro `cur` . Ejemplo: `2.51`
`cur`	`string` Obligatorio para eventos de ingresos. Código de moneda de tres letras ISO-4217 para el evento de ingresos. Úsalo con el parámetro `amt` . Referencia: Códigos de moneda ISO-4217 Ejemplo: `EUR`
`av`	`string` Opcional. Versión de la aplicación o identificador de compilación del juego. Ejemplo: `1.1.5.581823a`
`global_properties`	`JSON` Opcional. JSON codificado en URL. Hasta 5 propiedades, 200 caracteres máximo cada una. Pares clave-valor guardados para el usuario. Debe persistir en todas las solicitudes posteriores si se establece. Ejemplo: `%7B%22key1%22%3A%22value1%22%7D`
`utime`	`integer` Opcional. Timestamp UNIX (segundos). Timestamp del evento en tiempo UNIX. Ejemplo: `1483228800`
`umilisec`	`integer` Opcional. Timestamp UNIX (milisegundos). Timestamp del evento en tiempo UNIX. Ejemplo: `1483228800000`

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

Manejo de respuestas

Ambos endpoints devuelven respuestas JSON consistentes 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. Valida siempre el campo status del cuerpo de la respuesta para determinar el éxito ( ok ) o el fallo ( error ).

Para consultar la documentación completa de códigos de respuesta y las estrategias de manejo de errores, consulta Códigos de respuesta S2S y manejo de errores .

Recursos adicionales

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