Prebid Server - Adding a Privacy Module

This feature is currently only available in PBS-Java.

Overview

Privacy Modules are different than Request Modules. They work in this way:

  1. Privacy Modules are called by the Activity Control System
  2. They are meant to use aspects of the request to determine whether a particular activity is allowed, disallowed, or abstain.

Here are the use cases envisioned for Privacy Modules:

  • Prebid will publish privacy modules for major IAB privacy protocols such as the US National Privacy Specification.
  • PBS host companies can develop custom versions of privacy modules for their publishers that may meet special legal requirements more efficiently.
  • Anyone can contribute privacy modules in support of regulations not addressed by Prebid or the IAB.

Terminology

  • PBS: short for Prebid Server
  • PBS-core: The inner workings of Prebid Server – not part of a module, bid adpater, or analytics adapter
  • PBS-Java: the Java version of Prebid Server
  • PBS-Go: the Go-Lang version of Prebid Server
  • Host Company: the entity running the PBS cluster, e.g. one of the ones on this list.
  • Activity Controls: a centralized mechanism for managing privacy-sensitive activities.
  • Privacy Module: a block of code that plugs into Prebid Server that enhances the functionality of the Activity Controls.
  • Allow: If the module returns this value, it has determined that the requested activity in the specified context is allowable.
  • Disallow: If the module returns this value, it has determined that the requested activity in the specified context is not allowable.
  • Abstain: If the module returns this value, it does not have a definitive answer about whether the requested activity in the specified context is allowable.

Building Your Privacy Module

1. Define the Behavior With Your Lawyers

As with any legally sensitive thing, you should have the desired behavior fully documented and signed off in conjunction with legal counsel.

Prebid cannot guarantee that the Activity Controls and Privacy Modules enable all possible legal scenarios. Please submit an issue to discuss enhancements to this system.

2. Review the Module Rules

There are a number of things modules in general are not allowed to do without disclosing prominently on their documentation. Please review the Module Rules page.

Privacy Modules are particularly constrained in what they can do. Basically all they can do is answer allow, disallow, or abstain to a request from an Activity Control. They cannot make HTTP requests, log analytics, or affect the request/response in any way.

2. Define a Module Code

The module code is how Activity Control configuration will refer to this privacy module. For example, if the module is named host1.publisherA.emea, it could be activated in the privacy config in any of these ways:

{
  "privacy": {
    "allowactivities": {
      "ACTIVITY1": {
        "privacyreg": ["*"]
      },
      "ACTIVITY2": {
        "privacyreg": ["host1.*"]
      },
      "ACTIVITY3": {
        "privacyreg": ["host1.publisherA.*"]
      },
      "ACTIVITY4": {
        "privacyreg": ["host1.publisherA.emea"]
      }
    }
  }
}

To choose the name, you should consider how the publisher may want to invoke the privacy modules that are available.

  • If you’re not going to open source the privacy module, we recommend prefixing the name with your host company so it doesn’t clash with open source modules as they become available.
  • If the module is publisher-specific, we recommend placing the publisher name in the module code.

3. Determine What Should be Configurable

Your module may not need any configuration, or it may have a complex configuration. Here are the kind of things to consider:

  • Does it need to identify or prioritize privacy parameters differently? (e.g. which consent and scope strings to use and prefer?)
  • Does it need to provide different exceptions? (e.g. if a particular publisher wants to allow or disallow certain scenarios.)

4. Write the Code, Config, and Unit Tests

The details of the implementation depend on the platform.

If you plan on open sourcing your privacy module, other rules for open source PBS pull request:

5. Write the Module Documentation

If this is an open source module, fork the documentation repo and create a file in /prebid-server/pbs-modules. You can start by copying one of the existing files. It should contain:

  • A description of the module functionality: why people might be interested in using it.
  • Prerequisites: any necessary account activation, other required modules, etc.
  • Configuration

6. Submit the Pull Requests

If open sourcing the module, submit the PRs for review when everything looks good in your test environment.

Further Reading