How to Add a Go Module to Prebid Server: A Practical Guide for Publishers
Many publishers want to unlock more control and innovation within their header bidding stack, but Prebid Server’s default functionality can feel rigid. Adding custom modules to Prebid Server (Go), sometimes called PBS-Go, offers a path to introduce unique hooks, advanced blocking, or analytics directly into the auction workflow.
However, starting with custom modules can be daunting—especially given the strict repository structure, specific interfaces, and testing expectations. This guide breaks down the essentials for publisher teams and ad operations leaders, focusing on what matters most: operational clarity, future-proofing, and revenue optimization.
Understanding Prebid Server Module Architecture
Prebid Server (Go) organizes custom logic into discrete “modules.” Each module can interact with different points in the auction flow via predefined hook interfaces. This modularity lets publishers tailor Prebid behavior without forking or patching the core, maintaining upgrade compatibility and vendor neutrality.
Directory and Code Structure Overview
Modules reside in a dedicated ‘modules’ package within the main Prebid Server repository. To add a module, create a vendor-named directory inside ‘modules’, then create a subfolder representing your module. For example:
– prebid-server/
– modules/
– mycompany/
– dealblocker/
– module.go
Stick to letters, numbers, and underscores—no hyphens or special characters in folder names. This directory layout is crucial for recognition by Prebid’s build tooling and future maintainability.
Key Steps to Adding a Go Module to Prebid Server
The overall process focuses on clarity and predictability. Publishers or technical teams should expect these core steps:
Implementing the Core Module
Each module must define a ‘Builder’ function in Go—this handles module instantiation, passing configuration details and shared dependencies. The minimum requirement is implementation of at least one Prebid Server ‘hook’ interface, determining where your module operates in the auction life cycle (e.g., modifying a bidder request, filtering bids, processing bid responses).
Example: To filter bids before sending to a particular SSP, implement the ‘BidderRequest’ hook, which receives request context, can mutate payload, or even reject bidders based on your business logic.
Making Your Module Visible to Prebid Server
Once added, your module is picked up through automated tooling that scans for new ‘module.go’ files. Do not manually edit the main Prebid Server module registry. Instead, from the root directory, run:
– ‘make build-modules’ or
– ‘go generate modules/modules.go’
This ensures your new module is registered and available for configuration.
How Modules Interact with the Auction: Hooks and Use Cases
Hooks provide integration points into the Prebid Server auction flow. Publishers can use modules to perform data transformations, apply business rules, add analytics tags, or integrate real-time decisioning without touching the central code base.
Common Hooks Publishers Might Use
– Entrypoint: Prepares shared context between parallel modules
– RawAuctionRequest: Intercepts the request before internal processing
– BidderRequest: Allows custom filtering or manipulation before sending to SSPs
– RawBidderResponse / AllProcessedBidResponses: Modify or reject bid responses prior to auction resolution
Parallelization: For bidder-specific logic (e.g., blocklist enforcement, deal prioritization), BidderRequest hooks operate in isolation across all active bidders, ensuring efficiency and avoiding cross-bidder data leakage.
Examples Relevant to Publishers
– Block unwanted advertiser domains proactively during bidding
– Reject non-compliant bidders before they can participate
– Add granular analytics tags for custom reporting, such as tagging blocks by category or reason
– Share state between parallel hook invocations with a context map to maintain decision consistency across impressions
Testing, Documentation, and Configuration: Ensuring Robust Integration
Robust engineering isn’t optional—it is required for modules to go live in production. Prebid Server expects:
– Unit testing coverage of at least 90% on each implemented hook
– Proper in-module and open-source documentation (README.md and docs contribution)
– Module configuration exposed for operational toggling via JSON settings at startup
Sample Module Configuration
Module enablement is managed through the ‘hooks’ key in your Prebid Server configuration. Example:
{
“hooks”: {
“enabled”: true,
“modules”: {
“mycompany”: {
“dealblocker”: { “enabled”: true }
}
}
}
}
Execution order and parallel hook groups are set in ‘host_execution_plan’, allowing precise control for publisher ops teams.
What this means for publishers
Adding custom modules to Prebid Server means publishers gain new levers—without being locked into vendor-only solutions. Operationally, teams can introduce real-time logic, enforce compliance, or enhance tracking. It also opens the door for more rapid troubleshooting and innovation, since functionality can be iterated within isolated modules instead of monolithic updates. Ultimately, modules empower publisher tech teams to adapt Prebid to their business, data privacy, or revenue strategies—on their schedule.
Practical takeaway
For publishers with engineering resources, adding Go modules to Prebid Server unlocks deep customization and agility. In practice, this means:
– Define the business problem first: Only build a custom module when standard Prebid logic can’t meet your requirements.
– Ensure strict adherence to module directory conventions and testing practices—sloppy integration will break upgrades and slow down releases.
– Document not just the code, but the operational purpose, configuration, and contact points, so ad ops can manage module lifecycle without deep technical dependency.
Next steps: Audit your existing header bidding pain points, assess if custom PBS modules can solve them, and plan a minimal proof-of-concept module with thorough testing and rollout tracking. Prioritize changes that deliver revenue impact, efficiency, or actionable analytics.
