manuallatest产品手册 / 热力引擎集成方案
热力引擎集成方案
提示
请注意，第三方数据集成产生的数据会被纳入集群的消耗数据量
概要
接口简介
| 接口名 | 类型 | 粒度 | 归因 | 成本 | 收益 | 展示 | 点击 | 转化 |
|---|---|---|---|---|---|---|---|---|
| 实时 API | 回传 | 用户级别 | ✅ | ✅ |
在开始接入热力引擎数据前，请确保您已经阅读 AE 系统用户识别规则，理解 AE 如何通过 #distinct_id 和 #account_id 识别一个用户
热力引擎提供了实时 API 导出功能，支持实时回传激活等事件数据，详情可以参考热力引擎官网文档
集成流程
- 接入热力引擎 SDK 与 AE SDK，通过热力引擎 SDK 的公共事件属性设置接口传入 AE SDK 的访客 ID
- 登录 AE 后台，进入三方集成模块，新增热力引擎集成，完成相关配置，并复制回调地址
- 登录热力引擎后台，完成数据回传的配置
- 查看 AE 系统是否成功接收数据，并完成报表搭建
一、客户端 SDK 配置
1.1 引入热力引擎 SDK 与 AE SDK
首先，您需要在应用中引入热力引擎 SDK 以及 AE SDK，并完成初始化配置。热力引擎 SDK 与 AE SDK 的接入文档如下：
1.2 进行 SDK 配置
在引入 SDK 后，接下来需要做的就是将 AE SDK 的访客 ID 与账号 ID 设置到热力引擎 SDK 中，我们推荐的做法是使用热力引擎的公共事件属性的设置接口
请注意顺序：
- 完成 AE SDK 的初始化
- 获取 AE SDK 的访客 ID
- 调用热力引擎的设置公共属性接口，将 AE SDK 的访客 ID 设置为热力引擎 SDK 的公共属性
- 热力引擎 SDK 初始化
- 当可以获取 AE SDK 的账号 ID 时（即登录账号或角色上线时），调用 AE SDK 的 login 接口，并再次调用热力引擎的设置公共属性接口，将账号 ID 设置为热力引擎 SDK 的公共属性
以下是安卓的代码样例：
// 完成 AE SDK 的初始化
TDAnalytics.init(context, APPID, SERVER_URL);
// 获取 AE SDK 的访客 ID
String te_distinct_id = TDAnalytics.getDistinctId();
// 使用公共事件属性设置接口，将 AE 的访客 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);
// 使用公共事件属性设置接口，将 AE 的账号 ID 设置为热力引擎 SDK 的公共属性
SolarEngineManager.getInstance().setSuperProperties(context,"te_account_id", te_account_id);
二、方案配置
在完成了 SDK 的配置之后，接下来需要您登录 AE 系统后台，在「三方集成」模块中完成热力引擎的配置。下图是热力引擎的配置界面：
2.1 用户识别字段
由于热力引擎回传的是用户级别数据，因此需要为其设置用户识别规则。AE 系统将根据该配置，在转换回传数据时，将这些字段设置为数据中的用户识别字段。
如果您按照本文档上一步进行客户端 SDK 配置，请使用以下配置：
- 账号 ID 关联字段：event_custom_params.te_account_id
- 访客 ID 关联字段：event_custom_params.te_distinct_id
2.2 事件表入库设置
打开「事件表入库设置」开关后，回传的数据（包括激活事件和应用内事件）都将写入到事件表中
我们建议您开启事件数据入库。但需要注意，默认情况下，我们会接收所有热力引擎回传的数据。如果回传的事件类型过多，会导致 AE 项目的事件量过度膨胀。因此建议在热力引擎平台设置回传时，只选择必要事件进行回传。
2.3 用户属性入库规则
在默认情况下，AE 系统会自动将热力引擎回传数据中的归因字段写入到标准化处理后的用户属性中，以下是写入用户属性的字段及其含义：
| 热力引擎字段 | 标准化字段 | 说明 |
|---|---|---|
| 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。这样配置，则 AE 系统只会从热力引擎回传的 install 事件中提取需要写入用户属性的字段并进行写入。入库方式默认是 user_setOnce，也就是只会保留首次上报的信息。
如果您希望关闭用户属性入库，可以停止所有规则：
2.4 集成配置
最后，您可以在集成配置模块对数据拉取的细节配置进行控制，比如入库后的事件名等。
集成配置中的内容是一个 JSON，您可以按照以下内容进行自定义配置：
| 模块 | 名称 | 含义 |
|---|---|---|
| sink_event | event_mapping | 入库后的事件名，可以自定义。Key 为热力引擎的事件名，Value 为入库后的事件名；默认的是激活事件：install |
2.5 终端地址
终端地址中展示了 AE 系统接收热力引擎回传数据的地址。
请注意，终端地址中自带了 APP 回传的参数，如果您要回传的是小程序/小游戏的数据，则请参考小程序/小游戏回调参数一节
请您直接复制该地址，在接下来进行回传配置时，请将该地址填入：
若此处无地址没有显示，请进入右上角菜单「项目管理 → 项目配置 → 接入配置」处配置公网地址。该地址即 AE SDK 中配置的数据上报地址。配置后再回到热力引擎配置页的「终端地址」复制终端地址。
三、在热力引擎完成回调配置
3.1 在热力引擎后台的实时api数据导出页面配置回调链接
在完成 AE 后台的方案创建后，请您登录热力引擎后台，选择您需要回传数据的项目，并从「归因」模块中选择「应用设置」-「数据导出」-「实时api导出」，即可进行热力引擎的实时回传配置
您可以按照以下规则来进行填写：
- 回调类型选择「激活」
- 回调地址填写您在 AE 后台获取到的回传地址
- 回调地址解析，建议您按照 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 | 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¤t_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&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¤cy_type=currency_type&purchase_type=purchase_type&product_id=product_id&product_name=product_name&product_num=product_num®ister_type=register_type&login_type=login_type
小程序/小游戏通用事件字段说明：
| 字段名称 | 建议使用 | 值（举例） | 说明 |
|---|---|---|---|
| appkey | 是 | 9b716df699b77694 | SE后台创建的应用唯一标识符 |
| app_name | 是 | 应用名称 | 应用名称 |
| app_platform | 是 | miniprogram | 操作系统：miniprogram或minigame |
| app_type | 是 | 平台类型：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 数据入库规则
默认情况下，我们会按照以下规则将拉取的数据以事件形式写入 AE 项目中：
- 使用数据中的 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 | 国家地区编码 |
这篇文档对你有帮助吗？