Prebid.js Activity Controls

Starting with version 7.52, Prebid.js introduced a centralized control mechanism for privacy-sensitive activities - such as accessing device storage or sharing data with partners. These controls are intended to serve as building blocks for privacy protection mechanisms, allowing module developers or publishers to directly specify what should be permitted or avoided in any given regulatory environment.

• Overview
  • Prebid Is a Toolkit
  • What is an Activity?
  • Example Activity Control
• Configuration
  • Activities
  • Rules
    • Rule Priority
    • Rule Conditions
    • Allow Flag
  • More examples
    • Always include a particular bidder in auctions
    • Disable all user syncs except for specific domains
    • Deny a particular vendor access to user IDs
    • __uspapi CCPA/CPRA based control
    • When there’s a GPP CMP active, anonymize everything
    • Always allow sharedId to be passed, others determined by privacy regs
• Further Reading

Overview

There are many privacy regulations that Prebid publishers need to accommodate. Prebid supplies modules to help Publishers implement their legal policies, but there are scenarios where extra control is needed:

• a Publisher’s lawyers want to make a particular exception
• a module hasn’t been built for a regulation the Publisher needs to support

Several, but not all, of the popular consent strings have modules (eg Prebid Activity Controls – GPP control module - usnat) that translate their contents into activity controls. These modules may have some overrides to default string interpretations available. When these overrides are insufficient for a publisher, or case law has abruptly changed, publishers may prefer direct control.

Prebid Is a Toolkit

1. Get a privacy lawyer.
2. Consider all the privacy regulations your content business is subject to.
3. Come up with a plan.
4. Use Prebid.js modules and these Activity Controls as ways to help implement your privacy plan with respect to header bidding.
5. Let us know if there are tools missing from the Prebid toolkit.

What is an Activity?

We did an analysis of the things Prebid.js does and identified those related to privacy regulations. We call these things “potentially restricted activities”, or just “activities” for short. Here are some:

• Setting a cookie
• Syncing ID cookies
• Transmitting user first-party data
• etc.

The full list of activities Prebid.js supports is below.

Think of an activity control as a ‘gatekeeper’ that makes the decision about whether the activity should be allowed in this specific context:

• Should I allow this cookie to be set for bidderA?
• Should I allow this usersync for bidderB?
• Is it ok for this data to be passed to bidderC and analyticsD?
• etc.

Prebid.js core checks with the Activity Controls to see whether an activity is allowed. The configuration for the activity can come from modules, custom functions in the page, or a rule-based JSON config.

Example Activity Control

In this example, bidderX wants to set a cookie through StorageManager, which queries the Activity Control System to determine whether that’s allowed. The publisher has set up configuration that specifically enables bidderX to do this.

Here’s an example JSON config that disables accessing local storage (including cookies) for everything except the bid adapter bidderX:

pbjs.setConfig({
   allowActivities: {
       accessDevice: {
           default: false,
           rules: [{
              condition(params) {
                  return params.componentName === 'bidderX'
              },
              allow: true
           }]
       }
   }
})

Configuration

allowActivities is a new option to setConfig. It contains a list of activity names – see the full list of activities below. Each activity is an object that can contain these attributes:

Rules is an array of objects that a publisher can construct to provide fine-grained control over a given activity. For instance, you could set up a series of rules that says:

• Amongst the bid adapters, BidderA is always allowed to receive user first-party data
• Always let analytics adapters receive user first-party data
• Otherwise, let the active privacy modules decide
• if they refuse to decide, then the overall default is to allow the transmitting of user first-party data

There’s more about rules below.

Activities

Here’s the list of the ‘potentially restricted activities’ that Prebid.js core can restrict for Publishers:

Rules

There are three parts to an Activity Control’s rule:

1. The priority
2. The condition
3. The allow flag

For example, this rule would allow bidderX to perform the activity if no higher priority rules take precedence.

...
    rules: [{
        priority: 10,               // average priority
        condition(params) {
            return params.componentName === 'bidderX'
        },
        allow: true
    }]
...

Rule Priority

Activity control rules in Prebid.js can be created by two main sources:

• Publisher setConfig({allowActivities}) as in the examples shown here. When set this way, rules are considered the highest priority value of 1.
• Modules can set activity control rules, e.g. usersync, bidderSettings, the GPP or GDPR modules. Rules set by modules have a less urgent priority of 10.

When rules are processed, they are sorted by priority, and all rules of the same priority are considered to happen at the same time. The details:

1. The highest rule priority is 1
2. There’s no defined lowest priority other than MAXINT
3. Default priority for rules defined with setConfig is 1. The default priority for other rules is 10.
4. When processing, group the rules by priority
5. Then, in descending order of priority:
   1. If any rule that matches the condition defines allow: false, the activity is DENIED.
   2. Otherwise, if at least one rule that matches the condition defines allow: true, the activity is ALLOWED.
   3. If any rule matches, break out of the priority loop.
6. If none of the rules match, and the activity defines default: false, the activity is DENIED.
7. Otherwise, the activity is ALLOWED.

So this means that when priority is omitted from allowActivities configuration, it acts as an override over other control mechanisms. For example:

pbjs.setConfig({
    accessDevice: false,      // this would have the effect of disabling device storage, but... 
    allowActivities: {
        accessDevice: {
            rules: [
                {allow: true} // ... it's overridden by this condition-less rule with a default priority of 1
            ]
        }
    } 
}) 

If a priority number greater than 10 is specified, the rule only takes effect when all other controls have allowed the activity. For example:

pbjs.setConfig({
    allowActivities: {
        accessDevice: {
            // the intent here is to disable cookies but allow HTML5 localStorage
            // because this defines priority > 10, other controls will be checked first
            // e.g. if GDPR is in-scope and there's no consent, this priority 20 rule won't be processed
            default: false,
            rules: [{
                condition({storageType}) {
                    return storageType === 'html5'
                },
                allow: true,
                priority: 20
            }]
        }
    }
})

Rule Conditions

A condition is a javascript function that receives information about the activity that is about to be performed. If a condition evaluates to true, the allow attribute of the rule will be utilized. If there’s no condition specified, the rule’s allow attribute will always be utilized.

These are the parameters available to the condition function:

Allow Flag

If the rule’s condition matches, this attribute defines whether the rule ‘votes’ to allow (true) or disallow (false) the activity in question.

As noted in the priority section, disallow (false) takes precedence amongst rules at the same priority level.

If allow is not defined, the rule is assumed to assert true (i.e. allow the activity to take place).

More examples

Always include a particular bidder in auctions

This is similiar to the ‘vendor exception’ feature of the TCF Control Module. This would always allow bidderA to participate in the auction, even without explicit consent in GDPR scenarios. It might indicate, for instance, that this is a ‘first party bidder’.

pbjs.setConfig({
  allowActivities: {
    fetchBids: {
        rules: [{
            condition: ({componentName}) => componentName === 'bidderA',
            allow: true
        }]
    }
  }
})

Disable all user syncs except for specific domains

const DOMAINLIST = [
    'https://example-domain.org',
    'https://other-domain.com',
];

pbjs.setConfig({
    allowActivities: {
        syncUser: {
            default: false,
            rules: [{
                condition({syncUrl}) {
                    return DOMAINLIST.some(domain => syncUrl.startsWith(domain));
                },
                allow: true
            }]
        }
    }
})

Deny a particular vendor access to user IDs

pbjs.setConfig({
  allowActivities: {
    transmitEids: {
        rules: [{
            condition: ({componentName}) => componentName === 'exampleVendor',
            allow: false,
        }]
    }
  }
})

__uspapi CCPA/CPRA based control

Reference: US Privacy User Signal Mechanism “USP API” Specification

function isCCPAConsentDenied() {
### assumes uspapi is properly implemented and available in your environment.
### check usp string for the second character (notice) is not 'Y' or third character (opt out) is not 'N' or first character (version) is not '1'
   __uspapi('getUSPData', 1 , (uspData, success) => { if(uspData.uspString.charAt(2) ==='Y' || uspData.uspString.charAt(1) !=='Y'|| uspData.uspString.charAt(0) !=='1') { return true } else { return false }});
}

pbjs.setConfig({
    allowActivities: {
          enrichUfpd: {
                 rules: [{
                       condition: isCCPAConsentDenied,
                       allow: false
                 }]
          },
          enrichEids: {
                rules: [{
                       condition: isCCPAConsentDenied,
                       allow: false
                }]
          },
          reportAnalytics: {
                rules: [{
                       condition: isCCPAConsentDenied,
                       allow: false
                }]
          },
          syncUser: {
                rules: [{
                       condition: isCCPAConsentDenied,
                       allow: false
                }]
          },
          transmitEids: {
                rules: [{
                       condition: isCCPAConsentDenied,
                       allow: false
                }]
          },
          transmitPreciseGeo: {
                rules: [{
                       condition: isCCPAConsentDenied,
                       allow: false
                }]
          },
          transmitUfpd: {
                rules: [{
                       condition: isCCPAConsentDenied,
                       allow: false
                }]
          }
          
    }
})

When there’s a GPP CMP active, anonymize everything

This example might be useful for publishers using a version of Prebid.js that supports activity controls but does not support the USNat module.

if (in-page code to detect that GPP SID 7 through 12 are in-scope or if the GPC flag is set) {
  pbjs.setConfig({
    allowActivities: {
      enrichEids: {
        default: false
      },
      transmitEids: {
        default: false
      },
      … see other activities in https://docs.prebid.org/dev-docs/activity-controls.html …
    }
  });
}

Always allow sharedId to be passed, others determined by privacy regs

To make exceptions for certain IDs, there are two steps:

1. Always allow the transmitEids activity to take place
2. Configure the enrichEids activity to allow only the desired IDs

This approach works in conjunction with other activity-control compiant modules (like the GPP USNat module.

    pbjs.setConfig({
      allowActivities: {
        enrichEids: {
          default: false,
          priority: 1,
          rules: [{
              condition(params) {
                  return params.componentName === 'sharedIdSystem'
              },
              allow: true
           }]
        },
        transmitEids: {
          rules: [{
              allow: true
        },
        … see other activities in https://docs.prebid.org/dev-docs/activity-controls.html …
      }
    });

Further Reading

• FAQ: How does Prebid.js support privacy regulations