Multi-Bid Module

[bretg]

Type of issue

New Module

Description

Allowing a single bidder to multi-bid into an auction has several use cases:

• allows a bidder to provide both outstream and banner
• supports the video VAST fallback scenario
• allows one bid to be blocked in the ad server and the second one still considered
• add extra high-value bids to the cache for future refreshes

This proposal expands the number of key value pairs going to the ad server in the normal Prebid way by establishing the concept of a "dynamic alias" -- a bidder code that exists only on the response, not in the adunit. The publisher defines which bidders can multi-bid and how many bids they can make.

e.g. bidderA is allowed to provide 2 bids into the auction. PBJS might send these values to the ad server:
hb_pb_bidderA = 5.00
hb_pb_bidA2 = 3.00
...

The proposed configuration fo the module:

pbjs.setConfig({
    multibid: [{
        bidder: "bidderA",
        maxBids: 2,
        targetBiddercodePrefix: "bidA"  
    },{
        bidder: "bidderB",
        maxBids: 3,
        targetBiddercodePrefix: "bidB"
    },{
        bidders: ["bidderC","bidderD"]
        maxBids: 3
        // don't send extra bids to ad server, just cache good ones
    }]
});

But it's desired that this feature also work for SDK and AMP, so full Prebid Server is required as well.

Requirements

Prebid.js

1. The multi-bid functionality should be part of an optional module.
2. The publisher should be able to allow certain bidders the ability to return one or more "extra" bids, up to a publisher defined quantity capped at 9.
3. One destination of extra bid(s) should be the ad server, converting the extra bids to use a "target biddercode" that's like a kind of dynamic alias that exists only on the bid response.
4. If bid caching is turned on, extra bids should automatically be added to the cache as if they came from the primary biddercode.
5. The extra bids must receive different bidids.
6. The targeting biddercode used for the extra bids should be definable as a base pattern prefix that will be appended with a dynamic 'index' starting from 2. e.g. "bidA2, bidA3". Practically speaking, the base of the dynamic aliases will need to be 5 characters or less because the longest base attribute name is 14 chars (hb_cache_host_) and attributes are truncated at 20 chars.
7. If floors are active, extra bids should only be accepted if they meet the floor defined in the floors module.
   a) The ad server targeting variables created for dynamic aliases are the same as those created for the main biddercode. i.e. the list of variables is defined in targetingControls.allowTargetingKeys.
8. Extra ad server targeting variables for dynamic aliases are subject to all targeting controls, including: targetingControls.auctionKeyMaxChars and sendBidsControl.bidLimit. Secondary bids should be removed from targeting before primary bids.
9. The pbsBidAdapter in PBJS must send ext.prebid.multibid configuration OpenRTB to Prebid server.
10. The pbsBidAdapter must be able to parse extra bids out of a PBS response.
11. PBJS must accept the additional bids from any 'dynamic aliases' generated by Prebid Server bids.
12. PBJS analytics adapters must be able to report against the dynamic alias. To do this, PBS-core should store a link from multi-bid responses to the original bidder. e.g. "bidresponse.bidder: bidderA" and "bidresponse.targetingbidder: bidAa". This will enable analytics adapters to link.
13. The various "getTargeting" routines should be updated to obtain extra bids from cache if the bid response didn't contain more than one bid but the bidder is allowed to have more.
14. The dfpAdServerVideo module needs to be able to pass multiple bids from the same bidder to the video player.
15. The system should support specifying a single bidder, in which case targetbiddercodeprefix is allowed. Or the user can specify multiple bidders, in which case targetbiddercodeprefix is not allowed. This is to support the scenario where multiple bids are allowed but just cached, not sent to the ad server.
16. If targetbiddercodeprefix is not specified, Prebid.js should still cache any additional bids but without setting targeting variables.

Note: It's not clear that the existing PBJS bid_response hook has access to all bids from the bidder. It may have to be moved or a new hook added?

Prebid Server

Prebid Server must be able to support multi-bidding as well. See prebid/prebid-server#1715

The proposed PBS OpenRTB Request enhancement is basically the same as the PBJS config:

{
  ...
  ext: {
    prebid: {
      multibid: [{
        bidder: "bidderA",
        maxbids: 2,
        targetbiddercodeprefix: "bidA"
      },{
        bidders: "bidderB",
        maxbids: 3,
        targetbiddercodeprefix: "bidB"
      }]
    }
  }
}

[bretg]

Updated based on community feedback:

• changed targetBiddercodePattern to targetBiddercodePrefix.
• the index will automatically be appended and start from 2

[bretg]

docs PR prebid/prebid.github.io#2757

[ChrisHuie]

closing with merge of #6404