启明ADX 广告API接入文档（v1.1.0）

—# 启明ADX 广告 API接入文档 (v1.1.0)

更新日志

::: tip
RTB对接请务必留意 5. RTB对接重点和5.1 价格加密。
:::

1. 请求协议说明

媒体广告平台和启明ADX之间的基础通信协议采用HTTP协议, 使用POST方法发送BidRequest消息, 消息格式为json;

启明ADX支持对请求和响应进行压缩, 压缩算法仅支持gzip; 如果媒体广告平台需要使用压缩, 请根据请求头和响应头进行标识;

编码: utf-8

1.1 请求地址

1.2 请求头

1.3 响应头

2. 请求参数说明(Request)

请求Json结构

2.1 App对象

2.2 AdPosition对象

2.3 Device对象

2.4 Deal对象

::: tip
（1）对安卓设备请求，imei、android_id、oaid至少要填写其中一个

（2）对于iOS设备请求，idfa、10个设备信息字段( modelNo~timeZone)三者至少填写一个，如果无idfa则10个设备信息字段都必填

（3）部分设备参数获取方法示例
:::

3. 响应参数说明(Response)

响应Json结构

3.1 Ad Object

3.2 Video Object

3.3 AppPromotion Object

3.4 Tracker Object

4. 广告上报宏替换

用户在曝光, 或者点击等其他广告上报事件中, 需要将上报 URL 中的宏定义替换成真实的值, 否则会影响收益, 甚至无收益, 如因异常情况获取不到.

5. RTB对接重点

• 接入RTB流量可返回价格, 参与媒体 ADX 的实时竞价. 媒体需返回结算价格(一般为 GSP 二价结算)
• Ad物料结构中的winNoticeUrl为启明ADX的竞价成功监测地址, 当启明ADX在媒体ADX竞价成功时, 媒体服务端立即通过此地址通知启明ADX, 注意不能在客户端发送, 媒体通知启明ADX前, 需要替换url中的价格宏占位; 当竞价不成功时, 不需要通知
• 结算价格为CPM价格, 单位:分, 整数形式, 不应高于启明ADX物料中bidPrice竞价价格. 在启明ADX的竞价成功通知和其他监测上报中(如展示上报, 点击上报等), 可能会包含价格宏占位, 媒体对启明ADX的结算价格加密后替换整个宏占位, 若URL中包含多个价格宏, 需支持多次替换.

5.1 价格加密

1. winNoticeUrl和tracker中的监测上报如果包含宏__ADS_BID_PRICE__, RTB接入方需要把自己的出价经过加密后, 与这个宏进行替换
2. 加密库选择 AES/ECB/PKCS5Padding, AES密钥: 联系启明ADX对接人获取

3. 加密出的结果, 需要经过UrlEncode, 不支持带小数点价格

加密案例

价格: 99
加密后结果: SMbvQwvZoyzKu6nh//Rb2w==
UrlEncode后结果：SMbvQwvZoyzKu6nh%2F%2FRb2w%3D%3D

5.2 竞败上报

lossNoticeUrl中需要替换的宏:

6 常量定义

6.1 广告样式

6.2 物料类型

6.3 交互类型

6.3.1 下载类 (action=3)

跳转url优先级:deeplink > wechatId / wechatPath > landingPageUrl

• 媒体根据支持的跳转类型及返回的相关字段，按上述优先级进行跳转处理
• 针对应用直达广告（deeplink存在），调用deeplink字段调起应用，调起失败调用landingPageUrl进行兜底
• 针对非应用直达广告, 支持优先应用市场下载时(downloadType=1)可选择跳转应用市场, 开发者调用下载应用前，配合使用appPromotion等字段，通过弹窗等形式向用户展示应用名称、版本等应用相关信息，提示用户是否确认进行下载

6.3.2 其他

跳转url优先级:deeplink > wechatId / wechatPath > landingPageUrl

• 媒体根据支持的跳转类型及返回的相关字段，按上述优先级进行跳转处理
• 针对应用直达广告（deeplink存在），调用deeplink字段调起应用，调起失败调用landingPageUrl进行兜底
• 针对非应用直达广告，属于微信小程序/小游戏广告时（wechatId/wechatPath存在），优先调用微信 openSDK 处理 wechatId/wechatPath 字段，跳转至微信小程序/小游戏页面
• 针对非应用直达和非微信小程序/小游戏广告，调用landingPageUrl跳转落地页

6.4 互动样式

6.5 互动玩法

6.6 下载类型

6.7 deeplink类型

7. 普通广告点击说明

如果有deeplinkUrl链接, 优先使用deeplinkUrl唤醒应用, 可能有deeplink事件需要上报;
| 字段 | 事件类型 | 上报时机 |
| :—- | :—– | :—— |
| tryDeeplink | 尝试调起deeplink | 用户点击应用直达广告后，尝试调用deeplinkUrl 或 iOS Universal link (deeplinkType =1 时) 或 时 |
| deeplink | deeplink调起成功 | Android端：调用 deeplinkUrl10秒后，检测开发者的app（即发起deeplink调起的宿主app）是否在后台，当在后台时上报唤起成功；
iOS端：调用 iOS Universal link (deeplinkType =1 时) 或 deeplinkUrl 后，iOS系统接口返回结果显示应用直达未被系统弹窗取消时，上报唤起成功 |

返回Tracker Object

8. 腾讯广告广告点击说明 (仅安卓需要处理)

当交互类型为腾讯广告下载时, 即action是4, 需按如下步骤获取实际落地页地址及相关操作

8.1 第一步:

客户端获取广告后请求landingPageURL地址(如果包含宏替换, 需要客户端先替换相应的宏参数再请求)

8.2 第二步:

根据替换后的landingPageUrl, 发起GET请求获取真正的落地页信息, 返回为json格式, 然后从json串中获得真实的落地页地址

响应Json示例如下:

 {
    "ret" : 0,    // 返回码; 0:成功, 1:失败
    "data" : {   // APP下载和转化上报信息
        "dstlink" : "http://xx.apk", // 当前广告对应的下载链接
        "clickid" : "ad45af45adf" // 需要缓存下来, 用于后续转化上报
    }
 }

参数说明:

8.3 第三步:

根据获取的目标地址dstlink进行相应的操作;

后续操作(下载开始, 下载完成, 安装开始, 安装完成等)执行事件上报前, 需要将上报URL进行宏替换, 需要替换的宏如下(如果存在的话):

9. 状态码

这里的状态码不是http状态码, 是返回Json结构中, code的定义码

10. Q&A

Q1. 出现问题如何快速排查?

A. 首先根据文档中的’code’和’message’; 如果自查查看是什么原因后无法解决, 请提供请求的响应头x-tm-traceid, 寻求启明ADX技术支持;