Pubeasy API

总体说明

本⽂档⽤于定义Pubeasy程序化接⼝和交互的标准规范.
⽬前只作为双⽅开发的协议约定,后期连调线下沟通.

请求接口说明

请求参数

字段类型说明

Object: Request

字段名字段类型字段说明
idstring;required表示请求的唯一 id,由渠道提供
impobject array;required描述广告展示的相关信息 具体字段参考 object: Imp
appobject;required发送请求的 app 相关信息,具体字段参考 object:App
deviceobject;required设备信息,详细字段见 object:Device
userobject;required用户信息, 详细字段参考 object: User
sourceobject; recommended标识广告请求来源的详细信息, 详细字段参考 object: Source
regsobject; recommended隐私法规 详细字段参考 object: Regs
atinteger; recommended; default 1交易类型, 1:一价成交 2: 二价成交
tmaxint;recommended请求最大响应时间,单位:毫秒,规定接口必须在多少毫秒内返回
bcatarray;recommended;default []广告类目黑名单,用以限制当前广告位上展示的广告类别, 如: IAB2 详细cat字段参考 Array: Category
badvarray;recommended; default []广告主黑名单, 用以限制哪些广告主不允许在当前广告位上展示广告, 填写广告主域名
curarray; required货币类型 固定['USD']
extobject; recommended扩展字段

Object: Imp

字段名字段类型字段说明
idstring; required用于竞价请求和响应中唯一标识每个广告位的标识符 由渠道自定义提供
bannerobject;广告类型banner, 参考Object: Banner Banner/Video/Native有且只能有一个
videoobject;广告类型video, 参考object: Video Banner/Video/Native有且只能有一个
nativeobject;广告类型native, 参考object: Native Banner/Video/Native有且只能有一个
displaymanagerstring; recommended当前广告请求中使用的展示系统或 SDK
displaymanagerverstring; recommended当前广告请求中使用的展示系统的版本号
instlinteger; default 0; recommended插屏(全屏)时为1
tagidstring,optional开发者自定义的标签,用于描述广告位的具体位置、属性或类型
bidfloorfloat; default 0; required此次广告位的底价
bidfloorcurstring; default 'USD';required固定 'USD'
secureinteger; recommended是否需要https来加载广告资源, 1:yes, 0: no
expinteger; recommended广告展示的有效期,超出时间将不再展示,dsp应尽早展示广告
extobject; recommended扩展字段

Object: Banner

字段名字段类型字段说明
formatobject array; required广告位支持的尺寸列表 具体参考object: Format
winteger; required表示广告位的宽度
hinteger; required表示广告位的长度
mimesstring array; required广告位支持的图片文件格式 image/jpeg, image/png, image/gif
posinteger; recommended表示广告位在页面的位置, 具体参考 Pos
apiinteger array; recommended支持的api框架类型 具体参考 Array: Api
idinteger; recommended横幅的唯一标识
extobject; recommended扩展字段

Object: Video

字段名字段类型字段说明
mimesstring array; required支持的类型 'video/mp4', 'video/x-ms-wmv'
mindurationinteger; recommended视频的最小时长
maxdurationinteger; recommended视频的最大时长
protocolsinteger array; recommended支持的协议 具体参考 Array: Protocols
winteger; recommended
hinteger; recommended
startdelayinteger; recommended播放前的启动延迟
placementinteger; recommended展示环境 具体参考 Array: Placement
linearityinteger; recommended是否是线性播放 1:是 0:不是
skipinteger; recommended是否是可跳过 1: 是, 0: 不是
skipmininteger; recommended;default 0跳过前的最小播放时间, 以秒为单位
skipafterinteger; recommended;default 0广告从播放开始后多久可以被跳过。 以秒为单位
sequenceinteger; optional广告的播放顺序
maxextendedinteger; optional视频广告的最大扩展播放时长
minbitrateinteger; recommended最小分辨率
maxbitrateinteger; recommended最大分辨率
boxingallowedinteger; recommended; default: 1是否允许缩放, 0不允许 1允许
playbackmethodinteger array; recommended视频的播放方式, 具体参考 Array: PlayBack
deliveryinteger array; recommended广告素材的传输方式 具体参考 Array: Delivery
posinteger; recommended素材的展示位置, 具体参考 Array: Pos
companionadobject array; optional伴生广告 Array of Banner objects
extobject; recommended扩展字段

Object: Native

字段名字段类型字段说明
requeststring; requiredRequest payload complying with the Native Ad Specification.
verstring; recommendedVersion of the Dynamic Native Ads API to which request complies; highly recommended for efficient parsing.
apiinteger array; recommendedArray: Api
battrinteger array; recommendedBlocked creative attributes. Array: Attr
extobject; recommended扩展字段

Object: Format

字段名字段类型字段说明
winteger; required广告位的宽度
hinteger; required广告位的长度
wratiointeger; recommended宽高比
hratiointeger; recommended宽高比
wmininteger; recommended广告位的最小宽度
extobject; optional扩展字段

Array: Pos

Array: Placement

Array: PlayBack

Array: Delivery

Array: Api

Object: App

字段名字段类型字段说明
idstring; requiredapp的id,渠道⾃定义
namestring; requiredapp name
bundlestring; requiredapp bundle
domainstring; recommended开发者域名
storeurlstring; recommended应用商店地址
catstring array; recommendedapp类别, 参考Cat
verstring; recommendedapp version
privacypolicyinteger; recommended隐私政策, 0没有, 1有
paidinteger; recommended是否是付费应用 0免费, 1付费
publisherobject; recommended应用的发布者信息, 详细信息: object: Publisher
contentobject; recommended应用内容的类型 详细信息 object: Content
keywordsstring; recommended应用的关键字信息 如 "新闻,时事,头条"
extobject; recommended扩展字段

Object: Publisher

字段名字段类型字段说明
idstring; recommended发布者的唯一标识
namestring; recommended发布者名称
catstring array; recommended发布者的内容类别 详细信息 object: Category
domainstring; recommended发布者域名
extobject; optional扩展字段

Object: Content

字段名字段类型字段说明
idstring; recommended内容的唯一标识符
titlestring; recommended内容的标题
seriesstring; optional内容所属系列
seasonstring; optional内容的季(如电视剧中的季数)
genrestring; optional内容的类型或流派
catstring array; recommended内容的类别代码 详细信息 object: Category
keywordsstring; recommended内容的关键字
leninteger; recommended内容的时长, 秒
languagestring; recommended内容的语言 如en

Object: Device

字段名字段类型字段说明
uastring; requiredua信息
geoObject; recommended设备地址信息,详细信息: Geo, 尽可能传递
dntinteger; recommended请勿追踪 0:没有启动 1: 已启用
lmtinteger; recommended限制广告追踪 1: 已启用,用户不希望被追踪,限制广告个性化 0:没有启用
ipstring; recommended设备ip 尽可能传递
ipv6string; recommendedipv6地址
devicetypeinteger; recommended设备类型, 详细信息: DeviceType
makestring; recommended设备制造商 如'Apple'
modelstring; recommended设备型号 如 'iPhone'
osstring; required操作系统 iOS, Android
osvstring; recommended操作系统版本
hwvstring; optional硬件版本
ppiinteger; optional屏幕像素密度
pxratiofloat; optional设备的像素比例
jsinteger; optional设备是否支持js代码
geofetchinteger; optional是否支持实时地理位置获取 1:支持, 0:不支持
flashverstring; optionalAdobe Flash 插件版本
carrierstring; recommended运营商信息
winteger; recommended设备宽度
hinteger; recommended设备高度
languagestring; required设备语言信息, 使用ISO-639-1-alpha-2.
connectiontypestring; recommended网络类型 详细信息: ConnectionType
ifastring; recommended设备id 尽可能获取
didsha1string; recommendedhashed via SHA1.
didmd5string; recommendedHardware device ID (e.g., IMEI); hashed via MD5.
dpidsha1string; recommendedPlatform device ID (e.g., Android ID); hashed via SHA1.
dpidmd5string; recommendedPlatform device ID (e.g., Android ID); hashed via MD5.
macsha1string; recommendedMAC address of the device; hashed via SHA1.
macmd5string; recommendedMAC address of the device; hashed via MD5.
extobject; recommended扩展字段

Object Geo

字段名字段类型字段说明
latfloat; recommended用户的纬度信息 如 37.7749
lonfloat; recommended用户的经度信息 如 -122.4194
typeinteger; optional地理信息的来源类型, 1: GPS, 2: IP定位, 3: 用户手动提供
accuracyinteger; optional精准度 以米为单位
countrystring; recommended国家三字码 尽可能传递
regionstring; recommendedRegion code using ISO-3166-2; 2-letter state code if USA.
lastfixinteger; optional设备最后一次地理位置更新的时间 以秒为单位
metrostring; optional大都会区域编码, 主要适用美国
zipstring; recommended邮编
utcoffsetinteger; recommendedutc时区
extobject; recommended扩展字段

Array DeviceType

Array ConnectionType

Object User

字段名字段类型字段说明
idstring; recommended用户的唯一标识符,渠道生成
yobinteger; recommended用户的出生年月 如1999
genderstring; recommendedM/F/O 三选一, 表示 男/女/未知
geoobject; recommended用户地理位置信息, 与device.geo相同 尽可能传递
keywordsstring; optional用户的关键字信息
extobject; optional扩展字段

Object Source

字段名字段类型字段说明
fdinteger; recommended表示负责该广告展示最终销售决策的实体 0: exchange, 1: publisher
tidstring; recommended表示此次广告请求的交易 ID,在竞价请求的所有参与方之间保持一致
pchainstring; recommended表示支付链的 ID 字符串,包含遵循 TAG Payment ID Protocol v1.0 的嵌入式语法
extobject; optional扩展字段

Object Regs

字段名字段类型字段说明
coppainteger; recommended用于指示该广告请求是否受美国《儿童在线隐私保护法案》的约束, 0: 不受约束, 1: 受约束
extobject; optional扩展字段

Array Category

 

返回参数

Object Response

字段名字段类型字段说明
idstring; required竞价响应的唯一标识符
seatbidobject array; required竞价信息, 参考 Object: SeatBid
bididstring; required标识具体的竞价信息
curstring; required固定 'USD'
extobject; optional自定义一些信息

Object SeatBid

字段名字段类型字段说明
bidobject array; required一个或多个具体的出价对象
seatstring; recommended出价者信息
groupinteger; recommended出价是否需要作为一个整体被接受或拒绝, 0: 可以被拆开, 1: 必须作为整体
extobject; optional扩展字段

Object bid

字段名字段类型字段说明
idstring; requiredbidder生成,用来追踪
impidstring; required请求时的imp.id
pricefloat; required出价
nurlstring; required竞价获胜时触发,会有宏替换
burlstring; required计费时触发,会有宏替换
lurlstring; recommended竞价失败时触发,会有宏替换
admstring; required广告素材内容 会有宏替换
adidstring; recommended广告内容唯一标识符
adomainstring array; recommended广告主的域名
bundlestring; recommended素材的bundle
iurlstring; recommended素材的预览url
cidstring; recommended广告活动的唯一标识
cridstring; recommended素材的唯一标识
catstring array; recommended素材的类别,参考Array: Category
attrstring array; recommended描述广告的特定属性或特征 参考Array: Attr
apiinteger; recommended广告支持的api框架 参考Array: Api
protocolinteger; recommended广告素材所支持的视频协议,用于视频素材 参考Array: Protocols
languagestring; recommended素材语言
winteger; recommended素材的宽
hinteger; recommended素材的高
wratiointeger; recommended素材的宽高比
hratiointeger; recommended素材的宽高比
expinteger; recommended出价有效的时间长度 以秒为单位
extobject; recommended扩展字段

Object Bid.Ext

字段名字段类型字段说明
deeplinkstring; recommended深度链接

宏替换规则

MacroDesciption
${AUCTION_ID}ID of the bid request; from BidRequest.id attribute.
${AUCTION_BID_ID}ID of the bid; from BidResponse.bidid attribute.
${AUCTION_IMP_ID}ID of the impression just won; from imp.id attribute.
${AUCTION_SEAT_ID}ID of the bidder seat for whom the bid was made.
${AUCTION_AD_ID}ID of the ad markup the bidder wishes to serve; from bid.adid attribute.
${AUCTION_PRICE}Clearing price using the same currency and units as the bid.
${AUCTION_CURRENCY}The currency used in the bid (explicit or implied); for confirmation only.
${AUCTION_LOSS}Loss reason codes.

Array Attr

Array Api

Array Protocols

样例

Video Request

Native Request

Video Response

Native Response