Dokumentacja Steamworks
Powiadomienia gry

Wprowadzenie

System powiadomień w grze Steam służy do wysyłania powiadomień offline do użytkowników gier, którzy obsługują asynchroniczny tryb gry wieloosobowej, taki jak szachy.

Celem API jest powiadamianie użytkowników o konieczności podjęcia działań w trwającej sesji gry. Na przykład w szachach, status gry jest aktualizowany po każdym ruchu danego gracza. Steam wyśle powiadomienie do gracza, aby powiadomić go, że gra oczekuje jego ruchu.

Zadania gry

Typowa gra offline będzie zarządzać sesją gry, aktualizując status każdego użytkownika i wysyłając powiadomienie do użytkownika tak, aby wiedział, że musi włączyć grę aby wykonać ruch. Po włączeniu i wykonaniu ruchu, gra ponownie zaktualizuje sesję dla wszystkich graczy w danej sesji gry.

Zadania Steam

Steam wyśle powiadomienie do użytkowników danej sesji gry na podstawie informacji dostarczonych przez grę, a także ustawień wybranych przez użytkownika dla tej gry. Powiadomienie o konieczności wykonania ruchu będzie wyświetlane w kliencie Steam oraz w przeglądarce.

Wymagania

Powiadomienia w grze API są dostarczane przez Web Api i wymagają ważnego klucza wydawcy. Połączenia z metodami Web API powinny pochodzić z serwera dedykowanego, a nie z klienta gry użytkownika — klucza wydawcy nie można wysłać z kodem pochodzącym od klienta gry.

Uwierzytelnianie i konta firm trzecich

Przed wywołaniem API powiadomień w grze musisz zidentyfikować użytkownika Steam, który zalogował się do gry. Można to zrobić na dwa sposoby — klient gry może generować uwierzytelnienie sesji i przekazać je z powrotem do serwera albo internetowa gra może weryfikować użytkownika używając OpenID. Instrukcje jak to zrobić są dostępne tutaj: Łączenie konta firmy trzeciej z kontem Steam. Ważne, abyś nie traktował przekazanych informacji identyfikujących użytkownika w wiadomościach wysyłanych bezpośrednio przez klienta gry, jako zaufanych, ponieważ te wiadomości mogą być modyfikowane.
W przypadku gier korzystających z kont firm trzecich należy postępować zgodnie z powyższymi instrukcjami, ale trzymać w pamięci podręcznej swojego systemu Steam ID użytkownika.

Powiadomienia API w grze

Podsumowanie techniczne

Powiadomienia API w grze są napisane i przedstawiane poprzez Web API i wymagają przekazania czterech parametrów w każdej z metod:
  • appid (id aplikacji dla twojej gry)
  • format (Format wyniku. Zalecamy json jako wartość zwrotną.)
  • input_json (dla metody wymagane kodowanie wszystkich parametrów w json)
  • klucz (wymagane przekazanie z każdym wezwaniem)
Jeśli działanie zakończy się pomyślnie, API zwróci kod statusu HTTP 200 ze szczegółami w tekście (jeśli ma zastosowanie).

Wartości stałe

UserState

Wartość ciągu zdefiniowana jako jedna z poniższych:
  • waiting — użytkownik oczekuje na ruch innych graczy nie blokując progresu. Żadne powiadomienia nie będą do niego wysłane, ponieważ oczekuje na ruch.
  • ready — Użytkownik jest gotowy; oczekiwanie na jego ruch. Powiadomienie będzie widoczne dopóki ten status nie zmieni się.
  • done — Gra została zakończona dla użytkownika. Użytkownik zostanie powiadomiony, kiedy gra zostanie zakończona, ale podjęcie żadnej akcji nie jest wymagane.

Struktury danych (JSON)

Struktury danych zaprezentowane są w formcie JSON.

Variable

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

LocalizedText

{ "token": "value", // string that maps to a localization token "variables": [ // Array of "Variable" (above) ] }

UserStatus

{ "steamid": "76561197960265729", // uint64 "state": // One of the "UserState" constants (described above), "title": // A "LocalizedText" object (described above), "message": // A "LocalizedText" object (described above) }

Session

{ "sessionid": "1", // uint64 "title": // A "LocalizedText" object (above), "time_created": "100000", // Unix epoch time (time since Jan 1st, 1970). "time_updated": "200000", // Unix epoch time (time since Jan 1st, 1970). // 64-bit value provided by the developer when the session is created which will be passed to the game when the game is launched. // This allows you to easily tie the session object to your own backend object, it is not used internally by Steam. "context": "31415926", "user_status": [ // Array of "UserStatus" objects (described above) ] }

RequestedSession

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

Wspólne dostępne API.

Zobacz IGameNotificationsService, aby zapoznać się z pełną listą.

Uruchomienie konkretnych sesji gry

Użytkownicy będą w stanie zobaczyć wszystkie aktywne sesje gry na stronie profilu społeczności na Steam. Wraz ze statusem gry znajduje się przycisk uruchomiający grę z określonymi parametrami definiującymi sesję gry. Kiedy gra jest uruchomiona w ten sposób, paramter uruchomienia "_sessionid" zostanie przekazany grze. Możesz otrzymać ten parametr, korzystając z ISteamApps::GetLaunchQueryParam.
na 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 i określić czy sesja id jest obecna i poprawna dla zalogowanego użytkownika i bezpośrednio załadować grę.

Lokalizacja

Lokalizacja jest dostarczana przez dewelopera gry poprzez narzędzie do lokalizacji, które jest częścią konfiguracji aplikacji. Deweloper odpowiada za zapewnienie, że wszystkie ciągi tłumaczenia we wszystkich językach są wprowadzane za pomocą tego narzędzia. Wszystkie nieprzetłumaczone na język gracza ciągi będą wyświetlane w języku angielskim.
System powiadomień w grze obsługuje lokalizację następujących właściwości:

Każdy localized text jest złożony z dwóch komponentów:

Token to klucz zaczynający się od symbolu „#”, reprezentujący ciąg, który został zlokalizowany w innych językach poprzez narzędzie do lokalizowania w sekcji ustawień aplikacji. Każdy token może zawierać kilka instancji zmiennej, która w trakcie działania programu, w zależności od kontekstu gry, zostanie zastąpiona, gdy tekst zostanie wygenerowany. Na przykład:
#InvitationText = "{{user}} has invited you to play a game of Chess."

W powyższym przykładzie tłumaczenie #InvitationText zawiera pojedyńczą zmienną — „użytkownik”. Kiedy chcesz wyświetlać tę wiadomość użytkownikowi, którego „SteamUserName” zaprasza do gry, należy zaktualizować LocalizationText w następujący sposób:
"message": { "token": "#InvitationText", "variables": [ { "key": "user", "value": "Michael" } ]

Kiedy gracz zobaczy swój status, zobaczy również wiadomość (w swoim własnym języku): "Michael has invited you to play a game of Chess."
Tokeny są ładowane w sekcji Async Localization w zakładce „Społeczność” na stronie ustawień aplikacji.
Każdy z języków można pobrać osobno w formacie pliku.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ć dane 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" } } }