使用条款
Mix-Mind系统公司（以下简称“Mix-Mind”）所有文档，接收者有保密义务。未经Mix-Mind书面许可，任何人或任何机构不得向第三方披露、泄露有关本文件的任何内容或细节。Mix-Mind拥有修改、调整、增补本文件的权利。Mix-Mind系统™和Mix-Mind Systems™及相关延展标识为Mix-Mind公司在中国和/或其他国家或地区的注册商标或商标。
| 版本/状态 | 作者 | 参与者 | 完成日期 | 备注 |
|---|---|---|---|---|
| 1.2.0 | 韦仕硕 | 2013-08-26 | 文档建立 | |
| 1.2.1 | 赵普明 | 2014-02-20 | 增加底价字段（fp） | |
| 1.2.2 | 赵普明 | 2014-02-24 | 增加流量来源字段 (od) | |
| 1.2.3 | 赵普明 | 2014-02-25 | 增加请求ID字段(reqid)，修改返回的JSON数据为支持多个广告的返回。 |
本文档描述媒体方Media通过Server-to-Server（S2S）方式连接AdExchange系统的通用接口。
--AdRequest-->
|Media| |AdExchange|
<--AdResponse--基本流程：
所有参数采用UTF-8编码
协议采用HTTP GET，开启keep-alive，请求参数放在URL参数里面， URL格式为http://[AdExchangeHOST]:[PORT]/bx?{PARAMS}。 一般情况下port不指定，默认80。
{PARAMS}参数是HTTP GET参数，用key1=value1&key2=value2的方式组合起来，详细参数说明见下表：
| 字段名称 | 描述 | 是否必须 | 样例 |
|---|---|---|---|
| ip | 请求来源ip，目前我们取一个ip，来自http headers，优先级为X-Forwarded-For > X-Real-IP > RemoteAddress，取第一个合法的ip，需要发送请求的server先获取ip | 是 | 127.0.0.1 |
| ua | 用户请求的User-Agent header，需要urlencode | 是 | Mozilla%2f5.0+(iPad%3b+U%3b+CPU+OS+3_2_1+like+Mac+OS+X%3b+en-us)+AppleWebKit%2f531.21.10+(KHTML%2c+like+Gecko)+Mobile%2f7B405 |
| uid | 用户id，如xtid等，需要urlencode | 是 | zzzzzzzzzzzz |
| l | 广告位id列表，用英文的逗号分隔(,)。注意，现在只支持一次请求返回同一个广告位ID的情况，出现多次表示这个请求需要返回多个广告素材，如l=13,13表示这个请求需要返回两个广告素材用于13号广告位的投放。 | 是 | 1,1 |
| v | 返回值类型，目前支持三种情况： 1）v=0为空或者0表示是RTB协议的Json返回类型； 2）v=1表示是Vast 3.0格式的返回类型 | 可选 | 1 |
| f | 用户请求的来源页面url，用于转发给dsp，需要urlencode | 可选 | http://ref.example.com |
| u | 广告所在页面url，用于进行域名验证和转发给dsp，需要urlencode | 对banner类型的广告且配置了验证的网站是必须的 | http://current.example.com |
| min | 视频广告最小时长，单位秒 | 可选，广告位也可以在网站上设置时长最小值 | 3 |
| max | 视频广告最大时长，单位秒 | 可选，广告位也可以在网站上设置时长最小值 | 5 |
| r | 版本号 | 是 | 目前都是1 |
| fp | 底价 | 可选，广告位底价在网站上设置，如果传入此字段，则使用传入的值作为本次请求的广告位底价 | 100 |
| od | 流量来源 | 可选，字段为0或者缺失时表示是Mix-Mind自己的流量；其他值时表示其他的流量。说明：od字段是为有特殊需要的媒体提供，Mix-MindAdExchange在返回广告的json格式上会有区别，目前支持的值od=0和od=1 | 0 |
| reqid | 请求ID，流量来源处自定义的ID，exchange会在响应中返还。说明：该字段对od=1的流量适用返还 | 可选 | |
| oaid | 安卓设备的OAID 明文 | 可选 | 47befdff-fb1f-4b96-ddff-bf3fb77f744e |
| oaidmd5 | 安卓设备的OAID MD5 | 可选 | e10adc3949ba59abbe56e057f20f883e |
说明：od字段和reqid字段是server-to-server提供的，媒体根据需要的返回json格式来确定是否提供该字段
通用Ad Request如下：
http://s.ad.xelements.cn/bx?ip=127.0.0.1&ua= Mozilla%2f5.0+(iPad%3b+U%3b+CPU+OS+3_2_1+like+Mac+OS+X%3b+en-us)+AppleWebKit%2f531.21.10+(KHTML%2c+like+Gecko)+Mobile%2f7B405&uid=zzzzzzzzzzzz&l=1&v=1&f=http://ref.example.com&u=http://current.example.com&r=1添加流量来源od字段Ad Request如下：
http://s.ad.xelements.cn/bx?ip=127.0.0.1&ua= Mozilla%2f5.0+(iPad%3b+U%3b+CPU+OS+3_2_1+like+Mac+OS+X%3b+en-us)+AppleWebKit%2f531.21.10+(KHTML%2c+like+Gecko)+Mobile%2f7B405&uid=zzzzzzzzzzzz&l=1&v=1&f=http://ref.example.com&u=http://current.example.com&r=1&od=1&reqid=123正常响应包的返回状态码为HTTP 200 ok。其他情况会当做出错处理，如403 forbidden或500 internal server error。响应的格式目前支持json以及vast 3.0.
2.2.1.1 当请求参数中v=0或者v字段不存在 并且 od=0或od字段不存在的时候，返回JSON格式的响应，具体字段如下：
{
"pid": "100", // 广告位ID (placement id)
"etype": "V", // 展示类型
"type": "V", // 物料类型
"src": "http://example.com/sample.flv", // 物料URL
"adw": 450, // 广告位宽度
"adh": 300, // 广告位高度
"pm": { // 曝光监测地址，结构是 "发送时间" -> [监测地址]
"0": [ // 一般都是希望指定第0秒，即开始播放的同时发送监测请求，该字段是数组，可以发送第三方监测
"http://example.com/monitor.gif?a=1&b=2",
"http://third-party.com/monitor.gif?a=1&b=2"
],
"15": [
"http://example.com/monitor..."
]
},
"cm": [ // 点击监测地址，当广告被点击时应当额外触发对这个数组中的URL的请求，以便监测点击事件。该字段是数组，希望支持多个点击监测地址。
"http://example.com/click.gif?a=1&b=2",
"http://third-party.com/monitor.gif?a=1&b=2"
],
"ldp":"http://brand-landing-page.com/", // 点击落地页，一般是广告主的网站或者电商购买页。
"meta": { // 其他信息
"check":1
"duration": 15 // 广告物料的播放时长(视频类型)
}
}当AdExchange没有合适的广告可以返回的时候，会返回src为空的json数据，通知媒体此次响应为空，请转投其他来源的广告。
NOTE:
如果竞价成功，返回的json中src一定不为空
如果竞价失败但该广告位设置了默认物料，返回的json中src为默认物料URL
如果竞价失败且该广告位没有设置默认物料，则返回的json中src为空2.2.1.2 当请求参数中v=0或者v字段不存在并且od=1的时候，返回JSON格式的响应，具体字段如下：
{
"ad": [ // 广告素材，数组形式
{
"pid": "100", // 广告位ID (placement id)
"etype": "V", // 展示类型
"type": "V", // 物料类型
"src": "http://example.com/sample.flv", // 物料URL
"adw": 450, // 广告位宽度
"adh": 300, // 广告位高度
"pm": { // 曝光监测地址，结构是 "发送时间" -> [监测地址]
"0": [ // 一般都是希望指定第0秒，即开始播放的同时发送监测请求，该字段是数组，可以发送第三方监测
"http://example.com/monitor.gif?a=1&b=2",
"http://third-party.com/monitor.gif?a=1&b=2"
],
"15": [
"http://example.com/monitor..."
]
},
"cm": [ // 点击监测地址，当广告被点击时应当额外触发对这个数组中的URL的请求，以便监测点击事件。该字段是数组，希望支持多个点击监测地址。
"http://example.com/click.gif?a=1&b=2",
"http://third-party.com/monitor.gif?a=1&b=2"
],
"ldp":"http://brand-landing-page.com/", // 点击落地页，一般是广告主的网站或者电商购买页。
"meta": { // 其他信息
"duration": 15 // 广告物料的播放时长(视频类型)
}
}
],
"version":"1", // 数据协议版本号
"pt":200, // AdExchange系统内部处理花费的时间
"reqid":"1234" // 请求中带的表示本次请求的唯一ID，AdExchange返回该ID方便媒体方记录日志
}当AdExchange没有合适的广告可以返回的时候，会返回如下格式的数据，通知媒体此次响应为空，请转投其他来源的广告：
{
"version":"1",
"pt":200,
"reqid":"1234"
}上述字段的详细解释如下表所示：
| 字段名称 | 类型及范围 | 说明 |
|---|---|---|
| ad | Array | 返回的广告信息，具体参加下面ad对象的组成和含义列表。 |
| version | String | 版本号 |
| pt | Number | 服务器处理时间，单位ms |
| reqid | String | 请求ID，由媒体来源方给定，用来标定一次请求，系统会原样返回 |
ad字段的详细解释如下：
| 字段名称 | 类型及范围 | 说明 |
|---|---|---|
| pid | String | 广告位id，即Mix-Mind分配给媒体的合作广告位的唯一标识 |
| etype | String | 物料展示类型，在嵌入式视频广告的Ad Response中，此字段的值为“V”。Banner："N"。动态物料："C" |
| type | String | 物料类型，“I”表示图片物料，“F”表示swf Flash物料，“V”表示视频物料，“X”表示多点击地址Flash物料（多点击地址Flash物料是已嵌入Click监测代码的物料） |
| src | String | 物料URL |
| adw | Number | 广告位宽 |
| adh | Number | 广告位高 |
| ldp | String | 情况1. Landing page（直接打开页面，click监测由"cm"值通过程序发出） eg. http://www.cnn.com; 情况2. ClickTrackingUrl with landing page(302跳转方式) eg.http://e.cn.xelements.cn/r.gif?&bc=90_14030_1355798855_1&k=1003043&p=3xxL60&ro=sm&rt=2&o=http://www.braun.com/cn/home.html。注：客户端对ldp的处理在这两个情形下都是一样的，直接跳转到ldp指向的地址就行。 |
| cm | Array | clickTrackingUrl Array 对于"ldp"参数说明的情况1，该值为包含点击监测地址的数组 eg. ["url1", "url2", …]. 对于"ldp"参数说明的情况2，该值为空数组 |
| pm | Object | key为发送曝光监测时机（秒），value为pvTrackingUrl Array; eg. {"0":["url1","url2",…], "10":["urlA","urlB",…]} |
| debug | String | 投放debug日志 |
| meta | Object | 其他信息，参见下表的详细解释 |
说明：
1.ldp不管是带302跳转方式的地址, 还是直接是最终跳转页，媒体客户端处理是一样的，直接跳转到ldp指向的地址
2.只要cm数组不为空，媒体客户端就需要支持点击监测的发送并且会有多个点击监测的情况。meta字段的内容解释:
| 字段名称 | 类型及范围 | 说明 |
|---|---|---|
| check | Number | 是否检查时长 |
| duration | Number | 物料时长 |
当请求的参数v=1时，AdExchange系统返回的是VAST格式的数据。 数据格式遵循VAST v3.0版本。AdExchange返回的是VAST的一个子集，返回的全部字段都包含在下面的示例中。
注： 关于VAST格式的详细说明，参看
正常的广告返回示例如下：
<?xml version="1.0" encoding="UTF-8"?>
<VAST version="3.0">
<Ad>
<InLine>
<AdSystem>Mix-Mind AdExchange</AdSystem>
<AdTitle>title</AdTitle>
<Creatives>
<Creative>
<Linear>
<!-- 广告时长 -->
<Duration>00:00:30</Duration>
<MediaFiles>
<!-- 物料信息，MIME type，宽，高 -->
<MediaFile delivery="progressive" type="video/x-flv" width="200" height="400">
<!-- 物料地址 -->
<![CDATA[
http://i.stfile.com/aaaa.flv
]]>
</MediaFile>
</MediaFiles>
<TrackingEvents>
<!-- 曝光监测URL -->
<!—注意：具体何时发送曝光监测请求需要Mix-Mind、媒体、广告主三方协商确定，此处 start 表示在广告播放开始的时候发送监测请求 -->
<Tracking event="start">
<!-- 监测地址将包装到CDATA里面 需要支持多个曝光Tracking发送 -->
<![CDATA[
http://g.x.cn.xelements.cn/x.gif?....
]]>
</Tracking>
<Tracking event="start">
<!-- 第三方曝光监测 -->
<![CDATA[
http://g.cn.xelements.cn/x.gif?....
]]>
</Tracking>
<Tracking event="start">
<!-- dsp曝光监测 -->
<![CDATA[
http://dsp.xxx.com/x.gif?....
]]>
</Tracking>
</TrackingEvents>
<!-- 点击事件 -->
<VideoClicks>
<!-- ClickThrough 设置，跳转到Landing Page设置 -->
<ClickThrough>
<!-- 监测+跳转地址将包装到CDATA里面 -->
<![CDATA[
http://e.cn.xelements.cn/r.gif?....
]]>
</ClickThrough>
<!-- ClickTracking 设置，发送Mix-Mind、广告主、媒体第三方点击监测请求 需要支持多个点击监测ClickTracking发送 -->
<ClickTracking>
<!-- 点击监测地址将包装到CDATA里面 dsp监测地址 -->
<![CDATA[
http://www.dsp.com/r.gif?...
]]>
</ClickTracking>
<ClickTracking>
<!-- 点击监测地址将包装到CDATA里面 第三方监测地址-->
<![CDATA[
http://www.disanfang.com/r.gif?...
]]>
</ClickTracking>
</VideoClicks>
</Linear>
</Creative>
</Creatives>
</InLine>
</Ad>
</VAST>当没有合适的物料返回时，AdResponse内容为：
<VAST version="3.0"></VAST>为了方便媒体Server监测AdExchange的服务器状况，AdExchange提供一个心跳接口，URL为格式为http://[AdExchange-HOST]:[PORT]/heartbeat，响应status为200，支持Keep-Alive，内容为空。
