供应商接入文档 · CPA 合作

本文档面向 CPA 采买供应商，规范点击上报与转化回传的技术契约。 供应商仅需对接 C 端接口即可跑通完整业务流程；B 端接口为可选的数据查询能力。

C 端 · 上报数据（必需）

http://monitor.mardenad.com

点击上报 /ad-action/click · 转化回传 callback

B 端 · 数据查询（可选）

https://agency.mardenad.com

任务投放状态 · 跑量数据报表（T+1）

00概述

CPA 采买旨在通过供应商提供流量点击的方式，达成投放的有效归因，从而实现我方投放的转化目标。

业务流程由两段构成，二者相互独立：

C 端（必需）：供应商上报点击事件 → 我方归因 → 我方按 callback 回传转化事件。完成本段即视为业务跑通。
B 端（可选）：供应商凭 token 主动查询任务投放状态与跑量数据，用于自助对账。

AC 端接口 · 上报数据必需

C 端接口承载点击上报与转化回传两个动作，是供应商接入的最小闭环。供应商完成本章对接后，业务流程即可正常运行，无需接入 B 端。

1.1产品矩阵登记

接入前请先与销售侧沟通，登记本次合作覆盖的产品矩阵流量（产品名称 + 包名），用于后续归因与数据核对。

产品名称	包名
携程	`ctrip.android.view`
同程	`com.tongcheng.android`

1.2点击上报

1.2.1接口地址

GET http://monitor.mardenad.com/ad-action/click

请求方：广告媒体（供应商）
接收方：我方广告点击上报服务
协议：HTTP / HTTPS
返回码：200 正常返回；404 / 500 异常
宏参数请严格按下表替换（双下划线 __XXX__ 形式）

android_click_endpoint

// Android · 替换宏参数后 GET
http://monitor.mardenad.com/ad-action/click?userId=xxxxxx
  &imeiMd5=__IMEI__
  &oaid=__OAID__
  &oaidMd5=__OAID_MD5__
  &androidId=__ANDROID_ID__
  &androidIdMd5=__ANDROID_ID_MD5__
  &ts=__TS__
  &ip=__IP__
  &os=__OS__
  &ua=__UA__
  &model=__MODEL__
  &callback=__CALLBACK__
  &requestId=__REQID__
  &clickId=__CLICK_ID__

ios_click_endpoint

// iOS · 替换宏参数后 GET
http://monitor.mardenad.com/ad-action/click?userId=xxxxxx
  &caid=__CAID__
  &idfa=__IDFA__
  &idfaMd5=__IDFA_MD5__
  &ts=__TS__
  &ip=__IP__
  &os=__OS__
  &ua=__UA__
  &model=__MODEL__
  &callback=__CALLBACK__
  &requestId=__REQID__
  &clickId=__CLICK_ID__

说明 userId=xxxxxx 由我方定义并分配，用于标识本次采购流量对应的投放主体。

1.2.2宏参数说明

宏参数	必填	说明
__CAID__	否	中国广告协会推出的广告标识符，有版本号概念；后端算法升级时会获得升级前后的两个 caid。标准格式 `[{"caid":"…","version":"20220111"}, …]`，序列化为 JSON 字符串后透传
__IDFA__	否	iOS 设备 ID，仅 iOS 6+ 有效，用于 iOS 设备用户识别和兴趣投放
__IDFA_MD5__	否	32 位 idfa MD5 值
__TS__	是	广告点击时间，unix 时间戳毫秒（ms）
__TS_S__	是	广告点击时间，unix 时间戳秒（s）
__IP__	是	IPv4：A.B.C.D（四段，以 `.` 分隔）；IPv6：需 encode 一次
__OS__	是	操作系统类型，`ios` / `android`
__UA__	是	设备 User Agent，urlencode 编码
__MODEL__	否	设备型号，如 `iPhone6s`
__IMEI__	是	32 位 imei MD5 值
__OAID__	是	oaid 原值
__OAID_MD5__	是	32 位 oaid MD5 值
__ANDROID_ID__	否	androidid 原值
__ANDROID_ID_MD5__	否	32 位 androidid MD5 值
__REQID__	否	RTA 请求 ID，接入了 RTA 时该字段必填
__CLICK_ID__	是	由 req_id + 时间戳生成，根据具体产品与运营确认必传
__PASS_THROUGH__	否	支持多包场景下必填
__CALLBACK__	是	回调 URL（用于转化回传，供应商侧动态替换），urlencode 编码

1.2.3请求结果

参数名称	说明
code	`200` 成功；其他为异常，详见错误码列表
msg	请求结果描述

验收上报后请观察转化回传数据的情况，确认无问题即视为 C 端接入完成。

1.3转化回调

1.3.1回调地址说明

__CALLBACK__ 转化回传地址在点击上报请求时由供应商侧动态替换。当发生转化行为时，我方会在 callback 后拼接对应的 event 事件类型发起回调。

1.3.2事件类型定义

事件类型	说明
activate	激活
register	注册
leave	次日留存
pay	用户付费
first_activate	首活

1.4完整参数示例

Android 端替换宏参数后的完整请求示例：

android_click_full

http://monitor.mardenad.com/ad-action/click
  ?userId=123
  &imeiMd5=f549a70edc6379c7a446a5e46a1cf923
  &oaid=1743d5a8-172d-4079-9b92-08e74ce59963
  &ts=1704038400000
  &ip=192.168.0.1
  &os=android
  &ua=Mozilla%2F5.0%20%28iPhone%3B%20CPU%20iPhone%20OS%2011_4_1%20like%20Mac%20OS%20X%29%20AppleWebKit%2F605.1.15%20%28KHTML%2C%20like%20Gecko%29%20Mobile%2F15G77
  &model=iPhone6s
  &callback=http%3A%2F%2Fapi.XXXX.com%2Factivate.api%3Fxxx%3Dxxx

其中转化回传地址为 http://api.XXXX.com/activate.api?xxx=xxx。发生转化时我方会拼接对应事件后回调，例如 http://api.xxxx.com/activate.api?xxx=xxx&event=activate。

参数	说明
userId	采购流量的投放主体标识，由我方固定给出，例如 `123`
imeiMd5	imei 原值进行 32 位 MD5 加密
oaid	oaid 原值
ts	毫秒时间戳
ip	设备点击 IP；IPv4：A.B.C.D（以 `.` 分隔）；IPv6：需 encode 一次
os	操作系统，`ios` / `android`
ua	设备 User Agent，urlencode 编码
model	设备型号，如 `iPhone6s`
callback	接收转化回传的地址。如需性别回传，请在回传链接中拼接宏参数 `gender=__GENDER__`，我方回调时会替换（`0` 女 / `1` 男），例如 `gender=1`

注意如需要曝光监测和 RTA，请单独联系。

BB 端接口 · 数据查询可选

B 端接口用于供应商自助查询任务投放状态与跑量数据，不影响业务流程运行。未接入 B 端的供应商仍可正常完成点击上报与转化回传。

API Base

https://agency.mardenad.com

任务投放状态 / 数据报表

数据更新频率

T + 1

跑量数据每日更新；最大查询跨度 7 天

2.1鉴权方式

接入前请联系商务运营获取访问令牌 token 及 API 请求地址，所有 B 端请求需携带 Header：

字段	说明	备注
Authorization	token 认证信息	`Bearer xxxxxxxx`，联系商务运营获取

2.2查询任务投放状态

GET https://agency.mardenad.com/media/cpa/task/info

请求 Query

字段	说明	备注
taskId	我方分配的 taskId	—
passThrough	支持多包任务参数	—

返回字段

字段	说明	备注
taskId	任务 ID	—
passThrough	多包任务参数	与查询时 `passThrough` 一致
status	任务状态	`1` 开启 / `0` 关闭
price	采购出价	单位：分

2.3查询任务或产品跑量数据

POST https://agency.mardenad.com/media/cpa/task/summary

请求 Body

字段	说明	备注
type	查询维度	`1` task 维度 / `2` 产品维度，默认 task 维度
taskId	我方分配的 taskId	—
startDate	查询开始时间	例如 `2024-09-18`
endDate	查询结束时间	例如 `2024-09-24`；最大查询跨度 7 天

返回字段

字段	说明	备注
dt	日期	例如 `2024-09-18`
vendorName	供应商名称	已弃用，不返回
productId	产品包名	例如 `com.xs.fm`
productName	产品名称	例如番茄畅听
platform	平台	`android` / `ios`
actNum	转化数	—
leaveNum	次留数	—
payNum	付费数	—
registerNum	注册数	—
liveNum	首活数	—
payAmount	付费金额	单位：元

C运行流程图

供应商侧只需对接我方系统：上报点击 → 接收转化回调 → （可选）查询跑量数据。

图 1 · 供应商与我方系统交互链路

D附录：错误码列表

说明 message 内容会根据实际的错误内容变化，下表仅作参考。

错误码	含义	Message	触发条件
200	成功	`ok`	请求正常处理
201	任务状态异常	`Invalid UserId`	无效的任务 ID
202	预算撞线	`the account cannot be used for delivery`	账户超出日预算限制
203	余额不足	`Insufficient account balance`	账户余额不足
204	参数校验失败	`miss required param`	缺少必填参数
205	参数过长	`param is too long`	参数超过字符长度限制
300	系统异常	`系统异常`	未知系统错误