Skip to content
Audienzz Documentation

Special Ad Formats

Special ad formats are pluggable visual behaviours that transform how a winning ad is displayed — for example a sidebar that expands the creative to fill the side of the viewport. They are designed around a strict separation of concerns, so a format is reusable and the decision of when to apply it stays with the publisher.

The three layers

Section titled “The three layers”
  1. The format — a small, self-contained behaviour. It only knows how to apply itself to a placement and whether it tolerates auto-reloads. Each format lives in its own CDN app named htag-format-<name> (one format per app) and self-registers via registerFormat when loaded.
  2. The trigger — a condition that decides when a format should run, delivered as a RawJS snippet. It calls bindFormat with a predicate over the auction winners (a dealId, creative, bidder — anything). Because the condition lives here, the same format can be bound to many different triggers.
  3. Htag core — provides the registerFormat / bindFormat registry, lazily loads a format’s app on first use, and ties the format’s teardown into the Effects system so it is reverted on reload.

Lazy loading by convention

Section titled “Lazy loading by convention”

There is no feature flag. A declarative bindFormat(divId, name, when) bind warms the format’s app at header start — it imports and runs the app immediately (more than a prefetch: the app self-registers on load), so the format is already registered when the winning ad renders. Otherwise the first time a format must apply, Htag imports https://cdn.adnz.co/htag-format-<name>/htag-format-<name>.js (once), the app self-registers, and the buffered call is applied. A format app is therefore fetched only on pages where a trigger binds it — nothing is loaded otherwise.

Reload control

Section titled “Reload control”

A format declares allowScheduledReload(). While a format with allowScheduledReload() === false is active on a placement, Htag suppresses automatic (timer/scheduled) reloads of that placement — checked both when a reload is scheduled and again when it fires. An explicit refreshAds still tears the format down and re-runs the auction. Formats never touch reload-related DOM attributes directly; reload behaviour is owned through allowScheduledReload().

Teardown

Section titled “Teardown”

applyFormat returns a teardown function. Htag registers it as an effect tagged ad:{divId}, so when the ad reloads or clearEffects runs for that placement, the format is reverted automatically. Formats should also self-heal — stop tracking — if their placement disappears.

Example: the sidebar format

Section titled “Example: the sidebar format”

The sidebar format (app htag-format-sidebar) expands the winning ad’s creative iframe to fill the space from the placement’s left edge to the viewport’s right edge and the full viewport height, and opts out of auto-reloads. A publisher binds it to specific deals with a trigger:

// Delivered as a RawJS snippet. The predicate decides when the format applies; the bind also warms the format's
// app at header start so there is no render flash when the ad arrives.
window.htag.api('1').bindFormat('sky', 'sidebar', (winners, divId) => {
  const bid = winners[divId]?.bid;
  return Boolean(bid && [2287270].includes(bid.dealId));
});
Section titled “Related”