将游戏数据作为事件日志发送：事件日志发送 第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 方式，都需要自行设置必填属性。具体发送方法请参阅开发者网站的事件发送。

应用事件发送代码

在 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，把想要分析的游戏行为的事件结构与真实游戏数据关联起来吧。