diff --git a/_data/sidebar.yml b/_data/sidebar.yml index 4a10ea3ab0..d359f3d1f5 100644 --- a/_data/sidebar.yml +++ b/_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 diff --git a/dev-docs/adunit-reference.md b/dev-docs/adunit-reference.md index ad7436892b..266ca9b6c0 100644 --- a/dev-docs/adunit-reference.md +++ b/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. | diff --git a/dev-docs/bidders/admixer.md b/dev-docs/bidders/admixer.md index 80893e09e2..28d99d7c9f 100644 --- a/dev-docs/bidders/admixer.md +++ b/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 diff --git a/dev-docs/bidders/adplus.md b/dev-docs/bidders/adplus.md new file mode 100644 index 0000000000..976e0131d5 --- /dev/null +++ b/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` | \ No newline at end of file diff --git a/dev-docs/bidders/beachfront.md b/dev-docs/bidders/beachfront.md index aa28971a92..1c13275ca6 100644 --- a/dev-docs/bidders/beachfront.md +++ b/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 diff --git a/dev-docs/bidders/goldbach.md b/dev-docs/bidders/goldbach.md new file mode 100644 index 0000000000..6f9b4f7fc5 --- /dev/null +++ b/dev-docs/bidders/goldbach.md @@ -0,0 +1,199 @@ +--- +layout: bidder +title: Goldbach +description: Prebid Goldbach Bidder Adaptor +biddercode: goldbach +media_types: banner, video, native +gdpr_supported: true +prebid_member: true +userIds: criteo, unifiedId, netId, identityLink, flocId, uid2 +schain_supported: true +coppa_supported: true +usp_supported: true +getFloor: true +pbjs: true +pbs: true +--- + +### Table of Contents + +- [Bid Params](#godlbach-bid-params) +- [Video Object](#godlbach-video-object) +- [User Object](#godlbach-user-object) +- [App Object](#godlbach-app-object) +- [Custom Targeting keys](#custom-targeting-keys) +- [Passing Keys Without Values](#godlbach-no-value) +- [User Sync in AMP](#godlbach-amp) +- [Debug Auction](#godlbach-debug-auction) + + + +{: .alert.alert-danger :} +All Goldbach (Xandr) placements included in a single call to `requestBids` must belong to the same parent Publisher. If placements from two different publishers are included in the call, the Goldbach bidder will not return any demand for those placements.
+*Note: This requirement does not apply to adapters that are [aliasing](/dev-docs/publisher-api-reference/aliasBidder.html) the Goldbach adapter.* + +#### Bid Params + +{: .table .table-bordered .table-striped } +| Name | Scope | Description | Example | Type | +|---------------------|----------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-------------------------------------------------------|------------------| +| `placementId` | required | The placement ID from Goldbach. You may identify a placement using the `invCode` and `member` instead of a placement ID. The `placementID` parameter can be either a `string` or `integer` for Prebid.js, however `integer` is preferred. Legacy code can retain the `string` value. **Prebid Server requires an integer value.** | `234234` | `integer` | +| `member` | optional | The member ID from Goldbach. Must be used with `invCode`. | `'12345'` | `string` | +| `invCode` | optional | The inventory code from Goldbach. Must be used with `member`. | `'abc123'` | `string` | +| `publisherId` | optional | The publisher ID from Goldbach. It is used by the Goldbach end point to identify the publisher when `placementId` is not provided and `invCode` goes wrong. The `publisherId` parameter can be either a `string` or `integer` for Prebid.js, however `integer` is preferred. | `12345` | `integer` | +| `frameworks` | optional | Array of integers listing API frameworks for Banner supported by the publisher. | `integer` | +| `user` | optional | Object that specifies information about an external user. See [User Object](#godlbach-user-object) for details. | `user: { age: 25, gender: 0, dnt: true}` | `object` | +| `allowSmallerSizes` | optional | If `true`, ads smaller than the values in your ad unit's `sizes` array will be allowed to serve. Defaults to `false`. | `true` | `boolean` | +| `usePaymentRule` (PBJS) or `use_pmt_rule` (PBS) | optional | If `true`, Xandr will return net price to Prebid.js after publisher payment rules have been applied. | `true` | `boolean` | +| `keywords` | optional | A set of key-value pairs applied to all ad slots on the page. Mapped to [buy-side segment targeting](https://monetize.xandr.com/docs/segment-targeting) (login required). Values can be empty. See [Passing Keys Without Values](#godlbach-no-value) below for examples. Note that to use keyword with the Prebid Server adapter, that feature must be enabled for your account by an Goldbach account manager. | `keywords: { genre: ['rock', 'pop'] }` | `object` | +| `video` | optional | Object containing video targeting parameters. See [Video Object](#godlbach-video-object) for details. | `video: { playback_method: ['auto_play_sound_off'] }` | `object` | +| `app` | optional | Object containing mobile app parameters. See the [App Object](#godlbach-app-object) for details. | `app : { id: 'app-id'}` | `object` | +| `reserve` | optional | Sets a floor price for the bid that is returned. If floors have been configured in the Goldbach Console, those settings will override what is configured here unless 'Reserve Price Override' is checked. See [Xandr docs](https://docs.xandr.com/bundle/monetize_monetize-standard/page/topics/create-a-floor-rule.html) | `0.90` | `float` | +| `position` | optional | Identify the placement as above or below the fold. Allowed values: Unknown: `unknown`; Above the fold: `above`; Below the fold: `below` | `'above'` | `string` | +| `trafficSourceCode` | optional | Specifies the third-party source of this impression. | `'my_traffic_source'` | `string` | +| `supplyType` | optional | Indicates the type of supply for this placement. Possible values are `web`, `mobile_web`, `mobile_app` | `'web'` | `string` | +| `supplyType` | optional | Indicates the type of supply for this placement. Possible values are `web`, `mobile_web`, `mobile_app` | `'web'` | `string` | +| `pubClick` | optional | Specifies a publisher-supplied URL for third-party click tracking. This is just a placeholder into which the publisher can insert their own click tracker. This parameter should be used for an unencoded tracker. This parameter is expected to be the last parameter in the URL. Please note that the click tracker placed in this parameter will only fire if the creative winning the auction is using Goldbach click tracking properly. | `'http://click.adserver.com/'` | `string` | +| `extInvCode` | optional | Specifies predefined value passed on the query string that can be used in reporting. The value must be entered into the system before it is logged. | `'10039'` | `string` | +| `externalImpId` | optional | Specifies the unique identifier of an externally generated auction. | `'bacbab02626452b097f6030b3c89ac05'` | `string` | +| `generate_ad_pod_id`| optional | Signal to Goldbach to split impressions by ad pod and add unique ad pod id to each request. Specific to long form video endpoint only. Supported by Prebid Server, not Prebid JS. | `true` | `boolean` | + + + +#### Video Object + +{: .table .table-bordered .table-striped } +| Name | Description | Type | +|-------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|------------------| +| `minduration` | Integer that defines the minimum video ad duration in seconds. | `integer` | +| `maxduration` | Integer that defines the maximum video ad duration in seconds. | `integer` | +|`context` | A string that indicates the type of video ad requested. Allowed values: `"pre_roll"`; `"mid_roll"`; `"post_roll"`; `"outstream"`. | `string` | +| `skippable` | Boolean which, if `true`, means the user can click a button to skip the video ad. Defaults to `false`. | `boolean` | +|`skipoffset`| Integer that defines the number of seconds until an ad can be skipped. Assumes `skippable` setting was set to `true`. | `integer` | +| `playback_method` | A string that sets the playback method supported by the publisher. Allowed values: `"auto_play_sound_on"`; `"auto_play_sound_off"`; `"click_to_play"`; `"mouse_over"`; `"auto_play_sound_unknown"`. | `string` | +| `frameworks` | Array of integers listing API frameworks supported by the publisher. Allowed values: None: `0`; VPAID 1.0: `1`; VPAID 2.0: `2`; MRAID 1.0: `3`; MRAID 2.0: `4`; ORMMA: `5`; OMID 1.0 `6`. | `Array` | + + + + +#### User Object + +{: .table .table-bordered .table-striped } +| Name | Description | Example | Type | +|-------------------|---------------------------------------------------------------------------------------------------------------------------------|--------------------------------------------------------------------------|------------------| +| `age` | The age of the user. | `35` | `integer` | +| `externalUid` | Specifies a string that corresponds to an external user ID for this user. | `'1234567890abcdefg'` | `string` | +| `segments` | Specifies the segments to which the user belongs. | `[1, 2]` | `Array` | +| `gender` | Specifies the gender of the user. Allowed values: Unknown: `0`; Male: `1`; Female: `2` | `1` | `integer` | +| `dnt` | Do not track flag. Indicates if tracking cookies should be disabled for this auction | `true` | `boolean` | +| `language` | Two-letter ANSI code for this user's language. | `EN` | `string` | + + + + +#### App Object + +Goldbach supports using prebid within a mobile app's webview. If you are interested in using an SDK, please see [Prebid Mobile]({{site.baseurl}}/prebid-mobile/prebid-mobile.html) instead. + +{: .table .table-bordered .table-striped } +| Name | Description | Example | Type | +|-------------------|---------------------------------------------------------------------------------------------------------------------------------|--------------------------------------------------------------------------|------------------| +| `id` | The App ID. | `'B1O2W3M4AN.com.prebid.webview'` | `string` | +| `device_id` | Object that contains the advertising identifiers of the user (`idfa`, `aaid`, `md5udid`, `sha1udid`, or `windowsadid`). | `{ aaid: "38400000-8cf0-11bd-b23e-10b96e40000d" }` | `object` | +| `geo` | Object that contains the latitude (`lat`) and longitude (`lng`) of the user. | `{ lat: 40.0964439, lng: -75.3009142 }` | `object` | + + + +#### Custom Targeting keys + +Goldbach returns custom keys that can be sent to the adserver through bidderSettings: buyerMemberId, dealPriority, and dealCode. The following snippet demonstrates how to add these custom keys as key-value pairs. + +``` +pbjs.bidderSettings = { + godlbach: { + adserverTargeting: [ + { + key: "apn_buyer_memberid", // Use key configured in your adserver + val: function(bidResponse) { + return bidResponse.appnexus.buyerMemberId; + } + }, + { + key: "apn_prio", // Use key configured in your adserver + val: function(bidResponse) { + return bidResponse.appnexus.dealPriority; + } + }, { + key: "apn_dealcode", // Use key configured in your adserver + val: function(bidResponse) { + return bidResponse.appnexus.dealCode; + } + } + ] + } +} +``` + + + +#### Passing Keys Without Values + +It's possible to use the `keywords` parameter to define keys that do not have any associated values. Keys with empty values can be created in Prebid.js and can also be sent through Prebid Server to Goldbach. The following are examples of sending keys with empty values: + + +``` +keywords: { + myKeyword: '', + myOtherKeyword: [''] +} +``` + +The preceding example passes the key `myKeyword` with an empty value. The key `myOtherKeyword` contains an empty value array. + +You can define keys with values and without values in the same `keywords` definition. In this next example, we've defined the key `color` with an array of values: `red`, `blue`, and `green`. We've followed that with the key `otherKeyword` with an empty value array. + +``` +keywords: { + color: ['red', 'blue', 'green'], + otherKeyword: [''] +} +``` + + + +#### User Sync in AMP + +If you are syncing user id's with Prebid Server and are using Goldbach's managed service, see [AMP Implementation Guide cookie-sync instructions](/dev-docs/show-prebid-ads-on-amp-pages.html#user-sync) for details. + + + +#### Mobile App Display Manager Version + +The Goldbach endpoint expects `imp.displaymanagerver` to be populated for mobile app sources +requests, however not all SDKs will populate this field. If the `imp.displaymanagerver` field +is not supplied for an `imp`, but `request.app.ext.prebid.source` +and `request.app.ext.prebid.version` are supplied, the adapter will fill in a value for +`diplaymanagerver`. It will concatenate the two `app` fields as `-` fo fill in +the empty `displaymanagerver` before sending the request to Goldbach. + +#### Debug Auction + +{: .alert.alert-danger :} +Enabling the Goldbach Debug Auction feature should only be done for diagnosing the Goldbach auction. Do not enable this feature in a production setting where it may impact users. + +To understand what is happening behind the scenes during an auction, you can enable a debug auction by adding an `apn_prebid_debug` cookie with a JSON string. For example: + +{% highlight js %} +{ "enabled": true, "dongle": "QWERTY", "debug_timeout": 1000, "member_id": 958 } +{% endhighlight %} + +To view the results of the debug auction, add the `pbjs_debug=true` query string parameter and open your browser's developer console. + +{: .table .table-bordered .table-striped } +| Name | Description | Example | Type | +|-------------------|-----------------------------------------------------------------|-----------------------|------------------| +| `enabled` | Toggle the debug auction to occur | `true` | `boolean` | +| `dongle` | Your account's unique debug password. | `QWERTY` | `string` | +| `member_id` | The ID of the member running the debug auction | `958` | `integer` | +| `debug_timeout` | The timeout for the debug auction results to be returned | `3000` | `integer` | + diff --git a/dev-docs/bidders/iprom.md b/dev-docs/bidders/iprom.md index 5c123a13db..86f0ac647d 100644 --- a/dev-docs/bidders/iprom.md +++ b/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: diff --git a/dev-docs/bidders/limelightDigital.md b/dev-docs/bidders/limelightDigital.md index 6acf929fb6..9714e224f2 100644 --- a/dev-docs/bidders/limelightDigital.md +++ b/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` | diff --git a/dev-docs/bidders/luponmedia.md b/dev-docs/bidders/luponmedia.md index 7c7b46b1b5..598bc5d82e 100644 --- a/dev-docs/bidders/luponmedia.md +++ b/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: diff --git a/dev-docs/bidders/missena.md b/dev-docs/bidders/missena.md index 4b2c853b0c..895cfe8c43 100644 --- a/dev-docs/bidders/missena.md +++ b/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 diff --git a/dev-docs/bidders/smartx.md b/dev-docs/bidders/smartx.md index ecfbcf42be..ed78dc7b10 100644 --- a/dev-docs/bidders/smartx.md +++ b/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` | diff --git a/dev-docs/bidders/visx.md b/dev-docs/bidders/visx.md index f39b0db05d..53a833abf3 100644 --- a/dev-docs/bidders/visx.md +++ b/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 } }] }; diff --git a/dev-docs/modules/floors.md b/dev-docs/modules/floors.md index e5d652df1d..cd081275e5 100644 --- a/dev-docs/modules/floors.md +++ b/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 | - | diff --git a/dev-docs/modules/gpt-pre-auction.md b/dev-docs/modules/gpt-pre-auction.md index 504b648e59..189e5e1dae 100644 --- a/dev-docs/modules/gpt-pre-auction.md +++ b/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) diff --git a/dev-docs/modules/intersectionRtdProvider.md b/dev-docs/modules/intersectionRtdProvider.md new file mode 100644 index 0000000000..a4381b8e92 --- /dev/null +++ b/dev-docs/modules/intersectionRtdProvider.md @@ -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 + } +} +``` + diff --git a/dev-docs/modules/userId.md b/dev-docs/modules/userId.md index e8b39639c3..5da0614e23 100644 --- a/dev-docs/modules/userId.md +++ b/dev-docs/modules/userId.md @@ -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 | diff --git a/dev-docs/modules/yieldmoSyntheticInventoryModule.md b/dev-docs/modules/yieldmoSyntheticInventoryModule.md index e6d044d890..5b49276bd3 100644 --- a/dev-docs/modules/yieldmoSyntheticInventoryModule.md +++ b/dev-docs/modules/yieldmoSyntheticInventoryModule.md @@ -7,6 +7,7 @@ module_code : yieldmoSyntheticInventoryModule display_name : Synthetic Inventory Module enable_download : true sidebarType : 1 +vendor_specific: true --- # Yieldmo Synthetic Inventory Module diff --git a/dev-docs/publisher-api-reference/bidderSettings.md b/dev-docs/publisher-api-reference/bidderSettings.md index c2ddb80c18..ddc7e5b5ec 100644 --- a/dev-docs/publisher-api-reference/bidderSettings.md +++ b/dev-docs/publisher-api-reference/bidderSettings.md @@ -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 @@ -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). +
diff --git a/dev-docs/publisher-api-reference/onEvent.md b/dev-docs/publisher-api-reference/onEvent.md index e322367352..6e779971ca 100644 --- a/dev-docs/publisher-api-reference/onEvent.md +++ b/dev-docs/publisher-api-reference/onEvent.md @@ -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 diff --git a/dev-docs/publisher-api-reference/setConfig.md b/dev-docs/publisher-api-reference/setConfig.md index 1d2904bc70..f9a6641b7b 100644 --- a/dev-docs/publisher-api-reference/setConfig.md +++ b/dev-docs/publisher-api-reference/setConfig.md @@ -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.
+ +## Related Reading + +- [Prebid.js and Ad Server Key Values](/features/adServerKvps.html) diff --git a/features/InterstitialAds.md b/features/InterstitialAds.md index e034212528..67a68304fe 100644 --- a/features/InterstitialAds.md +++ b/features/InterstitialAds.md @@ -11,24 +11,26 @@ sidebarType: 1 * TOC {:toc} -Interstitails ads are often placed at natural transition points of the user's experince, such as moving from one page to the next. These ads are generally center aligned overlaying user content. +Interstitial ads are often placed at natural transition points of the user's experience, such as moving from one page to the next. These ads are generally center-aligned overlaying user content. This document covers how to setup interstitial ad units. {: .alert.alert-warning :} -Please check with each of your bidders to ensure they're reading the interstitial flag from the standard Prebid location. +Please check with each of this AdUnit's bidders to ensure they're reading the interstitial flag from the standard Prebid location. +If the bidder doesn't specifically support interstitials, results may be unexpected. ## How It Works -The intended flow for publishers is the following: -- Publisher traffics interstitial line item with appropriate size(s) ([GAM example](https://support.google.com/admanager/answer/9840201?hl=en)) +The flow for publishers is the following: +- Publisher traffics an interstitial line item with appropriate size(s) ([GAM example](https://support.google.com/admanager/answer/9840201?hl=en)) - Publisher defines ad server interstitial slot on the page ([GAM Example](https://developers.google.com/publisher-tag/samples/display-web-interstitial-ad)) -- Publisher defines the appropriate interstitial ad sizes within appriate adUnit.mediaType and supplies the adUnit Interstitial flag within the [AdUnit.ortb2Imp](/dev-docs/adunit-reference.html#adUnit-interstitial-example) config +- Publisher creates a PBJS AdUnit and defines the appropriate interstitial ad sizes, adUnit.mediaType, and a special interstitial flag +- Publisher adds bidders and parameters that support interstitials to the PBJS AdUnit(s) - Prebid requests bids for interstitial adUnits and invokes the ad server call from the requestBids callback ## Ad Sizes -Publishers are intended to set the desired size in the respective adUnit. +Publishers must set the desired size in the respective adUnit. The below sizes are specials sizes to indicate the ad will be full screen for mobile or tablet devices: - 320x480: Fullscreen mobile phone portrait ad @@ -40,7 +42,6 @@ The below sizes are specials sizes to indicate the ad will be full screen for mo The Prebid Interstitial flag reflects the OpenRTB standard, specifying it at the imp level. - ### Supplying Interstitial Flag If an attribute is specific to an AdUnit, it can be passed this way: @@ -56,7 +57,9 @@ pbjs.addAdUnits({ ortb2Imp: { instl:1 }, - ... + bids: [ + ... bidders that support interstitials ... + ] }); {% endhighlight %} @@ -64,7 +67,7 @@ pbjs.addAdUnits({ ## How Bid Adapters Should Read Interstitial Flag -To access global data, a Prebid.js bid adapter needs only to retrive the interstitial flag from the adUnit like this: +To access global data, a Prebid.js bid adapter needs only to retrieve the interstitial flag from the adUnit like this: {% highlight js %} utils.deepAccess(bidRequest.ortb2Imp, 'instl') diff --git a/features/adServerKvps.md b/features/adServerKvps.md new file mode 100644 index 0000000000..af51c91c24 --- /dev/null +++ b/features/adServerKvps.md @@ -0,0 +1,171 @@ +--- +layout: page_v2 +title: Prebid.js and Ad Server Key Values +description: Prebid.js and Ad Server Key Values +sidebarType: 1 +--- + +# Prebid.js and Ad Server Key Values +{: .no_toc} + +* TOC +{:toc} + + +The point of header bidding is to supply bids into the regular ad server calls. +Prebid.js provides many ways to do this. This document describes the +controls for obtaining auction results. + +## Overview + +Here's the general way PBJS is integrated into the page: +1. Define AdUnits so they can be linked to existing ad server ad slots in the page +1. Set auction parameters +1. Initiate the auction +1. Gather bid responses to send to the ad server + +This last step has historically been called "targeting" in Prebid.js, but really what's +sent to the adserver is a set of Key Value Pairs (KVPs) that serve several purposes: +- **Ad server line item targeting**. These values are used to pick out which line items match the request. Generally targets depend on the hb_pb attribute, but could also include hb_deal and hb_format. +- **Display**. Some of these values are needed for rendering the creative properly when the Prebid line item is chosen, including hb_adid, hb_uuid, hb_size, and for AMP/app hb_cache_host. +- **Reporting**. Some publishers rely on ad server key-values for important business reporting. The keys used for reporting could be any of the above, along with hb_source. + +## Obtaining Auction Results + +### Display and Native + +In the early versions of Prebid.js, there were a couple of basic functions +publishers could use to get the +- [pbjs.setTargetingForGPTAsync](/dev-docs/publisher-api-reference/setTargetingForGPTAsync.html) - matches Google Publisher Toolkit ad slots to Prebid.js AdUnits, obtains the auction results for that adunit, and adds "targeting" values using GPT-provided functions. +- [pbjs.getAdserverTargeting](/dev-docs/publisher-api-reference/getAdserverTargeting.html) - a more generic interface for obtaining KVPs + +All of the other functions available in the [publisher API](/dev-docs/publisher-api-reference.html) for obtaining auction bids came later. + +When there are a lot of adunits and bidders on a page, the number of KVPs being sent +to the ad server can grow pretty large, so it quickly became apparent that many options were needed for controlling which KVPs these functions returned. + +Note that in old versions of Prebid.js, native ad components were passed via ad server KVPs. +That approach has been deprecated -- all implementations should now use [one of the recommended approaches for native](/prebid/native-implementation.html). + +### Video + +Video's always been a different implementation than banners because +it's the video player that controls the ad call, not in-page javascript like +the GPT library. So the [Google Ad Manager Video module](/dev-docs/modules/dfp_video.html) includes the [buildVideoUrl](/dev-docs/publisher-api-reference/adServers.dfp.buildVideoUrl.html) function. + +Publishers using other ad servers need to integrate on their own +using the [pbjs.getAdserverTargetingForAdUnitCode](/dev-docs/publisher-api-reference/getAdserverTargetingForAdUnitCode.html) function to build whatever +needed to pass to the video player. + +## Controls + +Over the years, quite a few options have been added to adjust the number of bids and the exact set of KVPs sent to the ad server. This is an overlapping-but-powerful set of controls. There are often +multiple ways to implement the same requirements, and there's no "wrong" +way to do it. + +The list is ordered by those functions that Prebid recommends starting with: + +1. [enableSendAllBids](/dev-docs/publisher-api-reference/setConfig.html#setConfig-Send-All-Bids) - the grandaddy of targeting options. If false, only the winning set of KVPs will be sent. We recommend leaving this to the default value of true so that all bidders are represented in the final decision and for detailed reporting in the ad server, but setting it to false (aka "Send Top Bid" mode) is the most dramatic way to minimize what's sent to the ad server. +1. [targetingControls.alwaysIncludeDeals](/dev-docs/publisher-api-reference/setConfig.html#setConfig-targetingControls) - this option makes sure that deals are sent along even if another control would have suppressed it. Publishers running deals should set this value to true. +1. [sendBidsControl.bidLimit](/dev-docs/publisher-api-reference/setConfig.html#setConfig-Send-Bids-Control) - this option sorts the bids in CPM order and returns the top N, plus any deals if the 'alwaysIncludeDeals' flag is true. +1. [targetingControls.allowTargetingKeys](/dev-docs/publisher-api-reference/setConfig.html#setConfig-targetingControls) - this resets the default keys defined by Prebid.js, defining which KVPs are sent for the winning set. (e.g. hb_pb) +1. [targetingControls.allowSendAllBidsTargetingKeys](/dev-docs/publisher-api-reference/setConfig.html#setConfig-targetingControls) - similar to allowTargetingKeys but works on the bidder-specific KVPs. (e.g. hb_pb_BIDDER) +1. [bidderSettings.standard.adserverTargeting](/dev-docs/publisher-api-reference/bidderSettings.html) - completely redefine what Prebid produces for the winning bid's KVPs. +1. [bidderSettings.BIDDER.adserverTargeting](/dev-docs/publisher-api-reference/bidderSettings.html) - completely redefine what Prebid produces for the bidder-specific KVPs. +1. [targetingControls.addTargetingKeys](/dev-docs/publisher-api-reference/setConfig.html#setConfig-targetingControls) - This is similar to allowTargetingKeys but adds KVPs to the default set rather than replacing them. +1. [targetingControls.auctionKeyMaxChars](/dev-docs/publisher-api-reference/setConfig.html#setConfig-targetingControls) - This limits the number of characters Prebid is allowed to add to the KVPs. The function will count the number of characters used and will limit to the integer number of bids that won't exceed this count. +1. [sendBidsControl.dealPrioritization](/dev-docs/publisher-api-reference/setConfig.html#setConfig-Send-Bids-Control) - This changes the sort order used by 'bidLimit' to put deals first. It's not useful when alwaysIncludeDeals is specified. + +### Examples + +Here are a few scenarios to give you a sense of the configurability. + +#### Send All KVPs + +If the number of KVPs sent to the ad server is not a concern, then the recommended approach is to Send All Bids and all deals: + +``` +pbjs.setConfig({ + enableSendAllBids: true, + targetingControls: { + alwaysIncludeDeals: true + } +}); +``` + +#### The Bare Minimum for Display Ads + +The opposite approach is to send only the winning set of KVPs directly needed for targeting line items and rendering. + +``` +pbjs.setConfig({ + enableSendAllBids: false, + targetingControls: { + allowTargetingKeys: ['PRICE_BUCKET', 'AD_ID', 'SIZE'] + } +}); +``` + +Note: this example lacks video support, deal support, and doesn't even tell you which bidder won. + +#### Top Two Bids and Deals + +``` +pbjs.setConfig({ + sendBidsControl: { bidLimit: 2 }, + targetingControls: { + alwaysIncludeDeals: true, + allowTargetingKeys: ['BIDDER', 'AD_ID', + 'PRICE_BUCKET', 'SIZE', 'UUID', 'FORMAT', 'DEAL'], + allowSendAllBidsTargetingKeys: ['AD_ID', 'PRICE_BUCKET', 'SIZE', + 'FORMAT', 'DEAL'] + } +}); +``` +Notes: +- this assumes that video creatives are set up refering to HB_UUID rather than bidder-specific UUID values. + +#### Completely Custom KVPs + +Publishers that don't want to use KVPs prefixed with "hb_" can change them with +bidderSettings: + +``` +pbjs.setConfig({ + enableSendAllBids: false +}); +pbjs.bidderSettings={ + standard: { + adserverTargeting: [{ + key: "pb_price", + // note the price granularity assumption below is Medium Granularity + // other options are pbAg (auto), pbCg (custom), pbDg (dense), + // pbHg (high), pbLg (low) + val: function(bidResponse) { return bidResponse.pbMg; } + },{ + key: "pb_size", + val: function(bidResponse) { return bidResponse.size; } + },{ + key: "pb_adid", + val: function(bidResponse) { return bidResponse.adId; } + },{ + key: "pb_uuid", + val: function(bidResponse) { return bidResponse.videoCacheKey; } + },{ + key: "pb_format", + val: function(bidResponse) { return bidResponse.mediaType; } + },{ + key: "pb_bidder", + val: function(bidResponse) { return bidResponse.bidder; } + },{ + key: "pb_deal", + val: function(bidResponse) { return bidResponse.dealId; } + }] + } +}; +``` + +## Related Topics + +- [Prebid.js Publisher API setConfig() routine](/dev-docs/publisher-api-reference/setConfig.html) +- [Ad Ops and Prebid](/adops/before-you-start.html) diff --git a/features/pbAdSlot.md b/features/pbAdSlot.md index 05478a0f76..8da35d6380 100644 --- a/features/pbAdSlot.md +++ b/features/pbAdSlot.md @@ -1,114 +1,151 @@ --- layout: page_v2 -title: Prebid Ad Slot -description: The Prebid Ad Slot +title: Prebid Ad Slot and GPID +description: Prebid Ad Slot and GPID sidebarType: 1 --- -# Prebid Ad Slot +# The Prebid Ad Slot and the GPID +{:.no_toc} -The Prebid AdUnit 'code' is a mixed attribute that's generally either the GPT slot name or the HTML div ID. The undecided nature of the 'code' makes it harder to utilize for reporting and auction targeting. +* TOC +{:toc} -The `Prebid Ad Slot` is an optional inventory management convention allowing publishers to supply a descriptive and stable label for each ad on the page. This makes it possible to have more granular reporting and better deal targeting. +Prebid Ad Slot and the Global Placement ID (GPID) are overlapping conventions that allow publishers to identify ad inventory on their pages so bidders and reporting systems can better deal with their sites. + +## Background + +It all starts with how publishers decide to label their ad slots: the places on their pages +where ads can be served. In some ad servers like GAM, these things are called "ad units". +Most publishers use unique ad slot names, but some publishers utilize the same name for every ad slot on their page. e.g. "/homepage" might be the name for 5 different slots. + +It's the case of 'same ad slot names' that Prebid Ad Slot and GPID are +meant to address. + +### The Prebid.js AdUnit + +When Prebid.js was developed in 2015, they needed a data structure that would link each ad slot to the bidders and parameters involved in the auction for that slot. Thus was born the Prebid.js [AdUnit](/dev-docs/adunit-reference.html). The AdUnit 'code' is what links this object to the adserver's ad slot. Because some pubs use the same ad slot name everywhere, AdUnit.code is a mixed attribute that can be either the ad slot name **or** the HTML div ID. The undecided nature of AdUnit.code makes it hard to utilize for reporting and auction targeting. + +### The Prebid Ad Slot + +The 'Prebid Ad Slot' was developed in Prebid.js v3 as an optional inventory management convention allowing publishers to supply a descriptive and stable label for each ad on the page. This makes it possible to have more granular reporting and better deal targeting. +However, the PB ad slot is not an industry standard convention, so didn't gain +much traction. + +### The GPID + +The Global Placement ID (GPID) was an initiative in the Fall of 2021 led +by the TradeDesk to solve the problem of inventory identification in an industry-wide way. i.e. Buyers want to be able to identify ad slots in a unique way even +when the publisher uses the same ad slot name multiple times. + +The original suggestion for GPID was to simply append the HTML div element id (aka the 'div-id') to the ad slot name. But some publishers generate div-ids randomly, so the definition of GPID has become: + +``` +imp[].ext.gpid: ADSLOTNAME#UNIQUIFIER +``` +Where ADSLOTNAME is the ad server's slot name (e.g. /1111/homepage) and UNIQUIFIER is something that makes the ADSLOTNAME different from others. Normally it's a +div-id, but if div-ids are random, it can be something else. The "#UNIQUIFIER" is only required if the ADSLOTNAME isn't unique enough on its own. {: .alert.alert-info :} -The Prebid Ad Slot was introduced with Prebid.js 3.x. +The Prebid Ad Slot didn't ever get broad adoption, so it's likely that +someday we'll deprecate it in favor of the more standard GPID. -## A Scenario +## Defining Prebid Ad Slot and GPID -1. The publisher utilizes the same 'slotname' in the page for multiple holes-in-the-page, differentiating in the ad server by size. e.g. -- defineSlot('/1111/homepage', [[300,250]], 'div-293rj893p9wje9we9fj'); -- defineSlot('/1111/homepage', [[728,90]], 'div-j98s9u9usj987665da'); -- defineSlot('/1111/homepage', [[160,600]], 'div-B2q3s4gseshekhsei9sh'); -2. In order to be able to display the right ad in the right hole, the Prebid AdUnit therefore sets the 'code' to the div ID instead of the slotname. -3. The div ID in this case is a random number, not very useful for reporting. -4. Therefore, to get a stable ID that's useful from a business perspective to identify a hole-in-the-page, the publisher -decides to add another identifier... the Prebid Ad Slot. -5. The publisher adds a function to the page that annotates each Prebid AdUnit in the auction with the `pbadslot`. -6. Participating bid adapters read the `pbadslot` and can target deals to them. -7. Participating analytics adapters read the `pbadslot` for more granular reporting. - -Example page function: -{% highlight js %} - -// Use adunit.ortb2Imp.ext.data.pbadslot if it exists. Otherwise, if the -// the adunit.code is a div ID, then look for a data-adslotid attribute, then look a matching slot in GPT -// Otherwise, just use the AdUnit.code -var setPbAdSlot = function setPbAdSlot(adUnits) { - // set pbadslot for all ad units - adUnits.forEach(function (adUnit) { - if (!adUnit.ortb2Imp) { - adUnit.ortb2Imp = {} - } - if (!adUnit.ortb2Imp.ext) { - adUnit.ortb2Imp.ext = {}; - } - if (!adUnit.ortb2Imp.ext.data) { - adUnit.ortb2Imp.ext.data = {}; - } - - // use existing pbadslot if it is already set - if (adUnit.ortb2Imp.ext.data.pbadslot) { - return; - } - - // check if AdUnit.code has a div with a matching id value - const adUnitCodeDiv = document.getElementById(adUnit.code); - if (adUnitCodeDiv) { - // try to retrieve a data element from the div called data-adslotid. - if (adUnitCodeDiv.dataset.adslotid) { - adUnit.ortb2Imp.ext.data.pbadslot = adUnitCodeDiv.dataset.adslotid; - return; - } - // Else if AdUnit.code matched a div and it's a banner mediaType and googletag is present - if (adUnit.mediaTypes && typeof adUnit.mediaTypes === 'object' && adUnit.mediaTypes.banner && adUnit.mediaTypes.banner.sizes && window.googletag && googletag.apiReady) { - var gptSlots = googletag.pubads().getSlots(); - // look up the GPT slot name from the div. - var linkedSlot = gptSlots.find(function (gptSlot) { - return (gptSlot.getSlotElementId() === adUnitCodeDiv.id); - }); - if (linkedSlot) { - adUnit.ortbImp.ext.data.pbadaslot = linkedSlot.getAdUnitPath(); - return; - } - } - } - // Else, just use the AdUnit.code, assuming that it's an ad unit slot - adUnit.ortb2Imp.ext.data.pbadslot = adUnit.code; - }); -}; +There are two ways a publisher can inject these values into the header bidding auctions: -pbjs.onEvent('beforeRequestBids', setPbAdSlot); +1. Supply them manually on the PBJS AdUnits +2. Install the [GPT Pre-Auction module](/dev-docs/modules/gpt-pre-auction.html) -{% endhighlight %} +### Defining them on the PBJS Ad Unit -## How It Works +#### Example 1 - unique ad slot names -The Prebid Ad Slot is just a convention -- it's a form of adunit-specific first party data -stored under `adunit.ortb2Imp.ext.data.pbadslot`. -It can be utilized by any code ready to look for it. +In this example, there's no need for the "UNIQUIFIER" string because every ad slot +on the publisher page is already unique. -It's intended to be specified via Prebid.js in one of two ways: +``` +pbjs.addAdUnits({ + code: '/1111/homepage-leftnav', + ortb2Imp: { + ext: { + gpid: "/1111/homepage-leftnav", + data: { + pbadslot: "/1111/homepage-leftnav" + } + } + }, + mediaTypes: ... + bids: ... +}); +``` + +#### Example 2 - duplicate ad slots + +In this example, the publisher's ad slots all have the same name, but at least + the div-ids are unique. + +``` +pbjs.addAdUnits({ + code: 'div-leftnav', + ortb2Imp: { + ext: { + gpid: "/1111/homepage#div-leftnav", + data: { + pbadslot: "/1111/homepage#div-leftnav" + } + } + }, + mediaTypes: ... + bids: ... +}); +``` -1. Either directly on the AdUnit itself -2. Or defined during the run of a function before the auction +#### Example 3 - duplicate ad slots, random div IDs -The function could determine the pbadslot in any way that produces a stable value useful for targeting and reporting. -Some scenarios that could be supported: +In this example, the publisher utilizes the same 'slotname' in the page for multiple holes-in-the-page, differentiating in the ad server by size. They also use random div-ids. e.g. +- defineSlot('/1111/homepage', [[300,250]], 'div-293rj893p9wje9we9fj'); +- defineSlot('/1111/homepage', [[728,90]], 'div-j98s9u9usj987665da'); -- parse a substring of the ad server's slot name -- use a custom div data element ID, else the AdUnit.code -- use the AdUnit.ortb2Imp.ext.data.pbadslot as a default rather than primary -- support a different ad server +``` +pbjs.addAdUnits({ + code: 'div-293rj893p9wje9we9fj', + ortb2Imp: { + ext: { + gpid: "/1111/homepage#300x250", + data: { + pbadslot: "/1111/homepage#300x250" + } + } + }, + mediaTypes: ... + bids: ... +},{ + code: 'div-j98s9u9usj987665da', + ortb2Imp: { + ext: { + gpid: "/1111/homepage#728x90", + data: { + pbadslot: "/1111/homepage#728x90" + } + } + }, + mediaTypes: ... + bids: ... +}); +``` ## Prebid Server -The OpenRTB location for the Prebid Ad Slot is `imp[].ext.data.pbadslot`: +The Prebid Server Bid Adapter just sends the values to the conventional OpenRTB locations: +- Prebid Ad Slot is `imp[].ext.data.pbadslot` +- GPID is `imp[].ext.gpid` + +Mobile and AMP Stored Requests should place the values there as desired. -- The Prebid SDK will place the value there. -- AMP Stored Requests should place the value there if desired. -- Server-side bid and anlytics adapters may be modified to read the value. +Server-side bid and anlytics adapters may be modified to read the value. ## Further Reading -- The [onEvent()](/dev-docs/publisher-api-reference/onEvent.html) function +- [GPT Pre-Auction Module](/dev-docs/modules/gpt-pre-auction.html) +- [Ad Unit Reference](/dev-docs/adunit-reference.html) diff --git a/prebid-mobile/pbm-api/android/pbm-targeting-params-android.md b/prebid-mobile/pbm-api/android/pbm-targeting-params-android.md index 01cce946bc..9fc0fbaa4e 100755 --- a/prebid-mobile/pbm-api/android/pbm-targeting-params-android.md +++ b/prebid-mobile/pbm-api/android/pbm-targeting-params-android.md @@ -168,9 +168,10 @@ Example: BannerAdUnit bannerAdUnit = new BannerAdUnit("PREBID_SERVER_CONFIGURATION_ID", 300, 250); bannerAdUnit.setUserKeyword("my_key", "my_value"); BannerBaseAdUnit.Parameters parameters = new BannerBaseAdUnit.Parameters(); -parameters.setApi(Arrays.asList(new Signals.Api(6, 7))); +parameters.setApi(Arrays.asList(new Signals.Api(7))); ``` +Note that the OMID value for imp.banner/video/native.api field should be 7, as defined by the IAB in the [OMSDK v1.2 document](https://s3-us-west-2.amazonaws.com/omsdk-files/docs/Open+Measurement+SDK+Onboarding_version_1.2.pdf). ### Inventory (Context) Keywords diff --git a/prebid-mobile/pbm-api/ios/pbm-targeting-ios.md b/prebid-mobile/pbm-api/ios/pbm-targeting-ios.md index a118da3145..6c1700b670 100644 --- a/prebid-mobile/pbm-api/ios/pbm-targeting-ios.md +++ b/prebid-mobile/pbm-api/ios/pbm-targeting-ios.md @@ -219,7 +219,7 @@ parameters.api = [Signals.Api(7)] adUnit.setParameters(parameters); ``` - +Note that the OMID value for imp.banner/video/native.api field should be 7, as defined by the IAB in the [OMSDK v1.2 document](https://s3-us-west-2.amazonaws.com/omsdk-files/docs/Open+Measurement+SDK+Onboarding_version_1.2.pdf). ## Inventory (Context) Keywords diff --git a/prebid-server/developers/add-new-bidder-java.md b/prebid-server/developers/add-new-bidder-java.md index 4a94b172af..5e56b338f4 100644 --- a/prebid-server/developers/add-new-bidder-java.md +++ b/prebid-server/developers/add-new-bidder-java.md @@ -58,6 +58,10 @@ Occasionally, we'll introduce changes to the core framework as part of our ongoi Please be attentive in reading and responding to emails and [GitHub issues](https://github.com/prebid/prebid-server-java/issues) from publishers, hosts, and Prebid.org project maintainers. If we receive complaints about your bid adapter and you do not respond to our communications, we may disable your adapter by default or remove it from the project entirely. +## Generic Adapter + +Before creating your own bid adapter, consider looking into [generic adapter implementation](https://github.com/prebid/prebid-server-java/blob/master/src/main/java/org/prebid/server/bidder/GenericBidder.java). Its main purpose is to simplify testing of PBS. As this adapter just passes requests through without any additional manipulations with data, it can be used to test behaviour of PBS core logic. But, it can be also used as template for simple bid adapters or even for aliasing the very basic ones. + ## Create Your Adapter Prebid Server bid adapters consist of several components: bidder config yaml, bidder parameters, bid adapter code, configuration for framework and default configuration(.yaml) values. This chapter will guide you though each component.