Enhancing docs for Ad Server KVPs

_data/sidebar.yml

@@ -467,6 +467,14 @@
   sectionTitle:
   subgroup: 8
 
+- sbSecId: 1
+  title: Ad Server Key Values
+  link: /features/adServerKvps.html
+  isHeader: 0
+  isSectionHeader: 0
+  sectionTitle:
+  subgroup: 8
+
 - sbSecId: 1
   title: Native Ads
   link: /prebid/native-implementation.html
@@ -500,7 +508,7 @@
   subgroup: 8
 
 - sbSecId: 1
-  title: Prebid Ad Slot
+  title: Prebid Ad Slot and GPID
   link: /features/pbAdSlot.html
   isHeader: 0
   isSectionHeader: 0
@@ -515,6 +523,14 @@
   sectionTitle:
   subgroup: 8
 
+- sbSecId: 1
+  title: Interstitial Ads
+  link: /features/interstitialAds.html
+  isHeader: 0
+  isSectionHeader: 0
+  sectionTitle:
+  subgroup: 8
+
 - sbSecId: 1
   title: Timeouts
   link: /features/timeouts.html

dev-docs/adunit-reference.md

@@ -37,7 +37,7 @@ See the table below for the list of properties on the ad unit.  For example ad u
 | `mediaTypes` | Optional | Object                                | Defines one or more media types that can serve into the ad unit.  For a list of properties, see [`adUnit.mediaTypes`](#adUnit.mediaTypes) below.                                           |
 | `labelAny`   | Optional | Array[String]                         | Used for [conditional ads][conditionalAds].  Works with `sizeConfig` argument to [pbjs.setConfig][configureResponsive].                                                                    |
 | `labelAll`   | Optional | Array[String]                         | Used for [conditional ads][conditionalAds]. Works with `sizeConfig` argument to [pbjs.setConfig][configureResponsive].                                                                     |
-| `ortb2Imp`   | Optional | Object                         | ortb2Imp is used to signal OpenRTB Imp objects at the adUnit grain. Similar to the global ortb2 field used for [global first party data configuration](/dev-docs/publisher-api-reference/setConfig.html#setConfig-fpd), but specific to this adunit. The ortb2Imp object currently supports [first party data](#adUnit-fpd-example) including the [Prebid Ad Slot](/features/pbAdSlot.html) and the [insterstitial](#adUnit-interstitial-example) signal. |
+| `ortb2Imp`   | Optional | Object                         | ortb2Imp is used to signal OpenRTB Imp objects at the adUnit grain. Similar to the global ortb2 field used for [global first party data configuration](/dev-docs/publisher-api-reference/setConfig.html#setConfig-fpd), but specific to this adunit. The ortb2Imp object currently supports [first party data](#adUnit-fpd-example) including the [Prebid Ad Slot](/features/pbAdSlot.html) and the [interstitial](#adUnit-interstitial-example) signal. |
 
 <a name="adUnit.bids" />
 

dev-docs/bidders/admixer.md

@@ -5,7 +5,7 @@ description: Prebid AdMixer Bidder Adaptor
 pbjs: true
 pbs: true
 biddercode: admixer
-media_types: video
+media_types: banner, video, native
 gdpr_supported: true
 usp_supported: true
 schain_supported: true

dev-docs/bidders/adplus.md

@@ -0,0 +1,19 @@
+---
+layout: bidder
+title: AdPlus
+description: Prebid AdPlus Bidder Adapter
+biddercode: adplus
+media_types: banner
+pbjs: true
+---
+### Note:
+
+The AdPlus Bidding adapter requires setup before beginning. Please contact us at adplus.destek@yaani.com.tr
+
+### Bid Params
+
+{: .table .table-bordered .table-striped }
+| Name          | Scope    | Description   | Example                                   | Type      |
+|---------------|----------|---------------|-------------------------------------------|-----------|
+| `adUnitId`    | required | Ad Unit ID    | `'-3'`                                    | `string`  |
+| `inventoryId` | required | Inventory ID  | `'-1'`                                    | `string`  |

dev-docs/bidders/beachfront.md

@@ -5,6 +5,7 @@ description: Prebid Beachfront Bidder Adapter
 biddercode: beachfront
 media_types: video
 floors_supported: true
+fpd_supported: true
 gdpr_supported: true
 usp_supported: true
 userIds: unifiedId, identityLink, uid2, haloId

dev-docs/bidders/iprom.md

@@ -5,7 +5,7 @@ description: iPROM Prebid Adaptor
 biddercode: iprom
 media_types: banner
 pbjs: true
-pbjs_version_notes: not in 5.x
+pbjs_version_notes: not in 5.x, in 6.2+
 ---
 
 ### Prebid Server Note:

dev-docs/bidders/limelightDigital.md

@@ -13,5 +13,6 @@ media_types: video
 | Name           | Scope      | Description                                                    | Example            |type|
 | :-----------   | :--------- | :------------                                                  | :----------------- |:---|
 | `host` | required | Ad network's RTB host | `'exchange.ortb.net'` | `string` |
-| `adUnitId` | required   | Ad Unit Id will be generated on Limelight Digital Platform. | 0                        |integer|
-| `adUnitType`      | required   | Type of Ad Unit (`'video'`, `'banner'`)                                             | `'banner'`                 |string|
+| `adUnitId` | required   | Ad Unit Id will be generated on Limelight Digital Platform. | 0                        | `integer` |
+| `adUnitType`      | required   | Type of Ad Unit (`'video'`, `'banner'`)                                             | `'banner'`                 | `string` |
+| `publisherId` | optional | Publisher ID | `'12345'` | `string` |

dev-docs/bidders/luponmedia.md

@@ -9,7 +9,7 @@ usp_supported: true
 coppa_supported: true
 schain_supported: true
 userIds: digitrust, identityLink, liveIntentId, pubCommonId
-pbjs_version_notes: not in 5.x
+pbjs_version_notes: not in 5.x, in 6.2+
 ---
 
 ### Note:

dev-docs/bidders/missena.md

@@ -6,7 +6,7 @@ biddercode: missena
 gvl_id: 867
 pbjs: true
 safeframes_ok: false
-pbjs_version_notes: not in 5.x
+pbjs_version_notes: not in 5.x, in 6.2+
 ---
 
 ### Note

dev-docs/bidders/smartx.md

@@ -43,10 +43,11 @@ Please reach out to your smartclip business contact for any questions and assist
 | Name            | Scope    | Description                                                                                  | Example          | Type        |
 | --------------- | -------- | -------------------------------------------------------------------------------------------- | ---------------- | ----------- |
 | `slot`          | required | ID of element that video ad should be rendered into.                                         | `'adSlot1'`      | `string`    |
-| `minAdWidth`    | optional | Minimum amount of space the player needs to expand.                                          | `290`            | `integer`   |
-| `maxAdWidth`    | optional | Maximum size of the player.                                                                  | `900`            | `integer`   |
-| `title`         | optional | Makes a defined advertising text appear in the below right corner. `[remainingTime]` can be used to display the remaining time of the advertisement. | `'Advertisement [remainingTime]s'` | `string`    |
-| `skipOffset`    | optional | Define whenever the advertisement can be skipped. 0 = never                                  | `0`              | `integer`   |
-| `startOpen`     | optional | Define whether the player should be initialized open or open when it is within view.         | `'false'`        | `string`    |
-| `endingScreen`  | optional | Define whether the player should stay open after advertising or not.                         | `'true'`         | `string`    |
-| `desiredBitrate`| optional | Define the desired bitrate of the mediafile.                                                 | `800`            | `integer`   |
+| `minAdWidth`    | optional | If the visible area is narrower than this size, no ad will be requested. The value is given in pixels. Default is `280`.       | `290`            | `integer`   |
+| `maxAdWidth`    | optional | The player will fill the whole width of the element it gets, to have it narrower a different maximum width can be defined in pixels. Default is `800`.                                | `900`            | `integer`   |
+| `title`         | optional | The player can show a freely definable text, a macro `[remainingTime]` in this string will be replaced with the remaining play time of the ad in seconds. | `'Advertisement [remainingTime]s'` | `string`    |
+| `skipOffset`    | optional | In order to enable skipping from the start set the delay to `0`, to show the skip button after 5 seconds set it to `5`. Setting a general skipOffset is discouraged. Note that linear creatives carrying a skipsoffet attribute will override the general player setting. By default the player does not set a general skipoffset, so a skip button will only be shown, if an ad has a specific skipoffset attached. |  `0`  | `integer`   |
+| `startOpen`     | optional | Per default the player will start fully expanded, if a valid ad can be played. Setting this option to `false` will trigger an expand animation instead once the player comes into view. Default is `true`.              | `'false'`        | `string`    |
+| `endingScreen`  | optional | By default the player will not close, but show the ending screen when an advertisement is complete (last frame of the ad and a replay button, if an advertisment comes with an endcard that will be shown). If set to `false` the player will collapse. Some VPAID creatives can cause issues with ending screen or replay behaviour. Default is `true`.              | `'true'`         | `string`    |
+| `desiredBitrate`| optional | You can specify a target bitrate for the creative, higher values will increase video quality but will cost bandwidth. Value is given in kpbs. Default is `700`.                       | `800`            | `integer`   |
+| `visibilityThreshold`| optional | Defines the percentage of the player which has to be in the visible area to play and pause the advertisment. The default is `50`.                           | `50`             | `integer`   |

dev-docs/bidders/visx.md

@@ -72,7 +72,7 @@ Best practices:
 
 ### Configuration: Video
 
-The YOC VIS.X adapter responds with VAST XML (in the 'vastXml' field) and expects client-side caching enabled.
+The YOC VIS.X Prebid.js adapter responds with VAST XML (in the `vastXml` field) and expects client-side caching enabled. To enable it, use the following settings:
 
 ```javascript
 pbjs.setConfig({
@@ -103,12 +103,7 @@ pbjs.setConfig({
 |-------|----------|-------------------------------------|------------|----------|
 | `context`     | required | The video context, only 'instream' is allowed. | `'instream'` | `string` |
 | `playerSize`  | required | The size (width, height) of the video player on the page, in pixels. | `[640, 480]` | `integer array` |
-| `mimes`       | required | Content MIME types supported. | `['video/mp4', 'video/x-ms-wmv']` | `string array` |
-| `protocols`   | required | Array of supported video protocols. Refer to List 5.8 of IAB OpenRTB 2.5 (e.g., VAST 3.0 Wrapper). | `[2,3,5,6]` | `integer array` |
-| `api`         | optional | List of supported API frameworks for this impression. Refer to List 5.6 of IAB OpenRTB 2.5 (e.g., VPAID 2.0). If an API is not explicitly listed, it is assumed not to be supported. | `[2]` | `integer array` |
-| `minduration` | optional | Minimum video ad duration in seconds. | `5` | `integer` |
-| `maxduration` | optional | Maximum video ad duration in seconds. | `30` | `integer` |
-| `skip`        | optional | Indicates if the player will allow the video to be skipped, where 0 = no, 1 = yes. | `1` | `integer` |
+| `mimes`       | optional | Content MIME types supported. | `['video/mp4', 'video/x-ms-wmv']` | `string array` |
 
 ### Example of Banner Ad unit
 
@@ -117,13 +112,13 @@ var bannerAdUnit = {
     code: 'bannerAdUnit1',
     mediaTypes: {
         banner: {
-            sizes: [[320, 480], [728, 90]]             // required
+            sizes: [[320, 480], [728, 90]]    // required
         }
     },
     bids: [{
         bidder: 'visx',
         params: {
-            uid: '903536'           // required
+            uid: '903536'                     // required
         }
     }]
 };
@@ -136,20 +131,15 @@ var videoAdUnit = {
     code: 'videoAdUnit1',
     mediaTypes: {
         video: {
-            context: 'instream',                       // required
-            playerSize: [400, 300],                    // required
-            mimes: ['video/mp4', 'video/x-ms-wmv'],    // required
-            protocols: [2, 3, 5, 6],                   // required
-            api: [2],                                  // optional
-            minduration: 5,                            // optional
-            maxduration: 30,                           // optional
-            skip: 1                                    // optional
+            context: 'instream',              // required
+            playerSize: [400, 300],           // required
+            mimes: ['video/mp4']              // optional, required by Prebid Server
         }
     },
     bids: [{
         bidder: 'visx',
         params: {
-            uid: '921068'           // required
+            uid: '921068'                     // required
         }
     }]
 };

dev-docs/modules/floors.md

@@ -354,14 +354,14 @@ While some attributes are common in both schema versions, for completeness, all
 | data.modelGroups[].skipRate | integer | skipRate is a random function whose input value is any integer 0 through 100 to determine when to skip all floor logic, where 0 is always use floor data and 100 is always skip floor data. The use case is for publishers or floor providers to learn bid behavior when floors are applied or skipped. Analytics adapters will have access to model version (if defined) when skipped is true to signal the module is in floors mode. | 0 |
 | data.modelGroups[].modelVersion | string | Used by floor providers to train on model version performance. The expectation is a floor provider’s analytics adapter will pass the model verson back for algorithm training. | - |
 | data.modelGroups[].modelWeight | integer | Used by the module to determine when to apply the specific model. All weights will be normalized and applied at runtime. Futher clarification will be provided in examples below. | - |
-| data.schema | object | Allows for flexible definition of how floor data is formatted. | - |
+| data.modelGroups[].schema | object | Allows for flexible definition of how floor data is formatted. | - |
 | data.modelGroups[].schema.delimiter | string | Character separating the floor keys. | '\|' |
 | data.modelGroups[].schema.fields | array of strings | Supported pre-defined values are: gptSlot, adUnitCode, mediaType, size | - |
 | data.modelGroups[].values | key / values | A series of attributes representing a hash of floor data in a format defined by the schema object. | - |
 | data.modelGroups[].values."rule key" | string | Delimited field of attribute values that define a floor. | - |
 | data.modelGroups[].values."rule floor value" | float | The floor value for this key. | - |
 | data.modelGroups[].default | float | Floor used if no matching rules are found. | - |
-| additionalSchemaFields | object | Object contain the lookup function to map custom schema.fields | - |
+| additionalSchemaFields | object | Object contain the lookup function to map custom schema.fields. Not supported by Prebid Server. | - |
 | additionalSchemaFields."custom key" | string | custom key name | - |
 | additionalSchemaFields."key map function" | function | Function used to lookup the value for that particular custom key | - |
 

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

@@ -19,19 +19,25 @@ sidebarType : 1
 
 ## Overview
 
-This module enables targeting and tracking at the ad server adunit level.
+This module enables bidder targeting and tracking at the ad server ad slot level.
 
-Enabled by default if compiled into your package, this module will add the [Prebid Ad Slot](/features/pbAdSlot.html) and matching GAM ad unit name to each ad unit's first-party data before bid requests are sent to the adapters.
+This module is enabled by default if it's compiled into your PBJS package. It will add the [Prebid Ad Slot and GPID](/features/pbAdSlot.html) along with the matching GAM ad unit name to each ad unit's first-party data before bid requests are sent to the adapters.
 
 * **Prebid.js Adapters** - will be able to utilize these values as:
+    * AdUnit.ortb2Imp.ext.gpid="/1111/home-left"
     * AdUnit.ortb2Imp.ext.data.adserver.name="gam"
     * AdUnit.ortb2Imp.ext.data.adserver.adslot="/1111/home"
     * AdUnit.ortb2Imp.ext.data.pbadslot="/1111/home-left"
 * **Prebid Server Adapters** - will see the OpenRTB as:
+    * imp[].ext.gpid
     * imp[].ext.data.adserver.name
     * imp[].ext.data.adserver.adslot
     * imp[].ext.data.pbadslot
 
+{: .alert.alert-info :}
+The Prebid Ad Slot didn't get broad adoption, so it's likely that
+someday we'll deprecate it in favor of the more standard GPID.
+
 ## Configuration
 
 {: .alert.alert-info :}
@@ -67,23 +73,87 @@ pbjs.setConfig({
 
 ## How It Works
 
-When this module is on, it uses the BEFORE_REQUEST_BIDS event to insert functionality that:
+When this module is turned on, it uses the BEFORE_REQUEST_BIDS event to insert functionality that:
 
 - loops through each adunit in the auction
-- maps the adunit to the GPT slot using the same algorithm as setTargetingForGPTAsync including customGptSlotMatching
+- maps the PBJS adunit to the GPT slot using the same algorithm as setTargetingForGPTAsync including customGptSlotMatching
+
+### Defining the AdServer name and adslot
 
 If GPT slot matching succeeds:
 
 - it sets the Adunit ortb2Imp.ext.data.adserver.name to 'gam'
 - it copies the resulting GPT slot name to ortb2Imp.ext.data.adserver.adslot
 
+### Defining Prebid Ad Slot
+
 The customPbAdSlot function is called if it was specified, writing the results to ortb2Imp.ext.data.pbadslot.
-If there's no customPbAdSlot, a default algorithm is used to determine ortb2Imp.ext.data.pbadslot:
+
+If there's no customPbAdSlot function, a default algorithm is used to determine ortb2Imp.ext.data.pbadslot:
 
 - first use the AdUnit's ortb2Imp.ext.data.pbadslot if defined
-- else, see if the AdUnit.code corresponds to a div and if so, try to retrieve a data element from the div called data-adslotid.
+- else, see if the AdUnit.code corresponds to a div-id and if so, try to retrieve a data element from the div called data-adslotid.
 - else if the GPT slot matching succeeded, use the GPT slot name
-- else, just use the AdUnit.code, assuming that that's the ad unit slot
+- else, just use the AdUnit.code
+
+### Defining GPID
+
+Here's what the module does to define GPID:
+
+1. If AdUnit.ortb2Imp.ext.gpid already exists, don't do anything. Assume the publisher or another module has provided the value.
+2. Otherwise, if a customPbAdSlot function was defined by the publisher and the result is not empty, then copy that value to AdUnit.ortb2Imp.ext.gpid.
+3. Otherwise, if a value was found for GAM AdSlot, copy that to AdUnit.ortb2Imp.ext.gpid
+
+## Example customPbAdSlot function
+
+The following customPbAdSlot function will work for many publishers. Assumptions:
+- AdUnits have been registered with [pbjs.addAdUnits](/dev-docs/publisher-api-reference/addAdUnits.html).
+- AdUnit.code is either the GPT slot name or the div-id.
+- The site has unique (non-random) div-ids.
+
+If either of these isn't the case, you'll need to supply your own function.
+
+```
+// Use adunit.ortb2Imp.ext.data.pbadslot if it exists.
+// compare adunit.code to find a single matching slot in GPT
+// if there is a single slot match, just use that slot name
+// finally, there must be multiple slots that match. Define pbadslot as slot#div
+
+pbjs.setConfig({
+    gptPreAuction: {
+	enabled: true, // enabled by default
+	customPbAdSlot: function(adUnitCode, adServerAdSlot) {
+		// get adunit object
+		au=pbjs.adUnits.filter(au => au.code==adUnitCode);
+		if (au.length==0) {
+		    return;
+		}
+
+		// use pbadslot if supplied
+		if (au[0].ort2bImp && au[0].ort2bImp.ext && au[0].ort2bImp.ext.data && au[0].ort2bImp.ext.data.pbadslot) {
+		    return au[0].ort2bImp.ext.data.pbadslot;
+		}
+
+		// confirm that GPT is set up
+		if (!(googletag && googletag.apiReady)) {
+		    return;
+		}
+		// find all GPT slots with this name
+		var gptSlots = googletag.pubads().getSlots().filter(function(gpt) {
+		    return gpt.getAdUnitPath() == adServerAdSlot;
+		});
+		if (gptSlots.length==0) {
+		    return;  // should never happen
+		}
+		if (gptSlots.length==1) {
+		    return adServerAdSlot;
+		}
+		// else the adunit code must be div id. append it.
+		return adServerAdSlot+"#"+adUnitCode;
+	}
+  });
+};
+```
 
 # Further Reading
-- [Prebid Ad Slot](/features/pbAdSlot.html)
+- [Prebid Ad Slot and GPID](/features/pbAdSlot.html)