> For the complete documentation index, see [llms.txt](https://docs.hbwrapper.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.hbwrapper.com/description.md). # Project Description A high-performance, fully modular, and enterprise-grade Header Bidding Wrapper built on **Prebid.js**, designed to scale effortlessly across **thousands of websites** and optimized for **billions of pageviews monthly**. > **In plain terms:** this is one script that runs the entire process of selling a website's ad space through open competition. When a page loads, the wrapper asks many ad buyers to bid at the same time, picks the best offer, hands it to Google Ad Manager, and shows the winning ad — all in a fraction of a second. It's designed so that one team can manage the ad setup for thousands of sites from a single place, just by editing settings files. If any term below is unfamiliar, the [Glossary](/glossary.md) explains them all in everyday language. *** ## 🚀 Key Features ### 🔧 Modular Micro-Script Architecture * **Only the code you need, per site**\ Each domain loads a minimal, optimized JavaScript payload tailored to its unique configuration. * **Automatic builds and deployments**\ CI/CD system ensures your wrapper is always up to date, with each configuration change triggering a fresh, versioned build. ### 🌍 Designed for Scale * Manage **thousands of sites** from a centralized, structured configuration. * JSON-based config makes onboarding and updates fast and reliable. * Production-tested on **billions of monthly pageviews**. ### ☁️ Delivered via Specialized CDN * Served from a **CDN optimized for ad tech assets**, ensuring: * **Fast initial load** * **Caching optimization** * **Frequent updates** without cache bloat or versioning issues ### 🧱 Built on Prebid.js * On top of Prebid.js, supports **hybrid header bidding** (client-side + server-side) * Supports: * **High-impact Rich Media** ad formats * **ID modules** * **User sync** * **GDPR/CCPA compliance** ### 🎯 Manages Google Ad Manager (GAM) * **No on-page GAM setup required** — the wrapper fully manages all GAM interactions. * Pushes **precise key-values** to GAM for: * Advanced delivery targeting * Optimized creative decisioning * Vast and detailed key values reporting for GAM to analyze the delivery and results of ads ### 📊 Advanced Ad Tech Capabilities * **Flexible Safe Frames Signal** — Industry-first impression-level SafeFrame control based on bid characteristics (bidder, CPM, domain, category, or ad unit) * **Bot detection** to reduce invalid traffic * **Granular ad refresh controls** * **Fallback renderer** to display ads when GAM returns no creative * **Custom JS hooks** for full control at auction, render, or bid-won events ### ⚙️ Easy to Implement * Built for fast integration * Suitable for **both simple and complex implementations** * **Supports complex integrations with a Publisher API** ### 🧑‍💻 Developer-Friendly * **Implement any custom JavaScript** * **All configuration handled in JSON** — clean, structured, and scalable ### 🔄 Always Up to Date * Actively maintained to reflect: * The **latest releases from Prebid.org** * **IAB Tech Lab standards** * **Industry best practices** — implemented by default *** ## 🧰 Use Cases * Ad tech teams managing thousands of sites * Publishers seeking flexibility, performance, and complete control * Networks needing rapid deployment and ad decisioning at scale *** ## 🧭 Key Concepts * Wrapper: Script coordinating header bidding, auctions, and GAM requests. * Ad unit: Placement configured in GAM and mapped on-page via `data-aa-...` attributes. * GAM: Google Ad Manager, the ad server receiving requests from the wrapper. * Auction: Parallel demand competition (Prebid) before the GAM request. * Lazy load: Defers ad requests until elements approach the viewport. * Refresh: Re-requests ads on a timer or when viewable. See also * Public API: `Public-API.md` * Configuration: `Configuration.md` ## 📊 Workflow ``` +-----------------------+ +-----------------------+ +---------------------+ +-------------------------+ +--------------------+ | JSON Config Files | --> | Build System | --> | CDN Delivery | --> | Publisher Site Loads | --> | Ads Displayed | | (Structured Settings) | | (Wrapper Generator) | | (Optimized Wrapper) | | (Script Integration) | | (User Sees Ads) | +-----------------------+ +-----------------------+ +---------------------+ +-------------------------+ +--------------------+ | | | | | Site-specific JSON Auto versioning & Cached, fast-loading Wrapper executes and Wrapper handle for units, bidders, minified script builds wrapper scripts via CDN triggers auction on page auction & render refresh, etc. ``` --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation by asking a question. Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters: ``` GET https://docs.hbwrapper.com/description.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.