Documentazione di Steamworks
Game Notifications

Panoramica

Steam Game Notifications is a system for delivering offline notifications to users for games that provide asynchronous multiplayer gaming, such as Chess.

Lo scopo di questa API è di notificare agli utenti che è necessaria un'azione nella sessione di gioco in corso. Nell'esempio degli scacchi, lo stato della sessione di gioco viene aggiornato dopo ogni mossa del giocatore. Steam invierà quindi notifiche agli utenti in base allo stato della sessione per avvisarli che il gioco è in attesa del loro turno.

Elementi gestiti dal gioco

Un tipico gioco offline è responsabile della gestione della sessione di gioco, che deve essere condotta aggiornando lo stato di ciascun giocatore. Tale stato, a sua volta, attiva l'invio di una notifica all'utente per informarlo sulla necessità di avviare il gioco ed eseguire un'azione. Nel momento in cui l'utente avvia il programma ed esegue le azioni richieste, il gioco aggiorna nuovamente la sessione assieme agli stati di tutti i giocatori partecipanti.

Elementi gestiti da Steam

Steam si occupa della gestione delle notifiche agli utenti nella sessione di gioco, sulla base degli stati forniti dal gioco stesso e a seconda delle impostazioni specifiche selezionate dall'utente. Quando un gioco richiede un'azione, verrà visualizzato un avviso nel client di Steam e nel browser web dell'utente.

Requisiti

L'API delle notifiche di gioco è fornita tramite i metodi API Web e richiede una chiave dell'editore valida. Le chiamate del metodo API Web devono provenire da un server ospitato che sia separato dal client di gioco. È di fondamentale importanza non fornire la chiave dell'editore insieme ai codici di gioco del client.

Authentication and 3rd Party Accounts

Per procedere con la chiamata alle API delle notifiche di gioco, è necessario innanzitutto stabilire l'identità dell'utente di Steam che ha effettuato l'accesso. Puoi verificarla in due modi: se il gioco è basato sul client puoi generare un ticket di sessione per l'autenticazione e passarlo nuovamente al tuo server, mentre se è basato sul web puoi ottenere la verifica dell'identità dell'utente per mezzo di OpenID. Nella sezione Linking third-party accounts to Steam accounts sono disponibili tutte le istruzioni necessarie. È importante non fare affidamento sui messaggi relativi all'identità dell'utente inviati direttamente dal client di gioco al server, in quanto tali messaggi possono essere falsificati.
Per i giochi che utilizzano account di terze parti, utilizza le istruzioni fornite in precedenza ma carica nella cache del tuo sistema lo SteamID dell'utente.

API delle notifiche di gioco

Panoramica tecnica

The Game Notifications API is written and exposed through Web APIs and require 4 parameters passed in each method:
  • appid (the application id for your game)
  • format (the format of the result. We recommend json as the return value)
  • input_json ( json encoding of all the parameters required for a method)
  • key (your publisher key to be passed with every call)
The API will return a HTTP status code of 200 on success, with details in the message body (if applicable).

Constant Values

UserState

A string value defined as one of below:
  • waiting - The user is waiting for other players and not blocking any action. No notification will be sent to the user because he is waiting for something to happen.
  • ready - The user is ready -- the game session is waiting on a response from the user. A notification will be sent to the user until this state has been cleared.
  • done - The game is completed for this user. The user will be notified that the game is over, but no action is required.

Data Structures (JSON)

All data structures are represented in JSON format.

Variable

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

LocalizedText

{ "token": "value", // string that maps to a localization token "variables": [ // Array of "Variable" (above) ] }

UserStatus

{ "steamid": "76561197960265729", // uint64 "state": // One of the "UserState" constants (described above), "title": // A "LocalizedText" object (described above), "message": // A "LocalizedText" object (described above) }

Session

{ "sessionid": "1", // uint64 "title": // A "LocalizedText" object (above), "time_created": "100000", // Unix epoch time (time since Jan 1st, 1970). "time_updated": "200000", // Unix epoch time (time since Jan 1st, 1970). // 64-bit value provided by the developer when the session is created which will be passed to the game when the game is launched. // This allows you to easily tie the session object to your own backend object, it is not used internally by Steam. "context": "31415926", "user_status": [ // Array of "UserStatus" objects (described above) ] }

RequestedSession

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

Common APIs available.

See IGameNotificationsService for the full list.

Launching specific game sessions

Users will be able to view all their active game sessions on their community profile page in Steam. Along with game status, there is a button to instruct steam to launch the game with specific launch parameters to define the game session. When a game is launched this way, a launch parameter of "_sessionid" will be provided to the game, you can receive this parameter using ISteamApps::GetLaunchQueryParam.
Like so:
const char *pchSessionID = ISteamApps()->GetLaunchQueryParam("_sessionid");
A game that supports launching directly into a game in this way should call this interface on game launch, determine if the session id string is present and valid for the signed in user, and load the game directly.

Localization

Localization is provided by the game developer through a localization tool that is part of the application configuration. You are responsible for setting each language translation for every string entered into the localization tool. Any strings that are not translated to a player’s language will be rendered in English.
Game notification supports localization for the following properties:

Each localized text is comprised of two components:

A token is a key that begins with the "#" symbol, and represents a string that is localized in different languages through the localization tool in your application configuration. A single token can contain multiple variable instances that can be replaced at runtime based on the context of the game when the text is to be generated. An example would be:
#InvitationText = "{{user}} has invited you to play a game of Chess."

In the above example, the English translation for #InvitationText contains a single variable called user. When you want to render this text message to a user when "SteamUserName" invites him to a game, you will update LocalizationText object with the following properties:
"message": { "token": "#InvitationText", "variables": [ { "key": "user", "value": "Michael" } ] }

When the player views his status, he will then see this message (in his local language): "Michael has invited you to play a game of Chess."
Localization tokens can be uploaded in the Async Localization section of the Community tab on the Steamworks Settings page for your app.
Each language can be uploaded individually in VDF files that look like this:
"lang" { "Language" "english" "Tokens" { "TheNameOfTheToken" "The localized text associated with the token" "TheNameOfAnotherToken" "The localized text associated with the second token" } }

Alternatively, the tokens for all languages can be uploaded in a single file that looks like this:
"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" } } }