Prebid Server Activity Controls

PBS-Java fully supports Activity Controls. PBS-Go support for the main request workflow is complete. They are working on support for Activities in modules and analytics.

Prebid supports a centralized control mechanism for privacy-sensitive activities. These controls are intended to serve as building blocks for privacy protection mechanisms, allowing publishers to directly specify what should be permitted or avoided in any given regulatory environment.

• Overview
  • Prebid Server Is a Toolkit
  • What is an Activity?
  • Example Activity Control
  • Activity Controls in Relation to Privacy Features
• Activity Control Configuration
  • Activities
  • Rules
    • Rule Conditions
    • Allow
  • Examples
    • Example 1 - enable all privacy modules
    • Example 2 - bidder exception
    • Example 3 - analytics exception
    • Example 4 - GPP overrides
    • Example 5 - GPC override
• Modules
• Further Reading

Overview

There are many privacy regulations for Prebid publishers to consider. Prebid Server supplies several privacy features to help Publishers implement their legal policies.

The Activity Control system is a common framework that serves as a central privacy control mechanism. It currently supports a number of scenarios:

• Delegate the decision about a certain activity to a particular privacy module or all privacy modules in general.
• Allow a Publisher’s lawyers to define an exception for a certain bidder or module.
• Enable reasonable configuration for regulations not specifically supported by Prebid Server.

At this time, the older PBS privacy features such as TCF/GDPR and USP are not part of the Activity Control system. They may be integrated into the system over time, but for now the only privacy module that plugs into this system is the USGen Privacy Module. There will be more.

The Activity Control configuration has two components:

1. Account-level configuration allows each publisher to define different anonymization policies
2. Host-level configuration allows each PBS host company to define a default privacy behavior that covers accounts that don’t define their own.

Prebid Server Is a Toolkit

Activity Controls and privacy features within Prebid Server are tools meant to be useful to publishers within their overall privacy strategy. Prebid assumes a larger context around these tools:

1. Get a privacy lawyer.
2. Consider all the privacy regulations your media content business is subject to.
3. Come up with a plan.
4. Use Prebid Server server features 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?

Prebid did an analysis of the things Prebid does that might be of concern to privacy regulations. We call these things “potentially restricted activities”, or just “activities” for short. Some examples:

• Syncing ID cookies
• Transmitting user first party data
• Transmitting the user’s geographic location
• etc.

The full list of activities is below.

An activity control is a gatekeeper that makes a decision about whether the activity should be allowed in a specific context:

• Should I allow this usersync for bidderB?
• Is it ok for this data to be passed to bidderC and analyticsD?
• Should I anonymize the geographic information for this request?
• etc.

Prebid Server core checks with the Activity Controls to see whether a given activity is allowed for a given situation. The configuration for the activity comes from one of two places: either account-specific configuration or if not specified there, there’s a host-level default.

Example Activity Control

Here’s an example account config that prevents bidderA, bidderB, and analytics adapters from receiving user.eids[] and user.ext.data. It does not specifically link out to any privacy regulations, so would not involve privacy modules that are linked into the Activity Controls.

{
  "privacy": {
    "allowactivities": {
      "transmitUfpd": {
        "default": true,
        "rules": [{
          "condition": {
            "componentName": ["bidderA", "bidderB"]
          },
          "allow": false
        },{
          "condition": {
            "componentType": ["analytics"]
          },
          "allow": false
        }]
      }
    }
  }
}

Activity Controls in Relation to Privacy Features

In the long-term, the vision is that Activity Control config will become a complete description of the allow/deny status of a particular action. However, for now, the existing privacy regulations (GDPR, USP, COPPA) sit ouside of Activity config.

Here’s how the Activity Control system works with other privacy features:

1. When PBS-core hits certain spots during request processing, it calls the Activity Control system.
2. Activity config may instruct the server to call privacy modules like US General privacy.
3. If the Activity Control denies the activity, the action will be suppressed/anonymized.
4. However, if the Control allows the activity, the system will still go on to check other relevant privacy activities like TCF/GDPR.

Here’s a list of the PBS privacy-related features and whether it’s integrated into the Activity Control system:

So, for example, TCF/GDPR-suppression activities must still be managed through that feature’s configuration. (See details for PBS-Go or PBS-Java)

Activity Control Configuration

The privacy.allowActivities is a new account configuration option that contains a list of activity names – see the full list of activities below.

Here’s a general template for how activity configuration looks in the account config:

{
  "privacy": {
    "allowactivities": {
      "ACTIVITY": {                 // one of the activities in the table below
        "default": true,            // whether to allow if no rules match
        "rules": [{
          "condition": { ... },     // publisher-defined override
          "allow": true/false
        },{
          "privacyreg": ["*"]       // delegate to all configured privacy modules
        },{
          ... more rules ...
        }]
     }
   }
 }
}

The activity rules array can be thought of as a script: Prebid Server processes each array entry in order and will stop once it gets a definitive result.

Each ACTIVITY is an object that can contain these attributes:

Rules is an array of objects that a publisher can contruct to provide fine-grained control over a given activity.

There’s more about rules below.

Activities

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

Rules

There are several parts to an Activity Control rule:

1. Priority - the rule’s position within the array matters - they are processed in order, and processing stops as soon as a definitive answer is found about whether to allow the activity or not.
2. Either a condition or a privacyreg directive.
   1. A condition defines the logic for matching the publisher’s exception scenario. The condition should come along with an allow flag - what happens if the condition matches. The ‘allow’ flag defaults to true.
   2. A privacyreg statement defines which privacy modules the publisher wants to delegate this privacy decision.

The processing of each rule object has one of three outcomes:

1. allow:true (aka allow) - the activity is allowed to take place.
2. allow:false (aka deny) - the activity is not allowed to take place. This may result in anonymizing a portion of the request, stopping a usersync, or stopping a request from going to a bid adapter.
3. abstain - the rule does not definitively determine whether the activity should be allowed. This can happen in a number of scenarios:
   1. the rule condition doesn’t match
   2. the privacy module determines the request is not in the scope of the legal jurisdiction. e.g. the USGen module will only make a ruling when the GPP Section ID declares the request in-scope.

As an example, here’s a rule that always allows ‘bidderX’ to perform the activity and then delegates the decision for every other bidder to the privacy modules:

...
    "rules": [{
      "condition": {
        "componentName": ["bidderX"]
      },
      "allow": true
    },{
      "privacyreg": ["*"]
    }]
...

Note: The Prebid.js version of Activity Controls supports explicit priority signals. That’s not the case for the Prebid Server feature. Instead, priority in PBS is implicit in the ordering of the array.

Rule Conditions

If a condition in a rule 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 conditional attributes available:

Note on names: if two components share a name (e.g. “ssp1”) for both a bid adapter and an analytics adapter, the rule can distinguish between them by providing both componentName and componentType.

Here’s how the geo condition works:

1. If the value in the supplied array (e.g. [“USA”]) does not have a dot, then PBS looks only at device.geo.country for a case-sensitive match.
2. If the value in the supplied array (e.g. [“CAN.ON”]) does have a dot, PBS splits the value on the dot and looks for the left-hand side in device.geo.country and the right-hand side in device.geo.region. Both have to match.
3. Note that the specific values and cases of the country/region will depend on your geo-lookup service. i.e. you’ll have to get the table of allowed values from MaxMind, Netacuity, or whichever geo-lookup service is in use.

Allow

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

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

Examples

Example 1 - enable all privacy modules

This example may be a reasonable global default for host companies that want to default all their accounts to use the US General module for all activities:

{
  "privacy": {
    "allowactivities": {
      "syncUser": {
        "rules": [{
          "privacyreg": ["*"]
        }]
      },
      "fetchBids": {
        "rules": [{
          "privacyreg": ["*"]
        }]
      },
      "enrichUfpd": {
        "rules": [{
          "privacyreg": ["*"]
        }]
      },
      "reportAnalytics": {
        "rules": [{
          "privacyreg": ["*"]
        }]
      },
      "transmitUfpd": {
        "rules": [{
          "privacyreg": ["*"]
        }]
      },
      "transmitPreciseGeo": {
        "rules": [{
          "privacyreg": ["*"]
        }]
      }
    }
  }
}

Example 2 - bidder exception

Anonymize auctions and disable usersyncs for bidderA but otherwise delegate to privacy modules:

{
  "privacy": {
    "allowactivities": {
      "transmitUfpd": {
        "rules": [{
            "condition": {
                "componentName": ["bidderA"]
            },
            "allow": false
        },{
            "privacyreg": ["*"]
        }]
      },
      "syncUser": {
        "rules": [{
            "condition": {
                "componentName": ["bidderA"]
            },
            "allow": false
        },{
            "privacyreg": ["*"]
        }]
      }
    }
  }
}

Example 3 - analytics exception

Prevent User First Party Data and EIDs from going to analytics adapters

{
  "privacy": {
    "allowactivities": {
      "transmitUfpd": {
        "rules": [{
            "condition": {
                "componentType": ["analytics"]
            },
            "allow": false
        },{
            "privacyreg": ["iab.*"]
        }]
      }
    }
  }
}

Example 4 - GPP overrides

Anonymize when in the US states of Virginia or California when a relevant SID is active.

This scenario is a way to achieve a blunt anonymization even without the PBS USGen module:

{
  "privacy": {
    "allowactivities": {
      "ACTIVITY": {
        "rules": [{
            "condition": {
                "gppSid": [7,8,9]
                "geo": ["USA.CA", "USA.VA"]
            },
            "allow": false
        }]
      }
    }
  }
}

Example 5 - GPC override

Anonymize when the GPC flag is set.

{
  privacy: {
    allowactivities: {
      ACTIVITY: {
        rules: [{
            condition: {
                gpc: "1"
            },
            allow: false
        }]
      }
    }
  }
}

Modules

Modules that perform any ‘potentially restricted activity’ are responsible for confirming they are allowed to perform that activity. See Adding a PBS Module for more information.

Further Reading

• Prebid Server privacy regulation support
• Prebid Server USGen privacy module