prebid 11.0 release notes

dev-docs/modules/bidViewable.md

@@ -2,7 +2,7 @@
 layout: page_v2
 page_type: module
 title: Module - Bid Viewability - GAM
-description: Triggers a BID_VIEWABLE event when a rendered bid is viewable according to Active View criteria
+description: Triggers a 'bidViewable' event when a rendered bid is viewable according to Active View criteria
 module_code : bidViewability
 display_name : Bid Viewability - GAM
 enable_download : true
@@ -18,7 +18,7 @@ sidebarType : 1
 
 ## Overview
 
-This optional module will trigger a BID_VIEWABLE event which can be consumed by Analytics adapters. In addition, the winning bidder can implement an `onBidViewable` method to capture this event.
+This optional module will trigger a `bidViewable` event which can be consumed by Analytics adapters. In addition, the winning bidder can implement an `onBidViewable` method to capture this event.
 
 Notes:
 
@@ -48,19 +48,15 @@ The default logic used to find a matching Prebid.js bid for a GPT slot is
 | `bidViewability` | Required | Object | Configuration object |
 | `bidViewability.enabled` | Required | Boolean | when set to true, the module will emit BID_VIEWABLE when applicable. Default: `false` |
 | `bidViewability.firePixels` | Optional | Boolean | when set to true, will fire the urls mentioned in `bid.vurls` which should be array of URLs. Default: `false` |
-| `bidViewability.customMatchFunction` | Optional | function(bid, slot) | this function will be used to find the matching winning bid for the GPT slot. See above for the default. |
+| `bidViewability.customMatchFunction` | Optional | function(bid, slot) | REMOVED in 11.0; use [customGptSlotMatching](/dev-docs/publisher-api-reference/setConfig.html#customGptSlotMatching) instead. This function will be used to find the matching winning bid for the GPT slot. See above for the default. |
 
 ## Example of setting module config
 
 ```javascript
     pbjs.setConfig({
         bidViewability: {
             enabled: true,
-            firePixels: true,
-            customMatchFunction: function(bid, slot){
-                console.log('using custom match function....');
-                return bid.adUnitCode === slot.getAdUnitPath();
-            }
+            firePixels: true
         }
     });
 ```

dev-docs/modules/bidViewableIO.md

@@ -2,7 +2,7 @@
 layout: page_v2
 page_type: module
 title: Module - Bid Viewability - Ad Server Independent
-description: Triggers a BID_VIEWABLE event when a rendered bid is viewable according to an approximation of IAB viewability criteria
+description: Triggers a `bidViewable` event when a rendered bid is viewable according to an approximation of IAB viewability criteria
 module_code : bidViewabilityIO
 display_name : Bid Viewability - Ad Server Independent
 enable_download : true
@@ -17,7 +17,7 @@ sidebarType : 1
 
 ## Overview
 
-This optional module will trigger a BID_VIEWABLE event which can be consumed by Analytics adapters. In addition, the winning bidder can implement an `onBidViewable` method to capture this event.
+This optional module will trigger a `bidViewable` event which can be consumed by Analytics adapters. In addition, the winning bidder can implement an `onBidViewable` method to capture this event.
 
 Notes:
 

dev-docs/modules/gpt-pre-auction.md

@@ -49,7 +49,7 @@ Optional initialization parameters:
 {: .table .table-bordered .table-striped }
 | Param | Required? | Type | Description | Example |
 | enabled | no | boolean | allows turning off of module. Default value is true | true |
-| customGptSlotMatching | no | function | GPT slot matching function should match the customSlotMatching function sent to [setTargetingForGptAsync](/dev-docs/publisher-api-reference/setTargetingForGPTAsync.html) | |
+| customGptSlotMatching | no | function | REMOVED in 11.0; use [customGptSlotMatching](/dev-docs/publisher-api-reference/setConfig.html#customGptSlotMatching) instead. GPT slot matching function should match the customSlotMatching function sent to [setTargetingForGptAsync](/dev-docs/publisher-api-reference/setTargetingForGPTAsync.html) | |
 | useDefaultPreAuction | no | boolean | (PBJS 6.5+) If true, use default behavior for determining GPID and PbAdSlot. Defaults to false. | true |
 | customPreAuction | no | function | (PBJS 6.5+) Custom function for defining the GPID and PbAdSlot. | |
 | customPbAdSlot | no | function | Custom PB AdSlot function. (Note, this function will be deprecated in the future.) | |

dev-docs/pb11-notes.md

@@ -0,0 +1,137 @@
+---
+layout: page_v2
+title: Prebid.js 11.0 Release Notes & Publisher API Changes
+description: Description of the breaking changes included for Prebid.js 11.0
+sidebarType: 1
+---
+
+# Prebid.js 11.0 Adapter Interface and Publisher API Changes
+
+{:.no_toc}
+
+This document describes the changes included for Prebid.js version 11.0.
+
+* TOC
+  {:toc}
+
+## Publisher Summary
+
+1. A number of obsolete modules have been removed (see list below).
+2. Adpod is no longer supported.
+3. PAAPI is no longer supported.
+4. The `addAdUnits`, `bidAccepted`, and `seatNonBid` events have been removed.
+5. Bids whose `mediaType` does not match their request's `mediaTypes` are now rejected as invalid.
+6. The `storageControl` module now defaults to strict enforcement.
+7. [setTargetingForGPTAsync](/dev-docs/publisher-api-reference/setTargetingForGPTAsync.html) no longer takes a `customSlotMatching` argument; the configuration options `bidViewability.customMatchFunction` and `gptPreAuction.customGptSlotMatching` have been removed. The replacement is a single new configuration option `customGptSlotMatching`. 
+8. The way viewability is calculated and signaled has been overhauled.
+
+## Adapter summary
+
+1. A new utility function, `getAdUnitElement`, should be used to link an ad unit / bid request / bid response to its DOM element.
+2. DNT (`navigator.doNotTrack`) is no longer supported. The `getDNT()` utility function now always returns `false`.
+3. Typescript is now preferred over Javascript. New modules should provide types for their public interface. 
+
+<a id="removed-modules"></a>
+
+## Removed Modules
+
+The following modules have been removed from Prebid.js as part of the 11.0 release:
+
+{: .table .table-bordered .table-striped }
+
+| Module                          | Notes                          |
+|:--------------------------------|:-------------------------------|
+| `adpod`                         |                                |
+| `categoryTranslation`           | Adpod submodule                |
+| `dfpAdServerVideo`              | Use `gamAdServerVideo` instead |
+| `dfpAdpod`                      | Adpod submodule                |
+| `dmdIdSystem`                   |                                |
+| `express`                       |                                |
+| `freeWheelAdserverVideo`        | Adpod submodule                |
+| `gamAdpod`                      | Adpod submodule                |
+| `intersectionRtdProvider`       |                                |
+| `optableBidAdapter`             | No longer useful without PAAPI |
+| `paapi`                         |                                |
+| `paapiForGpt`                   |                                | 
+| `topLevelPaapi`                 |                                |
+| `quantcastBidAdapter`           |                                | 
+| `quantcastIdSystem`             |                                |
+| `ringieraxelspringerBidAdapter` |                                | 
+
+## Removed events
+
+The following events have been removed and will no longer trigger callbacks registered with [pbjs.onEvent](/dev-docs/publisher-api-reference/onEvent.html):
+
+* `addAdUnits`: this event carried no information besides the fact that `pbjs.addAdUnits` was called. `auctionInit` and `beforeRequestBids` contain the ad units involved in each auction.           
+* `bidAccepted`: use `bidResponse` instead.
+* `seatNonBid`: use `pbsAnalytics` instead.
+
+## Stricter mediaType enforcement
+
+Bids that declare a `mediaType` not present in their ad unit's `mediaTypes` are now rejected as invalid. This validation can be turned off by setting `auctionOptions.rejectInvalidMediaTypes` to `false`.
+
+Bids that do not declare any `mediaType` are assumed to be `'banner'`; you may require an explicit mediaType with `auctionOptions.rejectUnknownMediaTypes`. If enabled, bids that do not set `mediaType` will also be rejected as invalid. For example:
+
+```javascript
+pbjs.setConfig({
+  auctionOptions: {
+    rejectInvalidMediaTypes: false, // allow bids on the wrong format
+    rejectUnknownMediaTypes: true   // disallow bids that do not declare their format
+  }
+})
+```
+
+## Strict storageControl enforcement
+
+The [storageControl](/dev-docs/modules/storageControl.html) module now defaults to strict enforcement; including it will cause undisclosed storage use to fail instead of just logging a warning. You may revert to warning only with
+
+```javascript
+pbjs.setConfig({
+  storageControl: {
+    enforcement: 'off'
+  }
+})
+```
+
+## `customGptSlotMatching`
+
+A new configuration option `customGptSlotMatching` is replacing the following:
+
+* the second argument of [setTargetingForGPTAsync](/dev-docs/publisher-api-reference/setTargetingForGPTAsync.html);
+* the `customGptSlotMatching` configuration option of [gptPreAuction](/dev-docs/modules/gpt-pre-auction.html);
+* the `customMatchFunction` configuration option of [bidViewability](/dev-docs/modules/bidViewable.html).
+
+<a id="viewability-overhaul"><a>
+
+## Viewability overhaul
+
+A number of changes were aimed at standardizing two related problems: viewability of an ad unit at the time an auction starts; and viewability of an ad that was rendered on the page.
+
+### `adUnit.element` and `getAdUnitElement`
+
+Many adapters attempt to calculate the position of an ad unit on the page so that they can include that information in their bid request. To facilitate this, 11.0 adds a new `element` configuration option for ad units that can be used to specify the page element it corresponds to. For example:
+
+```javascript
+pbjs.requestBids({
+  adUnits: [{
+    code: 'myAdUnit',
+    element: document.querySelector('#ad-container')
+    // ...
+  }]
+})
+```
+
+Adapters can retrieve the element using the `getAdUnitElement` utility function. If `element` is not specified for an ad unit it defaults to `document.getElementById(adUnit.code)`.
+
+### Viewability after rendering
+
+To determine viewability of an ad rendered on the page, publishers can choose one of two optional modules:
+
+* [`bidViewability`](/dev-docs/modules/bidViewable.html) only works with GPT ad units, and relies on its `impressionViewable` events;
+* [`bidViewabilityIO`](/dev-docs/modules/bidViewableIO.html) approximates the same viewability criteria (IAB's MRC 50%) using [`IntersectionObserver`](https://developer.mozilla.org/en-US/docs/Web/API/Intersection_Observer_API).
+
+When a bid is deemed viewable, both modules now:
+
+* fire a `bidViewable` event
+* run the relevant adapter's `onBidViewable` method
+* trigger "viewable-mrc50" (`event: 2`) event trackers in the bid's `eventtracker` array.

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

@@ -30,23 +30,23 @@ The available events are:
 | beforeRequestBids | Bids are about to be requested from adapters (added in 3.x) | Array of adunits in the auction |
 | beforeBidderHttp | bidder network request is about be triggered | Array of Bid request objects |
 | bidRequested  | A bid was requested from a specific bidder | Bid request object |
-| bidResponse   | A bid response has arrived              | Bid response object |
+| bidResponse   | A bid response has been added to an auction             | Bid response object |
 | pbsAnalytics    | Prebid Server has returned extra information for analytics adapters. | { [seatnonbid](/prebid-server/endpoints/openrtb2/pbs-endpoint-auction.html#seat-non-bid), auctionId, [atag](/prebid-server/developers/module-atags.html) } |
-| seatNonBid    | DEPRECATED - use pbsAnalytics instead. Prebid Server has returned nonbid information. Must be enabled in s2sConfig.extPrebid | None |
+| seatNonBid    | Removed in 11.0 - use `pbsAnalytics` instead. Prebid Server has returned nonbid information. Must be enabled in s2sConfig.extPrebid | None |
 | bidRejected   | A bid was rejected                      | Bid response object |
 | bidAdjustment | A bid was adjusted                      | Bid response object |
 | bidWon        | A bid has won                           | Bid response object |
 | bidTimeout    | A bid timed out                         | Array of objects with timed out bids |
 | setTargeting  | Targeting has been set                  | Hash of targeting values |
 | requestBids   | Bids have been requested from adapters (i.e. pbjs.requestBids() was called) | The argument passed to [`requestBids`](https://docs.prebid.org/dev-docs/publisher-api-reference/requestBids.html), except that `adUnits` and `adUnitCodes` are always set and reflect the ad units involved in the auction. Event handlers may not modify `adUnitCodes`. |
-| addAdUnits    | Ad units have been added to the auction | None |
+| addAdUnits    | Removed in 11.0 - use `auctionInit` instead. Ad units have been added to the auction. Removed in 11.0. | None |
 | adRenderFailed| Ad rendering failed | Object containing 'reason' and 'message' |
 | adRenderSucceeded | Ad rendering succeeded| Object containing 'doc', 'bid', and 'adId'. 'doc' is the DOM root containing the ad and may be `null` if it was rendered in a cross-origin iframe. This event indicates that the render function did not generate an error, it does not guarantee that tracking for this event has occurred yet.|
 | auctionDebug  | An error was logged to the console | Object containing 'type' and 'arguments' |
 | bidderDone    | A bidder has signaled they are done responding | Bid request object |
 | bidderError    | A bidder responded with an error | Object with the XMLHttpRequest error and the bid request object `{ error, bidderRequest }` |
 | tcf2Enforcement | There was a TCF2 enforcement action taken | `{ storageBlocked: ['moduleA', 'moduleB'], biddersBlocked: ['moduleB'], analyticsBlocked: ['moduleC'] }` |
-| bidAccepted | A bid was accepted and is about to be added to auction | Bid response object |
+| bidAccepted | Removed in 11.0 - use `bidResponse` instead. A bid was accepted and is about to be added to auction | Bid response object |
 | browserIntervention | The browser reported an intervention affecting a rendered creative (e.g., heavy-ad unload). | `{ bid, adId, intervention }` |
 
 The example below shows how these events can be used.

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

@@ -1317,6 +1317,24 @@ pbjs.setConfig({
 {: .alert.alert-warning :}
 In PBJS 4.29 and earlier, don't add the `ortb2` level here -- just `site` directly. Oh, and please upgrade. 4.29 was a long time ago.
 
+<a id="customGptSlotMatching"></a>
+
+### Custom GPT slot matching
+
+By default, Prebid matches ad units to GPT slots by code, i.e. a GPT `slot` corresponds to a Prebid `adUnit` if `slot.getAdUnitPath() === adUnit.code`. You can provide a custom matching function to override this, for example:
+
+```javascript
+pbjs.setConfig({
+  customGptSlotMatching: function(slot) {
+    return function(adUnitCode) {
+      return slot.getAdUnitPath() === adUnitCode
+    }
+  }
+})
+```
+
+`customGptSlotMatching` should be a function accepting a single GPT [Slot](https://developers.google.com/publisher-tag/reference#googletag.Slot). It should return another function accepting a single string representing an ad unit code. The inner function should return true if the givne slot matches the given ad unit code. 
+
 <a name="setConfig-auctionOptions"></a>
 
 ### Auction Options

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

@@ -14,7 +14,7 @@ Set query string targeting on GPT ad units after the auction.
 | Param | Scope | Type | Description |
 | --- | --- | --- | -- |
 | [codeArr] | Optional | `array` | an array of adUnitCodes to set targeting for. |
-| customSlotMatching | Optional | `function` | gets a GoogleTag slot and returns a filter function for adUnitCode. |
+| customSlotMatching | Optional | `function` | REMOVED in 11.0; use [customGptSlotMatching](/dev-docs/publisher-api-reference/setConfig.html#customGptSlotMatching) instead. Gets a GoogleTag slot and returns a filter function for adUnitCode. |
 
 This function matches AdUnits that have returned from the auction to a GPT ad slot and adds the `hb_`
 targeting attributes to the slot so they get sent to GAM.

dev-docs/release-notes.md

@@ -15,6 +15,7 @@ This page has links to release notes for each of the projects associated with Pr
 ## Prebid.js
 
 + [Release notes on GitHub](https://github.com/prebid/Prebid.js/releases)
++ [Prebid.js 11 Release Notes](/dev-docs/pb11-notes.html)
 + [Prebid.js 10 Release Notes](/dev-docs/pb10-notes.html)
 + [Prebid.js 9 Release Notes](/dev-docs/pb9-notes.html)
 + [Prebid.js 8 Release Notes](/dev-docs/pb8-notes.html)