multibid docs

dev-docs/modules/index.md

@@ -35,10 +35,11 @@ If you are looking for bidder adapter parameters, see [Bidders' Params]({{site.b
 | [**Google Ad Manager Express**](/dev-docs/modules/dfp_express.html) | A simplified installation mechanism for publishers that have Google Publisher Tag (GPT) ad calls in their pages. |
 | [**Supply Chain Object**](/dev-docs/modules/schain.html) | Validates and makes the Supply Object available to bidders |
 | [**User ID**](/dev-docs/modules/userId.html) | Sub-modules are available to support a range of identification approaches. |
+| [**ID Import Library**](/dev-docs/modules/idLibrary.html) | Retrieve user ids deployed on your site, and return them to a configurable endpoint for ID Graphing |  
 | [**Advanced Size Mapping**](/dev-docs/modules/sizeMappingV2.html) | Display Responsive AdUnits in demanding page environments. |
 | [**Price Floors Module**](/dev-docs/modules/floors.html) | Configure and enforce minimum bids. |
 | [**GPT Pre-Auction Module**](/dev-docs/modules/gpt-pre-auction.html) | Adds a PB Ad Slot and matching GAM ad unit name to each ad unit's first-party data before bid requests are sent to the adapters. |
-| [**ID Import Library**](/dev-docs/modules/idLibrary.html) | Retrieve user ids deployed on your site, and return them to a configurable endpoint for ID Graphing |  
+| [**MultiBid Module**](/dev-docs/modules/multibid.html) | Allows bidders to send multiple bids to the ad server. |
 
 ## Real-Time Data Providers
 

dev-docs/modules/multibid.md

@@ -0,0 +1,107 @@
+---
+layout: page_v2
+page_type: module
+title: Module - MultiBid
+description: Allows bidders to return more than one bid response
+module_code : multibid
+display_name : MultiBid
+enable_download : true
+sidebarType : 1
+---
+
+# MultiBid Module
+{:.no_toc}
+
+* TOC
+{:toc}
+
+## Overview
+
+This module allows configured bidders to pass more than one bid per AdUnit
+through to the ad server.
+
+Without this module, bidders can place multiple bids on the bid cache, but only the
+highest bid will be considered for sending to the ad server.
+
+## Use Cases
+
+- Allows a bidder to provide bids on both outstream and banner.
+- Supports the ability of one bidder to provide multiple video bids for the fallback scenario.
+- Allows some bids to be blocked in ad server targeting logic while allowing other bids from the same bidder to be considered.
+
+There are two specific actions enabled by this module:
+
+1) It tells bidders how many bids will be considered. If [useBidCache](https://docs.prebid.org/dev-docs/publisher-api-reference.html#setConfig-Use-Bid-Cache) is on, more than one bid response per adapter can be registered. (Note that this is the case even without this module, but bid adapters might not know they can supply extra bids without the `multibid` config.)
+
+2) It expands the number of ad server targeting values that can go to the ad server.
+
+Here's an example configuration:
+
+```
+pbjs.setConfig({
+    multibid: [{
+        bidder: "bidderA",
+        // bidderA can supply up to two bids
+        maxBids: 2,
+	// the second bid will go to the ad server as hb_pb_bidA2
+        targetBiddercodePrefix: "bidA"  
+    },{
+        bidder: "bidderB",
+        // bidderB can supply up to three bids
+        maxBids: 3,
+	// additional bids will be passed as hb_pb_bidB2 and hb_pb_bidB3
+        targetBiddercodePrefix: "bidB"
+    },{
+        bidders: ["bidderC","bidderD"]
+        maxBids: 3
+        // don't send extra bids to ad server, just cache good ones
+    }]
+});
+```
+
+## Parameters
+
+MultiBid configuration takes these parameters:
+
+{: .table .table-bordered .table-striped }
+| Param | Required? | Type | Description | Example |
+| --- | --- | --- | --- | --- |
+| bidder | Yes, unless bidders is specified | string | A biddercode | `'bidderA'` |
+| bidders | Yes, unless bidder is specified | array of strings | Multiple biddercodes | `['bidderB','bidderC']` |
+| maxBids | Yes | integer | The number of bids the named bidder(s) can supply. Max of 9. | `2` |
+| targetBiddercodePrefix | No | string | An alternate (short) bidder code to send to the ad server. A number will be appended, starting from 2, e.g. hb_pb_PREFIX2. If not provided, the extra bids will not go to the ad server. | `'bidA'` |
+
+Note: Some bid adapters normally return more than one bid response per AdUnit. These
+bids are available to the `useBidCache` scenario even without this module.
+If those bidders are mentioned in the `multibid` config, the additional bids will
+become subject to the `maxBids` limit.
+
+## Building Prebid.js with the MultiBid Module
+
+The MultiBid module is not included with Prebid.js by default. To get this behavior, you must include the module in the build:
+
+```
+gulp build --modules=multibid,exampleBidAdapter
+```
+
+## Setting Up New Line Items
+
+Publishers don't need to set up more line items in the ad server unless they
+want to optimize a scenario where the primary bid might not match special targeting. Example scenarios include:
+
+- The publisher has set up special blocking on header bidding line items. For example: hb_adomin_bidderA not in "advA, advB, advC". In this case, the primary bid may be skipped over, so creating line items for the secondary bids could make sense.
+- There's ad targeting logic that could exclude outstream bids on certain ad units for certain bidders. For example: AdUnit="abc" and hb_format_bidderA not in "video". In this case, the bidder can return a banner bid as well as video.
+- The ad server supports video fallbacks, in which case multiple video bids from the same bidder can be part of the fallback list.
+
+
+## Bid Adapter Interface
+
+Bid adapters can check the bidRequest.bidLimit value to see if they're going to
+be allowed to provide more than one bid response.
+
+When they are allowed to do so, just add another bid response object to the
+array returned from the `interpretResponse` function.
+
+## Related Topics
+
+- [MultiBid in the Prebid Server /openrtb2/auction endpoint](/prebid-server/endpoints/openrtb2/pbs-endpoint-auction.html#multibid-pbs-java-only)

prebid-server/endpoints/openrtb2/pbs-endpoint-amp.md

@@ -80,6 +80,12 @@ An example Stored Request is given below:
 }
 ```
 
+Note that other ext.prebid extensions can be specified in the stored request such as:
+- [ext.prebid.currency](/prebid-server/endpoints/openrtb2/pbs-endpoint-auction.html#currency-support)
+- [ext.prebid.aliases](/prebid-server/endpoints/openrtb2/pbs-endpoint-auction.html#bidder-aliases)
+- [ext.prebid.multibid](/prebid-server/endpoints/openrtb2/pbs-endpoint-auction.html#multibid-pbs-java-only)
+- etc.
+
 #### First Party Data
 
 (Currently only supported in PBS-Java)

prebid-server/endpoints/openrtb2/pbs-endpoint-auction.md

@@ -113,7 +113,7 @@ Prebid Server recognizes several standard OpenRTB2.5 fields.
 #### Currency
 
 The `cur` field is read and the first element of the array is taken to be the
-"Ad Server Currency" for purposes of [currency conversion](/prebid-server/features/pbs-currency.html). 
+"Ad Server Currency" for purposes of [currency conversion](/prebid-server/features/pbs-currency.html).
 
 #### Expiration
 
@@ -170,14 +170,14 @@ This flag triggers Prebid Server to dump additional debug info into the OpenRTB
 Prebid Server reads the OpenRTB privacy fields:
 
 - regs.coppa
-- regs.ext.gdpr 
+- regs.ext.gdpr
 - regs.ext.us_privacy
 - user.ext.consent
 - device.lmt
 
 #### Other OpenRTB Fields
 
-Prebid Server doesn't do any special processing on any other fields, but passes them 
+Prebid Server doesn't do any special processing on any other fields, but passes them
 all to the bid and analytics adapters.
 
 ### OpenRTB Extensions
@@ -261,7 +261,7 @@ One of "includewinners" or "includebidderkeys" must be true (both default to tru
 
 The parameter "includeformat" indicates the type of the bid (banner, video, etc) for multiformat requests. It will add the key `hb_format` and/or `hb_format_{bidderName}` as per "includewinners" and "includebidderkeys" above.
 
-MediaType PriceGranularity (PBS-Java only) - when a single OpenRTB request contains multiple impressions with different mediatypes, or a single impression supports multiple formats, the different mediatypes may need different price granularities. If `mediatypepricegranularity` is present, `pricegranularity` would only be used for any mediatypes not specified. 
+MediaType PriceGranularity (PBS-Java only) - when a single OpenRTB request contains multiple impressions with different mediatypes, or a single impression supports multiple formats, the different mediatypes may need different price granularities. If `mediatypepricegranularity` is present, `pricegranularity` would only be used for any mediatypes not specified.
 
 ```
 {
@@ -418,6 +418,7 @@ To do this, just set `ext.prebid.aliasgvlids` alongside ext.prebid.aliases:
     }
   }
 });
+```
 
 #### Bidder Response Times
 
@@ -741,7 +742,7 @@ In contrast to what's outlined above, this approach lets some real auctions take
                   { "bidder": "BidderA", "id": "333333" },
                   { "bidder": "BidderB", "id": "444444" },
              ]
-           } 
+           }
       }
     },
     {
@@ -752,7 +753,7 @@ In contrast to what's outlined above, this approach lets some real auctions take
                   { "bidder": "BidderA", "id": "5555555" },
                   { "bidder": "BidderB", "id": "6666666" },
              ]
-           } 
+           }
       }
     }
   ]
@@ -804,9 +805,9 @@ It specifies where in the OpenRTB request non-standard attributes should be pass
          }
     },
     "user": {
-        "keywords": "", 
-        "gender": "", 
-        "yob": 1999, 
+        "keywords": "",
+        "gender": "",
+        "yob": 1999,
         "geo": {},
         "ext": {
             data: { GLOBAL USER DATA }  // only seen by bidders named in ext.prebid.data.bidders[]
@@ -892,6 +893,88 @@ In order to pull AMP parameters out into targeting, Prebid Server places AMP que
     }
 ```
 
+#### MultiBid (PBS-Java only)
+
+Allows a single bidder to bid more than once into an auction and have extra bids passed
+back to the client.
+
+See the [Prebid.js MultiBid Module](/dev-docs/modules/multibid.html) for background information and use cases.
+
+The Prebid extension to the OpenRTB protocol is `ext.prebid.multibid`. For example:
+
+```
+{
+  ext: {
+    prebid: {
+      multibid: [{
+        bidder: "bidderA",
+        maxbids: 2,
+        targetbiddercodeprefix: "bidA"
+      },{
+        bidder: "bidderB",
+        maxbids: 3,
+        targetbiddercodeprefix: "bidB"
+      },{
+        bidders: ["bidderC", "bidderD"]
+        maxbids: 2
+      }]
+    }
+  }
+}
+```
+
+MultiBid parameter details:
+
+{: .table .table-bordered .table-striped }
+| Attribute | Required? | Description | Example | Type |
+| --- | --- | --- | --- | --- |
+| bidder | Yes, unless bidders is specified | A biddercode | `'bidderA'` | string |
+| bidders | Yes, unless bidder is specified | Multiple biddercodes | `['bidderB','bidderC']` | array of strings |
+| maxBids | Yes | The number of bids the named bidder(s) can supply. Max of 9. | `2` | integer |
+| targetBiddercodePrefix | No | An alternate (short) bidder code to send to the ad server. A number will be appended, starting from 2, e.g. hb_pb_PREFIX2. If not provided, the extra bids will not go to the ad server. | `'bidA'` | string |
+
+Prebid Server core does the following when it sees `ext.prebid.multibid`:
+
+1. Before sending the request to bid adapters, it removes all entries from the multibid array except the one for that particular bid adapter. This lets the bid adapters be aware of how many bids they're going to be allowed to submit into the auction.
+2. Lets any additional bids through the OpenRTB response on `seatbid[].bid[]`.
+3. Adds the additional specified targeting on `seatbid[].bid[].ext.prebid.targeting` and repeats the biddercode used for targeting on `seatbid[].bid[].ext.prebid.targetbiddercode`.
+
+Here's an example response:
+```
+{
+seatbid: [{
+  seat: "bidderA",
+  bid: [{
+    id: "bid1",
+    impid: "imp1",
+    price: 1.04,
+    ext: {
+        prebid: {
+            targeting: {
+                hb_pb_bidderA: 1.00
+            },
+            targetbiddercode: "bidderA"
+        }
+    }
+    ...
+  },{
+    id: "bid2",
+    impid: "imp1",   // same imp as above
+    price:0.8,
+    ext: {
+        prebid: {
+            targeting: {
+                hb_pb_bidA2: 0.50
+            },
+            targetbiddercode: "bidA2"
+        }
+    }
+    ...
+  }]
+}]
+}
+```
+
 ### OpenRTB Ambiguities
 
 This section describes the ways in which Prebid Server **implements** OpenRTB spec ambiguous parts.