Unaffiliated

Home Documentation & Help
Steamworks Documentation
Game Notifications

Overview

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

The purpose of this API is to notify users that there is action required for a game session to progress. In the Chess example, game session state is updated after each player's move. Steam will then send notifications to users based on the state of the game session to alert them when the game is waiting on their turn.

Responsibilities of the Game

A typical offline game would manage a game session, updating the status of each user with states that will, in turn, send a notification to the user so that they will know that they need to launch the game and perform an action. Upon launching and performing game actions, the game is expected to update the game session again with the up-to-date states for all users in the session.

What Steam will manage

Steam will manage notifying users in a game session based on the states provided by the game and the specific settings that the user has selected for the game. An alert will be displayed in the Steam client and the web browser for the user when action is required for a game.

Requirements

The Game Notifications API is provided through Web API methods and requires a valid publisher key. The Web API method calls must originate from a hosted server that is separated from the game client – the publisher key must not be shipped with any game client code.

Authentication and 3rd Party Accounts

In order to call the Game Notifications APIs, you must first establish the identity of the Steam user logged into your game. You can do this one of two ways: a client game can generate an authentication session ticket and pass it back to your server, or a web based game can verify the user by using OpenID. Instructions to do so are available in Linking third-party accounts to Steam accounts. It is important that you do not trust user identity in messages sent directly from the game client to your game server, as these messages can be tampered with.
For games that use 3rd party accounts, use the instructions provided above but cache the user’s Steam ID in your system.

Game Notifications API

Technical Overview

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 Notifications 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" } } }