BidSwitch Buyer Protocol

BidSwitch Supplier Protocol

General Information

Buyer Guides

Supplier Guides

Protocol Release Notes

v5.3 - November 2017

New Protocol Fields

Bid Request fields:

Bid Response fields:

Updated Protocol Fields

Deprecated Protocol Fields

  • ext.s2s_nurl, replaced by imp.ext.s2s_nurl
  • Both the seatbid.bid.ext.native.jstracker and seatbid.bid.ext.native.imptracker fields have been replaced by seatbid.bid.ext.native.eventtrackers

Updated or New Sections

v5.2 - February 2017

New Protocol Fields

Bid Request fields:

  • imp.video.placement
  • imp.video.playbackend
  • imp.video.skip
  • device.mccmnc
  • source.fd
  • imp.native.request.assets.video.ext see, Native Request Object
  • imp.native.request.assets.video.ext.playbackmethod
  • imp.native.ext see Native Object
  • imp.native.ext.triplelift
  • imp.native.ext.triplelift.formats
  • imp.metric, see Metric Object

Bid Response fields:

  • seatbid.bid.burl, and see the Using the burl Field section for more details.
  • seatbid.bid.language
  • seatbid.bid.ext.native.jstracker
  • seatbid.bid.ext.native.assets.video.ext, see Native Asset Video Object
  • seatbid.bid.ext.native.assets.video.ext.playbackmethod

Updated Protocol Fields

  • seatbid.bid.nurl
  • ext.s2s_nurl

Deprecated Fields

  • imp.ext.viewability bid request field, replaced by the use of the Metric Object

Recently Added or Updated Sections

v5.1 - October 2016

New Protocol Fields

Added the following bid request fields:

  • ext.dooh
  • video.ext.vast_url_rq
  • user.data.segment.name
  • publisher.cat

Updated Protocol Fields

  • The seatbid.bid.ext.vast_url description, this field can be omitted for some bid requests.

v5.0 - July 2016

New Sections

Updated Sections

  • Updated the seatbid.bid.ext.vast_url description, this field can only be used for video trading.
  • Updated the adm and nurl fields, see the Bid Object section.
  • Updated the Macros section with added win price macro usage options.
  • Updated the nurl Response Difference section with information about how to use the nurl and adm fields correctly.

v4.3 - May 2016

Added

Added the Compatibility and Deprecation and Protocol Version Differences sections to help users keep their BidSwitch integration up to date.

Added the following bid response fields:

  • seatbid.bid.ext.native.ext.viewtracker
  • seatbid.bid.ext.native.ext.adchoiceurl

Added the following bid request fields:

  • imp.audio
  • device.geo.utcoffset
  • video.ext.outstream
  • ext.tv
  • imp.banner.format

Added programmatic TV bid request example.

Updated

  • Updated the badv, site and app field descriptions.
  • Bid response fields seatbid.bid.ext.native.assets.img.h and seatbid.bid.ext.native.assets.img.w are now required.
  • The imp.pmp.private_auction field is now optional.
  • Deprecated the imp.banner.ext.extra_sizes bid request field.
  • The ext.vast_url field now supports DAAST (audio) creatives.

Removed

  • Removed fields and objects deprecated in v4.0 - May 2015.
  • Removed the ext.creative_params and data bid request fields.

v4.2 - March 2016

Added

Added support for the following bid request fields:

  • allimps
  • ext.s2s_nurl
  • imp.exp
  • imp.video.maxextended
  • imp.video.boxingallowed
  • imp.video.playbackmethod
  • imp.video.delivery
  • imp.video.sequence
  • device.w
  • device.h
  • device.lmt
  • device.pxratio
  • site.privacypolicy
  • app.privacypolicy
  • user.yob
  • user.gender
  • user.data
  • user.ext.ug
  • user.ext.cookie_age

Added the following bid response fields:

  • seatbid.bid.crid
  • seatbid.bid.ext.agency_id

Updated

  • BidSwitch now supports Compressed JSON as an alternative bid request and bid response data format.
  • The seatbid.bid.adid bid response field is now optional, and the seatbid.bid.crid field may be used instead of it.
  • Removed fields and objects deprecated in v2.6 - February 2015.

v4.1 - September 2015

Added

Added the following bid request fields:

  • site.ref
  • ext.clktrkrq
  • ext.gumgum.cat
  • imp.tagid
  • imp.native.request.assets.img.mimes
  • user.keywords
  • imp.ext.yieldone.cat
  • imp.bidfloorcur
  • pmp.deal.bidfloorcur

Updated

  • Updated the bid request currency array so that it may contain multiple values.
  • Extended enumeration for the imp.video.ext.player_type bid request field.
  • Updated the imp.video.mimes bid request field description.
  • Updated the seatbid.bid.nurl bid response field description.
  • Changed the accepted seatbid.bid.cat type bid response field to a strings array.
  • Updated the Supplier Click Tracking URL Macro section.
  • Updated the Bid Request JSON Examples section, added new example requests and responses.

Removed

Removed fields and objects deprecated in v2.5 - December 2014.

v4.0 - May 2015

Added

Added the following bid request fields:

  • site.mobile
  • device.geo.type
  • imp.iframebuster

Added the following bid response fields:

  • seatbid.bid.cat
  • seatbid.bid.adm
  • seatbid.bid.ext.native

Updated

  • Updated the imp.banner.btype bid request field description.
  • Updated the seatbid.bid.nurl bid response field description.
  • Updated the Macros section, ${CLICK_URL} is no longer supported.
  • Bid response fields seatbid.seat and seatbid.bid.nurl are now required.
  • Bid response seatbid.bid.iurl field is now required for banner ads.

Removed

  • Removed fields and objects deprecated in v2.4 - October 2014.
  • Removed the Creative approval and Additional Features sections.
  • Deprecated site.ext.mobile_site and ext.ghostery bid request fields.
  • Deprecated seatbid.bid.ext.cat bid response field.

Removed the following bid response fields. See this Protocol Version Differences section for more details about how this affects the different major versions.

  • seatbid.bid.ext.js_url
  • seatbid.bid.ext.img_url
  • seatbid.bid.ext.click_url

v2.6 - February 2015

Added

Added the following bid request fields:

  • imp.secure
  • imp.banner.ext.extra_sizes
  • imp.ext.viewability

Added the following bid response fields:

  • seatbid.bid.ext.lpdomain
  • seatbid.bid.h
  • seatbid.bid.w
  • seatbid.bid.iurl bid

Deprecated

  • Deprecated the ext.is_secure bid request field. The new imp.secure field replaces this, see the Impression Object section for more details.

General

  • Removed creative preview section.
  • Removed fields and objects deprecated in v2.3 - September 2014.
  • Updated request and response samples.

v2.5 - December 2014

Added

Added the following bid request fields:

  • imp.video.ext.player_type
  • imp.ext.yieldone.allowed_creative_category_id

Added the following bid response fields:

  • seatbid.bid.ext.yieldone.creative_category_id
  • ext.protocol
  • seatbid.bid.attr
  • seatbid.bid.dealid

Updated

  • Click tracking macro is now required in OpenX bids.
  • The field imp.pmp.deal.at is now optional.

Removed

  • Removed fields and objects deprecated in v2.2 - June 2014.
  • Deprecated the seatbid.bid.ext.deal bid response field.

v2.4 - October 2014

Added

Added the following bid request fields:

  • tmax
  • app.paid
  • regs.coppa
  • device.dnt
  • device.ipv6
  • device.js
  • device.flashver
  • device.devicetype
  • site.name
  • imp.instl
  • imp.displaymanagerapp
  • imp.displaymanagerver
  • imp.ext.yieldone.allowed_creative_types
  • imp.video.pos
  • imp.ext.inventory_class

Added the following bid response field:

  • seatbid.bit.ext.yieldone.creative_type

Updated

Changed the imp.pmp.deals.at values to comply with OpenRTB 2.2.

Removed

Deprecated the imp.ext.yieldone.inventory_class bid request field.

v2.3 - September 2014

Added

Added the following bid requests fields:

  • site.ext.mobile_site
  • imp.banner.mimes

Added the following bid request objects:

  • imp.ext.yieldone
  • imp.pmp
  • ext.creative_params

Added the following bid response fields:

  • seatbid.bid.ext.duration
  • seatbid.bid.ext.img_url
  • seatbid.bid.ext.click_url

Updated

  • Updated the Buyer User Matching section.

  • The field imp.video.linearity is now an optional field.

  • Updated the btype field description.

    Important

    Usage of nurl, ext.js_url or ext.liveintent.img_url bid response fields depends on the btype bid request field value.

Removed

  • Deprecated seatbid.bid.ext.liveintent and pmp objects.

v2.2 - June 2014

Added

  • Added the following bid request fields:

    • imp.video.protocols
    • imp.banner.api
    • site.publisher.name
    • app.publisher.name
    • app.name
    • video.companionad.id
    • device.os
    • device.osv
    • device.make
    • device.model
  • Added extended sensitive categories, used in bcat field.

  • Added imp.ext.google and ext.ghostery bid request objects.

Removed

  • Deprecated the following bid request fields:
    • imp.video.protocol
    • ext.google.excluded_attribute
    • ext.google.allowed_vendor_type

v2.1 - April 2014

Added

  • Added seatbid.bid.ext.js_url bid response field.
  • Added the following bid request fields:
    • pmp.deals.wseat
    • imp.banner.expdir
    • at

Updated

  • Bid response seatbid.bid.nurl field is optional now.

v2.0 - February 2014

Added

  • Added application traffic support.
  • Added the following bid request fields:
    • ext.google.excluded_attribute
    • ext.google.allowed_vendor_type
  • Added the following bid response fields:
    • seatbid.bid.ext.google
    • Added seatbid.bid.cid

Updated

  • Bid request site object is optional now.