เอกสาร Steamworks
การแจ้งเตือนเกม

ภาพรวม

การแจ้งเตือนเกม 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" } } }