1.如何定义用户

广义的用户，是使用产品的最终的人，这个人在登录的场景下可能通过多端，比如 iOS 端或 Android 同时或先后产生行为数据，但都是同一个人产生的，这时候标识用户就需要有跨端的唯一识别 ID：账号 ID。

狭义的用户，是与产品产生数据交互的终端，这种情况一般不做跨端统计，即使是同一人，跨端或者不跨端但更换设备时，都会被统计为不同的用户，这时候标识用户一般使用与设备有关的唯一标识 ID：访客 ID。

访客 ID 一般与设备标识 ID 相关，不需要注册登录即可生成；账号 ID 一般与人有关，需要注册登录才会生成。

但在实际应用中，还可能存在一个用户在安装应用时只有访客 ID，没有账号ID的情况，而我们又需要分析一个用户由新增到注册登录成功，乃至之后付费、观看广告等等整个生命周期的行为，因此需要一个新的 ID 用来串联登录前与登录后的用户标识，这个 ID 即是热力引擎系统中的用户 ID。

因此热力引擎的用户 ID，是串联起用户全生命周期、跨多端的用户标识 ID，因为涉及到跨端的识别，在热力引擎标识用户的规则中，数据中的账号 ID 的优先级将高于访客 ID 的优先级。

1.1 用户标识

热力引擎系统中以设备 ID、用户 ID、账户 ID、访客 ID 来对用户进行识别

• 设备 ID：SDK 生成的设备唯一 ID, 属性名为 _distinct_id。
• 用户 ID：热力引擎的用户唯一标识, 属性名为 _user_id, 由_account_id 和_visitor_id 按用户识别规则生成。
• 账户 ID：由开发者上报的账户 ID, 属性名为 _account_id。
• 访客 ID：访客 ID, 属性名为 _visitor_id, 优先取值为开发者传入的值, 未传入时取值为 _distinct_id。

1.2 用户识别规则

为方便阅读，下面分别以 user、account、 visitor 指代用户 ID、账户 ID、访客 ID

• 账户 ID 与用户 ID 的绑定优先级高于访客 ID
• 同一个 user 只能绑定 1 个 account、1 个 visitor
• 1 个 account 只能绑定 1 个 user，1 个 visitor 只能绑定 1 个 user

识别规则描述

• 当仅含有 account、且 account 已与 user 绑定时，则本数据归属于已绑定的 user
• 当仅含有 account、且 account 未与已有 user 绑定时，则创建新 user 并绑定
• 当仅含有 visitor、且 visitor 已与 user 绑定时，则本数据归属于已绑定的 user
• 当仅含有 visitor、且 visitor 未与已有 user 绑定时，则创建新 user 并绑定
• 当同时含有 account 与 visitor、且 account 已与 user 绑定时，不修改 account 的绑定关系，且本数据归属于 account 已绑定的 user，再检查 visitor 与已有数据的绑定情况：
• 当 visitor 已与某 user 绑定时，visitor 的绑定关系不做修改
• 当 visitor 未与任何 user 绑定时，再检查与 account 绑定的 user 是否有 visitor：
• user 已有 visitor，则该 visitor 不与任何 user 做绑定
• user 没有 visitor，将该 visitor 与当前 account 绑定的 user 进行绑定
• 当同时含有 account 与 visitor、且 account 未与已有 user 绑定时，则检查 visitor 与已有数据的绑定情况：
• 当 visitor 已与 user 绑定、且绑定的 user 已绑定 account 时，则创建新 user 并将当前 account 与新建 user 进行绑定
• 当 visitor 已与 user 绑定、且绑定的 user 未绑定 account 时，则本数据中 account 绑定到 visitor 绑定的 user
• 当 visitor 未与 user 绑定时，则创建新 user 并将当前 account 与 visitor 与新建 user 进行绑定

2.用户属性

在实际的分析场景中，我们发现，单纯的用户 ID 只能满足简单的用户数量的统计，而客户往往需要的是更加深入的用户分析维度。例如：如何按照某一个用户的属性或者特征来分拆分析用户的行为。

因此热力引擎提供了用户属性的概念，允许用户上报用户相关的用户属性，并支持在分析模型中使用用户属性来进行业务分析。

建议客户将与用户相关的不变的、或变化频率比较低、或保存价值比较高的属性，比如年龄、创建角色时间、等级、所在地、首次付费时间、总付费金额等属性设置为用户属性，其它变化频率比较高的属性通过事件进行上报和记录。

用户属性分为预置用户属性和自定义用户属性。

2.1 预置用户属性

系统默认采集的用户属性字段请参考如下：

2.2 自定义用户属性

客户可以根据自己的业务场景进行个性化定义，比如用户等级、年龄、创建角色时间、首次付费时间、总付费金额等属性设置为自定义用户属性；建议同步更新在埋点采集方案中，方便内部统一数据采集口径。

自定义用户属性上报数据格式与数据类型确定关系表：（与事件属性上报格式标准相同）

3.如何定义设备

很多场景下，我们的客户的应用中，并不会强制要求用户登录，用来标识设备的设备 ID 即是访问用户 ID。在无注册体系或很少有多设备登录情况的产品中可以使用设备 ID（_distinct_id）来作为用户唯一标识，比如 IAA 行业休闲游戏没有登录系统，我们可以直接使用设备 ID 作为用户唯一识别标识。

基于上述场景，热力引擎目前推出了设备表的功能，实时更新设备 ID 级别的设备属性以及广告侧渠道标签。

设备ID（_distinct_id）生成规则请参考如下：

3.1 设备表

当一个设备首次产生事件时，设备表中会实时加入该设备 ID 和此事件的属性作为该设备的信息

每日 02:00 设备表会更新前一天新增设备的属性值，每个属性值以最晚上报的不为空的属性值为准

3.2 设备表应用

设备表同步到热力引擎平台后，当主体为 _distinct_id 时，可以使用配置表中设备表属性，以下三个模块场景可使用设备表属性：

• 模块一：自定义分析

自定义分析模型支持设备属性的筛选与分组

用户分析新增支持以设备维度作为用户进行分析统计

• 模块二：在线参数

当分流主体是 _distinct_id 时，受众用户筛选条件支持配置表中设备表属性

• 模块三：A/B 测试

当分流主体是 _distinct_id 时，受众用户筛选条件支持配置表中设备表属性

4.如何定义事件

用户行为数据，即事件（event），指用户操作产品(APP/小程序/网页等）的一个行为，即用户在产品内做了什么事情，转义成描述性语言就是“对象+操作”。

代表用户在系统中发生过的行为，包括注册、启动、登录、查看内容、购买、战斗、换角、消耗等，都可以理解为是事件。有些事件在一个用户的生命周期里只会发生一次，比如注册账号事件；而大多数事件在用户生命周期里会发生多次，比如启动 App，查看变现广告、产生购买等等。

一个完整的事件应该包含以下几个方面：

• Who ：描述用户的信息，如：用户ID（访问 or 登录）。
• When ：该事件发生的实际时间。
• Where ：该事件发生的地点。
• How：即用户从事这个事件的方式。这个概念就比较广了，包括用户使用的设备信息、使用的浏览器、使用的 App 版本、操作系统版本、渠道来源等，使用者也可以根据自己的需要来增加相应的自定义属性。

一个用户从创建之后会发生很多的事件，这些事件是独立的，可以按时间顺序排列的，多个事件具有明确的线性特征；而一个用户创建之后，这个用户的属性在同一时刻仅有一条记录，具有唯一性的特征。

事件数据存于事件表、用户数据存于用户表，之间通过 用户 ID 进行关联。

4.1 事件类型

按照事件采集方式的不同，可以将SE平台支持上报事件分为两大类：预置事件和埋点事件。

我们SDK上报目前针对APP端默认采集预置事件包括：APP启动，APP退出，APP安装。

此外还提供了自定义事件采集， 比如针对用户加购行为的分析，我们可以通过埋点采集方式上报 “点击加入购物车按钮” 这个事件，从而统计该事件触发用户的UV，PV等。

4.1.1 预置事件

预置事件是指用户无需额外开发任何代码，通过集成热力引擎SDK ，自动采集生成的事件。

我们SDK上报目前针对APP端默认采集预置事件包括：APP启动，APP退出，APP安装。

4.1.2 埋点事件

在很多业务分析场景中，仅有预置事件无法满足用户的分析需求；热力引擎支持用户根据自身监测需求上报事件，系统支持热力引擎SDK或API两种上报方式报送到数据平台，我们统称此类事件为埋点事件。在SE系统中，埋点事件的行为层级关系和预置事件一致。

埋点事件分为预定义事件，自动采集事件和自定义事件。

预定义事件

1）变现广告展示事件

App内变现广告展示时，报送该事件，用于进行广告展示及变现收入分析。

使用ROI分析功能、自定义分析变现指标时，为必须报送事件。

广告展示事件的 _event_name 为 _appImp

2）变现广告点击事件

用户点击变现广告时报送上报。

广告点击事件的 _event_name 为 _appClick

3）应用内购买事件

App 内付费购买时，报送该事件，用于进行购买及内购收入分析。

该事件为用于付费预测模型训练的关键事件，使用系统提供的预测服务时，为必须报送事件。

应用内购买事件的 _event_name 为 _appPur

4）订单事件

用户产生订单时上报。

订单事件的 _event_name 为 _appOrder

5）注册事件

用户产生注册行为时上报。

注册事件的 _event_name 为 _appReg

6）登录事件

用户产生登录行为时上报。

登录事件的 _event_name 为 _appLogin

7）上报自归因事件

增加归因安装事件，支持统计归因数据，满足客户使用三方归因或者自归因之后的结果数据回传到自定义分析，上报时机支持开发者自定义触发

自归因事件的 _event_name 为 _appAttr

自动采集事件

开发者可以在 SDK 初始化时设置自动采集，自动采集包含浏览和点击事件：

1）APP浏览页面事件 _appViewScreen

2）APP元素点击事件 _appElementClick

自定义事件

除了以上已经列出的有行业明确定义的事件外，开发者可以根据自己的分析需求，进行自定义事件的上报。

自定义事件，即事件的 _event_name 由开发者自定义。

事件名称要求：

• 只能以字母开头，不能以下划线开头，其余字符可包含数字、小写字母和下划线 "_"
• 长度最大为 40 个字符
• 仅支持小写字母

5.事件属性

事件属性类型

• 通用事件属性： SDK 上报通用事件属性
• 公共事件属性：由开发者创建的属性，公共属性会在后续上报的事件中自动加入
• 预定义事件特定属性：开发者调用预定义事件上报时必须传入的特定属性
• 自动采集事件特定属性：开启 SDK 自动采集时，浏览事件和点击事件包含的属性
• 自定义事件属性：由开发者创建的属性，在事件上报时加入到事件中一并上报

5.1 通用事件属性

5.2 自定义事件属性

当开发者按分析需求，需要在埋点中增加一些自定义属性时，可以按各端的集成对接文档设置自定义事件属性。

需要注意的是，热力引擎的自定义事件属性的数据类型，会根据该自定义属性首次上报时的格式自动确定，确定之后不能修改。因此在制定埋点方案时，需要您提前了解系统针对各类属性可以提供的分析方法，以便上报的数据可以满足分析目标。

上报数据格式与数据类型确定关系表：

5.3 预定义事件特定属性

预定义事件的事件属性采集包括通用事件属性，用户根据需求自行上报的自定义事件属性以及针对这个预定义事件特定的预定义事件属性。

针对系统中预定义事件特定的预定义属性说明如下

1）变现广告展示事件 _appImp

变现广告展示事件特定的预定义属性请参考如下:

2）变现广告点击事件 _appClick

变现广告点击事件特定的预定义属性请参考如下:

3）应用内购买事件 _appPur

应用内购买事件特定的预定义属性请参考如下:

4）订单事件 _appOrder

订单事件的特定的预定义属性请参考如下:

5）注册事件 _appReg

注册事件的特定的预定义属性请参考如下:

6）登录事件 _appLogin

登录事件的特定的预定义属性请参考如下:

7）上报自归因事件 _appAttr

自归因事件的的特定的预定义属性请参考如下:

5.4 自动采集事件特定属性

自动采集事件的事件属性采集包括通用事件属性，用户根据需求自行上报的自定义事件属性以及针对此事件特定的预定义事件属性。

针对系统中自动采集事件特定的预定义属性说明如下

1）APP浏览页面事件 _appViewScreen

APP浏览页面事件特定的预定义属性请参考如下:

2）APP元素点击事件 _appElementClick

APP元素点击事件特定的预定义属性请参考如下:

5.5 首日首次事件属性

在行为分析中，我们可能会关注一些用户新增首日的事件的指标、或新增后某些事件首次发生的指标，为了方便分析，每一个事件都会被打上是否首日事件、是否首次事件的标识，如下：

• 首日事件

即安装日当日发生的全部事件，非首日发生的事件不算做首日事件。

在事件中以 _is_first_day 属性进行标识，true 是首日事件，false 为非首日事件。

• 首次事件

即一种事件首次发生的事件，每种事件都会有且仅有一次首次事件，不限定是否在安装首日发生。

在事件中以 _is_first_time 属性进行标记，true 是首次事件，false 为非首次事件。

实际应用中，根据数据报送方式不同、事件种类不同，这两个标记的处理方式也不相同：

可以看到，有一些重要的事件，其首日、首次事件的标记我们在服务端通过用户过往上报的数据进行了赋值修正，来提升这两个标记的可信度。

开发者通过 API 报送数据时，需要自行对这两个值进行准确赋值，同时在行为分析模型中合理使用。

6.埋点采集方案设计

由于用户行为复杂性极高以及针对大量级的行为埋点需要分阶段上线，建议客户内部统一埋点采集方案文档，规范埋点上报操作、保持数据口径的 一致性；

数据上报方式可分为SDK上报或API上报，两者在上报数据上并无本质区别。使用SDK上报时，SDK处理了一部分逻辑，比如APP安装、启动、退出等事件的监控，但如果通过API上报，则全部逻辑需要开发者自行处理上报。

SDK/API对接时按照应用维度对接，不同应用使用不同的appkey。

6.1 埋点方案注意事项

• 确定用户识别体系
• 确定事件，事件属性以及事件触发时机
• 确定用户属性
• 确定埋点上线优先级

6.2埋点命名规范

埋点采集时，自定义事件标识及自定义属性标识必须符合命名要求：不能以下划线开头、不超过40字符，支持小写字母、数字、下划线，不能含空格。

• 属性值类型由首次上报时的格式类型决定，后续上报的只接受相同类型的输入，否则将被记为错误数据，错误属性不会入库。
• 事件标识和属性标识为埋点时研发人员使用，由业务人员或技术人员填写。
• 埋点数据触发时机建议运营与研发人员内部对齐口径后统一填写。