引力引擎集成方案
第三方回传会增加项目数据量,请评估所选事件与已有埋点的重复统计。
概要
接口简介
| 接口名 | 类型 | 粒度 | 归因 | 成本 | 收益 | 展示 | 点击 | 转化 |
|---|---|---|---|---|---|---|---|---|
| 实时 API | 回传 | 用户级别 | ✅ | ✅ | ✅ | ✅ |
引力引擎(Gravity Engine)通过 POST JSON 回传事件批次、用户属性及归因宏参数。数数依据项目配置将其转换为事件数据和用户属性操作。
接入前请阅读数数的用户识别规则,理解 #distinct_id 与 #account_id 的用途。引力引擎回调协议见引力引擎官方文档。
集成流程
- 接入并初始化数数 SDK,取得数数访客 ID;接入引力 SDK,并将数数身份同步到引力用户属性。
- 在数数侧配置 gravityengine 集成:设置用户识别字段、事件上报和用户属性映射,获取项目回调地址。
- 在引力后台开启事件回调,选择必要事件、填写 POST 地址,并按本方案约定添加广告归因宏参数。
- 用测试用户触发事件,在数数核对事件名称、时间、用户关联和用户属性,再开启正式流量。
一、客户端 SDK 配置
1.1 引入引力引擎 SDK 与数数 SDK
按实际运行端选择 SDK 并完成初始化。参考引力客户端 SDK 文档和数数 SDK 接入文档。各端 SDK 方法签名以所用版本为准,以下给出身份同步流程。
1.2 同步用户识别字段
- 先初始化数数 SDK,并获取数数访客 ID。
- 按引力与数数对接约定,初始化引力 SDK 时传入数数访客 ID;账号 ID 已知时一并传入,由引力写入 ta_distinct_id、ta_account_id 用户属性。
- 用户登录或角色上线后,调用数数 SDK 的 login,并调用引力用户属性设置接口,同步更新 ta_account_id。账号切换时保持两端身份一致。
- 发起测试回调,确认 user_properties 中实际存在以下身份字段。不要仅把身份写入事件 properties。
{
"user_properties": {
"ta_distinct_id": "ta-test-distinct-id",
"ta_account_id": "ta-test-account-id"
}
}
对接约定要求引力传入 ta_distinct_id,账号 ID 在可用时传入;转换时至少需要一个有效身份。正文 client_id 是引力标识,不自动替代数数访客 ID。
二、方案配置
本节对应参考模板的数数侧配置。请在目标环境支持的第三方集成入口中选择引力引擎;平台标识为 gravityengine。下图是引力引擎的配置界面:
2.1 用户识别字段
| 数数身份 | 推荐关联字段 | 取值规则 |
|---|---|---|
| 账户 ID(#account_id) | user_properties.ta_account_id | 优先读取入库设置 -> 用户识别字段 -> 账户ID 指定的正文路径;取不到非空值时独立回退到本字段。 |
| 访客 ID(#distinct_id) | user_properties.ta_distinct_id | 优先读取入库设置 -> 用户识别字段 -> 访客ID 指定的正文路径;取不到非空值时独立回退到本字段。 |
两个身份分别取值和回退,最终均为空时不生成事件或用户操作。事件属性中的 $ta_account_id、$ta_distinct_id 以及 client_id 均不自动覆盖这套身份来源。
2.2 事件表入库设置
打开「事件表入库设置」开关后,回传的数据里 events[] 下的所有事件都将写入到事件表中。启用后,每个名称和毫秒时间戳均合法的 events[] 条目生成一条事件数据;名称缺失、时间非法或非对象条目被跳过,不影响其他合法事件。建议只在引力后台选择业务需要的事件,避免事件量和已有埋点重复膨胀。
入库的事件名默认会将events[].event的值去掉开头的$,再增加gravity_前缀,作为入库的事件名。如果需要事件名映射规则,可以在2.4 集成配置中配置映射关系。
2.3 用户属性入库规则
在默认情况下,AE 系统会自动将引力引擎回传数据中的归因字段写入到标准化处理后的用户属性中,以下是写入用户属性的字段及其含义:
| 引力引擎字段 | 标准化字段 | 说明 |
|---|---|---|
| callback_params.channel | te_ads_object.media_source | 媒体渠道 |
| callback_params.campaign_name | te_ads_object.campaign_name | 广告计划名 |
| callback_params.ad_name | te_ads_object.ad_name | 广告名 |
| callback_params.ad_id | te_ads_object.ad_id | 广告 ID |
如果需要进行修改,您可以点击「配置规则」进入到入库规则配置页,如下图所示
在此,您可以修改用户属性从哪些事件来。如果您不希望用户属性被频繁写入,可以关闭「包含所有事件」,并将来源事件名修改为指定事件名。这样配置,则 AE 系统只会从引力引擎回传的指定事件中提取需要写入用户属性的字段并进行写入。入库方式默认是 user_setOnce,也就是只会保留首次上报的信息。
如果您希望关闭用户属性入库,可以停止所有规则:
2.4 集成配置
可以在集成配置中指定事件名映射规则
2.5 终端地址
POST https://<数数接收域名>/callback/integration/gravityengine/<数数项目APPID>
Content-Type: application/json
使用已核验的数数接收公网域名和目标项目 APPID,填入引力的回调地址。路径 APPID 选择数数项目;正文 app_id 是引力应用 ID,两者不可混用。APPID 用于项目关联,不构成强身份认证。
三、在引力引擎完成回调配置
3.1 配置事件回调
进入引力后台应用管理中的事件回调配置,开启开关并填写下表。
3.2 配置广告归因宏参数
以下小写 key 是本方案约定的 callback_params 字段名,需要在引力后台主动配置对应宏。宏定义见引力归因回调文档;数数接收端读取宏解析后的值,不替换宏模板,也不会自动查询缺失的广告信息。
| 回调参数名 | 引力宏值 | 含义 |
|---|---|---|
| advertiser_id | __ADVERTISER_ID__ | 广告主账户 ID |
| campaign_id | __CAMPAIGN_ID__ | 广告计划 ID |
| campaign_name | __CAMPAIGN_NAME__ | 广告计划名称 |
| ad_id | __AD_ID__ | 引力广告 ID |
| ad_name | __AD_NAME__ | 引力广告名称 |
| creative_id | __CREATIVE_ID__ | 引力广告创意 ID |
| creative_name | __CREATIVE_NAME__ | 引力广告创意名称 |
| ad_platform | __AD_PLATFORM__ | 媒体平台 |
| csite | __CSITE__ | 广告投放版位 |
| os_type | __OS_TYPE__ | 设备类型 |
例如设置参数名 campaign_id、宏值 __CAMPAIGN_ID__ 后,实际请求应包含 callback_params.campaign_id="测试广告计划ID"。未配置或宏未能返回有效值时,相应广告字段不会生成;无 $ 的 key 不代表引力默认自动携带。
事件与用户的宏参数约定相同,各端事件属性以引力对接文档附件为准。小程序属性 $app_id 表示小程序 APPID,与正文根节点的引力应用 app_id 分开处理。
3.3 回调数据示例
以下使用示例 ID 和历史时间戳说明结构,不是可直接用于生产联调的数据。联调时使用真实测试用户、当前事件时间及引力实际生成的签名。user_properties 为本次引力与数数专项对接约定字段。
{
"app_id": "gravity-app-id",
"client_id": "gravity-client-id",
"sign": "<引力生成的签名>",
"events": [
{
"event": "$PayEvent",
"time": 1779439377000,
"properties": {
"$os": "iOS",
"$model": "iPhone 12",
"$country": "China",
"$pay_amount": 600,
"$pay_type": "CNY"
}
}
],
"callback_params": {
"channel": "campaign-a",
"advertiser_id": "ad-account-1",
"campaign_id": "campaign-1",
"campaign_name": "测试计划",
"ad_id": "group-1",
"creative_id": "creative-1",
"ad_platform": "bytedance",
"os_type": "ios"
},
"user_properties": {
"ta_distinct_id": "ta-test-distinct-id",
"ta_account_id": "ta-test-account-id",
"$ad_count": 1
}
}
| 字段 | 类型 | 说明 |
|---|---|---|
| app_id、client_id | string | 引力应用与客户端标识,不用于替代数数项目或数数用户身份。 |
| events | array | 事件批次;条目包含 event、time、properties。只控制事件输出,不控制用户规则是否执行。 |
| events[].time | number | 正整数毫秒 Unix 时间戳;兼容整数数字字符串,不按长度猜测秒单位。 |
| events[].properties | object | 当前事件属性。 |
| callback_params | object | 宏解析后的参数及自定义参数。 |
| user_properties | object | 数数身份及可映射的用户属性来源。 |
四、数据入库
4.1 事件数据入库规则
| 项目 | 方案规则 |
|---|---|
| 事件名 | 默认去掉开头首个 $,按第三方名称规则标准化,再加 gravity_;例如 $PayEvent → gravity_PayEvent。原始名命中有效 event_mapping 时使用标准化后的映射值,不再自动加前缀。 |
| 事件时间 | 按 events[].time 毫秒时间戳转为服务本地时间,写 #time,并在属性中写对应 #zone_offset(小时);不使用当前时间补非法事件。 |
| 事件属性 | 先合并 callback_params,再合并当前 properties;完成名称映射后,事件属性优先。同源显式属性优先于 $ 别名,例如 #os 优先于 $os、amount 优先于 $amount。 |
| 协议根字段 | app_id、client_id 存在且非 null 时写入 properties.gravity_app_id、properties.gravity_client_id,保留原始类型并覆盖同名输入;空字符串保留。缺失或 null 不额外写入,也不删除已合并同名属性。 |
| IP 与来源 | 合并后的 $ip/#ip 写事件顶层 #ip,字符串有效时输出,不用回调服务器 IP 补充;#data_source_detail 固定 GravityEngine,#zone_offset 由服务计算,二者不接受输入覆盖。 |
| 其他字段 | 不自动平铺 sign、整包 user_properties 或 events;普通属性名不加 gravity_ 前缀,数字、布尔值、数组、对象保留原始 JSON 类型。 |
配置示例将 $PayEvent 映射为 pay_event;不配置该映射则输出 gravity_PayEvent。在 Asia/Shanghai 环境中,示例时间 1779439377000 对应 2026-05-22 16:42:57.000,#zone_offset=8。部署使用其他时区时,以服务实际时区为准。
4.2 事件预置属性映射
下表保留原 Gravity 方案的 38 项映射。值来自 callback_params 与当前事件属性,不补造默认值。除 #ip 位于事件顶层,其余目标写入 properties。
| 引力源字段 | 数数目标字段 | 说明 |
|---|---|---|
| $ip | #ip | 写事件顶层;输入须为字符串。 |
| $country | #country | 国家。 |
| $province | #province | 省份。 |
| $city | #city | 城市。 |
| $os | #os | 操作系统。 |
| $os_version | #os_version | 系统版本。 |
| $manufacturer | #manufacturer | 制造商。 |
| $model | #device_model | 设备型号,保留已确定的异名映射。 |
| $screen_width | #screen_width | 屏幕宽度。 |
| $screen_height | #screen_height | 屏幕高度。 |
| $app_version | #app_version | 应用版本。 |
| $carrier | #carrier | 运营商。 |
| $network_type | #network_type | 网络类型。 |
| $device_id | #device_id | 设备标识。 |
| $lib | #lib | SDK 标识。 |
| $lib_version | #lib_version | SDK 版本。 |
| $browser | #browser | 浏览器。 |
| $browser_version | #browser_version | 浏览器版本。 |
| $scene | #scene | 场景值。 |
| $system_language | #system_language | 系统语言。 |
| $bundle_id | #bundle_id | 应用包名。 |
| $duration | #duration | 时长,保留源值的秒单位及数值类型。 |
| $app_crashed_reason | #app_crashed_reason | 崩溃原因。 |
| $background_duration | #background_duration | 后台时长,保留源值。 |
| $element_content | #element_content | 元素内容。 |
| $element_id | #element_id | 元素标识。 |
| $element_position | #element_position | 元素位置。 |
| $element_selector | #element_selector | 元素选择器。 |
| $element_type | #element_type | 元素类型。 |
| $resume_from_background | #resume_from_background | 从后台恢复。 |
| $scene_name | #scene_name | 场景名称。 |
| $scene_path | #scene_path | 场景路径。 |
| $screen_name | #screen_name | 页面或屏幕名称。 |
| $share_depth | #share_depth | 分享深度。 |
| $start_reason | #start_reason | 启动原因。 |
| $title | #title | 页面标题。 |
| $url | #url | 页面 URL。 |
| $url_path | #url_path | URL 路径。 |
未命中表的 $xxx 去掉首个 $ 后标准化,例如 $pay_amount → pay_amount、$brand → brand。$timezone_offset 单位未明确,保留普通 timezone_offset;$event_duration 保留普通 event_duration。$user_id、$account_id、$distinct_id、$event_name、$event_time、$server_time 不自动覆盖对应数数协议字段。系统支持某个 # 预置属性,不代表引力一定回传,也不据此开放存储和内部字段覆盖。

