Введение
Система игровых уведомлений Steam предназначена для доставки офлайновых уведомлений пользователям игр, которые поддерживают асинхронный многопользовательский режим, таких как шахматы.
API игровых уведомлений предназначен для уведомления пользователей о том, что от них требуется предпринять то или иное действие в продолжающейся игровой сессии. В примере с шахматами состояние игровой сессии обновляется после каждого хода игроков. Получив информацию о состоянии игровой сессии после хода, Steam отправит уведомление пользователю в том случае, когда игра ожидает его хода.
Функциональные обязанности игры
В типичной офлайновой игре создаётся игровая сессия, в рамках которой статус каждого игрока имеет свое состояние, при обновлении которого пользователям отправляется уведомление о том, что им нужно выполнить игровые действия. После того, как пользователь запустит игру и выполнит свои действия, игра должна снова обновить игровую сессию с учётом новых состояний игроков в данной игровой сессии.
Функциональные обязанности Steam
Steam отправит уведомление пользователям игровой сессии исходя из информации о состояниях, предоставленных игрой, а также настроек, которые пользователь установил для этой игры. В клиенте Steam или в веб-браузере будет показано уведомление о том, что пользователю необходимо предпринять действие в игре.
Требования
API уведомлений реализован с помощью методов веб-API и требует наличия действительного ключа издателя. Вызовы методов веб-API должны исходить с выделенного сервера, а не с игрового клиента на компьютере пользователя — ключ издателя нельзя отправлять с кодом, исходящим с игрового клиента.
Аутентификация и сторонние аккаунты
Прежде чем вызывать API игровых уведомлений, вам потребуется идентифицировать пользователя Steam, вошедшего в игру. Это можно сделать двумя способами: игровой клиент на компьютере пользователя может сгенерировать билет сессии аутентификации и передать его на ваш сервер, либо браузерная игра может верифицировать пользователя, используя OpenID. Инструкции, как это сделать, приведены в разделе
Привязка сторонних аккаунтов к аккаунтам Steam. Важно, чтобы вы не передавали идентифицирующую пользователя информацию в сообщениях, напрямую отправляемых игровым клиентом на ваш игровой сервер, поскольку эти сообщения могут быть подделаны.
Для игр, которые используют сторонние аккаунты, используйте приведенные выше инструкции, но кэшируйте SteamID пользователя в системе.
API игровых уведомлений
Технический обзор
API игровых уведомлений написан и предоставляется через веб-API и требует, чтобы в каждом методе были переданы 4 параметра:
- appid (the application id for your game)
- 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. Вместе со статусом игры пользователю будет показана кнопка, при нажатии на которую Steam запустит игру с конкретными параметрами, определяющими игровую сессию. Когда игра запущена таким образом, ей предоставляется параметр запуска "_sessionid". Вы можете получить его, используя
ISteamApps::GetLaunchQueryParam.
К примеру, так:
const char *pchSessionID = ISteamApps()->GetLaunchQueryParam("_sessionid");
Приложение, которое подобным образом поддерживает загрузку игры напрямую, должно при запуске вызывать этот интерфейс, определять, на месте ли _sessionid, является ли он действительным для вошедшего в игру пользователя, а затем напрямую загрузить игру.
Локализация
Файлы локализации предоставляются разработчиком приложения при помощи инструмента локализации, который является частью интерфейса настройки приложения. Разработчик несёт ответственность за то, чтобы все строки перевода на всех языках были введены при помощи этого инструмента. Любые не переведенные на язык игрока строки будут отображены на английском языке.
Система игровых уведомлений поддерживает локализацию для следующих свойств:
Каждый
LocalizedText состоит из двух компонентов:
Token — это ключ, который начинается с символа "#", и представляет собой строку, которая локализована для разных языков с помощью инструмента локализации в разделе настроек приложения. Каждый token может содержать несколько вхождений variable, которые во время выполнения программы в зависимости от контекста игры будут заменяться тогда, когда должен быть сгенерирован текст. Для примера:
#InvitationText = "{{user}} пригласил вас сыграть в шахматы."В этом примере русский перевод #InvitationText содержит единственную переменную variable, которая называется user. Когда приложение должно будет показать это сообщение пользователю, когда "SteamUserName" приглашает его в игру, объект LocalizationText должен быть обновлён с использованием следующих свойств:
"message":
{
"token": "#InvitationText",
"variables":
[
{ "key": "user", "value": "Michael" }
]
}
При просмотре игроком своего статуса он увидит это сообщение (на своем языке): "Михаил пригласил вас сыграть в шахматы."
Строки локализации загружаются в секции асинхронных уведомлений во вкладке «Сообщество» на странице настроек вашего приложения.
Каждый из языков можно загрузить по отдельности в формате .vdf-файла таким образом:
"lang"
{
"Language" "english"
"Tokens"
{
"TheNameOfTheToken" "The localized text associated with the token"
"TheNameOfAnotherToken" "The localized text associated with the second token"
}
}
Также токены локализации можно загрузить в одном файле таким образом:
"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"
}
}
}
