SSP DSP 竞价对接指南

本文说明 DSP 如何接收 SSP 的实时竞价请求、返回广告，以及处理监测和成交价。适用于已完成 DSP 账号、广告主和素材审核的接入方。

1. 对接概览

一次竞价分四步：

SSP 用 POST 把 BidRequest 发给 DSP 的 bid_url。
DSP 有出价时返回 HTTP 200 和 BidResponse；无出价返回 HTTP 204。
SSP 校验价格和素材，胜出后把广告交回媒体。
曝光、点击发生时，SSP 先记自己的监测，再回调 DSP 的监测地址，并替换成交价宏。

SSP 会并发请求所有通过流量过滤的 DSP。超时、5xx、响应解析失败都算本次无效出价。

2. 广告形态

广告形态看请求里实际带了哪个对象：

请求对象	广告形态
`imp.banner`	页面广告：信息流、开机图、猜你喜欢、视频关联位、焦点图、巨幕
`imp.video`	框内广告：贴片、暂停、通用浮层、触点
`imp.native`	原生广告

广告位、行业和模板的取值见对接时提供的字典，接口本身不硬编码。

3. DSP 需要提供什么

接入前向 SSP 提供三项：

项目	要求
竞价地址 `bid_url`	公网可访问，例如 `https://dsp.example.com/bid`，支持长连接
获胜通知地址	用于曝光回调，建议和 `bid.adm.win_notice_url` 使用同一套
最大 QPS	DSP 能稳定承受的每秒请求数，超出会被丢弃

请求约定：

方法 POST，请求头 Content-Type: application/x-protobuf。
请求体是 BidRequest 的 Protobuf 二进制，不是 JSON。
响应时间按平均低于 120ms 准备。SSP 下发的超时更短时，以 SSP 的超时为准。
开启 gzip 时，请求体为压缩后的 Protobuf，带 Content-Encoding: gzip 和 Accept-Encoding: gzip；响应也可以用 Content-Encoding: gzip 返回。

4. 竞价请求

4.1 BidRequest

字段	类型	说明
`id`	string	本次请求的唯一标识，原样回传到响应 `id`
`user`	User	用户信息
`site`	Site	站点、包名和内容
`device`	Device	设备信息
`imp`	Impression，可重复	广告位曝光机会，一次请求可有多个
`source_id`	int32	流量来源，取值为 `3`
`m_id`	string	合作方 ID

4.2 Impression

字段	类型	说明
`id`	string	本次曝光机会的标识。响应 `bid.impid` 必须回传它
`banner`	Banner	页面广告。和 `video`、`native` 三选一出现
`video`	Video	贴片、暂停、浮层等框内广告
`native`	Native	原生广告
`bidfloor`	int32	CPM 底价，单位分。出价应不低于它
`is_pmp`	bool	仅 PD 流量下发，`true` 表示 PD
`pmp`	Pmp	仅 PD 流量下发，里面是订单
`extended_ads_position`	int32	是否支持 5 秒广告。`0` 不支持，`1` 正一，`2` 倒一，`3` 都支持
`impression_date`	int32	开机屏预加载的预计曝光日期。有此字段是预加载，一般提前 1 到 3 天；没有则是实时请求
`info_stream_max_bids_allowed`	int32	信息流单次允许返回的广告数。大于 1 时可以返回多个

floor_price 按行业分底价，当前不下发，底价以 bidfloor 为准。

框内广告看 video：

字段	类型	说明
`ad_zone_id`	string	广告位 ID，取值见广告位字典
`linearity`	int32	`1` 串行在正片中，`2` 不是
`ad_type`	int32	广告类型，见第 9 节
`minduration` / `maxduration`	int32	素材时长范围，单位秒。返回的素材不能超出
`protocol`	int32	协议版本号
`startdelay`	int32	广告从第几秒开始
`is_entire_roll`	bool	是否为完整流量
`video_startdelay`	int32	播放进度，单位秒

页面广告看 banner：

字段	类型	说明
`ad_zone_id`	string	广告位 ID
`ad_type`	int32	广告类型，见第 9 节
`creative_template`	int64，可重复	当前可投放的创意模板，含快速审核模板

4.4 用户、站点与内容

user：

字段	类型	说明
`id`	string	用户 ID。网页端取 cookie；iOS 取 idfa、openudid、mac；Android 取 imei、android id、mac；电视取 mac
`is_privacy_protected`	bool	为真时该用户的隐私应被保护，不要用其标识做定向

site：

字段	类型	说明
`id`	int32	站点 ID
`app_bundle_id`	string	应用包名
`content`	Content	网站或视频内容

content：

字段	类型	说明
`title`	string	标题
`url`	string	网址
`keyword`	string，可重复	关键字
`len`	int32	视频时长
`album_id`	int64	剧目
`channel_id`	int64	频道 ID，原样转发
`tag`	string，可重复	场景广告（通用浮层、创可贴）的识别标签
`video_tag`	int64，可重复	视频定向标签
`video_clip_id`	string	本次请求的点位，场景广告专用

4.5 Device

字段	类型	说明
`ua`	string	User-Agent。App 流量不传
`ip` / `ipv6`	string	设备 IP，使用广协 IP 库
`geo`	Geo	地域。`country`、`metro`（省）、`city` 都是广协地域编码
`connection_type`	int32	网络，见第 9 节
`platform_id`	int32	平台，见第 9 节
`os` / `os_version`	string	操作系统及版本，如 `android`、`6.0.1`
`model`	string	机型，如 `iPhone 15.1`
`manufacturer`	string	厂商，如 `huawei`、`xiaomi`
`app_version`	string	App 版本
`screen_width` / `screen_height`	int32	屏幕分辨率，单位像素
`carrier_name`	string	运营商，UTF-8

设备标识按系统不同：

字段	适用	取值
`idfa`	iOS	原值
`idfv`	iOS	原值
`openudid`	iOS	原值
`caid_info`	iOS	广协 CAID。内含多个版本，每项有 `version` 和 `caid`
`imei`	Android	MD5 后的值
`android_id`	Android	原值
`oaid`	Android	原值。Android Q 及以上取不到时为空
`mac`	通用	去掉冒号后 MD5

iOS 还可能带 local_timezone、os_update_time、startup_time（微秒时间戳）、cpu_num、disk_total、mem_total，以及 auth_status：-1 无法获取，0 未弹窗，1 受限，2 拒绝，3 已授权。

这些标识只用于当次已授权的实时决策，不要落成未脱敏日志，也不要用于接口约定以外的用途。

4.6 PD 流量

imp.is_pmp 为真时才是 PD，此时读 imp.pmp.deals：

字段	类型	说明
`deals.id`	string	订单 ID
`deals.bidfloor`	int32	该订单的底价，单位分。PD 以这个值为准，不用 `imp.bidfloor`

不是 PD 的请求不要去读 pmp。

5. 竞价响应

有出价返回 HTTP 200，无出价返回 HTTP 204。除这两种以外的状态码都视为异常。不要用 200 返回空的或解析不了的内容。

返回的素材必须和请求匹配：时长不能超过 imp 的限制，类型要对应，不能用离线素材。

5.1 BidResponse、Seatbid、Bid

字段	必填	说明
`id`	是	与请求 `id` 相同，用来关联请求
`seatbid`	是	至少一个。每个里可以有多个 `bid`
`bid.id`	是	DSP 生成的竞价 ID，用于日志
`bid.impid`	是	对应请求里的 `imp.id`，必须一致
`bid.price`	是	出价，单位分/CPM
`bid.adm`	是	物料、监测和落地页
`bid.startdelay`	否	贴片的播放时间。想要更多曝光机会就不要填
`bid.deeplink_url`	条件	原生唤醒时必填
`bid.universal_link_url`	条件	iOS universal link 唤醒时必填
`bid.mini_app_name`	条件	微信小程序原始 ID，小程序唤醒时必填
`bid.mini_app_path`	条件	微信小程序页面路径，小程序唤醒时必填
`bid.creative_content`	条件	快速审核模板的内容，JSON 字符串
`bid.creative_adi`	条件	下载类六要素，JSON，见 5.5

5.2 Adm

字段	必填	说明
`win_notice_url`	是	DSP 曝光监测。可带成交价宏，长度不超过 1200。SSP 用它判断本次是否出价
`ck_monitior_url`	是	DSP 点击监测，长度不超过 1200。字段名就是这个拼写
`adid`	是	DSP 侧创意 ID，必须已完成到媒体素材的映射
`click_throughs`	是	落地页，见 5.3
`pmo`	否	第三方曝光监测，不能带价格宏。最多 3 条，多出的不会被请求
`cmo`	否	第三方点击监测，不能带价格宏。最多 3 条
`native_title` / `native_desc`	否	广告标题和描述
`duration`	条件	视频广告的播放时长，视频类必填
`tracking_events`	否	播放、下载等节点监测，见 5.4
`icon`	否	DSP logo，25×25 的透明 PNG
`cat`	否	创意的内容类别

win_notice_url 和 ck_monitior_url 必须是公网可访问的地址。

5.3 落地页 ClickThroughs

字段	必填	说明
`click_type`	是	点击类型，见下方
`url`	否	落地页地址，以竞价返回的值为准

click_type 的取值：

值	含义
`0`	默认，打开网页
`4`	App 下载
`11`	App 直接下载，不弹窗
`14`	原生唤醒，配合 `deeplink_url`
`15`	iOS universal link 唤醒
`67`	微信小程序

落地页不再从素材上传信息里取，统一用这里实时返回的地址。

5.4 播放与下载监测

tracking_events 的每一项：

字段	说明
`event`	事件，取值见下表
`percent`	播放进度，`0.25`、`0.5`、`0.75`、`1`
`tracking_url`	该事件的监测地址

值	事件	适用范围
0	播放到 25%	只对贴片有效
1	播放到 50%	只对贴片有效
2	播放到 75%	只对贴片有效
3	播放到 100%	只对贴片有效
4	开始下载	Android，点击类型为直接下载时
5	下载完成	同上
6	安装完成	Android，广告下载的 App 安装完成后回传
9	deeplink 跳转成功
10	用户关闭广告	如开屏点跳过

0 到 10 都支持。同一个事件可以加多条，只加需要的事件；没有任何监测需求时整段省略。

5.5 下载类六要素

下载类广告必须在 bid.creative_adi 返回 JSON：

字段	含义
`name`	应用名称
`version`	版本号
`developer`	开发者名称
`permission`	权限说明入口
`privacy`	隐私说明入口
`feature`	应用功能

六项都必填。

6. 什么算有效出价

返回 200 只说明 SSP 收到了响应。成为候选还要同时满足：

seatbid 和 bid 都非空，adm.adid、adm.win_notice_url 有值。
DSP 广告位和当前媒体广告位的映射存在。
出价不低于媒体底价和 DSP 广告位底价；PD 流量用订单底价。
收益计算成功，包括返点、固定底价、浮动收益。
adid 已配置到目标媒体素材的映射。
曝光监测地址可用。

任一不满足，本次出价被丢弃。素材 ID、底价和监测地址是最常见的原因。所有 DSP 都没有有效候选时，SSP 对媒体返回 204，这是正常的无填充，不是故障。

7. 监测与成交价

7.1 监测怎么走

DSP 只返回自己的原始监测地址。SSP 不把它们直接交给媒体，而是先生成自己的跟踪地址，再带上 DSP 的地址：

曝光：https://trk.fireaipro.com/im?...
点击：https://trk.fireaipro.com/ck?...
胜出：https://ntc.fireaipro.com/win?...

地址上的 info 由 SSP 生成并做 Base64，里面是 DSP、素材、广告位、底价、出价和来源。DSP 不要自己构造 info，也不要依赖参数顺序。

竞价成功后由 SSP 服务端触发 DSP 的获胜通知。

7.2 成交价宏

监测地址里用 ${SETTLEMENT} 表示成交价，单位是分。CPM 按每千次曝光计，CPC 按每次点击计。

替换后的值是一个 Settlement 消息：先 Protobuf 序列化，再用一套自定义 Base64 编码。

protobuf

message Settlement {
  optional uint32 version = 1;
  required bytes price = 2;   // AES 加密后的价格
  optional bytes auth = 3;
}

解密步骤：

用自定义 Base64 解码。字典是 A-Z a-z 0-9 _ -，填充字符是 ! 而不是 =。
按 Protobuf 解出 Settlement，取 price。
用分配给该 DSP 的密钥做 AES-256-ECB 解密，PKCS5 填充。密钥是 32 个字符，每个 DSP 一把，测试和正式不同，联调时单独提供。
去掉填充后就是价格明文，例如 123456.78。

第三方监测（pmo、cmo）不允许带这个宏。

8. 联调清单

[ ] bid_url 从 SSP 所在网络能访问，支持 Protobuf 而不是 JSON。
[ ] 正确处理 gzip：压缩的请求能解开，需要时压缩响应。
[ ] 在超时内返回。按平均低于 120ms 准备，P95 建议控制在 10ms 以内。
[ ] 无出价返回 204，不返回解析不了的空 body。
[ ] 有出价时 id、impid、price、adm.adid、win_notice_url、ck_monitior_url 都在，且 impid 与请求一致。
[ ] 素材时长、类型和请求匹配，素材 ID 已提交映射。
[ ] 曝光和点击地址公网可访问，成交价宏能正确解密。

9. 枚举

9.1 广告类型 `ad_type`

值	类型	值	类型
0	页面	1	前贴
2	中贴	3	后贴
6	暂停	10	通用浮层

9.2 网络 `connection_type`

值	网络	值	网络
0	未知	1	有线
2	Wi-Fi	3	2G
4	3G	5	4G
6	5G

9.3 平台 `platform_id`

值	平台	值	平台
11	PC 网页	12	PC 客户端
13	Mac 客户端	21	iPad H5（贴片可点）
22	iPad 客户端	23	Android 平板
32	iPhone 客户端	33	Android 手机
311	Android 手机 H5	312	iPhone H5（贴片不可点）
5201	电视（Android）

25、35 不支持 RTB。

9.4 广告类型 `adtype`

值	类型	值	类型
1	Banner	2	插屏
3	开屏	4	Banner
5	应用图标	6	激励视频
7	原生

11. 参考

广告位、行业、频道和模板的取值见对接时提供的字典。

SSP DSP 竞价对接指南 ​

1. 对接概览 ​

2. 广告形态 ​

3. DSP 需要提供什么 ​

4. 竞价请求 ​

4.1 BidRequest ​

4.2 Impression ​

4.3 Video 与 Banner ​

4.4 用户、站点与内容 ​

4.5 Device ​

4.6 PD 流量 ​

5. 竞价响应 ​

5.1 BidResponse、Seatbid、Bid ​

5.2 Adm ​

5.3 落地页 ClickThroughs ​

5.4 播放与下载监测 ​

5.5 下载类六要素 ​

6. 什么算有效出价 ​

7. 监测与成交价 ​

7.1 监测怎么走 ​

7.2 成交价宏 ​

8. 联调清单 ​

9. 枚举 ​

9.1 广告类型 ad_type ​

9.2 网络 connection_type ​

9.3 平台 platform_id ​

9.4 广告类型 adtype ​

11. 参考 ​