跳转至

XMLY OpenRTB Protocol

Table of Contents

Top

xmopenrtb_v1_4.proto

BidRequest

Field Type Label Description
id string 本次请求的唯一id
api_version string 协议版本（目前为"v1.2"）
request_type int32 请求类型(1: 正式环境; 2: ping,测试RTT; 4: 测试广告，不计费; 8:其他)
imps BidRequest.Imp repeated 曝光机会列表
app BidRequest.App APP信息
device BidRequest.Device 设备信息
user BidRequest.User 用户信息
geo BidRequest.Geo 地理位置信息
timeout uint32 请求预留的时间，单位为ms
ext BidRequest.Ext 扩展参数

BidRequest.App

Field Type Label Description
name string 应用名称：例如：喜马拉雅FM
bundle string 应用程序包名：例如：com.ximalaya.iting
version string 应用版本号: 例如: 9.2.6

BidRequest.Caid

Field Type Label Description
id string caid 的值
version string caid 版本

BidRequest.Device

Field Type Label Description
ua string UA信息
ipv4 string optional 用户设备ipv4地址
ipv6 string optional 用户设备ipv6地址
carrier int32 运营商（0：未知；1：移动; 2：联通；3：电信; 4: 广电）
network_type int32 网络连接类型（0:未知; 1:Ethernet/Wifi；2：2G；3：3G；4：4G; 5: 5G; 6: 6G[预留], 7: 移动网络未知）
make string 手机品牌，如：iPhone，Xiaomi
model string 手机型号，如：iPhoneX, KNT-AL10
os string 操作系统名称（ios、android、windows、macos、linux, 均为小写）
osv string 操作系统版本
device_type int32 设备类型（0：手机；1:平板; 2: 电脑; 3: other）
screen_height int32 optional 屏幕的物理高度，以像素为单位
screen_width int32 optional 屏幕的物理宽度，以像素为单位
imei string optional Android IMEI原始值明文
imei_md5 string optional IMEI MD5, hex 小写
android_id string optional AndroidId原始值明文
android_id_md5 string optional AndroidId MD5, hex 小写
oaid string optional Android OAID原始值明文
oaid_md5 string optional Android OAID MD5, hex 小写
hms_version string optional 华为机型HMS Core版本号，华为设备必填
ag_version string optional 设备应用市场版本号，华为设备必填
ag_country_code string optional 应用市场中设置的国家和地区，华为设备必填
oppo_store_version string optional oppo应用商店版本号，oppo设备必填
vivo_store_version string optional vivo应用商店版本号，vivo设备必填
mi_store_version string optional 小米应用商店版本号，小米设备必填
miui_version string optional 小米系统版本，miui系统必填
boot_ts string optional 设备启动时间 iOS: 1657043138
update_ts string optional 设备系统更新时间 iOS: 1647545826.588793
idfa string optional IDFA原始值明文
idfa_md5 string optional IDFA MD5, 小写
caids BidRequest.Caid repeated CAID 对象数组
caid_criteria BidRequest.Device.CAIDCriteria optional caid相关参数
birth_ts string optional 设备初始化时间[协议v1.2新增] iOS: 1647545718.125795458
paid_1_3 string optional PDD归因v1.3版本paid[协议v1.2新增]
paid_1_4 string optional PDD归因v1.4版本paid[协议v1.2新增]

BidRequest.Device.CAIDCriteria

Field Type Label Description
caid_boot_sec string 设备启动时间 UnixTimestamp eg: 1691052221
caid_country_code string 国家 eg: CN
caid_language string 语言 eg: zh-Hans-CN
caid_device_name_md5 string 设备名称MD5 eg: e910dddb2748c36b47fcde5dd720eec1
caid_system_version string 系统版本 eg: 14.0
caid_hardware_machine string 设备 Machine, eg: iPhone10,3
caid_carrier_info string 运营商信息 eg: 中国移动
caid_physical_memory_byte string 物理内存容量 eg: 3955589120
caid_harddisk_size_byte string 硬盘容量 eg: 63900340224
caid_system_update_sec string 系统更新时间, 保留小数点后 6 位，如不够需补 0
caid_hardware_model string 设备 Model eg: D22AP
caid_time_zone string 时区 eg: 28800
caid_mnt_id string mnt_id eg: 30225948939346695D0D744027A07803D5F8410346398776C879B727@/dev/disk1s1
caid_file_init_time string 设备初始化时间 eg: 1632467920.301150749

BidRequest.Ext

Field Type Label Description
extra BidRequest.Ext.ExtraEntry repeated Extra自定义Map

BidRequest.Ext.ExtraEntry

Field Type Label Description
key string
value string

BidRequest.Geo

Field Type Label Description
type int32 坐标系: 经纬度有值时必传，坐标系类型 0:GCJ-02; 1:WGS-84; 2:bd09ll
lat float 纬度 latitude, 取值从-90 到 90，南为负值
lon float 经度 longitude, 取值从-180 到 180，西为负值

BidRequest.Imp

Field Type Label Description
id string 标识唯一一次曝光机会
tag_id string 广告位ID
ad_type int32 广告类型（1:开屏、2：信息流、3：激励视频、4：贴片、5：banner）
bid_type int32 出价类型, 0：cpm 1：cpc 当前仅支持cpm
bid_floor int64 底价，分/千次曝光
assets BidRequest.Imp.Asset repeated 模版信息，详见模版资源映射表

BidRequest.Imp.Asset

Field Type Label Description
template_id string 广告位模版ID, 详见模版资源映射表
width int32 广告位模版宽度
height int32 广告位模版高度

BidRequest.User

Field Type Label Description
id string [保留字段] 用户唯一标识
app_list string 用户已安装app列表, 英文逗号分隔，如 com.xmly.ting,com.xunmeng.pinduoduo,com.jingdong.app.mall

BidResponse

Field Type Label Description
id string 请求ID，需与BidRequest.id一致
code int32 广告响应状态码
bid_id string 喜马联盟侧生成的竞价ID
seat_bids BidResponse.SeatBid repeated 喜马联盟侧生成的竞价信息，目前只有一个

BidResponse.Bid

Field Type Label Description
id string dsp侧针对这次竞价的ID
imp_id string 曝光ID，对应BidRequest.imp.id，必填
ad_id string 广告id
price int64 DSP出价，单位：分/千次曝光
win_notice_urls string repeated 竞价成功通知地址
loss_notice_urls string repeated 可选。竞价失败通知的url列表
imp_trackers string repeated 曝光监测地址
clk_trackers string repeated 点击监测地址
adm BidResponse.Bid.Adm 创意物料信息
evoke_monitor_urls string repeated 唤起APP成功监测地址
evoke_fail_monitor_urls string repeated 唤起APP失败监测地址

BidResponse.Bid.Adm

物料信息

Field Type Label Description
template_id string 模版ID
creative_id string 可选。广告物料的唯一标识
title string 标题
desc string 描述
images BidResponse.Bid.Adm.Image repeated 图片信息
video BidResponse.Bid.Adm.Video 视频信息
optimization_goal BidResponse.Bid.Adm.OptimizationGoal optional 推广目标 : 拉新，拉活，线索表单，小程序
action_type BidResponse.Bid.Adm.ActionType optional 交互类型
landing_page string 落地页url
deep_link string optional 客户端优先跳转deeplink链接,其次跳转普通网址类或应用下载类的落地页
app_info BidResponse.Bid.Adm.AppInfo optional APP信息，用于下载类广告需要的APP信息
download_monitor BidResponse.Bid.Adm.DownloadMonitor optional 下载类广告下载监测链接
mini_program_info BidResponse.Bid.Adm.MiniProgramInfo optional 微信小程序信息
logo BidResponse.Bid.Adm.Image optional logo信息

BidResponse.Bid.Adm.AppComplianceInfo

合规六要素

Field Type Label Description
name string 应用中文名
version string 应用版本号码
developer string 开发者
privacy_url string 隐私协议网址
permission BidResponse.Bid.Adm.AppComplianceInfo.PermissionEntry repeated 权限列表
permissions_url string optional 权限URL，与权限列表二选一填充
function_desc_url string 功能

BidResponse.Bid.Adm.AppComplianceInfo.PermissionEntry

Field Type Label Description
key string
value string

BidResponse.Bid.Adm.AppInfo

Field Type Label Description
name string APP中文名称，针对应用下载类广告，用于下载广告
desc string APP文字描述，用于下载广告
version string APP版本号，用于下载广告
package_name string APP包名，用于下载广告
package_size string optional APP应用包大小，用于下载广告
ios_bundle_id int64 optional iOS下载应用ID，用于下载广告
update_time int64 optional app更新时间
score float optional 应用评分
icon_image_url string optional app icon url
icon_image_width int32 optional app icon width
icon_image_height int32 optional app icon height
download_url string optional 下载地址
download_url_expires int64 optional 下载过期时间戳,秒级
download_url_file_md5 string optional 文件md5
ulk_url string optional universal link url, 用于iOS调起
ulk_scheme string optional universal link scheme,用于iOS嗅探
app_store_link string optional 安卓应用商店直投下载地址
compliance_info BidResponse.Bid.Adm.AppComplianceInfo optional 合规六要素

BidResponse.Bid.Adm.DownloadMonitor

Field Type Label Description
dm_down_start_monitor_urls string repeated 下载开始检测链接
dm_down_end_monitor_urls string repeated 下载完成检测链接
dm_install_start_monitor_urls string repeated 开始安装监控
dm_install_end_monitor_urls string repeated 安装完成监控

BidResponse.Bid.Adm.Image

Field Type Label Description
url string 图片URL
width int32 图片宽度
height int32 图片高度
mime string 图片类型， 如：JPG/JPEG/PNG

BidResponse.Bid.Adm.MiniProgramInfo

Field Type Label Description
release_type BidResponse.Bid.Adm.MiniProgramReleaseType 发布类型
program_id string 小程序id
program_path string 小程序页面路径

BidResponse.Bid.Adm.Video

Field Type Label Description
video_url string 视频URL
width int32 视频宽度
height int32 视频高度
duration int32 视频素材的播放时长，单位：秒
size int32 视频文件的大小，单位Byte
mime string 视频素材类型，以MIME类型表示
cover string 视频封面图

BidResponse.SeatBid

Field Type Label Description
bids BidResponse.Bid repeated DSP参与竞价的位置，与BidRequest.imp对应，每个imp最多只可返回一个bid

BidResponse.Bid.Adm.ActionType

广告点击后优先行为

Name Number Description
ACTION_TYPE_UNSPECIFIED 0 未指定
ACTION_TYPE_LANDING_PAGE 1 打开落地页
ACTION_TYPE_DEEP_LINK 2 deep_link [+ 落地页]
ACTION_TYPE_ANDROID_INSTALL 3 android下载安装
ACTION_TYPE_IOS_INSTALL 4 应用商店安装
ACTION_TYPE_MINI_PROGRAM 5 小程序

BidResponse.Bid.Adm.MiniProgramReleaseType

小程序发布类型

Name Number Description
MINI_PROGRAM_RELEASE_TYPE_UNSPECIFIED 0 未指定
MINI_PROGRAM_RELEASE_TYPE_PRODUCT 1 正式
MINI_PROGRAM_RELEASE_TYPE_TEST 2 测试
MINI_PROGRAM_RELEASE_TYPE_PREVIEW 3 预览

BidResponse.Bid.Adm.OptimizationGoal

投放优化目标

Name Number Description
OPTIMIZATION_GOAL_UNSPECIFIED 0 未指定
OPTIMIZATION_GOAL_LEAD_GENERATION 1 线索类(表单or线索提交)
OPTIMIZATION_GOAL_APP_INSTALL 2 拉新, 应用下载
OPTIMIZATION_GOAL_APP_ENGAGEMENT 3 拉活, 应用使用度提升
OPTIMIZATION_GOAL_BRAND_AWARENESS 4 品牌曝光
OPTIMIZATION_GOAL_MINI_PROGRAM 5 小程序

Scalar Value Types

.proto Type Notes C++ Java Python Go C# PHP Ruby
double double double float float64 double float Float
float float float float float32 float float Float
int32 Uses variable-length encoding. Inefficient for encoding negative numbers – if your field is likely to have negative values, use sint32 instead. int32 int int int32 int integer Bignum or Fixnum (as required)
int64 Uses variable-length encoding. Inefficient for encoding negative numbers – if your field is likely to have negative values, use sint64 instead. int64 long int/long int64 long integer/string Bignum
uint32 Uses variable-length encoding. uint32 int int/long uint32 uint integer Bignum or Fixnum (as required)
uint64 Uses variable-length encoding. uint64 long int/long uint64 ulong integer/string Bignum or Fixnum (as required)
sint32 Uses variable-length encoding. Signed int value. These more efficiently encode negative numbers than regular int32s. int32 int int int32 int integer Bignum or Fixnum (as required)
sint64 Uses variable-length encoding. Signed int value. These more efficiently encode negative numbers than regular int64s. int64 long int/long int64 long integer/string Bignum
fixed32 Always four bytes. More efficient than uint32 if values are often greater than 2^28. uint32 int int uint32 uint integer Bignum or Fixnum (as required)
fixed64 Always eight bytes. More efficient than uint64 if values are often greater than 2^56. uint64 long int/long uint64 ulong integer/string Bignum
sfixed32 Always four bytes. int32 int int int32 int integer Bignum or Fixnum (as required)
sfixed64 Always eight bytes. int64 long int/long int64 long integer/string Bignum
bool bool boolean boolean bool bool boolean TrueClass/FalseClass
string A string must always contain UTF-8 encoded or 7-bit ASCII text. string String str/unicode string string string String (UTF-8)
bytes May contain any arbitrary sequence of bytes. string ByteString str []byte ByteString string String (ASCII-8BIT)

Generated by protoc-gen-doc