เอกสาร 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" } ] }

When the player views his status, he will then see this message (in his local language): "Michael has invited you to play a game of Chess."
Localization tokens can be uploaded in the Async Localization section of the Community tab on the Steamworks Settings page for your app.
Each language can be uploaded individually in VDF files that look like this:
"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" } } }