Configuring an Open Bidding Integration

This guide helps exchanges leverage Open Bidding to access Google Ad Manager inventory.

To make your exchange available to Ad Manager publishers for Open Bidding, configure a customized Open Bidding integration and send bidder endpoints to your Google account manager for testing to verify that the integration functions correctly. This is a one-time process and is not required for each publisher integration.

Supported protocols and encoding

Open Bidding uses the Authorized Buyers and OpenRTB real-time bidding (RTB) protocols. Learn more.

Supported versions

  • AdX standard protocol with Protobuf encoding
  • OpenRTB 2.5 protocol with Protobuf encoding
  • OpenRTB 2.5 protocol with JSON encoding
  • OpenRTB 2.4 protocol with Protobuf encoding
  • OpenRTB 2.4 protocol with JSON encoding
  • OpenRTB 2.3 protocol with Protobuf encoding
  • OpenRTB 2.3 protocol with JSON encoding
  • OpenRTB 2.2 protocol with JSON encoding

OpenRTB exceptions

Unsupported fields

  • Bid.nurl (win notifications)

    nurl is not supported and will be ignored if populated in the bid response. As a workaround for win notifications, buyers may use impression and click requests and real-time feedback. Normally when a bidder wins the auction, they will eventually receive at least an impression, which can contain the winning price and also other information they can put in impression URL parameters.


    Replaced by the empty string.

  • Macro substitution is supported in impression_tracking_url, burl, and adm

    Macro substitution doesn't apply to any other string fields of the bid response given other restrictions on those fields. For example, crid must not be unique per impression.

Specific requirements for campaign ID and creative ID

  • Bid.cid (campaign ID)
    Must be set to the same value as billing_id would be in the AdX bid response. If this is not set properly, a BAD_ADGROUP error is thrown. If only one billing_id is present in the bid request, any bid is assumed to be a bid for that billing_id regardless of what is sent in the response, this includes no billing_id in the response.
  • Bid.crid (creative ID)
    Must be set according to the same rules as for the buyer_creative_id in the AdX bid response (in particular, avoid per-impression uniqueness). Below is the comment on that field:
    // 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.


Receive bid requests with BidRequest

Open Bidding uses the same bidrequest structure as Authorized Buyers, but some fields are not sent to exchanges for exchange bidding requests.

  • The minimum_cpm_micros (AdX RTB) or bidfloor (OpenRTB) field contains the price to beat, calculated by Ad Manager.
  • The dfp_ad_unit_code field contains the publisher's Ad Manager network code and Ad Manager ad unit code.
  • The BidRequest.wseat and Deal.wseat fields are not populated, and any value received in the is ignored.
  • The Device.carrier field is populated with Google's carrier ID.

List of BidRequest fields sent in callouts to exchanges

Respond to bid requests with Bid

A demand source participating in Open Bidding must respond to each bid request within 160 to 300 ms (check the BidRequest.tmax field for the exact limit). To return a "no bid" response, simply return an HTTP 204 No Content with an empty payload.

  • For video requests, the ad.video_url (AdX RTB) or adm (OpenRTB) field must return a VAST URL or inline VAST XML. See example.
  • The ${AUCTION_PRICE} macro uses an encrypted value identical to the %%WINNING_PRICE%% macro.
  • Click-through URLs shouldn't be escaped (input "as-is" in the field). If the optional click_through_url (adomain) field is used, it must be populated with the creative's landing page domain or the full URL.

Note that duplicate pings can be caused by user devices for the impressions that were won in regular auctions. When this happens, all but one ping is marked as spam and only the remaining ping is billed.

List of Bid fields supported for exchanges

Google demand discrepancy resolution (Beta)

This feature aims to ensure that the number of impressions for which an exchange is billed aligns with the number of impressions that are paid by Google Display & Video 360 (DV360).

By accurately identifying DV360 impressions that were served by Open Bidding, Google can then adjust for ad spam and billable event discrepancies to make sure you are not billed for impressions for which you are not paid.

Propagate google_query_id in bid requests

In order to ensure that the number of valid impressions matches across Google demand, the google_query_id must be propagated as is from Open Bidding requests to Google demand platforms. This is a prerequisite to Open Bidding discrepancy resolution. The current expected length of the google_query_id is around 64 bytes.

Propagate third_party_buyer_token in bid responses

In the event that the Google demand platform wins an exchange's internal auction, third_party_buyer_token field must be propagated as is in the bid response back through the Open Bidding impression. This allows Google publisher platforms to establish that the winning bid from an Open Bidding partner is a bid on behalf of Google demand for the same impression opportunity. The current maximum length of this field is expected to be 150 bytes.

Pass Google creative markup as is in bid responses

In order to ensure that the discrepancy resolution applies to bids from Google demand, we request an exchange propagates Google creative markup without any wrappers (script tags, iframes, or VAST wrappers). Due to the discrepancy resolution, Google may invalidate and not invoice for those Open Bidding impressions that weren’t counted by Google demand platforms. We periodically check creative markup to confirm that bids with third_party_buyer_token were submitted on behalf of Google demand, and not any other buyer.

HTML5 creatives

We request that an exchange submits Google HTML markup as is, with exchange-specific macro expansions that normally apply, and, optionally, extra tracker pixels or scripts an exchange normally adds.

We are unable to apply discrepancy resolution if an exchange wraps Google HTML creative into a tag (script, iframe, or other techniques) that subsequently load or render Google HTML code.

VAST video creatives

We request that an exchange uses one of the following approaches to populate VASTTagURI in VAST XML responses:

  1. An exchange can preserve the value of VASTTagURI element as part of VAST XML document returned by Google in adm field as is, with exchange-specific macro expansions that normally apply.
  2. DV360 can populate the nurl field with a VAST document URL in bid responses to an exchange. An exchange can then pass the value of nurl that Google (DV360) responds with in VASTTagURI tag, with exchange-specific macros expanded normally as needed.

An exchange can specify additional VAST event and error trackers within VAST XML document if necessary.

Support for Preferred Deals and Private Auctions

When using Preferred Deals (PD) and Private Auctions (PA) with Open Bidding, the deal ID and type must be specified as follows:

  • Set the dealid field: This field is the deal ID from the exchange's namespace associated with the bid and reported to publishers. This is arbitrary UTF8 text and must be no more than 64 bytes.
  • Set the exchange_deal_type enum: This enum specifies the type of deal. This is reported to publishers and affects how the deal is treated in the auction. Possible values are:

See the AdSlot object under BidResponse in the RTB guide for more details.

Below is a sample OpenRTB bid response for PD/PA.

seatbid {
  bid {
    id: "BID_ID"
    impid: "1"
    price: 1.23
    adm: "AD_TAG"
    cid: "BILLING_ID"
    crid: "CREATIVE_ID"
    dealid: "DEAL_ID"
    w: 300
    h: 250
    [] {
      impression_tracking_url: "IMPRESSION_TRACKING_URL"
      exchange_deal_type: "DEAL_TYPE"

Cookie matching

Google hosts match tables and exchanges have the option to use one or both of the options below.

  • Buyer/exchange-initiated cookie matching. Learn more.
  • Google-initiated cookie matching ("pixel push" or "pixel match"). Learn more.
  • Cookie match assist. Learn more.

Cookie match assist (CMA)

Exchanges currently use cookie matching (exchange-initiated user sync) and pixel push (Google-initiated user sync) to create a mapping between Google user IDs and the exchange's user IDs (typically in a Google-hosted cookie match table). Cookie match assist offers more cookie matching opportunities for exchanges to build up their own match tables with their DSP/networks.

How it Works:

  1. The exchange provides a single cookie matching URL dedicated to cookie match assist, which points to the exchange's own server.
  2. The exchange provides a quota for CMA requests so Google doesn't overload their server with cookie match requests.
  3. Google configures the CMA URL and CMA quota for the exchange's Exchange Bidding account.
  4. Similar to pixel push functionality, Google selects an exchange and executes CMA on their behalf:
    1. Google drops an empty 1x1 pixel on the client that points to the CMA URL provided in step #1 above.
    2. The exchange's server identifies the user, dynamically decides which single bidding partner (DSP, network) it wants to match that user with (based on its own match tables), and then redirects to the selected bidding partner using the exchange's own cookie matching service.
    3. The bidding partner then redirects back to the exchange with the user ID to be stored in the cookie match table.

Implementation Notes:

  • In step 4b above, only one bidder partner may be chosen—no chaining of cookie match requests is allowed.
  • In the future, we will require the exchange to redirect back to Google signaling a successful CMA request/response. If Google doesn't receive the redirect back from the exchange, Google will consider the response unsuccessful and will throttle the quota of CMA requests.

Managing latency

We recommend you use these reference domains to estimate latency between your bidder endpoints and each of our four trading locations. Learn more about trading locations.

We also recommend that any larger exchange receiving a large volume of requests consider setting up a peering arrangement with us to reduce latency and latency volatility. Learn more about peering.

Click macros

We recommend that you consider implementing click macros. This will allow reporting that includes clicks and click-derived metrics for your account and for the publishers you work with. Learn more.

Additional resources

Sample bid requests and responses

This section contains examples of bid requests and responses for OpenRTB, using both JSON and protobuf.


Request and response samples for OpenRTB using JSON.

OpenRTB Protobuf

Request and response samples for OpenRTB using protobuf.