使用条款

“阿里妈妈全域媒体”所有文档,接收者有保密义务。未经“阿里妈妈全域媒体”书面许可,任何人或任何机构不得向第三方披露、泄露有关本文件的任何内容或细节。“阿里妈妈全域媒体”拥有修改、调整、增补本文件的权利。

目录

RTB对接说明文档

版本历史

版本/状态 作者 参与者 完成日期 备注
1.3.0.1 杨子利 2016-01-14 bidRequest新增参数:device.idfa、device.androidid、device.imei、device.mac、device.make、
device.model、device.connectiontype、device.carrier、device.screenwidth、device.screenhight、
banner.pos、video.startdelay;修改参数:video.linearity
1.3.0.2 杨子利 2016-04-11 新增广告主信息上传接口;新增获取广告主信息接口
1.3.0.3 董庆明 2016-05-16 请求新增deal 价格;返回新增播放完成曝光监测em
1.3.0.4 杨子利 2016-06-27 返回新增指定时间点曝光监测tm
1.3.0.5 杨子利 2016-08-04 上传素材前需先上传广告主
1.3.0.6 杨子利 2016-08-16 广告主信息新增address,contacts,tel三个字段,且营业执照资质文件为必填
1.3.0.7 杨子利 2016-09-21 新增开机图广告位linearity=5
1.3.1.0 2016-10-26 新增信息流广告规则
1.3.2.0 潘英学 2018-06-29 实时接口:信息流增加video节点,下载增加apk节点
1.3.3.0 歆琦 2019-02-21 修正歧义描述与常见问题Q&A
1.3.4.0 歆琦 2019-06-19 修改android设备id下发规则,原文字段废弃,增加md5值
1.3.5.0 歆琦 2019-07-24 素材送审和竞价接口升级,主要针对PDB部分,素材送审增加deal信息,RTB竞价接口去掉了orderid,同时补充了完整性校验规则。
1.3.6.0 歆琦 2019-11-27 1,修复PD请求没有下发底价问题;2,增加Android Q版本OAID字段;
1.3.6.1 歆琦 2020-05-28 1,修正PDB一些错误描述;2,开放Deeplink支持,增加Universallink字段;3,增加App包名和bundleid字段(未上线);
1.3.7 lushi 2021-03-02 请求参数device节点下发caid、aaid

一、总述

ADX提供了两组API供DSP使用:

信息同步API:用于DSP和ADX之间互相同步将会用于竞价过程的各种信息。包括:广告主信息,素材信息,素材审核状态等。

实时竞价API:ADX用来向DSP发送实时竞价请求,并获取竞价结果的接口。PS : DSP需要提前和商务或运营同学获取ADX提供的dspid和token信息

API参数编码

所有参数采用UTF-8编码

二、信息同步API接口

信息同步API包括7个接口:

  1. 广告位信息获取API:获取ADX系统中各个广告位的信息。
  2. 广告主信息上传API:用于上传广告主信息到ADX系统,进行人工审核
  3. 获取广告主信息API:制定广告主名称,获取广告主及其所属资质信息
  4. 素材信息上传API:用于DSP上传素材到ADX系统,进行人工审核,素材通过人工审核后,才可以成功参与竞价。
  5. 获取指定素材的审核结果API: 指定素材列表,获取各个素材的审核结果。
  6. 获取素材的拒绝原因API: 指定上传日期,获取之后上传的素材中,被拒绝的素材的拒绝原因。
  7. 报表获取API:获取DSP日报,包括概览报表和详细报表两类。其中概览报表是DSP当日整体的统计;详细报表精确到广告位粒度。
  8. 广告主和行业获取API:获取ADX系统中的广告主以及广告主对应的行业

请求域名

RTB:api.yes.youku.com

PDB:adx.alimama.com

文档后续都使用{youku.adx.domain}代替,DSP开发请自行替换。

请求格式

以上各个API,请求参数为JSON格式,均通过HTTP POST发送:

注意

1. 为了符合标准,请求头中必须设置"Content-Type: application/json",以及"Host:{youku.adx.domain}",否则服务器拒绝解析。

2. 所有请求的JSON Body中都需要包含安全参数,用于进行权限验证。

参数名称 类型 是否必须 含义
dspid string DSP在ADX系统中的ID,用来标识使用API的是哪个DSP
token string DSP对应的token值,用来进行权限验证

这两个参数值可以在对接之前,和“阿里妈妈全域媒体”商务/运营/产品同学沟通获取

注:业务参数将在下面的每个接口分别进行说明,系统参数和业务参数组成的对象对应的JSON,作为请求的参数。

所有的API请求的Body都如下面的格式:

{
  "dspid":"11268", // DSP ID
  "token":"92205dff8f9d48e1b7a26b0b88af7dc1", // DSP Token
  ... // 其他业务参数,将在下面各节API详细介绍中说明
}

响应格式

API以JSON格式返回,返回信息是由如下的参数组成的对象对应的JSON数据:

参数名称 是否必须 含义
result 0:执行成功 1:系统认证失败 2:请求参数错误 3:其他错误
message 提示信息

1. 广告位信息获取API

说明:

DSP通过该接口获得Exchange拥有的库存信息,包括广告位总量,每个广告位的ID、名称、尺寸、底价、广告主行业黑名单以及支持的素材格式(暂时支持gif、jpg、png、swf、flv等几种格式)

API地址:POST http://{youku.adx.domain}/dsp/api/adplacements

业务参数:

返回信息:

参数名称 类型 含义
result int 0:接口执行成功。也包括执行成功,但内含业务错误的情况;
1:系统认证失败;
2:请求参数错误;
3:其他错误
message object或者string 若result为0,message类型为object,表示操作成功;
若result为1,message类型为string,表示系统认证失败;
若result为2,message类型为string,表示请求参数错误;
若result为3,message类型为object({"errno":["err_str","err_str"], "errno":["err_str","err_str"]})

请求示例:

\\ POST 'http://{youku.adx.domain}/dsp/api/adplacements'
\\ JSON:
{"dspid":"11268","token":"92205dff8f9d48e1b7a26b0b88af7dc1"}

curl示例:

curl -H 'content-type:application/json' -d '{"dspid":"11121", "token":"ca8d0a0f59ee4302a6c3b5e41052e43b"}' 'http://api.sandbox.yes.youku.com/dsp/api/adplacements'

广告位信息API的正常返回示例:

{
    "result":0,
    "message":
    {
        "total" :2, // 总数
        "count" :2,  // 本次返回数,这个字段是预设的未来可以分页读取的参数,现在都和total相等
        "records" : [{  // 广告位数组
            "adplacementid": 101,  // 广告位ID, integer类型
            "adplacementname": "汽车-首页-banner" ,  // 名称
            "size": "300*250" ,  // 尺寸,"width*height"
            "bidfloor": 20 ,     // 广告位底价,单位是:分/CPM
            "blockcategory": ["1", "2"] , // 广告主行业黑名单,这里的值是黑名单行业的行业ID,具体行业映射表见字典文件<http://api.yes.youku.com/dicts/industry.txt>
            "allowmaterial": ["jpg", "gif", "swf", "png"]  // 允许的素材类型,内容是后缀名。注意,“优酷”视频贴片素材在这里是用flv代表的
            "bidfloor": 300,                    //广告位低价,单位:分/CPM
            "native_template_ids": []    //信息流广告位模板ID
            "openType": "banner"    //广告类型(banner/video/native)
        },{
            "adplacementid": 101,  // 广告位ID, integer类型
            "adplacementname": "汽车-首页-banner" ,  // 名称
            "size": "0*0" ,  // 尺寸,"width*height"
            "bidfloor": 20 ,     // 广告位底价,单位是:分/CPM
            "blockcategory": ["1", "2"] , // 广告主行业黑名单,这里的值是黑名单行业的行业ID,具体行业映射表见字典文件<http://api.yes.youku.com/dicts/industry.txt>
            "allowmaterial": []  // 允许的素材类型,内容是后缀名。注意,“阿里妈妈全域媒体”视频贴片素材在这里是用flv代表的
            "bidfloor": 300,                    //广告位低价,单位:分/CPM
            "native_template_ids": ["1001", "1002"]    //信息流广告位模板ID
            "openType": "native"    //广告类型(banner/video/native)
        },{
        }]
    }
}

2. 广告主信息上传API(仅RTB)

说明:

ADX需要对DSP将要下的的广告主资质进行审核,如果审核不通过,将不会允许在ADX上进行交易。DSP通过该接口向ADX提交需要审核的广告主信息,包括广告主名称,品牌名称,统计行业,资质信息等。

API地址:POST http://{youku.adx.domain}/dsp/api/uploadadvertiser

业务参数:

字段名称 类型 必填 描述
type String Y 广告主业务所属类型(枚举值:PDB、RTB。默认值RTB)
advertiser object Y 广告主信息

advertiser对象元素说明

字段名称 类型 必填 描述
name string Y 广告主名称(如:合一网络技术有限公司)
brand string Y 品牌名称(如:“阿里妈妈全域媒体”土豆)
address string Y 广告主公司地址(北京市海淀区中关村大街8号中国大厦22层) 2016年09月01日版本升级后生效
contacts string Y 广告主联系人(最多30个字符-张三) 2016年09月01日版本升级后生效
tel string Y 广告主联系电话(最多20个数字-18699998888/010-87432387) 2016年09月01日版本升级后生效
firstindustry number(int) Y 一级统计行业
secondindustry number(int) Y 二级统计行业
qualifications array of objects Y 本次同步需要新增或者修改的素材信息,是JSON格式的数据。具体参见下面的qualifications对象说明,每次最多上传50个资质 营业执照资质必填 2016年09月01日版本升级后生效

qualifications数组每个元素的对象说明

字段名称 类型 必填 描述
name string Y 资质证书名称(全名)
url string Y 资质文件的URL地址,由DSP提供可访问的资质文件URL地址(注意:只支持http协议,不支持https协议)
md5 string Y 资质文件内容的MD5值,即对图片二进制内容求md5值,MD5值采用32位小写格式
operation string Y 针对资质文件的操作(add/update/delete)

新增的address、contacts、tel、营业执照必填项采用7天内完成上传,7天后未补充的以上信息的广告主将禁止参与RTB竞价,"营业执照"四个字为严格匹配

operation字段使用说明:

请求示例:

\\ POST 'http://{youku.adx.domain}/dsp/api/uploadadvertiser'
\\ JSON:
{
    "dspid":"11268",
        "token":"92205dff8f9d48e1b7a26b0b88af7dc1",
        "advertiser":{
            "name":"合一网络技术有限公司",
            "brand":"优酷”“土豆",
            "address":"北京市海淀区中关村大街8号中国大厦22层",
            "contacts":"张三",
            "tel":"18699998888",
            "firstindustry":3,
             "secondindustry":5,
             "qualifications":[{
                 "name": "营业执照",    // 必须填写
                 "url": "http://material.client.com/123.jpg", // 资质文件的URL地址
                 "md5": "38b8c2c1093dd0fec383a9d9ac940515",
                 "operation": "add"
             },{
                 "name": "网络文化经营许可证",    // 必须填写
                 "url": "http://material.client.com/456.jpg", // 资质文件的URL地址
                 "md5": "38b8c2c1093dd0fec383a9d9ac940sdf",
                 "operation": "add"
             }]
        }
}

curl示例

curl -i -H 'content-type:application/json' -d '{"dspid":"11121", "token":"ca8d0a0f59ee4302a6c3b5e41052e43b", "advertiser":{"name":"合一网络技术股份有限公司", "brand":"优酷土豆", "address":"北京市海淀区中关村大街8号中国大厦22层", "contacts":"张三", "tel":"18699998888", "firstindustry":1, "secondindustry":3, "qualifications":[{"name":"“优酷”", "url":"http://dsp.youku.com/banner_01.jpg", "md5":"653c3891f16c4fc1ad86ea4510ee039e", "option":"add"}, {"name":"土豆", "url":"http://dsp.tudou.com/banner_02.jpg", "md5":"9531f03720547ce3e6e67e0e45cd29d9", "operation":"add"}]}}' "http://api.sandbox.yes.youku.com/dsp/api/uploadadvertiser"

返回信息:

参数名称 类型 含义
result int 0:执行成功 1:系统认证失败 2:请求参数错误 3:其他错误
message string或object 若result为0,message类型为object,表示操作成功;
若result为1,message类型为string,表示系统认证失败;
若result为2,message类型为string,表示请求参数错误;
若result为3,message类型为object({"errno":["err_str","err_str"], "errno":["err_str","err_str"]})

message字段说明

{
    "result":0, //成功
    "message": {}
}
{
    "result":1, //DSP认证失败
    "message":"认证失败"
}
{
    "result":2, //请求参数错误
    "message":"json格式错误",
}
{
    "result":3, //其他错误
    "message"{"119":["营业执照 is exist","网络文化经营许可证 is exist"]},
}

3. 获取广告主信息API

说明:DSP通过该API获取ADX对请求中指定广告主的相关信息

API地址:POST http://{youku.adx.domain}/dsp/api/getadvertiser

业务参数:

字段名称 类型 必填 描述
advertiser string Y 广告主名称

请求示例:

{
    "dspid":"11268",
    "token":"92205dff8f9d48e1b7a26b0b88af7dc1",
    "advertiser":"合一网络"
}

curl示例

curl -i -H 'content-type:application/json' -d '{"dspid":"11121", "token":"ca8d0a0f59ee4302a6c3b5e41052e43b", "advertiser":"合一网络技术股份有限公司"}' "http://api.sandbox.yes.youku.com/dsp/api/getadvertiser"

返回信息:

参数名称 类型 含义
result int 0:执行成功 1:系统认证失败 2:请求参数错误 3:其他错误
message object或string 若result为0,message类型为object,表示操作成功;
若result为1,message类型为string,表示系统认证失败;
若result为2,message类型为string,表示请求参数错误;
若result为3,message类型为object({"errno":["err_str","err_str"], "errno":["err_str","err_str"]})

message object说明

参数名称 类型 含义
name string 广告主名称
brand string 广告主品牌
firstindustry number(int) 一级统计行业
secondindustry number(int) 二级统计行业
address string 广告主公司地址(北京市海淀区中关村大街8号中国大厦22层) 2016年09月01日版本升级后生效
contacts string 广告主联系人(最多30个字符-张三) 2016年09月01日版本升级后生效
tel string 广告主联系电话(最多20个数字-18699998888/010-87432387) 2016年09月01日版本升级后生效
state string 广告主状态(待审核、通过、拒绝)
refusetype string 广告主拒绝类型,1:需补充资质,2:广告主禁止投放
refusereason string 广告主被拒原因, 在state为拒绝的情况下才会传递拒绝原因
industryid number(int) 如果该广告主针对某一行业有些才会传递该字段(由运营手动审核后标记广告主投放的行业)
qualifications objects 广告主下的资质信息,如有则传递该字段,如无则不传递该字段

qualifications object 说明

参数名称 类型 含义
name string 资质文件名称(全名)
md5 string 资质文件内容的MD5值
url string 通过DSP提供的URL拉取到“阿里妈妈全域媒体”CDN的访问地址

错误码

请求示例:

{
    "result":0
        "message":{
            "name": "合一网络技术有限公司",
                "brand": "“阿里妈妈全域媒体”土豆",
                "address":"北京市海淀区中关村大街8号中国大厦22层",
                "contacts":"张三",
                "tel":"18699998888",
                "firstindustry":3,
                "secondindustry":5,
                "state":"通过",
                "refusereason":"广告主非法", //在state为拒绝的情况下才会传递拒绝原因
                "industryid":12, //如果该广告主针对某一行业有些才会传递该字段(由运营手动审核后标记广告主投放的行业)
                "qualifications"[{
                    "name":"广告主资质名称",
                    "md5":"38b8c2c1093dd0fec383a9d9ac940515",
                    "url":"http://r1.ykimg.com/material/0A05/qualification/2077/4aa90305b8dc24c86e3b40a983664f1e.jpg" //通过DSP提供的URL拉取到CDN的访问地址
                },{
                    "name":"广告主资质名称",
                    "md5":"38b8c2c1093dd0fec383a9d9ac940515",
                    "url":"http://r1.ykimg.com/material/0A05/qualification/2077/4aa90305b8dc24c86e3b40a983664f1e.jpg" //通过DSP提供的URL拉取到CDN的访问地址
                }]
        }
}

4. 素材信息上传API

说明:

ADX需要对DSP将要投放的素材进行审核,如果审核不通过,将不会允许在ADX上进行交易。DSP通过该接口向ADX提交需要审核的素材信息,包括素材URL、落地页URL、广告主名称、监测代码等。

注意

1) 贴片视频素材除了调用该API通知ADX进行审核,还需要预先上传到“优酷”视频系统才能使用。具体参见附录H. “优酷”贴片素材上传附加说明

2) PDB和RTB有一些差异,PDB所有资源类型以material.creative字段提交;RTB静态资源以material字段提交,原生资源以native字段提交;

API地址:POST http://{youku.adx.domain}/dsp/api/upload

业务参数:

字段名称 类型 必填 描述
type String Y 广告主业务所属类型(枚举值:PDB、RTB。默认值RTB)
material array of objects N 本次同步需要新增或者修改的素材信息,单次最大上传素材数小于50个。对应RTB资源类型:banner,暂停,贴片,角标。对应PDB资源类型:“优酷”&“UC”全部资源;
native array of objects N 本次同步需要新增或者修改的原生素材信息,单次最大上传创意数小于50个。对应RTB资源类型:信息流,焦点图。对应PDB资源类型:无(PDB素材送审全部使用material下的creative字段);

material数组每个元素的对象说明

字段名称 类型 必填 描述
crid string Y DSP创意ID, 保证DSP层级下的唯一性,作为竞价时的唯一创意ID
url string N RTB投放送审的素材URL地址,ADX会根据该地址获取实际素材用于审核,支持资源类型包括:贴片,暂停,角标,banner,开机图(信息流,焦点图等使用native字段)
creative object N PDB投放送审素材内容(与URL字段互斥)
landingpage string Y 点击跳转落地页的地址
deeplink string Y Deeplink点击跳转落地页的地址
advertiser string Y 广告主名称;ADX系统通过广告主名称进行区分。该名称用于广告主行业黑名单过滤功能,具体参见行业黑名单过滤说明。PDB可不填,最终广告主以deal对应的广告主信息一致。
startdate string Y 素材生效日期,格式要求:YYYY-mm-dd,必须填写。生效日期之前,该素材当做审核未通过处理。
enddate string Y 素材失效时间,格式要求:YYYY-mm-dd,必须填写。
注意: 到达失效日期以后,素材即使审核通过,也会被当做未通过来处理(当前校验失败原因里没有区分是因为人工审核没通过还是因为到达失效日期。
monitor array of string N 曝光监测地址:非必填。PDB投放需要注意,优酷对支持的监测有白名单约束,具体规则需要和PDB的运营和商务确认。RTB投放该字段暂时无效。
tmonitor array of object N 播中监测地址:非必填。
emonitor array of string N 播放结束监测地址:非必填。
cmonitor array of string N 点击监测地址:非必填。PDB投放需要注意,优酷对支持的监测有白名单约束,具体规则需要和PDB的运营和商务确认。RTB投放该字段暂时无效。
ldptype integer N 0:普通链接;1:iOS下载地址;2:安卓apk下载地址。3:deeplink跳转(dp参数必须返回);4:universallink跳转(仅IOS支持),universallink地址对应landingpage参数。注:目前仅支持淘宝换端,dp的白名单规则为:tbopen://m.taobao.com开头,Uniervallink以https://b.mashort.cn开头。返回其他默认为0
orderid array of int N PDB订单ID列表
dealid array of string N PDB Deal ID列表,PDB投放为必填

tmonitor Object

字段名 类型 必填 描述
t integer Y 在播放器触发检测链接url的时间点,单位为秒。
url string Y 展示监测链接,在指定时间点t发送,包括投放引擎、客户与第三方监测链接。

creative对象说明(PDB专用)

字段名 类型 必填 描述
attr_name string Y 创意属性名,见附录 material.creative.attr_name Enum详解
attr_value string Y 创意属性值,URL 地址或文本内容
width integer Y 素材宽度(单位px)
height integer Y 素材高度(单位px)
md5 string Y 素材文件的 MD5 值或文本内容的 MD5 值
ext string Y 素材文件的扩展名或文本类型(txt)

Native数组对象说明

字段名 类型 必填 描述
native_template_ids array of string Y 信息流模板ID列表,该值作为DSP创意推荐的投放模板ID,不作为投放引擎过滤条件使用
crid string Y DSP创意ID, 保证DSP层级下的唯一性,作为竞价时的唯一创意ID
title string N 广告Title,根据模板样式定义选填该字段
image_url string N 广告素材URL,根据模板样式定义选填该字段
video_url string N 广告视频素材URL,根据模板样式定义选填该字段
logo_url string N 广告LOGO素材地址,根据模板样式定义选填该字段
brand string N 广告品牌名称,根据模板样式定义选填该字段
advertiser string Y 广告主名称
startdate string Y 创意生效日期,格式YYYY-mm-dd
enddate string Y 创意失效日期,格式YYYY-mm-dd
landingpage string Y 广告落地页
monitor array of string N 曝光监测地址:非必填。这个只是做审核备注用,实际的DSP曝光监测地址或者第三方监测地址需要在RTB实时接口中的BidResponse里返回,具体参见RTB实时接口。
注意: 当前版本的系统因为实现原因,该字段不能完全不填,如果没有该字段,请暂时使用 "monitor": []空数组表示
ldptype integer N 0:普通链接;1:iOS下载地址;2:安卓apk下载地址。3:deeplink跳转(dp参数必须返回);4:universallink跳转(仅IOS支持),universallink地址对应landingpage参数。注:目前仅支持淘宝换端,dp的白名单规则为:tbopen://m.taobao.com开头,Uniervallink以https://b.mashort.cn开头。返回其他默认为0

请求示例:

\\ POST 'http://{youku.adx.domain}/dsp/api/upload'
\\ JSON:
{
    "dspid":"11268",
    "token":"92205dff8f9d48e1b7a26b0b88af7dc1",
    "material":
    [
    // RTB material素材提交
    {
        "crid":"dsp_crid_11101",
        "url": "https://v.youku.com/v_show/id_XMzc1NDUxNjUwMA==.html", // 素材的URL地址
        "landingpage": "http://www.some.com", // 点击跳转落地页的地址
        "advertiser": "广告主的名称",    // 必须填写
        "startdate":"2012-07-16",    //素材生效时间,格式要求:YYYY-mm-dd,必须填写
        "enddate":"2012-08-30",     //素材失效时间,格式要求:YYYY-mm-dd,必须填写
        "monitor": [], // 曝光监测地址:非必填
    },
    // PDB 素材提交
    {
        "crid":"dsp_crid_11102",
        "creative": [ {
        	"attr_name":"video",
        	"attr_value": "https://v.youku.com/v_show/id_XMzc1NDUxNjUwMA==.html",
        	"md5": "a5d69636cbf7c899647d4484df04bb78",
        	"ext": "mp4"
        	},{
        	"attr_name":"image",
        	"attr_value": "http://creative.jdkic.com/img/6e4e281843f3
4d3a84533374112b6e0c.jpg",
        	"md5": "70098db4b6ad6036e85d20e9d715e2a7",
        	"ext": "jpg"
        	},{
        	"attr_name":"logo_title",
        	"attr_value": "三国2"
        	},
        ],
        "landingpage": "http://www.some.com",
        "advertiser": "广告主的名称",
        "startdate":"2012-07-16",
        "enddate":"2012-08-30",
        "monitor": ["http://miaozhen.com/1", "http://miaozhen.com/2"]
    }],
    // RTB native素材提交
    "native":[{
        "native_template_ids":["100"],
        "crid":"dsp_crid_11001",
        "title":"美丽中国",
        "image_url":"http://cdn.youku.com/beautifulchina.jpg",
        "advertiser":"广告主名称",
        "startdate":"2012-08-16",
        "enddate":"2013-08-16",
        "landingpage":"http://yes.youku.com",
        "monitor": ["http://miaozhen.com/1", "http://miaozhen.com/2"]
    }]
}

curl实例:

curl -H "Content-Type:application/json" -d '{"dspid":"11121","token":"dcc5424ad4854294bcbc03dc6c4f0959","material":[{"url":"http://v.youku.com/v_show/id_XOTIzNjgwNDQ0.html","landingpage":"http://www.some.com","advertiser":"zhaocan","startdate":"2012-07-16","enddate":"2015-08-30","monitor":[]}]}' 'http://api.sandbox.yes.youku.com/dsp/api/upload'

返回信息:

参数名称 类型 含义
result int 0:执行成功 1:系统认证失败 2:请求参数错误 3:其他错误
message object或string 若result为0,message类型为object,表示操作成功;
若result为1,message类型为string,表示系统认证失败;
若result为2,message类型为string,表示请求参数错误;
若result为3,message类型为object({"errno":["err_str","err_str"], "errno":["err_str","err_str"]})

如果全部素材上传成功,则message对象为空,即接口返回:

{
    "result":0,
    "message": {} // message对象为空,所有素材均成功上传
}

如果有素材没有成功上传,则message对象是一个key-value映射,key值为具体错误码,value值是一个数组,表示当前API调用中有哪些素材符合key值表示的错误码。

示例如下:

{
    "result":3,
    "message":
    {
        "102":["http://material.client.com/123.abc"], // Error 102: 不支持的素材格式
        "103":["http://material.client.com/134.jpg"]  // Error 103: 无法获取素材的尺寸信息
        "103":["dsp_crid_11001"]  // Error 103: 无法获取素材的尺寸信息
    }
}

素材上传错误码说明: 错误码

5. 获取指定素材的审核结果API

说明:DSP通过该API获取ADX对请求中指定的素材审核的结果

API地址:POST http://{youku.adx.domain}/dsp/api/status

业务参数:

字段名称 类型 描述
type String 广告主业务所属类型(枚举值:PDB、RTB。默认值RTB)
materialurl array of string 需要查询的一个或多个素材的URL
crid array of string 需要查询的一个或多个创意的ID

返回信息:

参数名称 类型 含义
result int 0:执行成功 1:系统认证失败 2:请求参数错误 3:其他错误
message object或者string 若result为0,message类型为object,表示操作成功;
若result为1,message类型为string,表示系统认证失败;
若result为2,message类型为string,表示请求参数错误;
若result为3,message类型为object({"errno":["err_str","err_str"], "errno":["err_str","err_str"]})

请求示例:

\\ POST 'http://{youku.adx.domain}/dsp/api/status'
\\ JSON:
{
    "dspid":"11268",
    "token":"92205dff8f9d48e1b7a26b0b88af7dc1",
    "materialurl":["http://material.client.com/134.swf","http://material.client.com/135.swf","http://material.client.com/136.swf"]
    "crid":["dsp_crid_11001","dsp_crid_11002","dsp_crid_11003"]
}

curl示例

curl -H 'content-type:application/json' -d '{"dspid":"11121", "token":"ca8d0a0f59ee4302a6c3b5e41052e43b", "materialurl":["http://mt.wiplatform.com//m/img/39/20160322140115.png"]}' 'http://api.sandbox.yes.youku.com/dsp/api/status'

正常返回示例:

{
    "result":0,
    "message":
    {
        "total" :3,
        "records" : [
        {
            "crid": "dsp_crid_11001",
            "url": "http://material.client.com/134.swf",
            "result":"不通过"
            "reason": "默认素材不需要上传了"
        },{
            "crid": "dsp_crid_11002",
            "url": "http://material.client.com/135.swf",
            "result":"通过"
            "reason": ""
        },{
            "crid": "",
            "url": "http://material.client.com/136.swf",
            "result":"待审核"
            "reason": ""
        }]
    }
}

6. 获取素材的拒绝原因API

说明:素材上传到ADX以后,有三种状态:待审核,通过,不通过。因为审核不通过的素材,将不会允许在ADX上进行交易,所以DSP最好通过该接口确保正在投放的素材的审核状态为通过。DSP可以通过该接口查询在某个时间点之后上传的素材的拒绝原因,该接口只返回审核不通过的素材。

API地址:POST http://{youku.adx.domain}/dsp/api/reject

业务参数:

字段名称 类型 描述
uploaddate string 上传的时间:将返回该时间之后上传的所有未审核通过的素材列表 可以为空,为空时返回所有的未审核通过的素材列表 格式要求:YYYY-mm-dd

返回信息:

参数名称 类型 含义
result int 0:执行成功 1:系统认证失败 2:请求参数错误 3:其他错误
message object或者string 若result为0,message类型为object,表示操作成功;
若result为1,message类型为string,表示系统认证失败;
若result为2,message类型为string,表示请求参数错误;
若result为3,message类型为object({"errno":["err_str","err_str"], "errno":["err_str","err_str"]})

message字段说明

当调用result=0时,message对象包含各个拒绝素材的URL和拒绝原因,message对象字段如下:

参数名称 类型 含义
total int 拒绝素材总数
records array of objects 每条素材,对象内包括URL和拒绝原因

records每个元素的说明

参数名称 类型 含义
url string 拒绝素材的URL
crid string 拒绝创意的ID
reason string 拒绝原因,由审核人员人工填写

请求示例:

\\ POST 'http://{youku.adx.domain}/dsp/api/reject'
\\ JSON:
{
    "dspid":"11268",
    "token":"92205dff8f9d48e1b7a26b0b88af7dc1",
    "uploaddate":"2013-12-24"
}

curl示例

curl -H 'content-type:application/json' -d '{"dspid":"11121", "token":"ca8d0a0f59ee4302a6c3b5e41052e43b", "uploaddate":"2016-03-20"}' 'http://api.sandbox.yes.youku.com/dsp/api/reject'

返回示例:

{
    "result":0,
    "message":
    {
        "total" :2,
        "records" : [
        {
            "crid": "dsp_crid_11001",
            "url": "http://material.client.com/123.swf",
            "reason": "显示异常"
        },
        {
            "crid": "",
            "url": "http://material.client.com/134.swf",
            "reason": "跳转地址异常"
        }
        ]
    }
}

7. 报表获取API

说明:

DSP可以通过该API向ADX请求下载报表,报表分为概览数据报表和详细数据报表两个形式。概览数据报表内容包括查询日期段内,DSP整体参与竞价次数、竞价胜出次数、曝光量、点击量、费用、ADX收取的服务费;概览数据报表每次查询日期段最大允许31天。详细数据报表内容包括查询日期段内,DSP每天、每个广告位上参与竞价次数、竞价胜出次数、曝光量、点击量、费用、ADX收取的服务费;详细数据报表查询日期段最大允许7天。

API地址:POST http://{youku.adx.domain}/dsp/api/report

业务参数:

字段名称 类型 描述
type string 请求的报表类型,包括:general(概览)和detail(详细数据),如果为空,则默认为general
startdate string 报表查询的开始日期,要求是YYYY-MM-dd的格式,如2012-02-01,不能为空
enddate string 报表查询的结束日期,要求是YYYY-MM-dd的格式,如2012-02-07,不能为空

返回信息:

参数名称 类型 含义
result int 0:执行成功 1:系统认证失败 2:请求参数错误 3:其他错误
message object或者string 若result为0,message类型为object,表示操作成功;
若result为1,message类型为string,表示系统认证失败;
若result为2,message类型为string,表示请求参数错误;
若result为3,message类型为object({"errno":["err_str","err_str"], "errno":["err_str","err_str"]})

message对象说明

如果是概览报表(请求type=general),则响应为一个报表对象,字段如下:

参数名称 类型 含义
bid int 竞价数
winbid int 成功数
pv int 曝光数
click int 点击数
cost double 花费
platformincome double 平台服务费,因为“阿里妈妈全域媒体”ADX不收费,这里通常是0

如果是详细报表(请求type=detail),则响应对象里有total(结果条数)和records(报表项列表):

参数名称 类型 含义
total int 结果条数
records object 报表项,这是一个hash,key是报表日期,value是一个报表项数组,每一项和上面定义的概览报表项类似,但多一个aid字段表示广告位ID,每一项的数值是该日期和广告位ID上的统计数据

records结构是一个hash:

形式 说明
key {日期} 报表日期,格式是 yyyy-MM-dd
value array of objects 当天的报表项列表,每个元素表示该日某一个广告位的统计数据

records报表项对象说明:

参数名称 类型 含义
aid string 广告位ID
bid int 竞价数
winbid int 成功数
pv int 曝光数
click int 点击数
cost double 花费
platformincome double 平台服务费,因为“阿里妈妈全域媒体”ADX不收费,这里通常是0

具体格式参看下面的响应示例。

请求示例:

\\ POST 'http://{youku.adx.domain}/dsp/api/report'
\\ JSON:
{
    "dspid":"11268",
    "token":"92205dff8f9d48e1b7a26b0b88af7dc1",
    "type":"general"/"detail",
    "startdate":"2012-12-01",
    "enddate":"2012-12-07"
}

curl示例:沙箱环境暂不支持报表查询呢

curl -H 'content-type:application/json' -d '{"dspid":"11121", "token":"ca8d0a0f59ee4302a6c3b5e41052e43b", "type":"general", "startdate":"2012-12-01", "enddate":"2012-12-07"}' 'http://api.sandbox.yes.youku.com/dsp/api/report'

请求中type为general,返回示例:

{
    "result":0,
    "message":
    [{
        "bid": 5000,
        "winbid": 4000,
        "pv": 3950,
        "click": 125,
        "cost": 120.00,
        "platformincome":20.00
    }]
}

请求中type为detail,返回示例:

{
    "result":0,
        "message":
        {
            "total" :1,
            "records" :
            {
                "2012-02-01":
                    [{
                        "aid": "101", // 2012年2月1日再广告位ID=101上的统计数据
                        "bid": 6400,
                        "winbid": 4300,
                        "pv": 4100,
                        "click": 200,
                        "cost": 980.00,
                        "platformincome":10.00
                    },{
                        "aid": "102",
                        "bid": 3600,
                        "winbid": 2000,
                        "pv": 1990,
                        "click": 40,
                        "cost": 90.00,
                        "platformincome":9.00
                    }]
            }
        }
}

8. 广告主和行业获取API

说明:根据提供的dspid,查询该dspid下所有的广告主和广告主行业

API地址:POST http://{youku.adx.domain}/dsp/api/industry

业务参数:

返回信息:

参数名称 类型 含义
result int 0:接口执行成功。也包括执行成功,但内含业务错误的情况;
1:系统认证失败;
2:请求参数错误;
3:其他错误
message object或者string 若result为0,message类型为object,表示操作成功;
若result为1,message类型为string,表示系统认证失败;
若result为2,message类型为string,表示请求参数错误;
若result为3,message类型为object({"errno":["err_str","err_str"], "errno":["err_str","err_str"]})

请求示例:

\\ POST 'http://{youku.adx.domain}/dsp/api/industry'
\\ JSON:
{"dspid":"11268","token":"92205dff8f9d48e1b7a26b0b88af7dc1"}

curl示例

curl -H 'content-type:application/json' -d '{"dspid":"11121", "token":"ca8d0a0f59ee4302a6c3b5e41052e43b"}' 'http://api.sandbox.yes.youku.com/dsp/api/industry'

广告主-行业信息API的正常返回示例:

{
    "result":0,
    "message":
    {
        "total" :2, // 总数
        "records" : [ // 广告主-行业对应关系数组
        {
            "advertiser": "汽车-首页-banner" ,  // 名称
            "industry": "1", // 广告主行业id
        },
        {
            "advertiser": "新闻-视频",
            "industry": ""
        }
        ]
    }
}

说明:获取yes系统设置的广告流量数据

API地址:POST http://{youku.adx.domain}/dsp/api/shunt

业务参数:

返回信息:

参数名称 类型 含义
result int 0:接口执行成功。也包括执行成功,但内含业务错误的情况;
1:系统认证失败;
2:请求参数错误;
3:其他错误
message object或者string 若result为0,message类型为object,表示操作成功;
若result为1,message类型为string,表示系统认证失败;
若result为2,message类型为string,表示请求参数错误;
若result为3,message类型为object({"errno":["err_str","err_str"], "errno":["err_str","err_str"]})

请求示例:

\\ POST 'http://{youku.adx.domain}/dsp/api/shunt'
\\ JSON:
{"dspid":"11268","token":"92205dff8f9d48e1b7a26b0b88af7dc1"}

curl示例

curl -H 'content-type:application/json' -d '{"dspid":"11121", "token":"ca8d0a0f59ee4302a6c3b5e41052e43b"}' 'http://api.sandbox.yes.youku.com/dsp/api/shunt'

广告流量设置信息API的正常返回示例:

{
    "result":0,
    "message":
    {
        "total" :2, // 总数
        "records" : [{  // 广告流量数组
            "area": "11,12" ,  // 地区
            "type": "PC", // 设备
            "system": "IOS", // 操作系统
            "channel": "9001,9002,9003", // 分类
            "positionid ": "15" // 广告位id
        },{
           "area": "11,12" ,
            "type": “PC",
            "system": “IOS",
            "channel":9001,9002,9003",
            "positionid ": "16"
        }]
    }   
}

三、实时竞价接口

说明

ADX的实时竞价接口参照OpenRTB V2.2协议实现,基本上是OpenRTB的一个子集,另外在某些字段的ext对象里扩充了一些信息。

关于OpenRTB V2.2的协议,参见IAB网站上的官方文档

RTB实时竞价接口包括Bid请求和响应两部分,ADX发送BidRequest给DSP,DSP解析并返回BidResponse给ADX参与竞价。

Bid Request

协议采用HTTP POST,开启keep-alive,消息格式为JSON,目前timeout为贴片100ms,native和banner(包括焦点图和信息流)120ms。请求头中需要设"Content-Type: application/json"

Bid Request结构图:

bid request

bid request

Request Object

字段名称 类型 描述
id string 请求ID
imp array of objects 曝光对象,一次request可以包含多个imp
site object 媒体站点对象。注意:同一个请求中site和app只会有一个出现,当请求由浏览器发起时是site; 当请求由移动app发起时有app。
app object 移动app对象。注意:同一个请求中site和app只有一个出现。
device object 设备对象
user object 用户对象
imp object

说明:只包含一个banner或video对象,两者不会同时存在

字段名称 类型 描述
id string 曝光ID,在同一次请求中,区分不同的广告位
tagid string 广告位ID
bidfloor float 底价,单位是分/千次曝光,即CPM
banner object banner类型的广告位
video object video类型的广告位
native object native类型的广告位
pmp object Preferred Deal相关参数,参看pmp字段说明
ext object 扩展字段,参看imp.ext字段的说明
secure interger secure=1 https url, secure=0 http url,默认0
imp.ext object
字段名称 类型 描述
repeat integer 本次竞价请求支持返回的最大广告素材数量(信息流和贴片资源需要处理)。贴片资源中,以15s为一个单位,累计repeat*15s的最长播放时长素材(单个素材满足15s的倍数)。例如:repeat=3,支持所有素材时长累计3*15s=45s,可返回素材序列 【3个15s,1个30s+1个15s,1个45s素材】。多贴广告竞价的规则,具体参见附录竞价规则说明
campaign_start integer 订单预投起始时间戳(单位:秒)目前仅PDB开屏广告使用该字段
campaign_end integer 订单预投终止时间戳(单位:秒)目前仅PDB开屏广告使用该字段
字段名称 类型 描述
w integer 广告位宽度
h integer 广告位高度
pos integer 广告位未知,0:未知;1:首屏;2:次屏
video object
字段名称 类型 描述
mimes array of strings 支持播放的视频格式,目前支持: video/x-flv,application/x-shockwave-flash。
注意:“优酷”的贴片视频广告,实际上要求DSP先上传创意素材到“优酷”视频系统,并获取返回的播放页URL作为素材的地址,类似于:http://v.youku.com/v_show/id_XODQyMjY2MzY0.html,在RTB响应中,直接返回该地址即可。由于历史原因,“优酷”RTB请求中mimes均使用video/x-flv,DSP不需要判断这个情况,直接返回播放页地址即可。
linearity integer 广告展现样式,0: "未知"; 1:"instream/linear"即线性贴片素材,包括前贴中贴后贴; 2:"overlay/nonlinear"即视频播放中的悬浮广告; 3:"pause"即视频播放暂停中的悬浮广告; 4:"fullscreen"即视频全屏播放时的悬浮广告; 5:"openapp"即开机图广告
minduration integer 视频广告最短播放时长,单位是秒
maxduration integer 视频广告最长播放时长,单位是秒
w integer 广告位宽度
h integer 广告位高度
startdelay integer 该字段仅在linearity=1时有效;线性贴片,0:前帖;-1:中贴;-2:后贴。
native object
字段名称 类型 描述
native_template_ids array of string 原生广告模板ID数组
assets array of object 原生广告模板规则要求
assets object
字段名 类型 描述
native_template_id string 原生广告模板ID
title object 广告标题要求
image_url object 广告图片素材要求
video_url object 广告视频素材要求
logo_url object 广告素材LOGO规格
brand object 广告素材品牌要求
title和brand object
字段名 类型 描述
len int 广告标题长度限制
image_url和logo_url object
字段名 类型 描述
w int 广告素材宽度限制
h int 广告素材高度限制
mimes array of string 广告素材类型mime类型限制
video_url object
字段名 类型 描述
minduration int 视频广告最短播放时长,单位是秒
maxduration int 视频广告最长播放时长,单位是秒
mimes array of string 广告素材类型mime类型限制
imp.pmp object
字段名称 类型 描述
deals array of object 符合exchange系统的deal条件的deal对象数组,每个元素是一个deal对象。见deal对象说明
imp.pmp.deal objcet
字段名称 类型 描述
id string 符合条件的deal id
at int 竞价的方式,目前都是1,即第一竞价法。最高的deal获得竞价成功,取最高出价作为最终胜出价。注:只有当多个Deal同时响应时才互相之间竞价。这个字段和OpenRTB相同。
bidfloor float deal 价格,单位是分/千次曝光,即CPM。 1.3.0.3 版本新增
site object
字段名称 类型 描述
name string 媒体网站名称
page string 当前页面URL
ref string Referrer URL
content object 视频的内容相关信息。只有视频贴片类型的广告位才会有这个字段,参见site.content对象描述
site.content
字段名称 类型 描述
title string 视频标题名称
keywords string 视频标签关键字,如果是多个关键字,则使用英文竖线分隔
ext object 参见site.content.ext描述
site.content.ext object
字段名称 类型 描述
channel string 视频的频道ID,例如"a"。具体的频道列表,参见字典文件Youku ADX频道列表
cs string 二级频道ID。具体的二级频道列表信息,参见字典文件Youku ADX二级频道列表
usr string 视频上传者id,“优酷”里上传视频的用户ID
s string 节目id
vid string 视频id
app object
字段名称 类型 描述
name string App的名称,一般是"“优酷客户端",或者"土豆客户端"。
pck(未上线) string App的包名,一般是com.youku.app。
bundlid(未上线) string App bundlid。
content object 视频的内容相关信息。只有视频贴片类型的广告位才会有这个字段,内容与site.content对象相同
device object
字段名称 类型 描述
ua string user agent(Browser user agent string)
ip string IP。使用的是"123.123.123.123"格式。如果是IPV6,格式类似"98:FA:E3:5C:C6:4B"。
didmd5 string 使用MD5哈希的Device ID,在移动流量里,这个字段是IMEI的md5值(废弃,不推荐使用)
os string 操作系统,取值如下:
Windows: "Windows",
Android: "Android",
iPhone: "ios",
苹果电脑: "Mac"
osv string 操作系统版本号,如"4.1", "XP"等
devicetype integer 设备类型,和0—手机,1—平板,2—PC,3—互联网电视。
注:现在实际流量中没有“互联网电视”类型。
idfa string 当os = ‘ios’时有效, 明文传输,默认为空字符串
caid string 广协推广的caid,用于替代ios不能获取idfa,caid由版本号和具体的CAID值组成,格式ver_caid,每次传输传两个caid,分别为当前最新版本号和上一版本号caid,两者之间逗号分隔, 最后拼接后需用URLEncode编码,比如,明文为: 20210401_xxxx,20210101_xxxx 则caid=20210401_xxxx%2c20210101_xxxx
aaid string 阿里内部推广的设备ID标识
oaid string Android Q设备id
androidid string 当os = ‘android’时有效,明文传输,默认为空字符串(已废弃,协议还会下发,值为空)
imei string IMEI, 明文传输,默认为空字符串(已废弃,协议还会下发,值为空)
mac string MAC地址,明文传输,默认为空字符串(已废弃,协议还会下发,值为空)
androidid_md5 string 当os = ‘android’时有效,传输明文md5值,默认为空字符串
imei_md5 string IMEI, 传输明文md5值,默认为空字符串。注:Android Q版本无法获取
mac_md5 string MAC地址,传输明文md5值,默认为空字符串
make string 制造厂商,如“apple”“Samsung”“Huawei“,默认为空字符串
model string 型号, 如”iphoneA1530”,默认为空字符串
connectiontype integer 链接类型, 0:未知; 1:以太网2:Wifi; 3:移动数据 -未知; 4:2G; 5:3G
carrier string 运营商, 0:wifi;1:中国移动;2:中国联通:3:中国电信;4:其他;5:未识别
注:由于历史原因及参照openRTB协议;将integer类型修改string类型
screenwidth string 屏幕宽度, 像素 ,默认为空字符串
screenhight string 屏幕高度, 像素 ,默认为空字符串
user object
字段名称 类型 必填 描述
id string Y 用户ID。在PC流量中,这个ID是youku.com的cookie中的用户ID字段;在移动流量中,该字段具体取值方式,参见附录UserID取值规则
Bid Request-banner示例
{
    "id":"auction-server-1.2-sandbox-1-t12-1387962585-0-702",//请求id
    "site":{//媒体站点对象
        "name":"联调网站1",
        "ref":"",
        "page":"http://www.youku.com/"//当前页面url
    },
    "device":{//设备对象
        "ip":"192.168.1.226",
        "ua":"Mozilla/5.0 (X11; Ubuntu; Linux x86_64; rv:20.0) Gecko/20100101 Firefox/20.0"
    },
    "user":{//用户对象
        "id":"1393314446719HTx"//
        "tag":{
            "1": 50,
            "2": 50
        }
    },
    "imp":[{//曝光对象
        "id":"00448754623f45c7a245274392213a0f",//曝光id
        "tagid":"319",//曝光对应的exchange系统的广告位id
        "bidfloor":1,//广告位低价
        "banner":{
            "w":300, //广告位尺寸
            "h":250,
            "pos":"3",//第几屏
        }
    }]
}
Bid Request-video示例
{
   "id" : "auction-server-1.2-sandbox-1-t12-1387962585-0-702",
   "imp" : [
      {
         "bidfloor" : 800,
         "id" : "impid123",
         "tagid" : "19",
         "video" : {
            "h" : 480,
            "linearity" : 1,//广告展现样式
            "minduration":1,//视频广告最短播放时长,单位是秒
            "maxduration":15,//视频广告最长播放时长,单位是秒
            "mimes" : ["video/x-flv"],//广告位允许的素材类型
            "w" : 640
         },
         "pmp": { // Deal
             "deals" : [
             {
                 "id": "1",
                 "at": 1
             }
             ]
         }
      }
   ],
   "device" : {
      "ip":"192.168.1.226",
      "ua":"Mozilla/5.0 (Windows NT 5.1) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/31.0.1650.63 Safari/537.36",
      "didmd5":"d41d8cd98f00b204e9800998ecf8427e",
      "os":"Windows",
      "osv":"XP",
      "devicetype":2
    },
   "site" : {
      "name" : "“阿里妈妈全域媒体”网",
      "content" : {
         "title": "Big Bang Theory",
         "keywords": "Sitcom|Funny"
         "ext" : {
            "channel": "1",
            "cs": "2"
         }
      }
   },
   "user" : {
      "id" : "1393314446719HTx"
      "tag":{
          "1": 50,
          "2": 50
      }
   }
}
Bid Request-app示例(贴片)

目前提供字段app示例:


{
    "id":"v1.2-test-1-t12-1396427099-0-779",
    "device":{
      "ip":"192.168.1.226"
      "didmd5":"d41d8cd98f00b204e9800998ecf8427e",
      "os":"Windows",
      "ua":"Mozilla/5.0(iPhone;CPUiPhoneOS6_0likeMacOSX)AppleWebKit/536.26(KHTML,likeGecko)Version/6.0Mobile/10A403Safari/8536.25",
      "devicetype":0,
      "os":"iOS",
      "idfa":"B919E320-3140-4290-B2B3-B4D8C75A272F",
      "make":"apple",
      "carrier":"4",
      "connectiontype":2,
      "model":"iPhone4,1",
      "mac":"02:00:00:00:00:00",
      "screenwidth":"640",
      "screenhight":"960",
    },
    "user":{
        "id":"1393309862708emQ"
    },
    "app":{
        "name":"“优酷”客户端",
        "content":{
            "title":"%E7%94%B5%E8%A7%86%E5%89%A7",
            "ext":{
                "channel":"d",
                "cs":"2038"
            }
        }
    },
    "imp":[
      {
        "id":"35829dda8b5642f99d5dd4c6e3628dbe",
        "tagid":"19",
        "bidfloor":13400,
        "video": {
          "w":640,
          "h":480,
          "mimes":["video/x-flv"],
          "linearity":1,
          "minduration":1,
          "maxduration":15
        }
      }
    ]
 }

PDB Request-app示例

{
    "id": "a12-0ASh-03PFKt-0RV-2OR",
        "app": {
            "name": "“优酷”客户端",
            "content": {
                "keywords": "关键词",
                "title": "视频标题",
                "ext": {
                    "channel": "c",
                    "usr": "97454045",
                    "cs": "2034",
                    "vid": "420613008",
                    "s": "306281"
                }
            }
        },
        "device": {
            "androidid": "d097a86f3f9dd712",
            "make": "OPPO",
            "screenwidth": "1080",
            "carrier": "1",
            "connectiontype": 2,
            "model": "OPPO R9m",
            "screenhight": "1920",
            "mac": "cc:2d:83:16:fd:d0",
            "ua": "Youku;5.10.1;Android;5.1;OPPO R9m",
            "imei": "862965038483716",
            "ip": "49.77.178.130",
            "devicetype": 0,
            "osv": "5.1",
            "idfa": "",
            "os": "Android",
            "didmd5": "e79efc200a79a4a5cf511829e5c1e52a"
        },
        "imp": [{
            "bidfloor": 1650,
            "id": "055f797a16e807d05027e0b4b945d7c9",
            "pmp": {
                "deals": [{
                    "at": 1,
                    "id": "01402729"
                }]
            },
            "video": {
                "h": 480,
                "startdelay": 0,
                "w": 640,
                "mimes": ["video/x-flv"],
                "minduration": 13,
                "linearity": 1,
                "maxduration": 16
            },
            "tagid": "55"
        }],
        "user": {
            "id": "862965038483716"
        }
}

Native Request-app示例

{
    "id": "a01-00SD-02h1tX-001-0Vf",
    "imp": [{
        "id":"2015f1d9dc6f6e317cf91c3c7e07345b",
        "tagid":"201",
        "bidfloor":200,
        "native":{
            "native_template_ids":["1","3"],  //原生广告位模板ID
            "assets":[{             //原生广告模板规则定义
                "native_template_id":"1",
                "title":{
                    "len":8
                },
                "image_url":{
                    "w":1280,
                    "h":720,
                    "mimes":["image/jpg","image/png"]
                },
            },{
                "native_template_id":"3",
                "title":{
                    "len":10
                },
                "image_url":{
                    "w":600,
                    "h":500,
                    "mimes":["image/jpg","image/png"]
                },
            }],
        },
    }],
    "app": {
        "content": {
            "keywords": "中国",
            "title": "中国人名",
            "ext": {
                "channel": "u",
                "usr": "93129229",
                "cs": "",
                "vid": "108066107",
                "s": ""
            }
        },
        "name": "“优酷”客户端"
    },
    "device": {
        "androidid": "43debaa64c42eeb7",
        "screenhight": "1920",
        "ua": "Youku;5.5;Android;5.1;m1metal",
        "mac": "",
        "idfa": "",
        "carrier": "5",
        "devicetype": 0,
        "connectiontype": 2,
        "didmd5": "f0577d676559ee51588fe5b5f85f3c26",
        "make": "Meizu",
        "os": "Android",
        "screenwidth": "1080",
        "imei": "868024029860260",
        "osv": "5.1",
        "ip": "125.111.101.163",
        "model": "m1metal"
    },
    "user": {
        "id": "868024029860260"
    }
}

Bid Response

说明:

DSP正常出价响应包的返回状态码为200 OK,并在Body里填写JSON格式的BidResponse。

如果决定不出价,则应该返回状态码204 No Content,Body置空。

如果返回其他状态吗,如403 Forbidden500 Internal Server Error,则ADX会当做做出错处理.

Bid Response结构图

bid response

bid response

Bid Response object

字段名称 类型 描述
id string 请求ID
bidid string DSP给出的该次竞价的ID
seatbid array of objects DSP出价
seatbid object
字段名称 类型 描述
bid array of objects 针对单次曝光的出价
bid object
字段名称 类型 描述
id string DSP对该次出价分配的ID
impid string Bid Request中对应的曝光ID
native object 参与竞价的原生广告创意信息
price float DSP出价,单位是分/千次曝光,即CPM
nurl string win notice url(已废弃,返回不会报错,效果和曝光监测一致)
adm string 广告素材URL。banner,贴片,暂停,角标,开机图资源必填。注意:PDB2.0该字段无效,统一接收crid。
crid string DSP系统中的创意ID。信息流,焦点图资源必填。保证在DSP侧的ID唯一性,作为竞价时的唯一创意ID,否则会引起素材投放混乱。
advertiser string 广告主ID,对应广告审核的广告主ID
industry string 广告主行业ID,需要使用YOUKU系统的行业
pvm array of string 曝光监测URL,可以有多个。注意是json数组(@Deprecated,版本1.4以后会删除这个字段,请使用ext.pm 目前版本1.3两个都支持)
clickm string 点击目标URL,可以包括点击监测串。(@Deprecated,版本1.4以后会删除这个字段,请使用ext.ldp) 目前版本1.3两个都支持
dealid string DSP参加的deal id
orderid string DSP参加PDB的订单ID
ext object 扩展字段
native object
字段名 类型 描述
native_template_id string 参与竞价的原生广告模板ID
title string 信息流素材Title信息(仅适用于先投后审的情况)
image object 信息流图片素材信息(仅适用于先投后审的情况)
logo object 信息流素材LOGO信息(仅适用于先投后审的情况)
video object 信息流素材VIDEO信息(仅适用于先投后审的情况)
brand string 信息流素材品牌信息(仅适用于先投后审的情况)
native.image和native.logo object
字段名 类型 描述
url string 素材URL
type string 素材文件类型(jpg/png等)
width int 素材尺寸宽度
height int 素材尺寸高度
native.video object
字段名 类型 描述
url string 素材URL
vl int 视频素材时长
size int 视频素材大小,以B为单位

原生广告采用创意ID筛选投放的物料信息,故投放原生必须传回crid字段值

ext object
字段名称 类型 描述
ldp string 点击目标URL。这个字段是新的用来替代clickm的,所以请保证clickm和ldp两个字段只有一个填写。如果两个都填写,我们会优先取ldp。
dp string deeplink地址。目前只移动APP,PC及移动WAP暂不支持。dp跳转失败会使用ldp进行跳转
ldptype integer 0:普通链接;1:iOS下载地址;2:安卓apk下载地址。3:deeplink跳转(dp参数必须返回);4:universallink跳转(仅IOS支持),universallink地址对应ldp参数。注:目前仅支持淘宝换端,dp的白名单规则为:tbopen://m.taobao.com开头,Uniervallink以https://b.mashort.cn开头。返回其他默认为0
pm array of strings 曝光监测URL,可以有多条,建议最多3条,数量太多可能被审核拒审。注意格式为json数组
em array of strings 可选字段,曝光监测URL,广告播放结束后触发,可以有多个。注意是json数组 。1.3.0.3 版本新增
tm array of object 可选字段,视频素材播中曝光监测URL,指定时间点发送的一系列检测地址,可以有多个注意是json数组 。1.3.0.3 版本新增
cm array of strings 点击监测URL,可以有多条,建议最多3条,数量太多可能被审核拒审。注意是json数组
type string 素材的类型。注意只有当素材为动态HTML snippet时,需要指定"type":"c"; 当素材为先投后审的静态或native素材时,需要指定"type":"x"。其他类型的素材均不需要提供type字段。
macro object PDB送审的监测地址中宏替换值,格式为K/V格式,K格式只能使用字母、数字和下划线并且宏由双下划线开始和双下划线结束,例如__MAC__
apk object 应用相关信息,应用下载推荐回传,该字段会关联终端显示,有利于提高应用下载投放效率。
tm object
字段名称 类型 描述
t integer 在播放器触发检测链接url的时间点,单位为秒。
url string 展示监测链接,在指定时间点t发送,包括投放引擎、客户与第三方监测链接。
apk object
字段名 类型 必填 描述
download_url string N 应用下载链接,iOS为appstore地址,Android为apk包下载地址。回传后,“阿里妈妈全域媒体”视频信息流支持前置下载
packagename string N 应用包名,iOS为应用市场ID,即:appid;Android为包名
versioncode integer N 应用版本号
versionname string N 应用版本名称
size long N 包大小,单位:字节
sign string N 包签名
md5 string N 包MD5
minsdklevel integer N 系统最低版本要求
Bid Response示例
{
    "id":"auction-server-1.2-sandbox-1-t12-1387962585-0-702",//竞价请求ID(对应Bid Request中的id)
    "bidid":"100002_200004_1000014",//DSP给出的该次竞价的ID
    "seatbid":[{//注意第一层数组  DSP出价
        "bid":[{//注意第二层数组 针对单次曝光的出价
            "adm":"http://xxx.jpg",
            "id":"100002_200004_1000014_0",//DSP对该次出价分配的ID
            "impid":"297902be955e49a291bcc44c7f13448c",//Bid Request中对应的曝光ID
            "nurl":"http://test.xxx.com?id=${AUCTION_ID}&bidid=${AUCTION_BID_ID}&impid=${AUCTION_IMP_ID}&price=${AUCTION_PRICE}",//目前nurl支持这四个宏替换
            "price":600,//DSP出价,注意单位是分/千次曝光,即CPM
            "crid":"1000014",//投放动态创意(即c类型的素材),需添加该字段
            "ext":{
                "ldp":"http://ss.thinkworld.com.cn/",
                "pm":["http://test.xxx.com"],//注意曝光监测url是数组
                "cm":["http://test.xxx.com"],//注意点击监测url是数组
                "em":["http://test.xxx.com"],//注意点击监测url是数组
                "tm":[{"t":5,"url":"http://test.xxx.com"},{"t":10,"url":"http://test.xxx.com"}]//
            }
        }]
    }]
}
Native Response 示例
{
    "id":"a01-00SD-02h1tX-001-0Vf",
    "bidid":"dsp_bid_id_0001",
    "seatbid":[{
        "bid":[{
            "id":"dsp_imp_id_0001",
            "impid":"2015f1d9dc6f6e317cf91c3c7e07345b",
            "price":100.23,
            "crid":"dsp_creative_id_0001",  //DSP创意id,保证在DSP侧的id唯一性
            "nurl":"http://xxx.xxx.xxx/1x1.gif?requestid=110&price=xkjlkd",
            "type":"x" //动态创意必须返回(暂时只支持内部渠道),
            "native":{
                "native_template_id":"1",     //DSP response native template id
            },
            "ext":{
                "ldp":"http://www.youku.com",
                "pm":["http://yes.youku.com"],
                "cm":["http://yes.youku.com"],
            }
        }]
    }]
}

注意:动态创意返回必须加"type":"x"字段。已不支持HTML动态创意支持(即:type=c)

宏参数

DSP竞价返回的监测代码中,可以根据需要返回“阿里妈妈全域媒体”支持的宏参数,获取成交价格,bidid等信息。

目前支持的宏如下:

字段名称 类型 描述
id ${AUCTION_ID} Bid Request ID,即BidRequest.id
bidid ${AUCTION_BID_ID} Bid Response ID per request,即BidResponse.bidid
impid ${AUCTION_IMP_ID} Impression ID,即BidRequest.imp.id
price ${AUCTION_PRICE} 曝光的最终拍卖价,以及时间戳。
因为历史原因,该字段除了成交价,还包含了成交的时间戳,格式是{PRICE}_{TIME}(例如:201_1376468920380),并使用DSP的token作为key,进行AES加密。
DSP在收到该字段之后,需要先使用token作为key进行AES解密,再split分别获得{PRICE}和{TIME}。
这里的时间戳是精确到毫秒的。另外,对于动态素材,也可以在"bid":"adm"字段中通过宏%%WINNING_PRICE%%来获取价格。

四、附录

A. RTB错误码

错误码 错误类型 错误注释   处理说明 
101 严重 文件加载失败 文件加载经常是因为根据素材url地址获取信息时超时,在确保url正常的情况下可以重新再试一下
102 严重 不支持的文件格式,目前支持的文件格式:jpg,gif,png,swf,flv,x
103 严重 根据素材url获取不到尺寸信息  图片文件不合法
104 严重 执行插入过程中发生了错误 该错误经常是因为将素材保存到本地是超时,在确保url正常的情况下可以重新再试一下
105 严重 素材所属的广告主为空;广告主不存在,调用uploadadvertiser接口上传广告主信息
106 严重 素材生效时间为空或者不能解析 注:时间格式为YYYY-mm-dd,如2014-01-01写成2014-1-01会报错
107 严重 素材失效时间为空或者不能解析 注:时间格式为YYYY-mm-dd
108 严重 内部错误  服务内部未知异常
109 严重 素材尺寸不符合广告位要求 上传到exchange状态会直接是未通过
110 严重 素材时长不符合广告位要求 针对视频素材
111 严重 上传总数超过限制 每次最多上传素材数量为500个;每次最多上传资质数量为50个
112 严重 获取素材时长时错误 有可能是素材时长还不能正常获取,或者网络原因,可以尝试再次上传
113 严重 广告主名称存在错误
114 严重 广告主品牌存在错误
115 严重 广告主第一统计行业存在错误
116 严重 广告主第二统计行业存在错误
117 严重 广告主资质存在错误
118 严重 资质名称存在错误
119 严重 资质操作类型错误
120 严重 资质文件的MD5错误
121 严重 资质文件URL存在错误
122 警告 广告主地址错误
123 警告 广告主联系人错误
124 警告 广告主联系方式错误
125 警告 未上传营业执照
126 严重 创意ID错误
127 严重 没有匹配的native模板ID
128 严重 没有上传创意
129 严重 没有上传主素材
130 严重 主素材MD5校验失败
131 严重 主素材格式校验失败
132 严重 开始监测地址错误
133 严重 播中监测地址错误
134 严重 播后监测地址错误
135 严重 点击监测地址错误
136 严重 创意未上传订单

B. Exchange素材类型说明

素材类型 对应文件类型 MIME 备注
png *.png image/png PNG图片
jpg *.jpg,*.jpeg image/jpg JPG或JPEG图片
gif *.gif image/gif GIF图片
flv *.flv video/x-flv FLV视频
swf *.swf application/x-shockwave-flash Flash动画
c HTML text/html HTML类型的动态素材,包括iframe或javascript格式。可以内嵌任何形式的HTML。
x * * 移动端动态素材类型(内部预留字段不对外开放)

注意: 贴片模式下,素材需要先预上传到“优酷”的视频系统中,得到的URL是*.html格式的,但这个素材实际上是flv类型。具体参见“优酷”贴片素材上传附加说明

C. CookieMapping

说明:目前cookiemapping和投放过程是分开的,即cookiemapping是单独的流程与投放过程无关。所以cookiemapping需要dsp单独找流量来累计cookie对应值。

ADX向DSP发送Bid Request中,会携带当前曝光的用户的“阿里妈妈全域媒体”Cookie ID,而DSP需要通过Cookie ID获取对应的DSP的用户ID,Cookie Mapping就是用来建立这一对应关系的过程。

cookiemapping的过程如下图所示:

CookieMapping

CookieMapping

两个url:ADX服务器地址和dsp服务器地址

HTTP: ADX接收Cookie Mapping服务器地址:http://c.yes.youku.com/cm.gif?dspid=xxxx,将该地址提供给DSP;DSP向ADX提供其接收302重定向的服务器的地址:http://cm.dsp.com

HTTPS: ADX接收Cookie Mapping服务器地址:https://cyes.youku.com/cm.gif?dspid=xxxx&s=1,将该地址提供给DSP;DSP向ADX提供其接收302重定向的服务器的地址:https://cm.dsp.com。注:如果DSP 想使用HTTPS服务, dsp 服务器地址域名需和HTTP的一致

整个Cookie Mapping的流程如下:

  1. DSP将ADX提供的url中的dspid的值修改成ADX给其分配的dspid,通过img标签嵌入到其某个页面上(dsp找到的流量),当该页面曝光时,将会向ADX的Cookie Mapping服务器发送一次请求
  2. ADX的Cookie Mapping服务器接收到请求以后,从Cookie中获得“阿里妈妈全域媒体”的Cookie ID,然后,将该ID以mzid为参数名,附在DSP提供的url上:http://cm.dsp.com?mzid=xxxx,然后返回302,redirect到这个URL(如果不能获取到Youku Cookie ID,则返回200)
  3. DSP的Cookie Mapping服务器收到请求以后,从url中获取mzid参数即可

D. CookieMapping商务流程

  1. 默认方式
    1. 广告曝光环节发起cookie mapping
    2. 使用者:月消耗10万以下的DSP
  2. 简单方式
    1. 通过购买视频播放页底通增加匹配率
    2. 使用者:月消耗10-100万的DSP
  3. 主动方式
    1. 在视频播放页增加主动发起mapping的代码
    2. 使用者:月消耗100万以上的DSP(具体与商务/产品部门进行商务沟通

E. 移动端流量信息FAQ

1,如何区分移动端和PC端? 移动端的流量,通过device.devicetype字段可以和PC端流量进行区分,具体参看字段的描述。

2,如何区分应用和WEB? 在移动端流量中,如果是来自移动应用的流量,则会传递app字段(当前只有app.name信息),否则会只传递site字段,表示这个是一个来自移动端的网页请求(比如手机上的浏览器发出来的)。

3,当前移动端提供的信息? 目前移动端BidRequest对象 deviceObject和appObject协议中有很多字段,但实际上移动端目前只提供一下这些字段

字段 BidRequest字段 备注
设备类型 device.devicetype 0为phone,1为pad,2为pc,3为tv 注:pc端和移动端都会提供
操作系统 device.os IOS,Android 注:os字段只在移动端提供,pc端不提供
操作系统版本 device.osv 如"4.1" 注:osv字段只在移动端提供,pc端不提供
应用名称 app.name 如““阿里妈妈全域媒体”客户端”,“土豆客户端”,注:当BidRequest中传递了app.name字段时,表示这是从应用发出的请求
频道信息 app.content.ext.channel 视频的频道ID
频道信息 cs 二级频道ID

4,device和app中的协议里的移动字段是否会增加支持? 我们预计在下一版中会增加更多的移动字段信息。现在协议中这些字段是最初设计时预留的。

F. 行业黑名单过滤说明

因为公司政策要求,不同的广告位对素材有不同的要求,“阿里妈妈全域媒体”ADX按照广告位和素材所属广告主的行业进行黑名单过滤,不符合过滤规则的素材将无法参与竞价。

行业黑名单与素材的关联是手动建立的,过程如下:

  1. DSP上传素材,信息中附带广告主名称
  2. ADX系统中如果存在该广告主,则素材与广告主建立关联,如果不存在,则根据广告主名称生成一个广告主
  3. ADX的运营同学人工标记新广告主所属的行业,如“游戏”等。这样,素材通过广告主名称与行业关联起来。
  4. 所有的广告位都有人工设置的行业黑名单,即该广告位不能投放黑名单上的行业关联的素材。
  5. 实时投放过程中,ADX服务器根据DSP返回的素材,查找其所属行业,判断是否属于黑名单,并做相应处理。

例如:

  1. 上传素材中,广告主名称字段"advertiser":"游戏厂商A".
  2. ADX系统建立一个广告主实体,ID=123, NAME="游戏厂商A".
  3. 运营同学人工给该广告主标记行业,其行业为"游戏"(industry: {id=1, name="游戏"}).
  4. DSP可以从广告位信息的API接口中,从"blockCategory"字段获取当前广告位设定的行业黑名单,其值为行业ID数组。如"blockCategory":["1","2"].
  5. 实时投放过程中,DSP返回一个素材,其广告主为"游戏厂商A",行业为"游戏"(ID=1),正好该广告位的blockCategory字段包含"1",因此该素材不能参与竞价

为了能够避免黑名单情况,DSP需要获取素材对应的行业,以及广告位对应的黑名单。

G. 竞价规则说明

a. 第二竞价法

ADX竞价采取第二竞价法,即多个素材参与竞价,出价最高者胜出,但实际花费采用的不是它的出价,而是第二高的价格+1分。

例如:有三个DSP,A, B, C参与竞价,出价为

DSP 出价(单位:分/CPM)
A 1500
B 1400
C 1300

那么胜出者是A,实际花费是B+1=1401 (分/CPM)。

b. 广告位底价

如果只有一个素材参与竞价,那么采用该广告位的底价作为第二高的参考价。

例如:DSP A参与竞价,出价为1500;广告位底价是1000,那么胜出者为A,花费为1000+1=1001 (分/CPM)。

c. 多贴片Top N竞价

“阿里妈妈全域媒体”前贴片广告经常有超过一个的展示位,例如4前贴。“阿里妈妈全域媒体”前贴片现在都是15s广告,ADX系统中最高会出现4前贴共60秒的广告。

这种广告是一次请求发送给各个DSP,通过repeat字段标注当前请求有N贴展示位,并最终竞价获得N个素材,按出价高低顺序播放。此时每个素材的实际花费使用次高的参考价+1,但是有三个特殊情况,下方会分别描述。

例如:3前贴,有三个DSP,A, B, C参与竞价,出价为

DSP 出价(单位:分/CPM)
A 1500
B 1400
C 1200
底价 1000

那么按照价格排序为:

DSP 出价(单位:分/CPM) 实际花费
A 1500 B+1=1401
B 1400 C+1=1201
C 1200 底价+1=1001
底价 1000 --

三个特殊情况:

例如假如是4前贴:

DSP 出价(单位:分/CPM) 实际花费
A1 1500 B1+1=1201
A2 1400 B1+1=1201
A3 1300 B1+1=1201
B1 1200 底价+1=1001
B2 1100 --
底价 1000 --

这里A1, A2, A3连续排列,所以参考价使用不属于A的次高的B1;对B1来说,参考价也是使用不属于他自己的底价(跳过同属一个DSP的B2)。

例如加入是2前贴:

DSP 出价(单位:分/CPM) 实际花费
A1 1500 C1+1=1101
B1 1500 C1+1=1101
C1 1100 --
底价 1000 --

H. “优酷”贴片素材上传附加说明

注意:PDB直接调用素材接口送审接口,RTB需要DSP处理。

贴片素材和普通素材有所区别:因为公司政策要求,为了确保素材播放的顺畅,要求所有的视频贴片素材都上传到“阿里妈妈全域媒体”视频系统中,由“阿里妈妈全域媒体”的视频系统CDN存放,而不能使用第三方Host的素材。

这样要求DSP在投放贴片素材时需要进行以下步骤:

  1. 将自有的或者第三方Host的flv素材上传到“阿里妈妈全域媒体”视频系统中。这个步骤可以人工使用“阿里妈妈全域媒体”的客户端,或者通过open.youku.com提供的视频上传API进行。该API的调用方法,参见cloud.youku.com视频上传API介绍
  2. 视频在“阿里妈妈全域媒体”系统上传后,可以获得一个URL地址表示该素材资源,该地址即素材视频的播放页URL,如http://v.youku.com/v_show/id_XMzg3NzAxMjk2.html
  3. 使用播放页URL作为素材的URL,调用ADX的素材上传API接口,将素材通知给ADX进行人工审核
  4. RTB实时接口中,返回BidResponse时,也是用这个播放页URL作为素材地址返回。

I. UserID字段说明

user.id字段在PC流量上,传递的是浏览器Cookie中存放的youku用户ID,在移动平台尽量采用设备唯一ID号,具体采集方式如下:

在各个系统中,按照优先级获取设备中的参数,如果获取到空值,或者取到的原值在下面描述的非法值名单中,则尝试获取下一优先级的参数作为uid:

系统 获取参数优先级
Android IMEI → AndroidID → MAC
iOS IDFA → OpenUDID → MAC

黑名单:

参数 非法值(原始值,非摘要值)
IMEI 0
IMEI 000000000000000
IMEI 111111111111111
AndroidID 9774d56d682e549c
IDFA 00000000-0000-0000-0000-000000000000

上述各个参数获取后转化为uid的细节要求如下:

参数 用途 格式
IMEI 用户终端的IMEI, 15位数字 取md5sum摘要
MAC 用户终端的eth0接口的MAC地址(大写, 去除冒号和分隔符) 取md5sum摘要
AndroidID 保留原始值 保留原始值
IDFA 保留原始值 保留原始值
OpenUDID 保留原始值 保留原始值

如果所有的参数都无法正常获取,则可以在最后加入其他维度信息,比如IP,UA等,这个不在规范以内。


J. PreferDeal交易规则说明

  1. prefer deal 采用第一竞价规则

K. PDB交易规则说明

  1. 产品形态是固定价格保量投放,形式是线下下单-线上投放-线下结算
  2. 素材对接,PDB素材由DSP来上传CDN,response里携带素材id,dealid等信息返回即可。
  3. 保量投放,按推送比售卖,所以需要DSP每天保证固定比例的填充和返回
  4. 不需要做广告位id、尺寸的判断,只要根据dealid判断一个活动的唯一性即可。一个dealid中只会推送一种广告位类型,不会即有贴片又有暂停等
  5. 数据完整性:
    1)确保上传的素材,素材中展示的内容与deal对应的广告主信息一致,不允许出现素材展示为A客户,deal对应广告主为B客户的情况;
    2)确保竞价的deal与请求deal一致;
    3)确保素材提审的dealid,与竞价时返回的dealid一致,否则会导致竞价失败;
    4)素材送审的广告主信息可以不填,服务端会直接取deal对应的广告主信息;

L. material.creative.attr_name 枚举

枚举值 说明描述
video创意视频元素,PDB送审对应贴片资源
image创意静态图片元素,PDB送审对应Banner资源
title创意主标题文本
sub_title创意副标题文本
logo_title创意 LOGO 文本
logo_image创意 LOGO 图片
image_dynamic创意动态图素材
image_background创意背景图素材
image_small创意缩略图素材
image2创意三图中的图 2 素材
image3创意三图中的图 3 素材

五、常见问题答疑

1. 如何判断设备类型?即:PC,移动,OTT。

答: Bid Request中device.devicetype为设备类型,点击这里查看

2. 如何判断客户端类型?即:APP还是WEB

答: Bid Request中包含app段为应用(如:移动APP,PC客户端),包含site段为web(如:移动WEB,PC WEB);

3. 如何判断资源类型?

答:

资源类型判断方法备注
贴片(前贴,中插,后贴) 贴片判断:imp.video.linearity=1;
贴片类型判断: imp.video.startdelay: 0:前帖;-1:中贴;-2:后贴
支持视频时长:imp.ext.repeat*15,如: imp.ext.repeat=2支持最长30秒广告, imp.ext.repeat=4支持最长60秒广告
原生广告判断(信息流 & 焦点图) 资源类型判断:imp.native.native不为空
支持样式判断: imp.native.native.template_ids=[“106”, “109”]
具体支持的信息流还是焦点图,以及需要的素材元素和样式,查看“阿里妈妈全域媒体”资源说明。原生资源判断尽量根据模版id判断。
imp.ext.repeat是指一次支持返回两个素材,最终出哪一个取决于价格和频次控制逻辑。所以,尽量保证两个素材客户不重复,品牌名称不重复,素材id不重复。
banner判断 资源判断:imp.banner
尺寸判断:宽:imp.banner.w,高: imp.banner.h
暂停判断 资源判断:imp.video.linearity=3;
尺寸判断:宽:imp.video.w,高: imp.video.h
角标判断 资源判断:imp.video.linearity=2;
尺寸判断:宽:imp.video.w,高: imp.video.h
开机图判断 资源判断:imp.video.linearity=5;
尺寸判断:宽:imp.video.w,高: imp.video.h
注意:尽量不要使用tagid判断资源类型,tagid可能会有调整和变动,会影响正常的广告投放

4. 视频素材上传后有水印怎么办?

答: 提供clientid给“阿里妈妈全域媒体”运营,“阿里妈妈全域媒体”运营处理。

5. 视频素材上传后视频无法访问怎么办?

答: 提供clientid给“阿里妈妈全域媒体”运营,“阿里妈妈全域媒体”运营处理。

6. 视频素材上传报错,超过每日上传最大限制怎么办?

答: 提供clientid给“阿里妈妈全域媒体”运营,“阿里妈妈全域媒体”运营处理。

7. 视频素材上传报错后,审核找不到文件?

答: 提供clientid给“阿里妈妈全域媒体”运营,“阿里妈妈全域媒体”运营处理。

8. openapi上传视频文件,分片总是失败或超时?

答: 确认文档是否为http://cloud.youku.com/docs?id=110;确认“create_file”接口设置的“slice_length”是否小于分片上传的内容长度。默认情况下“slice_length”为2M,最大可以设置为10M;确认下设置的超时时间是否足够长(一般超过1分钟就可以了)。

9. openapi上传视频文件,token如何维护?如何刷新?

答: Token有两个,一个是access_token一个是refresh_token,初始化获取通过” http://cloud.youku.com/tools”获取。默认情况下access_token的有效期是30天,refresh_token是40天,需要注意的是access_token在有效期内刷新无效。获取后存储在数据库中,并记录过期时间,到时间后请求api刷新access_token,根据返回的expires_in记录下次刷新时间。

10. 视频素材提交审核时服务端返回101错误码?

答: 这种情况是视频素材上传“阿里妈妈全域媒体”视频云没完成。DSP需要检查接口调用和素材推送审核的流程,一般按如下流程执行:

(1)首先检查链接后面是否拼接参数,拼接参数肯定会返回101错误码;

(2)如果没有拼接参数,并视频链接可访问,按如下步骤检查;

11. openapi上传视频文件,分片总是失败或超时?

答: 确认文档是否为http://cloud.youku.com/docs?id=110;确认“create_file”接口设置的“slice_length”是否小于分片上传的内容长度。默认情况下“slice_length”为2M,最大可以设置为10M;确认下设置的超时时间是否足够长(一般超过1分钟就可以了)。

12. 视频素材上传state返回limited是什么意思?

答: 上传是成功的,和normal状态一样。不过,地域上限制了港澳台海外。