SSP对接文档协议

文档说明

此文档仅供 SSP 公司与 ZPLAY 交易服务对接使用

接入准备

在 SSP 和 ADX 双方运营人员初步沟通会议之后,由 ADX 运营人员以邮件方式提供 SSP 账号和相应的 Token 信息。

Warning

暂不提供 线上提交注册信息功能。

SSP 平台需要向 ADX 申请 app 的 key(即 app_key 字段)，不需要 SSP 在后台做任何操作

实时竞价流程

实时竞标(RTB) 是指用户在访问媒体产生广告曝光机会时,SSP平台向ADX发送带有广告位信息的广告请求, ADX根据曝光信 息及 DSP 出价竞拍结果实时返回给 SSP,客户端展示竞价优胜的广告。

下图描述了一个曝光从发生到实时竞标,直到最后获胜广告展示的全过程:

  1. 用户(USER)向 SSP 网站发起访问请求, 产生曝光机会时,SSP 将用户重定向到 ADX
  2. ADX 向众多家 DSP 并行发起曝光竞标请求, DSP 进行估值后给出此次曝光的报价,ADX 集齐 DSP 报价返回后进行拍卖
  3. ADX 对竞标成功的 DSP 广告信息返回给 SSP 平台,将获胜 DSP 的广告返回给用户展示
  4. 用户客户端(USER)向 DSP 发送展示通知及竞价结果

其中 ADX 与 SSP 的实时交互集中在 1),3)

接入说明

请求URL

当需要请求广告时,发送一个 HTTP POST 请求到下面的地址:bid.adx.yumimobi.com/adx

通信方式及编码

ZPLAY ADX 和 SSP 之间的基础通信协议采用 HTTP 协议、POST 方法,数据使用 JSON 格式,编码采用 UTF-8 编码。

请求头

http头信息段 说明
X-Forwarded-For 包含客户端真正的请求地址, 例:“8.8.8.8”。如果通过服务端对接,请务必 传递客户端的地址,使用服务器地址会被视为 作弊流量屏蔽
User-Agent 移动设备的 User-Agent, 从服务端使用非真实 User-Agent 会被视为问题 流量.例:“Mozilla/5.0 (iPad; CPU OS 5_0 like Mac OS X) AppleWebKit/534.46 (KHTML, like Gecko) Version/5.1 Mobile/9A334 Safari/7534.48.3”。

竞价信息

竞价请求

Request 请求是广告位请求广告的入口,由 SSP 按本文档中规定 URL 向 ADX 发送

Rquest字段信息

字段名称 类型 必须 描述
ver string 是 协议版本，当前版本号1.1
ssp_token string 是 ssp token,从 ZPlay ADX 获得
is_test int 否 这是不是测试请求的标志,如果是测试请求 则只发给测试的 dsp, 0 表示不是测试, 1 表示测试, 默认 不是测试
is_tail int 否 是否为尾量的标志,默认为 0,0 表示正 常量,1 表示为尾量, 2 标识为正常量但不 走 api(针对联想), 3 标 识为尾量但也不 走 api(针对联想)
need_https int 否 是否需要 https 链接的标识,默认为 0,0 标识不需要,1 标识需要。当为 1 时,需要 返回的所有素材及追 踪链接必须是 https 链接
sdk_ver string 否 zplay自由广告sdk版本号
app 对象 是 app对象信息
site 对象 否 site对象信息
device 对象 是 设备信息
user 对象 否 用户信息
ad 对象 否 广告信息, 保留此元素是为了保持向后兼 容,只存在于协议版本 1.0(包括)之前。从 1.1(包括)以后, 使用 ads
ads ad对象数 组 是 广告信息数组
zplay 对象 否 自主系统信息，zplay内部使用

app对象信息

字段类型 类型 必须 描述
id string 是 app id
name string 是 app 名称
app_key string 是 app key
bundle string 是 app bundle id
ver string 否 app 版本号
cat []string 否 app类别
publisher 对象 否  

site对象信息

字段名称 类型 必须 描述
id string 是 网站ID
name string 否 网站名称
domain string 否 网站域名
page string 是 当前页面网址
cat []string 否 网站类别
sectioncat []string 否 网站当前频道类别
pagecat []string 否 网站当前页面类别
ref string 否 当前页面Referrer网址
search string 否 进入当前页面的搜索关键词
mobile int 是 是否为移动网站，1为移动网站
keywords string 否 网页关键字，可多个，逗号分隔
publisher 对象 否 出品方

Publisher对象信息

字段名称 类型 必须 描述
name string 是 出品方名称
domain string 否 出品方顶级域名
cat string 否 出品方类别

Device对象信息

字段名称 类型 必须 描述
model string 是 设备型号
make string 否 生产厂商，例如：“Samsung”
brand string 否 手机品牌，例如：“MI4”
plmn string 否 国家运营商编号
adt boolean 否 是否允许通过追踪用户行为进行定向投放, 0:不允许,1:允许,默认为 1
connection_typ e string 是 连接类型,空串表示未知,wifi, 2g, 3g, 4g, ethernet, cell_unknown
carrier int 是 运营商,0:移动,1:电信,3:联通,4:unknown
orientation int 是 设备方向,1:纵向,3:横向
mac string 否 MAC 地址;ios7 以上取不到,可为空
imei string 是 IMEI 码。ios 没有 (cdma 手机请传 meid 码)
imsi string 否 imsi
android_id string 否 Android ID 。Android 手机不传会影响填 充
android_adid string 否 Android AD ID
ios_adid string 是 ios 系统的 idfa。
idfv string 否 idfv
openudid string 否 openudid
local string 否 设备上的本地首选项设置
os_type string 是 操作系统类型, “ios”, “android”, “wp”(windows phone)
os_version string 是 操作系统版本
screen 对象 是 设备的屏幕信息
geo 对象 否 设备的位置信息

Screen对象信息

字段名称 类型 必须 描述
w int 是 水平分辨率,单位:像素
h int 是 纵向分辨率,单位:像素
dpi int 否 像素密度,单位:每英寸像素个数
pxratio float 否 屏幕物理像素密度,例:iPhone 3 为 1, iPhone 4 为 2, iPhone 6S plus 为 3

Geo对象信息

字段名称 类型 必须 描述
lat float 是 纬度
lon float 是 经度
accu int 否 精度

User对象信息

字段名称 类别 必须 描述
id string 否 用户id
gender int 否 性别,0:女 1：男 2：其他 3：未知
age int 否 年龄
keywords array 否 用户感兴趣的关键词

Native对象信息

字段名称 类型 必须 描述
layout int 是 原生广告类型,1: 内容墙, 2: 应用墙, 3:新闻流, 4:聊天列表,5:走马灯广告, 6:内容流,7:矩阵
assets Asset数组 是 原生广告元素列表,当前有 5 种元素,分别 为标题 (title), Icon(img), Large imag e (img), Description (data), Rating (data)

Asset对象信息

字段名称 类型 必须 描述
id int 是 广告元素id
required int 否 广告元素是否必须,1:必须,0:可选, 默认为 0
title 对象 否 文字元素
img 对象 否 图像元素
data 对象 否 其他数据元素

Warning

img,title,data 这三个元素，一个asset只能存在一个

Image对象信息

字段名称 类型 必须 描述
type int 是 image 元素的类型,1:图标,2:品牌 Logo, 3:大图
w int 否 image 元素的宽度,单位为像素, 当广告形式为 native 时,该值必填
h int 否 image 元素的高度,单位为像素, 当广告形式为 native 时,该值必填

Title对象信息

字段名称 类型 必须 描述
len int 是 title 元素最大文字长度

Data对象信息

字段名称 类型 必须 描述
type int 是 数据类型 1:Sponsor 名称,应该包含品牌 名称, 2:描述,3:打分, 4:点赞个数,5:下 载个数,6: 产品价格, 7:销售价格,往往和 前者结合,表示折扣价,8:电话, 9:地址, 10:描述 2, 11:显 示的链接, 12:行动按 钮名称,1001:视频 url,1002:评论数
len int 是 元素最大文字长度

Zplay对象信息

字段名称 类型 必须 描述
app_channel string 否 应用渠道 ID
uuid string 否 uuid
request_id string 否 request_id
preload int 否 插屏是否预加载 0 不预加载 插屏,1,预加 载
banner_interva l int 否 Banner 轮播时间,单位秒
intersect_inte rval int 否 插屏轮播时间,单位秒
splash_interva l int 否 开屏轮播时间,单位秒
is_close int 否 是否可关闭, 0:不可关闭, 1:可关闭
ad_loc_id string 否 广告位id
ios_idfv string 否 ios idfv
open_uuid string 否 open_uuid, 设备号

ADX返回信息

Response字段信息

字段名称 类型 必须 描述
result int 是 返回结果，0：成功，小于0表示失败
msg string 否 失败的话，内有失败原因,例：”网络错误”
ad 对象 否 如果失败,或者无对应广告则无此数据，下 面是ad的字段说明. 此字段为协议版本1.0 （包括）以下有效， 版本1.1（包括)以上 请使用ads
ads ad对象数 组 否 如果失败,或者无对应广告则无此数据
cur string 否 广告价格货币类型，默认为”CNY”

Ad对象信息

字段名称 类型 必须 描述
id string 是 广告id
place_id string 是 广告位id，与request中的place_id对应
action int 是 广告动作类型， 1: 在app内webview打开 目标链接， 2： 在系统浏览器打开目标链 接, 3：打开地图，4： 拨打电话，5：播 放视频, 6:App下载
html_snippet string 否 html广告代码
image_url string 否 图片地址
w int 是 广告宽度
h int 是 广告高度
app_bundle string 否 Android应用为包名，例：”com.zplay.dem o”；iOS应用为iTunes ID，例：”12345678 “，app推广广告需要
app_ver string 否 应用版本号
target_url string 否 目标地址
click_trackers array 否 当点击广告时，监控URL列表，应在后台访 问
imp_trackers array 否 当广告被展示时，监控URL列表，应在后台 访问
refresh_interv al int 是 广告应该在这个间隔后刷新，若为0则不刷 新
inventory_type int 是 广告资源类型, 1:图片，2:图文，3:视频 ，4:html5，5:文本， 6:原生, 7:html5 u rl, 即一个指向html5素材页面的url
title string 否 广告标题，图文广告时需要
desc string 否 广告描述，图文广告时需要
ssp_id string 是 ssp id, 当ssp api返回的广告时时具体的 ssp id值， 当时dsp返回的广告时，为自 主ADX的ssp id（10）
download_file_ name string 否 下载文件名，动作类型为下载类型时需要
file_size int 否 当广告为下载广告时，这是下载文件大小
price float 否 广告价格，若没有该数据则为0, 单位为分
ex_param []string 否 扩展参数
ssp_ad_id string 否 自主api返回的sspAdId
video 对象 否 视频对象
native 对象 否 原生广告对象

Video对象信息

字段名称 类型 必须 描述
url string 是 视频播放url
play_duration int 否 视频播放时长， 单位为秒
player_start_t rackers array 否 播放时上报url
player_end_tra ckers array 否 播放完成时上报url
target_page_sh ow_trackers array 否 目标页展示上报url，与imp_trackers效果 相同
target_page_cl ick_trackers array 否 目标页点击上报url，与click_trackers效 果相同

Zplay对象信息

字段名称 类型 必须 描述
app_id string 否 zplay ssp api返回的app id
position_sid string 否 zplay ssp api返回的position sid
app_secret string 否 zplay ssp api返回的app secret
trans_data string 否 zplay ssp api透传数据
deep_link_back up_url string 否 deeplink 链接访问失败时的备份链接

Native对象信息

字段名称 类型 必须 描述
assets Asset对象 数组 是

原生广告元素列表，当前主要支持5种元素 ，分别为标题 (title), 图标(img), 大图

(img), 描述 (data), 得分 (data)
imptracker 数组 否 展示跟踪地址数组，需要返回一个1像素图 片
link 对象 否 目标链接，默认链接对象，当assets中不 包括link对象时，使用此对象

Asset对象信息

字段名称 类型 必须 描述
id int 是 广告元素ID
required int 否 广告元素是否必须显示，1：必须，0：可 选， 默认为0
title 对象 否 文字元素
img 对象 否 图像元素
data 对象 否 其他数据元素
link 对象 否 点击目标链接

Image对象信息

字段名称 类型 必须 描述
url string 是 image url地址
w int 否 image元素的宽度，单位为像素
h int 否 image元素的宽度，单位为像素

Title对象信息

字段名称 类型 必须 描述
text string 是 标题文字

Data对象信息

字段名称 类型 必须 描述
label string 否 数据名称
value string 是 数据正文

上报地址宏替换信息

Note

客户端在触发上报信息时，需要将一些客户端的参数一起上报，通过替换下面的宏即可

宏变量 说明
YUMI_ADSERVICE_CLICK_DOWN_X 点击落下X坐标，客户端将改字符串替换为真实值即可
YUMI_ADSERVICE_CLICK_DOWN_Y 点击落下Y坐标，客户端将改字符串替换为真实值即可
YUMI_ADSERVICE_CLICK_UP_X 点击离开X坐标，客户端将改字符串替换为真实值即可
YUMI_ADSERVICE_CLICK_UP_Y 点击离开Y坐标，客户端将改字符串替换为真实值即可