广告主对接文档

法律声明

我方签订合同后，我方提供对接协议作为指引文档。未经我方书面许可，不得以任何形式向第三方披露、泄露有关本文档的任何内容。

文档说明

本文档用于消耗方对接我方系统。我方发送流量给消耗方。

修订历史

文档版本	修订日期	修订描述
1.0.0	2023-12-01	初版
1.1.0	2024-08-01	支持protobuf
1.2.0	2025-01-16	支持loss notice
1.2.1	2025-12-10	更新Protobuf

[TOC]

参数定义

HTTP 请求方法

设置HTTP Method 为 POST。

HTTP 请求头

已升级为protobuf，请使用protobuf对接,请到资源页下载

设置Content-type为application/x-protobuf

要求系统支持长链接keepalive

支持gzip,请求头 Content-Encoding:gzip Accept-Encoding:gzip

示例：

POST /bid path HTTP/1.1
HOST: host
Content-Type: application/x-protobuf
Content-Length: length
Connection: Keep-Alive

1 请求

1.1 请求参数

请求参数详见下表：

字段	必须	类型	描述
id	Y	string	请求唯一标识
imp	Y	[Imp](#1.1.2 Imp)	广告位信息
device	Y	[Device](#1.1.1 Device)	设备信息
app	Y	[App](#1.1.3 APP)	应用信息
user	N	[User](#1.1.4 User)	用户信息
site	N	[Site](#1.1.2.2 Size)	站点信息
timeout	N	int	超时时间（毫秒)
debug	N	bool	测试模式，默认false
secure	N	int	是否只支持https：0-无要求，http和https都支持；1-只支持https

1.1.1 Device

字段	类型	必须	描述
ip	string	Y	客户端IP，优先IPv4
ua	string	N	客户端webview User-Agent
devicetype	int	N	设备类型：0 未知; 1 手机; 2 平板; 4 互联网电视
h	int	N	屏幕高
w	int	N	屏幕宽
orientation	int	N	设备方向：1 竖屏；2 横屏
geo	[Geo](#1.1.1.1 Geo)	N	经纬度坐标系定义
make	string	N	设备品牌
vendor	string	N	生产厂商
model	string	N	设备型号
carrier	int	N	⽹运营商定义：0 未知; 1 移动; 2 联通; 3 电信; 4 铁通
connection_type	int	N	网络类型：0 未知; 1 以太网; 2 wifi; 3 蜂窝网络; 4 2G; 5 3G; 6 4G; 7 5G
os	int	N	系统：0 未知; 1 iOS; 2 Android
osv	string	N	系统版本
mac	string	N	设备MAC地址原值
mac_md5	string	N	设备MAC地址md5值
imei	string	N	设备imei原值
imei_md5	string	N	设备imei md5值
oaid	string	N	设备oaid原值
oaid_md5	string	N	设备oaid md5值
idfa	string	N	设备idfa原值
idfa_md5	string	N	设备idfa md5值
android_id	string	N	设备android_id原值
android_id_md5	string	N	设备android_id md5值
paid	string	N	拼多多IOS设备标识v1.4
caid	string	N	中⼴协caid原值
caid_version	string	N	中⼴协caid版本号
caid_md5	string	N	中⼴协caid md5值
boot_mark	string	N	设备启动标识
update_mark	string	N	设备更新标识
boot_time	string	N	iOS设备系统启动时间，整数：秒（拼多多）
update_time	string	N	iOS设备系统更新时间，6位小数：秒（拼多多）
birth_time	string	N	iOS设备系统初始化时间，9位小数：秒（拼多多）
vercode_ag	string	N	应⽤市场版本号,华为设备必须
vercode_hms	string	N	HMS Core 版本号,华为设备必须
country_code	string	N	应⽤市场中设置的国家地区
disk_total	int64	N	磁盘总空间，单位：KB
mem_total	int64	N	系统总内存空间，单位：KB
device_name	string	N	设备名称
hardware_machine	string	N	机型编码："iPhone10,3"
language	string	N	语言示例："zh-Hans-CN"
time_zone	string	N	时区示例："28800"，单位：秒
density	float64	N	设备像素密度系数
ppi	int32	N	设备每英寸的像素数
dpi	int32	N	设备每英寸的点数
caids	[][CaidInfo](#1.1.1.2 CaidInfo)	N	多版本CAID

1.1.1.1 Geo

字段	类型	必须	描述
lat	float32	Y	纬度
lon	float32	Y	经度

1.1.1.2 CaidInfo

字段	类型	必须	描述
version	string	Y	CAID版本
caid	string	Y	CAID值

1.1.2 Imp

字段	类型	必须	描述
id	string	Y	曝光唯一ID
bid_floor	float	Y	底价，单位分
slot_id	string	Y	广告位ID
slot_type	int	Y	广告位类型，0 未知; 1 视频贴片; 5 横幅;6 开屏; 7 插屏; 8 信息流;12 激励视频
size	[][Size](#1.1.2.2 Size)	Y	此展现机会支持的尺寸列表,原生素材具体的尺寸定义见native对象
deal	[][Deal](#1.1.2.1 Deal)	N	deal交易信息，见Deal对象
minduration	int	N	支持video素材时，最小时长
maxduration	int	N	支持video素材时，最大时长
template_id	[]int	N	支持的模板列表
support_action	[]int	N	支持的交互类型，0 h5;1 下载;2 deeplink;3 小程序

1.1.2.1 Deal

字段	类型	必须	描述
id	string	N	deal id
bid_floor	int	N	deal底价,单位分

1.1.2.2 Size

字段	类型	必须
w	int	N
h	int	N

1.1.3 APP

字段	类型	必须	描述
appid	string	N	appid
name	string	N	app名称
bundle	string	N	app包名
version	String	N	App版本号

1.1.4 User

字段	类型	必须	描述
gender	string	N	性别 M 男；F 女
age	string	N	年龄
install_app	[]string	N	用户安装列表

1.1.5 Site

字段	类型	必须	描述
name	string	N	站点名称
domain	string	N	站点域名
page	string	N	当前站点页面url
ref	string	N	Referrer

1.2 JSON请求示例

{
  "id": "cfa0sdf3b42",
  "device": {
    "device_type": 1,
    "ip": "127.0.0.1",
    "ua": "Mozilla/5.0 (Macintosh) AppleWebKit/537.36 Chrome/41.0.2272.101 Safari/537.36",
    "oaid": "977jd56d682e549c",
    "imei": "68677178957650",
    "imei_md5": "686779178957650",
    "android_id": "9774d56d682e549c",
    "idfa": "9774d56d682e549c",
    "mac": "b2:e2:35:ad:18:9c",
    "mac_md5": "977cd56d682e549a",
    "vendor": "apple",
    "model": "iphone XR",
    "os": 1,
    "osv": "9.1",
    "carrier": 3,
    "w": 1920,
    "h": 1080,
    "lat": 12.11,
    "lng": 120.763
  },
  "imp": [
    {
      "id": "1",
      "slot_id": "120_haokan_001",
      "slot_type": 3,
      "bid_floor": 1200,
      "size": [
        {
          "w": 300,
          "h": 250
        }
      ],
      "deal": [
        {
          "id": "3306",
          "bid_floor": 1000
        }
      ],
      "video_min": 15,
      "video_max": 30,
      "template_id": [1, 2, 3],
      "support_interact": [0, 2]
    }
  ],
  "app": {
    "name": "qqqq",
    "package": "com.qqqq",
    "version": "v8.0"
  },
  "debug": true,
  "source": 1
}

2 响应

一个 BidResponse 中可包含多个 SeatBid 对象。一个 SeatBid 代表DSP端的一个广告主。 SeatBid 中又可包含多个 Bid 对象，一个 Bid 代表一个参与竞价的广告。正常出价返回 HTTP 200 OK，不出价返回 204 no content，150ms内，无响应的，视为竞价异常。响应头Content-Type: application/x-protobuf

2.1 响应参数

字段	类型	必须	说明
id	string	Y
code	int	Y	code=0表示成功,code=9表示命中设备冷却
msg	string	Y
seat_bid	[SeatBid](#2.1.1 SeatBid)	Y
bidid	string	N
cold_end_time	int	N	code=9时才触发设备冷却，如果该值为：1678377600

2.1.1 SeatBid

字段	类型	必须	说明
seat	string	N	adx为广告主分配的广告主id
bid	[][Bid](#2.1.2 Bid)	Y	竞价信息

2.1.2 Bid

字段	类型	必须	说明
id	string	Y	dsp生成的bid id，用于追踪或打log
impid	string	Y	bid request中对应的Imp对象id
support_action	int	Y	交互类型，0 h5;1 下载;2 deeplink;3 小程序
creative_id	string	Y	素材唯一id，此id在一次广告投放中与素材绑定，同一素材组合下唯一.
price	int	Y	竞价价格,单位分/CPM，实际成交价见价格宏
dealid	string	N	deal ID，对应请求Deal中的一个. PD/PDB订单必须回复
nurl	string	N	竞价成功通知url，支持宏替换
lurl	string	N	竞价失败通知url，支持宏替换
app	[App](#2.1.2.2 App)	N	app下载类应用可能包含的推广信息
native	[Native](#2.1.2.1 Native)	Y	广告物料，Native对象，该字段不为空
tracking	[Tracking](#2.1.2.3 Tracking)	N	监测链接

2.1.2.1 Native

名称	必填	类型	说明
template_id	Y	int	模版id，根据填充的素材从请求中选择对应的模版ID
assets	Y	[][Asset](#2.1.2.1.1 Asset)	资源对象

2.1.2.1.1 Asset

名称	必填	类型	说明
image	N	[Image](#2.1.2.1.1 Image)	见Image对象定义
video	N	[Video](#2.1.2.1.2 Video)	见Video对象定义
data	N	[Data](#2.1.2.1.3 Data)	标题描述

2.1.2.1.1 Image

名称	必填	类型	说明
type	Y	int	图片类型: 1 主图；2 logo；3 icon
url	Y	string	图片素材url
w	N	int	素材宽
h	N	int	素材高

2.1.2.1.2 Video

名称	必填	类型	说明
url	Y	string	视频url
w	N	int	素材宽
h	N	int	素材高
duration	N	int	视频时长，单位秒
cover_url	N	string	封面图

2.1.2.1.3 Data

名称	必填	类型	说明
type	Y	int	数据类型: 1 标题；2 描述
value	N	string	标题

2.1.2.2 App

名称	必填	类型	说明
name	Y	string	app名称
package_name	Y	string	app包名
app_icon	N	string	app icon图
app_id	N	string	ios app store id
app_version	N	string	app下载类App版本
developer	N	string	app开发者信息
app_size	N	int	app下载类App Size，单位：KB
app_privacy	N	string	app下载类隐私协议URL
app_permission	N	string	app下载类应用权限描述
app_desc	N	string	app下载类应用功能描述文案
app_desc_url	N	string	app下载类应用功能描述URL

2.1.2.3 Tracking

字段	类型	必须	说明
landing_page	string	N	落地页,下载类广告填下载地址
deep_link	string	N	deeplink：安卓为scheme_link,iOS为universal_link
wx_program_id	string	N	唤起的微信小程序ID
wx_program_path	string	N	微信小程序唤起后打开的页面路径,默认是小程序主页
imp_trackers	[]string	N	曝光上报地址，支持宏替换
clk_trackers	[]string	N	点击上报地址，支持宏替换
deeplink_trackers	[]string	N	dp唤起成功监测链接，支持宏替换
download_start	[]string	N	下载开始上报地址, 支持宏替换
download_end	[]string	N	下载完成上报地址，支持宏替换
install_start	[]string	N	安装开始上报地址，支持宏替换
install_end	[]string	N	安装成功上报地址，支持宏替换
video_start_play	[]string	N	视频播放开始，支持宏替换
video_25_play	[]string	N	视频播放25%，支持宏替换
video_50_play	[]string	N	视频播放50%，支持宏替换
video_70_play	[]string	N	视频播放75%，支持宏替换
video_end_play	[]string	N	视频播放完成，支持宏替换
video_close	[]string	N	视频关闭，支持宏替换

2.2 JSON响应示例

{
  "code": 0,
  "seat_bid": [
    {
      "bid": [
        {
          "id": "1",
          "impid": "1",
          "support_action": 1,
          "price": 1000,
          "creative_id": "xxxxxx",
          "nurl": "https://www.xxx.com/nurl",
          "lurl": "https://www.xxx.com/lurl",
          "native": {
            "assets": [
              {
                "image": {
                  "type": 1,
                  "w": 720,
                  "h": 1280,
                  "url": "https://h5.m.taobao.com/1.jpg"
                }
              },
              {
                "data": {
                  "type": 1,
                  "value": "好物分享"
                }
              }
            ]
          },
          "tracking": {
            "landing_page": "https://h5.m.taobao.com/guangguang/index.htm?",
            "deep_link": "tbopen://m.taobao.com/tbopen/index.html?",
            "imp_trackers": [
              "https://www.xxx.com/imptrakc",
              "https://www.xxx.com/imptrakc"
            ],
            "clk_tracker": [
              "https://www.xxx.com/clktrakc",
              "https://www.xxx.com/clktrakc"
            ],
            "deeplink_trackers": [
              "https://www.xxx.com/dptrakc",
              "https://www.xxx.com/dptrakc"
            ]
          }
        }
      ]
    }
  ]
}

3. 监测上报和宏替换说明

3.1 上报说明

媒体对竞价成功的DSP，发送获胜通知（nurl），协议为HTTP GET；
支持Server端上报竞价失败loss notice(lurl)，协议为HTTP GET，支持宏替换；
在广告被曝光时并行上报多组展现监测(imp_trackers)
在广告被点击时，并行上报多组点击监测（clk_trackers），同时进行跳转
对于有下载监测需求的广告，需要回传下载进度
对于有deeplink唤起监测需求的广告，需要回传deeplink唤起
所有监测链接需要支持https

3.2 宏替换说明

需要支持以下宏替换：

Macro	Descrption
`__AUCTION_DX__`	鼠标或手指按下时相对于广告位左上角的X坐标（单位像素），clk_tracking/dplink/land替换
`__AUCTION_DY__`	鼠标或手指按下时相对于广告位左上角的Y坐标（单位像素），clk_tracking/dplink/land替换
`__AUCTION_UX__`	鼠标或手指弹起时相对于广告位左上角的X坐标（单位像素），clk_tracking/dplink/land替换
`__AUCTION_UY__`	鼠标或手指弹起时相对于广告位左上角的Y坐标（单位像素），clk_tracking/dplink/land替换
`__PRICE__`	价格宏，支持明文，回传rtb bidding的成本，单位为分，文档参考：加密方式
`__LOSS_PRICE__`	竟败时竟胜方的出价，明文。单位：分
`__LOSS_REASON__`	竟败原因
`__SLD__`	点击交互方式：0 常规点击；1 滑动点击；2 摇一摇；5 扭一扭或者倾斜；6 擦除
`__WIDTH__`	实际广告视图的宽，单位像素
`__HEIGHT__`	实际广告视图的高，单位像素
`__SLOT_WIDTH__`	广告位宽，单位像素
`__SLOT_HEIGHT__`	广告位高，单位像素
`__DENSITY__`	设备屏幕密度
`__TS__`	客户端当前时间，单位秒
`__TMS__`	客户端当前时间，单位毫秒

价格宏示例

    ## 测试密钥
    ekey = "9410234e6e712b2680898dd1ecf48b32";
    ikey  = "6087d837248d32698334bf4cc0eb67b1";

    加密字符串：1B2M2Y8AsgTpgAmY7PhCfillTtAhSEp3pVpA9A
    明文：12

4. 模板列表

模版id	素材要求
1	单图二文（标题描述）
5	三图二文（标题描述）
6	一图一视频
7	一图一icon
9	三图一icon
11	一图一文（标题）

法律声明​

文档说明​

修订历史​

参数定义​

1 请求​

1.1 请求参数​

1.1.1 Device​

1.1.1.1 Geo​

1.1.1.2 CaidInfo​

1.1.2 Imp​

1.1.2.1 Deal​

1.1.2.2 Size​

1.1.3 APP​

1.1.4 User​

1.1.5 Site​

1.2 JSON请求示例​

2 响应​

2.1 响应参数​

2.1.1 SeatBid​

2.1.2 Bid​

2.1.2.1 Native​

2.1.2.2 App​

2.1.2.3 Tracking​

2.2 JSON响应示例​

3. 监测上报和宏替换说明​

3.1 上报说明​

3.2 宏替换说明​

4. 模板列表​