diff --git a/dev-docs/modules/bidViewable.md b/dev-docs/modules/bidViewable.md index 78fcb4285c..ee6782afa3 100644 --- a/dev-docs/modules/bidViewable.md +++ b/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,7 +48,7 @@ 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 @@ -56,11 +56,7 @@ The default logic used to find a matching Prebid.js bid for a GPT slot is pbjs.setConfig({ bidViewability: { enabled: true, - firePixels: true, - customMatchFunction: function(bid, slot){ - console.log('using custom match function....'); - return bid.adUnitCode === slot.getAdUnitPath(); - } + firePixels: true } }); ``` diff --git a/dev-docs/modules/bidViewableIO.md b/dev-docs/modules/bidViewableIO.md index 0d7ecc1ea7..2fbf445662 100644 --- a/dev-docs/modules/bidViewableIO.md +++ b/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: diff --git a/dev-docs/modules/gpt-pre-auction.md b/dev-docs/modules/gpt-pre-auction.md index cab3e3489b..e7eb1e4991 100644 --- a/dev-docs/modules/gpt-pre-auction.md +++ b/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.) | | diff --git a/dev-docs/pb11-notes.md b/dev-docs/pb11-notes.md new file mode 100644 index 0000000000..ddd26ee0b2 --- /dev/null +++ b/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. + + + +## 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). + + + +## 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. diff --git a/dev-docs/publisher-api-reference/getEvents.md b/dev-docs/publisher-api-reference/getEvents.md index 6462ad9eb1..a374315d74 100644 --- a/dev-docs/publisher-api-reference/getEvents.md +++ b/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. diff --git a/dev-docs/publisher-api-reference/setConfig.md b/dev-docs/publisher-api-reference/setConfig.md index 801b453c6b..9198fc6979 100644 --- a/dev-docs/publisher-api-reference/setConfig.md +++ b/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. + + +### 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. + ### Auction Options diff --git a/dev-docs/publisher-api-reference/setTargetingForGPTAsync.md b/dev-docs/publisher-api-reference/setTargetingForGPTAsync.md index 16d682dfe3..e5c1c8822a 100644 --- a/dev-docs/publisher-api-reference/setTargetingForGPTAsync.md +++ b/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. diff --git a/dev-docs/release-notes.md b/dev-docs/release-notes.md index 19e49c530f..e100083c1f 100644 --- a/dev-docs/release-notes.md +++ b/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)