Prebid Server Modules

The core of Prebid Server contains the foundational code needed for header bidding. Any functionality that could be considered an add-on or that covers a special case is covered by modules.

If you’re looking for bidder adapter parameters, see Bidders’ Params.

The Modules

There are two types of modules:

  1. General Modules - these plug into various stages within the main auction workflow and can affect any part of the request or response.
  2. Privacy Modules - these are more limited, plugging into the Activity Controls system to delegate decisions about potentially privacy-sensitive scenarios.

The full list of modules:

Module Description Type PBS-Go PBS-Java
ORTB2 Blocking Support bidders that aren’t full-service SSPs. general check check
Confiant Ad Quality Scans bid responses for security and quality issues. general   check
US Gen Privacy Links with the Activity Controls to process GPP strings to determine whether an activity should be allowed. privacy   check
US Custom Logic Privacy Similar to the US Gen Privacy module, but publishers define their own interpretation of the GPP string. privacy   check
Richmedia Filter Can filter MRAID creatives from the bid stream. validation   check
51Degrees Device Detection Enriches an incoming OpenRTB request with 51Degrees Device Data general check check

Installing a PBS General Module

Once a Prebid Server host company decides which modules they want to support, here’s how installation works:

1. Build PBS with modules

Note that modules are currently an all-or-nothing nothing from a code perspective.

mvn clean package --file extra/pom.xml

2. Define an ‘execution plan’

The execution plan details:

  • which modules are used in your server
  • what order they’re invoked in
  • how long modules have to run before timeout
  • whether any modules depend on each other

If you want the module to run on every request regardless of account, this is a host-level config you should place in application.yaml. If the module should be active only for certain accounts, you’ll need to place the plan in the account-specific config.

To define a plan, you’ll need to know the following module details, which should be available in the module documentation:

  • urls: which PBS ‘entry points’ are relevant. e.g. /openrtb2/auction, /openrtb2/amp
  • stages: one or more of the 7 workflow stages where the module should be called: entrypoint, raw-auction-request, processed-auction-request, bidder-request, raw-bidder-response, processed-bidder-response, and/or auction-response.
  • hooks: for each stage where a module runs, its documentation will provide the hook function name.

Here’s an example application.yaml entry:

hooks: 
  host-execution-plan: >   # these hooks are always run for all accounts
  {
    "endpoints": {
      "/openrtb2/auction": { # endpoint
        "stages": {
          "entrypoint": { # stage
            "groups": [
              {
                "timeout": 3,  # in milliseconds
                "hook-sequence": [
                  {
                    "modulecode": "modulecode1",
                    "hookimplcode": "hook1"
                  },
                  {
                    "modulecode": "modulecode2",
                    "hookimplcode": "hook2"
                  }
                ]
              },{ // this group depends on the results of the first group
                    "timeout": 5,  # in milliseconds
                    "hook-sequence": [
                  {
                    "modulecode": "modulecode3",
                    "hookimplcode": "hook3-depends-on-hook1"
                  }
                ]
              }
            ]
          }
        }
      }
    }
  }
  # these hooks are run for all accounts unless overridden by DB config
  default-account-execution-plan: >
  {
   "endpoints": {
      "/openrtb2/amp": { # endpoint
        "stages": {
          "raw-auction-request": { # stage
            "groups": [
              {
                "timeout": 5,
                "hook-sequence": [
                  {
                    "modulecode": "modulecodeA",
                    "hookimplcode": "hookA"
                  }
                ]
              }
            ]
          }
        }
      }
    }
  }

3. Supply the module with configuration

Modules may require configuration at startup or during the request:

  • If the module requires config at initialization, its documentation will describe where the config file lives and what format it should take.
  • If the module requires runtime config, it should be passed via the account-conig mechanism.

Installing a PBS Privacy Module

Privacy modules are already built into the code base. They just need to be linked to the relevant ‘Activity’ using the privacyreg directive as described in the Activity Control reference.

Further Reading