diff --git a/dev-docs/pb10-notes.md b/dev-docs/pb10-notes.md index 20fa95ba27..664677a343 100644 --- a/dev-docs/pb10-notes.md +++ b/dev-docs/pb10-notes.md @@ -19,11 +19,12 @@ This document describes the changes included for Prebid.js version 10.0. 1. A large number of obsolete modules have been removed. Many modules have changed name. See below for the list. 2. The legacy method of native targeting keys, `sendTargetingKeys`, has been removed. 3. `pbadslot` has been removed from the preAuction module. Use `ortb2Imp.ext.gpid` instead. -4. The API methods `getBidResponses` and `getNoBidsForAdUnitCode` now return arrays of bids. -5. TypeScript support has landed and Node.js 20+ is required to build. -6. Using Prebid as an NPM dependency no longer requires using Babel or Prebid's Babel settings. -7. `targetingControls.allBidsCustomTargeting` now defaults to `false`, this prevents custom targeting values from being set for non-winning bids. -8. Storage use disclosures can now be enforced and catalogued +4. The API methods `getBidResponsesForAdUnitCode` and `getNoBidsForAdUnitCode` now return arrays of bids. +5. The API methods `getBidResponses` and `getNoBids` now return an object with an array of bids for each ad unit. +6. TypeScript support has landed and Node.js 20+ is required to build. +7. Using Prebid as an NPM dependency no longer requires using Babel or Prebid's Babel settings. +8. `targetingControls.allBidsCustomTargeting` now defaults to `false`, this prevents custom targeting values from being set for non-winning bids. +9. Storage use disclosures can now be enforced and catalogued ## Removed Modules @@ -32,7 +33,7 @@ The following modules have been removed from Prebid.js as part of the 10.0 relea {: .table .table-bordered .table-striped } | Module | Replacement | -|:-----------------------------|:-------------------------| +| :----------------------------- | :------------------------- | | dfpAdServerVideo | gamAdServerVideo | | dfpAdPod | gamAdPod | | telariaBidAdapter | | diff --git a/dev-docs/publisher-api-reference/adServers.dfp.buildAdpodVideoUrl.md b/dev-docs/publisher-api-reference/adServers.gam.buildAdpodVideoUrl.md similarity index 88% rename from dev-docs/publisher-api-reference/adServers.dfp.buildAdpodVideoUrl.md rename to dev-docs/publisher-api-reference/adServers.gam.buildAdpodVideoUrl.md index 2622837b3c..cf0d72f57c 100644 --- a/dev-docs/publisher-api-reference/adServers.dfp.buildAdpodVideoUrl.md +++ b/dev-docs/publisher-api-reference/adServers.gam.buildAdpodVideoUrl.md @@ -1,19 +1,19 @@ --- layout: api_prebidjs -title: pbjs.adServers.dfp.buildAdpodVideoUrl(options) [Alpha] -description: adServers.dfp.buildAdpodVideoUrl API +title: pbjs.adServers.gam.buildAdpodVideoUrl(options) [Alpha] +description: adServers.gam.buildAdpodVideoUrl API sidebarType: 1 --- {: .alert.alert-info :} -The GAM implementation of this function requires including the `dfpAdServerVideo` module in your Prebid.js build. +The GAM implementation of this function requires including the `gamAdServerVideo` module in your Prebid.js build. This method combines publisher-provided parameters with Prebid.js targeting parameters to build a GAM video ad tag URL that can be used by a video player. -#### Argument Reference +## Argument Reference -##### The `options` object +### The `options` object {: .table .table-bordered .table-striped } | Field | Type | Description | @@ -23,7 +23,7 @@ This method combines publisher-provided parameters with Prebid.js targeting para {% include alerts/alert_important.html content="For long form Prebid.js will add key-value strings for multiple bids. This prevents retrieving the description url from bid." %} -#### Example +## Example ```JavaScript pbjs.que.push(function(){ @@ -42,7 +42,7 @@ pbjs.que.push(function(){ pbjs.requestBids({ bidsBackHandler: function(bids) { - pbjs.adServers.dfp. buildAdpodVideoUrl({ + pbjs.adServers.gam. buildAdpodVideoUrl({ codes: ['sample-code'], params: { iu: '/123456/testing/prebid.org/adunit1', diff --git a/dev-docs/publisher-api-reference/adServers.dfp.buildVideoUrl.md b/dev-docs/publisher-api-reference/adServers.gam.buildVideoUrl.md similarity index 92% rename from dev-docs/publisher-api-reference/adServers.dfp.buildVideoUrl.md rename to dev-docs/publisher-api-reference/adServers.gam.buildVideoUrl.md index 6c8ccae331..a071056949 100644 --- a/dev-docs/publisher-api-reference/adServers.dfp.buildVideoUrl.md +++ b/dev-docs/publisher-api-reference/adServers.gam.buildVideoUrl.md @@ -1,19 +1,19 @@ --- layout: api_prebidjs -title: pbjs.adServers.dfp.buildVideoUrl(options) -description: adServers.dfp.buildVideoUrl API +title: pbjs.adServers.gam.buildVideoUrl(options) +description: adServers.gam.buildVideoUrl API sidebarType: 1 --- {: .alert.alert-info :} -The Google Ad Manager implementation of this function requires including the `dfpAdServerVideo` module in your Prebid.js build. +The Google Ad Manager implementation of this function requires including the `gamAdServerVideo` module in your Prebid.js build. This method combines publisher-provided parameters with Prebid.js targeting parameters to build a Google Ad Manager video ad tag URL that can be used by a video player. -#### Argument Reference +## Argument Reference -##### The `options` object +### The `options` object {: .table .table-bordered .table-striped } | Field | Type | Description | @@ -26,7 +26,7 @@ This method combines publisher-provided parameters with Prebid.js targeting para {: .alert.alert-warning :} One or both of options.params and options.url is required. In other words, you may pass in one, the other, or both, but not neither. -##### The `options.params` object +### The `options.params` object {: .table .table-bordered .table-striped } | Field | Type | Description | Example | @@ -37,7 +37,7 @@ One or both of options.params and options.url is required. In other words, you m For more information on any of these params, see [the Google Ad Manager video tag documentation](https://support.google.com/admanager/answer/1068325). -#### Examples +## Examples There are several different ways to build up your video URL, as shown in the examples below: @@ -46,7 +46,7 @@ Using `options.params` only: ```javascript pbjs.requestBids({ bidsBackHandler: function(bids) { - var videoUrl = pbjs.adServers.dfp.buildVideoUrl({ + var videoUrl = pbjs.adServers.gam.buildVideoUrl({ adUnit: videoAdUnit, params: { iu: '/19968336/prebid_cache_video_adunit', @@ -72,7 +72,7 @@ var adserverTag = 'https://pubads.g.doubleclick.net/gampad/ads?' + '&env=vp&output=xml_vast2&unviewed_position_start=1&hl=en&url=https://www.example.com' + '&cust_params=section%3Dblog%26anotherKey%3DanotherValue'; -var videoUrl = pbjs.adServers.dfp.buildVideoUrl({ +var videoUrl = pbjs.adServers.gam.buildVideoUrl({ adUnit: videoAdUnit, url: adserverTag }); diff --git a/dev-docs/publisher-api-reference/getBidResponses.md b/dev-docs/publisher-api-reference/getBidResponses.md index 0a01d9f02a..96fc83da5a 100644 --- a/dev-docs/publisher-api-reference/getBidResponses.md +++ b/dev-docs/publisher-api-reference/getBidResponses.md @@ -10,7 +10,7 @@ This function returns the bid responses at the given moment. **Kind**: static method of `pbjs`. -**Returns**: `object` - map | object that contains the bidResponses. +**Returns**: `object` - map | object that contains for each ad unit the array of bid responses. For backwards compatibility, the arrays expose the array also under the `.bids` property. **Returned Object Params**: @@ -36,7 +36,6 @@ This function returns the bid responses at the given moment. | `adserverTargeting` | Object | Contains all the adserver targeting parameters | `{ "hb_bidder": "appnexus", "hb_adid": "7a53a9d3" }` | | `native` | Object | Contains native key value pairs. | `{ "title": "", "body": "" }` | | `status` | String | Status of the bid. Possible values: targetingSet, rendered | `"targetingSet"` | -| `statusMessage` | String | The bid's status message | "Bid returned empty or error response" or "Bid available" | | `ttl` | Integer | How long (in seconds) this bid is considered valid. See this [FAQ entry]({{site.github.url}}/dev-docs/faq.html#does-prebidjs-cache-bids) for more info. | `300` |
@@ -54,13 +53,11 @@ This function returns the bid responses at the given moment. ```json { - "/9968336/header-bid-tag-0": { - "bids": [ + "/9968336/header-bid-tag-0": [ { "bidderCode": "appnexus", "width": 300, "height": 250, - "statusMessage": "Bid available", "adId": "7a53a9d3", "creative_id": 29681110, "cpm": 0.5, @@ -81,7 +78,6 @@ This function returns the bid responses at the given moment. "bidderCode": "pubmatic", "width": "300", "height": "250", - "statusMessage": "Bid available", "adId": "1139e34e14", "adSlot": "39620189@300x250", "cpm": 1, @@ -105,7 +101,6 @@ This function returns the bid responses at the given moment. "bidderCode": "rubicon", "width": "300", "height": "250", - "statusMessage": "Bid available", "adId": "130d3b0d9b", "cpm": 0.795995, "ad": "", @@ -124,15 +119,12 @@ This function returns the bid responses at the given moment. "hb_pb": "0.50" } } - ] - }, - "/9968336/header-bid-tag1": { - "bids": [ + ], + "/9968336/header-bid-tag1": [ { "bidderCode": "casale", "width": 0, "height": 0, - "statusMessage": "Bid returned empty or error response", "adId": "108c0ba49d", "requestTimestamp": 1444844944130, "responseTimestamp": 1444844944223, @@ -145,7 +137,6 @@ This function returns the bid responses at the given moment. "bidderCode": "openx", "width": "728", "height": "90", - "statusMessage": "Bid available", "adId": "14d7f9208f", "ad_id": "537161420", "cpm": 1.717, @@ -164,7 +155,6 @@ This function returns the bid responses at the given moment. } } ] - } } ``` @@ -188,8 +178,7 @@ This function returns the bid responses at the given moment. ```json { - "div-banner-outstream-native" : { - "bids" : [ + "div-banner-outstream-native" : [ { "pbMg" : "10.00", "pbLg" : "5.00", @@ -250,12 +239,10 @@ This function returns the bid responses at the given moment. "ttl" : 300, "status" : "targetingSet", "height" : 0, - "statusMessage" : "Bid available", "cpm" : 10, "currency" : "USD" } ] - } } ``` diff --git a/dev-docs/publisher-api-reference/getBidResponsesForAdUnitCode.md b/dev-docs/publisher-api-reference/getBidResponsesForAdUnitCode.md index 7e2c984bdd..9018148b4a 100644 --- a/dev-docs/publisher-api-reference/getBidResponsesForAdUnitCode.md +++ b/dev-docs/publisher-api-reference/getBidResponsesForAdUnitCode.md @@ -9,9 +9,10 @@ Returns bidResponses for the specified adUnitCode. See full documentation at [pb **Kind**: static method of `pbjs` -**Returns**: `Object` - bidResponse object +**Returns**: `Array` - an array of bid responses. For backwards compatibility, the array exposes the array also under the `.bids` property. {: .table .table-bordered .table-striped } + | Param | Scope | Type | Description | | --- | --- | --- | --- | | adUnitCode | Required | `String` | adUnitCode | diff --git a/dev-docs/publisher-api-reference/getHighestUnusedBidResponseForAdUnitCode.md b/dev-docs/publisher-api-reference/getHighestUnusedBidResponseForAdUnitCode.md index 03058d70c3..8a03ad9570 100644 --- a/dev-docs/publisher-api-reference/getHighestUnusedBidResponseForAdUnitCode.md +++ b/dev-docs/publisher-api-reference/getHighestUnusedBidResponseForAdUnitCode.md @@ -6,5 +6,6 @@ sidebarType: 1 --- Use this method to retrieve the highest unused bid for the specified adUnit. Unused means not it's not rendered. +Returns `null` when no suitable bid exists. This differs from [`getHighestCpmBids()`](/dev-docs/publisher-api-reference/getHighestCpmBids.html) in that getHighestCpmBids only considers bids for auctions that have completed (and are also unused), this function considers bids for ongoing auctions as well.