技术对接说明.md

Adx对接步骤及相关问题解答

1. Adx技术对接说明

1.1 技术对接步骤

1. 开始对接
2. 向DSP提供最新的ADX协议文档和接口协议联调工具
3. DSP按照协议进行对接开发
4. DSP使用接口协议联调工具dsp_check_tool测试通过
5. 线下真实环境联调
6. 线上小流量测试通过
7. 对接完成

1.2 技术对接说明

1. 向Dsp提供的资料包括最新的Adx协议文档，接口协议联调工具
2. Dsp在按照协议文档开发完成，使用接口联调工具dsp_check_tool测试通过后，可以联系芒果技术对接人安排真实环境的联调
3. 在真实环境联调通过后，联系芒果运营对接人安排线上小流量测试，小流量在200QPS以内
4. 待以上流程都走通之后，测试通过，可以进行线上投放

---

2. 对接常见问题解答

2.1 在返回广告内容的时候，ad_url和creative_id的使用

使用方法是：
如果是先审后播的dsp，只需要在素材上传成功后，将生成的id作为creative_id返回即可，不需要再返回ad_url；如果是先播后审的dsp，只需要返回包含http://或者https://的素材地址作为ad_url的值即可，而不用返回creative_id字段。使用creative_id的好处在于：一个creative_id对应多个端的素材，我们会根据请求的不同，自动选择不同端的素材。

素材上传接口中的xy_ratio字段目前只支持: AD_16:9, AD_4:3两种比例，如果不符合这两种比例，则在这两种比例中选择最为接近的一个即可（可能会添加黑边）。

2.3 补充最新的分类列表

综艺	电视剧	电影	动漫	少儿	新闻	音乐	逗爸	爱豆	乐活	趣玩	教育	纪录片
1	2	3	50	50	106	20	111	111	105	116	115	51

2.4 价格加解密相关

说明
芒果tv PMP平台中，针对价格传输(包括但不限于py上报、第三方监测上报等），采用AES 对称加密。对于加密密钥，直接将字符串强制转换为128byte的二进制使用的。其中：
加密算法：AES-128 CBC 方式
初始化向量IV：和加密密钥相同
BlockSize：16
补码方式：PKCS5Padding（padding byte=blockSize len(待加密字符串)%blockSize）
加密结果编码方式：16进制

示例
原价格：2000 (单位是分/CPM)
当前时间戳: 1482230774
待加密字符串："2000|1482230774"
加密密匙："d6797b0f95f8ead1"
加密后字符串："3dd5e5b6c16eea4635af0cd9820dda34"
代码（golang/c++版）：见示例代码中的golang/c++版的加解密代码

2.5 不参与竞价时无广告时的返回

当Dsp不参与竞价，如果没有广告返回的话，必须按照以下格式返回： {"version":3,"bid":"ad68e04d-ee12-4f0c-6dff-5900b388aa90","err_code":204}

2.6 DSP接口测试工具使用指南

在Linux环境下，运行./dsp_check_tool -h 查看帮助,通过该工具可以自助测试mgtv adx的协议，其中包含的广告类型包括前贴片广告，暂停广告以及通栏广告
使用方法示例如下：
./dsp_check_tool -d -t "pc_front" -u "http://127.0.0.1:10000/dsp"

2.7 space_id, creative_id, adid三者的区别

目前只使用space_id作为广告位Id，是广告位唯一标示，creative_id作为素材唯一标示，Dsp只有在调用芒果的素材上传接口之后，才会生成对应素材的creative_id，adid目前只是作为一个保留字段，不推荐使用

2.9 pmp在bid request中是否会传多个，响应的时候是否一定要带上dealid

Request中的字段中会带有首选交易相关的信息，如果pmp字段为空，则标示此交易为rtb请求；如果pmp字段不为空，则标示此次请求的是首选交易。首选交易中的pmp字段是数组类型。如果返回的广告是首选交易类型，则返回中必须带有请求中对应的dealid字段。如果返回广告中dealid为空，则进行rtb竞价。

2.10 Dsp请求中的min_playtime, max_playtime的作用

Dsp请求中的min_playtime, max_playtime作用标示可返回时长控制。返回广告的时长必须要在这个时间范围内，即返回广告的时间长度必须要大于等于min_playtime，小于等于 max_playtime。对于一个请求，dsp可以返回这个时间范围内的一只或者多支广告。在返回时间范围内的多支广告时，dsp自行处理好广告之间的互斥关系。如果返回广告的时长不满足此时长限制，该广告将被过滤，不参与竞价。

2.11 Dsp怎么获取自己的dsp_id和加解密token

在线上投放前，Dsp需要联系芒果TV的运营的同学开通账户。开通之后，可以自行登录管理后台，点击右上角的“修改个人资料”，查看dsp_id和token，其中token为dsp的加解密的秘钥。该秘钥的具体使用参见2.4

2.12 向Dsp发送的广告请求中，Device中的os和type的关系

os字段是直接由前端获取的数据，并未做任何处理；type字段是具体的设备请求类型，是经过具体的判断处理后的结果。由于os字段的复杂多变性，所以广告请求的设备类型以type字段为准，os字段供参考。

2.13 关于芒果流量问题的说明

目前分为rtb流量和首选交易流量。其中，rtb交易的流量是全部的流量，不对地域、终端类型和其他维度做任何区分，dsp在接收到rtb的流量后，可以自己做定向。首选交易的流量是可以做包括地域、广告类型，终端、视频级别、频道、合集等维度的定向，所以pdb的请求都是经过定向的流量。

2.14 关于请求中imp.pmp字段里at字段的说明

at字段表示竞价方式，其中0表示此次请求是pdb交易，1表示采用第一竞价法的首选交易。

2.15 关于Response中dealid字段的返回

Response中dealid字段表示DSP参与的交易，目前包括首选交易pd和pdb两种。当DSP参与pd或者pdb交易时，则需要返回对应的dealid。如果dealid为空，则表示参与的是rtb交易。

2.16 关于banner广告多种样式字段的说明

返回广告中可以自定义banner展示样式，具体的样式由 style 控制，click_action字段控制点击广告后的行为，分为 0-打开网页，1-下载应用。Title和AdDesc分别为banner广告的标题和广告的描述字段。同一个广告位可以支持多种样式，但必须满足以下条件：上图下文：标题必填，描述不填；纯图：标题和描述不填；左图右文：标题、描述必填；左图中文右按钮：标题、描述必填