This guide describes each field in the Authorized Buyers Real-time Bidding proto v.330, 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.
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 |
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 |
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 |
optional | int32 | The time in seconds since the google_user_id was created.
This number may be quantized.
|
hosted |
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. |
session_duration_seconds |
optional | int32 | Time in seconds since the first ad request in a given app or site session. The session is reset after a sufficiently long break in user activity. Currently, the field is only populated for mobile app requests. |
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 |
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 |
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 |
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
|
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 |
optional | bytes | Encrypted hyperlocal targeting signals. |
hyperlocal |
optional | HyperlocalSet | Unencrypted version of encrypted_hyperlocal_set . This field
is only set when using an SSL connection.
|
timezone |
optional | int32 | The offset of the user's time from GMT in minutes. For example, GMT+10
is timezone_offset = 600 .
|
user |
repeated | UserList | |
publisher |
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 |
optional | int32 | Deprecated. This field will be removed in Q2 2024. 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 |
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 |
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 |
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 |
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 |
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 |
optional | enum | The production quality of the content where an ad can be shown, as
determined by the publisher. Default = QUALITY_UNKNOWN .
|
content |
optional | enum | The rating of the content where an ad can be shown. Default =
RATING_UNKNOWN .
|
google |
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 .
|
device |
optional | Device | |
key |
repeated | KeyValue | |
mobile |
optional | Mobile | |
video |
optional | Video | |
publisher |
optional | fixed64 | The publisher settings list ID that applies to this page. Refer to the RTB Publisher Settings guide for details. |
publisher |
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 .
|
page |
optional | enum | The visibility state of the web page containing the ad slots. See
www.w3.org/TR/page-visibility/.
|
adslot |
repeated | AdSlot | |
bid |
repeated | BidResponseFeedback | |
response |
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 |
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.
ParentAttribute | 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
|
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.
|
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
ParentA 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 |
optional | Hyperlocal |
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
ParentCoarse 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
ParentA 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 .
|
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 |
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 |
optional | int32 | The width of the device screen in pixels. |
screen |
optional | int32 | The height of the device screen in pixels. |
screen |
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 = |
screen |
optional | enum | The screen orientation of the device when the ad request is sent.
Default = UNKNOWN_ORIENTATION .
|
hardware |
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 |
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 |
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.
|
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 .
|
OsVersion object
ParentContains 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
|
optional | int32 |
KeyValue object
Additional key-value attributes. Currently unused.
Attribute | Required/Optional | Type |
---|---|---|
key
|
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 |
optional | bool | If true, then this is a mobile full screen ad request. |
app |
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 |
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 |
optional | bool | Indicates whether a mobile app bid request is for an app open ad. See App open ad guidance for more information. |
encrypted |
optional | bytes | This field is used for advertising identifiers for:
When the |
encrypted |
optional | bytes | Also refer to the description for encrypted_advertising_id .
|
advertising |
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 |
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 |
optional | string | App names for Android apps are from the Google Play store. App names for iOS apps are provided by App Annie. |
app |
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
ParentIdentification 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
ParentSemantic 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
ParentPublisher'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.
|
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 .
|
|
plcmt |
optional | enum | Video placement type for the impression. Default = PLCMT_UNKNOWN .
|
|
inferred_plcmt |
optional | enum | Google inferred video placement type for the impression. This field is always filled and can
be different from BidRequest.video.plcmt (the publisher-declared placement type).
|
|
description |
optional | string | The URL of the page that the publisher gives Google to describe the video content, with parameters removed. | |
is |
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 =
|
|
is |
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 |
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 |
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 |
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 |
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 |
optional | int32 | The maximum duration of a pod in seconds. | |
video_ad |
optional | enum | Does the publisher allow/require/block skippable video ads? Default =
ALLOW_SKIPPABLE .
|
|
skippable |
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.
|
|
allowed |
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 |
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.
|
|
content |
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 |
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 )
|
|
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 |
optional | enum | Type of audio content feed where an audio ad can be played. Default =
FEED_TYPE_UNKNOWN .
|
|
delivery |
repeated | enum | Supported delivery methods for the video or audio content where an ad can
be shown.
|
|
CompanionSlot object
ParentInformation 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 |
repeated | enum | These are the formats of the creatives allowed in this companion ad
slot.
|
ContentAttributes object
ParentAttributes 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 |
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 |
optional | uint64 | A stable identifier for the combination of publisher, ad slot, and page. |
targetable |
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
|
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 |
optional | FlexibleAdSlotSettings | If the adslot is flexible, this contains settings on how the slot may be resized. |
excluded |
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 |
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 |
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 |
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 |
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 |
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 |
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 |
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 |
repeated | MatchingAdData | Information about the pre-targeting configs that matched. |
blocked |
repeated | string | If non-empty, this field contains a list of seat IDs in the bidder's
namespace set by media planners that are blocked by the publisher. Any
bids on behalf of a blocked seat, as indicated by the
BidResponse.ad.adslot.seat_id field, will be filtered before the auction.
If this field is non-empty, allowed_seat_ids will be empty. If this field
and allowed_seat_ids are both empty, there are no seat ID restrictions
for this request.
|
allowed |
repeated | string | If non-empty, this field contains a list of seat IDs in the bidder's
namespace set by media planners that are allowed by the publisher. All
seat IDs not included in this list are blocked. Bids on behalf of other
seats, as indicated by the BidResponse.ad.adslot.seat_id field , and bids
with no seat ID will be filtered before the auction. If this field is
non-empty, blocked_seat_ids will be empty. If this field and
blocked_seat_ids are both empty, there are no seat ID restrictions for
this request.
|
exchange |
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 |
optional | OpenBidding | Parameters sent in all Open Bidding requests. |
ad_unit |
optional | AdUnitMapping | Ad unit mappings that match the given adslot. |
dfp_ad |
optional | string | The Ad Manager ad unit code. This is currently only set for Open Bidding requests. |
slot |
optional | enum | Visibility information for the slot. 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]. The default value -1 indicates that viewability could not be estimated. |
click |
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 |
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 |
optional | enum | iFraming state of the ad slot on the webpage where it is present.
Default = UNKNOWN_IFRAME_STATE .
|
iframing |
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 .
|
native |
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 |
optional | enum | Describes placement of native ad slot with respect to surrounding
context.
|
mediation |
optional | enum | Whether the ad request has been determined to come directly from the
publisher. Default = UNKNOWN .
|
auto |
optional | AutoRefresh | |
sticky |
optional | StickySettings | |
non |
optional | enum | Publisher declaration stating that this ad slot may serve on non-browser
inventory, like desktop apps. Default = UNDECLARED_SOURCE .
|
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.
|
amp_ad |
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 .
|
is |
optional | enum | Whether this is an AMP page or not.
|
amp_ad |
optional | enum | Possible requirement types for AMP ads.
|
is |
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 |
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.
|
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 |
repeated | fixed64 | The publisher settings list IDs that apply to this slot. Refer to the RTB Publisher Settings guide for details. |
secure_signals |
repeated | Secure |
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:
|
billable_event |
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 | BillableEventRate
|
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.
|
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: |
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
ParentSettings 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
ParentInformation 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
ParentA 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
ParentThe 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 |
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 |
repeated | DirectDeal |
DirectDeal object
ParentInformation about any deals that matched for this inventory.
Attribute | Required/Optional | Type | Implementation details |
---|---|---|---|
direct |
optional | int64 | An ID identifying the deal. |
fixed |
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 or deal_type=AUCTION_PACKAGE or
deal_type=MARKETPLACE_PACKAGE . For these 3 deal types, 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 or deal_type=AUCTION_PACKAGE or
deal_type=MARKETPLACE_PACKAGE , 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 .
|
publisher |
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).
|
must |
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 |
optional | CreativeConstraints | Creative constraints for this deal. If this is not set, bidders should refer to the BidRequest-level setting of each field. |
allowed |
optional | string | If non-empty, this field contains a list of seat IDs in the bidder's
namespace set by media planners that are allowed by the publisher to
bid on this deal. All seat IDs not included in this list are blocked
from bidding on this deal. Bids on this deal on behalf of other
seats, as indicated by the BidResponse.ad.adslot.seat_id field, and
bids with no seat ID will be filtered before the auction. If this
field is empty, there are no restrictions on the seat IDs that can
bid on this deal.
|
CreativeConstraints object
ParentInformation about creative constraints of a direct deal.
Attribute | Required/Optional | Type | Implementation details |
---|---|---|---|
allowed |
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
|
video |
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
|
max_ad |
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
ParentParameters 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 |
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
ParentParameters 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
ParentAdUnitMapping 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:
|
Keyval object
ParentMultiple key-value pairs can be specified in order to support bidders whose inventory unit space is hierarchical and has multiple identifiers. The key-value pairs for the chosen AdUnitMapping should be sent back in the bid response as BidResponse.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
ParentA 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_ |
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.
HEADLINE = 0x1
|
recommended |
optional | int64 | Bitfield describing which fields are recommended by the publisher. All
recommended fields are supported, but not all recommended fields are
required.
HEADLINE = 0x1
|
headline_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
|
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 |
optional | enum | Type of style layout for each native ad template. Default =
PIXEL .
|
style_height
|
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
ParentAuto refresh settings.
Attribute | Required/Optional | Type | Implementation details |
---|---|---|---|
refresh |
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 |
optional | int32 | The number of times this ad slot had been refreshed since last page load. |
AutoRefreshSettings object
ParentAttribute | Required/Optional | Type | Implementation details |
---|---|---|---|
refresh |
optional | enum | The type of the declared auto refresh. Default =
UNKNOWN_AUTO_REFRESH_TYPE .
|
min |
optional | int32 | The minimum refresh interval. This applies to all refresh types. |
StickySettings object
ParentStickiness settings declared by the publisher.
Attribute | Required/Optional | Type | Implementation details |
---|---|---|---|
vertical |
optional | enum | Whether the ad slot is a sidebar that sticks on screen when user scrolls. Default =
UNKNOWN_STICKINESS .
|
top |
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 .
|
bottom |
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 .
|
SecureSignal object
ParentSecure 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 =
|
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 |
optional | bytes | The unique ID from BidRequest.id |
creative |
optional | int32 | The index of the BidResponse_Ad if there was more than one.
The index starts at zero for the first creative.
|
creative |
optional | int32 | The status code for the ad. Refer to creative-status-codes.txt in the technical documentation for a list of IDs. |
cpm |
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 |
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 |
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_ |
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 |
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 |
optional | bytes | Event notification token that was included in the bid response. |
buyer |
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
ParentAttribute | 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 |
---|---|---|---|
id |
optional | string | The Google assigned ID of the data provider. For the list of data providers, see https://storage.googleapis.com/adx-rtb-dictionaries/data_providers.txt. |
name |
optional | string | Exchange-specific name for the signal provider. |
segment |
repeated | Segment | Segment objects. |
type |
optional | enum | Identifies the taxonomy that the segment IDs belong to. Google supports the following taxonomies:
|
Segment object
Segment objects contain segment IDs that can be used with the taxonomy type to access first party data.
ParentAttribute | 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.
|
publisher_rendering_support |
optional | enum | Options describing a publisher's ability to render DSA transparency declarations.
|
data_to_publisher |
optional | enum | Options describing if a publisher requires DSA transparency declarations.
|
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 |
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 |
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 |
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 |
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 |
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 |
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 |
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 |
optional | NativeAd | The content of a native ad. Native ads consist of multiple building blocks, which are rendered by the publisher. |
click |
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 |
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 |
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 |
repeated | string | All names of the ad's advertisers. |
bidder |
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
|
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 |
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 |
repeated | string | The URLs to call when the impression is rendered. This is supported for all inventory types and all formats. |
click |
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 |
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 |
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
ParentThe 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 |
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 |
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 |
optional | double | The app rating in the app store. Must be in the range [0-5]. |
click |
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 |
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
ParentAttribute | Required/Optional | Type | Implementation details |
---|---|---|---|
url |
optional | string | |
width
|
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
ParentAttribute | Required/Optional | Type | Implementation details |
---|---|---|---|
id |
required | int32 | The slot ID from the BidRequest that the ad may appear in. |
max_cpm |
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 |
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 |
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 |
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 |
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.
|
seat_id |
optional | string | The seat ID in the bidder's namespace representing the seat on whose behalf this bid was made. |
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: 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 = 0POD_POSITION_LAST = 1POD_POSITION_FIRST = 2POD_POSITION_FIRST_OR_LAST = 3
|
bid_group_id |
optional | string | All bids with the same This field is currently only supported for rewarded video pods
requests. If an ad is submitted on multiple positional bids represented
by |
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:
The currency of a buyer account is set on account creation and can be checked by contacting a Technical Account Manager. |
FrequencyCap object
ParentAttribute | 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.
|
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
ParentAttribute | 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.
|
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
ParentAttribute | 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
.
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
ParentAttribute | 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
ParentSKAdNetwork 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 .
|
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
ParentAttribute | 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. |