Ü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
Drittanbieteraccounts mit Steam-Accounts verknüpfen. 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":
[
// „Variablen“-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 ein Beispiel:
#InvitationText = "{{user}} hat Sie zu einer Partie Schach eingeladen."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" }
]
}
Wenn der Spieler seinen Status anzeigt, sieht er diese Nachricht (in seiner lokalen Sprache): „Michael hat Sie zu einer Partie Schach eingeladen.“
Lokalisierungstoken können Sie auf der Steamworks-Seite mit den Einstellungen für Ihre Anwendung im Communitytab im Abschnitt „Asynchrone Benachrichtigungen“ hochladen.
Sie können jede Sprache in Form einer VDF-Datei hochladen, die wie folgt aussieht:
"lang"
{
"Language" "german"
"Tokens"
{
"TheNameOfTheToken" "Der mit dem Token verbundene lokalisierte Text"
"TheNameOfAnotherToken" "Der mit dem zweiten Token verbundene lokalisierte Text"
}
}
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"
}
}
}
