Огляд
Ігрові сповіщення Steam — це система позамережевого повідомлення користувачів, що дозволяє асинхронні багатокористувацькі ігри, як-от шахи.
Мета цього API полягає в сповіщенні користувачів про необхідність певних дій під час ігрового сеансу. Наприклад, у шахах стан ігрового сеансу оновлюється після ходу кожного гравця. Steam надсилає сповіщення користувачам відповідно до стану ігрового сеансу, щоби повідомити їх про очікування їхнього ходу.
Обов’язки гри
Типова гра не в мережі управляє ігровим сеансом шляхом оновлення стану кожного гравця так, що він отримує сповіщення, коли від нього очікується дія. Після запуску гравцем гри й виконання ним необхідних дій, гра знову оновлює ігровий сеанс з урахуванням актуальних станів усіх гравців сеансу.
Що робить Steam
Steam надсилатиме сповіщення користувачам ігрового сеансу відповідно до інформації, наданої грою, а також налаштувань, які гравець обрав для цієї гри. У клієнті Steam чи веб-оглядачі користувачу буде показано сповіщення, що він має виконати певні дії в грі.
Вимоги
API ігрових сповіщень надається методами веб-API й потребує наявності дійсного ключа видавця. Виклики методів веб-API повинні йти від виділеного сервера, що знаходиться окремо від ігрового клієнта. Ключ видавця не можна надсилати з кодом з ігрового клієнта.
Автентифікація і сторонні акаунти
Для виклику API ігрових сповіщень вам спершу необхідно ідентифікувати користувача Steam, який увійшов у вашу гру. Це можна зробити двома способами: ігровий клієнт може згенерувати квиток сеансу автентифікації й передати його назад на ваш сервер, а веб-гра може перевірити користувача за допомогою OpenID. Інструкції наявні в розділі про
автентифікацію. Важливо, щоби ви не передавали ідентифікацію користувача в повідомлення, що надсилаються безпосередньо з ігрового клієнта до вашого сервера, адже ці повідомлення можна підробити.
Для ігор зі сторонніми акаунтами використовуйте наведені вище інструкції, але кешуйте SteamID користувача у своїй системі.
API ігрових сповіщень
Технічний огляд
API ігрових сповіщень написаний і надається через веб-API та вимагає передачі 4 параметрів у кожному методі:
- appid (ідентифікатор застосунку для вашої гри)
- format (формат результату; рекомендуємо використовувати json)
- input_json (для методу необхідне кодування всіх параметрів у json)
- key (ключ видавця необхідно передавати з кожним викликом)
API поверне 200-й код стану HTTP у разі успіху, з подробицями в тілі повідомлення (якщо такі будуть).
Постійні значення
UserState
Текстове значення, визначене як одне з наступного:
- waiting — користувач очікує інших гравців і не блокує жодних дій. Він не бачитиме жодних сповіщень, оскільки це він очікує дій інших.
- ready — користувач готовий. Ігровий сеанс очікує на відповідь користувача. Користувач бачитиме сповіщення, доки цей стан не зміниться.
- done — гра для цього користувача завершена. Користувач отримає сповіщення, що гра завершена, але від нього не очікується жодних дій.
Структури даних (JSON)
Усі структури даних представляються у форматі JSON.
Variable
{
"key": "key_name", // текстовий рядок
"value": "value_of_key" // текстовий рядок
}
LocalizedText
{
"token": "value", // рядок, що посилається на токен локалізації
"variables":
[
// Масив «Variable» (вище)
]
}
UserStatus
{
"steamid": "76561197960265729", // uint64
"state": // Одна з постійних «UserState» (описано вище),
"title": // Об’єкт «LocalizedText» (описано вище),
"message": // Об’єкт «LocalizedText» (описано вище)
}
Session
{
"sessionid": "1", // uint64
"title": // Об’єкт «LocalizedText» (вище),
"time_created": "100000", // Unix-час (з 1 січня 1970).
"time_updated": "200000", // Unix-час (з 1 січня 1970).
// 64-бітне значення, надане розробником під час створення сеансу, що передається грі після запуску гри.
// Дозволяє прив’язати об’єкт сесії до об’єкту на вашому сервері, внутрішньо не використовується в Steam.
"context": "31415926",
"user_status":
[
// Масив об’єктів «UserStatus» (описано вище)
]
}
RequestedSession
{
"sessionid": "1", // uint64
"include_all_user_messages": "0" // логічне значення
}
Доступні загальні API
Дивіться
IGameNotificationsService для повного списку.
Запуск окремих ігрових сеансів
Користувачі зможуть бачити всі свої активні ігрові сеанси у своєму профілі спільноти в Steam. Разом зі станом гри показується кнопка, яка запускає гру з конкретними параметрами запуску, що визначають ігровий сеанс. Коли гра запущена таким чином, їй надається параметр запуску "_sessionid". Ви можете отримати його за допомогою
ISteamApps::GetLaunchQueryParam.
Наприклад, так:
const char *pchSessionID = ISteamApps()->GetLaunchQueryParam("_sessionid");
Гра, що підтримує запуск безпосередньо в гру, повинна викликати цей інтерфейс під час запуску, визначати, чи на місці _sessionid, чи є він дійсним для користувача сеансу, і тільки потім почати завантаження гри.
Локалізація
Локалізація надається розробником гри за допомогою інструмента локалізації, який є частиною конфігурації застосунку. Розробник відповідає за вказання перекладу кожного рядка для кожної мови в інструменті локалізації. Неперекладені на мову користувача рядки будуть виводитися англійською.
Ігрові сповіщення підтримують локалізацію для наступних властивостей:
Кожен
LocalizedText складається із двох компонентів:
Токен — це ключ, що починається із символу «#» і представляє локалізований для різних мов рядок за допомогою інструмента локалізації в розділі конфігурації застосунку. Один токен може містити різні змінні, які будуть замінюватися під час виконання програми залежно від контексту в момент генерування тексту. Приклад:
#InvitationText = "{{user}} запрошує вас зіграти в шахи."У цьому прикладі український переклад #InvitationText містить єдину змінну variable, яка називається user. Якщо вам потрібно буде показати це текстове повідомлення користувачу, коли «SteamUserName» запрошує його до гри, об’єкт LocalizationText потрібно оновити з наступними властивостями:
"message":
{
"token": "#InvitationText",
"variables":
[
{ "key": "user", "value": "Michael" }
]
}
Коли гравець переглядатиме свій статус, то побачить це повідомлення (своєю мовою): «Michael запрошує вас зіграти в шахи».
Токени локалізації вивантажуються в розділ асинхронної локалізації вкладки спільноти на сторінці налаштувань Steamworks для вашого застосунку.
Кожну мову можна вивантажити окремо у файлах VDF таким чином:
"lang"
{
"Language" "ukrainian"
"Tokens"
{
"TheNameOfTheToken" "Локалізований текст токена"
"TheNameOfAnotherToken" "Локалізований текст другого токена"
}
}
Також токени для всіх мов можна вивантажити в один файл таким чином:
"lang"
{
"english"
{
"Tokens"
{
"TheNameOfTheToken" "The localized text associated with the token"
"TheNameOfAnotherToken" "The localized text associated with the second token"
}
}
"ukrainian"
{
"Tokens"
{
"TheNameOfTheToken" "Локалізований текст токена"
"TheNameOfAnotherToken" "Локалізований текст другого токена"
}
}
}
