Áttekintés
A Steam Játékértesítések egy offline értesítések küldésére szolgáló rendszer, olyan aszinkron többjátékos módú játékokat játszóknak, mint például a sakk.
Ennek az API-nak a célja a felhasználók értesítése arról, hogy teendőjük van egy játékmenet előremozdításához. A sakk példában a játékmenet állapota az egyes játékosok lépése után frissül. A Steam ezután értesítéseket küld a felhasználóknak a játékmenet állapota alapján, hogy értesítse őket, amikor a játék rájuk vár.
A játék teendői
Egy offline játék jellemzően a játékmenetet kezelné, frissítve az egyes felhasználók állapotát olyan állapotokkal, amelyek pedig értesítést küldenek a felhasználónak, hogy tudja, el kell indítania a játékot és tennie kell valamit. Elindításkor és játékműveletek végrehajtásakor a játéktól elvárjuk a játékmenet újabb frissítését a játékmenet összes felhasználójának naprakész állapotával.
Amit a Steam fog kezelni
A Steam fogja kezelni az egy játékmenetben levő felhasználók értesítését a játék által biztosított állapotok, és a felhasználó által a játékhoz választott konkrét beállítások alapján. A felhasználónak értesítés fog megjelenni a Steam kliensben és a webböngészőben, amikor egy játékban cselekvésre van szükség.
Követelmények
A Játékértesítések API web API metódusokon keresztül biztosított, és érvényes kiadói kulcsot igényel. A web API metódushívásoknak a játékklienstől elkülönülő távol üzemeltetett szerverről kell eredniük; a kiadói kulcsot nem szabad kiadni játékkliens kód részeként.
Hitelesítés és külső fiókok
A Játékértesítések API-k meghívásához először meg kell állapítani a játékba bejelentkezett Steam felhasználó személyazonosságát. Ezt kétféleképpen lehet megtenni: egy klienses játék generálhat hitelesítési munkamenetjegyet, és visszaadhatja azt a szerverednek, egy web alapú játék pedig OpenID használatával ellenőrizheti a felhasználót. Útmutatás ennek megtételéhez a
Linking third-party accounts to Steam accounts dokumentációban érhető el. Fontos, hogy ne bízz a felhasználói személyazonosságban a játékklienstől közvetlenül a játékszerverednek küldött üzenetekben, mivel ezek az üzenetek megváltoztathatók.
Külső fiókot használó játékok esetében használd a fenti útmutatást, de gyorsítótárazd a felhasználó SteamID-jét a rendszeredben.
Játékértesítések API
Műszaki áttekintés
A Játékértesítések API web API-kként van megírva és elérhetővé téve, és mindegyik metódus négy paraméter átadását igényli:
- appid (a játékod alkalmazás-azonosítója),
- format (Az eredmény formátuma. Visszatérési értékként JSON-t javaslunk.),
- input_json (az egy metódushoz szükséges összes paraméter JSON kódolással),
- key (a minden hívással átadandó kiadói kulcsod).
Az API siker esetén 200-as HTTP állapotkódot fog visszaadni, részletekkel az üzenet törzsében (ha van ilyen).
Konstans értékek
UserState
Az alábbiakban definiált string értékek egyike:
- waiting – A felhasználó más játékosokra vár, nem blokkol semmilyen műveletet. Nem küldünk értesítést a felhasználónak, mert várja, hogy valami történjen.
- ready – A felhasználó készen áll; a játékmenet válaszra vár a felhasználótól. Értesítést küldünk a felhasználónak, amíg ez az állapot meg nem szűnik.
- done – A játék ennek a felhasználónak befejeződött. Értesítjük a felhasználót, hogy a játék véget ért, de cselekvésre nincs szükség.
Adatstruktúrák (JSON)
Minden adatstruktúra JSON formátumban van ábrázolva.
Variable
{
"key": "kulcsnév", // string
"value": "kulcsérték" // string
}
LocalizedText
{
"token": "érték", // egy lokalizációs tokenre leképeződő string
"variables":
[
// "Variable" (fentebb) tömb
]
}
UserStatus
{
"steamid": "76561197960265729", // uint64
"state": // A "UserState" konstansok egyike (fentebb leírva),
"title": // Egy "LocalizedText" objektum (fentebb leírva),
"message": // Egy "LocalizedText" objektum (fentebb leírva)
}
Session
{
"sessionid": "1", // uint64
"title": // Egy "LocalizedText" objektum (fentebb),
"time_created": "100000", // Unix epoch idő (az 1970. január 1. óta eltelt idő).
"time_updated": "200000", // Unix epoch idő (az 1970. január 1. óta eltelt idő).
// A fejlesztő által a játékmenet kezdetén adott 64 bites érték, ami át lesz adva a játéknak annak elindításakor.
// Ez teszi lehetővé, hogy könnyen a háttéroldali objektumodhoz kösd a munkamenet-objektumot; a Steam maga nem használja.
"context": "31415926",
"user_status":
[
// "UserStatus" objektumok tömbje (fentebb leírva)
]
}
RequestedSession
{
"sessionid": "1", // uint64
"include_all_user_messages": "0" // bool
}
Elérhető általános API-k
A teljes listáért lásd a
IGameNotificationsService-t.
Konkrét játékmenetek indítása
A felhasználók meg tudják nézni az összes aktív játékmenetüket a közösségi profiloldalukon a Steamen. A játékállapot mellett van egy gomb, amely utasítja a Steamet a játék elindítására konkrét indítási paraméterekkel a játékmenet meghatározásához. Amikor egy játékot így indítanak el, egy „_sessionid” indítási paraméter lesz megadva annak. Ezt a paramétert az
iSteamApps::getLaunchQueryParam használatával tudod megkapni.
Ezen a módon:
const char *pchSessionID = ISteamApps()->GetLaunchQueryParam("_sessionid");
Egy olyan játéknak, amely támogatja a közvetlenül egy játékmenetbe indítást ezen a módon, meg kell hívnia ezt az interfészt játékindításkor, megállapítani, hogy jelen van-e a sessionid string, érvényes-e a bejelentkezett felhasználónak, és közvetlenül be kell töltenie a játékot.
Lokalizáció
A lokalizációt a játék fejlesztője biztosítja az alkalmazás konfigurációjának részét képező lokalizációs eszközön keresztül. A te dolgod a lokalizációs eszközbe bevitt minden string mindegyik nyelvű fordításának beállítása. Bármely string, ami nincs lefordítva egy játékos nyelvére, angolul lesz megjelenítve.
A Játékértesítés a következő tulajdonságok lokalizációját támogatja:
Minden egyes
LocalizedText két összetevőből áll:
A token egy olyan kulcs, amely a „#” szimbólummal kezdődik, és egy olyan stringet képvisel, amely az alkalmazáskonfigurációdban levő lokalizációs eszközön keresztül különféle nyelvekre van lokalizálva. Egyetlen token több változópéldányt tartalmazhat, amelyek futásidőben behelyettesíthetők a játékkontextus alapján, amikor a szöveg generálása szükséges. Egy példa erre:
#InvitationText = "{{user}} meghívott téged egy sakkjátszmára."A fenti példában az #InvitationText magyar fordítása egyetlen, „user” nevű változót tartalmaz. Ha meg akarod jeleníteni ezt a szöveges üzenetet egy felhasználónak, amikor „SteamUserName” játékra hívja őt, a következő tulajdonságokkal frissíted a LocalizationText objektumot:
"message":
{
"token": "#InvitationText",
"variables":
[
{ "key": "user", "value": "Michael" }
]
}
Amikor a játékos megnézi az állapotát, ezt az üzenetet fogja látni (a saját nyelvén): „Michael meghívott téged egy sakkjátszmára.”
A lokalizációs tokenek az alkalmazásod Steamworks beállítások oldalának Közösség fülén, az Aszinkron lokalizáció szakaszban tölthetők föl.
Minden egyes nyelv feltölthető külön-külön VDF fájlokban, amelyek így néznek ki:
"lang"
{
"Language" "english"
"Tokens"
{
"ATokenNeve" "The localized text associated with the token"
"EgyMasikTokenNeve" "The localized text associated with the second token"
}
}
Alternatív megoldásként az összes nyelv tokenjei feltölthetők egyetlen fájlban, amely így néz ki:
"lang"
{
"english"
{
"Tokens"
{
"ATokenNeve" "The localized text associated with the token"
"EgyMasikTokenNeve" "The localized text associated with the second token"
}
}
"hungarian"
{
"Tokens"
{
"ATokenNeve" "A tokenhez társított lokalizált szöveg."
"EgyMasikTokenNeve" "A második tokenhez társított lokalizált szöveg."
}
}
}
