From df216bd0d6ac04342ea20cec54cae7e65d76d1c8 Mon Sep 17 00:00:00 2001 From: Jason Snellbaker Date: Fri, 2 Mar 2018 15:25:36 -0500 Subject: [PATCH 1/9] initial commit for gdpr module docs --- dev-docs/modules/consentManagement.md | 125 ++++++++++++++++++++++++++ dev-docs/modules/index.md | 1 + 2 files changed, 126 insertions(+) create mode 100644 dev-docs/modules/consentManagement.md diff --git a/dev-docs/modules/consentManagement.md b/dev-docs/modules/consentManagement.md new file mode 100644 index 0000000000..8ea56f012a --- /dev/null +++ b/dev-docs/modules/consentManagement.md @@ -0,0 +1,125 @@ +--- +layout: page +title: Module - GDPR ConsentManagement +description: User ID persisted in first party domain +top_nav_section: dev_docs +nav_section: modules +module_code : consentManagement +display_name : GDPR ConsentManagement +--- + +
+ +# GDPR ConsentManagement Module +{:.no_toc} + +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 will perform its tasks with the CMP prior to the auction starting. A rough synopsis of this interaction process would be: + +1. Fetch the user's encoded consent string from the CMP. +2. If this request doesn't return a string, we assume this is a new-user and is undergoing the consent process. We will wait for a signal from the CMP that the consent has finished and perform the lookup again. +3. With a valid consent string, we will incorporate this data into the auction objects (for adapters to collect) and then allow the auction to proceed. + +There are timeout settings in place in the module to permit this interaction with the CMP a specified length of time to operate before it's unacceptable or assumed an issue has occurred. + +When this timeout occurs, one of two options are taken, either: + +1. The auction is canceled outright +2. The auction proceeds without the user's consent information. + +Though these options are mutually exclusive, they are configurable by the site with 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 (as decided by the site's developers). + + +## Page integration + +To utilize this module, a separate CMP needs to be implemented onto the site to interact with the user and obtain their consent choices. + +The actual implementation details of this CMP is 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. + +The module currently supports the following CMPs: + +* IAB (iab) + +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. + +{: .table .table-bordered .table-striped } +| Param | Type | Description | Example | +| --- | --- | --- | --- | +| cmp | `string` | The ID for the CMP in use on the page. Default is 'iab' | 'iab' | +| waitForConsentTimeout | `integer` | Length of time (in milliseconds) to allow the CMP to perform its tasks before aborting the process. Default is 5000 | 5000 | +| lookUpFailureResolution | `string` | A setting to determine what will happen when obtaining consent information from the CMP fails; to either **cancel** the auction entirely or **proceed** with the auction minus the user's encoded consent string. Default is 'proceed' | 'proceed' or 'cancel' | + +Example: Using IAB CMP with a custom timeout value and cancel option. + +{% highlight js %} + var pbjs = pbjs || {}; + pbjs.que = pbjs.que || []; + pbjs.que.push(function() { + pbjs.setConfig({ + consentManagement: { + cmp: 'iab', + waitForConsentTimeout: 4000, + lookUpFailureResolution: 'cancel' + } + }); + pbjs.addAdUnits(adUnits); + }); +{% endhighlight %} + +### Build the package + +#### Step 1: Bundle the module code + +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: + +{% 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 + +Adapters should look for `bidderRequest.gdprConsent` in buildRequests() method. + +{% highlight js %} +{ + "bidderCode": "appnexus", + "auctionId": "e3a336ad-2761-4a1c-b421-ecc7c5294a34", + "bidderRequestId": "14c4ede8c693f", + "bids": [ + { + "bidder": "appnexus", + "params": { + "placementId": "10433394" + }, + "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==", + "consentRequired": true + }, + "start": 1520001292884, + "doneCbCallCount": 0 +} +{% endhighlight %} + + +## Technical Details + +- + +
diff --git a/dev-docs/modules/index.md b/dev-docs/modules/index.md index 54813a62e4..d97711f3d6 100644 --- a/dev-docs/modules/index.md +++ b/dev-docs/modules/index.md @@ -39,6 +39,7 @@ If you are looking for bidder adapter parameters, see [Bidders' Params]({{site.b | [**Server-to-Server Testing**]({{site.baseurl}}/dev-docs/modules/s2sTesting.html) | Adds A/B test support for easing into server-side header bidding. | | [**DFP Video**]({{site.baseurl}}/dev-docs/modules/dfp_video.html) | Required for serving instream video through DFP. | | [**Publisher Common ID**]({{site.baseurl}}/dev-docs/modules/pubCommonId.html) | Adds a persisted user ID in the publisher's domain. | +| [**GDPR ConsentManagement**]({{site.baseurl}}/dev-docs/modules/consentManagement.html) | Facilitates collecting/passing consent information in support of the GDPR regulation. | ## Further Reading From 8b9b01a06f4097804ebeac896a952ec51299b6cc Mon Sep 17 00:00:00 2001 From: Jason Snellbaker Date: Fri, 23 Mar 2018 10:18:06 -0400 Subject: [PATCH 2/9] updated module syntax examples as well as compliant adapter table & logic --- dev-docs/bidders/appnexus.md | 1 + dev-docs/bidders/prebidServer.md | 1 + dev-docs/modules/consentManagement.md | 47 +++++++++++++++++---------- dev-docs/modules/index.md | 2 +- 4 files changed, 33 insertions(+), 18 deletions(-) diff --git a/dev-docs/bidders/appnexus.md b/dev-docs/bidders/appnexus.md index 9ab7a68f26..5669a9d3c3 100644 --- a/dev-docs/bidders/appnexus.md +++ b/dev-docs/bidders/appnexus.md @@ -8,6 +8,7 @@ biddercode: appnexus biddercode_longer_than_12: false hide: true prebid_1_0_supported : true +gdpr_supported: true --- **Table of Contents** diff --git a/dev-docs/bidders/prebidServer.md b/dev-docs/bidders/prebidServer.md index 7ac24c2b7d..c131631b93 100644 --- a/dev-docs/bidders/prebidServer.md +++ b/dev-docs/bidders/prebidServer.md @@ -8,6 +8,7 @@ biddercode: prebidServer biddercode_longer_than_12: true hide: true prebid_1_0_supported : true +gdpr_supported: true --- ### Sign up diff --git a/dev-docs/modules/consentManagement.md b/dev-docs/modules/consentManagement.md index 8ea56f012a..68e7cacb82 100644 --- a/dev-docs/modules/consentManagement.md +++ b/dev-docs/modules/consentManagement.md @@ -23,34 +23,34 @@ This module will perform its tasks with the CMP prior to the auction starting. There are timeout settings in place in the module to permit this interaction with the CMP a specified length of time to operate before it's unacceptable or assumed an issue has occurred. -When this timeout occurs, one of two options are taken, either: +When this timeout occurs one of two options are taken, either: -1. The auction is canceled outright +1. The auction is canceled outright. 2. The auction proceeds without the user's consent information. -Though these options are mutually exclusive, they are configurable by the site with 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 (as decided by the site's developers). +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. ## Page integration To utilize this module, a separate CMP needs to be implemented onto the site to interact with the user and obtain their consent choices. -The actual implementation details of this CMP is 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. +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. The module currently supports the following CMPs: -* IAB (iab) +* AppNexus (appnexus) 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. {: .table .table-bordered .table-striped } | Param | Type | Description | Example | | --- | --- | --- | --- | -| cmp | `string` | The ID for the CMP in use on the page. Default is 'iab' | 'iab' | -| waitForConsentTimeout | `integer` | Length of time (in milliseconds) to allow the CMP to perform its tasks before aborting the process. Default is 5000 | 5000 | -| lookUpFailureResolution | `string` | A setting to determine what will happen when obtaining consent information from the CMP fails; to either **cancel** the auction entirely or **proceed** with the auction minus the user's encoded consent string. Default is 'proceed' | 'proceed' or 'cancel' | +| cmp | `string` | The ID for the CMP in use on the page. Default is 'appnexus' | 'appnexus' | +| 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|false | -Example: Using IAB CMP with a custom timeout value and cancel option. +Example: Using AppNexus CMP with a custom timeout value and cancel option. {% highlight js %} var pbjs = pbjs || {}; @@ -58,9 +58,9 @@ Example: Using IAB CMP with a custom timeout value and cancel option. pbjs.que.push(function() { pbjs.setConfig({ consentManagement: { - cmp: 'iab', - waitForConsentTimeout: 4000, - lookUpFailureResolution: 'cancel' + cmp: 'appnexus', + timeout: 8000, + allowAuctionWithoutConsent: false } }); pbjs.addAdUnits(adUnits); @@ -85,7 +85,7 @@ Note that there are more dynamic ways of combining these components for publishe ## Adapter integration -Adapters should look for `bidderRequest.gdprConsent` in buildRequests() method. +Adapters should look for `bidderRequest.gdprConsent` in their buildRequests() method. {% highlight js %} { @@ -117,9 +117,22 @@ Adapters should look for `bidderRequest.gdprConsent` in buildRequests() method. } {% endhighlight %} - -## Technical Details - -- +{% assign bidder_pages = site.pages | where: "layout", "bidder" %} + + + +Below is a list of supported Adapters: +
+{% for page in bidder_pages %} +
+ {{ page.title }} +
+{% endfor %} +
diff --git a/dev-docs/modules/index.md b/dev-docs/modules/index.md index d97711f3d6..f326ef829f 100644 --- a/dev-docs/modules/index.md +++ b/dev-docs/modules/index.md @@ -39,7 +39,7 @@ If you are looking for bidder adapter parameters, see [Bidders' Params]({{site.b | [**Server-to-Server Testing**]({{site.baseurl}}/dev-docs/modules/s2sTesting.html) | Adds A/B test support for easing into server-side header bidding. | | [**DFP Video**]({{site.baseurl}}/dev-docs/modules/dfp_video.html) | Required for serving instream video through DFP. | | [**Publisher Common ID**]({{site.baseurl}}/dev-docs/modules/pubCommonId.html) | Adds a persisted user ID in the publisher's domain. | -| [**GDPR ConsentManagement**]({{site.baseurl}}/dev-docs/modules/consentManagement.html) | Facilitates collecting/passing consent information in support of the GDPR regulation. | +| [**GDPR ConsentManagement**]({{site.baseurl}}/dev-docs/modules/consentManagement.html) | Facilitates collecting/passing consent information in support of the EU GDPR. | ## Further Reading From 915f05172dcaaa7a610ba4101bd29e60521d697b Mon Sep 17 00:00:00 2001 From: Jason Snellbaker Date: Tue, 27 Mar 2018 14:51:00 -0400 Subject: [PATCH 3/9] adding consentRequired field to module page --- dev-docs/modules/consentManagement.md | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/dev-docs/modules/consentManagement.md b/dev-docs/modules/consentManagement.md index 68e7cacb82..be2eeb851a 100644 --- a/dev-docs/modules/consentManagement.md +++ b/dev-docs/modules/consentManagement.md @@ -47,10 +47,13 @@ Once the CMP is implemented, simply include the module in your build and add a c | Param | Type | Description | Example | | --- | --- | --- | --- | | cmp | `string` | The ID for the CMP in use on the page. Default is 'appnexus' | 'appnexus' | +| consentRequired | `boolean` | An override type setting to indicate if GDPR consent is required or not. Default is true* | true|false | | 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|false | -Example: Using AppNexus CMP with a custom timeout value and cancel option. +* Note - There are some technologies to determine if a given request is in scope of GDPR or not. While this technology is not part of the consentManagement module (nor prebid), some adapters may have this technology available. If they do, they have the opportunity to set their own default value for the consentRequired field instead of using the module's default. If you are using a GDPR supported adapter that has this capability, simply do **not** include this field in your config to let the corresponding adapter(s) set their value. All other adapters will use the system default (true), to err on the side that consent was likely required. + +Example: AppNexus CMP using the custom timeout and cancel auction options with the consentRequired field not defined. {% highlight js %} var pbjs = pbjs || {}; From d8ad66465bcf8944fe24d2f947479e0f461522c2 Mon Sep 17 00:00:00 2001 From: Jason Snellbaker Date: Wed, 4 Apr 2018 12:41:59 -0400 Subject: [PATCH 4/9] updated adapter integration section --- dev-docs/modules/consentManagement.md | 36 ++++++++++++++++++++++++--- 1 file changed, 32 insertions(+), 4 deletions(-) diff --git a/dev-docs/modules/consentManagement.md b/dev-docs/modules/consentManagement.md index be2eeb851a..f19f59193a 100644 --- a/dev-docs/modules/consentManagement.md +++ b/dev-docs/modules/consentManagement.md @@ -23,7 +23,7 @@ This module will perform its tasks with the CMP prior to the auction starting. There are timeout settings in place in the module to permit this interaction with the CMP a specified length of time to operate before it's unacceptable or assumed an issue has occurred. -When this timeout occurs one of two options are taken, either: +When either this timeout occurs or if an error from the CMP is thrown, one of two options are taken; either: 1. The auction is canceled outright. 2. The auction proceeds without the user's consent information. @@ -51,7 +51,7 @@ Once the CMP is implemented, simply include the module in your build and add a c | 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|false | -* Note - There are some technologies to determine if a given request is in scope of GDPR or not. While this technology is not part of the consentManagement module (nor prebid), some adapters may have this technology available. If they do, they have the opportunity to set their own default value for the consentRequired field instead of using the module's default. If you are using a GDPR supported adapter that has this capability, simply do **not** include this field in your config to let the corresponding adapter(s) set their value. All other adapters will use the system default (true), to err on the side that consent was likely required. +* Note - There are some technologies to determine if a given request is in scope of GDPR or not. While this technology is not part of the consentManagement module (nor prebid), some adapters may have this technology available. If they do, they have the opportunity to set their own default value for the consentRequired field instead of using the module's default. If you are using a GDPR supported adapter that has this capability, simply do **not** include this field in your config to let the corresponding adapter(s) set their value. Example: AppNexus CMP using the custom timeout and cancel auction options with the consentRequired field not defined. @@ -88,7 +88,8 @@ Note that there are more dynamic ways of combining these components for publishe ## Adapter integration -Adapters should look for `bidderRequest.gdprConsent` in their buildRequests() method. +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: {% highlight js %} { @@ -120,6 +121,33 @@ Adapters should look for `bidderRequest.gdprConsent` in their buildRequests() me } {% endhighlight %} +As described earlier in this page - if the publisher didn't set their own value for `consentRequired` in the prebid `setConfig` code, 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: + +- Set a hardcoded default value. +- Using their own system, derive if 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: + +{% highlight js %} +... +buildRequests: function (bidRequests, bidderRequest) { + ... + if (bidderRequest && bidderRequest.gdprConsent) { + adapterRequest.gdpr_consent = { + consent_string: bidderRequest.gdprConsent.consentString, + consent_required: (typeof bidderRequest.gdprConsent.consentRequired === 'boolean') ? bidderRequest.gdprConsent.consentRequired : true + } + } + ... +} +... +{% 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.consentRequired` field is undefined and if so, set the derived value. + +If neither option are taken, then there is a chance this field's value will be undefined on certain requests. As long as that acceptable, this could be a potential third option - though we recommend to set a default at that point. + {% assign bidder_pages = site.pages | where: "layout", "bidder" %} -Below is a list of supported Adapters: +Below is a list of Adapters that support GDPR:
{% for page in bidder_pages %}
From 566ab6e8231697976164cc5732df055dcc008eb6 Mon Sep 17 00:00:00 2001 From: Jason Snellbaker Date: Wed, 4 Apr 2018 13:16:57 -0400 Subject: [PATCH 5/9] further revisions to Adapter Integration section --- dev-docs/modules/consentManagement.md | 22 ++++++++++++++-------- 1 file changed, 14 insertions(+), 8 deletions(-) diff --git a/dev-docs/modules/consentManagement.md b/dev-docs/modules/consentManagement.md index f19f59193a..209c62ad75 100644 --- a/dev-docs/modules/consentManagement.md +++ b/dev-docs/modules/consentManagement.md @@ -46,12 +46,12 @@ Once the CMP is implemented, simply include the module in your build and add a c {: .table .table-bordered .table-striped } | Param | Type | Description | Example | | --- | --- | --- | --- | -| cmp | `string` | The ID for the CMP in use on the page. Default is 'appnexus' | 'appnexus' | -| consentRequired | `boolean` | An override type setting to indicate if GDPR consent is required or not. Default is true* | true|false | -| 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|false | +| cmp | `string` | The ID for the CMP in use on the page. Default is `'appnexus'` | `'appnexus'` | +| consentRequired | `boolean` | An override type setting to indicate if GDPR consent is required or not. See note in regards to default. | `true` or `false` | +| 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` | -* Note - There are some technologies to determine if a given request is in scope of GDPR or not. While this technology is not part of the consentManagement module (nor prebid), some adapters may have this technology available. If they do, they have the opportunity to set their own default value for the consentRequired field instead of using the module's default. If you are using a GDPR supported adapter that has this capability, simply do **not** include this field in your config to let the corresponding adapter(s) set their value. +* Note - There are some technologies to determine if a given request is in scope of GDPR or not. While this technology is not part of the consentManagement module (nor prebid), some adapters may have this technology available. If they do, they have the opportunity to set their own default value for the `consentRequired` field. If you are using a GDPR supported adapter that has this capability, simply do **not** include this field in your config to let the corresponding adapter(s) set their value. Example: AppNexus CMP using the custom timeout and cancel auction options with the consentRequired field not defined. @@ -70,7 +70,7 @@ Example: AppNexus CMP using the custom timeout and cancel auction options with t }); {% endhighlight %} -### Build the package +## Build the package #### Step 1: Bundle the module code @@ -121,6 +121,12 @@ Below is a sample of how the data is structured in the `bidderRequest` object: } {% endhighlight %} +### Notes about 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. + +#### *consentRequired* As described earlier in this page - if the publisher didn't set their own value for `consentRequired` in the prebid `setConfig` code, 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: @@ -144,9 +150,9 @@ 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.consentRequired` field is undefined and if so, set the derived value. +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.consentRequired` field is undefined and if so, set the derived value from your independent system. Otherwise, you would use the publisher's value that was set in the `bidderRequest.gdprConsent.consentRequired` field. -If neither option are taken, then there is a chance this field's value will be undefined on certain requests. As long as that acceptable, this could be a potential third option - though we recommend to set a default at that point. +If neither option are taken, then there is a chance this field's value will be undefined on certain requests. As long as that acceptable, this could be a potential third option. {% assign bidder_pages = site.pages | where: "layout", "bidder" %} From b24dfb8d6cfb73996c60fc57994895d3e4a95af0 Mon Sep 17 00:00:00 2001 From: Jason Snellbaker Date: Wed, 11 Apr 2018 10:31:09 -0400 Subject: [PATCH 6/9] pending release comments added --- dev-docs/modules/consentManagement.md | 3 +++ 1 file changed, 3 insertions(+) diff --git a/dev-docs/modules/consentManagement.md b/dev-docs/modules/consentManagement.md index 209c62ad75..a87d6eb941 100644 --- a/dev-docs/modules/consentManagement.md +++ b/dev-docs/modules/consentManagement.md @@ -10,6 +10,9 @@ display_name : GDPR ConsentManagement
+## PENDING RELEASE +This module is still considered under development, but the core logic and integration steps documented here will very likely remain as described. + # GDPR ConsentManagement Module {:.no_toc} From e5e928e91b0818ce2c52956c52a4b9ebf9db3cb8 Mon Sep 17 00:00:00 2001 From: Jason Snellbaker Date: Wed, 11 Apr 2018 11:16:52 -0400 Subject: [PATCH 7/9] updated description and added comment in code snippet --- dev-docs/modules/consentManagement.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/dev-docs/modules/consentManagement.md b/dev-docs/modules/consentManagement.md index a87d6eb941..51c0f41af4 100644 --- a/dev-docs/modules/consentManagement.md +++ b/dev-docs/modules/consentManagement.md @@ -1,7 +1,7 @@ --- layout: page title: Module - GDPR ConsentManagement -description: User ID persisted in first party domain +description: Manage consent data in support of EU GDPR top_nav_section: dev_docs nav_section: modules module_code : consentManagement @@ -145,6 +145,7 @@ buildRequests: function (bidRequests, bidderRequest) { if (bidderRequest && bidderRequest.gdprConsent) { adapterRequest.gdpr_consent = { consent_string: bidderRequest.gdprConsent.consentString, + // will check if the consentRequired field was populated with a boolean value (ie from page config). If it's undefined, then default to true consent_required: (typeof bidderRequest.gdprConsent.consentRequired === 'boolean') ? bidderRequest.gdprConsent.consentRequired : true } } From 48dc6c8031dcbaa97d95858c53a32a82086dac71 Mon Sep 17 00:00:00 2001 From: Jason Snellbaker Date: Wed, 11 Apr 2018 11:19:10 -0400 Subject: [PATCH 8/9] fixing description update --- dev-docs/modules/consentManagement.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/dev-docs/modules/consentManagement.md b/dev-docs/modules/consentManagement.md index 51c0f41af4..9575768172 100644 --- a/dev-docs/modules/consentManagement.md +++ b/dev-docs/modules/consentManagement.md @@ -1,7 +1,7 @@ --- layout: page title: Module - GDPR ConsentManagement -description: Manage consent data in support of EU GDPR +description: Add on module to consume and distribute consent information to bidder adapters top_nav_section: dev_docs nav_section: modules module_code : consentManagement From 4d233577e609cd749fa68c650a3cf453b382033e Mon Sep 17 00:00:00 2001 From: Jason Snellbaker Date: Mon, 16 Apr 2018 09:32:12 -0400 Subject: [PATCH 9/9] updated module page based on feedback --- dev-docs/modules/consentManagement.md | 17 +++++++---------- 1 file changed, 7 insertions(+), 10 deletions(-) diff --git a/dev-docs/modules/consentManagement.md b/dev-docs/modules/consentManagement.md index 9575768172..47a39edf42 100644 --- a/dev-docs/modules/consentManagement.md +++ b/dev-docs/modules/consentManagement.md @@ -21,8 +21,7 @@ Designed to support the EU General Data Protection Regulation ([GDPR](https://ww This module will perform its tasks with the CMP prior to the auction starting. A rough synopsis of this interaction process would be: 1. Fetch the user's encoded consent string from the CMP. -2. If this request doesn't return a string, we assume this is a new-user and is undergoing the consent process. We will wait for a signal from the CMP that the consent has finished and perform the lookup again. -3. With a valid consent string, we will incorporate this data into the auction objects (for adapters to collect) and then allow the auction to proceed. +2. With a valid consent string, we will incorporate this data into the auction objects (for adapters to collect) and then allow the auction to proceed. There are timeout settings in place in the module to permit this interaction with the CMP a specified length of time to operate before it's unacceptable or assumed an issue has occurred. @@ -40,21 +39,19 @@ To utilize this module, a separate CMP needs to be implemented onto the site to 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. -The module currently supports the following CMPs: +The module currently supports any CMP that conforms to the IAB standard ([more info here](https://github.com/InteractiveAdvertisingBureau/GDPR-Transparency-and-Consent-Framework)). -* AppNexus (appnexus) - -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 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. {: .table .table-bordered .table-striped } | Param | Type | Description | Example | | --- | --- | --- | --- | -| cmp | `string` | The ID for the CMP in use on the page. Default is `'appnexus'` | `'appnexus'` | +| cmpApi | `string` | The ID for the CMP in use on the page. Default is `'iab'` | `'iab'` | | consentRequired | `boolean` | An override type setting to indicate if GDPR consent is required or not. See note in regards to default. | `true` or `false` | -| timeout | `integer` | Length of time (in milliseconds) to allow the CMP to perform its tasks before aborting the process. Default is `10000` | `10000` | +| timeout | `integer` | Length of time (in milliseconds) to allow the CMP to perform its tasks before aborting the process. Default is `500` | `500` | | 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` | -* Note - There are some technologies to determine if a given request is in scope of GDPR or not. While this technology is not part of the consentManagement module (nor prebid), some adapters may have this technology available. If they do, they have the opportunity to set their own default value for the `consentRequired` field. If you are using a GDPR supported adapter that has this capability, simply do **not** include this field in your config to let the corresponding adapter(s) set their value. +* Note - Some SSPs can determine whether a given request is in GDPR scope or not. If the page specifies `consentRequired`, it will override any dynamic determination and force the bidders to use this override value -- i.e. tell the SSP whether the consent string must be enforced for this user. Each bidder adapter supporting GDPR will default to the proper setting for the backend SSP, so it's not recommended to set this value unless override is what's desired. Example: AppNexus CMP using the custom timeout and cancel auction options with the consentRequired field not defined. @@ -65,7 +62,7 @@ Example: AppNexus CMP using the custom timeout and cancel auction options with t pbjs.setConfig({ consentManagement: { cmp: 'appnexus', - timeout: 8000, + timeout: 1000, allowAuctionWithoutConsent: false } });