实时竞价接口v1.0版本

简介

请使用2.0文档

v1.0于2023.05.30停止更新

请求与响应

BidRequest结构说明

ADX向DSP发送HTTP竞价请求，竞价请求信息保存在BidRequest中。BidRequest将包含曝光信息、站点信息、APP信息、设备信息、用户信息。

基础结构说明

字段	类型	必填	描述
reqid	string	必填	标识一次请求的唯一id
imp_list	object[]	必填	曝光信息, 广告位信息, 一个BidRequest可能包含多个imp对象, 至少包含一个 object的结构见imp object
site	object	选填	站点信息, 仅当广告位出现在web时, 才会包含site对象 object的结构见site object
app	object	选填	APP信息, 仅当广告位出现在APP时, 才会包含APP对象 object的结构见app object
device	object	选填	设备信息 object的结构见device object
user	object	选填	用户信息 object的结构见user object
bcat	string[]	选填	拒绝的广告分类
badv	stirng[]	选填	拒绝的广告主域名
test	int	选填	测试字段, 标识是否涉及收费 0-生产模式 1-调试模式
ext	object	选填	保留字段

imp object字段说明

字段	类型	必填	描述
id	string	必填	标识该imp的唯一id
seat_id	int	必填	广告位标识id, DSP先同步获取ADX资源的素材标准，然后根据本字段识别曝光资源的来源和素材标准
ad_type	int	必填	广告类型: 1-开屏 2-插屏 3-信息流 4-激励视频 5-推送
display_list	object[]	必填	广告位支持的广告形式: 包含多个，代表该位置支持多种广告形式，投放方可以根据自己需要选取其中一个广告投放，返回投放广告对应的广告形式id object的结构见display object
bid_info_list	object[]	必填	竞价信息，包含允许的竞价类型和底价，至少存在一个bidinfo object的结构见bid_info object
deal_id	string[]	选填	直接交易标识 ID列表,由交易平台和 DSP 提前约定
action_type	int[]	选填	支持的广告交互类型 0-无限制、1-H5、2-下载、3-唤醒、4-微信小程序、10-LBA、21-仅展示不可点击

display object字段说明

字段	类型	必填	描述
display_id	int	必填	广告形式id
width	int	必填	广告位宽度
height	int	必填	广告位高度

bid_info object字段说明

字段	类型	必填	描述
bid_type	int	必填	允许的竞价类型 0-CPM
bid_floor	int	选填	可接受的底价 单位:分/千次曝光

site object字段说明

字段	类型	必填	描述
id	int	必填	站点id, 由ADX定义的site id
name	string	选填	站点名称
domain	string	选填	站点域名
url	string	选填	当前页面的url
ref	string	选填	当前页面的referer url
keywords	string	选填	逗号分隔的页面关键词

app object字段说明

字段	类型	必填	描述
id	string	必填	APP id, 由ADX定义
name	string	选填	APP名称
package_name	string	选填	APP package name, 平台内唯一
cat	int[]	选填	APP类型
ver	string	选填	APP版本号
keywords	string	选填	逗号分隔的APP关键词

device object字段说明

字段	类型	必填	描述
ua	string	选填	浏览器的user agent
device_type	int	选填	设备类型 0-PC 1-手机 2-平板 3-互联网电视
brand	string	选填	设备品牌(如: apple)
model	string	选填	设备型号(如: iphone)
make	string	选填	设备厂商(如: apple)
hmsVersion	string	选填	华为机型HMS Core版本号(如: 60000306)
asVersion	string	选填	大陆厂商安卓设备AS版本号(如: 110302302)
os	int	选填	操作系统 0-Windows 1-MacOS 2-Linux 3-IOS 4-Android
osv	string	选填	操作系统版本号
density	int	选填	屏幕密度, 默认为400
ip	string	选填	ipv4
ipv6	string	选填	ipv6
carrier	int	选填	运营商 0-电信 1-移动 2-联通 3-网通 4-未知
network	int	选填	网络类型 0-wifi 1-earthnet(有线网络) 2-2G 3-3G 4-4G 5-5G 6-未知
width	int	选填	物理屏幕宽度
height	int	选填	物理屏幕高度
imei	string	选填	设备号imei
imei_md5	string	选填	设备号imei的md5
oaid	string	选填	Android Q以上版本的设备号 明文形式
dpid	string	选填	Android id
dpid_md5	string	选填	Android id的md5
idfa	string	选填	Apple设备的idfa
idfa_md5	string	选填	Apple设备的idfa的md5
boot_mark	string	选填	取原值进⾏传输 iOS：1623815045.970028 Android：ec7f4f33-411a-47bc-8067-744a4e7e0723
update_mark	string	选填	取原值进⾏传输 iOS：1581141691.570419583 Android：1004697.709999999
mac	string	选填	设备的mac值
mac_md5	string	选填	设备的mac值的md5
geo	object	选填	地域信息 object的结构见geo object

geo object字段说明

字段	类型	必填	描述
lat	float	选填	纬度 (-90.0 - 90.0), 负值代表南
lon	float	选填	经度 (-180.0 - 180.0), 负值代表西
type	int	选填	位置来源 1-GPS定位 2-IP地址 3-用户提供(如注册信息)
country	string	选填	国家
province	string	选填	省份
city	string	选填	城市

user object字段说明

字段	类型	必填	描述
id	string	选填	由ADX定义的用户id
yob	int	选填	出生年份 4位数字
gender	string	选填	性别 M-男 F-女 默认-未知
keywords	string	选填	逗号分隔得用户关键词或兴趣点

ext object字段说明

字段	类型	必填	描述
iapp_list	string	选填	定向应用id列表(逗号分隔), 最多50个id, 请联系我们商务或运营开通, 及索要包名和id映射关系表, 用于支持部分唤醒或下载类广告业务

BidRequest的请求示例

{
    "reqid":"b-8910dd1fc643149c88906fc77a70f4a2",
    "imp_list":[
        {
            "id":"1",
            "seat_id":10007201,
            "ad_type": 3,
            "display_list":[
                {
                    "display_id":100005,
                    "width":480,
                    "height":360
                },
                {
                    "display_id":100004,
                    "width":480,
                    "height":360
                },
                {
                    "display_id":100003,
                    "width":720,
                    "height":360
                }
            ],
            "bid_info_list":[
                {
                    "bid_type":0,
                    "bid_floor":30
                }
            ],
            "deal_id":[
                "100072011125192"
            ]
        },
        {
            "id":"2",
            "seat_id":10007202,
            "ad_type": 3,
            "display_list":[
                {
                    "display_id":100005,
                    "width":480,
                    "height":360
                },
                {
                    "display_id":100004,
                    "width":480,
                    "height":360
                },
                {
                    "display_id":100003,
                    "width":720,
                    "height":360
                }
            ],
            "bid_info_list":[
                {
                    "bid_type":0,
                    "bid_floor":30
                }
            ],
            "deal_id":[
                "10007202464452"
            ]
        },
        {
            "id":"3",
            "seat_id":10007203,
            "ad_type": 3,
            "display_list":[
                {
                    "display_id":100005,
                    "width":480,
                    "height":360
                },
                {
                    "display_id":100004,
                    "width":480,
                    "height":360
                },
                {
                    "display_id":100003,
                    "width":720,
                    "height":360
                }
            ],
            "bid_info_list":[
                {
                    "bid_type":0,
                    "bid_floor":30
                }
            ],
            "deal_id":[
                "10007202464452"
            ]
        }
    ],
    "site":{
        "id":1,
        "name":"2345网址导航",
        "domain":"www.2345.com",
        "url":"http://www.2345.com/index.html",
        "ref":"http://www.2345.com",
        "keywords":"音乐,小说,财经"
    },
    "app":{
        "id":"52",
        "name":"2345手机浏览器-安卓主版",
        "package_name":"com.browser2345",
        "cat":[
            6502
        ],
        "ver":"61000",
        "keywords":"魅力的小鸟"
    },
    "device":{
        "ua":"Mozilla/5.0(Linux;Android7.0;FRD-AL00Build/HUAWEIFRD-AL00;wv)AppleWebKit/537.36(KHTML,likeGecko)Version/4.0Chrome/60.0.3112.116MobileSafari/537.36",
        "device_type":1,
        "hmsVersion":"60000306",
        "asVersion":"110302302",
        "brand":"honor",
        "model":"FRD-AL00",
        "make": "huawei",
        "os":4,
        "osv":"7.0",
        "ip":"172.16.171.88",
        "ipv6":"",
        "carrier":4,
        "network":0,
        "width":1080,
        "height":1794,
        "imei":"862679030655599",
        "imei_md5":"b9b7d034a11df90d0be1d095c9ffe1f2",
        "oaid":"8bc673b56ca9c1bc",
        "dpid":"da79762cdb2521e8",
        "dpid_md5":"7c16cd22b9034aeca5afc7403895ef70",
        "idfa":"",
        "idfa_md5":"",
        "mac":"d41a844d7028",
        "mac_md5":"8f0f4c4532c0d8fac13df364d31545b5",
        "boot_mark":"ec7f4f33-411a-47bc-8067-744a4e7e0723",
        "update_mark":"1004697.709999999",
        "geo":{
            "lat":31.180670080928,
            "lon":121.60124658875,
            "type":1,
            "country":"",
            "province":"",
            "city":""
        }
    },
    "user":{
        "id":"d4a1484d7208",
        "yob":0,
        "gender":"",
        "keywords":""
    },
    "bcat":[

    ],
    "badv":[

    ],
    "test":0,
    "ext":{
	    "iapp_list":"10001,10002"
    }
}

BidResponse基础结构说明

DSP通过BidResponse返回参与竞价的广告

一个BidResponse中可包含多个BidSeat对象。通常，一个BidSeat代表DSP端的一个广告主。每个BidSeat中又可包含多个Bid对象，一个Bid代表一个参与竞价的广告，对应于BidRequest中的一个Imp对象

基础结构说明

字段	类型	必填	描述
resid	string	必填	response id, 与request id相同
seat_bid_list	object[]	选填	广告位-竞价列表, 如果参与竞价, 必须至少包含一个seat_bid对象 object的结构见seat_bid object
bidid	string	选填	由DSP定义的响应id，用于 logging/tracking(日志或效果追踪)

seat_bid object字段说明

字段	类型	必填	描述
bid_list	object[]	必填	竞价信息 object的结构见bid object
adv	string	选填	该次竞价是代表谁参与的，一般设置成广告主id，用于logging/tracking

bid object字段说明

字段	类型	必填	描述
imp_id	string	必填	本次竞价所关联的imp id
price	int	必填	出价 单位:分
deal	string	选填	预定的资源id, 仅pd和pdb业务使用
creative_id	string	必填	广告创意素材id, DSP需保证该id在DSP侧的唯一性, 最长支持32位
directive_response	object	选填	广告创意信息, 免审核时使用, 白名单内的DSP此项必填 object的结构见directive_response object
iapp_filter	int	选填	0=不过滤(默认) 1=过滤已安装 2=过滤未安装
ext_data	string	选填	自定义宏, 会替换竞价成功后的__EXT_DATA__宏

directive_response object字段说明

字段	类型	必填	描述
creative_id	string	必填	广告创意素材id, DSP需保证该id在DSP侧的唯一性
advertiser_id	int	必填	广告主id
advertiser_name	string	必填	广告主名称
vocation	int	必填	广告主行业编码, 详见广告主行业编码表
display_id	int	必填	广告形式id
ad_content_list	object[]	必填	创意素材内容, 包括视频, 图片, 文本等. 需严格按照广告形式的定义顺序来指定上传 object的结构见ad_content object
app_info	object	选填	app下载唤起 object的结构见app_info object
url	string	必填	落地url 支持302
videosize	string	选填	视频大小，单位千字节(KB)。
videotime	string	选填	视频时长，单位秒。仅信息流视频、激励视频类广告必填
bgimg	string	选填	视频后贴片图片地址，仅激励视频类广告必填
videoProtocol	int	选填	视频协议类型，0=JSON。仅信息流视频、激励视频类广告必填
incentiveloadedtk	string[]	选填	仅用于激励视频广告，激励视频加载成功时统计url列表, 最多3个
videostarttk	string[]	选填	仅用于信息流视频、激励视频，视频开始播放统计url列表，最多3个
firstQuartiletk	string[]	选填	仅用于激励视频，视频播放至25%时统计url列表，最多3个
midpointtk	string[]	选填	仅用于激励视频，视频播放至50%时统计url列表，最多3个
thirdQuartiletk	string[]	选填	仅用于激励视频，视频播放至75%时统计url列表，最多3个
videoCompletetk	string[]	选填	仅用于信息流视频、激励视频，视频播放完成统计url列表，最多3个
incentiveerrortk	string[]	选填	仅用于激励视频广告，激励视频播放错误时统计url列表，最多3个
imptk	string[]	选填	曝光监测url, 最多8个
clktk	string[]	选填	点击监测url, 最多8个
dstarttk	string[]	选填	仅用于应用下载广告，开始下载监播地址, 如果需要该信息请与我方确认投放资源是否支持，最多3个
dfinishtk	string[]	选填	仅用于应用下载广告，下载完成监播地址，最多3个
dinstalltk	string[]	选填	仅用于应用下载广告；安装完成监播地址，最多3个
deeplinktk	string[]	选填	唤醒成功上报地址，当前仅用于开屏广告位，最多8个
dstartinstalltk	string[]	选填	仅用于应用下载广告；开始安装监播地址。如果需要该信息请与我方确认投放资源是否支持，最多3个
deeplinkfailedtk	string[]	选填	deeplink调起失败时上报的url列表，最多3个
installedtk	string[]	选填	deeplink跳转时判断应用已安装情况下上报的url列表，最多3个
uninstalledtk	string[]	选填	deeplink跳转时判断应用未安装情况下上报的url列表，最多3个

ad_content object字段说明

字段	类型	必填	描述
file_text	string	必填	file_text, file_url 必须指定其中一个，按照广告形式id的定义校验，文件大小，类型，尺寸
file_url	string	必填	file_text, file_url 必须指定其中一个，按照广告形式id的定义校验，文件大小，类型，尺寸

app_info object字段说明

字段	类型	必填	描述
product_type	int	必填	1-普通链接 2-android应用下载 3-ios应用下载
android_url	string	选填	安卓下载地址，下载类时android_url或 ios_url⾄少填⼀个，其它情况直接过滤为空
ios_url	string	选填	IOS下载地址，下载类选填
deeplink	string	选填	应用直达URL，SDK客户端会对deeplink地址进行有效性校验，无效的话会自动转成非唤起的广告形式，打开落地页
package_name	string	推荐	下载应用包名 下载和唤醒类广告必填
actionurl	string	选填	电话号码或获取号码的URL
app_name	string	选填	应用名称，下载和唤醒类广告必填
app_size	int	选填	应用大小，单位 KB，下载类需要
app_logo	string	选填	应用logo，下载和唤醒类广告必填
intro	string	选填	应用介绍
version	string	选填	应用版本号，下载类广告必填
developer	string	选填	应用开发者，下载类广告必填
privacy	string	选填	应用隐私协议，下载类广告必填
privacy_url	string	选填	应用隐私协议链接，下载类广告必填 注：下载类广告 privacy、privacy_url 任填一个即可。
permissions	object[]	选填	应用隐私权限列表，下载类广告必填。详见permission对象
wx_miniprogram	object[]	选填	调起微信小程序。详见wxMiniProgram对象

permission object字段说明

字段	类型	必填	描述
title	string	必填	隐私权限标题
desc	string	必填	隐私权限详细描述

wxMiniProgram object字段说明

字段名称	类型	必填	备注
wx_username	string	必填	所需跳转的小程序原始 ID（以"gh_"开头）
wx_path	string	选填	推荐，所需跳转的小程序内页面路径及参数，不填默认拉起小程序主页。
wx_minitype	int	必填	所需跳转的小程序类型，0=正式版、1=开发版、2=体验版

BidResponse的响应示例

{
    "resid":"b-9946d8caf773a38d0dc9864945de6f5f",
    "seat_bid_list":[
        {
            "adv":"10010",
            "bid_list":[
                {
                    "imp_id":"1",
                    "price":357143,
                    "deal":"10007201382782",
                    "creative_id":"10000357",
                    "directive_response":{
                        "creative_id":"10000357",
                        "advertiser_id":100106,
                        "advertiser_name":"京东商城",
                        "vocation":303,
                        "display_id":100005,
                        "ad_content_list":[
                            {
                                "file_text":"京东好物节"
                            },
                            {
                                "file_url":"http://www.adgoo.cn/201909/34_1_5d82f8d9536283.69356696.jpg"
                            },
                            {
                                "file_text":"先领券后下单，1元好物包邮到家，仅限今日！"
                            }
                        ],
                        "app_info":{
                            "product_type":2,
                            "android_url":"http://download.2345.com/latest/taobao4android_1001001.apk",
                            "ios_url":"",
                            "deeplink":"tbopen://m.taobao.com/tbopen/index.html?action=ali.open.nav&bootImage=0&module=h5&source=alimama&bc_fl_src=tanx_df_643466909_0_15456_105032_37853_3648_4639_3&backURL=oppobrowser%3A%2F%2Fresume%3Ffrom%3Dcom.taobao.taobao&packageName=com.android.browser&h5Url=https%3A%2F%2Fclick.tanx.com%2Ftfn%3Fe%3De4fZ4%252bte2x3zgR8y%252fb1Y00Kc3sAmalVszN1VIJJUwTdz3z9bRz09oDvAx2TRREVuA%252fYbPr9t7QqAqkCG91x4hjXH6%252brBCQREcuYK5fam3%252fG6CPvXhWf7zYBm1fKOXs36e4hg4npzkB8%253d%26u%3Dhttps%253a%252f%252fpages.tmall.com%252fwow%252fa%252fact%252ftmall%252ftmc%252f2375e%252fwupr%253fwh_pid%253dmain-174357%2526resource_id%253d15456%26k%3D140%26ext%3Da%253d7ef207a42f51aecd77fb49784fe7b734%2526b%253d__IDFA__%2526c%253d__MAC__%2526d%253d__OAID__",
                            "package_name":"com.taobao.taobao"
                        },
                        "videosize":"190",
                        "videotime":"8",
                        "bgimg":"http://www.2345.com",
                        "videoProtocol":0,
                        "incentiveloadedtk": [
                            "http://www.2345.com/exposure?type=0&adxRid=__EXT_DATA__&winpriceEncr=__WIN_PRICE__",
                            "http://www.2345.com/exposure?type=0&adxRid=__EXT_DATA__&winpriceEncr=__WIN_PRICE__"
                        ],
                        "videostarttk": [
                            "http://www.2345.com/click?type=1&adxRid=__EXT_DATA__&winpriceEncr=__WIN_PRICE__"
                        ],
                        "firstQuartiletk" : [
                            "http://www.2345.com/dstart?type=2&adxRid=__EXT_DATA__&winpriceEncr=__WIN_PRICE__"
                        ],
                        "midpointtk" : [
                            "http://www.2345.com/dfinish?type=3&adxRid=__EXT_DATA__&winpriceEncr=__WIN_PRICE__",
                            "http://www.2345.com/dfinish2?type=3&adxRid=__EXT_DATA__&winpriceEncr=__WIN_PRICE__"
                        ],
                        "thirdQuartiletk" : [
                            "http://www.2345.com/dinstall?type=4&adxRid=__EXT_DATA__&winpriceEncr=__WIN_PRICE__"
                        ],
                        "videoCompletetk" : [
                            "http://www.2345.com/dinstall?type=4&adxRid=__EXT_DATA__&winpriceEncr=__WIN_PRICE__"
                        ],
                        "incentiveerrortk" : [
                            "http://www.2345.com/dinstall?type=4&adxRid=__EXT_DATA__&winpriceEncr=__WIN_PRICE__"
                        ],
                        "url":"http://www.adgoo.cn",
                        "imptk":[
                            "http://www.adgoo.cn/api/external/drs?reqid=__ID__&action=show&win_price=0"
                        ],
                        "clktk":[
                            "http://www.adgoo.cn/api/external/drs?reqid=__ID__&action=click&win_price=0"
                        ],
                        "dstarttk" : [
                            "http://www.2345.com/dstart?type=2&adxRid=__EXT_DATA__&winpriceEncr=__WIN_PRICE__"
                        ],
                        "dfinishtk" : [
                            "http://www.2345.com/dfinish?type=3&adxRid=__EXT_DATA__&winpriceEncr=__WIN_PRICE__",
                            "http://www.2345.com/dfinish2?type=3&adxRid=__EXT_DATA__&winpriceEncr=__WIN_PRICE__"
                        ],
                        "dinstalltk" : [
                            "http://www.2345.com/dinstall?type=4&adxRid=__EXT_DATA__&winpriceEncr=__WIN_PRICE__"
                        ],
                        "deeplinktk" : [
                            "http://www.2345.com/deeplink?type=6&adxRid=__EXT_DATA__&winpriceEncr=__WIN_PRICE__"
                        ],
                        "dstartinstalltk" : [
                            "http://www.2345.com/dstartinstall?type=2&adxRid=__EXT_DATA__&winpriceEncr=__WIN_PRICE__"
                        ],
                        "deeplinkfailedtk" : [
                            "http://www.2345.com/deeplinkfailed?type=3&adxRid=__EXT_DATA__&winpriceEncr=__WIN_PRICE__",
                            "http://www.2345.com/deeplinkfailed2?type=3&adxRid=__EXT_DATA__&winpriceEncr=__WIN_PRICE__"
                        ],
                        "installedtk" : [
                            "http://www.2345.com/installed?type=4&adxRid=__EXT_DATA__&winpriceEncr=__WIN_PRICE__"
                        ],
                        "uninstalledtk" : [
                            "http://www.2345.com/uninstalled?type=6&adxRid=__EXT_DATA__&winpriceEncr=__WIN_PRICE__"
                        ]
                    },
                    "iapp_filter" : 0,
                    "ext_data": "50c0e9a8c8d293b2"
                },
                {
                    "imp_id":"2",
                    "price":7143,
                    "deal":"10007202889218",
                    "creative_id":"10000354",
                    "directive_response":{
                        "creative_id":"10000354",
                        "advertiser_id":100106,
                        "advertiser_name":"京东商城",
                        "vocation":303,
                        "display_id":100005,
                        "ad_content_list":[
                            {
                                "file_text":"京东好物节"
                            },
                            {
                                "file_url":"http://www.adgoo.cn/201909/34_1_5d82f8d9536283.69356696.jpg"
                            },
                            {
                                "file_text":"先领券后下单，1元好物包邮到家，仅限今日！"
                            }
                        ],
                        "app_info":{
                            "product_type":1,
                            "deeplink":"",
                            "package_name":""
                        },
                        "url":"http://www.adgoo.cn",
                        "imptk":[
                            "http://www.adgoo.cn/api/external/drs?reqid=__ID__&action=show&win_price=__WIN_PRICE__"
                        ],
                        "clktk":[
                            "http://www.adgoo.cn/api/external/drs?reqid=__ID__&action=click&win_price=__WIN_PRICE__"
                        ]
                    }
                }
            ]
        }
    ],
    "bidid":"b00290"
}