# Scalable Header Bidding Wrapper

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**.

***

## 🚀 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: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.hbwrapper.com/description.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
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.