热力引擎集成方案

TIP

请注意，第三方数据集成产生的数据会被纳入集群的消耗数据量

概要

接口简介

接口名	类型	粒度	归因	成本	收益	展示	点击	转化
实时 API	回传	用户级别	✅					✅

在开始接入热力引擎数据前，请确保您已经阅读 TE 系统用户识别规则，理解 TE 如何通过 #distinct_id 和 #account_id 识别一个用户

热力引擎提供了实时 API 导出功能，支持实时回传激活等事件数据，详情可以参考热力引擎官网文档 (opens new window)

集成流程

1. 接入热力引擎 SDK 与 TE SDK，在调用热云 SDK 注册方法时传入 TE SDK 的访客 ID
2. 登录 TE 后台，进入三方集成模块，新增热云 TrackingIO 集成，完成相关配置，并复制回调地址
3. 将应用的 APP_ID 与 Secret、回调地址以及回调数据类型提供给热云技术人员，热云技术人员将协助您配置数据回传
4. 查看 TE 系统否成功接收数据，并完成报表搭建

一、客户端 SDK 配置

1.1 引入热力引擎 SDK 与 TE SDK

首先，您需要在应用中引入热力引擎 SDK 以及 TE SDK，并完成初始化配置。热力引擎 SDK 与 TE SDK 的接入文档如下：

• 热 (opens new window)力引擎 SDK 文档 (opens new window)
• TE SDK 接入文档 (opens new window)

1.2 进行 SDK 配置

在引入 SDK 后，接下来需要做的就是将 TE SDK 的访客 ID 与账号 ID 设置到热力引擎 SDK 中，我们推荐的做法是使用热力引擎的公共事件属性的设置接口

请注意顺序：

1. 完成 TE SDK 的初始化
2. 获取 TE SDK 的访客 ID
3. 调用热力引擎的设置公共属性接口，将 TE SDK 的访客 ID 设置为热力引擎 SDK 的公共属性
4. 热力引擎 SDK 初始化
5. 当可以获取 TE SDK 的账号 ID 时（即登录账号或角色上线时），调用 TE SDK 的 login 接口，并再次调用热力引擎的设置公共属性接口，将账号 ID 设置为热力引擎 SDK 的公共属性

以下是安卓的代码样例：

// 完成 TE SDK 的初始化
TDAnalytics.init(context, APPID, SERVER_URL);

// 获取 TE SDK 的访客 ID
String te_distinct_id = TDAnalytics.getDistinctId();

// 使用公共事件属性设置接口，将 TE 的访客 ID 设置为热力引擎 SDK 的公共属性
SolarEngineManager.getInstance().setSuperProperties(context, "te_distinct_id",  te_distinct_id);

// 热力引擎 SDK 初始化
SolarEngineConfig config = new SolarEngineConfig.Builder().build(); 
SolarEngineManager.getInstance().initialize(context, "开发者申请的appkey","开发者申请的userId",config);

// .....

// 用户登录后
// 获取账号 ID
String te_account_id = "login_id";

// TE SDK 调用 login
TDAnalytics.login(te_account_id);

// 使用公共事件属性设置接口，将 TE 的账号 ID 设置为热力引擎 SDK 的公共属性
SolarEngineManager.getInstance().setSuperProperties(context,"te_account_id", te_account_id);

二、方案配置

在完成了 SDK 的配置之后，接下来需要您登录 TE 系统后台，在「三方集成」模块中完成热力引擎的配置。下图是热力引擎的配置界面：

2.1 用户识别字段

由于热力引擎回传的是用户级别数据，因此需要为其设置用户识别规则。TE 系统将根据该配置，在转换回传数据时，将这些字段设置为数据中的用户识别字段。

如果您按照本文档上一步进行客户端 SDK 配置，请使用以下配置：

• 账号 ID 关联字段：event_custom_params.te_account_id
• 访客 ID 关联字段：event_custom_params.te_distinct_id
  

2.2 事件表入库设置

打开「事件表入库设置」开关后，回传的数据（包括激活事件和应用内事件）都将写入到事件表中

我们建议您开启事件数据入库。但需要注意，默认情况下，我们会接收所有热力引擎回传的数据。如果回传的事件类型过多，会导致 TE 项目的事件量过度膨胀。因此建议在热力引擎平台设置回传时，只选择必要事件进行回传。

2.3 用户属性入库规则

在默认情况下，TE 系统会自动将热力引擎回传数据中的归因字段写入到标准化处理后的用户属性中，以下是写入用户属性的字段及其含义：

热力引擎字段	标准化字段	说明
channel_name	te_ads_object.media_source	媒体渠道
adplan_name	te_ads_object.campaign_name	广告计划名
adgroup_name	te_ads_object.ad_group_name	广告组名
adcreative_name	te_ads_object.ad_name	广告名

如果需要进行修改，您可以点击「配置规则」进入到入库规则配置页，如下图所示

在此，您可以修改用户属性从哪些事件来。如果您不希望用户属性被频繁写入，可以关闭「包含所有事件」，并将来源事件名修改为 install。这样配置，则 TE 系统只会从热力引擎回传的 install 事件中提取需要写入用户属性的字段并进行写入。入库方式默认是 user_setOnce，也就是只会保留首次上报的信息。

如果您希望关闭用户属性入库，可以停止所有规则：

2.4 集成配置

最后，您可以在集成配置模块对数据拉取的细节配置进行控制，比如入库后的事件名等。

集成配置中的内容是一个 JSON，您可以按照以下内容进行自定义配置：

模块	名称	含义
sink_event	event_mapping	入库后的事件名，可以自定义。Key 为热力引擎的事件名，Value 为入库后的事件名；默认的是激活事件：install

2.5 终端地址

终端地址中展示了 TE 系统接收热力引擎回传数据的地址。

请注意，终端地址中自带了 APP 回传的参数，如果您要回传的是小程序/小游戏的数据，则请参考小程序/小游戏回调参数一节

请您直接复制该地址，在接下来进行回传配置时，请将该地址填入：

若此处无地址没有显示，请进入右上角菜单「项目管理」-「接入配置」-「数据上报地址」处配置公网地址。该地址即 TE SDK 中配置的数据上报地址。配置后再回到热力引擎配置页的「数据源」复制终端地址。

三、在热力引擎完成回调配置

3.1 在热力引擎后台的实时api数据导出页面配置回调链接

在完成 TE 后台的方案创建后，请您登录热力引擎后台，选择您需要回传数据的项目，并从「归因」模块中选择「应用设置」-「数据导出」-「实时api导出」，即可进行热力引擎的实时回传配置

您可以按照以下规则来进行填写：

• 回调类型选择「激活」
• 回调地址填写您在 TE 后台获取到的回传地址
• 回调地址解析，建议您按照 3.2 章节的内容进行填写
• 回调方式，请选择 POST
• 超时时长、重试次数可以按需修改，无特殊需求可以使用默认值

当您完成配置后，点击提交即可

3.2 热力引擎的回调参数

以下展示的是热力引擎回调支持设置的参数，我们建议您在配置时，填入的参数名称与所选值保持一致，您可以从下表中获取所有我们推荐回传的字段，请注意一定要回传 event_name、event_time 与 event_custom_params 字段，否则数据可能转换失败

3.2.1 App 回调参数

参数名	默认使用	值（举例）	说明
event_type	是	枚举值： preset，custom	是否预制事件
event_name	是	事件名称：install，startup，etc...	事件名称
attribution_time	是	2023/7/1 22:47	归因时间
attribution_touch_type	是	click	归因触点类型
attribution_method	是	枚举值： deviceid fingerprint	归因方法
attribution_lbw		86400	归因时间窗
attribution_ttit		68	归因时间差
channel_name	是	Mintegral	归因的渠道名称
app_name	是	Cat EscapeInfinity	APP名称
appkey	是		appkey
app_platform	是	ios	app的平台
landing_page_url		[https://apps.apple.com/us/app/cat-escape-infinity/id6445884698](https://apps.apple.com/us/app/cat-escape-infinity/id6445884698)	app落地页地址
turl_id		Ev2Evya	监测链接短链ID
turl_string			监测链接短链
turl_campaign_id	是	7b35b6bd982780f729fcf4ff925b9c4e	监测链接唯一ID
turl_campaign_name	是	躲猫猫无尽版-IOS	监测链接名称
channel_id	是	8221	监测链接对应的渠道ID
ry_touchpoint_ts	是	1688222783854	展点时间
attribution_type	是	ua	归因类型（写死UA拉新）
account_id	是		投放账号ID
adgroup_id	是		投放平台广告组ID
adgroup_name	是	CatEscapeInfinity_CN_FO_0404_WX_iOS_MTG_1	投放平台广告组名称
adplan_id	是	ss_Duomm_CN_FO_0404_WX_iOS_MTG_1	投放平台广告计划ID
adplan_name	是		投放平台广告计划名称
adcreative_id	是	1804913040	投放平台广告素材ID
adcreative_name	是	wadmm_21186_0_V_1203_mtg_nndb_cn_1024x768_cy.mp4	投放平台广告素材名称
adcreative_type	是		投放平台广告素材类型
site_id	是	mtg1183741824	投放平台子渠道ID
site_name	是		投放平台子渠道名称
ad_type	是		投放平台广告类型
placement_id	是		投放平台广告位id
conversion_id			投放平台接收转化的唯一ID
click_id		mtg64a03bfe52979a0001a8cb4y	投放平台点击唯一ID
impression_id			投放平台展示唯一ID
request_id		7434D04B787321D534C7268DD8D4D52E	投放平台请求唯一ID
callback_id			投放平台回调唯一ID
callback_url			投放平台回调地址
custom_params_1			投放平台自定义参数数据1-10
custom_params_2			投放平台自定义参数数据1-10
custom_params_3			投放平台自定义参数数据1-10
custom_params_4			投放平台自定义参数数据1-10
custom_params_5			投放平台自定义参数数据1-10
custom_params_6			投放平台自定义参数数据1-10
custom_params_7			投放平台自定义参数数据1-10
custom_params_8			投放平台自定义参数数据1-10
custom_params_9			投放平台自定义参数数据1-10
custom_params_10			投放平台自定义参数数据1-10
device_id	是	B9BBB98D-FFEE-448D-A9BE-52883FF230FD	归因设备唯一ID
device_id_type	是	distinct_id	distinct_id
device_id_md5_type		distinct_id_md5	distinct_id_md5
device_id_md5		55a6187afabbe2ed4c6e9bc0fdca423d	归因设备唯一ID的md5
gaid			gaid
gaid_md5			gaid_md5
imei1			imei1
imei1_md5			imei1_md5
imei2			imei2
imei2_md5			imei2_md5
oaid			oaid
oaid_md5			oaid_md5
mac			mac
mac_md5			mac_md5
android_id			android_id
android_id_md5			android_id_md5
idfa		49BB9C2F-E0DB-46B8-9C68-21C4C7FB30CC	idfa
idfa_md5		1225a829ea48f2fc62a2d3faee263829	idfa_md5
idfv		B9BBB98D-FFEE-448D-A9BE-52883FF230FD	idfv
idfv_md5		55a6187afabbe2ed4c6e9bc0fdca423d	idfv_md5
ipv4		110.154.208.22	ipv4
ipv6			ipv6
ua	是	Mozilla/5.0 (iPad; CPU OS 14_2 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) Mobile/15E148	ua
manufacturer	是	apple	品牌
model	是	iPad11,6	机型
os	是	枚举值 1：安卓 2：ios	系统
os_version	是	14.2	版本
ua_device_type		iPad	ua解析的设备类型
ua_os		IOS	ua解析的系统
ua_osv		14.2	ua解析的os version
language	是	zh-Hans-CN	语言
country	是	CN	国家
city	是		城市
att_status		枚举值： denied、restricted、authorized、unknown、空
lat_status		枚举值： enable、disable、unknown、空
network_type	是	枚举值： 0：无网络 1：unknown 2：2G 3：3G 4：4G 5：5G 6：6G或下一代网络 9：WIFI	上传数据时的网络状态
carrier	是		运营商
install_time		1688222848242	激活时间
event_time	是	1689781058000	服务端收到事件时间
channel_package_name		default	渠道包名称
app_version	是	1.0.2	app版本
bundleid	是	jp.os.catescape	app bundle id
event_data	是
collector_version		1.1.8.0	sdk版本
integration_type		枚举值： sdk api s2s	对接方式
event_custom_params	是	客户的自定义事件属性内容
caid		事件的caid值
caid_md5		事件caid的md5值
event_account_id		事件的account_id

3.2.2 小程序/小游戏回调参数

如果需要接入的是小程序或小游戏，那么请使用以下回调地址，请将上报地址替换 {receiver-host}，用项目的 APP ID 替换以下的 {app-id}：

https://{receiver-host}/attribution/callback/solarengine/{app-id}?appkey=appkey&app_name=app_name&app_platform=app_platform&app_type=app_type&event_name=event_name&country=country&event_time=current_event_time&channel_name=channel_name&os=os&os_version=os_version&brand=brand&model=model&ua=ua&user_id=user_id&account_id=account_id&adgroup_id=adgroup_id&adgroup_name=adgroup_name&adplan_id=adplan_id&adplan_name=adplan_name&adcreative_id=adcreative_id&adcreative_name=adcreative_name&adcreative_type=adcreative_type&scene_id=scene_id&event_custom_params=custom_params&ad_platform=ad_platform&ad_type=ad_type&ad_appid=ad_appid&ad_id=ad_id&mediation_platform=mediation_platform&ad_ecpm=ad_ecpm&order_id=order_id&order_amount=order_amount&currency_type=currency_type&purchase_type=purchase_type&product_id=product_id&product_name=product_name&product_num=product_num&register_type=register_type&login_type=login_type

请注意，上述回调地址已经将 current_event_time 的入参替换为 event_time，custom_params 的入参替换为 event_custom_params，所以您可以使用与 App 一样的用户识别字段配置

小程序/小游戏通用事件字段说明：

字段名称	建议使用	值（举例）	说明
appkey	是	9b716df699b77694	SE后台创建的应用唯一标识符
app_name	是	应用名称	应用名称
app_platform	是	miniprogram	操作系统：miniprogram或minigame
app_type	是	wechat	平台类型：wechat、douyin
event_name	是	startup	事件名称。固定为install（激活）、startup（启动）、register（注册）、login（登录）、order（订单）、purchase（付费）、adimpression（广告曝光）...
country	是	CHN	国家
install_time		1637823377000	安装时间
current_event_time	是	1637823377000	当前事件发生的时间
report_time		1637823377000	服务器接收到的时间
integration_type		sdk	集成方式。固定为sdk
collector_version		1.8.0	收集器版本
attribution_method		path	归因方式：路径归因（path）、点击归因（click）
channel_id		8221	渠道id
channel_name	是	tiktok	渠道名称
turl_campaign_id		871bbfa4560283c5a0ca00483c529c63	监测链接ID
turl_campaign_name		监测链接名称_Mintegral	监测链接名称
openid		oUFfk5coGBwScTmIsr008qL93ANk	当前小程序内，用户唯一ID
anonymous_openid			抖音专属，当前小程序内，匿名用户唯一ID
unionid		f7510d9ab***********	同一开发者下的不同小程序，用户唯一ID
device_id		oUFfk5UyO--kSbPVEuC5zWtqYvbs	设备ID
device_id_type		openid	设备ID类型
container_name		toutiao	宿主 APP 名称，抖音专属
os	是	android	宿主 App 操作系统平台
os_version	是	10	宿主 App 操作系统版本
brand	是	HUAWEI	宿主 App 设备生产厂商
model	是	Mate 40	宿主 App 设备型号
language		zh-han	宿主 App 设备语言
ipv4		1.1.1.1	用户公网IP v4版本
ua	是	Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/95.0.4638.54 Safari/537.36	UA
user_id	是		账号ID（用户id）
account_id	是		广告账户id
adgroup_id	是		广告组id
adgroup_name	是		广告组名称
adplan_id	是		广告计划id
adplan_name	是		广告计划名称
adcreative_id	是		广告创意id
adcreative_name	是		广告创意名称
adcreative_type	是		创意类型（例如大图、小图、视频等）
material_1			素材ID_1
material_2			素材ID_2
material_3			素材ID_3
material_4			素材ID_4
material_5			素材ID_5
material_6			素材ID_6
click_id			广告点击id
impression_id			广告展示id
request_id			广告请求id
callback_id			渠道回调id
callback_url			渠道回调地址
site_id			流量媒体id（例如巨量的今日头条、穿山甲、抖音等）。
site_name			流量媒体名称（例如巨量的今日头条、穿山甲、抖音等）。
scene_id	是	1	场景值
path		index/xxx	小程序启动页面路径
query_info		{ "channel_id": "234234", "turl_id": "234234", ...}	从小程序平台获取的query信息，SE携带参数+渠道追加参数
custom_params	是	{ "add_cart": "234234", //自定义参数。 "sku": "234234", "level_up": "234234" ... }	/事件自定义参数嵌套，内含参数最多10项。

小程序/小游戏部分事件专属的字段说明：

事件	字段名称	建议使用	说明
adimpression	ad_platform	是	变现平台
	ad_type	是	展示广告的类型
	ad_appid	是	变现平台的应用 ID
	ad_id	是	变现平台的变现广告位 ID
	mediation_platform	是	聚合平台标识，没有聚合平台标识，请设置为 "custom"
	ad_ecpm	是	广告ECPM（广告千次展现的变现收入，0或负值表示没传），单位：元
	is_rendered		广告是否渲染成功，具体枚举值如下： YES：成功 NO：失败 如果不需要统计该指标，请传 YES
adclick	ad_platform	是	变现平台
	ad_type	是	展示广告的类型
	ad_id	是	变现平台的变现广告位 ID
	mediation_platform	是	聚合平台标识，没有聚合平台标识，请设置为 "custom"
purchase	order_id	是	订单 ID
	order_amount	是	本次购买支付的金额
	currency_type	是	支付的货币各类，遵循《ISO 4217国际标准》，如 CNY、USD
	purchase_type	是	支付方式：如 alipay、weixin、applepay、paypal 等
	product_id	是	购买商品的ID
	product_name	是	商品名称
	product_num	是	购买商品的数量
order	order_id	是	订单 ID
	order_amount	是	订单金额，单位：元
	currency_type	是	展示收益的货币种类，遵循《ISO 4217国际标准》，如 CNY、USD
	purchase_type	是	支付方式：如 alipay、weixin、applepay、paypal 等
register	register_type	是	注册类型如 "WeChat"、"QQ" 等自定义值
login	login_type	是	登录类型如 "WeChat"、"QQ" 等自定义值

四、数据入库

4.1 数据入库规则

默认情况下，我们会按照以下规则将拉取的数据以事件形式写入 TE 项目中：

• 使用数据中的 event_time 字段，作为事件的数据时间 #event_time
• 使用数据中的 event_name 作为数据的事件名
• 其他字段将全数入库

4.2 标准化字段

原始字段	标准化字段	含义
account_id	te_ads_object.ad_account_id	广告账号 ID
adplan_name	te_ads_object.campaign_name	广告计划名
adplan_id	te_ads_object.campaign_id	广告计划 ID
adgroup_name	te_ads_object.ad_group_name	广告组名，变现广告的 Unit 名
adgroup_id	te_ads_object.ad_group_id	广告组 ID，变现广告的 Unit ID
adcreative_name	te_ads_object.ad_name	广告名
adcreative_id	te_ads_object.ad_id	广告 ID
placement_id	te_ads_object.placement	广告位置
channel_name	te_ads_object.media_source	媒体渠道或变现渠道
bundleid	te_ads_object.app_id	应用 ID
app_name	te_ads_object.app_name	应用名
app_platform	te_ads_object.platform	平台，即 Android、iOS 等
country	te_ads_object.country	国家地区编码