Authorized Buyers Real-time Bidding Proto

This guide describes each field in the Authorized Buyers Real-time Bidding proto v.322, along with additional implementation tips and information.

Also refer to the Authorized Buyers RTB proto file upon which this guide is based.

BidRequest object

This is the message that Google uses to request bids. A BidRequest includes the ad slot from a single impression.

This section lists information that we know about the user.

Information about the web page or mobile application where the impression originates.
Attribute Required/Optional Type Implementation details
id required bytes Unique request ID generated by Google. This is 16 bytes long.
ip optional bytes The first 3 bytes of the IP address in network byte order for IPv4, or the first 6 bytes for IPv6. Note that the number and position of the bytes included from IPv6 addresses may change later.
user_data_treatment repeated enum When user_data_treatment is set, the user's cookie/id data is cleared from the request and is not sent in callout. The impacted fields are:
  • google_user_id
  • hosted_match_data
  • mobile.encrypted_advertising_id
  • mobile.encrypted_hashed_idfa
  • session_id

TAG_FOR_CHILD_DIRECTED_TREATMENT = 0 - The current request should be treated as child-directed for purposes of the Children's Online Privacy Protection Act. See this article for more information.

google_user_id optional string The Google ID for the user as described in the documentation for the cookie matching service. This field is the unpadded web-safe base64-encoded version of a binary cookie ID. Refer to the Base 64 Encoding with URL and Filename Safe Alphabet section in RFC 3548 for encoding details. This field is the same as the Google ID returned by the cookie matching service.
cookie_version optional int32 The version number of the google_user_id. We may sometimes change the mapping from cookie to google_user_id. In this case the version will be incremented.
cookie_age_seconds optional int32 The time in seconds since the google_user_id was created. This number may be quantized.
hosted_match_data optional bytes Match data stored for this google_user_id through the cookie matching service. If a match exists, then this field holds the decoded data that was passed in the google_hm parameter.
session_id optional string 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.
user_agent optional string A string that identifies the browser and type of device that sent the request. Certain data may be redacted or replaced.
privacy_treatments optional PrivacyTreatments 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.
user_agent_data optional UserAgent User Agent information.
publisher_country optional string The billing address country of the publisher. This may be different from the detected country of the user in geo_criteria_id or the hosting country of the website. For a complete list of country codes, refer to the country codes list documentation.
host_publisher_id optional string 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.
inventorypartnerdomain optional string The domain of the partner (of the site or app owner) with ownership of some portion of ad inventory on the site or 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
geo_criteria_id optional int32 Location of the end user. Uses a subset of the codes used in the Google Ads API. See the geo-table.csv table in the technical documentation for a list of IDs. The geo_criteria_id field replaces the deprecated country, region, city, and metro fields.
geo optional Geo The user's approximate geographic location. All location information is IP geolocation-derived. The lat/lon fields may be a reference position (for example, centroid) for the IP geolocation-derived location that's also carried by the other fields (for example, a city), and accuracy will be the radius of a circle with the approximate area of that location. Location and its accuracy will be fuzzified as necessary to protect user privacy.
postal_code
postal_code_prefix
optional string Detected postal code of the appropriate type for the country of the end user (for example, zip code if the country is "US"). The postal_code_prefix field is set when accuracy is too low to imply a full code, otherwise the postal_code field is set.
encrypted_hyperlocal_set optional bytes Encrypted hyperlocal targeting signals.
hyperlocal_set optional HyperlocalSet Unencrypted version of encrypted_hyperlocal_set. This field is only set when using an SSL connection.
timezone_offset optional int32 The offset of the user's time from GMT in minutes. For example, GMT+10 is timezone_offset = 600.
user_list repeated UserList
publisher_id optional string The publisher ID as defined by the publisher code suffix of the web property code. For instance, "pub-123" is the publisher code of web property code "ca-pub-123" (ca- is the product-specific prefix of the web property).
seller_network_id optional int32 The seller network ID. Refer to the seller-network-ids.txt file in the technical documentation for a list of IDs. This is only set if the site is not anonymous and the publisher allows site targeting.
partner_id optional fixed64 ID for the partner that provides this inventory. This is only set when seller_network_id is also set and further partner information beyond the seller_network_id is also available. The value of the partner_id is not meaningful beyond providing a stable identifier.
url optional string The URL of the page with parameters removed. This always starts with a protocol (either http or https).
is_semi_transparent_request optional bool 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.
detected_language repeated string Detected user languages, based on the language of the web page, the browser settings, and other signals. The order is arbitrary. The codes are 2 or 5 characters and are documented in the language codes table.
detected_vertical repeated Vertical Note: Values for this field are now redacted. Unordered list of detected content verticals. Refer to the publisher-verticals.txt file in the technical documentation for a list of IDs.
detected_content_label repeated int32 Note: Values for this field are now redacted. List of detected content labels. Refer to the content-labels.txt file in the technical documentation for a list of IDs.
production_quality optional enum The production quality of the content where an ad can be shown, as determined by the publisher. Default = QUALITY_UNKNOWN.

QUALITY_UNKNOWN = 0
PROFESSIONAL = 1
; Content that is usually created or produced by media and entertainment companies using professional-grade equipment, talent, and production crews that hold or maintain the rights for distribution and syndication.
PROSUMER = 2; Consumer or user-generated content that has professional or industrial qualities (e.g. shot with professional-grade equipment, using professional talent, etc.).
USER_GENERATED = 3; Publicly available video content that is created or produced by end users.

content_rating optional enum The rating of the content where an ad can be shown. Default = RATING_UNKNOWN.

RATING_UNKNOWN = 0
GENERAL_AUDIENCES = 1
; Content suitable for general audiences.
PARENTAL_GUIDANCE = 2; Content suitable for most audiences with parental guidance.
TEEN = 3; Content suitable for teen and older audiences.
MATURE_AUDIENCES = 4; Content suitable only for mature audiences.

google_query_id optional string 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.
auction_type optional enum The type of auction that will be run for this query. Default = SECOND_PRICE.

UNKNOWN_AUCTION_TYPE = 0
FIRST_PRICE = 1
SECOND_PRICE = 2
FIXED_PRICE = 3

device optional Device
key_value repeated KeyValue
mobile optional Mobile
video optional Video
publisher_settings_list_id optional fixed64 The publisher settings list ID that applies to this page. Refer to the RTB Publisher Settings guide for details.
publisher_type optional enum Publisher type of the inventory where the ad will be shown. For a given request, publisher inventory can be either owned and operated (O&O), represented by the publisher, or of unknown status. Default = UNKNOWN_PUBLISHER_TYPE.

UNKNOWN_PUBLISHER_TYPE = 0
PUBLISHER_OWNED_AND_OPERATED = 1
PUBLISHER_REPRESENTED = 2

page_visibility optional enum The visibility state of the web page containing the ad slots. 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.

adslot repeated AdSlot
bid_response_feedback repeated BidResponseFeedback
response_deadline_ms optional int32 States how long Google will wait for a response, in milliseconds, for this particular bid request. If unset, bidders should assume that the default deadline is used.
is_test optional bool If true, then this is a test request. Results will not be displayed to users and you will not be billed for a response even if it wins the auction. You should still do regular processing since the request may be used to evaluate latencies or for other testing. During your initial testing with Google traffic any response that you make will be filtered out of the auction whether this option has a value of true or false.
is_ping optional bool If true, then this request is intended to measure network latency. Return an empty BidResponse with only processing_time_ms set as quickly as possible without executing any bidding logic.
is_predicted_to_be_ignored optional bool If true, then the callout model predicted that you will not bid on this request. We send a sampled percentage of such requests so that we can automatically update the model when bidding patterns change.
supply_chain optional SupplyChain
segment_data optional SegmentData Data segments for Publisher Provided Signals.
dsa optional Dsa The Digital Services Act (DSA) transparency information requirements. See Help Center link.

UserAgent object

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 Required/Optional Type Implementation details
browser optional BrandVersion Identifies the browser.
platform optional BrandVersion Identifies the platform.
mobile optional bool 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 optional string Device architecture, for example, "x86" or "arm".
bitness optional string Device's bitness, for example, "64" for 64-bit architecture.
model optional string Device model.

PrivacyTreatments Object

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.

Parent
Attribute Required/optional Type Implementation details
non_personalized_ads_reason optional NonPersonalizedAdsReason enum

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 BidRequest.device.limit_ad_tracking and BidRequest.device.app_tracking_authorization_status fields for more information.

UNKNOWN = 0; Reason unknown.

PUBLISHER_DECLARED_NPA = 1; The publisher has declared that this request should serve non-personalized ads independent of other signals.

RESTRICT_DATA_PROCESSING= 2; The publisher has requested restricted data processing for this request.

USER_OPT_OUT = 3; The user has opted out of ads personalization.

device_storage_restriction_reason optional DeviceStorageRestrictionReason enum

Indicates the reason why access of local device storage during winning ad rendering and measurement is restricted. See Limited ads requests for additional details.

DEVICE_STORAGE_RESTRICTION_UNKNOWN = 0; Reason unknown.

INSUFFICIENT_USER_CONSENT = 1; This request is subject to user consent requirements to allow for device storage access for advertising use cases such as ads measurement, frequency capping, or profiling, but consent was insufficient or not provided.

allow_user_data_collection optional bool 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.

BrandVersion object

Parent

A tuple of (brand, version) for the browser or platform.

Attribute Required/Optional Type Implementation details
brand optional string Brand identifier, for example, "Chrome" or "Windows".
version repeated string Version, split in components if needed, for example, {"85", "1"} = v85.1.

Geo object

The user's approximate geographic location. All location information is IP geolocation-derived. The lat/lon fields may be a reference position (for example, centroid) for the IP geolocation-derived location that's also carried by the other fields (for example, a city), and accuracy will be the radius of a circle with the approximate area of that location. Location and its accuracy will be fuzzified as necessary to protect user privacy.

Attribute Required/Optional Type Implementation details
lat optional double
lon optional double Longitude from -180.0 to +180.0, where negative is west.
country optional string Country using ISO-3166-1 Alpha-3.
region optional string Region code using ISO-3166-2; 2-letter state code if USA.
metro optional string Google metro code; similar to but not exactly Nielsen DMAs.
city optional string City using United Nations Code for Trade & Transport Locations. Click on a country from the countries list to see city codes.
zip optional string Zip/postal code.
accuracy optional int32 Estimated location accuracy in meters.
utcoffset optional int32 Local time as the number +/- of minutes from UTC.

HyperlocalSet object

Attribute Required/Optional Type Implementation details
hyperlocal repeated Hyperlocal This field currently contains at most one hyperlocal polygon.
center_point optional Hyperlocal.Point The approximate geometric center of a geofence area. It is calculated exclusively based on the geometric shape of the geofence area and in no way indicates the mobile device's actual location within the geofence area. If multiple hyperlocal polygons are specified above then center_point is the geometric center of all hyperlocal polygons.

Hyperlocal object

Parent

Coarse geolocation information approximated based on the IP address of the device the ad request originated from.

Attribute Required/Optional Type Implementation details
corners repeated Point The device can be at any point inside the geofence polygon defined by a list of corners. Currently, the polygon is always a parallelogram with 4 corners.
Point object
Parent

A location on the Earth's surface.

Attribute Required/Optional Type Implementation details
latitude optional float Latitude of the location.
longitude optional float Longitude of the location.

UserList object

This field is not populated by default. We recommend that bidders instead store and look up list IDs using either google_user_id or hosted_match_data as keys.

Attribute Required/Optional Type Implementation details
id optional int64 The user list ID.
age_seconds optional int32 The time in seconds since the user was added to the list.

Vertical object

One or more detected verticals for the page as determined by Google.

Attribute Required/Optional Type Implementation details
id required int32 The vertical ID. Refer to the publisher-verticals.txt file in the technical documentation for a list of IDs.
weight required float Weight for this vertical, in the (0.0, 1.0] range. More relevant verticals have higher weights.

Device object

Information about the device.

Attribute Required/Optional Type Implementation details
device_type optional enum The type of device on which the ad will be shown. Default = UNKNOWN_DEVICE.

UNKNOWN_DEVICE = 0
HIGHEND_PHONE = 1
TABLET = 2
PERSONAL_COMPUTER = 3
- Desktop or laptop devices.
CONNECTED_TV = 4 - Both connected TVs (smart TVs) and connected devices (such as Roku and Apple TV).
GAME_CONSOLE = 5

platform optional string The platform of the device. Examples: Android, iPhone, Palm.
brand optional string The brand of the device (for example, "Apple" or "Samsung").
model optional string 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_version optional OsVersion The OS version; for example, 2 for Android 2.1, or 3.3 for iOS 3.3.1.
carrier_id optional int64 Unique identifier for the mobile carrier if the device is connected to the internet through a carrier (as opposed to through WiFi). To look up carrier name and country from carrier ID, refer to this mobile carriers table.
screen_width optional int32 The width of the device screen in pixels.
screen_height optional int32 The height of the device screen in pixels.
screen_pixel_ratio_millis optional int32 Used for high-density devices (for example, iOS retina displays). A non-default value indicates that the nominal screen size (with pixels as the unit) does not describe the actual number of pixels in the screen. For example, nominal width and height may be 320x640 for a screen that actually has 640x1280 pixels, in which case screen_width=320, screen_height=640, and screen_pixel_ratio_millis=2000, since each axis has twice as many pixels as its dimensions would indicate.

Default = 0.

screen_orientation optional enum The screen orientation of the device when the ad request is sent. Default = UNKNOWN_ORIENTATION.

UNKNOWN_ORIENTATION = 0
PORTRAIT = 1
LANDSCAPE = 2

hardware_version optional string 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.
limit_ad_tracking optional bool "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.

app_tracking_authorization_status optional enum This field is only populated for iOS devices. Indicates the app tracking authorization status. This value is retrieved from ATTrackingManager and provided as is. For more information about iOS's app tracking authorization status, see this article.

NOT_DETERMINED = 0
RESTRICTED = 1
DENIED = 2
AUTHORIZED = 3

connection_type optional enum The type of network to which the user's device is connected. For 5G conection type, we send CELL_4G instead of CELL_5G. Default = CONNECTION_UNKNOWN.

CONNECTION_UNKNOWN = 0
ETHERNET = 1
WIFI = 2
CELL_UNKNOWN = 3
CELL_2G = 4
CELL_3G = 5
CELL_4G = 6
CELL_5G = 7

OsVersion object

Parent

Contains the OS version of the platform. For instance, for Android 2, major=2, minor=0. For iPhone 3.3.1, major=3 and minor=3.

Attribute Required/Optional Type
major
minor
micro
optional int32

KeyValue object

Additional key-value attributes. Currently unused.

Attribute Required/Optional Type
key
value
optional string

Mobile object

Information for ad queries coming from mobile devices. A mobile device is either a smart phone or a tablet. This is present for ad queries both from mobile devices browsing the web and from mobile apps.

Attribute Required/Optional Type Implementation details
is_app optional bool If true, then this request is from a mobile application. For branded requests, app_id will also be filled in. If the request is from a mobile web page contained inside an app, is_app will still be false, but app_id could be filled in with the app identifier. For SDK-less requests (mostly from connected TVs), this will be true if an app ID is provided directly in the request.
app_id optional string The identifier of the mobile app when this ad query comes from a mobile app. If the app was downloaded from the Apple iTunes app store, then this is the app-store ID; for example, 343200656. For Android devices, this is the fully qualified package name; for example, com.rovio.angrybirds. For Windows devices it's the App ID; for example, f15abcde-f6gh-47i0-j3k8-37l93817mn3o.
is_interstitial_request optional bool If true, then this is a mobile full screen ad request.
app_category_ids repeated int32 Note: Values for this field are now redacted. This field contains the IDs of categories to which the current mobile app belongs. This field will be empty if is_app is false. The mapping between mobile apps and categories is defined by the Google Play Store for Android apps, or the Apple iTunes Store for iOS apps. To look up category name from category ID, refer to the mobile app categories table.
is_mobile_web_optimized optional bool For a mobile web request, this field indicates whether the page is optimized for mobile browsers on high-end mobile phones. Default = false.
is_app_open_ad optional bool Indicates whether a mobile app bid request is for an app open ad. See App open ad guidance for more information.
encrypted_advertising_id optional bytes This field is used for advertising identifiers for:
  1. iOS devices (This is called Identifier for Advertising, or IDFA, as described in this Help Center article.)
  2. Android devices.
  3. Roku devices.
  4. Microsoft Xbox devices.
  5. Amazon devices.

When the encrypted_advertising_id is an IDFA, the plaintext after decrypting the ciphertext is the IDFA (16-byte UUID) returned by iOS's [ASIdentifierManager advertisingIdentifier]. For encrypted_hashed_idfa, the plaintext is the 16-byte MD5 hash of the IDFA. Only one of the two fields will be available, depending on the version of the SDK making the request. Later SDKs provide unhashed values.

encrypted_hashed_idfa optional bytes Also refer to the description for encrypted_advertising_id.
advertising_id optional bytes Unencrypted version of encrypted_advertising_id. This field is only set when using an SSL connection. This field is a 16-byte UUID.
hashed_idfa optional bytes Unencrypted version of encrypted_hashed_idfa. This field is only set when using an SSL connection. This field is a 16-byte MD5.
app_name optional string App names for Android apps are from the Google Play store. App names for iOS apps are provided by App Annie.
app_rating optional float Average user rating for the app. The range of user rating is between 1.0 and 5.0. Currently only available for apps in Google Play store.
installed_sdk optional InstalledSdk 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.
skadn optional SKAdNetworkRequest 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 this article.

InstalledSdk object

Parent

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.

Attribute Required/Optional Type Implementation details
id optional string Identifier for the installed SDK.
sdk_version optional Version The version of the installed SDK.
adapter_version optional Version The version of the adapter that communicates with the installed SDK.
Version object
Parent

Semantic version of the installed SDK and the adapter that communicates between the installed SDK and Google's SDK.

Attribute Required/Optional Type Implementation details
major optional int32 Default = -1
minor optional int32 Default = -1
micro optional int32 Default = -1

SKAdNetworkRequest object

Parent

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 this article.

Attribute Required/Optional Type Implementation details
versions repeated string List of all SKAdNetwork versions supported by the request, depending on the OS version and the SDK version.
sourceapp optional string ID of publisher app in Apple's App Store.
skadnetids repeated string SKAdNetworkIdentifier entries in the publisher app's Info.plist.
supported_fidelity_types repeated enum List of fidelity types supported, depending on the SKAdNetwork API version supported by the operating system and SDK as well as ad slot properties.

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.

skoverlay optional bool Indicates if this request supports SKOverlay for video ads.

Video object

Information about the video if this is an in-video ad request.

Attribute Required/Optional Type Implementation details
placement optional enum 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-
Describes where the video ad will play. Default = UNKNOWN_PLACEMENT.

UNKNOWN_PLACEMENT = 0.
INSTREAM = 1 - Instream means the ad plays before, during, or after other video content. This is similar to a traditional TV commercial. The video content the user is watching does not play while the ad is playing.
INTERSTITIAL = 2 - Interstitial means the video ad plays in front of non-video content, (for example, a news article or video game). The ad covers all or nearly all of the space on the screen occupied by the content and the user is not able to proceed to the content until the ad has finished or been skipped.
IN_FEED = 3 - The in-feed video format is a video creative that shows within a feed of content, typically a social app feed, a list of editorial content items, etc, as the user is scrolling. It renders centered and not to the side.
AUDIO = 4 - Audio is a request for an ad that is an audio stream. It is distinct from INSTREAM above as that is exclusive to video requests.
IN_ARTICLE = 5 - The in-article video format is a video creative that loads and plays between paragraphs of editorial content as a standalone video player.

plcmt optional enum Video placement type for the impression. Default = PLCMT_UNKNOWN.

PLCMT_UNKNOWN = 0.
PLCMT_INSTREAM = 1 - Pre-roll, mid-roll, and post-roll ads that are played before, during or after the streaming video content that the consumer has requested. Instream video must be set to “sound on” by default at player start, or have explicitly clear user intent to watch the video content. While there may be other content surrounding the player, the video content must be the focus of the user’s visit. It should remain the primary content on the page and the only video player in-view capable of audio when playing. If the player converts to floating/sticky, subsequent ad calls should accurately convey the updated player size.
PLCMT_ACCOMPANYING_CONTENT = 2 - Pre-roll, mid-roll, and post-roll ads that are played before, during, or after streaming video content. The video player loads and plays before, between, or after paragraphs of text or graphical content, and starts playing only when it enters the viewport. Accompanying content should only start playback upon entering the viewport. It may convert to a floating/sticky player as it scrolls off the page.
PLCMT_INTERSTITIAL = 3 - Video ads that are played without video content. During playback, it must be the primary focus of the page and take up the majority of the viewport and cannot be scrolled out of view. This can be in placements like in-app video or slideshows.
PLCMT_NO_CONTENT_STANDALONE = 4 - Video ads that are played without streaming video content. This can be in placements like slideshows, native feeds, in-content or sticky/floating.

description_url optional string The URL of the page that the publisher gives Google to describe the video content, with parameters removed.
is_embedded_offsite optional bool If true, the video is embedded on a page outside the publisher's domain. When this is set, description_url points to a description of the video (as it always does), and the url field in BidRequest is the page in which the video is embedded. For example, a request for an in-stream ad in a Vimeo video shared on Facebook has is_embedded_offsite set. The url field is for a Facebook page and the description_url points to the video on Vimeo.
playback_method optional enum Describes how the video ad will be played. The playback method is determined to be auto-play, click-to-play or mouse-over based on the best measurement available. This includes things like how recently the user interacted with a web page. For auto-play, ads can start playing with the sound on or off. Some ads (for example, in-feed ads) are muted until the user interacts with the ad.

Alternatively, if an ad would normally play with the sound on but the device is muted then the value will be set to sound off. For devices where it is not possible to determine if the device is muted (for example, desktop), we assume that sound is on. Default = METHOD_UNKNOWN.

METHOD_UNKNOWN = 0
AUTO_PLAY_SOUND_ON = 1
AUTO_PLAY_SOUND_OFF = 2
CLICK_TO_PLAY = 3
MOUSE_OVER = 4
INITIATE_ON_ENTERING_VIEWPORT_SOUND_ON = 5
INITIATE_ON_ENTERING_VIEWPORT_SOUND_OFF = 6

is_clickable optional bool Whether the inventory allows clicking on the video ad to take the user to an advertiser site. Some platforms, notably connected TVs, do not support clicking on video ads, in which case this field is set to false.
videoad_start_delay optional int32 The time in milliseconds from the start of the video when the ad will be displayed. 0 means pre-roll, -1 (or any negative 32-bit int) means post-roll, and 1 (or a positive 32-bit int) means mid-roll. The value is valid only if this param is set. When not set, the display position is unknown.
max_ad_duration optional int32 The maximum duration in milliseconds of the ad that you should return. If this is not set or has value <= 0, any duration is allowed.
min_ad_duration optional int32 The minimum duration in milliseconds of the ad that you should return. If this is not set or has value <= 0, there is no minimum duration.
max_ads_in_pod optional int32 The maximum number of ads in a video pod. A non-zero value indicates that the current ad slot is a video pod that can show multiple video ads. Actual number of video ads shown can be less than or equal to this value but cannot exceed it.
max_pod_duration_seconds optional int32 The maximum duration of a pod in seconds.
video_ad_skippable optional enum Does the publisher allow/require/block skippable video ads? Default = ALLOW_SKIPPABLE.

ALLOW_SKIPPABLE = 0
REQUIRE_SKIPPABLE = 1
BLOCK_SKIPPABLE = 2

skippable_max_ad_duration optional int32 The maximum duration in milliseconds for the ad you should return, if this ad is skippable (this generally differs from the maximum duration allowed for non-skippable ads). If this is not set or has value <= 0, any duration is allowed.
protocols repeated enum Array of supported video bid response protocols. Supported video protocols.

VAST_1_0 = 1
VAST_2_0 = 2
VAST_3_0 = 3
VAST_1_0_WRAPPER = 4
VAST_2_0_WRAPPER = 5
VAST_3_0_WRAPPER = 6
VAST_4_0 = 7
VAST_4_0_WRAPPER = 8
DAAST_1_0 = 9
DAAST_1_0_WRAPPER = 10

allowed_video_formats repeated enum The video file formats that are allowed for this request. The response should support at least one of them.

UNKNOWN_VIDEO_FORMAT = -1;
// Flash video files are accepted (FLV).
VIDEO_FLV = 0;
VIDEO_MP4 = 1;
// Valid VAST ads with at least one media file
// hosted on youtube.com.
YT_HOSTED = 2;
// Flash VPAID (SWF).
VPAID_FLASH = 3;
// JavaScript VPAID.
VPAID_JS = 4;
AUDIO_MP3 = 5;
AUDIO_OGG = 6;
// Requires both MP3 & OGG as Google does not know
// which codecs are installed on the player.
AUDIO_MP3_OGG = 7;
VIDEO_WEBM = 8;
VIDEO_MOV = 9;
VIDEO_3GPP = 10;
VIDEO_HLS = 11;
VIDEO_DASH = 12;
// Audio version of MP4.
AUDIO_MP4A = 13;

companion_slot repeated CompanionSlot Information about the companion ad slots that can be shown with the video. While this is a repeated field there will only be one value in most cases. If there are no companion ads available this field will not be set.
end_cap_support optional enum End cap support. When enabled, the companion ad can be picked to be rendered as an end cap (info card) in the video slot after the video ad finishes playing. If multiple companion ads are returned, IMA SDK chooses one which best matches the device screen size. End cap is supported only on mobile video interstitial inventory. As of August 2015, END_CAP_FORBIDDEN and END_CAP_REQUIRED are not supported.

END_CAP_NOT_ENABLED = 0; - Companion ad won't be rendered as end cap.
END_CAP_OPTIONAL = 1; - End cap will be rendered if response contains eligible companion banner, but companion banner is not required.
END_CAP_FORBIDDEN = 2; - Response with companion ad is filtered.
END_CAP_REQUIRED = 3; - Response without companion ad is filtered.

content_attributes optional ContentAttributes Attributes of the video that the user is viewing, not the video ad. These fields are based on the availability of the video metadata from the video publisher and may not always be populated.
DEPRECATED_inventory_type optional enum The type of inventory from which request is sent. Deprecated but will continue to be filled in until January 2017. Use the placement field to determine if inventory is interstitial or instream. Use Device.device_type to determine if the request comes from a mobile device and Mobile.is_app to determine if the request comes from an app. WEB_VIDEO is INSTREAM placements from web browsers. GAMES consists of INTERSTITIAL placements from both apps and web browsers. MOBILE_INTERSTITIAL is INTERSTITIAL placements from apps only. This inventory also allows display ads. You can tell if an adslot allows display ads if adslot.excluded_attributes does not contain 21 (CreativeType: Html)

MOBILE_APP_VIDEO is INSTREAM placement from apps only.

WEB_VIDEO = 0
GAMES = 1
MOBILE_INTERSTITIAL = 2
MOBILE_APP_VIDEO = 3

is_livestream optional bool Identify whether or not the ad request is being served from a live video stream (0 = is not live, 1 = is live). Default = false.
feed_type optional enum Type of audio content feed where an audio ad can be played. Default = FEED_TYPE_UNKNOWN.

FEED_TYPE_UNKNOWN = 0
MUSIC_SERVICE = 1
; Music streaming service.
FM_AM_BROADCAST = 2; Live content broadcast over the air but also available through online streaming.
PODCAST = 3; Original, pre-recorded content distributed as episodes in a series.

delivery_method repeated enum Supported delivery methods for the video or audio content where an ad can be shown.

CONTENT_DELIVERY_METHOD_UNKNOWN = 0
STREAMING = 1
; Content is transferred continuously by the network; clients receive real-time content for playback while connected. Example: broadcast TV.
PROGRESSIVE = 2; Content is transferred incrementally as client's playback requires. Example: on-demand movies, podcasts, or music.
DOWNLOAD = 3; Content should be transferred completely prior to use/playback. Example: content downloaded to the user's device for offline consumption.

CompanionSlot object

Parent

Information about the companion ad slots that can be shown with the video. While this is a repeated field there will only be one value in most cases. If there are no companion ads available this field will not be set. It is not shown if the user skips the video. Refer to the Video Ads guide for more information.

Attribute Required/Optional Type Implementation details
height repeated int32 These fields represent the available heights and widths in this slot. There will always be the same number heights and widths fields.
width repeated int32 These fields represent the available heights and widths in this slot. There will always be the same number heights and widths fields.
creative_format repeated enum These are the formats of the creatives allowed in this companion ad slot.

IMAGE_CREATIVE = 0
FLASH_CREATIVE = 1
HTML_CREATIVE = 2

ContentAttributes object

Parent

Attributes of the video that the user is viewing, not the video ad.

These fields are based on the availability of the video metadata from the video publisher and may not always be populated.

Attribute Required/Optional Type Implementation details
duration_seconds optional int32 The duration of the video, in seconds.

AdSlot object

Information about the adslots on the page.

Attribute Required/Optional Type Implementation details
id required int32 An arbitrarily assigned slot ID that is unique on a given page and usually starts counting from 1. You use this to identify which slot to bid on in the BidResponse.
ad_block_key optional uint64 A stable identifier for the combination of publisher, ad slot, and page.
targetable_channel repeated string Set of channels of which this ad slot is a member. A channel is a set of ad slots on a site. You can target a channel (like "the sports section", or "all top banners") to get more fine-grained control over where your ad shows. Channel names are provided by the publisher.
width
height
repeated int32 For mobile interstitial ads (including those where video ads are eligible), the first width, height pair is the screen size (this is also the video player size for VAST video ads). Subsequent pairs represent recommended interstitial ad sizes that satisfy the interstitial size restrictions; for example, no bigger than the screen size and no smaller than 50% of width and 40% of the height.
flexible_adslot_settings optional FlexibleAdSlotSettings If the adslot is flexible, this contains settings on how the slot may be resized.
excluded_attribute repeated int32 The disallowed attribute IDs for the ads that can show in this slot. Refer to the publisher-excludable-creative-attributes.txt file in the technical documentation for a list of IDs.
allowed_vendor_type repeated int32 The allowed vendor types. Refer to the vendors.txt file in the technical documentation for a list of IDs. This field does not apply to deals with block overrides (refer to this Help Center article).
consented_providers_settings optional ConsentedProvidersSettings Information about the providers for whom the publisher has told Google that its EEA users have consented to the use of their personal data for ads personalization. This field will only be populated when regs_gdpr is true.
regs_gdpr optional bool Authorized Buyers fills this field solely based on whether the impression will serve to an EEA user, based on information available to Google. It does not constitute legal guidance on GDPR.
regs_lgpd optional bool 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.

gpp_consent_string optional string Contains the Global Privacy Platform's consent string. See IAB-GPP spec for details.
gpp_section_ids repeated int32 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.
excluded_sensitive_category repeated int32 The disallowed sensitive ad categories. Refer to the ad-sensitive-categories.txt file in the technical documentation for a list of IDs. You should enforce these exclusions if you have the ability to classify ads into the listed categories. This field does not apply to deals with block overrides (this Help Center article has more information).
allowed_restricted_category repeated int32 The allowed restricted ad categories for private and open auctions. Refer to the ad-restricted-categories.txt file in the technical documentation for a list of IDs. These only apply for private and open auction bids. Refer to the allowed_restricted_category_for_deals field for preferred deals or programmatic guarantees.
allowed_restricted_category_for_deals repeated int32 The allowed restricted ad categories for preferred deals or programmatic guarantees. The ad-restricted-categories.txt file in the technical documentation has a list of IDs. These only apply for preferred deals or programmatic guarantees. Refer to the allowed_restricted_category field for private and open auctions. In some cases, restricted categories are only allowed on preferred deals or programmatic guarantees, so this field lists all categories in allowed_restricted_category, and additionally, restricted categories that are only allowed for preferred deals or programmatic guarantees.
allowed_languages repeated string List of creative languages allowed by the publisher. The order is arbitrary. The codes are 2 or 5 characters and are documented in the language codes table. When not set, all languages are allowed.
excluded_product_category repeated int32 The disallowed ad product categories. Refer to the ad-product-categories.txt file in the technical documentation for a list of IDs. You should enforce these exclusions if you have the ability to classify ads into the listed categories. This field does not apply to deals with block overrides (as in this Help Center article).
excluded_creatives repeated ExcludedCreative 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.
only_deal_bids_accepted optional bool Whether the adslot is only eligible for deals bids. Bids for the open auction will be filtered when this field is set to true. Bidders can bid on the open auction or deals when this field is set to false.
matching_ad_data repeated MatchingAdData Information about the pre-targeting configs that matched.
exchange_bidding optional ExchangeBidding Parameters related to exchange bidding (third-party exchanges doing real-time bidding on Google Ad Manager). This is never populated in calls to Authorized Buyers real-time bidders.
open_bidding optional OpenBidding Parameters sent in all Open Bidding requests.
ad_unit_mapping optional AdUnitMapping Ad unit mappings that match the given adslot.
dfp_ad_unit_code optional string The Ad Manager ad unit code. This is currently only set for Open Bidding requests.
slot_visibility optional enum Visibility information for the slot. Default = NO_DETECTION.

NO_DETECTION = 0
ABOVE_THE_FOLD = 1
BELOW_THE_FOLD = 2

viewability optional int32 Viewability percentage for the ad slot. This is an estimate of the likelihood that this slot will be viewable by the end user based on historical and environment data. It is expressed as a percentage in the range of [0, 100]. The default value -1 indicates that viewability could not be estimated.
click_through_rate optional float Historical click-through rate for ads served in the ad slot. This is expressed as a fraction in the range [0.0, 1.0]. The default value of -1.0 indicates that historical click-through rate data is not available. This figure does not include data aggregated from Google Ads. The click-through rate can vary for a given ad slot throughout the day.
video_completion_rate optional float Historical completion rate for video ads served in the ad slot. This is expressed as a fraction in the range [0.0, 1.0]. The default value of -1.0 indicates that historical completion rate data is not available. This field is only applicable to video inventory, and does not include data aggregated from Google Ads.
iframing_state optional enum iFraming state of the ad slot on the webpage where it is present. Default = UNKNOWN_IFRAME_STATE.

UNKNOWN_IFRAME_STATE = 0
NO_IFRAME = 1
SAME_DOMAIN_IFRAME = 2
CROSS_DOMAIN_IFRAME = 3

iframing_depth optional enum iFrame depth of the ad slot on the webpage where it is present. Currently only set for video ad requests. Default = UNKNOWN_IFRAME_DEPTH.

UNKNOWN_IFRAME_DEPTH = 0
NOT_IN_IFRAME = 1
ONE_IFRAME = 2
MULTIPLE_IFRAME = 3

native_ad_template repeated NativeAdTemplate A native ad consists of pieces that are rendered by the publisher. A publisher may support multiple distinct native ad templates. If the request also allows banners or videos, you can respond with other types of ads by setting html_snippet or video_url instead. If only native templates exist, you must set the native_ad field in any response you send.
native_placement_type optional enum Describes placement of native ad slot with respect to surrounding context.

PLACEMENT_UNKNOWN = 0
PLACEMENT_IN_FEED = 1
- In the feed of content, for example as an item inside the organic feed/grid/listing/carousel.
PLACEMENT_ATOMIC_UNIT = 2 - In the atomic unit of the content for example, in the article page or single image page.
PLACEMENT_OUTSIDE = 3 - Outside the core content, for example in the ads section on the right rail, as a banner-style placement near the content, etc.
PLACEMENT_RECOMMENDATION = 4 - Recommendation widget, most commonly presented below the article content.

mediation_status optional enum Whether the ad request has been determined to come directly from the publisher. Default = UNKNOWN.

UNKNOWN = 0
DIRECT_REQUEST = 1

auto_refresh optional AutoRefresh
sticky_settings optional StickySettings
non_browser_slot_source optional enum Publisher declaration stating that this ad slot may serve on non-browser inventory, like desktop apps. Default = UNDECLARED_SOURCE.

UNDECLARED_SOURCE = 0
DESKTOP_APP = 1

renderer optional enum Defines who controls the environment that made the ad request and will render the ad. On platforms where code written by Google will handle the ad this field is set to GOOGLE. When this field is PUBLISHER the publisher has placed their own code on the device to handle playback of the ad. There is no technical difference in how these request are handled. You may use this field to differentiate between different environments for non-technical reasons. This field is only set for requests that allow VAST video ads.

UNKNOWN_RENDERER = 0
GOOGLE = 1
PUBLISHER = 2

amp_ad_request_type optional enum Whether this request is for an Accelerated Mobile Page (AMP). AMP HTML pages load faster, by restricting parts of HTML, CSS and JavaScript. For more information on how AMP ads render, refer to the AMP ads README. Default = NON_AMP_PAGE.

UNKNOWN_AMP = 0 - AMP status unknown. Request may or may not be from an AMP page.
NON_AMP_PAGE = 1 - Not an AMP page. Could be regular HTML, VAST video, etc.
AMP_PAGE_LATE_REQUEST = 2 - Late-loading request from an AMP HTML page. Ad will render with a slight delay so it will not negatively impact page render performance.

is_amp_page optional enum Whether this is an AMP page or not.

UNKNOWN_AMP_PAGE = 0 - AMP page status unknown.
DIALECT_HTML = 1 - This is not an AMP page.
DIALECT_HTML_AMP = 2 - This is an Amp page.

amp_ad_requirement_type optional enum Possible requirement types for AMP ads.

UNKNOWN_AMP_AD_REQUIREMENT_TYPE = 0 - AMP ad requirements unknown.
AMP_AD_NOT_ALLOWED = 1 - AMP ads are not allowed.
AMP_AD_ALLOWED_AND_NOT_EARLY_RENDERED = 2 - Either AMP ads or non-AMP ads are allowed; AMP ads are not early rendered.
AMP_AD_ALLOWED_AND_EARLY_RENDERED = 3 - Either AMP ads or non-AMP ads are allowed; AMP ads are early rendered.
AMP_AD_REQUIRED = 4 - AMP ads are required. Ads that are non-AMP may be rejected by the publisher.

is_rewarded optional bool 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.
allowed_ad_types repeated enum Possible ad types that are allowed in the bid response. allowed_ad_types always contains one or more values. Interstitial slots may also support banner ads. An ad slot with ALLOWED_AD_TYPE_NATIVE may or may not support native video, regardless of whether ALLOWED_AD_TYPE_VIDEO is set. Likewise, an ad slot without ALLOWED_AD_TYPE_NATIVE does not support native video, regardless of whether ALLOWED_AD_TYPE_VIDEO is set.

UNKNOWN_ALLOWED_AD_TYPE = -1
ALLOWED_AD_TYPE_BANNER = 0
ALLOWED_AD_TYPE_NATIVE = 1
ALLOWED_AD_TYPE_VIDEO = 2
ALLOWED_AD_TYPE_AUDIO = 3

session_depth optional int32 Total number of impressions served to this user (within this specific site or app) in this browsing session, plus 1. A session ends after 30 minutes inactivity. The default value of -1 indicates that the session depth cannot be estimated.
publisher_settings_list_id repeated fixed64 The publisher settings list IDs that apply to this slot. Refer to the RTB Publisher Settings guide for details.
secure_signals repeated SecureSignal Secure signals passed by the publisher.
api repeated enum List of supported API frameworks for this impression. If an API is not explicitly listed, it is assumed not to be supported. Can be one of the following:

UNKNOWN_FRAMEWORK = 0
MRAID_1 = 3
Mobile Rich Media Ad Interface Definitions Version 1.0.
MRAID_2 = 5 Mobile Rich Media Ad Interface Definitions Version 2.0.
MRAID_3 = 6 Mobile Rich Media Ad Interface Definitions Version 3.0.
OMID_1 = 7 Open Measurement Interface Definition Version 1.0.

billable_event_rate_adjustment optional double 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 repeated BillableEventRateBidAdjustment 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.
omidpn optional string Identifier of the OM SDK integration. For more info, see the OpenRTB Advisory for Open Measurement SDK.
omidpv optional string Version of the OM SDK integration. For more info, see the OpenRTB Advisory for Open Measurement SDK.
impression_expiration_seconds optional int32 The expected time period when an impression can occur in seconds following a winning bid. The impression may be billable only if it serves within this time. To learn more about impression expiration, see the following guide: https://developers.google.com/authorized-buyers/rtb/billing-event-guide
frequency_capping_scope required FrequencyCappingScope enum

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 BidResponse.ad.adslot.frequency_cap field.

FREQUENCY_CAPPING_SCOPE_UNKNOWN = 0; Default value which should not be used, or which can indicate that frequency cap scope could not be reliably determined.

FREQUENCY_CAPPING_SCOPE_NONE = 1; Frequency capping based on bid response specifications is not available for this request. A frequency-capped bid for a bid request with no frequency cap availability will be filtered prior to the auction.

FREQUENCY_CAPPING_SCOPE_BROWSER = 2; Frequency capping enforcement is available across multiple sites within the same browser.

FREQUENCY_CAPPING_SCOPE_DEVICE = 3; Frequency capping enforcement is available across multiple sites on the device, excluding browsers.

FREQUENCY_CAPPING_SCOPE_APP = 4; Frequency capping enforcement is available within a single app.

FREQUENCY_CAPPING_SCOPE_SITE = 5; Frequency capping enforcement is available within a single site.

excluded_app_ids repeated string 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.
supported_auction_environment optional AuctionEnvironment enum 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.
display_manager optional string The name of the rendering environment, such as a mobile ads or video SDK, or a publisher ad tag type. This field describes a Google SDK while the installed_sdk field describes third party SDKs.

Example strings:
GoogleMobileAds-iOS
GoogleMobileAds-Android
InteractiveMediaAds-iOS
InteractiveMediaAds-Android

display_manager_version optional string Version of the rendering environment specified by the display_manager field. This field describes a Google SDK while the installed_sdk field describes third party SDKs.

FlexibleAdSlotSettings object

Parent

Settings on how the slot may be resized.

Attribute Required/Optional Type
max_width optional int32
max_height optional int32
min_width optional int32
min_height optional int32

ConsentedProvidersSettings object

Parent

Information about the providers for whom the publisher has told Google that its EEA users have consented to the use of their personal data for ads personalization. This field will only be populated when regs_gdpr is true.

Attribute Required/Optional Type Implementation details
consented_providers repeated int64 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 ConsentedProvidersSettings.tcf_consent_string field.

A mapping of ATP ID to ATP name is posted at providers.csv.

tcf_consent_string optional string 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.

ExcludedCreative object

Parent

A creative that is disallowed to bid on this impression due to Google policies or creative disapproval, excluded creative attributes, excluded product or sensitive categories, allowed vendor types, restricted categories or languages applicable to the bid request.

Attribute Required/Optional Type Implementation details
buyer_creative_id optional string Buyer creative ID of the disallowed creative.

MatchingAdData object

Parent

The billing IDs corresponding to the pretargeting configs that matched.

Attribute Required/Optional Type Implementation details
billing_id repeated int64 The billing IDs corresponding to the pretargeting configs that matched.
minimum_cpm_micros optional int64 The minimum CPM value that you can bid to not be filtered before the auction. This may be a global minimum, or it may be a minimum set by the publisher. The value is in micros of your account currency.
direct_deal repeated DirectDeal
DirectDeal object
Parent

Information about any deals that matched for this inventory.

Attribute Required/Optional Type Implementation details
direct_deal_id optional int64 An ID identifying the deal.
fixed_cpm_micros optional int64 You must bid at least fixed_cpm_micros (in micros of your account currency) in order to participate in the deal. If you win, you will be charged fixed_cpm_micros. This does not apply when deal_type=PRIVATE_AUCTION. For private auctions, you must bid at least fixed_cpm_micros. Bidding higher CPM than fixed_cpm_micros will increase your chance to win when deal_type=PRIVATE_AUCTION, however it will not increase your chance to win in other types of deals.
deal_type optional enum The type of the deal. Default = UNKNOWN_DEAL_TYPE.

UNKNOWN_DEAL_TYPE = 0
PREFERRED_DEAL = 1
PRIVATE_AUCTION = 2
PROGRAMMATIC_GUARANTEED = 3
- Refer to the RTB differences for Programmatic Guaranteed Deals help center article for more information.
AUCTION_PACKAGE = 4 - Refer to the Auction Packages help center article for more information.
MARKETPLACE_PACKAGE = 5 - The deal ID for publisher curated inventory packages. Refer to the Marketplace Packages help center article for more information.

publisher_blocks_overridden optional bool Whether the publisher has exempted this deal from configured blocks. This setting does not override Authorized Buyers policies or Ad Review Center decisions.
creative_source optional enum 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 (Default).

CREATIVE_SOURCE_UNKNOWN = 0
CREATIVE_SOURCE_ADVERTISER = 1
- 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.

must_bid optional bool 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.
creative_constraints optional CreativeConstraints Creative constraints for this deal. If this is not set, bidders should refer to the BidRequest-level setting of each field.
CreativeConstraints object
Parent

Information about creative constraints of a direct deal.

Attribute Required/Optional Type Implementation details
allowed_ad_types repeated enum 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 BidRequest-level creative types in adslot.allowed_ad_types. The possible values this field may contain are

ALLOWED_AD_TYPE_BANNER = 0
ALLOWED_AD_TYPE_NATIVE = 1
ALLOWED_AD_TYPE_VIDEO = 2
ALLOWED_AD_TYPE_AUDIO = 3

video_ad_skippable optional enum Whether skippable creatives are allowed. For PROGRAMMATIC_GUARANTEED or PREFERRED_DEAL deals that specifically allow video or audio ad types, it is always set. For the skippability setting of other deal types or open auction bidding, refer to the corresponding BidRequest-level field video.video_ad_skippable. The possible values are

ALLOW_SKIPPABLE = 0
REQUIRE_SKIPPABLE = 1
BLOCK_SKIPPABLE = 2

max_ad_duration_ms optional int32 The maximum allowed duration in milliseconds for the ad. 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.max_ad_duration.

ExchangeBidding object

Parent

Parameters related to exchanges participating in Open Bidding (third party exchanges doing real-time bidding on Ad Manager). This is never populated in calls to Authorized Buyers real-time bidders.

Attribute Required/Optional Type Implementation details
publisher_parameter repeated string UTF8 strings optionally provided by the publisher as part of their matching yield group configurations in the Ad Manager UI. The format is arbitrary and should be agreed upon by the publisher and the exchange bidder.
key_value repeated KeyValue Repeated KeyValue pairs to be sent from the publisher to the exchange.

OpenBidding object

Parent

Parameters sent in all Open Bidding requests.

Attribute Required/Optional Type Implementation details
is_open_bidding optional bool 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 object

Parent

AdUnitMapping is used to identify publisher inventory units in the bidder's namespace. The mappings are only populated when the bidder works directly with a publisher, and provides the mapping from Google's ad unit namespace to the bidder's inventory namespace. The ad unit mapping is only applicable for requests that use a custom SDK. https://support.google.com/admanager/answer/9601810.

Attribute Required/Optional Type Implementation details
Keyval Optional Keyval Key-value pair used to specify the inventory unit in the bidder's namespace.
FormatType Optional enum Possible ad unit formats that can be used for the mapping. Corresponds to the adapter that will be used on the SDK.

Possible values:

  • FORMAT_UNKNOWN = 0;
  • Display banner ads for web or mobile apps. For example, a 320x50 leaderboard slot. This includes out-stream video.

    FORMAT_BANNER = 1;

  • A full-screen ad to be displayed inside a mobile app.

    FORMAT_INTERSTITIAL = 2;

  • Custom display or video ads for web or mobile apps that match the user experience of the site or app in which they’re placed.

    FORMAT_NATIVE = 3;

  • Video ads that appear before, during, or after video content streams.

    FORMAT_VIDEO_VAST = 4;

  • Video ads for mobile apps that allow users to voluntarily watch an ad in exchange for an in-app reward.

    FORMAT_REWARDED = 5;

  • Interstitial ads that allow users to watch an ad in exchange for an in-app reward. Does not require opt-in. https://support.google.com/admanager/answer/7386053

    FORMAT_REWARDED_INTERSTITIAL = 6;

  • App open ads shows at app load screens. App open ads can be closed at any time, and are designed to be shown when the users bring the app to the foreground.

    FORMAT_APP_OPEN = 7;

Keyval object
Parent

Multiple 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.ad.sdk_rendered_ad.sdk_params. This is passed to the bidder's SDK.

Attribute Required/Optional Type Implementation details
key Optional string The key is the name of the bidder's inventory unit identifier for the SDK.
value Optional string The value of the bidder's inventory unit identifier for the given format.

NativeAdTemplate object

Parent

A native ad consists of pieces that are rendered by the publisher. A publisher may support multiple distinct native ad templates. If the request also allows banners or videos, you can respond with other types of ads by setting html_snippet, video_url, or video_vast_xml instead. If only native templates exist, you must set the native_ad field in any response you send.

Attribute Required/Optional Type Implementation details
required_fields optional int64 Bitfield describing which fields are required by the publisher. Bid responses with no value for these fields will be rejected. Click and view tracking urls are always implicitly required.

enum Fields - Defines the bits used in required_fields and recommended_fields. There is one bit for each of the fields in BidResponse.Ad.NativeAd.

HEADLINE = 0x1
BODY = 0x2
CALL_TO_ACTION = 0x4
ADVERTISER = 0x8
IMAGE = 0x10
LOGO = 0x20
APP_ICON = 0x40
STAR_RATING = 0x80
PRICE = 0x100
STORE = 0x200
VIDEO = 0x400

recommended_fields optional int64 Bitfield describing which fields are recommended by the publisher. All recommended fields are supported, but not all recommended fields are required.

enum Fields - Defines the bits used in required_fields and recommended_fields. There is one bit for each of the fields in BidResponse.Ad.NativeAd.

HEADLINE = 0x1
BODY = 0x2
CALL_TO_ACTION = 0x4
ADVERTISER = 0x8
IMAGE = 0x10
LOGO = 0x20
APP_ICON = 0x40
STAR_RATING = 0x80
PRICE = 0x100
STORE = 0x200
VIDEO = 0x400

headline_max_safe_length
body_max_safe_length
call_to_action_max_safe_length
advertiser_max_safe_length
price_max_safe_length
optional int32 max_safe_length indicates the maximum number of Unicode characters that are guaranteed to be shown without truncation. Longer strings will be truncated by the publisher during rendering.
image_width
image_height
logo_width
logo_height
app_icon_width
app_icon_height
optional int32 The width and height from which to calculate the required aspect ratio. You can provide a larger image in the response. Images that have aspect ratios substantially different than those implied by the height and width may be filtered.
style_id optional int32 Globally distinct ID for the specific style, HTML, and CSS with which the native ad is rendered.
style_layout_type optional enum Type of style layout for each native ad template. Default = PIXEL.

PIXEL = 0
FLUID = 1

style_height
style_width
optional int32 If the style_layout_type is PIXEL, width and height of the entire native ad after rendering. If the style_layout_type is FLUID, the style_height and style_width may optionally not be populated.

AutoRefresh object

Parent

Auto refresh settings.

Attribute Required/Optional Type Implementation details
refresh_settings repeated AutoRefreshSettings The auto-refresh settings that the publisher has on this inventory. This is repeated because publishers may do multiple types of auto refresh on one piece of inventory.
refresh_count optional int32 The number of times this ad slot had been refreshed since last page load.
AutoRefreshSettings object
Parent
Attribute Required/Optional Type Implementation details
refresh_type optional enum The type of the declared auto refresh. Default = UNKNOWN_AUTO_REFRESH_TYPE.

UNKNOWN_AUTO_REFRESH_TYPE = 0
USER_ACTION = 1
- Refresh triggered by user-initiated action such as scrolling.
EVENT = 2 - Event-driven content change. For example, ads refresh when the football game score changes on the page.
TIME = 3 - Time-based refresh. Ads refresh on a predefined time interval even without user activity.

min_refresh_interval_seconds optional int32 The minimum refresh interval. This applies to all refresh types.

StickySettings object

Parent

Stickiness settings declared by the publisher.

Attribute Required/Optional Type Implementation details
vertical_stickiness optional enum Whether the ad slot is a sidebar that sticks on screen when user scrolls. Default = UNKNOWN_STICKINESS.

UNKNOWN_STICKINESS = 0
IS_STICKY = 1

top_horizontal_stickiness optional enum Whether the ad slot is a horizontal slot that sticks on the top of the screen when the user scrolls. Default = UNKNOWN_STICKINESS.

UNKNOWN_STICKINESS = 0
IS_STICKY = 1

bottom_horizontal_stickiness optional enum Whether the ad slot is a horizontal slot that sticks on the bottom of the screen when the user scrolls. Default = UNKNOWN_STICKINESS.

UNKNOWN_STICKINESS = 0
IS_STICKY = 1

SecureSignal object

Parent

Secure signals passed by the publisher.

Attribute Required/Optional Type Implementation Details
data optional string The secure signal.
source optional string The source of the signal. Identifier for the library or SDK that generated this data.

BillableEventRateBidAdjustment object

Parent

The billable event rate bid adjustment of an ad and the dependent features of the ad the adjustment applies to, such as the format or the SDK used to render the ad. Each feature combination may have a unique adjustment, each adjustment therefore specifies which SDK or creative format it applies to.

Attribute Required/Optional Type Implementation Details
bid_adjustment optional float 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 optional enum

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. Default = CREATIVE_TYPE_UNKNOWN.

CREATIVE_TYPE_UNKNOWN = 0
HTML_SNIPPET = 1 - Banner ads
VIDEO_VAST = 2 - VAST video or audio ads
NATIVE = 3 - Native ads
SDK_RENDERED = 4 - SDK rendered ad

sdk optional InstalledSdk 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.

BidResponseFeedback object

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 Required/Optional Type Implementation details
request_id optional bytes The unique ID from BidRequest.id
creative_index optional int32 The index of the BidResponse_Ad if there was more than one. The index starts at zero for the first creative.
creative_status_code optional int32 The status code for the ad. Refer to creative-status-codes.txt in the technical documentation for a list of IDs.
cpm_micros optional int64 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 1st price auctions, BidRequest.bid_response_feedback[].minimum_bid_to_win is also populated.
minimum_bid_to_win optional int64 The minimum bid value necessary to have won the auction, in micros of 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.
server_side_component_minimum_bid_to_win optional int64 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 micros 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 BidResponseFeedback object.
billable_event_rate_bid_adjustment optional double 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 optional int64 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 micros of your account currency.
event_notification_token optional bytes Event notification token that was included in the bid response.
buyer_creative_id optional string Buyer creative ID that was included in the bid response.

SupplyChain object

SupplyChain object. For more information, see this article.

Attribute Required/Optional Type Implementation details
complete optional bool 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.
nodes repeated SupplyChainNode 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.
version optional string 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 object

Parent
Attribute Required/Optional Type Implementation details
advertising_system_identifier optional string 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.
seller_identifier optional string The identifier associated with the seller or reseller account within the advertising system. This must contain the same value used in transactions, for example, "publisher_id" in Google protocol. Should be limited to 64 characters in length.
handles_payment optional bool Indicates whether this node will be involved in the flow of payment for the inventory. When set to true, the advertising system in the advertising_system_identifier field pays the seller in the seller_identifier field, who is responsible for paying the previous node in the chain. When set to false, this node is not involved in the flow of payment for the inventory.

SegmentData object

First party data segments that describe the content or audience. Each SegmentData object represents a different data source.

Attribute Required/Optional Type Implementation details
name optional string Exchange-specific name for the signal provider.
segment repeated Segment Segment objects.
type optional enum

The taxonomy in use for segment IDs. See AdCOM Taxonomies.

TAXONOMY_TYPE_UNKNOWN = 0
IAB_AUDIENCE_1_1 = 4
IAB_CONTENT_2_2 = 6
IAB_CONTENT_3_0 = 7

Segment object

Segment objects contain segment IDs that can be used with the taxonomy type to access first party data.

Parent
Attribute Required/Optional Type Implementation details
id repeated string ID of the data segment specific to the signal provider.

Dsa object

The Digital Services Act (DSA) transparency requirements. See Help Center article.

Attribute Required/Optional Type Implementation details
dsa_support optional enum This field is not populated by default. 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.

DSA_SUPPORT_UNKNOWN = 0
NOT_REQUIRED = 1 - DSA declarations are not required in the bid response.
SUPPORTED = 2 - DSA declarations are supported, but not required in the bid response.
REQUIRED = 3 - DSA declarations are required in the bid response.
REQUIRED_BY_ONLINE_PLATFORM = 4 - DSA declarations are required in the bid response and the publisher is an OP or VLOP.

publisher_rendering_support optional enum Options describing a publisher's ability to render DSA transparency declarations.

PUBLISHER_RENDERING_SUPPORT_UNKNOWN = 0
PUBLISHER_UNABLE_TO_RENDER = 1 - Publisher can't render.
PUBLISHER_CAN_RENDER = 2 - Publisher could render depending on the buyer's rendering capability as described in the BidResponse.ad.dsa_transparency.buyer_render field.
PUBLISHER_WILL_RENDER = 3 - Publisher will render regardless of the buyer's rendering capability as described in the BidResponse.ad.dsa_transparency.buyer_render field.

data_to_publisher optional enum Options describing if a publisher requires DSA transparency declarations.

DATA_TO_PUBLISHER_UNKNOWN = 0
DO_NOT_SEND = 1 - Do not send transparency data.
OPTIONAL = 2 - Optional to send transparency data.
SEND = 3 - Send transparency data.

BidResponse object

This is the message that you return in response to a BidRequest. You may specify zero or more ads. For each ad, you should provide an ad slot on which the ad can run. An ad slot is identified by the AdSlot.id from the BidRequest. If you do not want to bid, submit a response with no ads and with only the processing_time_ms set.

Attribute Required/Optional Type Implementation details
ad repeated Ad
debug_string optional string If is_test was set in the BidRequest, then you may return debug information as plain text in this field. Do not set this field under normal conditions, or set it to values longer than 100 characters. You should only use this field when asked to do so as part of troubleshooting particular problems.
processing_time_ms optional int32 Set this to the processing time in milliseconds from when you received the request to when you returned the response.
no_bid_reason optional int32 An optional, bidder-specified reason for not submitting a bid. This field is equivalent to BidResponse.nbr in the OpenRTB protocol and uses the same namespace of no-bid reason codes. See developers.google.com/authorized-buyers/rtb/downloads/no-bid-reasons.txt for the full set of no-bid reason codes.

Ad object

Attribute Required/Optional Type Implementation details
event_notification_token optional bytes The event notification token is sent to Authorized Buyers by bidders for troubleshooting. Authorized Buyers will include the token in real-time feedback for the bid. The content of the token will not be logged by Authorized Buyers. Authorized Buyers will ignore any token longer than 128 bytes.
buyer_creative_id optional string A unique identifier chosen by you for the creative in this response. This must always be set, must be limited to at most 64 bytes, and must be a valid UTF8 string. Every buyer_creative_id you use must always be associated with the same creative. This field is used to communicate approval statuses when issues are found. Do not specify the same ID for different creatives, or all creatives will be disapproved if a problem with a single creative is found. Do not specify different IDs for the same creative in different responses or no creatives will be served since approval status is assigned on a per-ID basis.
html_snippet optional string The HTML snippet that will be placed on the web page to display the ad. Use BidResponse.Ad.AdSlot.billing_id to indicate which billing ID this snippet is attributed to.
video_url optional string The URL to fetch a video ad. The URL should return an XML response that conforms to the VAST 2.0 or 3.0 standard. Use BidResponse.Ad.AdSlot.billing_id to indicate which billing ID to attribute this ad to. Only one of html_snippet, video_url, native_ad, sdk_rendered_ad, amp_ad_url, or video_vast_xml should be set. Only set this field if the BidRequest is for an in-video ad (BidRequest.video is present).
video_vast_xml optional string The VAST document to be returned. This document should conform to the VAST 2.0 or 3.0 standard. Use BidResponse.Ad.AdSlot.billing_id to indicate which billing ID to attribute this ad to. Only set this field if the BidRequest is for an in-video ad and the response is VAST XML. Only one of html_snippet, video_url, native_ad, sdk_rendered_ad, amp_ad_url, or video_vast_xml should be set.
amp_ad_url optional string The URL to fetch an AMPHTML ad. Only one of the following should be set: html_snippet, video_url, native_ad, sdk_rendered_ad, amp_ad_url, or video_vast_xml.
native_ad optional NativeAd The content of a native ad. Native ads consist of multiple building blocks, which are rendered by the publisher.
click_through_url repeated string The set of destination URLs for the snippet. This includes the URLs that the user will go to if they click on the displayed ad, and any URLs that are visible in the rendered ad. Do not include intermediate calls to the adserver that are unrelated to the final landing page. This data is used for post-filtering of publisher-blocked URLs among other things. A BidResponse that returns a snippet or video ad but declares no click_through_url will be discarded. For native ads, only the first value is used as the click URL, though all values are subject to categorization and review. Only set this field if html_snippet or video_url or native_ad are set. For native ads, if NativeAd.click_link_url is not set, the first value of click_through_url is used to direct the user to the landing page. For native ads, we recommend using click_link_url as the field to set the destination where the user will ultimately go. It is required to use this field in the case of dynamic landing pages.
vendor_type repeated int32 All vendor types for the ads that may be shown from this snippet. You should only declare vendor IDs listed in the vendors.txt file in the technical documentation. We will check to ensure that the vendors you declare are in the allowed_vendor_type list sent in the BidRequest.
attribute repeated int32 All attributes for the ads that may be shown from this snippet. Refer to buyer-declarable-creative-attributes.txt in the technical documentation for a list of IDs. We will check to ensure none of these attributes are in the excluded_attribute list in the BidRequest.
category repeated int32 All sensitive categories for the ads that may be shown from this snippet. Refer to ad-sensitive-categories.txt in the technical documentation for a list of IDs. We will check to ensure none of these categories were in the excluded_sensitive_category list in the BidRequest.
restricted_category repeated int32 All restricted categories for the ads that may be shown from this snippet. Refer to ad-restricted-categories.txt in the technical documentation for a list of IDs. We will check to ensure these categories were listed in the allowed_restricted_category list in the BidRequest.
advertiser_name repeated string All names of the ad's advertisers.
bidder_name optional string For exchange bidders (third party exchanges doing real-time bidding on Ad Manager), the name of the bidder that the exchange called to provide the ad. This is arbitrary UTF8 text but should be sufficient to identify the bidder and should be set consistently to the same value for the same bidder.
width
height
optional int32 The width and the height in pixels of the ad. Setting these is optional. However, these must be set if the bid BidRequest.AdSlot has more than one width and height or if BidRequest.Mobile.is_interstitial_request is true.
agency_id optional int64 Deprecated. This will be removed in November 2023. The Agency associated with this ad. Refer to the agencies.txt file in the technical documentation for a list of IDs. If this ad has no associated agency then the value NONE (agency_id: 1) should be used rather than leaving this field unset.
adslot repeated AdSlot
impression_tracking_url repeated string The URLs to call when the impression is rendered. This is supported for all inventory types and all formats.
click_tracking_url repeated string 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.
ad_choices_destination_url optional string Link to ad preferences page. This is only supported for native ads. If present, a standard AdChoices icon is added to the native creative and linked to this URL.
impression_tracking_resource repeated ImpressionTrackingResource Resources to invoke when the impression is rendered. This is supported for native and banner formats only and explicitly whitelisted scripts only.
sdk_rendered_ad optional SdkRenderedAd An ad that will be rendered by an SDK known to the buyer. This can only be used when the BidRequest includes a mobile.installed_sdk submessage.
skadn optional SKAdNetworkResponse 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.
advertised_app_id optional string ID of the advertised app (only for app promotion). On Android, this should be a bundle or package name such as com.foo.mygame. On iOS, it is a numeric ID. In addition to this field, set the app_promotion_type field below to take advantage of features specific to app promotion types.
app_promotion_type optional enum Type of the app promotion corresponding to the advertised app specified in the advertised_app_id field above. If the advertised app is not specified, this field will be ignored. Setting advertised_app_id field without this field will be treated as if this field were set to OTHER.
dsa_transparency optional DsaTransparency DSA Ad Transparency declarations. See Help Center link

NativeAd object

Parent

The content of a native ad. Native ads consist of multiple building blocks, which are rendered by the publisher. Only one of the following should be set: html_snippet, video_url, video_vast_xml, or native_ad. Only set this field if the BidRequest is for a native ad (BidRequest.adslot.native is present).

Attribute Required/Optional Type Implementation details
headline optional string A short title for the ad.
body optional string A long description of the ad.
call_to_action optional string A label for the button that the user is supposed to click.
advertiser optional string The name of the advertiser or sponsor, to be displayed in the ad creative.
image optional Image A large image.
logo optional Image A smaller image, for the advertiser's logo.
app_icon optional Image The app icon, for app download ads.
video_url optional string The URL to fetch a video ad. The URL should return an XML response that conforms to the VAST 2.0 standard. Only set this field if the BidRequest is for native ads and the video field is requested.
star_rating optional double The app rating in the app store. Must be in the range [0-5].
optional string The URL that the browser/SDK will load when the user clicks the ad. This can be the landing page directly, or the first step of a redirect chain that eventually leads to it. For backward compatibility, if this is not set, the first Ad.click_through_url is used. For native ads, we recommend using click_link_url instead of click_through_url.
click_tracking_url optional string Deprecated. The URL to use for click tracking. The SDK pings click tracking url on a background thread. When resolving the url, HTTP 30x redirects are followed. The SDK ignores the contents of the response; this URL has no effect on the landing page for the user.
price optional string The price of the promoted app including the currency info.
Image object
Parent
Attribute Required/Optional Type Implementation details
url optional string
width
height
optional int32 Image width and height are specified in pixels. You may provide a larger image than was requested, so long as the aspect ratio is preserved.

AdSlot object

Parent
Attribute Required/Optional Type Implementation details
id required int32 The slot ID from the BidRequest that the ad may appear in.
max_cpm_micros required int64 The maximum CPM you want to be charged if you win the auction for this ad slot, expressed in micros of the specified currency or default bidding currency. For example, to bid a CPM of 1.29 USD, set max_cpm_micros = 1290000. Winning bids are rounded up to billable units. For example, in USD, bids are rounded up to the next multiple of 10,000 micros (one cent).
min_cpm_micros optional int64 The minimum CPM you want to be charged if you win the auction for this ad slot, expressed in micros of the specified currency or default bidding currency. This may represent a second price if you choose max_cpm_micros as the highest of several bids, or some form of reserve price if you want to override the reserve price set by the publisher. The bid must be less than or equal to max_cpm_micros or it will be ignored. This field is optional and does not need to be set. This field is not applicable when responding to bid requests with auction_type set to FIRST_PRICE.
billing_id optional int64 Billing ID to attribute this impression to. The value must be in the set of billing IDs for this slot that were sent in the BidRequest.AdSlot.matching_ad_data.billing_id. This must always be set if the BidRequest has more than one BidRequest.AdSlot.matching_ad_data.billing_id.
deal_id optional int64 The deal ID that you want this bid to participate in. Leave unset or set it to "1" if a deal is available but you want to ignore the deal and participate in the open auction.
exchange_deal_id optional string For exchange bidders (third-party exchanges doing real-time bidding on Ad Manager), the deal ID from the exchange's namespace that is associated with this bid and reported to publishers. Leave unset if there is no associated deal. This is arbitrary UTF8 text and must be at most 64 bytes.
exchange_deal_type optional enum When exchange_deal_id is set, the type of deal. This is reported to publishers and affects how the deal is treated in the auction.

OPEN_AUCTION = 0
PRIVATE_AUCTION = 1
PREFERRED_DEAL = 2
EXCHANGE_AUCTION_PACKAGE = 3

buyer_reporting_id optional string 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.
third_party_buyer_token optional string Token used to identify end third party buyer information if an 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.
frequency_cap repeated FrequencyCap Experimental feature; may be subject to change. See github.com/google/ads-privacy/tree/master/experiments/frequency-capping for more information about the experiment on exchange-enforced frequency capping.

To enable frequency capping for your account, contact your account manager.

Specifies frequency capping to be applied to the bid. Impressions for each user are capped at the level specified by frequency_cap_id. A bid will not participate in the auction if an additional impression for the user would violate any of the specified caps. Multiple frequency caps can be specified for the same frequency_cap_id.

A bid is filtered before the auction if the frequency cap is malformed. Instances where the cap is malformed include:

  • frequency_cap_id is empty or is very long
  • max_mpressions or time_range are non-positive
  • there are a large number of frequency caps for a single bid
  • time_unit is not specified

    Note that if a subsequent bid with the same frequency_cap_id uses a different duration (represented by time_unit and time_range) then impressions counted against the old frequency cap will not count against the new one and the reverse.

  • position_in_pod optional enum

    Indicates that the bid is only eligible for a specific position within the pod.


    POD_POSITION_ANY = 0
    POD_POSITION_LAST = 1
    POD_POSITION_FIRST = 2
    POD_POSITION_FIRST_OR_LAST = 3
    bid_group_id optional string

    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. If an ad is submitted on multiple positional bids represented by AdSlot messages, each bid must have a different bid_group_id.

    currency optional string

    The currency used by max_cpm_micros and min_cpm_micros, 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:

    1. The bidder-level currency, if configured in RTB account settings.
    2. The buyer-level currency. The buyer will be determined by the billing ID specified in the billing_id field of the bid response if it is populated, otherwise it will be based on the sole billing ID sent in the bid request.

    The currency of a buyer account is set on account creation and can be checked by contacting a Technical Account Manager.

    FrequencyCap object
    Parent
    Attribute Required/Optional Type Implementation details
    frequency_cap_id optional string An ID that can represent a bidder's use-case for frequency capping; for example, it could represent their campaign, ad, line item, etc. It should not contain any user-specific information or identifiers.
    time_unit optional enum The time units for which frequency caps can be enforced.

    UNKNOWN_TIME_UNIT = 0
    MINUTE = 1
    DAY = 2
    WEEK = 3
    MONTH = 4
    INDEFINITE = 5
    : When INDEFINITE is used, time_range will be ignored. INDEFINITE means the frequency cap will be applied for a long period of time, (longer than a month) but not necessarily forever.

    time_range optional int32 The length of the time window, in units specified by time_unit, for which the frequency cap applies. For instance, if time_unit=WEEK and time_range=3, then capping is applied for a three week period. If the time_unit=INDEFINITE, this will be ignored.
    max_impressions optional int32 The maximum number of impressions allowed to be shown to a user for the provided frequency_cap_id within the time window described by time_unit and time_range.

    ImpressionTrackingResource object

    Parent
    Attribute Required/Optional Type Implementation details
    script_url optional string The URL of a JavaScript resource. The URLs should not contain script tags. For example: "https://mycdn.com/tracker.js".
    context repeated enum Additional context provided for rendering.

    UNKNOWN_CONTEXT = 0
    OMID = 1

    verification_parameters optional string 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 optional string Used to uniquely identify the verification script provider.

    SdkRenderedAd object

    Parent
    Attribute Required/Optional Type Implementation details
    id optional string The identifier for the SDK that will render the ad. Must match a mobile.installed_sdk.id sent in the corresponding bid request.
    rendering_data optional string Data to pass to the SDK in order to render the ad. This data is opaque to the publisher and to Google.
    declared_ad optional 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_ad.
    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_ad.

    Parent

    Attribute Required/optional Type Implementation details
    html_snippet optional string The HTML snippet representative of the SDK-rendered ad.
    video_url optional string The URL to the VAST asset used in the SDK-rendered ad.
    video_vast_xml optional string The VAST document used to render custom SDK-rendered ad. This document should conform to the VAST 2.0 or 3.0 standard.
    native_ad optional NativeAd The content of a native ad. Native ads consist of multiple building blocks, which are rendered by the buyer SDK.
    click_through_url optional string The final landing pages of the SDK-rendered ad.

    SKAdNetworkResponse object

    Parent
    Attribute Required/Optional Type Implementation details
    version optional string 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.mobile.skad.versions.
    network optional string Ad network identifier used in signature. This should match one of the items in BidRequest.mobile.skad.skadnetids.
    campaign optional int64 Campaign ID compatible with Apple's spec. Used in SKAdNetwork 3.0 and below. Replaced BidResponse.ad.skad.source_identifier field in SKAdNetwork 4.0 and above.
    source_identifier optional int64 A four-digit integer that ad networks define to represent the ad campaign. Used in SKAdNetwork 4.0+ and replaces the BidResponse.ad.skad.campaign field.
    itunesitem optional string ID of advertiser's app in Apple's app store.
    product_page_id optional string 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 repeated Fidelity 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 optional string 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.ad.skadn.fidelities.nonce field to support multiple fidelity types.
    sourceapp optional string ID of publisher's app in Apple's app store. This should match the ID from BidRequest.mobile.skad.sourceapp.
    timestamp optional int64 Unix time in millis used at the time of signature generation. Note: This field will be deprecated in favor of the BidResponse.ad.skadn.fidelities.timestamp field to support multiple fidelity types.
    signature optional string SKAdNetwork signature as specified by Apple. Note: This field will be deprecated in favor of the BidResponse.ad.skadn.fidelities.signature field to support multiple fidelity types.
    skoverlay optional SKOverlay object These options indicate how to present SKOverlay recommending the advertised app. Supported by iOS 14 and later.
    Fidelity object
    Parent

    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.

    Attribute Required/Optional Type Implementation details
    fidelity_type optional enum 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 optional string A unique all-lowercase UUID generated by the advertiser to use for generating the signature.
    timestamp optional int64 Unix time in millis used at the time of signature generation.
    signature optional string SKAdNetwork signature as specified by Apple.
    SKOverlay
    Parent
    Attribute Required/Optional Type Implementation details
    delay_seconds optional int32 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.
    endcard_delay_seconds optional int32 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 endcard_delay_seconds are set, the overlay will be automatically dismissed when the ad ends, and shown again after the endcard shows.
    dismissible optional bool Whether this overlay can be dismissed by the user. Default to be true.

    DsaTransparency object

    DSA Ad Transparency information provided by the buyer. See Help Center article.

    Attribute Required/Optional Type Implementation details
    displayed_on_behalf optional string 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.
    paying_entity optional string 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.
    buyer_render optional bool Indicates that the buyer will render their own DSA transparency information inside the creative.