事件設計與傳送指南¶

什麼是事件分類法？¶

事件分類法(Event Taxonomy)是將收集的事件與屬性以 一致的結構與命名規則系統化整理的分類體系。

如果不加規則地收集遊戲中發生的各種行為資料（登入、購買、升級等），就會出現各團隊以不同名稱傳送相同資料，或在分析時難以判斷某筆資料代表什麼的情況。事件分類法可避免這些混亂，並協助將收集到的資料直接用於分析。

為什麼需要？¶

結構¶

Analytics 的事件分類法由 事件 與 屬性 兩層構成。

事件 (Event)
├── 平台屬性 (Platform Attribute)   ← 只要串接 SDK 即自動收集
└── 事件屬性 (Event Attribute)      ← 隨事件直接傳送

什麼是事件？¶

事件是將使用者在遊戲內進行的特定行為記錄為資料的單位。它包含「何時、誰、做了什麼」，是分析的最基本單位。

• 例：使用者購買道具 → 發生 item_purchase 事件
• 例：使用者通過特定關卡 → 發生 stage_clear 事件
• 例：使用者登入 App → 發生 login 事件

什麼是屬性？¶

屬性是事件發生時一起記錄的細節資訊。只有事件本身時，只能知道「發生了什麼」，但透過屬性，還能進一步掌握「在什麼條件下、以什麼值」發生。

• 例：item_purchase 事件的屬性 → 道具 ID、付款金額、貨幣單位
• 例：stage_clear 事件的屬性 → 關卡編號、通關時間、使用角色

屬性會依收集主體分為兩種。

• 平台屬性：不需額外設定，只要串接 SDK，Hive 就會預設收集的屬性。包含國家、OS、App 版本、伺服器 ID 等。
• 事件屬性：隨事件直接傳送的屬性。由您直接定義並傳送分析所需項目。

自訂事件傳送¶

遊戲中自行定義的事件（自訂事件）可依下列收集 schema 傳送，並在 Analytics 中用於分析。

實際資料傳送使用 Hive SDK 用戶端日誌傳送 方法。傳送所需的原始碼可在 事件 的 [建立來源] 分頁中依語言自動產生。

在傳送事件前，可先於 事件 定義事件名稱與屬性，方便團隊內分享與管理。不過，即使未事先定義就傳送資料，Analytics 也會自動辨識收到的資料，並會在最長 1 小時內反映到事件清單中。

Analytics 收集 schema¶

傳送自訂事件時使用的基本 schema。所有事件都必須依下列格式傳送。

事件名稱命名規則¶

建議 eventName 使用的事件名稱遵循以下規則。

• 建議字元：英文字母(a–z, A–Z，區分大小寫)、數字(0–9)、底線(_)、連字號(-)
• 分隔符號：單字之間使用底線(_)分隔，不使用空格
• 形式：建議使用可清楚描述事件的 名詞_動詞 形式
• 範例：item_purchase, level_up, tutorial_complete, stage_start

hiveAttribute / eventAttribute 結構範例¶

hiveAttribute 與 eventAttribute 分別以 JSON 物件形式傳送。

hiveAttribute — 由 Hive provisioning server 提供的平台屬性。包含 market、server ID 等，目前需由開發者直接設定值後傳送。未來預計改為自動收集方式。

{
  "market": "GO",
  "serverId": "Asia"
}

eventAttribute — 與事件一起直接傳送的屬性。包含分析該事件所需的細節資訊。

{
  "level": "100",
  "contentsType": "dungeon"
}

屬性命名規則¶

建議 eventAttribute 與 hiveAttribute 的 key 名稱遵循以下規則。

• 建議字元：英文字母(a–z, A–Z，區分大小寫)、數字(0–9)、底線(_)、連字號(-)
• 分隔符號：單字之間使用底線(_)分隔，不使用空格
• 範例：item_id, contents-type, stage_level

屬性 key 轉換規則¶

傳送屬性時，系統會依下列規則自動轉換部分 key 名稱。請注意，實際在分析時查詢到的 key 名稱可能不同。

-Hive 後綴 (hiveAttribute)¶

hiveAttribute 的 所有 key 結尾都會自動加上 -Hive。

-Event 後綴 (eventAttribute)¶

僅當 eventAttribute 的 key 與下列 8 個共通欄位名稱重疊時，才會自動加上 -Event。

• timezone, dateTime, identifierProvider, userId, deviceId, appId, category, eventName

推薦事件¶

以下是 Analytics 中分析價值較高的事件範例。若依 eventName 與 eventAttribute 傳送這些事件，可直接用 Analytics 的所有功能進行圖表・漏斗・留存等分析。

升級¶

eventAttribute（共通）：

貨幣¶

eventAttribute（共通）：

內容¶

eventAttribute（共通）：

App 內商店¶

eventAttribute（共通）：

夥伴¶

eventAttribute（共通）：

社交活動¶

相關選單¶

• 事件 — 事件與屬性註冊・管理
• 指標 — 將常用事件彙總設定儲存為指標