Tổng quan
Hệ thống thông báo trò chơi Steam là hệ thống gửi các thông báo ngoại tuyến tới người dùng cho trò chơi có tính năng chơi nhiều người không đồng bộ, ví dụ như cờ vua.
Mục đích của API này là để thông báo người dùng rằng có hành động cần thực hiện để tiếp tục phiên chơi. Lấy cờ vua làm ví dụ, trạng thái phiên chơi sẽ được cập nhật sau mỗi nước đi của người chơi. Steam tiếp theo sẽ gửi thông báo tới người dùng dựa trên trạng thái phiên chơi để báo khi nào trận đấu đến lượt của họ.
Trách nhiệm của trò chơi
Một trò chơi khi ngắt mạng sẽ quản lý phiên chơi, cập nhật trạng thái của từng người dùng với trạng thái phiên chơi, qua đó gửi thông báo tới người dùng để họ biết mà khởi chạy trò chơi nhằm thực hiện hành động. Sau khi người chơi khởi chạy và thực hiện hành động, trò chơi nên cập nhật phiên chơi lần nữa với trạng thái hiện tại của tất cả người dùng trong phiên.
Steam sẽ quản lý những gì
Steam sẽ quản lý quá trình thông báo người dùng trong phiên chơi dựa trên trạng thái cung cấp bởi trò chơi và thiết lập cụ thể mà người dùng đã đặt cho trò chơi. Thông báo sẽ hiển thị trong phần mềm Steam và trình duyệt web khi nào người dùng cần thực hiện hành động cho trò chơi.
Yêu cầu
API thông báo trò chơi được cung cấp qua các phương thức API Web và yêu cầu một khóa nhà phát hành hợp lệ. Lệnh gọi phương thức API Web phải đến từ một máy chủ tách riêng khỏi phần mềm trò chơi – khóa nhà phát hành không được phép phát hành cùng đoạn code nào của trò chơi.
Xác thực và tài khoản bên thứ ba
Để có thể gọi các API thông báo trò chơi, trước tiên phải thiết lập danh tính người dùng Steam đã đăng nhập vào trò chơi của bạn. Bạn có thể làm theo hai cách: phần mềm trò chơi tạo một ticket xác thực phiên và gửi qua máy chủ của bạn, hoặc một trò chơi dựa trên web có thể xác nhận danh tính người dùng qua OpenID. Đọc hướng dẫn thực hiện tại đây:
Liên kết tài khoản bên thứ ba tới tài khoản Steam. Điều quan trọng là không nên tin tưởng danh tính người dùng gửi trực tiếp từ phần mềm trò chơi tới máy chủ, bởi vì các gói tin nhắn có thể bị giả mạo.
Với trò chơi sử dụng tài khoản bên thứ ba, sử dụng các hướng dẫn nêu trên nhưng lưu vào bộ nhớ tạm SteamID người dùng trong hệ thống của bạn.
API thông báo trò chơi
Tổng quan kỹ thuật
API thông báo trò chơi được viết và đưa ra qua API Web và yêu cầu thông qua 4 tham số cho mỗi phương thức:
- appid (appid trò chơi của bạn)
- format (định dạng kết quả. Chúng tôi khuyên bạn nên đặt json làm giá trị trả về)
- input_json (mã hóa json của tất cả các tham số cần thiết cho một phương thức)
- key (khóa nhà phát hành truyền vào với mỗi lệnh gọi)
API sẽ trả về mã trạng thái HTTP 200 nếu thành công, với chi tiết trong nội dung thông điệp (nếu có).
Giá trị hằng số
UserState
Giá trị string được định dạng dưới đây:
- waiting - Người dùng đang chờ người chơi khác và không chặn bất kỳ hành động nào. Không có thông báo được chuyển tới người dùng vì họ đang chờ điều gì đó xảy ra.
- ready - Người dùng đã sẵn sàng -- phiên chơi đang chờ phản hồi từ người dùng. Thông báo sẽ được chuyển tới người dùng cho tới khi trạng thái được xóa.
- done - Phiên chơi đã hoàn thành cho người dùng này. Người dùng được thông báo khi trận đấu kết thúc, nhưng không cần làm gì thêm.
Cấu trúc dữ liệu (JSON)
Tất cả cấu trúc dữ liệu sẽ được thể hiện qua định dạng JSON.
Variable
{
"key": "key_name", // string
"value": "value_of_key" // string
}
LocalizedText
{
"token": "value", // string liên kết tới token bản địa hóa
"variables":
[
// Mảng của "variables" (ở trên)
]
}
UserStatus
{
"steamid": "76561197960265729", // uint64
"state": // Một trong các hằng số "UserState" (mô tả ở trên),
"title": // Một object "LocalizedText" (mô tả ở trên),
"message": // Một object "LocalizedText" (mô tả ở trên)
}
Session
{
"sessionid": "1", // uint64
"title": // Một object "LocalizedText" (ở trên),
"time_created": "100000", // Định dạng giờ Unix (thời gian kể từ ngày 01/01/1970).
"time_updated": "200000", // Định dạng giờ Unix (thời gian kể từ ngày 01/01/1970).
// Giá trị 64-bit sẽ được cung cấp bởi nhà phát triển khi phiên được tạo và sau đó sẽ chuyển tới trò chơi khi khởi động.
// Điều này cho phép gắn object của phiên chơi tới object backend của bạn, sẽ không được sử dụng trong nội bộ bởi Steam.
"context": "31415926",
"user_status":
[
// Mảng của object "UserStatus" (mô tả ở trên)
]
}
RequestedSession
{
"sessionid": "1", // uint64
"include_all_user_messages": "0" // bool
}
Các API phổ biến có thể dùng
Xem
IGameNotificationsService để biết thêm danh sách đầy đủ.
Khởi động các phiên trò chơi cụ thể
Người dùng sẽ có thể xem tất cả phiên chơi đang hoạt động trên trang hồ sơ cộng đồng của họ trên Steam. Cùng với trạng thái trận đấu, sẽ có nút để hướng dẫn Steam khởi động trò chơi với thông số khởi động nhất định để định nghĩa phiên chơi. Khi trò chơi khởi động theo cách này, một tham số khởi động "_sessionid" sẽ được cung cấp tới trò chơi, bạn có thể nhận tham số này qua
ISteamApps::GetLaunchQueryParam.
Như thế này:
const char *pchSessionID = ISteamApps()->GetLaunchQueryParam("_sessionid");
Trò chơi có hỗ trợ khởi động trực tiếp vào trận đấu theo cách trên nên gọi interface này khi khởi động trò chơi, xác định string ID phiên chơi có tồn tại và hợp lệ cho người dùng đã đăng nhập không, và nạp trực tiếp trò chơi đó.
Bản địa hóa
Nội dung bản địa hóa sẽ được cung cấp bởi nhà phát triển qua công cụ bản địa hóa vốn là một phần của thiết lập ứng dụng. Bạn sẽ chịu trách nhiệm cho thiết lập các bản dịch của mỗi ngôn ngữ, cho mỗi chuỗi văn bản điền vào công cụ bản địa hóa. Bất kì chuỗi nào không dịch qua ngôn ngữ của người chơi sẽ hiển thị bằng tiếng Anh.
Thông báo trò chơi hỗ trợ bản địa hóa cho các thuộc tính sau:
Mỗi
văn bản bản địa hóa bao gồm hai thành phần sau:
Một token là một khóa (key) bắt đầu với ký tự biểu tượng "#", đại diện cho một chuỗi được bản địa hóa trong các ngôn ngữ khác nhau thông qua công cụ bản địa hóa trong thiết lập ứng dụng của bạn. Một token có thể bao gồm nhiều phiên bản các biến có thể bị thay đổi lúc runtime, dựa trên ngữ cảnh của trận đấu khi đoạn văn đó được tạo ra. Ví dụ như kiểu:
#InvitationText = "{{user}} đã mời bạn chơi một ván cờ vua".Trong ví dụ nêu trên, bản dịch tiếng Anh của #InvitationText bao gồm một biến mang tên user. Khi bạn muốn dựng nội dung văn bản tới người dùng khi "SteamUserName" mời họ tham gia trận đấu, bạn sẽ phải cập nhật object LocalizationText với các thuộc tính sau:
"message":
{
"token": "#InvitationText",
"variables":
[
{ "key": "user", "value": "Michael" }
]
}
Khi xem trạng thái của Michael, người chơi sẽ nhận được thông báo như sau (theo ngôn ngữ đã thiết lập): "Michael đã mời bạn chơi một ván cờ vua".
Token bản địa hóa có thể tải lên mục "Bản địa hóa bất đồng bộ" trong thẻ "Cộng đồng" của trang thiết lập Steamworks cho ứng dụng của bạn.
Có thể tải lên từng ngôn ngữ riêng lẻ trong file VDF trông như thế này:
"lang"
{
"Language" "vietnamese"
"Tokens"
{
"TênToken" "Đoạn văn bản đã dịch ra liên quan tới token"
"TênTokenKhác" "Đoạn văn bản đã dịch ra liên quan tới token thứ hai"
}
}
Ngoài ra, token của tất cả ngôn ngữ có thể tải lên theo một file đơn lẻ trông như thế này:
"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"
}
}
}
