Skip to content
Audienzz Documentation

bindFormat

The bindFormat method binds a registered special ad format to a placement. It is the single coupling point between a trigger (which decides when a format should run) and the format itself (which defines what it does) — so the same format can be bound to many different conditions.

Syntax

Section titled “Syntax”
// Declarative bind (recommended) — predicate decides when to apply
window.htag.api('1').bindFormat(divId, name, when);


// Imperative — apply immediately
window.htag.api('1').bindFormat(divId, name);

Parameters

Section titled “Parameters”
  • divId (string): The placement element id to bind the format to.
  • name (string): The name of the format to bind, e.g. 'sidebar'.
  • when (function, optional): A predicate (winners, divId) => boolean that receives the auction’s winners map (keyed by element id) and the bound divId, so it can check its own placement’s winner via winners[divId] without hardcoding the id. When provided, the format is applied on every auction.resolved for which the predicate returns true, instead of immediately.

Behaviour

Section titled “Behaviour”
  • The placement must already be defined. bindFormat binds only to a placement that has been registered with definePlacement; a bind for an unknown placement is a no-op. Triggers run as RawJS at start() (after placements are defined), so this is the normal order — bind a placement, not a not-yet-defined id.
  • Without when, the format is applied right away (or buffered until its app loads — see below).
  • With when, Htag binds the format declaratively: it warms the format’s CDN app at header start — before any auction — by importing and running it immediately (more than a prefetch: the app self-registers on load), so it is already registered by the time the winning ad renders, avoiding a “native size then resize” flash. It then applies the format whenever when(winners, divId) is true on auction.resolved. If the bind attaches after an auction already resolved (e.g. a TCF-deferred trigger), it also evaluates when immediately against the most recent (still-current) auction winners, so it applies without waiting for the next auction. The predicate (the condition) lives at the call site, so the same format can be bound to many different conditions.
  • If the format is not registered yet when it should apply, Htag lazily loads its CDN app (htag-format-<name>) once, buffers the call, and applies it as soon as the app registers the format. A buffered call is dropped if the placement refreshes before the app loads, so a format never lands on a newer ad.
  • The format’s teardown is wired into the Effects system, so it is reverted automatically when the ad reloads or clearEffects runs for that placement.

Example

Section titled “Example”

A trigger (typically delivered as a RawJS snippet) binds the format with the condition that decides when it runs:

window.htag.api('1').bindFormat('sky', 'sidebar', (winners, divId) => {
  const bid = winners[divId]?.bid;
  return Boolean(bid && bid.dealId === 2287270);
});
Section titled “Related Methods”