This document guides you through the process of developing a module for host companies to plug into their instance of Prebid Server. We encourage you to look at existing modules for working examples. You can also ask us questions by submitting a GitHub issue.
Modules are currently only supported in PBS-Java.
The ability to add optional modules in Prebid.js has been widely used, with dozens of interesting features forming a healthy ecosystem of vendor choice that’s good for publishers and the industry.
Prebid Server (Java) supports a rich module interface that allows anyone to contribute functionality at predefined places along the request pipeline. Here’s the general development process:
The first module written was the ORTB2 Blocking module. Example ideas for future modules include creative validation and traffic quality. If you have an idea for a module that’s not feasible (e.g. a new endpoint), open an issue with a detailed description of what you’re looking to do.
There are a number of things modules are not allowed to do without disclosing prominently on their documentation. Please review the Module Rules page. Here are some highlights:
Here’s a description of the Stages of a PBS request that modules can tap into for each supported endpoint:
Stage | Description | Endpoints | Example Use Cases |
---|---|---|---|
Entrypoint | Hook functions can see the raw request before PBS has processed or validated anything | auction, amp, video | A/B testing of account parameters, Alternate account validation, AMP pre-processing |
Raw Auction Request | Validations have been done, but no enrichments | auction, amp, video | A/B testing of StoredRequests, Advanced device detection, Traffic Quality |
Processed Auction Request | Any stored requests have been merged in and all PBS enrichments are done | auction, amp, video | Inject First Party Data, Channel determination, Bid floors, Bidder optimization |
Bidder Request | The request has been customized for a particular bidder in the auction | auction, amp, video | Bidder-specific bcat/badv, Bidder-specific deals |
Raw Bidder Response | Hook functions can get access to the unprocessed bidder response | auction, amp, video | Response validations |
Processed Bidder Response | PBS has done its own validations on an individual bidder’s response | auction, amp, video | Advanced CPM adjustments, Custom VAST macros |
All Processed Bid Responses | All bids are back and PBS-core bid validations are done. | auction, amp, video | Creative validation, advanced bid validations. (PBS-Java 1.97+) |
Auction Response | Last step before the response goes back to the client | auction, amp, video | Inject ad server targeting, alternate auction winner logic |
A module may be comprised of:
Some modules may plug into only one endpoint and one stage of processing. Others may coordinate activity across multiple stages. For example, this diagram illustrates the design of a module that’s rather extremely configured to plug into all of the stages of the processing workflow:
There are a few basic ways a module’s hook function can respond to PBS-core:
The amount of time your module takes to perform its actions will be limited by PBS-core. For example, if a creative validation module needs to ‘phone home’ to analyze the bid creative, it will have a tight window of a few milliseconds to get the response and apply it. Your documentation can request how long the module needs, but keep in mind that PBS host companies may not use your module if it leads to an increased rate in header bidding timeouts.
There are two sources of configuration for each module:
When Prebid Server starts up, it can be configured to initialize modules supported by the Host Company. This start up config should contain values that are constant across requests. e.g.:
Values in this config can only change with a bounce of Prebid Server.
For each user request, modules can have account-specific configuration stored in the account-config data source. This configuration is used to store parameters that could vary for different publishers utilizing this PBS instance. e.g.:
If your module will require state of some sort beyond configurtaion, you’ll have to provide instructions to the PBS host company. Examples:
Analytics Tags (aka ‘ATags’) are a log mechanism provided by PBS-core to inform downstream modules about what’s happened in the request so far. Use of the Analytics Tag structure is completely optional, but there may be application or reporting reasons for sharing the results. Examples:
See the Module Analytics Tag Conventions for more specific details about how to format ATags.
The details of the implementation depend on the platform.
Other rules for open source PBS pull request:
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:
When everthing checks out on your dev environment, submit the PRs for review.