From 5b24d26e8a5721fc6a89e9f11f2b4687e4cecc9e Mon Sep 17 00:00:00 2001 From: Demetrio Girardi Date: Mon, 30 Jun 2025 11:46:35 -0700 Subject: [PATCH 1/4] PBJS: new storageControl module docs --- dev-docs/modules/storageControl.md | 122 +++++++++++++++++++++++++++++ 1 file changed, 122 insertions(+) create mode 100644 dev-docs/modules/storageControl.md diff --git a/dev-docs/modules/storageControl.md b/dev-docs/modules/storageControl.md new file mode 100644 index 0000000000..e93cad45b0 --- /dev/null +++ b/dev-docs/modules/storageControl.md @@ -0,0 +1,122 @@ +--- +layout: page_v2 +page_type: module +title: Module - Storage Control +description: Check or enforce disclosure of device storage use +module_code : storageControl +display_name : storageControl +enable_download : true +sidebarType : 1 +--- + +# Storage Control Module + +This module checks other modules' use of device storage against their disclosed list of storage keys and warns about or (optionally) denies undisclosed storage use. +Additionally, it provides an API to list all disclosed storage keys. + +## Background + +The TCF Global Vendor List (GVL) requires vendors to disclose their use of device storage by publishing a [JSON file](https://github.com/InteractiveAdvertisingBureau/GDPR-Transparency-and-Consent-Framework/blob/master/TCFv2/Vendor%20Device%20Storage%20%26%20Operational%20Disclosures.md) that lists all the identifiers (cookie names and/or localStorage keys) and their associated domains. +The Storage Control module uses that information to validate that when a Prebid module accesses storage, it uses identifiers that have been disclosed as in use for first party domains. +Vendors not in the GVL can provide a disclosure JSON to Prebid directly - see [adapter integration](#adapter-integration) below. + +## Publisher Integration + +Include this module in the Prebid bundle: + + ```bash + gulp build --modules=storageControl,... + ``` + +If you are instead using Prebid as an NPM dependency, you'll need to explicitly import disclosure metadata. +This is done by including `metadata/prebid-core` and pairing each module import with a corresponding `import 'prebid.js/metadata/'`. For example: + +```javascript +import {pbjs} from 'prebid.js'; +import 'prebid.js/modules/userId'; +import 'prebid.js/modules/sharedIdSystem'; + +import 'prebid.js/metadata/prebid-core'; +import 'prebid.js/metadata/userId'; +import 'prebid.js/metadata/sharedIdSystem'; + +// ... +``` + +### Module Configuration + +This module exposes a single configuration option `storageControl.enforcement`, e.g.: + +```javascript +pbjs.setConfig({ + storageControl: { + enforcement: 'off' + } +}) +``` + +Possible values for it are: + +{: .table .table-bordered .table-striped } +|Value | Description | +| ------------ | ------------ | +|`'off''` | The default. Use of undisclosed storage keys only generates a console warning. | +|`'strict'` | Deny access to undisclosed storage keys | +|`'allowAliases'` | Deny access to undisclosed storage keys, unless the use is from an alias of a module that does disclose them, in which case only log a warning. This can happen for instance when a bidder provides an alias linked to a different vendor in the GVL. | + +### Storage Disclosure Summary + +With this module included, the `getStorageUseDisclosures` API returns a list of all disclosures pertaining the first party domain for all installed modules. For example: + +```javascript +pbjs.getStorageUseDisclosures() + +/** + [ + { + "disclosedIn": "https://cdn.jsdelivr.net/gh/prebid/Prebid.js/metadata/disclosures/prebid/sharedId-optout.json", + "disclosedBy": [ + "sharedIdSystem" + ], + "identifier": "_pubcid_optout", + "type": "cookie", + "maxAgeSeconds": 31536000, + "cookieRefresh": false, + "purposes": [] + }, + ... + ] + */ +``` + +The return value follows the same format as the TCF [disclosures array](https://github.com/InteractiveAdvertisingBureau/GDPR-Transparency-and-Consent-Framework/blob/master/TCFv2/Vendor%20Device%20Storage%20%26%20Operational%20Disclosures.md), except that + + - `domain`/`domains` is omitted (and always `'*'` in the original disclosure, as Prebid's storage is always on the first party domain); + - each item in the array contains these additional fields: + +{: .table .table-bordered .table-striped } +|Name | Type | Description | +| ------------ | ------------ | ------------ | +|`disclosedIn` | String | URL of the JSON containing this disclosure. Can be `null` for identifiers chosen trough publisher configuration - such as those set by the [userId module](#/dev-docs/modules/userId.html) | +|`disclosedBy` | Array of Strings | Names of the Prebid modules providing this disclosure | + + + +## Adapter Integration + +Modules that use storage should publish a [disclosure file](https://github.com/InteractiveAdvertisingBureau/GDPR-Transparency-and-Consent-Framework/blob/master/TCFv2/Vendor%20Device%20Storage%20%26%20Operational%20Disclosures.md) listing all keys that the pass to `storageManager` for the first party domain (`'*'`). This can be done by either: + + - providing a GVL ID in your adapter. The corresponding `deviceStorageDisclosureUrl` from the GVL is then used as your disclosure. + - providing a `disclosureURL` directly. This does not require membership in the GVL, and overrides its disclosure if provided. For example: + +```javascript +registerBidder({ + code: 'exampleBidder', + disclosureURL: 'https://exampleBidder.com/disclosures.json' +}) +``` + +## Related Reading + +- [Vendor Device Storage & Operational Disclosures](https://github.com/InteractiveAdvertisingBureau/GDPR-Transparency-and-Consent-Framework/blob/master/TCFv2/Vendor%20Device%20Storage%20%26%20Operational%20Disclosures.md) +- [Consent string and vendor list formats](https://github.com/InteractiveAdvertisingBureau/GDPR-Transparency-and-Consent-Framework/blob/master/TCFv2/IAB%20Tech%20Lab%20-%20Consent%20string%20and%20vendor%20list%20formats%20v2.md) From 431b4efd2d5904cbee44a2a5b70f22b48d4b8c67 Mon Sep 17 00:00:00 2001 From: Demetrio Girardi Date: Mon, 30 Jun 2025 11:50:41 -0700 Subject: [PATCH 2/4] Fix lint --- dev-docs/modules/storageControl.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/dev-docs/modules/storageControl.md b/dev-docs/modules/storageControl.md index e93cad45b0..9873829127 100644 --- a/dev-docs/modules/storageControl.md +++ b/dev-docs/modules/storageControl.md @@ -91,13 +91,13 @@ pbjs.getStorageUseDisclosures() The return value follows the same format as the TCF [disclosures array](https://github.com/InteractiveAdvertisingBureau/GDPR-Transparency-and-Consent-Framework/blob/master/TCFv2/Vendor%20Device%20Storage%20%26%20Operational%20Disclosures.md), except that - - `domain`/`domains` is omitted (and always `'*'` in the original disclosure, as Prebid's storage is always on the first party domain); - - each item in the array contains these additional fields: +- `domain`/`domains` is omitted (and always `'*'` in the original disclosure, as Prebid's storage is always on the first party domain); +- each item in the array contains these additional fields: {: .table .table-bordered .table-striped } |Name | Type | Description | | ------------ | ------------ | ------------ | -|`disclosedIn` | String | URL of the JSON containing this disclosure. Can be `null` for identifiers chosen trough publisher configuration - such as those set by the [userId module](#/dev-docs/modules/userId.html) | +|`disclosedIn` | String | URL of the JSON containing this disclosure. Can be `null` for identifiers chosen trough publisher configuration - such as those set by the [userId module](/dev-docs/modules/userId.html) | |`disclosedBy` | Array of Strings | Names of the Prebid modules providing this disclosure | @@ -106,8 +106,8 @@ The return value follows the same format as the TCF [disclosures array](https:// Modules that use storage should publish a [disclosure file](https://github.com/InteractiveAdvertisingBureau/GDPR-Transparency-and-Consent-Framework/blob/master/TCFv2/Vendor%20Device%20Storage%20%26%20Operational%20Disclosures.md) listing all keys that the pass to `storageManager` for the first party domain (`'*'`). This can be done by either: - - providing a GVL ID in your adapter. The corresponding `deviceStorageDisclosureUrl` from the GVL is then used as your disclosure. - - providing a `disclosureURL` directly. This does not require membership in the GVL, and overrides its disclosure if provided. For example: +- providing a GVL ID in your adapter. The corresponding `deviceStorageDisclosureUrl` from the GVL is then used as your disclosure. +- providing a `disclosureURL` directly. This does not require membership in the GVL, and overrides its disclosure if provided. For example: ```javascript registerBidder({ From e987d14af324d28a5324ac956054541edf215c35 Mon Sep 17 00:00:00 2001 From: Demetrio Girardi Date: Tue, 15 Jul 2025 12:26:32 -0700 Subject: [PATCH 3/4] set recommended flag --- dev-docs/modules/storageControl.md | 1 + 1 file changed, 1 insertion(+) diff --git a/dev-docs/modules/storageControl.md b/dev-docs/modules/storageControl.md index 9873829127..d576129d9a 100644 --- a/dev-docs/modules/storageControl.md +++ b/dev-docs/modules/storageControl.md @@ -6,6 +6,7 @@ description: Check or enforce disclosure of device storage use module_code : storageControl display_name : storageControl enable_download : true +recommended: true sidebarType : 1 --- From ddde86c2003dd2651968967a32436b372d5b0721 Mon Sep 17 00:00:00 2001 From: Demetrio Girardi Date: Tue, 15 Jul 2025 12:28:59 -0700 Subject: [PATCH 4/4] add min_js_version --- dev-docs/modules/storageControl.md | 1 + 1 file changed, 1 insertion(+) diff --git a/dev-docs/modules/storageControl.md b/dev-docs/modules/storageControl.md index d576129d9a..9c467841f0 100644 --- a/dev-docs/modules/storageControl.md +++ b/dev-docs/modules/storageControl.md @@ -8,6 +8,7 @@ display_name : storageControl enable_download : true recommended: true sidebarType : 1 +min_js_version: 10.0.0 --- # Storage Control Module