转化跟踪对接指南

工作原理

转化跟踪的核心思路很简单：元气智广在用户点击广告时，将设备信息传递给广告主；广告主在用户完成转化后，将转化事件回传给元气智广。这样双方就能准确匹配点击与转化，实现精准归因。

准备工作

在开始对接前，请确保您已具备以下条件：

步骤 1：配置点击监测链接

点击监测链接是元气智广向您上报点击事件的入口。您需要在创建广告计划时填写此链接，我们将在此链接后拼接宏参数并调用。

链接格式

点击监测链接由以下部分组成：

必须包含的参数

• 回调链接：用于接收您的转化回传。格式为 callback_url=_CALLBACK_URL_
  这是必须添加的参数，否则无法完成转化回传

推荐包含的宏参数

为了完成归因，建议在链接中包含以下设备信息参数：

完整示例

https://track.yourdomain.com/click?callback_url=_CALLBACK_URL_
  &idfa=_IDFA_&oaid=_OAID_&androidid=_ANDROIDID_
  &ip=_IP_&os=_OS_&source=qiyuanzhiguang

步骤 2：接收点击事件

当用户点击广告后，元气智广会立即调用您配置的点击监测链接。您需要：

1. 解析 URL 参数 从请求 URL 中提取宏参数替换后的值，包括设备 ID、IP、回调链接等
2. 存储回调链接 将 callback_url 参数值与用户设备信息关联存储，用于后续转化回传
3. 返回成功响应 返回 HTTP 200 状态码，表示已成功接收点击事件

步骤 3：完成转化归因

归因由您或您对接的第三方归因平台完成。当用户在您的 APP 内完成转化行为（如激活、注册、付费）时：

1. 采集转化设备 ID 从转化用户设备采集 IDFA、OAID 等设备标识
2. 匹配点击记录 将转化设备 ID 与之前存储的点击记录进行匹配
3. 确认转化来源 匹配成功后，确认该转化来自元气智广的广告投放

步骤 4：回传转化事件

归因完成后，您需要通过回调链接将转化事件回传给元气智广。这是计算转化的关键步骤。

回传前准备

• 解码回调链接：对存储的 callback_url 进行 UTF-8 URL 解码
  Java 示例：java.net.URLDecoder.decode(callbackUrl, "UTF-8")
• 设置事件类型：将链接中的 type 参数替换为对应的事件类型（默认为 act 激活）

回调示例

激活事件

http://chelaile.tracking.biddingads.com/ad-action/click/callback?uid=820634
  ×tamp=1767196800000&ip=116.236.101.90&os=ios
  &idfa=63557E56-67E6-4359-9F28-998736FA28B7
  &type=act

付费事件

http://chelaile.tracking.biddingads.com/ad-action/click/callback?uid=820634
  ×tamp=1767196800000&ip=116.236.101.90&os=ios
  &idfa=63557E56-67E6-4359-9F28-998736FA28B7
  &type=pay&pay_amount=68.00

回调 API 参考

基本信息

请求参数

响应格式

成功返回 HTTP 200，响应体如下：

{
    "type": "SUCCESS",
    "text": null,
    "data": null,
    "errors": []
}

渠道包场景回调

如果您投放的是 APK/EXE 渠道包，或落地页带渠道跟踪参数，可使用以下回调方式：

渠道包专属参数

请求示例

curl --location 'http://chelaile.tracking.biddingads.com/ad-action/click/callback?
  type=pay×tamp=1767196800000&trackId=682940157&ip=114.80.33.18
  &oaid=a557ce7503c8396ebe77367b54dc7651&pay_amount=6.48'

宏参数完整列表

以下是点击监测链接支持的所有宏参数：

事件类型列表

回传转化事件时，type 参数需使用以下枚举值：