[TOC]

1、前言

1.1、简介

美图程序化广告交易平台（以下简称“MAX”） 为DSP广告客户提供API接口，并支持PMP、RTB两种接入方式。本文档作为DSP与MAX进行对接的指引文档，主要包括两个部分：

• 整体对接流程：此部分主要描述了目前DSP与美图对接的流程，包含从开始对接到投放上线的一般流程。
• 程序化对接接口：此部分详细阐述了DSP与MAX的接口协议。

2、审核

2.1、送审

2.1.1、法律声明

客户在接入美图广告系统时，美图广告系统会向客户提供此文档，作为通过 API 审核素材的指引文档。未经美图广告系统许可，不得以任何形 式向第三方披露、泄露有关本文档的任何内容。美图广告系统拥有修改、调 整、增补本文档的权利，并在法律允许范围内对本文档拥有最终解释权。

2.2.2、修订历史

版本	修改日期	修改人	备注
1.0	2018.1.9	徐涛	接口文档创建
2.1	2018.2.12	徐涛	添加审核状态查看
2.2	2018.2.17	徐涛	添加 timestemp 字段
1.3	2018.5.3	徐涛	添加审核拒绝原因查看
1.4	2019.3.28	李燚	审核接口新增错误码 -3；新 增对接口请求次数上限的说明
1.5	2019.4.11	李燚	增加视频字段
1.6	2019.5.7	李燚	更换测试环境接口地址
1.7	2019.6.25	李燚	合并测试环境信息流和硬广接口地址
1.8	2019.10.24	秦晓鑫	新增推送字段 cover 及开屏视频数据举例
1.9	2020.12.17	李金阳	更换审核接口地址
1.9.1	2020.5.29	秦晓鑫	更新审核状态
2.10	2020.7.17	秦晓鑫	更新审核接口地址
2.11	2021.9.8	艾彩凤	PDF->网站
2.12	2023.10.11	艾彩凤	添加PDB模板ID字段
2.13	2023.12.7	艾彩凤	新增和修改接口返回错误码
2.14	2024.5.10	艾彩凤	更新错误码和接口限制注意事项

2.1.3、接口地址：

环境	地址
测试环境	http://stable-app.mis.bst.meitu.com/api/outpush
线上环境	https://api-mis.bst.meitu.com/api/outpush

2.1.4、接口参数：

参数名字	参数类型	说明	是否必填
token	string	生成方式 md5(固定字符串&每日零点零分零秒时间戳),使用timestamp参数的时间戳（秒）,例子md5(固定字符串&1715270400)，固定字符串值联系运营	必填
timestamp	string	每日零点零分零秒时间戳	必填
data[].ad_id	string	创意ID	必填
data[].os_type	string	平台=ios或者android	必填
data[].position_id	int	广告位ID，注意广告位ID不存在的会报错	必填
data[].link_instructions	string	跳转链接,最长3000字符	必填
data[].main	string	大图URL,最长3000字符
data[].icon	string	icon,即小图URL,最长3000字符
data[].video	string	视频URL,最长3000字符
data[].cover	string	封面URL,最长3000字符
data[].title	string	标题文案,最长30字符
data[].desc	string	描述文案,最长50字符
data[].ctatext	string	按钮文案,最长15字符
data[].ad_network_id	string	广告源标识，注意不存在的广告源会报错	必填
data[].third_template	string	模板标识，如,摇一摇=mt_shake_splash,滑动=mt_slide_splash,扭动=mt_new_shake_splash
data[].style_id	string	形式ID
data[].show_id	string	PDB模板ID	PDB必填

参数例子：

{
    "token":"552df064ef8310515f1a6a1a723864b7",
    "timestamp":"2.12738278",          //秒 生成token时使用的时间戳
    "data":[
        {
            "ad_id":1,  //广告ID
            "os_type":"android",  //手机系统
            "position_id":1,     //广告位ID(映射美图广告位的ID)
            "link_instructions":"我是点击跳转的目标链接",
            "main":"我是大图地址",
            "icon":"我是小图地址",
            "video":"我是视频地址",
            "cover":"我是封面图片地址",
            "title":"我是标题",
            "desc":"我是描述",
            "ctatext":"我是按钮",
            "ad_network_id":"广告源标识"
        },
        {
            "ad_id":2,
            "os_type":"ios",
            "position_id":2,
            "link_instructions":"http://www.meitu.com",
            "main":"http://mea.meitudata.com/kaiping-a013d44bce871fb945f9aacc3cf3a0f4-5993.jpg",
            "icon":"http://mea.meitudata.com/kaiping-e038a372.2a8c2ac0286f59da30a0fce-3721.jpg",
            "video":"http://mea.meitudata.com/kaiping-1631100008279.mp4",
            "cover":"http://mea.meitudata.com/kaiping-a013d44bce871fb945f9aacc3cf3a0f4-5993.jpg",
            "title":"我是标题",
            "desc":"我是描述",
            "ctatext":"我是按钮",
            "ad_network_id":"广告源标识"
        }
    ]
}

2.1.5、接口返回：

参数名字	参数类型	说明
error_code	int	默认值0
msg	string	默认值空

错误码详解：

错误值	含义	备注
0	success	推送成功
-1	token错误	校验失败
-1	token过期	校验失败
-2	参数不能为空
-2	每一次请求接口, data中的数据个数,不能大于20个ad_id
-2	data中广告源标识ad_network_id不能是空
-2	data中广告源标识ad_network_id的值不存在 或 不对
-2	data中创意IDad_id不能是空
-2	data中大图main，小图icon，视频video不能都是空
-2	data中广告位ID position_id值不对 或 不存在
-2	data中平台os_type值不对
-2	data中模板标识third_template值不对
-2	data中形式ID style_id值不对
-2	data中形式ID style_id的值,所对应的xx字段 不能为空
-2	某些特定源，data中PDB模板ID show_id不能是空
-2	某些特定源, data中PDB模板ID show_id值不对
-2	非特定源，data中PDB模板ID show_id不应该有值
-3	参数不是json格式
-3	联系运营人员找技术人员处理
-4	error: try catch exception	触发接口异常报错，联系运营人员找技术人员处理
-99	超出每日最大IP计数限制,联系运营人员
-99	超出每日广告源最大计数限制xxx个

返回例子：

{
    "error_code":0,
    "msg":""
}

2.1.6、注意事项：

1、关于请求审核接口返回 error ‘frequency error’的说明： 同一个 IP 一天只能请求审核 接口 1000 次，第二天自动重置。 2、不同广告ID的素材，不可以使用一个素材地址。

2.2、获取审核状态

2.2.1、法律声明

客户在接入美图广告系统时，美图广告系统会向客户提供此文档，作为通过 API 审核素材的指引文档。未经美图广告系统许可，不得以任何形 式向第三方披露、泄露有关本文档的任何内容。美图广告系统拥有修改、调 整、增补本文档的权利，并在法律允许范围内对本文档拥有最终解释权。

2.2.2、修订历史

版本	修改日期	修改人	备注
1.0	2018.1.9	徐涛	接口文档创建
2.1	2018.2.12	徐涛	添加审核状态查看
2.2	2018.2.17	徐涛	添加 timestemp 字段
1.3	2018.5.3	徐涛	添加审核拒绝原因查看
1.4	2019.3.28	李燚	审核接口新增错误码 -3；新 增对接口请求次数上限的说明
1.5	2019.4.11	李燚	增加视频字段
1.6	2019.5.7	李燚	更换测试环境接口地址
1.7	2019.6.25	李燚	合并测试环境信息流和硬广接口地址
1.8	2019.10.24	秦晓鑫	新增推送字段 cover 及开屏视频数据举例
1.9	2020.2.17	李金阳	更换审核接口地址
1.9.1	2020.5.29	秦晓鑫	更新审核状态
2.10	2020.7.17	秦晓鑫	更新审核接口地址
2.11	2021.9.8	艾彩凤	PDF->网站
2.12	2023.12.7	艾彩凤	新增和修改接口返回错误码
2.13	2024.5.10	艾彩凤	更新错误码和接口限制注意事项

2.2.3、接口地址：

环境	地址
测试环境	http://stable-app.mis.bst.meitu.com/api/getad
线上环境	https://api-mis.bst.meitu.com/api/getad

2.2.4、接口参数：

参数名字	参数类型	说明	是否必填
token	string	生成方式 md5(固定字符串&每日零点零分零秒时间戳),使用timestamp参数的时间戳（秒）,例子md5(固定字符串&1715270400)，固定字符串值联系运营	必填
timestamp	string	每日零点零分零秒时间戳	必填
data[].ad_id	string	创意ID	必填
data[].ad_network_id	string	广告源标识，注意不存在的广告源会报错	必填

返回例子：

{
    "token":"552df064ef8310515f1a6a1a723864b7",
    "timestamp":"2.12738278",      //秒 生成token时使用的时间戳
    "data":[
        {
            "ad_id":1,  //广告ID
            "ad_network_id":"广告源标识"
        },
        {
            "ad_id":2,
            "ad_network_id":"广告源标识"
        }
    ]
}

2.2.4、接口返回：

参数名字	参数类型	说明
ad_network_id	string	广告源标识
ad_id	int	广告ID
reason	string	审批拒绝的原因
status	string	状态文案：待审核、审核通过、审核拒绝

错误码详解：

错误值	含义	备注
0	success	推送成功
-1	token错误	校验失败
-1	token过期	校验失败
-2	参数data为空或者格式不对
-2	参数data中字段广告源标识ad_network_id为空
-2	参数data中字段创意IDad_id为空
-2	每一次请求接口, data中的数据个数,不能大于20个ad_id
-3	参数不是json格式
-4	error: try catch exception	触发接口异常报错
-99	超出每日最大IP计数限制,联系运营人员
-99	超出每日广告源最大计数限制xx个

返回例子：

{
    "error_code": 0 ,
    "msg":"",
    "data":[
        {
            "ad_id":1,
            "status": '审核拒绝',
            "reason": '拒绝原因',
            "ad_network_id":"广告源标识"
        },
        {
            "ad_id":1,
            "status": '审核通过',
            "ad_network_id":"广告源标识"
        },
    ]
}

2.2.5、拒绝原因：

1. 图片素材不符合规范
2. 不符合开屏或首页 icon 素材要求
3. 跳转链接无效
4. 竞品或禁投行业
5. 图片链接无效
6. 其他（手动填写原因）

2.2.6、注意：

1、关于请求查询接口返回 error ‘frequency error’的说明： 同一个 IP 一天只能请求 查询接口 3000 次，第二天自动重置。

3、对接

3.1、历史版本

版本	日期	修改内容	修改人	备注
1.0	2018/6/29	文档发布	李军、王乐
2.1	2018/10/15	增加 fallback 字段	李军、王乐
2.2	2018/12/14	增加视频相关请求	李军、王乐
1.3	2019/3/29	请求头去掉 content-type字段	李军、李燚
1.4	2019/4/11	返回示例补齐 video 内容	李军、李燚
1.5	2019/6/12	增加联盟流量	李军、李燚
1.6	2019/9/19	增加联盟请求和响应用例	李军、李燚
1.7	2019/12.19	1.请求图片枚举类型增加COVER 字段 2.增加 mac、did 字段 3.增加价格加解密例子	李军
1.8	2020/2/24	请求中增加 oaid	李军
1.9	2020/6/24	增加 app_name、vesion_code、package_name、detail_url字段	李军、徐诗惠
2.0	2020/7/28	增加支持小游戏(Game)以及素材类型字段	李军、徐诗惠
2.1	2021/4/27	增加支持小程序（Applet）投放以及素材类型字段	李军、徐诗惠
2.2	2021/7/6	增加点击监测注释内容	李军、徐诗惠
2.3	2021/12/9	增加 dplinktrackers 字段	李军、白格想
2.4	2022/5/22	返回增加模板 template_id 字段，请求增加 hms_version 和 hw_ag_version	李军、白格想
2.5	2022/08/01	增加下载监测	李军
2.6	2022/10/13	download 返回增加权限信息字段	李军
2.7	2023/08/28	新增trade_mode、campaign_date以及show_id字段	李军
2.8	2024/09/11	新增开屏视频预加载支持&去掉废弃不用的字段	李军
2.9	2024/10/09	新增视频播放监测	李军
2.10	2025/04/01	新增 sequence 字段	王莹莹

3.2、文档说明

本文档作为DSP与美图程序化广告交易平台（以下简称“MAX”）进行对接的指引文档。主要包括两个部分：

• 整体对接流程：此部分主要描述了目前DSP与美图对接的流程，包含从接触开始到投放上线的一般流程。
• 程序化对接：此部分详细阐述了DSP与MAX的接口协议。

3.3、整体对接流程

3.3.1、商务引入

有意愿和美图合作，经过商务或销售介绍，确认双方对接方式和结算方式，进入下一步合作。

3.3.2、同步信息

由商务或销售进行拉群，前期人员包含商务或销售，产品和技术，后期拉入运营和审核。包含文件为：

• 程序化对接文档
• 审核相关文档（竞品，审核）
• 审核对接文档
• 广告位说明

3.3.3、文档开发

DSP会根据我方文档进行开发，问题会在群中进行解答。

3.3.4、对接测试

文档开发完成后，双方进行测试，测试分为以下两个阶段：

• 测试环境：需要测试数据传输以及效果展示。
• 线上环境：需要双方进行数据测试，确保双方数据差异在合理范围之内。

3.3.5、正式投放

测试完成后，会转入线上的正式投放。目前采取的是先审后投的原则，素材要首先通过接口传到美图的审核中心进行审核。审核通过后，素材可用于投放（特殊位置需要客户端同时进行审核）广告开关有运营在群中接到通知后，打开流量。

3.3.6、数据结算

每月会由结算组取得广告数据，和第三方比对数据。差异范围之内，按预先约定好的价格进行结算。差异范围外，要首先进行排查，之后再进行结算。

3.4、程序化对接

对接流程示意图

1、请求广告: 媒体出现展示机会，向美图程序化广告交易平台（后简称MAX）发送广告请求。 2、Bid Request: MAX 向 DSP 发送广告请求。 3、Bid Response: DSP 将出价信息及素材信息返回 MAX。 4、Win Notice: MAX 向获得该流量的 DSP 发送 Win Notice。 5、广告返回: MAX 将该 DSP 返回的广告素材返回到媒体端。 6、广告展示并上报数据：媒体端接受展示素材，展示广告并进行数据上报。

3.4.1、通信方式

MAX 和 DSP 之间的基础通信协议采用 HTTP 协议，使用 POST 方法发送 Bid Request 消息，数据使用 Protobuf 格式，Bid Request 序列化之后作为 HTTP 请求的 Content 来发送。响应的时候Bid Resopnse 序列化之后作为 HTTP 响应的 Content 来返回。

3.4.2、编码方式

若无特殊说明，所有输入参数、返回结果中的字节编码全部使用 UTF-8（无BOM头）。

3.4.3、HTTP请求头

• Content-Type：application/x-protobuf

3.4.4、HTTP响应

如果有广告返回，返回码为 200，Content-Type：application/x-protobuf，content 为 Bid Response 序列化之后的二进制数据。如果不返回广告，则返回码204。

3.4.5、超时时间

美图程序化交易平台向 DSP 发送请求到 DSP 返回相应的时间：200ms。超时部分视为 DSP 放弃本次出价。

3.5、消息定义

3.5.1、Bid Request消息结构图

3.5.2、Bid Request

Bid Request类型

field	scope	type	default	description
id	required	string		请求的唯一id
imp	repeated	Imp		广告的展示相关信息，每个imp代表一个广告位的请求
app	optional	App		App的信息
device	optional	Device		用户的设备信息
user	optional	User		用户信息(暂未用)
test	optional	bool	false	该次请求是否为测试请求，0 非测试请求
proto_version	optional	string	1.0.0	proto协议的版本号
is_affiliate	optional	int32	0	流量类型：1代表联盟流量；0代表美图系app流量
trade_mode	optional	string		如果为PDB则代表PDB流量，否则其他流量

Imp类型

field	scope	type	default	description
id	required	string		Bid Request范围内，imp的唯一标记
banner	optional	Banner		banner 对象
tagid	optional	string		广告位id
bidfloor	optional	double		广告位的CPM底价, 单位: 分
native	optional	Native		原生广告对象,返回素材为图片地址，文字标题等元素
pmp	optional	Pmp		pmp（私有市场交易）对象，只有在请求Pmp广告时候才使用
style_ids	repeated	string		广告样式列表
campaign_date	optional	string		展示的日期，用以进行预缓存使用，对于PDB在当天直接进行展示以及预加载类广告需要加载的日期
show_id	optional	string		PDB模板id

Native类型

field	scope	type	default	description
request_native	oneof	NativeRequest		原生对象
ver	optional	string		OpenRTB中native广告协议版本号, "1.0" 对应 OpenRTB 2.3; "1.1" 对应 OpenRTB 2.4

Pmp类型

field	scope	type	default	description
private_auction	optional	bool	false	Deal对象可得性, 0 => 所有bid均可得, 1 => bid由deal限定
deals	repeated	Deal		Deal数组，用来表示此次请求的一些信息

Deal类型

field	scope	type	default	description
id	required	string		deal id，PMP 投放线下约定的合同号,当请求符合合同约定，则为对应的合同号
bidfloor	optional	double	0	CPM底价, 单位: 分

Video类型

field	scope	type	default	description
w	optional	int32		视频宽
h	optional	int32		视频高

App类型

field	scope	type	default	description
id	optional	string		app id
name	optional	string		app name
domain	optional	string		app 官网域名
ver	optional	string		app 版本号
bundle	optional	string		Android: 包名; iOS: ID

Device类型

field	scope	type	default	description
dnt	optional	bool		1 => 开启了do not track, 0 => 未设置或未开启do not track
ua	optional	string		客户端的UserAgent
ip	optional	string		客户端真实的外网IP地址
geo	optional	Geo		地理位置信息
didsha1	optional	string		SHA1加密的硬件设备ID(IMEI), 字母采用小写形式
didmd5	optional	string		MD5加密的硬件设备ID(IMEI), 字母采用小写形式
dpidsha1	optional	string		SHA1加密的平台设备ID(Android ID), 字母采用小写形式
dpidmd5	optional	string		MD5加密的平台设备ID(Android ID), 字母采用小写形式
ipv6	optional	string		ipv6
carrier	optional	string		运营商 46000:中国移动 46001:中国联通 46002:中国电信
language	optional	string		浏览器语言, ISO-639-1-alpha-2
make	optional	string		设备厂商 ("Apple")
model	optional	string		设备型号 ("iPhone")
os	optional	string		设备操作系统 ("iOS", "android")
osv	optional	string		设备操作系统版本号,如10.0.1
hwv	optional	string		设备硬件版本 ("5S" 对应 iPhone 5S)
w	optional	int32		设备的宽的物理像素数
h	optional	int32		设备的高的物理像素数
connectiontype	optional	ConnectionType		网络连接类型，包括(CONNECTION_UNKNOWN、ETHERNET、WIFI、CELL_UNKNOWN、CELL_2G、CELL_3G、CELL_4G、CELL_5G)
ifa	optional	string		Android ID明文或IDFA明文, 或者其他SDK可取得的ID, 字母采用小写形式
macsha1	optional	string		SHA1加密的MAC地址, 字母采用小写形式
macmd5	optional	string		MD5加密的MAC地址, 字母采用小写形式 注：对于联盟流量，此字段为明文mac
mac	optional	string		明文mac，只有在联盟流量时候才会有值
did	optional	string		明文imei, 只有在联盟流量时候才会有值
oaid	optional	string		oaid
caid	optional	string		caid
aaid	optional	string		aaid
hms_version	optional	string		华为 hms 版本
hw_ag_version	optional	string		华为 ag 版本
birth_time	optional	string		ios设备初始化时间
update_time	optional	string		ios设备的系统更新时间
boot_time	optional	string		ios设备的系统启动时间
update_mark	optional	string		系统更新标识，用c++代码获取 data/data 目录的存取执行时间加修改时间，形成的字符串 例如：iOS:581141691.57041958 Android:1004697.709999999
boot_mark	optional	string		系统启动标识bootid，每次开机都会产生一个唯一的ID 例如：iOS:1623815045.970028；Android:ec7f4f33-411a-47bc-8067-744a4e7e0723

Geo类型

field	scope	type	default	description
lat	optional	double		地理位置，纬度
lon	optional	double		地理位置，经度
country	optional	string		国家, ISO-3166-1 Alpha-3编码

User类型

field	scope	type	default	description
id	optional	string		用户id，对于每一个user，在exchange中都有一个唯一id
gender	optional	string		性别，M表示男，F代表女，O代表其他，如果不填则代表未知
keywords	optional	string		以逗号分隔的用户的关键词、兴趣或者倾向
geo	optional	Geo		用户所在的地理位置
sequence	optional	string		序列参考

NativeRequest类型

field	scope	type	default	description
ver	optional	string		OpenRTB中native广告协议版本号,"1.0" 对应 OpenRTB 2.3; "1.1" 对应 OpenRTB 2.4
assets	repeated	Asset		本次请求的素材信息

Asset类型

field	scope	type	default	description
id	required	int32		1:小图 2:大图 3:标题 4:描述 5:点击按钮文字 8:视频 9:封面图 10:组图
title	oneof	Title		标题(只能取title、img、data其中一个)
img	oneof	Img		图片(只能取title、img、data其中一个)
data	oneof	Data		其他文字等数据(只能取title、img、data其中一个)
Video	oneof	Video		视频

Title类型

field	scope	type	default	description
len	required	int32		最大支持的标题长度

Img类型

field	scope	type	default	description
type	optional	ImageAssetType		1:icon 2:logo 3:main 4:cover
w	optional	int32		所需图片的宽
h	optional	int32		所需图片的高

Date类型

field	scope	type	default	description
type	optional	DataAssetType		2:描述 12:点击按钮文字 具体含义参考proto
len	optional	int32		所需的最大长度

Video类型

field	scope	type	default	description
url	required	string		视频素材链接
duration	optional	int32		视频时长
w	optional	int32		视频宽
h	optional	int32		视频高

3.5.3、Bid Request 示例

• 常规流量请求样例：

{
  "id": "D1C3568E-DC83-40BD-B1EE-4AC742BC6B75",
  "imp": [
    {
      "id": "5e2d4540-342c-493a-98ee-1c618b0247f7",
      "tagid": "176",
      "bidfloor": 1200,
      "pmp": {
        "deals": [
          {
            "id": "meitu_xxx",
            "bidfloor": 1200
          }
        ]
      },
      "native": {
        "request_native": {
          "assets": [
            {
              "id": 2,
              "img": {
                "type": 3,
                "w": 640,
                "h": 900
              }
            }
          ]
        }
      }
    }
  ],
  "app": {
    "ver": "6.9.7",
    "bundle": "com.meitu.mtxx"
  },
  "device": {
    "ua": "Mozilla/5.0 (iPhone; CPU iPhone OS 11_4 like Mac OS X) AppleWebKit/6 05.1.15 (KHTML, like Gecko) Mobile/15F79 CreativeMall/6.9.7com.meitu.mtxx/6.9. 7 (iOS11.4)/lang:zh_CN",
    "ip": "222.83.132.149",
    "didsha1": "2cb6f19163b80dbd37a2fb195113b89ee1c37a86",
    "didmd5": "7f431997b410a9dd05bc1aab1e8f0772",
    "carrier": "460",
    "language": "zh-Hans-CN",
    "model": "iPhone8,1",
    "os": "iOS",
    "osv": "11.4",
    "connectiontype": 2,
    "ifa": "89AAFF34-3B25-48FB-843D-4AF47BC52DC3",
    "macsha1": "c1976429369bfe063ed8b3409db7c7e7d87196d9",
    "macmd5": "0f607264fc6318a92b9e13c65db7cd3c"
  }
}

• PDB流量请求样式：

{
  "id": "e3af4087-0886-4fca-bc6b-ffe622556a98",
  "imp": [
    {
      "id": "17938b9f-c7ad-4405-8991-81ea6a6228d7",
      "tagid": "40",
      "bidfloor": 3000,
      "iframebuster": [

      ],
      "pmp": {
        "deals": [
          {
            "id": "meitu_xxx",
            "bidfloor": 3000,
            "wseat": [

            ],
            "wadomain": [

            ]
          }
        ]
      },
      "native": {
        "request_native": {
          "assets": [
            {
              "id": 2,
              "img": {
                "type": 3,
                "w": 1440,
                "h": 1938,
                "mimes": [

                ]
              }
            }
          ]
        },
        "api": [

        ],
        "battr": [

        ]
      },
      "style_ids": [
        "1",
        "6",
        "15"
      ],
      "campaign_date": "20230818",
      "show_id":"10001"
    },
    {
      "id": "bae51257-357a-4f37-8f88-1d40e8ddd11d",
      "tagid": "40",
      "bidfloor": 3000,
      "iframebuster": [

      ],
      "pmp": {
        "deals": [
          {
            "id": "meitu_xxx",
            "bidfloor": 3000,
            "wseat": [

            ],
            "wadomain": [

            ]
          }
        ]
      },
      "native": {
        "request_native": {
          "assets": [
            {
              "id": 2,
              "img": {
                "type": 3,
                "w": 1440,
                "h": 1938,
                "mimes": [

                ]
              }
            }
          ]
        },
        "api": [

        ],
        "battr": [

        ]
      },
      "style_ids": [
        "1",
        "6",
        "15"
      ],
      "campaign_date": "20230819",
      "show_id":"10001"
    },
    {
      "id": "5ae997c9-832d-4986-8656-aab3057259a3",
      "tagid": "40",
      "bidfloor": 3000,
      "iframebuster": [

      ],
      "pmp": {
        "deals": [
          {
            "id": "meitu_xxx",
            "bidfloor": 3000,
            "wseat": [

            ],
            "wadomain": [

            ]
          }
        ]
      },
      "native": {
        "request_native": {
          "assets": [
            {
              "id": 2,
              "img": {
                "type": 3,
                "w": 1440,
                "h": 1938,
                "mimes": [

                ]
              }
            }
          ]
        },
        "api": [

        ],
        "battr": [

        ]
      },
      "style_ids": [
        "1",
        "6",
        "15"
      ],
      "campaign_date": "20230820",
      "show_id":"10001"
    }
  ],
  "app": {
    "name": "mtxx",
    "ver": "9.9.6.0",
    "bundle": "com.mt.mtxx.mtxx"
  },
  "device": {
    "ua": "Mozilla/5.0 (Linux; Android 12; M2012K11AC Build/SKQ1.211006.001; wv) AppleWebKit/537.36 (KHTML, like Gecko) Version/4.0 Chrome/105.0.5195.136 Mobile Safari/537.36",
    "ip": "110.86.31.122",
    "geo": {
      "lat": 24.6023,
      "lon": 118.011,
      "accuracy": 100,
      "provider": 2
    },
    "didsha1": "da39a3ee5e6b4b0d3255bfef95601890afd80709",
    "carrier": "46001",
    "language": "cn",
    "make": "Redmi",
    "model": "M2012K11AC",
    "os": "android",
    "osv": "12",
    "w": 1080,
    "h": 2276,
    "connectiontype": 2,
    "ifa": "d1e8e3b16ba1e740",
    "oaid": "7b32cf01e594afe0",
    "update_mark": "1692330800.327316377",
    "boot_mark": "15c63a8c-fd37-43aa-b7d8-511da6ee1868"
  }
}

• 视频预加载请求样例

{
  "id": "1fdcb3ee-119f-41f4-becb-ec16d13527af",
  "imp": [
    {
      "id": "24353945-79c8-48e2-bdec-c4146d9ea30a",
      "tagid": "72",
      "bidfloor": 3000,
      "iframebuster": [
        
      ],
      "pmp": {
        "deals": [
          {
            "id": "xxx",
            "bidfloor": 3000,
            "wseat": [
              
            ],
            "wadomain": [
              
            ]
          }
        ]
      },
      "style_ids": [
        "6",
        "15"
      ],
      "campaign_date": "20240909"
    },
    {
      "id": "819caa5c-2be7-494c-b17b-5532d1c7c842",
      "tagid": "72",
      "bidfloor": 3000,
      "iframebuster": [
        
      ],
      "pmp": {
        "deals": [
          {
            "id": "xxx",
            "bidfloor": 3000,
            "wseat": [
              
            ],
            "wadomain": [
              
            ]
          }
        ]
      },
      "style_ids": [
        "6",
        "15"
      ],
      "campaign_date": "20240910"
    },
    {
      "id": "2442054f-5937-4eb9-8b7a-c6f335c13ed0",
      "tagid": "72",
      "bidfloor": 3000,
      "iframebuster": [
        
      ],
      "pmp": {
        "deals": [
          {
            "id": "xxx",
            "bidfloor": 3000
          }
        ]
      },
      "style_ids": [
        "6",
        "15"
      ],
      "campaign_date": "20240911"
    }
  ],
  "app": {
    "name": "meiyancamera",
    "ver": "12.1.80",
    "bundle": "com.meitu.meiyancamera"
  },
  "device": {
    "ua": "Mozilla/5.0 (Linux; Android 14; V2203A Build/UP1A.231005.007; wv) AppleWebKit/537.36 (KHTML, like Gecko) Version/4.0 Chrome/116.0.0.0 Mobile Safari/537.36",
    "ip": "36.110.46.98",
    "geo": {
      "lat": 39.9389,
      "lon": 116.397,
      "accuracy": 100,
      "provider": 2
    },
    "didsha1": "da39a3ee5e6b4b0d3255bfef95601890afd80709",
    "carrier": "null",
    "language": "cn",
    "make": "vivo",
    "model": "V2203A",
    "os": "android",
    "osv": "14",
    "w": 1080,
    "h": 2318,
    "connectiontype": 2,
    "ifa": "e8de0554457ba527",
    "oaid": "420dcb495777fb4724c4881eb665beda46007b8d0279a91aede542a0224feb76",
    "update_mark": "1725880857.153616709",
    "boot_mark": "3ea8bee5-f004-408d-8509-99610f1a268f"
  }
}

视频预加载一次请求3天，即今天、明天和后天，每天对应一个imp结构，imp.campaign_date代表对应天的日期

3.5.4、Bid Response消息结构图

3.5.5、Bid Response

Bid Response类型

field	scope	type	default	description
id	required	string		与bid request中的id一致
seatbid	repeated	SeatBid		DSP方的出价集合，每个seatbid对应bid request中的一个imp
bidid	optional	string		买方bid id，用以记录和跟踪此次交易
nbr	optional	NoBidReason		0:UNKNOWN_ERROR 1:TECHNICAL_ERROR 2:INVALID_REQUEST 3:KNOWN_WEB_SPIDER 4:SUSPECTED_NONHUMAN_TRAFFIC 5:CLOUD_DATACENTER_PROXYIP 6:UNSUPPORTED_DEVICE 7:BLOCKED_PUBLISHER 8:UNMATCHED_USER

SeatBid类型

field	scope	type	default	description
bid	repeated	Bid		每个bid对应request中的一个imp
seat	optional	string		广告主id

Bid类型

field	scope	type	default	description
id	required	string		买方生成的id，用以记录和跟踪
impid	required	string		与bid request中的imp.id对应
price	required	double		出价（CPM，单位分）
adid	required	string		广告id
nurl	optional	string		win notice url
adm	oneof	string		废弃不使用
adm_native	oneof	NativeResponse		Native广告的响应
crid	optional	string		创意id，如果是送审的创意，此id对应送审时候的id，否则会被过滤
dealid	optional	string		与BidRequest中的 Pmp.Deal.id一致
style_id	optional	string		样式类型
creative_type	optional	int32		素材类型 1：图片/图文 2：视频 3：激励视频如果为激励视频，则此字段必填
template_id	optional	string		摇一摇或者滑动等
campaign_date	optional	string		展示的日期，用以进行预缓存使用，对于PDB在当天直接进行展示
show_id	optional	string		PDB模板id，返回此字段务必跟请求中的一致，如果不一致则使用请求中的

NativeResponse类型

field	scope	type	default	description
assets	repeated	Asset		与请求中的asset一致
link	optional	Link
imptrackers	repeated	string

NativeResponse.Asset类型

field	scope	type	default	description
id	required	int32		必须与NativeRequest.Asset.id一致
title	oneof	Title		标题
img	oneof	Img		图片
data	oneof	Data		描述、点击文字等
link	optional	Link		落地页相关
video	oneof	Video		视频
groupimg	oneof	Img		组图

NativeResponse.Asset.Title类型

field	scope	type	default	description
text	required	string		标题文字

NativeResponse.Asset.Img类型

field	scope	type	default	description
url	required	string		图片url
w	optional	int32		返回图片的宽
h	optional	int32		返回图片的高

NativeResponse.Asset.Data类型

field	scope	type	default	description
value	required	string		返回的文字或者描述等

NativeResponse.Asset.Video类型

field	scope	type	default	description
url	required	string		视频素材链接
duration	optional	int32		视频时长
w	optional	int32		视频宽
h	optional	int32		视频高
playtrackers	repeated	PlayTracker		视频监测

NativeResponse.Asset.Video.PlayTracker类型

field	scope	type	description
duration	optional	int32	时间，单位为秒
play_tracker_url	repeated	string	duration秒时候的监测链接。示例：如果duration为2，那么此字段为播放至2秒时候的上报链接

Link类型

field	scope	type	default	description
url	required	string		落地页（包含deeplink和ulk）
clicktrackers	repeated	string		点击监测，需注意 iOS 端不要返回%%类型，否则无法解析上报
fallback	optional	string		备用链接（deeplink执行失败时调用）
download	optional	Download		下载类广告,若需走下载管理器，则必填
game	optional	Game		小游戏类型广告，如果为小游戏广告，则必填
applet	optional	Applet		小程序类型广告，如果为小程序广告，则必填
dplinktrackers	repeated	string		deeplink 唤起结果监测链接；链接需拼接宏定义：__DP_RESULT__'：用于接收 deeplink 唤起结果，0=“成功”，1=“失败”；__DP_REASON__：用于接收 deeplink 唤起失败原因，1=“打开备用 H5”；2=“唤起异常”；

Link.Download类型

field	scope	type	default	description
package_name	required	string		下载包名
version_code	required	string		下载包版本号
app_name	required	string		应用名称
detail_url	optional	string		下载详情页地址，选填
download_begin_url	optional	string		客户端开始下载时上报
download_succ_url	optional	string		客户端下载完成时上报
install_begin_url	optional	string		客户端开始安装时上报
install_succ_url	optional	string		客户端完成安装时上报
app_permission	repeated	AppPermission		应用权限信息
app_privacy_policy_url	optional	string		应用隐私协议地址
app_developer	optional	string		应用开发者名称
app_icon_url	optional	string		应用 icon 地址
app_size	optional	string		应用大小，单位 KB

Link.Download.AppPermission类型

field	scope	type	default	description
permission_type	optional	int32	1	0 代表隐私权限，1 代表常规权限
describe	optional	string		权限描述
title	optional	string		权限标题

Link.Game类型

field	scope	type	default	description
type	required	string		游戏类型如：微信小游戏、H5小游戏等，取值分别为：wechatgame，h5game
platform	optional	string		游戏平台
id	required	string		游戏id
url	required	string		游戏地址
subpack_url	optional	string		游戏子包地址
ad_config_id	required	string		广告位配置id

Link.Applet类型

field	scope	type	default	description
username	required	string		小程序 ID（小程序原始ID）
type	required	string		小程序环境（0-正式版，1-开发版，2-体验版）
path	required	string		小程序地址

3.5.6、Bid Response 示例

• 常规流量：

{
  "id": "D1C3568E-DC83-40BD-B1EE-4AC742BC6B75",
  "seatbid": [
    {
      "bid": [
        {
          "id": "1",
          "impid": "5e2d4540-342c-493a-98ee-1c618b0247f7",
          "price": 1200,
          "nurl": "http://xxx.com",
          "adm_native": {
            "assets": [
              {
                "id": 3,
                "title": {
                  "text": "标题"
                }
              },
              {
                "id": 2,
                "img": {
                  "url": "https://大图.jpg",
                  "w": 640,
                  "h": 900
                }
              },
              {
                "id": 1,
                "img": {
                  "url": "https://小图.jpg",
                  "w": 100,
                  "h": 100
                }
              },
              {
                "id": 4,
                "data": {
                  "value": "描述"
                }
              },
              {
                "id": 5,
                "data": {
                  "value": "点击按钮文字"
                }
              },
              {
                "id": 8,
                "url": "http://xxx.com",
                "duration": 30,
                "w": 540,
                "h": 960
              }
            ],
            "link": {
              "url": "http://xxx.com",
              "clicktrackers": [

              ]
            },
            "imptrackers": [

            ]
          },
          "adomain": [

          ],
          "cat": [

          ],
          "attr": [

          ],
          "dealid": "meitu_xxx",
          "imp_track_urls": [
            "http://xxx.com"
          ],
          "clk_through_url": "http://xxx.com"
        }
      ]
    }
  ]
}

• PDB响应样例

{
  "id": "e3af4087-0886-4fca-bc6b-ffe622556a98",
  "seatbid": [
    {
      "bid": [
        {
          "id": "SmqmpFGLiK",
          "impid": "17938b9f-c7ad-4405-8991-81ea6a6228d7",
          "price": 1000,
          "adid": "xxx",
          "adm_native": {
            "assets": [
              {
                "id": 2,
                "img": {
                  "url": "xxx"
                }
              }
            ],
            "link": {
              "url": "xxx",
              "clicktrackers": [
                "xxx"
              ],
              "dplinktrackers": [

              ]
            },
            "imptrackers": [
              "xxx"
            ]
          },
          "adomain": [

          ],
          "crid": "xxx",
          "cat": [

          ],
          "attr": [

          ],
          "dealid": "xxx",
          "imp_track_urls": [

          ],
          "campaign_date": "20230818",
          "show_id": "10001"
        },
        {
          "id": "SmqmpFqAln",
          "impid": "bae51257-357a-4f37-8f88-1d40e8ddd11d",
          "price": 1000,
          "adid": "xxx",
          "adm_native": {
            "assets": [
              {
                "id": 2,
                "img": {
                  "url": "xxx"
                }
              }
            ],
            "link": {
              "url": "xxx",
              "clicktrackers": [
                "xxx"
              ],
              "dplinktrackers": [

              ]
            },
            "imptrackers": [
              "xxx"
            ]
          },
          "adomain": [

          ],
          "crid": "xxx",
          "cat": [

          ],
          "attr": [

          ],
          "dealid": "xxx",
          "imp_track_urls": [

          ],
          "campaign_date": "20230819",
          "show_id": "10001"
        },
        {
          "id": "SmqmpFqysf",
          "impid": "5ae997c9-832d-4986-8656-aab3057259a3",
          "price": 1000,
          "adid": "xxx",
          "adm_native": {
            "assets": [
              {
                "id": 2,
                "img": {
                  "url": "xxx"
                }
              }
            ],
            "link": {
              "url": "xxx",
              "clicktrackers": [
                "xxx"
              ],
              "dplinktrackers": [

              ]
            },
            "imptrackers": [
              "xxx"
            ]
          },
          "adomain": [

          ],
          "crid": "xxx",
          "cat": [

          ],
          "attr": [

          ],
          "dealid": "xxx",
          "imp_track_urls": [

          ],
          "campaign_date": "20230820",
          "show_id": "10001"
        }
      ],
      "group": false
    }
  ],
  "bidid": "82a4692e16f2181146a2febaea30de20"
}

注：PDB流量必须返回campaign_date和show_id

• 视频预加载返回样例

{
  "id": "E25FF06E-A105-4B2A-8EF6-980642A99368",
  "seatbid": [
    {
      "bid": [
        {
          "id": "oJhYMJNz8A",
          "impid": "5e665e48-420c-4236-b69f-64d9f2d85502",
          "price": 1000,
          "adid": "xxx",
          "adm_native": {
            "link": {
              "url": "https://m.tb.cn/h.gltObN6",
              "clicktrackers": [
                "http://xxx"
              ]
            },
            "imptrackers": [
              "http://xxx"
            ]
          },
          "crid": "xxx",
          "dealid": "xxx",
          "template_id": "mt_new_shake_splash",
          "campaign_date": "20240909"
        },
        {
          "id": "oJhYMJT71X",
          "impid": "5e665e48-420c-4236-b69f-64d9f2d85502",
          "price": 1000,
          "adid": "xxx",
          "crid": "xxx",
          "dealid": "xxx",
          "template_id": "mt_new_shake_splash",
          "campaign_date": "20240910"
        },
        {
          "id": "oJhYMiZzyN",
          "impid": "5e665e48-420c-4236-b69f-64d9f2d85502",
          "price": 1000,
          "adid": "xxx",
          "crid": "xxx",
          "dealid": "xxx",
          "template_id": "mt_new_shake_splash",
          "campaign_date": "20240911"
        }
      ],
      "group": false
    }
  ],
  "bidid": "7250aa0835811fdaf38a5b81425bd412"
}

需要注意以下几点：

• 每个bid结构对应请求中的imp结构(与常规流量一致)
• 每个bid结构中需要设置对应的campaign_date，即需要预加载的日期（如果非当天，只做预加载，不会自行曝光，到了日期当天，会再次请求，由广告主来决定是否曝光）
• 对于当天的bid，只需要返回crid和对应的落地页和监测地址，相应的asset等不需要返回；对于非当天的，只需要返回crid，落地页、监测地址以及asset不需要返回
• 如返回的bid中没有campaign_date，则美图方会当作当天曝光处理

3.6、价格加密

https://developers.google.cn/ad-exchange/rtb/response-guide/decrypt-price

Ikey：be980f628658b114d500a322eb222dec Ekey: ce7a8033fc93417e88dddabf34cc703f

例子： price: 994 W0MurQAE0MEAAAAAAAAAAB95lZS2Do1SAA7qCw== price: 995 W0MurQAE0RoAAAAAAAAAAFrRhSPycjXQk6Wpww== price: 996 W0MurQAE0TsAAAAAAAAAAIyVqvVgIk7wra1pTQ== price: 997 W0MurQAE0XIAAAAAAAAAAEqJkV5t0x_Tkg2BzQ== price: 998 W0MurQAE0i8AAAAAAAAAAN-QM4Hh2IrU1WDrwg== price: 999 W0MurQAE0r8AAAAAAAAAAOoDtBInJWFvEIlZ3g== price: 1000 W0MurQAE0s4AAAAAAAAAAAWTs0rwjfs7ni6IVA==

3.7、附件

meitu-bidding.proto (opens new window)