This guide covers integration of OpenRTB (including macros) and native ads with Authorized Buyers. It also describes each field in the Authorized Buyers OpenRTB extensions proto.
For more information on OpenRTB protos, have a look at the OpenRTB proto file. For Authorized Buyers extensions, refer to the OpenRTB Extensions Protocol Buffer file.
OpenRTB implementation on Authorized Buyers is available in two similar formats.
- JSON
- Protobuf:
.proto
definition file can be referenced for message decoding.
This page serves as a reference for Google's implementation of OpenRTB, and is based on the Protobuf protocol. We recommend that OpenRTB JSON users also refer to the official OpenRTB spec for more information on how these fields are populated in the JSON protocol.
Integration considerations
Structure of 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 that:
- The
cid
field represents the billing ID specified in your pretargeting setup. This field is used to link the bid to abilling_id
sent in the bid request. If there is more than onecid
/billing_id
in the request or you have active child seats, you must specify the intendedcid
in your response. If there is only one in the request and you do not have any active child seats, that is the value that will be assumed in the response. - 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; refer to the OpenRTB proto file.
- In JSON-encoded bid requests all fields typed int64 or fixed64 below will be sent as strings to prevent accuracy loss for 64-bit integer values.
- The OpenRTB JSON protocol represents all
bool
fields as integers in the request, where0
representsfalse
and1
representstrue
. This is required by the OpenRTB specification.
Counting impressions and using macros
To limit discrepancies, we recommend using the
BidResponse.seatbid[].bid[].ext.impression_tracking_url
field for all inventory, including native.
Buyers should remove impression tracking pixels from the creative (ad
markup), and include the impression_tracking_url
field (string
array) in the bid response instead.
BidResponse.seatbid[].bid[].burl
can also be used. 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.
Here is the list of macros supported by impression_tracking_url
and burl
:
${AUCTION_ID}
- ID of the bid request; fromBidRequest.id
attribute.${AUCTION_BID_ID}
- ID of the bid; fromBidResponse.bidid
attribute.${AUCTION_IMP_ID}
- ID of the impression just won; fromBidRequest.imp[].id
attribute.${AUCTION_SEAT_ID}
- ID of the bidder seat for whom the bid was made; fromBidResponse.seatbid[].seat
attribute.${AUCTION_AD_ID}
- ID of the ad markup the bidder wants to serve; fromBidResponse.seatbid[].bid[].adid
attribute.${AUCTION_PRICE}
- Clearing price using the same currency and units as the bid. Note that this macro is currently not supported in AMP ads.
Google's OpenRTB implementation encrypts AUCTION_PRICE
identically to the Authorized Buyers protocol's WINNING_PRICE
macro. For more information on how to decrypt the price, refer to the Decrypt Price
Confirmations guide.
Migration to Protobuf
Protobuf encoding is much more efficient in terms of bandwidth and processing, and is therefore recommended. 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 and the full XML for VAST ads.
Note that 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 supported, as is Bid.burl
:
Refer to the comments
above.
No bid
If the client does not want to bid, the client should reply with a
204
code.
Enums
All enums can be found in the official documentation for OpenRTB and Native ads.
Extended identifier UID source types
The BidRequest.user.eids.uids
field can refer to multiple types
of signals. In order to determine which type a given
UID represents, you
should use the stype
extension. The
following types are currently supported:
Type | Value | Description |
---|---|---|
Publisher-provided identifiers | ppuid |
The publisher ID returned by |
First-party cookie | fpc |
|
Publisher-provided identifiers
Publisher-provided identifiers are encrypted or hashed user IDs created by the publisher that can be used for frequency capping, and interest-based targeting when third-party cookies or device IDs aren’t available. These are only sent in bid requests when enabled by the publisher, and none of the following fields are populated:
BidRequest.device.ifa
BidRequest.user.buyeruid
BidRequest.user.id
Bid request variables and definitions
Ensure you have the OpenRTB Specification available while consulting this page. The specification contains information and nuances specific to the Authorized Buyers implementation. You should also follow the guidelines presented in OpenRTB when unchanged.
Note the following points on how fields are represented in the JSON bid request:
- The OpenRTB JSON protocol represents all
bool
fields as integers in the request, where0
representsfalse
and1
representstrue
. This is required by the OpenRTB specification. - In JSON-encoded bid requests, all fields typed
int64
orfixed64
are sent as strings to prevent accuracy loss for 64-bit integer values.
BidRequest
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 | Authorized Buyers equivalent |
Supported | Implementation details |
---|---|---|---|---|---|
id
|
Yes | string | BidRequest.id | Unique ID of the bid request, provided by the exchange.
OpenRTB is websafe base64 (no padding). |
|
imp
|
Yes | Array of Imp objects
|
BidRequest.AdSlot | Representing the impressions offered.
At least 1 |
|
site
|
No | Site object
|
BidRequest | Details about the publisher's website.
Only applicable and recommended for websites.
One off with |
|
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 |
|
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 | AuctionType object
|
BidRequest.auction_type | where 1 = First Price, 2 = Second Price Plus.
Exchange-specific auction types can be defined using values > 500. Default = SECOND_PRICE. |
|
tmax
|
No | int32 | BidRequest.response_deadline_ms | Maximum time in milliseconds to submit a bid to avoid timeout. Typically between 80ms and 1000ms. | |
wseat
|
No | string | BidRequest |
Allowlist of buyer seats (for example, 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 | Option to indicate if Exchange can verify that the impressions offered represent all of the impressions available in context (for example, 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 (for example, "addomain.com") | |
bapp
|
No | Array of string | BidRequest.AdSlot.excluded_app_ids | Block list of applications by their platform-specific exchange-independent application identifiers. On Android, these should be bundle or package names (for example, com.foo.mygame). On iOS, these are numeric IDs. | |
test
|
No | bool | BidRequest |
Indicator of test mode in which auctions are not billable, where 0 = live mode, 1 = test mode. Default : 1 | |
bseat
|
No | string | BidRequest |
Block list of buyer seats (for example, 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 |
Allowlist 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
|
Used only for extensions | A Source object that provides data about the
inventory source and which entity makes the final decision.
|
|
ext |
No | BidRequestExt object |
Not supported | For OpenRTB/Protobuf, you can access this object with the
[com.google.doubleclick.bid_request] extension key
(exact path varies based on language used to generate proto library). For
OpenRTB/JSON, you access with the ext field in the BidRequest
message.
|
BidRequestExt
Refer to Real-time feedback for more information.
Attribute | Always passed | Type | Authorized Buyers equivalent | Implementation details |
---|---|---|---|---|
bid_feedback |
No | Array of BidFeedback objects |
BidRequest.bid_response_feedback | Feedback on bids submitted in previous responses. This is only set if real-time feedback is enabled for your bidder. Contact your account manager if you want to enable real-time feedback. |
google |
No | string | BidRequest.google_query_id | This represents a unique ID for the overall query. In the event that there are multiple callouts for a query, all callout requests for that query will contain the same google_query_id. |
fcap_scope |
Yes | FrequencyCappingScope enum |
BidRequest.AdSlot |
Experimental feature; may be subject to change. See Set Google-hosted frequency caps for RTB bids for more information. Describes the scope of frequency cap enforcement available for this request. Frequency caps to be enforced for a bid can be specified in the Bid.ext.fcap field.
|
privacy_treatments |
No | PrivacyTreatments object |
BidRequest.privacy_treatments | Privacy treatments. Some fields in the bid request can be coarsened or redacted in order to protect user privacy. This message provides information about privacy treatments that apply to an ad opportunity offered through this request. |
ae |
Yes | AuctionEnvironment enum |
BidRequest.supported_auction_environment | The supported auction environment for this impression. For inventory which does not support
interest group bidding, this will always be set to SERVER_SIDE_AUCTION . For
inventory which does support interest group bidding, this will be set to
ON_DEVICE_INTEREST_GROUP_AUCTION . Note that this only indicates that the interest
group auction is supported, not that it is guaranteed to execute. If no buyer chooses to
participate in the interest group auction, then the interest group auction will be skipped and
the winner of the contextual auction, if any, will be served instead. |
BidFeedback
Feedback on bids submitted in previous responses. This is only set if real-time feedback is enabled for your bidder. Contact your account manager if you want to enable real-time feedback.
Attribute | Always passed | Type | Authorized Buyers equivalent | Implementation details |
---|---|---|---|---|
request_id |
No | string | BidRequest.BidResponse |
The unique ID from BidRequest.id. |
creative_status |
No | int32 | BidRequest |
The status code for the ad. See creative status codes on the Protos & Reference Data page for a list of IDs. |
price |
No | double | BidRequest |
If the bid won the auction, this is the price paid 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. This is not set if the bid was filtered prior to the auction, if the publisher or winning bidder has opted out of price feedback or if your account has opted out of sharing winning prices with other bidders. For first-price auctions, minimum_bid_to_win is populated instead of this field. |
minimum_bid_to_win |
No | double | BidRequest |
The minimum bid value necessary to have won the auction, in your account currency. If your bid won the auction, this is the second highest bid that was not filtered (including the floor price). If your bid did not win the auction, this is the winning candidate's bid. This field will only be populated if your bid participated in a first-price auction, and will not be populated if your bid was filtered prior to the auction. |
sscminbidtowin |
No | double | BidRequest |
The minimum bid value necessary to have won the server-side component of the overall auction given that there was also an interest group bidding component to the overall auction which ran using the Protected Audience API. The value is expressed in CPM of the buyer account currency. The minimum bid to win for the overall auction, including bids from the server-side and the on-device interest group components, is populated in the minimum_bid_to_win field of the same BidFeedback object. |
billable_ |
No | double | BidRequest |
Billable event rate multiplier that was applied to this bid during ranking. The adjustment reflects the likelihood that your bid would generate a billable event (namely, the ad renders successfully) if it won the auction, relative to the probability that other bids generate a billable event if they won the auction. This adjustment can be larger or smaller than 1. This affects the final ranking in the auction only; in particular, this multiplier does not affect the payment or whether the bid clears any floor price. |
sampled_mediation_cpm_ahead_of_auction_winner |
No | double | BidRequest |
When a publisher uses an RTB auction and waterfall-based SDK mediation on the same query, the winner of the real-time auction must also compete in a mediation waterfall (which is ordered by price) to win the impression. If the bid participated in the auction and there was no waterfall, the value of this field is 0. If the bid participated in the auction and there was a waterfall, the value of this field is a price representing a sample bid from the eligible mediation networks that were higher than the auction winner, weighted by expected fill rate. This field can be used in conjunction with minimum_bid_to_win to train bidding models. The CPM is in your account currency. |
event_notification_token |
No | EventNotificationToken object |
BidRequest |
The token included in the corresponding bid. |
buyer_creative_id |
No | string | BidRequest |
The creative ID included in the corresponding bid. |
EventNotificationToken
The token included in the corresponding bid.
Attribute | Always passed | Type | Authorized Buyers equivalent | Implementation details |
---|---|---|---|---|
event_notification |
No | string | BidRequest |
The contents of the token. |
PrivacyTreatments object
ParentPrivacy treatments. Some fields in the bid request can be coarsened or redacted in order to protect user privacy. This message provides information about privacy treatments that apply to an ad opportunity offered through this request.
Attribute | Always passed | Type | Authorized Buyers equivalent | Implementation details |
---|---|---|---|---|
non_personalized_ads_reason |
No | NonPersonalizedAdsReason enum |
BidRequest.privacy_treatments |
Specifies the reasons that ads returned in response to this request should not be
personalized. This signal does not reflect user decisions on surfaces including
iOS App Tracking
Transparency or
Android
advertising ID. See
|
storagerestrict |
No | DeviceStorageRestrictionReason enum |
BidRequest.privacy_treatments |
Indicates the reason why access of local device storage during winning ad rendering and measurement is restricted. See Limited ads requests for additional details.
|
allow_user_data_collection |
No | bool | BidRequest.privacy_treatments |
True if publisher grants the permission to allow the bidder to use bid request data to build user profiles for uses such as interest-based ads and remarketing. To use this data to build user profiles, a bidder must also win a given impression. See About data collection controls. |
Source
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 | Authorized Buyers equivalent |
Supported | 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 (for example, 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. | |
ext |
No | SourceExt object |
Not supported | For OpenRTB/Protobuf, you can access this object with the
[com.google.doubleclick.source] extension key
(exact path varies based on language used to generate proto library). For
OpenRTB/JSON, you access with the ext field in the Source
message.
|
|
schain |
No | SupplyChain object |
BidRequest.supply_chain | OpenRTB SupplyChain object. For more information, see this article. |
SourceExt
Attribute | Always passed | Type | Authorized Buyers equivalent | Implementation details |
---|---|---|---|---|
omidpn |
No | string | BidRequest.AdSlot |
Identifier of the OM SDK integration. For more info, see the OpenRTB Advisory for Open Measurement SDK. |
omidpv |
No | string | BidRequest.AdSlot |
Version of the OM SDK integration. For more info, see the OpenRTB Advisory for Open Measurement SDK. |
schain |
No | SupplyChain object |
BidRequest.supply_chain | This field has been deprecated in favor of BidRequest.source.schain, and will be removed in December 2023. This field contains the OpenRTB SupplyChain object. For more information, see this article. |
SupplyChain
OpenRTB SupplyChain object. For more information, see this article.
Attribute | Always passed | Type | Authorized Buyers equivalent | Implementation details |
---|---|---|---|---|
complete |
No | int32 | BidRequest.supply_chain.complete | Option indicating whether the chain contains all nodes involved in the transaction leading back to the owner of the site, app or other medium of the inventory, where 0 = no, 1 = yes. |
nodes |
No | Array of SupplyChainNode objects |
BidRequest.supply_chain.nodes | Array of SupplyChainNode objects in the order of the chain. In a complete supply chain, the first node represents the initial advertising system and seller ID involved in the transaction, for example, the owner of the site, app, or other medium. In an incomplete supply chain, it represents the first known node. The last node represents the entity sending this bid request. |
ver |
No | string | BidRequest.supply_chain.version | Version of the supply chain specification in use, in the format of "major.minor". For example, for version 1.0 of the spec, use the string "1.0". |
SupplyChainNode
Attribute | Always passed | Type | Authorized Buyers equivalent | Implementation details |
---|---|---|---|---|
asi |
No | string | BidRequest.supply_chain.nodes.advertising_system_identifier | The canonical domain name of the SSP, Exchange, Header Wrapper, etc system that bidders connect to. This may be the operational domain of the system, if that is different than the parent corporate domain, to facilitate WHOIS and reverse IP lookups to establish clear ownership of the delegate system. This should be the same value as used to identify sellers in an ads.txt file if one exists. |
sid |
No | string | BidRequest.supply_chain.nodes.seller_identifier | The identifier associated with the seller or reseller account within the advertising system. This must contain the same value used in transactions (for example, OpenRTB bid requests) in the field specified by the SSP/exchange. Typically, in OpenRTB, this is publisher.id. For OpenDirect it is typically the publisher’s organization ID. Should be limited to 64 characters in length. |
rid |
No | string | Not supported | The OpenRTB RequestId of the request as issued by this seller. |
name |
No | string | Not supported | The name of the company (the legal entity) that is paid for inventory transacted under the given seller_id. This value is optional and should NOT be included if it exists in the advertising system’s sellers.json file. |
domain |
No | string | Not supported | The business domain name of the entity represented by this node. This value is optional and should NOT be included if it exists in the advertising system’s sellers.json file. |
hp |
No | int32 | BidRequest.supply_chain.nodes.handles_payment | Indicates whether this node will be involved in the flow of payment for the inventory. When set to 1, the advertising system in the asi field pays the seller in the sid field, who is responsible for paying the previous node in the chain. When set to 0, this node is not involved in the flow of payment for the inventory. For version 1.0 of SupplyChain, this property should always be 1. It is explicitly required to be included as it is expected that future versions of the specification will introduce non-payment handling nodes. Implementers should ensure that they support this field and propagate it onwards when constructing SupplyChain objects in bid requests sent to a downstream advertising system. |
Imp
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
, or
Native
objects 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 | Authorized |
Supported | Implementation details |
---|---|---|---|---|---|
id |
Yes | string | BidRequest .Adslot.id |
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 |
BidRequest .AdSlot BidRequest .Video |
Required if this impression is offered as an audio ad opportunity. | |
displaymanager |
No | string | BidRequest .AdSlot .display_manager |
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.
Example strings: |
|
displaymanagerver |
No | string | BidRequest .AdSlot .display_manager_version |
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 | Supported obtained from 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.
A single currency, obtained from the included
|
|
clickbrowser |
No | bool | 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:RichMedia CapabilityNonSSL |
Option 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 | 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 | BidRequest .AdSlot .impression_expiration _seconds |
Advisory as to the number of seconds that may elapse between the auction and the actual impression. | |
metric |
No | Array of Metric objects |
BidRequest .AdSlot .viewability BidRequest .AdSlot .click_through _rate BidRequest .AdSlot .video_completion _rate BidRequest .AdSlot .session_depth. |
An array of Metric objects. AdX supplies these metrics for this field:
click_through_rate , viewability ,
completion_rate , and session_depth . The
viewability metric is a fraction from 0.00 to 1.00 in the
OpenRTB metric, but it's expressed as a percentage [0-100] in the AdX
protocol. Refer to the AdSlot object table in the Realtime
Bidding Guide for descriptions of these metrics. Note
session_depth is an integer value.
|
|
ext |
No | ImpExt object |
Not supported | For OpenRTB/Protobuf, you can access this object with the
[com.google.doubleclick.imp] extension key
(exact path varies based on language used to generate proto library). For
OpenRTB/JSON, you access with the ext field in the Imp
message.
|
|
rwdd |
No | bool | BidRequest.AdSlot.is_rewarded | Indicates 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. | |
refresh |
No | Array of Refresh objects |
BidRequest.AdSlot.auto_refresh | Details about ad slots being refreshed automatically. |
ImpExt
Attribute | Always passed | Type | Authorized Buyers equivalent | Implementation details |
---|---|---|---|---|
billing_id |
Yes | Array of int64 | BidRequest.AdSlot. |
The billing IDs corresponding to the pretargeting configs that matched. |
publisher_settings_ |
Yes | Array of fixed64 | BidRequest.publisher_ BidRequest.AdSlot. |
The publisher settings list ID that applies to this page. Refer to the RTB Publisher Settings guide for details. |
allowed_vendor_type |
No | Array of int32 | BidRequest.AdSlot. |
The allowed vendor types. Refer to the vendors.txt file for a list of IDs. |
excluded_creatives |
No | Array of ExcludedCreative
objects |
BidRequest.AdSlot. |
Creatives that are disallowed for the impression. Submitting a bid with one of the creatives in this list will result in such bid being filtered before the auction. Contact your account manager if you would like to enable this feature. |
dfp_ad_unit_code |
No | string | BidRequest.AdSlot. |
The Ad Manager ad unit code. This is currently only set for Open Bidding requests. |
is_rewarded_ |
No | bool | BidRequest.AdSlot. |
This field has been deprecated in favor of BidRequest.imp.rwdd, and will be removed in July 2023. This field indicates 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. |
is_app_open |
No | bool | BidRequest.Mobile. |
Indicates whether a mobile app bid request is for an app open ad. See App open ad guidance for more information. |
ampad |
No | Enum AmpAdRequirementType | BidRequest.AdSlot. |
Possible requirement types for AMP ads.
UNKNOWN_AMP_AD_ AMP_AD_NOT_ALLOWED = 2; AMP ads are not allowed. AMP_AD_ALLOWED_AND_ AMP_AD_ALLOWED_AND_ AMP_AD_REQUIRED = 5; AMP ads are required. Ads that are non-AMP may be rejected by the publisher. |
buyer |
No | Array of BuyerGenerated
objects
|
BidRequest.AdSlot. |
Secure signals passed by the publisher. |
billable_event_ |
No | double | BidRequest.AdSlot. |
Deprecated. This will be removed in Q1 2024.
This field has been deprecated in favor of the repeated field
billable_event_rate_bid_adjustment below.
For ads rendered using a custom SDK only: multiplier applied to bid in
the auction. The adjustment reflects the likelihood that your bid would
generate a billable event (for example, the ad renders successfully) if it won
the auction, relative to the probability that other bids generate a
billable event if they won the auction. This adjustment can be larger or
smaller than 1. This affects the final ranking in the auction only; in
particular, this multiplier does not affect the payment. Default = 1.0.
|
billable_event_rate_bid_adjustment |
No | Array of BillableEventRate objects
|
BidRequest.AdSlot. |
A list of billable event rate bid adjustments applicable to the request
and the ad features associated to the adjustment. Bid adjustments are
listed here only if they are not equal to 1.0, which is equivalent to
having no adjustment. This field replaces the deprecated field
billable_event_rate_adjustment .
|
open_bidding |
No | OpenBidding object |
BidRequest.AdSlot. |
Parameters related to Open Bidding. |
ad_unit |
No | AdUnitMapping object |
BidRequest.AdSlot. |
Ad unit mappings that match the given adslot. |
allowed_restricted_category |
No | int32 | BidRequest.AdSlot. |
The allowed restricted ad categories. See ad-restricted-categories.txt for a list of ids. |
skadn |
No | SKAdNetworkRequest
object |
BidRequest.Mobile. |
Publisher's SKAdNetwork information to support app installation attribution for iOS 14 and later. Apple's SKAdNetwork API helps advertisers measure ad-driven app installation by sending a postback to the ad network after a successful install. Publishers will need to configure supported ad networks in their app's property list (Info.plist) to allow an install to be attributed to the ad impression. For more info, see Apple's documentation. |
ExcludedCreative | ||||
buyer_creative_id |
No | string | BidRequest.AdSlot. |
Buyer creative ID of the disallowed creative. |
BuyerGeneratedRequestData | ||||
data |
No | string | BidRequest.AdSlot. |
The secure signal. |
source_app |
No | SourceApp | BidRequest.AdSlot. |
The source of the data. |
SourceApp | ||||
id |
No | string | BidRequest.AdSlot. |
Identifier for the SDK that generated this data. It will match the ID in
BidRequest.AppExt.InstalledSdk.id . |
OpenBidding | ||||
is_open_bidding |
No | bool | BidRequest.AdSlot. |
This field is set to true if the publisher set up a yield group or a mediation group that targets this adslot and this bidder. Visit our Help Center for information on Open Bidding and its effects on the bidding process. |
AdUnitMapping | ||||
Keyval |
No | Keyval object |
BidRequest.AdSlot. |
Key-value pair used to specify the inventory unit in the bidder's namespace. |
FormatType |
No | enum | BidRequest.AdSlot. |
Possible ad unit formats that can be used for the mapping. Corresponds
to the adapter that will be used on the SDK.
Possible values:
|
BillableEventRateBidAdjustment | ||||
bid_adjustment |
No | float | BidRequest.AdSlot. |
A multiplier to your bid to adjust for the likelihood that your bid would result in a billable event (namely, the ad renders successfully) if it won the auction, relative to the average probability that bids from other buyers would result in a billable event if they won the auction. This adjustment can be larger or smaller than 1. This affects the final ranking in the auction only; in particular, this multiplier does not affect the payment or whether the bid clears any floor price. |
creative_type |
No | CreativeType enum | BidRequest.AdSlot. |
The type of ads to which the above bid adjustment applies to. Each type corresponds to different ways of how the ad's creative is specified, as described in https://developers.google.com/authorized-buyers/rtb/response-guide#specify-creative. If the ad is SDK-rendered, this will be set to SDK_RENDERED regardless of the actual creative type. Possible values:
|
sdk |
No | InstalledSdk object | BidRequest.AdSlot. |
The SDK used to render the ad with. The SDK ID will match the one sent in mobile.installed_sdk.id. This field is not set for Google SDK. |
SKAdNetworkRequest | ||||
versions |
No | Array of strings | BidRequest.Mobile. |
List of all SKAdNetwork versions supported by the request, depending on the OS version and the SDK version. |
sourceapp |
No | string | BidRequest.Mobile. |
ID of publisher app in Apple's App Store. |
skadnetids |
No | Array of string | BidRequest.Mobile. |
SKAdNetworkIdentifier entries in the publisher app's Info.plist. |
fidelities |
No | Array of SKAdNetworkFidelityType objects |
BidRequest.Mobile. |
List of fidelity types supported, depending on the SKAdNetwork API version supported by the operating system and SDK as well as ad slot properties. |
skoverlay |
No | bool | BidRequest.Mobile. |
Indicates if this request supports SKOverlay for video ads. |
Keyval object
ParentMultiple key-value pairs can be specified in order to support bidders whose inventory unit space is hierarchical and has multiple identifiers. The key-value pairs for the chosen AdUnitMapping should be sent back in the bid response as BidResponse.seatbid.bid.ext.sdk_rendered_ad.sdk_params. This is passed to the bidder's SDK.
Attribute | Type | Always passed | Authorized Buyers equivalent | Implementation details |
---|---|---|---|---|
key |
string | No | BidRequest.AdSlot. |
The key is the name of the bidder's inventory unit identifier for the SDK. |
value |
string | No | BidRequest.AdSlot. |
The value of the bidder's inventory unit identifier for the given format. |
Metric
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 | Authorized Buyers equivalent |
Supported | Implementation details |
---|---|---|---|---|---|
type
|
No | string | One of: BidRequest .AdSlot .viewability BidRequest .AdSlot .click_ through_rate BidRequest .AdSlot .video_ completion_rate BidRequest .AdSlot .session_depth. |
Type of metric being presented using exchange curated string
names which should be published to bidders a priori. REQUIRED
by the OpenRTB specification. The types we support are:
click_through_rate , viewability , completion_rate ,
and session_depth .
|
|
value
|
No | double | Value between 0 and 1. | Number representing the value of the metric.
Probabilities must be in the range 0.00 – 1.00.
REQUIRED by the OpenRTB specification. The viewability metric
is a fraction from 0.00 to 1.00 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
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 | Authorized Buyers equivalent | Supported | Implementation details |
---|---|---|---|---|---|
w
|
No | int32 | BidRequest |
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 |
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 objects
|
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 |
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 BidRequest |
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 "4" - "7" apply to apps per the mobile
addendum to QAG version 1.5.
Can be one of the following values:
|
|
btype
|
No | Array of enum BannerAdType | Not supported | Blocked banner ad types
Examples: |
|
battr
|
No | Array of CreativeAttribute enum | BidRequest |
Blocked creative attributes. See the full list of available attributes. | |
mimes
|
No | Array of string | Only mapped for BidRequest BidRequest |
Allowlist 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
NO_IFRAME: false |
Specify if the banner is delivered in the top frame (true) or in an iframe (false). | |
expdir
|
No | Array of ExpandableDirection enum
|
BidRequest |
Directions in which the banner may expand. | |
api
|
No | Array of APIFramework objects
|
BidRequest |
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 |
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. | |
wmax |
No | int32 | BidRequest |
Maximum width of the impression in pixels. | |
hmax |
No | int32 | BidRequest |
Maximum height of the impression in pixels. | |
wmin |
No | int32 | BidRequest |
Minimum width of the impression in pixels. | |
hmin |
No | int32 | BidRequest |
Minimum height of the impression in pixels. | |
ext |
No | BannerExt object |
Not supported | For OpenRTB/Protobuf, you can access this object with the
[com.google.doubleclick.banner] extension key
(exact path varies based on language used to generate proto library). For
OpenRTB/JSON, you access with the ext field in the Banner
message.
|
BannerExt
Attribute | Always passed | Type | Authorized Buyers equivalent | Implementation details |
---|---|---|---|---|
flexslot |
No | FlexSlot object |
BidRequest |
This field contains information about a banner impression's flexible ad size ranges, if supported, and is unset otherwise. |
FlexSlot
Indicates the acceptable ad width and height ranges for impressions which support flexible ad sizes.Attribute | Always passed | Type | Authorized Buyers equivalent | Implementation details |
---|---|---|---|---|
wmin |
No | int32 | BidRequest |
The minimum acceptable ad width in device-independent pixels (DIPS). |
wmax |
No | int32 | BidRequest |
The maximum acceptable ad width in device-independent pixels (DIPS). |
hmin |
No | int32 | BidRequest |
The minimum acceptable ad height in device-independent pixels (DIPS). |
hmax |
No | int32 | BidRequest |
The maximum acceptable ad height in device-independent pixels (DIPS). |
Format
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 | Authorized Buyers equivalent | Supported | Implementation details |
---|---|---|---|---|---|
w
|
No | int32 | BidRequest |
Width in device independent pixels (DIPS). | |
h
|
No | int32 | BidRequest |
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
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.
Refer to the OpenRTB Video Ads guide for additional details.
Attribute | Always passed | Type | Authorized Buyers equivalent | Supported | Implementation details |
---|---|---|---|---|---|
mimes |
Yes | Array of string | BidRequest BidRequest |
Allowlist 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 | Indicates if the impression must be linear, nonlinear, etc. If none
specified, assume all are allowed.
LINEAR = 1: Linear/In-stream |
||
minduration |
No | int32 | BidRequest |
Minimum video ad duration in seconds.
RECOMMENDED by the OpenRTB specification. |
|
maxduration |
No | int32 | BidRequest |
Maximum video ad duration in seconds.
RECOMMENDED by the OpenRTB specification. |
|
protocols |
No | Array of Protocol objects |
BidRequest |
Array of supported video bid response protocols.
At least one supported protocol must be specified.
Examples: |
|
w |
No | int32 | BidRequest |
Width of the video player in device independent pixels (DIPS).
RECOMMENDED by the OpenRTB specification. |
|
h |
No | int32 | BidRequest |
Height of the video player in device independent pixels (DIPS).
RECOMMENDED by the OpenRTB specification. |
|
startdelay |
No | int32 | BidRequest
>0: start delay in seconds
Other values: |
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. |
maxseq
|
No | int32 | BidRequest |
The maximum number of ads that can be played in an ad pod. |
poddur
|
No | int32 | BidRequest |
Indicates the total amount of time in seconds that advertisers may fill
for a "dynamic" video ad pod, or the dynamic portion of a "hybrid" ad pod.
This field is required only for the dynamic portion(s) of video ad pods.
This field refers to the length of the entire ad break, whereas
minduration /maxduration /rqddurs are
constraints relating to the slots that make up the pod.This field is currently only supported for rewarded video pods requests. |
|
skip |
No | bool | BidRequest |
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 Creative |
BidRequest |
Blocked creative attributes. See the full list of available 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 Playback |
BidRequest AdX: |
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.
|
|
delivery |
No | Array of Content |
BidRequest |
Supported delivery methods (for example, streaming, progressive).
If none specified, assume all are supported.
|
|
pos |
No | AdPosition |
BidRequest |
Ad position on screen. | |
companionad |
No | Array of Banner objects |
BidRequest |
Array of Banner objects if companion
ads are available.
|
|
api |
No | Array of APIFramework objects |
BidRequest / 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 objects |
BidRequest |
Supported VAST companion ad types. Recommended if companion Banner
objects are included through the companionad array.
|
|
plcmt |
No | Plcmt | BidRequest
|
Video placement type for the impression. Introduced in OpenRTB 2.6 to reflect updated industry definitions around different types of video ad placements. This field supersedes the Video.placement field. IAB definition of the field and values: https://github.com/InteractiveAdvertisingBureau/AdCOM/blob/main/AdCOM%20v1.0%20FINAL.md#list--plcmt-subtypes---video- |
|
placement |
No | Video |
BidRequest
|
Note: Deprecated. This will be removed in Jan 2025 per the IAB here: https://github.com/InteractiveAdvertisingBureau/AdCOM/blob/main/AdCOM%20v1.0%20FINAL.md#list--placement-subtypes---video- Placement type for the impression.
|
|
playbackend |
No | Playback |
Not supported | The event that causes playback to end. | |
ext |
No | VideoExt object |
Not supported | For OpenRTB/Protobuf, you can access this object with the
[com.google.doubleclick.imp.video] extension key
(exact path varies based on language used to generate proto library). For
OpenRTB/JSON, you access with the ext field in the Video
object.
|
VideoExt
Attribute | Always passed | Type | Authorized Buyers equivalent | Implementation details |
---|---|---|---|---|
inferredplcmt |
No | Plcmt | BidRequest.Video.inferred_plcmt
|
Google inferred video placement type for the impression. This field is always filled and can
be different from BidRequest.imp.video.plcmt (the publisher-declared placement
type).
|
embeddedoffsite |
Yes | Embeddedoffsite | BidRequest.Video.embeddedoffsite
If true, the video is embedded on a page outside the publisher's domain. When this is set,
|
BidRequest.imp.video.ext.embeddedoffsite describes whether or not the video is embedded on a page outside the publisher's domain. |
Audio
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 | Authorized Buyers equivalent | Supported | Implementation details |
---|---|---|---|---|---|
mimes
|
No | Array of string | BidRequest |
Content MIME types supported (for example, "audio/mp4")
REQUIRED by the OpenRTB specification: at least 1 element. |
|
minduration
|
No | int32 | BidRequest |
Minimum video ad duration in seconds.
RECOMMENDED by the OpenRTB specification. |
|
maxduration
|
No | int32 | BidRequest |
Maximum video ad duration in seconds.
RECOMMENDED by the OpenRTB specification. |
|
protocols
|
No | Array of Protocol objects
|
BidRequest |
Array of supported video bid response protocols.
At least one supported protocol must be specified.
Examples: |
|
startdelay
|
No | int32 | BidRequest
>0: start delay in seconds
Other values: |
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 objects
|
BidRequest |
Blocked creative attributes. See the full list of available 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 Content |
BidRequest |
Supported delivery methods (for example, streaming, progressive).
If none specified, assume all are supported.
|
|
companionad
|
No | Array of Banner objects
|
BidRequest |
Array of Banner objects if companion ads are
available.
|
|
api
|
No | Array of APIFramework objects
|
BidRequest |
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 objects
|
BidRequest |
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 | BidRequest |
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
This object represents a native type impression. Native ad units are intended to blend seamlessly into the surrounding content (for example, a sponsored Twitter or Facebook post). As such, the response must be well-structured to afford the publisher fine-grained control over rendering.
Note that Native 1.1 is supported in OpenRTB 2.4 and OpenRTB 2.5.
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 | Authorized Buyers equivalent | Supported | Implementation details |
---|---|---|---|---|---|
request
|
No | string | BidRequest |
Request payload complying with the Native Ad Specification.
Exactly one of |
|
request_native
|
No | NativeRequest | BidRequest |
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 objects
|
BidRequest |
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 objects
|
BidRequest |
Blocked creative attributes. See the full list of available attributes. |
Pmp
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 | Authorized Buyers equivalent | Supported | Implementation details |
---|---|---|---|---|---|
private_auction
|
No | bool | BidRequest |
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 objects
|
BidRequest |
Array of Deal objects that convey the specific deals
applicable to this impression.
|
Deal
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 | Authorized Buyers equivalent | Supported | Implementation details |
---|---|---|---|---|---|
id |
Yes | string | BidRequest |
A unique identifier for the direct deal. REQUIRED by the OpenRTB specification. | |
bidfloor |
No | double | BidRequest |
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 | BidRequest |
Allowlist of buyer seats (for example, 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 (for example, advertiser.com) allowed to bid on this deal. Omission implies no advertiser restrictions. | |
at |
No | AuctionType | BidRequest.auction_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. | |
ext |
No | DealExt object |
Not supported | For OpenRTB/Protobuf, you can access this object with the
[com.google.doubleclick.deal] extension key
(exact path varies based on language used to generate proto library). For
OpenRTB/JSON, you access with the ext field in the Deal
message.
|
DealExt
Attribute | Always passed | Type | Authorized Buyers equivalent | Implementation details |
---|---|---|---|---|
deal_type |
No | Enum DealType | BidRequest.AdSlot. |
The type of the deal. Note that Authorized Buyers policy overrides
apply to all Programmatic Guaranteed and Preferred Deal bids, and do not
apply to bids for other deal types.
UNKNOWN_DEAL_TYPE = 0; Default. PREFERRED_DEAL = 1; Bids are fixed-price and evaluated before the Open Auction. Bidders are not required to bid with Preferred Deals when they are present on the bid request. See this article for more information. PRIVATE_AUCTION = 2; Bids participate in a Private Auction against a select list of buyers with specific floors. See this article for more information. PROGRAMMATIC_GUARANTEED = 3; Bids are fixed-price and evaluated before the Open Auction. Bidders are expected to bid with Programmatic Guaranteed deals whenever they are present on a bid request and the must_bid field is true in order to ensure that the number of impressions agreed upon for a given deal are served. See this article for more information. AUCTION_PACKAGE = 4; The deal ID is an identifier for a collection of Open Auction inventory matching a given set of targeting criteria. See this article for more information. MARKETPLACE_PACKAGE = 5; The deal ID for publisher curated inventory packages. These deal IDs are automatically sent to any eligible buyer for the package. See this article for more information. |
must_bid |
No | bool | BidRequest.AdSlot. |
This field is only applicable to Programmatic Guaranteed deals. The buyer is allowed to skip bidding on the impression if this field is false. When it is true, the buyer is required to bid on this deal for this impression opportunity. This field will always be filled explicitly for the JSON wire format. Default = true. |
publisher_blocks_overridden |
No | bool | BidRequest.AdSlot. |
Whether the publisher has exempted this deal from configured blocks. This setting does not override Authorized Buyers policies or Ad Review Center decisions. See this article for more information. |
creative_source |
No | Enum CreativeSourceType | BidRequest.AdSlot. |
Experimental field; subject to change.
An enum declaring the host of the creative, which will only be populated
for Programmatic Guaranteed deals. Currently, this field should only ever
be set to CREATIVE_SOURCE_ADVERTISER.
CREATIVE_SOURCE_UNKNOWN = 0; CREATIVE_SOURCE_ADVERTISER = 1; (Default) The creative is hosted by the advertiser, which means the bidder is required to provide a creative in the bid response. CREATIVE_SOURCE_PUBLISHER = 2; The creative is hosted by the publisher, which means the bidder does not need to include a creative in the bid response. For more information on publisher-hosted creatives, see https://support.google.com/admanager/answer/9243220. This feature isn't currently supported for RTB bidders. |
creative_constraints |
No | CreativeConstraints object |
BidRequest.AdSlot. |
Creative constraints for this deal. If this is not set, bidders should refer to the BidRequest-level setting of each field. |
billing_id |
No | int64 | BidRequest.AdSlot. |
Indicates the eligible billing IDs for this deal. If this list is not empty, the billing ID selected in `BidResponse.seatbid.bid.ext.billing_id` must be one of these IDs when submitting a bid on this deal. If this list is empty, then the bid on this deal can be attributed to any of the billing IDs in `BidRequest.imp.ext.billing_id`. |
CreativeConstraints
Attribute | Always passed | Type | Authorized Buyers equivalent | Implementation details |
---|---|---|---|---|
mtypes |
No | Enum CreativeMarkupType | BidRequest.AdSlot. |
The allowed ad types of the deal. If empty, there are no deal-specific allowed ad type
restrictions for the deal. In that case, bidders should refer to the presence of
Banner , Video , Audio or Native objects in
the BidRequest to check the allowed formats. The possible values contains in this field are
|
skippability |
No | Enum SkippabilityConstraint | BidRequest.AdSlot. |
Whether skippable creatives are allowed. For PROGRAMMATIC_GUARANTEED or
PREFERRED_DEAL deals that specifically allow video or audio ad types, it is
always set. This possible values of this field are
video.skip .
|
maxduration |
No | int32 | BidRequest.AdSlot. |
Maximum video ad duration in seconds. For PROGRAMMATIC_GUARANTEED or
PREFERRED_DEAL deals that specifically allow video or audio ad
types, it is always set. For the allowed max duration of other deal types or open auction
bidding, refer to the corresponding BidRequest-level field
video.maxduration .
|
Site
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 | Authorized Buyers equivalent | Supported | Implementation details |
---|---|---|---|---|---|
id
|
No | string | Not supported | Site ID on the exchange. RECOMMENDED by the OpenRTB specification. | |
name
|
No | string | Not supported | 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. Refer to enum ContentCategory .
|
|
sectioncat
|
No | Array of string | Not supported | Array of IAB content categories that describe the current section of the
site. Refer to enum ContentCategory .
|
|
pagecat
|
No | Array of string | Not supported | Array of IAB content categories that describe the current page or view
of the site. Refer to enum ContentCategory .
|
|
page
|
No | string | BidRequest |
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 the alternate representation may require custom handling of the JSON. | |
mobile
|
No | bool | BidRequest |
Indicates if the site has been programmed to optimize layout when viewed on mobile devices, where 0 = no, 1 = yes. | |
ext |
No | SiteExt object |
Not supported | For OpenRTB/Protobuf, you can access this object with the
[com.google.doubleclick.site] extension key
(exact path varies based on language used to generate proto library). For
OpenRTB/JSON, you access with the ext field in the Site
message.
|
SiteExt
Attribute | Always passed | Type | Authorized Buyers equivalent | Implementation details |
---|---|---|---|---|
amp |
No | Enum AmpPage | BidRequest.AdSlot .is_amp_page |
Whether this is an AMP page or not. Omitted if unknown. DIALECT_HTML = 0; This is not an AMP page. DIALECT_HTML_AMP = 1; This is an AMP page. |
page_visibility |
No | Enum VisibilityState | BidRequest |
The visibility state of the web page containing the ad slot. See www.w3.org/TR/page-visibility/. VISIBILITY_STATE_UNKNOWN = 0 VISIBILITY_STATE_VISIBLE = 1; The page is at least partially visible. For example, in the foreground tab of a non-minimized window. VISIBILITY_STATE_HIDDEN = 2; The page is not visible at all to users. For example, when the page is on a background browser tab, or in a minimized window. |
is_semi_transparent_request |
No | bool | BidRequest |
Indicates that the request is using semi-transparent branding, which means only a truncated version of the request URL will be provided. This decision is made by the publisher, see support.google.com/admanager/answer/4584891. |
inventorypartnerdomain |
No | string | BidRequest.inventorypartnerdomain | The domain of the partner (of the app owner) with ownership of some portion of ad inventory on the app. The partner's ads.txt or app-ads.txt file will be hosted here. More detail at http://iabtechlab.com/wp-content/uploads/2021/03/ctv-app-ads-explainer-guide.pdf |
App
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 | Authorized Buyers equivalent | Supported | Implementation details |
---|---|---|---|---|---|
id
|
No | string | Not supported | Application ID on the exchange. RECOMMENDED by the OpenRTB specification. | |
name
|
No | string | BidRequest |
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 | BidRequest |
Note: Values for this field are now redacted. Array of IAB
content categories of the app. Refer to enum ContentCategory .
|
|
sectioncat
|
No | Array of string | Not supported | Array of IAB content categories that describe the current section of the
app. Refer to enum ContentCategory .
|
|
pagecat
|
No | Array of string | Not supported | Array of IAB content categories that describe the current page or view
of the app. Refer to enum ContentCategory .
|
|
ver
|
No | string | Not supported | Application version. | |
bundle
|
No | string | BidRequest |
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 (for example, 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 | BidRequest |
App store URL for an installed app. | |
ext |
No | AppExt object |
Not supported | For OpenRTB/Protobuf, you can access this object with the
[com.google.doubleclick.app] extension key
(exact path varies based on language used to generate proto library). For
OpenRTB/JSON, you access with the ext field in the App
message.
|
AppExt
Attribute | Always passed | Type | Authorized Buyers equivalent | Implementation details |
---|---|---|---|---|
installed_sdk |
No | InstalledSdk | BidRequest.Mobile.installed_sdk | Identification of and information about an SDK installed in the publisher's app that the bidder has access to, often because it's the bidder's SDK. |
inventorypartnerdomain |
No | string | BidRequest.inventorypartnerdomain | The domain of the partner (of the app owner) with ownership of some portion of ad inventory on the app. The partner's ads.txt or app-ads.txt file will be hosted here. More detail at http://iabtechlab.com/wp-content/uploads/2021/03/ctv-app-ads-explainer-guide.pdf |
InstalledSdk | ||||
id |
Yes | string | BidRequest.Mobile. |
Identifier for the installed SDK. |
sdk_version |
Yes | Version | BidRequest.Mobile. |
The version of the installed SDK. |
adapter_version |
Yes | Version | BidRequest.Mobile. |
The version of the adapter that communicates with the installed SDK. |
Version | ||||
major |
No | int32 | Not supported | Default = -1. |
minor |
No | int32 | Not supported | Default = -1. |
micro |
No | int32 | Not supported | Default = -1. |
Publisher
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 | Authorized Buyers equivalent | Supported | Implementation details |
---|---|---|---|---|---|
id
|
No | string | BidRequest |
Exchange-specific publisher ID as defined by the publisher code suffix
of the web property code. For example, pub-123 is the publisher
code of the web property code ca-pub-123 .
|
|
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. Refer to enum ContentCategory .
|
|
domain
|
No | string | Not supported | Highest level domain of the publisher (for example, "publisher.com") | |
ext |
No | PublisherExt object |
Not supported | For OpenRTB/Protobuf, you can access this object with the
[com.google.doubleclick.publisher] extension key
(exact path varies based on language used to generate proto library). For
OpenRTB/JSON, you access with the ext field in the Publisher
message.
|
PublisherExt
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 or the hosting country of the website. Also refer to the complete list of country codes. |
host_publisher_id |
No | string | BidRequest |
The ID of the host publisher. When populated, indicates that the host publisher participated in revenue sharing, and the ID can be used to authorize ads.txt. |
Content
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 | Authorized Buyers equivalent | Supported | Implementation details |
---|---|---|---|---|---|
id
|
No | string | Not supported | ID uniquely identifying the content. | |
episode
|
No | int32 | Not supported | Content episode number (typically applies to video content). | |
title
|
No | string | Not supported | 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 (for example, "Season 3"). | |
artist
|
No | string | Not supported | Artist credited with the content | |
genre
|
No | string | Not supported | Genre that best describes the content (for example, 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 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. Refer to enum
ContentCategory .
|
|
prodq |
No | ProductionQuality | BidRequest |
Production quality.
|
|
keywords
|
No | Not supported | 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 GENERAL_AUDIENCES: "DV-G", PARENTAL_GUIDANCE: "DV-PG", TEEN: "DV-T", MATURE_AUDIENCES: "DV-MA" |
Content rating. Possible values: "DV-G", "DV-PG", "DV-T", "DV-MA". | |
userrating
|
No | string | (Only App.content) BidRequest |
User rating of the content (for example, 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 | BidRequest.Video.is_livestream | 0 = not live, 1 = content is live (for example, stream, live blog). | |
sourcerelationship
|
No | bool | Not supported | 0 = indirect, 1 = direct. | |
producer
|
No | string | BidRequest |
Details about the content Producer. | |
len
|
No | int32 | BidRequest |
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 (for example, an embeddable video player), where 0 = no, 1 = yes. | |
language
|
No | string | BidRequest |
Content language using ISO-639-1-alpha-2. | |
data
|
Yes | Array of Data objects
|
BidRequest |
Additional content data. Each object represents a different data source. Used for Publisher Provided Signals. |
Producer
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 | Authorized Buyers equivalent | Supported | 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 (for example, "Warner Bros"). | |
cat
|
No | Array of string | Not supported | Array of IAB content categories that describe the content producer. Refer to
enum ContentCategory .
|
|
domain
|
No | string |
BidRequest |
Highest level domain of the content producer (for example, "producer.com"). |
Device
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 | Authorized Buyers equivalent | Supported | Implementation details |
---|---|---|---|---|---|
dnt
|
No | bool | Unsupported; Refer to Cookie Guide, google_error=1: | Standard "Do Not Track" option 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 | BidRequest |
Browser user agent string. RECOMMENDED by the OpenRTB specification. | |
ip
|
No | string | BidRequest 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 (for example, IMEI); hashed through SHA1. | |
didmd5
|
No | string | Not supported | Hardware device ID (for example, IMEI); hashed through MD5. | |
dpidsha1
|
No | string | Not supported | Platform device ID (for example, Android ID); hashed through SHA1 | |
dpidmd5
|
No | string | BidRequest 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 (for example, Android ID); hashed through MD5. | |
ipv6
|
No | string | BidRequest - AdX truncates to first 6 octets; OpenRTB is "X:X:X:::::" |
IPv6 address closest to device. | |
carrier
|
No | string | BidRequest IDs will be the same Criterion IDs as in the Authorized Buyers protocol, refer to the mobile carriers list. |
Carrier or ISP (for example, "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 make (for example, "Apple" or "Samsung"). | |
model
|
No | string | BidRequest |
Device model (for example, "pixel 7 pro"). For iPhone/iPad, this field contains Apple's model identifier string (such as "iPhone12,1" and "iPad13,8") if available. Otherwise this field contains the generic model (either "iphone" or "ipad"). | |
os
|
No | string | BidRequest |
Device operating system (for example, "iOS") | |
osv
|
No | string | BidRequest |
Device operating system version | |
hwv
|
No | string | BidRequest |
Hardware version of the device. For iPhone/iPad, this field contains Apple's model identifier string (such as "iPhone12,1" and "iPad13,8") if available. | |
w
|
No | int32 | BidRequest |
Physical width of the screen in pixels. | |
h
|
No | int32 | BidRequest |
Physical height of the screen in pixels. | |
ppi
|
No | int32 | Not supported | Screen size as pixels per linear inch. | |
pxratio
|
No | double | BidRequest |
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 | BidRequest.Device.connection_type | Network connection type. Google: For 5G connection type, we send CELL_4G instead
of CELL_5G .
|
|
devicetype
|
No | DeviceType | BidRequest |
The general type of device. | |
flashver
|
No | string | Not supported | Version of Flash supported by the browser. | |
ifa
|
No | string | BidRequest 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 (for example, not hashed). | |
macsha1
|
No | string | Not supported | MAC address of the device; hashed through SHA1. | |
macmd5
|
No | string | Not supported | MAC address of the device; hashed through MD5 | |
lmt
|
No | bool | BidRequest |
"Limit Ad Tracking" is a commercially endorsed signal based on the
operating system or device settings, where false indicates
that tracking is unrestricted and true indicates that
tracking must be limited per commercial guidelines.
This signal reflects user decisions on surfaces including iOS App Tracking Transparency. See also lmt and App Tracking Transparency guidance and Android advertising ID. |
|
mccmnc
|
No | string | Not supported | Mobile carrier as the concatenated MCC-MNC code (for example, "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. | |
ext |
No | DeviceExt object |
Not supported | For OpenRTB/Protobuf, you can access this object with the
[com.google.doubleclick.device] extension key
(exact path varies based on language used to generate proto library). For
OpenRTB/JSON, you access with the ext field in the Device
message.
|
DeviceExt
Attribute | Always passed | Type | Authorized Buyers equivalent | Implementation details |
---|---|---|---|---|
session_id |
No | string | BidRequest.session_id | Represents a short-lived user session on CTV/OTT devices, with a maximum session duration of 6 hours. The use of session_id is never allowed for ads personalization. session_id may only be used for frequency capping, competitive exclusions or related purposes. This field is populated with web-safe base64 alphabet. |
atts |
No | int32 | BidRequest |
(iOS Only) An integer passed to represent the app's app tracking authorization status, where 0 = not determined 1 = restricted 2 = denied 3 = authorized. This value is retrieved from ATTrackingManager and provided as is. For more information about iOS's app tracking authorization status, see this article. |
user_agent_data |
No | UserAgent object |
BidRequest.user_agent_data | User Agent information. |
UserAgent
User Agent information. This will be populated with information about the user agent, extracted from the User-Agent header or from Sec-CH-UA headers.
Attribute | Always passed | Type | Authorized Buyers equivalent | Implementation details |
---|---|---|---|---|
browser |
No | BrandVersion object |
BidRequest.user_agent_data.browser | Identifies the browser. |
platform |
No | BrandVersion object |
BidRequest.user_agent_data.platform | Identifies the platform. |
mobile |
No | bool | BidRequest.user_agent_data.mobile | True if the agent prefers "mobile-optimized" content. Refer to the BidRequest.device field for specific information about the device, which may or may not be consistent with this field (for example, a mobile phone's browser can be requesting "Desktop site"). |
architecture |
No | string | BidRequest.user_agent_data.architecture | Device architecture, for example, "x86" or "arm". |
bitness |
No | string | BidRequest.user_agent_data.bitness | Device's bitness, for example, "64" for 64-bit architecture. |
model |
No | string | BidRequest.user_agent_data.model | Device model. |
BrandVersion object
A tuple of (brand, version) for the browser or platform.
Attribute | Always passed | Type | Authorized Buyers equivalent | Implementation details |
---|---|---|---|---|
brand |
No | string | BidRequest.user_agent_data.brand | Brand identifier, for example, "Chrome" or "Windows". |
version |
No | string | BidRequest.user_agent_data.version | Version, split in components if needed, for example, {"85", "1"} = v85.1. |
Geo
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 (for example, 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.
In Google's implementation of OpenRTB, coarse geolocation information is
approximated based on the IP address of the device the ad request originated
from. This information will typically–but not always–be included in the bid
request with lat
/lon
representing the center point of
a circle, where accuracy
is its radius. To learn more about
geolocation, see the
Geotargeting guide.
Attribute | Always passed | Type | Authorized Buyers equivalent | Supported | 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 |
Longitude from -180.0 to +180.0, where negative is west. | |
country
|
No | string | BidRequest |
Country using ISO-3166-1 Alpha-3. | |
region
|
No | string | BidRequest |
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 |
Google metro code; similar to but not exactly Nielsen DMAs.
Refer to the Geographical Targeting page for a link to the codes. |
|
city
|
No | string | BidRequest |
City using United Nations Code for Trade & Transport Locations in the format
"city": "San Antonio" .Refer to
Appendix A for a link to the
codes.
|
|
zip
|
No | string | BidRequest BidRequest |
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 (for example, type = 1). Note that this is the accuracy as reported from the device. Consult OS specific documentation (for example, Android, iOS) for exact interpretation. Google: The radius in meters of a circle approximating the location of a device, where the center point is defined by lat/lon. This field is populated based on coarse IP-based geolocation. | |
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 (for example, type = 2). | |
utcoffset
|
No | int32 | BidRequest |
Local time as the number +/- of minutes from UTC. | |
ext |
No | GeoExt object |
Not supported | For OpenRTB/Protobuf, you can access this object with the
[com.google.doubleclick.geo] extension key
(exact path varies based on language used to generate proto library). For
OpenRTB/JSON, you access with the ext field in the Geo
message.
|
GeoExt
Attribute | Always passed | Type | Authorized Buyers equivalent | Implementation details |
---|---|---|---|---|
geo_criteria_id |
No | int32 | BidRequest.geo_criteria_id | The device's approximate geographic location. See
geo-table.csv for
a list of IDs. This field is provisional, intended only to help with
migration from the Google Authorized Buyers protocol to OpenRTB; it will
be removed in the future. The standard fields in BidRequest.device.geo
should be used instead; they contain the same location as the
geo_criteria_id and both are subject to the same privacy treatments.
See Geotargeting
Guide. |
User
This object contains information known or derived about the human user of the device (for example, 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 | Authorized Buyers equivalent | Supported | Implementation details |
---|---|---|---|---|---|
id
|
No | string | BidRequest |
Exchange-specific ID for the user. At least one of id or buyerid
is recommended
|
|
buyeruid
|
No | string | BidRequest |
Buyer-specific ID for the user as mapped by the exchange for the buyer.
At least one of buyerid or id is recommended.
|
|
gender
|
No | string | Not supported | Gender as "M" male, "F" female, "O" Other. (Null indicates unknown) | |
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 |
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
|
Yes | Array of Data objects
|
BidRequest |
Additional user data. Each Data object represents a different data source. Used for Chrome Topics API and for Publisher Provided Signals. | |
eids
|
No | Array of EID objects | Not supported | Data made available by the publisher, such as publisher-provided
identifiers. For Secure Signals, see extension
BidRequest.user.ext.eids .
|
|
ext |
No | UserExt object |
Not supported | For OpenRTB/Protobuf, you can access this object with the
[com.google.doubleclick.user] extension key
(exact path varies based on language used to generate proto library). For
OpenRTB/JSON, you access with the ext field in the User
message.
|
EID
Extended data, such as a publisher-provided identifier, that allows buyers to use data made available by the publisher in real-time bidding. This object can contain one or more UIDs from a single source or a technology provider.
Attribute | Always passed | Type | Authorized Buyers equivalent | Supported | Implementation details |
---|---|---|---|---|---|
source
|
No | string |
|
Source or technology provider responsible for the set of included IDs. Expressed as a top-level domain. In Google's OpenRTB implementation, the |
|
uids
|
No | Array of UID objects | Not supported | Array of extended ID UID objects from the given source. |
UID
This object contains a single data item, such as a publisher-provided identifier, provided as part of extended identifiers.
Attribute | Always passed | Type | Authorized Buyers equivalent | Supported | Implementation details |
---|---|---|---|---|---|
id
|
No | string |
|
The data value, such as a publisher-provided identifier. |
|
ext
|
No | UIDExt object | Not supported | For OpenRTB/Protobuf, you can access this object with the
[com.google.doubleclick.user.eids.uids] extension key (exact
path varies based on language used to generate proto library). For
OpenRTB/JSON, you access with the ext field in the UID
message.
|
UserExt
Attribute | Always passed | Type | Authorized Buyers equivalent | Implementation details |
---|---|---|---|---|
consented_providers_ |
No | ConsentedProvidersSettings object |
BidRequest.AdSlot. |
Information about the ad tech providers for whom the publisher has specified to Google that its EEA user has consented to the use of their personal data for ads personalization in accordance with Google's EU User Consent Policy. This field will only be populated when RegsExt.gdpr is true. |
consent |
No | string | BidRequest.AdSlot. |
The web-safe base64-encoded IAB Transparency and Consent Framework
(TCF) v2 consent string fetched from the publisher's IAB Consent
Management Platform (CMP). The structure of the string is defined by the
IAB TCF v2. This field will be populated if the publisher has integrated
with a CMP for TCF v2 and that CMP indicates that GDPR applies to this ad
request and provides a valid consent string. See
this
article for additional information about the Google TCF v2 integration.
See the IAB Global Vendor List at vendor-list.consensu.org/v2/vendor-list.json for details about the vendors listed in the consent string. |
eids |
No | Array of ExtendedId objects |
Not supported | |
idage |
No | int32 | BidRequest.cookie_age_seconds | The amount of time, in seconds, since the ID in BidRequest.user.id was
created. |
session |
No | Session object |
Supported. See Session for mapping details. | Describes a user session in a given app or site. The session is reset after a sufficiently long break in user activity. |
UIDExt
Attribute | Always passed | Type | Authorized Buyers equivalent | Implementation details |
---|---|---|---|---|
stype
|
No | string | None. The value of this field will determine what the
|
The source type of the UID. See details here. |
ConsentedProviderSettings
Information about the ad tech providers for whom the publisher has specified to Google that its EEA user has consented to the use of their personal data for ads personalization in accordance with Google's EU User Consent Policy. This field will only be populated when RegsExt.gdpr is true.
Attribute | Always passed | Type | Authorized Buyers equivalent | Implementation details |
---|---|---|---|---|
consented_providers |
No | Array of int64 | BidRequest.AdSlot. |
Set of IDs corresponding to ad tech providers (ATPs) for whom the
publisher has specified to Google that its EEA users have given legally
valid consent to: 1) the use of cookies or other local storage where
legally required; and 2) the collection, sharing, and use of personal
data for personalization of ads by an ATP in accordance with Google's EU
User Consent Policy.
If a publisher is using the IAB Transparency and Consent Framework (TCF) v2 to manage user consent, this is the set of ATPs consented through the Additional Consent string (see this article for details about Google's Additional Consent mode). ATPs consented through the TCF v2 consent string are represented in the UserExt.consent field. A mapping of ATP ID to ATP name is posted at providers.csv. |
ExtendedId
Extended data, such as secure signals or a publisher-provided identifier, that allows buyers to use data made available by the publisher in real-time bidding. This object can contain one or more UIDs from a single source or a technology provider.
Attribute | Always passed | Type | Authorized Buyers equivalent | Implementation details |
---|---|---|---|---|
source |
No | string | BidRequest.AdSlot.SecureSignal.source | Source or technology provider responsible for the included signals. |
uids |
No | Array of ExtendedIdUid
objects from the given source. |
None | The secure signal. |
ExtendedIdUid
Attribute | Always passed | Type | Authorized Buyers equivalent | Implementation details |
---|---|---|---|---|
id |
No | string | BidRequest.AdSlot.SecureSignal.data | The data value, such as a secure signal. |
Session
Describes a user session in a given app or site. The session is reset after a sufficiently long break in user activity.
Attribute | Always passed | Type | Authorized Buyers equivalent | Implementation details |
---|---|---|---|---|
duration |
No | int32 | BidRequest.session_duration_seconds | Describes the time in seconds since the first ad request in the session. Currently the session duration is only populated for mobile app requests. |
Data
The data
and segment
objects together allow
additional contextual data 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.
This is used to send Publisher Provided Signals and Topics to the buyer.
Attribute | Always passed | Type | Authorized Buyers equivalent | Supported | Implementation details |
---|---|---|---|---|---|
id
|
No | string | Supported | The Google assigned ID of the data provider. Only set for Data segments from Publisher Provided Signals. For the list of data providers, see https://storage.googleapis.com/adx-rtb-dictionaries/data_providers.txt. | |
name
|
No | string | Supported | Exchange-specific name for the data provider. | |
segment
|
Array of Segment objects
|
Supported | Array of Segment objects that contain the actual
data values.
|
||
ext
|
No | DataExt object
|
Supported | Populated only if the Data segments contain values from taxonomies that Google supports. For
OpenRTB protobuf, you can access this object with the
[com.google.doubleclick.data] extension key. For OpenRTB JSON, you can access the
object with the ext field in the Data message.
|
DataExt
Attribute | Always passed | Type | Authorized Buyers equivalent | Implementation details |
---|---|---|---|---|
segtax |
No | int32 | BidRequest.segment_data.type | Identifies the taxonomy that the segment IDs belong to. Google supports the following taxonomies:
IAB Tech Lab Audience Taxonomy 1.1 = 4
|
Segment
The data
and segment
objects together allow
additional contextual data 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 | Authorized Buyers equivalent | Supported | Implementation details |
---|---|---|---|---|---|
id
|
No | string | Supported | ID of the data segment specific to the data provider. | |
name
|
No | string | Supported | Name of the data segment specific to the data provider. | |
value
|
string | Supported | String representation of the data segment value. |
Regs
This object contains any legal, governmental, or industry
regulations that apply to the request. The coppa
option 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 | Authorized Buyers equivalent | Supported | Implementation details |
---|---|---|---|---|---|
coppa
|
No | string | BidRequest |
Option indicating if this request is subject to the COPPA regulations established by the USA FTC, where 0 = no, 1 = yes. | |
gpp |
No | string | BidRequest.AdSlot. |
Contains the Global Privacy Platform's consent string. See IAB-GPP spec for more details. | |
gpp_sid |
No | Array of GppSectionId enum |
BidRequest.AdSlot. |
Array of the section(s) of the GPP string which should be applied for this transaction. Generally will contain one and only one value, but there are edge cases where more than one may apply. GPP Section 3 (Header) and 4 (Signal Integrity) do not need to be included. See IAB-GPP spec for details. | |
ext |
No | RegsExt object |
Not supported | For OpenRTB/Protobuf, you can access this object with the
[com.google.doubleclick.regs] extension key
(exact path varies based on language used to generate proto library). For
OpenRTB/JSON, you access with the ext field in the Regs
message.
|
RegsExt
Attribute | Always passed | Type | Authorized Buyers equivalent | Implementation details |
---|---|---|---|---|
gdpr |
No | bool | BidRequest.AdSlot. |
This field will be set to true in either of the two following cases:
|
lgpd |
No | bool | BidRequest.AdSlot. |
This field will be set to true when, based on information available to
Google, this impression will serve to a user in Brazil. See https://storage.googleapis.com/adx-rtb-dictionaries/lgpd-providers.csv
for the list of ad tech providers that are allowed to serve on
LGPD-enforced requests.
See this article for more information on LGPD. |
dsa |
No | Dsa object |
BidRequest. |
The Digital Services Act (DSA) transparency information requirements. See Help Center link. |
Dsa
Attribute | Required/Optional | Type | Implementation details |
---|---|---|---|
dsarequired |
optional | DsaSupport enum | Values indicating whether DSA declarations should be included in the bid response and,
if so, whether or not the publisher is an Online Platform (OP) or Very Large Online
Platform (VLOP), as defined by the DSA.
|
pubrender |
optional | PublisherRenderingSupport enum | Options describing a publisher's ability to render DSA transparency declarations.
|
datatopub |
optional | DataToPublisher enum | Options describing if a publisher requires DSA transparency declarations.
|
Refresh
Details about ad slots being refreshed automatically.
Attribute | Always passed | Type | Authorized Buyers equivalent | Supported | Implementation details |
---|---|---|---|---|---|
refsettings
|
No | Array of RefSettings objects
|
BidRequest.AdSlot. |
Describes the mechanics of how an ad placement automatically refreshes. | |
count |
No | int32 | BidRequest.AdSlot. |
The number of times this ad slot had been refreshed since last page load. |
RefSettings
Information on how often and what triggers an ad slot being refreshed.
Attribute | Always passed | Type | Authorized Buyers equivalent | Implementation details |
---|---|---|---|---|
reftype |
No | AutoRefreshType enum |
BidRequest.AdSlot. |
The type of the declared auto refresh. Refer to List: Auto Refresh Trigger in AdCOM 1.0 |
minint |
No | int32 | BidRequest.AdSlot. |
The minimum refresh interval in seconds. This applies to all refresh types. This is the (uninterrupted) time the ad creative will be rendered before refreshing to the next creative. If the field is absent, the exposure time is unknown. This field does not account for viewability or external factors such as a user leaving a page. |
Bid response variables and definitions
This section describes the bid response variables and definitions.
BidResponse
This object is the top-level bid response object (for example, 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 wants 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 | Always passed | Type | Authorized Buyers equivalent | Supported | 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 objects
|
BidResponse
|
Array of Seatbid objects; 1+ required if a bid is to be made.
|
|
bidid
|
No | string | BidResponse |
Bidder generated response ID to assist with logging/tracking. | |
cur |
No | string | BidResponse.Ad.AdSlot.currency |
Bid currency using ISO-4217 alpha codes. If this field is populated, the specified currency will be used to interpret the bid. Otherwise, the default bidding currency will be used, which is determined in the following priority:
The currency of a buyer account is set on account creation and can be checked by contacting a Technical Account Manager. |
|
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 object |
Not supported | For OpenRTB/Protobuf, you can access this object with the
[com.google.doubleclick.bid_response] extension key
(exact path varies based on language used to generate proto library). For
OpenRTB/JSON, you access with the ext field in the BidResponse
message.
|
BidResponseExt
Attribute | Always passed | Type | Authorized Buyers equivalent | Implementation details |
---|---|---|---|---|
processing_time_ms |
No | int32 | BidResponse |
Set this to the processing time in milliseconds from when you received the request to when you returned the response. |
Seatbid
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 | Always passed | Type | Authorized Buyers equivalent | Supported | Implementation details |
---|---|---|---|---|---|
bid
|
No | Array of Bid objects
|
BidResponse |
Array of 1+ Bid objects each related to an impression.
Multiple bids can relate to the same impression.
|
|
seat |
No | string | BidResponse |
ID of the buyer seat (for example, 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
A SeatBid
object contains one or more Bid
objects, each of which
relates to a specific impression in the bid request through the impid
attribute and
constitutes an offer to buy that impression for a given price.
Attribute | Always passed | Type | Authorized Buyers equivalent | Supported | 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 |
ID of the Imp object in the related bid request. REQUIRED
by the OpenRTB specification. |
|
price
|
Yes | double | BidResponse |
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 (for example, 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 | Not supported | 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 |
Optional means of conveying ad markup in case the bid wins; supersedes
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 |
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 |
Advertiser domain for block list checking (for example, "addomain.com"). This can be an array for the
case of rotating creatives. Exchanges can mandate that only one domain is allowed. The OpenRTB
spec only allows domain names in adomain ; Authorized Buyers support full URLs too.
Note this must be a crawlable domain or URL and the URL must be valid. For native ads, we recommend using
BidResponse.seatbid[].bid[].adm_native.link.url instead of adomain .
|
|
bundle
|
No | string | BidResponse |
The store ID of the app in an app store such as Apple App Store, Google Play. See OTT/CTV Store Assigned App Identification Guidelines for more details about expected strings for CTV app stores. For mobile apps in Google Play Store, these should be bundle or package names, such as com.foo.mygame. For apps in Apple App Store, these should be a numeric ID. Google: In addition to this field, set bid.ext.app_promotion_type field to take advantage of features specific to app promotion types. | |
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 |
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. If not set to one of the buyer's
When submitting creatives, a |
|
crid
|
No | string | BidResponse |
Creative ID to assist with ad quality checking. | |
cat
|
No | Array of string | BidResponse.Ad.category | IAB content categories of the creative. | |
attr
|
No | Array of CreativeAttribute objects
|
BidResponse |
Set of attributes describing the creative.
Can be declared in OpenRTB as bid.attr (OpenRTB),
or bid.ext.attribute (AdX).
|
|
api
|
No | APIFramework | Bid.api supports declaring attributes 1, 2, 3, and 5 which correspond to VPAID and MRAID versions | 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 |
Reference to the deal.id from the bid request if this bid pertains to a
private marketplace direct deal.
|
|
w
|
No | int32 | BidResponse |
Width of the creative in device independent pixels (DIPS). | |
h
|
No | int32 | BidResponse |
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 |
Billing notice URL called by the exchange when a winning bid becomes
billable based on exchange-specific business policy (for example, typically
delivered, viewed, etc.). Substitution macros can be
used. 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 can be used. Exchange-specific policy may preclude support for loss notices or the disclosure of winning clearing prices resulting in ${AUCTION_PRICE} macros being removed (for example, 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 (for example, 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. | |
slotinpod
|
No | int32 | BidResponse |
Indicates that the bid is only eligible for a specific position within the pod. This field is currently only supported for rewarded video pods requests. | |
ext |
No | BidExt object |
Not supported | For OpenRTB/Protobuf, you can access this object with the
[com.google.doubleclick.bid] extension key
(exact path varies based on language used to generate proto library). For
OpenRTB/JSON, you access with the ext field in the Bid
message.
|
BidExt
Attribute | Always passed | Type | Authorized Buyers equivalent | Implementation details |
---|---|---|---|---|
impression_tracking_url |
No | Array of string | BidResponse.Ad. |
The URLs to call when the impression is rendered. This is supported for all inventory types
and all formats. In OpenRTB 2.5, Bid.burl is the analogous standard field. |
ad_choices_destination_ |
No | string | BidResponse.Ad. |
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. |
click_tracking_ |
No | string | BidResponse.Ad. |
The URLs to call when the user clicks on the ad. Currently supported only for native ads and Programmatic Guaranteed deals with publisher-managed creatives. In the publisher managed case, these click trackers will be sent to the bidder server to server. In all other cases, these will be sent from the user's device. For more information on publisher-managed creatives, see Publisher-managed creatives. |
exchange_deal_type |
No | Enum ExchangeDealType | BidResponse.Ad.AdSlot. |
OPEN_AUCTION = 0; PRIVATE_AUCTION = 1; PREFERRED_DEAL = 2; EXCHANGE_AUCTION_PACKAGE = 3; default = OPEN_AUCTION |
attribute |
No | Array of int32 | BidResponse.Ad. |
Refer to
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" (also known as "responsive" or "sizeless") interstitials that dynamically
resize to take up the entire screen width and height. Refer to the
description in the Interstitial
Ads guide for more information.
|
amp_ad_url |
No | string | BidResponse.Ad. |
The URL to fetch an AMPHTML ad. Only one of the following should be set: html_snippet, video_url, amp_ad_url, native_ad. |
sdk_rendered_ad |
No | SdkRenderedAd object |
BidResponse.Ad. |
An ad that will be rendered by an SDK known to the buyer. This can only be used when the BidRequest included an AppExt.InstalledSdk submessage. |
event_notification_token |
No | EventNotificationToken object |
BidResponse.Ad. |
A token set by bidders for troubleshooting which will be included in the real-time feedback for the Bid it is sent in. The contents of the token will not be logged. |
restricted_category |
No | Array of int32 | BidResponse.Ad. |
All restricted categories for the ads that may be shown from this snippet. See ad-restricted-categories.txt for a list of ids. |
billing_id |
No | int64 | BidResponse.Ad.AdSlot. |
The billing ID to attribute this impression to. The value must be in the repeated BidRequest.Imp.ImpExt.billing_id field sent for this impression. If the length of BidRequest.Imp.ImpExt.billing_id is exactly 1 and the bidder does not have active child seats, this field is not required and its contents will be ignored. |
third_party_ |
No | string | BidResponse.Ad.Adslot. |
Token used to identify end third party buyer information if the exchange as an Open Bidder is an intermediary. This is obtained from the third-party buyer and must be passed to Google unaltered in the bid response. |
buyer_ |
No | string | BidResponse.Ad.Adslot. |
Buyer declared ID which will be used to break down spend and invalid traffic metrics in IVT transparency reporting in Query Tool. Note that IDs with fewer than 1000 impressions will not be used to break down metrics. IDs longer than 64 bytes will be ignored. |
skadn |
No | SKAdNetworkResponse
object |
BidResponse.Ad. |
Advertiser's SKAdNetwork information to support app installation attribution for iOS 14 and later. Apple's SKAdNetwork API helps advertisers measure ad-driven app installation by sending a postback to the ad network after a successful install. Ad networks will need to send their network ID and signed advertiser information to allow an install to be attributed to the ad impression. For more info, see this article. |
app_promotion_type |
No | enum | BidResponse.Ad. |
Type of the app promotion corresponding to the advertised app specified
in the seatbid.bid.bundle field.
If the advertised app is not specified, this field will be ignored.
Setting bundle field without this field will be treated as if
this field were set to OTHER.
|
bid_group_id |
No | string | BidResponse.adslot. |
All bids with the same bid_group_id will be won or lost as a
group. Bids must have a non-empty bid_group_id to allow an ad to be
played as part of a pod.This field is currently only supported for rewarded video pods requests. |
dsa |
No | Dsa object |
BidResponse.ad. |
DSA Ad Transparency declarations. See Help Center link |
clickurl |
No | Array of string | BidResponse.Ad.click_through_url | The URLs that the user could be directed to when clicking on this ad. Do not include URLs for intermediate calls to an ad server that are unrelated to the final landing page. All bids must declare either a click URL using this field, the advertiser domain in the `BidResponse.seatbid.bid.adomain` field, or both. We recommend that bidders use this field, possibly in addition to `BidResponse.seatbid.bid.adomain`, for more accurate enforcement of publisher and user protections, for instance so that your bid is not incorrectly filtered. |
SdkRenderedAd | ||||
id |
No | string | BidResponse.ad[].sdk_rendered_ad.id |
The identifier for the SDK that will render the ad. Must match a
BidRequest.app.ext.installed_sdk.id sent in the
corresponding bid request. |
rendering_data |
No | string | BidResponse.ad[].sdk_rendered_ad.rendering_data |
Data to pass to the SDK in order to render the ad. This data is opaque to the publisher and to Google. |
declared_ad |
No | DeclaredAd | BidResponse.ad[].sdk_rendered_ad.declared_ad |
Declared ad assets to support creative scanning, classification, and enforcement of ad
policy and publisher blocks for ads rendered with a custom SDK. Set only one of
html_snippet , video_url , video_vast_xml , or
native_response . |
EventNotificationToken | ||||
payload |
No | string | BidResponse.ad[].event_notification_token |
The contents of the token, which will be ignored if longer than 128 bytes. |
SKAdNetworkResponse | ||||
version |
No | string | BidResponse.ad[].skadn.version |
Version of SKAdNetwork supported by the advertiser. Also used to specify how the signature was generated by the advertiser. This should match one of the versions from BidRequest.imp.ext.skadn.versions. |
network |
No | string | BidResponse.ad[].skadn.network |
Ad network identifier used in signature. This should match one of the items in BidRequest.imp.ext.skadn.skadnetids. |
campaign |
No | string | BidResponse.ad[].skadn.campaign |
Campaign ID compatible with Apple's spec. Used in SKAdNetwork 3.0 and
below. Replaced by the BidResponse.imp.ext.skadn.sourceidentifier
field in SKAdNetwork 4.0 and above. |
sourceidentifier |
No | string | BidResponse.ad[].skadn.source_identifier |
A four-digit integer that ad networks define to represent the ad
campaign. Used in SKAdNetwork 4.0+ and replaces the
BidResponse.imp.ext.skadn.campaign field. |
itunesitem |
No | string | BidResponse.ad[].skadn.itunesitem |
ID of advertiser's app in Apple's app store. |
productpageid |
No | string | BidResponse.ad[].skadn.product_page_id |
ID of custom product page to display (for iOS 15 or later). If not specified, default product page will be displayed. See this article for more details about custom product pages. |
fidelities |
No | Array of Fidelity objects |
BidResponse.ad[].skadn.fidelities |
SKAdNetwork API starting from version 2.2 supports multiple ad
presentation options specified by the fidelity-type
parameter of the SKAdNetwork signature. This holds parameters used to
generate the signature that would be different for each fidelity type
supported. For more info, see this
article.
|
nonce |
No | string | BidResponse.ad[].skadn.nonce |
A unique all-lowercase UUID generated by the advertiser to use for generating the signature. Note: This field will be deprecated in favor of the BidResponse.bid.ext.skadn.fidelities.nonce field to support multiple fidelity types. |
sourceapp |
No | string | BidResponse.ad[].skadn.sourceapp |
ID of publisher's app in Apple's app store. This should match the ID from BidRequest.imp.ext.skadn.sourceapp. |
timestamp |
No | string | BidResponse.ad[].skadn.timestamp |
Unix time in millis used at the time of signature generation. Note: This field will be deprecated in favor of the BidResponse.bid.ext.skadn.fidelities.timestamp field to support multiple fidelity types. |
signature |
No | string | BidResponse.ad[].skadn.signature |
SKAdNetwork signature as specified by Apple. Note: This field will be deprecated in favor of the BidResponse.bid.ext.skadn.fidelities.signature field to support multiple fidelity types. |
skoverlay |
No | SKOverlay
object |
BidResponse.ad[].skadn.skoverlay |
These options indicate how to present SKOverlay recommending the advertised app. Supported by iOS 14 and later. |
Dsa | ||||
behalf |
No | string | BidResponse.ad[].dsa_transparency.displayed_on_behalf |
Free text string describing the name of the advertiser on whose behalf the ad is shown. Bids will not be accepted if this value is longer than 100 characters. |
paid |
No | string | BidResponse.ad[].dsa_transparency.paying_entity |
Free text string describing the advertiser who paid for the ad. Must always be included even if it's the same as what is listed in the displayed_on_behalf attribute. Bids will not be accepted if this value is longer than 100 characters. |
adrender |
No | bool | BidResponse.ad[].dsa_transparency.buyer_render |
Indicates that the buyer will render their own DSA transparency information inside the creative. |
DeclaredAd object
Declared ad assets to support creative scanning, classification, and enforcement of ad policy and publisher blocks for ads rendered with a custom SDK.
Set only one of
html_snippet
, video_url
, video_vast_xml
, or
native_response
.
Attribute | Always passed | Type | Authorized Buyers equivalent | Implementation details |
---|---|---|---|---|
html_snippet |
No | string | BidResponse.ad[].sdk_rendered_ad.declared_ad.html_snippet | The HTML snippet representative of the SDK-rendered ad. |
video_url |
No | string | BidResponse.ad[].sdk_rendered_ad.declared_ad.video_url | The URL to the VAST asset used in the SDK-rendered ad. |
video_vast_xml |
No | string | BidResponse.ad[].sdk_rendered_ad.declared_ad.video_vast_xml | The VAST document used to render custom SDK-rendered ad. This document should conform to the VAST 2.0 or 3.0 standard. |
native_response |
No | NativeResponse |
BidResponse.ad[].sdk_rendered_ad.declared_ad.native_response | The content of a native ad. Native ads consist of multiple building blocks, which are
rendered by the buyer SDK. Must match the
OpenRTB Native 1.2 standard
NativeResponse definition.
NativeResponse.assets.img.type is required. |
click_through_url |
No | Array of string | BidResponse.ad[].sdk_rendered_ad.declared_ad.click_through_url | The final landing pages of the SDK-rendered ad. Note this must be a valid URL. |
Fidelity
Attribute | Always passed | Type | Authorized Buyers equivalent | Implementation details |
---|---|---|---|---|
fidelity |
No | enum SKAdNetworkFidelityType | BidResponse.ad[].skadn.fidelity_type |
The fidelity type of the attribution to track. Default =
STOREKIT_RENDERED_ADS.
VIEW_THROUGH_ADS = 0; Attribution for app installs within 24 hours of viewing an ad for at least 3 seconds. Supported for SKAdnetwork version 2.2 and up. For more info, see this article. STOREKIT_RENDERED_ADS = 1; Attribution for app installs initiated from the StoreKit-rendered App Store product page driven by ad clicks. Supported for all SKAdNetwork versions. For more info, see this article. |
nonce |
No | string | BidResponse.ad[].skadn.nonce |
A unique all-lowercase UUID generated by the advertiser to use for generating the signature. |
timestamp |
No | string | BidResponse.ad[].skadn.timestamp |
Unix time in millis used at the time of signature generation. |
signature |
No | string | BidResponse.ad[].skadn.signature |
SKAdNetwork signature as specified by Apple. |
SKOverlay
Attribute | Always passed | Type | Authorized Buyers equivalent | Implementation details |
---|---|---|---|---|
delay |
No | int32 | BidResponse.ad[].skadn.skoverlay.delay_seconds |
Delay in seconds after the ad begins before presenting the overlay. If this field is set to 0, the overlay will be shown immediately after the ad begins. If this field is unset, the overlay will not be shown for the ad. |
endcarddelay |
No | int32 | BidResponse.ad[].skadn.skoverlay.endcard_delay_seconds |
Delay in seconds after the endcard shows before presenting the
overlay. (This field only applies to rewarded or interstitial video
creatives.) If this field is set to 0, the overlay will be shown
immediately after the endcard shows. If this field is unset,
the overlay will not be shown for the endcard.
If both delay and endcarddelay are set,
the overlay will be automatically dismissed when the ad ends, and
shown again after the endcard shows.
|
dismissible |
No | bool | BidResponse.ad[].skadn.skoverlay.dismissible |
Whether this overlay can be dismissed by the user. Default to be true. |
Native bid variables, definitions, and extensions
NativeRequest
The Native
object defines the native advertising opportunity
available for bid through this bid request. It must be included directly in the
impression object if the impression offered for auction is a native ad format.
Attribute | Always passed | Type | Authorized Buyers equivalent | Implementation details |
---|---|---|---|---|
ver |
Yes | string | "1.2" for OpenRTB 2.5. | 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 | NativeAdTemplate.native_placement_type | The design/format/layout of the ad unit being offered. |
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 objects |
Supported in NativeAdTemplate object.
The OpenRTB assets field maps to the AdX proto Google AdX proto conveys the same message through the The information in the |
Any bid must comply with the array of elements expressed by the Exchange. REQUIRED by the OpenRTB Native specification: at least 1 element. |
aurlsupport
|
No | bool
|
Supported. | Whether the supply source / impression supports returning an assetsurl instead of an asset object. 0 or the absence of the field indicates no such support. Implemented in 1.2 |
durlsupport
|
No | bool
|
Supported. | Whether the supply source / impression supports returning a DCO URL instead of an asset object. 0 or the absence of the field indicates no such support. Implemented in 1.2. Beta feature. |
eventtrackers
|
No | EventTrackers
|
OpenRTB version 1.2 supports IMPRESSION and IMG tracking. If OMSDK is enabled for Native, then JS is supported |
Specifies what type of event tracking is supported. Implemented in 1.2 |
privacy
|
No | bool
|
Not supported | Set to 1 when the native ad supports buyer-specific privacy notice. Set to 0 (or field absent) when the native ad doesn't support custom privacy links or if support is unknown. RECOMMENDED and implemented in 1.2. All native requests that we send support a privacy url, so this is implicitly always "1" for native requests. |
ext |
No | NativeRequestExt object |
Supported | For OpenRTB/Protobuf, you can access this object with the
[com.google.doubleclick.native_ext] extension key
(exact path varies based on language used to generate proto library). For
OpenRTB/JSON, you access with the ext field in the
NativeRequest message.
|
NativeRequestExt
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 | enum LayoutType | BidRequest.AdSlot. native_ad_template[0] .style_layout_type |
Enum LayoutType: PIXEL = 0; (Default) FLUID = 1; |
Asset
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 | Always passed | Type | Authorized Buyers 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 | RequestTitle | BidRequest.AdSlot.native_ad_template[0] of type HEADLINE | Title object for title assets.
RECOMMENDED by the OpenRTB Native specification. One of |
img
|
No | RequestImage | 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 |
video
|
No | Video | BidRequest.AdSlot.NativeAdTemplate.required_fields | 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. Bid requests can indicate that video is required in the
NativeResponse by setting NativeRequest.assets[].required to
true and specifying a NativeRequest.assets[].video .
RECOMMENDED by the OpenRTB Native specification. One of
Title , Image , Data ,
Video .
|
data
|
No | Data | BidRequest.AdSlot.native_ad_template[0] of types
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
The Title
object is to be used for title element of the
Native ad.
Attribute | Always passed | Type | Authorized Buyers 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
The Image
object is to be used for image elements of the
Native ad.
Attribute | Always passed | Type | Authorized Buyers 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_height LOGO/LOGO: logo_height ICON/APP_ICON: app_icon_height | 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.
|
mimes
|
No | string | Not supportedAllowlist of content MIME types supported. Popular MIME types include, but are not limited to "image/jpg" and "image/gif". Each implementing Exchange should have its own list of supported types in the integration docs. See Wikipedia's MIME page for more information and links to all IETF RFCs. If blank, assume all types are allowed. |
Video
The Video
object is to be used for video elements of the
Native ad.
Attribute | Always passed | Type | Authorized Buyers equivalent | Implementation details |
---|---|---|---|---|
mimes |
Yes | Array of string | BidRequest |
Content MIME types supported. Popular MIME types include
but are not limited to "video/x-mswmv" for Windows Media, and
"video/x-flv" for Flash Video, or "video/mp4". Note that native
frequently does not support flash.
REQUIRED by the OpenRTB Native specification: at least 1 element. |
minduration |
Yes | int32 | BidRequest |
Minimum video ad duration in seconds.
REQUIRED by the OpenRTB Native specification. |
maxduration |
Yes | int32 | BidRequest |
Maximum video ad duration in seconds.
REQUIRED by the OpenRTB Native specification. |
protocols |
Yes | Array of Protocol enum |
BidRequest |
An array of video protocols the publisher can accept in the bid response.
REQUIRED by the OpenRTB Native specification: at least 1 element. Examples: |
Data
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 | Always passed | Type | Authorized Buyers 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 |
Maximum length of the text in the element's response.
Note: not used for RATING/STAR_RATING, AdX needs a double 0..5 |
EventTrackers
The EventTrackers object specifies the type of events the bidder can request to be tracked in the bid response, and which types of tracking are available for each event type, and is included as an array in the request.Attribute | Always passed | Type | Authorized Buyers equivalent | Implementation details |
---|---|---|---|---|
event
|
Yes | EventType | Not supported | Type of event available for tracking. REQUIRED by the OpenRTB Native specification. |
methods
|
Yes | EventTrackingMethod | Not supported | Array of types of tracking available for the given event. REQUIRED by the OpenRTB Native specification. |
NativeResponse
The native response object is the top-level JSON object that identifies a native response.
Attribute | Always passed | Type | Authorized Buyers 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.
|
eventtrackers
|
No | Array of EventTracker objects
|
BidResponse.Ad.impression_tracking_url and BidResponse.Ad.impression_tracking_resource | Array of response event trackers to run with the ad, in response to the declared supported methods in the NativeRequest. Replaces imptrackers and jstrackers. Implemented in 1.2. |
EventTracker
The event trackers response is an array of objects and specifies the types of events the bidder wants to track and the URLs/information to track them. Bidder must only respond with methods indicated as available in the request. Note that most JavaScript trackers expect to be loaded at impression time, so it’s not generally recommended that the buyer respond with JavaScript trackers on other events, but the appropriateness of this is up to each buyer.
Attribute | Always passed | Type | Authorized Buyers equivalent | Implementation details |
---|---|---|---|---|
event
|
Yes | integer | Not supported | Type of event to track. |
method
|
Yes | integer | Not supported | Type of tracking requested. |
url
|
No | text | BidResponse.Ad. |
The URL of the image or js. Required for image or js, optional for custom. |
customdata
|
No | Object containing key:value pairs. | Not supported | To be agreed individually with the exchange, an array of key:value objects for custom tracking; for example, the account number of the DSP with a tracking company; for example, {"accountnumber":"123"}. |
ext |
No | EventTrackerExt object |
Not supported | For OpenRTB/Protobuf, you can access this object with the
[com.google.doubleclick.eventtrackers] extension key
(exact path varies based on language used to generate proto library). For
OpenRTB/JSON, you access with the ext field in the
EventTracker message.
|
EventTrackerExt
Attribute | Always passed | Type | Authorized Buyers equivalent | Implementation details |
---|---|---|---|---|
context |
No | Array of enum Context | BidResponse.Ad. |
Additional context provided for rendering. UNKNOWN = 0; OMID = 1; Currently not supported. |
verification_parameters |
No | string | BidResponse.Ad. |
Parameters associated with the resource that will be passed to the resource when it is loaded. The format of the parameters is dependent on the script vendor. |
vendor_key |
No | string | BidResponse.Ad. |
Used to uniquely identify the verification script provider. |
Link
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 | Always passed | Type | Authorized Buyers equivalent | Implementation details |
---|---|---|---|---|
url
|
No | string | BidResponse.ad[].native_ad.click_link_url | 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. Multiple clicktrackers are allowed. |
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
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 | Always passed | Type | Authorized Buyers 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| |
One of Title , Image , Data , Video
|
video
|
No | Video | BidResponse.Ad.NativeAd.video_url or BidResponse.Ad.NativeAd.video_vast_xml |
Can be either a string containing VAST XML or a URL to a VAST document
through the
|
data
|
No | Data | BidResponse.Ad.native_ad[0] / BODY|CALL_TO_ACTION| |
One of Title , Image , Data , Video .
|
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
Corresponds to the Title
object in the request, with the
value filled in.
Attribute | Always passed | Type | Authorized Buyers 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
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 | Always passed | Type | Authorized Buyers 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
Corresponds to the Video
object in the request, yet
containing a value of a conforming VAST tag as a value.
Attribute | Always passed | Type | Authorized Buyers equivalent | Implementation details |
---|---|---|---|---|
vasttag
|
Yes | string | Not supported | VAST xml. REQUIRED by the OpenRTB Native specification. |
Data
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 | Always passed | Type | Authorized Buyers 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) |
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. |