Ad Exchange OpenRTB Extensions

This guide describes each field in the Ad Exchange OpenRTB extensions proto.

See also the OpenRTB proto file and the corresponding OpenRTB guide.

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 all fields will be populated in the request if available. We will never pass null values or empty strings.

Extensions for the Imp object

ImpExt object

Attribute Always passed Type Ad Exchange equivalent Implementation details
billing_id Yes Array of int64 BidRequest.AdSlot.
MatchingAdData.billing_id
The billing IDs corresponding to the pretargeting configs that matched.
publisher_settings_list_id
Yes Array of fixed64 BidRequest.publisher_
settings_list_id
BidRequest.AdSlot.publisher
_settings_list_id
The publisher settings list ID that applies to this page. See the RTB Publisher Settings guide for details.
allowed_vendor_type No Array of int32 BidRequest.AdSlot.
allowed_vendor_type
The allowed vendor types. See the vendors.txt file for a list of IDs. When the seller_network is GDN, the vendor IDs listed in gdn-vendors.txt in the supporting technical documentation are also allowed.
publisher_parameter No Array of string BidRequest.AdSlot.
ExchangeBidding.publisher_parameter
UTF8 strings optionally provided by the publisher as part of their matching yield group configurations in the DFP UI. The format is arbitrary and should be agreed upon by the publisher and the exchange bidder.
dfp_ad_unit_code No string BidRequest.AdSlot.dfp_ad_unit_code The DFP ad unit code. This is currently only set for exchange bidding requests.
is_rewarded_inventory No Regs object BidRequest.AdSlot.is_rewarded Whether the user receives a reward for viewing the ad. For video ads, typical implementations allow users to read an additional news article for free, receive an extra life in a game, or get a sponsored ad-free music session. The reward is typically distributed after the video ad is completed.
amp_ad_requirement_type No Enum BidRequest.AdSlot.amp_ad_requirement_type Enum AmpAdRequirementType indicates requirements for AMP Ads and rendering treatment:
UNKNOWN_AMP_AD_REQUIREMENT_TYPE = 0; AMP ad requirements are unknown.
AMP_AD_NOT_ALLOWED = 1; AMP ads are not allowed.
AMP_AD_ALLOWED_AND_NOT_EARLY_RENDERED = 2; either AMP ads or non-AMP ads are allowed, AMP ads are not early rendered.
AMP_AD_ALLOWED_AND_EARLY_RENDERED = 3; either AMP ads or non-AMP ads are allowed; AMP ads are early rendered.
AMP_AD_REQUIRED = 4; AMP ads are required. Ads that are non-AMP may be rejected by the publisher.

Extension key for Ad Exchange Imp.ext

Attribute Always passed Type Ad Exchange equivalent Implementation details
imp No ImpExt Extends com.google.openrtb.BidRequest.Imp

Extension key for AdX Bid.ext

Attribute Required/Optional Type Ad Exchange equivalent Implementation details
bid Optional BidExt Extension key for AdX Bid.ext Extends com.google.openrtb.BidResponse.SeatBid.Bid

Extension key for the AdX Publisher.ext

Attribute Always passed Type Ad Exchange equivalent Implementation details
publisher No PublisherExt Extends com.google.openrtb.BidRequest.Publisher

Extension key for the AdX Site.ext

Attribute Always passed Type Ad Exchange equivalent Implementation details
amp No AmpPage Extends com.google.openrtb.BidRequest.Site

NativeRequestExt object

Attribute Always passed Type Ad Exchange equivalent Implementation details
style_id No int32 BidRequest.AdSlot.
native_ad_template[0].style_id
Globally distinct ID for the specific style, HTML, and CSS with which the native ad is rendered.
style_height No int32 BidRequest.AdSlot.
native_ad_template[0].style_height
If the style_layout_type is Pixel, this is the height of the entire native ad after rendering.
style_width No int32 BidRequest.AdSlot.
native_ad_template[0].style_width
If the style_layout_type is Pixel, this is the width of the entire native ad after rendering.
style_layout_type No LayoutType BidRequest.AdSlot.
native_ad_template[0].style_layout_type
Enum LayoutType:
PIXEL = 0;
FLUID = 1;

Extension key for AdX Native.ext

Attribute Always passed Type Ad Exchange equivalent Implementation details
native_ext No NativeRequestExt Extends com.google.openrtb.NativeRequest

PublisherExt object

Attribute Always passed Type Ad Exchange equivalent Implementation details
country No string BidRequest.publisher_country The billing address country of the publisher. This may be different from the detected country of the user in geo_criteria_id or the hosting country of the website. See also the complete list of country codes.

SiteExt object

Attribute Always passed Type Ad Exchange equivalent Implementation details
amp No Enum AmpPage BidRequest.AdSlot.is_amp_page Whether this is an AMP page, omitted if unknown:
DIALECT_HTML = 1; if not an AMP page.
DIALECT_HTML_AMP = 2; if an AMP page.

Extensions for the BidResponse object

BidResponseExt object

Attribute Required/Optional Type Ad Exchange equivalent Implementation details
processing_time_ms Optional 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.

Extension key for AdX BidResponse.ext

Attribute Required/Optional Type Ad Exchange equivalent Implementation details
bid_response Optional BidResponseExt BidResponse Extends com.google.openrtb.BidResponse

Extensions for the Bid object

BidExt object

Attribute Required/Optional Type Ad Exchange equivalent Implementation details
impression_tracking_
url
Optional string BidResponse.Ad.
impression_tracking_url
The URLs to call when the impression is rendered. This is supported for all inventory types and all formats except for VAST video. In OpenRTB 2.5, Bid.burl is the analogous standard field.
ad_choices_
destination_url
Optional string BidResponse.Ad.
ad_choices_
destination_url
Link to an ad preferences or opt-out page. If present, a standard AdChoices icon is added to the native creative and linked to this URL. This is supported for native ads but is not part of the native message in the bid response.
bidder_name Optional string BidResponse.Ad.
bidder_name
For exchange bidders (third party exchanges doing real-time bidding on DFP), the name of the bidder that the exchange called to provide the ad. This is arbitrary UTF8 text but should be sufficient to identify the bidder and should be set consistently to the same value for the same bidder.
exchange_deal_type Optional Enum ExchangeDealType BidResponse.Ad.AdSlot.
exchange_deal_type
OPEN_AUCTION = 0;
PRIVATE_AUCTION = 1;
PREFERRED_DEAL = 2;
default = OPEN_AUCTION
attribute Optional Array of attribute objects. BidResponse.Ad.attribute See buyer-declarable-creative-attributes.txt for a list of IDs. Note that not all declarable attributes come through in the BidRequest in the various battr fields. Many bidders declare the attribute for "fluid" (aka "responsive" or "sizeless") interstitials that dynamically resize to take up the entire screen width and height. See the description in the Interstitial Ads guide for more information.

Send feedback about...

Real-Time Bidding Protocol
Real-Time Bidding Protocol