Ctrlk
For the complete documentation index, see llms.txt. This page is also available as Markdown.

🌐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 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

PreviousIntroduction
NextGlossary

Last updated