Bid on Behalf of Multiple Accounts

A bidder can purchase inventory for multiple entities in a single bid, if those entities are Ad Exchange clients. For example, a demand-side platform (DSP) might use its bidder to purchase inventory for several marketers or agencies who are themselves Ad Exchange clients. This guide explains how to code your bidder to process a single request sent on behalf of multiple Ad Exchange clients.

Background

Ad Exchange works with ad networks, agency trading desks, and demand-side platforms (DSPs). In some scenarios, an ad network or agency trading desk may choose to work with one or more DSPs. There are two implementation options available for clients who work through a DSP:

  • The DSP purchases inventory for marketers or agencies that are not Ad Exchange clients. In this case, the DSP receives one bid request and responds with one bid. Google bills the DSP directly.
  • The DSP purchases inventory for marketers or agencies that are Ad Exchange clients. Ad Exchange clients are required to bid independently, even when they use a DSP. This is to ensure publishers have visibility of the actual buyer, to enable exclusive allocations of inventory, and to ensure no redirects go from network to network. In this model, Google bills the Ad Exchange client, not the DSP. The rest of this guide focuses on this scenario.

Ad Exchange routes bid requests for child accounts of a parent bidder (DSP) through ad group IDs. A child account is expected to set up pretargeting for both campaigns and ad groups, and to provide the ad group ID of the pretargeting along with any other requested fields to its DSP. The DSP uses this information to process the bid response.

There are two options for DSPs who have Ad Exchange clients using the DSP's technology to buy from Ad Exchange:

  • Receive a consolidated callout for a set of RTB clients. This scenario is described in this document.

  • Receive separate, multiple, RTB callouts for each Ad Exchange client buying through the DSP. In this case the DSP receives a separate HTTPS request for each account that configures the DSP's server as the associated URL. These calls come into the DSP's servers independently, allowing for easy load-balancing and logical separation of clients.
  • Receive a consolidated callout for a set of RTB clients. This scenario is described in this guide.

Setup and pretargeting

A DSP can choose to have multiple requests consolidated into a single HTTP request. To be configured for consolidated callouts, the DSP must sign an additional contract. Contact your account manager to arrange this.

For DSPs configured for consolidated requests, pretargeting criteria selection can be done on the parent bidder level for all child accounts. This is called Bidder Level Pretargeting (BLP). With BLP, inventory matching is only done on the parent bidder level regardless of the child account configuration. This simplifies the workflow and makes it easier to manage inventory and settings across many accounts.

Benefits of bidder level pretargeting vs. regular pretargeting

Bidder-level pretargeting Regular pretargeting
Parent seat manages eligibility for all seats Each seat manages their own inventory eligibility
All seats eligible for all traffic Varying pretargeting setups across many accounts
Simpler setup and easier to manage Less control at parent bidder level, but granular control for specific seats

Every pretargeting match is included as one entry in the matching_ad_data field of the BidRequest. Only one ad group from a child account will be sent, so as a best practice, only one ad group should be active for each child seat. If there is more than one ad group, the matching_ad_data entry will include the numerically lowest active ad group ID per child seat. Buyers can use the BillingInfo to gather all active ad group IDs.

When responding to a BidRequest that contains pretargeting matches from an account other than the parent account (i.e., any BidRequest for which the matching_network_data field is set), the billing_id field in the BidResponse is required so that Ad Exchange knows which account and campaign to associate with the bid. Any response that does not set the field is dropped. The field remains optional for any BidRequest that only includes pretargeting matches from the bidder account. A response to a BidRequest that contains pretargeting matches from multiple accounts can return multiple ads.

Bidder level pretargeting example

Child seat (ad group ID: 123) Parent seat (ad group ID: 124)
Pretargeting: US + EU Pretargeting: US + APAC
Callout criteria billing_id sent
US only 123 + 124
EU only 123
APAC only 124

Example BidRequest

Here is an example of a BidRequest:

protocol_version: 1
id: "Mv\2005\000\017.\001\n\345\177\307X\200M8"
ip: "\314j\310\004"
user_agent: "Mozilla/5.0 (Windows; U; Windows NT 5.1; en-US) AppleWebKit/534.13
 (KHTML, like Gecko) Chrome/9.0.597.107 Safari/534.13,gzip"
country: "US"
region: "US-MA"
city: "Boston"
metro: 506
url: "http://www.example.com/"
detected_language: "en"
detected_vertical {
  id: 22
  weight: 0.67789277
}
detected_vertical {
  id: 355
  weight: 0.32210726
}
adslot {
  id: 1
  width: 300
  height: 250
  excluded_attribute: 7
  excluded_attribute: 22
  matching_ad_data {
    billing_id: 19435125776
    billing_id: 9160285016
    minimum_cpm_micros: 10000
  }
  targetable_channel: "all pages,middle right"
  publisher_settings_list_id: "I\034\334o~)\367\034\020\230E#\235w\212"
  publisher_settings_list_id: "W\024c\\\200o\2214\242\323\302\362A_\2"
  slot_visibility: BELOW_THE_FOLD
}
is_test: false
cookie_version: 1
google_user_id: "CAESEIcS1pC2TBvb-4SLDjMqsY9"
seller_network_id: 1
publisher_settings_list_id: "\357\237V\206)\231\3125%|$\032\""
vertical_dictionary_version: 2
timezone_offset: -300
cookie_age_seconds: 7685804

Send feedback about...

Real-Time Bidding Protocol
Real-Time Bidding Protocol