Authorized Buyers OpenRTB Extensions

This guide describes each field in the Authorized Buyers 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 Authorized Buyers real-time bidding protobuf, and some implementation details.

Also note:

  • All fields will be populated in the request if available. We will never pass null values or empty strings.
  • In JSON encoded bid requests all fields typed int64 or fixed64 below will be sent as strings to prevent accuracy loss for 64-bit integral values.

Extensions for the Imp object

ImpExt object

Attribute Always passed Type Authorized Buyers 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 Ad Manager UI. The format is arbitrary and should be agreed upon by the publisher and the Authorized Buyers bidder.
dfp_ad_unit_code No string BidRequest.AdSlot.
dfp_ad_unit_code
The Ad Manager ad unit code. This is currently only set for Authorized Buyers 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 Authorized Buyers Imp.ext

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

Extension key for AdX Bid.ext

Attribute Required/Optional Type Authorized Buyers 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 Authorized Buyers equivalent Implementation details
publisher No PublisherExt Extends com.google.openrtb.BidRequest.Publisher

Extension key for the AdX Site.ext

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

NativeRequestExt object

Attribute Always passed Type Authorized Buyers 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 Authorized Buyers equivalent Implementation details
native_ext No NativeRequestExt Extends com.google.openrtb.NativeRequest

PublisherExt object

Attribute Always passed Type Authorized Buyers 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 Authorized Buyers 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 Authorized Buyers 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 Authorized Buyers equivalent Implementation details
bid_response Optional BidResponseExt BidResponse Extends com.google.openrtb.BidResponse

Extensions for the Bid object

BidExt object

Attribute Required/Optional Type Authorized Buyers 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 Authorized Buyers bidders (third-party exchanges doing real-time bidding on Ad Manager), 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 Exchange
DealType
BidResponse
.Ad.AdSlot.
exchange_deal_type
OPEN_AUCTION = 0;
PRIVATE_AUCTION = 1;
PREFERRED_DEAL = 2;
EXCHANGE_AUCTION_PACKAGE = 3;
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.
Event
_notification
_token.payload
Optional string BidResponse
.Ad.event_
notification_token
The event notification token is sent to AdX by bidders for troubleshooting. AdX will include the token in real-time feedback for the bid. The content of the token will not be logged by AdX. AdX will ignore any token longer than 64 bytes.

Only usable for bidders integrated with real-time feedback.

 

BidRequestExt object

See Real-time feedback for more information.

Attribute Type Authorized Buyers equivalent Implementation details
BidFeedback
.id
string BidRequest.BidResponse
Feedback.request_id.
The unique id from BidRequest.id
BidFeedback
.creative_status
_code
int32 BidRequest
.BidResponseFeedback
.creative_status_code
The status code for the ad. See creative status codes on the Protos & Reference Data page for a list of ids.
BidFeedback
.price
double BidRequest
.BidResponseFeedback
.cpm_micros
If the bid won the auction, this is the second price cpm in your account currency. If the bid participated in the auction but was out-bid, this is the cpm that should have been exceeded in order to win the auction. This is not set if the bid was filtered prior to the auction, if the publisher or winning bidder has opted out the price feedback or if your account has opted out of sharing winning prices with other bidders. This field will never be set for Authorized Buyers Bidders.
BidFeedback
.event_notification
_token.payload
string BidRequest
.BidResponseFeedback
.event_notification_token
The contents of Event_notification_token payload included in the corresponding bid (if applicable).
BidFeedback
.buyer_creative
_id
string BidRequest
.BidResponseFeedback
.buyer_creative_id
The creative ID included in the corresponding bid.

Send feedback about...

Authorized Buyers
Authorized Buyers