Cross-Frame Header Bidding
Technical Architecture

Architecture Overview

The cross-frame system splits the wrapper into two cooperating halves: a Core that runs the full Prebid auction pipeline, and one or more lightweight Workers that proxy the publisher's googletag API and relay results via @hbdev/woof postMessage.

Component Breakdown

Role Resolution

Every frame loading the wrapper must decide: am I the Core (runs auctions) or a Worker (proxies GAM)? The algorithm resolves to exactly one core per page within ~50ms, regardless of nesting depth or load order. No election, no random priorities — first frame to finish its probe wins naturally.

Key Implementation Details

// Top-level frame: CORE fast path
if (isTopLevel) {
    startProbeResponder();
    broadcastCoreElected();
    return ROLE_CORE;
}

// Nested frame: race quickProbe vs CORE_ELECTED broadcast
const found = await Promise.race([
    probePromise.then(result => result ? 'probe' : false),
    coreElectedPromise.then(elected => elected ? 'elected' : false),
]);

if (found) return ROLE_WORKER;

// No core found -- first to load wins
startProbeResponder();
broadcastCoreElected();
return ROLE_CORE;

workerEntry.js

The worker is a 566-line file that contains zero auction logic. It is a pure proxy: hook the publisher's GAM calls, relay to core, execute core's commands. Broken into five logical sections:

// Worker sends readiness signal to core
woof.send({ action: WORKER_READY });

// Core-side: on receiving WORKER_READY, sends CORE_READY back
// Worker: on receiving CORE_READY, flushes blocked googletag.cmd queue
woof.on(CORE_READY, () => {
    unblockGoogle();
    // Publisher's defineSlot, display, refresh calls now execute
    // through our hooks and relay to core
});

Event Protocol — 17 Bidirectional Events

All events are defined in crossFrame.events.js (40 lines) and imported by both core and worker. No magic strings. The protocol is fully typed by convention.

WORKER → CORE 8 Events

CORE → WORKER 9 Events

// --- Worker → Core events ---
export const WORKER_READY         = 'workerReady';
export const SLOT_DEFINED         = 'slotDefined';
export const DISPLAY              = 'display';
export const REFRESH              = 'refresh';
export const SLOT_RENDER_ENDED    = 'slotRenderEnded';
export const PREBID_REQUEST       = 'prebidRequest';
export const IMPRESSION_VIEWABLE  = 'impressionViewable';
export const SIZE_MAP_UPDATED     = 'sizeMapUpdated';

// --- Core → Worker events ---
export const CORE_READY           = 'coreReady';
export const SET_TARGETING        = 'setTargeting';
export const CLEAR_TARGETING      = 'clearTargeting';
export const TRIGGER_REFRESH      = 'triggerRefresh';
export const PREBID_RESPONSE      = 'prebidResponse';
export const RENDER_AD            = 'renderAd';
export const SET_PAGE_TARGETING   = 'setPageTargeting';
export const RECREATE_SLOT        = 'recreateSlot';
export const RENDER_PASSBACK      = 'renderPassback';

Placement Abstraction

The cross-frame placement extends the base placement with the same interface as a DFP placement. Hooks do not know whether they are operating on a local GAM slot or a remote one in a worker frame. This polymorphism is the key architectural decision that lets all existing auction, targeting, and refresh logic work unchanged.

setSlotTargeting(k, v) {
    this.slot.setTargeting(k, v);
}

clearSlotTargeting(k) {
    this.slot.clearTargeting(k);
}

getSizes() {
    return this.slot.getSizes();
}

setSlotTargeting(k, v) {
    targeting[k] = v;
    woofCore.send({
        action: SET_TARGETING,
        params: { elementId, key: k, value: v }
    }, workerId);
}

clearSlotTargeting(k) {
    delete targeting[k];
    woofCore.send({
        action: CLEAR_TARGETING,
        params: { elementId, key: k }
    }, workerId);
}

Same interface, different transport. The winnerTargetingHook and auctionDeliveryHook call placement.setSlotTargeting() and placement.clearSlotTargeting() without knowing whether the slot is local or remote.

Key Methods on crossFramePlacement

Refresh Flows

Refresh is the most complex cross-frame operation, with two distinct paths depending on the withDFP flag. Both paths must handle the core/worker split transparently.

Decision Tree

withDFP=1 — GAM Request Path

withDFP=0 — Direct Render Path

Key Differences: Network & Rendering Path

Both paths result in the same iframe depth (4 levels). The real advantage of withDFP=0 is fewer network round-trips: no GAM ad request, no PUC fetch, no SafeFrame initialization.

Viewability — IntersectionObserver Pipeline

Viewability tracking uses the browser's native IntersectionObserver API in the worker frame to detect when an ad slot becomes 50%+ visible (IO threshold 0.5). After a 1-second timer (IAB compliance), the worker sends an IMPRESSION_VIEWABLE woof message to the core, which triggers statistics events and bridges the signal to Prebid adapters via $pbjs$.markBidViewable().

Full Viewability Flow

Key Implementation Details

const viewTimers = new Map();

function observeViewability(elementId, container) {
    const observer = new IntersectionObserver((entries) => {
        for (const entry of entries) {
            if (entry.intersectionRatio >= 0.5) {
                viewTimers.set(elementId, setTimeout(() => {
                    woof.send({
                        action: IMPRESSION_VIEWABLE,
                        params: { elementId }
                    });
                }, 1000));
            } else {
                clearTimeout(viewTimers.get(elementId));
            }
        }
    }, { threshold: 0.5 });
    observer.observe(container);
}

function resetViewability(elementId) {
    clearTimeout(viewTimers.get(elementId));
    viewTimers.delete(elementId);
    // observer.unobserve(container) called internally
}

Secure Creative Relay (PUC)

Prebid's Publisher Universal Creative (PUC) uses postMessage to request the winning ad markup from the wrapper. In cross-frame mode, the PUC lives inside the worker's SafeFrame, but Prebid's cache lives in the core. The relay bridges this gap.

Why __pb_locator__ is Needed

Without the locator iframe in the worker, Prebid's PUC would climb the frame hierarchy all the way up to the core frame. When the core's resizeRemoteCreative() fires, it would try to find the ad container element — but the element lives in the worker frame, not the core frame. The resize would silently fail.

By inserting __pb_locator__ in the worker, PUC stops climbing at the worker level. The worker intercepts the Prebid Request, relays it to the core via woof, gets the response back, and forwards it to PUC. The worker also handles resizeAdSlot locally, where the DOM element actually lives.

// Insert the locator iframe so PUC stops at this frame
const locator = document.createElement('iframe');
locator.name = '__pb_locator__';
locator.style.display = 'none';
document.body.appendChild(locator);

// Listen for Prebid Request messages from PUC
window.addEventListener('message', (event) => {
    if (event.data.message === 'Prebid Request') {
        // Relay to core via woof
        woof.send({
            action: PREBID_REQUEST,
            params: { adId: event.data.adId }
        });
    }
});

Dual Rendering Path: PUC and FIF

The worker supports both SafeFrame (PUC) and Friendly Iframe (FIF) rendering paths. This is a deliberate architectural choice providing publishers with maximum flexibility:

GDPR / TCF Cross-Frame Consent

The TCF (Transparency and Consent Framework) API relies on a __tcfapiLocator iframe to establish a cross-frame communication channel. In cross-frame mode, the CMP may load in a different frame than the worker, requiring careful proxy setup.

How Consent Flows

9 Tested Scenarios

Test Coverage Matrix

14 spec files, 103+ test assertions. Every topology, timing edge case, and feature combination is covered. The specs run as part of the Playwright E2E suite.

Test Infrastructure

Live Demos

Each demo page tests a specific topology or feature. Open browser DevTools → Console and set localStorage.vpbdebug = 3 for full trace output. All demos are served from /cross-frame/scenarios/.

TCF / GDPR Demos

File Map

The entire cross-frame system is 1,423 lines across 7 source files. No external dependencies beyond @hbdev/woof for the postMessage transport.