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.

Only the Java version of PBS currently supports the module infrastructure.

The Modules

Module Description PBS-Go PBS-Java
ORTB2 Blocking Support bidders that aren’t full-service SSPs.  

Installing a PBS 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.

Further Reading