Steamworks-Dokumentation
Spielbenachrichtigungen

Übersicht

Steam-Spielbenachrichtigungen bieten ein System für die Bereitstellung von Offlinebenachrichtigungen für Nutzer von Spielen mit asynchronem Mehrspieler-Gameplay, zum Beispiel Schach.

Diese API dient dazu, Nutzer darüber zu informieren, dass eine Aktion erforderlich ist, damit die Spielsitzung fortgesetzt werden kann. Im Schach-Beispiel wird der Sitzungsstatus nach jedem Zug eines Spielers aktualisiert. Steam sendet basierend auf dem Status der Spielsitzung Benachrichtigungen an die Nutzer, um sie zu informieren, dass das Spiel auf ihren Zug wartet.

Anforderungen an das Spiel

Ein typisches Offlinespiel würde eine Spielsitzung verwalten und den Status jedes Nutzers in den Sitzungsstatus aktualisieren, der wiederum eine Benachrichtigung an den Nutzer sendet, um ihn aufzufordern, das Spiel zu starten und eine Aktion auszuführen. Wenn das Spiel gestartet und eine Aktion ausgeführt wird, soll das Spiel die Spielsitzung erneut auf den aktuellsten Status für alle Nutzer in der Sitzung aktualisieren.

Von Steam verwaltete Aufgaben

Steam verwaltet die Benachrichtigungen an Nutzer in der Sitzung basierend auf dem vom Spiel gemeldeten Status und den speziellen Einstellungen, die der Nutzer für das Spiel ausgewählt hat. Wenn für ein Spiel eine Aktion erforderlich ist, wird dem Nutzer im Steam-Client und im Webbrowser ein Hinweis angezeigt.

Anforderungen

Die API für Spielbenachrichtigungen wird über Web-API-Methoden bereitgestellt und erfordert einen gültigen Publisher-Schlüssel. Die Aufrufe der Web-API-Methoden müssen von einem gehosteten Server erfolgen, der vom Spielclient getrennt ist. Der Publisher-Schlüssel darf nirgends im Code für den Spiel-Client enthalten sein.

Authentifizierung und Drittanbieteraccounts

Damit Sie die APIs für Spielbenachrichtigungen aufrufen können, müssen Sie zunächst die Identität des bei Ihrem Spiel angemeldeten Steam-Nutzers feststellen. Dies kann auf zwei Arten erfolgen: Ein Clientspiel kann ein Sitzungsticket zur Authentifizierung generieren und an Ihren Server übergeben oder ein webbasiertes Spiel kann den Nutzer über OpenID verifizieren. Anleitungen hierzu finden Sie im Dokumentationsartikel Linking third-party accounts to Steam accounts. Wichtig ist, dass Sie keinesfalls Nutzeridentitäten trauen, die in direkt vom Spielclient an Ihren Spielserver gesendeten Nachrichten enthalten sind, da diese Nachrichten manipuliert werden könnten.
Befolgen Sie bei Spielen mit Drittanbieteraccounts die oben stehenden Anweisungen, aber speichern Sie die Steam-ID des Nutzers in Ihrem System zwischen.

API für Spielbenachrichtigungen

Technische Übersicht

Die API für Spielbenachrichtigungen wird über Web-APIs erstellt und bereitgestellt. In jeder Methode müssen 4 Parameter übergeben werden:
  • appid (die Anwendungs-ID für Ihr Spiel)
  • format (das Format des Ergebnisses. Wir empfehlen json als Rückgabewert.)
  • input_json (json-Encoding aller für eine Methode erforderlichen Parameter)
  • key (Ihr Publisher-Schlüssel, der mit jedem Aufruf übergeben werden soll.)
Bei Erfolg gibt die API den HTTP-Statuscode 200 sowie Details im Nachrichtentext zurück (falls zutreffend).

Konstanten

UserState

Ein String, definiert in einer der folgenden Formen:
  • waiting – Der Nutzer wartet auf andere Spieler und blockiert keinerlei Aktion. An den Nutzer wird keine Nachricht gesendet, da er warten muss, bis etwas passiert.
  • ready – Der Nutzer ist bereit, die Spielsitzung wartet auf eine Reaktion des Nutzers. An den Nutzer wird eine Nachricht gesendet, bis dieser Status wieder aufgehoben ist.
  • done – Das Spiel ist für diesen Nutzer beendet. Der Nutzer wird benachrichtigt, dass das Spiel beendet wurde und keine Aktion erforderlich ist.

Datenstrukturen (JSON)

Alle Datenstrukturen werden im JSON-Format dargestellt.

Variable

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

LocalizedText

{ "token": "value", // String, der zu einem Lokalisierungstoken gehört. "variables": [ // "Variable"-Array (siehe oben) ] }

UserStatus

{ "steamid": "76561197960265729", // uint64 "state": // Eine der oben beschriebenen "UserState"-Konstanten, "title": // Ein "LocalizedText"-Objekt (oben beschrieben), "message": // Ein "LocalizedText"-Objekt (oben beschrieben) }

Session

{ "sessionid": "1", // uint64 "title": // Ein "LocalizedText"-Objekt (oben beschrieben), "time_created": "100000", // Unix-Zeitstempel (Zeit seit dem 1. Januar 1970) "time_updated": "200000", // Unix-Zeitstempel (Zeit seit dem 1. Januar 1970) // 64-Bit-Wert, der vom Entwickler angegeben wird, wenn die Session beginnt, und beim Start des Spiels an dieses übergeben wird. // Dies erlaubt Ihnen, ein Session-Objekt leicht an Ihr eigenes Backend-Objekt zu koppeln; es wird nicht intern von Steam verwendet. "context": "31415926", "user_status": [ // Array mit "UserStatus"-Objekten (oben beschrieben) ] }

RequestedSession

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

Verfügbare allgemeine APIs.

Eine vollständige Liste finden Sie in IGameNotificationsService.

Starten spezifischer Spielsitzungen

Nutzer können in Steam auf der Seite mit ihrem Communityprofil alle ihre aktiven Spielsitzungen anzeigen. Neben dem Spielstatus ist eine Schaltfläche verfügbar, mit der Steam angewiesen werden kann, das Spiel mit bestimmten Parametern zu starten, um die Spielsitzung zu definieren. Wenn ein Spiel auf diese Weise gestartet wird, wird ein Startparameter "_sessionid" an das Spiel übergeben. Sie können diesen Parameter mit ISteamApps::GetLaunchQueryParam empfangen.
Beispielsweise so:
const char *pchSessionID = ISteamApps()->GetLaunchQueryParam("_sessionid");
Ein Spiel, das einen Start direkt mitten in das Spiel auf diese Weise unterstützt, sollte diese Schnittstelle beim Spielstart aufrufen, ermitteln, ob die Zeichenfolge mit der Sitzungs-ID vorhanden und für den angemeldeten Nutzer gültig ist, und das Spiel dann direkt laden.

Lokalisierung

Lokalisierung wird vom Spielentwickler über ein Lokalisierungswerkzeug bereitgestellt, das zur Anwendungskonfiguration gehört. Sie sind dafür verantwortlich, für jede in das Lokalisierungswerkzeug eingegebene Zeichenfolge die Übersetzung anzugeben. Alle Strings, die nicht in die Sprache des Spielers übersetzt wurden, werden auf Englisch ausgegeben.
In Spielbenachrichtigungen wird die Lokalisierung folgender Eigenschaften unterstützt:

Jeder lokalisierte Text setzt sich aus zwei Komponenten zusammen:

Ein Token ist ein Schlüssel, der mit dem #-Symbol beginnt, und steht für eine Zeichenfolge, die über das Lokalisierungswerkzeug in Ihrer Anwendungskonfiguration in verschiedene Sprachen lokalisiert wurde. Ein einzelnes Token kann mehrere Variableninstanzen enthalten, die zur Laufzeit abhängig vom Kontext im Spiel ersetzt werden können, wenn Text generiert werden muss. Hier ist ein Beispiel:
#InvitationText = "{{user}} has invited you to play a game of Chess."

Im Beispiel oben enthält die englische Übersetzung für #InvitationText eine Variable namens "user". Wenn Sie diese Textnachricht einem Nutzer anzeigen möchten, wenn "SteamUserName" ihn zu einem Spiel einlädt, aktualisieren Sie das LocalizationText-Objekt mit folgenden Eigenschaften:
"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" } }

Alternativ können Sie die Token für alle Sprachen in einer einzigen Datei hochladen, die wie folgt aussieht:
"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" } } }