Skip to content

Commit

Permalink
Enhancing docs for Ad Server KVPs (#3447)
Browse files Browse the repository at this point in the history
* Create generic bidder documentation (#3413)

* Fixed typo

* Added Generic bidder docs

* iProm Bid Adapter: update versions included (#3420)

per pr -> prebid/Prebid.js#7700

* add first-party data support to beachfront doc (#3418)

Co-authored-by: John Salis <john@beachfront.com>

* new bidderSettings field - allowZeroCpmBids (#3414)

* add native support (#3409)

* Missena Bid Adapter: update with prebid compliance (#3408)

* Missena Bid Adapter: update with prebid compliance

per pr -> prebid/Prebid.js#7648

* update versioning to include not in 5.x

* Add Intersection RTD Provider docs (#3407)

* upd docs

* Update dev-docs/modules/intersectionRtdProvider.md

Co-authored-by: Andrew <fowler446@users.noreply.github.com>

* Limelight Digital Bid Adapter: Add optional Publisher ID field (#3405)

* smartx Bid Adapter: refactor descriptions and adding "visibilityThreshold" (#3403)

* initial commit

* adjustments

* adjustments

* adjustments

* typo, further adjustments

* removed userIds and schain support

* Added optionals to outstream and made formatting

* Update smartx.md

minor edits for clarification and readability.

* adjusted outstream_options

* remove outstream_function, added pbjs_version_notes

* bugfix outstream options for default outstream renderer configuration

* refactor descriptions and adding "visibilityThreshold"

Co-authored-by: Gino <adtech@smartclip.tv>
Co-authored-by: Jean Stemp <38964447+jeanstemp@users.noreply.github.com>

* VIS.X: update docs (#3402)

Update the VIS.X documentation under the latest adapter changes.

* Adplus bid adapter doc added (#3389)

* Adplus bid adapter doc added

* Quotes added to string arguments

Co-authored-by: TCCDENIZ <cansin.deniz@turkcell.com.tr>

* Created gb_xandr.md docs (#3384)

* Create gb_xandr.md

* renamed the file

* Update dev-docs/bidders/goldbach.md

Co-authored-by: Andrew <fowler446@users.noreply.github.com>

* Lupon Media Bid Adapter: update prebid 5 complianc (#3347)

* Lupon Media Bid Adapter: update prebid 5 complianc

per pr -> prebid/Prebid.js#7458

* update not in 5.x

* Update userId.md (#2788)

* gpid docs (#3421)

* fixed broken link (#3423)

* fixed floors doc issue (#3425)

* added api version note (#3434)

* Interstitials (#2869)

* removed sizes from RP bid params

* added interstitial page and config to adUnit

* interstitial page corrections

* Update InterstitialAds.md

* Update InterstitialAds.md

* modified sidebar link

* changed interstitials file name and reference

* wordsmithing

Co-authored-by: MartianTribe <steve@martiantribe.com>
Co-authored-by: bretg <bgorsline@gmail.com>

* added vendor-specific flag (#3437)

* added KVP reference

Co-authored-by: Alex Maltsev <and1sscsgo@gmail.com>
Co-authored-by: Chris Huie <phoenixtechnerd@gmail.com>
Co-authored-by: John Salis <jsalis531@gmail.com>
Co-authored-by: John Salis <john@beachfront.com>
Co-authored-by: jsnellbaker <31102355+jsnellbaker@users.noreply.github.com>
Co-authored-by: AdmixerTech <35560933+AdmixerTech@users.noreply.github.com>
Co-authored-by: Andrew <fowler446@users.noreply.github.com>
Co-authored-by: Ilya Medvedev <medved55rus@gmail.com>
Co-authored-by: Skylinar <53079123+Skylinar@users.noreply.github.com>
Co-authored-by: Gino <adtech@smartclip.tv>
Co-authored-by: Jean Stemp <38964447+jeanstemp@users.noreply.github.com>
Co-authored-by: rrelict <rrelict@users.noreply.github.com>
Co-authored-by: cnsndnz <82813495+cnsndnz@users.noreply.github.com>
Co-authored-by: TCCDENIZ <cansin.deniz@turkcell.com.tr>
Co-authored-by: dveljovicTX <69788339+dveljovicTX@users.noreply.github.com>
Co-authored-by: Patrick McCann <patmmccann@gmail.com>
Co-authored-by: Bryan Szekely <49168870+bszekely1@users.noreply.github.com>
Co-authored-by: MartianTribe <steve@martiantribe.com>
  • Loading branch information
19 people authored Dec 6, 2021
1 parent b0400c1 commit 603a63f
Show file tree
Hide file tree
Showing 24 changed files with 549 additions and 48 deletions.
16 changes: 16 additions & 0 deletions _data/sidebar.yml
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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
Expand Down
2 changes: 1 addition & 1 deletion dev-docs/adunit-reference.md
Original file line number Diff line number Diff line change
Expand Up @@ -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" />

Expand Down
2 changes: 1 addition & 1 deletion dev-docs/bidders/admixer.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
19 changes: 19 additions & 0 deletions dev-docs/bidders/adplus.md
Original file line number Diff line number Diff line change
@@ -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` |
1 change: 1 addition & 0 deletions dev-docs/bidders/beachfront.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
199 changes: 199 additions & 0 deletions dev-docs/bidders/goldbach.md

Large diffs are not rendered by default.

2 changes: 1 addition & 1 deletion dev-docs/bidders/iprom.md
Original file line number Diff line number Diff line change
Expand Up @@ -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:
Expand Down
5 changes: 3 additions & 2 deletions dev-docs/bidders/limelightDigital.md
Original file line number Diff line number Diff line change
Expand Up @@ -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` |
2 changes: 1 addition & 1 deletion dev-docs/bidders/luponmedia.md
Original file line number Diff line number Diff line change
Expand Up @@ -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:
Expand Down
2 changes: 1 addition & 1 deletion dev-docs/bidders/missena.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
15 changes: 8 additions & 7 deletions dev-docs/bidders/smartx.md
Original file line number Diff line number Diff line change
Expand Up @@ -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` |
26 changes: 8 additions & 18 deletions dev-docs/bidders/visx.md
Original file line number Diff line number Diff line change
Expand Up @@ -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({
Expand Down Expand Up @@ -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

Expand All @@ -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
}
}]
};
Expand All @@ -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
}
}]
};
Expand Down
4 changes: 2 additions & 2 deletions dev-docs/modules/floors.md
Original file line number Diff line number Diff line change
Expand Up @@ -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 | - |

Expand Down
75 changes: 75 additions & 0 deletions dev-docs/modules/intersectionRtdProvider.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,75 @@
---
layout: page_v2
title: Intersection Module
display_name: Intersection
description: Real Time Intersection
page_type: module
module_type: rtd
module_code : intersectionRtdProvider
enable_download : true
sidebarType : 1
---

# Intersection Module
{:.no_toc}

* TOC
{:toc}

## Overview

The Intersection module provides intersection for ad slots on the page using
[Intersection Observer API](https://developer.mozilla.org/en-US/docs/Web/API/Intersection_Observer_API).

Implementation works like this:

1) Build the Intersection module into the Prebid.js package with:

```
gulp build --modules=intersectionRtdProvider&...
```

2) Use `setConfig` to instruct the browser to obtain the intersection data

## Configuration

This module is configured as part of the `realTimeData.dataProviders` object:

```
pbjs.setConfig({
"realTimeData": {
auctionDelay: 100,
dataProviders:[{
"name": "intersection",
"waitForIt": true
}]
}
});
```

## Output

For each bidder, the module adds intersection in a JSON format.
Example:
```
{
"intersection":{
'boundingClientRect': {
'left': 10,
'top': 10,
'right': 310,
'bottom': 260,
'width': 300,
'height': 250,
'x': 10,
'y': 10,
},
'intersectionRect': {/* ... */},
'rootRect': {/* ... */},
'intersectionRatio': 0.5,
'isIntersecting': false,
'time': 1636993868145
}
}
```

12 changes: 10 additions & 2 deletions dev-docs/modules/userId.md
Original file line number Diff line number Diff line change
Expand Up @@ -66,8 +66,16 @@ Publishers that want to do this should design their workflow and then set `_pbjs
## Basic Configuration

By including this module and one or more of the sub-modules, a number of new options become available in `setConfig()`,
all of them under the `userSync` object as attributes of the `userIds` array
of sub-objects. The table below has the options that are common across ID systems. See the sections below for specific configuration needed by each system and examples.
under the `userSync` object as attributes of the `userIds` array
of sub-objects. In addition, publishers using Google AdManager may want to sync one of the identifiers as their Google PPID for frequency capping or reporting.
The PPID has strict rules; refer to [Google AdManager documentation](https://support.google.com/admanager/answer/2880055?hl=en) for them.

{: .table .table-bordered .table-striped }
| Param under userSync | Scope | Type | Description | Example |
| --- | --- | --- | --- | --- |
| ppid | Optional | String | Must be a source from the pbjs.getUserIdsAsEids() array | `"pubcid.org"` |

The table below has the options that are common across ID systems. See the sections below for specific configuration needed by each system and examples.

{: .table .table-bordered .table-striped }
| Param under userSync.userIds[] | Scope | Type | Description | Example |
Expand Down
1 change: 1 addition & 0 deletions dev-docs/modules/yieldmoSyntheticInventoryModule.md
Original file line number Diff line number Diff line change
Expand Up @@ -7,6 +7,7 @@ module_code : yieldmoSyntheticInventoryModule
display_name : Synthetic Inventory Module
enable_download : true
sidebarType : 1
vendor_specific: true
---

# Yieldmo Synthetic Inventory Module
Expand Down
7 changes: 7 additions & 0 deletions dev-docs/publisher-api-reference/bidderSettings.md
Original file line number Diff line number Diff line change
Expand Up @@ -43,6 +43,7 @@ Some sample scenarios where publishers may wish to alter the default settings:
| bidCpmAdjustment | standard or adapter-specific | all | n/a | Could, for example, adjust a bidder's gross-price bid to net price. |
| sendStandardTargeting | adapter-specific | 0.13.0 | true | If adapter-specific targeting is specified, can be used to suppress the standard targeting for that adapter. |
| suppressEmptyKeys | standard or adapter-specific | 0.13.0 | false | If custom adserverTargeting functions are specified that may generate empty keys, this can be used to suppress them. |
| allowZeroCpmBids | standard of adapter-specific | 6.2.0 | false | Would allow bids with a 0 CPM to be accepted by Prebid.js and could be passed to the ad server. |

##### 2.1. adserverTargeting

Expand Down Expand Up @@ -218,4 +219,10 @@ See the [example above](#key-targeting-specific-bidder) for example usage.

If a custom adServerTargeting function can return an empty value, this boolean flag can be used to avoid sending those empty values to the ad server.

##### 2.5. allowZeroCpmBids

By default, 0 CPM bids are ignored by Prebid.js entirely. However if there's a valid business reason to allow these bids, this setting can be enabled to allow
either specific bid adapter(s) or all bid adapters the permission for these bids to be processed by Prebid.js and potentially sent to the respective ad server
(depending on the Prebid.js auction results).

<hr class="full-rule" />
2 changes: 1 addition & 1 deletion dev-docs/publisher-api-reference/onEvent.md
Original file line number Diff line number Diff line change
Expand Up @@ -12,7 +12,7 @@ This routine allows the page (or module) to create a callback function that's in

**Returns**: none

See the [getEvents](/publisher-api-reference/getEvents.html) function for the full list of eventTypes supported.
See the [getEvents](/dev-docs/publisher-api-reference/getEvents.html) function for the full list of eventTypes supported.

The optional `id` parameter provides more finely-grained event
callback registration. This makes it possible to register callback
Expand Down
4 changes: 4 additions & 0 deletions dev-docs/publisher-api-reference/setConfig.md
Original file line number Diff line number Diff line change
Expand Up @@ -1386,3 +1386,7 @@ ERROR: setConfig options must be an object
If you don't see that message, you can assume the config object is valid.

<hr class="full-rule" />

## Related Reading

- [Prebid.js and Ad Server Key Values](/features/adServerKvps.html)
Loading

0 comments on commit 603a63f

Please sign in to comment.