事件设计与发送指南¶

什么是事件分类体系？¶

事件分类体系（Event Taxonomy）是将收集的事件和属性以一致的结构和命名规则系统化组织起来的分类体系。

如果不加规则地收集游戏中发生的大量行为数据（登录、购买、升级等），团队之间可能会用不同的名称发送同一数据，或者在分析时难以理解某条数据具体意味着什么。事件分类体系可以避免这种混乱，并帮助收集到的数据直接用于分析。

为什么需要它？¶

结构¶

Analytics 的事件分类体系由 事件 和 属性 两层构成。

事件 (Event)
├── 平台属性 (Platform Attribute)   ← 仅通过 SDK 集成自动收集
└── 事件属性 (Event Attribute)      ← 随事件直接发送

什么是事件？¶

事件是记录用户在游戏内执行的特定行为的数据单位。它包含“什么时候、谁、做了什么”，是分析的最基本单位。

• 例：用户购买了道具 → 发生 item_purchase 事件
• 例：用户通关了某一关卡 → 发生 stage_clear 事件
• 例：用户登录了应用 → 发生 login 事件

什么是属性？¶

属性是在事件发生时一并记录的详细信息。仅靠事件只能知道“发生了什么”，而通过属性可以进一步了解“在什么条件下、以什么数值发生”。

• 例：item_purchase 事件的属性 → 道具 ID、支付金额、货币单位
• 例：stage_clear 事件的属性 → 关卡编号、通关时间、使用角色

按收集主体不同，属性分为两类。

• 平台属性：无需额外设置，仅通过 SDK 集成即可由 Hive 默认收集的属性。包括国家、OS、应用版本、服务器 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 服务器提供的平台属性。包括市场、服务器 ID 等，目前需要开发者手动设置值后发送。后续将改为自动收集方式。

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

eventAttribute — 与事件一起直接发送的属性。包含分析该事件所需的详细信息。

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

属性命名规则¶

建议按以下规则编写 eventAttribute 和 hiveAttribute 的键名。

• 推荐字符：英文字母(a–z, A–Z，区分大小写)、数字(0–9)、下划线(_)、连字符(-)
• 分隔符：单词之间不要使用空格，而使用下划线(_)分隔
• 示例：item_id, contents-type, stage_level

属性键转换规则¶

发送属性后，系统会按照以下规则自动转换部分键名。请注意，分析时实际查询到的键名可能会不同。

-Hive 后缀（hiveAttribute）¶

hiveAttribute 的 所有 键末尾都会自动添加 -Hive。

-Event 后缀（eventAttribute）¶

仅当 eventAttribute 中的键与下面 8 个共通字段中的任意名称重名时，才会自动添加 -Event。

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

推荐事件¶

以下是 Analytics 中分析价值较高的事件示例。按 eventName 和 eventAttribute 发送这些事件后，就可以直接用图表·漏斗·留存等 Analytics 的全部功能进行分析。

升级¶

eventAttribute（共通）：

货币¶

eventAttribute（共通）：

内容¶

eventAttribute（共通）：

应用内商店¶

eventAttribute（共通）：

伙伴¶

eventAttribute（共通）：

社交活动¶

关联菜单¶

• 事件 — 事件与属性注册·管理
• 指标 — 将常用的事件汇总设置保存为指标