Process the Request

A real-time bidding interaction begins when Google sends a bid request to your application. This guide explains how to code your application to process the bid request.

Parse request

Google sends a bid request as a serialized protocol buffer attached as the binary payload of an HTTP POST request. The Content-Type is set to application/octet-stream. See Example bid request for an example.

You must parse this request into an instance of the BidRequest message. BidRequest is defined in realtime-bidding.proto, which can be obtained from the reference data page. You can parse the message using the ParseFromString() method in the generated class for the BidRequest. For example, the following C++ code parses a request given a POST payload in a string:

string post_payload = /* the payload from the POST request */;
BidRequest bid_request;
if (bid_request.ParseFromString(post_payload)) {
  // Process the request.

Once you have the BidRequest you can then work with it as an object, extracting and interpreting the fields you need. For example, in C++:

for (int i = 0; i < bid_request.adslot_size(); ++i) {
  const BidRequest_AdSlot& adslot = bid_request.adslot(i);
  // Decide what to bid on adslot.

Some information sent in a BidRequest, such as the Google User ID, language, or geographic location, are not always available. If you have pretargeting ad groups that use information that is unknown for a given impression, then those ad groups will not match. In cases where the missing information doesn't matter for the pretargeting conditions, bid requests are sent with the information omitted.

Information about the pretargeting ad group is available in the MatchingAdData group for each AdSlot. It contains the first matching ad group ID of the pretargeting ad group that prompted Google to send out the bid request, that is, the ad group and campaign that are charged if your response wins the auction for the impression. Under certain circumstances, you need to explicitly specify the billing_id for attribution in the BidResponse.AdSlot, for example, when the BidRequest.AdSlot has more than one matching_ad_data. For more information on the constraints on the contents of the bid, refer to therealtime-bidding.proto.

Dictionary files

The bid request uses identifiers defined in dictionary files, which are available on the reference data page.

Bid URL macros

Optionally, some fields of the BidRequest can be inserted into the URL used in the HTTP POST request. This is useful, for example, if you use a lightweight frontend that load balances over multiple backends using a value from the request. Contact your technical account manager to request support for new macros.


Replaced with the google_user_id from the BidRequest. For example, the bidder URL
will be replaced by something like
at request time.

If the Google User ID is unknown, the empty string is substituted, with a result similar to

Replaced with 1 or 0 when calling BidRequest's has_mobile().


Replaced with 1 (true) or 0 (false) when calling BidRequest's has_video().


Replaced with the value of the hosted_match_data field from the BidRequest.


Replaced with 1 (true) or 0 (false) from BidRequest's mobile.is_app field.

Find mobile app ID from transaction URL

Mobile application transactions will report URLs that look like this:

Use a base-32 decoder to decode the portion of the string in bold (gewtimrzgyytanjyg4888888).

You can use an online decoder, but you'll have to capitalize the letters and replace trailing 8s with = values.

So decoding this value:

results in:
The string 429610587 is the app ID for the iOS app iFunny.

Here's another example. The reported URL is:
Decoding this value:
results in:
The result 314716233 is the app ID for the iOS app TextNow.

Find mobile app name from transaction URL

Here's an example of getting the app name. The reported URL is as follows:
Decoding this value:
results in:
The result equates to the Android app

Open Bidding fields

Bid requests sent to exchange and network bidders participating in Open Bidding are similar to those of Authorized Buyers participating in standard real-time bidding. Open Bidding customers will receive a small number of additional fields, and a few existing fields may have alternative uses. These include the following:

OpenRTB Authorized Buyers Details
BidRequest.imp[].ext.dfp_ad_unit_code BidRequest.adslot[].dfp_ad_unit_code

Contains the publisher's Ad Manager network code followed by the ad unit hierarchy, separated by forward slashes.

As an example, this would appear with formatting similar to: /1234/cruises/mars.[].segment[] BidRequest.adslot[].exchange_bidding.key_value[]

Repeated key-value pairs sent from publisher to exchange bidder.

You can determine that the values are key-value pairs sent by the publisher when[].name is set to “Publisher Passed”.

Declare allowed vendors

Technology vendors which provide services such as research, remarketing, and ad serving may play a role in the interaction between buyers and sellers. Only vendors which Google has vetted for participation in Authorized Buyers interactions are allowed.

To understand the BidRequest and create your BidResponse, you need to be aware of the two different possibilities for declaring technology vendors:

  1. Some vendors do not need to be declared; these vendors are listed in the Authorized Buyers Help.
  2. Other vendors can only participate if they are declared in both the BidRequest and BidResponse:
    • In the BidRequest, the allowed_vendor_type field specifies which vendors the seller allows. Vendors that will be sent in the allowed_vendor_type field of the BidRequest are listed in the Vendors.txt dictionary file.
    • In the BidResponse, the vendor_type field specifies which of those allowed vendors the buyer intends to use.

Example bid request

The following examples represent human-readable samples of the Protobuf and JSON requests.



OpenRTB Protobuf

To convert the bid request into a binary form, like you would get from the POST payload in a real request, you can do the following (in C++). Note, however, that this is not applicable to OpenRTB JSON.

string text_format_example = /* example from above */;
BidRequest bid_request;
if (TextFormat::ParseFromString(text_format_example, &bid_request)) {
  string post_payload;
  if (bid_request.SerializeToString(&post_payload)) {
    // post_payload is a binary serialization of the protocol buffer


Authorized Buyers passes a mobile advertising ID in bid requests from a mobile application. The mobile advertising ID can be an iOS IDFA or Android's advertising ID, which is sent through the %%EXTRA_TAG_DATA%% macro in the JavaScript tag managed by Authorized Buyers.

The %%ADVERTISING_IDENTIFIER%% macro allows buyers to receive iOS IDFA or Android's Advertising ID on impression rendering. It returns an encrypted proto buffer MobileAdvertisingId like %%EXTRA_TAG_DATA%%:

message MobileAdvertisingId {
  optional bytes advertising_id = 1;
  optional int32 user_id_type = 2;

The user_id_type is one of the values defined in the enum AdxMobileIdType:

enum AdxMobileIdType {
  IDFA = 1,

You can create user lists from mobile advertising IDs using advertising IDs you've collected during impression rendering. These user lists can be maintained on your server or on ours. To create user lists on Google's servers you can use our bulk upload facility.

When the mobile advertising ID matches a user list, you can use it to run remarketing.

Real-time feedback

Real-time feedback is available to Authorized Buyers, as well as exchanges and networks using Open Bidding.

Bid response feedback is supported on the subsequent bid request for both AdX Protocol and OpenRTB. For OpenRTB, it is sent in BidRequestExt.

In addition to the default fields sent in Bid Response Feedback, you can also send custom data in the bid response (in either AdX Proto or OpenRTB) using an event_notification_token that is returned in the BidResponse. The event_notification_token is arbitrary data known only to the bidder that might help with debugging, for example: a new targeting ID or bidding ID representing a new tactic, or metadata associated with the creative known only to the bidder. For details, see OpenRTB Extensions Protocol Buffer for RTB and AdX Proto for AdX.

When Authorized Buyers sends a bid request to a bidder, the bidder replies with a BidResponse. If the bidder has real-time feedback enabled, then in a subsequent bid request, Authorized Buyers sends feedback on the response in a BidResponseFeedback message, as shown below:

  // 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.
  message BidResponseFeedback {
    // The unique id from
    optional bytes request_id = 1;

    // The index of the BidResponse_Ad if there was more than one. The index
    // starts at zero for the first creative.
    optional int32 creative_index = 2;

    // The status code for the ad. See creative-status-codes.txt in the
    // technical documentation for a list of ids.
    optional int32 creative_status_code = 3;

    // If the bid won the auction, this is the price paid in your account
    // currency. If the bid participated in the auction but was out-bid, this
    // is the CPM that should have been exceeded in order to win. This is not
    // set if the bid was filtered prior to the auction, if the publisher or
    // winning bidder has opted out of price feedback or if your account has
    // opted out of sharing winning prices with other bidders. For first-price
    // auctions, minimum_bid_to_win is populated instead of this field.
    optional int64 cpm_micros = 4;

    // 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.
    optional int64 minimum_bid_to_win = 7;

    // 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.
    optional int64 server_side_component_minimum_bid_to_win = 16;

    // 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.
    optional float billable_event_rate_bid_adjustment = 15 [default = 1];

    // 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.
    optional int64 sampled_mediation_cpm_ahead_of_auction_winner = 10;

    // Event notification token that was included in the bid response.
    optional bytes event_notification_token = 5;

    // Buyer creative ID that was included in the bid response.
    optional string buyer_creative_id = 6;
  repeated BidResponseFeedback bid_response_feedback = 44;

  // How many milliseconds Google will wait for a response before ignoring it.
  optional int32 response_deadline_ms = 57;

  // -----------------------------------------------------------
  // Testing options.
  // 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.
  optional bool is_test = 15 [default = false];

  // 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.
  optional bool is_ping = 17 [default = false];

  // 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.
  optional bool is_predicted_to_be_ignored = 45 [default = false];

  // SupplyChain object. For more information, see
  message SupplyChain {
    // Indicates 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.
    optional bool complete = 1;

    message SupplyChainNode {
      // 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.
      optional string advertising_system_identifier = 1;

      // The identifier associated with the seller or reseller account within
      // the advertising system. This must contain the same value used in
      // transactions, specifically the publisher_id field in the Google
      // protocol. Should be limited to 64 characters in length.
      optional string seller_identifier = 2;

      // 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.
      optional bool handles_payment = 6;

    // 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.
    repeated SupplyChainNode nodes = 2;

    // 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".
    optional string version = 3;
  optional SupplyChain supply_chain = 69;

  // Experimental feature; may be subject to change. See
  // 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
  // field.
  enum FrequencyCappingScope {
    // Default value which should not be used, or which can indicate that
    // frequency cap scope could not be reliably determined.

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

    // Frequency capping enforcement is available across multiple sites within
    // the same browser.

    // Frequency capping enforcement is available across multiple apps on the
    // device, excluding browsers.

    // Frequency capping enforcement is available within a single app.

    // Frequency capping enforcement is available within a single site.
  optional FrequencyCappingScope frequency_capping_scope = 70;

// 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 from the
// BidRequest. If you do not want to bid, submit a response with no ads and
// with only the processing_time_ms set.
message BidResponse {

  message Ad {
    // The event notification token is sent to AdX by bidders for
    // troubleshooting. AdX will include the token in real-time feedback for the
    // bid. The content of the token will not be logged by AdX. AdX will ignore
    // any token longer than 128 bytes.
    optional bytes event_notification_token = 25;

    // 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.
    optional string buyer_creative_id = 10;

    // Only one of the following should be set:
    // 1) html_snippet, 2) video_url, 3) native_ad, or 4) sdk_rendered_ad.
    // 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.
    optional string html_snippet = 1;

    // The URL to fetch a video ad. The URL should return an XML response that
    // conforms to the VAST 2.0 or 3.0 standard. Use
    // BidResponse.Ad.AdSlot.billing_id to indicate which billing id to
    // attribute this ad to. Only one of the following should be set:
    // html_snippet, video_url. Only set this field if the BidRequest is for an
    // in-video ad ( is present).
    optional string video_url = 9;

    // 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.
    optional string video_vast_xml = 24;

    // The URL to fetch an AMPHTML ad. Only one of the following should be set:
    // html_snippet, video_url, amp_ad_url, native_ad.
    optional string amp_ad_url = 23;

    // The content of a native ad. Native ads consist of multiple building
    // blocks, which are rendered by the publisher. Only one of the following
    // should be set: html_snippet, video_url, or native_ad.
    // Only set this field if the BidRequest is for a native ad
    // (BidRequest.adslot.native is present).
    message NativeAd {
      // A video in the form of either a URL for a VAST tag, or an in-line VAST
      // tag. Only set this field if VIDEO is required or recommended in the
      // BidRequest's NativeAdTemplate.
      oneof video {
        // The URL to fetch a video ad. The URL should return an XML response
        // that conforms to VAST standards.
        string video_url = 13;

        // The VAST document to be returned. Max size is 100kB.
        string video_vast_xml = 16;

      // A short title for the ad.
      optional string headline = 1;

      // A long description of the ad.
      optional string body = 2;

      // A label for the button that the user is supposed to click
      optional string call_to_action = 3;

      // The name of the advertiser or sponsor, to be displayed in the ad
      // creative.
      optional string advertiser = 4;

      message Image {
        optional string url = 1;

        // 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.
        optional int32 width = 2;
        optional int32 height = 3;

      // A large image.
      optional Image image = 5;

      // A smaller image, for the advertiser's logo.
      optional Image logo = 6;

      // The app icon, for app download ads.
      optional Image app_icon = 7;

      // The app rating in the app store. Must be in the range [0-5].
      optional double star_rating = 8;

      // 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.
      optional string click_link_url = 14;

      // This field is deprecated in favor of the repeated click_tracking_urls
      // field at the BidResponse.Ad level. It will be removed at the end of
      // Q2 2022.
      // 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.
      optional string DEPRECATED_click_tracking_url = 11 [deprecated = true];

      // This field is deprecated in favor of the click_tracking_urls
      // field at the BidResponse.Ad level. It will be removed at the end of
      // Q2 2022.
      // The URLs to use for click tracking. This will be used throughout the
      // serving stack and will incorporate any URL in click_tracking_url.
      repeated string DEPRECATED_click_tracking_urls = 15 [deprecated = true];

      // The price of the promoted app including the currency info.
      optional string price = 10;
    optional NativeAd native_ad = 18;

    // 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 inal landing page. A BidResponse that
    // returns a snippet or video ad but declares no click_through_url will be
    // discarded. Only set this field if html_snippet or video_url or native_ad
    // are set. This data is used as a destination URL declaration, for example
    // for post-filtering of publisher-blocked URLs or ad categorization.
    // For non-native ads, it is not used for click tracking or any
    // other ad functionality; it is only used as a destination URL
    // declaration.
    // 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. In addition, all values are used as destination
    // URL declarations (similar to the non-native case).
    repeated string click_through_url = 4;

    // All vendor types for the ads that may be shown from this snippet. You
    // should only declare vendor ids listed in the vendors.txt file in the
    // technical documentation. We will check to ensure that the vendors you
    // declare are in the allowed_vendor_type list sent in the BidRequest for
    // AdX publishers.
    repeated int32 vendor_type = 5;

    // All attributes for the ads that may be shown from this snippet. See
    // buyer-declarable-creative-attributes.txt in the technical documentation
    // for a list of ids. We will check to ensure none of these attributes are
    // in the excluded_attribute list in the BidRequest.
    repeated int32 attribute = 6;

    // All sensitive categories for the ads that may be shown from this snippet.
    // See ad-sensitive-categories.txt in the technical documentation for a list
    // of ids. We will check to ensure none of these categories were in the
    // excluded_sensitive_category list in the BidRequest.
    repeated int32 category = 7;

    // All restricted categories for the ads that may be shown from this
    // snippet. See ad-restricted-categories.txt in the technical documentation
    // for a list of ids. We will check to ensure these categories were listed
    // in the allowed_restricted_category list in the BidRequest. If you are
    // bidding with ads in restricted categories you MUST ALWAYS declare them
    // here.
    repeated int32 restricted_category = 17;

    // All names of the ad's advertisers.
    repeated string advertiser_name = 11;

    // 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.
    optional int32 width = 14;
    optional int32 height = 15;

    // Deprecated. This field will be removed in November, 2023.
    // The Agency associated with this ad. See agencies.txt file in the
    // technical documentation for a list of ids. If this ad has no associated
    // agency then the value NONE (agency_id: 1) should be used rather than
    // leaving this field unset.
    optional int64 agency_id = 16 [deprecated = true];

    message AdSlot {
      // The slot id from the BidRequest that the ad may appear in.
      required int32 id = 1;

      // 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).
      required int64 max_cpm_micros = 2;

      // 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.
      optional int64 min_cpm_micros = 3;

      // The currency used by max_cpm_micros and min_cpm_micros, using ISO-4217
      // alpha codes. If this field is populated, the specified currency will
      // be used to interpret the bid. Otherwise, the default bidding currency
      // will be used, which is determined in the following priority:
      // 1. The bidder-level currency, if configured in RTB account settings.
      // 2. The buyer-level currency. The buyer will be determined by the
      // billing ID specified in the billing_id field of the bid response if it
      // is populated, otherwise it will be based on the sole billing ID sent
      // in the bid request.
      // The currency of a buyer account is set on account creation and can be
      // checked by contacting a Technical Account Manager.
      optional string currency = 15;

      // 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 or if the bidder has
      // active child seats.
      optional int64 billing_id = 4;

      // 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.
      optional int64 deal_id = 5 [default = 0];

      // For exchange bidders (third party exchanges doing real-time bidding on
      // DFP), the deal id from the exchange's namespace that is associated with
      // this bid and reported to publishers. Leave unset if there is no
      // associated deal. This is arbitrary UTF8 text and must be at most 64
      // bytes.
      optional string exchange_deal_id = 6;

      // When exchange_deal_id is set, the type of deal. This is reported to
      // publishers and affects how the deal is treated in the auction.
      enum ExchangeDealType {
        OPEN_AUCTION = 0;
        PRIVATE_AUCTION = 1;
        PREFERRED_DEAL = 2;
      optional ExchangeDealType exchange_deal_type = 7 [default = OPEN_AUCTION];

      // The seat ID in the bidder's namespace representing the seat on whose
      // behalf this bid was made.
      optional string seat_id = 25;

      // 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.
      optional string buyer_reporting_id = 8;

      // 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.
      optional string third_party_buyer_token = 12;

      // Experimental feature; may be subject to change. See
      // for more
      // information.
      // Specifies frequency capping to be applied to the bid. Impressions for
      // each user are capped at the level specified by frequency_cap_id. A bid
      // will not participate in the auction if an additional impression for the
      // user would violate any of the specified caps. Multiple frequency caps
      // can be specified for the same frequency_cap_id.
      // A bid is filtered before the auction if the frequency cap is malformed.
      // Instances where the cap is malformed include:
      //  - frequency_cap_id is empty or is very long
      //  - max_mpressions or time_range are non-positive
      //  - there are a large number of frequency caps for a single bid
      //  - time_unit is not specified
      // Note that if a subsequent bid with the same frequency_cap_id uses a
      // different duration (represented by time_unit and time_range) then
      // impressions counted against the old frequency cap will not count
      // against the new one, and the impressions counted against the new
      // frequency cap with a different time_unit and time_range will not count
      // against the old frequency cap..
      message FrequencyCap {
        // An ID that can represent a bidder's use-case for frequency capping.
        // For example, it could represent their campaign, ad, line item, or
        // some other entity. It should not contain any user-specific
        // information or identifiers and should not be longer than 64
        // characters.
        optional string frequency_cap_id = 1;

        // The time units for which frequency caps can be enforced.
        enum TimeUnit {
          UNKNOWN_TIME_UNIT = 0;
          MINUTE = 1;
          DAY = 2;
          WEEK = 3;
          MONTH = 4;

          // When INDEFINITE is used, time_range will be ignored. INDEFINITE
          // means the frequency cap will be applied for a long period of time,
          // (longer than a month) but not necessarily forever.
          INDEFINITE = 5;

        // The unit of time used to specify the time window for which a
        // frequency cap applies.
        optional TimeUnit time_unit = 2;

        // 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.
        optional int32 time_range = 3 [default = 1];

        // 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.
        optional int32 max_impressions = 4;
      repeated FrequencyCap frequency_cap = 16;

      // Position within the pod.
      enum PodPosition {
        // Any position in the pod.
        POD_POSITION_ANY = 0;

        // Last position in the pod.
        POD_POSITION_LAST = 1;

        // First position in the pod.

        // First or last position in the pod.

      // Indicates that the bid is only eligible
      // for a specific position within the pod.
      optional PodPosition position_in_pod = 22;

      // All bids with the same bid_group_id will be won or lost as a group.
      // Bids must have a non-empty bid_group_id to allow an ad to be played
      // as part of a pod.
      // This field is currently only supported for rewarded video pods
      // requests. If an ad is submitted on multiple positional bids
      // represented by AdSlot messages, each bid (AdSlot message)
      // must have a different bid_group_id.
      // For example, if a bidder wants to bid ad_1 for first position
      // and last position in the pod and ad_2 for any position and
      // want to ensure either both win at the same time or neither of those
      // wins, bidder needs to submit:
      // ad {
      //   buyer_creative_id: "ad_1",
      //   adslot {
      //     position_in_pod: POD_POSITION_FIRST,
      //     bid_group_id: "group1"
      //   },
      //   adslot {
      //     position_in_pod: POD_POSITION_LAST,
      //     bid_group_id: "group2"
      //   }
      // },
      // ad {
      //   buyer_creative_id: "ad_2",
      //   adslot {
      //     position_in_pod: POD_POSITION_ANY,
      //     bid_group_id: "group1"
      //   },
      //   adslot {
      //     position_in_pod: POD_POSITION_ANY,
      //     bid_group_id: "group2"
      //   }
      // }
      optional string bid_group_id = 23;
    repeated AdSlot adslot = 3;

    // The URLs to call when the impression is rendered. This is supported for
    // all inventory types and all formats.
    repeated string impression_tracking_url = 19;

    // 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
    repeated string click_tracking_urls = 30;

    // 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.
    optional string ad_choices_destination_url = 21;

    message ImpressionTrackingResource {
      // The URL of a Javascript resource. The URLs should not contain script
      // tags. For example: "".
      optional string script_url = 1;

      // Additional context provided for rendering.
      enum Context {
        UNKNOWN_CONTEXT = 0;

        // Currently not supported.
        OMID = 1;
      repeated Context context = 2;

      // 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.
      optional string verification_parameters = 3;

      // Used to uniquely identify the verification script provider.
      optional string vendor_key = 4;

    // Resources to invoke when the impression is rendered. This is supported
    // for native and banner formats only and explicitly allowed scripts
    // only.
    repeated ImpressionTrackingResource impression_tracking_resource = 26;

    // An ad that will be rendered by an SDK known to the buyer. This can only
    // be used when the BidRequest included a mobile.installed_sdk submessage.
    message SdkRenderedAd {
      // The identifier for the SDK that will render the ad. Must match a
      // sent in the corresponding bid request.
      optional string id = 1;

      // Data to pass to the SDK in order to render the ad. This data is opaque
      // to the publisher and to Google.
      optional string rendering_data = 2;

      // Declared ad assets to support creative scanning, classification, and
      // enforcement of ad policy and publisher blocks for ads rendered with a
      // custom SDK.
      message DeclaredAd {
        // Ad content used by SDK to render an ad.
        oneof content {
          // The HTML snippet representative of the SDK-rendered ad.
          string html_snippet = 1;

          // The URL to the VAST asset used in the SDK-rendered ad.
          string video_url = 2;

          // The VAST document used to render custom SDK-rendered ad. This
          // document should conform to the VAST 2.0 or 3.0 standard.
          string video_vast_xml = 5;

          // The content of a native ad. Native ads consist of multiple building
          // blocks (such as image and text), which are rendered by the buyer
          // SDK.
          NativeAd native_ad = 6;

        // The final landing pages of the SDK-rendered ad.
        repeated string click_through_url = 4;
      optional DeclaredAd declared_ad = 6;
    optional SdkRenderedAd sdk_rendered_ad = 27;

    // 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 visit:
    message SKAdNetworkResponse {
      // Version of SKAdNetwork supported by the advertiser. Also used to
      // specify how the signature was generated by the advertiser. This
      // should match the version from
      optional string version = 1;

      // Ad network identifier used in signature. This should match one of the
      // items in
      optional string network = 2;

      // Campaign ID compatible with Apple's spec. Used in SKAdNetwork 3.0 and
      // below. Replaced by Source Identifier (`source_identifier` field) in
      // SKAdNetwork 4.0 and above.
      optional int64 campaign = 3;

      // A four-digit integer that ad networks define to represent the ad
      // campaign. Used in SKAdNetwork 4.0+ and replaces the `campaign` field.
      optional int64 source_identifier = 11;

      // ID of advertiser's app in Apple's app store.
      optional string itunesitem = 4;

      // ID of custom product page to display (for iOS 15 or later).
      // If not specified, default product page will be displayed.
      // See
      // for more details about custom product pages.
      optional string product_page_id = 12;

      // 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 visit:
      message Fidelity {
        // The fidelity type of the attribution to track.
        optional SKAdNetworkFidelityType fidelity_type = 1 [default =

        // A unique all-lowercase UUID generated by the advertiser to use for
        // generating the signature.
        optional string nonce = 2;

        // Unix time in millis used at the time of signature generation.
        optional int64 timestamp = 3;

        // SKAdNetwork signature as specified by Apple.
        optional string signature = 4;
      repeated Fidelity fidelities = 9;

      // 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
      // field to support multiple
      // fidelity types.
      optional string nonce = 5;

      // ID of publisher's app in Apple's app store. This should match the ID
      // from
      optional string sourceapp = 6;

      // Unix time in millis used at the time of signature generation.
      // Note:  This field will be deprecated in favor of the
      // field to support multiple
      // fidelity types.
      optional int64 timestamp = 7;

      // SKAdNetwork signature as specified by Apple.
      // Note:  This field will be deprecated in favor of the
      // field to support multiple
      // fidelity types.
      optional string signature = 8;

      // These options indicate how to present SKOverlay recommending the
      // advertised app.
      // Supported by iOS 14 and later.
      // For more info visit:
      message SKOverlay {
        // 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.
        optional int32 delay_seconds = 1;

        // 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_seconds` and `endcard_delay_seconds` are set,
        // the overlay will be automatically dismissed when the ad ends,
        // and shown again after the endcard shows.
        optional int32 endcard_delay_seconds = 2;

        // Whether this overlay can be dismissed by the user.
        optional bool dismissible = 3 [default = true];
      optional SKOverlay skoverlay = 13;

      // Google Mobile Ads SDK options for SKAdNetwork handling.
      message SKAdNetworkOptions {
        // By default, SKAdNetwork attribution will only be initiated if the
        // click-through URL lands on the app store, either as a direct link to
        // the app store or as the final destination of a server-side redirect
        // chain. Enables GMA SDK to always initiate SKAdNetwork
        // attribution on-click regardless of the detected click's final
        // destination URL. Note that enabling this will launch the app store
        // even for clicks that are not meant to open the app store, for example
        // clicks on Ad Choices icon. For more info, see:
        optional bool always_open_appstore = 1 [default = false];
      optional SKAdNetworkOptions skadn_options = 10;
    optional SKAdNetworkResponse skadn = 29;

    // ID of the advertised app (only for app promotion).
    // On Android, this should be a bundle or package name such as
    // 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.
    optional string advertised_app_id = 32;

    // Possible types of app promotion.
    enum AppPromotionType {

      // For encouraging new users to download and install the advertised app.
      // Clicking this ad will show the app store listing as an overlay (for
      // supported formats), without leaving the publisher app.
      // Click through URL for this ad points to the app store listing.
      INSTALLS = 1;

      // Other types of app promotion that do not fall into the categories
      // above. No features specific to app promotion types will apply.
      OTHER = 3;

    // 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.
    optional AppPromotionType app_promotion_type = 33;
  repeated Ad ad = 2;

  // If is_test was set in the BidRequest, then you may return debug information
  // as plain text in this field. Don't 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.
  optional string debug_string = 5;

  // Set this to the processing time in milliseconds from when you
  // received the request to when you returned the response.
  optional int32 processing_time_ms = 4;

  // 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
  // for the full set of no-bid reason codes.
  optional int32 no_bid_reason = 6;

// SKAdNetwork API starting from version 2.2 supports multiple ad
// presentation options specified by the `fidelity-type` parameter of the
// SKAdNetwork signature. The following are the fidelity types supported by
// Apple. For more info visit:
enum SKAdNetworkFidelityType {
  // Attribution for app installs within 24 hours of viewing an ad for at least
  // 3 seconds. Supported for SKAdnetwork version 2.2 and up. For more info see:

  // Attribution for app installs initiated from the StoreKit-rendered App Store
  // product page driven by ad clicks. Supported for all SKAdNetwork versions.
  // For more info see:

From this message, the first field you should check is bid_response_feedback.creative_status_code; you can find the code meaning in creative-status-codes.txt. Note that if you win the bid, you can opt out from the price feedback. For more information, see How to opt-out.

The real-time feedback includes the bid request ID and one of the following:

Auction outcome Real-time feedback
The buyer didn't submit a bid. Nothing.
The buyer submitted a bid that was filtered out before reaching the auction. The creative status code (see creative-status-codes.txt).
The buyer submitted a bid but lost the auction. The creative status code 79 (outbid in auction).
The buyer submitted a bid that won the auction. The clearing price and creative status code 1.

For an app impression and a creative status code of 53, the app publisher could have been using a mediation waterfall and therefore the winning bid would have competed against other demand in the publisher's passback waterfall chain. Learn how to use sampled_mediation_cpm_ahead_of_auction_winner when bidding.


The following is a sample of real-time feedback as seen in supported protocols:



OpenRTB Protobuf

Build a bidding model for first-price auctions

After placing a bid in a first-price auction, you will receive real-time feedback including the minimum_bid_to_win and sampled_mediation_cpm_ahead_of_auction_winner fields if the bid was not filtered from the auction. These signals can be used to inform your bidding logic on how much higher or lower your bid could have been in order to win the impression.

  • minimum_bid_to_win: The minimum bid that could have been placed to win the real-time bidding auction. If you won the auction, this will be the lowest bid you could have placed while still winning. If you lost the auction, this will be the winning bid.
  • sampled_mediation_cpm_ahead_of_auction_winner: If there are other networks in the mediation chain, the value of this field is a price representing a sample bid from one of the eligible mediation networks that were higher than the auction winner, weighted by expected fill rate. This will be set to 0 if none of the networks in the mediation chain are expected to fill, or if the publisher does not use SDK mediation.

How it works

In order to describe the calculations used to determine the possible values for minimum_bid_to_win and sampled_mediation_cpm_ahead_of_auction_winner, we first need to define the following:

  • The following represents the CPMs in the mediation chain in descending order:
    \[C_1, C_2, …, C_n\]
  • The following represents the corresponding fill rates for the CPMs in the mediation chain:
    \[f_1, f_2, …, f_n\]
  • The following is a function used to determine the expected CPM and its probability from mediation chain element \(i\), based on the given fill rate:
    \(X_i = \{C_i\) with probability \(f_i\); \(0\) with probability \(1 - f_i\}\)
  • The final winning mediation chain will be:
    \[\{C_1, C_2, …, C_K, W\}\]
    where \(W\) is the winning bid, and \(C_K > W >= C_{K+1}\)
  • The reserve price, or floor, is denoted as \(F\).
  • The runner-up bid is denoted as \(R\).
Calculations for auction winner
Field Calculation
\(max\{F, R, X_{K+1}, …, X_n\}\)
\(\{C_i\) with probability \(\prod_{j=1}^{i-1}(1-f_j) \cdot f_i \div \prod_{j=1}^{K}(1-f_j)\}\)
For \(1 <= i <= K\).

Calculations for auction loser
Field Calculation
\(max\{F, W\}\)
\(max\{X_1, …, X_K\}\)

Example with a simple mediation chain

Assume a publisher uses both real-time bidding and an SDK mediation chain as follows:

SDK Mediation Chain Expected CPM Fill Rate
Network 1 \(C_1 = $3.00\) \(f_1 = 5\%\)
Network 2 \(C_2 = $2.00\) \(f_2 = 45\%\)
Network 3 \(C_3 = $0.50\) \(f_3 = 80\%\)
Network 4 \(C_4 = $0.10\) \(f_4 = 85\%\)

Assume the following as the result of the RTB auction:

RTB Auction CPM
Auction Winner (W) $1.00
Auction Runner-UP (R) $0.05
Reserve Price / Floor (F) $0
Bid that won the auction

The following is an example of how values and probabilities for minimum_bid_to_win and sampled_mediation_cpm_ahead_of_auction_winner are calculated for a bid that won.

minimum_bid_to_win Probability
\(max(F, R, C_3) = $0.50\) \(f_3 = 80\%\)
\(max(F, R, C_4) = $0.10\) \((1-f_3) \cdot f_4 = 17\%\)
\(max(F, R, 0) = $0.05\) \((1-f_3) \cdot (1-f_4) = 3\%\)
\(C_1 = $3.00\) \(f_1 \div (1-(1-f_1) \cdot (1-f_2)) =~ 10.5\%\)
\(C_2 = $2.00\) \(((1-f_1) \cdot f_2) \div (1-(1-f_1) \cdot (1-f_2)) =~ 89.5\%\)
Bids that lost the auction

The following is an example of how values and probabilities for minimum_bid_to_win and sampled_mediation_cpm_ahead_of_auction_winner are calculated for a bids that lost.

minimum_bid_to_win Probability
\(max(F, W) = $1.00\) \(100\%\)
\(C_1 = $3.00\) \(f_1 = 5\%\)
\(C_2 = $2.00\) \((1-f_1) \cdot f_2 =~ 42.8\%\)
\(0\) \((1-f_1) \cdot (1-f_2) =~ 52.2\%\)

Bid flattening

Bid flattening describes the processing of a single complex BidRequest into multiple bid requests that are sent to your application. Because they retain identical IDs (BidRequest.google_query_id in the Authorized Buyers RTB Protocol or BidRequestExt.google_query_id in the OpenRTB protocol) you can determine which bid requests are correlated after flattening.

Ad formats

Some ad opportunities can accept multiple formats. With bid flattening, each format is sent in a distinct bid request where attributes such as eligible billing IDs are relevant to the format specified in the request.

Bid requests containing the following formats will be flattened into distinct bid requests:

  • Banner
  • Video
  • Audio
  • Native

Ad format flattening example

Below is an example showing a simplified OpenRTB JSON bid request without ad format flattening in comparison to an equivalent set of flatenned requests:




An ad opportunity for a given bidder can be applicable to various deal types, in addition to the open auction. With bid flattening for deals, one bid request will be sent for the open auction, and one for each type of fixed-price deal. In practice, ad constraints can differ between auctions and fixed-price deal types, for example, for a given video ad opportunity that is available to both the open auction and a fixed-price deal, a bidder will receive distinct bid requests for each where constraints such as maximum ad duration and whether skippable ads are allowed can differ. As a result, flattening applied to the ad opportunity lets you more easily discern the ad constraints for the open auction and the fixed-price deal.

Max skippable video duration

Google's protocol and OpenRTB implementation support the following fields for video duration and skipability:

Duration Skippable duration Skipability
Google protocol max_ad_duration skippable_max_ad_duration video_ad_skippable
OpenRTB maxduration n/a skip

This means that while the Google protocol can have a granular skippable and non-skippable duration, the OpenRTB implementation only has a single maximum duration value.

Prior to bid flattening, OpenRTB's maxduration would be set to the lower of the Google protocol's max_ad_duration and skippable_max_ad_duration fields. This behavior has now changed to sending two separate bid requests when these values differ: one representing the maxduration for skippable and the other for non-skippable opportunities.

The following examples show how a Google protocol request translates to OpenRTB before and after bid flattening. The equivalent Google protocol request has a max_ad_duration of 15 and a skippable_max_ad_duration of 60.

Example max_ad_duration skip (true OR false)
Original request without flattening 15 true
Flattened request #1: Non-skippable 15 false
Flattened request #2: Skippable 60 true

Skippable video duration bid request flattening will only take place when these conditions are met:

  • The request allows video.
  • Both skip and no-skip videos are allowed, and the two respective max durations differ in value.
  • This request is Private Auction or Open Auction-eligible.
  • The bidder account has active OpenRTB endpoints.

You can opt out from this type of flattening by contacting your technical account manager.

Video pods

Bid requests for a video pod with multiple ad opportunities are flattened, such that each bid request is for an individual ad opportunity from that pod. This enables you to bid on multiple ad opportunities for a given pod.

Open Measurement

Open Measurement lets you specify third-party vendors that provide independent measurement and verification services for ads served to mobile app environments.

You can determine whether a publisher supports Open Measurement in the bid request by checking whether the ad opportunity excludes the OmsdkType: OMSDK 1.0 attribute found in Publisher-excludable creative attributes. For the Authorized Buyers protocol, this would be found under BidRequest.adslot[].excluded_attribute. For the OpenRTB protocol, this would be found under the battr attribute for Banner or Video, depending on the format.

For more information on how to interpret bid requests containing Open Measurement signals, refer to the Open Measurement SDK Help Center article.

Sample bid requests

The following sections show sample bid requests for different ad types.

App banner



OpenRTB Protobuf

App interstitial



OpenRTB Protobuf

App interstitial video


OpenRTB Protobuf

App native



OpenRTB Protobuf

Web video


Mobile web banner for exchange bidder

OpenRTB Protobuf