Skip to content
Audienzz Documentation

Placements

Placements are the core building blocks of ad delivery in htag. A placement represents a specific location on your webpage where an ad will be displayed.

How It Works

Section titled “How It Works”

Each placement in htag consists of an HTML element (typically a div) where the ad will be rendered, along with configuration settings that determine how the ad will be displayed and which ads are eligible.

Configuration

Section titled “Configuration”

Placements are configured using the definePlacement method, which allows you to specify:

  • The element ID where the ad will be displayed
  • The ad formats supported (BANNER, VIDEO, etc.)
  • The sizes of ads that can be displayed
  • The bidders that can participate in the auction
  • Various other settings like lazy loading and preload groups

Placement Lifecycle

Section titled “Placement Lifecycle”

Placements progress through several stages, each reflected by HTML attributes that help with styling, debugging, and state tracking:

Initialization

Section titled “Initialization”

When a placement is first defined:

  • data-adnz-placement="1" marks it as an ad placement
  • data-adnz-effect-tag contains the effect tag, ad:{element ID}
  • Initial state attributes are set:
    • data-adnz-loaded="0" (content not yet loaded)
    • data-adnz-shown="0" (ad not yet visible)
    • data-adnz-creative-id="0" (no creative assigned)

data-adnz-placement="0" is the opposite direction: you set it on an element that exists but is not ready to be treated as a placement yet, and htag skips it until you remove it or set "1".

The element will receive minWidth and minHeight if none are already defined.

Loading

Section titled “Loading”

When htag starts putting the creative into the element:

  • data-adnz-loaded="1" means different things on the two paths, so do not read it as one signal: on the direct path it is written just before the iframe is appended, but on the Google path it is written when GAM’s slotResponseReceived arrives — before anything is inserted, and even when the response turns out to be empty.
  • data-adnz-shown="0" shows it’s still not counted as visible

For an ad to be requested for a placement, the placement element MUST be considered intersecting with extended browser viewport.

Impression

Section titled “Impression”

When the ad is finally rendered:

  1. data-adnz-shown="1" indicates the impression was counted
  2. data-adnz-winner contains the winning bidder’s name
  3. data-adnz-creative-id stores the creative ID (when available)
  4. data-adnz-query-id provides a unique identifier for the render attempt. It is regenerated whenever the creative ID is written, including the reset to "0", so it marks an attempt rather than a counted impression.

Other data-adnz-* attributes you may see

Section titled “Other data-adnz-* attributes you may see”

These are not lifecycle stages, and not all of them are written by htag itself:

Attribute Meaning
data-adnz-no-reload Written when a roadblock or high-impact result locks the placement — on the winner and on the companions it blocked, and on a placement still occupied by an earlier multi-slot win. A special ad format that opts out of auto-reloads suppresses them too, but writes nothing to the DOM, so absence of this attribute does not mean reloads are running.
data-adnz-reload-count How many times the placement has been reloaded. htag stops scheduling reloads once it reaches 999.
data-adnz-anzeige Present while the creative carries the “Anzeige” label. Written by the ad app, removed by the label’s own effect.
data-adnz-viewability-target Present on a hidden pointer element htag appends inside the placement; its value is the id of the element viewability should measure instead of the placement. Ad apps that render outside their placement set it through the frame they pass to htag — never by hand.

There is one attribute htag only reads: data-hydrated, which the publisher owns. See Hydration.

For an ad to be rendered in a placement, the placement element MUST be considered intersecting with extended browser viewport & visible by the checkVisibility() API, which considers an element visible when:

  • The element is connected to the DOM (isConnected is true)
  • The element is not hidden (hidden attribute is false)
  • The element does not have aria-hidden="true"
  • The element’s CSS display property is not none
  • The element’s CSS visibility property is not hidden
  • The element’s CSS opacity is greater than 0
  • The element’s dimensions are greater than 0

Custom Placement Workflow

Section titled “Custom Placement Workflow”

For sites that need to set up placements in a custom workflow, htag provides a definePlacements callback mechanism that’s automatically invoked during the configuration process. This reassignable callback can be customized for different workflows.

How It Works

Section titled “How It Works”

When using the configure method with placement data, the definePlacements callback is automatically invoked to process all placement configurations in bulk. By default, it processes each config as-is, but you can reassign this callback to implement custom transformation logic before placements are created.

Section titled “Related Methods”