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

Authorized Buyers 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 want 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 Remarketing: IsRemarketing
    The ad targets consumers based on their cookie ID or Device ID where the list of cookie IDs or Device IDs represent 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 or Device ID where the list of cookie IDs or Device ID represent 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 Authorized Buyers 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 Authorized Buyers 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.

Open Bidding fields

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

OpenRTB Authorized Buyers Details

The deal ID from the exchange's namespace that is associated with this bid and reported to publishers.


The type of deal reported to publishers, affecting how the deal is treated in the auction.

BidResponse.seatbid[].bid[].ext.third_party_buyer_token[].adslot[].third_party_buyer_token Token used to identify end third-party buyer information if the 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.


  • Enable persistent HTTPS connections (also known as "keep-alive" or "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 Authorized Buyers 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.
  • Include 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.
  • Limit your response size to under 8K. Very large responses may increase network latency and cause timeouts.
  • Follow the guidelines for bids on iOS inventory that require SKAdNetwork attribution.

Example bid response

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



OpenRTB Protobuf

Important: The Protobuf messages depicted in the samples are represented here as human-readable text. However, that is not how the messages are sent over the wire. When using the Google or OpenRTB Protobuf format, only serialized BidResponse messages will be accepted.

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. Your bid must include one of the supported ad formats (AMP, video, native). In this example, we specify the creative using the html_snippet field.

Alternatively, you can specify your creative using one of the following fields, based on ad format:

  • SDK rendered ad
    • BidResponse.Ad.sdk_rendered_ad
  • AMP
    • BidResponse.Ad.amp_ad_url
  • Video
    • BidResponse.Ad.video_url or
    • BidResponse.Ad.video_vast_xml
  • Native
    • BidResponse.Ad.native_ad

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 HTML snippet so that the ad (banner or interstitial) renders correctly inside an iFrame, and at an appropriate size for the ad slot you are bidding on.

In addition, the ad size declared in the bid response must match exactly one of the size combinations in the bid request when:

  • An ad is a regular banner (not video, native, or interstitial).
  • The bidder has declared the size in the bid response. Size declaration is required whenever more than one size is present in the request.
  • An exception is made for interstitial ads. For interstitials the width must be at least 50% of the screen width and the height to at least 40% of the screen height.

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 Authorized Buyers 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 CLICK_URL_ESC macro 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.

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, then the following code could be used with the single-escaped version of the third party click URL following the macro invocation:

<a href=""></a>

At ad serving time, this is expanded to:

<a href="http://google-click-url?...&"></a>

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


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=""></a>

At ad serving time, this is expanded to:

<a href=" url%3F...%26ad_url%3D"></a>

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

You can append a double-escaped URL after %%CLICK_URL_ESC%%. After the unescaping is done by, 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.


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=""></a>

At ad serving time, this is expanded to:

<a href=""></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.
VERIFICATION The different values for production and when the creative is scanned in the verification pipeline. The format is: %%?VERIFICATION:true-val:false-val%% where any values except macros can be used for true-val and false-val, including empty strings. For Open Bidding, we recommend that exchanges use this macro; once they do so, demand-side platforms do not need to make changes.

For example if a creative were to include %%?VERIFICATION:-1:5000%% then the text replacement would be 5000 on serving and -1 in the verification pipeline. This is to help differentiate between these two sets of pings.
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.

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.
  • 35 Social Casino Games
    Includes simulated gambling games (including, without limitation, poker, slots, bingo, lotteries, sports betting, betting on races, as well as other card games and casino games) where there is no opportunity to win anything of value (such as money or prizes).
  • 36 Significant Skin Exposure
    Ad images where any part of the human body from the sternum to the mid-thigh is not clothed; or the body is clothed in underwear, swimwear, lingerie, or other see-through clothes or non-clothing items such as a towel or bed sheet.
  • 37 Sensationalism
    Ads that aim to induce users to click them by appealing to their curiosity, often using a teaser message with hyperbolic language or imagery. Includes ads that center around sensationalistic subjects (such as celebrity arrests, deaths, or divorces) or aim for shock value.

Open Measurement

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

Supported ad formats currently include video, banner, and interstitial ads. For more information on how to use Open Measurement in a bid response containing these formats, refer to the Open Measurement SDK Help Center article.

Sample bid responses

The following sections show sample bid responses 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