Click here to see your recently viewed pages and most viewed pages.
Hide
DoubleClick Ad Exchange Real-Time Bidding Protocol

Processing the Request

A real-time bidding interaction begins when Google sends a bid request to your application. The following topics explain how to code your application to process the bid request.

  1. Parsing the request
  2. Dictionary files
  3. Content labels
  4. Bid URL macros
  5. Declaring allowed vendors
  6. Adapting as BidRequest fields are deprecated
  7. Example bid request
  8. Remarketing with IDFA or Advertising ID
  9. Real-time feedback

Parsing the 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 Downloads 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, vertical classification, and geographic location, is not always available. If you have pre-targeting 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 pre-targeting conditions, bid requests are sent with the information omitted.

Information about the pre-targeting ad group is available in the MatchingAdData group for each AdSlot. It currently contains the first matching ad group id of the pre-targeting ad group that prompted us to send out a bid request. That is the ad group and campaign that will be charged if your response wins the auction for the impression. Under certain circumstances, you need to explicitly specify the adgroup_id for attribution in BidResponse.AdSlot, e.g., when the BidRequest.AdSlot has more than one matching_ad_data. To understand the constraints on the contents of the bid, study the comments in realtime-bidding.proto.

Back to top

Dictionary files

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

Back to top

Content labels

Content labels inform buyers about the characteristics of the inventory that is up for bid—whether its content includes profanity, or touches on crime or military conflict, among other things. The detected_content_labels field in the BidRequest contains values which correspond to content labels. For example, the value 23 indicates "Social networks." The complete list of content labels and the values that stand for them is defined in the content-labels.txt file, available from the Downloads page.

If no content labels have been applied to the inventory described by a BidRequest, the BidRequest omits the detected_content_labels field. If multiple labels have been applied, the field contains multiple values.

For video inventory, content labels can indicate what audiences are appropriate (all, aged 14+, or mature only) or that the video content has not yet been rated. Since at present, all video inventory is from YouTube, these are known as YouTube content labels. A given item of video inventory can have one or more regular content labels along with a YouTube content label. As described in the Help Center, buyers with UI advertising campaigns for YouTube content can apply filters to restrict their ads from showing next to one or more of the content categories.

You can use pre-targeting to ensure that Google sends you bid requests for the impressions that are most appropriate for you. Content labels can be among the attributes you use in pre-targeting.

Back to top

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 light-weight front end that load balances over multiple backends using a value from the request. Currently, only one such macro, GOOGLE_USER_ID, is supported. Contact your technical account manager to request support for new macros.

Insert %%GOOGLE_USER_ID%% into your bidder URL and this will be replaced by the corresponding google_user_id field from the BidRequest. For example, the bidder URL http://google.bidder.com/path?gid=%%GOOGLE_USER_ID%% will be replaced by something like http://google.bidder.com/path?gid=dGhpcyBpcyBhbiBleGFtGxl at request time.

If the Google User ID is unknown, the empty string is substituted, with a result similar to http://google.bidder.com/path?gid=.

Insert the %%HAS_VIDEO%% macro into your bidder URL and this will be replaced by 1 (true) or 0 (false) returned from the call to the BidRequest's has_video() function.

Insert the %%HAS_MOBILE%% macro into your bidder URL and this will be replaced by a boolean value (true or false) returned by the call to the BidRequest's has_mobile() function.

Back to top

Adapting as BidRequest fields are deprecated

At any time, some fields in the BidRequest may appear with the prefix DEPRECATED_. This means that after a specified period of time those fields will no longer appear in the BidRequest. The exact period of time in each case—called a notification period—is announced in Release Notes, blog posts, and the email newsletter. During the notification period, you should update your bidder code to remove any dependencies on deprecated fields. Otherwise, your bidder may rely on information from the BidRequest that is no longer being sent.

Deprecated fields (updated May 1, 2013)

The fields in the following table are no longer being sent:

Message Field
BidRequest protocol_version
excluded_click_through_url
company_name
country
region
city
metro
Mobile submessage of the BidRequest (Formerly called the MobileApp submessage) app_name
company_name
carrier_name
carrier_country
MatchingAdData submessage of the BidRequest campaign_id

The following table describes fields in the BidRequest that have been deprecated:

Message Field
MatchingAdData submessage of the BidRequest buyer_minimum_cpm
fixed_cpm_micros
Ad submessage of BidRequest allowed_attribute
publisher_settings
excluded_click_through_url
BidRequest protocol_version
click_tracking_url
cookie
hashed_cookie
excluded_click_through_url
seller_network
publisher_settings
MatchingNetwork network_id
google_user_id

Back to top

Declaring allowed vendors

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

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

  1. Some vendors do not need to be declared; these vendors are listed in the Ad Exchange Buyer 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.
  3. Finally, for impressions from the Google Display Network (GDN), there is a list of vendors which are always allowed. These vendors are not declared in the BidRequest. In the BidResponse, the buyer can only declare vendors from that list. Vendors that must be declared in the BidResponse for impressions on Google Display Network (GDN) sites are not sent. They are implicitly declared in the gdn_vendors.txt dictionary file.

Note: These rules represent a streamlining of the RTB Protocol which took effect on April 1, 2012. Prior to that date, the BidRequest and the BidResponse behaved somewhat differently in terms of declaring vendors, and some of the relevant dictionary files were different too.

Back to top

Example bid request

The following example shows a BidRequest protocol buffer as serialized using the TextFormat class in google/protobuf/text_format.h. This is an example of what you can expect to receive from Google:

id: "Mv\2005\000\017.\001\n\345\177\307X\200M8"
ip: "\314j\310"
user_agent: "Mozilla/5.0 (Windows; U; Windows NT 5.1; en-US) AppleWebKit/534.13 (KHTML, like Gecko) Chrome/9.0.597.107 Safari/534.13,gzip"
url: "http://www.example.com/"
detected_language: "en"
detected_vertical {
  id: 22
  weight: 0.67789277
}
detected_vertical {
  id: 355
  weight: 0.32210726
}
adslot {
  id: 1
  width: 300
  height: 250
  excluded_attribute: 7
  excluded_attribute: 22
  matching_ad_data {
    adgroup_id: 3254984134
    minimum_cpm_micros: 2000000
  }
  matching_ad_data {
    adgroup_id: 2646216548
    minimum_cpm_micros: 2000000
  }
  targetable_channel: "all pages,middle right"
  publisher_settings_list_id: 4985794913155998850
  slot_visibility: BELOW_THE_FOLD
}
is_test: false
cookie_version: 1
google_user_id: "CAESEIcS1pC2TBvb-4SLDjMqsY9"
seller_network_id: 1
publisher_settings_list_id: "\357\237V\206)\231\3125%|$\032\"
vertical_dictionary_version: 2
timezone_offset: -300
cookie_age_seconds: 7685804
geo_criteria_id: 1001193

To convert this into a binary form, like you would get from the POST payload in a real request, you can do the following (in C++):

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
  }
}

Back to top

Remarketing with IDFA or Advertising ID

Ad Exchange 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 via the %%EXTRA_TAG_DATA%% macro in the JavaScript tag managed by Ad Exchange.

The %%ADVERTISING_IDENTIFIER%% macro allows buyers to receive iOS IDFA or Android's Avertising 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 {
  MOBILE_ID_UNKNOWN = 0,
  IDFA = 1,
  ANDROID_ID = 2,
};

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

You can get real-time feedback on bid responses by enabling it on your bidder—contact your technical account manager to turn on real-time feedback.

When Ad Exchange 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, Ad Exchange 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. Please contact your account
  // manager if you wish to enable real-time feedback.
  //
  message BidResponseFeedback {
    // The unique id from BidRequest.id
    optional bytes request_id = 1;

    // The index of the creative within the BidResponse if there was more than
    // one. The index starts at zero for the first creative. This is usually the
    // index of the BidResponse.Ad, but may be the
    // BidResponse.Ad.TemplateParameter if you use a template ad.
    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;

    // The second price cpm in micros of your account currency if your bid won
    // the auction, or the winning bid that must be exceeded to win the auction
    // if your ad did not win. This is only set if your bid participated in the
    // auction. It is not set if the bid was filtered prior to the auction. It
    // is also witheld 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.
    optional int64 cpm_micros = 4;
  }
  repeated BidResponseFeedback bid_response_feedback = 44;

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 doesn't submit a bid request. Nothing.
The buyer submits a bid request that gets filtered out before reaching the auction. The creative status code (see creative-status-codes.txt).
The buyer submits a bid request but loses the auction. The price (not the clearing price) in the buyer's local currency to win the auction and the creative status code 79 (outbid in auction). Note that the price is not set if the buyer that won the auction has opted out of sharing price feedback.
The buyer submits a bid request and wins the auction. The clearing price and creative status code 1.

Back to top