ส่งข้อมูลเกมเป็นล็อกอีเวนต์: การส่งล็อกอีเวนต์ ตอนที่ 3

Hive Analytics · 29 ตุลาคม 2569 · อ่าน 5 นาที

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

เก็บการกระทำในเกมจริงเป็นข้อมูล

"ตรวจสอบโครงสร้างการเก็บข้อมูลและตัวชี้วัดด้วยล็อกทดสอบ: การส่งล็อกอีเวนต์ ตอนที่ 2" ได้อธิบายการส่งล็อกทดสอบเพื่อตรวจสอบโครงสร้างการเก็บข้อมูลและการสร้างตัวชี้วัดของอีเวนต์ ในตอนนี้จะอธิบายวิธีนำโครงสร้างอีเวนต์ที่ตรวจสอบแล้วไปใช้กับเกมจริง และส่งข้อมูลจริง ณ เวลาที่การกระทำของผู้ใช้เกิดขึ้น

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

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

การส่งล็อกอีเวนต์ของ Hive Analytics

ล็อกอีเวนต์ของ Hive Analytics ส่งได้จากไคลเอนต์ของเกมหรือจากเซิร์ฟเวอร์ การส่งจากไคลเอนต์รองรับสภาพแวดล้อมการพัฒนา Unity, Unreal Engine, C++, Android และ iOS ส่วนเซิร์ฟเวอร์สามารถส่งล็อกอีเวนต์ด้วยวิธี Fluentd หรือ HTTP

ล็อกอีเวนต์ประกอบด้วยพร็อพเพอร์ตี้ที่จำเป็นสำหรับการเก็บและประมวลผลตามปกติ และพร็อพเพอร์ตี้ที่กำหนดเองซึ่งแสดงรายละเอียดของอีเวนต์

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

ชื่อพร็อพเพอร์ตี้	คำอธิบาย	ชนิดข้อมูล	ตัวอย่าง
`userId`	ตัวระบุผู้ใช้ตามบัญชี	STRING	`100001`
`deviceId`	ตัวระบุผู้ใช้ตามอุปกรณ์	STRING	`100000`
`identifierProvider`	ระบบที่ออกตัวระบุผู้ใช้ ตั้งค่าเป็น `hive`	STRING	`hive`
`appId`	ID ที่ระบุแอปที่ลงทะเบียนไว้ใน Hive Console	STRING	`com.com2us.game.ios`
`appIdGroup`	ID โปรเจกต์ (เกม) ที่ออกโดย Hive Console สร้างขึ้นโดยอัตโนมัติเมื่อส่ง `appId`	STRING	`com.com2us.game`
`eventTime`	เวลาที่อีเวนต์เกิดขึ้น ส่งในรูปแบบ RFC 3339 ที่มีเขตเวลา	STRING	`2026-07-20T14:01:01+09:00`
`eventName`	ชื่ออีเวนต์ที่ใช้แยกอีเวนต์ที่เกิดขึ้น	STRING	`asset_drop`

กฎการส่งพร็อพเพอร์ตี้ที่จำเป็น
หากพร็อพเพอร์ตี้ที่จำเป็นไม่เป็นไปตามกฎต่อไปนี้ อีเวนต์จะไม่ถูกเก็บตามปกติ และจะถูกจัดเก็บในตารางกักกัน t_raw_event_log_rescue

พร็อพเพอร์ตี้ที่จำเป็นขาดหายไปหรือถูกส่งเป็นค่าว่าง

ส่ง appId ที่ไม่ได้ลงทะเบียนไว้ใน Hive Console

ส่งชื่อพร็อพเพอร์ตี้ที่จำเป็นในรูปแบบ snake case เช่น user_id

eventTime ไม่อยู่ในรูปแบบ RFC 3339 ที่มีเขตเวลา

eventTime อยู่นอกช่วงที่อนุญาต คือ 10 ปีในอดีตถึง 5 ปีในอนาคตนับจากเวลาปัจจุบัน

ต้องส่งชื่อพร็อพเพอร์ตี้ที่จำเป็นในรูปแบบ camel case หรือตัวพิมพ์เล็ก สำหรับล็อกที่ถูกกักกัน ให้ตรวจสอบข้อมูลต้นฉบับและสาเหตุของการกักกันใน t_raw_event_log_rescue แก้ไขค่าที่ไม่ถูกต้อง แล้วส่งใหม่อีกครั้ง

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

ส่งอีเวนต์การเล่นคอนเทนต์สำเร็จด้วย contents_success

ส่วนนี้เป็นขั้นตอนการนำอีเวนต์ contents_success ไปใช้กับเกมจริง ให้ส่งอีเวนต์เมื่อผู้ใช้เล่นคอนเทนต์ในเกมสำเร็จ และเชื่อมประเภทคอนเทนต์ สถานะของผู้ใช้ และผลการเล่นเข้ากับข้อมูลเกมจริง

ตรวจสอบเวลาส่งอีเวนต์

contents_success เป็นอีเวนต์ที่เกิดขึ้นเมื่อคอนเทนต์ในเกมเสร็จสมบูรณ์ ให้ส่งอีเวนต์ทันทีหลังจากที่ผลการเล่นสำเร็จได้รับการยืนยันผ่านการตอบกลับของเซิร์ฟเวอร์หรือลอจิกของเกม ไม่ใช่ตอนเข้าคอนเทนต์หรือตอนเริ่มเล่น

หากการประมวลผลการเล่นสำเร็จแบบเดียวกันอาจทำงานซ้ำหลายครั้งระหว่างการลองใหม่หรือการเปลี่ยนหน้าจอ ให้จัดการไม่ให้อีเวนต์ถูกส่งซ้ำสำหรับการกระทำเดียว

เชื่อมพร็อพเพอร์ตี้ที่กำหนดเอง

ตรวจสอบพร็อพเพอร์ตี้ที่กำหนดไว้ล่วงหน้าของ contents_success แล้วเชื่อมข้อมูลเกมจริง ณ เวลาที่อีเวนต์เกิดขึ้นเข้ากับแต่ละพร็อพเพอร์ตี้

พร็อพเพอร์ตี้	ค่าที่จะส่ง
`characterLv`	เลเวลตัวละคร ณ เวลาที่เล่นคอนเทนต์สำเร็จ
`modeTypeId`	ID ที่ใช้แยกประเภทคอนเทนต์
`modeTypeName`	ประเภทคอนเทนต์หรือชื่อคอนเทนต์
`score`	คะแนนที่ได้รับในคอนเทนต์
`playTimeSec`	เวลาที่ใช้จนเล่นคอนเทนต์สำเร็จ (วินาที)

ให้คงชื่อพร็อพเพอร์ตี้ ชนิดข้อมูล และหน่วยของค่าไว้ตามเกณฑ์ที่ตรวจสอบด้วยล็อกทดสอบ โดยเฉพาะพร็อพเพอร์ตี้ที่เกี่ยวกับเวลาอย่าง playTimeSec ควรใช้หน่วยเดียวกัน เช่น วินาทีหรือมิลลิวินาที เพื่อให้วิเคราะห์ข้อมูลของหลายเกม (โปรเจกต์) ด้วยเกณฑ์เดียวกันได้

กำหนดพร็อพเพอร์ตี้ที่จำเป็น

ล็อกอีเวนต์ต้องมีพร็อพเพอร์ตี้ที่จำเป็น ได้แก่ userId, deviceId, identifierProvider, appId, appIdGroup, eventTime และ eventName

เมื่อส่งจากไคลเอนต์ด้วย Hive SDK v4 ค่าของพร็อพเพอร์ตี้ที่จำเป็นทั้งหมดยกเว้น eventName จะถูกเก็บโดยอัตโนมัติ พร็อพเพอร์ตี้ที่แสดงแอปและสภาพแวดล้อมการทำงานของผู้ใช้ เช่น market, hive_country, language, os และ app_version ก็ถูกเก็บด้วย ดังนั้นในส่วนของพร็อพเพอร์ตี้ที่จำเป็นจึงกำหนดเพียง eventName เอง

เมื่อส่งจากไคลเอนต์ด้วย Hive Axyl identifierProvider จะถูกกำหนดเป็น hive ที่ฝั่งเซิร์ฟเวอร์ และ appId จะถูกส่งผ่านเฮดเดอร์ของคำขอส่งล็อกโดยอัตโนมัติด้วยค่าที่ระบุไว้ตอนเริ่มต้น SDK ส่วนพร็อพเพอร์ตี้ที่จำเป็นอื่นๆ ให้กำหนดและส่งเอง

เมื่อส่งจากเซิร์ฟเวอร์ ให้กำหนดพร็อพเพอร์ตี้ที่จำเป็นเองทั้งในวิธี Fluentd และ HTTP ดูรายละเอียดวิธีการส่งได้ที่ การส่งอีเวนต์ ในเว็บไซต์ Hive Developers

ใส่โค้ดส่งอีเวนต์

ใน Data > Event ให้เลือก contents_success แล้วไปที่แท็บ Source Generation เลือกวิธีการพัฒนาแบบไคลเอนต์หรือเซิร์ฟเวอร์และสภาพแวดล้อมการพัฒนาของเกม แล้วตรวจสอบซอร์สที่สร้างขึ้น

นักพัฒนาจะแทนที่ค่าตัวอย่างในซอร์สที่สร้างขึ้นด้วยตัวแปรจริงของเกม แล้วใส่โค้ดในตำแหน่งที่การเล่นคอนเทนต์สำเร็จได้รับการยืนยัน ให้ใส่ contents_success เป็นชื่ออีเวนต์ และส่งค่า characterLv, modeTypeId, modeTypeName, score และ playTimeSec ณ เวลาที่เล่นคอนเทนต์สำเร็จเป็นพร็อพเพอร์ตี้ที่กำหนดเอง

หากส่งจากไคลเอนต์ ให้กำหนดพร็อพเพอร์ตี้ที่จำเป็นซึ่งต้องส่งเองตาม SDK ที่ใช้ และไม่ต้องใส่พร็อพเพอร์ตี้ที่จำเป็นที่ถูกเก็บโดยอัตโนมัติลงในโค้ด ตัวอย่างเช่น เมื่อส่งจากไคลเอนต์ด้วย Hive SDK v4 ในสภาพแวดล้อม Unity ให้ใส่ eventName ซึ่งเป็นพร็อพเพอร์ตี้ที่จำเป็นเพียงตัวเดียวที่ต้องส่ง และพร็อพเพอร์ตี้ที่กำหนดเองลงใน JSONObject แล้วเรียก Analytics.sendAnalyticsLog(logData) เพื่อส่งอีเวนต์

JSONObject logData = new JSONObject();
// พร็อพเพอร์ตี้ที่จำเป็น (ส่งเฉพาะ eventName ส่วนที่เหลือ SDK เก็บโดยอัตโนมัติ)
logData.AddField("eventName", "contents_success");
// พร็อพเพอร์ตี้ที่กำหนดเอง
logData.AddField("characterLv", 15);
logData.AddField("modeTypeId", 1);
logData.AddField("modeTypeName", "Tutorial_1");
logData.AddField("score", 12);
logData.AddField("playTimeSec", 120);
Analytics.sendAnalyticsLog(logData);

การจัดเก็บอีเวนต์

อีเวนต์ที่ถูกเก็บตามปกติจะถูกจัดเก็บใน t_raw_event_log ส่วนอีเวนต์ที่ไม่เป็นไปตามเกณฑ์การเก็บข้อมูล เช่น พร็อพเพอร์ตี้ที่จำเป็นขาดหายไปหรือรูปแบบ eventTime ผิดพลาด จะถูกกักกันไว้ใน t_raw_event_log_rescue

โครงสร้างการจัดเก็บข้อมูลปกติและข้อมูลที่ถูกกักกัน รวมถึงวิธีตรวจสอบสาเหตุของการกักกัน จะอธิบายโดยละเอียดใน "ตรวจสอบโครงสร้างการจัดเก็บล็อกอีเวนต์และข้อมูลที่โหลดไม่สำเร็จ: การส่งล็อกอีเวนต์ ตอนที่ 4"

เริ่มต้นใช้งาน Hive Analytics

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

Hive Analytics เป็นโซลูชันวิเคราะห์ข้อมูลเฉพาะสำหรับเกม ที่ช่วยให้ส่งอีเวนต์ด้วยวิธีที่เหมาะกับสภาพแวดล้อมของไคลเอนต์และเซิร์ฟเวอร์ และนำข้อมูลที่เก็บได้ไปใช้วิเคราะห์ ลองเชื่อมโครงสร้างอีเวนต์ของการกระทำในเกมที่ต้องการวิเคราะห์ใน Hive Analytics เข้ากับข้อมูลเกมจริงได้เลยวันนี้