Advertiser Integration Guide

应用推广 · 转化对接说明

打通广告主与人人视频的数据连接通路,完成转化跟踪与归因,
让广告系统找到更多高价值用户。

适用主体 · 投放自有 APP 的广告主 对接方式 · API 回调域名 · monitor.adwutong.com

01应用跟踪实现原理

广告主按要求填写点击监测链接和拼接预留宏参数。人人视频会自动替换这些宏参数并下发给广告主, 提供给广告主广告展示点击用户的 IDFA、OAID、ANDROIDID、CAID 等用户设备信息、回调链接及其他相关信息。 广告主将其与自己监测到的转化用户的相关信息进行匹配后,通过回调链接回传转化数据给媒体。

02应用推广类 API 对接流程

  1. 广告主填写点击监测链接并投放广告用户在 APP 内点击广告。
  2. 人人视频向广告主上报点击事件调用广告主填写的点击监测链接,并替换宏参数,上报用户设备信息、转化回调链接及其他相关信息。
  3. 用户在广告主 APP 产生转化
  4. 广告主完成匹配归因根据人人视频上报的设备信息与自己 APP 监测到的转化设备信息进行匹配归因。
  5. 广告主回传转化事件通过转化回调链接回传给媒体。

2.1 对接点击上报服务

广告主在新建应用转化时,需要填写点击监测链接,用来接收人人视频上报的点击事件,进而完成转化归因。

2.2 通信协议

支持通过 HTTP 或 HTTPS 通道进行请求通信。为了获得更高的安全性,推荐使用 HTTPS 通道; 如果您使用的是 http 通道,需保证也能支持 https 通道。

2.3 请求方法

支持 GET 方法发送请求,这种方式下请求参数需要包含在请求的 URL 中。

2.4 格式要求

点击监测链接主要由四部分组成:

https://www.xxx.com? + 自选宏参数 + 回调链接宏参数 + 自定义参数(可选)

点击监测链接示例

click_track_url
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 示例 · 激活

callback_activate
http://monitor.adwutong.com/ad-action/click/callback?uid=820634
  &timestamp=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 位)。参数明细见附件二。
callback_pay
http://monitor.adwutong.com/ad-action/click/callback?uid=820634
  &timestamp=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,标准返回值如下;失败:其他值。

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

05渠道包投放场景转化回调服务

说明:适用于 PC 游戏、安卓游戏等渠道包投放场景,将渠道包投放带来的转化事件进行转化回调。
适用归因方式:渠道包归因(apk 下载包/exe 下载包)、落地页 URL 渠道跟踪参数归因。

5.1 对接转化事件回调服务

完成归因后,用户在应用中达成转化事件时,广告主需要通过 API 回调媒体用户转化事件。

5.2 通信协议

目前接口仅支持通过 HTTP 方式进行请求通信。

GET http://monitor.adwutong.com/ad-action/click/callback

5.3 请求方法

请使用 GET 方法发送请求,这种方式下请求参数需要包含在请求的 URL 中。

5.4 参数说明

参数名类型必选说明
typestring是转化类型。参考「附件二:转化事件参数列表」,样例 act(激活事件)
timestamplong是转化事件发生时间(毫秒),UTC 时间戳
trackIdstring是用于追踪来源广告的追踪 ID(若投放链路为 apk/exe,则否)。请联系商务获取
ipstring否设备的联网公网 IPv4 地址。IPv4 格式,四段点分(A.B.C.D)
oaidstring否Android Q 及更高版本的设备号。H5 页面、PC 游戏等获取不到 oaid 场景的,使用空值
pay_amountstring否付费金额。若回传事件为付费,可拼接 pay_amount 字段传入付费金额(单位元,支持小数点 2 位)
uastring否数据上报用户终端设备的 User Agent。样例 Mozilla 5.0(Linux Android4.0.4 GTI9220 Build IMM76D)

5.5 请求示例

回调链接地址示例

callback_url
http://monitor.adwutong.com/ad-action/click/callback?type=pay
  &timestamp=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)

OkHttpCallback.java
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&timestamp=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

request.sh
curl --location 'http://monitor.adwutong.com/ad-action/click/callback?oaid=a557ce7503c8396ebe77367b54dc7651&type=pay&timestamp=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 返回值

response.json
{
    "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&timestamp=1767196800000&type=act&…
_IP_string媒体投放系统获取的用户终端的公共 IP 地址116.236.101.90
_OS_string操作系统平台,ios 或 androidios
_IMEI_MD5_stringAndroid 的设备 ID 的 md5 加密,32 位—
_OAID_stringAndroid Q 及更高版本的设备号—
_OAID_MD5_stringAndroid Q 及更高版本的设备号 md5 加密,32 位—
_ANDROIDID_stringAndroid ID 原值—
_IDFA_stringiOS 6+ 的设备 ID 字段,32 位63557E56-67E6-4359-9F28-998736FA28B7
_IDFA_MD5_stringiOS 6+ 的设备 ID 字段,md5 值92c23c98e93a834dbeaffc4f5de1b50f
_CAID_stringiOS 14 以上设备 ID 字段,32 位f41fcb28e1eca2291aa5148c01a8c3f5
_CAID2_stringiOS 14 以上设备 ID 字段,32 位。注意:caid 升级期间会回传两个 caid,广告主需要用两个 id 做关联,任一匹配即可b7b3ff7b623dd8df0cd58cc6f137bdc5
_CAIDV_string含两个版本的 CAID 值和版本号urldecode 后:[{"version":"20230330","caid":"b7b3ff7b…"},{"version":"20250325","caid":"f41fcb28…"}]
_UA_string客户端 user agentMozilla%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平台提供的广告组 ID480251
_TASK_NAME_string广告组名称—
_PLAN_ID_long平台提供的计划 ID902167
_PLAN_NAME_string计划名称—
_MATERIAL_ID_long平台提供的创意 ID6820941
_MATERIAL_NAME_string物料名称—
_ACCOUNT_ID_string账户 ID2030866

附件二转化事件参数列表

type 指转化事件类型,下表描述了不同的转化事件类型的对应枚举值。 回传的转化事件的值(type 参数的值)需在列表范围内并严格按照此拼写,否则平台将无法识别具体事件类型。

取值事件名称定义附加参数
act激活用户下载安装完毕应用之后,在联网环境下打开应用—
register注册完成应用下载并且在联网环境打开应用后,完成个人账号注册信息提交—
leave次留用户激活后,次日联网环境下打开应用—
active首活用户当日首次打开应用产生活跃行为—
pay付费 用户激活后,在应用内完成了付费行为 pay_amount
字符串 · 付费金额
pay_amount 说明 仅当 type=pay 时支持该参数,其余事件类型传入将被忽略。
  • 参数名:pay_amount
  • 类型:string(字符串)
  • 含义:付费金额,单位为元,支持小数点后 2 位
  • 示例:pay_amount=68.00(完整回调示例见 04 节 · 付费事件)