Update reference docs with the changes made in V10 (#6506)

* Update pb10-notes.md: refer to correct method

* dfp has been renamed to gam

* Made distinction between methods returnning an array and methods returning a map

* Clarified return type

* Clarified return type

* Documented null return type

* Lint error: add missing space to the left/right of table pipe

* Lint error: table should be surrounded by blank lines

* Lint error: add missing space to table pipe

* Lint error: heading levels should only increment by one level at a time

* Restored the level of the headers

* dfpAdServerVideo -> gamAdServerVideo

* Remove trailing blank lines

* Fix header levels

* Re-add a single trailing white line

Author: robin-crazygames

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 | |

dev-docs/publisher-api-reference/adServers.dfp.buildVideoUrl.md

@@ -1,19 +1,19 @@
 ---
 layout: api_prebidjs
-title: pbjs.adServers.dfp.buildAdpodVideoUrl(options) <span style="color:red" markdown="1">[Alpha]</span>
-description: adServers.dfp.buildAdpodVideoUrl API
+title: pbjs.adServers.gam.buildAdpodVideoUrl(options) <span style="color:red" markdown="1">[Alpha]</span>
+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',

…ence/adServers.dfp.buildAdpodVideoUrl.md …ence/adServers.gam.buildAdpodVideoUrl.mddev-docs/publisher-api-reference/adServers.dfp.buildAdpodVideoUrl.md renamed to dev-docs/publisher-api-reference/adServers.gam.buildAdpodVideoUrl.md dev-docs/publisher-api-reference/adServers.dfp.buildAdpodVideoUrl.md renamed to dev-docs/publisher-api-reference/adServers.gam.buildAdpodVideoUrl.md

@@ -5,7 +5,6 @@ description: adServers.gam.buildVideoUrl API
 sidebarType: 1
 ---
 
-
 {: .alert.alert-info :}
 The Google Ad Manager implementation of this function requires including the `gamAdServerVideo` module in your Prebid.js build.
 

dev-docs/publisher-api-reference/adServers.gam.buildVideoUrl.md

@@ -7,15 +7,15 @@ 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 extends the behavior of `buildVideoUrl` by not only constructing the Google Ad Manager video ad tag URL, but also fetching and processing the resulting VAST wrapper returned by GAM.
 
 If the `cache.useLocal` flag is set to true, the function scans the received GAM VAST wrapper for the bid’s cached asset URL that corresponds to a locally stored blob in Prebid.js. When such a match is found, it replaces the contents of the GAM wrapper with the contents of the locally cached VAST XML blob, effectively inlining the ad markup instead of referencing it remotely.
 
-#### Argument Reference
+## Argument Reference
 
-##### The `options` object
+### The `options` object
 
 {: .table .table-bordered .table-striped }
 | Field    | Type   | Description                                                                                                                                                                        |
@@ -28,7 +28,7 @@ If the `cache.useLocal` flag is set to true, the function scans the received GAM
 {: .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                                         |
@@ -39,7 +39,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).
 
-#### Example
+## Example
 
 ```javascript
 pbjs.requestBids({

dev-docs/publisher-api-reference/adServers.gam.getVastXml.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` |
 | `meta` | Object | (Optional) Contains additional meta information about the bid. | `{ "advertiserDomains": [ "wherewindsmeetgame.com" ] }` |
 | `meta.advertiserDomains` | String[] | (Optional) Array with the advertiser domains | |
@@ -69,13 +68,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,
@@ -96,7 +93,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,
@@ -120,7 +116,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": "<scri...pt>",
@@ -139,15 +134,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,
@@ -160,7 +152,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,
@@ -179,7 +170,6 @@ This function returns the bid responses at the given moment.
         }
       }
     ]
-  }
 }
 ```
 
@@ -203,8 +193,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",
@@ -265,12 +254,10 @@ This function returns the bid responses at the given moment.
             "ttl" : 300,
             "status" : "targetingSet",
             "height" : 0,
-            "statusMessage" : "Bid available",
             "cpm" : 10,
             "currency" : "USD"
           }
       ]
-    }
 }
 ```
 

dev-docs/publisher-api-reference/getBidResponses.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 |

dev-docs/publisher-api-reference/getBidResponsesForAdUnitCode.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.