Přehled
Systém offline upozornění najde využití ve hrách podporujících asynchronní hru pro více hráčů (např. šachy).
Účelem tohoto API je upozornit uživatele na to, že pro pokračování herní relace je vyžadována jeho akce. Upozornění jsou službou Steam rozesílána na základě stavu herní relace, kdykoli se čeká na akci daného uživatele. Na příkladu šachů by tak byl uživatel upozorněn po každém tahu soupeře.
Povinnosti hry
Běžně by offline hra měla spravovat herní relaci a aktualizovat údaje jednotlivých uživatelů o nové změny, které vyvolají upozornění pro dalšího uživatele, od něhož se očekává spuštění hry a provedení nějaké akce. Až se tak stane, hra opětovně aktualizuje stav herní relace, a tím pádem i údaje všech zúčastněných uživatelů.
Zapojení služby Steam
Služba Steam má na starosti upozorňování uživatelů v herní relaci podle údajů poskytnutých hrou a se započtením specifických nastavení, která může mít uživatel pro hru. Upozornění na vyžadovanou akci se poté uživateli zobrazí v klientu služby Steam a ve webovém prohlížeči (je-li přihlášen).
Požadavky
Herní upozornění jsou řízena přes metody webového API a vyžadují platný vydavatelský klíč. Volání metod musí pocházet z hostovaného serveru, který je oddělený od herního klienta – vydavatelský klíč nesmí být distribuován s kódem hry.
Ověření a účty třetích stran
Před voláním metod API musíte nejprve zjistit totožnost uživatele služby Steam přihlášeného ve Vaší hře. To lze provést dvěma způsoby: hra s vlastním klientem může vygenerovat ověřovací tiket relace a vrátit ho zpět Vašemu serveru, zatímco prohlížečová hra může ověření provést za použití standardu OpenID. Související pokyny naleznete na stránce
Propojení účtu třetí strany s účtem služby Steam. Je však důležité, abyste nedůvěřovali totožnosti ze zpráv odeslaných z herního klienta přímo Vašemu hernímu serveru, jelikož s těmito zprávami může být manipulováno.
Pro hry využívající účty třetích stran se také řiďte pokyny odkázanými výše, ale ve svém systému si ukládejte Steam ID uživatelů.
API pro herní upozornění
Technický přehled
K systému herních upozornění je přistupováno přes metody webového API, přičemž každá z těchto metod vyžaduje čtyři parametry:
- appid (ID Vaší aplikace)
- format (formát výsledku; doporučujeme JSON)
- input_json (soubor formátu JSON s kódováním všech parametrů vyžadovaných metodou)
- key (Váš vydavatelský klíč předávaný s každým voláním)
Pokud je volání úspěšné, API vrátí stavový kód HTTP 200 s podrobnostmi v těle zprávy (jsou-li nějaké dostupné).
Konstantní hodnoty
UserState
Řetězec definovaný jako:
- waiting – Uživatel čeká na dalšího uživatele a neblokuje žádnou akci. Tento uživatel neobdrží žádné upozornění, jelikož čeká, až se něco stane.
- ready – Uživatel je připraven a herní relace čeká na jeho odpověď. Tento uživatel bude dostávat upozornění, dokud se tento stav nezmění.
- done – Hra (resp. tah) je dokončen a uživatel je upozorněn, že má „hotovo“, ale není od něj vyžadována žádná další akce.
Datové struktury (JSON)
Všechny datové struktury jsou reprezentovány ve formátu JSON.
Variable
{
"key": "key_name", // Řetězec.
"value": "value_of_key" // Řetězec.
}
LocalizedText
{
"token": "value", // Řetězec mapovaný na lokalizační token.
"variables":
[
// Pole z „Variable“ (viz výše).
]
}
UserStatus
{
"steamid": "76561197960265729", // uint64.
"state": // Jedna z konstant „UserState“ (viz výše).
"title": // Objekt „LocalizedText“ (viz výše).
"message": // Objekt „LocalizedText“ (viz výše).
}
Session
{
"sessionid": "1", // uint64.
"title": // Objekt „LocalizedText“ (viz výše).
"time_created": "100000", // Unixový čas (čas uplynulý od 1. ledna 1970).
"time_updated": "200000", // Unixový čas (čas uplynulý od 1. ledna 1970).
// 64bitová hodnota poskytnutá vývojářem při vytvoření relace, která bude se spuštěním předána hře.
// Díky tomu můžete objekt relace jednoduše spojit s vlastním objektem backendu. Tento objekt není interně používán službou Steam.
"context": "31415926",
"user_status":
[
// Pole z objektů „UserStatus" (viz výše).
]
}
RequestedSession
{
"sessionid": "1", // uint64.
"include_all_user_messages": "0" // Booleovská hodnota.
}
Časté metody
Kompletní výčet naleznete na stránce
IGameNotificationsService.
Spuštění konkrétní herní relace
Uživatelé mohou vidět všechny své aktivní herní relace na profilu v komunitě služby Steam. Kromě stavu každé této relace je přítomno také tlačítko, které instruuje klienta služby Steam ke spuštění hry se specifickými parametry definujícími danou herní relaci. Když je hra spuštěna tímto způsobem, je hře poskytnut parametr „_sessionid“, který lze získat pomocí funkce
ISteamApps::GetLaunchQueryParam.
Příklad:
const char *pchSessionID = ISteamApps()->GetLaunchQueryParam("_sessionid");
Hry, které podporují takovéto přímé spouštění, by měly před spuštěním zavolat toto rozhraní, určit, jestli je pro přihlášeného uživatele přítomen platný řetězec ID relace, a poté provést přímé spuštění.
Lokalizace
Lokalizaci zajišťuje vývojář za pomoci nástroje, který je součástí konfigurace aplikace. Za lokalizaci každého řetězce zadaného do příslušného nástroje tedy zodpovídá sám vývojář. Veškeré řetězce, které nejsou přeloženy do jazyka daného uživatele, se zobrazí v angličtině.
Herní upozornění podporují lokalizaci následujících objektů:
Každý objekt
LocalizedText se skládá ze dvou částí:
Token je klíč, který začíná symbolem „#“ a reprezentuje řetězec lokalizovaný prostřednictvím příslušného nástroje v konfiguraci aplikace do jiných jazyků. Jeden token může obsahovat více proměnných, které jsou doplněny na základě kontextu hry v okamžik vygenerování. Příklad:
#InvitationText = "{{user}} has invited you to play a game of Chess."V příkladu výše obsahuje anglický překlad tokenu #InvitationText jednu proměnnou nazvanou „user“. Když tedy jiný uživatel („SteamUserName“) pozve uživatele do hry, bude objekt „LocalizedText“ aktualizován o:
"message":
{
"token": "#InvitationText",
"variables":
[
{ "key": "user", "value": "Michael" }
]
}
Když si uživatel zobrazí stav herní relace, uvidí tuto zprávu (ve svém jazyce): „Michael has invited you to play a game of Chess.“ („Michael Vás pozval do hry Šachy.“)
Lokalizační tokeny lze nahrát v „Nastavení v systému Steamworks > Komunita > Lokalizace asynchronních upozornění“.
Každý jazyk je možné nahrát odděleně v souborech formátu VDF, které vypadají následovně:
"lang"
{
"Language" "english"
"Tokens"
{
"Nazev_tokenu" "The localized text associated with the token"
"Nazev_dalsiho_tokenu" "The localized text associated with the second token"
}
}
Případně je možné nahrát tokeny pro všechny jazyky v jednom souboru:
"lang"
{
"english"
{
"Tokens"
{
"Nazev_tokenu" "The localized text associated with the token"
"Nazev_dalsiho_tokenu" "The localized text associated with the second token"
}
}
"czech"
{
"Tokens"
{
"Nazev_tokenu" "Lokalizovaný text spjatý s tímto tokenem"
"Nazev_dalsiho_tokenu" "Lokalizovaný text spjatý s dalším tokenem"
}
}
}
