將遊戲資料以事件日誌傳送：事件日誌傳送 第3篇

將實際遊戲行為收集為資料

「用測試日誌驗證收集結構與指標：事件日誌傳送 第2篇」介紹了如何傳送測試日誌，驗證事件的收集結構與指標組成。本篇將說明如何把驗證過的事件結構套用到實際遊戲，並在用戶行為發生時傳送實際資料。

即使已透過測試日誌確認事件名稱與屬性、資料型別與值的格式，在實際遊戲中仍必須配合用戶行為發生的時機執行日誌傳送程式碼。請將程式碼套用在內容完成、取得貨幣、使用道具等行為確定的位置，並將當下的實際遊戲資料連結到事件屬性。

如果事件傳送得太早，可能會把尚未完成的行為計入統計；傳送得太晚，則可能因畫面切換或關閉應用程式而遺失日誌。因此，應依事件的意義決定傳送時機，並在實際行為完成後立即傳送日誌。

Hive Analytics 的事件日誌傳送

Hive Analytics 的事件日誌可以從遊戲用戶端或伺服器傳送。用戶端傳送支援 Unity、Unreal Engine、C++、Android 與 iOS 開發環境，伺服器則可透過 Fluentd 或 HTTP 方式傳送事件日誌。

事件日誌由正常收集與處理所需的必要屬性，以及表示事件詳細資訊的自訂屬性組成。

必要屬性包含以下用來識別用戶與裝置、應用程式與專案（遊戲）、事件名稱與發生時間的值。

必要屬性傳送規則
若必要屬性不符合以下規則，事件將無法正常收集，並會儲存在隔離資料表 t_raw_event_log_rescue。

• 必要屬性缺漏或以空值傳送時
• 傳送未在 Hive 控制台登錄的 appId 時
• 以 user_id 這類蛇形命名（snake case）傳送必要屬性名稱時
• eventTime 不是包含時區的 RFC 3339 格式時
• eventTime 超出以目前時間為基準、過去 10 年至未來 5 年的允許範圍時

必要屬性名稱必須以駝峰式命名（camel case）或小寫傳送。被隔離的日誌，請在 t_raw_event_log_rescue 確認原始資料與隔離原因，修正錯誤的值後重新傳送。

自訂屬性可自由組成，用來分析角色等級、內容類型、分數與遊玩時間等事件的詳細資訊。無論用戶端或伺服器，都要將實際遊戲值連結到分析所需的自訂屬性並直接傳送。

以 contents_success 傳送內容完成事件

以下是將 contents_success 事件套用到實際遊戲的流程。在用戶完成遊戲內容時傳送事件，並將內容類型、用戶狀態與遊玩結果連結到實際遊戲資料。

確認事件傳送時機

contents_success 是在遊戲內容完成時發生的事件。請不要在進入內容或開始遊玩時傳送，而是在透過伺服器回應或遊戲邏輯確定完成結果後立即傳送事件。

如果在重試或畫面切換的過程中，同一個完成處理可能執行多次，請避免針對單一行為重複傳送事件。

連結自訂屬性

確認 contents_success 預先定義的屬性，並將事件發生當下的實際遊戲資料連結到各個屬性。

屬性名稱、資料型別與值的單位，請維持與測試日誌驗證時相同的基準。特別是 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，將想分析的遊戲行為事件結構與實際遊戲資料連結起來吧。