ภาพรวม
การแจ้งเตือนเกม Steam เป็นระบบที่จะนำส่งการแจ้งเตือนแบบออฟไลน์ให้กับผู้ใช้ สำหรับเกมที่ให้บริการการเล่นเกมผู้เล่นหลายคนแบบอะซิงโครนัส เช่น เกมหมากรุก เป็นต้น
จุดประสงค์ของ API คือเพื่อแจ้งให้ผู้ใช้ทราบว่าผู้ใช้ต้องดำเนินการบางอย่าง เซสชันเกมจึงจะมีความคืบหน้า ในตัวอย่างเกมหมากรุก สถานะเซสชันเกมจะอัปเดตหลังจากที่ผู้เล่นแต่ละคนเดินหมาก จากนั้น Steam จะส่งการแจ้งเตือนไปยังผู้ใช้ตามสถานะของเซสชันเกมนั้น ๆ เพื่อแจ้งให้ผู้ใช้ได้รับทราบว่าเกมกำลังรอรอบการเล่นของผู้ใช้ท่านนั้นอยู่
สิ่งที่ตัวเกมจะต้องดำเนินการ
โดยปกติแล้วในเกมประเภทออฟไลน์ ตัวเกมจะจัดการเซสชันเกม อัปเดตสถานะของผู้ใช้แต่ละคนด้วยสถานะที่จะส่งการแจ้งเตือนไปยังผู้ใช้ เพื่อให้ผู้ใช้เหล่านั้นได้รับทราบว่าตนเองจำเป็นจะต้องเปิดเกมและเริ่มดำเนินการ เมื่อเปิดเกมและดำเนินการตามที่เกมได้แจ้งแล้ว ตัวเกมก็จะอัปเดตเซสชันของเกมอีกครั้งด้วยสถานะล่าสุดให้แก่ผู้เล่นทุกคนที่อยู่ในเซสชันนั้น
สิ่งที่ Steam จะจัดการ
Steam จะจัดการการแจ้งเตือนผู้ใช้ในเซสชันเกมตามสถานะที่ได้รับแจ้งมาจากเกม และการตั้งค่าเฉพาะที่ผู้ใช้ได้เลือกไว้กับเกมนั้น ๆ ทั้งนี้ จะมีการแสดงการแจ้งเตือนในไคลเอนต์ Steam และในเว็บเบราว์เซอร์ให้ผู้ใช้ได้ทราบ หากมีการดำเนินการที่จำเป็นต้องกระทำสำหรับเกมนั้น
สิ่งที่ต้องทำล่วงหน้า
คุณสามารถใช้งาน API การแจ้งเตือนเกมได้ผ่านทางเมธอด Web API และจำเป็นจะต้องใช้คีย์ผู้เผยแพร่ที่ถูกต้อง การเรียกเมธอด Web API จะต้องเริ่มต้นจากเซิร์ฟเวอร์โฮสต์ที่แยกออกจากไคลเอนต์เกม ต้องไม่นำส่งคีย์ผู้เผยแพร่ไปพร้อมกับโค้ดของไคลเอนต์เกมเด็ดขาด
การยืนยันตัวตนและบัญชีภายนอก
ในการเรียก API การแจ้งเตือนเกม คุณจะต้องระบุอัตลักษณ์ของผู้ใช้ Steam ที่ได้เข้าสู่ระบบเกมของคุณเสียก่อน ซึ่งคุณสามารถดำเนินการได้ 2 วิธีด้วยกัน ได้แก่ โดยให้ไคลเอนต์เกมสร้างตั๋วเซสชันการยืนยันตัวตนและส่งตั๋วดังกล่าวกลับไปยังเซิร์ฟเวอร์ของคุณ หรือเกมแบบเล่นบนเว็บสามารถยืนยันผู้ใช้ได้ด้วยการใช้ OpenID คุณสามารถดูคำแนะนำการใช้งานได้ที่
การเชื่อมบัญชีของผู้พัฒนาภายนอกเข้ากับบัญชี Steam อย่างไรก็ตาม ถือเป็นสิ่งสำคัญมากที่คุณไม่ควรจะเชื่อถืออัตลักษณ์ของผู้ใช้จากข้อความที่ไคลเอนต์ของเกมส่งไปยังเซิร์ฟเวอร์เกมของคุณโดยตรง ทั้งนี้ เพราะว่าข้อความเหล่านี้สามารถถูกดัดแปลงแต่งเติมได้
สำหรับเกมที่ใช้งานบัญชีภายนอก กรุณาใช้คำแนะนำที่ได้ระบุไว้ข้างต้น แต่ให้แคชไอดี Steam ของผู้ใช้รายนั้นลงไว้ในระบบของคุณด้วย
API การแจ้งเตือนเกม
ภาพรวมเชิงเทคนิค
API การแจ้งเตือนเกม เขียนขึ้นและเปิดให้ใช้งานผ่านทาง Web API และในแต่ละเมธอดก็จำเป็นจะต้องได้รับพารามิเตอร์ทั้งหมด 4 พารามิเตอร์ด้วยกัน:
- appid (ไอดีแอปพลิเคชันสำหรับเกมของคุณ)
- format (รูปแบบของผลลัพธ์ ทางเราขอแนะนำให้ค่าส่งคืนอยู่ในรูปแบบ json)
- input_json (พารามิเตอร์ทั้งหมดสำหรับเมธอดจำเป็นต้องเข้ารหัสในรูปแบบ json)
- key (คีย์สำหรับผู้จัดจำหน่ายของคุณที่จะส่งไปกับการเรียกทุกครั้ง)
หากสำเร็จ API จะคืนค่ารหัสสถานะ HTTP เป็น 200 พร้อมกับรายละเอียดในเนื้อความของข้อความ (หากเกี่ยวข้อง)
ค่าคงที่
UserState
ค่าสตริงที่จะถูกกำหนดให้มีค่าเป็นค่าใดค่าหนึ่งดังต่อไปนี้:
- 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");
เกมที่ให้การรองรับการเริ่มเปิดเข้าสู่ตัวเกมโดยตรงด้วยวิธีนี้ ควรจะเรียกอินเตอร์เฟสดังกล่าวนี้ตั้งแต่ตอนที่เริ่มเปิดเกม แล้วดูว่ามีสตริงไอดีเซสชันที่มีความถูกต้องให้แก่ผู้ใช้ที่ได้เข้าสู่ระบบหรือไม่ และจากนั้นก็โหลดเกมโดยตรง
การแปลภาษา
ผู้พัฒนาเกมจะเป็นผู้เตรียมการแปลภาษาไว้ให้ผ่านทางเครื่องมือการแปลภาษาซึ่งเป็นส่วนหนึ่งของการกำหนดค่าแอปพลิเคชัน โดยคุณจะต้องรับผิดชอบตั้งค่าการแปลภาษาแต่ละภาษาให้กับสตริงทุกสตริงที่ผ่านเข้ามาในเครื่องมือการแปลภาษาดังกล่าว ซึ่งสตริงใดก็ตามที่ไม่ได้รับการแปลภาษาให้เป็นภาษาของผู้เล่นก็จะถูกแสดงผลออกมาในรูปแบบของภาษาอังกฤษ
การแจ้งเตือนเกมจะให้การรองรับการแปลภาษาสำหรับคุณสมบัติดังต่อไปนี้:
ข้อความที่ได้รับการแปล แต่ละข้อความจะประกอบด้วย 2 ส่วน:
โทเค็นเป็นคีย์ที่จะขึ้นต้นด้วยสัญลักษณ์ "#" และจะเป็นตัวแทนของสตริงที่ได้รับการแปลภาษาเป็นภาษาต่าง ๆ ผ่านทางเครื่องมือการแปลภาษาที่อยู่ในการกำหนดค่าแอปพลิเคชันของคุณ โทเค็นหนึ่งโทเค็นจะสามารถบรรจุอินสแตนซ์ของตัวแปรไว้ได้หลายอินสแตนซ์ ซึ่งสามารถแทนที่อินสแตนซ์เหล่านี้ได้ที่รันไทม์ ตามบริบทของเกมในเวลาที่ได้สร้างข้อความขึ้นมา ตัวอย่างมีดังต่อไปนี้:
#InvitationText = "{{user}} has invited you to play a game of Chess."ในตัวอย่างข้างต้น คำแปลภาษาอังกฤษของ #InvitationText ได้บรรจุตัวแปรเอาไว้ 1 ตัวแปรที่เรียกว่า user เวลาที่คุณต้องการจะแสดงผลข้อความตัวอักษรดังกล่าวนี้ให้แก่ผู้ใช้ เมื่อ "SteamUserName" ได้เชิญผู้ใช้เข้าร่วมเล่นเกม คุณจะอัปเดตออบเจ็กต์ LocalizationText ด้วยคุณสมบัติดังต่อไปนี้:
"message":
{
"token": "#InvitationText",
"variables":
[
{ "key": "user", "value": "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"
}
}
}
