From 406d09361bd7f2fc2bebbe4148e63c2b4a1d63b0 Mon Sep 17 00:00:00 2001 From: Bret Gorsline Date: Tue, 26 Nov 2019 20:33:01 -0500 Subject: [PATCH 1/5] CCPA docs --- _data/sidebar.yml | 4 +- dev-docs/bidders/proxistoreBidAdapter.md | 1 + dev-docs/modules/consentManagement.md | 207 ++++++++++++++--------- dev-docs/modules/index.md | 2 +- 4 files changed, 128 insertions(+), 86 deletions(-) diff --git a/_data/sidebar.yml b/_data/sidebar.yml index 5ec558ff9b..d840f82c73 100644 --- a/_data/sidebar.yml +++ b/_data/sidebar.yml @@ -416,7 +416,7 @@ subgroup: 5 - sbSecId: 1 - title: GPDR Consent Management + title: Consent Management link: /dev-docs/modules/consentManagement.html isHeader: 0 isSectionHeader: 0 @@ -1780,4 +1780,4 @@ isHeader: 0 isSectionHeader: 0 sectionTitle: - subgroup: 0 \ No newline at end of file + subgroup: 0 diff --git a/dev-docs/bidders/proxistoreBidAdapter.md b/dev-docs/bidders/proxistoreBidAdapter.md index 2e7245ebfc..a61b7f925a 100644 --- a/dev-docs/bidders/proxistoreBidAdapter.md +++ b/dev-docs/bidders/proxistoreBidAdapter.md @@ -1,5 +1,6 @@ --- layout: bidder +title: Proxistore description: Prebid Proxistore Bidder Adapter hide: true biddercode: proxistore diff --git a/dev-docs/modules/consentManagement.md b/dev-docs/modules/consentManagement.md index ae095ab832..c1083ea8f0 100644 --- a/dev-docs/modules/consentManagement.md +++ b/dev-docs/modules/consentManagement.md @@ -1,63 +1,73 @@ --- layout: page_v2 page_type: module -title: Module - GDPR ConsentManagement +title: Module - Consent Management description: Add on module to consume and distribute consent information to bidder adapters module_code : consentManagement -display_name : GDPR ConsentManagement +display_name : Consent Management enable_download : true sidebarType : 1 --- - - -# GDPR ConsentManagement Module +# Consent Management Module {: .no_toc } * TOC {: toc } -## Summary & Purpose +## Overview -Designed to support the EU General Data Protection Regulation ([GDPR](https://www.eugdpr.org/)), this module works with supported Consent Management Platforms (CMPs) to fetch an encoded string representing the user's consent choices and make it available for adapters to consume and process. +This module is designed to support the following privacy regulations: -This module will perform its tasks with the CMP prior to the auction starting. A rough synopsis of this interaction process would be: +- EU General Data Protection Regulation ([GDPR](https://www.iab.com/topics/consumer-privacy/gdpr/)), +- California Consumer Privacy Act ([CCPA](https://www.iab.com/guidelines/ccpa-framework/)). The IAB has generalized this to cover future regulations, referring to their feature as 'US Privacy'. -1. Fetch the user's consent data from the CMP (see note below regarding a workflow variance for new users). -2. With a valid set of consent information, we will incorporate this data into the auction objects (for adapters to collect) and then allow the auction to proceed. +It works with supported Consent Management Platforms (CMPs) to fetch an encoded string representing the user's consent choices and make it available for adapters to consume and process. -Note - In the the case of a new user, the CMP will respond only once there is consent information available; ie the user picked their consent choices. Given this can take some time for the average user, coupled into the module is a timeout setting. -For those unfamiliar with this timeout setting in place, the CMP will be permitted a specified amount of time to operate before it's deemed unacceptable or it's assumed an issue has occurred. +{: .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. +In otherwords, **we recommend consulting with legal counsel before determining how to utilize these features in support of your overall privacy approach.** -When either this timeout occurs or if an error from the CMP is thrown, one of two options are taken; either: +A summary of the interaction process: -1. The auction is canceled outright. -2. The auction proceeds without the user's consent information. +1. Fetch the user's GDPR and/or US-Privacy(CCPA) consent data from the CMP. +2. Incorporate this data into the auction objects for adapters to collect +3. Proceed with the auction -Though these options are mutually exclusive, they are configurable by the publisher via the site's implementation of the prebid code (see further below for details) so that they can be used in the proper scenarios for that site/audience. +In the the case of a new user, CMPs will generally respond only once there is consent information available; ie the user picked their consent choices. +Given that this can take some time for the average user, the module provides timeout settings. -{: .alert.alert-warning :} -Any Prebid functionality created to address regulatory requirements (e.g. the GDPR) does not replace each party's independent responsibility to determine its own legal obligations and comply with all applicable laws. +If the timeout occurs or if an error from the CMP is thrown, one of these things occurs: -## Page integration +1. The auction is canceled outright. (configurable for GDPR only) +2. The auction proceeds without the user's consent information. -To utilize this module, a separate CMP needs to be implemented onto the site to interact with the user and obtain their consent choices. +## Page Integration -The actual implementation details of this CMP are not covered by this page; any questions on that implemenation should be referred to the CMP in question. However, we would recommend to have the CMP's code located before the prebid code in the head of the page, in order to ensure their framework is implemented before the prebid code starts to execute. +To utilize this module, a CMP compatible with the [IAB 1.1 TCF spec](https://github.com/InteractiveAdvertisingBureau/GDPR-Transparency-and-Consent-Framework) needs to be implemented onto the site to interact with the user and obtain their consent choices. -The module currently supports any CMP that conforms to the IAB standard for the 1.1 CMP spec ([more info here](https://github.com/InteractiveAdvertisingBureau/GDPR-Transparency-and-Consent-Framework)). +Though implementation details for the CMP are not covered by Prebid.org, we do recommend to that the CMP's code be located before the Prebid.js code in the head of the page, in order to ensure their framework is loaded before the Prebid code executes. -Once the CMP is implemented, simply include the module in your build and add a `consentManagement` object in the `setConfig()` call. Adapters that support this feature will be able to retrieve the consent information and incorporate it in their requests. +Once the CMP is implemented, simply include this module into your build and add a `consentManagement` object in the `setConfig()` call. Adapters that support this feature will then be able to retrieve the consent information and incorporate it in their requests. Here are the parameters supported in the `consentManagement` object: {: .table .table-bordered .table-striped } | Param | Type | Description | Example | | --- | --- | --- | --- | -| cmpApi | `string` | The ID for the CMP in use on the page. Default is `'iab'` | `'iab', 'static'` | -| timeout | `integer` | Length of time (in milliseconds) to allow the CMP to perform its tasks before aborting the process. Default is `10000` | `10000` | -| allowAuctionWithoutConsent | `boolean` | A setting to determine what will happen when obtaining consent information from the CMP fails; either allow the auction to proceed (**true**) or cancel the auction (**false**). Default is `true` | `true` or `false` | -| consentData | `Object` | A Object representing the consentData being passed directly, only in used when cmpApi is 'static'. Default is `undefined`. Example see the tests for consentManagement. | | +| cmpApi | `string` | Which CMP interface is in use. Supported values are **'iab'** or **'static'**. Static allows integrations where IAB-formatted consent strings are provided in a non-standard way. Default is `'iab'`. | `'iab'` | +| consentAPIs | `array of strings` | Defines which IAB privacy APIs to look for. Possible values are ['gdpr', 'usp']. The default is ['gdpr']. | `['gdpr']` | +| timeout | `integer` | Length of time (in milliseconds) to allow the CMP to obtain the GDPR consent string. Default is `10000` | `10000` | +| uspTimeout | `integer` | Length of time (in milliseconds) to allow the CMP to obtain the US-Privacy consent string. Default is `50` | `50` | +| allowAuctionWithoutConsent | `boolean` | GDPR only: determines what will happen when obtaining consent information from the CMP fails; either allow the auction to proceed (**true**) or cancel the auction (**false**). Default is `true` | `true` or `false` | +| consentData | `Object` | An object representing the GDPR consent data being passed directly, only in used when cmpApi is 'static'. Default is `undefined`. Not currently supported for US Privacy. | | -Example: IAB CMP using the custom timeout and cancel auction options. +{: .alert.alert-info :} +Note that the `allowAuctionWithoutConsent` option really should be named `allowAuctionWithoutConsentString`. +Prebid.js does not parse either GDPR or US-Privacy strings, so doesn't know if the user has consented +to any particular action. + +### GDPR Examples + +Example 1: GDPR IAB CMP using custom timeout and cancel-auction options. {% highlight js %} var pbjs = pbjs || {}; @@ -74,7 +84,7 @@ Example: IAB CMP using the custom timeout and cancel auction options. }); {% endhighlight %} -Example: Static CMP using custom data passing. +Example 2: Static CMP using custom data passing. {% highlight js %} var pbjs = pbjs || {}; @@ -93,8 +103,6 @@ Example: Static CMP using custom data passing. getVendorConsents: { 'metadata': 'BOOgjO9OOgjO9APABAENAi-AAAAWd7_______9____7_9uz_Gv_r_ff_3nW0739P1A_r_Oz_rm_-zzV44_lpQQRCEA', ... - ... - ... } } } @@ -103,35 +111,49 @@ Example: Static CMP using custom data passing. }); {% endhighlight %} -The consentData object can be retrieved by a existing CMP by calling +### US-Privacy Examples + +Example 1: Support both US-Privacy and GDPR {% highlight js %} -window.__cmp('getConsentData', null, function(result ) { }); -window.__cmp('getVendorConsents', null, function(result ) { }); +pbjs.setConfig({ + consentManagement: { + cmpApi: 'iab', + consentAPIs: ['gdpr', 'usp'], + allowAuctionWithoutConsent: false, // suppress auctions if there's no GDPR consent string + timeout: 3000, // GDPR timeout 3000ms + uspTimeout: 100 // US-Privacy timeout 100ms + } +}); {% endhighlight %} +Example 1: Support US-Privacy -## Build the package +{% highlight js %} +pbjs.setConfig({ + consentManagement: { + cmpApi: 'iab', + consentAPIs: ['usp'], + uspTimeout: 100 // US-Privacy timeout 100ms + } +}); +{% endhighlight %} -#### Step 1: Bundle the module code +## Build the package -Follow the basic build instructions on the GitHub repo's main README. To include the module, an additional option must be added to the the gulp build command: +Follow the basic build instructions on the GitHub repo's main [README](https://github.com/prebid/Prebid.js/blob/master/README.md). To include the module, an additional option must be added to the the gulp build command: {% highlight bash %} gulp build --modules=consentManagement,bidAdapter1,bidAdapter2 {% endhighlight %} -#### Step 2: Publish the package(s) to the CDN - -After testing, get your javascript file(s) out to your Content Delivery Network (CDN) as normal. - -Note that there are more dynamic ways of combining these components for publishers or integrators ready to build a more advanced infrastructure. - ## Adapter Integration -_Note - for any adapters submitting changes to support this approach, please also submit a PR to the [docs repo](https://github.com/prebid/prebid.github.io) to add a `gdpr_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 have your adapter's name automatically appear on the list of adapters supporting GDPR (at the bottom of this page)._ +_Note - for any adapters submitting changes to support this approach, please also submit a PR to the [docs repo](https://github.com/prebid/prebid.github.io) to add `gdpr_supported: true` and/or `usp_supported: true` variables to your respective page in the [bidders directory](https://github.com/prebid/prebid.github.io/tree/master/dev-docs/bidders). This will have your adapter's name automatically appear on the list of adapters supporting GDPR and US Privacy._ + +### Bidder Adapter Integration -### BuildRequests Integration +#### GDPR Integration To find the GDPR consent information to pass along to your system, adapters should look for the `bidderRequest.gdprConsent` field in their buildRequests() method. Below is a sample of how the data is structured in the `bidderRequest` object: @@ -140,34 +162,18 @@ Below is a sample of how the data is structured in the `bidderRequest` object: { "bidderCode": "appnexus", "auctionId": "e3a336ad-2761-4a1c-b421-ecc7c5294a34", - "bidderRequestId": "14c4ede8c693f", - "bids": [ - { - "bidder": "appnexus", - "params": { - "placementId": "13144370" - }, - "adUnitCode": "ad-unit-code", - "transactionId": "0e8c6732-0999-4ca8-b44f-8fe514f53cc3", - "sizes": [[300, 250], [300, 600]], - "bidId": "2e6fe30b22b4fc", - "bidderRequestId": "14c4ede8c693f", - "auctionId": "e3a336ad-2761-4a1c-b421-ecc7c5294a34" - } - ], - "auctionStart": 1520001292880, + ... "timeout": 3000, "gdprConsent": { "consentString": "BOJ/P2HOJ/P2HABABMAAAAAZ+A==", "vendorData": {...}, "gdprApplies": true }, - "start": 1520001292884, - "doneCbCallCount": 0 + ... } {% endhighlight %} -#### **Notes about the data fields** +**Notes about the data fields** **_consentString_** @@ -207,27 +213,35 @@ The implementation of the latter option is up to the adapter, but the general pr If neither option are taken, then there is the remote chance this field's value will be undefined. As long as that acceptable, this could be a potential third option. +#### US-Privacy Integration + +To find the US-Privacy/CCPA consent information to pass along to your system, adapters should look for the +`bidderRequest.us_privacy` field in their buildRequests() method. +Below is a sample of how the data is structured in the `bidderRequest` object: + +{% highlight js %} +{ + "bidderCode": "appnexus", + "auctionId": "e3a336ad-2761-4a1c-b421-ecc7c5294a34", + ... + "us_privacy": "1YYY", + ... +} +{% endhighlight %} + ### UserSync Integration -The `gdprConsent` object is also available when registering `userSync` pixels. The object can be accessed by including it as an argument in the `getUserSyncs` function in the following manner: +The `gdprConsent` and `usPrivacy` objects are also available when registering `userSync` pixels. +The object can be accessed by including it as an argument in the `getUserSyncs` function in the following manner: {% highlight js %} -getUserSyncs: function(syncOptions, responses, gdprConsent) { +getUserSyncs: function(syncOptions, responses, gdprConsent, usPrivacy) { ... } {% endhighlight %} Depending on your needs, you could potentially either include the consent information in a query of your pixel and/or given the consent choices determine if you should drop the pixels at all. -{% assign bidder_pages = site.pages | where: "layout", "bidder" %} - - - ## Publishers not using an IAB-Compliant CMP Prebid.js and much of the ad industry rely on the IAB CMP standard for GDPR support, but there are some publishers who may have @@ -323,15 +337,42 @@ This should be false if there was some error in the consent data, true otherwise **cmpLoaded** This should be be set to true once parameters above are processed. -## List of Adapters That Currently Support GDPR +## Adapters Supporting Privacy Regulations + + -Below is a list of Adapters that currently support GDPR: -
-{% for page in bidder_pages %} -
- {{ page.title }} -
+ +### Adapters supporting GDPR +
+
- +### Adapters supporting US-Privacy +
+ +
diff --git a/dev-docs/modules/index.md b/dev-docs/modules/index.md index 0b0344fb5a..045c75d70c 100644 --- a/dev-docs/modules/index.md +++ b/dev-docs/modules/index.md @@ -31,7 +31,7 @@ If you are looking for bidder adapter parameters, see [Bidders' Params]({{site.b | Module | Description | |---------------------+--------------| | [**Currency**](/dev-docs/modules/currency.html) | Converts bid currency into ad server currency based on data in a supplied exchange rate file. | -| [**GDPR ConsentManagement**](/dev-docs/modules/consentManagement.html) | Facilitates collecting/passing consent information in support of the EU GDPR. | +| [**ConsentManagement**](/dev-docs/modules/consentManagement.html) | Facilitates collecting/passing consent information in support of privacy regulations: EU GDPR and US Privacy (CCPA). | | [**Google Ad Manager Express**](/dev-docs/modules/dfp_express.html) | A simplified installation mechanism for publishers that have Google Publisher Tag (GPT) ad calls in their pages. | | [**Supply Chain Object**](/dev-docs/modules/schain.html) | Validates and makes the Supply Object available to bidders | | [**User ID**](/dev-docs/modules/userId.html) | Sub-modules are available to support a range of identification approaches: Criteo RTUS, DigiTrust, ID5 Universal ID, IdentityLink, PubCommon ID, and Unified ID. | From e7674415b3af96c08cb14baac53e39d6e94b2337 Mon Sep 17 00:00:00 2001 From: Jean Stemp Date: Tue, 3 Dec 2019 11:55:00 -0800 Subject: [PATCH 2/5] a few edits --- dev-docs/modules/consentManagement.md | 151 +++++++++++++------------- 1 file changed, 77 insertions(+), 74 deletions(-) diff --git a/dev-docs/modules/consentManagement.md b/dev-docs/modules/consentManagement.md index c1083ea8f0..cfb40a9088 100644 --- a/dev-docs/modules/consentManagement.md +++ b/dev-docs/modules/consentManagement.md @@ -17,53 +17,53 @@ sidebarType : 1 ## Overview -This module is designed to support the following privacy regulations: +This consent management module is designed to support the following privacy regulations: -- EU General Data Protection Regulation ([GDPR](https://www.iab.com/topics/consumer-privacy/gdpr/)), -- California Consumer Privacy Act ([CCPA](https://www.iab.com/guidelines/ccpa-framework/)). The IAB has generalized this to cover future regulations, referring to their feature as 'US Privacy'. +- EU General Data Protection Regulation ([GDPR](https://www.iab.com/topics/consumer-privacy/gdpr/)) +- 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." -It works with supported Consent Management Platforms (CMPs) to fetch an encoded string representing the user's consent choices and make it available for adapters to consume and process. +This module works with supported [Consent Management Platforms](https://advertisingconsent.eu/cmp-list/) (CMPs) to fetch an encoded string representing the user's consent choices and make it available for adapters to consume and process. {: .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. -In otherwords, **we recommend consulting with legal counsel before determining how to utilize these features in support of your overall privacy approach.** +**We recommend consulting with your legal counsel before determining how to utilize these features in support of your overall privacy approach.** -A summary of the interaction process: +Here's a summary of the interaction process: -1. Fetch the user's GDPR and/or US-Privacy(CCPA) consent data from the CMP. -2. Incorporate this data into the auction objects for adapters to collect -3. Proceed with the auction +1. Fetch the user's GDPR and/or US Privacy (CCPA) consent data from the CMP. +2. Incorporate this data into the auction objects for adapters to collect. +3. Proceed with the auction. -In the the case of a new user, CMPs will generally respond only once there is consent information available; ie the user picked their consent choices. -Given that this can take some time for the average user, the module provides timeout settings. +In the the case of a new user, CMPs will generally respond only after there is consent information available (i.e., the user has made their consent choices). +Making these selections can take some time for the average user, so the module provides timeout settings. -If the timeout occurs or if an error from the CMP is thrown, one of these things occurs: +If the timeout period expires or an error from the CMP is thrown, one of these actions occurs: -1. The auction is canceled outright. (configurable for GDPR only) +1. The auction is canceled outright. (Configurable only for GDPR.) 2. The auction proceeds without the user's consent information. ## Page Integration -To utilize this module, a CMP compatible with the [IAB 1.1 TCF spec](https://github.com/InteractiveAdvertisingBureau/GDPR-Transparency-and-Consent-Framework) needs to be implemented onto the site to interact with the user and obtain their consent choices. +To utilize this module, a CMP compatible with the [IAB 1.1 TCF spec](https://iabeurope.eu/tcf-v1/) needs to be implemented onto the site to interact with the user and obtain their consent choices. -Though implementation details for the CMP are not covered by Prebid.org, we do recommend to that the CMP's code be located before the Prebid.js code in the head of the page, in order to ensure their framework is loaded before the Prebid code executes. +Though implementation details for the CMP are not covered by Prebid.org, we do recommend to that you place the CMP code before the Prebid.js code in the head of the page in order to ensure the CMP's framework is loaded before the Prebid code executes. -Once the CMP is implemented, simply include this module into your build and add a `consentManagement` object in the `setConfig()` call. Adapters that support this feature will then be able to retrieve the consent information and incorporate it in their requests. Here are the parameters supported in the `consentManagement` object: +Once the CMP is implemented, simply include this module into your build and add a `consentManagement` object in the `setConfig()` call. Adapters that support this feature will then be able to retrieve the consent information and incorporate it in their requests. + +Here are the parameters supported in the `consentManagement` object: {: .table .table-bordered .table-striped } | Param | Type | Description | Example | | --- | --- | --- | --- | -| cmpApi | `string` | Which CMP interface is in use. Supported values are **'iab'** or **'static'**. Static allows integrations where IAB-formatted consent strings are provided in a non-standard way. Default is `'iab'`. | `'iab'` | -| consentAPIs | `array of strings` | Defines which IAB privacy APIs to look for. Possible values are ['gdpr', 'usp']. The default is ['gdpr']. | `['gdpr']` | -| timeout | `integer` | Length of time (in milliseconds) to allow the CMP to obtain the GDPR consent string. Default is `10000` | `10000` | -| uspTimeout | `integer` | Length of time (in milliseconds) to allow the CMP to obtain the US-Privacy consent string. Default is `50` | `50` | -| allowAuctionWithoutConsent | `boolean` | GDPR only: determines what will happen when obtaining consent information from the CMP fails; either allow the auction to proceed (**true**) or cancel the auction (**false**). Default is `true` | `true` or `false` | -| consentData | `Object` | An object representing the GDPR consent data being passed directly, only in used when cmpApi is 'static'. Default is `undefined`. Not currently supported for US Privacy. | | +| cmpApi | `string` | The CMP interface that is in use. Supported values are **'iab'** or **'static'**. Static allows integrations where IAB-formatted consent strings are provided in a non-standard way. Default is `'iab'`. | `'iab'` | +| consentAPIs | `array of strings` | Defines which IAB privacy APIs to look for. Possible values are `['gdpr', 'usp']`. The default is `['gdpr']`. | `['gdpr']` | +| timeout | `integer` | Length of time (in milliseconds) to allow the CMP to obtain the GDPR consent string. Default is `10000`. | `10000` | +| uspTimeout | `integer` | Length of time (in milliseconds) to allow the CMP to obtain the US Privacy consent string. Default is `50`. | `50` | +| allowAuctionWithoutConsent | `boolean` | GDPR only. Determines what will happen if obtaining consent information from the CMP fails; either allow the auction to proceed (`true`) or cancel the auction (`false`). Default is `true` | `true` | +| consentData | `Object` | An object representing the GDPR consent data being passed directly; only used when cmpApi is 'static'. Default is `undefined`. Not currently supported for US Privacy. | | {: .alert.alert-info :} -Note that the `allowAuctionWithoutConsent` option really should be named `allowAuctionWithoutConsentString`. -Prebid.js does not parse either GDPR or US-Privacy strings, so doesn't know if the user has consented -to any particular action. +Note that the `allowAuctionWithoutConsent` parameter refers to the entire consent string, not to any individual consent option. Prebid.js does not parse either GDPR or US Privacy strings, so it doesn't know if the user has consented to any particular action. ### GDPR Examples @@ -111,9 +111,9 @@ Example 2: Static CMP using custom data passing. }); {% endhighlight %} -### US-Privacy Examples +### US Privacy Examples -Example 1: Support both US-Privacy and GDPR +Example 1: Support both US Privacy and GDPR {% highlight js %} pbjs.setConfig({ @@ -122,26 +122,26 @@ pbjs.setConfig({ consentAPIs: ['gdpr', 'usp'], allowAuctionWithoutConsent: false, // suppress auctions if there's no GDPR consent string timeout: 3000, // GDPR timeout 3000ms - uspTimeout: 100 // US-Privacy timeout 100ms + uspTimeout: 100 // US Privacy timeout 100ms } }); {% endhighlight %} -Example 1: Support US-Privacy +Example 2: Support US Privacy {% highlight js %} pbjs.setConfig({ consentManagement: { cmpApi: 'iab', consentAPIs: ['usp'], - uspTimeout: 100 // US-Privacy timeout 100ms + uspTimeout: 100 // US Privacy timeout 100ms } }); {% endhighlight %} -## Build the package +## Build the Package -Follow the basic build instructions on the GitHub repo's main [README](https://github.com/prebid/Prebid.js/blob/master/README.md). To include the module, an additional option must be added to the the gulp build command: +Follow the basic build instructions on the GitHub Prebid.js repo's main [README](https://github.com/prebid/Prebid.js/blob/master/README.md). To include the consent management module, an additional option must be added to the the gulp build command: {% highlight bash %} gulp build --modules=consentManagement,bidAdapter1,bidAdapter2 @@ -149,19 +149,19 @@ gulp build --modules=consentManagement,bidAdapter1,bidAdapter2 ## Adapter Integration -_Note - for any adapters submitting changes to support this approach, please also submit a PR to the [docs repo](https://github.com/prebid/prebid.github.io) to add `gdpr_supported: true` and/or `usp_supported: true` variables to your respective page in the [bidders directory](https://github.com/prebid/prebid.github.io/tree/master/dev-docs/bidders). This will have your adapter's name automatically appear on the list of adapters supporting GDPR and US Privacy._ +If you are submitting changes to an adapter to support this approach, please also submit a PR to the [docs repo](https://github.com/prebid/prebid.github.io) to add the `gdpr_supported: true` and/or `usp_supported: true` variables 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 GDPR and US Privacy.** ### Bidder Adapter Integration #### GDPR Integration -To find the GDPR consent information to pass along to your system, adapters should look for the `bidderRequest.gdprConsent` field in their buildRequests() method. -Below is a sample of how the data is structured in the `bidderRequest` object: +To find the GDPR consent information to pass along to your system, adapters should look for the `bidderRequest.gdprConsent` field in their `buildRequests()` method. +Here is a sample of how the data is structured in the `bidderRequest` object: {% highlight js %} { "bidderCode": "appnexus", - "auctionId": "e3a336ad-2761-4a1c-b421-ecc7c5294a34", + "auctionId": "e3a336ad-2222-4a1c-bbbb-ecc7c5294a34", ... "timeout": 3000, "gdprConsent": { @@ -173,25 +173,26 @@ Below is a sample of how the data is structured in the `bidderRequest` object: } {% endhighlight %} -**Notes about the data fields** +**gdprConsent Data Fields** **_consentString_** -This field contains the user's choices on consent, represented as an encoded string value. In certain scenarios, this field may come to you with an `undefined` value; normally this happens when there was an error during the CMP interaction and the publisher had the config option `allowAuctionWithoutConsent` set to `true`. If you wish to set your own value for this scenario rather than pass along `undefined` to your system, you can check for the `undefined` value in the field and replace it accordingly. The code sample provided in the *consentRequried* section below provides a possible approach to perform this type of check/replacement. +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 during the CMP interaction and the publisher had the config option `allowAuctionWithoutConsent` set to `true`. 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. **_vendorData_** -This field contains the raw vendor data in relation to the user's choices on consent. This object will contain a map of all available vendors for any potential adapters that may wish to read the data directly. One use-case for reading this data could be if an adapter wished to be omitted in a request if they knew if consent wasn't given for them. Adapters will need to read through the object to find their appropriate information. +This field contains the raw vendor data in relation to the user's choices on consent. This object will hold a map of all available vendors for any potential adapters that want to read the data directly. One use-case for reading from this field would be when an adapter wants to be omitted from a request where they were not given consent. Adapters are able to read through the object to find their appropriate information. **_gdprApplies_** -This boolean represents if the user in question belonged to an area where GDPR applies. This field comes from the CMP itself; it's comes included in the response when a request is made to the CMP API. In the odd chance for some reason this value isn't defined by the CMP, each adapter has the opportunity to set their own value for this field. -There are two general approaches that can be taken by the adapter to populate this field: +This boolean field represents whether the user in question is in an area where GDPR applies. This field comes from the CMP itself; it's comes included in the response when a request is made to the CMP API. On the rare occasion where this value isn't defined by the CMP, each adapter has the opportunity to set their own value for this field. + +One of two general approaches can be taken by the adapter to populate this field: - Set a hardcoded default value. -- Using their own system, derive if consent is required for the end-user and set the value accordingly. +- Use their own system to determine whether consent is required for the end-user and set the value accordingly. -Using the former option, below is an example of how the integration could look: +The folowing is an example of how the integration could look for the former option: {% highlight js %} ... @@ -209,20 +210,19 @@ buildRequests: function (bidRequests, bidderRequest) { ... {% endhighlight %} -The implementation of the latter option is up to the adapter, but the general premise should be the same. You would check to see if the `bidderRequest.gdprConsent.gdprApplies` field is undefined and if so, set the derived value from your independent system. +The implementation of the latter option is up to the adapter, but the general premise is the same. You would check to see if the `bidderRequest.gdprConsent.gdprApplies` field is undefined and if so, set the derived value from your independent system. -If neither option are taken, then there is the remote chance this field's value will be undefined. As long as that acceptable, this could be a potential third option. +If neither option are taken, then there is the remote chance this field's value will be undefined. As long as that's acceptable for the given system, this could be a potential third option. -#### US-Privacy Integration +#### US Privacy Integration -To find the US-Privacy/CCPA consent information to pass along to your system, adapters should look for the -`bidderRequest.us_privacy` field in their buildRequests() method. +To find the US Privacy/CCPA consent information to pass along to your system, adapters should look for the `bidderRequest.us_privacy` field in their buildRequests() method. Below is a sample of how the data is structured in the `bidderRequest` object: {% highlight js %} { "bidderCode": "appnexus", - "auctionId": "e3a336ad-2761-4a1c-b421-ecc7c5294a34", + "auctionId": "e3a336ad-2222-4a1c-bbbb-ecc7c5554a34", ... "us_privacy": "1YYY", ... @@ -232,7 +232,7 @@ Below is a sample of how the data is structured in the `bidderRequest` object: ### UserSync Integration The `gdprConsent` and `usPrivacy` objects are also available when registering `userSync` pixels. -The object can be accessed by including it as an argument in the `getUserSyncs` function in the following manner: +The objects can be accessed by including them as arguments in the `getUserSyncs` function: {% highlight js %} getUserSyncs: function(syncOptions, responses, gdprConsent, usPrivacy) { @@ -240,23 +240,22 @@ getUserSyncs: function(syncOptions, responses, gdprConsent, usPrivacy) { } {% endhighlight %} -Depending on your needs, you could potentially either include the consent information in a query of your pixel and/or given the consent choices determine if you should drop the pixels at all. +Depending on your needs, you could include the consent information in a query of your pixel and/or, given the consent choices, determine if you should drop the pixels at all. ## Publishers not using an IAB-Compliant CMP -Prebid.js and much of the ad industry rely on the IAB CMP standard for GDPR support, but there are some publishers who may have -implemented different approach to meeting the privacy rules. Those publishers may utilize Prebid.js and the whole header bidding ecosystem if they build a translation layer between their consent method and the IAB method. +Prebid.js and much of the ad industry rely on the IAB CMP standard for GDPR support, but there might be some publishers who have implemented a different approach to meeting the privacy rules. Those publishers can utilize Prebid.js and the whole header bidding ecosystem by building a translation layer between their consent method and the IAB method. -At a high level this looks like: -- build a window.__cmp() function which will be seen by Prebid -- build a message receiver function if safeframes are in use -- format consent data in a string according to the [IAB standard](https://github.com/InteractiveAdvertisingBureau/GDPR-Transparency-and-Consent-Framework) +At a high level, this could be done as follows: +- Build a `window.__cmp()` function, which will be seen by Prebid. +- If SafeFrames are in use, build a message receiver function. +- Format consent data in a string according to the [IAB standard](https://github.com/InteractiveAdvertisingBureau/GDPR-Transparency-and-Consent-Framework). -Below is sample code for implementing the stub functions. Sample code for formatting the consent string may be obtained [here](https://github.com/appnexus/cmp). +Below is sample code for implementing the stub functions. Sample code for formatting the consent string can be obtained [here](https://github.com/appnexus/cmp). {% highlight js %} var iabConsentData; // build the IAB consent string -var gdprApplies; // true if gdpr Applies to the user, else false +var gdprApplies; // true if gdpr applies to the user, else false var hasGlobalScope; // true if consent data was retrieved globally var responseCode; // false if there was an error, else true var cmpLoaded; // true if iabConsentData was loaded and processed @@ -319,23 +318,24 @@ var cmpLoaded; // true if iabConsentData was loaded and processed {% endhighlight %} ### Explanation of Parameters -**iabConsentData** -For how to generate the IAB consent string see the [IAB CMP 1.1 Spec](https://github.com/InteractiveAdvertisingBureau/GDPR-Transparency-and-Consent-Framework) and [IAB Consent String SDK](https://github.com/InteractiveAdvertisingBureau/GDPR-Transparency-and-Consent-Framework/tree/master/Consent%20String%20SDK). -**gdprApplies** -How to generate the gdprApplies field: -- True if the current user is in the European Economic Area (EEA) OR if the publisher wants to have all traffic considered in-scope for GDPR -- False if it's known that the user is outside the EEA -- Leave the attribute unspecified if user's location is unknown +**iabConsentData** +For instructions on how to generate the IAB consent string see the [IAB CMP 1.1 Spec](https://github.com/InteractiveAdvertisingBureau/GDPR-Transparency-and-Consent-Framework) and [IAB Consent String SDK](https://github.com/InteractiveAdvertisingBureau/GDPR-Transparency-and-Consent-Framework/tree/master/Consent%20String%20SDK). + +**gdprApplies** +Use the following values in the gdprApplies field: +- True: the current user is in the European Economic Area (EEA) *or* the publisher wants to have all traffic considered in-scope for GDPR. +- False: It's known that the user is outside the EEA. +- Leave the attribute unspecified if user's location is unknown. -**hasGlobalScope** -This should be set as true if consent data was retrieved from global "euconsent" cookie, or was it publisher-specific. For general purpose, set this to false. +**hasGlobalScope** +This should be set to true if consent data was retrieved from global "euconsent" cookie, or it was publisher-specific. For general purpose, set this to false. -**responseCode** -This should be false if there was some error in the consent data, true otherwise. False is the same as calling the callback with no parameters. +**responseCode** +This should be false if there was some error in the consent data; otherwise set to true. False is the same as calling the callback with no parameters. -**cmpLoaded** -This should be be set to true once parameters above are processed. +**cmpLoaded** +This should be be set to true once the parameters listed above are processed. ## Adapters Supporting Privacy Regulations @@ -363,14 +363,17 @@ var idx_usp=0; {% endif %} {% endfor %} -### Adapters supporting GDPR + +### Adapters Supporting GDPR +
-### Adapters supporting US-Privacy +### Adapters Supporting US-Privacy +
-### Adapters Supporting GDPR -
- -### Adapters Supporting US-Privacy - -
- -
diff --git a/dev-docs/modules/consentManagementUsp.md b/dev-docs/modules/consentManagementUsp.md new file mode 100644 index 0000000000..15ab3d643a --- /dev/null +++ b/dev-docs/modules/consentManagementUsp.md @@ -0,0 +1,153 @@ +--- +layout: page_v2 +page_type: module +title: Consent Management - US Privacy +description: Module to consume and distribute US Privacy consent information to bidder adapters +module_code : consentManagementUsp +display_name : Consent Management - US Privacy +enable_download : true +sidebarType : 1 +--- + +# US Privacy Consent Management Module +{: .no_toc } + +* TOC +{: toc } + +## Overview + +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 supported [Consent Management Platforms](https://advertisingconsent.eu/cmp-list/) (CMPs) to fetch an encoded string representing the user's consent choices and make it available for adapters to consume and process. + +{: .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) + +{: .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.** + +Here's a summary of the interaction process: + +1. Fetch the user's US Privacy (CCPA) consent data from the CMP. +2. Incorporate this data into the auction objects for adapters to collect. +3. Proceed with the auction. + +In the the case of a new user, CMPs will generally respond only after there is consent information available (i.e., the user has made their consent choices). +Making these selections can take some time for the average user, so the module provides timeout settings. + +If the timeout period expires or an error from the CMP is thrown, the auction proceeds without the user's consent information. + +## Page Integration + +To utilize this module, a CMP compatible with the [IAB 1.1 TCF spec](https://iabeurope.eu/tcf-v1/) needs to be implemented onthe site to interact with the user and obtain their consent choices. + +Though implementation details for the CMP are not covered by Prebid.org, we do recommend to that you place the CMP code before the Prebid.js code in the head of the page in order to ensure the CMP's framework is loaded before the Prebid code executes. + +Once the CMP is implemented, simply include this module into your build and add a `consentManagement` object in the `setConfig()` call. Adapters that support this feature will then be able to retrieve the consent information and incorporate it in their requests. + +Here are the parameters supported in the `consentManagement` object: + +{: .table .table-bordered .table-striped } +| Param | Type | Description | Example | +| --- | --- | --- | --- | +| usp | object | | | +| usp.cmpApi | `string` | The CMP interface that is in use. The only currently supported value is **'iab'**, which is the default. | `'iab'` | +| usp.timeout | `integer` | Length of time (in milliseconds) to allow the CMP to obtain the GDPR consent string. Default is `10000`. | `10000` | + +### Examples + +Example 1: Support both US Privacy and GDPR + +{% highlight js %} +pbjs.setConfig({ + consentManagement: { + gdpr: { + cmpApi: 'iab', + allowAuctionWithoutConsent: false, // suppress auctions if there's no GDPR consent string + timeout: 3000 // GDPR timeout 3000ms + }, + usp: { + timeout: 100 // US Privacy timeout 100ms + } + } +}); +{% endhighlight %} + +Example 2: Support US Privacy + +{% highlight js %} +pbjs.setConfig({ + consentManagement: { + usp: { + cmpApi: 'iab', + timeout: 100 // US Privacy timeout 100ms + } + } +}); +{% endhighlight %} + +## Build the Package + +Follow the basic build instructions on the GitHub Prebid.js repo's main [README](https://github.com/prebid/Prebid.js/blob/master/README.md). To include the consent management module, an additional option must be added to the the gulp build command: + +{% highlight bash %} +gulp build --modules=consentManagementUsp,bidAdapter1,bidAdapter2 +{% endhighlight %} + +## Adapter Integration + +If you are submitting changes to an adapter to support this approach, please also submit a PR to the [docs repo](https://github.com/prebid/prebid.github.io) to add the `usp_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 US Privacy.** + +### Bidder Adapter US PrivacyIntegration + +To find the US Privacy/CCPA consent information to pass along to your system, adapters should look for the `bidderRequest.uspConsent` field in their buildRequests() method. +Below is a sample of how the data is structured in the `bidderRequest` object: + +{% highlight js %} +{ + "bidderCode": "bidderA", + "auctionId": "e3a336ad-2222-4a1c-bbbb-ecc7c5554a34", + ... + "uspConsent": "1YYY", + ... +} +{% endhighlight %} + +### UserSync Integration + +The `usPrivacy` object is also available when registering `userSync` pixels. +The objects can be accessed by including them as arguments in the `getUserSyncs` function: + +{% highlight js %} +getUserSyncs: function(syncOptions, responses, gdprConsent, usPrivacy) { +... +} +{% endhighlight %} + +Depending on your needs, you could include the consent information in a query of your pixel and/or, given the consent choices, determine if you should drop the pixels at all. + +## Adapters Supporting US Privacy / CCPA + + + + + +
+ +
diff --git a/dev-docs/modules/index.md b/dev-docs/modules/index.md index 045c75d70c..c4f23b331b 100644 --- a/dev-docs/modules/index.md +++ b/dev-docs/modules/index.md @@ -31,7 +31,7 @@ If you are looking for bidder adapter parameters, see [Bidders' Params]({{site.b | Module | Description | |---------------------+--------------| | [**Currency**](/dev-docs/modules/currency.html) | Converts bid currency into ad server currency based on data in a supplied exchange rate file. | -| [**ConsentManagement**](/dev-docs/modules/consentManagement.html) | Facilitates collecting/passing consent information in support of privacy regulations: EU GDPR and US Privacy (CCPA). | +| **ConsentManagement** | Facilitates collecting and passing consent information in support of privacy regulations: [EU GDPR](/dev-docs/modules/consentManagement.html) and [US Privacy](/dev-docs/modules/consentManagementUsp.html) (CCPA). | | [**Google Ad Manager Express**](/dev-docs/modules/dfp_express.html) | A simplified installation mechanism for publishers that have Google Publisher Tag (GPT) ad calls in their pages. | | [**Supply Chain Object**](/dev-docs/modules/schain.html) | Validates and makes the Supply Object available to bidders | | [**User ID**](/dev-docs/modules/userId.html) | Sub-modules are available to support a range of identification approaches: Criteo RTUS, DigiTrust, ID5 Universal ID, IdentityLink, PubCommon ID, and Unified ID. | From f7420259aefb9eefdbf18fec1f6bedd0e7df84ae Mon Sep 17 00:00:00 2001 From: Bret Gorsline Date: Wed, 4 Dec 2019 13:54:02 -0500 Subject: [PATCH 4/5] added usp_supported flag to rubicon --- dev-docs/bidders/rubicon.md | 1 + 1 file changed, 1 insertion(+) diff --git a/dev-docs/bidders/rubicon.md b/dev-docs/bidders/rubicon.md index 61a8bc9945..78fe3a08c2 100644 --- a/dev-docs/bidders/rubicon.md +++ b/dev-docs/bidders/rubicon.md @@ -5,6 +5,7 @@ description: Rubicon Project Prebid Bidder Adaptor hide: true biddercode: rubicon gdpr_supported: true +usp_supported: true coppa_supported: true schain_supported: true media_types: video From 401177b6b5afa59e2233a09cd3d28d87e5b4f127 Mon Sep 17 00:00:00 2001 From: Jean Stemp Date: Wed, 4 Dec 2019 11:11:49 -0800 Subject: [PATCH 5/5] a few more very minor edits --- dev-docs/modules/consentManagement.md | 36 ++++++++++++------------ dev-docs/modules/consentManagementUsp.md | 12 ++++---- 2 files changed, 24 insertions(+), 24 deletions(-) diff --git a/dev-docs/modules/consentManagement.md b/dev-docs/modules/consentManagement.md index 6f527eeb85..110d99f268 100644 --- a/dev-docs/modules/consentManagement.md +++ b/dev-docs/modules/consentManagement.md @@ -39,8 +39,8 @@ Making these selections can take some time for the average user, so the module p If the timeout period expires or an error from the CMP is thrown, one of these actions occurs: -1. The auction is canceled outright. -2. The auction proceeds without the user's consent information. +- The auction is canceled outright. +- The auction proceeds without the user's consent information. ## Page Integration @@ -54,19 +54,19 @@ Here are the parameters supported in the `consentManagement` object: {: .alert.alert-warning :} Note that versions of Prebid.js before 2.43.0 had a different GDPR configuration. The module is backwards-compatible, -but we recommend migrating to the new config structure when possible. +but we recommend migrating to the new config structure as soon as possible. {: .table .table-bordered .table-striped } | Param | Type | Description | Example | | --- | --- | --- | --- | -| gdpr | object | | | +| gdpr | `Object` | | | | gdpr.cmpApi | `string` | The CMP interface that is in use. Supported values are **'iab'** or **'static'**. Static allows integrations where IAB-formatted consent strings are provided in a non-standard way. Default is `'iab'`. | `'iab'` | | gdpr.timeout | `integer` | Length of time (in milliseconds) to allow the CMP to obtain the GDPR consent string. Default is `10000`. | `10000` | | gdpr.allowAuctionWithoutConsent | `boolean` | Determines what will happen if obtaining consent information from the CMP fails; either allow the auction to proceed (`true`) or cancel the auction (`false`). Default is `true` | `true` | | gdpr.consentData | `Object` | An object representing the GDPR consent data being passed directly; only used when cmpApi is 'static'. Default is `undefined`. Not currently supported for US Privacy. | | {: .alert.alert-info :} -Note that the `allowAuctionWithoutConsent` parameter refers to the entire consent string, not to any individual consent option. Prebid.js does not parse the GDPR consent string, so it doesn't know if the user has consented to any particular action. +NOTE: The `allowAuctionWithoutConsent` parameter refers to the entire consent string, not to any individual consent option. Prebid.js does not parse the GDPR consent string, so it doesn't know if the user has consented to any particular action. ### Examples @@ -120,7 +120,7 @@ Example 2: Static CMP using custom data passing. ## Build the Package -Follow the basic build instructions on the GitHub Prebid.js repo's main [README](https://github.com/prebid/Prebid.js/blob/master/README.md). To include the consent management module, an additional option must be added to the gulp build command: +Follow the basic build instructions in the GitHub Prebid.js repo's main [README](https://github.com/prebid/Prebid.js/blob/master/README.md). To include the consent management module, an additional option must be added to the **gulp build** command: {% highlight bash %} gulp build --modules=consentManagement,bidAdapter1,bidAdapter2 @@ -162,7 +162,7 @@ This field contains the raw vendor data in relation to the user's choices on con **_gdprApplies_** -This boolean field represents whether the user in question is in an area where GDPR applies. This field comes from the CMP itself; it's comes included in the response when a request is made to the CMP API. On the rare occasion where this value isn't defined by the CMP, each adapter has the opportunity to set their own value for this field. +This boolean field represents whether the user in question is in an area where GDPR applies. This field comes from the CMP itself; it's included in the response when a request is made to the CMP API. On the rare occasion where this value isn't defined by the CMP, each adapter has the opportunity to set their own value for this field. One of two general approaches can be taken by the adapter to populate this field: @@ -194,7 +194,7 @@ If neither option are taken, then there is the remote chance this field's value ### UserSync Integration The `gdprConsent` object is also available when registering `userSync` pixels. -The objects can be accessed by including them as arguments in the `getUserSyncs` function: +The object can be accessed by including it as an argument in the `getUserSyncs` function: {% highlight js %} getUserSyncs: function(syncOptions, responses, gdprConsent, usPrivacy) { @@ -208,10 +208,10 @@ Depending on your needs, you could include the consent information in a query of Prebid.js and much of the ad industry rely on the IAB CMP standard for GDPR support, but there might be some publishers who have implemented a different approach to meeting the privacy rules. Those publishers can utilize Prebid.js and the whole header bidding ecosystem by building a translation layer between their consent method and the IAB method. -At a high level, this could be done as follows: -- Build a `window.__cmp()` function, which will be seen by Prebid. -- If SafeFrames are in use, build a message receiver function. -- Format consent data in a string according to the [IAB standard](https://github.com/InteractiveAdvertisingBureau/GDPR-Transparency-and-Consent-Framework). +At a high level, this could be done as follows: +1. Build a `window.__cmp()` function, which will be seen by Prebid. +2. If SafeFrames are in use, build a message receiver function. +3. Format consent data in a string according to the [IAB standard](https://github.com/InteractiveAdvertisingBureau/GDPR-Transparency-and-Consent-Framework). Below is sample code for implementing the stub functions. Sample code for formatting the consent string can be obtained [here](https://github.com/appnexus/cmp). @@ -281,22 +281,22 @@ var cmpLoaded; // true if iabConsentData was loaded and processed ### Explanation of Parameters -**iabConsentData** +**_iabConsentData_** For instructions on how to generate the IAB consent string see the [IAB CMP 1.1 Spec](https://github.com/InteractiveAdvertisingBureau/GDPR-Transparency-and-Consent-Framework) and [IAB Consent String SDK](https://github.com/InteractiveAdvertisingBureau/GDPR-Transparency-and-Consent-Framework/tree/master/Consent%20String%20SDK). -**gdprApplies** -Use the following values in the gdprApplies field: +**_gdprApplies_** +Use the following values in the _gdprApplies_ field: - True: the current user is in the European Economic Area (EEA) *or* the publisher wants to have all traffic considered in-scope for GDPR. - False: It's known that the user is outside the EEA. - Leave the attribute unspecified if user's location is unknown. -**hasGlobalScope** +**_hasGlobalScope_** This should be set to true if consent data was retrieved from global "euconsent" cookie, or it was publisher-specific. For general purpose, set this to false. -**responseCode** +**_responseCode_** This should be false if there was some error in the consent data; otherwise set to true. False is the same as calling the callback with no parameters. -**cmpLoaded** +**_cmpLoaded_** This should be be set to true once the parameters listed above are processed. ## Adapters Supporting GDPR diff --git a/dev-docs/modules/consentManagementUsp.md b/dev-docs/modules/consentManagementUsp.md index 15ab3d643a..54fbfeb714 100644 --- a/dev-docs/modules/consentManagementUsp.md +++ b/dev-docs/modules/consentManagementUsp.md @@ -22,7 +22,7 @@ This consent management module is designed to support the California Consumer Pr This module works with supported [Consent Management Platforms](https://advertisingconsent.eu/cmp-list/) (CMPs) to fetch an encoded string representing the user's consent choices and make it available for adapters to consume and process. {: .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 - GDPR Module](/dev-docs/modules/consentManagement.html) for supporting the EU General Data Protection Regulation (GDPR) {: .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. @@ -52,7 +52,7 @@ Here are the parameters supported in the `consentManagement` object: {: .table .table-bordered .table-striped } | Param | Type | Description | Example | | --- | --- | --- | --- | -| usp | object | | | +| usp | `Object` | | | | usp.cmpApi | `string` | The CMP interface that is in use. The only currently supported value is **'iab'**, which is the default. | `'iab'` | | usp.timeout | `integer` | Length of time (in milliseconds) to allow the CMP to obtain the GDPR consent string. Default is `10000`. | `10000` | @@ -90,7 +90,7 @@ pbjs.setConfig({ ## Build the Package -Follow the basic build instructions on the GitHub Prebid.js repo's main [README](https://github.com/prebid/Prebid.js/blob/master/README.md). To include the consent management module, an additional option must be added to the the gulp build command: +Follow the basic build instructions in the GitHub Prebid.js repo's main [README](https://github.com/prebid/Prebid.js/blob/master/README.md). To include the consent management module, an additional option must be added to the the **gulp build** command: {% highlight bash %} gulp build --modules=consentManagementUsp,bidAdapter1,bidAdapter2 @@ -100,9 +100,9 @@ gulp build --modules=consentManagementUsp,bidAdapter1,bidAdapter2 If you are submitting changes to an adapter to support this approach, please also submit a PR to the [docs repo](https://github.com/prebid/prebid.github.io) to add the `usp_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 US Privacy.** -### Bidder Adapter US PrivacyIntegration +### Bidder Adapter US Privacy Integration -To find the US Privacy/CCPA consent information to pass along to your system, adapters should look for the `bidderRequest.uspConsent` field in their buildRequests() method. +To find the US Privacy/CCPA consent information to pass along to your system, adapters should look for the `bidderRequest.uspConsent` field in their `buildRequests()` method. Below is a sample of how the data is structured in the `bidderRequest` object: {% highlight js %} @@ -118,7 +118,7 @@ Below is a sample of how the data is structured in the `bidderRequest` object: ### UserSync Integration The `usPrivacy` object is also available when registering `userSync` pixels. -The objects can be accessed by including them as arguments in the `getUserSyncs` function: +The object can be accessed by including it as an argument in the `getUserSyncs` function: {% highlight js %} getUserSyncs: function(syncOptions, responses, gdprConsent, usPrivacy) {