Configuring an Exchange Bidding Integration

This guide provides information on setting up your exchange for DFP exchange bidding in dynamic allocation.

To make your exchange available to DFP publishers for exchange bidding in dynamic allocation, configure a customized exchange 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 not required for each publisher integration.

Supported protocols and encoding

Exchange bidding uses the Ad Exchange 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)
    Setting "nurl" will result in a PROTO_PARSE_ERROR. As a workaround for win notifications, buyers may use impression and click requests. 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. The major loss of not having a separate win notification is that buyers can't use that to provide ad markup--that has to be provided by the bid responses.
  • ${AUCTION_CURRENCY}
    Replaced by the empty string.
  • Macro substitution is only supported in impression_tracking_url 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.
  • 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.

Resources

Receive bid requests with BidRequest

Exchange bidding uses the same bidrequest structure as Ad Exchange, 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 DFP.
  • The dfp_ad_unit_code field contains the publisher's DFP network code and DFP ad unit code.
  • The BidRequest.wseat and Deal.wseat fields are not populated, and any value received in the BidResponse.SeatBid.seat 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

An exchange must respond to each bid request in 160ms. To return a "no bid" response, simply return a 204 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). AdX requires that the click_through_url (adomain) field is populated with the creative's landing page domain or the full URL.

List of Bid fields supported for exchanges

Support for Preferred Deals and Private Auctions

When using Preferred Deals (PD) and Private Auctions (PA) with exchange 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:
    OPEN_AUCTION = 0;
    PRIVATE_AUCTION = 1;
    PREFERRED_DEAL = 2;
    

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

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

id: "ECHO_BIDREQUEST_ID"
seatbid {
  bid {
    id: "BID_ID"
    impid: "1"
    price: 1.23
    adm: "AD_TAG"
    adomain: "DECLARED_LANDING_PAGE_URL"
    cid: "BILLING_ID"
    crid: "CREATIVE_ID"
    dealid: "DEAL_ID"
    w: 300
    h: 250
    [com.google.doubleclick.bid] {
      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.

OpenRTB JSON

Request and response samples for OpenRTB using JSON.

OpenRTB Protobuf

Request and response samples for OpenRTB using protobuf.

Send feedback about...

Real-Time Bidding Protocol
Real-Time Bidding Protocol