01应用跟踪实现原理
广告主按要求填写点击监测链接和拼接预留宏参数。人人视频会自动替换这些宏参数并下发给广告主, 提供给广告主广告展示点击用户的 IDFA、OAID、ANDROIDID、CAID 等用户设备信息、回调链接及其他相关信息。 广告主将其与自己监测到的转化用户的相关信息进行匹配后,通过回调链接回传转化数据给媒体。
02应用推广类 API 对接流程
- 广告主填写点击监测链接并投放广告用户在 APP 内点击广告。
- 人人视频向广告主上报点击事件调用广告主填写的点击监测链接,并替换宏参数,上报用户设备信息、转化回调链接及其他相关信息。
- 用户在广告主 APP 产生转化
- 广告主完成匹配归因根据人人视频上报的设备信息与自己 APP 监测到的转化设备信息进行匹配归因。
- 广告主回传转化事件通过转化回调链接回传给媒体。
2.1 对接点击上报服务
广告主在新建应用转化时,需要填写点击监测链接,用来接收人人视频上报的点击事件,进而完成转化归因。
2.2 通信协议
支持通过 HTTP 或 HTTPS 通道进行请求通信。为了获得更高的安全性,推荐使用 HTTPS 通道; 如果您使用的是 http 通道,需保证也能支持 https 通道。
2.3 请求方法
支持 GET 方法发送请求,这种方式下请求参数需要包含在请求的 URL 中。
2.4 格式要求
点击监测链接主要由四部分组成:
https://www.xxx.com? + 自选宏参数 + 回调链接宏参数 + 自定义参数(可选)
- 前缀:广告主自有或三方点击监测服务的地址,格式为
https://www.xxx.com? -
回调链接宏参数:媒体接受广告主转化回传的地址,广告主将用户的转化事件通过此链接回传给媒体。
必须填写,格式为「广告主自定义参数名=
__CALLBACK_URL__」,如callback_url=__CALLBACK_URL__ -
自选宏参数:广告主需要在点击监测链接后拼接宏参数占位符,用以获取归因/回传所必要的信息(如 OAID/IDFA/回调链接)。
用户点击广告后,人人视频会动态替换约定好的宏参数并上报给点击监测地址,广告主即可获取到广告点击的相关信息。
广告主可以根据需要自选参数,格式为「广告主自定义参数名=
__参数__」。 平台支持的宏参数范围请见附件一,__参数__须严格按照附件中的值拼写,否则无法识别。__参数__必须全部大写__参数__格式中参数两边为单下划线,即参数左右两边均为单个英文字符_
- 广告主自定义参数:不在媒体支持的宏参数范围内的自定义参数名和固定值,由广告主自定义,媒体不做替换。如
source=rrtv,标记为该媒体的点击上报。 - 点击监测链接支持大小写字母、数字以及下划线字符,多个参数中间使用
&连接。
点击监测链接示例
https://www.xxx.com?&callback_url=__CALLBACK_URL__&ip=__IP__&os=__OS__
&oaid=__OAID__&oaidmd5=__OAID_MD5__&androidid=__ANDROIDID__
&idfa=__IDFA__&caid=__CAID__&caid2=__CAID2__
03广告主归因
由广告主或广告主对接的第三方机构完成。广告主在收到人人视频上报的点击事件后,进行转化归因。 人人视频会替换广告主选择的宏参数,如广告主广告点击用户的 IDFA、OAID、ANDROIDID、CAID 等设备信息, 广告主将其与自己监测到的转化用户的相关信息进行匹配,完成转化归因。
04对接转化事件回调服务
在完成归因后,广告主需要将相应的转化事件信息通过请求上报点击事件里的回调链接回传给媒体服务器,并以此计算一次转化。
4.1 回调链接
媒体在点击事件上报时下发的 callback URL。广告主需完成以下操作后,请求此链接完成转化事件回传。
-
解码:callback URL 字段值需先做 UTF-8 decode 解码。
即,使用标准 HTML、
application/x-www-form-urlencoded、UTF-8 对获取到的 callback URL 解码。 如使用java.net.URLDecoder#decode(java.lang.String)解码。 -
替换转化事件类型参数值:callback URL 中
type默认是激活(act)。 如需支持其他事件,需要替换type取值。type 支持的事件类型及其枚举值请参考附件二。
callback URL 示例 · 激活
http://monitor.adwutong.com/ad-action/click/callback?uid=820634
×tamp=1767196800000&ip=116.236.101.90&os=ios
&idfa=63557E56-67E6-4359-9F28-998736FA28B7
&caid=f41fcb28e1eca2291aa5148c01a8c3f5&materialId=85200461
&oaid=&type=act
&invokeId=900612345&responseId=18462739501284
type=pay),可拼接 pay_amount 字段传入付费金额
(string 类型,单位元,支持小数点 2 位)。参数明细见附件二。
http://monitor.adwutong.com/ad-action/click/callback?uid=820634
×tamp=1767196800000&ip=116.236.101.90&os=ios
&idfa=63557E56-67E6-4359-9F28-998736FA28B7
&caid=f41fcb28e1eca2291aa5148c01a8c3f5&creativeId=85200461
&oaid=&type=pay
&invokeId=900612345&responseId=18462739501284&pay_amount=68.00
- callback URL 是由平台动态生成,除 type 以外的其余参数不要进行替换,否则会识别不成功。
- 如需上报多次事件,每次事件均需要进行回调。
- 若需上报多个事件类型,例如广告主同时选择了浅层转化目标和深度转化目标,每个事件类型均需要进行回调。
4.2 通信协议
目前接口仅支持通过 HTTP 方式进行请求通信。
4.3 请求方法
支持 GET 方法发送请求,这种方式下请求参数需要包含在请求的 URL 中。
4.4 返回值
成功:HTTP code 200,标准返回值如下;失败:其他值。
{
"type":"SUCCESS",
"text":null,
"data":null,
"errors":[]
}
05渠道包投放场景转化回调服务
说明:适用于 PC 游戏、安卓游戏等渠道包投放场景,将渠道包投放带来的转化事件进行转化回调。
适用归因方式:渠道包归因(apk 下载包/exe 下载包)、落地页 URL 渠道跟踪参数归因。
5.1 对接转化事件回调服务
完成归因后,用户在应用中达成转化事件时,广告主需要通过 API 回调媒体用户转化事件。
5.2 通信协议
目前接口仅支持通过 HTTP 方式进行请求通信。
5.3 请求方法
请使用 GET 方法发送请求,这种方式下请求参数需要包含在请求的 URL 中。
5.4 参数说明
| 参数名 | 类型 | 必选 | 说明 |
|---|---|---|---|
| type | string | 是 | 转化类型。参考「附件二:转化事件参数列表」,样例 act(激活事件) |
| timestamp | long | 是 | 转化事件发生时间(毫秒),UTC 时间戳 |
| trackId | string | 是 | 用于追踪来源广告的追踪 ID(若投放链路为 apk/exe,则否)。请联系商务获取 |
| ip | string | 否 | 设备的联网公网 IPv4 地址。IPv4 格式,四段点分(A.B.C.D) |
| oaid | string | 否 | Android Q 及更高版本的设备号。H5 页面、PC 游戏等获取不到 oaid 场景的,使用空值 |
| pay_amount | string | 否 | 付费金额。若回传事件为付费,可拼接 pay_amount 字段传入付费金额(单位元,支持小数点 2 位) |
| ua | string | 否 | 数据上报用户终端设备的 User Agent。样例 Mozilla 5.0(Linux Android4.0.4 GTI9220 Build IMM76D) |
5.5 请求示例
回调链接地址示例
http://monitor.adwutong.com/ad-action/click/callback?type=pay
×tamp=1767196800000&trackId=682940157&ip=114.80.33.18
&oaid=a557ce7503c8396ebe77367b54dc7651
&ua=Mozilla%205.0(Linux%20Android4.0.4%20GTI9220%20Build%20IMM76D)&pay_amount=6.48
Java(OkHttp)
OkHttpClient client = new OkHttpClient().newBuilder()
.build();
MediaType mediaType = MediaType.parse("text/plain");
RequestBody body = RequestBody.create(mediaType, "");
Request request = new Request.Builder()
.url("http://monitor.adwutong.com/ad-action/click/callback?oaid=a557ce7503c8396ebe77367b54dc7651&type=pay×tamp=1767196800000&trackId=682940157&ip=114.80.33.18&ua=Mozilla%205.0(Linux%20Android4.0.4%20GTI9220%20Build%20IMM76D)&pay_amount=6.48")
.method("GET", body)
.build();
Response response = client.newCall(request).execute();
cURL
curl --location 'http://monitor.adwutong.com/ad-action/click/callback?oaid=a557ce7503c8396ebe77367b54dc7651&type=pay×tamp=1767196800000&trackId=682940157&ip=114.80.33.18&ua=Mozilla%205.0(Linux%20Android4.0.4%20GTI9220%20Build%20IMM76D)&pay_amount=6.48'
5.6 返回值
{
"type":"SUCCESS",
"text":null,
"data":null,
"errors":[]
}
附件一点击监测链接支持的宏参数列表
| 宏 | 类型 | 定义 | 返回广告数据示例 |
|---|---|---|---|
| _TS_ | long | 客户端发生广告点击事件的时间,以毫秒为单位时间戳 | 1767196800000 |
| _CALLBACK_URL_ | string | 平台提供的回调接口,已 urlencode 处理,回调时广告主需要 urldecode。注意:点击监测链接中,必须添加该参数 | http://monitor.adwutong.com/ad-action/click/callback?uid=820634×tamp=1767196800000&type=act&… |
| _IP_ | string | 媒体投放系统获取的用户终端的公共 IP 地址 | 116.236.101.90 |
| _OS_ | string | 操作系统平台,ios 或 android | ios |
| _IMEI_MD5_ | string | Android 的设备 ID 的 md5 加密,32 位 | — |
| _OAID_ | string | Android Q 及更高版本的设备号 | — |
| _OAID_MD5_ | string | Android Q 及更高版本的设备号 md5 加密,32 位 | — |
| _ANDROIDID_ | string | Android ID 原值 | — |
| _IDFA_ | string | iOS 6+ 的设备 ID 字段,32 位 | 63557E56-67E6-4359-9F28-998736FA28B7 |
| _IDFA_MD5_ | string | iOS 6+ 的设备 ID 字段,md5 值 | 92c23c98e93a834dbeaffc4f5de1b50f |
| _CAID_ | string | iOS 14 以上设备 ID 字段,32 位 | f41fcb28e1eca2291aa5148c01a8c3f5 |
| _CAID2_ | string | iOS 14 以上设备 ID 字段,32 位。注意:caid 升级期间会回传两个 caid,广告主需要用两个 id 做关联,任一匹配即可 | b7b3ff7b623dd8df0cd58cc6f137bdc5 |
| _CAIDV_ | string | 含两个版本的 CAID 值和版本号 | urldecode 后:[{"version":"20230330","caid":"b7b3ff7b…"},{"version":"20250325","caid":"f41fcb28…"}] |
| _UA_ | string | 客户端 user agent | Mozilla%2F5.0+%28iPhone%3B+CPU+iPhone+OS+17_5_1+like+Mac+OS+X%29+AppleWebKit%2F605.1.15… |
| _CID_ | string | 点击标识 | 883920156 |
| _MODEL_ | string | 手机设备型号 | iPhone 15 Pro |
| _TASK_ID_ | long | 平台提供的广告组 ID | 480251 |
| _TASK_NAME_ | string | 广告组名称 | — |
| _PLAN_ID_ | long | 平台提供的计划 ID | 902167 |
| _PLAN_NAME_ | string | 计划名称 | — |
| _MATERIAL_ID_ | long | 平台提供的创意 ID | 6820941 |
| _MATERIAL_NAME_ | string | 物料名称 | — |
| _ACCOUNT_ID_ | string | 账户 ID | 2030866 |
附件二转化事件参数列表
type 指转化事件类型,下表描述了不同的转化事件类型的对应枚举值。
回传的转化事件的值(type 参数的值)需在列表范围内并严格按照此拼写,否则平台将无法识别具体事件类型。
| 取值 | 事件名称 | 定义 | 附加参数 |
|---|---|---|---|
| act | 激活 | 用户下载安装完毕应用之后,在联网环境下打开应用 | — |
| register | 注册 | 完成应用下载并且在联网环境打开应用后,完成个人账号注册信息提交 | — |
| leave | 次留 | 用户激活后,次日联网环境下打开应用 | — |
| active | 首活 | 用户当日首次打开应用产生活跃行为 | — |
| pay | 付费 | 用户激活后,在应用内完成了付费行为 | pay_amount字符串 · 付费金额 |
type=pay 时支持该参数,其余事件类型传入将被忽略。
- 参数名:
pay_amount - 类型:string(字符串)
- 含义:付费金额,单位为元,支持小数点后 2 位
- 示例:
pay_amount=68.00(完整回调示例见 04 节 · 付费事件)