US Privacy Consent Management Module

• Overview
  • Deletes
• Page Integration
  • Examples
• Build the Package
• Adapter Integration
  • Bidder Adapter US Privacy Integration
  • UserSync Integration
• Adapters Supporting US Privacy / CCPA

Overview

This consent management module is designed to support the California Consumer Privacy Act (CCPA). The IAB has generalized these guidelines to cover future regulations, referring to the feature as “US Privacy.”

This module works with an IAB-compatible US Privacy API (USP-API) to fetch an encoded string representing the user’s notice and opt-out choices and make it available for adapters to consume and process. In Prebid 7+; the module defaults to working with an IAB-compatible US Privacy API; in prior versions, the module had to be configured to be in effect.

See also the Prebid Consent Management - GDPR Module for supporting the EU General Data Protection Regulation (GDPR)

Here’s a summary of the interaction process:

1. Fetch the user’s US Privacy (CCPA) notice and opt out status from the USP-API.
2. Incorporate this data into the auction objects for adapters to collect.
3. Proceed with the auction.

The IAB USP-API will respond immediately if it is available. The module timeout settings are not related to user selection, but only to API availability.

If the timeout period expires or an error from the USP-API is thrown, the auction proceeds without a US Privacy string attached.

The string has four characters:

Deletes

As of January 1st 2023, CCPA will require that requests to “delete my personal information” (right to delete) must be propagated to all 3rd parties user data is being shared with. US Privacy Consent Management Module will support this feature in 7.23.0 and above.

Prebid Modules that receive user data (bid adapters, analytics adapters), or set user data (UserId, RTD) may define a new method called onDataDeletionRequest. The US Privacy Consent Management Module will attach a registerDeletion event handler with the CMP, when triggered it will:

The USP module attaches a ‘registerDeletion’ event handler with the CMP; when triggered, it will:

• invoke the methods above on all adapters
• delete all IDs from cookies/localStorage

3rd parties can define the method like this:

• UserID submodules can define a method onDataDeletionRequest(config, idValue)
• Bid adapters can define a method spec.onDataDeletionRequest(bidderRequests)
• Analytics adapters can define a method onDataDeletionRequest()

Page Integration

To utilize this module, software that provides the USP-API must to be implemented on the site to interact with the user and obtain their notice and opt-out status.

Though implementation details for the USP-API are not covered by Prebid.org, we do recommend to that you place the code before the Prebid.js code in the head of the page in order to ensure the framework is loaded before the Prebid code executes. Many publishers who ensure the prior availability of the __uspapi set the timeout parameter to zero.

Once the USP-API is implemented, simply include this module into your build and add a consentManagement object in the setConfig() call. Without configuration, Prebid will throw a warning that the module is unconfigured, and will proceed with the default configuration parameter cmpApi as ‘iab’. Adapters that support this feature will then be able to retrieve the notice and opt-out status information and incorporate it in their requests.

Here are the parameters supported in the consentManagement object:

Note that the term ‘CMP’ (Consent Management Platform) was chosen in Prebid to keep the interface similar to the GDPR implementation, though US-Privacy doesn’t specifically use that term.

Examples

Example 1: Support both US Privacy and GDPR

     var pbjs = pbjs || {};
     pbjs.que = pbjs.que || [];
     pbjs.que.push(function() {
       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
           }
         }
       });
     });

Example 2: Support US Privacy; timeout the api availability at zero because it is always available if it applies

     var pbjs = pbjs || {};
     pbjs.que = pbjs.que || [];
     pbjs.que.push(function() {
       pbjs.setConfig({
         consentManagement: {
           usp: {
            cmpApi: 'iab',
            timeout: 0 // US Privacy timeout 100ms
           }
         }
       });
     });

Example 3: Static CMP using custom data passing. Placing this config call in the command queue before loading Prebid is important to ensure the string is available before Prebid begins making external calls.

     var pbjs = pbjs || {};
     pbjs.que = pbjs.que || [];
     pbjs.que.push(function() {
        pbjs.setConfig({
          consentManagement: {
            usp: {
              cmpApi: 'static',
              consentData: {
                getUSPData: {
                  uspString: '1YYY'
                }
              }
            }
          }
        });
     });

Example 4: Static CMP with USP string set to does not apply for all fields, which may be useful to prevent excessive interaction with the __uspapi outside of the geographic scope. Placing this config call in the command queue before loading Prebid is important to ensure it is available early.

     var pbjs = pbjs || {};
     pbjs.que = pbjs.que || [];
     pbjs.que.push(function() {
        pbjs.setConfig({
          consentManagement: {
            usp: {
              cmpApi: 'static',
              consentData: {
                getUSPData: {
                  uspString: '1---'
                }
              }
            }
          }
        });
     });

Build the Package

Follow the basic build instructions in the GitHub Prebid.js repo’s main README. To include the consent management module, an additional option must be added to the the gulp build command:

gulp build --modules=consentManagementUsp,bidAdapter1,bidAdapter2

Adapter Integration

If you are submitting changes to an adapter to support this approach, please also submit a PR to the docs repo to add the usp_supported: true variable to your respective page in the bidders directory. This will ensure that your adapter’s name will automatically appear on the list of adapters supporting US Privacy.

Bidder Adapter US Privacy Integration

To find the US Privacy/CCPA notice and opt-out status 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:

{
  "bidderCode": "bidderA",
  "auctionId": "e3a336ad-2222-4a1c-bbbb-ecc7c5554a34",
  ...
  "uspConsent": "1YYY",
  ...
}

UserSync Integration

The usPrivacy object is also available when registering userSync pixels. The object can be accessed by including it as an argument in the getUserSyncs function:

getUserSyncs: function(syncOptions, responses, gdprConsent, usPrivacy) {
...
}

Depending on your needs, you could include the US-Privacy information in a query of your pixel and/or, given the notice and opt-out status choices, determine if you should drop the pixels at all.

Adapters Supporting US Privacy / CCPA