Documentación de Steamworks
Notificaciones del juego

Descripción general

El sistema de notificaciones del juego de Steam sirve para enviar notificaciones en local a los usuarios de juegos con multijugador asíncrono, como el ajedrez.

El propósito de esta API es avisar a los usuarios de que hay que realizar alguna acción para que la sesión de juego progrese. En el ejemplo del ajedrez, el estado de la sesión de juego se actualiza tras el movimiento de cada jugador. Steam envía entonces notificaciones a los usuarios conforme al estado de la sesión de juego para alertarlos de que el juego está esperando sus turnos.

Responsabilidades del juego

Un juego fuera de línea suele gestionar una sesión de juego, actualizando el estado de cada jugador con estados que, a su vez, enviarán una notificación al usuario para que sepan que deben iniciar el juego y realizar una acción. Tras iniciar el juego y realizar acciones dentro del mismo, se espera que el juego actualice la sesión de juego nuevamente con los estados actualizados para todos los usuarios de la sesión.

Lo que Steam gestionará

Steam gestionará la notificación a los usuarios en una sesión de juego conforme a los estados aportados por el juego y los ajustes específicos que el usuario haya seleccionado para el juego. Se mostrará una alerta en el cliente de Steam y en el navegador para el usuario cuando se requiera una acción para un juego.

Requisitos

La API de notificaciones del juego se suministra a través de los métodos de la Web de API y exige tener una clave de editor válida. Las llamadas del método de la Web de API deben originarse desde un servidor hospedado independiente del cliente del juego: la clave del editor no debe incluirse en ninguna parte del código del cliente del juego en la versión comercial.

Autenticación y cuentas de terceros

Para llamar a las API de las notificaciones de juego, primero debe establecerse la identidad del usuario de Steam que ha iniciado sesión. Esto puede hacerse de dos formas: un cliente del juego puede generar un ticket de sesión de autenticación y pasarlo de nuevo al servidor del desarrollador, o bien un juego basado en la red puede verificar al usuario usando OpenID. Las instrucciones están disponibles en Vincular cuentas de terceros a cuentas de Steam. Es importante que no confíes en la identidad del usuario en los mensajes enviados directamente desde el cliente del juego a tu servidor de juegos, ya que estos mensajes pueden manipularse.
Para juegos que utilizan cuentas de terceros, usa las instrucciones proporcionadas anteriormente, pero almacena en caché el id. de Steam del usuario en tu sistema.

API de notificaciones del juego

Resumen técnico

La API de notificaciones del juego se escribe y se expone a través de la Web de API y requiere que se pasen cuatro parámetros en cada método:
  • appid (el id. de aplicación de tu juego)
  • format (el formato del resultado; se recomienda JSON para el valor devuelto)
  • input_json (codificación en JSON de todos los parámetros requeridos para un método)
  • key (tu clave de editor para pasar con cada llamada)
La API devolverá un código de estado HTTP de 200 si no hay errores, con información en el cuerpo del mensaje (si fuese aplicable).

Valores constantes

UserState

Un valor de cadena definido como alguno de los abajo indicados:
  • waiting: el usuario está esperando a otros jugadores y no está bloqueando ninguna acción. No se enviará ninguna notificación al usuario porque está esperando a que algo suceda.
  • ready: el usuario está listo: la sesión del juego está esperando una respuesta del usuario. Se enviará una notificación al usuario hasta que cambie su estado.
  • done: se completó el juego para este usuario. Se notificará al usuario que el juego ha terminado, pero no es necesaria ninguna acción.

Estructuras de datos (JSON)

Todas las estructuras de datos se representan en formato JSON.

Variable

{ "key": "key_name", // string "value": "value_of_key" // string }

LocalizedText

{ "token": "value", // conecta los mapas al token de localización "variables": [ // Vector de "Variables" (arriba) ] }

UserStatus

{ "steamid": "76561197960265729", // uint64 "state": // Uno de las constantes "UserState" (descritas arriba), "title": // Un objeto "LocalizedText" (descrito arriba), "message": // Un objeto "LocalizedText" (descrito arriba) }

Session

{ "sessionid": "1", // uint64 "title": // Un objeto "LocalizedText" (anterior), "time_created": "100000", // Tiempo Unix (desde el 1 de enero de 1970). "time_updated": "200000", // Tiempo Unix (desde el 1 de enero de 1970). // Valor de 64 bits proporcionado por el desarrollador cuando la sesión fue creada, que irá al juego cuando este se inicie. // Esto permite vincular fácilmente el objeto de sesión a su propio objeto backend; no es utilizado internamente por Steam. "context": "31415926", "user_status": [ // Vector de objeto "UserStatus" (descrito anteriormente) ]0> }

RequestedSession

{ "sessionid": "1", // uint64 "include_all_user_messages": "0" // bool }

API comunes disponibles

Mira IGameNotificationsService para la lista completa.

Inicio de sesiones específicas de juego

Los usuarios podrán ver todas sus sesiones de juego activas en su página de perfil de la comunidad en Steam. Además del estado de juego, hay un botón para ordenar a Steam que inicie la aplicación con parámetros de inicio específicos para definir la sesión de juego. Cuando un juego se lanza de esta manera, un parámetro de lanzamiento de "_sessionid" se proporcionará al juego, puedes recibir este parámetro usando ISteamApps::GetLaunchQueryParam.
Al igual que:
const char *pchSessionID = ISteamApps()->GetLaunchQueryParam("_sessionid");
Un juego compatible con esta forma de inicio directo de partida deberá llamar a esta interfaz al inicio de la aplicación, determinar si la cadena del id. del juego está presente y es válida para el usuario conectado y cargar el juego directamente.

Localización

La localización o traducción la aporta el desarrollador del juego mediante una herramienta a tal fin que es parte de la configuración de la aplicación. El desarrollador es responsable de establecer la traducción a cada idioma para cada cadena introducida en la herramienta de localización. Cualquier cadena que no esté traducida al idioma de un jugador se representará en inglés.
La notificación de juego admite la localización de las siguientes propiedades:

Cada texto localizado tiene dos componentes:

Un token es una clave que comienza con el símbolo "#" y representa una cadena que se localiza en diferentes idiomas a través de la herramienta de localización en la configuración de tu aplicación. Un único token puede contener instancias múltiples de variables que se pueden sustituir en el tiempo de ejecución conforme al contexto del juego cuando se va a generar el texto. Un ejemplo:
#InvitationText = "{{user}} te ha invitado a jugar una partida de ajedrez".

En el ejemplo de arriba, la traducción para #InvitationText contiene una única variable llamada usuario. Siempre que se quiera representar este mensaje de texto para un usuario cuando "SteamUserName" lo invita a un juego, habrá de actualizarse el objeto "LocalizationText" con las siguientes propiedades:
"message": { "token": "#InvitationText", "variables": [ { "key": "user", "value": "Michael" } ] }

Cuando el jugador vea su estado, verá este mensaje (en su idioma local): "Michael te ha invitado a jugar una partida de ajedrez".
Los tokens de localización se pueden cargar en la sección de localización asincrónica de la pestaña Comunidad en la página de configuración de Steamworks para su aplicación.
Cada idioma se puede cargar individualmente en archivos VDF que se parecen a esto:
"lang" { "Language" "english" "Tokens" { "TheNameOfTheToken" "The localized text associated with the token" "TheNameOfAnotherToken" "The localized text associated with the second token" } }

Alternativamente, los tokens para todos los idiomas pueden cargarse en un único archivo similar al siguiente:
"lang" { "english" { "Tokens" { "TheNameOfTheToken" "The localized text associated with the token" "TheNameOfAnotherToken" "The localized text associated with the second token" } } "spanish" { "Tokens" { "TheNameOfTheToken" "El texto localizado asociado con el token" "TheNameOfAnotherToken" "El texto localizado asociado con el segundo token" } } }