BidRequest Object

This object describes the nature and behavior of the entity that is the source of the bid request upstream from the OpenX Ad Exchange. The primary purpose of this object is to define post-auction or upstream decisioning when the OpenX Ad Exchange itself does not control the final decision. A common example of this is header bidding.

To enable this object or receive more information, please contact your Business Development Manager.

Extensions object

BidRequest.source.ext

The optional Extensions object can provide additional details about the source of the bid request.

SupplyChain object

BidRequest.source.ext.schain

The SupplyChain object enables buyers to see all parties who are selling or reselling a given bid request. If you would like to receive schain in your bid requests from OpenX, please contact your Platform Development Manager. For more information please see the official IAB spec.

To interpret the OpenX node of the schain object, you can reference OpenX’s sellers.json file that contains a list of all our supply partners at openx.com/sellers.json. To interpret the node of any other advertising system in the schain, simply append “/sellers.json” to the provided asi.

SupplyChainNode object

BidRequest.source.ext.schain.node

Each BidRequest object contains an array with a single Imp object to describe the impression. Each Imp object can contain one of the following objects to describe the ad space:

• Banner
• Video
• Native

In addition, the Imp object can contain a Pmp object along with a Banner or Native object.

For additional publisher enrichment fields, see Supplemental Data.

This object is associated with an impression as an array of metrics. These metrics can offer insight into the impression to assist with decisioning (such as viewability). Each metric is identified by its type, reports the value of the metric, and optionally identifies the source or vendor measuring the value.

To enable this object or receive more information, please contact your Platform Development Manager.

Supported metrics

The following is subject to regular updates. We strongly recommend regularly checking this table for new metrics that are supported by OpenX.

Each Imp object can contain one Banner object, which is required for banner impressions.

For additional details, see the IAB’s OpenRTB 2.5 specification.

For additional publisher enrichment fields, see Supplemental Data.

Extensions object

BidRequest.imp.banner.ext

The optional Extensions object can provide the following details about the banner.

MatchingAdId object

BidRequest.imp.banner.ext.matching_ad_id

Each MatchingAdId object provides details about a matching ad for which OpenX Ad Exchange is soliciting bids.

The Video object provides details about a video ad request. Each Imp object can contain one Video object, which is required for video impressions. Alternatively, an Imp object can contain a Banner or a Native object.

See also, Video Examples.

Guidance on Video creatives

• Suggested maximum file size: 10MB.
• Preferred video file formats: MP4 (H.264) and JavaScript VPAID.
• Accepted video file formats: HTML5, at least one media provided must be in MP4 format.
• Dimensions: Video ads can be rendered in any size video player. For example, 480x360, 640x360, 1920x800.
• Video bitrate: 240kbps - 4mbps, depending on device; at least one media at 1mbps or below is required.
• Max frame rate: 30FPS.
• Playback methods: All playback methods defined in OpenRTB are supported.
• Video types:
  • In-stream (an ad that appears within video content, and can be pre, mid, or post-roll)
  • Out-stream
  • Interstitial: for mobile app video and opt-in video, video type is interstitial.

NOTE

Flash support deprecation: July 3, 2017. Deprecation includes the VPAID 1.0 API Framework and the following MIME types: application/x-shockwave-flash and video/x-flv.

For additional details, see the IAB’s OpenRTB 2.5 specification.

For additional publisher enrichment fields, see Supplemental Data.

Extensions object

BidRequest.imp.video.ext

Provides additional details about the video ad. The Video object may include an Extensions object.

BidRequest.imp.video.ext.matching_ad_id

Each MatchingAdId object provides details about a matching ad for which Ad Exchange is soliciting bids.

The Native object provides details about a native ad request. A well-structured response must comply with the OpenRTB dynamic native ads API specification.

Each Imp object can contain one Native object, which is required for native impressions. Alternatively, an Imp object can contain a Banner object.

Before the implementation of the OpenRTB native ads API, OpenX used key value pairs to describe a native ad opportunity. OpenX now passes a serialized string of structured JSON data describing the opportunity via the BidRequest.imp.native.request field. To respond to this opportunity, send your native markup via the BidResponse.seatbid.bid.adm field.

NOTE

Native ads are currently not available in the OpenX Ad Exchange.

For additional details, see the IAB’s:

• OpenRTB 2.5 specification
• OpenRTB dynamic native ads API specification
• Supplemental Data (for additional publisher enrichment fields)

This object represents an allowed size (specifically, height and width combination) for a banner impression. These are typically used as an array of objects for an impression where multiple sizes are permitted. It is recommended to submit multiple bids in a single BidResponse if you want to take advantage of the format object for multiple ad sizes.

To enable this object, or for more information about how to use the format object, please contact your Platform Development Manager.

Format object example

"banner": {
            "format": [
                {"w": 728, "h": 90},
                {"w": 320, "h": 50},
                {"w": 160, "h": 60}
              ],
          }    

If the available impression is on a website, Ad Exchange may include a Site object to describe the website.

A BidRequest can only contain a single Site or App object, not both.

A Site object can reference the Publisher object and the Content object.

For additional details, see:

• IAB’s OpenRTB 2.5 specification
• Supplemental Data (for additional publisher enrichment fields)

If the available impression is within a mobile app, the BidRequest includes the App object to describe the mobile app.

A BidRequest can only contain a single App or Site object, not both.

An App object can reference the Content object.

For additional details, see IAB’s OpenRTB 2.5 specification.

For additional publisher enrichment fields, see Supplemental Data.

The Publisher object describes the seller of the ad space (for the App or Site) in which the ad is displayed.

For additional publisher enrichment fields, see Supplemental Data.

The Content object describes the type of content of the App or Site in which the ad is displayed. The OpenX implementation currently supports a subset of the OpenRTB Content object.

This section contains some Beta out-stream content for Video. If you are already consuming out-stream bid requests, you may be able to use the same style parsing for out-stream when you consume your OpenX bid requests. If you aren’t already consuming out-stream bid requests and are interested in doing so, we advise you build toward the IAB’s OpenRTB 2.5 specification, leveraging the new placement field for the Video object. Please reach out to your OpenX Platform Development Manager if you have any questions.

For additional details, see:

• IAB’s OpenRTB 2.5 specification
• Supplemental Data (for additional publisher enrichment fields)

Each BidRequest object may contain a Device object, which provides details about the end-user’s computing environment. The Device object can contain an Extensions object (see below) and can reference the Geo object.

For additional details, see:

• IAB’s OpenRTB 2.5 specification
• Supplemental Data (for additional publisher enrichment fields)

To provide additional details about the end-user’s device, the Device object may include an Extensions object.

The Geo object provides details about the user’s current location (in relation to the Device object) or their primary location (via the User object).

Each Geo object can include the optional Extensions object (see below).

For additional details, see:

• IAB’s OpenRTB 2.5 specification
• Supplemental Data (for additional publisher enrichment fields)

To provide additional details about the end-user’s physical location, the Geo object may include an Extensions object.

Each BidRequest object can contain a User object, which provides details about the end-user.

The User object can contain an Extensions object and can reference the user’s Geo via their Device.

NOTE

With the enactment of the General Data Protection Regulation (GDPR), OpenX includes GDPR-specific elements in its support of OpenRTB. For more information, please contact your OpenX Platform Development Manager. See also Regs object.

For additional publisher enrichment fields, see Supplemental Data.

To provide additional details about the end-user, Ad Exchange may include an Extensions object.

See also, OpenRTB Advisory-GDPR.

The Data object provides details about the user.

NOTE

This object is supported, but not currently populated. Ask your Platform Development Manager for more details.

For additional publisher enrichment fields, see Supplemental Data.

The Segment object provides data about the user.

NOTE

This object is supported, but not currently populated. Ask your Platform Development Manager for more details.

For additional publisher enrichment fields, see Supplemental Data.

With the enactment of the General Data Protection Regulation (GDPR), OpenX includes GDPR-specific elements in its support of OpenRTB. For more information, please contact your OpenX Platform Development Manager. See also User object.

The Regs object provides details about any regulations applicable to the request.

The optional Extensions object can provide additional regulatory details.

The us_privacy string consists of the following components.

The Imp object can contain a Pmp object, which describes deals eligible for impressions.

If the Pmp object is sent, its fields are always sent.

See also, PMP bid request sample.

The Deal object (direct deals) describes a list of deals eligible for impressions. If the Deal object is sent, its at field is sent.