流量购买方对接协议

文档目的

本文档定义了Adxing SSP 平台向购买方合作请求广告，以及购买方平台返回广 告的规范。 平台之间的实时交互，使用标准 HTTP 协议、protocol buffers 格式进行交互。 可以通过http://code.google.com/p/protobuf 获取最新的protocol buffers 技术支持。 具体的 protocol buffers 的格式定义，请查看 adxing-for-dsp.proto

文档范围

本文档范围包括描述Adxing 服务器发送请求到流量购买方服务器的数据交互。

请求通用认证

所有的请求均遵循HTTP协议，请求和响应数据如无特殊说明均为JSON。

编码方式

若无特殊说明或响应头中的 Content-Type 未指定编码,请求和响应中的字符 编码均使用UTF-8 编码。

通用参数

HTTP Header 中包含OAuth2 的Bearer 的授权Token：

HTTP Header 名称	Value	描述
Authorization	Bearer XXXXXX	授权令牌，由调用方自行生成

警告

Token 有效期20 分钟，失效后需要重新生成。

API 响应

支持HTTP标准状态码，具体如下：

状态码	名称	说明
200	成功
400	未授权	没有权限

API 授权

API 所有接口均通过请求头（HEADER）中传递的TOKEN（授权令牌）来进行 身份认证和鉴权，系统会校验TOKEN 有效性。

授权令牌（TOKEN）生成算法如下： token=base64(app_id+","+user_id+","+timestamp+","+signature)

说明：","逗号前无空格

所有内容使用半角逗号（,）按顺序拼接起来，再经过Base64 编码。 app_id、user_id：API授权接入方唯一身份标识，在“开发者信息”页面中获取； app_key：开通API授权后获得的私钥，在“开发者信息”页面中获取；

timestamp：发起请求时的时间戳，精确到秒，这个值跟接收到请求时的服务 器时间戳值偏差（正或负）超过1200秒（20分钟）时，请求会被拒绝，要求调 用方重新生成token（请使用UTC+08:00 中国北京时间）； signature：签名字符串，signature = sha1(app_id + app_key+timestamp)， 采用sha1 加密算法生成签名串（此处加号+代表字符串拼接，不是指要包含加 号+），timestamp 为上面使用的时间戳；

接口定义

请求URL 参考RESTful 风格，请求方式为POST，约定了使用的协议、域名、版本，详 细定义如下： https://api.example.com/ <API_VERSION>/req_ad 其中:

-1. 协议: 必须使用HTTPS（开发阶段HTTP）。

-2. API_VERSION: 版本号,当前版本号码为 v1。

注：api 支持protobuf、json 等格式的请求/响应数据，使用时需要设置对应的 Content-Type 和Accept 为 application/x-protobuf 或 application/json

BidRequest&Response

BidRequest

即 adxing-for-dsp.proto 中定义的 BidRequest 消息。具体说明如下:

BidRequest 对象，广告请求

参数名称	类型	必须	说明
id	string	是	请求唯一标示；例如：m83390492620425
app	array Object	是	请求应用程序信息
device	Object	是	请求中的设备信息
network	Object	是	设备的网络环境
imp	array object	是	展示广告位置信息(目前只支持单个请求)
precache	int	否	是否为预缓存请求，默认0-非预缓存，1-预缓存请求
test	int	否	当前请求是否是test 请求，0-正式请求（默认），1-测试请求
tmax	int	否	广告竞价超时时间，单位毫秒。默认200ms

APP 对象，应用程序

参数名称	类型	必须	说明
id	string	是	应用程序id；例如：1032
cat	string	否	应用程序所属行业类型，类型见附录 应用程序行业类型
name	string	否	应用程序名称；例如：mygame
bundle	string	否	应用程序 bundle 或 package 名称；例如： com.example.mygame
domain	string	否	应用程序域；例如：mygame.example.com
keywords	string	否	应用程序关键字，多个词之间用“,”分割； 例如：益智游戏,休闲娱乐
publisher	Object	是	所属开发者

publisher 对象，开发者信息

参数名称	类型	必须	说明
id	string	是	开发者id；例如：1232
name	string	是	所属开发者名称；例如：developer-exam

Device对象， 设备

参数名称	类型	必须	说明
devicetype	int	否	设备类型，1-Phone，2-Tablet；
make	string	否	设备品牌(小写)；例如：apple
model	string	否	设备型号(小写)；例如：iphone
hwv	string	否	设备的硬件版本（Hardware version）；例如： “5S”，iPhone 5s 的“5S”
os	string	否	操作系统，0-UNKNOWN，1-iOS，2-Android， 3-WindowsPhone，例如：1
osv	string	否	操作系统版本；例如：7.0.2
size	string	否	设备的屏幕分辨率；例如：1024x768
pixel_ratio	int	否	设备像素比例，用于广告位size 缩放， 千分位表示，默认1000
screen_density	float	否	屏幕像素密度
screen_orientation	int	否	横竖屏；0-未知; 1-表示竖屏; 2-表示横屏， 缺省是未知
ua	string	否	浏览器用户代理，例如： Mozilla/5.0 (iPhone; U; CPU iPhone OS 4_3_2 like Mac OS X; en-us) AppleWebKit/533.17.9 (KHTML, like Gecko) Version/5.0.2 Mobile/8H7 Safari/6533.18.5
ip	string	否	手机设备IP 地址，ipv4；例如：8.8.8.8
geo	object	否	设备地理位置信息
ifa	string	否	IOS 设备idfa，原始值；例如：e4273e31-97a9- 4b29-93a8-8a99f0cea068
ifa_md5	string	否	IOS 设备idfa，md5 加密值；例如：e4273e31-97a9- 4b29-93a8-8a99f0cea068
android_id	string	否	android 设备的android id，原始值
android_id_md5	string	否	android 设备的android id，md5 加密值
imei	string	否	imei 原始值
imei_md5	string	否	imei,md5加密值
mac	string	否	手机设备mac原始值，大写去除冒号分隔符
mac_md5	string	否	手机设备mac的md5加密值，大写去除冒号分隔符
duid	string	否	Windows Phone 设备DUID，原始值
duid_md5	string	否	Windows Phone 设备DUID，md5加密值

geo 对象，设备地理位置信息

参数名称	类型	必须	说明
lat	float	否	latitude，设备所在地理位置的纬度（小数点格式）； 例如：39.91667
lon	float	否	longitude，设备所在地理位置的经度（小数点格式）； 例如：116.41667
type	int	否	经纬度信息来源 1-通过GPS 定位, 2-通过IP 地址定位

network 对象，设备的网络环境

参数名称	类型	必须	说明
type	int	否	网络环境 0-UNKNOWN, 1-WIFI, 2-2G, 3-3G, 4-4G
operator	int	否	设备的网络运营商；0-未知, 1-移动, 2-联通, 3-电信
cellular_id	string	否	基站 ID
wifis	array object	否	周边 wifi 热点

wifis 对象，wifi 热点

参数名称	类型	必须	说明
mac	string	否	WIFI 热点 MAC 地址
rssi	string	否	信号强度

imp 对象，展示广告位置信息

参数名称	类型	必须	说明
id	int	是	imp 对象序列号id，从1 开始
mtype	int	是	广告素材组成类型，1-素材元素（默认），2-html； 当前仅支持1
banner	object	否	Banner 广告请求对象，包括横幅、插屏、开屏
video	object	否	视频广告请求对象
native	object	否	原生广告请求对象，包括图文信息流、视频信息流
pmp	object	否	pmp私有广告（pd、pdb）对象

Banner 对象,图片广告位信息

参数名称	类型	必须	说明
pos_id	string	是	SSP 系统广告位唯一标识（ID
type	int	是	广告位类型，4-横幅，5-插页，6-开屏
w	int	否	广告位宽；例如：300
h	int	否	广告位高；例如：250
mimes	int array	否	支持素材格式，1-png,2-jpg,3-gif,4-mp4
size_kb	int	否	图片大小限制
bidfloor	float	否	该展示接收cpm 出价方式的最低价格，单位元； 例如 1.23
bidfloor_cpc	float	否	该展示接收cpc 出价方式的最低价格，单位元； 广告出价，单位元；例如 1.23
bcat	string array	否	禁止投放广告主行业类型，类型见附录 广告主行业类型
badv	string array	否	禁止投放广告主主域，例如：“ford.com”

Video 对象,视频广告位信息

参数名称	类型	必须	说明
pos_id	string	是	SSP 系统广告位唯一标识（ID
type	int	是	广告位类型，3-视频
w	int	否	广告位宽；例如：640
h	int	否	广告位高；例如：100
mimes	int array	否	支持素材格式，，4-mp4,5-flv,6-swf
size_kb	int	否	视频支持最大尺寸
bidfloor	float	否	该展示接收cpm 出价方式的最低价格，单位元； 例如 1.23
bidfloor_cpc	float	否	该展示接收cpc 出价方式的最低价格，单位元； 广告出价，单位元；例如 1.23
bcat	string array	否	禁止投放广告主行业类型，类型见附录 广告主行业类型
badv	string array	否	禁止投放广告主主域，例如：“ford.com”
linearity	int	是	广告展现样式 0: "未知"; 1:"instream/linear"即线性贴片素材，包括前贴中贴后贴; 2:"overlay/nonlinear"即视频播放中的悬浮广告; 3:"pause"即视频播放暂停中的悬浮广告; 4:"fullscreen"即视频全屏播放时的悬浮广告; 5:"openapp"即开机广告
startdelay	int	否	线性贴片素材类型，该字段仅在linearity=1时有效； 0：前帖；-1：中贴；-2：后贴。
pos	int	否	广告在多个视频广告中播放先后位置序号，linearity=1播 放在前或5时有效；如该请求广告会贴视频或开屏 视频广告中第一个播放，则传1。

Native 对象,原生广告位信息

参数名称	类型	必须	说明
pos_id	string	是	SSP 系统广告位唯一标识（ID)
type	int	是	广告位类型，7-图文信息流、8-视频信息流
pos_template _id	int	否	广告位模板规格ID，见附录 广告位模板规格
bidfloor	float	否	该展示接收cpm 出价方式的最低价格，单位元； 例如 1.23
bidfloor_cpc	float	否	该展示接收cpc 出价方式的最低价格，单位元； 广告出价，单位元；例如 1.23
bcat	string array	否	禁止投放广告主行业类型，类型见附录 广告主行业类型
badv	string array	否	禁止投放广告主主域，例如：“ford.com”

PMP对象,私有广告交易对象（PD、PDB）

参数名称	类型	必须	说明
private_auction	Bool	否	是否私有交易
deals	Object	否	Deal信息，在private_auction为true时必须存在

deals对象,私有广告交易设定对象

参数名称	类型	必须	说明
Id	String	是	Dealid
bidfloor	Double	否	底价
wseat	String	否	N/A
wadomain	String	否	N/A

BidResponse

即 adxing-for-dsp.proto 中定义的 SellerResponse 消息。具体说明如下:

BidResponse对象

参数名称	类型	必须	说明
success	bool	是	检索是否成功 请求验证失败 :False 请求验证成功 进入广告筛选: True
id	string	是	返回媒体方广告请求ID ； 仅success 时为required。 例如：m83390492620425
bidid	string	否	Response id，DSP 系统生成唯一id，跟踪广告请求id
mtype	int	是	广告素材组成类型，1-素材元素（默认） 2-html；同bidrequest mtype 值保持相同
seatbid	array object	是	广告竞价对象；仅success 时为required。
nbr	int	是	检索状态描述, 参考 Nbr定义。

Seatbid 对象

参数名称	类型	必须	说明
id	string	是	跟踪竞价广告id，DSP 系统生成唯一id
imp_id	int	否	imp 对象序列号id
cost_type	int	否	计费方式 1-cpc, 2-cpm
price	float	否	广告出价，单位元；例如 1.23
pos_id	string	是	广告位 ID
interaction_type	int	是	广告交互类型 0-NO_INTERACT 1-SURFING( 打开网页， 默认) 2-DOWNLOAD(下载)
adv	string array	否	投放广告主主域，例如：“ford.com”
cat	string array	否	禁止投放广告主行业类型，类型见附录 广告主行业类型
cid	string	否	广告活动id（或订单、计划id）
sid	string	否	广告策略id（或广告组、单元id）
adid	string	是	广告id（或创意id）
ssp_adid	string	是	SSP平台 广告id（或创意id）
creative_elements	object	是	创意元素；广告位广告类型对应具体广告元素， 见附录“广告位返回广告元素参照表”
site_url	string	否	推广标的物地址，最终落地页地址
click_through_url	string	否	点击地址（同步点击监测地址）。 注：如果site_url、click_through_url同时存在，点击响应 地址为click_through_url
click_tracking_urls	array	否	异步点击监测地址，最多同时支持3条 注：仅存在异步上报地址时，媒体客户端需要在点击响应 site_url或click_tracking_url跳转的同时，单独上报 call）单条或多条异步点击监测地址
imp_tracking_urls	array	否	曝光监测地址，最多同时支持3条

creative_elements 对象

参数名称	类型	必须	说明
corporate_name	string	否	商标名称
corporate_img	string	否	商标，图片url
image	string	否	图片1 url
image2	string	否	图片2 url
image3	string	否	图片3 url
title	string	否	广告文案
description	string	否	广告描述
video	string	否	VIDEO url