实时竞价接口

版本历史

版本号	日期	作者	描述
1.0	2019-05-27	赵家勇	支持移动端业务
1.0.1	2019-08-29	王骁恒	创意送审、创意修改、创意查询、BidResponse支持下载类第3方监控
1.0.2	2019-11-15	王骁恒	获取广告位详情`memo`字段改为选填，新增`platform`字段
1.0.3	2019-11-15	王骁恒	下载类广告的`package_name`字段改为选填
1.0.4	2019-12-30	王骁恒	添加deeplinktk字段
1.0.5	2020-02-12	赵家勇	添加应用定向和广告过滤字段说明
1.0.6	2020-05-25	梁春雷	添加下载或调起类广告效果上报字段，dstartinstalltk、deeplinkfailedtk、installedtk、uninstalledtk
1.0.7	2020-09-04	徐华根	添加actionurl在BidResponse和创意同步接口-创意送审/创意修改/创意查询中的app_info object[]
1.0.7	2020-12-20	徐华根	添加`bgimg`, `videotime`等字段在BidResponse和创意同步接口-directive_response object[]
1.0.8	2021-08-03	黄有龙	在BidRequest.Device增加`hmsVersion`, `asVersion`
2.0	2023-04-21	黄有龙	增加ApiVersion2.0版本，BidRequest结构`display`对象更新,BidResponse结构新增`material`对象
2.0.1	2023-05-25	黄有龙	在BidRequest.Device增加IOS相关字段`birthTime`, `bootTime`, `updateTime`, `idfv`, `caid`
2.0.2	2023-06-30	黄有龙	在BidRequest.Device增加拼多多caid字段`paid`
2.0.3	2023-07-26	黄有龙	在BidRequest.Device增加caid的version字段`caid`.`version`
2.0.4	2023-08-11	黄有龙	在BidResponse.AppInfo新增下载要素的字段：`permission_url`, `function_desc`
2.0.5	2023-09-04	黄有龙	支持`protobuf`格式对接, 支持`gzip`, `zstd`压缩方式; 在BidRequest.Device增加`ppi`, `pxRatio`字段, 即将废弃`density`字段
2.0.6	2023-10-16	黄有龙	在BidRequest.Device增加阿里广告标识aaid字段`aaid`
2.0.7	2023-11-29	黄有龙	在BidResponse.AppInfo新增ios universal_link字段，`universal_link`字段
2.0.8	2023-12-28	黄有龙	增加点击事件与摇一摇相关宏：`__itm__`, `__acw__`, `__ach__`, `__xma__`, `__yma__`, `__zma__`
2.0.9	2024-01-19	黄有龙	在BidRequest.Device增加：`elapseTime`, `sysCpuNum`, `batteryState`, `battery`, `romVersion`, `sdFreeSpace`
2.0.10	2024-12-11	黄有龙	在BidRequest.Device增加：`anDisk`, `anMemory`

通信方式

简介

ADX和DSP之间的通信协议采用HTTP协议
ADX使用POST方法向DSP发送Bid Request消息
数据格式: json, protobuf
支持压缩方式：gzip, zstd
ADX使用GET 方式向DSP发送Win Notice消息

请求头

参数名称	参数值	备注
Content-Type	application/json	目前支持json和protobuf格式 json: 固定传 application/json protobuf：固定传 application/x-protobuf
Accept-Encoding		压缩方式, 不压缩的时候不传支持压缩方式有`gzip`，`zstd`, 选择对应压缩方式则会传对应的压缩
Content-Encoding		压缩方式, 不压缩的时候不传支持压缩方式有`gzip`，`zstd`, 选择对应压缩方式则会传对应的压缩

提示

建议DSP使用protobuf对接, 对接参考proto文件
出于降低带宽的角度, 希望DSP支持压缩, 支持压缩后, 我方会采用对应压缩方式请求(Request Header头会传Accept-Encoding与Content-Encoding)，对应值如: gzip

响应头

参数名称	参数值	备注
Content-Type	application/json	目前支持json和protobuf格式 json: 固定传 application/json protobuf：固定传 application/x-protobuf
Content-Encoding		压缩方式, 不压缩的时候不传支持压缩方式有`gzip`，`zstd`, 选择对应压缩方式则需传对应的值

HTTP状态码

DSP正常出价响应包的HTTP状态码: 200 OK
DSP不出价的HTTP状态码: 204 no content
其他状态码均认为异常

接口定义v2.0

2.0更新说明

1.0版本升级到2.0版本须知：

2.0版本的主要目标：针对素材适配做了调整，提升DSP侧的素材适配性。建议升级以提升跑量能力

2.0版本相对1.0版本主要调整：

请求参数调整：

1. 增加BidRequest.api_version参数，固定传值2.0
1. Display对象调整：BidRequest.ImpList<Imp>.DisplayList<Display>移除display_id字段，新增template_id字段，为模板字段，具体可以参照帮助中心/广告形式规范报表/广告模板V2.0

返回参数调整：

1. 移除directive_response下相关字段：display_id、ad_content_list、bgimg、videosize、videotime、videoProtocol
1. 增加directive_response.template_id字段，增加directive_response.material字段，用于表示素材，提高素材可适配性

BidRequest结构说明

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

BidRequest object

字段	类型	必填	描述
reqid	string	必填	标识一次请求的唯一id
api_version	string	必填	版本号，固定为2.0
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

字段	类型	必填	描述
template_id	int	必填	广告模板id 参考帮助中心/广告形式规范报表/广告模板v2.0
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)
orientation	int	选填	屏幕方向 0-未知 1-竖屏 2-横屏
hmsVersion	string	选填	华为机型HMS Core版本号(如: 60000306)
asVersion	string	选填	大陆厂商安卓设备AS版本号(如: 110302302)
os	int	选填	操作系统 0-Windows 1-MacOS 2-Linux 3-IOS 4-Android 5-WP
osv	string	选填	操作系统版本号
density	int	选填	屏幕密度, 默认为400，即将废弃，用ppi字段取代
ppi	int	选填	像素密度, 表示每英寸像素点, 默认为400
pxRatio	float	选填	屏幕密度, 例如 1.5
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
birthTime	string	选填	设备初始化时间
bootTime	string	选填	系统启动时间
updateTime	string	选填	系统更新时间
idfv	string	选填	苹果开发者标识
paid	string	选填	拼多多版caid，仅iOS
caid	object	选填	中广协设备id，object的结构见`Caid object`，仅iOS
geo	object	选填	地域信息 object的结构见`geo object`
aaid	string	选填	阿里集团内推出的匿名广告标识符，格式示例：CD7D878A870C-97D4-89A4-3EB3-D48AF066
elapseTime	string	选填	开机时长
sysCpuNum	int	选填	设备cpu数量
batteryState	int	选填	设备当前充电状态 1:未知状态，2:正在充电，3 放电 4:未充满，5:满状态
battery	int	选填	设备电量
romVersion	string	选填	系统rom版本
sdFreeSpace	string	选填	磁盘剩余空间
anDisk	string	选填	安卓磁盘空间
anMemory	string	选填	安卓内存空间

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	选填	逗号分隔得用户关键词或兴趣点

Caid object

字段	类型	必填	描述
id	string	选填	caid原值
version	string	选填	caid版本号，caid原值跟版本号同时传才有意义，建议传caid原值时，同时也传caid_version
bootTimeInSec	string	选填	iOS设备启动时间(单位秒，无小数点)
countryCode	string	选填	国家
language	string	选填	语言
deviceName	string	选填	设备名称
model	string	选填	设备model
systemVersion	string	选填	系统版本
machine	string	选填	设备machine
carrierInfo	string	选填	运营商
memory	string	选填	物理内存,单位字节
disk	string	选填	磁盘空间,单位字节
sysFileTime	string	选填	系统更新时间
timeZone	string	选填	时区
initTime	string	选填	应用首次启动时间

ext object

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

BidRequest请求示例

{
    "reqid":"b-8910dd1fc643149c88906fc77a70f4a2",
    "api_version": "2.0",
    "imp_list":[
        {
            "id":"1",
            "seat_id":10007201,
            "ad_type": 3,
            "display_list": [
            {
              "template_id": 3,
              "width": 480,
              "height": 360
            },
            {
              "template_id": 4,
              "width": 480,
              "height": 360
            },
            {
              "template_id": 5,
              "width": 720,
              "height": 360
            },
            {
              "template_id": 6,
              "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":[
              {
                "template_id": 3,
                "width": 480,
                "height": 360
              },
              {
                "template_id": 4,
                "width": 480,
                "height": 360
              },
              {
                "template_id": 5,
                "width": 720,
                "height": 360
              },
              {
                "template_id": 6,
                "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",
        "idfv": "",
        "bootTime": "1633371485.234154208",
        "updateTime": "1644125433.724374",
        "birthTime": "",
        "caid": {
            "id": "",
            "bootTimeInSec": "1671304611",
            "countryCode": "CN",
            "language": "zh-Hans-CN",
            "deviceName": "867e57bd062c7169995dc03cc0541c19",
            "model": "D17AP",
            "systemVersion": "15.3",
            "machine": "iPhone14,5",
            "carrierInfo": "中国移动",
            "memory": "3866836992",
            "disk": "127866785792",
            "sysFileTime": "1644125433.724374",
            "timeZone": "28800",
            "initTime": "1633371485.234154208"
        },
        "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对象

BidResponse object

字段	类型	必填	描述
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,DSP侧可自定义
advertiser_name	string	必填	广告主名称,DSP侧可自定义
vocation	int	必填	广告主行业编码, 详见广告主行业编码表
template_id	int	必填	广告模板id
material	`Material`	必填	广告创意素材信息，详见`Material`对象
app_info	object	选填	app下载唤起 object的结构见`app_info object`
url	string	必填	落地url 支持302
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个
nurl	string	选填	竞胜通知url
lurl	string	选填	竞败通知url

Material object

字段名称	类型	是否必填	备注
title	string	推荐	广告标题
description	string	推荐	广告描述
btn	string	否	广告按钮文字
brand	string	推荐	品牌描述
images	`Image`[]	推荐	广告图片素材，图文或纯图时必填，详见`Image`对象
video	`Video`	推荐	广告视频素材，视频广告必填，详见`Video`对象
icon	`Image`	推荐	广告 icon 图片，详见`Image`对象

Image object

字段名称	类型	是否必填	备注
url	string	是	图片地址
width	int	推荐	图片宽度，单位：像素
height	int	推荐	图片高度，单位：像素

Video object

字段名称	类型	是否必填	备注
url	string	是	视频地址
duration	int	否	视频时长，单位：秒
size	int	否	视频大小，单位：KB
cover	`Image`	否	视频封面图片或视频后贴片图片，详见`Image`对象
width	int	推荐	图片宽度，单位：像素
height	int	推荐	图片高度，单位：像素
protocol	int	否	视频协议类型

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地址进行有效性校验，无效的话会自动转成非唤起的广告形式，打开落地页
universal_link	string	选填	iOS universal_link
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`对象
permission_url	string	选填	应用隐私权限Url，下载类广告必填。注：下载类广告 permission_url、permissions 任填一个即可
function_desc	string	选填	产品功能介绍，下载类广告必填
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,
                        "template_id": 4,
                        "material": {
                          "title": "插屏_图文礼盒素材27",
                          "images": [
                            {
                              "url": "https://ldaskd.obs.cn-south-1.myhuaweicloud.com:443/20220808163745-1006239809808371712.jpg"
                            }
                          ]
                        },
                        "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"
                        },
                        "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,
                        "template_id": 3,
                        "material": {
                          "title": "京东好物节",
                          "description": "先领券后下单，1元好物包邮到家，仅限今日！",
                          "images": [
                            {
                              "url": "http://www.adgoo.cn/201909/34_1_5d82f8d9536283.69356696.jpg"
                            }
                          ]
                        },
                        "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"
}

Proto文件

仅适用于以protobuf格式对接

bid.proto
syntax = "proto3";

message Request {
  string reqid = 1; //必填 	标识一次请求的唯一id
  string api_version = 2; //版本号，固定为2.0
  message Imp {
    string id = 1; //必填 	标识该imp的唯一id
    int32 seat_id = 2; //选填 	广告位标识id, DSP先同步获取ADX资源的素材标准，然后根据本字段识别曝光资源的来源和素材标准
    message Display {
      int32 template_id = 1; //必填 	广告模板id
      int32 width = 2; //必填 	广告位宽度
      int32 height = 3; //必填 	广告位高度
    }
    repeated Display display_list = 3; //选填 	广告位支持的广告形式: 包含多个，代表该位置支持多种广告形式，投放方可以根据自己需要选取其中一个广告投放，返回投放广告对应的广告形式id object的结构见display object
    message BidInfo {
      int32 bid_type = 1; //必填 	允许的竞价类型 0-CPM
      float bid_floor = 2; //选填 	可接受的底价 单位:分/千次曝光
    }
    repeated BidInfo bid_info_list = 4; //选填 	竞价信息，包含允许的竞价类型和底价，至少存在一个bidinfo object的结构
    repeated string deal_id = 5; //选填 	直接交易标识 ID,由交易平台和 DSP 提前约定
    repeated int32 action_type = 6; //支持的广告交互类型 0-无限制、1-H5、2-下载、3-唤醒、4-微信小程序、10-LBA、21-仅展示不可点击
    int32 ad_type = 7; //选填 	广告类型: 1-开屏 2-插屏 3-信息流 4-激励视频 5-推送
  }

  repeated Imp imp_list = 3; //必填 	曝光信息, 广告位信息, 一个BidRequest可能包含多个imp对象, 至少包含一个 object的结构见imp object
  message App {
    string id = 1; //必填 	APP id, 由ADX定义
    string name = 2; //选填 	APP名称
    string package_name = 3; //选填 APP package name, 平台内唯一
    repeated int32 cat = 4; //选填 	APP类型        需要参数测试？？？？？
    string ver = 5; //选填 	APP版本号
    string keywords = 6; //选填 	逗号分隔的APP关键词
    string cid = 7; //选填 	ssp对应渠道id
    string appchannel = 8; //选填 	app渠道id
  }
  App app = 4; //选填 	APP信息, 仅当广告位出现在APP时, 才会包含APP对象 object的结构见app object
  message Device {
    string ua = 1; //选填 	浏览器的user agent
    int32 device_type = 2; //选填 	设备类型 0-PC 1-手机 2-平板 3-互联网电视
    string brand = 3; //选填 	设备品牌(如: apple)
    string model = 4; //选填 	设备型号(如: iphone)
    string make = 5; //选填 	设备厂商(如: apple)
    int32 orientation = 6; // 屏幕方向 0-位置 1-竖屏 2-横屏
    string hmsVersion = 7; // 华为机型HMS Core版本号(如: 60000306)
    string asVersion = 8; // 大陆厂商安卓设备AS版本号(如: 110302302)
    int32 os = 9; //选填 	操作系统 0-Windows 1-MacOS 2-Linux 3-IOS 4-Android
    string osv = 10; //选填 	操作系统版本号
    int32 density = 11; //选填 	屏幕密度, 默认为400  即将废弃
    string ip = 12; //选填 	ipv4
    string ipv6 = 13; //选填 	ipv6
    int32 carrier = 14; //选填 	运营商 0-电信 1-移动 2-联通 3-网通 4-未知
    int32 network = 15; //选填 	网络类型 0-wifi 1-earthnet(有线网络) 2-2G 3-3G 4-4G 5-5G 6-未知
    int32 width = 16; //选填 	物理屏幕宽度
    int32 height = 17; //选填 	物理屏幕高度
    string imei = 18; //选填 	设备号imei
    string imei_md5 = 19; //选填 设备号imei的md5
    string oaid = 20; //选填 Android Q以上版本的设备号 明文形式
    string oaid_md5 = 21; //选填 oaid的md5
    string dpid = 22; //选填 	Android id
    string dpid_md5 = 23; //选填 	Android id的md5
    string idfa = 24; //选填 	Apple设备的idfa
    string idfa_md5 = 25; //选填 	Apple设备的idfa的md5
    string mac = 26; //选填 	设备的mac值
    string mac_md5 = 27; //选填 设备的mac值的md5
    string boot_mark = 28; //选填 取原值进⾏传输 iOS：1623815045.970028 Android：ec7f4f33-411a-47bc-8067-744a4e7e0723
    string update_mark = 29; //选填 取原值进⾏传输 iOS：1581141691.570419583 Android：1004697.709999999
    string birthTime = 30; //选填 设备初始化时间
    string bootTime = 31; //选填 系统启动时间
    string updateTime = 32; //选填 系统更新时间
    string idfv = 33; //选填 苹果开发者标识
    string paid = 34; //选填 拼多多版caid，仅iOS
    message Caid {
      string id = 1;            // caid 原值
      string bootTimeInSec = 2; // 设备启动时间
      string countryCode = 3;   // 国家
      string language = 4;      // 语言
      string deviceName = 5;    // 设备名称
      string model = 6;         // 设备型号
      string systemVersion = 7; // 系统版本
      string machine = 8;       // 设备 machine
      string carrierInfo = 9;   // 运营商
      string memory = 10;       // 物理内存
      string disk = 11;         // 磁盘大小
      string sysFileTime = 12;  //
      string timeZone = 13;     // 时区
      string initTime = 14;     // 设备初始化时间
      string version = 15;      // caid 原值版本号
    }
    Caid caid = 35;
    message Geo {
      float lat = 1; //选填 	纬度 (-90.0 - 90.0), 负值代表南
      float lon = 2; //选填 	经度 (-180.0 - 180.0), 负值代表西
      int32 type = 3; //选填 	位置来源 1-GPS定位 2-IP地址 3-用户提供(如注册信息)
      string country = 4; //选填 	国家
      string province = 5; //选填 	国家
      string city = 6; //选填 	城市
    }
    Geo geo = 36; //选填 	地域信息 object的结构见geo object
    int32 ppi = 37; //选填 	像素密度，表示每英寸像素点
    float pxRatio = 38; //选填 屏幕密度
    string aaid = 39; //选填 阿里集团内推出的匿名广告标识符，格式示例：CD7D878A870C-97D4-89A4-3EB3-D48AF066
    string elapseTime = 40; //选填 开机时长
    int32 sysCpuNum = 41; //选填  设备cpu数量
    int32 batteryState = 42; //设备当前充电状态 1:未知状态，2:正在充电，3 放电 4:未充满，5:满状态
    int32 battery = 43; //选填  设备电量
    string romVersion = 44; //选填 系统rom版本
    string sdFreeSpace = 45; //选填 磁盘剩余空间
    string anDisk = 46; //选填 安卓磁盘空间
    string anMemory = 47; //选填 安卓内存空间
  }
  Device device = 5; //选填 	设备信息
  message User {
    string id = 1; //选填 	由ADX定义的用户id
    int32 yob = 2; //选填 	出生年份 4位数字
    string gender = 3; //选填 	性别 M-男 F-女 默认-未知
    string keywords = 4; //选填 	逗号分隔得用户关键词或兴趣点
    string wuid = 5; //选填 	逗号分隔得用户关键词或兴趣点
  }
  User user = 6; //选填 	用户信息
  message Site {
    int32 id = 1; //必填 	站点id, 由ADX定义的site id
    string name = 2; //选填 	站点名称
    string domain = 3; //选填 站点域名
    string url = 4; //选填 	当前页面的url
    string ref = 5; //选填 	当前页面的referer url
    string keywords = 6; //选填 	逗号分隔的页面关键词
  }
  Site site = 7; //选填 	站点信息, 仅当广告位出现在web时, 才会包含site对象
  repeated string bcat = 8; //选填 	拒绝的广告分类
  repeated string badv = 9; //选填 	拒绝的广告主域名
  int32 test = 10; //选填 	测试字段, 标识是否涉及收费 0-生产模式 1-调试模式
  int32 at = 11; //选填 	该值固定为2 竞价类型 1-first price 2-second price plus dsp可以只处理at值为2的请求（仅rtb）
  message Ext {
    string iapp_list = 1; //需要测试与完善扩展结构
  }
  Ext ext = 12; //选填 	保留字段
}


message Response {
  string resid = 1; //必填 	response id, 与request id相同
  repeated SeatBidOptions seat_bid_list = 2; //选填 广告位-竞价列表, 如果参与竞价, 必须至少包含一个seat_bid对象 object的结构
  string bidid = 3; //选填 由DSP定义的响应id，用于 logging/tracking(日志或效果追踪)
}

message SeatBidOptions {
  repeated BidOptions bid_list = 1; //必填 竞价信息
  string adv = 2; //选填 该次竞价是代表谁参与的，一般设置成广告主id，用于logging/tracking
}

message BidOptions {
  string imp_id = 1; //必填 本次竞价所关联的imp id
  int32 price = 2; //必填 出价 单位:分
  string creative_id = 3; //必填 广告创意素材id, DSP需保证该id在DSP侧的唯一性
  string deal = 4; //选填 预定的资源id, 仅pd和pdb业务使用
  DirectiveResponseOptions directive_response = 5; //选填 广告创意信息, 免审核时使用, 白名单内的DSP此项必填
  int32 iapp_filter = 6; //选填 0=不过滤(默认) 1=过滤已安装 2=过滤未安装
  string ext_data = 7; //选填 自定义宏, 会替换竞价成功后的__EXT_DATA__宏
}

message DirectiveResponseOptions {
  string creative_id = 1; //必填 广告创意素材id, DSP需保证该id在DSP侧的唯一性
  int32 advertiser_id = 2; //必填 广告主id
  string advertiser_name = 3; //必填 广告主名称
  int32 vocation = 4; //必填 广告主行业编码, 详见广告主行业编码表
  int32 template_id = 5; //必填 广告模板id
  message Material {
    string title = 1;          // 推荐 广告标题
    string description = 2;    // 推荐 广告描述
    string btn = 3;            // 广告按钮文字
    string brand = 4;          // 品牌描述
    message Image {
      string url = 1;   // 必填 图片地址
      int32 width = 2;  // 推荐 图片宽度，单位：像素
      int32 height = 3; // 推荐 图片高度，单位：像素
    }
    repeated Image images = 5; // 推荐 广告图片素材，图文或纯图时必填
    Video video = 6;           // 推荐 广告视频素材，视频广告必填
    message Video {
      string url = 1;     // 必填 视频地址
      int32 duration = 2; // 推荐 视频时长，单位：秒
      int32 size = 3;     // 选填 视频大小，单位：KB
      Image cover = 4;    // 推荐 视频封面图片或视频后贴片图片
      int32 protocol = 5; // 选填 视频协议类型
    }
    Image icon = 7; // 广告 icon 图片
  }
  Material material = 6; //必填 创意素材内容, 包括视频, 图片, 文本等. 需严格按照广告形式的定义顺序来指定上传
  message AppInfo {
    int32 product_type = 1; //必填 1-普通链接 2-android应用下载 3-ios应用下载
    string android_url = 2; //选填 安卓下载地址，下载类时android_url或 ios_url⾄少填⼀个，其它情况直接过滤为空
    string ios_url = 3; //选填 IOS下载地址，下载类选填
    string deeplink = 4; //选填 应用直达URL，SDK客户端会对deeplink地址进行有效性校验，无效的话会自动转成非唤起的广告形式，打开落地页
    string package_name = 5; //选填 下载应用包名 下载类广告必填
    string app_name = 6; //选填 应用名称，下载和唤醒类广告必填
    int32 app_size = 7; //选填 应用大小，单位 KB，下载类需要
    string app_logo = 8; //选填 应用logo，下载和唤醒类广告必填
    string intro = 9;   // 选填 应用介绍
    string version = 10;   // 选填 应用版本号，下载类广告必填
    string developer = 11; // 选填 应用开发者，下载类广告必填
    string privacy = 12;  // 选填 应用隐私协议，下载类广告必填
    string privacy_url = 13; // 选填 应用隐私协议链接，下载类广告必填。注：下载类广告 privacy、privacy_url 任填一个即可。
    message Permission {
      string title = 1; // 必填 隐私权限标题
      string desc = 2;  // 必填 隐私权限详细描述
    }
    repeated Permission permissions = 14; // 应用隐私权限列表
    string permission_url = 15; // 选填 应用隐私权限Url，下载类广告必填。注：下载类广告 permission_url、function_desc 任填一个即可
    string function_desc = 16; // 选填 产品功能介绍，下载类广告必填
    message MiniProgram {
      string wx_username = 1; // 必填 所需跳转的小程序原始 ID（以"gh_"开头）
      string wx_path = 2;     // 推荐 所需跳转的小程序内页面路径及参数，不填默认拉起小程序主页
      uint32 wx_minitype = 3; // 必填 所需跳转的小程序类型，0：正式版，1：开发版，2：体验版
    }
    MiniProgram wx_miniProgram = 17; // 调起小程序
    string universal_link = 18; // 选填 IOS universal_link
  }
  AppInfo app_info = 7; //选填 app下载唤起
  string url = 8; //必填 落地url 支持302
  repeated string imptk = 9; //选填 曝光监测url, 最多5个
  repeated string clktk = 10; //选填 点击监测url, 最多3个
  repeated string dstarttk = 11; //选填 仅用于应用下载广告，开始下载监播地址, 如果需要该信息请与我方确认投放资源是否支持，最多3个
  repeated string dfinishtk = 12; //选填 仅用于应用下载广告，下载完成监播地址，最多3个
  repeated string dinstalltk = 13; //选填 仅用于应用下载广告；安装完成监播地址，最多3个
  repeated string deeplinktk = 14; //选填 唤醒成功上报地址，当前仅用于开屏广告位，最多8个
  repeated string dstartinstalltk = 15; //选填 仅用于应用下载广告；开始安装监播地址。如果需要该信息请与我方确认投放资源是否支持，最多3个
  repeated string deeplinkfailedtk = 16; //选填 deeplink调起失败时上报的url列表，最多3个
  repeated string installedtk = 17; //选填 deeplink跳转时判断应用已安装情况下上报的url列表，最多3个
  repeated string uninstalledtk = 18; //选填 deeplink跳转时判断应用未安装情况下上报的url列表，最多3个
  repeated string incentiveloadedtk = 19; //选填 仅用于激励视频广告，激励视频加载成功时统计url列表, 最多3个
  repeated string videostarttk = 20; //选填 仅用于信息流视频、激励视频，视频开始播放统计url列表，最多3个
  repeated string firstQuartiletk = 21; //选填 仅用于激励视频，视频播放至25%时统计url列表，最多3个
  repeated string midpointtk = 22; //选填 仅用于激励视频，视频播放至50%时统计url列表，最多3个
  repeated string thirdQuartiletk = 23; //选填 仅用于激励视频，视频播放至75%时统计url列表，最多3个
  repeated string videoCompletetk = 24; //选填 仅用于信息流视频、激励视频，视频播放完成统计url列表，最多3个
  repeated string incentiveerrortk = 25; //选填 仅用于激励视频广告，激励视频播放错误时统计url列表，最多3个
  string nurl = 26; //选填 竞胜通知
  string lurl = 27; //选填 竞败通知
}

接口定义v1.0

警告

v1.0已经过期，请尽快升级到v2.0
如要查看v1.0的历史文档，👉v1.0归档

Win Notice与宏

win notice 会随着曝光上报（展示监测链接）一起发送，不做单独的 win notice。通过对展示监测链接中特定参数的宏替换，将广告的计费价格发送给赢得竞价的 DSP 平台。

win notice随曝光上报下发至客户端，并支持以下宏

宏名称	描述
`__WIN_PRICE__`	广告成交价格
`__ID__`	在BidRequest的reqid
`__BID_ID__`	在BidResponse的bidid
`__IMP_ID__`	在BidResponse的imp_id
`__ADV__`	在BidResponse的seat_bid.adv
`__CRID__`	在BidResponse的bid.creative_id
`__EXT_DATA__`	在BidResponse的bid.ext_data
`__re_down_x__`	按下时相对横坐标（相对广告位）
`__re_down_y__`	按下时相对纵坐标（相对广告位）
`__re_up_x__`	离开时相对横坐标（相对广告位）
`__re_up_y__`	离开时相对纵坐标（相对广告位）
`__down_x__`	按下时绝对横坐标（屏幕坐标）
`__down_y__`	按下时绝对纵坐标（屏幕坐标）
`__up_x__`	离开时绝对横坐标（屏幕坐标）
`__up_y__`	离开时绝对纵坐标（屏幕坐标）
`__acw__`	点击时，实际展示的广告容器宽
`__ach__`	点击时，实际展示的广告容器高
`__itm__`	触发事件类型 1：正常点击，即常规触屏点击 2：摇一摇 3：划动点击
`__xma__`	设备摇动时，x 轴加速度，单位：m/s^2 用户摇动点击时，x轴加速度峰值100倍取整，仅摇一摇需替换
`__yma__`	设备摇动时，y 轴加速度，单位：m/s^2 用户摇动点击时，y轴加速度峰值100倍取整，仅摇一摇需替换
`__zma__`	设备摇动时，z 轴加速度，单位：m/s^2 用户摇动点击时，z轴加速度峰值100倍取整，仅摇一摇需替换
`__utc_ts__`	上报时间戳，执行任务上报时手机客户端的时间戳，毫秒级别
`__TIMESTAMP__`	上报时间戳，执行任务上报时手机客户端的时间戳，秒级别

注：相对坐标和绝对坐标在无法获取时传"-999"

DSP的展现监测链接中必须加入__WIN_PRICE__、__ID__宏

带宏的展现链接示例

 http://dsp.com/monitor?reqid=__ID__&price=__WIN_PRICE__

出于保密的考虑，价格参数（WIN_PRICE）做了加密处理，加密解密方法见后面价格加密解密小节 DSP如果要记录成交价格，需要在曝光监控地址里面包含宏__WIN_PRICE__，2345_ADX 会将该宏替换为加密后的成交价格串业务说明

DSP需要预先在2345-ADX平台注册自己的cookie-mapping-url

业务流程

2345-ADX向DSP发起广告请求时，携带用户在2345-ADX的唯一UID；
DSP根据UID决定是否发起Cookie Mapping。若发起, 则将ADX的CM URL添加到返回广告的pv字段中；
2345-ADX的CM服务器接收到请求后，解析dspid参数，然后带上u2345id，302到DSP的CM URL；
DSP CM Service接收请求，记录ADX_UID和u2345id的映射关系；并向用户浏览器返回一个透明像素点(或204 No Content)。

备注：若提供CM，需要监测CM的使用情况；适当防止强制cookie映射

cookie mapping实现流程

DSP在网页上设置一个像素点tag，用户浏览器向该url请求数据
```
http://2345-adx.com/dsp/cm?dspid=1234
```
dspid是2345-ADX平台分配给DSP的全局唯一ID
2345-ADX平台会将该请求重定向(302 Redirect)到DSP提供的cookie-mapping-url
```
http://dsp.cookie-mapping-url?u2345id=9043F352A
```
u2345id是用户在2345-ADX平台的userid
DSP接收到该请求，记录下u2345id和dsp_uid的映射关系
DSP向用户浏览器返回一个透明像素点(或204 No Content)

备注：当2345-ADX接收到的请求中，没有携带有效的dspid时，会直接返回用户一个透明像素点

价格加密解密

参数名	描述
iv	初始化向量，16字节，每一次展现都会有唯一的初始化向量
e_key	价格加密密钥，32字节，每个dsp会被分配唯一的加密密钥
i_key	价格校验密钥，32字节，每个dsp会被分配唯一的校验密钥
price	原始价格，8字节
hmac(k, d)	使用密钥 k 对数据 d 进行 SHA-1 HMAC 哈希
^	异或操作
a + b	拼接字符串 a 和 b

加密伪代码：

pad = hmac(e_key, iv);  // first 8 bytes
enc_price = pad ^ price; 
signature = hmac(i_key, price + iv);  // first 4 bytes
${__WIN_PRICE__} = urlsafe_b64encode(iv + enc_price + signature); 

价格解密过程

参数名	描述
e_key	价格加密密钥(价格解密)，32字节，每个dsp会被分配唯一的加密密钥
i_key	价格校验密钥，32字节，每个dsp会被分配唯一的校验密钥
`${__WIN_PRICE__}`	价格宏，28字节

解密伪代码

enc_price = urlsafe_b64decoded(${__WIN_PRICE__});
(iv, p, sig) = split enc_price according to fixed lengths;
pad = hmac(e_key, iv);  // first 8 bytes
price = p ^ pad;
local_sig = hmac(i_key, price + iv);  // first 4 bytes
success = (local_sig == sig);

//示例
winPrice = "YWJjZGVmZ2hpamtsbW5vcAlRUhUYREUXMTFjZA=="; //加密后的价格
ekey = "16db4a04510503f7d0c1505e5d9007d2";
ikey = "d02cd2afcd942568e4b297529a0784e4";
//解密后的price
price = "100";

golang
java
php

import (
"crypto/hmac"
"crypto/sha1"
"fmt"
"github.com/foursking/bstring"
"github.com/thinkeridea/go-extend/exstrings"
)

func PriceDecode(b64 string, eKey string) string {
    b64 = exstrings.Replace(exstrings.Replace(b64, "-", "+", -1), "_", "/", -1)
    str, err := bstring.Base64DecodeString(b64)
    if err != nil || len(str) < 28 {
        return ""
    }
    return StrByXOR(str[16:len(str)-4], HmacSha1(str[:16], eKey)[:8])
}

func StrByXOR(message string, keywords string) string {
    messageLen := len(message)
    keywordsLen := len(keywords)
    result := ""
    for i := 0; i < messageLen; i++ {
        result += string(message[i] ^ keywords[i%keywordsLen])
    }
    return result
}

func HmacSha1(src string, secret string) string {
    h := hmac.New(sha1.New, []byte(secret))
    h.Write([]byte(src))
    return fmt.Sprintf("%x", h.Sum(nil))
}

//示例
func main() {
    winPrice := "YWJjZGVmZ2hpamtsbW5vcAlRUhUYREUXMTFjZA=="
    ekey := "16db4a04510503f7d0c1505e5d9007d2"
    fmt.Printf("%s", PriceDecode(winPrice, ekey)) //100
}

package Check2345;
import org.testng.annotations.Test;
import java.nio.ByteBuffer;
import java.nio.ByteOrder;
import javax.crypto.Mac;
import javax.crypto.spec.SecretKeySpec;
import org.apache.commons.codec.binary.Base64;
import org.apache.commons.lang3.ArrayUtils;

public class ADX_price {
    private static final String MAC_NAME = "HmacSHA1";

    public static void main(String[] args) {
        try {
            System.out.println(decodePrice("a9033eebd57f5561d64d8e58eb354604", "bcd92b70e3ba0c5959f4d2ac6b1b5696",
            "YWRjZmU0Y2ZjNjljMzdkMFcCREVGQRcRNDUyZQ=="));
        } catch (Exception e) {
            e.printStackTrace();
        }
    }

    /**
     *
     * @param e_key 价格加密密钥
     * @param i_key 价格校验密钥
     * @param e_enc 待解密
     * @return
     * @throws Exception
     */
    private static double decodePrice(String e_key, String i_key, String e_enc) throws Exception {
        if ("".equals(e_key) || "".equals(i_key) || "".equals(e_enc)) {
            return 0;
        }

        byte[] e_src = Base64.decodeBase64(e_enc); // base64解码

        byte[] iv = ArrayUtils.subarray(e_src, 0, 16); // 初始化矢量数组

        byte[] en_price = ArrayUtils.subarray(e_src, 16, 24); // 加密的价格数组

        byte[] sig = ArrayUtils.subarray(e_src, 24, 28); // 完整性签名的前4位

        byte[] pad = ArrayUtils.subarray(getSignature(new String(iv), e_key).getBytes(), 0, 8); // 加密得到加密数组

        byte[] price = xor_bytes(en_price, pad, 8); // 通过异或运算得到价格数组

        byte[] merge = byteMerger(price, iv); // 合并price与iv数组

        byte[] conf_sig = ArrayUtils.subarray(getSignature(new String(merge), i_key).getBytes(), 0, 4);

        boolean flag = ArrayUtils.isEquals(sig, conf_sig); // 比较两个签名数组是否相同

        if (!flag) {
            throw new Exception("signature is illegal"); // 返回签名非法的错误
        } else {
            return Double.parseDouble(new String(price));
        }
    }

    private static byte[] xor_bytes(byte[] bytes1, byte[] bytes2, int length) {
        byte[] result = new byte[length];
        for (int i = 0; i < length; i++) {
            result[i] = (byte) (bytes1[i] ^ bytes2[i]);
        }
        return result;
    }

    // System.arraycopy()方法
    public static byte[] byteMerger(byte[] bt1, byte[] bt2) {
        if (bt1 == null || bt2 == null) {
            return null;
        }
        byte[] bt3 = new byte[bt1.length + bt2.length];
        System.arraycopy(bt1, 0, bt3, 0, bt1.length);
        System.arraycopy(bt2, 0, bt3, bt1.length, bt2.length);
        return bt3;
    }

    public static String getSignature(String data, String key) throws Exception {
        if ("".equals(data) || "".equals(key)) {
            return "";
        }
        byte[] keyBytes = key.getBytes();
        // 根据给定的字节数组构造一个密钥。
        SecretKeySpec signingKey = new SecretKeySpec(keyBytes, MAC_NAME);
        Mac mac = Mac.getInstance(MAC_NAME);
        mac.init(signingKey);

        byte[] rawHmac = mac.doFinal(data.getBytes());

        String hexBytes = byte2hex(rawHmac);
        return hexBytes;
    }

    private static String byte2hex(final byte[] b) {
        if (b == null) {
            return "";
        }
        String hs = "";
        String stmp = "";
        for (int n = 0; n < b.length; n++) {
            // 以十六进制（基数 16）无符号整数形式返回一个整数参数的字符串表示形式。
            stmp = (java.lang.Integer.toHexString(b[n] & 0xFF));
            if (stmp.length() == 1) {
                hs = hs + "0" + stmp;
            } else {
                hs = hs + stmp;
            }
        }
        return hs;
    }
}

function priceDecode($winPrice, $eKey, $iKey): float {
    if (empty($winPrice)) {
        return 0;
    }
    $s1 = base64_decode(str_pad(strtr($winPrice, ["-" => "+", "_" => "/"]), strlen($winPrice) % 4, '=', STR_PAD_RIGHT));
    $iv = substr($s1, 0, 16);
    $enc_price = substr($s1, 16, 8);
    $sig = substr($s1, 24, 4);
    $pad = substr(hash_hmac("sha1", $iv, $eKey), 0, 8);
    $price = $enc_price ^ $pad;
    $conf_sig = substr(hash_hmac("sha1", $price . $iv, $iKey), 0, 4);
    if ($sig == $conf_sig) {
        return floatval($price);
    }
    return 0;
}

$winPrice = "YWJjZGVmZ2hpamtsbW5vcAlRUhUYREUXMTFjZA==";
$ekey = "16db4a04510503f7d0c1505e5d9007d2";
$ikey = "d02cd2afcd942568e4b297529a0784e4";
echo priceDecode($winPrice, $ekey, $ikey); //100

实时竞价接口

版本历史​

通信方式​

简介​

请求头​

响应头​

HTTP状态码​

接口定义v2.0​

2.0更新说明​

BidRequest结构说明​

BidRequest object​

imp object​

display object​

bid_info object​

site object​

app object​

device object​

geo object​

user object​

Caid object​

ext object​

BidRequest请求示例​

BidResponse基础结构说明​

BidResponse object​

seat_bid object​

bid object​

directive_response object​

Material object​

Image object​

Video object​

app_info object​

permission object​

wxMiniProgram object​

BidResponse响应示例​

Proto文件​

接口定义v1.0​

Win Notice与宏​

用户映射 Cookie Mapping​

价格加密解密​