Wprowadzenie
System powiadomień w grze Steam służy do wysyłania powiadomień offline do użytkowników gier, które obsługują asynchroniczny tryb wieloosobowy w grze, np. takiej jak szachy.
Celem tego API jest powiadamianie użytkowników, że do uczynienia postępów w sesji gry wymagane jest działanie. Przykładowo w szachach status sesji gry jest aktualizowany po ruchu każdego gracza. Steam następnie wyśle powiadomienia do użytkowników w oparciu o stan sesji gry, by dać im znać, że gra oczekuje ich ruchu.
Oczekiwania od gry
Typowa gra offline miałaby zarządzać sesją gry, aktualizując status każdego użytkownika stanami, które z kolei mają wysyłać powiadomienia do użytkowników tak, aby wiedzieli, że muszą uruchomić grę i wykonać ruch. Gdy gracz włączy grę i wykona w niej działania, od gry oczekuje się ponownej aktualizacji sesji gry wraz z aktualnymi stanami dla wszystkich użytkowników należących do sesji.
Czym Steam będzie zarządzał
Steam będzie zarządzał powiadamianiem użytkowników w sesji gry w oparciu o stany dostarczane przez grę i konkretne ustawienia, które użytkownik wybrał dla gry. Powiadomienie o konieczności wykonania działania w grze zostanie wyświetlone w kliencie Steam oraz w przeglądarce internetowej.
Wymagania
API powiadomień w grze jest częścią Web API i wymaga ważnego klucza wydawcy. Wywołania metod Web API muszą pochodzić z hostowanego serwera, który jest oddzielny od klienta gry – klucz wydawcy nie może być przesyłany z wszelkim kodem klienta gry.
Uwierzytelnianie i konta innych firm
Aby wywoływać API powiadomień w grze, musisz najpierw zidentyfikować użytkownika Steam, który zalogował się do twojej gry. Można to zrobić na dwa sposoby — klient gry może wygenerować kupon sesji uwierzytelnienia i przekazać go z powrotem do twojego serwera albo gra sieciowa może weryfikować użytkownika z wykorzystaniem OpenID. Instrukcje na ten temat są dostępne
tutaj. Ważną rzeczą jest, by nie pokładać zaufania w tożsamości użytkownika wysyłanej w wiadomościach bezpośrednio z klienta gry do twojego serwera gry – istnieje możliwość manipulacji nimi.
W przypadku gier korzystających z kont innych firm skorzystaj z powyższych instrukcji, ale przechowuj ID Steam użytkownika w pamięci podręcznej swojego systemu.
API powiadomień w grze
Wprowadzenie techniczne
API powiadomień w grze jest częścią Web API i wymaga przekazania czterech parametrów w każdej metodzie:
- appid (ID aplikacji dla twojej gry)
- format (format rezultatu – zalecamy użycie JSON-a jako wartości zwrotnej)
- input_json (wszystkie parametry wymagane dla metody zakodowane w JSON)
- key (twój klucz wydawcy, który jest przekazywany z każdym wywołaniem).
Pomyślne wywołanie sprawi, że API zwróci kod statusu HTTP 200 ze szczegółami w tekście (tam, gdzie ma to zastosowanie).
Wartości stałe
UserState
Wartość w postaci łańcuchu znaków zdefiniowana jako jedna z poniższych:
- waiting – użytkownik oczekuje na innych graczy i nie blokuje żadnego działania. Żadne powiadomienia nie będą do niego wysłane, ponieważ oczekuje on na jakieś działanie.
- ready – użytkownik jest gotowy, a sesja gry oczekuje na odpowiedź z jego strony. Powiadomienie będzie wysyłane do użytkownika, dopóki ten status nie zmieni się.
- done – gra została zakończona dla tego użytkownika. Użytkownik zostanie powiadomiony, kiedy gra zostanie zakończona, ale nie jest wymagane wykonanie żadnego działania.
Struktury danych (JSON)
Struktury danych zaprezentowane są w formacie JSON.
Variable
{
"key": "key_name", // string
"value": "value_of_key" // string
}
LocalizedText
{
"token": "value", // string, który mapuje się do tokenu lokalizacji
"variables":
[
// Tablica obiektów "Variable" (powyżej)
]
}
UserStatus
{
"steamid": "76561197960265729", // uint64
"state": // Jedna ze stałych z "UserState" (opisane powyżej),
"title": // Obiekt "LocalizedText" (opisany powyżej),
"message": // Obiekt "LocalizedText" (opisany powyżej)
}
Session
{
"sessionid": "1", // uint64
"title": // Obiekt "LocalizedText" (powyżej),
"time_created": "100000", // Czas uniksowy (czas od 1 stycznia 1970).
"time_updated": "200000", // Czas uniksowy (czas od 1 stycznia 1970).
// 64-bitowa wartość określana przez producenta, gdy tworzona jest sesja i która będzie przekazywana do gry, gdy zostanie ona uruchomiona.
// Pozwala ci na łatwe powiązanie obiektu sesji ze swoim własnym obiektem back-endowym, który nie jest używany wewnętrznie przez Steam.
"context": "31415926",
"user_status":
[
// Tablica obiektów "UserStatus" (opisany powyżej)
]
}
RequestedSession
{
"sessionid": "1", // uint64
"include_all_user_messages": "0" // bool
}
Dostępne pospolite API
Zobacz
IGameNotificationsService, aby zapoznać się z pełną listą.
Uruchamianie konkretnych sesji gry
Użytkownicy będą w stanie zobaczyć wszystkie aktywne sesje gry na stronie ich profilu w Społeczności Steam. Wraz ze statusem gry istnieje przycisk uruchamiający grę z określonymi parametrami definiującymi sesję gry. Kiedy gra zostaje uruchomiona w ten sposób, parametr uruchomienia "_sessionid" zostanie przekazany grze. Możesz otrzymać ten parametr, korzystając z
ISteamApps::GetLaunchQueryParam.
Przykład:
const char *pchSessionID = ISteamApps()->GetLaunchQueryParam("_sessionid");
Gra, która wspiera uruchamianie bezpośrednio w taki sposób, powinna wywołać interfejs podczas uruchomienia, a następnie określić, czy string ID sesji jest obecny i poprawny dla zalogowanego użytkownika, po czym bezpośrednio wczytać grę.
Lokalizacja
Lokalizacja jest dostarczana przez producenta gry poprzez narzędzie do lokalizacji, które jest częścią konfiguracji aplikacji. Na tobie leży odpowiedzialność konfiguracji tłumaczenia każdego języka dla wszystkich łańcuchów znaków wprowadzonych w narzędziu do lokalizacji. Wszystkie łańcuchy znaków nieprzetłumaczone na język gracza będą wyświetlane w języku angielskim.
System powiadomień w grze obsługuje lokalizację następujących właściwości:
Każdy
zlokalizowany tekst składa się z dwóch komponentów:
Token to klucz zaczynający się od symbolu „#”, reprezentujący łańcuch znaków, który został zlokalizowany w różnych językach poprzez narzędzie do lokalizacji w twojej konfiguracji aplikacji. Każdy token może zawierać wiele instancji zmiennych, które mogą zostać zastąpione podczas działania gry w oparciu o jej kontekst w momencie, gdy tekst ma zostać wygenerowany. Na przykład:
#InvitationText = "{{user}} has invited you to play a game of Chess."W powyższym przykładzie angielskie tłumaczenie tokenu #InvitationText zawiera pojedynczą zmienną — „user”. Kiedy chcesz wyświetlać tę wiadomość użytkownikowi, gdy „SteamUserName” zaprasza go do gry, musisz zaktualizować LocalizationText w następujący sposób:
"message":
{
"token": "#InvitationText",
"variables":
[
{ "key": "user", "value": "Michael" }
]
Kiedy gracz sprawdzi swój status, to zobaczy tę wiadomość (w swoim własnym języku): „Michael has invited you to play a game of Chess.”
Tokeny lokalizacji można przesłać w sekcji „Lokalizacja asynchroniczna” w zakładce „Społeczność” na stronie ustawień Steamworks dla twojej aplikacji.
Każdy z języków można przesłać osobno w formacie VDF, który wygląda w następujący sposób:
"lang"
{
"Language" "english"
"Tokens"
{
"TheNameOfTheToken" "The localized text associated with the token"
"TheNameOfAnotherToken" "The localized text associated with the second token"
}
}
Można również przesłać tokeny dla wszystkich języków w jednym pliku, który wygląda następująco:
"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"
}
}
}
