Skip to content
Audienzz Documentation

Placements

Overview

Section titled “Overview”

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
  • 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)

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

Loading

Section titled “Loading”

When the ad content is loaded but not yet rendered:

  • data-adnz-loaded="1" indicates content is ready
  • data-adnz-shown="0" shows it’s still not 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 ad is visible
  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 impression

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”