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 trò chơi với hệ thố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 đang chờ 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 nó 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:
Linking third-party accounts to Steam accounts. Điều quan trọng là không được tin 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 cache thông tin Steam ID của 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 sẽ chuyển qua 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.
Biến
{
"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ác "biến" (giá trị biến ở trên)
]
}
UserStatus
{
"steamid": "76561197960265729", // uint64
"state": // Một trong các hằng "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" (nêu trên),
"time_created": "100000", // Thời gian theo mốc Unix (kể từ 1/1/1970).
"time_updated": "200000", // Thời gian theo mốc Unix (kể từ 1/1/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 bắt đầu khởi động trò chơi đó.
// Điều này cho phép bạn có thể gắn object của phiên chơi tới object backend của bạn, nó sẽ không được sử dụng trong nội bộ bởi Steam.
"context": "31415926",
"user_status":
[
// Mảng các 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ợ nội đị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 tham gia một trậ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 người chơi xem trạng thái của bản thân, họ sẽ nhận được thông báo như sau (theo ngôn ngữ họ đã thiết lập): "Michael đã mời bạn chơi Chess."
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.
Mỗi ngôn ngữ có thể tải lên riêng biệt dưới dạng file VDF trông như sau:
"lang"
{
"Language" "vietnamese"
"Tokens"
{
"TênToken" "Đoạn văn bản đã được dịch ra liên quan tới token"
"TênTokenKhác" "Đoạn văn bản đã được 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"
{
"TênToken" "The localized text associated with the token"
"TênTokenKhác" "The localized text associated with the second token"
}
}
"vietnamese"
{
"Tokens"
{
"TênToken" "Đoạn văn bản đã được dịch ra liên quan tới token"
"TênTokenKhác" "Đoạn văn bản đã được dịch ra liên quan tới token thứ hai"
}
}
}
