Tech Reference

HBMP Public Events

A reference for publishers integrating with the HBMP wrapper. Subscribe to ad lifecycle events via vpb.on(eventName, callback). All events carry an elementId so events from different placements can be distinguished, and a timestamp for timing correlation.

// Wrap subscriptions in vpb.cmd.push so they run after the wrapper boots
vpb.cmd.push(function () {
    vpb.on('RenderEnded', function (data) {
        if (data.winner === 'hb') {
            console.log('HB won', data.elementId, 'cpm:', data.cpm);
        }
    });
});

Event Lifecycle Order

For a standard slot integrated with Google Ad Manager, events fire in this order:

PlacementCreated

→

AuctionStarted

→

AuctionEnd

→

RenderEnded

→

AdViewable

AdViewable fires asynchronously after RenderEnded when MRC viewability criteria are met (≥50% pixel visibility for ≥1 second). It may not fire if the user scrolls away first. For each refresh cycle, the sequence repeats from AuctionStarted onward.

1PlacementCreated

Fires once per ad slot, when the wrapper first registers the slot. For pages that recreate slots (e.g. SPA navigation), a new PlacementCreated fires after the previous placement is destroyed.

Field	Type	Description
`elementId`	`string`	DOM element ID of the ad slot
`hbUnitId`	`number`	HBMP ad unit ID
`gpId`	`string`	Global placement ID
`sizes`	`number[][]`	Array of `[width, height]` tuples
`timestamp`	`number`	`Date.now()` at creation

2AuctionStarted

Fires when an HB auction begins, before bid requests go out to demand partners.

Field	Type	Description
`auctionId`	`string`	Unique auction ID (matches the following AuctionEnd)
`placements`	`Array<{ elementId, hbUnitId }>`	All placements participating in this auction
`isRefresh`	`boolean`	`true` for refresh cycles, `false` for initial auction
`timestamp`	`number`	`Date.now()` at auction start

Use auctionId to correlate with the matching AuctionEnd.

3AuctionEnd

Fires when the auction completes and per-placement winners have been picked. Fires even when no bids were received (winner will be null).

Field	Type	Description
`auctionId`	`string`	Same ID as the preceding AuctionStarted
`placements`	`Array<{ elementId, hbUnitId, winner }>`	All placements with winner data
`placements[].winner`	`object \| null`	Winner info, or `null` if no HB bid was selected
`placements[].winner.cpm`	`number`	Bid CPM
`placements[].winner.bidder`	`string`	Winning bidder name
`placements[].winner.size`	`[number, number]`	Winning creative size
`timestamp`	`number`	`Date.now()` at finalization

A non-null winner here means an HB bid was selected for GAM targeting — it does NOT yet mean the ad rendered. The final HB vs GAM resolution happens in RenderEnded.

4RenderEnded

The unified impression event. Fires once per render with the final resolution of who served the ad.

Field	Type	Description
`elementId`	`string`	DOM element ID of the rendered slot
`winner`	`'hb' \| 'gam' \| 'empty'`	Who served the ad
`size`	`[number, number] \| null`	Rendered creative size
`adUnitPath`	`string \| null`	GAM ad unit path
`isRefresh`	`boolean`	`true` if this is a refresh render
`timestamp`	`number`	`Date.now()` at resolution
`cpm`	`number \| null`	Bid CPM when winner is 'hb', null otherwise
`bidder`	`string \| null`	Winning bidder name when winner is 'hb'
`dealId`	`string \| null`	PMP deal ID if the winning bid was a deal
`currency`	`string \| null`	Bid currency code (e.g. `'USD'`)

Winner Values

'hb' — A header-bidding creative was rendered
'gam' — Google Ad Manager served its own ad (house, direct sold, AdX, etc.)
'empty' — Slot rendered empty (no fill from any source)

When winner === 'gam' or 'empty', all bid-related fields (cpm, bidder, dealId, currency) are null.

5AdViewable

Fires when the rendered ad meets MRC viewability criteria (≥50% pixel visibility for ≥1 second). Fires asynchronously after RenderEnded, and may not fire if the user scrolls away before the threshold is met. Fires only for HB winners — GAM-served impressions do not produce this event.

Field	Type	Description
`elementId`	`string`	DOM element ID of the slot
`auctionId`	`string`	Auction ID this impression belongs to
`adUnitPath`	`string`	GAM ad unit path
`bidder`	`string`	Winning bidder name
`requestId`	`string`	Bid request identifier
`sizes`	`number[][]`	Rendered size as `[[width, height]]`
`cpm`	`number`	Bid CPM

Stage-by-Stage Data Availability

Stage	Event	elementId	auctionId	Winner Known	CPM
Placement registered	`PlacementCreated`	yes	no	no	no
Auction begins	`AuctionStarted`	yes	yes	no	no
Auction finalized	`AuctionEnd`	yes	yes	HB winner only	HB only
Slot rendered	`RenderEnded`	yes	no	HB / GAM / empty	HB only
Viewability met	`AdViewable`	yes	yes	HB only	yes