跳到主要内容

媒体对接文档

接入须知

  1. 法律声明

媒体与本公司签订合同后,本公司向媒体提供对接协议作为指引文档。

未经我方书面许可,不得以任何形式向第三方披露、泄露有关本文档的任何内容。

修订历史

文档版本修订日期修订描述
2.0.02024-06-04修改imp.adtype,imp.ctype,device.connection_type 定义
2.1.02024-06-05增加response app定义,app_version下列字段,提供给app下载用
2.2.02024-07-12增加设备启动时间等
2.3.02024-08-01广告位宽高,formids信息变成必填,废弃tagid
2.4.02024-08-23新增paid,caids字段
2.5.02024-08-27增加imp.support_size_type 支持横竖版强制要求
2.6.02025-01-16支持loss notice, 支持返回code & not biding reason
2.7.02025-02-11添加华为媒体特殊字段支持: 响应中,bid.ext新增huawei_cat、language、advertiser字段,img和video新增mime字段
2.8.02025-02-20支持请求Ext字段,增加流量来源标识
2.9.02025-04-18请求Imp中支持填入多个广告位尺寸

[TOC]

整体流程

本文档描述媒体方如何通过客户端c2s的方式或者服务端s2s的方式请求我方SSP广告系统的通用接口。

基本流程如下:

image-20250208101432545

  1. 媒体方向SSP发送广告请求,请求数据见BidRequest说明。
  2. SSP内部通过竞价产生出合适的广告,SSP将内部竞价成功的广告返回给向媒体方,返回数据格式详情见BidResponse说明。
  3. 媒体上报返回的曝光点击监控等。

广告竞价

所有参数均采用UTF-8编码。

HTTP请求类型

媒体方设置HTTP Method为POST。

HTTP请求Header

媒体方设置Content-type为application/json

媒体方设置在条件允许的前提下使用长链接来持续发起广告请求。

1. 广告请求Bid Request说明

字段类型必须说明
idstringY请求唯一ID
impobject[]Y广告位信息,1.1imp对象
appobjectY媒体的app信息 1.2app对象
deviceobjectY设备信息
siteobjectN站点信息对象,浏览器端
userobjectN用户信息对象
tmaxintN超时时间(毫秒),默认100ms
testboolN测试模式,默认false
extobjectN扩展字段,详见章节1.8

1.1 Imp 对象

字段类型必须说明
idstringYimp唯一id
slotidstringY平台分配的广告位id,推荐使用平台分配广告位id
tagidstringN媒体方广告位ID,废弃, 不使用
wintY广告位宽,推荐必填
hintY广告位高,推荐必填
sizesSize[]N额外可支持的广告位尺寸
mindurationintN视频广告最小播放时长,单位:秒
maxdurationintN视频广告最大播放时长,单位:秒
formidsint[]Y广告广告展现形式ids,见 附录1。推荐必填
adtypeintN广告位类型(1 : 视频贴片, 2 : 视频暂停 ,3. 视频悬浮 ,4 : 横幅, 5 : 开屏, 6 : 插屏, 7 : 信息流 ,8: 文字链, 10: 激励视频)。
ctypeint[]N允许的素材类型 (1: JPG,2. PNG, 3:GIF, 4:JPEG, 5:SWF, 6:MP4, 7:FLV, 8:文字链, 9:信息流, 10:视频信息流 )。
bidfloorfloatN底价(分/cpm)
bidtypeintN售卖方式,0:cpm;1:cpc ,default = 0
pmpPMP[]NPMP 模式
secureintN是否只支持https,0-无要求,http和https都支持;1-只支持https
support_interactint[]N支持的交互类型(0:不限;1:webview;2:下载;3:微信小程序唤起;4:deeplink唤起),为空或者传0则默认都支持
support_size_typeint[]N支持的素材的横竖版判断,1:横版,2:竖版。支持多选,不填则为不限。

1.2 Size 对象

字段类型必须说明
wintY广告位宽
hintY广告位高

1.3 App 对象

字段类型必须说明
idstringNapp id
namestringNapp name
verstringNapp 版本
sdk_versionstringNsdk版本
bundlestringNapp 包名
catstring[]Napp 类型

1.4 Device 对象

字段类型必须说明
imeistringN设备号,IMEI(安卓设备imei,imeimd5至少一个必填)
imeimd5stringN设备号的imei MD5值,32位小写
oaidstringN设备标识,OAID(安卓10以上,oaid,oaidmd5至少一个必填)
oaidmd5stringN设备标识的oaid MD5,32位小写
aidstringNAndroid Id
aidmd5stringNAndroid Id 的 MD5,32位小写
idfastringNIos唯一标示,idfa原值(ios系统idfa,idfamd5至少一个必填)
idfamd5stringNidfa的md5, 32位小写
caidstringNIOS14后idfa的替代方案,广协caid
caid_versionstringNcaid sdk版本号,多个使用最新版本
ali_aaidstringNali aaid,需对接ali aaid sdk,可不填
osintN操作系统 (0 :未知 ,1 :ios,2 :android,3 :windows phone, 4 : symbian, 5 :windows, 6 :Mac OS,7:其他)
osvstringN操作系统版本号字符串
makestringN设备制造商同brand
modelstringN设备型号
devicetypeintN设备类型 1:手机;2:PAD ;3:移动设备;4: PC;5:智能电视
ipstringNip
macstringNmac 地址
macmd5stringNmac地址的md5
uastringNuser agent
carrierintN运营商 0:未知;1:移动;2:联通;3:电信
connection_typeintN网络类型 0:其他;1:WIFI;2:2G;3:3G;4:4G;5:5G;6:局域网
swintN屏幕宽
shintN屏幕高
denfloatN屏幕密度
oriintN屏幕方向 1:竖屏,2:横屏,0:未知
geoobjectN地域信息
boot_markstringN系统启动标识,取原值回传。 iOS:1623815045.970028;Android:ec7f4f33-411a-47bc-8067-744a4e7e0723
update_markstringN系统启动标识,取原值回传。 iOS:1581141691.570419583;Android:1004697.709999999
verCodeOfHmsstringNHMS Core 版本号。实现被推广应用的静默安装依赖 HMS Core 能力,华为设 备必填
verCodeOfAGstringN应用市场版本号。与下载类广告的转化路径有关。华为设备必填
agCountry_codestringN应用市场中设置的国家地区,华为设备推荐填,例:CN
device_namestringN设备名
device_modelstringN硬件机型 如"iPhone10,3"
device_init_timestringN系统初始化时间
device_startup_timestringN系统启动时间
device_upgrade_timestringN系统更新时间
system_total_memint64N系统总内存,单位:KB
system_free_memint64N系统剩余内存,单位:KB
system_total_diskint64N系统总磁盘,单位:KB
system_free_diskint64N系统剩余磁盘,单位:KB
languagestringN例:zh-Hans-CN
ppiintN屏幕 ppi
paidstringN拼多多paid
caids[]stringN历史版本caid,格式:version+_+ caid ,(CaidVersion+下划线+Caid)

1.5 Geo 对象

字段类型必须说明
latfloatN纬度
lonfloatN经度
geotypeintNgeo坐标系类型(1: WGS84,2:GCJ_02火星,3:BD_09百度,4:BD_09_LL百度墨卡)
citystringN城市名

1.6 Site 对象

字段类型必须说明
namestringN站点名称
domainstringN站点域名
pagestringN当前站点页面url
refstringNReferrer url

1.7 User 对象

字段类型必须说明
idstringN媒体端用户id,一般pc和wap端为媒体cookie id
genderstringN性别(M: 男,F: 女,缺省:未知)
ageintN年龄
audience_tagstring[]N兴趣标签,标签体系线下沟通
app_liststring[]N用户app安装列表

1.8 PMP 对象

字段类型必须说明
dealstringYdeal id
priceintNdeal 价格,单位:分

1.9 Ext 对象

字段类型必须说明
sourcestringN流量来源标识,例如: huawei, xiaomi, sina, ...

附录

1. 广告展现形式id(formid)

形式id说明
1一图二文 标题描述
2一图一文
3单图片
4单视频
5三图文
6一图一视频
7一图一icon
8文字链
9三图一icon

2. 广告响应Bid Response说明

正常竞价返回 HTTP 200 OK,同时返回body。

无广告返回。

字段类型必须说明
idstringYresponse id 和request id保持一致
seatbidobject[]N如果参与竞价,必须包含一个seatbid对象, 2.1seatbid对象
bididstringN由ssp生成的response id
codeintN接口返回码,0:成功(默认情况),其他情况下返回错误码,详见章节2.12
msgstringN成功时默认返回空字符串,其他情况下返回对应的错误内容,详见章节2.12

2.1 SeatBid 对象

字段类型必须说明
seatstringYssp为广告主分配的广告主id。
bidobject[]Y竞价信息 2.2bid对象

2.2 Bid 对象

字段类型必须说明
idstringYssp生成的bid id,用于追踪或打log
impidstringYbid request中对应的Imp对象id
pricefloatY出价,单位:分
dealidstringNPDB、PD模式必选
cridstringY创意id,需素材审核的广告位该字段不为空
nurlstringN竞价成功通知url,需要支持宏替换,见章节3.2
lurlstringN竞价失败通知url,需要支持宏替换,见章节3.2
admobjectN广告物料,Native对象,非素材审核的广告位该字段不为空,见章节2.4
imp_trackersstring[]N曝光上报地址,需要支持宏替换,见章节3.2
click_trackersstring[]N点击上报地址,需要支持宏替换,见章节3.2
down_start_trackersstring[]N下载开始上报地址,需要支持宏替换,见章节3.2
down_comp_trackersstring[]N下载完成上报地址,需要支持宏替换,见章节3.2
install_start_trackersstring[]N安装开始上报地址,需要支持宏替换,见章节3.2
install_comp_trackersstring[]N安装成功上报地址,需要支持宏替换,见章节3.2
video_trackersobject[]N视频监测链接数组,需要支持宏替换,见章节3.2
dp_trackersstring[]Ndp唤起成功监测链接,需要支持宏替换,见章节3.2
video_close_trackersstring[]N视频播放中途关闭事件上报地址,需要支持宏替换,见章节3.2
extobjectN扩展字段,见章节2.11

2.3 Video Tracker 对象

字段类型必须说明
eventintY曝光上报时间点,单位秒
urlstringY监测地址

2.4 Adm 对象

字段类型必须说明
titlestringN标题
descstringN描述
imgobject[]N图片
videoobjectN视频
landstringN落地页
interactintN交互类型(1:webview;2:下载;3:微信小程序唤起;4:deeplink唤起)
ctypeintN创意类型(1: JPG,2. PNG, 3:GIF, 4:JPEG, 5:SWF, 6:MP4, 7:FLV, 8:文字链, 9:信息流, 10:视频信息流,11:激励视频 )
formidintN广告展现形式Id
dplinkstringNdeeplink。dplink 包括schemelink或者universalLink地址;当返回dplink时,interact需要返回4,同时落地⻚页land字段返回h5点击地址,作为deeplink唤起失败的打底地址;
appobjectNapp下载类应用可能包含的推广信息
extobjectN对物料的附加信息,章节2.10

2.5 Image 对象

字段类型必须说明
urlstringY图片url
wintY
hintY
md5stringN素材MD5
mimestringY素材格式。主要有image/jpg,image/gif,image/png

2.6 Video 对象

字段类型必须说明
urlstringY原生视频信息流视频地址
wintY
hintY
durationintN时长,单位:秒
filesizeintN视频大小, 单位:KB
md5stringN素材MD5
mimestringY素材格式。主要有video/mp4,video/flv,video/webm

2.7 App 对象

字段类型必须说明
namestringNapp下载类包含的推广信息
iconstringNapp下载类包含的icon信息
package_namestirngNapp下载类或者deeplink包含的包名信息
wechat_extobjectN微信小程序相关信息
app_idstringNapp下载类型包含的app id,仅ios下提供
app_versionstringNapp下载类应用版本
package_sizeintNapp下载类包体大小, 单位:KB
privacystringNapp下载类隐私协议URL
permissionstringNapp下载类应用权限URL
permission_desc[]PermissionDescNapp下载类应用权限描述,详⻅2.8章节
app_descstringNapp下载类应用功能描述文案
app_desc_urlstringNapp下载类应用功能描述URL
developstringNapp下载类应用开发者
app_beianstringNapp备案号
app_agestringNapp适用年龄 18表示18+

2.8 PermissionDesc对象

类型必须说明
permission_labstirngN权限名称
permission_descstringN权限用途说明

2.9 WechatExt 对象

字段类型必须说明
program_idstirngN小程序id号
program_pathstringN小程序页面路径

2.10 Ext 对象

字段类型必须说明
iconstringN物料的icon
logostringN广告主logo
advertiser_namestringN广告主名称
sub_titlestringN广告副标题
btnstringN按钮文字

2.11 bid.Ext 对象

字段类型必须说明
huawei_catstringN华为的广告主行业分类
languagestringN创意的语言。比如zh,en
advertiserstringN广告主的名称。也就是广告来源

2.12 错误码

错误码(code)错误描述(msg)
0请求成功
400解析请求失败
401请求参数错误
402无效的设备
403请求媒体ID无效
404无效的媒体广告位ID
405ip黑名单
406设备ID黑名单
407请求中imp信息为空
408请求中device信息为空
409请求IP无效
500系统内部错误
501响应媒体超时
502响应媒体数据错误

3. 监测上报和宏替换说明

3.1 上报说明

  1. 媒体对竞价成功的SSP,发送获胜通知(nurl),协议为HTTP GET;
  2. 媒体对竞价失败的SSP,发送竟败通知(lurl),协议为HTTP GET;
  3. 在广告被曝光时并行上报多组展现监测(imp_trackers)
  4. 在广告被点击时,并行上报多组点击监测(clk_trackers),同时进行跳转
  5. 对于有下载监测需求的广告,需要回传下载进度
  6. 对于有deeplink唤起监测需求的广告,需要回传deeplink唤起数

3.2 宏替换说明

需要支持以下宏替换:

MacroDescrption
__PRICE__竞拍价(次高价结算),rtb结算下需要替换该宏,单位为分
__DOWN_X__鼠标或手指按下时相对于素材的X坐标,clk_tracking/dplink/land需要替换
__DOWN_Y__鼠标或手指按下时相对于素材的Y坐标,clk_tracking/dplink/land需要替换
__UP_X__鼠标或手指弹起时相对于素材的X坐标,clk_tracking/dplink/land需要替换
__UP_Y__鼠标或手指弹起时相对于素材的Y坐标,clk_tracking/dplink/land需要替换
__WIDTH__广告所占屏幕的宽度
__HEIGHT__广告所占屏幕的高度

3.2.1 价格宏替换说明

价格宏替换可以选择明文替换或者加密替换。

价格为CPM价格, 单位为分。

1.使用明文替换

价格宏替换使用明文替换。

2.加密替换

加密算法如下:

https://developers.google.com/authorized-buyers/rtb/response-guide/decrypt-price?hl=zh-cn

注意其中base64使用web safe base64,且是nopadding模式

在完成对接后,请联系系统运营获取系统分配的密钥

测试用例

ekey = "6087d837248d32698334bf4cc0eb67b1"; ikey = "SznRK5aU44UyUb3aY0jdokLiNxi93qFY";

1B2M2Y8AsgTpgAmY7PhCfvqWMP8e_kZGMbnTUg -> 12 1B2M2Y8AsgTpgAmY7PhCfvqWMP8e_kN8Qqdc4A -> 1334

4. 请求和响应示例

4.1 请求示例

4.1.1 Banner / 开屏 / 信息流

{
"id": "u4qmILh1JN9ajbRqXer4yTzNz9jl1Mzl",
"imp": [
{
"id": "sbqXo8iOVz3CptLdTIbEuaQJd1FErubz",
"slotid": "1018",
"w": 414,
"h": 896,
"bidfloor": 39,
"bidtype": 0,
"formids": [1, 2, 3, 4],
"ctype": [1, 2, 3, 6, 9],
"adtype": 7
}
],
"app": {
"id": "13304029",
"name": "test",
"ver": "1.0.1",
"sdk_version": "1.1.0.1",
"bundle": "com.test.demo"
},
"device": {
"idfa": "4356CF32-DDA4-483E-8F9C-5970F6946C5E",
"idfamd5": "848db21db0b5a60833632670906e219c",
"mac": "2cfdabd034a9",
"imei": "869952030827861",
"os": 1,
"osv": "14.6",
"make": "Apple",
"model": "iPhone12,1",
"ip": "223.72.87.18",
"ua": "Mozilla/5.0 (iPhone; CPU iPhone OS 14_6 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) Mobile/15E148",
"carrier": 2,
"connection_type": 1,
"sw": 414,
"sh": 896,
"ori": 2,
"boot_mark": "1714256771.567281"
}
}

4.2 响应示例

4.2.1 Banner / 开屏 等图片

{
"seatbid": [
{
"bid": [
{
"imp_trackers": [
"http://l.test.monitor.com/imp?price=__PRICE__",
"http://www.imp1.com/0",
"http://www.imp2.com/1"
],
"nurl": "http://l.test.monitor.com/wnotice?price=__PRICE__",
"lurl": "http://l.test.monitor.com/lnotice?price=__PRICE__",
"crid": "1234",
"click_trackers": [
"http://l.test.monitor.com/click?a=1&b=2",
"http://www.click1.com/click0",
"http://www.click2.com/click1"
],
"adm": {
"formid": 3,
"img": [
{
"h": 640,
"w": 360,
"url": "http://www.img.jpg"
}
],
"ctype": 1,
"interact": 1,
"land": "http://www.baidu.com"
},
"id": "1323132131",
"price": 500,
"impid": "sbqXo8iOVz3CptLdTIbEuaQJd1FErubz"
}
],
"seat": ""
}
],
"bidid": "sbqXo8iOVz3CptLdTIbEuaQJd1FErubz",
"id": "u4qmILh1JN9ajbRqXer4yTzNz9jl1Mzl",
"code": 0
}

4.2.2 视频广告

{
"seatbid": [
{
"bid": [
{
"imp_trackers": ["http://l.test.monitor.com/imp?price=__PRICE__"],
"nurl": "http://l.test.monitor.com/wnotice?price=__PRICE__",
"lurl": "http://l.test.monitor.com/lnotice?price=__PRICE__",
"crid": "12235",
"click_trackers": ["http://l.test.monitor.com/click?a=2&b=3"],
"adm": {
"formid": 4,
"video": {
"url": "http://www.video.mp4",
"h": 360,
"w": 640
},
"ctype": 6,
"interact": 1,
"land": "http://www.baidu.com"
},
"id": "13231313",
"price": 1500,
"impid": "sbqXo8iOVz3CptLdTIbEuaQJd1FErubz"
}
],
"seat": ""
}
],
"bidid": "sbqXo8iOVz3CptLdTIbEuaQJd1FErubz",
"id": "u4qmILh1JN9ajbRqXer4yTzNz9jl1Mzl",
"code": 0
}

4.2.3 信息流广告

{
"seatbid": [
{
"bid": [
{
"imp_trackers": [
"http://l.test.monitor.com/win?price=__PRICE__"
],
"nurl": "http://l.test.monitor.com/wnotice?price=__PRICE__",
"lurl": "http://l.test.monitor.com/lnotice?price=__PRICE__",
"crid": "13231233",
"click_trackers": [
"http://l.test.monitor.com/click?a=1&b=2"
],
"adm": {
"img": [
{
"h": 360,
"w": 690,
"url": "https://www.jpg"
}
],
"desc": "测试描述",
"title": "测试标题",
"formid": 1,
"ctype": 9,
"interact": 1,
"land": "http://www.baidu.com"
},
"id": "3582132313
"price": 200,
"impid": "sbqXo8iOVz3CptLdTIbEuaQJd1FErubz"
}
],
"seat": ""
}
],
"bidid": "sbqXo8iOVz3CptLdTIbEuaQJd1FErubz",
"id": "u4qmILh1JN9ajbRqXer4yTzNz9jl1Mzl",
"code": 0
}

5. 联调说明

媒体方可以直接访问测试环境竞价地址获取广告。

联调地址、mid和广告位线下提供

mid 和线上请求地址,正式投放由ssp运营提供

6. 补充说明

一、针对rta效果投放的请求,字段可以缩减;

二、转化数据回传(媒体可以不接入):

1)支持动态回调。

response.click_tracker为系统的点击监测,点击监测上**支持__CBURL__可以供媒体动态替换成媒体侧的cpa回调地址,我方会在有转化时通过 callback url 回传给媒体(服务端回调)。**针对动态回调,将会在媒体传入的 callback_url 地址后拼接event_type。

event_type:
激活:1;
注册:2;
授信:3;
付费:4;
次留:5;
唤起应用:6;
下载:7;

例如:媒体callback_url 为 http://xxxx.com?param1=a,激活回调为 http://xxxx.com?param1=a&event_type=1

2)支持静态回调。

媒体线下将cpa回调地址callback给到我方,回调地址需要支持我方的宏替换规则。具体见文档-监测说明。我方会在有转化时,对callback url 进行宏替换后,回传给媒体(服务端回调)

以下为请求的示例:

{
"id": "070c9ee9-3ef3-4577-95ce-75d6af626f82",
"imp": [
{
"id": "1", //rta的token
"tagid": "1" //填成跟id一样,系统投放定向需求
},
{
"id": "2", //rta的token,跟id填一样
"tagid": "2" //填成跟id一样,系统投放定向需求
}
],
"app": {
"id": "1603040292218.app.ln",
"name": "test",
"ver": "9.7.0.88",
"sdk_version": "1.1.0.1",
"bundle": "com.lestore.ad.demo"
},
"device": {
"ua": "com.lenovo.leos.appstore/9.7.0.88(Lenovo L38012; OS Android8.0.0)",
"ip": "111.205.43.250",
"mac": "2cfdabd034a9",
"imei": "869952030827861",
"carrier": 0,
"make": "lenovo",
"model": "Lenovo L38012",
"os": 2,
"osv": "8.0",
"devicetype": 1,
"connection_type": 4,
"den": 0,
"ori": 1,
"sw": 720,
"sh": 1142
}
}

响应示例,其中__CBURL__可以供媒体动态替换成媒体侧的cpa回调地址,我方会在有转化时回调该地址:

{
"seatbid":[
{
"bid":[
{
"click_trackers":[
"http://l.test.monitor.com/click"
],
"impid":"1"//对应imp.id,即rta的token
},
{
"click_trackers":[
"http://l.test.monitor.com/click?cb=__CBURL__"
],
"impid":"2"//对应imp.id,即rta的token
}
]
}
],
"bidid":"1603040292218_243582",
"id":"070c9ee9-3ef3-4577-95ce-75d6af626f82"
}