Contract
天启媒体广告接入协议文档
V2.0
1 使用条款
x文档接收者有保密义务。未经书面许可，任何人或任何机构不得向第三方披露、泄露有关本文件的任何内容或细节。
2 名词解释
名词 | 说明 |
DSP | Demand Side Platform，需求方平台 |
SSP | Supply Side Platform，供应方平台 |
ADX | Ad Exchange，广告交易平台 |
RTB | Real Time Bidding，实时竞价 |
3 实时竞价接口
x协议基于 openRTB 协议,定义了接口和交互的标准规范，通信协议采用 HTTP 或者 HTTPS 协议，使用 POST 方式发送数据请求。开启 keep-alive，消息格式为 JSON，编码格式为 UTF-8。对于广告事件通知上报消息采用 GET 方式。
请求广告URL: xxxx://xxxx.xxxxxxxx.xxx/xxx/xxx/xxxxx
4 数据请求定义
4.1 请求头说明
请求头 | 必填 | 参数 |
Content-Type | 是 | application/json;charset=utf-8 |
4.2 Bid Request Object
参数 | 类型 | 必填 | 描述 |
id | String | 是 | x次请求唯一标识 |
imp | Xxxxx of Imp Object | 是 | 广告位信息数组，目前只支持一个 |
app | App Object | 是 | 应用信息 |
device | Device Object | 是 | 设备信息 |
user | User Object | 否 | 用户信息 |
at | Integer | 是 | 竞价类型： 0 - 优先购买（不参与竞价） 1 - 最高价格成交（参与竞价） 2 - 以次高价格成交（参与竞价）缺省：0 |
tmax | Integer | 否 | 允许接受最大响应时间，单位：毫秒（ms） |
4.3 Imp Object
参数 | 类型 | 必填 | 描述 |
id | String | 是 | 唯一标识 |
tagid | String | 是 | 广告位 ID，由平台生成提供 |
w | Integer | 是 | 广告位的宽度，单位为像素； |
h | Integer | 是 | 广告位的高度，单位为像素； |
video | Video Object | 否 | 视频广告位信息 |
bidfloor | Double | 否 | CPM 底价，单位：分 |
bidfloorcur | String | 否 | 价格单位： USD – 美元 CNY – 人民币 缺省：CNY |
4.3.1 Xxx.Xxxxx Object
参数 | 类型 | 必填 | 描述 |
w | Integer | 是 | 允许的视频尺⼨宽度 缺省：0 不限制 |
h | Integer | 是 | 允许的视频尺寸高度 缺省：0 不限制 |
minduration | Integer | 否 | 最小的视频长度，闭区间，包含最小长度单位：秒（s） 缺省：0 不限制 |
maxduration | Integer | 否 | 最大的视频长度，闭区间，包含最小长度单位：秒（s） 缺省：0 不限制 |
maxlength | Integer | 否 | 支持最大视频大小（KB） |
mimes | Array of String | 否 | 支持的视频格式，“video/mp4”，“video/x- flv”，“video/3gpp”，“video/x-msvideo”， “video/x-ms-wmv”，“video/quicktime” |
delivery | Integer | 否 | 视频加载方式： 0 – 不限 1 – 实时 2 – 预加载缺省：0 |
4.4 App Object
参数 | 类型 | 必填 | 描述 |
id | String | 否 | app 唯一标识 |
name | String | 是 | app 名称 |
bundle | String | 是 | app 包名 |
ver | String | 是 | app 版本 |
domain | String | 否 | app 官网地址 |
storeurl | String | 否 | app 下载地址 |
keywords | String | 否 | app 关键词，有多个用逗号分割 |
4.5 Device Object
参数 | 类型 | 必填 | 描述 |
ip | String | 是 | 移动设备所处⽹络的公⽹IP（⾮局域⽹IP） |
ua | String | 是 | 移动设备浏览器 User-Agent（不支持自定义） |
dnt | Integer | 否 | 是否允许广告追踪 0 - 允许 1 - 不允许缺省：0 |
geo | Geo Object | 建议 | 设备的当前地理位置信息 |
carrier | Integer | 是 | 设备使用的运营商： 0 – 其它 1 - 中国移动 2 - 中国联通 3 - 中国电信 |
mccmnc | String | 是 | MCC+MNC，详见 Mobile country code 46000、46002、46007 - 中国移动 46001、46006 - 中国联通 46003、46005 - 中国电信 |
connectiontype | Integer | 是 | 网络连接类型： 0 - 未知 1 - Ethernet 2 - WIFI 3 - Cellular Network – Unknown Generation 4 - Cellular Network – 2G 5 - Cellular Network – 3G 6 - Cellular Network – 4G 7 - Cellular Network – 5G |
devicetype | Integer | 是 | 设备类型： 1 - 手机 2 - 平板 3 - 智能 TV 4 - PC |
make | String | 是 | 设备制造商 |
brand | String | 是 | 设备品牌 |
model | String | 是 | 设备型号 |
orientation | Integer | 是 | 屏幕方向： 0 - 未知 1 - 竖屏 2 - 横屏 |
os | Integer | 是 | 操作系统类型： 0 - 未知 1 - iOS 2 - Android 3 - HarmonyOS |
osv | String | 是 | 设备操作系统版本号，例如：”10.0.1” |
osl | Integer | 否 | xx系统版本系统级别 |
w | Integer | 是 | 设备屏幕分辨率宽度，单位：像素 |
h | Integer | 是 | 设备屏幕分辨率高度，单位：像素 |
dpi | Integer | 建议 | 屏幕像素密度 |
density | Float | 建议 | 设备屏幕密度 Android 参考 DisplayMetrics.density iOS 参考 UIScreen.scale |
hwv | String | 否 | 设备硬件版本, 序列号 |
language | String | 建议 | 设备的语言设置，使用 alpha-2/ISO 639-1 |
idfa | String | 是 | 原始 IDFA 值（ios 设备必须） |
idfamd5 | String | 建议 | IDFA 的 MD5 值，全部小写 |
idfv | String | 建议 | 原始 IDFV 值（ios 设备） |
openudid | String | 建议 | 原始 openUDID 值（ios 设备） |
imei | String | 是 | 原始 IMEI 值（android 设备必须） |
imeimd5 | String | 建议 | IMEI 的 MD5 值，全部小写 |
androidid | String | 是 | 原始 Android ID （android 设备必须） |
androididmd5 | String | 建议 | Android ID 的 MD5 值，全部小写 |
oaid | String | 是 | 原始 oaid 值（android 10 以上设备必须） 移 动 安 全 联 盟 推 出 的 匿 名 设 备 标 识 符 |
mac | String | 是 | 原始 MAC 地址 |
macmd5 | String | 建议 | MAC 地址的 MD5 值，全部小写 |
imsi | String | 建议 | 国际移动用户识别码 |
ssid | String | 建议 | ⽆线⽹SSID 名称 |
wifimac | String | 建议 | WIFI 路由器 MAC 地址 |
romver | String | 建议 | 手机 ROM 版本 |
syscompilingtime | String | 建议 | 系统编译时间，时间戳 |
appstoreversion | String | 建议 | 应用商店版本号（vivo 和 oppo⼴告必填） |
bootmark | String | 建议 | 系统启动标识 |
updatemark | String | 建议 | 系统更新标识 |
timezone | String | 建议 | 时区，iOS 为必传项 |
devicenamemd5 | String | 建议 | 设备名称的MD5值，iOS 为必传项 |
hardwaremachine | String | 建议 | 设备machine值，iOS 为必传项 |
hardwaremodel | String | 建议 | 设备model值，iOS 为必传项 |
inittime | String | 建议 | 设备初始化时间戳，单位：秒，iOS 为必传项 |
startuptime | String | 建议 | 系统开机时间戳，单位：秒，iOS 为必传项 |
upgradetime | String | 建议 | 系统版本更新时间戳，单位：秒，iOS 为必传项 |
physicalmemory | String | 建议 | 物理内存大小，单位：字节，iOS 为必传项 |
harddisk | String | 建议 | 物理硬盘大小，单位：字节，iOS 为必传项 |
cpunum | Integer | 建议 | 处理器核数，iOS 为必传项 |
cpufreq | Float | 建议 | 处理器主频，iOS 为必传项 |
idfapolicy | Integer | 建议 | IDFA授权策略，iOS 为必传项0 - 未确定1 - 受限制 2 - 被拒绝3 - 已授权 |
batterystatus | Integer | 建议 | 电池充电状态，iOS 为必传项1 - 未知状态2 - 不在 充电3 - 正在充电4 - 满電状态 |
batterypower | Integer | 建议 | 电池电量比例，iOS 为必传项,例如: 60 代表 60%，80 代表 80% |
hmsversion | String | 建议 | 鸿蒙内核版本，华为设备为必传项 |
agversion | String | 建议 | 应用市场版本，华为设备为必传项 |
4.5.1 Geo Object
参数 | 类型 | 必填 | 描述 |
lat | Float | 是 | 纬度 |
lon | Float | 是 | 经度 |
country | String | 否 | 国家，使用 ISO-3166-1 Alpha-3 |
region | String | 否 | 地区，使用 ISO 3166-2 |
city | String | 否 | 城市 |
4.6 User Object
参数 | 类型 | 必填 | 描述 |
id | String | 否 | 媒体方特定的用户 ID，id 或 buyeruid 至少有一个 |
buyeruid | String | 否 | 接入方映射的用户 ID |
xxx | Xxxxxxx | 否 | 生日年份, 四位数字表示，例如:1987 |
gender | String | 否 | 性别： M - 男 F - 女 O - 其它 |
keywords | String | 否 | 用户关键字，兴趣或意向，多个用逗号分割 |
5 数据响应定义
5.1 Bid Response Object
参数 | 类型 | 必填 | 描述 |
id | String | 是 | 回填 Bid Request 中的 id |
seatbid | Array of Seatbid Object | 是 | 响应席位对象数组 |
bidid | String | 是 | DSP 响应 ID，可用于日志跟踪 |
cur | String | 是 | 货 币 类 型 USD – 美元 CNY – 人民币 |
5.2 Seatbid Object
参数 | 类型 | 必填 | 描述 |
bid | Array of Bid Object | 是 | 与请求的 imp 对象对应 |
5.3 Bid Object
参数 | 类型 | 必填 | 描述 |
id | String | 是 | 唯一标识，可用于日志追踪 |
impid | String | 是 | 对应请求中的 xxx.xx |
price | Float | 否 | CPM 出价,单位：分 |
adid | String | 否 | 广告 ID |
crid | String | 否 | 广告创意 ID |
adm | String | 否 | HTML5 广告代码段 |
materialtype | Integer | 是 | 广告素材类型： 1 - 图片广告 2 - 图文广告 3 - 文字链广告 4 - HTML5 广告 5 - 激励视频广告 6 - 原生视频广告 7 - 开屏视频广告 |
interactiontype | Integer | 是 | 广告点击交互类型： 1 - 跳转目标链接 2 - 应用下载 3 - deeplink 4 - 广点通 |
icon | String | 否 | 广告图标地址 |
w | Integer | 否 | 广告物料宽度 |
h | Integer | 否 | 广告物料高度 |
images | Array of String | 是 | 广告物料地址数组，三图信息流广告返回三张图片，其它广告返回一张图片 |
title | String | 否 | 广告文字标题 |
desc | String | 否 | 广告文字描述 |
appname | String | 否 | 下载类广告应用名称 |
appbundle | String | 否 | 下载类广告应用包名 |
appsize | Integer | 否 | 下载类广告应用大小 |
source | String | 否 | 广告来源 |
applet_id | String | 否 | 小程序原始ID |
applet_path | String | 否 | 小程序可带参路径 |
video | Video Object | 否 | 视频广告响应信息 |
targeturl | String | 是 | 广告点击跳转落地页，可以支持重定向 |
deeplinkurl | String | 否 | deeplink 点击跳转地址，若该字段有值则优先使用唤醒 app，唤醒失败则使用 targeturl 跳转落地页 |
trackers | Array of Tracker Object | 是 | 广告事件监测链接，客户端逐条汇报 |
5.3.1 Xxx.Xxxxx Object
参数 | 类型 | 必填 | 描述 |
duration | Integer | 是 | 视频的播放时长，单位：秒（s） |
url | String | 是 | 视频文件地址 |
coverurl | String | 否 | 视频封面图片地址 |
w | Integer | 否 | 视频宽度 |
h | Integer | 否 | 视频高度 |
length | Integer | 否 | 视频大小，单位：千字节（kb） |
skip | Integer | 否 | 在播放时间到达最小播放时长后是否允许出现跳过按钮： 0 - 不允许跳过 1 - 允许跳过 |
skipmintime | Integer | 否 | 视频允许跳过最小播放时长， 单位： 秒 （s），当 skip=1 时有效 |
preloadtime | Integer | 否 | 激励视频预加载后的有效时间（在该时间间隔内播放有效），单位：秒（s） |
endcardurl | String | 否 | 视频播放完成后需要展示的图片地址， endcardurl 和 endcardhtml，选择其中一个有值的进行展示 |
endcardhtml | String | 否 | 视频播放完成后需要加载的 html 代码， endcardurl 和 endcardhtml，选择其中 一个有值的进行展示 |
endicon | String | 否 | 视频播放完成后显示的广告图标 |
endtitle | String | 否 | 视频播放完成后显示的广告标题 |
enddesc | String | 否 | 视频播放完成后显示的广告描述 |
endbuttontext | String | 否 | 视频播放完成后显示的按钮文字 |
endbuttonurl | String | 否 | 视频播放完成后点击的落地页，若为空则使用 targeturl |
trackers | Array of Tracker Object | 是 | 视频播放事件监测链接，客户端逐条汇报 |
5.3.2 Bid.Tracker Object
参数 | 类型 | 必填 | 描述 |
type | Integer | 是 | 事件类型: 1 - 展示 2 - 点击 3 - 开始下载 4 - 下载完成 5 - 开始安装 6 - 安装完成 7 - 激活完成 8 - 尝试唤醒应用 9 - 唤醒应用成功 10 - 唤醒应用失败 11 - 开始播放视频 12 - 视频播放至 25% 13 - 视频播放至 50% 14 - 视频播放至 75% 15 - 视频播放完成 16 - 视频静音 17 - 跳过视频 18 - 关闭视频 |
urls | Array of String | 是 | 事件监测链接，客户端逐条汇报 |
注意：广告效果上报必须是客户端上报，监测链接除了正常的宏替换不允许作任何修改，如有部分内容不上报，会影响变现效果；上报的 ua 需要与上报请求的 ua 保持一致，否则视为无效上报。
在广告体系中需要用到的 ua 指的是移动设备浏览器 webview 的 user-agent。而非系统原始 user-agent 或者自定义 user-agent。
正确的 UA 示例：
Android：
Mozilla/5.0 (Linux; Android 8.1.0; vivo X9s Build/OPM1.171019.019; wv) AppleWebKit/537.36 (KHTML, like Gecko) Version/4.0 Chrome/00.0.0000.00 Mobile Safari/537.36
iOS:
Mozilla/5.0 (iPhone; CPU iPhone OS 12_1_2 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko)
Mobile/16C101
错误的 UA 示例：
Android:
Dalvik/2.1.0 (Linux; U; Android 9; HRY-AL00a Build/HONORHRY-AL00a) 或 kan_2.3.12(GT-
N7100,Adnroid23) 等
iOS:
类似 CFNetwork/xxxxxx 或者 Xxxxxx/14.0.0 或者 xxxxxx/7.1.5(iPhone;iOS 9.1 Scale/2.0) 等
6 宏定义
宏名 | 描述 | 场景 |
PRICE | 成交价 以密文的方式传输加密：先采用 AES/ECB/PKCS5Padding，再采用 base64-url-safe 编码 密钥：token | 赢价通知链接，展示监控链接，HTML 代码段 |
REQ_WIDTH | 广告请求中的广告位宽度，单位像素 | 点击落地页，点击监控链接 |
REQ_HEIGHT | 广告请求中的广告位高度，单位像素 | 点击落地页，点击监控链接 |
WIDTH | 实际广告位的宽度，单位像素 | 点击落地页，点击监控链接 |
HEIGHT | 实际广告位的高度，单位像素 | 点击落地页，点击监控链接 |
DOWN_X | 用户手指按下时的横坐标，如无法获取，请填“-999” | 点击落地页，点击监控链接 |
DOWN_Y | 用户手指按下时的纵坐标，如无法获取，请填“-999” | 点击落地页，点击监控链接 |
UP_X | 用户手指离开手机屏幕时的横坐标，如无法获取，请填“-999” | 点击落地页，点击监控链接 |
UP_Y | 用户手指离开手机屏幕时的纵坐标，如无法获取，请填“-999” | 点击落地页，点击监控链接 |
AB_DOWN_X | 屏幕左上角为坐标原点,用户手指按下 时的横坐标 | 点击落地页，点击监控链接 |
AB_DOWN_Y | 屏幕左上角为坐标原点,用户手指按下 时的纵坐标 | 点击落地页，点击监控链接 |
AB_UP_X | 屏幕左上角为坐标原点,用户手指离开 时的横坐标 | 点击落地页，点击监控链接 |
AB_UP_Y | 屏幕左上角为坐标原点,用户手指离开 时的纵坐标 | 点击落地页，点击监控链接 |
DP_WIDTH | 广告位的宽度，Android 端单位为逻辑 像素（dp） | 点击落地页，点击监控链接 |
DP_HEIGHT | 广告位的高度，Android 端单位为逻辑 像素（dp） | 点击落地页，点击监控链接 |
DP_DOWN_X | 手指按下手机屏幕时的x 坐标(相对于素材左上顶点), Android 端单位为逻 辑像素（dp） | 点击落地页，点击监控链接 |
DP_DOWN_Y | 手指按下手机屏幕时的y 坐标(相对于素材左上顶点), Android 端单位为逻 辑像素（dp） | 点击落地页，点击监控链接 |
DP_UP_X | 手指离开手机屏幕时的x 坐标(相对于素材左上顶点), Android 端单位为逻 辑像素（dp） | 点击落地页，点击监控链接 |
DP_UP_Y | 手指离开手机屏幕时的y 坐标(相对于素材左上顶点), Android 端单位为逻 辑像素（dp） | 点击落地页，点击监控链接 |
SLD | 广告交互方式，常规触屏点击、滑动点击、自定义手势、擦除需上报点击坐标；摇一摇、扭一扭可以不上报点击坐标，需将点击坐标宏替换为 -999 0 - 常规触屏点击 1 - 滑动点击 2 - 摇一摇 3 - 自定义手势 5 - 扭一扭 6 - 擦除 | 点击落地页，点击监控链接 |
EVENT_TIME | 时间戳，从 epoch (00:00:00 UTC on 1 January 1970)起的秒数 | 所有监控链接 |
CLICK_TIME_START | 点击时间戳，从 epoch (00:00:00 UTC on 1 January 1970)起的毫秒数 | 所有监控链接 |
CLICK_TIME_END | 离开时间戳，从 epoch (00:00:00 UTC on 1 January 1970)起的毫秒数 | 所有监控链接 |
CLICK_ID | 点击 ID | 广点通转化上报 |
DURATION | 视频总时长，单位为秒 | 视频广告监控链接 |
PLAY_BEGIN_TIME | 视频播放开始时间，单位为秒。如果视频从头开始播放，则为 0 | 视频广告监控链接 |
PLAY_END_TIME | 视频播放结束时间，单位为秒。如果视频播放到结尾，则等于视频总时长 | 视频广告监控链接 |
PLAY_FIRST_FRAME | 视频是否从第一帧开始播放。从第一帧开始播放，则为 1；否则，为 0 | 视频广告监控链接 |
PLAY_LAST_FRAME | 视频是否播放到最后一帧。播放到最后一帧，则为 1；否则，为 0 | 视频广告监控链接 |
PLAY_SCENE | 视频播放场景。推荐场景如下： 1 - 在广告曝光区域播放； 2 - 全屏竖屏、只展示视频； 3 - 全屏竖屏、屏幕上方展示视频、下方展示广告推广目标网页（仅适用于交互类型是打开网页的广告）； 4 - 全屏横屏、只展示视频； 0 - 其它开发者自定义场景； | 视频广告监控链接 |
PLAY_TYPE | 播放类型： 1 - 第一次播放； 2 - 暂停后继续播放； 3 - 重新开始播放； | 视频广告监控链接 |
PLAY_BEHAVIOR | 播放行为： 1 - 自动播放（ 推荐联网方式为 WIFI、4G、5G 时， 设置视频自动播放）； 2 - 点击播放； | 视频广告监控链接 |
PLAY_STATUS | 播放状态： 0 - 正常播放； 1 - 视频加载中； 2 - 播放错误。 | 视频广告监控链接 |
监控链接中存在的宏定义必须全部被替换，开发者在用户点击广告时需要获取点击坐标（以⼴告位左上⾓作为原点的相对值），并将上报链接中的宏定义替换成真实坐标，否则会影响收益，甚至无收益。 宏 DOWN_X 、 DOWN_Y 、 UP_X 、 UP_Y 必须替换，如因异常情况获取不到，请替换为
默认值-999。
7 落地页处理
7.1 浏览类广告（interactiontype = 1）
对于浏览类广告，targeturl 直接作为落地页地址使用。
7.2 唤醒类广告（interactiontype = 3）
使用 deeplinkurl 地址唤醒 app，如果唤醒失败则使用 targeturl 跳转到落地页。
7.3 下 载 类 广 告 （interactiontype = 2）
targeturl 直接作为下载地址使用，点击即下载。
7.4 下载类广告（interactiontype = 4）
注：此处是⼴点通⼴告特有，其他情况不需要处理。
⽤户点击时 targeturl 并不是真正的 apk 下载链接，需要终端做进⼀步处理，得到真正的下载链接和转化 id（转化 id 和收益相关，必须按要求处理），先对 targeturl 进行参数宏替换后进行 http 请求，如果 targeturl 请求返回的状态码为 200。返回内容为一个 JSON,从中可以解析出dsklink 和 clickid,其中 dstlink 为 apk 下载地址。
响应结构如下：
{
"ret":0, //0.成功 1.失败
"data":{ // APP 下载和转化上报信息
"clickid":"xxx", // clickid 需要缓存下来，用于后续转化上报
"dstlink":"xxxx://xxx" //当前广告对应的下载链接
}
}
媒体必需在后续的转化上报中，将宏 CLICK_ID 用获取到的 clickid 替换，否则会影响收益，甚至无收益。