Document bid desirability adjustment (#6602)

Author: patmmccann

dev-docs/publisher-api-reference/bidderSettings.md

@@ -6,7 +6,7 @@ sidebarType: 1
 ---
 
 
-#### 1. Overview
+## 1. Overview
 
 The bidderSettings object provides a way to define some behaviors for the
 platform and specific adapters. The basic structure is a 'standard' section with defaults for all adapters, and then one or more adapter-specific sections that override behavior for that bidder:
@@ -33,23 +33,24 @@ Some sample scenarios where publishers may wish to alter the default settings:
 * passing additional information to the ad server
 * adjusting the bid CPM sent to the ad server
 
-#### 2. Bidder Setting Attributes
+## 2. Bidder Setting Attributes
 
 {: .table .table-bordered .table-striped }
 | Attribute | Scope | Version | Default | Description |
 | --- | --- | --- | --- | --- |
 | adserverTargeting | standard or adapter-specific | all | see below | Define which key/value pairs are sent to the ad server. |
 | bidCpmAdjustment | standard or adapter-specific | all | n/a | Custom CPM adjustment function. Could, for example, adjust a bidder's gross-price bid to net price. |
+| bidDesirabilityAdjustment | standard or adapter-specific | 11.15.0 | n/a | Custom bid desirability adjustment function. Allows bids to be ranked by a publisher-defined score without changing the adjusted CPM. |
 | inverseBidAdjustment | standard or adapter-specific | 7.33.0 | n/a | Inverse of `bidCpmAdjustment` |
 | sendStandardTargeting | adapter-specific | 0.13.0 | true | If adapter-specific targeting is specified, can be used to suppress the standard targeting for that adapter. |
 | suppressEmptyKeys | standard or adapter-specific | 0.13.0 | false | If custom adserverTargeting functions are specified that may generate empty keys, this can be used to suppress them. |
 | allowZeroCpmBids | standard or adapter-specific | 6.2.0 | false | Would allow bids with a 0 CPM to be accepted by Prebid.js and could be passed to the ad server. |
 | storageAllowed | standard or adapter-specific | 6.13.0 | true in 6.x, false after 7.0 | Allow use of cookies and/or local storage. |  
-| allowAlternateBidderCodes | standard or adapter-specific | 6.23.0 | true in v6.x <br /> false from v7.0| Allow adapters to bid with alternate bidder codes. |  
+| allowAlternateBidderCodes | standard or adapter-specific | 6.23.0 | true in v6.x <br /> false from v7.0 | Allow adapters to bid with alternate bidder codes. |  
 | allowedAlternateBidderCodes | standard or adapter-specific | 6.23.0 | n/a | Array of bidder codes for which an adapter can bid. <br />`undefined` or `['*']` will allow adapter to bid with any bidder code. |
 | adjustAlternateBids | standard or adapter-specific | 7.48.0 | false | Optionally allow alternate bidder codes to use an adapter's bidCpmAdjustment function by default instead of the standard bidCpmAdjustment function if present (note: if a bidCpmAdjustment function exists for the alternate bidder code within bidderSettings, then this will be used instead of falling back to the adapter's bidCpmAdjustment function). |
 
-##### 2.1. adserverTargeting
+### 2.1. adserverTargeting
 
 As described in the [AdOps documentation]({{site.baseurl}}/adops/before-you-start.html), Prebid has a recommended standard
 set of ad server targeting that works across bidders. This standard targeting approach is
@@ -144,15 +145,15 @@ pbjs.bidderSettings = {
 }
 ```
 
-In other words, the above config sends 2 pairs of key/value strings targeting for every AppNexus bid and for every ad unit. The 1st pair would be `apn_pbMg` => the value of `bidResponse.pbMg`. The 2nd pair would be `apn_adId` => the value of `bidResponse.adId`. You can find the bidResponse object documentation [here](/troubleshooting/troubleshooting-guide.html#common-bid-response-parameters).
+In other words, the above config sends 2 pairs of key/value strings targeting for every AppNexus bid and for every ad unit. The 1st pair would be `apn_pbMg` => the value of `bidResponse.pbMg`. The 2nd pair would be `apn_adId` => the value of `bidResponse.adId`. See [common bid response parameters](/troubleshooting/troubleshooting-guide.html#common-bid-response-parameters) for bidResponse object documentation.
 
 Note that sendStandardTargeting is set to false so that the standard Prebid targeting (hb_bidder, etc.) aren't also sent to the ad server.
 
 **Price Buckets**
 
 Now let's say you would like to define a bidder-specific price bucket function rather than use the ones available by default in prebid.js. Even the [priceGranularity config](/dev-docs/publisher-api-reference/setConfig.html#setConfig-Price-Granularity) option applies to all bidders -- with this approach you can overwrite price buckets.
 
-*Note: this will only impact the price bucket sent to the ad server for targeting. It won't actually impact the cpm value used for ordering the bids.*
+*Note: this will only impact the price bucket sent to the ad server for targeting. It won't actually impact the CPM or desirability score used for ordering the bids.*
 
 ```javascript
 pbjs.bidderSettings = {
@@ -180,7 +181,7 @@ pbjs.bidderSettings = {
 }
 ```
 
-##### 2.2. bidCpmAdjustment
+### 2.2. bidCpmAdjustment
 
 Some bidders return gross prices instead of the net prices (what the publisher will actually
 get paid). For example, a publisher's net price might be 15% below the returned gross price.
@@ -189,7 +190,7 @@ header bidding auction. Otherwise, this bidder's gross price will unfairly win o
 other demand sources who report the real price.
 
 Custom adjustment can be provided as a function taking 3 arguments: `bidCpmAdjustment(cpm, bidResponse, bidRequest)`.
-Note that either `bidResponse` or `bidRequest` may be missing, although at least one of them is guaranteed to be present. This is because Prebid will sometimes need to run adjustment when no bid has been made yet; see [inverseBidAdjustment](#23-inversebidadjustment) below.
+Note that either `bidResponse` or `bidRequest` may be missing, although at least one of them is guaranteed to be present. This is because Prebid will sometimes need to run adjustment when no bid has been made yet; see [inverseBidAdjustment](#24-inversebidadjustment) below.
 
 For example:
 
@@ -208,7 +209,34 @@ pbjs.bidderSettings = {
 
 In the above example, the AOL bidder will inherit from "standard" adserverTargeting keys, so that you don't have to define the targeting keywords again.
 
-##### 2.3. inverseBidAdjustment
+### 2.3. bidDesirabilityAdjustment
+
+By default, Prebid.js ranks accepted bids using their CPM after `bidCpmAdjustment` has been applied. Publishers who want to rank bids with additional business logic can provide `bidDesirabilityAdjustment`. This function returns a numeric score used to compare bids: higher scores are preferred.
+
+This is useful when the publisher wants auction ordering to account for signals that should not change the bid's adjusted CPM, price bucket, or ad server reporting value. For example, a publisher could prefer bids from a demand source that has better historical fill, lower discrepancy, or other business-priority signals while keeping the CPM available for targeting and reporting unchanged.
+
+The function takes 3 arguments: `bidDesirabilityAdjustment(cpm, bidResponse, bidRequest)`. The `cpm` argument is the bid CPM after `bidCpmAdjustment` has been applied. The function should return a number, and the default score is the adjusted CPM. If the function throws an error, Prebid.js logs the error and falls back to the adjusted CPM.
+
+For example:
+
+```javascript
+pbjs.bidderSettings = {
+  standard: { ... },
+  exampleBidder: {
+    bidDesirabilityAdjustment: function(adjustedCpm, bid) {
+      // Prefer this bidder slightly for ordering without changing its CPM.
+      if (bid.dealId) {
+        return adjustedCpm + 0.25;
+      }
+      return adjustedCpm;
+    }
+  }
+};
+```
+
+In the above example, deal bids from `exampleBidder` receive a higher desirability score than their adjusted CPM. The bid's CPM is not changed by this function.
+
+### 2.4. inverseBidAdjustment
 
 When using [price floors](/dev-docs/modules/floors.html), Prebid attempts to calculate the inverse of `bidCpmAdjustment`, so that the floor values it requests from SSPs take into account how the bid will be adjusted.
 For example, if the adjustment is `bidCpm * .85` as above, floors are adjusted by `bidFloor * 1 / .85`.
@@ -231,7 +259,7 @@ pbjs.bidderSettings = {
 };
 ```
 
-##### 2.4. sendStandardTargeting
+### 2.5. sendStandardTargeting
 
 This boolean flag minimizes key/value pairs sent to the ad server when
 adapter-specific targeting is specified. By default, the platform will send both adapter-specific adServerTargeting as well as the standard adServerTargeting.
@@ -241,19 +269,19 @@ suppress the standard targeting for adapters that define their own.
 
 See the [example above](#key-targeting-specific-bidder) for example usage.
 
-##### 2.5. suppressEmptyKeys
+### 2.6. suppressEmptyKeys
 
 If a custom adServerTargeting function can return an empty value, this boolean flag can be used to avoid sending those empty values to the ad server.
 
-##### 2.6. allowZeroCpmBids
+### 2.7. allowZeroCpmBids
 
 By default, 0 CPM bids are ignored by Prebid.js entirely.  However if there's a valid business reason to allow these bids, this setting can be enabled to allow
 either specific bid adapter(s) or all bid adapters the permission for these bids to be processed by Prebid.js and potentially sent to the respective ad server
 (depending on the Prebid.js auction results).
 
 <a id="storageAllowed"></a>
 
-##### 2.7. storageAllowed
+### 2.8. storageAllowed
 
 This setting defines if the bid adapter can access browser cookies or local storage. Allowed values are:
 
@@ -271,13 +299,13 @@ Note that:
 
 <a id="allowAlternateBidderCodes" />
 
-##### 2.8. allowAlternateBidderCodes
+### 2.9. allowAlternateBidderCodes
 
 If this flag is set to `true`, bidders that have not been explicitly requested in [`adUnit.bids`](../adunit-reference.html#adunitbids) may take part in the auction.
 <br />Default value is `true` in version 6.x
 <br />Default value will be `false` from version 7.0
 
-##### 2.9. allowedAlternateBidderCodes
+### 2.10. allowedAlternateBidderCodes
 
 This array will work in conjunction with `allowAlternateBidderCodes`. In this array, you can specify the names of the bidder for which an adapter can accept the bid. If the value is not specified for the array or `[‘*’]` is specified, Prebid will accept bids of all the bidders for the given adapter.
 
@@ -310,7 +338,7 @@ pbjs.bidderSettings = {
 In the above example, `groupm` bid will have a bid adjustment of 80% since the `bidCpmAdjustment` function says so.<br />
 If `appnexus` bids with another bidder code, say `appnexus2`. This bidder code will adjust the bid cpm to 95% because it will apply the `bidCpmAdjustment` function from `standard` setting, since the `bidCpmAdjustment` is missing for given bidder code I.e `appnexus2`
 
-##### 2.10. adjustAlternateBids
+### 2.11. adjustAlternateBids
 
 Optionally allow alternate bidder codes originating from a specific bid adapter to fallback to that same adapter's bidCpmAdjustment function. When adjustAlternateBids is set to true, the prioity of which bidCpmAdjustment function to utilize will be as follows based on what is present within the bidderSettings object: