oCPX媒体对接文档
更新日志
| 版本 | 更新日期 | 更新描述 |
|---|---|---|
| 1.0.0 | 2024-10-04 | 初始化文档 |
概述
为了准确评估媒体投放的转化效果，优化广告投放提供指导和参考，我们推出了支持接收媒体上报点击及给媒体回传转化事件的API对接方案。
业务流程
- 我方提供接收广告点击数据的监测链接，接收媒体上传的点击数据。
- 我方将匹配成功的转化数据通过callback参数回调给媒体。
接口设置流程
- 申请监测链接，不同的推广活动对应不同的监测链接。监测链接支持同步及异步两种，媒体可根据需求自主选择。
- 点击上报接口接收媒体提供的点击信息：
- 请求方：媒体
- 处理方：我方服务器
- 请求协议：HTTP/HTTPS
- 参数由我方根据具体活动信息自动生成，callback转化回调接口地址由媒体通过宏替换提供，我方通过此地址，将转化数据回调给媒体
以slot=1为例，点击监测链接示例如下：
https://bid.adbiding.cn/bid?slot=1&mid=1&bnd=__BRAND__&m0=__OPENUDID__&m11=__OAID__&m70s=__CAIDS__&m11a=__OAID1__&m1a=__ANDROIDID__&m2=__IMEI__&m2a=__SIMEI__&m4=__AAID__&m5=__IDFA__&m5a=__IDFA1__&m6=__MAC1__&m6a=__MAC__&m70=__CAID__&m70a=__CAID1__&mdl=__MODEL__&mo=__OS__&nn=__APP__&ns=__IP__&tr=__REQUESTID__&ts=__TS__&ua=__UA__&wf=__WIFI__&cb=__CBURL__&amod=c
点击监测宏定义说明
| 字段含义 | 宏名称 | 宏参数 | 字段定义 | 是否必填 |
|---|---|---|---|---|
| 操作系统 | mo | __OS__ | 枚举值0: Android; 1: iOS; 2:WindowsPhone;3:Others | 必填 |
| IP地址 | ns | __IP__ | 投放系统服务器观察到的用户远程IP | 必填 |
| OAID | m11 | __OAID__ | 终端的oaid，原值 | 条件必填 |
| OAID MD5 | m11a | __OAID1__ | 针对设备OAID取md5 | 选填 |
| AndroidID MD5 | m1a | __ANDROIDID__ | Android设备ID，AndroidID取md5值 | 选填 |
| APP NAME | nn | __APP__ | App名 urlencode | 选填 |
| APK NAME | apk | __APK__ | App包名 urlencode | 选填 |
| OS version | ov | __OSV__ | 操作系统版本号 15.0.0 | 选填 |
| Android ID | m1 | __AndroidID__ | AndroidID原值 | 选填 |
| IMEI | m2 | __IMEI__ | IMEI（Android设备ID），IMEI取md5 | 必填 |
| IMEI | m2a | __SIMEI__ | IMEI，取原值 | 选填 |
| IDFA | m5 | __IDFA__ | IOS设备ID。取原值，32位十六进制数字+4位连接符"-"，iOS6及以上使用 | 条件必填 |
| IDFA MD5 | m5a | __IDFA1__ | IDFA原值转大写后取md5 | 选填 |
| MAC | m6a | __MAC__ | 去除分隔符”:”的大写MAC地址取md5 | 选填 |
| MAC MD5 | m6 | __MAC1__ | 保留分隔符":"，(保持大写)，取 md5 | 选填 |
| CAID | m70 | __CAID__ | CAID原值，格式为caid版本_caid（取最新的版本） | 条件必填 |
| CAID MD5 | m70a | __CAID1__ | CAID原值取md5，格式为"版本_caid" md5（取最新的版本） | 选填 |
| 时间戳 | ts | __TS__ | 投放发⽣时的Unix时间戳，毫秒 | 必填 |
| UA | ua | __UA__ | User Agent信息，明文 | 必填 |
| 设备品牌 | bnd | __BRAND__ | 手机设备厂商，明文 | 选填 |
| 设备型号 | mdl | __MODEL__ | 手机机型，明文 | 选填 |
| 网络类型 | wf | __WIFI__ | 枚举值： 0： 2/3/4G; 1： wifi | 选填 |
| 请求id | tr | __REQUESTID__ | 请求的唯一标识 | 必填 |
| cpa 回调监测 | cb | __CALLBACK__ | 系统支持的cpa回调监测宏，只有点击监测支持该宏 | 选填 |
| 广告主ID | madvi | __M_ADVID__ | 媒体方广告主ID或者标识 | 选填 |
| 创意ID | mci | __M_CID__ | 媒体方创意ID | 选填 |
| 素材ID | mmi | __M_MID__ | 媒体方素材ID | 选填 |
| 广告组ID | madgi | __M_ADGID__ | 媒体方广告组ID | 选填 |
| 广告ID | mai | __M_ADID__ | 媒体方广告ID | 选填 |
| 广告计划ID | mcpi | __M_CPID__ | 媒体方广告计划ID | 选填 |
点击监测补充说明
点击监测上支持宏 __CALLBACK__ 可以供媒体动态替换成媒体侧的cpa回调地址，我方会在有转化时通过 callback url 回传给媒体(服务端回调)。 针对动态回调，将会在媒体传入的 callback_url 地址后拼接event_type。 event_type 枚举值如下：
| 事件 | 值 |
|---|---|
| 激活 | activate |
| 注册 | register |
| 表单提交 | commit_msg |
| 唤起 | open_app |
| 下载 | download |
| 加购 | add_cart |
| 支付 | pay |
| 次日留存 | retained |
| 2日留存 | retained_2d |
| 3日留存 | retained_3d |
| 4日留存 | retained_4d |
| 5日留存 | retained_5d |
| 6日留存 | retained_6d |
| 7日留存 | retained_7d |
| 授信 | credit |
| 首次下单 | new_order |
| 下单 | old_order |
| 关键行为 | addiction |
| 自定义1 | custom1 |
| 自定义2 | custom2 |
例如:callback_url 为 http://abc.com?param1=a ，会改写成 http://abc.com?param1=a&event_type=activate
其他
为了保证归因的准确性，媒体侧需要尽可能的将获取到的设备号参数都替换，设备号宏参替换优先级如下： • IOS： idfa>caid>ip+ua；（idfa、caid为空时，则 ip+ua 必传） • 安卓：imei>oaid>ip+ua；（imei、oaid 为空时，则 ip+ua 必传）