diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index f72c668240..53536e800d 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -15,15 +15,15 @@ jobs: name: run markdownlint runs-on: ubuntu-latest steps: - - uses: actions/checkout@v3 + - uses: actions/checkout@v4 with: fetch-depth: 0 - - uses: tj-actions/changed-files@v41 + - uses: tj-actions/changed-files@v44 id: changed-files with: files: '**/*.md' separator: "," - - uses: DavidAnson/markdownlint-cli2-action@v15 + - uses: DavidAnson/markdownlint-cli2-action@v16 if: steps.changed-files.outputs.any_changed == 'true' with: globs: "${{ steps.changed-files.outputs.all_changed_files }},!_includes" diff --git a/_data/sidebar.yml b/_data/sidebar.yml index 892a9936d1..5a509cee5d 100644 --- a/_data/sidebar.yml +++ b/_data/sidebar.yml @@ -1486,14 +1486,6 @@ sectionTitle: subgroup: 3 -- sbSecId: 5 - title: Programmatic Guaranteed - link: /prebid-server/features/pg/pbs-pg-idx.html - isHeader: 0 - isSectionHeader: 0 - sectionTitle: - subgroup: 3 - - sbSecId: 5 title: Modules link: /prebid-server/pbs-modules/ @@ -1801,7 +1793,7 @@ subgroup: 1 - sbSecId: 7 - title: Prebid and MSPA + title: Prebid US Compliance link: /features/mspa-usnat.html isHeader: 0 isSectionHeader: 0 diff --git a/assets/js/download.js b/assets/js/download.js index 09197ae3e7..e5cc8f7538 100644 --- a/assets/js/download.js +++ b/assets/js/download.js @@ -8,7 +8,7 @@ // show all adapters $(".adapters .col-md-4").show(); setPrepickedModules(); - + document.getElementById('download-button').addEventListener('click', function (event) { event.preventDefault(); submit_download(); @@ -112,6 +112,23 @@ }); } + const renameModules = (function() { + const RENAMES = [ + [ + /^8\./, + { + tcfControl: 'gdprEnforcement', + consentManagementTcf: 'consentManagement', + paapiForGpt: 'fledgeForGpt' + } + ] + ]; + return function(version, modules) { + const renames = RENAMES.find(([pat]) => pat.test(version))?.[1] || {}; + return modules.map(mod => renames.hasOwnProperty(mod) ? renames[mod] : mod) + } + })(); + function get_form_data() { var modules = []; var version = $(".selectpicker").val(); @@ -138,7 +155,7 @@ }); return { - modules, + modules: renameModules(version, modules), version, removedModules, }; diff --git a/dev-docs/activity-controls.md b/dev-docs/activity-controls.md index ef227c9d9b..f1f55285bb 100644 --- a/dev-docs/activity-controls.md +++ b/dev-docs/activity-controls.md @@ -152,7 +152,7 @@ For example, this rule would allow bidderX to perform the activity if no higher Activity control rules in Prebid.js can be created by two main sources: * Publisher `setConfig({allowActivities})` as in the examples shown here. When set this way, rules are considered the highest priority value of 1. -* Modules can set activity control rules, e.g. [usersync](/dev-docs/publisher-api-reference/setConfig.html#setConfig-Configure-User-Syncing), [bidderSettings](/dev-docs/publisher-api-reference/bidderSettings.html), the [GPP](/dev-docs/modules/consentManagementGpp.html) or [GDPR](/dev-docs/modules/gdprEnforcement.html) modules. Rules set by modules have a less urgent priority of 10. +* Modules can set activity control rules, e.g. [usersync](/dev-docs/publisher-api-reference/setConfig.html#setConfig-Configure-User-Syncing), [bidderSettings](/dev-docs/publisher-api-reference/bidderSettings.html), the [GPP](/dev-docs/modules/consentManagementGpp.html) or [GDPR](/dev-docs/modules/tcfControl.html) modules. Rules set by modules have a less urgent priority of 10. When rules are processed, they are sorted by priority, and all rules of the same priority are considered to happen at the same time. The details: @@ -234,7 +234,7 @@ If `allow` is not defined, the rule is assumed to assert **true** (i.e. allow th #### Always include a particular bidder in auctions -This is similiar to the 'vendor exception' feature of the [GDPR Enforcement Module](/dev-docs/modules/gdprEnforcement.html). This would always allow bidderA to participate in the auction, even without explicit consent in GDPR scenarios. It might indicate, for instance, that this is a 'first party bidder'. +This is similiar to the 'vendor exception' feature of the [TCF Control Module](/dev-docs/modules/tcfControl.html). This would always allow bidderA to participate in the auction, even without explicit consent in GDPR scenarios. It might indicate, for instance, that this is a 'first party bidder'. ```javascript pbjs.setConfig({ diff --git a/dev-docs/add-rtd-submodule.md b/dev-docs/add-rtd-submodule.md index fbf85669cf..b17f43f36e 100644 --- a/dev-docs/add-rtd-submodule.md +++ b/dev-docs/add-rtd-submodule.md @@ -123,7 +123,7 @@ submodule('realTimeData', subModuleObject); Several of the interfaces get a `userConsent` object. It's an object that carries these attributes: -* [gdpr](/dev-docs/modules/consentManagement.html#bidder-adapter-gdpr-integration) - GDPR +* [gdpr](/dev-docs/modules/consentManagementTcf.html#bidder-adapter-gdpr-integration) - GDPR * [usp](/dev-docs/modules/consentManagementUsp.html#bidder-adapter-us-privacy-integration) - US Privacy (aka CCPA) * [coppa](/dev-docs/publisher-api-reference/setConfig.html#setConfig-coppa) - the Child Online Privacy Protection Act diff --git a/dev-docs/analytics/prebidmanager.md b/dev-docs/analytics/AsteriobidPbm.md similarity index 59% rename from dev-docs/analytics/prebidmanager.md rename to dev-docs/analytics/AsteriobidPbm.md index 40f7936fd4..fa22aa4553 100644 --- a/dev-docs/analytics/prebidmanager.md +++ b/dev-docs/analytics/AsteriobidPbm.md @@ -1,8 +1,8 @@ --- layout: analytics -title: PrebidManager -description: PrebidManager Analytics Adapter -modulecode: prebidmanager +title: Asteriobid PBM +description: Asteriobid PBM Analytics Adapter +modulecode: asteriobidpbm --- #### Registration diff --git a/dev-docs/analytics/eplanning.md b/dev-docs/analytics/eplanning.md index 674a616eb5..70fc8a36b7 100644 --- a/dev-docs/analytics/eplanning.md +++ b/dev-docs/analytics/eplanning.md @@ -3,6 +3,7 @@ layout: analytics title: ePlanning description: ePlanning Analytics Adapter modulecode: eplanning +pbjs_version_notes: removed in 9.0 --- #### Registration diff --git a/dev-docs/analytics/growthcode.md b/dev-docs/analytics/growthcode.md index 37ac5e3647..c1947aff27 100644 --- a/dev-docs/analytics/growthcode.md +++ b/dev-docs/analytics/growthcode.md @@ -16,6 +16,7 @@ Please visit [growthcode.io](https://growthcode.io/) for more information. #### Analytics Options +{: .table .table-bordered .table-striped } | Param enableAnalytics | Scope | Type | Description | Example | |-----------------------|----------|--------|---------------------------------------------------------|--------------------------| | provider | Required | String | The name of this Adapter. | `"growthCodeAnalytics"` | diff --git a/dev-docs/analytics/marsmedia.md b/dev-docs/analytics/marsmedia.md deleted file mode 100644 index c1ebc51008..0000000000 --- a/dev-docs/analytics/marsmedia.md +++ /dev/null @@ -1,10 +0,0 @@ ---- -layout: analytics -title: MarsMedia -description: MarsMedia Analytics Adapter -modulecode: marsmedia ---- - -#### Registration - -Please visit [mars.media](https://mars.media/#!group) for more information. diff --git a/dev-docs/analytics/sharethrough.md b/dev-docs/analytics/sharethrough.md index 4c50e6a3ed..a3fb0791db 100644 --- a/dev-docs/analytics/sharethrough.md +++ b/dev-docs/analytics/sharethrough.md @@ -36,7 +36,7 @@ gulp bundle --modules=gptPreAuction,sharethroughBidAdapter,sharethroughAnalytics Please note that the above snippet is a "bare bones" example - you will likely want to include other modules as well. A more realistic example might look something like the example below (with other bid adapters also included in the list as needed): ```sh -gulp bundle --modules=gptPreAuction,consentManagement,consentManagementGpp,consentManagementUsp,enrichmentFpdModule,gdprEnforcement,sharethroughBidAdapter,sharethroughAnalyticsAdapter +gulp bundle --modules=gptPreAuction,consentManagementTcf,consentManagementGpp,consentManagementUsp,enrichmentFpdModule,tcfControl,sharethroughBidAdapter,sharethroughAnalyticsAdapter ``` Enable the Sharethrough Analytics Adapter in Prebid.js using the analytics provider `sharethrough` as seen in the **Example Configuration** section. diff --git a/dev-docs/analytics/sigmoid.md b/dev-docs/analytics/sigmoid.md index 33596e9fc4..cf4bc79a83 100644 --- a/dev-docs/analytics/sigmoid.md +++ b/dev-docs/analytics/sigmoid.md @@ -2,6 +2,7 @@ layout: analytics title: Sigmoid description: Sigmoid Analytics Adapter +pbjs_version_notes: removed in 9.0 modulecode: sigmoid --- diff --git a/dev-docs/analytics/smartyads.md b/dev-docs/analytics/smartyads.md new file mode 100644 index 0000000000..1d522cd655 --- /dev/null +++ b/dev-docs/analytics/smartyads.md @@ -0,0 +1,16 @@ +--- +layout: analytics +title: Smartyads +description: Smartyads Analytics Adapter +modulecode: smartyads +--- + +#### Example Configuration + +```javascript +pbjs.que.push(function () { + pbjs.enableAnalytics({ + provider: 'smartyads' + }); +}); +``` diff --git a/dev-docs/analytics/sonobi.md b/dev-docs/analytics/sonobi.md index 3cf0340b71..c60b4f49de 100644 --- a/dev-docs/analytics/sonobi.md +++ b/dev-docs/analytics/sonobi.md @@ -3,6 +3,7 @@ layout: analytics title: Sonobi description: Sonobi Analytics Adapter modulecode: sonobi +pbjs_version_notes: removed in 9.0 enable_download: false --- diff --git a/dev-docs/analytics/sovrn.md b/dev-docs/analytics/sovrn.md index e9dea298b0..c68bdc5e39 100644 --- a/dev-docs/analytics/sovrn.md +++ b/dev-docs/analytics/sovrn.md @@ -4,6 +4,7 @@ title: Sovrn description: Sovrn Analytics Adapter modulecode: sovrn prebid_member: true +pbjs_version_notes: removed in 9.0 enable_download: false --- diff --git a/dev-docs/analytics/staq.md b/dev-docs/analytics/staq.md index d5e866f490..35ca122e06 100644 --- a/dev-docs/analytics/staq.md +++ b/dev-docs/analytics/staq.md @@ -2,6 +2,7 @@ layout: analytics title: STAQ description: STAQ Analytics Adapter +pbjs_version_notes: removed in 9.0 modulecode: staq --- diff --git a/dev-docs/bidder-adaptor.md b/dev-docs/bidder-adaptor.md index 49fbc7e540..aaeb9dae4c 100644 --- a/dev-docs/bidder-adaptor.md +++ b/dev-docs/bidder-adaptor.md @@ -352,7 +352,7 @@ Notes on parameters in the bidderRequest object: Some of the data in `ortb2` is also made available through other `bidderRequest` fields: * **refererInfo** is provided so you don't have to call any utils functions. See below for more information. -* **gdprConsent** is the object containing data from the [GDPR ConsentManagement](/dev-docs/modules/consentManagement.html) module. For TCF2+, it will contain both the tcfString and the addtlConsent string if the CMP sets the latter as part of the TCData object. +* **gdprConsent** is the object containing data from the [TCF ConsentManagement](/dev-docs/modules/consentManagementTcf.html) module. For TCF2+, it will contain both the tcfString and the addtlConsent string if the CMP sets the latter as part of the TCData object. * **uspConsent** is the object containing data from the [US Privacy ConsentManagement](/dev-docs/modules/consentManagementUsp.html) module. diff --git a/dev-docs/bidders/adbookpsp.md b/dev-docs/bidders/adbookpsp.md index edef5f1ed2..3e601f64bf 100644 --- a/dev-docs/bidders/adbookpsp.md +++ b/dev-docs/bidders/adbookpsp.md @@ -11,6 +11,7 @@ coppa_supported: true usp_supported: true pbjs: true pbs: false +pbjs_version_notes: removed in 9.0 sidebarType: 1 --- diff --git a/dev-docs/bidders/adnuntius.md b/dev-docs/bidders/adnuntius.md index d0a04091e8..d720931716 100644 --- a/dev-docs/bidders/adnuntius.md +++ b/dev-docs/bidders/adnuntius.md @@ -86,9 +86,9 @@ pbjs.setBidderConfig({ }); ``` -### Disable cookies for adnuntius +### Disable cookies for Adnuntius -You have the option to tell adnuntius not to set cookies in your browser. This does not mean that third party ads being served through the ad server will not set cookies. Just that Adnuintius will not set it for internal ads. +You have the option to tell adnuntius not to set cookies in your browser. This does not mean that third party ads being served through the ad server will not set cookies. Just that Adnuntius will not set it for internal ads. ```js pbjs.setBidderConfig({ @@ -101,6 +101,21 @@ pbjs.setBidderConfig({ Use cookie will always be set to true by default. Changing it to false will disable cookies. +### Trigger Advertiser Transparency Mode in Adnuntius + +You have the option to tell Adnuntius to only serve ads that have their Advertiser's legal name specified. + +```js +pbjs.setBidderConfig({ + bidders: ['adnuntius'], + config: { + advertiserTransparency: true + } +}); +``` + +By default, `advertiserTransparency` is set to `false`, meaning there is no restriction on which ads can deliver. By setting `advertiserTransparency` to `true`, ad delivery is restricted to those that have their Advertiser's legal name specified. + ### Prebid Server Test Request The following test parameters can be used to verify that Prebid Server is working properly with the server-side Adnuntius adapter. the `auId` below will not return a creative. Please substitute it with your own. diff --git a/dev-docs/bidders/aidem.md b/dev-docs/bidders/aidem.md index ea8ba9b2ed..6aeb6266eb 100644 --- a/dev-docs/bidders/aidem.md +++ b/dev-docs/bidders/aidem.md @@ -70,7 +70,7 @@ This module is GDPR and CCPA compliant, and no 3rd party userIds are allowed. {: .table .table-bordered .table-striped } | Name | Scope | Description | Example | Type | |--------|----------|--------------------------------------------------------------------------------------------------|---------|----------| -| `gdpr` | optional | GDPR Object see [Prebid.js doc](https://docs.prebid.org/dev-docs/modules/consentManagement.html) | `{}` | `Object` | +| `gdpr` | optional | GDPR Object see [Prebid.js doc](https://docs.prebid.org/dev-docs/modules/consentManagementTcf.html) | `{}` | `Object` | | `usp` | optional | USP Object see [Prebid.js doc](https://docs.prebid.org/dev-docs/modules/consentManagementUsp.html) | `{}` | `Object` | #### Example Banner ad unit @@ -212,7 +212,7 @@ For video: gulp serve --modules=aidemBidAdapter,dfpAdServerVideo ## FAQs -#### How do I view AIDEM bid request? +### How do I view AIDEM bid request? Navigate to a page where AIDEM is setup to bid. In the network tab, search for requests to `zero.aidemsrv.com/bid/request`. diff --git a/dev-docs/bidders/appnexus.md b/dev-docs/bidders/appnexus.md index a8dff8af88..834f91fe41 100644 --- a/dev-docs/bidders/appnexus.md +++ b/dev-docs/bidders/appnexus.md @@ -45,6 +45,9 @@ All AppNexus (Xandr) placements included in a single call to `requestBids` must #### Bid Params +{: .alert.alert-danger :} +Starting with Prebid.js version 9.0, an update was made to the `appnexusBidAdapter.js` file to remove the support for the `transformBidParams` function. Previously this standard adapter function was used in conjunction of Prebid.js > PBS requests to modify any bid params for that bidder to the bid param format used by the PBS endpoint. Part of the changes for 9.0 in general were to remove these functions from the client-side adapter files, in order to reduce the build size of Prebid.js for those publishers who wanted to make the PBS requests. In the case of our adapter, we instead created a new module named `anPspParamsConverter` that would mimic behavior of the `transformBidParams` function. There's no setup instructions needed on the Prebid.js configs, the module only needs to be included in the Prebid.js build file and it will perform the needed steps. If you have any questions on this change, please reach out to your Microsoft representative and they can help. + {: .alert.alert-danger :} Starting with Prebid.js version 7.36.0, an update was made to the `appnexusBidAdapter.js` file to support bid params in a lower-case underscore format (eg `invCode` to `inv_code`) similar to how the params are formatted for the Prebid Server AppNexus bidder. This change was implemented to streamline publisher setups for both projects instead of maintaining separate versions of the same params depending on what setup is used. To avoid breaking changes, the old 'camelCase' format is still currently supported for all AppNexus bid params in the `appnexusBidAdapter.js` file. If you are using an older version of Prebid.js, you will need to continue to use the older 'camelCase' format as appropriate. diff --git a/dev-docs/bidders/bizzclick.md b/dev-docs/bidders/bizzclick.md deleted file mode 100644 index 15872a4126..0000000000 --- a/dev-docs/bidders/bizzclick.md +++ /dev/null @@ -1,47 +0,0 @@ ---- -layout: bidder -title: BizzClick -description: Prebid BizzClick Bidder Adaptor -biddercode: bizzclick -tcfeu_supported: false -usp_supported: true -coppa_supported: true -schain_supported: true -media_types: banner, video, native -safeframes_ok: true -deals_supported: true -pbjs: true -pbs: true -pbs_app_supported: true -sidebarType: 1 -floors_supported: true -prebid_member: false -fpd_supported: false -gvl_id: none -multiformat_supported: will-bid-on-one -ortb_blocking_supported: true -userIds: all ---- - -### Note - -The Example Bidding adapter requires setup before beginning. Please contact us at .BizzClick will only respond to the first impression and that multiple ad formats of that single impression are not supported. - -### Bid Params for Prebid Server and Prebid Mobile - -{: .table .table-bordered .table-striped } -| Name | Scope | Description | Example | Type | -|---------------|----------|-----------------------|-----------|-----------| -| `sourceId` | required | Unique hash provided by bizzclick | `'6dllcEHSxYdSb6yLmCqE'` | `string` | -| `accountId` | required | Unique name provided by bizzclick | `'bizzclick-test'` | `string` | -| `host` | optional | Bizzclick server region. US East by default | `'us-e-node1'` | `string` | -| `placementId` | required | Deprecated parameter. Please use sourceId instead |`'6dllcEHSxYdSb6yLmCqE'`|`string` | - -### Bid Params for Prebid.js - -{: .table .table-bordered .table-striped } -| Name | Scope | Description | Example | Type | -|---------------|----------|-----------------------|-----------|-----------| -| `sourceId` | required | Unique hash provided by bizzclick | `'6dllcEHSxYdSb6yLmCqE'` | `string` | -| `accountId` | required | Unique name provided by bizzclick | `'bizzclick-test'` | `string` | -| `host` | optional | Bizzclick server region. US East by default | `'us-e-node1'` | `string` | diff --git a/dev-docs/bidders/blasto.md b/dev-docs/bidders/blasto.md new file mode 100644 index 0000000000..cda556c3a6 --- /dev/null +++ b/dev-docs/bidders/blasto.md @@ -0,0 +1,48 @@ +--- +layout: bidder +title: Blasto +description: Prebid Blasto Bidder Adaptor +biddercode: blasto +tcfeu_supported: false +usp_supported: true +coppa_supported: true +schain_supported: true +media_types: banner, video, native +safeframes_ok: true +deals_supported: true +pbjs: true +pbs: true +pbs_app_supported: true +sidebarType: 1 +floors_supported: true +prebid_member: false +fpd_supported: false +gvl_id: none +multiformat_supported: will-bid-on-one +ortb_blocking_supported: true +userIds: all +--- + +### Note + +The Example Bidding adapter requires setup before beginning. Please contact us at . +Blasto will only respond to the first impression. + +### Bid Params for Prebid Server +Blasto supports diffrent regions for the prebid server. By default US East. +Please deploy the prebid config in each of your datacenters with the appropriate regional subdomain. + +{: .table .table-bordered .table-striped } +| Name | Scope | Description | Example | Type | +|---------------|----------|-----------------------|-----------|-----------| +| `sourceId` | required | Unique hash provided by blasto | `'6dllcEHSxYdSb6yLmCqE'` | `string` | +| `accountId` | required | Unique name provided by blasto | `'blasto-test'` | `string` | + +### Bid Params for Prebid.js + +{: .table .table-bordered .table-striped } +| Name | Scope | Description | Example | Type | +|---------------|----------|-----------------------|-----------|-----------| +| `sourceId` | required | Unique hash provided by blasto | `'6dllcEHSxYdSb6yLmCqE'` | `string` | +| `accountId` | required | Unique name provided by blasto | `'blasto-test'` | `string` | +| `host` | optional | Blasto server region. US East by default | `'us-e-node1'` | `string` | diff --git a/dev-docs/bidders/bluebillywig.md b/dev-docs/bidders/bluebillywig.md index 33c8a43772..53ae1c57c0 100644 --- a/dev-docs/bidders/bluebillywig.md +++ b/dev-docs/bidders/bluebillywig.md @@ -11,6 +11,7 @@ schain_supported: true coppa_supported: true usp_supported: true userIds: britepoolId, criteo, id5Id, identityLink, liveIntentId, netId, parrableId, pubCommonId, unifiedId +pbjs_version_notes: removed in 9.0 sidebarType: 1 --- diff --git a/dev-docs/bidders/brightcom.md b/dev-docs/bidders/brightcom.md deleted file mode 100644 index 2953aba6a7..0000000000 --- a/dev-docs/bidders/brightcom.md +++ /dev/null @@ -1,25 +0,0 @@ ---- -layout: bidder -title: Brightcom -description: Prebid Brightcom Bidder Adaptor -top_nav_section: dev_docs -nav_section: reference -pbjs: true -biddercode: brightcom -gvl_id: 883 -tcfeu_supported: true -sidebarType: 1 ---- - -### Note - -The Brightcom bidder adapter requires setup and approval from the Brightcom team. Please reach out to your account manager for more information and to start using it. - -### Bid params - -{: .table .table-bordered .table-striped } - -| Name | Scope | Description | Example | Type | -| ---- | ----- | ----------- | ------- | ---- | -| `publisherId` | required | The publisher ID from Brightcom | `2141020` | `integer` | -| `bidFloor` | optional | The minimum bid value desired | `1.23` | `float` | diff --git a/dev-docs/bidders/brightcomssp.md b/dev-docs/bidders/brightcomssp.md deleted file mode 100644 index d78e661a67..0000000000 --- a/dev-docs/bidders/brightcomssp.md +++ /dev/null @@ -1,30 +0,0 @@ ---- -layout: bidder -title: Brightcom SSP -description: Prebid Brightcom SSP Bidder Adaptor -top_nav_section: dev_docs -nav_section: reference -pbjs: true -biddercode: bcmssp -filename: brightcomSSPBidAdapter -tcfeu_supported: true -usp_supported: true -coppa_supported: true -schain_supported: true -sidebarType: 1 -gvl_id: 883 -floors_supported: true ---- - -### Note - -The Brightcom SSP bidder adapter requires setup and approval from the Brightcom team. Please reach out to your account manager for more information and to start using it. - -### Bid params - -{: .table .table-bordered .table-striped } - -| Name | Scope | Description | Example | Type | -| ---- | ----- | ----------- | ------- | ---- | -| `publisherId` | required | The publisher ID from Brightcom | `2141020` | `integer` | -| `bidFloor` | optional | The minimum bid value desired | `1.23` | `float` | diff --git a/dev-docs/bidders/cointraffic.md b/dev-docs/bidders/cointraffic.md index 336d71f251..e97e89fdf6 100644 --- a/dev-docs/bidders/cointraffic.md +++ b/dev-docs/bidders/cointraffic.md @@ -3,6 +3,7 @@ layout: bidder title: Cointraffic description: Prebid Cointraffic Bidder Adaptor pbjs: true +pbs: true biddercode: cointraffic sidebarType: 1 --- diff --git a/dev-docs/bidders/colossus.md b/dev-docs/bidders/colossus.md index a377f317eb..4b16843149 100644 --- a/dev-docs/bidders/colossus.md +++ b/dev-docs/bidders/colossus.md @@ -14,10 +14,6 @@ pbs_app_supported: true sidebarType: 1 --- -### Disclosure - -This adapter is known to use an HTTP 1 endpoint. Header bidding often generates multiple requests to the same host and bidders are encouraged to change to HTTP 2 or above to help improve publisher page performance via multiplexing. - ### Prebid.Server Bid Params {: .table .table-bordered .table-striped } diff --git a/dev-docs/bidders/colossusssp.md b/dev-docs/bidders/colossusssp.md index 4edb102200..57d78f1ab9 100644 --- a/dev-docs/bidders/colossusssp.md +++ b/dev-docs/bidders/colossusssp.md @@ -22,4 +22,4 @@ sidebarType: 1 | `group_id` | optional | Group Id will be generated on Colossus SSP Platform. Use instead of placement_id | `0` | `integer` | | `traffic` | optional | Type traffic | `'banner'` | `string` | -*For colossus prebid server parametres, look into colossus.md* +*For colossus prebid server parameters, look into colossus.md* diff --git a/dev-docs/bidders/copper6ssp.md b/dev-docs/bidders/copper6ssp.md new file mode 100644 index 0000000000..d9cb4b2f49 --- /dev/null +++ b/dev-docs/bidders/copper6ssp.md @@ -0,0 +1,35 @@ +--- +layout: bidder +title: Copper6SSP +description: Prebid Copper6SSP Bidder Adapter +biddercode: copper6ssp +gpp_sids: usstate_all +tcfeu_supported: false +usp_supported: true +coppa_supported: true +schain_supported: true +deals_supported: false +floors_supported: true +fpd_supported: false +ortb_blocking_supported: false +media_types: banner, video, native +multiformat_supported: will-bid-on-one +userIds: all +pbjs: true +pbs: false +pbs_app_supported: true +safeframes_ok: true +sidebarType: 1 +--- + +### Bid Params + +{: .table .table-bordered .table-striped } +| Name | Scope | Description | Example | Type | +|---------------|----------|--------------|---------------------------------|------------| +| `placementId` | optional | Placement Id | `'0'` | `'string'` | +| `endpointId` | optional | Endpoint Id | `'0'` | `'string'` | + +### Note + +For the prebid server and prebid.js you only need to use one parameter: either placementId or endpointId diff --git a/dev-docs/bidders/cpmstar.md b/dev-docs/bidders/cpmstar.md index 0573d20d60..0c43369a01 100644 --- a/dev-docs/bidders/cpmstar.md +++ b/dev-docs/bidders/cpmstar.md @@ -6,9 +6,11 @@ pbjs: true pbs: true biddercode: cpmstar media_types: banner, video -tcfeu_supported: false +tcfeu_supported: true +gvl_id: 1317 usp_supported: true coppa_supported: true +schain_supported: true sidebarType: 1 --- diff --git a/dev-docs/bidders/dailymotion.md b/dev-docs/bidders/dailymotion.md index 5557b2befb..e418e7db33 100644 --- a/dev-docs/bidders/dailymotion.md +++ b/dev-docs/bidders/dailymotion.md @@ -24,7 +24,7 @@ To use the adapter with any non-test request, you first need to ask an API key f This API key will ensure proper identification of your inventory and allow you to get real bids. -# Configuration options +### Configuration options Before calling this adapter, you need to at least set a video adUnit in an instream context and the API key in the bid parameters: @@ -49,7 +49,29 @@ const adUnits = [ `apiKey` is your publisher API key. For testing purpose, you can use "dailymotion-testing". -# Test Parameters +#### User Sync + +To enable user synchronization, add the following code. Dailymotion highly recommends using iframes and/or pixels for user syncing. This feature enhances DSP user match rates, resulting in higher bid rates and bid prices. Ensure that `pbjs.setConfig()` is called only once. + +```javascript +pbjs.setConfig({ + userSync: { + syncEnabled: true, + filterSettings: { + iframe: { + bidders: '*', // Or add dailymotion to your list included bidders + filter: 'include' + }, + image: { + bidders: '*', // Or add dailymotion to your list of included bidders + filter: 'include' + }, + }, + }, +}); +``` + +### Test Parameters By setting the following bid parameters, you'll get a constant response to any request, to validate your adapter integration: @@ -74,7 +96,7 @@ const adUnits = [ Please note that failing to set these will result in the adapter not bidding at all. -# Sample video AdUnit +### Sample video AdUnit To allow better targeting, you should provide as much context about the video as possible. There are three ways of doing this depending on if you're using Dailymotion player or a third party one. @@ -130,7 +152,12 @@ const adUnits = [ private: false, tags: 'tag_1,tag_2,tag_3', title: 'test video', + url: 'https://test.com/testvideo' topics: 'topic_1, topic_2', + isCreatedForKids: false, + videoViewsInSession: 1, + autoplay: false, + playerVolume: 8 } } }], @@ -139,6 +166,12 @@ const adUnits = [ video: { api: [2, 7], context: 'instream', + mimes: ['video/mp4'], + minduration: 5, + maxduration: 30, + playbackmethod: [3], + plcmt: 1, + protocols: [7, 8, 11, 12, 13, 14] startdelay: 0, w: 1280, h: 720, @@ -160,10 +193,18 @@ Each of the following video metadata fields can be added in bids.params.video. * `private` - True if video is not publicly available * `tags` - Tags for the video, comma separated * `title` - Video title +* `url` - URL of the content * `topics` - Main topics for the video, comma separated * `xid` - Dailymotion video identifier (only applicable if using the Dailymotion player) +* `isCreatedForKids` - [The content is created for children as primary audience](https://faq.dailymotion.com/hc/en-us/articles/360020920159-Content-created-for-kids) + +The following contextual informations can also be added in bids.params.video. + +* `videoViewsInSession` - Number of videos viewed within the current user session +* `autoplay` - Playback was launched without user interaction +* `playerVolume` - Player volume between 0 (muted, 0%) and 10 (100%) -If you already specify [First-Party data](https://docs.prebid.org/features/firstPartyData.html) through the `ortb2` object when calling [`pbjs.requestBids(requestObj)`](https://docs.prebid.org/dev-docs/publisher-api-reference/requestBids.html), we will fallback to those values when possible. See the mapping below. +If you already specify [First-Party data](https://docs.prebid.org/features/firstPartyData.html) through the `ortb2` object when calling [`pbjs.requestBids(requestObj)`](https://docs.prebid.org/dev-docs/publisher-api-reference/requestBids.html), we will collect the following values and fallback to bids.params.video values when applicable. See the mapping below. | From ortb2 | Metadata fields | |---------------------------------------------------------------------------------|-----------------| @@ -174,3 +215,9 @@ If you already specify [First-Party data](https://docs.prebid.org/features/first | `ortb2.site.content.livestream` | `livestream` | | `ortb2.site.content.keywords` | `tags` | | `ortb2.site.content.title` | `title` | +| `ortb2.site.content.url` | `url` | +| `ortb2.app.bundle` | N/A | +| `ortb2.app.storeurl` | N/A | +| `ortb2.device.lmt` | N/A | +| `ortb2.device.ifa` | N/A | +| `ortb2.device.ext.atts` | N/A | diff --git a/dev-docs/bidders/e_volution.md b/dev-docs/bidders/e_volution.md index 5282e7589b..0d061f302c 100644 --- a/dev-docs/bidders/e_volution.md +++ b/dev-docs/bidders/e_volution.md @@ -2,16 +2,24 @@ layout: bidder title: E-volution tech description: Prebid E-volution tech Bidder Adapter -pbjs: true biddercode: e_volution +gpp_sids: usstate_all tcfeu_supported: true +usp_supported: true +coppa_supported: true +schain_supported: true +deals_supported: false +floors_supported: true +fpd_supported: false +ortb_blocking_supported: false media_types: banner, video, native gvl_id: 957 +multiformat_supported: will-bid-on-one +userIds: all +pbjs: true pbs: true pbs_app_supported: true -usp_supported: true -schain_supported: true -userIds: id5Id +safeframes_ok: true sidebarType: 1 --- diff --git a/dev-docs/bidders/ebdr.md b/dev-docs/bidders/ebdr.md index 0fc6be4dd5..d1938b3aff 100644 --- a/dev-docs/bidders/ebdr.md +++ b/dev-docs/bidders/ebdr.md @@ -5,6 +5,7 @@ description: Prebid EngageBDR Bidder Adaptor biddercode: ebdr pbjs: true media_types: video +pbjs_version_notes: removed in 9.0 sidebarType: 1 --- diff --git a/dev-docs/bidders/improvedigital.md b/dev-docs/bidders/improvedigital.md index 0cc21342ff..893e98b235 100644 --- a/dev-docs/bidders/improvedigital.md +++ b/dev-docs/bidders/improvedigital.md @@ -39,11 +39,11 @@ sidebarType: 1 #### Sizes -By default, the adapter doesn't send Prebid ad unit sizes to Improve Digital's ad server and the sizes defined for each placement in the Polaris platform will be used. If the ad server should only respond with creative sizes as defined in Prebid ad unit configuration, turn on `usePrebidSizes` adapter parameter like this: +By default, the adapter sends Prebid ad unit sizes to Improve Digital's ad server. If the ad server should only respond with creative sizes as defined for each placement in the Origin platform, turn off `usePrebidSizes` adapter parameter like this: ```javascript pbjs.setConfig({ - improvedigital: { usePrebidSizes: true } + improvedigital: { usePrebidSizes: false } }); ``` diff --git a/dev-docs/bidders/inmobi.md b/dev-docs/bidders/inmobi.md index be796ccfc0..456433b46b 100644 --- a/dev-docs/bidders/inmobi.md +++ b/dev-docs/bidders/inmobi.md @@ -21,9 +21,11 @@ For queries, write to us at ### User Sync Disclosure -InMobi has partnered with a third party, ID5, to use their ID as our primary user identifier for mobile web supply. We will also rely on ID5 IDs to handle compliance flows related to Data Subject Right requests in our systems. Hence, we require the publisher to use ID5’s sync URL for user syncing and passing the corresponding ID5 ID to InMobi in the bid request. For this purpose, we provide ID5’s sync URL in our Prebid adapter for User ID sync. Note that, InMobi has a direct contract with ID5 for consuming ID5 ID and the user sync via Prebid does not require the publisher to get into a contractual relationship with ID5. +Third-party cookie syncing helps publishers leverage their audience data, enhance targeting capabilities, and drive better ad performance. InMobi third party cookie syncing improves monetization for publishers by giving them a competitive positioning in the digital advertising ecosystem. +Ids for third parties can be synced through our pixel: `https://sync.inmobi.com/prebid?gdpr={GDPR}&gdpr_consent={GDPR_CONSENT}&us_privacy={US_PRIVACY}&redirect={RedirectURL}` . +The RedirectURL should contain uuid macro, which is {ID5UID}. -To opt out of InMobi ads on mobile web inventory or for any other requests, the user needs to visit the Opt-out page on InMobi website (). For opting out of ID5 ID entirely, the user needs to visit ID5’s opt out page: . +To opt out of InMobi ads on web inventory the user needs to visit the Opt-out page on InMobi website `https://www.inmobi.com/page/opt-out/`. ### Bid Params diff --git a/dev-docs/bidders/insticator.md b/dev-docs/bidders/insticator.md index 87880a2ba6..0ec593375a 100644 --- a/dev-docs/bidders/insticator.md +++ b/dev-docs/bidders/insticator.md @@ -16,6 +16,7 @@ multiformat_supported: will-bid-on-any pbjs: true gvl_id: 910 sidebarType: 1 +userIds: all --- ### Bid Params @@ -24,6 +25,7 @@ sidebarType: 1 | Name | Scope | Description | Example | Type | |-----------------------------|----------|-----------------------------------------------------------------------------------------|------------------------------------|----------| | `adUnitId` | Required | The ad unit ID provided by Insticator | `'test'` | `string` | +| `publisherId` | optional | The publisher ID provided by Insticator | `'test'` | `string` | | `yob` | optional | Year of Birth | `'1982'` | `string` | | `gender` | optional | Gender | `'M'` | `string` | | `instl` | optional | 1 = the ad is interstitial or full screen, 0 = not interstitial. | `1` | `number` | @@ -58,7 +60,8 @@ var adUnitsBannerOnly = [ { bidder: 'insticator', params: { - adUnitId: 'example_adunit_id', + adUnitId: 'example_adunit_id', + publisherId: 'example_publisher_id', }, }, ], @@ -170,7 +173,8 @@ var adUnits = [ bids: [{ bidder: 'insticator', params: { - adUnitId: 'example_adunit_id' + adUnitId: 'example_adunit_id', + publisherId: 'example_publisher_id', } }], ... diff --git a/dev-docs/bidders/iqm.md b/dev-docs/bidders/iqm.md index 31b546afcb..d27390b972 100644 --- a/dev-docs/bidders/iqm.md +++ b/dev-docs/bidders/iqm.md @@ -4,6 +4,7 @@ title: iQM description: Prebid iQM Bidder Adaptor pbjs: true biddercode: iqm +pbjs_version_notes: removed in 9.0 sidebarType: 1 --- @@ -23,7 +24,7 @@ Module that connects to iQM demand sources ## Test Parameters -``` +```javascript var adUnits = [{ code: 'div-gpt-ad-1460505748561-0', mediaTypes: { @@ -51,7 +52,7 @@ var adUnits = [{ ## adUnit Video -``` +```javascript var videoAdUnit = { code: 'video1', mediaTypes: { diff --git a/dev-docs/bidders/kargo.md b/dev-docs/bidders/kargo.md index 9a3d684579..0f83489e7a 100644 --- a/dev-docs/bidders/kargo.md +++ b/dev-docs/bidders/kargo.md @@ -25,10 +25,6 @@ pbjs_version_notes: if you require schains, avoid versions 7.46 to 7.53 sidebarType: 1 --- -### Disclosure - -This adapter is known to use an HTTP 1 endpoint. Header bidding often generates multiple requests to the same host and bidders are encouraged to change to HTTP 2 or above to help improve publisher page performance via multiplexing. - ### Note Kargo is an invitation-only marketplace. Please reach out to your Kargo account manager to get setup. Also, you *must* test on a mobile device, or emulate a mobile device by manipulating the user agent string sent to the server. diff --git a/dev-docs/bidders/markapp.md b/dev-docs/bidders/markapp.md new file mode 100644 index 0000000000..3e427f8119 --- /dev/null +++ b/dev-docs/bidders/markapp.md @@ -0,0 +1,39 @@ +--- +layout: bidder +title: MarkApp +description: MarkApp Bidder Adapter +biddercode: markapp +aliasCode : smarthub +usp_supported: true +coppa_supported: true +schain_supported: true +dchain_supported: true +media_types: banner, video, native +safeframes_ok: true +deals_supported: true +floors_supported: true +fpd_supported: false +pbjs: true +pbs: true +pbs_app_supported: true +multiformat_supported: will-bid-on-any +--- + +### Prebid.js Bid Params + +{: .table .table-bordered .table-striped } +| Name | Scope | Description | Example | Type | +|---------------|----------|---------------------------------|-------------------------------------|-----------| +| `seat` | required | Seat value | `'9Q20EdGxzgWdfPYShScl'` | `string` | +| `token` | required | Token | `'eKmw6alpP3zWQhRCe3flOpz0wpuwRFjW'` | `string` | +| `iabCat` | optional | Array of IAB content categories that describe the content producer | `['IAB1-1', 'IAB3-1', 'IAB4-3']` | `Array(String)` | +| `minBidfloor` | optional | Minimal CPM value | `0.03` | `float` | +| `pos` | optional | The position of the placement on the page, see Open RTB spec v2.5. | `4` | `number` | + +### Prebid Server Bid Params + +{: .table .table-bordered .table-striped } +| Name | Scope | Description | Example | Type | +|---------------|----------|---------------------|--------------------------------------|----------| +| `seat` | required | Seat value | `'9Q20EdGxzgWdfPYShScl'` | `string` | +| `token` | required | Token | `'eKmw6alpP3zWQhRCe3flOpz0wpuwRFjW'` | `string` | diff --git a/dev-docs/bidders/mediago.md b/dev-docs/bidders/mediago.md index 4b5f4fcd94..3d31348b80 100644 --- a/dev-docs/bidders/mediago.md +++ b/dev-docs/bidders/mediago.md @@ -3,11 +3,14 @@ layout: bidder title: MediaGo description: MediaGo Prebid Bidder Adapter biddercode: mediago -media_types: banner +media_types: banner,native +prebid_member: true +userIds: all (with commercial activation) tcfeu_supported: true coppa_supported: true usp_supported: true pbjs: true +pbs: true floors_supported: true gvl_id: 1020 pbjs_version_notes: not ported to 5.x, added back 7.13 @@ -26,7 +29,8 @@ The MediaGo Bidding adapter requires setup before beginning. Please contact us a {: .table .table-bordered .table-striped } | Name | Scope | Description | Example | Type | |---------------|----------|-----------------------|-----------|-----------| -| `token` | required | publisher token | `'1e100887dd614b7f69fdd1360437'` | `string` | -| `test` | recommend | 0(default): production env mode.
1: dev env mode and no charge.we will bid Higher frequency to make debug easier. | `1/0` | `Number` | -| `bidfloor` | recommend | Sets a floor price for the bid | `0.05` | `float` | +| `token` | required | publisher token, This parameter expects all imps to be the same | `'1e100887dd614b7f69fdd1360437'` | `string` | +| `region` | recommend | Server region for PBS request: US for US Region, EU for EU Region, APAC for APAC Region, default is US. This parameter expects all imps to be the same. This parameter is available for PBS only. | `'US'` | `string` | +| `test` | recommend | 0(default): production env mode.
1: dev env mode and no charge.we will bid Higher frequency to make debug easier. This parameter is available for PBJS only. | `1/0` | `Number` | +| `bidfloor` | recommend | Sets a floor price for the bid. This parameter is available for PBJS only. | `0.05` | `float` | | `placementId` | recommend | The AD placement ID | `12341234` | `string` | diff --git a/dev-docs/bidders/mediakeys.md b/dev-docs/bidders/mediakeys.md index 45efb078da..ca43f30489 100644 --- a/dev-docs/bidders/mediakeys.md +++ b/dev-docs/bidders/mediakeys.md @@ -166,7 +166,7 @@ Mediakeys fully supports the following [Prebid.js Modules](https://docs.prebid.o {: .table .table-bordered .table-striped } | Module | Scope | |-------------------------------------------------------------------------------------------------------|-----------------------------| -| [Consent Management - GDPR](https://docs.prebid.org/dev-docs/modules/consentManagement.html) | Required in Europe | +| [Consent Management - GDPR](https://docs.prebid.org/dev-docs/modules/consentManagementTcf.html) | Required in Europe | | [Consent Management - US Privacy](https://docs.prebid.org/dev-docs/modules/consentManagementUsp.html) | Required in US - California | | [Supply Chain Object](https://docs.prebid.org/dev-docs/modules/schain.html) | Required for all traffic | | [Instream Tracking](https://docs.prebid.org/dev-docs/modules/instreamTracking.html) | Required for Instream Video | diff --git a/dev-docs/bidders/mgidX.md b/dev-docs/bidders/mgidX.md index 93bbca96db..d3388edb5a 100644 --- a/dev-docs/bidders/mgidX.md +++ b/dev-docs/bidders/mgidX.md @@ -3,14 +3,18 @@ layout: bidder title: MgidX description: Prebid MgidX Bidder Adapter biddercode: mgidX -usp_supported: true -gdpr_supported: true +gpp_sids: usstate_all tcfeu_supported: true +usp_supported: true coppa_supported: true schain_supported: true +deals_supported: false floors_supported: true +fpd_supported: false +ortb_blocking_supported: false media_types: banner, video, native multiformat_supported: will-not-bid +userIds: all pbjs: true pbs: true pbs_app_supported: true diff --git a/dev-docs/bidders/minutemediaplus.md b/dev-docs/bidders/minutemediaplus.md index 68f867d9de..b1d8ef2c0e 100644 --- a/dev-docs/bidders/minutemediaplus.md +++ b/dev-docs/bidders/minutemediaplus.md @@ -21,6 +21,7 @@ ortb_blocking_supported: false multiformat_supported: will-bid-on-one gvl_id: 918 pbjs: true +pbjs_version_notes: removed in 9.0 sidebarType: 1 --- diff --git a/dev-docs/bidders/monetixads.md b/dev-docs/bidders/monetixads.md new file mode 100644 index 0000000000..2039fb405e --- /dev/null +++ b/dev-docs/bidders/monetixads.md @@ -0,0 +1,91 @@ +--- +layout: bidder +title: Monetix Ads +description: Prebid Monetix Bidder Adapter. +pbjs: true +pbs: true +biddercode: monetixads +media_types: banner,video,native +gvl_id: 1281 (admatic) +tcfeu_supported: true +usp_supported: true +coppa_supported: true +gpp_sids: tcfeu, tcfca, usnat, usstate_all, usp +schain_supported: true +dchain_supported: false +userIds: criteo, id5Id, sharedId, unifiedId +safeframes_ok: true +floors_supported: true +aliasCode: admatic +multiformat_supported: will-bid-on-any +sidebarType: 1 +--- + +### Description + +Monetix Ads header bidding adapter connects with Monetix Ads demand sources to fetch bids for network ID. Please reach out to your account manager or for more information. + +### Bid params + +{: .table .table-bordered .table-striped } +| Name | Scope | Description | Example | Type | +|-------------|----------|-------------------------------------|----------|----------| +| `networkId` | required | The network ID from Monetix Ads | `12345` | `number` | +| `host` | required | RTB Host | `rtb.network.monetixads.com` | `string` | + +### Test Parameters + +300x250 banner test + +```javascript +var adUnits = [{ + code: 'your-slot_1-div', + mediaTypes: { + banner: { sizes: [[300, 250]] }, + }, + bids: [{ + bidder: 'monetixads', + params: { + networkId: 12345, + host: 'rtb.network.monetixads.com' + } + }] +},{ + code: 'your-slot_2-div', + mediaTypes: { + native: { ... }, + }, + bids: [{ + bidder: 'monetixads', + params: { + networkId: 12345, + host: 'rtb.network.monetixads.com' + } + }] +},{ + code: 'your-slot_3-div', + mediaTypes: { + video: { ... }, + }, + bids: [{ + bidder: 'monetixads', + params: { + networkId: 12345, + host: 'rtb.network.monetixads.com' + } + }] +}]; +``` + +## UserSync example + +```javascript +pbjs.setConfig({ + userSync: { + iframeEnabled: true, + syncEnabled: true, + syncDelay: 1, + aliasSyncEnabled: true + } +}); +``` diff --git a/dev-docs/bidders/mytarget.md b/dev-docs/bidders/mytarget.md index a10bf209fe..854ab029d5 100644 --- a/dev-docs/bidders/mytarget.md +++ b/dev-docs/bidders/mytarget.md @@ -4,6 +4,7 @@ title: myTarget description: Prebid myTarget Bidder Adapter pbjs: true biddercode: mytarget +pbjs_version_notes: removed in 9.0 sidebarType: 1 --- diff --git a/dev-docs/bidders/openweb.md b/dev-docs/bidders/openweb.md index 59c7e50ab1..8f0554cfe7 100644 --- a/dev-docs/bidders/openweb.md +++ b/dev-docs/bidders/openweb.md @@ -13,7 +13,7 @@ gpp_supported: true gpp_sids: tcfeu, usstate_all, usp usp_supported: true safeframes_ok: false -pbs: false +pbs: true floors_supported: true userIds: all fpd_supported: true diff --git a/dev-docs/bidders/pubmatic.md b/dev-docs/bidders/pubmatic.md index 26af4168e8..6f1ace23e7 100644 --- a/dev-docs/bidders/pubmatic.md +++ b/dev-docs/bidders/pubmatic.md @@ -98,6 +98,7 @@ The PubMatic adapter supports video as of Prebid v1.16.0 | `video.battr` | optional | Blocked creative attributes, See [OpenRTB 2.5 specification](https://www.iab.com/wp-content/uploads/2016/03/OpenRTB-API-Specification-Version-2-5-FINAL.pdf), List 5.3 for values | `[3, 9]` | | `video.linearity` | optional | Indicates if the impression is linear or nonlinear
Values:
`1`: Linear/In-Stream
`2`: Non-Linear/Overlay. | `1` | | `video.placement` | optional | Video placement type. See [OpenRTB 2.5 specification](https://www.iab.com/wp-content/uploads/2016/03/OpenRTB-API-Specification-Version-2-5-FINAL.pdf), List 5.9 for Values | `1` | +| `video.plcmt` | optional | Video placement type. See [OpenRTB 2.6 specification - github](https://github.com/InteractiveAdvertisingBureau/openrtb2.x/blob/develop/2.6.md#327---object-video-), For values [plcmt subtypes](https://github.com/InteractiveAdvertisingBureau/AdCOM/blob/develop/AdCOM%20v1.0%20FINAL.md#list_plcmtsubtypesvideo) | `1` | | `video.minbitrate` | optional | Minumim bit rate in Kbps. | 50 | | `video.maxbitrate` | optional | Maximum bit rate in Kbps. | 70 | @@ -120,8 +121,9 @@ var videoAdUnits = [ api: [ 1, 2 ], // optional protocols: [ 2, 3 ], // optional battr: [ 13, 14 ], // optional - linearity: 1, // optional + linearity: 1, // optional placement: 2, // optional + plcmt: 1, // optional minbitrate: 10, // optional maxbitrate: 10 // optional } diff --git a/dev-docs/bidders/qt.md b/dev-docs/bidders/qt.md new file mode 100644 index 0000000000..c0838c774f --- /dev/null +++ b/dev-docs/bidders/qt.md @@ -0,0 +1,35 @@ +--- +layout: bidder +title: QT +description: Prebid QT Bidder Adapter +biddercode: qt +gpp_sids: usstate_all +tcfeu_supported: false +usp_supported: true +coppa_supported: true +schain_supported: true +deals_supported: false +floors_supported: true +fpd_supported: false +ortb_blocking_supported: false +media_types: banner, video, native +multiformat_supported: will-bid-on-one +userIds: all +pbjs: true +pbs: false +pbs_app_supported: true +safeframes_ok: true +sidebarType: 1 +--- + +### Bid Params + +{: .table .table-bordered .table-striped } +| Name | Scope | Description | Example | Type | +|---------------|----------|--------------|---------------------------------|------------| +| `placementId` | optional | Placement Id | `'0'` | `'string'` | +| `endpointId` | optional | Endpoint Id | `'0'` | `'string'` | + +### Note + +For the prebid server and prebid.js you only need to use one parameter: either placementId or endpointId diff --git a/dev-docs/bidders/ras.md b/dev-docs/bidders/ras.md index e8f9ce3837..3c39d03575 100644 --- a/dev-docs/bidders/ras.md +++ b/dev-docs/bidders/ras.md @@ -13,6 +13,7 @@ floors_supported: false fpd_supported: false sidebarType: 1 multiformat_supported: will-bid-on-one +pbjs_version_notes: removed in 9.0 --- diff --git a/dev-docs/bidders/relevatehealth.md b/dev-docs/bidders/relevatehealth.md new file mode 100644 index 0000000000..5b9e80ab16 --- /dev/null +++ b/dev-docs/bidders/relevatehealth.md @@ -0,0 +1,56 @@ +--- +layout: bidder +title: RelevateHealth +description: Prebid RelevateHealth Bidder Adaptor +pbjs: true +biddercode: relevatehealth +media_types: banner +tcfeu_supported: false +usp_supported: true +coppa_supported: true +gpp_sids: usstate_all +schain_supported: false +safeframes_ok: false +ortb_blocking_supported: false +dsa_supported: false +deals_supported: true +floors_supported: true +sidebarType: 1 +--- + +### Bid Params + +| Name | Scope | Description | Example | Type | +|---------------|-----------|-----------------------|----------------|----------| +| `placement_id` | mandatory | Placement Id | `110011` | `number` | +| `user_id` | mandatory | Unique id for HCP | `'1111111'` | `string` | +| `height` | optional | Height of the creative| `600` | `number` | +| `width` | optional | Width of the creative | `160` | `number` | +| `domain` | optional | Domain | `'domain.com'` | `string` | +| `bid_floor` | optional | Bid Floor Price | `0.5` | `decimal`| + +### AdUnit Format for Banner + +```javascript +var adUnits = [ + { + code: 'banner-ad', + mediaTypes: { + banner: { + sizes: [[160, 600]] + } + }, + bids: [{ + bidder: 'relevatehealth', + params: { + placement_id: 110011, + user_id: '', + height: 600, + width: 160, + domain: '', + bid_floor: 0.5 + } + }] + } + ]; +``` diff --git a/dev-docs/bidders/richaudience.md b/dev-docs/bidders/richaudience.md index f452b0d9a6..acb20c0fc5 100644 --- a/dev-docs/bidders/richaudience.md +++ b/dev-docs/bidders/richaudience.md @@ -7,12 +7,14 @@ userIds: criteo, id5Id, identityLink, liveIntentId, pubCommonId, unifiedId media_types: banner, video tcfeu_supported: true gvl_id: 108 +gpp_supported: true safeframes_ok: false prebid_member: true pbjs: true pbs: true schain_supported: true floors_supported: true +pbjs_version_notes: Please use version 9.1; version 9.0 does not support our adapter. sidebarType: 1 --- diff --git a/dev-docs/bidders/ringieraxelspringer.md b/dev-docs/bidders/ringieraxelspringer.md new file mode 100644 index 0000000000..abb1af0f09 --- /dev/null +++ b/dev-docs/bidders/ringieraxelspringer.md @@ -0,0 +1,44 @@ +--- +layout: bidder +title: RingierAxelSpringer +description: Prebid RingierAxelSpringer Bidder Adapter +biddercode: ringieraxelspringer +media_types: banner, native +pbjs: true +pbs: false +prebid_member: false +gvl_id: 1021 +tcfeu_supported: true +safeframes_ok: false +deals_supported: false +floors_supported: false +fpd_supported: false +sidebarType: 1 +multiformat_supported: will-bid-on-one +dsa_supported: true +privacy_sandbox: paapi +ortb_blocking_supported: false +schain_supported: false +dchain_supported: false +gpp_sids: None +coppa_supported: false +usp_supported: false +--- + +### Bid Params + +{: .table .table-bordered .table-striped } +| Name | Scope | Description | Example | Type | +|------------------|----------|------------------------------------------------------------------------------------------------------|---------------------------------------------|----------| +| `network` | required | Specific identifier provided by RAS | `'4178463'` | `string` | +| `site` | required | Specific identifier name (case-insensitive) that is associated with this ad unit and provided by RAS | `'example_com'` | `string` | +| `area` | required | Ad unit category name; only case-insensitive alphanumeric with underscores and hyphens are allowed | `'sport'` | `string` | +| `slot` | required | Ad unit placement name (case-insensitive) provided by RAS | `'slot'` | `string` | +| `pageContext` | optional | Web page context data | `{}` | `object` | +| `pageContext.dr` | optional | Document referrer URL address | `'https://example.com/'` | `string` | +| `pageContext.du` | optional | Document URL address | `'https://example.com/sport/football/article.html?id=932016a5-02fc-4d5c-b643-fafc2f270f06'` | `string` | +| `pageContext.dv` | optional | Document virtual address as slash-separated path that may consist of any number of parts (case-insensitive alphanumeric with underscores and hyphens); first part should be the same as `site` value and second as `area` value; next parts may reflect website navigation | `'example_com/sport/football'` | `string` | +| `pageContext.keyWords` | optional | List of keywords associated with this ad unit; only case-insensitive alphanumeric with underscores and hyphens are allowed | `['euro', 'lewandowski']` | `string[]` | +| `pageContext.keyValues` | optional | Key-values associated with this ad unit (case-insensitive); following characters are not allowed in the values: `" ' = ! + # * ~ ; ^ ( ) < > ] [ & @` | `{}` | `object` | +| `pageContext.keyValues.ci` | optional | Content unique identifier | `'932016a5-02fc-4d5c-b643-fafc2f270f06'` | `object` | +| `pageContext.keyValues.adunit` | optional | Ad unit name | `'example_com/sport'` | `string` | diff --git a/dev-docs/bidders/setupad.md b/dev-docs/bidders/setupad.md index a6ce0dad27..f48d280776 100644 --- a/dev-docs/bidders/setupad.md +++ b/dev-docs/bidders/setupad.md @@ -27,7 +27,7 @@ sidebarType: 1 | Name | Scope | Description | Example | Type | |----------------+-------+-----------------------------------+-----------+---------| | `placement_id` | required | Placement ID, provided by setupad | `'12345'` | String | -| `account_id` | optional | Account ID, provided by setupad | `'12345'` | String | +| `account_id` | required | Account ID, provided by setupad | `'12345'` | String | ### Additional options diff --git a/dev-docs/bidders/smaato.md b/dev-docs/bidders/smaato.md index f298759132..56227993bf 100644 --- a/dev-docs/bidders/smaato.md +++ b/dev-docs/bidders/smaato.md @@ -8,6 +8,7 @@ gvl_id: 82 usp_supported: true coppa_supported: true gpp_supported: true +dsa_supported: true media_types: banner, video, native userIds: all pbjs: true @@ -59,7 +60,7 @@ The Smaato adapter will convert bidfloors to 'USD' currency as needed. | `adbreakId` | required | Your Smaato adbreak id. Required for adpod (long-form video) requests | `'41002234'` | `string` | | `app` | optional | Object containing mobile app parameters. See the [App Object](#smaato-app-object) for details.| `app : { ifa: '56700000-9cf0-22bd-b23e-46b96e40003a'}` | `object` | -##### Note +#### Note In case of AdPods, the Smaato adapter will only read the first `imp[].skadn` entry for each AdPod, such that there should only be one `skadn` occurrence per AdPod. @@ -274,7 +275,7 @@ Following example includes sample `imp` object with publisherId and adSlot which }, "ext":{ "smaato":{ - "publisherId":"100042525", + "publisherId":"1100042525", "adspaceId":"130563103" } } diff --git a/dev-docs/bidders/smilewanted.md b/dev-docs/bidders/smilewanted.md index 42429175b0..4cedc9c33c 100644 --- a/dev-docs/bidders/smilewanted.md +++ b/dev-docs/bidders/smilewanted.md @@ -2,14 +2,22 @@ layout: bidder title: Smile Wanted description: SmileWanted Bidder Adapter -media_types: banner, video -pbjs: true -pbs: true biddercode: smilewanted tcfeu_supported: false +gvl_id: 639 usp_supported: true +coppa_supported: true +schain_supported: true userIds: all -gvl_id: 639 +media_types: banner, video, native +safeframes_ok: true +deals_supported: true +floors_supported: true +pbjs: true +pbs: true +prebid_member: false +multiformat_supported: will-bid-on-one +privacy_sandbox: no sidebarType: 1 --- @@ -37,7 +45,7 @@ You can add `#sw_test_campaign` to the end of any URL. This will have the effect Add the following code to enable user sync. Smile Wanted strongly recommends enabling user syncing through iFrames. This functionality improves partners' user match rates and increases the Smile Wanted bid rate and bid price. Be sure to call `pbjs.setConfig()` only once. -``` +```javascript pbjs.setConfig({ userSync: { iframeEnabled: true, diff --git a/dev-docs/bidders/spotx.md b/dev-docs/bidders/spotx.md index 0c4fa8ce6b..9f9a9b91d9 100644 --- a/dev-docs/bidders/spotx.md +++ b/dev-docs/bidders/spotx.md @@ -13,6 +13,7 @@ safeframes_ok: false pbjs: true gvl_id: 165 floors_supported: true +pbjs_version_notes: removed in 9.0 sidebarType: 1 --- diff --git a/dev-docs/bidders/stailamedia.md b/dev-docs/bidders/stailamedia.md new file mode 100644 index 0000000000..4b09273bbf --- /dev/null +++ b/dev-docs/bidders/stailamedia.md @@ -0,0 +1,31 @@ +--- +layout: bidder +title: stailamedia +description: stailamedia Bidder Adapter +biddercode: stailamedia +aliasCode: appnexus +tcfeu_supported: true +gvl_id: 32 +schain_supported: true +userId: all +media_types: banner, video, native +safeframes_ok: true +deals_supported: true +pbjs: true +pbs: true +prebid_member: false +multiformat_supported: will-bid-on-any +sidebarType: 1 +--- +### Bid Params + +{: .table .table-bordered .table-striped } +| Name | Scope | Description | Example | Type | +|---------------|----------|-----------------------|-----------|-----------| +| `placement_id` (PBS+PBJS) or `placementId` (PBJS) | required | Placement id | `'33037108'` | `string` | + +stailamedia is an aliased bidder for AppNexus. + +### Note + +For setup with stailamedia, please reach out to [prebid@stailamedia.com](mailto:prebid@stailamedia.com) diff --git a/dev-docs/bidders/teads.md b/dev-docs/bidders/teads.md index c3f623978a..52b57d77d0 100644 --- a/dev-docs/bidders/teads.md +++ b/dev-docs/bidders/teads.md @@ -25,9 +25,10 @@ fpd_supported: false sidebarType: 1 --- -### Note +### Notes -The Teads Bidding adapter requires setup before beginning. Please contact us on +1. The Teads Bidding adapter requires setup before beginning. Please contact us on +2. When this adapter is enabled and Prebid.js is used in an iOS WebView, the WebView should allow videos to play inline. This is required because the Teads adapter delivers video ads and starts by detecting the autoplay capability of the device. ### Bid Params diff --git a/dev-docs/bidders/vidazoo.md b/dev-docs/bidders/vidazoo.md index a058e6d9af..84cca015f8 100644 --- a/dev-docs/bidders/vidazoo.md +++ b/dev-docs/bidders/vidazoo.md @@ -10,6 +10,7 @@ tcfeu_supported: true gpp_supported: true usp_supported: true pbjs: true +pbs: true sidebarType: 1 --- @@ -19,6 +20,6 @@ sidebarType: 1 | Name | Scope | Description | Example | Type | |------------|----------|------------------------------------------------------------------------------------------|------------------------------|----------| | `cId` | required | The connection ID from Vidazoo. | `'562524b21b1c1f08117fc7f9'` | `string` | -| `pId` | required | The publisher ID from Vidazoo. | `'59ac17c192832d0011283fe3'` | `string` | +| `pId` | required | The publisher ID from Vidazoo (pbjs only). | `'59ac17c192832d0011283fe3'` | `string` | | `bidFloor` | optional | The minimum bid value desired. Vidazoo will not respond with bids lower than this value. | `0.90` | `float` | | `subDomain`| optional | Sets the server subdomain, default: 'prebid'. | `'prebid'` | `string` | diff --git a/dev-docs/bidders/vox.md b/dev-docs/bidders/vox.md index b531bb3079..2d3e9904b3 100644 --- a/dev-docs/bidders/vox.md +++ b/dev-docs/bidders/vox.md @@ -6,6 +6,7 @@ schain_supported: true floors_supported: true userIds: all pbjs: true +pbs: true media_types: banner, video biddercode: vox tcfeu_supported: true @@ -26,6 +27,7 @@ Please reach out to your partners account team before using this plugin to get p | `placementId` | required | The place id. | '5af45ad34d506ee7acad0c26' | `string` | | `placement` | required | Adunit placement, possible values: banner, video, inImage | 'banner' | `string` | | `imageUrl` | required for inImage | URL of the image on which the banner will be displayed | `'https://example.com/images/image.jpg'` | `string` | +| `displaySizes` | optional, only supported by inImage format | An array of strings. Each string should be in `x` format (currently, this parameter is supported only by PrebidServer vox adapter) | `["123x90", "720x100"]` | `string[]` | ### Sample Banner Ad Unit @@ -54,7 +56,7 @@ var adUnits = [{ code: 'video_ad_unit', mediaTypes: { video: { - context: 'outstream', // required, possible values: instream, outstream + context: 'outstream', // required, possible values: instream, outstream playerSize: [[640, 480]] // required } }, diff --git a/dev-docs/bidders/liftoff.md b/dev-docs/bidders/vungle.md similarity index 83% rename from dev-docs/bidders/liftoff.md rename to dev-docs/bidders/vungle.md index c55d6febc9..b66c0d254b 100644 --- a/dev-docs/bidders/liftoff.md +++ b/dev-docs/bidders/vungle.md @@ -1,8 +1,8 @@ --- layout: bidder -title: liftoff -description: Prebid liftoff Bidder Adapter -biddercode: liftoff +title: vungle +description: Prebid vungle Bidder Adapter +biddercode: vungle tcfeu_supported: false usp_supported: true gpp_supported: false @@ -25,7 +25,7 @@ sidebarType: 1 ### Note -The Liftoff Bidding adapter requires setup before beginning. Please contact us at . +The Vungle Bidding adapter requires setup before beginning. Please contact us at . ### Bid Params diff --git a/dev-docs/bidders/yahooAdvertising.md b/dev-docs/bidders/yahooAdvertising.md index 219a7a4347..b5543dd165 100644 --- a/dev-docs/bidders/yahooAdvertising.md +++ b/dev-docs/bidders/yahooAdvertising.md @@ -5,7 +5,7 @@ description: Yahoo Advertising Bid Adapter pbs: true pbjs: true media_types: banner, video -filename: yahoosspBidAdapter +filename: yahooAdsBidAdapter biddercode: yahooAds prebid_member: true tcfeu_supported: true @@ -63,7 +63,7 @@ For new partners/publishers joining Yahoo Advertising and legacy "oneVideo" part ### Prebid.js Adapter Supported Features -For further setup details & examples please see +For further setup details & examples please see * Media Types: Banner & Video * Outstream renderer @@ -76,4 +76,3 @@ For further setup details & examples please see pbjs.ge Examples of scenarios where a bid may be reconsidered in Prebid.js: -* Auto-refresh: Some pages will reload an AdUnit on a set interval (often 60-240 seconds). Previous bids for that particular AdUnit can be reconsidered for subsequent refreshes of that unit up to the TTL or until they win the unit. -* Infinite scroll: As the user scrolls, the same AdUnit may be dynamically created over and over. The bid can be reconsidered for dynamically-created AdUnits with the same name. Again, the bid is only re-considered on that AdUnit up to the bid TTL or until it's displayed. -* Galleries: Some pages feature carousel-style galleries that contain an AdUnit that refreshes as the user cycles through the content in the gallery. +- Auto-refresh: Some pages will reload an AdUnit on a set interval (often 60-240 seconds). Previous bids for that particular AdUnit can be reconsidered for subsequent refreshes of that unit up to the TTL or until they win the unit. +- Infinite scroll: As the user scrolls, the same AdUnit may be dynamically created over and over. The bid can be reconsidered for dynamically-created AdUnits with the same name. Again, the bid is only re-considered on that AdUnit up to the bid TTL or until it's displayed. +- Galleries: Some pages feature carousel-style galleries that contain an AdUnit that refreshes as the user cycles through the content in the gallery. Here's how it works: @@ -162,13 +175,13 @@ Therefore, it requires Prebid.js to run in a blocking/synchronous fashion. **Thi Here are a couple of alternative workarounds: -* **Option 1:** +- **Option 1:** Load a blocking script that has a load time of 300-500ms. This script does nothing but keep the page waiting. In the meantime Prebid.js can run asynchronously and return the bids. After the blocking script finishes loading, GPT can start synchronously; at this point there will be header bidding bids available. For the best user experience, you probably want to insert this blocking script after the above the fold page content has loaded. Or if you're okay with additional 500ms latency added to your page load time, this can be easily done. -* **Option 2:** +- **Option 2:** Use post-bid. The downsides are that post-bid no longer allows your header bidding partners to compete with Google Ad Manager/AdX, but they can still compete with each other. For more information, see [What is post-bid?]({{site.baseurl}}/overview/what-is-post-bid.html). @@ -209,9 +222,9 @@ what's sent to the ad server with [targetingControls.auctionKeyMaxChars](/dev-do It's technically possible, but we don't recommend doing this: -* The code isn't small. For performance reasons you don't want to run two versions if you can help it -* We don't test concurrent versions -* We won't specifically support debugging problems caused by running two concurrent versions. But will take take PRs if someone finds an issue. +- The code isn't small. For performance reasons you don't want to run two versions if you can help it +- We don't test concurrent versions +- We won't specifically support debugging problems caused by running two concurrent versions. But will take take PRs if someone finds an issue. If all this wasn't enough to warn you away from trying, it should work if you name the PBJS global differently for each instance (Update the value of 'globalVarName' in ) @@ -259,6 +272,6 @@ Sometimes the owner of a bid adapter or other kind of module wants to rename the ## Related Reading -* [Prebid.js Troubleshooting Guide](/troubleshooting/troubleshooting-guide.html) -* [Prebid.js Common Issues](/dev-docs/common-issues.html) -* [Prebid.js issues tagged 'question'](https://github.com/prebid/Prebid.js/issues?utf8=%E2%9C%93&q=is%3Aissue%20label%3Aquestion%20) +- [Prebid.js Troubleshooting Guide](/troubleshooting/troubleshooting-guide.html) +- [Prebid.js Common Issues](/dev-docs/common-issues.html) +- [Prebid.js issues tagged 'question'](https://github.com/prebid/Prebid.js/issues?utf8=%E2%9C%93&q=is%3Aissue%20label%3Aquestion%20) diff --git a/dev-docs/integrate-with-the-prebid-analytics-api.md b/dev-docs/integrate-with-the-prebid-analytics-api.md index f7518828c3..b073000889 100644 --- a/dev-docs/integrate-with-the-prebid-analytics-api.md +++ b/dev-docs/integrate-with-the-prebid-analytics-api.md @@ -86,7 +86,7 @@ Analytics adapter for Example.com. Contact prebid@example.com for information. adapter needs to specify an enableAnalytics() function, but it should also call the base class function to set up the events. -5. Doing analytics may require user permissions under [GDPR](/dev-docs/modules/consentManagement.html), which means your adapter will need to be linked to your [IAB Global Vendor List](https://iabeurope.eu/vendor-list-tcf/) ID. If no GVL ID is found, and Purpose 7 (Measurement) is enforced, your analytics adapter will be blocked unless it is specifically listed under vendorExceptions. Your GVL ID can be added to the `registerAnalyticsAdapter()` call. +5. Doing analytics may require user permissions under [GDPR](/dev-docs/modules/consentManagementTcf.html), which means your adapter will need to be linked to your [IAB Global Vendor List](https://iabeurope.eu/vendor-list-tcf/) ID. If no GVL ID is found, and Purpose 7 (Measurement) is enforced, your analytics adapter will be blocked unless it is specifically listed under vendorExceptions. Your GVL ID can be added to the `registerAnalyticsAdapter()` call. #### Basic prototype analytics adapter diff --git a/dev-docs/modules/adagioRtdProvider.md b/dev-docs/modules/adagioRtdProvider.md index 2078f4cc30..4f10a192a9 100644 --- a/dev-docs/modules/adagioRtdProvider.md +++ b/dev-docs/modules/adagioRtdProvider.md @@ -34,6 +34,7 @@ pbjs.setConfig({ params: { organizationId: '1000', // Required. Provided by Adagio site: "my-site" // Required. Provided by Adagio + placementSource: 'ortb' // Optional. Possible values: 'ortb' | 'code' | 'gpid' } }] } @@ -43,12 +44,13 @@ pbjs.setConfig({ Syntax details: {: .table .table-bordered .table-striped } -| Name | Scope | Description | Example | Type | -|-------------------------|----------|-----------------------------------------------|-------------|----------| -| `name` | required | Real time data module name: Always `'adagio'` | `'adagio'` | `string` | -| `params` | required | | | `Object` | -| `params.organizationId` | required | Account id provided by Adagio. | `'1000'` | `string` | -| `params.site` | required | Account site name provided by Adagio. | `'my-site'` | `string` | +| Name | Scope | Description | Example | Type | +|--------------------------|----------|-----------------------------------------------|-------------|----------| +| `name` | required | Real time data module name: Always `'adagio'` | `'adagio'` | `string` | +| `params` | required | | | `Object` | +| `params.organizationId` | required | Account id provided by Adagio. | `'1000'` | `string` | +| `params.site` | required | Account site name provided by Adagio. | `'my-site'` | `string` | +| `params.placementSource` | optional | Programmatically set the `ortb2Imp.ext.data.placement` signal based on location. Possible values: `ortb` (default), `code`, `gpid`. | `'ortb'` | `string` | ## Installation diff --git a/dev-docs/modules/anPspParamsConverter.md b/dev-docs/modules/anPspParamsConverter.md new file mode 100644 index 0000000000..876f29be4e --- /dev/null +++ b/dev-docs/modules/anPspParamsConverter.md @@ -0,0 +1,26 @@ +--- +layout: page_v2 +page_type: module +title: Module - anPspParamsConverter +description: Formats bid params for AppNexus PSP requests made through Prebid.js. +module_code : anPspParamsConverter +display_name : anPspParamsConverter +enable_download : true +sidebarType : 1 +--- + +# anPspParamsConverter Module + +{:.no_toc} + +This module is a temporary measure for publishers running Prebid.js 9.0+ and using the AppNexus PSP endpoint through their Prebid.js setup. Please ensure to include this module in your builds of Prebid.js 9.0+, otherwise requests to PSP may not complete successfully. + +## Module's Purpose + +This module replicates certain functionality that was previously stored in the appnexusBidAdapter.js file within a function named transformBidParams. + +This transformBidParams was a standard function in all adapters, which helped to change/modify the params and their values to a format that matched the bidder's request structure on the server-side endpoint. In Prebid.js 9.0, this standard function was removed in all adapter files, so that the whole client-side file (eg appnexusBidAdapter.js) wouldn't have to be included in a prebid.js build file that was meant for server-side bidders. + +## How to use the module as a publisher + +There is no setConfig setup needed for this module. Simply include this module in your Prebid.js build file if you plan to make requests to the AppNexus PSP endpoint through Prebid.js. diff --git a/dev-docs/modules/anonymisedRtdProvider.md b/dev-docs/modules/anonymisedRtdProvider.md index d266b01d6f..72e678faa9 100644 --- a/dev-docs/modules/anonymisedRtdProvider.md +++ b/dev-docs/modules/anonymisedRtdProvider.md @@ -21,10 +21,10 @@ Anonymised’s Real-time Data Provider automatically obtains segment IDs from th - Build the anonymisedRtd module into the Prebid.js package with: ```bash -gulp build --modules=anonymisedRtdProvider,... +gulp build --modules=rtdModule,anonymisedRtdProvider,... ``` -- Use `setConfig` to instruct Prebid.js to initilaize the anonymisedRtdProvider module, as specified below. +- Use `setConfig` to instruct Prebid.js to initialize the anonymisedRtdProvider module, as specified below. ### Configuration diff --git a/dev-docs/modules/azerionedgeRtdProvider.md b/dev-docs/modules/azerionedgeRtdProvider.md index 2c3da1eb4d..d58254d1c8 100644 --- a/dev-docs/modules/azerionedgeRtdProvider.md +++ b/dev-docs/modules/azerionedgeRtdProvider.md @@ -74,7 +74,7 @@ received from the user, this module does not require a TCF vendor configuration. provided to the module when the user gives the relevant permissions on the publisher website. As Prebid.js utilizes TCF vendor consent for the RTD module to load, the module needs to be labeled -within the Vendor Exceptions. If the Prebid GDPR enforcement is enabled, the module should be configured +within the Vendor Exceptions. If the Prebid TCF Controls are enabled, the module should be configured as exception, as shown below: ```js diff --git a/dev-docs/modules/consentManagementGpp.md b/dev-docs/modules/consentManagementGpp.md index 1e8ad5cb19..9a99ac96ce 100644 --- a/dev-docs/modules/consentManagementGpp.md +++ b/dev-docs/modules/consentManagementGpp.md @@ -129,7 +129,7 @@ You can also use the [Prebid.js Download](/download.html) page. {: .alert.alert-info :} -If you are submitting changes to an adapter to support GPP, please also submit a PR to the [docs repo](https://github.com/prebid/prebid.github.io) to add the `gpp_supported: true` variable to your respective page in the [bidders directory](https://github.com/prebid/prebid.github.io/tree/master/dev-docs/bidders). **This will ensure that your adapter's name will automatically appear on the list of adapters supporting GPP.** +If you are submitting changes to an adapter to support GPP, please also submit a PR to the [docs repo](https://github.com/prebid/prebid.github.io) to add the `gpp_sids` meta data with a comma separated list of section names (`tcfeu`, `tcfca`, `usnat`, `usstate_all`, `usp`) to your respective page in the [bidders directory](https://github.com/prebid/prebid.github.io/tree/master/dev-docs/bidders). **This will ensure that your adapter's name will automatically appear on the list of adapters supporting GPP.** ### Bidder Adapter GPP Integration @@ -172,7 +172,7 @@ Depending on your needs, you could include the consent information in a query of ## Adapters Supporting GPP -Bidders on this list have self-declared their GPP support in their [github.com/prebid/prebid.github.io/tree/master/dev-docs/bidders] md file by adding "gpp_supported: true". +Bidders on this list have self-declared their GPP support in their [github.com/prebid/prebid.github.io/tree/master/dev-docs/bidders] md file by adding "gpp_sids: tcfeu, tcfca, usnat, usstate_all, usp". @@ -200,7 +200,7 @@ var idx_gdpr=0; - [IAB Global Privacy Platform Full Specification Repository](https://github.com/InteractiveAdvertisingBureau/Global-Privacy-Platform) - [IAB Global Privacy Platform CMP API Specification](https://github.com/InteractiveAdvertisingBureau/Global-Privacy-Platform/blob/main/Core/CMP%20API%20Specification.md) -- [Prebid Consent Management - GDPR Module](/dev-docs/modules/consentManagement.html) +- [Prebid Consent Management - GDPR Module](/dev-docs/modules/consentManagementTcf.html) - [Prebid Consent Management - US Privacy Module](/dev-docs/modules/consentManagementUsp.html) - [Prebid Activity Controls](/dev-docs/activity-controls.html) - [Prebid Activity Controls -- GPP control module - usnat](/dev-docs/modules/gppControl_usnat.html) diff --git a/dev-docs/modules/consentManagement.md b/dev-docs/modules/consentManagementTcf.md similarity index 89% rename from dev-docs/modules/consentManagement.md rename to dev-docs/modules/consentManagementTcf.md index 518ce48a02..de965ca030 100644 --- a/dev-docs/modules/consentManagement.md +++ b/dev-docs/modules/consentManagementTcf.md @@ -1,16 +1,16 @@ --- layout: page_v2 page_type: module -title: Consent Management - GDPR -description: If you have users in Europe, this module works with your Consent Management Platform to pass consent info to bidders and help align with EU regulations. See also the GDPR Enforcement module. -module_code : consentManagement -display_name : Consent Management - GDPR +title: Consent Management - TCF +description: If you have users in Europe, this module works with your Consent Management Platform to pass consent info to bidders and help align with EU regulations. See also the TCF Control module. +display_name : Consent Management - TCF +module_code : consentManagementTcf enable_download : true recommended: true sidebarType : 1 --- -# GDPR Consent Management Module +# TCF Consent Management Module {: .no_toc } - TOC @@ -28,12 +28,12 @@ This module works with supported [Consent Management Platforms](https://www.cmsw Prebid functionality created to address regulatory requirements does not replace each party's responsibility to determine its own legal obligations and comply with all applicable laws. **We recommend consulting with your legal counsel before determining how to utilize these features in support of your overall privacy approach.** -This base EU GDPR consent management module performs these actions: +This base EU TCF consent management module performs these actions: 1. Fetch the user's GDPR & Google additional consent data from the CMP. 2. Incorporate this data into the auction objects for adapters to collect. -The optional [GDPR enforcement module](/dev-docs/modules/gdprEnforcement.html) adds on these actions: +The optional [TCF control module](/dev-docs/modules/tcfControl.html) adds on these actions: 1. Allows the page to define which activities should be enforced at the Prebid.js level. 2. Actively enforces those activities based on user consent data (in the TCF string, not the AC string). @@ -71,16 +71,17 @@ but we recommend migrating to the new config structure as soon as possible. | gdpr.actionTimeout | `integer` | Length of time (in milliseconds) to allow the user to take action to consent if they have not already done so. The actionTimer first waits for the CMP to load, then the actionTimeout begins for the specified duration. Default is `undefined`. | `10000` | | gdpr.defaultGdprScope | `boolean` | Defines what the `gdprApplies` flag should be when the CMP doesn't respond in time or the static data doesn't supply. Defaults to `false`. | `true` | | gdpr.consentData | `Object` | An object representing the GDPR consent data being passed directly; only used when cmpApi is 'static'. Default is `undefined`. | | -| gdpr.consentData.getTCData.tcString | `string` | Base64url-encoded TCF v2.x string with segments. | | -| gdpr.consentData.getTCData.addtlConsent | `string` | Additional consent string if available from the cmp TCData object | | -| gdpr.consentData.getTCData.gdprApplies | `boolean` | Defines whether or not this pageview is in GDPR scope. | | -| gdpr.consentData.getTCData.purpose.consents | `Object` | An object representing the user's consent status for specific purpose IDs. | | -| gdpr.consentData.getTCData.purpose.legitimateInterests | `Object` | An object representing the user's legitimate interest status for specific purpose IDs. | | -| gdpr.consentData.getTCData.vendor.consents | `Object` | An object representing the user's consent status for specific vendor IDs. | | -| gdpr.consentData.getTCData.vendor.legitimateInterests | `Object` | An object representing the user's legitimate interest status for specific vendors IDs. | | +| gpdr.dsaPlatform | `boolean` | If true, indicates that the publisher is to be considered an "Online Platform" for the purposes of the [Digital Services Act](https://digital-strategy.ec.europa.eu/en/policies/digital-services-act-package) | | +| gdpr.consentData.tcString | `string` | Base64url-encoded TCF v2.x string with segments. | | +| gdpr.consentData.addtlConsent | `string` | Additional consent string if available from the cmp TCData object | | +| gdpr.consentData.gdprApplies | `boolean` | Defines whether or not this pageview is in GDPR scope. | | +| gdpr.consentData.purpose.consents | `Object` | An object representing the user's consent status for specific purpose IDs. | | +| gdpr.consentData.purpose.legitimateInterests | `Object` | An object representing the user's legitimate interest status for specific purpose IDs. | | +| gdpr.consentData.vendor.consents | `Object` | An object representing the user's consent status for specific vendor IDs. | | +| gdpr.consentData.vendor.legitimateInterests | `Object` | An object representing the user's legitimate interest status for specific vendors IDs. | | {: .alert.alert-info :} -NOTE: The `purpose` and `vendor` objects are required if you are using the `gdprEnforcement` module. If the data is not included, your bid adapters, analytics adapters, and/or userId systems will likely be excluded from the auction as Prebid will assume the user has not given consent for these entities. +NOTE: The `purpose` and `vendor` objects are required if you are using the `tcfControl` module. If the data is not included, your bid adapters, analytics adapters, and/or userId systems will likely be excluded from the auction as Prebid will assume the user has not given consent for these entities. A related parameter is `deviceAccess`, which is at the global level of Prebid.js configuration because it can be used GDPR, CCPA, or custom privacy implementations: @@ -210,7 +211,7 @@ Here is a sample of how the data is structured in the `bidderRequest` object: **_consentString_** -This field contains the user's choices on consent, represented as an encoded string value. In certain scenarios, this field might come to you with an `undefined` value; normally this happens when there was an error (or timeout) during the CMP interaction and the publisher turned off GDPR enforcement. If you don't want to pass `undefined` to your system, you can check for this value and replace it with a valid consent string. See the _consent_required_ code in the example below (under "gdprApplies") for a possible approach to checking and replacing values. +This field contains the user's choices on consent, represented as an encoded string value. In certain scenarios, this field might come to you with an `undefined` value; normally this happens when there was an error (or timeout) during the CMP interaction and the publisher turned off TCF controls. If you don't want to pass `undefined` to your system, you can check for this value and replace it with a valid consent string. See the _consent_required_ code in the example below (under "gdprApplies") for a possible approach to checking and replacing values. **_addtlConsent_** @@ -369,7 +370,7 @@ This should be false if there was some error in the consent data; otherwise set ## Further Reading -- [GDPR Enforcement Module](/dev-docs/modules/gdprEnforcement.html) +- [TCF Control Module](/dev-docs/modules/tcfControl.html) - [IAB TCF Implementation Guide](https://github.com/InteractiveAdvertisingBureau/GDPR-Transparency-and-Consent-Framework/blob/master/TCFv2/TCF-Implementation-Guidelines.md) - [IAB Transparancy and Consent Framework Policies](https://iabeurope.eu/iab-europe-transparency-consent-framework-policies/) - [Prebid Consent Management - US Privacy Module](/dev-docs/modules/consentManagementUsp.html) diff --git a/dev-docs/modules/consentManagementUsp.md b/dev-docs/modules/consentManagementUsp.md index 90aed2ad66..ca804d5646 100644 --- a/dev-docs/modules/consentManagementUsp.md +++ b/dev-docs/modules/consentManagementUsp.md @@ -6,7 +6,7 @@ description: If you have users in California, this module works with your Consen module_code : consentManagementUsp display_name : Consent Management - US Privacy enable_download : true -recommended: true +recommended: false sidebarType : 1 --- @@ -22,10 +22,10 @@ sidebarType : 1 This consent management module is designed to support the California Consumer Privacy Act ([CCPA](https://www.iab.com/guidelines/ccpa-framework/)). The IAB has generalized these guidelines to cover future regulations, referring to the feature as "US Privacy." -This module works with an IAB-compatible US Privacy API (USP-API) to fetch an encoded string representing the user's notice and opt-out choices and make it available for adapters to consume and process. In Prebid 7+; the module defaults to working with an IAB-compatible US Privacy API; in prior versions, the module had to be configured to be in effect. +This module works with an IAB-compatible US Privacy API (USP-API) to fetch an encoded string representing the user's notice and opt-out choices and make it available for adapters to consume and process. In Prebid 7+; the module defaults to working with an IAB-compatible US Privacy API; in prior versions, the module had to be configured to be in effect. This module is no longer recommended, as the signal is no longer supported by a contractual framework as of January 31, 2024. {: .alert.alert-info :} -See also the [Prebid Consent Management - GDPR Module](/dev-docs/modules/consentManagement.html) for supporting the EU General Data Protection Regulation (GDPR) +See also the [Prebid Consent Management - TCF Module](/dev-docs/modules/consentManagementTcf.html) for supporting the IABTL Transparency and Consent Framework. Here's a summary of the interaction process: diff --git a/dev-docs/modules/dfpAdpod.md b/dev-docs/modules/dfpAdpod.md new file mode 100644 index 0000000000..6904af0f8d --- /dev/null +++ b/dev-docs/modules/dfpAdpod.md @@ -0,0 +1,21 @@ +--- +layout: page_v2 +page_type: module +title: Module - Google Ad Manager Adpod Support +description: Required for serving adpod video through Google Ad Manager. +module_code : dfpAdpod +display_name : Google Ad Manager Adpod Support +enable_download : true +vendor_specific: true +sidebarType : 1 +--- + +# Google Ad Manager Adpod Support + +{:.no_toc} + +This module exposes the [`pbjs.adServers.dfp.buildAdpodVideoUrl](/dev-docs/publisher-api-reference/adServers.dfp.buildAdpodVideoUrl.html) method, required to use [adpod](/dev-docs/modules/adpod.md) with Google Ad Manager. + +## Further Reading + +- [Show long form video ads with GAM](/dev-docs/show-long-form-video-with-gam.html) diff --git a/dev-docs/modules/enrichmentFpdModule.md b/dev-docs/modules/enrichmentFpdModule.md deleted file mode 100644 index d80b64570e..0000000000 --- a/dev-docs/modules/enrichmentFpdModule.md +++ /dev/null @@ -1,80 +0,0 @@ ---- -layout: page_v2 -page_type: module -title: Module - First Party Data Enrichment -description: Injects additional data into the auction stream, including: domain, keywords, and page url. -module_code : enrichmentFpdModule -display_name : First Party Data Enrichment -enable_download : true -recommended: true -sidebarType : 1 ---- - -# First Party Data Enrichment Module - -{:.no_toc} - -{: .alert.alert-warning :} -Since version 7.29, this module does nothing; its functionality is instead included by default in all Prebid distributions. - -This module adds a number of First Party Data (FPD) fields from the environment. - -Add it to the Prebid.js build with this command: - -```bash -gulp build --modules=enrichmentFpdModule -``` - -If included in the build, it will automatically perform the enrichments unless controlled with setConfig: - -```javascript -pbjs.setConfig({ - firstPartyData: { - skipEnrichments: true // defaults to false - } -}); -``` - -## How it works - -At the beginning of each auction, this module merges a number of values into the `ortb2` [requestBids parameter](/dev-docs/publisher-api-reference/requestBids.html). Specific details below. - -## Enrichments - -{: .table .table-bordered .table-striped } -| Page Source | ortb2 field | Notes | -|---+---+---| -| page URL | site.page | Uses pbjs getRefererInfo().page | -| referer URL | site.ref | Uses pbjs getRefererInfo().ref | -| host domain | site.domain | Pulled from the getRefererInfo().page the host domain is used with the www component dropped. | -| aggregated domain | site.publisher.domain | The highest level domain in which cookies can be set. | -| viewport width | device.w | Hunts for window.innerWidth, window.document.documentElement.clientWidth, window.document.body.clientWidth | -| viewport height | device.w | Hunts for window.innerHeight, window.document.documentElement.clientHeight, window.document.body.clientHeight | -| UA client hints | device.sua | Collects user agent client hints. See [note](#ua-hints) below. | -| meta keywords | site.keywords | Looks for a meta tag. e.g. | -| currency | cur | Collects the currency defined by the [Currency module](/dev-docs/modules/currency.html). | - - - -### User agent client hints - -The module populates `device.sua` with UA client hints retrieved from `navigator.userAgentData`. By default, it won't ask for any high entropy hint. You can specify the list of hints using the `uaHints` option with [any available high entropy hint](https://developer.mozilla.org/en-US/docs/Web/API/NavigatorUAData#returning_high_entropy_values): - -```javascript -pbjs.setConfig({ - firstPartyData: { - uaHints: [ - 'platform', - // ... - ] - } -}) -``` - -If `uaHints` is set to an empty array or is not set, the module will not attempt to retrieve any high entropy hint and use only the available low-entropy values. - -# Related Reading - -- [Prebid.js First Party Data feature](/features/firstPartyData.html) -- [First Party Data Validation Module](/dev-docs/modules/validationFpdModule) -- [OpenRTB 2.5](https://www.iab.com/wp-content/uploads/2016/03/OpenRTB-API-Specification-Version-2-5-FINAL.pdf) diff --git a/dev-docs/modules/fledgeForGpt.md b/dev-docs/modules/fledgeForGpt.md index 5f64dfa5a5..221b11d6d3 100644 --- a/dev-docs/modules/fledgeForGpt.md +++ b/dev-docs/modules/fledgeForGpt.md @@ -3,7 +3,7 @@ layout: page_v2 page_type: module title: Module - fledgeForGpt description: how to use PAAPI with GPT -module_code : fledgeForGpt +module_code : paapiForGpt display_name : Fledge (PAAPI) for GPT enable_download : true sidebarType : 1 @@ -24,7 +24,7 @@ To use PAAPI with GPT: - include this module with your Prebid.js bundle; this also automatically includes the [PAAPI module](/dev-docs/modules/paapi.html) ```bash - gulp build --modules=fledgeForGpt,... + gulp build --modules=paapiForGpt,... ``` - [configure PAAPI](/dev-docs/modules/paapi.html#config) diff --git a/dev-docs/modules/floors.md b/dev-docs/modules/floors.md index ea86698556..634f61d7b1 100644 --- a/dev-docs/modules/floors.md +++ b/dev-docs/modules/floors.md @@ -371,7 +371,7 @@ a subset that will be merged under the 'data' object. | enforcement.floorDeals | boolean | Enforce floors for deal bid requests. | false | | enforcement.bidAdjustment | boolean | If true, the module will use the bidAdjustment function to adjust the floor per bidder. If false (or no bidAdjustment function is provided), floors will not be adjusted. Note: Setting this parameter to false may have unexpected results, such as signaling a gross floor when expecting net or vice versa. | true | | enforcement.enforceRate | integer | Prebid Server only: Defines a percentage for how often bid response enforcement activity should take place given that the floors feature is active. If the floors feature is skipped due to skipRate, this has no affect. For every non-skipped auction, this percent of them should be enforced: i.e. bids discarded. This feature lets publishers ease into enforcement in case bidders aren't adhering to floor rules. | 100 | -| enforcement.noFloorSignalBidders | array of strings | (Prebid.js 8.31+) Bidders which should not receive floor signals. | none | +| enforcement.noFloorSignalBidders | array of strings | (PBJS 8.31+, PBS-Java 3.4+) This is an array of bidders for which to avoid sending floors. This is useful for bidders where the publishers has established different floor rules in their systems. The value can be `["*"]`. | - | | endpoint | object | Controls behavior for dynamically retrieving floors. | - | | endpoint.url | string | URL of endpoint to retrieve dynamic floor data. | - | | data | object (required) | Floor data used by the module to pass floor data to bidders and floor enforcement. | - | @@ -380,7 +380,7 @@ a subset that will be merged under the 'data' object. | data.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. If skipRate is supplied in both the root level of the floors object and within the data object, the skipRate configuration within the data object shall prevail.| 0 | | data.floorsSchemaVersion | integer | The module supports two version of the data schema. Version 1 allows for only one model to be applied in a given data set, whereas Version 2 allows you to sample multiple models selected by supplied weights. If no schema version is provided, the module will assume version 1 for the sake of backwards compatiblity.| 1 | | data.modelTimestamp | int | Epoch timestamp associated with modelVersion. Can be used to track model creation of floor file for post auction analysis.| - | -| data.noFloorSignalBidders | array of strings | (Prebid.js 8.31+) Bidders which should not receive floor signals. | none | +| data.noFloorSignalBidders | array of strings | (PBJS 8.31+, PBS-Java 3.4+) This is an array of bidders for which to avoid sending floors. This is useful for bidders where the publishers has established different floor rules in their systems. The value can be `["*"]`. | - | | data.modelGroups | array of objects | Array of model objects to be used for A/B sampling multiple models. This field is only used when data.floorsSchemaVersion = 2 | - | | data.modelGroups[].currency | string | Currency of floor data. Floor Module will convert currency where necessary. See Currency section for more details. | 'USD' | | 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 | @@ -393,7 +393,7 @@ a subset that will be merged under the 'data' 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. | - | -| data.modelGroups[].noFloorSignalBidders | array of strings | (Prebid.js 8.31+) Bidders which should not receive floor signals. | none | +| data.modelGroups[].noFloorSignalBidders | array of strings | (PBJS 8.31+, PBS-Java 3.4+) This is an array of bidders for which to avoid sending floors. This is useful for bidders where the publishers has established different floor rules in their systems. The value can be `["*"]`. | - | | 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/genericAnalyticsAdapter.md b/dev-docs/modules/genericAnalyticsAdapter.md index 8c21311c66..201410e70b 100644 --- a/dev-docs/modules/genericAnalyticsAdapter.md +++ b/dev-docs/modules/genericAnalyticsAdapter.md @@ -28,9 +28,9 @@ This is an analytics adapter that can interface with any backend, meant for publ -### Note on GDPR enforcement +### Note on TCF controls -If you are using the [GDPR enforcement module](/dev-docs/modules/gdprEnforcement.html) to enforce purpose 7, by default this module will be blocked when GDPR is in scope. +If you are using the [TCF control module](/dev-docs/modules/tcfControl.html) to enforce purpose 7, by default this module will be blocked when GDPR is in scope. To enable it, you may either specify the `gvlid` option (if you are interfacing with a partner) or declare a `softVendorException` if you deem that vendor consent is not required for compliance: ```javascript diff --git a/dev-docs/modules/gppControl_usnat.md b/dev-docs/modules/gppControl_usnat.md index b9de3e0585..b250ae618b 100644 --- a/dev-docs/modules/gppControl_usnat.md +++ b/dev-docs/modules/gppControl_usnat.md @@ -21,7 +21,7 @@ sidebarType : 1 ## Overview -This consent management control module is designed to support the [Global Privacy Platform](https://iabtechlab.com/gpp/) Section 7 string, USNat. For more Prebid-related background, see [Prebid MSPA Support](/features/mspa-usnat.html). In sum, the USNat string is intended to unify various state laws into a single privacy string, with participants' behavior governed by the IAB's ([MSPA](https://www.iabprivacy.com/#)). It is intended to complement, not replace, the GPP consent management module, which gathers GPP consent strings and makes them available to vendor integrations. The goal is to gather sensible and conservative [activity controls](/dev-docs/activity-controls.html) for elements of Prebid.js given various expressions of the [USNat consent string](https://github.com/InteractiveAdvertisingBureau/Global-Privacy-Platform/blob/main/Sections/US-National/IAB%20Privacy%E2%80%99s%20National%20Privacy%20Technical%20Specification.md). +This consent management control module is designed to support the [Global Privacy Platform](https://iabtechlab.com/gpp/) Section 7 string, USNat. For more Prebid-related background, see [Prebid US Compliance Support](/features/mspa-usnat.html). In sum, the USNat string is intended to unify various state laws into a single privacy string, with participants' behavior governed by the IAB's ([MSPA](https://www.iabprivacy.com/#)). It is intended to complement, not replace, the GPP consent management module, which gathers GPP consent strings and makes them available to vendor integrations. The goal is to gather sensible and conservative [activity controls](/dev-docs/activity-controls.html) for elements of Prebid.js given various expressions of the [USNat consent string](https://github.com/InteractiveAdvertisingBureau/Global-Privacy-Platform/blob/main/Sections/US-National/IAB%20Privacy%E2%80%99s%20National%20Privacy%20Technical%20Specification.md). This module does not support any other GPP section id or local GPP api. For US state section see the [GPP Control - US State module](/dev-docs/modules/gppControl_usstates.html). In order to control activities in a section without a control module, publishers can express their controls directly in the syntax of the [activity control infrastructure](/dev-docs/activity-controls.html). If a publisher wants finer control over section 7 implications on Prebid.js behavior than this module provides (eg not invalidating certain strings), they are able to achieve that using the activity control syntax as an alternative to this module. @@ -47,7 +47,7 @@ You can also use the [Prebid.js Download](/download.html) page. - [IAB Global Privacy Platform Full Specification Repository](https://github.com/InteractiveAdvertisingBureau/Global-Privacy-Platform) - [IAB Global Privacy Platform CMP API Specification](https://github.com/InteractiveAdvertisingBureau/Global-Privacy-Platform/blob/main/Core/CMP%20API%20Specification.md) - [IAB Global Privacy Platform USNat string Specification](https://github.com/InteractiveAdvertisingBureau/Global-Privacy-Platform/blob/main/Sections/US-National/IAB%20Privacy%E2%80%99s%20National%20Privacy%20Technical%20Specification.md) -- [Prebid MSPA Support](/features/mspa-usnat.html) +- [Prebid US Compliance Support](/features/mspa-usnat.html) - [Prebid Activity Controls](/dev-docs/activity-controls.html) - [Prebid Consent Management - US Privacy Module](/dev-docs/modules/consentManagementUsp.html) - [Prebid Consent Management - GPP Module](/dev-docs/modules/consentManagementGpp.html) diff --git a/dev-docs/modules/gppControl_usstates.md b/dev-docs/modules/gppControl_usstates.md index e82ba32b91..502fe1845b 100644 --- a/dev-docs/modules/gppControl_usstates.md +++ b/dev-docs/modules/gppControl_usstates.md @@ -22,7 +22,7 @@ sidebarType : 1 ## Overview This consent management control module is designed to support the [Global Privacy Platform](https://iabtechlab.com/gpp/) US state strings, [GPP sections](https://github.com/InteractiveAdvertisingBureau/Global-Privacy-Platform/blob/main/Sections/Section%20Information.md) 8 through 12. -It works by translating them into an equivalent US national string as detailed in [Interpreting USNat strings](/features/mspa-usnat.html#interpreting-usnat-strings), and using it to apply the same [activity restricitons](/features/mspa-usnat.html#usnat-activity-restrictions). +It works by translating them into an equivalent US national string as detailed in [Interpreting USNat strings](/features/mspa-usnat.html#interpreting-usnat-strings), and using it to apply the same [activity restrictions](/features/mspa-usnat.html#usnat-activity-restrictions). {: .alert.alert-warning :} Prebid functionality created to address regulatory requirements does not replace each party's responsibility to determine its own legal obligations and comply with all applicable laws. **We recommend consulting with your legal counsel before determining how to utilize these features in support of your overall privacy approach. This module is not intended to replace other consent modules; it supplements them.** @@ -118,7 +118,7 @@ You can also use the [Prebid.js Download](/download.html) page. - [IAB Global Privacy Platform Full Specification Repository](https://github.com/InteractiveAdvertisingBureau/Global-Privacy-Platform) - [IAB Global Privacy Platform CMP API Specification](https://github.com/InteractiveAdvertisingBureau/Global-Privacy-Platform/blob/main/Core/CMP%20API%20Specification.md) - [IAB Global Privacy Platform USNat string Specification](https://github.com/InteractiveAdvertisingBureau/Global-Privacy-Platform/blob/main/Sections/US-National/IAB%20Privacy%E2%80%99s%20National%20Privacy%20Technical%20Specification.md) -- [Prebid MSPA Support](/features/mspa-usnat.html) +- [Prebid US Compliance Support](/features/mspa-usnat.html) - [Prebid Activity Controls](/dev-docs/activity-controls.html) - [Prebid Consent Management - US Privacy Module](/dev-docs/modules/consentManagementUsp.html) - [Prebid Consent Management - GPP Module](/dev-docs/modules/consentManagementGpp.html) diff --git a/dev-docs/modules/idWardRtdProvider.md b/dev-docs/modules/idWardRtdProvider.md index 642ae36ddd..9f49220c3d 100644 --- a/dev-docs/modules/idWardRtdProvider.md +++ b/dev-docs/modules/idWardRtdProvider.md @@ -8,6 +8,7 @@ module_type: rtd module_code : idWardRtdProvider enable_download : false vendor_specific: true +pbjs_version_notes: removed in 9.0 sidebarType : 1 --- diff --git a/dev-docs/modules/jwplayerRtdProvider.md b/dev-docs/modules/jwplayerRtdProvider.md index dacdf35035..7b973cdbef 100644 --- a/dev-docs/modules/jwplayerRtdProvider.md +++ b/dev-docs/modules/jwplayerRtdProvider.md @@ -42,7 +42,11 @@ To use this module, you'll need to work with [JW Player](https://www.jwplayer.co name: "jwplayer", waitForIt: true, params: { - mediaIDs: ['abc', 'def', 'ghi', 'jkl'] + mediaIDs: ['abc', 'def', 'ghi', 'jkl'], + overrideContentId: 'always', + overrideContentUrl: 'always', + overrideContentTitle: 'always', + overrideContentDescription: 'always' } }] } @@ -65,7 +69,7 @@ To use this module, you'll need to work with [JW Player](https://www.jwplayer.co | waitForIt | Boolean | Required to ensure that the auction is delayed until prefetch is complete | Optional. Defaults to false | | params | Object | | | | params.mediaIDs | Array of Strings | Media Ids for prefetching | Optional | - | params.overrideContentId | String enum: 'always', 'whenEmpty' or 'never' | Determines when the module should update the oRTB site.content.id | Defaults to 'always' | + | params.overrideContentId | String enum: 'always', 'whenEmpty' or 'never' | Determines when the module should update the oRTB site.content.id | Defaults to 'whenEmpty' | | params.overrideContentUrl | String enum: 'always', 'whenEmpty' or 'never' | Determines when the module should update the oRTB site.content.url | Defaults to 'whenEmpty' | | params.overrideContentTitle | String enum: 'always', 'whenEmpty' or 'never' | Determines when the module should update the oRTB site.content.title | Defaults to 'whenEmpty' | | params.overrideContentDescription | String enum: 'always', 'whenEmpty' or 'never' | Determines when the module should update the oRTB site.content.ext.description | Defaults to 'whenEmpty' | @@ -182,6 +186,6 @@ To view an example: * in your browser, navigate to: -`http://localhost:9999/integrationExamples/gpt/jwplayerRtdProvider_example.html` +`http://localhost:9999/integrationExamples/realTimeData/jwplayerRtdProvider_example.html` **Note:** the mediaIds in the example are placeholder values; replace them with your existing IDs. diff --git a/dev-docs/modules/mobianRtdProvider.md b/dev-docs/modules/mobianRtdProvider.md new file mode 100644 index 0000000000..8958fddf85 --- /dev/null +++ b/dev-docs/modules/mobianRtdProvider.md @@ -0,0 +1,19 @@ +--- +layout: page_v2 +title: Mobian Real-Time Data Provider +display_name: Mobian Prebid Brand Safety Evaluation +description: Mobian provides contextual brand safety evaluations of pages given a URL, which publishers can use for targeting as an alternative to keyword-based evaluation. +page_type: module +module_type: rtd +module_code : mobianRtdProvider +enable_download : true +vendor_specific: false +sidebarType : 1 +--- +# Mobian Brand Safety Module + +Mobian uses AI to determine the GARM risk level of articles from our publisher partners. +This methodology is contextual, rather than keyword-based. +Our evaluation of articles is openly available through our API. This prebid header +exposes that API at prebid time so that advertisers can easily target articles with +the desired mobianGarmRisk diff --git a/dev-docs/modules/permutiveRtdProvider.md b/dev-docs/modules/permutiveRtdProvider.md index b09e2f0dba..984ff6ccbf 100644 --- a/dev-docs/modules/permutiveRtdProvider.md +++ b/dev-docs/modules/permutiveRtdProvider.md @@ -73,7 +73,7 @@ as well as enabling settings for specific use cases mentioned above (e.g. acbidd Permutive is not listed as a TCF vendor as all data collection is on behalf of the publisher and based on consent the publisher has received from the user. Rather than through the TCF framework, this consent is provided to Permutive when the user gives the relevant permissions on the publisher website which allow the Permutive SDK to run. -This means that if GDPR enforcement is configured _and_ the user consent isn’t given for Permutive to fire, no cohorts will populate. +This means that if TCF controls are enabled _and_ the user consent isn’t given for Permutive to fire, no cohorts will populate. As Prebid utilizes TCF vendor consent, for the Permutive RTD module to load, Permutive needs to be labeled within the Vendor Exceptions ### Instructions diff --git a/dev-docs/modules/prebidServer.md b/dev-docs/modules/prebidServer.md index 22bb4c6737..60713aa438 100644 --- a/dev-docs/modules/prebidServer.md +++ b/dev-docs/modules/prebidServer.md @@ -56,20 +56,20 @@ The same bidder cannot be set in both configs. For example: ```javascript pbjs.setConfig({ s2sConfig: [ - { - name: "pbs-appnexus", - accountId: '12345', - bidders: ['appnexus','pubmatic'], - defaultVendor: 'appnexus', - timeout: 300, - }, - { - name: "pbs-rubicon", - accountId: '678910', - bidders: ['rubicon'], - defaultVendor: 'rubicon', - timeout: 300, - }, + { + name: "pbs-appnexus", + accountId: '12345', + bidders: ['appnexus','pubmatic'], + defaultVendor: 'appnexus', + timeout: 300, + }, + { + name: "pbs-rubicon", + accountId: '678910', + bidders: ['rubicon'], + defaultVendor: 'rubicon', + timeout: 300, + }, ], }); ``` @@ -85,7 +85,7 @@ There are many configuration options for s2sConfig: | `allowUnknownBidderCodes` | Optional | Boolean | Allow Prebid Server to bid on behalf of bidders that are not explicitly listed in the adUnit. See important [note](#allowUnknownBidderCodes) below. Defaults to `false`. | | `defaultVendor` | Optional | String | Automatically includes all following options in the config with vendor's default values. Individual properties can be overridden by including them in the config along with this setting. See the Additional Notes below for more information. | | `enabled` | Optional | Boolean | Enables this s2sConfig block - defaults to `false` | -| `timeout` | Optional | Integer | Number of milliseconds allowed for the server-side auctions. This should be approximately 200ms-300ms less than your Prebid.js timeout to allow for all bids to be returned in a timely manner. Defaults to 1000ms. | +| `timeout` | Optional | Integer | Number of milliseconds allowed for the server-side auctions. This should be approximately 200ms-300ms less than your Prebid.js timeout to allow for all bids to be returned in a timely manner. Defaults to 75% of [`bidderTimeout`](/dev-docs/publisher-api-reference/setConfig.html#setConfig-Bidder-Timeouts) or 750ms, whichever is lesser. | | `adapter` | Required | String | Adapter to use to connect to Prebid Server. Defaults to 'prebidServer' | | `endpoint` | Required | URL or Object | Defines the auction endpoint for the Prebid Server cluster. See table below for object config properties. | | `syncEndpoint` | Required | URL or Object | Defines the cookie_sync endpoint for the Prebid Server cluster. See table below for object config properties. | @@ -96,6 +96,7 @@ There are many configuration options for s2sConfig: | `defaultTtl` | Optional | Integer | Configures the default TTL in the Prebid Server adapter to use when Prebid Server does not return a bid TTL - 60 if not set | | `adapterOptions` | Optional | Object | Arguments will be added to resulting OpenRTB payload to Prebid Server in every impression object at request.imp[].ext.BIDDER. See the example above. | | `extPrebid` | Optional | Object | Arguments will be added to resulting OpenRTB payload to Prebid Server in request.ext.prebid. See the examples below. | +| `customHeader` | Optional | Object | These custom headers will be included in the XHR call to the bidder's endpoint. This will allow you to send data specific to your use case. The format consists of an object where the keys represent the header names and the values correspond to the respective header values. Here is an example how a customHeader object might look like - `{"Header1": "Value1", "Header2": "Value2"}`| If `endpoint` and `syncEndpoint` are objects, these are the supported properties: diff --git a/dev-docs/modules/pubxaiRtdProvider.md b/dev-docs/modules/pubxaiRtdProvider.md index 26a0f84923..f94758a106 100644 --- a/dev-docs/modules/pubxaiRtdProvider.md +++ b/dev-docs/modules/pubxaiRtdProvider.md @@ -48,18 +48,20 @@ pbjs.setConfig({ ..., realTimeData: { auctionDelay: AUCTION_DELAY, - dataProviders: { - name: "pubxai", - waitForIt: true, - params: { - pubxId: ``, - endpoint: ``, // (optional) - floorMin: ``, // (optional) - enforcement: ``, // (optional) - data: `` // (optional) - } - } - } + dataProviders: [ + { + name: "pubxai", + waitForIt: true, + params: { + pubxId: ``, + endpoint: ``, // (optional) + floorMin: ``, // (optional) + enforcement: ``, // (optional) + data: `` // (optional) + }, + }, + ], + }, // rest of the config ..., }); diff --git a/dev-docs/modules/gdprEnforcement.md b/dev-docs/modules/tcfControl.md similarity index 93% rename from dev-docs/modules/gdprEnforcement.md rename to dev-docs/modules/tcfControl.md index 27906a944b..42977e1e7c 100644 --- a/dev-docs/modules/gdprEnforcement.md +++ b/dev-docs/modules/tcfControl.md @@ -1,10 +1,10 @@ --- layout: page_v2 page_type: module -title: GDPR Enforcement Module +title: TCF Control Module description: If you have users in Europe, you can use this module to enable actions for processing under the GDPR and ePrivacy -module_code : gdprEnforcement -display_name : GDPR Enforcement +module_code : tcfControl +display_name : TCF Control enable_download : true recommended: true sidebarType : 1 @@ -19,17 +19,17 @@ sidebarType : 1 {% include legal-warning.html %} {: .alert.alert-warning :} -This module requires the [EU GDPR consent management module](/dev-docs/modules/consentManagement.html) (the base consent module), which reads consent values from the Consent Management Platform (CMP). The GDPR Enforcement Module -will then take action based on the results. See the [base module page](/dev-docs/modules/consentManagement.html) for general background, usage, and legal disclaimers. +This module requires the [TCF consent management module](/dev-docs/modules/consentManagementTcf.html) (the base consent module), which reads consent values from the Consent Management Platform (CMP). The TCF Control Module +will then take action based on the results. See the [base module page](/dev-docs/modules/consentManagementTcf.html) for general background, usage, and legal disclaimers. ## Overview -The [base consent module](/dev-docs/modules/consentManagement.html) performs the following actions: +The [base consent module](/dev-docs/modules/consentManagementTcf.html) performs the following actions: 1. Fetches the user's GDPR consent data from the CMP. 2. Incorporates this data into the auction objects for adapters to collect. -The GDPR Enforcement Module adds the following: +The TCF Control Module adds the following: 1. Allows the page to define which activities should be enforced at the Prebid.js level. 2. Actively enforces those activities based on user consent data. @@ -58,10 +58,10 @@ A page needs to define configuration rules about how Prebid.js should enforce ea {: .alert.alert-info :} To turn on Prebid.js enforcement you must: -(1) Include the gdprEnforcement module in the Prebid.js build +(1) Include the tcfControl module in the Prebid.js build and (2) setConfig `consentManagement.gdpr.cmpApi` to either 'iab' or 'static' -The following fields related to GDPR enforcement are supported in the [`consentManagement`](/dev-docs/modules/consentManagement.html) object: +The following fields related to GDPR enforcement are supported in the [`consentManagement`](/dev-docs/modules/consentManagementTcf.html) object: {: .table .table-bordered .table-striped } | Param | Type | Description | Example | @@ -228,14 +228,14 @@ This behavior can be changed to the same "basic enforcement" algorithm described Follow the basic build instructions in the GitHub Prebid.js repo's main [README](https://github.com/prebid/Prebid.js/blob/master/README.md). Include the base consent management module and this enforcement module as additional options on the **gulp build** command: ```bash -gulp build --modules=consentManagement,gdprEnforcement,bidAdapter1,bidAdapter2 +gulp build --modules=consentManagement,tcfControl,bidAdapter1,bidAdapter2 ``` You can also use the [Prebid.js Download](/download.html) page. ## Further Reading -* [EU GDPR Consent Management Module](/dev-docs/modules/consentManagement.html) +* [EU GDPR Consent Management Module](/dev-docs/modules/consentManagementTcf.html) * [IAB TCF Implementation Guidelines](https://github.com/InteractiveAdvertisingBureau/GDPR-Transparency-and-Consent-Framework/blob/master/TCFv2/TCF-Implementation-Guidelines.md) * [IAB TCF2 Consent String Format](https://github.com/InteractiveAdvertisingBureau/GDPR-Transparency-and-Consent-Framework/blob/master/TCFv2/IAB%20Tech%20Lab%20-%20Consent%20string%20and%20vendor%20list%20formats%20v2.md) * [Prebid TCF2 Support](https://docs.google.com/document/d/1fBRaodKifv1pYsWY3ia-9K96VHUjd8kKvxZlOsozm8E/edit#) diff --git a/dev-docs/modules/topLevelPaapi.md b/dev-docs/modules/topLevelPaapi.md new file mode 100644 index 0000000000..735846a760 --- /dev/null +++ b/dev-docs/modules/topLevelPaapi.md @@ -0,0 +1,124 @@ +--- +layout: page_v2 +page_type: module +title: Module - topLevelPaapi +description: Run top level PAAPI auctions +module_code : topLevelPaapi +display_name : Run top level PAAPI auctions +enable_download : true +sidebarType : 1 +--- + +# Top level PAAPI module + +This module allows Prebid.js to support PAAPI by running on-device auctions as the top level seller. + +## Comparison with paapiForGpt + +Both this module and [paapiForGpt](/dev-docs/modules/paapiForGpt.html) allow bid adapters to participate in PAAPI auctions as component sellers. + +With paapiForGpt, bidders' intent to participate in PAAPI is submitted to GPT, which can then decide how to run the on-device auction. +With topLevelPaapi, Prebid.js directly manages the on-device auction, trading ease of use for more control. + +## Publisher Integration + +To use topLevelPaapi: + +- you'll need a [decision logic URL](https://github.com/WICG/turtledove/blob/main/FLEDGE.md#23-scoring-bids) that has been [attested](https://github.com/privacysandbox/attestation) with Google. How to write decision logic and how to attest it are both out of scope for this document. +- include this module with your Prebid.js bundle; this also automatically includes the [PAAPI module](/dev-docs/modules/paapi.html) + + ```bash + gulp build --modules=topLevelPaapi,... + ``` + +- [configure this module](#config) +- render PAAPI bids (see [examples](#examples)) + + +## Module Configuration + +This module exposes the following settings: + +{: .table .table-bordered .table-striped } +|Name |Type |Description |Notes | +| ------------ | ------------ | ------------ |------------ | +|paapi.topLevelSeller | Object | | | +|paapi.topLevelSeller.auctionConfig | Object | Base [AuctionConfig](https://github.com/WICG/turtledove/blob/main/FLEDGE.md#2-sellers-run-on-device-auctions) to use in `runAdAuction` | Only `seller` and `decisionLogicURL` are required | +|paapi.topLevelSeller.autorun | Boolean | If `true` (the default) , automatically start PAAPI auctions as soon as possible | | +|paapi.topLevelSeller.overrideWinner | Boolean | If `true`, replace contextual winners with PAAPI winners as they are rendered. Default is `false`. | see [example](#overrideWinner) | + + +## Examples + +### Basic Example using renderAd + +```javascript +pbjs.setConfig({ + paapi: { + enabled: true, + defaultForSlots: 1, + topLevelSeller: { + auctionConfig: { + seller: 'https://www.publisher.com', + decisionLogicURL: 'https://www.publisher.com/decisionLogic.js', + }, + } + } +}) +``` + +With the above, `navigator.runAdAuction` is invoked once per ad unit, and the result is made available through [`getPAAPIBids`](/dev-docs/publisher-api-reference/getPAAPIBids.html): + +```javascript +pbjs.requestBids({ + bidsBackHandler: function(contextualBids) { + pbjs.getPAAPIBids().then(paapiBids => { + Object.entries(contextualBids).forEach(([adUnitCode, {bids}]) => { + const paapiWinner = paapiBids[adUnitCode]; + const contextualWinner = bids?.[0]; + const targetDoc = document.getElementById(adUnitCode).contentDocument // assumes there's an iframe with id = adUnitCode + // PAAPI bids can be rendered as if they were "normal" Prebid bids + if (paapiWinner) { + pbjs.renderAd(targetDoc, paapiWinner.adId) + } else { + pbjs.renderAd(targetDoc, contextualWinner.adId) + } + }) + }) + } +}) +``` + + +### Automatically render PAAPI winners instead of contextual bids + +When `overrideWinner` is enabled, rendering a "normal" Prebid bid will instead render a PAAPI bid, if the PAAPI auction for the slot yielded a winner. This is an easy way include the result of PAAPI auctions without having to change the rendering logic. For example: + +```javascript +pbjs.setConfig({ + paapi: { + enabled: true, + defaultForSlots: 1, + topLevelSeller: { + auctionConfig: { + seller: 'https://www.publisher.com', + decisionLogicURL: 'https://www.publisher.com/decisionLogic.js', + }, + overrideWinner: true + } + } +}); + +pbjs.requestBids({ + bidsBackHandler: function() { + // if Prebid wins the GAM auction (and renders a Prebid creative), the following will render PAAPI winners over the Prebid winners + pbjs.setTargetingForGPTAsync(); + } +}) +``` + +## Related Reading + +- [PAAPI module](/dev-docs/modules/paapi.html) +- [FLEDGE](https://github.com/WICG/turtledove/blob/main/FLEDGE.md) +- [getPAAPIBids](/dev-docs/publisher-api-reference/getPAAPIBids.html) diff --git a/dev-docs/modules/topicsFpdModule.md b/dev-docs/modules/topicsFpdModule.md index 30eff8b5e0..27346a3c01 100644 --- a/dev-docs/modules/topicsFpdModule.md +++ b/dev-docs/modules/topicsFpdModule.md @@ -55,15 +55,34 @@ pbjs.setConfig({ userSync: { // ..., topics: { - maxTopicCaller: 3, // SSP rotation + maxTopicCaller: 4, bidders: [{ bidder: 'pubmatic', - iframeURL: 'https://ads.pubmatic.com/AdServer/js/topics/topics_frame.html', - expiry: 7 // Configurable expiry days - },{ - bidder: 'appnexus', - iframeURL: 'https://appnexus.com:8080/topics/fpd/topic.html', // dummy URL - expiry: 7 // Configurable expiry days + iframeURL: 'https://ads.pubmatic.com/AdServer/js/topics/topics_frame.html' + }, { + bidder: 'rtbhouse', + iframeURL: 'https://topics.authorizedvault.com/topicsapi.html' + }, { + bidder: 'openx', + iframeURL: 'https://pa.openx.net/topics_frame.html' + }, { + bidder: 'improvedigital', + iframeURL: 'https://hb.360yield.com/privacy-sandbox/topics.html' + }, { + bidder: 'onetag', + iframeURL: 'https://onetag-sys.com/static/topicsapi.html' + }, { + bidder: 'taboola', + iframeURL: 'https://cdn.taboola.com/libtrc/static/topics/taboola-prebid-browsing-topics.html' + }, { + bidder: 'discovery', + iframeURL: 'https://api.popin.cc/topic/prebid-topics-frame.html' + }, { + bidder: 'undertone', + iframeURL: 'https://creative-p.undertone.com/spk-public/topics_frame.html' + }, { + bidder: 'vidazoo', + iframeURL: 'https://static.vidazoo.com/topics_api/topics_frame.html' }] } // ... diff --git a/dev-docs/modules/userId.md b/dev-docs/modules/userId.md index 3025b6e144..ff11f4b0e6 100644 --- a/dev-docs/modules/userId.md +++ b/dev-docs/modules/userId.md @@ -39,7 +39,7 @@ Not all bidder adapters support all forms of user ID. See the tables below for a ## User ID, GDPR, Permissions, and Opt-Out -When paired with the [Consent Management](/dev-docs/modules/consentManagement.html) module, privacy rules are enforced: +When paired with the [Consent Management](/dev-docs/modules/consentManagementTcf.html) module, privacy rules are enforced: * The module checks the GDPR consent string * If no consent string is available OR if the user has not consented to Purpose 1 (local storage): @@ -88,7 +88,7 @@ The table below has the options that are common across ID systems. See the secti | name | Required | String | May be any of the following values: {% for page in userid_pages -%}{% if count == 1 %}{{ name_string │ append: ", " -}}{% endif %}{% assign count = 1 %}`"{{ name_string │ append: name_string -}}{{ name_string │ append: page.useridmodule -}}"`{% endfor %} | `"unifiedId"` | | params | Based on User ID sub-module | Object | | | | bidders | Optional | Array of Strings | An array of bidder codes to which this user ID may be sent. | `['bidderA', 'bidderB']` | -| storage | Optional | Object | The publisher can specify some kind of local storage in which to store the results of the call to get the user ID. This can be cookie, HTML5 storage or both. This is not needed when `value` is specified or the ID system is managing its own storage | | +| storage | Optional | Object | The publisher can specify some kind of local storage in which to store the results of the call to get the user ID. This can be a cookie, HTML5 storage or both.| | | storage.type | Required | String | Must be `"cookie"`, `"html5"` or `"cookie&html5"`. This is where the results of the user ID will be stored. | `"cookie"` | | storage.name | Required | String | The name of the cookie or html5 local storage where the user ID will be stored. | `"_unifiedId"` | | storage.expires | Strongly Recommended | Integer | How long (in days) the user ID information will be stored. If this parameter isn't specified, session cookies are used in cookie-mode, and local storage mode will create new IDs on every page. | `365` | @@ -259,6 +259,7 @@ Bidders that want to support the User ID module in Prebid.js need to update thei | ConnectID | Yahoo | connectId | yahoo.com | {"connectId": "72d04af6..."} | | FreePass ID | FreePass | freepassId | | "1111" | | UtiqMtp ID | Utiq | utiqMtpId | utiq-mtp.com | "1111" | +| Yandex ID | Yandex | yandexId | yandex.com | "11111111111111111" | For example, the adapter code might do something like: @@ -344,7 +345,11 @@ If you're an ID provider that wants to get on this page: * Add your *IdSystem name into the modules/.submodules.json file * Follow all the guidelines in the [contribution page](https://github.com/prebid/Prebid.js/blob/master/CONTRIBUTING.md). * Submit a Pull Request against the [Prebid.js repository](https://github.com/prebid/Prebid.js). -* Fork the prebid.org [documentation repository](https://github.com/prebid/prebid.github.io), modify /dev-docs/modules/userId.md, /download.md, and submit a documentation Pull Request. +* Update the Prebid docs + * Fork the prebid.org [documentation repository](https://github.com/prebid/prebid.github.io) + * Add `/dev-docs/modules/userid-submodules/.md` + * Add a new row to `/dev-docs/modules/userId.md#prebidjs-adapters` + * Submit a documentation Pull Request @@ -411,4 +416,4 @@ This will have no effect until you call the `registerSignalSources` API. This me ## Further Reading * [Prebid.js Usersync](/dev-docs/publisher-api-reference/setConfig.html#setConfig-Configure-User-Syncing) -* [GDPR ConsentManagement Module](/dev-docs/modules/consentManagement.html) +* [TCF ConsentManagement Module](/dev-docs/modules/consentManagementTcf.html) diff --git a/dev-docs/modules/userid-submodules/33across.md b/dev-docs/modules/userid-submodules/33across.md index 903bc2a9df..d63c246e10 100644 --- a/dev-docs/modules/userid-submodules/33across.md +++ b/dev-docs/modules/userid-submodules/33across.md @@ -26,10 +26,11 @@ The following configuration parameters are available: | name | Required | String | The name of this sub-module | `"33acrossId"` | | params ||| Details for the sub-module initialization || | params.pid | Required | String | Partner ID (PID) | Please reach out to [PrebidUIM@33across.com](mailto:PrebidUIM@33across.com) and request your PID | -| params.storeFpid | Optional | Boolean | Indicates whether a supplemental first-party ID may be stored to improve addressability | `false` (default) or `true` | +| params.storeFpid | Optional | Boolean | Indicates whether a supplemental first-party ID may be stored to improve addressability | `true` (default) or `false` | +| params.storeTpid | Optional | Boolean | Indicates whether a supplemental third-party ID may be stored to improve addressability | `true` (default) or `false` | | storage ||||| | storage.name | Required | String | The name of the cookie or html5 local storage key | `"33acrossId"` (recommended) | -| storage.type | Required | String | This is where the 33across user ID will be stored | `"html5"` (recommended) or `"cookie"` | +| storage.type | Required | String | This is where the 33across user ID will be stored | `"cookie&html5"` (recommended) or `"html5"` or `"cookie"` | | storage.expires | Strongly Recommended | Number | How long (in days) the user ID information will be stored | `30` (recommended) | | storage.refreshInSeconds | Strongly Recommended | Number | How many seconds until the ID is refreshed | `8 * 3600` (recommended) | @@ -46,7 +47,7 @@ pbjs.setConfig({ }, storage: { name: "33acrossId", - type: "html5", + type: "cookie&html5", expires: 30, refreshInSeconds: 8 * 3600 } diff --git a/dev-docs/modules/userid-submodules/id5.md b/dev-docs/modules/userid-submodules/id5.md index e6f65a7bfd..1ab7dc315f 100644 --- a/dev-docs/modules/userid-submodules/id5.md +++ b/dev-docs/modules/userid-submodules/id5.md @@ -35,9 +35,10 @@ The following configuration parameters are available: | params.abTesting.enabled | Optional | Boolean | Set this to `true` to turn on this feature | `true` or `false` | | params.abTesting.controlGroupPct | Optional | Number | Must be a number between `0.0` and `1.0` (inclusive) and is used to determine the percentage of requests that fall into the control group (and thus not exposing the ID5 ID). For example, a value of `0.20` will result in 20% of requests without an ID5 ID and 80% with an ID. | `0.1` | | params.disableExtensions | Optional | Boolean | Set this to `true` to force turn off extensions call. Default `false` | `true` or `false` | +| params.provider | Optional | String | An identifier provided by ID5 to technology partners who manage API deployments on behalf of their clients. Reach out to ID5 if you have questions about this parameter. | `"providerName"` | {: .alert.alert-info :} -**NOTE:** The ID5 ID that is delivered to Prebid will be encrypted by ID5 with a rotating key to avoid unauthorized usage and to enforce privacy requirements. Therefore, we strongly recommend setting `storage.refreshInSeconds` to `8` hours (`8*3600` seconds) or less to ensure all demand partners receive an ID that has been encrypted with the latest key, has up-to-date privacy signals, and allows them to transact against it. +**NOTE:** The ID5 ID that is delivered to Prebid will be encrypted by ID5 with a rotating key to avoid unauthorized usage and to enforce privacy requirements. Therefore, we strongly recommend setting `storage.refreshInSeconds` to `2` hours (`7200` seconds) or less to ensure all demand partners receive an ID that has been encrypted with the latest key, has up-to-date privacy signals, and allows them to transact against it. ### A Note on A/B Testing @@ -70,7 +71,7 @@ pbjs.setConfig({ type: 'html5', // "html5" is the required storage type name: 'id5id', // "id5id" is the required storage name expires: 90, // storage lasts for 90 days - refreshInSeconds: 8*3600 // refresh ID every 8 hours to ensure it's fresh + refreshInSeconds: 7200 // refresh ID every 2 hours to ensure it's fresh } }], auctionDelay: 50 // 50ms maximum auction delay, applies to all userId modules @@ -80,3 +81,64 @@ pbjs.setConfig({ {: .alert.alert-warning :} **ATTENTION:** As of Prebid.js v4.14.0, ID5 requires `storage.type` to be `"html5"` and `storage.name` to be `"id5id"`. Using other values will display a warning today, but in an upcoming release, it will prevent the ID5 module from loading. This change is to ensure the ID5 module in Prebid.js interoperates properly with the [ID5 API](https://github.com/id5io/id5-api.js) and to reduce the size of publishers' first-party cookies that are sent to their web servers. For the same reasons it is very important as of Prebid.js v8.33.0 to provide the `externalModuleUrl` parameter and set it to the latest available module version at `https://cdn.id5-sync.com/api/1.0/id5PrebidModule.js`. If you have any questions, please reach out to us at [prebid@id5.io](mailto:prebid@id5.io). + +### Provided eids +The module provides following eids: + +```javascript +[ + { + source: 'id5-sync.com', + uids: [ + { + id: 'some-random-id-value', + atype: 1, + ext: { + linkType: 2, + abTestingControlGroup: false + } + } + ] + }, + { + source: 'true-link-id5-sync.com', + uids: [ + { + id: 'some-publisher-true-link-id', + atype: 1 + } + ] + }, + { + source: 'uidapi.com', + uids: [ + { + id: 'some-uid2', + atype: 3, + ext: { + provider: 'id5-sync.com' + } + } + ] + } +] +``` + +The id from `id5-sync.com` should be always present (though the id provided will be '0' in case of no consent or optout) + +The id from `true-link-id5-sync.com` will be available if the page is integrated with TrueLink (if you are an ID5 partner you can learn more at [ID5 wiki](https://wiki.id5.io/en/identitycloud/retrieve-id5-ids/true-link-integration)) + +The id from `uidapi.com` will be available if the partner that is used in ID5 user module has the EUID2 integration enabled (it has to be enabled on the ID5 side) + +### Providing TrueLinkId as a Google PPID + +TrueLinkId can be provided as a PPID - to use, it the `true-link-id5-sync.com` needs to be provided as a ppid source in prebid userSync configuration: + +```javascript +pbjs.setConfig({ + userSync: { + ppid: 'true-link-id5-sync.com', + userIds: [], //userIds modules should be configured here + } +}); +``` diff --git a/dev-docs/modules/userid-submodules/intentiq.md b/dev-docs/modules/userid-submodules/intentiq.md index e99228ef2a..d6540a0326 100644 --- a/dev-docs/modules/userid-submodules/intentiq.md +++ b/dev-docs/modules/userid-submodules/intentiq.md @@ -31,15 +31,16 @@ Please find below list of parameters that could be used in configuring Intent IQ {: .table .table-bordered .table-striped } -| Param under userSync.userIds[] | Scope | Type | Description | Example | -| ------------------------------ | -------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | --------------- | -| name | Required | String | The name of this module: "intentIqId" | `"intentIqId"` | -| params | Required | Object | Details for IntentIqId initialization. | | -| params.partner | Required | Number | This is the partner ID value obtained from registering with IntentIQ. | `1177538` | -| params.percentage | Required | Number | This a percentage value for our A/B testing group distribution. The values supposed to be in range of 0 to 100. We suggest to set it to 95 percent for optimal balance ofbetween prefromance and preceision. | `95` | -| params.pcid | Optional | String | This is the partner cookie ID, it is a dynamic value attached to the request. | `"g3hC52b"` | -| params.pai | Optional | String | This is the partner customer ID / advertiser ID, it is a dynamic value attached to the request. | `"advertiser1"` | -| params.enableCookieStorage | Optional | Boolean | This is a parameter allowing to enable or disable cookie storage. Defaults to false. | `"true"` | +| Param under userSync.userIds[] | Scope | Type | Description | Example | +| ------------------------------ | -------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------- | +| name | Required | String | The name of this module: "intentIqId" | `"intentIqId"` | +| params | Required | Object | Details for IntentIqId initialization. | | +| params.partner | Required | Number | This is the partner ID value obtained from registering with IntentIQ. | `1177538` | +| params.pcid | Optional | String | This is the partner cookie ID, it is a dynamic value attached to the request. | `"g3hC52b"` | +| params.pai | Optional | String | This is the partner customer ID / advertiser ID, it is a dynamic value attached to the request. | `"advertiser1"` | +| params.callback | Required | Function | This is a callback which is trigered with data and AB group | `(data, group) => console.log({ data, group })` | +| params.timeoutInMillis | Optional | Number | This is the timeout in milliseconds, which defines the maximum duration before the callback is triggered. The default value is 500. | `450` | +| params.browserBlackList | Optional |  String | This is the name of a browser that can be added to a blacklist. | `"chrome"` | ### Configuration example @@ -51,14 +52,13 @@ pbjs.setConfig({ name: "intentIqId", params: { partner: 123456, // valid partner id - percentage: 95, - enableCookieStorage: true + callback: (data, group) => window.pbjs.requestBids(), }, storage: { type: "html5", name: "intentIqId", // set localstorage with this name - expires: 60, - refreshInSeconds: 4 * 3600, // refresh ID every 4 hours to ensure it's fresh + expires: 0, + refreshInSeconds: 0, }, }, ], @@ -76,13 +76,14 @@ pbjs.setConfig({ partner: 123456 // valid partner id pcid: PCID_VARIABLE, // string value, dynamically loaded into a variable before setting the configuration pai: PAI_VARIABLE , // string value, dynamically loaded into a variable before setting the configuration - percentage: 95, - enableCookieStorage: false + timeoutInMillis: 500, + browserBlackList: "chrome", + callback: (data, group) => window.pbjs.requestBids() }, storage: { type: "html5", name: "intentIqId", // set localstorage with this name - expires: 60 + expires: 0 } }], syncDelay: 3000 diff --git a/dev-docs/modules/userid-submodules/liveintent.md b/dev-docs/modules/userid-submodules/liveintent.md index 882209903c..934fc5dca0 100644 --- a/dev-docs/modules/userid-submodules/liveintent.md +++ b/dev-docs/modules/userid-submodules/liveintent.md @@ -82,7 +82,7 @@ pbjs.setConfig({ ### Multiple user IDs -The attributes `uid2`, `medianet`, `magnite`, `bidswitch`, `pubmatic`, `openx`, `sovrn`, `index` and `thetradedesk` are treated specially by LiveIntent's user ID sub-module. Each of these attributes will result in a separate ID returned by the sub-module. +The attributes `uid2`, `medianet`, `magnite`, `bidswitch`, `pubmatic`, `openx`, `sovrn`, `index`, `thetradedesk` and `fpid` are treated specially by LiveIntent's user ID sub-module. Each of these attributes will result in a separate ID returned by the sub-module. Note: `thetradedesk` will be exposed as `tdid` because of historical reasons. For example, in case `uid2` is configured to be requested in addition to the `nonID`, the `request.userId` object would look like the following: @@ -100,9 +100,54 @@ For example, in case `uid2` is configured to be requested in addition to the `no } ``` -NOTE: `uid2` is exposed as part of `lipb` as well as separately as `uid2`. `medianet`, `magnite`, `bidswitch`, `pubmatic`, `openx`, `sovrn`, `index` and `thetradedesk` behave the same way. +NOTE: `uid2` is exposed as part of `lipb` as well as separately as `uid2`. `medianet`, `magnite`, `bidswitch`, `pubmatic`, `openx`, `sovrn`, `index`, `thetradedesk` (as `tdid`) and `fpid` behave the same way. -For the attributes `lipbid` (nonID), `uid2`, `medianet`, `magnite`, `bidswitch`, `pubmatic`, `openx`, `sovrn`, `index` and `thetradedesk`, there is also support for their conversion into OpenRTB EIDS format. Please refer to [User ID Module](../userId.md) documentation for more information on conversion, and [Example of eids array generated by UserId Module](https://github.com/prebid/Prebid.js/blob/master/modules/userId/eids.md) for output format examples. +For the attributes `lipbid` (nonID), `uid2`, `medianet`, `magnite`, `bidswitch`, `pubmatic`, `openx`, `sovrn`, `index`, `thetradedesk` (`tdid`) and `fpid` there is also support for their conversion into OpenRTB EIDS format. Please refer to [User ID Module](../userId.md) documentation for more information on conversion, and [Example of eids array generated by UserId Module](https://github.com/prebid/Prebid.js/blob/master/modules/userId/eids.md) for output format examples. + +### FPID + +The `fpid` is a first party identifier that can be exposed through the liveconnect user ID module. In order to use this functionality tell the module which identifier you want to use as a `fpid` in the config params: + +```javascript +{ + "params": { + "fpid": { + "strategy": "cookie", // "cookie" | "html5" -- Where the identifier should be read from + "name": "foobar" // key in the chosen storage backend + } + } +} +``` + +Additionally, add it to the requested attributes: + +```javascript +{ + //... + "params": { + "fpid": { + "strategy": "cookie", + "name": "foobar" + }, + "requestedAttributesOverrides": {'fpid': true} + } + //... +} +``` + +The user id result will contain both the `fpid` directly in the `lipb` object and separately: + +```javascript +{"lipb":{"fpid":"foobar"},"fpid":{"id":"foobar"}} +``` + +The same applies for the eids: + +```javascript +[{"source":"fpid.liveintent.com","uids":[{"id":"foobar","atype":1}]}] +``` + +NOTE: If COPPA applies, LiveIntent’s user ID module will not return the `fpid`. ### Request uid2 @@ -139,7 +184,7 @@ NOTE: For optimal performance, the LiveIntent ID sub-module should be called at | params.ajaxTimeout |Optional| Number |This configuration parameter defines the maximum duration of a call to the `IdentityResolution` endpoint. By default, 5000 milliseconds.|`5000`| | params.partner | Optional| String |The name of the partner whose data will be returned in the response.|`prebid`| | params.identifiersToResolve |Optional| Array[String] |Used to send additional identifiers in the request for LiveIntent to resolve against the LiveIntent ID and additional attributes.|`['my-id']`| -| params.requestedAttributesOverrides | Optional | Object | Object containing booleans used to override the default resolution. Attributes set to `true` will be added to the resolved list, while attributes set to `false` will be removed. Valid attributes are `nonId`, `uid2`, `medianet`, `magnite`, `bidswitch`, `pubmatic`, `openx`, `sovrn`, `index` and `thetradedesk`. | `{'uid2': true}` | +| params.requestedAttributesOverrides | Optional | Object | Object containing booleans used to override the default resolution. Attributes set to `true` will be added to the resolved list, while attributes set to `false` will be removed. Valid attributes are `nonId`, `uid2`, `medianet`, `magnite`, `bidswitch`, `pubmatic`, `openx`, `sovrn`, `index`, `thetradedesk` (`tdid`) and `fpid`. | `{'uid2': true}` | | params.emailHash |Optional| String |The hashed email address of a user. We can accept the hashes, which use the following hashing algorithms: md5, sha1, sha2.|`1a79a4d60de6718e8e5b326e338ae533`| | params.url | Optional| String |Use this to change the default endpoint URL if you can call the LiveIntent Identity Exchange within your own domain.|`https://idx.my-domain.com`| | params.liCollectConfig |Optional| Object |Container of all collector params.|| @@ -148,6 +193,12 @@ NOTE: For optimal performance, the LiveIntent ID sub-module should be called at | params.liCollectConfig.fpiExpirationDays |Optional| Number |The expiration time of an identifier created and updated by LiveConnect. By default, 730 days.|`729`| | params.liCollectConfig.collectorUrl |Optional| String |The parameter defines where the signal pixels are pointing to. The params and paths will be defined subsequently. If the parameter is not set, LiveConnect will by default emit the signal towards `https://rp.liadm.com`.| `https://rp.liadm.com`| | params.liCollectConfig.appId |Optional| String |LiveIntent's media business entity application ID.|`a-0012`| +| params.fpid.name | Optional | String | The parameter is cookie/localstorage key name | `'__super_duper_cookie'`| +| params.fpid.strategy | Optional | String | The parameter defines where to get the identifier from. Either from the cookie jar, `'cookie'`, or from the local storage, `'html5'`. | `'html5'`| +| storage | Required | Object | This object defines where and for how long the results of the call to get a user ID will be stored. | | +| storage.type | Required | String | This parameter defines where the resolved user ID will be stored (either `'cookie'` or `'html5'` localstorage).| `'cookie'` | +| storage.name | Required | String | The name of the cookie or html5 localstorage where the resolved user ID will be stored. | `'pbjs_li_nonid'` | +| storage.expires | Recommended | Integer | How long (in days) the user ID information will be stored. The recommended value is `1` | `1` | ## LiveIntent ID examples @@ -202,6 +253,10 @@ NOTE: For optimal performance, the LiveIntent ID sub-module should be called at fpiExpirationDays: 730, collectorUrl: "https://rp.liadm.com", appId: "a-0012" + }, + fpid: { + strategy: "cookie" + name: "foobar" } } }] diff --git a/dev-docs/modules/userid-submodules/parrable.md b/dev-docs/modules/userid-submodules/parrable.md index f022af4c33..d8aa3be3ea 100644 --- a/dev-docs/modules/userid-submodules/parrable.md +++ b/dev-docs/modules/userid-submodules/parrable.md @@ -2,6 +2,7 @@ layout: userid title: Parrable ID description: Parrable ID User ID sub-module +pbjs_version_notes: removed in 9.0 useridmodule: parrableIdSystem --- diff --git a/dev-docs/modules/userid-submodules/tncIdSystem.md b/dev-docs/modules/userid-submodules/tncIdSystem.md new file mode 100644 index 0000000000..6b82fd0250 --- /dev/null +++ b/dev-docs/modules/userid-submodules/tncIdSystem.md @@ -0,0 +1,36 @@ +# TNCID UserID Module + +## Prebid Configuration + +First, make sure to add the TNCID submodule to your Prebid.js package with: + +```bash +gulp build --modules=tncIdSystem,userId +``` + +## TNCIDIdSystem module Configuration + +Disclosure: This module loads external script unreviewed by the prebid.js community + +You can configure this submodule in your `userSync.userIds[]` configuration: + +```javascript +pbjs.setConfig({ + userSync: { + userIds: [{ + name: 'tncId', + params: { + url: 'https://js.tncid.app/remote.min.js' //Optional + } + }], + syncDelay: 5000 + } +}); +``` + +## Configuration Params + +| Param Name | Required | Type | Description | +| --- | --- | --- | --- | +| name | Required | String | ID value for the TNCID module: `"tncId"` | +| params.url | Optional | String | Provide TNC fallback script URL, this script is loaded if there is no TNC script on page | diff --git a/dev-docs/modules/userid-submodules/yandex.md b/dev-docs/modules/userid-submodules/yandex.md new file mode 100644 index 0000000000..1b0f8bbbbc --- /dev/null +++ b/dev-docs/modules/userid-submodules/yandex.md @@ -0,0 +1,37 @@ +--- +layout: userid +title: Yandex ID +description: Yandex User ID sub-module +useridmodule: yandexIdSystem +--- + +Yandex ID module is designed to improve the personalization of ads for publishers' users. This documentation provides information about the Yandex User ID module, and instructions to install it. + +## Step 1. Add Yandex ID to Prebid.js package + +Add the module to your Prebid.js package: + +{: .alert.alert-info :} +gulp build --modules=yandexIdSystem + +## Step 2. Enable Yandex ID + +Include the following call to `setConfig` in your Prebid.js code: + +```javascript +pbjs.setConfig({ + userSync: { + userIds: [ + { + name: 'yandex', + bidders: ['yandex'], + storage: { + type: 'cookie', + name: '_ym_uid', + expires: 365, + }, + }, + ], + }, +}); +``` diff --git a/dev-docs/pb9-notes.md b/dev-docs/pb9-notes.md new file mode 100644 index 0000000000..39bf23619b --- /dev/null +++ b/dev-docs/pb9-notes.md @@ -0,0 +1,124 @@ +--- +layout: page_v2 +title: Prebid.js 9.0 Release Notes & Publisher API Changes +description: Description of the breaking changes included for Prebid.js 9.0 +sidebarType: 1 +--- + +# Prebid.js 9.0 Bidder Interface and Publisher API Changes + +{:.no_toc} + +This document describes the changes included for Prebid.js version 9.0. + +* TOC +{:toc} + +## Removed Modules + +The following modules have been removed from Prebid.js as part of the 9.0 release. Publishers building with one of them will need to point to its replacement or remove the module from their build. + +{: .table .table-bordered .table-striped } +| Module | Replacement | +|:-----------------------------------------|:---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| Brightcom | OMS Bid Adapter | +| Sovrn Analytics | | +| Empty FPD module file | | +| Adomik | | +| Britepool | | +| SpotX | | +| pirId | | +| Engage BDR | | +| MyTarget | | +| Parrable | | +| Blue BillyWig | | +| Idward RTD | Anonymized RTD | +| Minutemedia Plus | | +| eplanning Analytics | | +| mars media Analytics | | +| sigmoid Analytics | | +| sonobi Analytics | | +| staq Analytics | | +| RichAudience | Update: added to 9.1.0 | +| adbookpsp | | +| yahooSSP | yahooAds | +| GDPR Consent module | TCF Consent module | +| GDPR Enforcement module | TCF Control module | +| Bizzclick | Blasto | +| Utiq | UtiqId | +| Prebid Manager | AsterioBid Prebid Manager | +| Ras | RingierAxelSpringer | +| Fledge for GPT | PAAPI for GPT | +| DFP Video | Split into DFP Video and DFP AdPod | + +## Consent changes + +The USP string was removed from the consent metadata; also USP module is no longer in the recommended build. The GDPR modules were renamed to TCF modules, to reflect their adherence to a technical specification and not imply adherence to the underlying legislation and case law. Support for GPP 1.0 was removed from the GPP module. Of particular importance, "vendorless" modules such as the sharedid module no longer rely on vendor consent in the TCF object, but instead rely on publisher purpose consent. Publishers should check their __tcfapi consent data object to confirm publisher purpose consents are requested by their CMP. + +## Rendering + +This [creative](https://github.com/prebid/Prebid.js/blob/master/integrationExamples/gpt/x-domain/creative.html) is now the preferred creative choice for Google Ad Manager users for web. It is created as part of the build process. This [legacy implementation](https://github.com/prebid/Prebid.js/blob/8.52.0/integrationExamples/gpt/creative_rendering.html) was deleted and examples using the Prebid Universal Creative (PUC) in documentation are being ported over to [the new guidance](https://docs.prebid.org/adops/js-dynamic-creative.html). Publishers also using Prebid Mobile SDK creative for apps may wish to remain on the PUC for ease of operations. + +The legacy method of trafficking native creatives has also had a deprecation warning issued. Publishers should prefer the Ortb2 implementation as sendTargetingKeys for native, hb_native_ASSET, will no longer be supported in a coming version. + +## Video ORTB2 Objects + +The Ortb2 core adapter utility no longer infers placement from context. Context = 'instream' now only refers to the technical integration method the publisher is using to interact with the player and is not relevant to the ortb2 bid requests. Adapters should not infer placement nor plcmt is instream from this value. It is however reasonable to infer plcmt = 4 from context = outstream. Adapters are not permitted to only support placement and not plcmt; they are welcome to pass both. Publishers are advised to set plcmt on their video ad units explicitly to avoid downstream inferences causing buyer inventory quality enforcements. + +## PAAPI + +Any module described as Fledge is now PAAPI. PAAPI Configuration is simplified and publishers experimenting with Fledge in 8.x should refer to the module documentation for updates. + +Publishers wishing to support PAAPI should install the PAAPI module and select the submodule appropriate for their top level seller (TLS). Both gpt.js and publisher designated top level decision logic have submodules. Ad servers wishing to add support for top level selling in Prebid.js may choose to issue instructions compatible with the newly released publisher designated TLS or submit their own submodule. + +Bid adapters can now return either complete auction config or an `igb` object according to the Ortb community extension for PAAPI. Publishers wishing to be or to designate a component seller to handle the `igb` objects returned by some bid modules should configure PAAPI with, for example + +`pbjs.setConfig({ + paapi: { + enabled: true, + componentSeller: { + auctionConfig: { + decisionLogicURL: 'publisher.example' + // ... + } + } + } + })` + +PAAPI for GPT now supports custom slot configuration. Also, the autoConfig option has been removed and replaced with configWithTargeting, defaulting to true, which sets GPT targeting and submits auction configs together. It differs in the previous autoconfig in that it no longer relies on gpt being available at the time of requestBids, only at the time of setTargeting. + +Publishers should be aware this behavior may prohibit submission of auction configuration to GPT sooner than the Prebid.js auction has completed, and will likely prefer to use `setPAAPIConfigForGPT`. We're hoping a futute gpt.js release will enable submission of configuration including unresolved promises earlier than the completion of the Prebid auction, by providing an `allConfigsSubmitted` type utility. Prebid support for other top level sellers will include this functionality in the near future. + +## Miscellaneous configuration changes (publishers) + +Pbadslot has had a deprecation warning issued, it is redundant specifying with imp.ext.gpid. Publishers setting pbadslot explicitly will see a warning. In the future, the pre-auction module will not populate it and setting it in configuration will have no effect. + +We stopped supporting top level site, app, and device configuration directly, eg `setConfig({device: X})`. Please prefer the ortb2 object in configuration (or in requestBids), eg `setConfig({ortb2: {device: X}})` + +s2s tmax and userId module default timings were set to more reasonable defaults. + +The Topics module now requires publishers to choose which external topics gathering frames will be injected. Documentation lists many options. + +We now require node.js 20+ to build. Babel was upgraded; the build target was modernized. The test suite raised its browser version targets. + +transformBidParams was removed from the build so publishers would not need an adapter to use a bidder in prebid server. Appnexus adapter added the anPspParamsConverter module as a temporary measure to solve for their adapter. + +Private functions are no longer available to npm consumers. + +Some adapters changed their configuration, including JW Player RTD, Openweb, Yahoo Ads, Improve Digital and 33Across Id module. See [https://github.com/prebid/Prebid.js/issues/11608](https://github.com/prebid/Prebid.js/issues/11608). + +## Miscellaneous deprecation notices (module maintainers) + +Bidders should prefer the eids object in the bidrequest. The redundant userid object in bid requests will be removed in a future version. + +Userid submodules may no longer be able to access set methods in storage manager in the future. The parent userid module is capable of setting the value returned by the submodule according to publisher configuration. + +A variety of performance degrading functions may become unavailable to adapters. Some already have, including .innerText and .outerText. Bidders should generally rely on the request object to interrogate navigator, and if things are missing from the request object, we invite PRs on it as preferred over redundant module implementations. + +Some modules not using our methods, or using excessive payloads, for storage or network transmission were modified. + +Bidders may no longer import the events system. + +getConfig is no longer allowed to gather consent, as it may be stale; use the consent object. + +Bidder companion scripts are now completely removed; only other module types may source js. diff --git a/dev-docs/publisher-api-reference/aliasBidder.md b/dev-docs/publisher-api-reference/aliasBidder.md index fd0a7248ef..24d7e6aef3 100644 --- a/dev-docs/publisher-api-reference/aliasBidder.md +++ b/dev-docs/publisher-api-reference/aliasBidder.md @@ -27,7 +27,7 @@ The options object supports these parameters: {: .table .table-bordered .table-striped } | Option Parameter | Type | Description | |------------|---------|---------------------------------| -| gvlid | integer | IAB Global Vendor List ID for this alias for use with the [GDPR Enforcement module](/dev-docs/modules/gdprEnforcement.html). | +| gvlid | integer | IAB Global Vendor List ID for this alias for use with the [TCF control module](/dev-docs/modules/tcfControl.html). | {: .alert.alert-info :} Creating an alias for a Prebid Server adapter is done differently. See 'extPrebid' diff --git a/dev-docs/publisher-api-reference/getPAAPIBids.md b/dev-docs/publisher-api-reference/getPAAPIBids.md new file mode 100644 index 0000000000..aa6cdb5365 --- /dev/null +++ b/dev-docs/publisher-api-reference/getPAAPIBids.md @@ -0,0 +1,93 @@ +--- +layout: api_prebidjs +title: pbjs.getPAAPIBids(options) +description: getPAAPIBids API +sidebarType: 1 +--- + +Returns a promise of the latest PAAPI bid for each ad unit, optionally filtered by auction or ad unit. + +**Kind**: static method of pbjs API. Only available when the [topLevelPaapi module](/dev-docs/modules/topLevelPaapi.html) is installed. + +**Returns**: `Promise` - Promise to a map from ad unit code to the PAAPI winner for that ad unit, if available. + +**Parameters**: + +{: .table .table-bordered .table-striped } +| Param | Scope | Type | Description | +| --- | --- | --- | --- | +| options | Optional | `Object` | | +| options.adUnitCode | Optional | `String` | Ad unit filter; if provided, only return the PAAPI winner for this ad unit | +| options.auctionId | Optional | `String` | Auction filter; if provided, only return PAAPI winners for this auction | + +**Result**: + +The return value is a map where each value is either `null` (when there is no PAAPI winner), or an object with this format: + +{: .table .table-bordered .table-stripped :} +| Param | Type | Description | +| --- | --- | --- | +| adId | String | Ad ID. can be used with [renderAd](/dev-docs/publisher-api-reference/renderAd.html) | +| auctionId | String | Auction ID tied to this bid | +| adUnitCode | String | Ad unit code tied to this bid | +| source | String | Always `"paapi"` | +| urn | String | Creative URN (only set if `paapi.topLevelSeller.auctionConfig.resolveToConfig` is `false`| +| frameConfig | Object | Creative fenced frame config (only set if `paapi.topLevelSeller.auctionConfig.resolveToConfig` is `true`| +| auctionConfig | Object | The auction config object that was passed to `navigator.runAdAuction` and generated this bid | +| width | Number | Creative width | +| height | Number | Creative height | + +**Example**: + +```js +pbjs.getPAAPIBids({adUnitCode: 'test-slot'}) +``` + +```json +{ + "test-slot": { + "source": "paapi", + "adId": "paapi:/0c00694d-958d-4250-98b3-5fe15cb019ab/:/test-slot", + "width": 300, + "height": 250, + "adUnitCode": "test-slot", + "auctionId": "0c00694d-958d-4250-98b3-5fe15cb019ab", + "urn": "urn:uuid:81005931-5726-4fb4-8bec-9ae74248e1ef", + "auctionConfig": { + "auctionSignals": { + "prebid": { + "bidfloor": 1, + "bidfloorcur": "USD" + } + }, + "requestedSize": { + "width": 300, + "height": 250 + }, + "componentAuctions": [ + { + "requestedSize": { + "width": "300px", + "height": "250px" + }, + "seller": "https://ads.optable.co", + "decisionLogicURL": "https://ads.optable.co/ca/paapi/v1/ssp/decision-logic.js?origin=daa30ba1-5613-4a2c-b7f0-34e2c033202a", + "interestGroupBuyers": [ + "https://ads.optable.co" + ], + "sellerCurrency": "USD", + "perBuyerCurrencies": { + "https://ads.optable.co": "USD" + }, + "perBuyerMultiBidLimits": { + "https://ads.optable.co": 100 + } + } + ], + "resolveToConfig": false, + "seller": "https://publisher.com", + "decisionLogicURL": "https://publisher.com/decisionLogic.js" + } + } +} +``` diff --git a/dev-docs/publisher-api-reference/setConfig.md b/dev-docs/publisher-api-reference/setConfig.md index 73ad3d0643..0ee1994b45 100644 --- a/dev-docs/publisher-api-reference/setConfig.md +++ b/dev-docs/publisher-api-reference/setConfig.md @@ -48,7 +48,7 @@ Core config: Module config: other options to `setConfig()` are available if the relevant module is included in the Prebid.js build. * [Currency module](/dev-docs/modules/currency.html) -* [Consent Management](/dev-docs/modules/consentManagement.html#page-integration) +* [Consent Management](/dev-docs/modules/consentManagementTcf.html#page-integration) * [User ID module](/dev-docs/modules/userId.html#configuration) * [Adpod](/dev-docs/modules/adpod.html) * [IAB Category Translation](/dev-docs/modules/categoryTranslation.html) diff --git a/dev-docs/release-notes.md b/dev-docs/release-notes.md index e85e26c54f..90b21a65c9 100644 --- a/dev-docs/release-notes.md +++ b/dev-docs/release-notes.md @@ -15,6 +15,7 @@ This page has links to release notes for each of the projects associated with Pr ## Prebid.js + [Release notes on GitHub](https://github.com/prebid/Prebid.js/releases) ++ [Prebid.js 9 Release Notes](/dev-docs/pb9-notes.html) + [Prebid.js 8 Release Notes](/dev-docs/pb8-notes.html) + [Prebid.js 7 Release Notes](/dev-docs/pb7-notes.html) + [Prebid.js 6 Blog Post](https://prebid.org/blog/prebid-6-0-release/) diff --git a/dev-docs/show-long-form-video-with-gam.md b/dev-docs/show-long-form-video-with-gam.md index 7f9d4ef178..fd18bc87b7 100644 --- a/dev-docs/show-long-form-video-with-gam.md +++ b/dev-docs/show-long-form-video-with-gam.md @@ -175,7 +175,7 @@ For instructions on setting custom price buckets, view the [Custom Price Granula ### 5. Send request for bids and build video URL -The `dfpAdServerVideo` module provides a method, `buildAdpodVideoUrl`, that combines publisher-provided parameters with Prebid.js targeting key values to build a GAM video ad tag URL that can be used by a video player. +The `dfpAdpod` module provides a method, `buildAdpodVideoUrl`, that combines publisher-provided parameters with Prebid.js targeting key values to build a GAM video ad tag URL that can be used by a video player. In the example below the callback in the `bidsBackHandler` returns the video ad tag needed by the video player. @@ -196,7 +196,7 @@ pbjs.que.push(function(){ pbjs.requestBids({ bidsBackHandler: function(bids) { - pbjs.adServers.dfp. buildAdpodVideoUrl({ + pbjs.adServers.dfp.buildAdpodVideoUrl({ codes: ['sample-code'], params: { iu: '/123456/testing/prebid.org/adunit1', diff --git a/dev-docs/show-prebid-ads-on-amp-pages.md b/dev-docs/show-prebid-ads-on-amp-pages.md index 555b42648b..b9244d2611 100644 --- a/dev-docs/show-prebid-ads-on-amp-pages.md +++ b/dev-docs/show-prebid-ads-on-amp-pages.md @@ -6,7 +6,6 @@ sidebarType: 2 --- # Prebid AMP Implementation Guide - {: .no_toc} This page has instructions for showing ads on Accelerated Mobile Pages (AMP) using Prebid.js. @@ -15,11 +14,11 @@ Through this implementation, [Prebid Server][PBS] fetches demand and returns key For more information about AMP RTC, see: -* [Prebid Server and AMP](/prebid-server/use-cases/pbs-amp.html) -* [Prebid Server AMP Endpoint Technical Documentation](/prebid-server/endpoints/openrtb2/pbs-endpoint-amp.html) -* [Prebid Server Stored Bid Requests](https://github.com/prebid/prebid-server/blob/master/docs/developers/stored-requests.md#stored-bidrequests) -* [AMP RTC Overview](https://github.com/ampproject/amphtml/blob/master/extensions/amp-a4a/rtc-documentation.md) -* [AMP RTC Publisher Integration Guide](https://github.com/ampproject/amphtml/blob/master/extensions/amp-a4a/rtc-publisher-implementation-guide.md) +- [Prebid Server and AMP](/prebid-server/use-cases/pbs-amp.html) +- [Prebid Server AMP Endpoint Technical Documentation](/prebid-server/endpoints/openrtb2/pbs-endpoint-amp.html) +- [Prebid Server Stored Bid Requests](https://github.com/prebid/prebid-server/blob/master/docs/developers/stored-requests.md#stored-bidrequests) +- [AMP RTC Overview](https://github.com/ampproject/amphtml/blob/master/extensions/amp-a4a/rtc-documentation.md) +- [AMP RTC Publisher Integration Guide](https://github.com/ampproject/amphtml/blob/master/extensions/amp-a4a/rtc-publisher-implementation-guide.md) {% capture tipNote %} For ad ops setup instructions, see [Google Ad Manager with Prebid Step by Step](/adops/step-by-step.html). @@ -27,25 +26,25 @@ For ad ops setup instructions, see [Google Ad Manager with Prebid Step by Step]( {% include alerts/alert_note.html content=tipNote %} -* TOC +- TOC {:toc } ## Prerequisites To set up Prebid to serve ads into your AMP pages, you'll need: -* An account with a [Prebid Server][PBS] instance -* One or more Prebid Server Stored Bid Requests. A Stored Bid Request is a partial OpenRTB JSON request which: - * Specifies properties like currency, schain, price granularity, etc. - * Contains a list of demand partners and their respective parameters -* An AMP page containing at least one amp-ad element for an AMP ad network that supports Fast Fetch and AMP RTC +- An account with a [Prebid Server][PBS] instance +- One or more Prebid Server Stored Bid Requests. A Stored Bid Request is a partial OpenRTB JSON request which: + - Specifies properties like currency, schain, price granularity, etc. + - Contains a list of demand partners and their respective parameters +- An AMP page containing at least one amp-ad element for an AMP ad network that supports Fast Fetch and AMP RTC ## Implementation -* [Prebid Server Stored Request](#prebid-server-stored-request): This is the Prebid Server Stored Bid Request. -* [AMP content page](#amp-content-page): This is where your content lives. -* [HTML Creative](#html-creative): This is the creative your Ad Ops team puts in your ad server. -* [User Sync in AMP](#user-sync): This is the `amp-iframe` pixel that must be added to your AMP page to sync users with Prebid Server. +- [Prebid Server Stored Request](#prebid-server-stored-request): This is the Prebid Server Stored Bid Request. +- [AMP content page](#amp-content-page): This is where your content lives. +- [HTML Creative](#html-creative): This is the creative your Ad Ops team puts in your ad server. +- [User Sync in AMP](#user-sync): This is the `amp-iframe` pixel that must be added to your AMP page to sync users with Prebid Server. ### Prebid Server Stored Request @@ -54,12 +53,12 @@ You will have to create at least one Stored Request for Prebid Server. Valid St An example Stored Request is given below. You'll see that the Stored Request contains some important info that doesn't come from /amp parameters: -* cur -* schain -* ext.prebid.cache.bids - needed to let Prebid Server know that you want it to store the result in PBC -* ext.prebid.targeting.pricegranularity - needed to let Prebid Server know how to calculate the price bucket -* ext.prebid.aliases -* bidders and their parameters +- cur +- schain +- ext.prebid.cache.bids - needed to let Prebid Server know that you want it to store the result in PBC +- ext.prebid.targeting.pricegranularity - needed to let Prebid Server know how to calculate the price bucket +- ext.prebid.aliases +- bidders and their parameters ```json { @@ -129,10 +128,10 @@ This script provides code libraries that will convert `` properties to t The `amp-ad` elements in the page body need to be set up as shown below, especially the following attributes: -* `data-slot`: Identifies the ad slot for the auction. -* `rtc-config`: Used to pass JSON configuration data to [Prebid Server][PBS], which handles the communication with AMP RTC. - * `vendors` is an object that defines any vendors that will be receiving RTC callouts (including Prebid Server) up to a maximum of five. The list of supported RTC vendors is maintained in [callout-vendors.js](https://github.com/ampproject/amphtml/blob/master/src/service/real-time-config/callout-vendors.js). We recommend working with your Prebid Server hosting company to set up which bidders and parameters should be involved for each AMP ad unit. - * `timeoutMillis` is an optional integer that defines the timeout in milliseconds for each individual RTC callout. The configured timeout must be greater than 0 and less than 1000ms. If omitted, the timeout value defaults to 1000ms. +- `data-slot`: Identifies the ad slot for the auction. +- `rtc-config`: Used to pass JSON configuration data to [Prebid Server][PBS], which handles the communication with AMP RTC. + - `vendors` is an object that defines any vendors that will be receiving RTC callouts (including Prebid Server) up to a maximum of five. The list of supported RTC vendors is maintained in [callout-vendors.js](https://github.com/ampproject/amphtml/blob/master/src/service/real-time-config/callout-vendors.js). We recommend working with your Prebid Server hosting company to set up which bidders and parameters should be involved for each AMP ad unit. + - `timeoutMillis` is an optional integer that defines the timeout in milliseconds for each individual RTC callout. The configured timeout must be greater than 0 and less than 1000ms. If omitted, the timeout value defaults to 1000ms. e.g. for the AppNexus cluster of Prebid Servers: @@ -222,15 +221,15 @@ Replace `MACRO` in the preceding example with the appropriate macro for the ad s ### User Sync -To sync user IDs with Prebid Server, the `amp-iframe` below may be added to your AMP pages referring to `load-cookie.html` or if you're running an IAB-compliant AMP CMP you can use `load-cookie-with-consent.html`. +To sync user IDs with Prebid Server, the `amp-iframe` below may be added to your AMP pages referring to `load-cookie.html`. -Note that AMP constrains syncing as described in the [amp-iframe](https://amp.dev/documentation/components/amp-iframe) documentation. You may only have *one* amp-iframe on your page that is small, e.g. 1x1. Many publishers already have some kind of analytics or tracking frame on their page, so they may find it difficult to manage this. Several hacks are possible, including building a 'frankenstein' script that combines all of your required tracking into one or tying the sync to an image that's large enough to be visible. +AMP constrains syncing as described in the [amp-iframe](https://amp.dev/documentation/components/amp-iframe) documentation. You may only have *one* amp-iframe on your page that is small, e.g. 1x1. Many publishers already have some kind of analytics or tracking frame on their page, so they may find it difficult to manage this. Several hacks are possible, including building a 'frankenstein' script that combines all of your required tracking into one or tying the sync to an image that's large enough to be visible. Notes: -* The following examples include a transparent image as a placeholder which will allow you to place the example at the top within the HTML body. If this is not included the iFrame must be either 600px away from the top or not within the first 75% of the viewport when scrolled to the top – whichever is smaller. For more information on this, see [amp-iframe](https://amp.dev/documentation/components/amp-iframe/) -* Note that the `sandbox` parameter to the amp-iframe must include both "allow-scripts" and "allow-same-origin". -* The load-cookie-with-consent.html file has the same argument syntax as load-cookie.html. It's a different file because it's larger and depends on the existence of an AMP Consent Management Platform. +- The following examples include a transparent image as a placeholder which will allow you to place the example at the top within the HTML body. If this is not included the iFrame must be either 600px away from the top or not within the first 75% of the viewport when scrolled to the top – whichever is smaller. For more information on this, see [amp-iframe](https://amp.dev/documentation/components/amp-iframe/) +- The `sandbox` parameter to the amp-iframe must include both "allow-scripts" and "allow-same-origin". +- If your PBS host company is using a version of `load-cookie.html` older than July of 2024 and if your AMP page is using a CMP, you should consider using `load-cookie-with-consent.html` instead. It's the same functionality, but older versions of `load-cookie.html` cannot read from CMPs. If you're using AppNexus' managed service, you would enter something like this: @@ -268,44 +267,44 @@ Or you can specify a full URL to another Prebid Server location (including a QA ``` -See [manually initiating a sync](/prebid-server/developers/pbs-cookie-sync.html#manually-initiating-a-sync) for more information about the available parameters. +See [manually initiating a sync](/prebid-server/developers/pbs-cookie-sync.html#manually-initiating-a-sync) for more information about the available parameters and for how to host the load-cookie script. ### AMP RTC If you're using a custom RTC callout rather than one of the pre-defined [vendor callouts](https://github.com/ampproject/amphtml/blob/main/src/service/real-time-config/callout-vendors.js), here are the parameters that can be passed through the RTC string: -* tag_id (this correspondes to the Prebid Server stored request ID) -* w=ATTR(width) -* h=ATTR(height) -* ow=ATTR(data-override-width) -* oh=ATTR(data-override-height) -* ms=ATTR(data-multi-size) -* slot=ATTR(data-slot) -* targeting=TGT -* curl=CANONICAL_URL -* timeout=TIMEOUT -* adc=ADCID -* purl=HREF -* gdpr_consent=CONSENT_STRING -* consent_type=CONSENT_METADATA(consentStringType) -* gdpr_applies=CONSENT_METADATA(gdprApplies) -* attl_consent=CONSENT_METADATA(additionalConsent) +- tag_id (this correspondes to the Prebid Server stored request ID) +- w=ATTR(width) +- h=ATTR(height) +- ow=ATTR(data-override-width) +- oh=ATTR(data-override-height) +- ms=ATTR(data-multi-size) +- slot=ATTR(data-slot) +- targeting=TGT +- curl=CANONICAL_URL +- timeout=TIMEOUT +- adc=ADCID +- purl=HREF +- gdpr_consent=CONSENT_STRING +- consent_type=CONSENT_METADATA(consentStringType) +- gdpr_applies=CONSENT_METADATA(gdprApplies) +- attl_consent=CONSENT_METADATA(additionalConsent) ## Debugging Tips To review that Prebid on AMP is working properly the following aspects can be looked at: -* Include `#development=1` to the URL to review AMP specifc debug messages in the browser console. -* Look for the Prebid server call in the network panel. You can open this URL in a new tab to view additional debugging information relating to the Prebid Server Stored Bid Request. If working properly, Prebid server will display the targeting JSON for AMP to use. -* Look for the network call from the Ad Server to ensure that key values are being passed. (For Google Ad Manager these are in the `scp` query string parameter in the network request) -* Most of the debugging information is omitted from the Prebid Server response unless the `debug=1` parameter is present in the Prebid Server query string. AMP won't add this parameter, so you'll need to grab the Prebid Server URL and manually add it to see the additional information provided. +- Include `#development=1` to the URL to review AMP specifc debug messages in the browser console. +- Look for the Prebid server call in the network panel. You can open this URL in a new tab to view additional debugging information relating to the Prebid Server Stored Bid Request. If working properly, Prebid server will display the targeting JSON for AMP to use. +- Look for the network call from the Ad Server to ensure that key values are being passed. (For Google Ad Manager these are in the `scp` query string parameter in the network request) +- Most of the debugging information is omitted from the Prebid Server response unless the `debug=1` parameter is present in the Prebid Server query string. AMP won't add this parameter, so you'll need to grab the Prebid Server URL and manually add it to see the additional information provided. ## Further Reading -* [Prebid Server and AMP](/prebid-server/use-cases/pbs-amp.html) -* [Google Ad Manager with Prebid Step by Step](/adops/step-by-step.html) (Ad Ops Setup) -* [AMP RTC Overview](https://github.com/ampproject/amphtml/blob/master/extensions/amp-a4a/rtc-documentation.md) -* [callout-vendors.js] +- [Prebid Server and AMP](/prebid-server/use-cases/pbs-amp.html) +- [Google Ad Manager with Prebid Step by Step](/adops/step-by-step.html) (Ad Ops Setup) +- [AMP RTC Overview](https://github.com/ampproject/amphtml/blob/master/extensions/amp-a4a/rtc-documentation.md) +- [callout-vendors.js] diff --git a/faq/prebid-server-faq.md b/faq/prebid-server-faq.md index 26d7946c36..5f6ad81c19 100644 --- a/faq/prebid-server-faq.md +++ b/faq/prebid-server-faq.md @@ -248,6 +248,10 @@ In the long run, if you'd prefer to change the filenames too, that's ok - but ou 1. Submit a PR that changes the filenames and makes the old name a hard-coded alias. 2. Keep both bidder documentation files. +## May I build a server that calls Prebid Server? + +Sure. The main endpoint you're going to utilize is the [auction endpoint](/prebid-server/endpoints/openrtb2/pbs-endpoint-auction.html). Basically, it's just OpenRTB 2.6, but with quite a few Prebid-specific extensions. See the [auction request example](/prebid-server/endpoints/openrtb2/auction-request-example.html). + ## Should Prebid bidders be in ads.txt? Publishers should be careful to list all their bidding partners in their ads.txt file. Bidders without an entry in ads.txt may be diff --git a/features/ac-quebec.md b/features/ac-quebec.md index 7a76f77f07..f8555e3530 100644 --- a/features/ac-quebec.md +++ b/features/ac-quebec.md @@ -101,9 +101,6 @@ bidders are in such alignment. An alternate solution would utilize the Prebid Server version of the [Activity Control system](/prebid-server/features/pbs-activitycontrols.html). -{: .alert.alert-info :} -Only the Java version of Prebid Server currently supports targeting Activity Controls to geographic regions. - Here's an example account configuration that utilizes the user's geographic region to determine whether to allow or deny the named activities. Publishers will need to confirm the details with their Prebid Server host company. diff --git a/features/firstPartyData.md b/features/firstPartyData.md index 135f78e363..899956f4fd 100644 --- a/features/firstPartyData.md +++ b/features/firstPartyData.md @@ -188,7 +188,7 @@ pbjs.setConfig({ {: .alert.alert-warning :} Note that supplying first party **user** data may require special -consent in certain regions. By default, Prebid's [gdprEnforcement](/dev-docs/modules/gdprEnforcement.html) module does **not** police the passing +consent in certain regions. By default, Prebid's [tcfControl](/dev-docs/modules/tcfControl.html) module does **not** police the passing of user data, but can optionally do so if the `personalizedAds` rule is enabled. {: .alert.alert-warning :} diff --git a/features/mspa-usnat.md b/features/mspa-usnat.md index f488fd3a06..635783088d 100644 --- a/features/mspa-usnat.md +++ b/features/mspa-usnat.md @@ -1,11 +1,11 @@ --- layout: page_v2 -title: Prebid MSPA Support -description: Prebid MSPA Support +title: Prebid US Compliance Support +description: Prebid US Compliance Support sidebarType: 7 --- -# Prebid Multi-State Privacy Agreement Support +# Prebid US Compliance Support {: .no_toc} - TOC @@ -17,24 +17,27 @@ sidebarType: 7 Starting July 1st 2023, several US states started enforcing new privacy regulations. -The IAB released the "Multi-State Privacy Agreement" (MSPA) as its proposal for how the advertising ecosystem can support these and future US State regulations. References: +As a result, the IAB released the "Multi-State Privacy Agreement" (MSPA), the Global Privacy Protocol (GPP), and several "sections" of the GPP dedicated to these US states. References: - [IAB's MSPA](https://www.iab.com/news/multi-state-privacy-agreement-mspa/) - IAB Guidance on the [MSPA Decision Tree](https://www.iab.com/wp-content/uploads/2022/12/IAB_MSPA_Decision_Tree.pdf) - IAB's [US National technical protocols](https://github.com/InteractiveAdvertisingBureau/Global-Privacy-Platform/tree/main/Sections) +Prebid refers to GPP Sections 7-12 as "US Compliance", which is distinct from the original [US Privacy](https://github.com/InteractiveAdvertisingBureau/USPrivacy/blob/master/CCPA/US%20Privacy%20String.md) approach which has been deprecated. + ### Glossary 1. **Global Privacy Platform (GPP)** - A technical IAB framework that defines a container format for communicating multiple privacy protocols. e.g. GPP can contain existing Transparency and Consent Framework (TCF) strings, various US privacy string formats, and other future implementations. 1. **GPP Section ID (SID)** - the GPP container may contain multiple encoded privacy protocol strings. Each protocol gets its own SID in the overall GPP container. e.g. TCF-EU is assigned SID 2. -1. **Multi-State Privacy Agreement (MSPA)** - the IAB's contractual framework for publishers to manage various US state privacy laws. +1. **Multi-State Privacy Agreement (MSPA)** - the IAB's contractual framework for publishers to manage various US state privacy laws. Note that there are high profile companies in the industry that have not signed the MSPA, but are still able to process the IAB's technical protocol to consider user preferences. 1. **MSPA Covered Transaction** - Whether a given ad auction falls legally under the MSPA's privacy requirements. For MSPA-covered 'transactions' (ad auctions), publishers must declare themselves in one of two modes: "Service Provider Mode" or "Opt-Out Mode". 1. **MSPA Service Provider Mode** - "Service Provider Mode is for First Parties who do not Sell or Share Personal Information, and do not Process Personal Information for Targeted Advertising". This means that personal information is never sent to downstream entities. 1. **MSPA Opt-Out Mode** - For First Parties that may engage in targeted advertising activities or disclose personal information for such purposes. This means that user consent is gathered before privacy-sensitive data is sent to downstream entities. 1. **US National Privacy Technical Specification (USNat)** - the IAB's technical framework for encoding MSPA publisher policies and user consents. Stored in the GPP container as SID 7. 1. **US State Privacy Technical Specifications** - the IAB has defined technical frameworks for 5 states based on their interpretation of state privacy laws. These protocols are similar to the US National protocol and are stored in the GPP container as SIDs 8 through 12. +1. **US Compliance** - the term Prebid uses to encompass both US National Privacy Technical Specification and the US State Privacy Technical Specifications. 1. **Global Privacy Control (GPC)** - a browser-level control for end users. Some US states have referred to a global control so that users don't have to state their preferences on each website they visit. The USNat protocol strings also contain the GPC flag. -1. **US Privacy** - this is the IAB's original version of a US privacy protocol, meant to address CCPA only. It's active during a transition period until September 30, 2023. +1. **US Privacy** - this is the IAB's original, now deprecated, version of a US privacy protocol, meant to address older California laws. 1. **Prebid Activity Controls** - Prebid.js and Prebid Server have identified a set of behaviors for activities that may be in scope for privacy concerns such as transmitting user IDs. These activities may be allowed or suppressed with flexible conditions and exceptions as defined by the publisher. - [Prebid.js Activity Controls](/dev-docs/activity-controls.html) were released with PBJS 7.52 - [Prebid Server Activity Controls](/prebid-server/features/pbs-activitycontrols.html) were released with PBS-Java 1.118 @@ -50,29 +53,29 @@ Prebid's assumptions about the MSPA and the US National Privacy specification: 1. For requests that are in-scope for SIDs 7 through 12 that are not "covered" by MSPA, Prebid treats them as being in "Opt-Out Mode". This implies that CMPs have prompted users for consent and encoded the results in the relevant section of the GPP container. 1. Prebid never changes the GPP string. This means that all downstream vendors will see whatever the CMP set. 1. Prebid has implemented a default way to interpret the US National string (SID 7) in the context of each Prebid Activity. -1. US state privacy rules do not mandate the cancellation of contextual advertising, but rather are focused on protecting user privacy. Therefore, Prebid's MSPA module may anonymize different aspects of a header bidding auction, but will never outright cancel an auction. +1. US state privacy rules do not mandate the cancellation of contextual advertising, but rather are focused on protecting user privacy. Therefore, Prebid's US compliance modules may anonymize different aspects of a header bidding auction, but will never outright cancel an auction. 1. There are differences in the US state-level protocols and the US National protocol as defined by the IAB. (e.g. child consent for targeted advertising is somewhat different across SIDs 7 through 12.) 1. Rather than implementing several very similar modules and forcing publishers to include separate modules for each US state, Prebid handles state differences through a normalization process. The differences for each state are mapped onto the US National (SID 7) string, and that string is interpreted for which activities are allowed or suppressed. As with the rest of Prebid’s approach, this is a default intended to ease publishers’ ability to comply with the state laws, but publishers should make their own determinations about state law obligations and consult legal counsel to ensure that they feel comfortable that this approach allows them to meet their legal obligations. 1. Publishers that do not agree with Prebid's default behavior may override the behavior. This includes the interpretation of the USNat string as well as the normalization of state protocols. 1. The Global Privacy Control (GPC) flag is interpreted as a strong user signal that ad requests should be anonymized. 1. There's no need to support a data-deletion activity for MSPA. -1. Prebid doesn't need to explicitly support mapping US National Privacy SID 6 (legacy US Privacy) for anonymization activities. This is covered by a feature on Prebid Server where SID 6 is pulled out into regs.us_privacy and is covered by documentation in Prebid.js. +1. Prebid doesn't need to explicitly support mapping GPP SID 6 (legacy US Privacy) for anonymization activities. This is covered by a feature on Prebid Server where SID 6 is pulled out into regs.us_privacy and is covered by documentation in Prebid.js. -## USNat Support in Prebid Products +## US Compliance Support in Prebid Products ### Prebid.js Here's a summary of the privacy features in Prebid.js that publishers may use to align with the guidance of their legal counsel: {: .table .table-bordered .table-striped } -| Prebid.js Version | USNat-Related Features | Notes | +| Prebid.js Version | US Compliance-Related Features | Notes | | ----------------- | ---------------------- | ----- | | before 7.30 | None | If you operate in the US, you should consider upgrading. | -| 7.30-7.51 | **GPP module** | The [GPP module](/dev-docs/modules/consentManagementGpp.html) reads the GPP string from a compliant CMP and passes to compliant bid adapters. Not many bid adapters supported GPP in earlier versions. | -| 7.52-8.1 | GPP module
**Activity Controls** | [Activity Controls](/dev-docs/activity-controls.html) provide the ability for publishers to allow or restrict certain privacy-sensitive activities for particular bidders and modules. See examples in that document for supporting CCPA directly. | -| 8.2-8.x | GPP module
Activity Controls
**USNat module** | The [USNat module](/dev-docs/modules/gppControl_usnat.html) processes SID 7. | -| After 8.x | GPP module
Activity Controls
USNat module
**US State module** | The US State module processes SIDs 8 through 12 after normalizing protocol differences. | -| After 8.10 | **GPP Module** | The [GPP module](/dev-docs/modules/consentManagementGpp.html) now understands GPP 1.1 which makes it incompatible with GPP 1.0. Publishers **MUST** upgrade for continued GPP support. | +| 7.30-7.51 | **Consent Mgmt GPP module** | The [GPP module](/dev-docs/modules/consentManagementGpp.html) reads the GPP string from a compliant CMP and passes to compliant bid adapters. Not many bid adapters supported GPP in earlier versions. | +| 7.52-8.1 | Consent Mgmt GPP module
**Activity Controls** | [Activity Controls](/dev-docs/activity-controls.html) provide the ability for publishers to allow or restrict certain privacy-sensitive activities for particular bidders and modules. See examples in that document for supporting CCPA directly. | +| 8.2-8.9 | Consent Mgmt GPP module
Activity Controls
**GPP USNat module** | The [GPP USNat module](/dev-docs/modules/gppControl_usnat.html) processes SID 7. | +| 8.10+ | Consent Mgmt GPP module
Activity Controls
USNat module
**GPP US State module** | The [GPP US State module](/dev-docs/modules/gppControl_usstates.html) processes SIDs 8 through 12 after normalizing protocol differences. | +| 8.10+ | **Consent Mgmt GPP module** | The [GPP module](/dev-docs/modules/consentManagementGpp.html) now understands GPP 1.1 which makes it incompatible with GPP 1.0. Publishers **MUST** upgrade for continued GPP support. | ### Prebid Server diff --git a/identity/sharedid.md b/identity/sharedid.md index cd25557eac..78c7acc23c 100644 --- a/identity/sharedid.md +++ b/identity/sharedid.md @@ -6,11 +6,10 @@ sidebarType: 9 --- # Prebid SharedID - {: .no_toc} - TOC - {:toc} +{:toc} {: .alert.alert-warning :} As of Prebid.js 5.0, PubCommon ID is no longer supported -- it's been merged into SharedId. Also, SharedId no longer syncs to sharedid.org like it did in Prebid.js 4.x. @@ -157,7 +156,7 @@ You can find available configuration options for the SharedID module [here](http There are several privacy scenarios in which a user ID is not created or read: 1. The User ID module suppresses all cookie reading and setting activity - when the [GDPR Enforcement Module](/dev-docs/modules/gdprEnforcement.html) is in place and there's no consent for Purpose 1. + when the [TCF Control Module](/dev-docs/modules/tcfControl.html) is in place and there's no consent for Purpose 1. 2. The User ID module infrastructure supports a first-party opt-out, by setting the `_pbjs_id_optout` cookie or local storage to any value. No other cookies will be set if this one is set. 3. The SharedId module will suppress the ID when the COPPA flag is set. @@ -217,7 +216,7 @@ Below are the available configuration options for the PubCID script. | create | boolean | If true, then an id is created automatically by the script if it's missing. Default is true. If your server has a component that generates the id instead, then this should be set to false | | `true` | | expInterval | decimal | Expiration interval in minutes. Default is 525600, or 1 year | | `525600` | | extend | boolean | If true, the the expiration time is automatically extended whenever the script is executed even if the id exists already. Default is true. If false, then the id expires from the time it was initially created. | For publisher server support only. If true, the publisher's server will create the (pubcid) cookie. Default is true. | `true` | -| pixelUrl | string (optional) | For publisher server support only. Where to call out to for a server cookie. | | `/wp-json/pubcid/v1/extend/` +| pixelUrl | string (optional) | For publisher server support only. Where to call out to for a server cookie. | | `/wp-json/pubcid/v1/extend/` | | type | string | Type of storage. It's possible to specify one of the following: 'html5', 'cookie'. Default is 'html5' priority, aka local storage, and fall back to cookie if local storage is unavailable. | If true, the expiration time of the stored IDs will be refreshed during each page load. Default is false. | `cookie` | #### Example Configurations diff --git a/prebid-server/developers/add-a-module.md b/prebid-server/developers/add-a-module.md index c6263e096b..010e7cbc2d 100644 --- a/prebid-server/developers/add-a-module.md +++ b/prebid-server/developers/add-a-module.md @@ -2,7 +2,6 @@ layout: page_v2 sidebarType: 5 title: Prebid Server | Developers | Adding a Module - --- # Prebid Server - Adding a Module @@ -11,7 +10,7 @@ title: Prebid Server | Developers | Adding a Module This document guides you through the process of developing a module for host companies to plug into their instance of Prebid Server. We encourage you to look at existing modules for working examples. You can also ask us questions by [submitting a GitHub issue](https://github.com/prebid/prebid-server/issues/new). -* TOC +- TOC {:toc } ## Overview @@ -142,6 +141,7 @@ to the PBS host company. Examples: If your module either utilizes or supplies user-level data like User First Party Data or precise geographic information, it must adhere to the framework supplied by the [Activity Controls](/prebid-server/features/pbs-activitycontrols.html). For instance: + - if your module is going to supply user-level data (e.g. "job title") to bid adapters, it must check permissions for the `enrichUfpd` activity. - if your module is going to forward the entire ORTB request to an endpoint, it must check the `transmitUfpd` and `transmitPreciseGeo` activity permissions. @@ -173,7 +173,7 @@ The details of the implementation depend on the platform. Other rules for open source PBS pull request: - Unit test coverage must exceed 90%. -- A maintainer email address must be provided and be a group, not an individual. e.g. "support@example.com rather than jsmith@example.com +- A maintainer email address must be provided and be a group, not an individual. e.g. rather than ### 10. Write the Module Documentation @@ -184,7 +184,7 @@ create a file in /prebid-server/pbs-modules. You can start by copying one of the - Prerequisites: any necessary account activation, other required modules, etc. - Configuration: both init and runtime - Analytics Tag support -- Privacy Support: disclose whether the module has user privacy implications and support for TCF-EU, TCF-CA, CCPA, MSPA, etc. +- Privacy Support: disclose whether the module has user privacy implications and support for TCF-EU, TCF-CA, CCPA, etc. ### 11. Submit the Pull Requests diff --git a/prebid-server/developers/add-new-bidder-go.md b/prebid-server/developers/add-new-bidder-go.md index e2bcf0c114..a7b395f972 100644 --- a/prebid-server/developers/add-new-bidder-go.md +++ b/prebid-server/developers/add-new-bidder-go.md @@ -29,6 +29,8 @@ Bid adapters are responsible for translating a 'Prebid-flavored' OpenRTB Bid Req OpenRTB Bid Requests contain one or more impression objects, each representing a single ad placement. An impression may define multiple sizes and/or multiple ad formats. If your bidding server limits requests to a single ad placement, size, or format, then your adapter will need to split the impression into multiple calls and merge the responses. +See the [example auction request](/prebid-server/endpoints/openrtb2/auction-request-example.html) to get an idea for what your adapter will receive. + ## Plan Your Bid Adapter The job of your bid adapter is to adapt. You'll need to think about currency, floors, mediatypes, and other details as noted below. diff --git a/prebid-server/developers/add-new-bidder-java.md b/prebid-server/developers/add-new-bidder-java.md index a0c4da4e79..0c9d06e2a5 100644 --- a/prebid-server/developers/add-new-bidder-java.md +++ b/prebid-server/developers/add-new-bidder-java.md @@ -29,6 +29,8 @@ Bid adapters are responsible for translating a 'Prebid-flavored' OpenRTB Bid Req OpenRTB Bid Requests contain one or more impression objects, each representing a single ad placement. An impression may define multiple sizes and/or multiple ad formats. If your bidding server limits requests to a single ad placement, size, or format, then your adapter will need to split the impression into multiple calls and merge the responses. +See the [example auction request](/prebid-server/endpoints/openrtb2/auction-request-example.html) to get an idea for what your adapter will receive. + ## Plan Your Bid Adapter ### Choose A Name diff --git a/prebid-server/developers/module-atags.md b/prebid-server/developers/module-atags.md index f855805fc3..d30754dfc3 100644 --- a/prebid-server/developers/module-atags.md +++ b/prebid-server/developers/module-atags.md @@ -8,29 +8,30 @@ sidebar_entry: /prebid-server/developers/add-a-module.html # Prebid Server - Module Analytics Tags Conventions {: .no_toc} -* TOC +- TOC {:toc } ## Overview -Analytics Tags (aka ‘ATags’) are a log mechanism provided by PBS-core to allow modules +Analytics Tags (aka ‘aTags’) are a log mechanism provided by PBS-core to allow modules to inform analytics adapters about what happened in the request. Use of the Analytics Tag structure is completely optional. It's meant to be used when there are application or reporting reasons for sharing module results. See the [Prebid Server module overview](/prebid-server/developers/add-a-module.html) for background information. This document defines a convention aimed at allowing module developers to create -consistent ATags that can be easily read by analytics adapters. +consistent aTags that can be easily read by analytics adapters. -![Prebid Server ATags](/assets/images/prebid-server/module-atags.png){:class="pb-xlg-img"} +![Prebid Server aTags](/assets/images/prebid-server/module-atags.png){:class="pb-xlg-img"} -1. Modules may return a data structure containing ATags to PBS-Core. -2. PBS-Core adds any ATags to the 'invocation context' data structure. +1. Modules may return a data structure containing aTags to PBS-Core. +2. PBS-Core adds any aTags to the 'invocation context' data structure. 3. Analytics modules have access to the invocation context. ## Analytics Tag Conventions -The general idea is that ATags are a list of module-specific "activities" that have these attributes: +The general idea is that aTags are a list of module-specific "activities" that have these attributes: + - activity name: should be unique within the context of this module. e.g. 'enrich-request' - an overall status - an array of specific results within the activity @@ -41,7 +42,7 @@ The general idea is that ATags are a list of module-specific "activities" that h Here's an example from the [ORTB2 Blocking module](/prebid-server/pbs-modules/ortb2-blocking.html): -``` +```json [{ // scenario: response from bidderA blocked on badv for imp=1 activities: [{ @@ -71,7 +72,7 @@ Here's an example from the [ORTB2 Blocking module](/prebid-server/pbs-modules/or The following table contains the field conventions. {: .table .table-bordered .table-striped } -| ATag Attr | Required? | Description | Type | +| aTag Attr | Required? | Description | Type | |---+---+---+---| | activities | yes | One or more activities carried out by the module. | array of objects | | activities .name | yes | Name of the activity. Must be documented and unique within the module. | string | @@ -86,10 +87,9 @@ The following table contains the field conventions. | activities. results. appliedto. request | no | The service examined the entire openrtb request object. This is in case the module updated something not adunit-specific. | boolean | | activities. results. appliedto. response | no | The service examined the entire openrtb response object. This is in case the module updated something not adunit-specific. | boolean | - ## Designing Analytics Tags -ATags are for reporting. Start by considering what the module's doing that consumers might want to display. Each processing stage the module operates in may be +aTags are for reporting. Start by considering what the module's doing that consumers might want to display. Each processing stage the module operates in may be reported as a separate activity, or perhaps everything the module does is lumped as one activity. @@ -106,7 +106,7 @@ to report on what percentage of responses from each bidder were being thrown away due to blocking rules. This could have been done by defining a separate 'activity' for each of the 4 types of enforcement, but it was decided to just have one kind of activity ('enforce-blocking') and get the specific details as part of the 'value'. There was no requirement to report on the -outbound part of what the module does, so no ATags are created for that part +outbound part of what the module does, so no aTags are created for that part of the functionality. Once you know what reports are desired, figure out which activity 'results' @@ -123,6 +123,7 @@ Be sure to detail the results in your module documentation so that analytics ada aware of what they can look for. Let them know: + - which activities your module supports - what kind of results to expect - whether the results objects have module-specific `values` @@ -142,7 +143,8 @@ In short, to get analytics tags, you'll need to parse this data structure: Here's an example of the data structured as JSON, though the details of the actual object will differ in PBS-Java and PBS-Go. -``` + +```json "stages": [ { "stage": "raw-auction-request", @@ -227,6 +229,117 @@ of the actual object will differ in PBS-Java and PBS-Go. See the implementation guide for your platform for specific syntax. +## Sending aTags to the client-side + +{: .alert.alert-info :} +PBS-Java only + +The use cases for server-side and client-side analytics are different: + +- Server-side analytics are the only game in town when it comes to App, AMP, DOOH, etc. +- However, when Prebid.js is in use and bidders are split between client-side and server-side, it would be far better if auctions were only logged once. + +This feature allows all relevant data passed to the client from Prebid Server so that client-side analytics can be the one to log the results. +To allow the sharing of these details, there are two conditions: + +1. Server-side account configuration must allow sharing of these details by setting `analytics.allow-client-details: true` +1. The ORTB request must contain `ext.prebid.analytics.options.enableclientdetails: true` + +If both are true, then any and all PBS analytics tags will be copied to the response field ext.prebid.analytics.tags. + +### Client aTag example + +The "pb-ortb-blocking" module at the "processed auction" stage adds the following Analytics Tags (from the ORTB2 blocking module) + +```json +[{ + "activities": [{ + "name": "enforce-blocking", + "status": "success", + "results": [{ + "status": "success-block", + "values": { + "attributes": ["badv"], + "adomain": ["bad.com"] + }, + "appliedto": { + "bidder": "bidderA", + "impids": ["1"] + } + },{ + "status": "success-allow", + "appliedto": { + "bidder": "bidderA", + "impids": ["2","3","4"] + } + }] + }] + +Also, the "vendorA-brand-safety" module at the "all processed bid responses" stage adds these aTags: + +```json +[{ + "activities": [{ + "name": "brand-safety", + "status": "success", + "results": [{ + "status": "success-allow", + "appliedto": { + "bidder": "bidderA", + "impids": ["1,","2","3","4"] + } + }] + }] +``` + +The resulting response with the request ext.prebid.analytics.options.enableclientdetails: true and config analytics.options.enableclientdetails:true would be: + +```json5 +// this is actually a nested object - but aggregated for readablility +"ext.prebid.analytics.tags": [{ + "stage": "processed-auction-request", + "module": "pb-ortb-blocking", + "analyticstags": [{ + "activities": [{ + "name": "enforce-blocking", + "status": "success", + "results": [{ + "status": "success-block", + "values": { + "attributes": ["badv"], + "adomain": ["bad.com"] + }, + "appliedto": { + "bidder": "bidderA", + "impids": ["1"] + } + },{ + "status": "success-allow", + "appliedto": { + "bidder": "bidderA", + "impids": ["2","3","4"] + } + }] + }] +},{ + "stage": "all-processed-bid-responses", + "module": "vendorA-brand-safety", + "analyticstags": [{ + "activities": [{ + "name": "brand-safety", + "status": "success", + "results": [{ + "status": "success-allow", + "appliedto": { + "bidder": "bidderA", + "impids": ["1,","2","3","4"] + } + }] +}] +``` + +It's up to the client-side analytics adapters to be able to parse the module-specific contents of the aTags. + ## Further Reading - [PBS Module Overview](/prebid-server/developers/add-a-module.html) diff --git a/prebid-server/developers/pbs-cookie-sync.md b/prebid-server/developers/pbs-cookie-sync.md index 96bcb5e483..fa178b4be4 100644 --- a/prebid-server/developers/pbs-cookie-sync.md +++ b/prebid-server/developers/pbs-cookie-sync.md @@ -33,73 +33,116 @@ Here's how these IDs get placed in the cookie from Prebid.js: ![Prebid Server Cookie Sync](/assets/images/prebid-server/pbs-cookie-sync.png){:class="pb-lg-img"} -1. Prebid.js starts by calling the Prebid Server [`/cookie_sync`](/prebid-server/endpoints/pbs-endpoint-cookieSync.html), letting it know which server-side bidders will be participating in the header bidding auction. +1. When the [s2sConfig](/dev-docs/modules/prebidServer.html) is set, Prebid.js initiates a call to the Prebid Server [`/cookie_sync`](/prebid-server/endpoints/pbs-endpoint-cookieSync.html), letting it know which server-side bidders will be participating in the header bidding auction. - ```text +```text POST https://prebid-server.example.com/cookie_sync {"bidders":["bidderA","bidderB"], "gdpr":1, "gdpr_consent":"...", "us_privacy": "..."} - ``` +``` +{:start="2"} 2. If privacy regulations allow, Prebid Server will look at the `uids` cookie in the host domain and determine whether any bidders are missing or need to be refreshed. It responds with an array of pixel syncs. e.g. - ```javascript +```javascript {"status":"ok","bidder_status":[{"bidder":"bidderA","no_cookie":true,"usersync":{"url":"//biddera.com/getuid?https%3A%2F%2Fprebid-server.example.com%2Fsetuid%3Fbidder%3DbidderA%26gdpr%3D%26gdpr_consent%3D%26us_privacy%3D%26uid%3D%24UID","type":"redirect","supportCORS":false}},{"bidder":"bidderB","no_cookie":true,"usersync":{"url":"https://bidderB.com/u/match?gdpr=&euconsent=&us_privacy=&redir=https%3A%2F%2Fprebid-server.example.com%2Fsetuid%3Fbidder%3DbidderB%26gdpr%3D%26gdpr_consent%3D%26us_privacy%3D%26uid%3D","type":"redirect","supportCORS":false}}]} - ``` +``` -3. When it receives the response, Prebid.js loops through each element of `bidder_status[]`, dropping a pixel for each `bidder_status[].usersync.url`. +{:start="3"} +3. When it receives the response, Prebid.js loops through each element of `bidder_status[]`, creating a pixel for each `bidder_status[].usersync.url`. +{:start="4"} 4. The bidder-specific endpoints read the users' cookie for the bidder's domain and respond with a redirect back to Prebid Server's [`/setuid` endpoint](/prebid-server/endpoints/pbs-endpoint-setuid.html) . This allows that endpoint to read the 3rd party cookie and reflect it back to Prebid Server. Note that if this user doesn't yet have an ID in that 3rd party domain, the sync endpoint is expected to create one. +{:start="5"} 5. When the browser receives this redirect, it contacts Prebid Server, which will once again check the privacy settings and if allowed, update the `uids` cookie. -### Setting the uids cookie from AMP +### Cooperative Syncing + +Prebid Server supports a 'Cooperative Syncing' mode where all enabled bidders may be returned in a sync request even if they aren't on this particular page. This allows bidders to get their IDs in place for the next page where they are utilized. + +Cooperative sync defaults can be configured at the host and account level. See the docs for [PBS-Java](https://github.com/prebid/prebid-server-java/blob/master/docs/config-app.md) and [PBS-Go](https://github.com/prebid/prebid-server/blob/master/config/usersync.go). + +This is how to control the coop syncing behavior from Prebid.js: + +```javascript + pbjs.setConfig({ + s2sConfig: { + ... + coopSync: true, + userSyncLimit: 5 + ... + } + }); +``` + +### Manually initiating a sync -Cookie sync for AMP works in a way quite similar to Prebid.js. +Where Prebid.js isn't present, like on [AMP](/prebid-server/use-cases/pbs-amp.html) pages, the call to [/cookie_sync](/endpoints/pbs-endpoint-cookieSync.html) doesn't happen automatically. +If there are scenarios where Prebid.js isn't around to initiate the /cookie_sync call, publishers can choose to put an iframe on their page. + +This approach works in a way quite similar to Prebid.js except that the [/cookie_sync endpoint](/endpoints/pbs-endpoint-cookieSync.html) is initiated by a separate script that's part of `load-cookie.html'. This file must be placed on a CDN by the publisher's Prebid Server host company. Up until July 2024, the script existed in the [Prebid Universal Creative](https://github.com/prebid/prebid-universal-creative) repository, but has since been moved to the [user-sync](https://github.com/prebid/user-sync) repo. -1. The Prebid Server hosting company places the [load-cookie.html](#manually-initiating-a-sync) file onto a CDN. This script is part of the [Prebid Universal Creative](https://github.com/prebid/prebid-universal-creative/blob/master/src/cookieSync.js) repo. +1. The Prebid Server hosting company places the [load-cookie.html](#manually-initiating-a-sync) file onto a CDN. See [the AMP implementation guide](/dev-docs/show-prebid-ads-on-amp-pages.html#user-sync) for more information. -2. The publisher places the 'load-cookie' iframe into the page: +2. The publisher places a 'load-cookie' iframe into the page: - ```html +For AMP pages: + +```html + src="https://HOST/load-cookie.html?source=amp&endpoint=PBSHOST&max_sync_count=5"> - ``` +``` - {: .alert.alert-info :} - If the publisher has an AMP Consent Management Platform, they should use `load-cookie-with-consent.html`. +On regular web pages: -3. At runtime, the `load-cookie` script just calls the Prebid Server /cookie_sync endpoint. The rest works similar to what's described for Prebid.js above. One difference is that the bidders are not known on the AMP page so those aren't passed. Another difference is that AMP doesn't support iframe syncs, so load-cookie passes instructions to PBS so only pixel syncs are returned. +```html +