개요
Steam 게임 알림은 체스와 같은 비동기 멀티플레이어 게임의 사용자에게 오프라인 알림을 전달하는 시스템입니다.
이 API의 목적은 해당 게임 세션의 진행을 위해 특정 동작이 필요하다는 점을 사용자에게 알리는 것입니다. 체스를 예로 들면, 각 플레이어가 자신의 말을 옮겨야 게임 세션이 업데이트됩니다. Steam은 게임 세션의 상태에 따라 사용자의 차례가 돌아오면 사용자에게 알림을 보냅니다.
게임의 책임
일반적인 오프라인 게임의 관리 방식은 각 사용자의 상태를 업데이트하고 그에 따라 사용자에게 알림을 보내, 게임을 실행하여 특정 행동을 취해야 한다는 사실을 알리는 것입니다. 게임을 실행하여 게임 내에서 동작을 수행하면 게임은 세션을 다시 업데이트하여 세션의 모든 플레이어 상태를 최신으로 업데이트합니다.
Steam 담당 관리 부분
Steam은 게임에서 제공하는 사용자의 상태와 해당 사용자의 개인 설정에 따라 사용자들에게 알림을 보냅니다. 게임 내에서 어떤 동작이 요구되면, 사용자의 Steam 클라이언트 및 웹 브라우저에 알림이 표시됩니다.
요구 조건
게임 알림 API는 웹 API 메서드를 통해 제공되며 유효한 게시자 키가 필요합니다. 웹 API 메서드 호출은 반드시 게임 클라이언트와 분리된 별도의 호스트 서버에서 발생해야 합니다. 게시자 키는 게임 클라이언트 코드와 같이 발송해서는 안 됩니다.
인증 및 제3자 계정
게임 알림 API를 호출하려면 먼저 귀사의 게임에 접속한 Steam 사용자의 신원을 확인해야 합니다. 이는 두 가지 방법으로 진행할 수 있습니다. 클라이언트 게임의 경우 인증 세션 티켓을 생성하여 서버로 전송하고, 웹 기반 게임의 경우 OpenID를 사용하여 검색 인증을 진행할 수 있습니다. 자세한 방법은
타사 계정과 Steam 계정 연동 페이지를 확인하세요. 게임 클라이언트에서 게임 서버로 직접 전송되는 신원 메시지는 부정적인 수단으로 변질될 수 있기 때문에 신뢰할 수 없습니다.
제3자 계정을 사용하는 게임의 경우 위와 같은 방식으로 처리하되 귀사의 시스템에 사용자의 Steam ID를 캐시로 저장하세요.
게임 알림 API
기술 개요
게임 알림 API는 웹 API를 통해 작성 및 공개하며 각 메서드에서 4개의 매개변수를 전달해야 합니다.
- appid(게임의 애플리케이션 id)
- format(결과의 형식. 반환값은 json을 권장합니다)
- input_json(메서드에 요구되는 모든 매개변수의 json 인코딩)
- key(호출과 함께 항상 전달해야 하는 귀사의 게시자 키)
성공 시 API는 HTTP 상태 코드 200을 반환하며, 자세한 내용은 메시지 본문에서 확인할 수 있습니다(해당하는 경우).
상수 값
사용자 상태
다음 중 하나의 문자열 값:
- waiting - 사용자가 다른 플레이어를 기다리고 있으며 어떤 동작도 방해하고 있지 않습니다. 사용자가 어떤 일이 발생하기를 기다리고 있으므로 사용자에게 알림이 발송되지 않습니다.
- ready - 사용자가 준비된 상태이며, 게임 세션이 사용자의 응답을 기다리고 있습니다. 상태가 해결될 때까지 사용자에게 알림이 발송됩니다.
- done - 사용자가 게임을 완료하였습니다. 사용자에게 게임이 끝났다는 알림이 발송되나 어떠한 동작을 요구하지는 않습니다.
데이터 구조(JSON)
모든 데이터 구조는 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
}
사용 가능한 API
전체 목록은
IGameNotificationsService를 참고하세요.
특정 게임 세션 실행
사용자는 Steam 커뮤니티의 프로필 페이지에서 현재 활성화된 모든 게임 세션을 확인할 수 있습니다. 게임 상태와 함께, 게임 세션을 정의하는 실행 매개변수로 Steam의 게임 실행을 지시하는 버튼이 있습니다. 이러한 방법으로 게임을 실행하면 ‘_sessionid’ 라는 실행 매개변수가 게임에 제공되며 이 매개변수는
ISteamApps::GetLaunchQueryParam을 통해 회수할 수 있습니다.
const char *pchSessionID = ISteamApps()->GetLaunchQueryParam("_sessionid");
이렇게 직접 실행 방식을 지원하는 게임은 게임 실행과 동시에 이 인터페이스를 불러와 세션 id 문자열이 존재하며 로그인한 사용자의 유효한 세션 id 문자열인지를 확인한 후 게임을 직접 로드합니다.
현지화
게임 개발자는 애플리케이션 구성에 포함된 현지화 도구를 사용하여 현지화를 진행할 수 있습니다. 현지화 도구에 입력된 모든 문자열이 각 언어로 번역되었는지 여부는 직접 확인해야 합니다. 플레이어의 언어로 번역이 되지 않은 문자열은 자동으로 영어로 표시됩니다.
게임 알림은 다음과 같은 속성의 현지화를 지원합니다.
현지화된 텍스트는 각각 두 가지 요소로 구성되어 있습니다:
토큰은 ‘#’ 기호로 시작되는 키로, 애플리케이션 구성에 포함된 현지화 도구를 사용하여 다른 언어로 번역된 문자열을 나타냅니다.
하나의 토큰은 여러 건의 변수를 포함할 수 있으며 이는 게임의 내용에 따라, 텍스트를 생성해야 하는 런타임에 교체될 수 있습니다. 예:
#InvitationText = "{{user}}님이 체스 게임에 초대하셨습니다."위 예시에는 #InvitationText의 영어 번역에 user라는 하나의 변수가 포함되었습니다. 만약 ‘SteamUserName’이 사용자를 게임에 초대했을 때 그 사용자에게 이 텍스트 메시지를 나타내고 싶다면, LocalizationText 객체를 아래와 같은 속성으로 변경해야 합니다.
"message":
{
"token": "#InvitationText",
"variables":
[
{ "key": "user", "value": "Michael" }
]
}
플레이어가 자신의 상태를 확인하면 (자신의 언어로) ‘Michael님이 체스 게임에 초대하셨습니다’라는 메시지를 보게 됩니다.
현지화 토큰은 앱의 Steamworks 설정 페이지에 있는 커뮤니티 탭의 비동기 현지화 알림 섹션에서 업로드할 수 있습니다.
각 언어는 각각의 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"
}
}
}
