Skip to content
Audienzz Documentation

Roadblock

Roadblock is a feature that allows for coordinated ad delivery across multiple placements. It ensures that related ads from the same campaign can be displayed together across different positions on a page.

How It Works

Section titled “How It Works”

When a roadblock is configured, htag treats a group of placements as a single unit for bidding purposes. If a bid with roadblock configuration wins the auction, it will:

  1. Display the winning ad in the primary placement
  2. Block competing ads in companion placements from render
  3. Potentially display companion creatives in those blocked placements

How the Winner Is Chosen

Section titled “How the Winner Is Chosen”

Roadblock is not decided bid by bid. htag runs one allocator over every bid that claims something beyond its own placement, plus every high-impact bid — those enter even with an empty companions list, because the group still has to stay exclusive. It picks the combination that maximises the revenue of the whole page.

A roadblock bid whose companions do not resolve claims nothing — its placement has no preload group, or the named companions are not defined at the current breakpoint. It does not enter the allocator at all and competes as an ordinary single-placement bid.

For a candidate combination the score is the sum of the claiming bids’ CPMs, plus the ordinary per-placement winners still standing on the placements nobody claimed. The combination with the highest score wins; if none of them beats leaving every placement to its ordinary winner, no roadblock is activated.

Bids that skip the revenue comparison

Section titled “Bids that skip the revenue comparison”

A priority creative and an ast_override_div override bid take their placement without competing on CPM. When such a bid also claims companions, its companions are blocked without a revenue comparison either: the prebid price of a directly sold skin says nothing about what the insertion order is worth, so scoring it against the skyscrapers it has to blank would always read as a loss and leave it rendering underneath them.

These bids are allocated first, and everything else then competes for what is left, against a baseline that already contains them. Two of them can still want the same placements — two direct deals sold into one group. The higher CPM takes the group and the other does not render at all; the loser is reported with console.error so it is visible on an ordinary production page.

Three consequences worth knowing:

  • Several roadblocks can win at once. They conflict only if they want the same main placement, if one’s companion is another’s main placement, or if they are high-impact bids in the same group. Two winners may block the same companion.
  • A tie goes to the roadblock. A combination that merely matches the all-ordinary revenue is accepted, not rejected.
  • A placement already won by a priority or override bid is off limits, and a candidate that would claim it is discarded — it renders nowhere rather than on top of the creative sitting there. This holds for roadblock and high impact alike. It cannot collide with the bid’s own win: a bid that claims companions never takes its placement outside the allocator.

Above 20 candidates in that comparison — the ones left after the bids that skip it have been allocated — htag stops searching exhaustively and picks greedily by best marginal gain, which is fast but no longer guaranteed optimal.

Choosing Companions

Section titled “Choosing Companions”

roadblockType decides which placements a winning bid blocks, always within the bid’s own preload group:

  • NONE — not a roadblock bid.
  • PARTIAL — the placements named in roadblockElementIds, minus any that are in a different preload group.
  • ALL — every other placement of the preload group.

A placement with an empty preload group has no group members, so a roadblock on it blocks nothing — and a bid that blocks nothing is not treated as a roadblock at all. Making it a roadblock winner would lock its placement for the rest of the page, costing every later refresh in exchange for blocking nobody.

Testing Roadblocks

Section titled “Testing Roadblocks”

When testing roadblock functionality, you can use the ast_override_div URL parameter to manually block specific placements. This can be useful for simulating roadblock behavior without having actual roadblock bids.

For more details, see the Debugging htag guide.

Dynamic Roadblock Configuration

Section titled “Dynamic Roadblock Configuration”

For advanced use cases, you can also configure roadblock behavior dynamically using bid config extensions. This allows advertisers to embed roadblock configuration directly in their ad content, enabling fine-grained control without modifying the base htag setup.

See Bid Config Extension for detailed information on dynamic roadblock configuration.

Roadblock vs High Impact

Section titled “Roadblock vs High Impact”

Roadblock and High Impact are both mechanisms for coordinated ad delivery across multiple placements, but they differ in how they evaluate bids:

Both go through the same allocator described above, so neither is a plain highest-CPM contest. What differs is how each declares itself:

  • Roadblock: the bid claims its own placement plus companions derived from its preload group. Use it when one advertiser should take a known set of positions.
  • High Impact: the bid joins a named group, and htag lets at most one bid per group win. Use it for mutually exclusive formats — skins, topscrolls, midscrolls — that must not appear together even when they sit on unrelated placements.

Configure only one of them on a bid. 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.

See High Impact for detailed information on high-impact groups.

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