Realtime Bidding Proto

This guide describes each field in the Real-Time Bidding proto v.131, along with additional implementation tips and information.

See the RTB proto file, which contains much of the same information as this guide in the code comments.

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.

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 UserDataTreatment Reasons for constrained usage treatment of user data (google_user_id, hosted_match_data, IDFA, etc).

When set, the user's cookie/id data allows only restricted usage and is not available in the usual fields. Instead the data may be accessed through the constrained usage fields and stricter usage policies apply. There may be multiple restrictions applicable at the same time. You must only use the data for use cases allowed by all restrictions. You will receive the user_data_treatment value in BidRequests if there are any applicable restrictions. However, you must be whitelisted in order to receive the constrained usage user data fields. See the User Data Treatments guide for more information.

The impacted fields are:

  • google_user_id: Use constrained_usage_google_user_id.
  • hosted_match_data: Use constrained_usage_hosted_match_data.
  • mobile.encrypted_advertising_id: Use mobile.constrained_usage_
    encrypted_advertising_id
    .
  • mobile.encrypted_hashed_idfa: Use mobile.constrained_usage_
    encrypted_hashed_idfa
    .

enum UserDataTreatment
The current request should be treated as child-directed for purposes of the Children's Online Privacy Protection Act. See this Help Center article for more information.

TAG_FOR_CHILD_DIRECTED_TREATMENT
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. See 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. Not set if there is one or more user_data_treatment value, see constrained_usage_google_user_id instead.
constrained_usage_
google_user_id
optional string Only set if there is one or more user_data_treatment value. If constrained_usage_google_user_id is set, then google_user_id is not set. You must be whitelisted for all user_data_treatments in this request in order to receive this field.
cookie_version optional uint32 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.

Not set if there is one or more user_data_treatment value, see constrained_usage_hosted_match_data instead.

constrained_usage_
hosted_match_data
optional bytes Only set if there is one or more user_data_treatment value. If constrained_usage_hosted_match_data is set, then hosted_match_data is not set. You must be whitelisted for all user_data_treatments in this request in order to receive this field.
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.
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, see the country codes list in the AdWords API documentation.
geo_criteria_id optional int32 Location of the end user. Uses a subset of the codes used in the AdWords 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.
postal_code
postal_code_prefix
optional string Detected postal code of the appropriate type for the country of the end user (e.g., 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 Hyperlocal targeting signal when available, encrypted as described in the Decrypt Hyperlocal Target Signals guide.
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_vertical repeated int32 List of detected user verticals. Currently unused.
user_list repeated UserList

This section lists information that we know about the web page or mobile application where the impression originates.

Attribute Required/Optional Type Implementation details
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. See 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 is only set if the site is not anonymous and the publisher allows site targeting. You can use anonymous_id for targeting if the inventory is anonymous. Otherwise, use detected_vertical. Only one of url or anonymous_id is ever set in the same request. This always starts with a protocol (either http or https).
anonymous_id optional string An id for the domain of the page. This is set when the inventory is anonymous. Only one of url or anonymous_id is ever set in the same request.
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 Unordered list of detected content verticals. See the publisher-verticals.txt file in the technical documentation for a list of IDs.
detected_content_label repeated int32 List of detected content labels. See the content-labels.txt file in the technical documentation for a list of IDs.
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. See the RTB Publisher Settings guide for details.
publisher_type optional PublisherType Publisher type of the inventory where the ad will be shown. For an AdX publisher, its inventory can be either owned and operated (O&O), represented by the publisher, or of unknown status. AdSense and AdMob inventory is represented by Google.

enum PublisherType
UNKNOWN_PUBLISHER_TYPE = 0;
ADX_PUBLISHER_OWNED_AND_OPERATED = 1;
ADX_PUBLISHER_REPRESENTED = 2;
GOOGLE_REPRESENTED = 3;
default = UNKNOWN_PUBLISHER_TYPE

adslot repeated AdSlot
bid_response_feedback repeated BidResponseFeedback

Testing flags:

Attribute Required/Optional Type Implementation details
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 flag has a value of true or false.
is_ping optional bool If true, then this request is intended to measure network latency. Please 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 selective 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.

Hyperlocal object

A hyperlocal targeting location when available.

Attribute Required/Optional Type Implementation details
corners repeated Point The mobile 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

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.

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 the 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.
encrypted_hyperlocal_set optional bytes Hyperlocal targeting signal when available, encrypted as described in this guide

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. See 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
DeviceType enum 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;
device_type optional DeviceType default = UNKNOWN_DEVICE
platform optional string The platform of the device. Examples: Android, iPhone, Palm
brand optional string The brand of the device, e.g., Nokia, Samsung.
model optional string The model of the device, e.g., N70, Galaxy.
os_version optional OsVersion The OS version; e.g., 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 via a carrier (as opposed to via 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 (e.g., 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 640x1080 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 ScreenOrientation The screen orientation of the device when the ad request is sent.

enum ScreenOrientation
UNKNOWN_ORIENTATION = 0;
PORTRAIT = 1;
LANDSCAPE = 2;
default = UNKNOWN_ORIENTATION

hardware_version optional string Apple iOS device model, e.g., "iphone 5s", "iphone 6+", "ipad 4".

OSVersion object

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 smartphone 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. Will always be true when app_id is set. May also be true for anonymous inventory, in which case anonymous_id will be set.
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, e.g., 343200656. For Android devices, this is the fully qualified package name, e.g., com.rovio.angrybirds. For Windows devices it's the App ID, e.g., 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 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

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.

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. They are not set if there is one or more user_data_treatment value in the BidRequest, see constrained_usage_encrypted_advertising_id and constrained_usage_encrypted_hashed_idfa instead.

encrypted_hashed_idfa optional bytes See also 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.
constrained_usage_
encrypted_advertising_id
optional bytes Only set if the BidRequest contains one or more user_data_treatment value. If constrained_usage_encrypted_advertising_id or constrained_usage_encrypted_hashed_idfa is set, then the corresponding non-constrained field is not set. You must be whitelisted for all user_data_treatments in this request in order to receive these fields.
constrained_usage_advertising_id optional bytes Unencrypted version of constrained_usage_encrypted_advertising_id. This field is only set when using an SSL connection. This field is a 16 byte UUID.
constrained_usage_
encrypted_hashed_idfa
optional bytes
constrained_usage_hashed_idfa optional bytes Unencrypted version of constrained_usage_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.

Video object

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

Attribute Required/Optional Type Implementation details
Placement enum 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, (e.g., 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 when the user is scrolling through a feed of content, typically a social app feed, a news article, etc. The video renders in the main feed and in the user's vision and reading flow, not to the side as e.g., for in-banner video.
placement optional placement Describes where the video ad will play.
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.
VideoPlaybackMethod 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 (e.g., 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 (e.g., desktop), we assume that sound is on.

METHOD_UNKNOWN = 0;
AUTO_PLAY_SOUND_ON = 1;
AUTO_PLAY_SOUND_OFF = 2;
CLICK_TO_PLAY = 3;
MOUSE_OVER = 4;

playback_method optional VideoPlaybackMethod default = METHOD_UNKNOWN
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 and -1 means post-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 an Adx 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.
video_ad_skippable optional SkippableBidRequestType Does the publisher allow/require/block skippable video ads?

enum SkippableBidRequestType
ALLOW_SKIPPABLE = 0;
REQUIRE_SKIPPABLE = 1;
BLOCK_SKIPPABLE = 2;
default = ALLOW_SKIPPABLE

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 VideoProtocol Array of supported video bid response protocols. Supported video protocols.

enum VideoProtocol
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 VideoFormat The video file formats that are allowed for this request. The response should support at least one of them.

enum VideoFormat
VIDEO_FLV = 0; - Flash video files are accepted (FLV).
VIDEO_MP4 = 1;
YT_HOSTED = 2; - Valid VAST ads with at least one media file hosted on youtube.com.
VPAID_FLASH = 3; - Flash VPAID (SWF).
VPAID_JS = 4; - JavaScript VPAID

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 EndCapSupport 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.

enum EndCapSupport
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 InventoryType 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.

enum InventoryType
WEB_VIDEO = 0;
GAMES = 1;
MOBILE_INTERSTITIAL = 2;
MOBILE_APP_VIDEO = 3;

CompanionSlot object

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. See 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 CreativeFormat These are the formats of the creatives allowed in this companion ad slot.

enum CreativeFormat
IMAGE_CREATIVE = 0;
FLASH_CREATIVE = 1;
HTML_CREATIVE= 2;

ContentAttributes object

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
title optional string The title of the video.
duration_seconds optional int32 The duration of the video, in seconds.
keywords repeated string A list of keywords describing the video, extracted from the content management system of the video publisher. There will be no more than 10 keywords in this list.

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 ones 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 are recommended interstitial ad sizes that satisfy the interstitial size restrictions, i.e., no bigger than the screen size and no smaller than 50% of width and 40% height.
excluded_attribute repeated int32 The disallowed attribute IDs for the ads that can show in this slot. See 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. See the vendors.txt file in the technical documentation for a list of IDs. When the seller_network is GDN, the vendor IDs listed in gdn-vendors.txt in the supporting technical documentation are also allowed. This field does not apply to deals with block overrides (see this Help Center article).
excluded_sensitive_category repeated int32 The disallowed sensitive ad categories. See 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 (see this Help Center article).
allowed_restricted_category repeated int32 The allowed restricted ad categories for private and open auctions. See the ad-restricted-categories.txt file in the technical documentation for a list of IDs. These only apply for private and open auction bids. See the allowed_restricted_category_for_deals field for preferred deals or programmatic guarantees. If you bid with an ad in a restricted category, you MUST ALWAYS declare the category in the bid response regardless of the values in this field.
allowed_restricted_
category_for_deals
repeated int32 The allowed restricted ad categories for preferred deals or programmatic guarantees. See the ad-restricted-categories.txt file in the technical documentation for a list of IDs. These only apply for preferred deals or programmatic guarantees. See 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. If you bid with an ad in a restricted category, you MUST ALWAYS declare the category in the bid response regardless of the values in this field.
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 at the language codes table. When not set, all languages are allowed.
excluded_product_category repeated int32 The disallowed ad product categories. See 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 (see this Help Center article).
matching_ad_data repeated MatchingAdData
exchange_bidding optional ExchangeBidding
dfp_ad_unit_code optional string The DFP ad unit code. This is currently only set for exchange bidding requests.
slot_visibility optional SlotVisibility Visibility information for the slot.

enum SlotVisibility
NO_DETECTION = 0;
ABOVE_THE_FOLD = 1;
BELOW_THE_FOLD = 2;
default = NO_DETECTION

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] and rounded down to the next multiple of 10. 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 AdWords.
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 AdWords.
iframing_state optional IFramingState iFraming state of the ad slot on the webpage where it is present.

enum IFramingState
UNKNOWN_IFRAME_STATE = 0;
NO_IFRAME = 1;
SAME_DOMAIN_IFRAME = 2;
CROSS_DOMAIN_IFRAME = 3;
default = UNKNOWN_IFRAME_STATE

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

enum IFramingDepth
UNKNOWN_IFRAME_DEPTH = 0;
NOT_IN_IFRAME = 1;
ONE_IFRAME = 2;
MULTIPLE_IFRAME = 3;
default = UNKNOWN_IFRAME_DEPTH

native_ad_template repeated NativeAdTemplate
mediation_status optional MediationStatus Whether the ad request has been determined to come directly from the publisher.

enum MediationStatus
UNKNOWN = 0;
DIRECT_REQUEST = 1;
default = UNKNOWN

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

default = UNDECLARED_SOURCE

is_interstitial_slot optional bool Publisher declaration stating that this ad slot will serve an interstitial ad. An interstitial ad covers the content for a period of time.
renderer optional Renderer 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.

enum Renderer:
UNKNOWN_RENDERER = 0;
GOOGLE = 1;
PUBLISHER = 2;

amp_ad_request_type optional AmpAdRequestType 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.

enum AmpAdRequestType:
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.
default = NON_AMP_PAGE

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 AllowedAdType 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.

enum AllowedAdType:
ALLOWED_AD_TYPE_BANNER = 0;
ALLOWED_AD_TYPE_NATIVE = 1;
ALLOWED_AD_TYPE_VIDEO = 2;

MatchingAdData object

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.
pricing_rule repeated BuyerPricingRule
direct_deal repeated DirectDeal

BuyerPricingRule object

Publisher open auction pricing rules applicable to a particular buyer.

Attribute Required/Optional Type Implementation details
included_advertisers
excluded_advertisers
repeated int64 Only one of the included_advertisers and excluded_advertisers fields can be set in a rule. See advertisers.txt file in the technical documentation for a list of IDs.
included_agencies
excluded_agencies
repeated int64 Only one of the included_agencies and excluded_agencies fields can be set in a rule. See agencies.txt file in the technical documentation for a list of IDs.
blocked optional bool Only one of the blocked and minimum_cpm_micros can be set in a rule. If set to true, indicates that the specified advertisers/agencies are blocked from bidding.
minimum_cpm_micros optional int64 Minimum CPM value that you can bid to not be filtered before the auction. The value is in micros of the bidder account currency.

DirectDeal object

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 and you pay the second price. 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 DealType The type of the deal.

enum DealType
UNKNOWN_DEAL_TYPE = 0;
PREFERRED_DEAL = 1;
PRIVATE_AUCTION = 2;
default = UNKNOWN_DEAL_TYPE

publisher_blocks_overridden optional bool Whether the publisher has exempted this deal from configured blocks. This setting does not override AdX policies or Ad Review Center decisions.
publisher_settings_list_id repeated fixed64 The publisher settings list IDs that apply to this slot. See the RTB Publisher Settings guide for details.

ExchangeBidding object

Parameters related to exchange bidding (third party exchanges doing real-time bidding on DFP). This is never populated in calls to AdX 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 DFP UI. The format is arbitrary and should be agreed upon by the publisher and the exchange bidder.

NativeAdTemplate object

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.

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
store_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 LayoutType Type of style layout for each native ad template.

enum LayoutType
PIXEL = 0;
FLUID = 1;
default = PIXEL

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

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

Attribute Required/Optional Type Implementation details
refresh_type optional AutoRefreshType The type of the declared auto refresh.

enum AutoRefreshType:
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.
default = UNKNOWN_AUTO_REFRESH_TYPE

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

StickySettings object

Stickiness settings declared by the publisher. Next Tag: 4

Attribute Required/Optional Type Implementation details
vertical_stickiness optional Stickiness Whether the request originated from an ad slot that scrolls along with the contents of the page vertically.

enum Stickiness
UNKNOWN_STICKINESS = 0;
IS_STICKY = 1;

top_horizontal_stickiness optional Stickiness Whether the request originated from an ad slot that scrolls along with the contents of the page horizontally, and is located at the top of the page.

default = UNKNOWN_STICKINESS

bottom_horizontal_stickiness optional Stickiness Whether the request originated from an ad slot that scrolls along with the contents of the page horizontally, and is located at the bottom of the page.

default = UNKNOWN_STICKINESS

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 wish 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. See creative-status-codes.txt in the technical documentation for a list of IDs.
cpm_micros optional int64 The second price cpm in micros of your account currency if your bid won the auction, or the cpm that must be exceeded to win the auction if your bid was outbid. This is only set if your bid participated in the auction. It is not set if the bid was filtered prior to the auction. It is also withheld 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.
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 flag has a value of true or false.
is_ping optional bool If true, then this request is intended to measure network latency. Please 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 selective 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.

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 wish 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.

Ad object

Attribute Required/Optional Type Implementation details
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 the following should be set: html_snippet, video_url. Only set this field if the BidRequest is for an in-video ad (BidRequest.video is present).
agency_id optional int64 The Agency associated with this ad. See 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.
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.
native_ad optional NativeAd
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.
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 for AdX publishers, or in gdn-vendors.txt for GDN publishers.
attribute repeated int32 All attributes for the ads that may be shown from this snippet. See 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. See 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. See 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. If you are bidding with ads in restricted categories you MUST ALWAYS declare them here.
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 DFP), the name of the bidder that the exchange called to provide the ad. This is arbitrary UTF8 text but should be sufficient to identify the bidder and should be set consistently to the same value for the same bidder.
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.
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 except for VAST video.

NativeAd object

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, 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].
click_link_url 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.
click_tracking_url optional string 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.
store optional string The URL to the app store to purchase/download the promoted app.
DEPRECATED_impression_tracking_url repeated string This field is deprecated. Use BidResponse.Ad.impression_tracking_url instead.

Image object

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

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 your account 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. This may represent a second price if you choose max_cpm as the highest of several bids, or some form of reserve price if you wish 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.
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 DFP), 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 ExchangeDealType 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.

enum ExchangeDealType
OPEN_AUCTION = 0;
PRIVATE_AUCTION = 1;
PREFERRED_DEAL = 2;

Send feedback about...

Real-Time Bidding Protocol
Real-Time Bidding Protocol