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.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 not sent in callouts to exchanges

AdX RTB OpenRTB
hyperlocal_set
encrypted_hyperlocal_set
Geo.lat
Geo.long
user_demographic User.yob
User.gender
detected_vertical User.data
detected_content_label Content.contentrating
slot_visibility Banner.pos
iframing_state Banner.topframe
publisher_settings_list_id ImpExt.publisher_settings_list_id
excluded_sensitive_category BidRequest.bcat
allowed_vendor_types BidExt.allowed_vendor_type
direct_deal Deal.id
is_mobile_web_optimized Site.mobile
viewability
click_through_rate
iframing_depth
mediation_status
bid_response_feedback
is_predicted_to_be_ignored
auto_refresh
stickiness
allowed_restricted_category
allowed_restricted_category_for_deals
Buyer_pricing_rules

Respond to bid requests with BidResponse

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.
AdX RTB Open RTB
Required: ad.buyer_creative_id
ad.html_snippet or ad.video_url
ad.click_through_url
ad.width
ad.height
ad.ad_slot.max_cpm_micros
ad.ad_slot.id
Bid.crid
Bid.adm
Bid.adomain
Bid.w
Bid.h
Bid.price
Optional: impression_tracking_url
ad.ad_slot.billing_id
BidExt.impression_tracking_url
Bid.cid
Unsupported: category
advertiser_name
restricted_category
vendor_type
min_cpm_micros
Bid.api
Bid.attr
Bid.cat

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.

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