OpenRTB Integration

This guide covers integration of OpenRTB 2.5 and Native ads with Google Ad Exchange.

See also the OpenRTB proto file.

OpenRTB implementation on Google Ad Exchange is available in two similar formats. This page serves as a reference for both:

  • JSON: Limit of 5 kQPS per bidder.
  • Protobuf: .proto definition file can be referenced for message decoding.

See the Examples below for more details.

Integration considerations

How to use this document

The tables below contain definitions of objects, including the object's name, whether or not it's required in the bid request or bid response, its equivalent in our Ad Exchange Protobuf, and some implementation details.

Also note that:

  • Naming in the sections below follows OpenRTB for simplicity.
  • All fields will be populated in the request if available. We will never pass null values or empty strings.
  • Types and descriptions from OpenRTB aren't included in the tables below; see the OpenRTB proto file.

Counting impressions and macro

To limit discrepancies, we recommend using the impression_tracking_url field for all inventory, including native.

Ad Exchange buyers should remove impression tracking pixels from the creative (ad markup), and include the impression_tracking_url field in the bid response instead. The impression_tracking_url fires when the impression is considered billable. This provides more accuracy than tracking pixels, which can track impressions that, because of prefetching, were fetched by the app, but never rendered. Use the encrypted %%WINNING_PRICE%% macro for this field, or the ${AUCTION_PRICE} macro. Also note that an array is expected.

5 kQPS limit and migration to Protobuf

Protobuf encoding is much more efficient in terms of bandwidth and processing, and is therefore recommended. Implementations using OpenRTB JSON will be limited to a maximum of 5 kQPS. The migration to Protobuf is trivial since both formats have matching fields.

When migrating from JSON to Protobuf, make sure the field cid is set up as a string in the bid response. We use that field to link the bid to your billing_id within your pretargeting. If it's not readable, we won't accept the bid.

VAST and video support

We support SSL URLs rather than the full XML for VAST ads.

Note that in OpenRTB 2.4 and higher, if video.skip=1, buyers can bid with non-skippable or skippable video creatives. We recommended opting in to Skip Correction during account setup, because in OpenRTB no distinction is made between ALLOW_SKIPPABLE and REQUIRE_SKIPPABLE.

Unsupported fields

The Nurl field is currently not supported, but impression_tracking_url is . See the comments above regarding impression_tracking_url. Note that burl is also supported in OpenRTB 2.5 or higher.

No bid

If the client does not want to bid, the client could reply with a 204 code.

Real-time feedback

OpenRTB does not support real-time feedback on bid responses at this time.

Enums

All enums can be found in the official documentation for OpenRTB 2.5 and Native ads.

Note that MRAID-1 is a subset of MRAID-2. In OpenRTB 2.1 and earlier, value 3 was MRAID. However, not all MRAID-capable APIs understand MRAID-2 features, so the only safe interpretation of value 3 is MRAID-1. In OpenRTB 2.2, this was made explicit and MRAID-2 has been added as value 5.

Bid request variables and definitions

Bidrequest object

OpenRTB 2.0

The top-level bid request object contains a globally unique bid request or auction ID. This ID attribute is required, as is at least one Imp (impression) object. Other attributes in this top-level object establish rules and restrictions that apply to all impressions being offered.

There are also several subordinate objects that provide detailed data to potential buyers. Among these are the Site and App objects which describe the type of published media in which the impressions appear. These objects are highly recommended, but only one applies to a given bid request depending on whether the media is browser-based web content or a non-browser application, respectively.

Attribute Always passed Type Ad Exchange equivalent Implementation details
id Yes string BidRequest.id Unique ID of the bid request, provided by the exchange.

OpenRTB is base64 (no padding).

imp Yes Array of Imp objects BidRequest.AdSlot Representing the impressions offered.

At least 1 Imp object is required.

site No Site object BidRequest Details via a about the publisher's website.

Only applicable and recommended for websites.

One off with app.

app No App object BidRequest, BidRequest.Mobile Details about the publisher's app.

(non-browser applications). Only applicable and recommended for apps.

One off with site.

device No Device object BidRequest.Mobile, BidRequest.Device Details about the user's device to which the impression will be delivered.
regs No Regs object Specifies any industry, legal, or governmental regulations in force for this request.
user No User object BidRequest Details about the human user of the device; the advertising audience.
at No Auction type 2 where 1 = First Price, 2 = Second Price Plus.

Exchange-specific auction types can be defined using values > 500.

tmax No int32 fixed to 100ms Maximum time in milliseconds to submit a bid to avoid timeout. This value is commonly communicated offline.
wseat No string Not supported Whitelist of buyer seats (e.g., advertisers, agencies) allowed to bid on this impression. IDs of seats and knowledge of the buyer's customers to which they refer must be coordinated between bidders and the exchange a priori. Omission implies no seat restrictions.
allimps No bool Not supported Flag to indicate if Exchange can verify that the impressions offered represent all of the impressions available in context (e.g., all on the web page, all video spots such as pre/mid/post roll) to support road-blocking. 0 = no or unknown, 1 = yes, the impressions offered represent all that are available.
cur No Array of string Not supported Array of allowed currencies for bids on this bid request using ISO-4217 alpha codes. Recommended only if the exchange accepts multiple currencies.
bcat No Array of string BidRequest.AdSlot.
excluded_sensitive_category, BidRequest.AdSlot.
excluded_product_category
Blocked advertiser categories using the IAB content categories. Refer to enum ContentCategory.
badv No Array of string Not supported Block list of advertisers by their domains (e.g., "ford.com")
bapp No Array of string Not supported Block list of applications by their platform-specific exchange independent application identifiers. On Android, these should be bundle or package names (e.g., com.foo.mygame). On iOS, these are numeric IDs.
test No bool Not supported Indicator of test mode in which auctions are not billable, where 0 = live mode, 1 = test mode. Default : 1
bseat No string Not supported Block list of buyer seats (e.g., advertisers, agencies) restricted from bidding on this impression. IDs of seats and knowledge of the buyer's customers to which they refer must be coordinated between bidders and the exchange a priori. At most, only one of wseat and bseat should be used in the same request. Omission of both implies no seat restrictions.
wlang No string BidRequest.AdSlot.allowed_languages Whitelist of languages for creatives using ISO-639-1-alpha-2. Omission implies no specific restrictions, but buyers would be advised to consider language attribute in the Device and/or Content objects if available.
source No Source object Not supported A Source object that provides data about the inventory source and which entity makes the final decision.
ext No ImpExt object Not supported For OpenRTB Protobuf, [com.google.doubleclick.imp] is used in place of imp.ext.

Source object

OpenRTB 2.5

This object describes the nature and behavior of the entity that is the source of the bid request upstream from the exchange. The primary purpose of this object is to define post-auction or upstream decisioning when the exchange itself does not control the final decision. A common example of this is header bidding, but it can also apply to upstream server entities such as another RTB exchange, a mediation platform, or an ad server combines direct campaigns with 3rd party demand in decisioning.

Attribute Always passed Type Ad Exchange equivalent Implementation details
fd No boolean Not supported Entity responsible for the final impression sale decision, where 0 = exchange, 1 = upstream source RECOMMENDED by the OpenRTB specification.
tid No string Not supported Transaction ID that must be common across all participants in this bid request (e.g., potentially multiple exchanges). RECOMMENDED by the OpenRTB specification.
pchain No string Not supported Payment ID chain string containing embedded syntax described in the TAG Payment ID Protocol v1.0. RECOMMENDED by the OpenRTB specification.

Imp object

OpenRTB 2.0

This object describes an ad placement or impression being auctioned. A single bid request can include multiple Imp objects, a use case for which might be an exchange that supports selling all ad positions on a given page. Each Imp object has a required ID so that bids can reference them individually.

The presence of Banner, Video, and/or Native objects (see below) subordinate to the Imp object indicates the type of impression being offered. The publisher can choose one such type which is the typical case or mix them at their discretion. Any given bid for the impression must conform to one of the offered types.

Attribute Always passed Type Ad Exchange equivalent Implementation details
id Yes string Not supported A unique identifier for this impression within the context of the bid request (typically, value starts with 1, and increments up to n for n impressions).
banner No Banner object BidRequest.AdSlot A Banner object; required if this impression is offered as a banner ad opportunity.
video No Video object BidRequest.AdSlot, BidRequest.Video Required if this impression is offered as a video ad opportunity.
audio No Audio

object

Not supported Required if this impression is offered as an audio ad opportunity.
displaymanager No string Not supported Name of ad mediation partner, SDK technology, or player responsible for rendering ad (typically video or mobile). Used by some ad servers to customize ad code by partner. Recommended for video and/or apps.
displaymanagerver No string Not supported Version of ad mediation partner, SDK technology, or player responsible for rendering ad (typically video or mobile). Used by some ad servers to customize ad code by partner. Recommended for video and/or apps.
instl No bool BidRequest.AdSlot.Mobile.
is_interstitial_request
1 = the ad is interstitial or full screen, 0 = not interstitial.
tagid No string BidRequest.AdSlot.ad_block_key Identifier for specific ad placement or ad tag that was used to initiate the auction. This can be useful for debugging of any issues, or for optimization by the buyer.
bidfloor No double min(BidRequest.AdSlot.
matching_ad_data.
minimum_cpm_micros) * 1,000,000
Minimum bid for this impression expressed in CPM.
bidfloorcur No string Not supported Currency specified using ISO-4217 alpha codes. This may be different from bid currency returned by bidder if this is allowed by the exchange.

A single currency, obtained from the included billing_id.

clickbrowser No bool Not supported Indicates the type of browser opened upon clicking the creative in an app, where 0 = embedded, 1 = native.

Note that the Safari View Controller in iOS 9.x devices is considered a native browser for purposes of this attribute.

secure No bool BidRequest.ad_slot.excluded_attribute 48:RichMediaCapabilityNonSSL Flag to indicate if the impression requires secure HTTPS URL creative assets and markup, where 0 = non-secure, 1 = secure. If omitted, the secure state is unknown, but non-secure HTTP support can be assumed.
iframebuster No Array of string Unsupported;
use macro %%CACHEBUSTER%%
in the snippet
Array of exchange-specific names of supported iframe busters.
pmp No Pmp object BidRequest.AdSlot.MatchingAdData A Pmp object containing any private marketplace deals in effect for this impression.
native No Native BidRequest.AdSlot.NativeAdTemplate A Native object; required if this impression is offered as a native ad opportunity.
exp No int32 Not supported Advisory as to the number of seconds that may elapse between the auction and the actual impression.
metric No Array of Metric object BidRequest.AdSlot.viewability, BidRequest.AdSlot.click_through_rate, BidRequest.AdSlot.video_completion_rate An array of Metric object. AdX supplies three metrics for this field: click_through_rate, viewability, and completion_rate. The viewability metric is a fraction from 0.0 to 1.0 in the OpenRTB metric, but it's expressed as a percentage [0-100] in the AdX protocol. See the AdSlot object table in the Realtime Bidding Guide for descriptions of these metrics.

Metric object

OpenRTB 2.5

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 average recent viewability, click-through rate, etc. Each metric is identified by its type, reports the value of the metric, and optionally identifies the source or vendor measuring the value.

Attribute Always passed Type Ad Exchange equivalent Implementation details
type No string One of: BidRequest.AdSlot.viewability, BidRequest.AdSlot.click_through_rate, BidRequest.AdSlot.video_completion_rate Type of metric being presented using exchange curated string names which should be published to bidders a priori. REQUIRED by the OpenRTB specification. The three types we support are: click_through_rate, viewability, and completion_rate.
value No double Value between 0 and 1. Number representing the value of the metric. Probabilities must be in the range 0.0 – 1.0. REQUIRED by the OpenRTB specification. The viewability metric is a fraction from 0.0 to 1.0 in the OpenRTB metric, but it's expressed as a percentage [0-100] in the AdX protocol.
vendor No string EXCHANGE Source of the value using exchange curated string names which should be published to bidders a priori. If the exchange itself is the source versus a third party, "EXCHANGE" is recommended. RECOMMENDED by the OpenRTB specification.

Banner object

OpenRTB 2.0

This object represents the most general type of impression. Although the term "banner" may have very specific meaning in other contexts, here it can be many things including a simple static image, an expandable ad unit, or even in-banner video (refer to the Video object for the more generalized and full featured video ad units). An array of Banner objects can also appear within the Video to describe optional companion ads defined in the VAST specification.

The presence of a Banner as a subordinate of the Imp object indicates that this impression is offered as a banner type impression. At the publisher's discretion, that same impression may also be offered as video and/or native by also including as Imp subordinates the Video and/or Native objects, respectively. However, any given bid for the impression must conform to one of the offered types.

Attribute Always passed Type Ad Exchange equivalent Implementation details
w No int32 BidRequest.AdSlot.width[0] Width in device independent pixels (DIPS). If no Format objects are specified, this is an exact width requirement. Otherwise it is a preferred width.
h No int32 BidRequest.AdSlot.height[0] Height in device independent pixels (DIPS). If no Format objects are specified, this is an exact height requirement. Otherwise it is a preferred height.
format No Array of Format object Not supported Array of Format objects representing the banner sizes permitted. If none are specified, then use of the h and w attributes is highly recommended.
id No string BidRequest.AdSlot.id Unique identifier for this Banner object. Recommended when Banner objects are used with a Video object to represent an array of companion ads. Values usually start at 1 and increase with each object; should be unique within an impression.
pos No Enum AdPosition BidRequest.AdSlot.slot_visibility This OpenRTB table has values derived from the IAB Quality Assurance Guidelines (QAG). Practitioners should keep in sync with updates to the QAG values as published on IAB.net. Values "3" - "6" apply to apps per the mobile addendum to QAG version 1.5.

Examples:
UNKNOWN = 0;
ABOVE_THE_FOLD = 1;
BELOW_THE_FOLD = 3;

btype No Array of enum BannerAdType Not supported Blocked banner ad types

Examples:
XHTML_TEXT_AD = 1; // "Usually mobile".
XHTML_BANNER_AD = 2; // "Usually mobile".
JAVASCRIPT_AD = 3; // Javascript must be valid xhtml
IFRAME = 4; // Iframe.

battr No Array of CreativeAttribute enum BidRequest.AdSlot.excluded_attribute Blocked creative attributes.

Examples:
AUDIO_AUTO_PLAY = 1;
AUDIO_USER_INITIATED = 2;

mimes No Array of string Only mapped for BidRequest.Video.companionad: BidRequest.Video.companionad.creative_format, BidRequest.AdSlot.excluded_attribute / VPAID Whitelist of content MIME types supported. Popular MIME types include, but are not limited to "image/jpg", "image/gif" and"application/x-shockwave-flash".
topframe No bool BidRequest.AdSlot.iframing_state

NO_IFRAME: false
SAME_DOMAIN_IFRAME, CROSS_DOMAIN_IFRAME: true

Specify if the banner is delivered in the top frame (true) or in an iframe (false).
expdir No Array of ExpandableDirection enum BidRequest.AdSlot.excluded_attribute / EXPANDING_* Directions in which the banner may expand.
api No Array of APIFramework BidRequest.AdSlot.excluded_attribute / MRAID_1_0 List of supported API frameworks for this impression. If an API is not explicitly listed, it is assumed not to be supported.
vcm No bool BidRequest.Video.end_cap_support Relevant only for Banner objects used with a Video object in an array of companion ads. Indicates the companion banner rendering mode relative to the associated video, where 0 = concurrent, 1 = end-card. We currently only support end-cards on mApp video interstitials.

Format object

OpenRTB 2.4

This object represents an allowed size (height and width combination) for a banner impression. These are typically used in an array for an impression where multiple sizes are permitted.

Attribute Always passed Type Ad Exchange equivalent Implementation details
w No int32 Not supported Width in device independent pixels (DIPS).
h No int32 Not supported Height in device independent pixels (DIPS).
wratio No int32 Not supported Relative width when expressing size as a ratio.
hratio No int32 Not supported Relative height when expressing size as a ratio.
wmin No int32 Not supported The minimum width in device independent pixels (DIPS) at which the ad will be displayed when the size is expressed as a ratio.

Video object

OpenRTB 2.0

This object represents an in-stream video impression. Many of the fields are non-essential for minimally viable transactions, but are included to offer fine control when needed. Video in OpenRTB generally assumes compliance with the VAST standard. As such, the notion of companion ads is supported by optionally including an array of Banner objects that define these companion ads.

The presence of a Video as a subordinate of the Imp object indicates that this impression is offered as a video type impression. At the publisher's discretion, that same impression may also be offered as banner and/or native by also including as Imp subordinates the Banner and/or Native objects, respectively. However, any given bid for the impression must conform to one of the offered types.

Attribute Always passed Type Ad Exchange equivalent Implementation details
mimes No Array of string BidRequest.Video.
allowed_video_formats, BidRequest.AdSlot.
excluded_attribute / VPAID
Whitelist of content MIME types supported. Popular MIME types include but are not limited to "image/jpg", "image/gif" and "application/x-shockwave-flash".

REQUIRED by the OpenRTB specification: at least 1 element.

linearity No int32 Not supported Indicates if the impression must be linear, nonlinear, etc. If none specified, assume all are allowed.

LINEAR = 1; // Linear/In-stream
NON_LINEAR = 2; // Non-linear/Overlay

minduration No int32 BidRequest.Video.
min_ad_duration
Minimum video ad duration in seconds.

RECOMMENDED by the OpenRTB specification.

maxduration No int32 BidRequest.Video.
max_ad_duration
Maximum video ad duration in seconds.

RECOMMENDED by the OpenRTB specification.

protocols No Array of Protocol BidRequest.Video.protocols Array of supported video bid response protocols.

At least one supported protocol must be specified.

Examples:
VAST_1_0 = 1;
VAST_2_0 = 2;
VAST_3_0 = 3;

w No int32 BidRequest.AdSlot.
width[0]
Width of the video player in device independent pixels (DIPS).

RECOMMENDED by the OpenRTB specification.

h No int32 BidRequest.AdSlot.
height[0]
Height of the video player in device independent pixels (DIPS)

RECOMMENDED by the OpenRTB specification.

startdelay No in32 BidRequest.Video.
videoad_start_delay

0: PRE_ROLL
1: GENERIC_MID_ROLL
-1: GENERIC_POST_ROLL

Other values:
videoad_start_delay / 1,000

Indicates the start delay in seconds for pre-roll, mid-roll, or post-roll ad placements. Refer to enum StartDelay for generic values.

RECOMMENDED by the OpenRTB specification.

skip No bool Not supported Indicates if the player will allow the video to be skipped / where 0 = no, 1 = yes. If a bidder sends markup/creative that is itself skippable, the Bid object should include the attr array with an element of 16 indicating skippable video.
skipmin No int32 Not supported Videos of total duration greater than this number of seconds can be skippable; only applicable if the ad is skippable.
skipafter No int32 Not supported Number of seconds a video must play before skipping is enabled; only applicable if the ad is skippable.
sequence No int32 Not supported If multiple ad impressions are offered in the same bid request, the sequence number will allow for the coordinated delivery of multiple creatives.[default = 1];
battr No Array of
CreativeAttribute
BidRequest.AdSlot.
excluded_attribute
Blocked creative attributes.
maxextended No int32 Not supported Maximum extended video ad duration, if extension is allowed. If blank or 0, extension is not allowed. If -1, extension is allowed, and there is no time limit imposed. If greater than 0, then the value represents the number of seconds of extended play supported beyond the maxduration value.
minbitrate No int32 Not supported Minimum bit rate in Kbps.
maxbitrate No int32 Not supported Maximum bit rate in Kbps.
boxingallowed No bool Not supported Indicates if letter-boxing of 4:3 content into a 16:9 window is allowed, where 0 = no, 1 = yes.
default = true
playbackmethod No Array of
PlaybackMethod
BidRequest.Video.
playback_method
Playback methods that may be in use. If none are specified, any method may be used. Only one method is typically used in practice. As a result, this array may be converted to an integer in a future version of the specification. It is strongly advised to use only the first element of this array in preparation for this change.

// [AdX: VideoPlaybackMethod.AUTO_PLAY_SOUND_ON]
AUTO_PLAY_SOUND_ON = 1;
// [AdX: VideoPlaybackMethod.AUTO_PLAY_SOUND_OFF]
AUTO_PLAY_SOUND_OFF = 2;
// [AdX: VideoPlaybackMethod.CLICK_TO_PLAY]
CLICK_TO_PLAY = 3;

delivery No Array of
ContentDelivery
Method
Not supported Supported delivery methods (e.g., streaming, progressive). If none specified, assume all are supported.
STREAMING = 1;
PROGRESSIVE = 2;
pos No AdPosition BidRequest.AdSlot.
slot_visibility
Ad position on screen.
companionad No Array of Banner BidRequest.Video.
companion_slot
Array of Banner objects if companion ads are available.
api No Array of APIFramework BidRequest.AdSlot.
excluded_attribute
/ MRAID_1_0
List of supported API frameworks for this impression. If an API is not explicitly listed, it is assumed not to be supported.
companiontype No Array of
CompanionType
BidRequest.Video.
companion_slot.
creative_format
Supported VAST companion ad types. Recommended if companion Banner objects are included via the companionad array.
placement No VideoPlacementType BidRequest.Video.Placement Placement type for the impression.
playbackend No PlaybackCessationMode Not supported The event that causes playback to end.

Audio object

This object represents an audio type impression. Many of the fields are non-essential for minimally viable transactions, but are included to offer fine control when needed. Audio in OpenRTB generally assumes compliance with the DAAST standard. As such, the notion of companion ads is supported by optionally including an array of Banner objects that define these companion ads. The presence of an Audio object as a subordinate of the Imp object indicates that this impression is offered as an audio type impression. At the publisher's discretion, that same impression may also be offered as banner, video, and/or native by also including as Imp subordinates objects of those types. However, any given bid for the impression must conform to one of the offered types.

Attribute Always passed Type Ad Exchange equivalent Implementation details
mimes No Array of string Not supported Content MIME types supported (e.g., "audio/mp4")

REQUIRED by the OpenRTB specification: at least 1 element.

minduration No int32 Not supported Minimum video ad duration in seconds.

RECOMMENDED by the OpenRTB specification.

maxduration No int32 Not supported Maximum video ad duration in seconds.

RECOMMENDED by the OpenRTB specification.

protocols No Array of Protocol Not supported Array of supported video bid response protocols. At least one supported protocol must be specified.

Examples:
DAAST_1_0 = 9;
DAAST_1_0_WRAPPER = 10;

startdelay No in32 Not supported Indicates the start delay in seconds for pre-roll, mid-roll, or post-roll ad placements. Refer to enum StartDelay for generic values.

RECOMMENDED by the OpenRTB specification.

sequence No int32 Not supported If multiple ad impressions are offered in the same bid request, the sequence number will allow for the coordinated delivery of multiple creatives.[default = 1];
battr No Array of CreativeAttribute Not supported Blocked creative attributes.
maxextended No int32 Not supported Maximum extended video ad duration, if extension is allowed. If blank or 0, extension is not allowed. If -1, extension is allowed, and there is no time limit imposed. If greater than 0, the value represents the number of seconds of extended play supported beyond the maxduration value.
minbitrate No int32 Not supported Minimum bit rate in Kbps.
maxbitrate No int32 Not supported Maximum bit rate in Kbps.
delivery No Array of ContentDeliveryMethod Not supported Supported delivery methods (e.g., streaming, progressive). If none specified, assume all are supported.

STREAMING = 1;
PROGRESSIVE = 2;

companionad No Array of Banner Not supported Array of Banner objects if companion ads are available.
api No Array of APIFramework Not supported List of supported API frameworks for this impression. If an API is not explicitly listed, it is assumed not to be supported.
companiontype No Array of CompanionType Not supported Supported DAAST companion ad types.
maxseq No int32 Not supported The maximum number of ads that can be played in an ad pod.
feed No FeedType Not supported Type of audio feed.
stitched No bool Not supported Indicates if the ad is stitched with audio content or delivered independently, where 0 = no, 1 = yes.
nvol No VolumeNormalizationMode Not supported Volume normalization mode.

Native object

OpenRTB 2.3

This object represents a native type impression. Native ad units are intended to blend seamlessly into the surrounding content (e.g., a sponsored Twitter or Facebook post). As such, the response must be well-structured to afford the publisher fine-grained control over rendering.

The Native Subcommittee developed a companion specification to OpenRTB called the Native Ad Specification. It defines the request parameters and response markup structure of native ad units.

This object provides the means of transporting request parameters as an opaque string so that the specific parameters can evolve separately under the auspices of the Native Ad Specification. Similarly, the ad markup served will be structured according to that specification. The presence of a Native as a subordinate of the Imp object indicates that this impression is offered as a native type impression. At the publisher's discretion, that same impression may also be offered as banner and/or video by also including as Imp subordinates the Banner and/or Video objects, respectively. However, any given bid for the impression must conform to one of the offered types.

Attribute Always passed Type Ad Exchange equivalent Implementation details
request No string BidRequest.AdSlot.NativeAdTemplate Request payload complying with the Native Ad Specification.

Exactly one of {request, request_native} should be used.

request_native No NativeRequest BidRequest.AdSlot.NativeAdTemplate Request payload complying with the Native Ad Specification. Exactly one of {request, request_native} should be used; this is an alternate field preferred for Protobuf serialization.
ver No string RECOMMENDED by the OpenRTB specification. Version of the Native Ad Specification to which request complies. RECOMMENDED by the OpenRTB specification.
api Array of APIFramework BidRequest.AdSlot.excluded_attribute / MRAID_1_0 List of supported API frameworks for this impression. If an API is not explicitly listed, it is assumed not to be supported.
battr Array of CreativeAttribute BidRequest.AdSlot.excluded_attribute Blocked creative attributes.

PMP object

OpenRTB 2.2

This object is the private marketplace container for direct deals between buyers and sellers that may pertain to this impression. The actual deals are represented as a collection of Deal objects.

Attribute Always passed Type Ad Exchange equivalent Implementation details
private_auction No bool Not supported Indicator of auction eligibility to seats named in the Direct Deals object, where 0 = all bids are accepted, 1 = bids are restricted to the deals specified and the terms thereof.
deals No Array of Deal BidRequest.AdSlot.MatchingAdData.DirectDeal Array of Deal objects that convey the specific deals applicable to this impression.

Deal object

OpenRTB 2.2

This object constitutes a specific deal that was struck a priori between a buyer and a seller. Its presence with the Pmp collection indicates that this impression is available under the terms of that deal.

Attribute Always passed Type Ad Exchange equivalent Implementation details
id yes string BidRequest.AdSlot.
MatchingAdData.DirectDeal.
direct_deal_id
A unique identifier for the direct deal. REQUIRED by the OpenRTB specification.
bidfloor No double BidRequest.AdSlot.
MatchingAdData.DirectDeal.
fixed_cpm_micros *1,000,000
Minimum bid for this impression expressed in CPM.
bidfloorcur No string single currency, obtained from the included billing_id Currency specified using ISO-4217 alpha codes. This may be different from bid currency returned by bidder if this is allowed by the exchange.default = "USD"
wseat No Array of string Not supported Whitelist of buyer seats (e.g., advertisers, agencies) allowed to bid on this deal. IDs of seats and knowledge of the buyer's

customers to which they refer must be coordinated between bidders and the exchange a priori. Omission implies no seat restrictions.

wadomain No Array of string Not supported Array of advertiser domains (e.g., advertiser.com) allowed to bid on this deal. Omission implies no advertiser restrictions.
at No AuctionType BidRequest.AdSlot.
MatchingAdData.
DirectDeal.deal_type
Optional override of the overall auction type of the bid request, where 1 = First Price, 2 = Second Price Plus, 3 = the value passed in bidfloor is the agreed upon deal price. Additional auction types can be defined by the exchange.

Site object

OpenRTB 2.0

This object should be included if the ad supported content is a website as opposed to a non-browser application. A bid request must not contain both a Site and an App object. At a minimum, it is useful to provide a site ID or page URL, but this is not strictly required.

Attribute Always passed Type Ad Exchange equivalent Implementation details
id No string Not supported Site ID on the exchange. RECOMMENDED by the OpenRTB specification.
name No string BidRequest.anonymous_id Site name (may be masked at publisher's request)
domain No string Not supported Domain of the site, used for advertiser side blocking. For example, "foo.com".
cat No Array of string Not supported Array of IAB content categories of the site. See enum ContentCategory.
sectioncat No Array of string Not supported Array of IAB content categories that describe the current section of the site. See enum ContentCategory.
pagecat No Array of string Not supported Array of IAB content categories that describe the current page or view of the site. See enum ContentCategory.
page No string BidRequest.url URL of the page where the impression will be shown
privacypolicy No bool Not supported Indicates if the site has a privacy policy, where 0 = no, 1 = yes.
ref No string Not supported Referrer URL that caused navigation to the current page.
search No string Not supported Search string that caused navigation to the current page.
publisher No Publisher object BidRequest Details about the Publisher object of the site.
content No Content object BidRequest Details about the Content within the site.
keywords No string Not supported Comma-separated list of keywords about this site. Note: OpenRTB 2.2 allowed an array of strings as alternate implementation but this was fixed in 2.3+ where it's definitely a single string with CSV content again. Compatibility with some OpenRTB 2.2 exchanges that adopted vthe alternate representation may require custom handling of the JSON.
mobile No bool BidRequest.Mobile.
is_mobile_web_optimized
Indicates if the site has been programmed to optimize layout when viewed on mobile devices, where 0 = no, 1 = yes.

App object

OpenRTB 2.0

This object should be included if the ad supported content is a non-browser application (typically in mobile) as opposed to a website. A bid request must not contain both an App and a Site object. At a minimum, it is useful to provide an App ID or bundle, but this is not strictly required.

Attribute Always passed Type Ad Exchange equivalent Implementation details
id No string Not supported Application ID on the exchange. RECOMMENDED by the OpenRTB specification.
name No string BidRequest.Mobile.
app_name
Application name (may be aliased at publisher's request)
domain No string Not supported Domain of the application, used for advertiser side blocking. For example, "mygame.foo.com".
cat No Array of string Not supported Array of IAB content categories of the app. See enum ContentCategory.
sectioncat No Array of string Not supported Array of IAB content categories that describe the current section of the app. See enum ContentCategory.
pagecat No Array of string Not supported Array of IAB content categories that describe the current page or view of the app. See enum ContentCategory.
ver No string Not supported Application version.
bundle No string BidRequest.Mobile.
app_id
A platform-specific application identifier intended to be unique to the app and independent of the exchange. On Android, this should be a bundle or package name (e.g., com.foo.mygame). On iOS, it is a numeric ID.
privacypolicy No bool Not supported Indicates if the site has a privacy policy, where 0 = no, 1 = yes.
paid No bool Not supported 0 = app is free, 1 = the app is a paid version.
publisher No Publisher object BidRequest Details about the Publisher object of the app.
content No Content object BidRequest Details about the Content within the app.
keywords No string Not supported Comma-separated list of keywords about this app. Note: OpenRTB 2.2 allowed an array of strings as alternate implementation but this was fixed in 2.3+ where it's definitely a single string with CSV content again. Compatibility with some OpenRTB 2.2 exchanges that adopted the alternate representation may require custom handling of the JSON.
storeurl No string Not supported App store URL for an installed app; for QAG 1.5 compliance.

Publisher object

OpenRTB 2.0

This object describes the publisher of the media in which the ad will be displayed. The publisher is typically the seller in an OpenRTB transaction.

Attribute Always passed Type Ad Exchange equivalent Implementation details
id No string BidRequest.seller_network_id Exchange-specific publisher ID.
name No string Not supported Publisher name (may be aliased at publisher's request)
cat No Array of string Not supported Array of IAB content categories of the app. See enum ContentCategory.
domain No string Not supported Highest level domain of the publisher (e.g., "publisher.com")

Content object

OpenRTB 2.0

This object describes the content in which the impression will appear, which may be syndicated or non-syndicated content. This object may be useful when syndicated content contains impressions and does not necessarily match the publisher's general content. The exchange might or might not have knowledge of the page where the content is running, as a result of the syndication method. An example might be a video impression embedded in an iframe on an unknown web property or device.

Attribute Always passed Type Ad Exchange equivalent Implementation details
id No string (Only App.content)
BidRequest.anonymous_id
ID uniquely identifying the content.
episode No int32 Not supported Content episode number (typically applies to video content).
title No string BidRequest.Video.
ContentAttributes.title
Content title. Video examples: "Search Committee" (television), "A New Hope" (movie),or "Endgame" (made for web). Non-Video example: "Why an Antarctic Glacier Is Melting So Quickly" (Time magazine article).
series No string Not supported Content series. Video examples: "The Office" (television), "Star Wars" (movie) or "Arby 'N' The Chief" (made for web).

Non-Video example: "Ecocentric" (Time Magazine blog)

season No string Not supported Content season; typically for video content (e.g., "Season 3").
artist No string Not supported Artist credited with the content
genre No string Not supported Genre that best describes the content (e.g., rock, pop, etc.).
album No string Not supported Album to which the content belongs; typically for audio.
isrc No string Not supported International Standard Recording Code conforming to ISO-3901.
url No string (Only App.content)
BidRequest.url
URL of the content, for buy-side contextualization or review.
cat No Array of string Not supported Array of IAB content categories that describe the content. See enum ContentCategory.
prodq No ProductionQuality Not supported Production quality.
No BidRequest.Video.
ContentAttributes.keywords
Comma separated list of keywords describing the content.

Note: OpenRTB 2.2 allowed an array of strings as alternate implementation but this was fixed in 2.3+ where it's definitely a single string with CSV content again. Compatibility with some OpenRTB 2.2 exchanges that adopted the alternate representation may require custom handling of the JSON.

contentrating No string BidRequest.detected_content_label 39:
"DV_G", 40: "DV_PG", 41: "DV_T", 42: "DV_MA", 43:
"DV_UNRATED"
Content rating (e.g., MPAA).
userrating No string (Only App.content)
BidRequest.Mobile.app_rating
User rating of the content (e.g., number of stars, likes, etc.).
context No ContentContext Not supported Type of content (game, video, text, etc.).
context_22 No string Not supported OpenRTB <= 2.2 compatibility; use context for 2.3+.
livestream No bool Not supported 0 = not live, 1 = content is live (e.g., stream, live blog).
sourcerelationship No bool Not supported 0 = indirect, 1 = direct.
producer Producer Not supported Details about the content Producer.
len No int32 BidRequest.Video.
ContentAttributes.duration_seconds
Length of content in seconds; appropriate for video or audio.
qagmediarating No QAGMediaRating Not supported Media rating per QAG guidelines.
embeddable No bool Not supported Indicator of whether or not the content is embeddable (e.g., an embeddable video player), where 0 = no, 1 = yes.
language No string BidRequest.detected_language Content language using ISO-639-1-alpha-2.

Producer object

OpenRTB 2.0

This object defines the producer of the content in which the ad will be shown. This is particularly useful when the content is syndicated and may be distributed through different publishers and thus when the producer and publisher are not necessarily the same entity.

Attribute Always passed Type Ad Exchange equivalent Implementation details
id No string Not supported Content producer or originator ID. Useful if content is syndicated, and may be posted on a site using embed tags.
name No string Not supported Content producer or originator name (e.g., "Warner Bros").
cat No Array of string Not supported Array of IAB content categories that describe the content producer. See enum ContentCategory.
domain No string BidRequest.Video.description_url Highest level domain of the content producer (e.g., "producer.com").

Device object

OpenRTB 2.0

This object provides information pertaining to the device through which the user is interacting. Device information includes its hardware, platform, location, and carrier data. The device can refer to a mobile handset, a desktop computer, set-top box, or other digital device.

Attribute Always passed Type Ad Exchange equivalent Implementation details
dnt No bool Unsupported; See Cookie Guide, google_error=1: Standard "Do Not Track" flag as set in the header by the browser, where 0 = tracking is unrestricted, 1 = do not track. RECOMMENDED by the OpenRTB specification.
ua No string Not supported Browser user agent string. RECOMMENDED by the OpenRTB specification.
ip No string BidRequest.ip (AdX truncates to first 3 octets;
OpenRTB is "X.X.X.0")
IPv4 address closest to device. RECOMMENDED by the OpenRTB specification
geo No Geo object BidRequest Location of the device assumed to be the user's current location defined by a Geo object.

RECOMMENDED by the OpenRTB specification.

didsha1 No string Not supported Hardware device ID (e.g., IMEI); hashed via SHA1.
didmd5 No string Not supported Hardware device ID (e.g., IMEI); hashed via MD5.
dpidsha1 No string Not supported Platform device ID (e.g., Android ID); hashed via SHA1
dpidmd5 No string BidRequest.Mobile.hashed_idfa -
AdX is binary, OpenRTB is base16 (lowercase hex)
This is the hashed version of ifa.
Either dpidmd5 or ifa is available
depending on the mobile SDK version.
Platform device ID (e.g., Android ID); hashed via MD5.
ipv6 No string BidRequest.ip

- AdX truncates to first 6 octets; OpenRTB is "X:X:X:::::"

IPv6 address closest to device.
carrier No string BidRequest.Device.carrier_id -
IDs will be the same Criterion IDs as in AdX protocol, see the mobile carriers list.
Carrier or ISP (e.g., "VERIZON"), using exchange curated string names which should be published to bidders a priori.
language No string Not supported Browser language using ISO-639-1-alpha-2.
make No string BidRequest.Device.brand Device make (e.g., "Apple").
model No string BidRequest.Device.model Device model (e.g., "iPhone")
os No string BidRequest.Device.platform Device operating system (e.g., "iOS")
osv No string BidRequest.Device.os_version Device operating system version
hwv No string BidRequest.Device.hardware_version Hardware version of the device (e.g., "5S" for iPhone 5S)
w No int32 BidRequest.Device.screen_width Physical width of the screen in pixels
h No int32 BidRequest.Device.screen_height Physical height of the screen in pixels.
ppi No int32 Not supported Screen size as pixels per linear inch.
pxratio No double BidRequest.Device.screen_pixel_ratio_millis / 1,000 The ratio of physical pixels to device independent pixels.
js No bool Not supported Support for JavaScript, where 0 = no, 1 = yes.
geofetch No bool Not supported Indicates if the geolocation API will be available to JavaScript code running in the banner, where 0 = no, 1 = yes.
connectiontype No ConnectionType Not supported Network connection type
devicetype No DeviceType BidRequest.Device.device_type The general type of device.
flashver No string Not supported Version of Flash supported by the browser.
ifa No string BidRequest.Mobile.advertising_id -
AdX is binary, OpenRTB is 36-char UUID (Android ID: all lowercase, IDFA: all uppercase).
ifa is either Android ID or Apple's IDFA, and either dpidmd5 or
ifa is available depending on the mobile SDK version.
ID sanctioned for advertiser use in the clear (i.e., not hashed).
macsha1 No string Not supported MAC address of the device; hashed via SHA1.
macmd5 No string Not supported MAC address of the device; hashed via MD5
lmt No bool Not supported "Limit Ad Tracking" signal commercially endorsed (e.g., iOS, Android), where 0 = tracking is unrestricted, 1 = tracking must be limited per commercial guidelines.

RECOMMENDED by the OpenRTB specification.

mccmnc No string Not supported Mobile carrier as the concatenated MCC-MNC code (e.g., "310-005" identifies Verizon Wireless CDMA in the USA). Refer to https://en.wikipedia.org/wiki/Mobile_country_code for further examples. Note that the dash between the MCC and MNC parts is required to remove parsing ambiguity.

Geo object

OpenRTB 2.0

This object encapsulates various methods for specifying a geographic location. When subordinate to a Device object, it indicates the location of the device which can also be interpreted as the user's current location. When subordinate to a User object, it indicates the location of the user's home base (i.e., not necessarily their current location). The lat/lon attributes should only be passed if they conform to the accuracy depicted in the type attribute. For example, the centroid of a geographic region such as postal code should not be passed.

Note about the Ad Exchange protocol: fine geolocation information is limited by the same constraints that apply to the Ad Exchange Hyperlocal object. Not all requests have this info, and lat/lon represent some point (not necessarily the center) of an area the size of which is inversely proportional to population density. That's good enough for targeting but not for individual tracking.

Attribute Always passed Type Ad Exchange equivalent Implementation details
lat No double BidRequest.[encrypted_]hyperlocal_set.
center_point.latitude
Latitude from -90.0 to +90.0, where negative is south.
lon No double BidRequest.[encrypted_]hyperlocal_set.
center_point.longitude
Longitude from -180.0 to +180.0, where negative is west.
country No string BidRequest.geo_criteria_id via geo-table.csv Country using ISO-3166-1 Alpha-3.
region No string BidRequest.geo_criteria_id via geo-table.csv Region code using ISO-3166-2; 2-letter state code if USA.
regionfips104 No string Region of a country using FIPS 10-4 notation. While OpenRTB supports this attribute, it has been withdrawn by NIST in 2008.
metro No string BidRequest.geo_criteria_id via geo-table.csv, cities-dma-regions.csv Google metro code; similar to but not exactly Nielsen DMAs.

See the Geographical Targeting page for a link to the codes.

city No string BidRequest.geo_criteria_id via geo-table.csv City using United Nations Code for Trade & Transport Locations. See Appendix A for a link to the codes.
zip No string BidRequest.postal_code, BidRequest.postal_code_prefix Zip/postal code.
type No LocationType Source of location data; recommended when passing lat/lon.
accuracy No int32 Not supported Estimated location accuracy in meters; recommended when lat/lon are specified and derived from a device's location services (i.e., type = 1). Note that this is the accuracy as reported from the device. Consult OS specific documentation (e.g., Android, iOS) for exact interpretation.
lastfix No int32 Not supported Number of seconds since this geolocation fix was established.

Note that devices may cache location data across multiple fetches. Ideally, this value should be from the time the actual fix was taken.

ipservice No LocationService Not supported Service or provider used to determine geolocation from IP address if applicable (i.e., type = 2).
utcoffset No int32 BidRequest.timezone_offset Local time as the number +/- of minutes from UTC.

User object

OpenRTB 2.0

This object contains information known or derived about the human user of the device (i.e., the audience for advertising).The user ID is an exchange artifact and may be subject to rotation or other privacy policies. However, this user ID must be stable long enough to serve reasonably as the basis for frequency capping and retargeting.

Attribute Always passed Type Ad Exchange equivalent Implementation details
id No string BidRequest.[constrained_usage_]google_user_id Exchange-specific ID for the user. At least one of id or buyerid is recommended
buyeruid No string Not supported Buyer-specific ID for the user as mapped by the exchange for the buyer. At least one of buyerid or id is recommended.
keywords No string Not supported Comma-separated list of keywords, interests, or intent. Note: OpenRTB 2.2 allowed an array of strings as alternate implementation but this was fixed in 2.3+ where it's definitely a single string with CSV content again. Compatibility with some OpenRTB 2.2 exchanges that adopted the alternate representation may require custom handling of the JSON.
customdata No string BidRequest.[constrained_usage_]hosted_match_data - AdX is binary, OpenRTB is base64 (no padding) Optional feature to pass bidder data set in the exchange's cookie. The string must be in base85 cookie safe characters and be in any format. Proper JSON encoding must be used to include "escaped" quotation marks.
geo No Geo object Not supported Location of the user's home base defined by a Geo object. This is not necessarily their current location.
data No Array of Data BidRequest.Vertical -> (id: "DetectedVertical", name : "DoubleClick",

segment[n]: (id: dv[n].id, value: dv[n].weight))

Additional user data. Each Data object represents a different data source.

segment.id references the exchange-detected vertical of the page.

segment.value corresponds to the weight of that detected vertical, a higher weight suggesting the page is more relevant for the detected vertical.

Data object

OpenRTB 2.0

The data and segment objects together allow additional data about the user to be specified. This data may be from multiple sources whether from the exchange itself or third party providers as specified by the id field. A bid request can mix data objects from multiple providers. The specific data providers in use should be published by the exchange a priori to its bidders.

Attribute Always passed Type Ad Exchange equivalent Implementation details
id No string Not supported Exchange-specific ID for the data provider.
name No string Not supported Exchange-specific name for the data provider.
segment Array of Segment Not supported Array of Segment objects that contain the actual data values.

Segment object

OpenRTB 2.0

The data and segment objects together allow additional data about the user to be specified. This data may be from multiple sources whether from the exchange itself or third party providers as specified by the id field. A bid request can mix Data objects from multiple providers. The specific data providers in use should be published by the exchange a priori to its bidders.

Attribute Always passed Type Ad Exchange equivalent Implementation details
id No string Not supported ID of the data segment specific to the data provider.
name No string Not supported Name of the data segment specific to the data provider.
value string Not supported String representation of the data segment value.

Regs object

OpenRTB 2.2

This object contains any legal, governmental, or industry regulations that apply to the request. The coppa flag signals whether or not the request falls under the United States Federal Trade Commission's regulations for the United States Children's Online Privacy Protection Act ("COPPA"). Refer to Section 7.1 for more information.

Attribute Always passed Type Ad Exchange equivalent Implementation details
coppa No string BidRequest.user_data_treatment / TAG_FOR_CHILD_DIRECTED_TREATMENT Flag indicating if this request is subject to the COPPA regulations established by the USA FTC, where 0 = no, 1 = yes.

BidExt object (bid request)

This object exists only in the AdX protocol.

Attribute Always passed Type Ad Exchange equivalent Implementation details
billing_id No Array of int64 BidRequest.AdSlot.MatchingAdData.billing_id
ad_choices_destination_url No Array of fixed64 BidRequest.publisher_settings_list_id

BidRequest.AdSlot.publisher_settings_list_id

allowed_vendor_type No Array of int32 BidRequest.AdSlot.allowed_vendor_type
publisher_parameter No Array of string BidRequest.AdSlot.ExchangeBidding.publisher_parameter
dfp_network_code No int64 BidRequest.AdSlot.ExchangeBidding.dfp_network_code
dfp_ad_unit_code No string BidRequest.AdSlot.dfp_ad_unit_code

Bid response variables and definitions

This section describes the bid response variables and definitions

BidResponse object

OpenRTB 2.0

This object is the top-level bid response object (i.e., the unnamed outer JSON object). The id attribute is a reflection of the bid request ID for logging purposes. Similarly, bidid is an optional response tracking ID for bidders. If specified, it can be included in the subsequent win notice call if the bidder wins. At least one seatbid object is required, which contains at least one bid for an impression. Other attributes are optional. To express a "no-bid", return an empty response with HTTP 204. Alternately, if the bidder wishes to convey to the exchange a reason for not bidding, just a BidResponse object is returned with a reason code in the nbr attribute.

Attribute Required Type Ad Exchange equivalent Implementation details
id Yes string Not mapped to any field, but validated against the BidRequest.id. ID of the bid request to which this is a response.

REQUIRED by the OpenRTB specification.

seatbid No Array of Seatbid BidResponse.Ad Array of seatbid objects; 1+ required if a bid is to be made.
bidid No string BidResponse.debug_string Bidder generated response ID to assist with logging/tracking.
cur No string Not supported Bid currency using ISO-4217 alpha codes.
customdata No string Not supported Optional feature to allow a bidder to set data in the exchange's cookie. The string must be in base85 cookie safe characters and be in any format. Proper JSON encoding must be used to include "escaped" quotation marks.
nbr No NoBidReason Not supported Reason for not bidding.
ext No BidResponseExt Not supported External

Seatbid object

OpenRTB 2.0

A bid response can contain multiple SeatBid objects, each on behalf of a different bidder seat and each containing one or more individual bids. If multiple impressions are presented in the request, the group attribute can be used to specify if a seat is willing to accept any impressions that it can win (default) or if it is only interested in winning any if it can win them all as a group.

Attribute Required Type Ad Exchange equivalent Implementation details
bid No Bid BidResponse.Ad Array of 1+ Bid objects each related to an impression. Multiple bids can relate to the same impression.
seat No string Not supported ID of the buyer seat (e.g., advertiser, agency) on whose behalf this bid is made.
group No bool Not supported 0 = impressions can be won individually; 1 = impressions must be won or lost as a group. Default = false

Bid object

OpenRTB 2.0

A SeatBid object contains one or more Bid objects, each of which relates to a specific impression in the bid request via the impid attribute and constitutes an offer to buy that impression for a given price.

Attribute Required Type Ad Exchange equivalent Implementation details
id Yes string Not mapped to any field, but validated against the BidRequest.id. ID of the bid request to which this is a response.

REQUIRED by the OpenRTB specification.

impid Yes string BidResponse.Ad.AdSlot.id ID of the Imp object in the related bid request. REQUIRED by the OpenRTB specification.
price Yes double BidResponse.Ad.AdSlot.max_cpm_micros * 1,000,000 Bid price expressed as CPM although the actual transaction is for a unit impression only. Note that while the type indicates float, integer math is highly recommended when handling currencies (e.g., BigDecimal in Java). REQUIRED by the OpenRTB specification.
adid No string Not supported ID of a preloaded ad to be served if the bid wins.
nurl No string BidResponse.Ad.impression_tracking_url Win notice URL called by the exchange if the bid wins; optional means of serving ad markup.

DoubleClick doesn't support win notices; use %%WINNING_PRICE%% in snippet's impression URL, or ${AUCTION_PRICE}.

adm No string BidResponse.Ad.html_snippet, or BidResponse.Ad.video_url or BidResponse.Ad.native_ad Optional means of conveying ad markup in case the bid wins; supercedes the win notice if markup is included in both. For native ad bids, exactly one of {adm, adm_native} should be used; this is the OpenRTB-compliant field for JSON serialization.
adm_native No NativeResponse BidResponse.Ad.native_ad Native ad response. For native ad bids, exactly one of {adm, adm_native} should be used; this is the field used for Protobuf serialization.
adomain No Array of string BidResponse.Ad.click_through_url Advertiser domain for block list checking (e.g., "ford.com"). This can be an array for the case of rotating creatives. Exchanges can mandate that only one domain is allowed. OpenRTB spec only allows domain names in adomain; Ad Exchange support full URLs too.
bundle No string Not supported A platform-specific application identifier intended to be unique to the app and independent of the exchange. On Android, this should be a bundle or package name (e.g., com.foo.mygame). On iOS, it is a numeric ID.
iurl No string Not supported URL without cache-busting to an image that is representative of the content of the campaign for ad quality/safety checking.
cid No string BidResponse.Ad.AdSlot.billing_id Campaign ID to assist with ad quality checking; the collection of creatives for which iurl should be representative.

Matches the billing ID in the pretargeting.

crid No string BidResponse.Ad.buyer_creative_id Creative ID to assist with ad quality checking.
cat No Array of string Not supported IAB content categories of the creative.
attr No Array of CreativeAttribute BidResponse.Ad.attribute Set of attributes describing the creative.
api No APIFramework Not supported API required by the markup if applicable.
protocol No Protocol Not supported Video response protocol of the markup if applicable.
qagmediarating No QAGMediaRating Not supported Creative media rating per QAG guidelines.
dealid No string BidResponse.Ad.AdSlot.deal_id Reference to the deal.id from the bid request if this bid pertains to a private marketplace direct deal.
w No int32 BidResponse.Ad.width - only required if the impression is multisize Width of the creative in device independent pixels (DIPS).
h No int32 BidResponse.Ad.height - only required if the impression is multisize Height of the creative in device independent pixels (DIPS).
exp No int32 Not supported Advisory as to the number of seconds the bidder is willing to wait between the auction and the actual impression.
burl No string impression_tracking_url Billing notice URL called by the exchange when a winning bid becomes billable based on exchange-specific business policy (e.g., typically delivered, viewed, etc.). Substitution macros (Section 4.4) may be included. Note that BidExt.impression_tracking_url accepts a repeated list of billing notice URLs. If your use case requires more than one billing URL, use that extension instead of burl.
lurl No string Not supported Loss notice URL called by the exchange when a bid is known to have been lost. Substitution macros (Section 4.4) may be included. Exchange-specific policy may preclude support for loss notices or the disclosure of winning clearing prices resulting in ${AUCTION_PRICE} macros being removed (i.e., replaced with a zero-length string).
tactic No string Not supported Tactic ID to enable buyers to label bids for reporting to the exchange the tactic through which their bid was submitted. The specific usage and meaning of the tactic ID should be communicated between buyer and exchanges a priori.
language No string Not supported Language of the creative using ISO-639-1-alpha-2. The nonstandard code "xx" may also be used if the creative has no linguistic content (e.g., a banner with just a company logo).
wratio No int32 Not supported Relative width of the creative when expressing size as a ratio. Required for Flex Ads.
hratio No int32 Not supported Relative height of the creative when expressing size as a ratio. Required for Flex Ads.
ext No BidExt BidExt Extension key for Ad Exchange Bid.ext.

BidExt object (bid response)

This object exists only in the AdX protocol.

Attribute Required Type Ad Exchange equivalent Implementation details
impression_tracking_url No Array of string BidResponse.Ad.impression_tracking_url
ad_choices_destination_url No string BidResponse.Ad.ad_choices_destination_url
bidder_name No string BidResponse.Ad.bidder_name
exchange_deal_type No Enum

ExchangeDealType

BidResponse.Ad.AdSlot.exchange_deal_type

OPEN_AUCTION = 0;

PRIVATE_AUCTION = 1;

PREFERRED_DEAL = 2;

BidResponseExt object

Ad Exchange extensions for the BidResponse object.

Attribute Required Type Ad Exchange equivalent Implementation details
processing_time_ms No int32 BidResponse.processing_time_ms Set this to the processing time in milliseconds from when you received the request to when you returned the response.

Native bid request and response variables and definitions

NativeRequest object

OpenRTB Native 1.0

The Native object defines the native advertising opportunity available for bid via this bid request. It must be included directly in the impression object if the impression offered for auction is a native ad format.

Attribute Required Type Ad Exchange equivalent Implementation details
ver No string "1.0" for OpenRTB 2.3; "1.1" for OpenRTB 2.4 Number of the Native Markup version in use.
layout No LayoutId Not supported The Layout ID of the native ad unit. RECOMMENDED by OpenRTB Native 1.0; optional in 1.1, to be deprecated.
adunit No AdUnitId Not supported The Ad unit ID of the native ad unit. This corresponds to one of IAB Core-6 native ad units. RECOMMENDED by OpenRTB Native 1.0; optional in 1.1, to be deprecated
context No ContextType Not supported The context in which the ad appears.
contextsubtype No ContextSubtype Not supported A more detailed context in which the ad appears.
plcmttype No PlacementType Not supported The design/format/layout of the ad unit being offered.

RECOMMENDED by the OpenRTB Native specification.

plcmtcnt No int32 Not supported The number of identical placements in this Layout.
seq No int32 Not supported 0 for the first ad, 1 for the second ad, and so on. Note this would generally NOT be used in combination with plcmtcnt - either you are auctioning multiple identical placements (in which case plcmtcnt>1, seq=0) or you are holding separate auctions for distinct items in the feed (in which case plcmtcnt=1, seq>=1).
assets No Array of Asset Not supported Any bid must comply with the array of elements expressed by the Exchange. REQUIRED by the OpenRTB Native specification: at least 1 element.
ext No NativeRequestExt Not supported Google Extensions for Native.

Asset object

OpenRTB Native 1.0

The main container object for each asset requested or supported by Exchange on behalf of the rendering client. Any object that is required is to be flagged as such. Only one of the {title,img,video,data} objects should be present in each object. All others should be null/absent. The id is to be unique within the Asset array so that the response can be aligned.

Attribute Required Type Ad Exchange equivalent Implementation details
id Yes int32 1..N for N assets in unspecified order, corresponding to recommended or required fields in the first NativeAdTemplate. Unique asset ID, assigned by exchange. Typically a counter for the array. REQUIRED by the OpenRTB Native specification.
required No bool BidRequest.AdSlot.native_ad_template[0].
required_fields
Set to true if asset is required.
title No Title BidRequest.AdSlot.native_ad_template[0] of type HEADLINE Title object for title assets.

RECOMMENDED by the OpenRTB Native specification. One of Title, Image, Data, Video.

Image No img BidRequest.AdSlot.native_ad_template[0] of types MAIN/IMAGE, ICON/APP_ICON, LOGO/LOGO Image object for image assets.

RECOMMENDED by the OpenRTB Native specification. One of Title, Image, Data, Video.

video No BidRequest.Imp.Video Not supported Video object for video assets. Note that in-stream video ads are not part of Native. Native ads may contain a video as the ad creative itself. RECOMMENDED by the OpenRTB Native specification. One of Title, Image, Data, Video.

data No Data BidRequest.AdSlot.native_ad_template[0] of types ADDRESS/STORE, CTATEXT/CALL_TO_ACTION, DESC/BODY,

SPONSORED/ADVERTISER, PRICE/PRICE, RATING/STAR_RATING

Data object for ratings, prices etc.

RECOMMENDED by the OpenRTB Native specification. One of Title, Image, Data, Video.

Title object

OpenRTB Native 1.0

The Title object is to be used for title element of the Native ad.

Attribute Required Type Ad Exchange equivalent Implementation details
len No int32 BidRequest.AdSlot.native_ad_template[0].headline_max_safe_length Maximum length of the text in the title element. RECOMMENDED that the value be either of: 25, 90, 140. REQUIRED by the OpenRTB Native specification.

Image object

OpenRTB Native 1.0

The Title object is to be used for title element of the Native ad.

Attribute Required Type Ad Exchange equivalent Implementation details
type No ImageAssetType BidRequest.AdSlot.native_ad_template[0] field type Type ID of the image element supported by the publisher. The publisher can display this information in an appropriate format.
w No int32 Not supported Width of the image in pixels.
h No int32 Not supported Height of the image in pixels
wmin No int32 BidRequest.AdSlot.native_ad_template[0] of type: MAIN/IMAGE:image_width LOGO/LOGO: logo_width

ICON/APP_ICON: app_icon_width

The minimum requested width of the image in pixels. This option should be used for any rescaling of images by the client. Either w or wmin should be transmitted. If only w is included, it should be considered an exact requirement. RECOMMENDED by the OpenRTB Native specification.
hmin No int32 BidRequest.AdSlot.native_ad_template[0] of type: MAIN/IMAGE:image_width LOGO/LOGO: logo_width ICON/APP_ICON: app_icon_width The minimum requested height of the image in pixels. This option should be used for any rescaling of images by the client. Either h or hmin should be transmitted. If only h is included, it should be considered an exact requirement. RECOMMENDED by the OpenRTB Native specification.

Data object

OpenRTB Native 1.0

The Data object is to be used for all non-core elements of the native unit such as Ratings, Review Count, Stars, Download count, descriptions etc. It is also generic for future of Native elements not contemplated at the time of the writing of this document.

Attribute Required Type Ad Exchange equivalent Implementation details
type Yes DataAssetType BidRequest.AdSlot.native_ad_template[0] field type Type ID of the element supported by the publisher. The publisher can display this information in an appropriate format. REQUIRED by the OpenRTB Native specification.
len No int32 BidRequest.AdSlot.native_ad_template[0] of type:

DESC/BODY: body_max_safe_length

CTATEXT/CALL_TO_ACTION: call_to_action_max_safe_length

SPONSORED/ADVERTISER: advertiser_max_safe_length

PRICE/PRICE: price_max_safe_length

ADDRESS/STORE: store_max_safe_length

Maximum length of the text in the element's response.

Note: not used for RATING/STAR_RATING, AdX needs a double 0..5

NativeRequestExt object

OpenRTB Native 1.0

The Title object is to be used for title element of the Native ad.

Attribute Required Type Ad Exchange equivalent Implementation details
style_id No int32 BidRequest.AdSlot.native_ad_template[0].style_id
style_height No int32 BidRequest.AdSlot.native_ad_template[0].style_height
style_width No int32 BidRequest.AdSlot.native_ad_template[0].style_width
style_layout_type No Enum LayoutType BidRequest.AdSlot.native_ad_template[0].style_layout_type PIXEL = 0;

FLUID = 1;

NativeResponse object

OpenRTB Native 1.0

The native response object is the top level JSON object which identifies an native response.

Attribute Required Type Ad Exchange equivalent Implementation details
ver No string "1.0" for OpenRTB 2.3; "1.1" for OpenRTB 2.4 Version of the Native Markup version in use.
assets No Array of assets BidResponse.Ad.native_ad[0]. All assets are mapped to fields of a single NativeAd. List of native ad's assets.
link Yes Link BidResponse.Ad.native_ad[0] Destination Link.REQUIRED by the OpenRTB Native specification.
imptrackers No Array of string BidResponse.Ad.impression_tracking_url Array of impression tracking URLs, expected to return a 1x1 image or 204 response - typically only passed when using 3rd party trackers. Use %%WINNING_PRICE%% macro or ${AUCTION_PRICE}.
jstracker No string Not supported Optional javascript impression tracker. Contains script tags to be executed at impression time where it can be supported.

Link object

OpenRTB Native 1.0

Used for "call to action" assets, or other links from the Native ad. This object should be associated with its peer object in the parent Asset object. When that peer object is activated (clicked) the action should take the user to the location of the link.

Attribute Required Type Ad Exchange equivalent Implementation details
url No string (NativeResponse.link) BidResponse.Ad.click_through_url (NativeResponse.Asset.link, for asset of type STORE) BidResponse.Ad.native_ad[0].store] Landing URL of the clickable link.
clicktrackers No Array of string (NativeResponse.link) BidResponse.Ad.NativeAd.click_tracking_url[0] Third-party tracker URLs to be fired on click of the URL. Google click trackers redirect HTTP 30x to the bidder's tracker. Google only maps the first click tracking url and the remaining are ignored.
fallback No string Not supported Fallback URL for deeplink. To be used if the URL given in url is not supported by the device.

Asset object

OpenRTB Native 1.0

Corresponds to the Asset object in the request. The main container object for each asset requested or supported by Exchange on behalf of the rendering client. Any object that is required is to be flagged as such. Only one of the {title,img,video,data} objects should be present in each object. All others should be null/absent. The ID should be unique within the Asset array so that the response can be aligned.

Attribute Required Type Ad Exchange equivalent Implementation details
id Yes int32 Not supported Unique asset ID, assigned by exchange, must match one of the asset IDs in request

REQUIRED by the OpenRTB Native specification.

required No bool Not supported Set to 1 if asset is required. (bidder requires it to be displayed)
title No Title AdX: BidResponse.Ad.native_ad[0] / HEADLINE One of Title, Image, Data, Video

Title object for title assets.

img No Image BidResponse.Ad.native_ad[0] / IMAGE|LOGO|APP_ICON One of Title, Image, Data, Video

Image object for image assets.

video No Video Not supported One of Title, Image, Data, Video

Video object for video assets. Note that in-stream video ads are not part of Native. Native ads may contain a video as the ad creative itself.

data No Data BidResponse.Ad.native_ad[0] /

BODY|CALL_TO_ACTION|ADVERTISER|STAR_RATING_PRICE_STORE

One of Title, Image, Data, Video

Data object for ratings, prices etc.

link No Link BidResponse.Ad.native_ad[0] Link object for call to actions. This link is to associated to the other populated field within the object.

Title object

OpenRTB Native 1.0

Corresponds to the Title object in the request, with the value filled in.

Attribute Required Type Ad Exchange equivalent Implementation details
text Yes string BidResponse.Ad.native_ad[0].headline The text associated with the text element. REQUIRED by the OpenRTB Native specification.

Image object

OpenRTB Native 1.0

Corresponds to the Image object in the request. The Image object to be used for all image elements of the Native ad such as Icons, Main Image, etc.

Attribute Required Type Ad Exchange equivalent Implementation details
url Yes string BidResponse.Ad.native_ad[0] for request asset type:

MAIN/IMAGE: image.url

ICON/APP_ICON: app_icon.url

LOGO/LOGO: logo.url

URL of the image asset. REQUIRED by the OpenRTB Native specification.
w No int32 BidResponse.Ad.native_ad[0] for request asset type:

MAIN/IMAGE: image.url

ICON/APP_ICON: app_icon.url

LOGO/LOGO: logo.url

Width of the image in pixels. RECOMMENDED by the OpenRTB Native specification.
h No int32 BidResponse.Ad.native_ad[0] for request asset type:

MAIN/IMAGE: image.url

ICON/APP_ICON: app_icon.url

LOGO/LOGO: logo.url

Height of the image in pixels.

Video object

OpenRTB Native 1.0

Corresponds to the Video object in the request, yet containing a value of a conforming VAST tag as a value.

Attribute Required Type Ad Exchange equivalent Implementation details
vasttag Yes string Not supported VAST xml. REQUIRED by the OpenRTB Native specification.

Data object

OpenRTB Native 1.0

Corresponds to the Data object in the request, with the value filled in. The Data object is to be used for all miscellaneous elements of the native unit such as Ratings, Review Count, Stars, Downloads, Price count etc. It is also generic for future Native elements not contemplated at the time of the writing of this document.

Attribute Required Type Ad Exchange equivalent Implementation details
label No string Not supported The optional formatted string name of the data type to be displayed.
value Yes string BidResponse.Ad.native_ad[0] for request asset type OpenRTB/AdX:

CTATEXT/CALL_TO_ACTION: call_to_action

DESC/BODY: body

SPONSORED/ADVERTISER: advertiser

PRICE/PRICE: price

RATING/STAR_RATING: star_rating (AdX requires a double 0..5)

Note: ADDRESS/STORE not mapped via data.value, use asset.link.url

The formatted string of data to be displayed. Can contain a formatted value such as "5 stars" or "$10" or "3.4 stars out of 5". REQUIRED by the OpenRTB Native specification.

Examples

This section contains examples of JSON bids and responses.

Example of bid request

{
  "id": "V+u4DAAI8CEKG+PVxAwrsA",
  "imp": [
    {
      "id": "1",
      "banner": {
        "w": 320,
        "h": 480,
        "pos": 1,
        "api": [
          3,
          5
        ],
        "wmax": 360,
        "hmax": 640,
        "wmin": 320,
        "hmin": 280
      },
      "instl": 1,
      "tagid": "1",
      "bidfloor": 0.01,
      "bidfloorcur": "USD",
      "ext": {
        "billing_id": [
          "12345678901"
        ],
        "publisher_settings_list_id": [
          "12345678901234567890"
        ],
        "allowed_vendor_type": [
          113
        ]
      }
    }
  ],
  "app": {
    "name": "Super Speed VPN",
    "bundle": "com.example.free.vpn.proxy",
    "publisher": {
      "id": "1"
    },
    "content": {
      "url": "https://play.google.com/store/apps/details?id=com.example.free.vpn.proxy",
      "contentrating": "DV-G",
      "userrating": "4.2",
      "language": "en"
    }
  },
  "device": {
    "ua": "Mozilla/5.0...(Mobile; afma-sdk-a-v9683236.8115000.2)",
    "ip": "123.456.789.0",
    "geo": {
      "country": "FRA",
      "utcoffset": 180
    },
    "make": "alcatel",
    "model": "5022d",
    "os": "android",
    "osv": "5.1",
    "devicetype": 4,
    "ifa": "ec162290-a098-43ac-9fac-411861ba2b1a",
    "w": 360,
    "h": 640,
    "pxratio": 2
  },
  "user": {
    "id": "CAESEPfSJVjdc8Mx2U_Dd3fQqvM"
  },
  "cur": [
    "USD"
  ]
}

Example of bid response

{
  "id": "V+u4DAAI8CEKG+PVxAwrsA",
  "seatbid": [
    {
      "bid": [
        {
          "id": "V+u4DAAI8CEKG+PVxAwrsA:1",
          "impid": "1",
          "price": 3.01,
          "adid": "1234556",
          "adm": "<script>...</script>",
          "adomain": [
            "example.fr"
          ],
          "iurl": "https://example-api.dsp.com/",
          "cid": "123456789012",
          "crid": "dspbuyerid123",
          "w": 320,
          "h": 480,
          "ext": {
            "impression_tracking_url": [
              "https://events.example.com/track/win?ctr=FRA&cs=320x480&pr=${AUCTION_PRICE}"
            ]
          }
        }
      ],
      "seat": "7c12fa29a8d84fb9bd0a71d566a14e2a"
    }
  ],
  "cur": "USD"
}

Example of video bid request

{
  "id": "WEejNwAL6doKG+LQcAQCnw",
  "imp": [
    {
      "id": "1",
      "banner": {
        "w": 360,
        "h": 592,
        "pos": 1,
        "api": [
          3,
          5
        ],
        "wmax": 360,
        "hmax": 592,
        "wmin": 250,
        "hmin": 250
      },
      "video": {
        "mimes": [
          "video/mp4",
          "video/webm",
          "video/x-flv"
        ],
        "maxduration": 10,
        "w": 360,
        "h": 592,
        "startdelay": 0,
        "playbackmethod": [
          1
        ],
        "pos": 1,
        "api": [
          3,
          5
        ],
        "protocols": [
          2,
          3,
          5,
          6
        ]
      },
      "instl": 1,
      "tagid": "1",
      "bidfloor": 0.09,
      "bidfloorcur": "EUR",
      "ext": {
        "billing_id": [
          "12345"
        ],
        "publisher_settings_list_id": [
          "15984503506551632562"]
      }
    }
  ],
  "app": {
    "name": "AppMyApp",
    "bundle": "fr.android.myapp",
    "publisher": {
      "id": "1"
    },
    "content": {
      "url": "https://play.google.com/store/apps/details?id=fr.android.myapp",
      "contentrating": "DV-G",
      "userrating": "4.1",
      "language": "fr"
    }
  },
  "device": {
    "ua": "Mozilla/5.0...(Mobile; afma-sdk-a-v10084448.9452000.2)",
    "ip": "236.162.37.0",
    "geo": {
      "country": "FRA",
      "region": "FR-D",
      "zip": "71150",
      "utcoffset": 60
    },
    "make": "sony",
    "model": "e5633",
    "os": "android",
    "osv": "6.0",
    "devicetype": 4,
    "ifa": "6e552d9b-bf7f-43c8-85aa-9c0790007503",
    "w": 360,
    "h": 592,
    "pxratio": 3
  },
  "user": {
    "id": "userid",
    "data": [
      {
        "id": "DetectedVerticals",
        "name": "DoubleClick",
        "segment": [
          {
            "id": "224",
            "value": "0.5"
          },
          {
            "id": "1461",
            "value": "0.5"
          }
        ]
      }
    ]
  },
  "cur": [
    "EUR"
  ],
  "bcat": [
    "IAB19-3"
  ]
}

Example of video bid response

{
  "id": "WEejNwAL6doKG+LQcAQCnw",
  "cur": "EUR",
  "seatbid": [
    {
      "seat": "197603482",
      "bid": [
        {
          "id": "1",
          "impid": "1",
          "price": 7,
          "adm": "<a href=\"https://ad.myexamplead.com/%%CLICK_URL_ESC%%\"...</a>",
          "iurl": "https://url",
          "adid": "myadname",
          "crid": "myadname",
          "cat": [
            "IAB22"
          ],
          "ext": {
            "impression_tracking_url": [
              "https://ad.myexampleadimpressiontracking/winning_price=${AUCTION_PRICE}"
            ]
          },
          "w": 320,
          "h": 480,
          "adomain": [
            "domainname.com"
          ],
          "cid": "01234567"
        }
      ]
    }
  ]
}

Example of native bid request

{
  "id": "WEcgigALZ28KT74DlAEKdA",
  "imp": [
    {
      "id": "1",
      "tagid": "3654083237",
      "bidfloor": 0.75,
      "bidfloorcur": "USD",
      "native": {
        "request": "{\"ver\":\"1.0\"...\"style_width\":300}}",
        "ver": "1.0"
      },
      "ext": {
        "billing_id": [
          "1234567" ],
        "publisher_settings_list_id": [
          "17725875107190109537"],
        "allowed_vendor_type": [
          10,
          42 ]
      }
    }
  ],
  "site": {
    "page": "https://www.example.com/story/30139/common-reasons-of-breakups",
    "publisher": {
      "id": "1234"
    },
    "content": {
      "language": "en"
    },
    "mobile": 1
  },
  "device": {
    "ua": "Mozilla/5.0 .../en_US;FBOP/5]",
    "ip": "104.191.75.0",
    "geo": {
      "country": "USA",
      "region": "US-TX",
      "metro": "641",
      "city": "San Antonio",
      "zip": "78259",
      "utcoffset": -360
    },
    "make": "apple",
    "model": "iphone",
    "os": "iOS",
    "osv": "10.2",
    "devicetype": 4,
    "w": 375,
    "h": 667,
    "pxratio": 2
  },
  "user": {
    "id": "CAESEI5Z85FbBUR-qiEz000000"
  },
  "cur": [
    "USD"
  ]
}

Example of native bid response

{
  "id": "WEcgigALZ28KT74DlAEKdA",
  "seatbid": [
    {
      "bid": [
        {
          "id": "707ff5aa-7e8c-4e02-bcef-0e454291a449",
          "impid": "1",
          "price": 1.4805768292682926,
          "iurl": "https://cdn.bttrack.com/li/1200/627/125953",
          "adm": "{\"assets\":...[//impressionurl.com/price=${AUCTION_PRICE}\"]}",
          "adomain": [
            "addomain.com"
          ],
          "cid": "1234567",
          "crid": "myadid",
          "cat": [
            "IAB1",
            "IAB9"
          ],
          "w": 0,
          "h": 0,
          "ext": {
            "impression_tracking_url": [
              "https://exampleimpressionurl.com/price=${AUCTION_PRICE}"
            ]
          }
        }
      ],
      "seat": "23568",
      "group": 0,
      "ext": {
        "CustomerBrandId": 23568
      }
    }
  ],
  "bidid": "64d3b1aa-ab1c-46f5-a328-8fe0506caaa",
  "cur": "USD"
}

Send feedback about...

Real-Time Bidding Protocol
Real-Time Bidding Protocol