สถิติการแข่งขัน

สถิติเกมคือสถิติสะสมเกี่ยวกับเกมของคุณที่ผู้เล่นดูได้ในโปรไฟล์เกมเมอร์ สถิติเหล่านี้ช่วยให้ผู้เล่นติดตามความคืบหน้าตลอดอายุการใช้งาน ดูช่วงเวลาไฮไลต์ และเปรียบเทียบกับผู้เล่นคนอื่นๆ รวมถึงขับเคลื่อนฟีเจอร์ของ Google Play เช่น ภารกิจ ความท้าทายทางโซเชียล และอื่นๆ ในอนาคต

สถิติการแข่งขันต้องมีลักษณะดังนี้

• ไม่จำเป็นต้องซื้อ (เช่น ซื้ออัญมณี) ซึ่งไม่ควรมีการอัปเดตอันเป็นผลมาจากการซื้อ IAP
• ไม่กำหนดให้ดูโฆษณา ซึ่งหมายความว่าไม่ควรมีการอัปเดตอันเป็นผลมาจากการดูโฆษณา
• ไม่ใช่การใช้งานเกมทั่วไป (เช่น เปิดเกม ใช้การตั้งค่า)
• ไม่รวมข้อมูลส่วนบุคคลและข้อมูลที่ละเอียดอ่อนของผู้ใช้ตามที่กำหนดไว้ในนโยบายของ Play ซึ่งรวมถึงรหัสผู้ใช้ รหัสผ่าน ตำแหน่งที่แน่นอน หรือข้อมูลสุขภาพ หรือเนื้อหาใดๆ ที่ทำให้เกิดความไม่พอใจ หยาบคาย เกี่ยวกับเรื่องเพศอย่างโจ่งแจ้ง รุนแรง หรือเนื้อหาแสดงความเกลียดชัง
• พร้อมให้บริการแก่ผู้ใช้ทุกคน (เช่น ไม่ใช่การดำเนินการเฉพาะทีมหรือพร้อมให้บริการแก่ผู้ใช้บางระดับเท่านั้น หรือจำกัดเฉพาะ LiveOps ที่มีเวลาจำกัด เป็นต้น)

ขั้นตอนการผสานรวม

ส่งข้อมูลโดยใช้ Game Stats API เป็นเหตุการณ์ของผู้เล่นสำหรับสถิติเกมที่เกิดซ้ำ และเหตุการณ์ที่กำหนดไว้ล่วงหน้า progressUpdate สำหรับสถิติความคืบหน้า นอกจากนี้ คุณยังต้อง กำหนดค่าตรรกะสำหรับการคำนวณสถิติเกมที่จะปรากฏในโปรไฟล์เกมเมอร์ และข้อมูลการแสดงผล

เหตุการณ์ของผู้เล่นแสดงถึงช่วงเวลาที่แตกต่างกันในเกม การวนซ้ำของเกมที่เสร็จสมบูรณ์ หรือ เหตุการณ์สำคัญของความคืบหน้า

เหตุการณ์ของผู้เล่นมีการกำหนดและสร้างแบบจำลองดังนี้

1. เหตุการณ์แสดงถึงการดำเนินการที่เฉพาะเจาะจงซึ่งผู้เล่นทำ เช่น การแข่งขันจนจบ การวิ่งจนจบ การปลดล็อกหีบ หรือการบันทึกความคืบหน้า ในพื้นที่
2. การดำเนินการแต่ละอย่างจะส่งผลให้เกิดผลลัพธ์หรือมีลักษณะบางอย่าง ที่กำหนดการดำเนินการ ซึ่งได้รับการจำลองเป็นพร็อพเพอร์ตี้เหตุการณ์ที่ให้บริบทเกี่ยวกับเหตุการณ์และผลลัพธ์ที่เฉพาะเจาะจง (เช่น ประเภทการแข่งขัน เหรียญที่เก็บรวบรวมระหว่างการแข่งขัน ผลการแข่งขัน หรือจำนวนการยิงที่ศีรษะ)

การผสานรวมประกอบด้วยขั้นตอนต่อไปนี้

• ประกาศสคีมาข้อมูลดิบ: กำหนดเหตุการณ์ของผู้เล่นโดยใช้การอัปโหลด CSV ใน Play Console ดูหัวข้อสร้างกิจกรรม
• ผสานรวมกับ Game Stats API: ส่งข้อมูลผู้เล่นดิบในรูปแบบที่ประกาศไว้ สําหรับเหตุการณ์ของผู้เล่นและเหตุการณ์ progressUpdate
  • ส่งเหตุการณ์ที่กําหนดทั้งหมดโดยใช้การผสานรวมฝั่งไคลเอ็นต์หรือฝั่งเซิร์ฟเวอร์ ดูข้อมูลเพิ่มเติมได้ที่ตัวอย่างสำหรับกิจกรรมของผู้เล่นและกิจกรรม progressUpdate
• อัปโหลดไฟล์ ZIP: ระบุไฟล์ CSV 3 ไฟล์และไฟล์รูปภาพไอคอนทั้งหมดที่ กำหนดสถิติที่ซ้ำกัน 5 รายการและระดับความก้าวหน้าของผู้เล่น 1 รายการ ดูข้อมูลเพิ่มเติมได้ที่หลักเกณฑ์สำหรับไฟล์ ZIP ระบุรายละเอียดต่อไปนี้
  • ไฟล์ CSV สำหรับสถิติที่ทำซ้ำ:
    • รหัสที่ไม่ซ้ำกันสำหรับสถิติ
    • ระบุป้ายกำกับเหตุการณ์ที่จะใช้สำหรับการคำนวณสถิติ คุณใช้progressUpdateป้ายกำกับเหตุการณ์ที่นี่ไม่ได้
      • ระบุป้ายกำกับพร็อพเพอร์ตี้ที่จะใช้สำหรับการคำนวณสถิติ ซึ่งต้องเป็นพร็อพเพอร์ตี้ของเหตุการณ์ที่ระบุ
      • ระบุประเภทการรวม (SUM, MAX, MIN หรือ COUNT) เพื่อ กำหนดวิธีคำนวณสถิติในป้ายกำกับพร็อพเพอร์ตี้ที่เลือก
      • ระบุเงื่อนไขตัวกรองที่ไม่บังคับเพื่อคำนวณตรรกะเฉพาะ เมื่อตรงตามเงื่อนไข กำหนดป้ายกำกับพร็อพเพอร์ตี้และเหตุการณ์ โอเปอเรเตอร์ (=, <, <=, >= หรือ >) และค่าเกณฑ์
    • ใส่แฟล็กบูลีนเพื่อระบุว่าใช้สถิติกับฟีเจอร์การแข่งขันได้หรือไม่
    • หากใช้ฟีเจอร์กับฟีเจอร์ที่แข่งขันกันได้ ให้กำหนดขีดจำกัดรายชั่วโมงขั้นต่ำและสูงสุดสำหรับผู้เล่นจริง เราจะใช้ข้อมูลนี้เพื่อระบุผู้เล่นที่อาจใช้ฟีเจอร์ต่างๆ ในทางที่ผิดเมื่อเข้าร่วมกิจกรรมต่างๆ เช่น ลีกและความท้าทายทางโซเชียล
    • ระบุชื่อที่แสดงที่ไม่ซ้ำกันสำหรับสถิติที่ผู้เล่นเห็น
    • ระบุข้อความที่ไม่ซ้ำกันซึ่งอธิบายสถิติ คำอธิบายนี้ควรให้รายละเอียดเกี่ยวกับวิธีที่ผู้เล่นได้รับสถิติดังกล่าว และจะแสดงต่อผู้เล่นใน UI โปรไฟล์เกมเมอร์
    • ระบุไอคอนที่ไม่ซ้ำกันซึ่งแสดงสถิติโดยป้อนชื่อไฟล์ไอคอนที่ถูกต้องในไฟล์ CSV
    • ระบุอินพุตที่ไม่บังคับว่าค่าที่เพิ่มขึ้นหรือลดลงเป็นผลดีต่อผู้เล่นหรือไม่ ระบบจะใช้ข้อมูลนี้เพื่อ เฉลิมฉลองการเคลื่อนไหวของผู้เล่น
    • ระบุหน่วยวัดที่ไม่บังคับสำหรับสถิติ เช่น กม. ไมล์ และวินาที
  • ไฟล์ CSV สำหรับสถิติความคืบหน้าของผู้เล่น:
    • ระบุชื่อที่แสดงที่ไม่ซ้ำกันสำหรับความคืบหน้าของผู้เล่นที่ผู้เล่นเห็น
    • ระบุไอคอนที่ไม่ซ้ำกันซึ่งแสดงสถิติ
    • ระบุคำอธิบายสำหรับสถิติความคืบหน้า
    • ระบุอินพุตที่ไม่บังคับว่าค่าที่เพิ่มขึ้นหรือลดลงเป็นผลดีต่อผู้เล่นหรือไม่ ระบบจะใช้อินพุตนี้เพื่อ เฉลิมฉลองการเคลื่อนไหวของผู้เล่นเฉพาะเมื่อพร็อพเพอร์ตี้ currentProgress เป็นประเภท INT
    • ระบุหน่วยวัดที่ไม่บังคับสำหรับสถิติ เช่น กม. ไมล์ วินาที
  • ไฟล์ CSV สำหรับการแปล: ระบุชื่อที่แสดงที่แปลแล้วสำหรับสถิติทั้งหมด
    • เพิ่ม 1 แถวสำหรับการแปลแต่ละภาษา
    • ใช้สตริงชื่อที่แสดงของสถิติตามที่เพิ่มใน CSV ก่อนหน้าเพื่อระบุสถิติที่ไม่ซ้ำกัน ซึ่งมีการเพิ่มการแปล
    • ระบุภาษาจากรายการรหัสภาษา
    • เพิ่มการแปลชื่อที่แสดงในภาษาที่ระบุ
    • เพิ่มการแปลคำอธิบายสถิติในภาษาที่ระบุ

วางแผนสคีมา

คุณสามารถส่งข้อมูล 2 ประเภทโดยใช้ API สถิติเกม ได้แก่ เหตุการณ์ของผู้เล่น และเหตุการณ์ที่กำหนดไว้ล่วงหน้าสำหรับสถิติความคืบหน้าของผู้เล่น

ตัวอย่างต่อไปนี้แสดงลักษณะของเหตุการณ์ของผู้เล่นในเกมประเภทต่างๆ

เหตุการณ์ของผู้เล่น

เหตุการณ์ของผู้เล่นกำหนดโดยช่วงเวลาที่แตกต่างกันในเกม การวนซ้ำของเกมที่เสร็จสมบูรณ์ หรือ เหตุการณ์สำคัญในการเลื่อนระดับ

• กําหนดเหตุการณ์เป็นช่วงเวลาที่เฉพาะเจาะจงในเกม การทํา Game Loop เสร็จสมบูรณ์ หรือ เหตุการณ์สําคัญในความคืบหน้า ดังนี้
  • การเล่นเกมจนจบ เช่น การแข่งขันหรือการวิ่งที่เสร็จสมบูรณ์
  • เหตุการณ์สำคัญของความคืบหน้า เช่น ความคืบหน้าในการสำรวจพื้นที่ที่บันทึกไว้หรือ ระดับที่ทำสำเร็จ
  • เนื่องจากสถิติที่ซ้ำกันควรแสดงถึงการกระทําที่ผู้เล่นทําซ้ำได้จริง เหตุการณ์ที่กําหนดจึงควรเชื่อมโยงกับการเล่นเกมหลัก
• เพิ่มพร็อพเพอร์ตี้เพื่อให้บริบทเกี่ยวกับเหตุการณ์และผลลัพธ์ เช่น หมายเลขเลเวล ประเภทการแข่งขัน ประเภทอาวุธ จำนวนอาวุธ การยิงที่ศีรษะ เหรียญที่เก็บได้ ผลการแข่งขัน เวลาต่อรอบ หรือประเภทรถ
• ส่งเหตุการณ์ภายในเซสชันการเล่นเกมทันทีที่เกิดขึ้น เช่น ส่งเหตุการณ์การวนซ้ำของเกมเสร็จสมบูรณ์ทันทีหลังจากที่ลูป เสร็จสมบูรณ์

progressUpdate เหตุการณ์

หากเกมมีกลไกความคืบหน้าหลัก ให้ใช้เหตุการณ์นี้เพื่อส่งความคืบหน้าปัจจุบันของผู้เล่น เหตุการณ์มีพร็อพเพอร์ตี้ที่กําหนดไว้ล่วงหน้า 1 รายการชื่อ "currentProgress" ประเภท INT หรือ STRING คุณต้องส่ง ค่าปัจจุบันของความคืบหน้าของผู้เล่นในกลไกความคืบหน้าหลักโดยใช้พร็อพเพอร์ตี้นี้ หากคุณใช้เหตุการณ์นี้ พร็อพเพอร์ตี้ "currentProgress" ที่กำหนดไว้ล่วงหน้าต้อง มีอยู่ และต้องกำหนดสถิติความคืบหน้าโดยใช้พร็อพเพอร์ตี้นี้

คุณสามารถส่งค่าปัจจุบันสำหรับระบบความคืบหน้าอื่นๆ ในเกม เช่น lifetime highest score หรือ current coin balance เป็นพร็อพเพอร์ตี้อื่นๆ ของเหตุการณ์นี้ได้

เนื่องจากผู้เล่นสามารถเปรียบเทียบโปรไฟล์ของตนเองตามความคืบหน้าปัจจุบันภายในเกม จึงเป็นสิ่งสำคัญที่จะต้องไม่มีความล่าช้าในการรับค่าความคืบหน้าปัจจุบันหลังจากการผสานรวมครั้งแรก คุณควรส่งเหตุการณ์ progressUpdate เมื่อเริ่มเซสชันเกมแต่ละเซสชันและทุกครั้งที่มีการอัปเดตความคืบหน้าปัจจุบัน เพื่อแสดงความคืบหน้าปัจจุบันที่ถูกต้องแก่ผู้เล่น

กำหนดค่าสถิติ

คุณจะต้องกำหนดค่าสถิติที่ทำซ้ำและสถิติความคืบหน้าโดยกำหนด ตรรกะการคำนวณและแสดงข้อมูลเกี่ยวกับสถิติแต่ละรายการ ตัวอย่าง สถิติที่ทำซ้ำจากประเภทเกมต่างๆ มีดังนี้ สถิติที่ซ้ำกัน มักเป็นสถิติที่อัปเดตซ้ำๆ สำหรับผู้เล่นทุกคนในเซสชันเกมเพียงไม่กี่เซสชัน (3-4 เซสชัน) และเชื่อมโยงกับลูปหลักของเกม

รายละเอียดการผสานรวม

ปลายทาง API และ SDK พร้อมให้รับความคิดเห็นในช่วงแรก และจะ พร้อมให้บริการแก่ผู้ใช้ทุกคน (GA) ตั้งแต่เดือนสิงหาคม 2026 เป็นต้นไป ดูไทม์ไลน์

ส่วนนี้แสดงวิธีสร้างเหตุการณ์และส่งในทั้งการผสานรวมฝั่งไคลเอ็นต์และ ฝั่งเซิร์ฟเวอร์

คุณควรส่งข้อมูลเมื่อใด

เหตุการณ์ของผู้เล่นแสดงการกระทําในเกมที่เกี่ยวข้องกับการทํา Game Loop ให้เสร็จสมบูรณ์ หรือช่วงเวลาที่เฉพาะเจาะจงในเกม โปรดส่งเหตุการณ์เหล่านี้ทันทีที่เกิดขึ้น เช่น ส่งเหตุการณ์การทำ Game Loop เสร็จสมบูรณ์ทันทีที่ลูปเสร็จสมบูรณ์

progressUpdate เหตุการณ์แสดงระดับความคืบหน้าปัจจุบันของผู้เล่น ควรส่งข้อมูลสถิติความคืบหน้าโดยใช้เหตุการณ์นี้ในสถานการณ์ต่อไปนี้

1. เมื่อใดก็ตามที่มีการอัปเดตความคืบหน้าปัจจุบัน ให้ส่งค่าล่าสุด ทันที
2. ทุกครั้งที่ผู้เล่นเปิดเกมเพื่อให้มั่นใจว่าสถิตินี้จะพร้อมใช้งานสำหรับผู้เล่นตลอดเวลา

เส้นทางการผสานรวม

การผสานรวมมี 2 เส้นทาง ได้แก่ ไคลเอ็นต์และเซิร์ฟเวอร์ต่อเซิร์ฟเวอร์

การผสานรวมแบบเซิร์ฟเวอร์ต่อเซิร์ฟเวอร์

ปลายทาง API สาธารณะช่วยให้คุณส่งเหตุการณ์ในเพย์โหลดคำขอได้โดยใช้การกำหนดค่าต่อไปนี้

คำขอ HTTP

POST https://games.googleapis.com/games/v1/players/{playerId}/gameStats: batchRecordEvents

พารามิเตอร์เส้นทาง

การให้สิทธิ์และการตรวจสอบสิทธิ์

การเรียก API แบบเซิร์ฟเวอร์ต่อเซิร์ฟเวอร์เป็นไปตามหลักเกณฑ์การเข้าถึงฝั่งเซิร์ฟเวอร์สำหรับบริการเกมของ Play มาตรฐานโดยใช้ OAuth 2.0 คำขอต้องมีโทเค็น Bearer ที่ได้รับอนุญาตด้วยขอบเขต https://www.googleapis.com/auth/games

เหตุการณ์: เนื้อหาของคำขอ

API แบ็กเอนด์มีขีดจำกัดการตรวจสอบโครงสร้างที่เข้มงวด ดังนี้

• ขนาดกลุ่ม: เหตุการณ์สูงสุด 30 รายการต่อ BatchRecordEventsRequest
• จํานวนพร็อพเพอร์ตี้: พร็อพเพอร์ตี้ที่กําหนดเองสูงสุด 25 รายการต่อ PlayerGameEvent
• ขีดจํากัดความยาว: ชื่อเหตุการณ์ (สูงสุด 100 อักขระ), คีย์พร็อพเพอร์ตี้ (สูงสุด 100 อักขระ) และค่าสตริงของพร็อพเพอร์ตี้ (สูงสุด 1,024 อักขระ)
• รหัสเหตุการณ์: ต้องเป็นสตริง UUID 36 อักขระที่ถูกต้อง
• ลองใหม่และการแคช: หลีกเลี่ยงการแคชหรือสะสมเหตุการณ์มากเกินไป ในเครื่องหาก API ล้มเหลว เนื่องจากระบบจะปฏิเสธการลองใหม่แบบเป็นกลุ่มที่เกิน 30 เหตุการณ์ แบ่งการลองใหม่เสมอเพื่อไม่ให้เกินขีดจำกัดขนาดกลุ่ม

BatchRecordEventsRequest

ดู BatchRecordEventsRequest

{
  "packageName": string,
  "requestTime": string,
  "events": [
    {
      object (PlayerGameEvent)
    }
  ]
}

PlayerGameEvent

{
  "eventId": string,
  "eventName": string,
  "eventProperties": {
    // keys (e.g., "matchId", "score")
    "": {
       object (PropertyValue)
    }
  },
  "eventTime": string // RFC 3339 formatted timestamp string (e.g., "2026-01-01T18:00:00Z").
}

PropertyValue

// ONE of the following fields will be present:
{
// 64-bit integer formatted as a string to prevent data loss
"intValue": "string",
// Double-precision floating point number.
"doubleValue": number,
// Standard UTF-8 text string.
"stringValue": "string",
// Boolean value (true or false).
"boolValue": boolean,
// Duration in seconds suffixed with 's' (e.g., "240s" or "3.5s").
"durationValue": "string"
}

progressUpdate event: เนื้อหาคำขอ

BatchRecordEventsRequest

{
  "packageName": string,
  "requestTime": string,
  "events": [
    {
      object (PlayerGameEvent)
    }
  ]
}

PlayerGameEvent - progressUpdate

{
  "eventId": string,
  "eventName": "progressUpdate",
  "eventProperties": {
    "": {
       object (PropertyValue)
// Must have at least one property "currentProgress"  of  type  INT  or  STRING
    }
  },
  "eventTime": string // RFC 3339 formatted timestamp string (e.g., "2026-01-01T18:00:00Z")
}

เนื้อหาการตอบกลับ

หากสำเร็จ จะแสดงสถานะ HTTP 200 OK พร้อมออบเจ็กต์ JSON ว่าง

ตัวอย่างเนื้อหาคำขอ

เหตุการณ์: PlayerGameEvent

{
  "packageName": "com.example.awesomegame",//Your package name
  "requestTime": "2026-05-09T00:44:44Z",
  "events": [
    {
      "eventId": "123e1234-e29b-41d4-a123-446655440000", // UUID for deduplication and idempotency
      "eventName": "matchCompleted",
      "eventTime": "2026-05-09T01:44:44Z", // RFC 3339 formatted timestamp string (e.g., "2026-05-09T01:44:44Z").
      "eventProperties": {
        "matchId": {
          "stringValue": "Match_A"
        },
        "gameMode": {
          "stringValue": "Battle_B"
        },
        "locationId": {
          "stringValue": "Location_XYZ"
        },
        "playerElimination": {
          "intValue": 2
        },
        "isWinner": {
          "boolValue": true
        }
      }
    }
  ]
}

progressUpdate กิจกรรม

{
  "packageName": "com.example.awesomegame",//Your package name
  "requestTime": "2026-05-09T00:44:44Z",
  "events": [
    {
      "eventId": "123e1234-e29b-41d4-a123-446655440000", // UUID
      "eventName": "progressUpdate",
      "eventTime": "2026-05-09T01:44:44Z", // RFC 3339 formatted timestamp string (e.g., "2026-01-01T18:00:00Z").
      "eventProperties": {
        "currentProgress": {
          "intValue": 52
        },
//Add more properties as per your requirement
      }
    }
  ]
}

การติดตั้งใช้งานฝั่งไคลเอ็นต์

ดูข้อมูลเกี่ยวกับการติดตั้งใช้งานไคลเอ็นต์สถิติเกมสําหรับแพลตฟอร์มของคุณได้ที่แหล่งข้อมูลต่อไปนี้

• Android
• Unity
• C++

เป้าหมาย