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 预置用户属性

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

属性名	说明	示例	类型
_tenant_id	分区字段，Appkey 归属的租户 ID	157	string
_prokey	分区字段，Appkey 归属的产品 ID	546279e4b8514d56	string
_user_id	热力引擎根据 user 规则生成的标识用户的 ID	90901129412	int
_account_id	业务系统中的系统账号 ID	aid25491084	string
_visitor_id	业务系统中的系统访客 ID	vid8709901241	string
_active_time	激活时间：该用户的第一条数据(含事件和用户属性数据)中的 _ts	2021/9/16 19:13	date
_reg_time	注册时间：该用户的第一条包含账号 ID 的数据(含事件和用户属性数据)中的 _ts	2021/9/16 19:13	date
_update_time	更新时间：收到的最后一条用户数据中的 _ts	2021/9/16 19:13	date
_user_operation	用户操作类型：收到的最后一条用户数据的_userset_type	init	string
_server_time	服务端时间：收到的最后一条用户数据的服务器时间	2021/9/16 19:13	date

2.2 自定义用户属性

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

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

数据类型	说明	示例
数值型-number	数据范围是 -9E15 至 9E15	不带引号的数值，如：1234,12.34
字符型-string	上限 2KB	"dashen","北京"带引号的数值也会被识别为字符
时间型-date	"yyyy-MM-dd HH:mm:ss.SSS"或"yyyy-MM-dd HH:mm:ss"，如需表示日期，可使用"yyyy-MM-dd 00:00:00"	"2021-03-01 12:34:56","2021-03-01 12:34:56.789""2021-03-01 00:00:00"
布尔型-boolean	true 或 false	true,false带引号的 true 或 false 会被识别为字符
列表型-array	列表中的元素都会转变为字符串类型	["a","1","true"]

3.如何定义设备

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

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

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

平台	（_distinct_id）设备ID取值逻辑
Android	默认取值：android_id 如果 android_id 取值失败则取 UUID
iOS	默认取值：idfv，加密如果 idfv 取值失败则取 UUID

3.1 设备表

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

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

属性名	说明	示例	类型
_tenant_id	Appkey 归属的租户 ID	1fca0a4b93fa7170	string
_prokey	Appkey 归属的产品 ID	540c8f9f1519f770	string
_appkey	管理后台应用的 16 位 Appkey与roi设备表中的attribution_app_id是一个含义	546279e4b8514d56	string
_distinct_id	设备 ID，_android_id/_idfv/cookie_id/openid	3e4416a9d42f4566	string
_uuid	Android 系统初始化时通过系统 API 生成的 UUID	99ae3a5b-750c-4f5f-aeb9-f128ab8a0ea0	string
_idfa	iOS 设备的 IDFA	1e2dfa89-496a-47fd-9941-df1fc4e6484a	string
_idfv	iOS 设备的 IDFV	599f9c00-92dc-4b5c-9464-7971f01f8370	string
_imei	Android 设备的 IMEI	8.61886E+14	string
_imei2	Android 设备的 IMEI	8.61886E+14	string
_gaid	Android 设备的 GAID	bd4b382b-2eeb-4aea-90c4-02b7f28a04b3	string
_oaid	Android 设备的 OAID	fdebebfd-c64f-e6c5-7eea-b7f73da79380	string
_android_id	Android 设备 AndroidID	55ae62239e982d88	string
_meid	Android 设备 MEID	0cf091d3-83da-42df-9b23-a05bdc9cce7a	string
_mac			string
_ua	设备 UA 信息	Mozilla/5.0 (iPhone; CPU iPhone OS 13_3_1 like Mac OS X)	string
_active_time	激活时间_ts(第一条数据时间)	06:34.7	DateTime64
_update_time	最后更新时间	08:02.9	DateTime64
_server_time	最后服务端时间	45:13.7	DateTime64
_db_time	入库时间	1.662E+12	Int64
_language	用户设备设置的语言	zh-han	string
_time_zone	用户设备设置的时区	GMT+08:00	string
_manufacturer	用户设备的制造商，如 Apple，vivo 等	Apple	string
_platform	平台，枚举值： 0：Other 1：Android 2：iOS 3：Windows 4：Mac 5：Web 6：WeChat	2	number
_os_version	最细粒度的系统版本号，如 iOS 14.3.1、Android 10.0.0 等	14.3.1	number
_screen_width	用户设备的屏幕宽度	1080	number
_screen_height	用户设备的屏幕高度	1920	number
_density	用户设备的像素密度	2.62	number
_device_model	最细粒度的设备型号标识，如 iPhone9,1 ， M2102J2SC 等	iPhone9,1	string
_device_type	用户的设备类型，枚举值： 0：Other 1：Android Phone 2：Android Pad 3：iPhone 4：iPad 5：Mac 6：PC	3	number
_app_version	App 的版本	1.0.10.404	string
_app_version_code	App Build 版本号	819	string
_package_name	App 包名或者进程名	com.aike.dashenguilai.ad	string
_app_name	系统中应用的名称	指上谈兵	string
_channel	渠道包名称，iOS 默认值为 AppStore	AppStore	string
_ip	ip 地址	1.119.176.34	string
_ipv6		392c:3e1:5158:f0ac:92ae:ed3:e852:4d42	string
_country	国家	CN	string
_country_code	国家二字码	CN	string
_province	省份	bj	string
_city	城市	beijing	string
attribution_platform	归因平台		string
promotion_platform	投放平台		string
promotion_account_id	投放账号id		string
promotion_account_name	投放账号名		string
campaign_name	campaign 名称		string
campaign_id	campaign id		string
offer_name	offer 名称		string
offer_id	offer id		string
creative_name	creative 名称		string
creative_id	creative id		string
sub_channel	子渠道		string
cost_amt	投放成本		double
monetization_platform_list	变现平台	["kuaishou","toutiao","mintegral"]	array
iap_revenue_amt_total	内购收益-总
iap_revenue_amt_h0	内购收益-H0
iap_revenue_amt_d0	内购收益-D0
iap_revenue_amt_d1	内购收益-D1
iap_revenue_amt_d3	内购收益-D3
iap_revenue_amt_d7	内购收益-D7
iap_revenue_amt_d14	内购收益-D14
iap_revenue_amt_d30	内购收益-D30
iap_revenue_amt_d60	内购收益-D60
all_estimate_revenue_amt_total	预估广告收益-总
all_estimate_revenue_amt_h0	预估广告收益-H0
all_estimate_revenue_amt_d0	预估广告收益-D0
all_estimate_revenue_amt_d1	预估广告收益-D1
all_estimate_revenue_amt_d3	预估广告收益-D3
all_estimate_revenue_amt_d7	预估广告收益-D7
all_estimate_revenue_amt_d14	预估广告收益-D14
all_estimate_revenue_amt_d30	预估广告收益-D30
all_estimate_revenue_amt_d60	预估广告收益-D60
all_real_revenue_amt_total	实际广告收益-总
all_real_revenue_amt_h0	实际广告收益-H0
all_real_revenue_amt_d0	实际广告收益-D0
all_real_revenue_amt_d1	实际广告收益-D1
all_real_revenue_amt_d3	实际广告收益-D3
all_real_revenue_amt_d7	实际广告收益-D7
all_real_revenue_amt_d14	实际广告收益-D14
all_real_revenue_amt_d30	实际广告收益-D30
all_real_revenue_amt_d60	实际广告收益-D60
monetization_properties	包含设备相关的收益指标：区分变现平台预估收益区分变现平台真实收益		map

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安装。

事件名称	事件标识符	触发时机
安装事件	_appInstall	每次安装后首次打开自动报送该事件
启动事件	_appStart	应用每次打开、或停留在后台超过30s再次进入前台时，自动报送该事件
退出事件	_appEnd	应用每次退出、或停留在后台超过30s时，自动报送该事件

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 通用事件属性

属性名	说明	示例	类型
_tenant_id	Appkey 归属的租户 ID	1fca0a4b93fa7170	string
_prokey	Appkey 归属的产品 ID	540c8f9f1519f770	string
_appkey	管理后台应用的 16 位 Appkey	546279e4b8514d56	string
_source_type	数据来源，SDK 默认传 sdk	sdk	string
_event_name	事件标识	_appInstall	string
_event_name	事件标识	_appInstall	string
_user_id	系统分配的唯一 ID，入库时生成	6.21562E+18	Int64
_account_id	业务系统中的系统账号 ID，由开发者端赋值	aid25491084	string
_visitor_id	系统访客 ID 未自定义 _visitor_id 值时系统会以 _distinct_id 填充	vid8709901241	string
_session_id	启动 ID，即从一次启动开始到启动结束(即退出)的标识 App ：冷启动时生成，进程销毁时结束 Web ：打开网站时生成，当前网站关闭后结束 WeChat ：冷启动（首次启动/销毁重启）时生成，进程销毁时结束	3e4a4f9d2258cc41ee86dd09132bc61c	string
_event_id	SDK 端生成的用于标识数据唯一性的 ID	56e3704cf535e5e6dccdc421e37b201e	string
_event_time	事件时间,相当于数据中的 _ts 字段，入库时补充	21:11.8	DateTime64
_server_time	服务端收到数据的时间，服务端补充	21:12.5	DateTime64
_db_time	入库时间，入库时生成	1.662E+12	Int64
_ds	事件发生的日期, 入库时由 _event_time 转化	2022/11/19	date
_ts	数据产生时的13位时间戳	1.63179E+12	long
_idfa	iOS 设备的 IDFA	1e2dfa89-496a-47fd-9941-df1fc4e6484a	string
_idfv	iOS 设备的 IDFV	599f9c00-92dc-4b5c-9464-7971f01f8370	string
_uuid	Android 系统初始化时通过系统 API 生成的 UUID，iOS 不传	99ae3a5b-750c-4f5f-aeb9-f128ab8a0ea0	string
_imei	Android 设备的 IMEI	8.61886E+14	string
_imei2	Android 设备的 IMEI	8.61886E+14	string
_gaid	Android 设备的 GAID	bd4b382b-2eeb-4aea-90c4-02b7f28a04b3	string
_oaid	Android 设备的 OAID	fdebebfd-c64f-e6c5-7eea-b7f73da79380	string
_android_id	Android 设备 AndroidID	55ae62239e982d88	string
_ua	设备 UA 信息	Mozilla/5.0 (iPhone; CPU iPhone OS 13_3_1 like Mac OS X)	string
_language	用户设备设置的语言	zh-han	string
_time_zone	用户设备设置的时区	GMT+08:00	string
_manufacturer	用户设备的制造商，如 Apple，vivo 等	Apple	string
_platform	平台，枚举值： 0：Other 1：Android 2：iOS 3：Windows 4：Mac 5：Web 6：Wechat	2	number
_os_version	最细粒度的系统版本号，如 iOS 14.3.1、Android 10.0.0 等	14.3.1	string
_resolution	分辨率，目前不采集		string
_screen_width	用户设备的屏幕宽度	1080	number
_screen_height	用户设备的屏幕高度	1920	number
_density	用户设备的像素密度	2.62	number
_device_model	最细粒度的设备型号标识，如 iPhone9,1 ， M2102J2SC 等	iPhone9,1	string
_device_name	设备的名称	iPadAir2	string
_device_type	用户的设备类型，枚举值： 0：Other 1：Android Phone 2：Android Pad 3：iPhone 4：iPad 5：Mac 6：PC	3	number
_network_type	上传数据时的网络状态，枚举值： 0：无网络 1： unknown 2：2G 3：3G 4：4G 5：5G 6：6G或下一代网络 9： WIFI	4	number
_carrier	网络运营商名		string
_app_version	App 的版本	1.0.10.404	string
_app_version_code	App Build 版本号	819	string
_package_name	App 包名或者进程名	com.aike.dashenguilai.ad	string
_app_name	系统中应用的名称	指上谈兵	string
_channel	渠道包名称，iOS 默认值为 AppStore	AppStore	string
_lib	接入的 SDK 类型，枚举值： 0：Other 1：Android 2：iOS 3：Js 4：小程序 5：小游戏 6：快应用	2	number
_lib_version	接入的 SDK 的版本	1.6.6	string
_duration	事件时长，单位：毫秒，AppEnd 事件时有值需要调用计时功能接口 timeEvent，记录事件发生时长	1280	number
_is_first_day	首日事件标记，安装首日的全部事件均为 true，非安装日的全部事件均为 false true：是首日事件 false：非首日事件	true	boolean
_is_first_time	首次事件标记，仅每种事件的首次事件为 true，不限定首次是否在首日发生 true：是首次事件 false：非首次事件	true	boolean
_browser	使用的浏览器类型，如 Chrome，Firefox 等	Chrome	string
_browser_version	使用的浏览器的版本，如 Chrome 61.0，Firefox 57.0 等	Chrome 61.0	string
_page_title	当前页面的标题 Android：Activity 的 android：label 属性值 iOS：ViewController 的 title 或 titleView 上的文本信息 Web：页面标题小程序：页面标题	购物车	string
_page_name	当前页面的地址 Android：Activity 或 Fragment 对应的包名、类名 iOS：ViewController 的类名 Web：页面地址小程序：页面地址	com.aike.dashenguilai.android.cart	string
_referrer_title	跳转前页面的标题	首页	string
_referrer_name	跳转前页面的地址	com.aike.dashenguilai.android.index	string
_log_count	事件类数据的单日递增序号，用于统计事件丢包情况	25	number
_distinct_id	用户设备ID iOS：保存到钥匙链的 IDFV Android：保存到路径的 AndroidID Web：cookie_id （通过当前时间戳+屏幕宽高+uuid随机数+UA 值 md5 后生成）保存在用户的浏览器的 cookie 中 WeChat：openid App 和 WeChat 的兜底取值：uuid + 当前时间 13 位时间戳	35f06a1106cd442d	String
_distinct_id_type	当 _distinct_id 为默认取值时该值为 1001 当 _distinct_id 为兜底取值时该值为 1002 当 _distinct_id_type 为自定义值时该值为 1003	1001	Decimal
_distinct_index	创建分群/人群包的索引，加速查询	1.24125E+12	Int64
_is_attr	是否自主归因，自助归因1，非自主归因0 true：1 fales：0	0	boolean
_adnetwork	投放广告的渠道 ID	toutiao	string
_sub_channel	投放广告的子渠道	103300	string
_adaccount_id	投放广告的投放账号 ID	1.65596E+15	string
_adaccount_name	投放广告的投放账号名称	xxx科技全量18	string
_adcampaign_id	投放广告的广告计划 ID	1.68071E+15	string
_adcampaign_name	投放广告的广告计划名称	小鸭快冲计划157-1024	string
_adoffer_id	投放广告的广告单元 ID	1.68522E+15	string
_adoffer_name	投放广告的广告单元名称	小鸭快冲单元406-1024	string
_adcreative_id	投放广告的广告创意 ID	1.68013E+15	string
_adcreative_name	投放广告的广告创意名称	自动创建20210901178921	string
_ad_platform	变现平台，前面为应传值，后面为平台名称 csj：穿山甲国内版 pangle：穿山甲国际版 tencent：腾讯优量汇 baidu：百度百青藤 kuaishou：快手 oppo：OPPO vivo：vivo mi：小米 huawei：华为 applovin：Applovin sigmob：Sigmob mintegral：Mintegral oneway：OneWay vungle：Vungle facebook：Facebook admob：AdMob unity：UnityAds is：IronSource adtiming：AdTiming klein：游可赢 fyber：Fyber chartboost：Chartboost adcolony：Adcolony	csj	string
_mediation_platform	填充广告的聚合平台 gromore topon 未使用聚合平台时传 custom	gromore	string
_ad_appid	变现平台的应用 ID	a603f46266d902	string
_placement_id	聚合平台的广告版位 ID		string
_ad_id	变现平台的变现广告位 ID	943508343	string
_ad_id	变现平台的变现广告位 ID	943508343	string
_ad_type	本次展示广告的类型 1：激励视频 2：开屏 3：插屏 4：全屏视频 5：Banner 6：信息流 7：短视频信息流 8：大横幅 9：视频贴片 10：其它	1	string
_bid_type	是否是 Header Bidding	0	string
_ad_ecpm	本次广告展示的 ecpm，单位：元	1.2206	number
_currency_type	展示收益的货币种类，遵循《ISO 4217国际标准》，如 CNY、USD	CNY	string
_is_rendered	广告是否渲染成功，无需统计时请传 true true：1 false：0	1	number


_order_id	本次购买由系统生成的订单 ID	2.02111E+21	string
_order_id	本次购买由系统生成的订单 ID	2.02111E+21	string
_pay_amount	本次购买支付的金额，单位：元	128	number
_pay_amount	本次购买支付的金额，单位：元	128	number
_pay_type	支付方式：如 alipay、weixin、applepay、paypal 等	alipay	string
_pay_type	支付方式：如 alipay、weixin、applepay、paypal 等	alipay	string
_product_id	购买商品的ID	1700923511	string
_product_name	商品名称	礼包 1	string
_product_num	购买商品的数量	1	number
_pay_status	支付状态 1：success成功 2：fail失败 3：restored恢复	1	string
_abgroup_id	ABTest 中的试验 ID		string
_abexp_id	ABTest 中的版本 ID		string
_bool_properties	通过 properties 解析对应类型属性		Map
_str_properties	通过 properties 解析对应类型属性		Map
_dec_properties	通过 properties 解析对应类型属性		Map
_arr_properties	通过 properties 解析对应类型属性		Map
_date_properties	通过 properties 解析对应类型属性		Map
_fail_reason	失败原因	BANK_ERROR	string
_reg_type	for tkio:注册类型，如 WeChat、QQ 等自定义值	WeChat	string
_login_type	for tkio:登录类型，如 WeChat、QQ 等自定义值	WeChat	string
_status	for tkio:对应事件中用户行为的完成状态	success	string
_status	for tkio:对应事件中用户行为的完成状态	success	string
_attribution_platform
_ip	ip 地址，优先使用客户端传入值，其次通过 header 解析	1.119.176.34	string
_country	国家，根据 IP 解析	CN	string
_country_code	国家二字码，根据 IP 解析	CN	string
_province	省份，根据 IP 解析	bj	string
_city	城市，根据 IP 解析	beijing	string
_ipv6		392c:3e1:5158:f0ac:92ae:ed3:e852:4d42	string
_page_host	页面地址域名	例如 xxx.com/a/a.action?id=123 取值为 xxx.com/a/a.action	string
_referrer_host	前向地址域名	例如 xxx.com/a/a.action?id=123 取值为 xxx.com/a/a.action	string
_element_id	元素ID	元素有 id 属性时采集：abc	string
_element_content	元素内容	元素标签对直接的文本，例如：<a><span>提交</span></a>，采集的是 “提交”，内容为图片时采集不到	string
_element_content	元素内容	app端控件代码内设置的元素内容，如果一个控件中没有设置元素内容，或者控件类型为图片	string
_element_name	元素名字	元素有 name 属性时采集	string
_element_class_name	元素样式名	元素有 class 属性时候采集	string
_element_type	元素类型	控件的类型，例如 Button	string
_element_target_url	元素链接地址	a 标签采集地址	string
_launch_scene	小程序启动场景 ID	场景值列表	number
_combination_id	配置中的组合 ID，未获取到该值时为 null	6b86b273ff34fce19d6b804eff5a3f5747ada4eaa22f1d49c01e52ddb7875b4b	string
_group_id_list	配置中的组 ID，未获取到该值时为 null	"124","431","412"	Array(String)
_enter_group_id	用户进入的分组 ID,由服务端解析，如果请求的是默认参数或当前请求的参数不在配置文件中，此值会为 null，sdk需要和服务端约定个字段传值	0	number
_enter_group_status	用户(设备)进入分组时的状态		number
_experiment_id	试验ID		string
_experiment_group_id	试验分组ID		string
_experiment_group_id_list	试验分组ID列表		Array(String)
_experiment_status	试验状态，标识是否为调试的设备		decimal
_custom_id	自定义属性ID		Map
_event_custom_id	自定义事件属性ID		Map
_user_custom_id	自定义用户属性ID		Map
_event_type	事件类型		decimal
_report_type	事件类型		decimal

5.2 自定义事件属性

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

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

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

数据类型	说明	示例
数值型-number	数据范围是 -9E15 至 9E15	不带引号的数值，如：1234,12.34
字符型-string	上限 2KB	"dashen","北京"带引号的数值也会被识别为字符
时间型-date	"yyyy-MM-dd HH:mm:ss.SSS"或"yyyy-MM-dd HH:mm:ss"，如需表示日期，可使用"yyyy-MM-dd 00:00:00"	"2021-03-01 12:34:56","2021-03-01 12:34:56.789""2021-03-01 00:00:00"
布尔型-boolean	true 或 false	true,false带引号的 true 或 false 会被识别为字符
列表型-array	列表中的元素都会转变为字符串类型	["a","1","true"]

5.3 预定义事件特定属性

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

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

1）变现广告展示事件 _appImp

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

属性名	说明	示例	类型	限制
_ad_platform	变现平台，前面为应传值，后面为平台名称 csj：穿山甲国内版 pangle：穿山甲国际版 tencent：腾讯优量汇 baidu：百度百青藤 kuaishou：快手 oppo：OPPO vivo：vivo mi：小米 huawei：华为 applovin：Applovin sigmob：Sigmob mintegral：Mintegral oneway：OneWay vungle：Vungle facebook：Facebook admob：AdMob unity：UnityAds is：IronSource adtiming：AdTiming klein：游可赢 fyber：Fyber chartboost：Chartboost adcolony：Adcolony	csj	string	必传
_ad_appid	变现平台的应用 ID	5043562	string
_mediation_platform	填充广告的聚合平台gromoretopon未使用聚合平台时传 custom	gromore	string	必传
_ad_id	变现平台的变现广告位 ID	943508343	string	必传
_ad_type	本次展示广告的类型 1：激励视频 2：开屏 3：插屏 4：全屏视频 5：Banner 6：信息流 7：短视频信息流 8：大横幅 9：视频贴片 0：其它	1	number	必传
_ad_ecpm	本次广告展示的ecpm，单位：元	34.00	number	必传
_currency_type	展示收益的货币种类，遵循《ISO 4217国际标准》，如 CNY、USD	CNY	string	必传
_is_rendered	广告是否渲染成功，无需统计时请传 truetrue：成功false：失败	true	boolean	必传

2）变现广告点击事件 _appClick

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

属性名	说明	示例	类型	限制
_ad_platform	变现平台，前面为应传值，后面为平台名称 csj：穿山甲国内版 pangle：穿山甲国际版 tencent：腾讯优量汇 baidu：百度百青藤 kuaishou：快手 oppo：OPPO vivo：vivo mi：小米 huawei：华为 applovin：Applovin sigmob：Sigmob mintegral：Mintegral oneway：OneWay vungle：Vungle facebook：Facebook admob：AdMob unity：UnityAds is：IronSource adtiming：AdTiming klein：游可赢	csj	string	必传
_mediation_platform	填充广告的聚合平台 gromore topon 未使用聚合平台时传 custom	gromore	string	必传
_ad_id	变现平台的变现广告位 ID	943508343	string	必传
_ad_type	本次展示广告的类型 1：激励视频 2：开屏 3：插屏 4：全屏视频 5：Banner 6：信息流 7：短视频信息流 8：大横幅 9：视频贴片 10：其它	1	number	必传

3）应用内购买事件 _appPur

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

属性名	说明	示例	类型	限制
_order_id	本次购买由系统生成的订单 ID	2021111918032157001921	string	必传
_pay_amount	本次购买支付的金额，单位：元	128.00	number	必传
_currency_type	支付的货币各类，遵循《ISO 4217国际标准》，如 CNY、USD	CNY	string	必传
_pay_type	支付方式：如 alipay、weixin、applepay、paypal 等	alipay	string	必传
_product_id	购买商品的ID	1700923511	string	必传
_product_name	商品名称	礼包 1	string	必传
_product_num	购买商品的数量	1	number	必传
_pay_status	支付状态 1：success成功 2：fail失败 3：restored恢复	1	number	必传
_fail_reason	支付失败的原因	BANK_ERROR	string	非必传

4）订单事件 _appOrder

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

属性名	说明	示例	类型	限制
_order_id	订单 ID	2341242342676398724	string	必传；不超过128 字符
_pay_amount	订单金额，单位：元	128.00	number	必传
_currency_type	货币类型，遵循《ISO 4217国际标准》	CNY	string	必传
_pay_type	支付方式：如 alipay、weixin、applepay、paypal 等	Alipay	string	不超过 32 字符
_status	订单状态	success	string

5）注册事件 _appReg

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

属性名	说明	示例	类型	限制
_reg_type	注册类型如 WeChat、QQ 等自定义值	WeChat	string	必传；不超过 32 字符
_status	注册状态	success	string

6）登录事件 _appLogin

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

属性名	说明	示例	类型	限制
_login_type	登录类型如 WeChat、QQ 等自定义值	WeChat	string	必传；不超过32 字符
_status	登录状态	success	string

7）上报自归因事件 _appAttr

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

属性名	说明	示例	类型	限制
_is_attr	是否自主归因 true：是自归因 fales：非自归因	true	boolean	非必传，缺省值 true
_adnetwork	投放广告的渠道 ID，需要与发行平台匹配	toutiao	string	必传
_sub_channel	投放广告的子渠道	103300	string
_adaccount_id	投放广告的投放账号 ID	1655958321988611	string
_adaccount_name	投放广告的投放账号名称	xxx科技全量18	string
_adcampaign_id	投放广告的广告计划 ID	1680711982033293	string
_adcampaign_name	投放广告的广告计划名称	小鸭快冲计划157-1024	string
_adoffer_id	投放广告的广告单元 ID	1685219082855528	string
_adoffer_name	投放广告的广告单元名称	小鸭快冲单元406-1024	string
_adcreative_id	投放广告的广告创意 ID	1680128668901378	string
_adcreative_name	投放广告的广告创意名称	自动创建20210901178921	string
_attribution_platform	监测平台		string	必传

5.4 自动采集事件特定属性

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

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

1）APP浏览页面事件 _appViewScreen

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

属性名	说明
_page_title	当前页面的标题
_page_name	当前页面的地址
_referrer_title	跳转前页面的标题
_referrer_name	跳转前页面的地址
_page_host	页面地址域名
_referrer_host	前向地址域名
_combination_id	配置中的组合 ID，未获取到该值时为 null
_group_id_list	配置中的组 ID，未获取到该值时为 null
_session_id	启动 ID，即从一次启动开始到启动结束(即退出)的标识

2）APP元素点击事件 _appElementClick

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

属性名	说明
_element_id	元素ID
_element_content	元素内容
_element_name	元素名字
_element_class_name	元素样式名
_element_type	元素类型
_element_target_url	元素链接地址
_combination_id	配置中的组合 ID，未获取到该值时为 null
_group_id_list	配置中的组 ID，未获取到该值时为 null
_session_id	启动 ID，即从一次启动开始到启动结束(即退出)的标识

5.5 首日首次事件属性

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

首日事件

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

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

首次事件

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

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

数据报送方式	事件种类	赋值方法	服务端修正
通过热力引擎 SDK	安装、启动、付费、广告展示	SDK 赋值	值为 true 时进行校验修正，值为 false 时不修正
通过热力引擎 SDK	其它事件（含自定义事件）	SDK 赋值	不进行修正，直接保存
通过热力引擎 API	安装、启动、付费、广告展示	开发者赋值	值为 true 时进行校验修正，值为 false 时不修正
通过热力引擎 API	其它事件（含自定义事件）	开发者赋值	不进行修正，直接保存

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

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

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

6.埋点采集方案设计

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

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

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

6.1 埋点方案注意事项

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

6.2埋点命名规范

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

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

数据接入