跳到主要内容

广告主对接文档

法律声明​

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

文档说明​

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

修订历史​

文档版本修订日期修订描述
1.0.02023-12-01初版
1.1.02024-08-01支持protobuf
1.2.02025-01-16支持loss notice
1.2.12025-12-10更新Protobuf
1.2.22026-06-01更新Protobuf, 支持DP失败回传
1.3.02026-10-15更新宏替换说明

[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 请求参数​

请求参数详见下表：

字段必须类型描述
idYstring请求唯一标识
impY[Imp](#1.1.2 Imp)广告位信息
deviceY[Device](#1.1.1 Device)设备信息
appY[App](#1.1.3 APP)应用信息
userN[User](#1.1.4 User)用户信息
siteN[Site](#1.1.2.2 Size)站点信息
timeoutNint超时时间（毫秒)
debugNbool测试模式，默认false
secureNint是否只支持https：0-无要求，http和https都支持；1-只支持https

1.1.1 Device​

字段类型必须描述
ipstringY客户端IP，优先IPv4
uastringN客户端webview User-Agent
devicetypeintN设备类型：0 未知; 1 手机; 2 平板; 4 互联网电视
hintN屏幕高
wintN屏幕宽
orientationintN设备方向：1 竖屏；2 横屏
geo[Geo](#1.1.1.1 Geo)N经纬度坐标系定义
makestringN设备品牌
vendorstringN生产厂商
modelstringN设备型号
carrierintN⽹运营商定义：0 未知; 1 移动; 2 联通; 3 电信; 4 铁通
connection_typeintN网络类型：0 未知; 1 以太网; 2 wifi; 3 蜂窝网络; 4 2G; 5 3G; 6 4G; 7 5G
osintN系统：0 未知; 1 iOS; 2 Android
osvstringN系统版本
macstringN设备MAC地址原值
mac_md5stringN设备MAC地址md5值
imeistringN设备imei原值
imei_md5stringN设备imei md5值
oaidstringN设备oaid原值
oaid_md5stringN设备oaid md5值
idfastringN设备idfa原值
idfa_md5stringN设备idfa md5值
android_idstringN设备android_id原值
android_id_md5stringN设备android_id md5值
paidstringN拼多多IOS设备标识v1.4
caidstringN中⼴协caid原值
caid_versionstringN中⼴协caid版本号
caid_md5stringN中⼴协caid md5值
boot_markstringN设备启动标识
update_markstringN设备更新标识
boot_timestringNiOS设备系统启动时间，整数：秒（拼多多）
update_timestringNiOS设备系统更新时间，6位小数：秒（拼多多）
birth_timestringNiOS设备系统初始化时间，9位小数：秒（拼多多）
vercode_agstringN应⽤市场版本号,华为设备必须
vercode_hmsstringNHMS Core 版本号,华为设备必须
country_codestringN应⽤市场中设置的国家地区
disk_totalint64N磁盘总空间，单位：KB
mem_totalint64N系统总内存空间，单位：KB
device_namestringN设备名称
hardware_machinestringN机型编码："iPhone10,3"
languagestringN语言示例："zh-Hans-CN"
time_zonestringN时区示例："28800"，单位：秒
densityfloat64N设备像素密度系数
ppiint32N设备每英寸的像素数
dpiint32N设备每英寸的点数
caids[][CaidInfo](#1.1.1.2 CaidInfo)N多版本CAID

1.1.1.1 Geo​

字段类型必须描述
latfloat32Y纬度
lonfloat32Y经度

1.1.1.2 CaidInfo​

字段类型必须描述
versionstringYCAID版本
caidstringYCAID值

1.1.2 Imp​

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

1.1.3 APP​

字段类型必须描述
appidstringNappid
namestringNapp名称
bundlestringNapp包名
versionStringNApp版本号

1.1.4 User​

字段类型必须描述
genderstringN性别 M 男；F 女
agestringN年龄
install_app[]stringN用户安装列表
1.1.5 Site​
字段类型必须描述
namestringN站点名称
domainstringN站点域名
pagestringN当前站点页面url
refstringNReferrer

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 响应参数​

字段类型必须说明
idstringY
codeintYcode=0表示成功,code=9表示命中设备冷却
msgstringY
seat_bid[SeatBid](#2.1.1 SeatBid)Y
bididstringN
cold_end_timeintNcode=9时才触发设备冷却，如果该值为：1678377600

2.1.1 SeatBid​

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

2.1.2 Bid​

字段类型必须说明
idstringYdsp生成的bid id，用于追踪或打log
impidstringYbid request中对应的Imp对象id
support_actionintY交互类型，0 h5;1 下载;2 deeplink;3 小程序
creative_idstringY素材唯一id，此id在一次广告投放中与素材绑定，同一素材组合下唯一.
priceintY竞价价格,单位分/CPM，实际成交价见价格宏
dealidstringNdeal ID，对应请求Deal中的一个. PD/PDB订单必须回复
nurlstringN竞价成功通知url，支持宏替换
lurlstringN竞价失败通知url，支持宏替换
app[App](#2.1.2.2 App)Napp下载类应用可能包含的推广信息
native[Native](#2.1.2.1 Native)Y广告物料，Native对象，该字段不为空
tracking[Tracking](#2.1.2.3 Tracking)N监测链接
ext_info[ExtInfo](#2.1.2.4 ExtInfo)N额外扩展信息
2.1.2.1 Native​
名称必填类型说明
template_idYint模版id，根据填充的素材从请求中选择对应的模版ID
assetsY[][Asset](#2.1.2.1.1 Asset)资源对象

2.1.2.1.1 Asset

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

2.1.2.1.1 Image

名称必填类型说明
typeYint图片类型: 1 主图；2 logo；3 icon
urlYstring图片素材url
wNint素材宽
hNint素材高

2.1.2.1.2 Video

名称必填类型说明
urlYstring视频url
wNint素材宽
hNint素材高
durationNint视频时长，单位秒
cover_urlNstring封面图

2.1.2.1.3 Data

名称必填类型说明
typeYint数据类型: 1 标题；2 描述
valueNstring标题
2.1.2.2 App​
名称必填类型说明
nameYstringapp名称
package_nameYstringapp包名
app_iconNstringapp icon图
app_idNstringios app store id
app_versionNstringapp下载类App版本
developerNstringapp开发者信息
app_sizeNintapp下载类App Size，单位：KB
app_privacyNstringapp下载类隐私协议URL
app_permissionNstringapp下载类应用权限描述
app_descNstringapp下载类应用功能描述文案
app_desc_urlNstringapp下载类应用功能描述URL
download_urlNstringapp下载类下载地址

2.1.2.3 Tracking​

字段类型必须说明
landing_pagestringN落地页,下载类广告填下载地址
deep_linkstringNdeeplink：安卓为scheme_link,iOS为universal_link
wx_program_idstringN唤起的微信小程序ID
wx_program_pathstringN微信小程序唤起后打开的页面路径,默认是小程序主页
imp_trackers[]stringN曝光上报地址，支持宏替换
clk_trackers[]stringN点击上报地址，支持宏替换
deeplink_trackers[]stringNdp唤起成功监测链接，支持宏替换
deeplink_failed_trackers[]stringNdp唤起失败(已安装目标应用)监测链接，支持宏替换
deeplink_reject_trackers[]stringNdp唤起失败(未安装目标应用)监测链接，支持宏替换
download_start[]stringN下载开始上报地址, 支持宏替换
download_end[]stringN下载完成上报地址，支持宏替换
install_start[]stringN安装开始上报地址，支持宏替换
install_end[]stringN安装成功上报地址，支持宏替换
video_start_play[]stringN视频播放开始，支持宏替换
video_25_play[]stringN视频播放25%，支持宏替换
video_50_play[]stringN视频播放50%，支持宏替换
video_70_play[]stringN视频播放75%，支持宏替换
video_end_play[]stringN视频播放完成，支持宏替换
video_close[]stringN视频关闭，支持宏替换

2.1.2.4 ExtInfo​

字段类型必须说明
x_request_with_package_namestringNX-Requested-With HTTP header
x_user_agentstringNX-User-Agent HTTP header
replaced_hoststringNHOST HTTP header
delivery_typestringN投递类型,值需线下沟通

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 上报说明​

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

3.2 宏替换说明​

支持以下宏替换：

MacroDescrption
__PRICE__竟胜价格，单位为分/千次曝光（CPC结算为 分/点击）。仅支持明文
__LOSS_PRICE__竟败时竟胜方的出价，明文。单位：单位为分/千次曝光（CPC结算为 分/点击）
__LOSS_REASON__竟败原因，见 #3.2.1 可选竟败原因枚举值
__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替换
__WIDTH__实际广告视图的宽，单位像素
__HEIGHT__实际广告视图的高，单位像素
__SLOT_WIDTH__广告位宽，单位像素
__SLOT_HEIGHT__广告位高，单位像素
__SLD__华为SLD宏：
0：常规触屏点击。
1：滑动点击，广告上有引导用户进行滑动以触发点击。
2：摇一摇，需要替换加速度。
5：扭一扭或倾斜，需要替换角度。
6：擦除。
注意
1.sld=0,1,6 情况下，点击坐标获取失败需用 -999 填充。
2.sld=2,5 无需替换点击坐标宏。
__SLD2__广告交互方式(Oppo): 0: 未知 1: 触屏点击 2: 摇一摇 3: 滑动 5: 扭一扭
__TS__客户端当前时间, Unix Timestamp 秒
__TMS__客户端当前时间, Unix Timestamp 毫秒
__MAX_ACC_X__摇一摇X轴最大加速度,单位m/s^2
__MAX_ACC_Y__摇一摇Y轴最大加速度,单位m/s^2
__MAX_ACC_Z__摇一摇Z轴最大加速度,单位m/s^2
__TURN_X__扭一扭X轴扭动角度,取值-180~180,单位度°
__TURN_Y__扭一扭Y轴扭动角度,取值-180~180,单位度°
__TURN_Z__扭一扭Z轴扭动角度,取值-180~180,单位度°
__DENSITY__屏幕密度
__IMP_DUR_TMS__广告曝光持续时间,毫秒
__IMP_RATIO__广告可视区展示比例,取值0-100
__TURN_DUR_TMS__扭动触发点击时的扭动时长,单位毫秒
__UP_TMS__点击(滑动)抬起时的时间戳，单位毫秒
__DOWN_TMS__点击(滑动)按下时的时间戳，单位毫秒
__VIDEO_TS__视频播放时长，单位秒
__APP_INSTALLED__目标APP是否已安装, 1: 已安装, 0: 未安装

3.2.1 竟败原因宏替换说明​

Code说明
0未知
1竞价成功
100竞价过低
101竞价低于其他DSP出价
102竞价低于底价
200响应超时
201响应数据错误
202响应素材错误
203响应创意被过滤
204响应落地页被过滤
205响应创意未审核
206响应创意审核中
207响应创意审核未通过

4. 模板列表​

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