Skip to content
Audienzz Documentation

High Impact

High-impact groups allow mutually exclusive ad formats – such as skins, topscrolls, and midscrolls – to appear at most one at a time across multiple placements. A winning bid renders in its native placement and blocks the companion placements it declares. This enables premium, page-dominating creatives to compete fairly without conflicting with each other.

How It Works

Section titled “How It Works”

A high-impact bid does not run in its own contest. It becomes a candidate in the same allocator that resolves roadblocks, which picks the combination of claiming bids that maximises the revenue of the whole page — their CPMs plus the ordinary winners left on unclaimed placements. The only rule specific to high impact is the group.

  1. Bids that include a highImpact configuration are taken out of the normal per-placement auction and offered to the allocator.
  2. At most one bid per highImpact.group can be selected, even when their placements do not overlap. That is what makes the formats mutually exclusive.
  3. The selected bid renders in its original placement.
  4. All placements listed in its companions array are blocked and will not render their own ads.
  5. Everything not claimed keeps its ordinary winner.

Two things follow that a “highest CPM wins” reading would get wrong:

  • The top-CPM bid of a group can lose. If blocking its companions costs more than the bid is worth, the allocator prefers the ordinary winners, and no high-impact ad is shown at all. The one exception is a priority creative or an override bid, which is allocated before the revenue comparison and therefore blocks its companions whatever it bid.
  • A high-impact bid and a roadblock can both win, including on the same page and blocking the same companion, as long as neither claims the other’s main placement.

Configuration

Section titled “Configuration”

High-impact behavior is configured per bid using the highImpact field on the bid configuration object:

highImpact?: {
  group: string;
  companions: string[];
}
  • group: A string identifier that determines which bids compete against each other. All bids with the same group value participate in the same high-impact auction.
  • companions: An array of placement element IDs that should be blocked if this bid wins. These are placements that would conflict with the winning creative (e.g., a skin blocking sky placements).

Example

Section titled “Example”

Consider a page with three placements: a superbanner, a left sky, and a right sky. Two high-impact formats (skin and topscroll) compete for dominance, along with a sitebar bidder on the right sky.

// Superbanner placement with a skin bidder and a topscroll bidder
window.htag.api('1').definePlacement({
  elementId: 'superbanner',
  adUnitPath: '/123456/site/superbanner',
  sizes: [[728, 90]],
  mediaTypes: ['BANNER'],
  preloadGroup: 'main',
  bids: [
    {
      bidder: 'skinProvider',
      params: { placementId: 'skin-1' },
      sizes: [[728, 90]],
      mediaTypes: ['BANNER'],
      highImpact: {
        group: 'hi',
        companions: ['sky_left', 'sky_right'],
      },
    },
    {
      bidder: 'topscrollProvider',
      params: { placementId: 'topscroll-1' },
      sizes: [[728, 90]],
      mediaTypes: ['BANNER'],
      highImpact: {
        group: 'hi',
        companions: ['floor_ad'],
      },
    },
  ],
});


// Right sky placement with a sitebar bidder
window.htag.api('1').definePlacement({
  elementId: 'sky_right',
  adUnitPath: '/123456/site/sky_right',
  sizes: [[160, 600]],
  mediaTypes: ['BANNER'],
  preloadGroup: 'main',
  bids: [
    {
      bidder: 'sitebarProvider',
      params: { placementId: 'sitebar-1' },
      sizes: [[160, 600]],
      mediaTypes: ['BANNER'],
      highImpact: {
        group: 'hi',
        companions: [],
      },
    },
  ],
});

In this scenario, the skinProvider, topscrollProvider, and sitebarProvider bids all share the high-impact group "hi", so at most one of them can be selected:

  • If the skin bid is selected, sky_left and sky_right are blocked.
  • If the topscroll bid is selected, floor_ad is blocked.
  • If the sitebar bid is selected, no companions are blocked.
  • If none of them is worth what it would displace, all three placements keep their ordinary winners.

Losing bids’ placements fall back to any remaining non-high-impact bids.

Reload Protection

Section titled “Reload Protection”

Once a high-impact bid wins in a group, htag protects the result until the next page transition:

  • Timer-based refreshes are blocked: The winning placement and all its companions are marked as no-reload, preventing timer-based refresh cycles from replacing them. This is the same mechanism used by Roadblock.
  • Cross-auction memory: If other placements are explicitly refreshed (via refreshAds without pageTransition), any new high-impact bids in the same group are excluded. Only one high-impact winner per group is allowed per page lifecycle.
  • Page transition resets everything: When refreshAds is called with pageTransition: true (or without specific elementIds), the won-group memory is cleared and all groups are eligible for high-impact competition again.

Constraints

Section titled “Constraints”
  • Same preload group: put every participating placement in one preloadGroup so their bids arrive in the same request and can be weighed against each other. Unlike roadblock, htag does not enforce this — highImpact.companions is used exactly as written, so a companion in another group is still blocked, but a bid that never reached the same request cannot compete.
  • Do not combine with roadblock: configure highImpact or roadblockType on a bid, not both. htag does not reject a bid that carries both — it logs a warning and keeps the high-impact configuration, dropping the roadblock silently. The warning only appears with adnz_debug; on an ordinary production page the roadblock disappears without a trace.
  • A placement held by a priority or override bid is off limits: any high-impact candidate that would claim it is discarded and renders nowhere, rather than on top of the creative sitting there. When the high-impact bid is itself a priority creative or an override bid, it is not discarded — it is allocated ahead of the revenue comparison, as described in Roadblock.

Dynamic Configuration

Section titled “Dynamic Configuration”

High-impact settings can also be applied dynamically using the bid config extension macro embedded in ad content. This allows advertisers to configure high-impact behavior without changes to the base htag setup.

<!-- @@extend_bid_config:{"highImpact":{"group":"hi","companions":["sky_left","sky_right"]}}@@ -->

See Bid Config Extension for more details.

Section titled “Related Methods”
Section titled “Related Concepts”