用事件模板定义日志采集结构：事件日志发送第1篇

Hive Analytics · 2026年10月22日 · 阅读约 5 分钟

Hive Analytics 以事件模板的形式提供游戏分析中常用的用户行为。模板已预先定义事件名和属性，无需从零设计事件结构，即可确定日志采集结构。分析人员在 Data > Event（数据 > 事件）中选择事件并查看可用指标，在 Property Setting（属性设置）中修改或添加预定义属性，再在 Source Generation（源码生成）中查看适合开发环境的源代码。在正式提交开发需求之前，先发送测试日志，验证数据是否按预期结构采集。

为什么游戏事件日志需要统一的定义

要准确分析游戏用户的行为，就必须按统一的标准定义事件名和属性。游戏中需要分析的用户行为不只有登录和购买，还包括完成内容、获得货币、使用道具等。要分析这些行为，需要把行为发生时的信息作为事件日志采集下来，因此必须事先定义事件名、触发时机，以及随事件一同发送的属性和数据类型。

如果每款游戏都从零设计这些项目，含义相同的行为也可能以不同的名称或结构被采集。要想在分析时准确理解每条日志的含义，并按同一标准比较多款游戏的数据，就要从事件定义开始保持一致。

什么是 Hive Analytics 的事件模板

Hive Analytics 的事件模板，是把游戏分析中常用的行为以预先定义好事件名和属性的形式提供出来的功能。在介绍事件模板之前，先梳理一下日志采集中用到的主要术语。

术语	说明
事件	把用户在游戏中执行的特定行为记录为数据的单位，包含何时、谁、做了什么。
属性	事件发生时一并记录的详细信息，表示该行为是在什么条件下、以什么值发生的。
源代码	为将事件发送到 Hive Analytics，在 Source Generation 标签页中按开发环境自动生成的代码。

在 app_login 事件的 Basic Info 标签页中查看事件名、类别和说明的界面 — 在 Basic Info（基本信息）标签页中可以查看 `app_login` 事件的发送时机，在 Property Setting 中查看属性，在 Source Generation 中查看源代码。

事件模板中也包含集成 Hive SDK 后自动采集的登录、购买等事件。模板中的事件已在 Data > Event 中预先定义好事件名和属性，无需从零设计结构即可直接使用，日志发送完成后即可在 Hive Analytics 中开始基于事件的分析。即使没有事先注册事件或属性就发送了日志，这些日志同样可以在 Hive Analytics 中使用。

在开发者网站查看事件模板
无需登录 Hive Analytics，也可以在 Hive 开发者网站的事件模板指南中，查看各预定义事件的发送时机、可用指标示例、是否由 Hive SDK 自动采集以及属性列表。

在 Hive Analytics 的 Data 菜单中查看游戏玩法事件列表的界面 — 在事件列表中查看事件名和说明、最近一次数据采集日期以及是否启用。

选择事件后，可以查看用该事件能够创建的指标。在 Property Setting 中检查预定义的项目，按分析目的进行修改或添加新属性。属性配置完成后，在 Source Generation 中选择游戏的开发环境，即可查看已包含所设事件和属性的源代码。

在把生成的源代码用于正式开发之前，先发送测试日志，验证事件和属性值是否按预期结构采集，以及能否用这些数据构建所需的指标。结合验证结果，就能把要交给开发人员的事件结构和源代码确定下来。

分析人员可以按以下顺序，选择与待分析行为匹配的事件，并准备所需的属性和日志发送源代码。

选择事件
找到与待分析行为相符的事件模板。
设置属性
检查预定义属性，修改或添加所需属性。
生成源代码
选择游戏的开发环境，生成包含所设事件和属性的源代码。

用 contents_success 准备内容完成事件

要分析完成内容的用户数、平均游玩时长等，就需要准备 contents_success 事件和日志发送源代码。从选择事件到生成源代码的流程如下。

选择事件

在 Data > Event 中选择 contents_success 并查看说明。contents_success 是在用户完成游戏内容时触发的事件，可用于构建内容完成次数、完成用户数、平均游玩时长、平均分数等指标。分析人员据此确定要使用的指标，并明确该事件应在游戏中的哪个时机触发。

显示 contents_success 事件的 Basic Info、Property Setting、Data Preview 和 Source Generation 标签页的界面 — 在 `contents_success` 的 Basic Info 中查看事件的含义和可用指标。

设置属性

在 Property Setting 中查看 contents_success 预定义的属性，以及各属性的说明和数据类型。之后在 Create（创建）中创建图表时，这些属性将用于构建度量值、维度值和筛选条件。contents_success 包含表示使用环境的 market 和 hive_country，用于识别用户的 userId 和 deviceId，以及表示内容完成具体条件的 characterLv 和 modeTypeId 等。

appId、appIdGroup、dateTime、userId、deviceId、eventName、eventTime、identifierProvider 是由系统管理的公共属性，无法在 Property Setting 中修改。其中，userId、deviceId、identifierProvider、eventTime、eventName 以及 appId 或 appIdGroup，是发送事件日志时必须包含的必填属性。dateTime 是将发送的 eventTime 转换为 UTC 后存储的时间。

预定义属性可按需修改。如果缺少分析所需的值，可点击编辑界面左下角的 Add Event + 添加新属性。例如，要在分析中使用角色名称，就添加 characterName 属性，并将数据类型设为字符串。即使是 Hive Analytics 中未预先定义的属性，只要包含在日志中发送，也可以用于分析。这样保存的事件和属性可以在多个项目中作为同一套采集标准使用，让相同的行为以一致的属性名、数据类型、值格式和单位发送。