Build the Response

After your application processes the bid request from Google, it must build and send a response. This guide explains how to code your application to build the response.

Create BidResponse message

Ad Exchange sends out the BidRequest as the message body of an HTTP POST. The response your application sends must have the Content-Type header set to application/octet-stream and a message body consisting of a serialized protocol buffer. The protocol buffer is a BidResponse message as defined in realtime-bidding.proto. Your application must return a parsable BidResponse in response to every BidRequest. Timeouts and responses that cannot be parsed are considered errors and Google throttles back bidders with high error rates.

If you do not wish to bid on an impression, you can set the processing_time_ms field alone, and leave all other fields empty. You can obtain realtime-bidding.proto from the reference data page.

Creative ID

Your BidResponse specifies a creative through the buyer_creative_id field (64 byte limit). Even similar creatives must have unique values for buyer_creative_id if they differ in any notable characteristics, including but not limited to: size, declared URL, creative attributes, and vendor types. In other words, you must give different creative IDs to any two ads which:

  • Look or behave differently.
  • Render to different images.
  • Render by different means (for example, one ad consists of an image, while the other contains Flash).

As you design your application, you should decide on a systematic way of generating identifiers that makes sense for the kinds of creatives you plan to submit.

Ad attributes

You must declare the creative attributes which describe fully the ad's characteristics and its targeting in BidResponse.Ad.attribute. The attributes that must be declared are (see also the full list of supported attributes at buyer-declarable-creative-attributes.txt):

  • 7 Tagging: IsTagged
    The ad contains within it a pixel or web-beacon for the purpose of creating a list of cookie IDs for subsequent re-marketing.
  • 8 CookieTargeting: IsCookieTargeted
    The ad targets consumers based on their cookie ID where the list of cookie IDs represents a set of consumers that previously interacted with a site owned or represented by the buyer.
  • 9 UserInterestTargeting: IsUserInterestTargeted
    The ad targets consumers based on their cookie ID where the list of cookie IDs represents a set of consumers the buyer defined as a common interest group.
  • 30 InstreamVastVideoType: Vpaid
    The ad requires VPAID support to render.
  • 32 MraidType: MRAID
    The ad requires the MRAID API to render.

In addition, the following attributes are supported but their declaration is not required, because Ad Exchange automatically detects them, and will block (or allow) your creatives based on the detected values, rather than your declaration. See Creatives API for explanation on how to get feedback regarding the detected properties of your creatives.

  • 34 RichMediaCapabilityType: RichMediaCapabilityFlash
    The ad requires Flash support to render.
  • 50 RichMediaCapabilityType: RichMediaCapabilityNonFlash
    The ad does not require Flash to render.
  • 47 RichMediaCapabilityType: RichMediaCapabilitySSL
    The ad has the ability to render on an SSL page. Note that Ad Exchange treats creatives with different declared values of this attribute as distinct (they will be reviewed separately and have distinct approval status). Therefore, if you bid with both SSL and non-SSL versions of the same creative, you should declare this attribute accordingly, so that this distinction is properly reflected in AdX.

Recommendations

  • Enable persistent HTTP connections (also known as "HTTP keep-alive" or "HTTP connection reuse") on your servers. Set the timeout to 10 seconds at minimum—higher values are beneficial in many cases. Google verifies this during the initial latency tests of your application, because Ad Exchange sends requests at a high rate and needs to avoid the latency overhead of establishing a separate TCP connection for each request.
  • Include the optional impression tracking URL to track when the impression renders rather than when the bidder wins. Because of the dropoff between wins and renderings, this yields more accurate tracking statistics.
  • Keep your bidder code free of dependencies on deprecated fields, which can cause your bids to fail with errors.
  • It is good practice to include the BidResponse.Ad.width and BidResponse.Ad.height in your BidResponse. A BidResponse to a request that includes multiple ad sizes must include the width and height values or it will be dropped from the auction.
  • Keeping your response size under 8K is highly recommended. Very large responses may increase network latency and cause timeouts.

Example bid response

The following example shows a BidResponse protocol buffer in text format as created with TextFormat::SerializeToString().

protocol_version: 1
ad <
  html_snippet: "<img src='my-image-adserver.com/1234567'/>"
  click_through_url: "https://my.click-through.com"
  buyer_creative_id: "my-creative-1234ABCD"
  category: 3
  adslot <
    id: 1
    max_cpm_micros: 1500000
  >
>
processing_time_ms: 3

Important: Never return text format in a real response. Always serialize the bid response object.

You can create and serialize a BidResponse message using the following C++ code:

BidResponse bid_response;
// fill in bid response with bid information
string post_response;
if (bid_response.SerializeToString(&post_response)) {
  // respond to the POST with post_response as the content
} else {
  // return an error to the POST
}

Specify creative

Your bid response specifies the creative to serve if your bid wins, using the html_snippet field.

Specify an ad that is hosted on your own server(s) using an HTML snippet in the html_snippet field of the BidResponse. The snippet is enclosed in an iFrame inserted in the web page, resulting in the ad being retrieved and rendered when the page is loaded. You must craft the snippet so that the ad renders correctly inside an iFrame, and at an appropriate size for the ad slot you are bidding on.

The html_snippet field supports any valid HTML code that renders properly, but keep in mind the restrictions on specifying the buyer_creative_id field in the Create BidResponse message section. One use for this is to put extra information into arguments of the URLs that are fetched from your servers as part of rendering the ad. This enables you to pass arbitrary data about the impression back to your own servers.

Most policies for HTML snippets returned in bid responses are the same as for third-party ads. See Ad Exchange Buyer Program Guidelines, Requirements for third-party ad serving and Declare click-through URLs in ads for more information.

Specify macros

The HTML snippet that defines a creative can include one or more special constructs called macros. At ad serving time, values are substituted for macros. For example, your client bidding application could use the WINNING_PRICE macro to determine how much it paid for the ad, if it wins the auction. To parse this macro, you will need to implement an application that decrypts price confirmations. Refer to the Decrypting Price Confirmations page for more information.

Specify a macro as part of an HTML snippet in the format %%MACRO%%, where MACRO is one of the supported macros listed in the table below.

Google requires that you use use either the CLICK_URL_UNESC or the CLICK_URL_ESC macros within the creative of the third-party served ad. Google uses the CLICK_URL macros for click tracking.

To use a macro, include it in the ad so that the URL gets fetched when someone clicks on it. The return value of the fetch is a redirect to another URL that you append to the CLICK_URL.

Macro Description
ADVERTISING_IDENTIFIER Allows buyers to receive iOS IDFA or Android's Advertising ID on impression rendering. See Decrypting Advertiser Identifiers for details.
CACHEBUSTER A string representation of a random, unsigned, four-byte integer.
CLICK_URL_UNESC

The unescaped click URL for the ad. In the snippet, an escaped version of the third party click URL should directly follow the macro.

For example, if the third-party click URL is http://my.adserver.com/some/path/handleclick?click=clk, then the following code could be used with the single-escaped version of the third party click URL following the macro invocation:

<a href="%%CLICK_URL_UNESC%%http%3A%2F%2Fmy.adserver.com%2Fsome%2Fpath%2Fhandleclick%3Fclick%3Dclk"></a>

At ad serving time, this is expanded to:

<a href="http://google-click-url?...&ad_url=http%3A%2F%2Fmy.adserver.com%2Fsome%2Fpath%2Fhandleclick%3Fclick%3Dclk"></a>

The URL will first register the click with Google, and then redirect to the third party click URL.

CLICK_URL_ESC

The escaped click URL for the ad. Use this instead of CLICK_URL_UNESC if you need to first pass the value through another server that will then return a redirect.

For example, the following code could be used in an HTML snippet:

<a href="http://my.adserver.com/click?google_click_url=%%CLICK_URL_ESC%%"></a>

At ad serving time, this is expanded to:

<a href="http://my.adserver.com/click?google_click_url=http://google-click- url%3F...%26ad_url%3D"></a>

This will register the click with my.adserver.com which will then be responsible for redirecting to the URL passed in the google_click_url parameter. This assumes that my.adserver.com unescapes the google_click_url parameter.

You can append a double-escaped URL after %%CLICK_URL_ESC%%. After the unescaping is done by my.adserver.com, that leaves a single-escaped version of the URL appended to the google_click_url. When the google_click_url is fetched, it will unescape once more and then redirect.

CLICK_URL_ESC_ESC

The double-escaped URL for the ad. Use this instead of CLICK_URL_UNESC if you need to first pass the value through another server that will then return a redirect.

For example, the following code could be used in an HTML snippet:

<a href="http://my.adserver.com/click?google_click_url=%%CLICK_URL_ESC_ESC%%"></a>

At ad serving time, this is expanded to:

<a href="http://my.otheradserver.com/click?google_click_url=http%3A%2F%2Fmy.adserver.com%2Fclick%3Fgoogle_click_url%3Dhttp%3A%2F%2Fgoogle-click-%20url%253F...%2526ad_url%253D"></a>
SCHEME Expanded to http: if the bid request does not require SSL or to https: if the bid request requires SSL.
SITE The url-escaped domain of the content URL or the anonymous ID for anonymous inventory.
SITE_URL Deprecated. Replaced by the SITE macro which provides identical functionality.
TZ_OFFSET The time-zone offset.
WINNING_PRICE The encoded impression cost (that is, CPI rather than CPM) in micros of the account currency. For example, a winning CPM of $5 USD corresponds to 5,000,000 micros CPM, or 5,000 micros CPI. The decoded value of WINNING_PRICE in this case would be 5,000. The winning price is specified in CPI.
WINNING_PRICE_ESC URL-escaped WINNING_PRICE.

URL escaping in macros uses the following scheme:

  • The space character is replaced by a plus sign (+).
  • Alphanumeric characters (0-9, a-z, A-Z) and characters from the set !()*,-./:_~ remain unchanged.
  • All other characters are replaced by %XX, where XX is the hexadecimal number representing the character.

Publisher restrictions

Publishers use the BidRequest to pass restrictions on what ads they will allow. You are required to enforce the restrictions in these fields:

  • allowed_vendor_type
  • excluded_attribute
  • excluded_sensitive_category

One field specifies allowed features of the ad and the other specifies disallowed features. Never return an ad with a disallowed feature. For allowed features such as vendor type, return an ad only if its vendor type is in the allowed_vendor_type list in the BidRequest. See the comments for these fields in the BidRequest protocol buffer definition for more details.

If an HTML snippet is returned in BidResponse, you are required to accurately set the attribute, category, and click_through_url fields in the BidResponse. If an ad has multiple applicable values for these fields, then you must include every value. See the comments for these fields in the BidResponse protocol buffer definition for more details. Responses that do not have these fields set are discarded.

The possible values of BidRequest.excluded_attribute are (see publisher-excludable-creative-attributes.txt):

  • 7 Tagging: IsTagged
    Ads are disallowed if they contain a pixel or web-beacon for the purpose of creating a list of cookie IDs for subsequent re-marketing.
  • 8 CookieTargeting: IsCookieTargeted
    Ads are disallowed if they target consumers based on their cookie ID where the list of cookie IDs represents a set of consumers that previously interacted with a site owned or represented by the buyer.
  • 9 UserInterestTargeting: IsUserInterestTargeted
    Ads are disallowed if they target consumers based on their cookie ID where the list of cookie IDs represents a set of consumers the buyer defined as a common interest group.
  • 21 CreativeType: Html
    Ads are disallowed to use the html_snippet or snippet_template field in BidResponse.Ad.
  • 22 CreativeType: VastVideo
    Ads are disallowed to use the video_url field in BidResponse.Ad.
  • 30 InstreamVastVideoType: Vpaid
    Ads are disallowed to require VPAID support to render.
  • 32 MraidType: MRAID
    Ads are disallowed to require the MRAID API to render.
  • 34 RichMediaCapabilityType: RichMediaCapabilityFlash
    Ads are disallowed to require Flash support to render.
  • 39 RichMediaCapabilityType: RichMediaCapabilityHTML5
    Ads are disallowed to require HTML5 features to render.
  • 48 RichMediaCapabilityType: RichMediaCapabilityNonSSL
    Ads are disallowed to make non-SSL requests.

Therefore, if the excluded_attribute field contains the value 7, then you should not return an ad that uses a pixel or web-beacon for creating a list. Note that if an ad does this, then it must set the value 7 in the attribute field of the BidResponse. Similarly, if the excluded_attribute field contains the value 48, then you should only return ads that can render on an SSL page (and accordingly declare attribute 47 RichMediaCapabilityType: RichMediaCapabilitySSL).

Also the excluded_sensitive_category field in the BidRequest uses codes from the ad-sensitive-categories.txt file available on the reference data page. Here are extended descriptions of some of these codes:

  • 3 Politics
    Includes politics or controversial social issues; does not include ads for news organizations that are not generally associated with a partisan viewpoint on issues.
  • 4 Dating
    Includes dating services and online dating communities.
  • 5 Religion
    Includes religious ads and ads advocating for or against religious views; does not include astrology or non-denominational spirituality.
  • 7 Video Games (Casual & Online)
    Includes video games, online games and downloadable games; does not include video game consoles.
  • 8 Ringtones & Downloadables
    Mobile add-ons including ringtones, and other downloadable goodies such as screensavers and wallpapers for desktop PCs and profile layouts and graphics for social networks.
  • 10 Get Rich Quick
    Schemes promising rapid earnings.
  • 18 Weight Loss
    Includes weight loss, dieting, and related products and programs; does not include healthy eating or general fitness ads.
  • 19 Cosmetic Procedures & Body Modification
    Includes lifts, suctions, lasers, hair removal and restoration, tattoos, and body modification.
  • 23 Drugs & Supplements:
    Includes pharmaceuticals, vitamins, supplements, and related retailers; does not include resources providing information about drugs.
  • 24 Sexual & Reproductive Health
    Includes sexual function and fertility ads; does not include normal pregnancy resources.

Sample bid responses

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

App banner

App interstitial

App interstitial video

App native

Web video

Send feedback about...

Real-Time Bidding Protocol
Real-Time Bidding Protocol