Bid Config Extension

The Bid Config Extension feature lets advertisers configure per-creative behaviour directly within their ad content using an embedded macro, without changing the base htag configuration. htag scans the ad content for the macro and applies the embedded configuration on top of the placement’s own configuration. Three mechanisms can be extended this way: roadblock behaviour, high-impact competition and frequency capping.

How It Works

The feature uses a special macro pattern embedded in ad content:

@@extend_bid_config:{"roadblockType":"PARTIAL","roadblockElementIds":["sidebar","footer"]}@@

When htag processes a winning bid, it:

1. Scans the ad content for the @@extend_bid_config:...@@ pattern
2. Extracts and validates the JSON configuration
3. Applies the configuration on top of the placement’s own bid configuration
4. Processes roadblock, high-impact and frequency-cap logic using the combined configuration

A key only overrides the placement’s own configuration when it carries a value. {"roadblockType":null} does not cancel a roadblock configured on the seat in Adconsole — an extension can add behaviour to a creative, not take away what was booked for it.

This allows advertisers to create campaigns whose behaviour adapts to the specific creative being served.

Configuration Options

roadblockType

Defines how the winning bid should interact with other placements:

• "NONE" - No roadblock behavior (default)
• "PARTIAL" - Block only specific placements defined in roadblockElementIds
• "ALL" - Block all other placements in the same preload group

roadblockElementIds

An array of element IDs that should be blocked when roadblockType is set to "PARTIAL".

{
  "roadblockType": "PARTIAL",
  "roadblockElementIds": ["sidebar-ad", "footer-banner", "inline-ad-2"]
}

Note: This property is only used when roadblockType is "PARTIAL". It’s ignored for other roadblock types.

roadblockSubscribeToCompanionVisibility

A boolean that determines whether this placement should be considered visible when any of its companion placements become visible.

{
  "roadblockType": "PARTIAL",
  "roadblockElementIds": ["companion-1", "companion-2"],
  "roadblockSubscribeToCompanionVisibility": true
}

This is useful for tracking visibility across related placements in a roadblock campaign.

highImpact

An object that configures high-impact behavior for the bid. High-impact groups allow mutually exclusive ad formats to compete in a single auction across multiple placements.

• group (string) - Identifier for the high-impact group. All bids sharing the same group compete against each other.
• companions (string array) - Placement element IDs to block if this bid wins.

{
  "highImpact": {
    "group": "hi",
    "companions": ["sky_left", "sky_right"]
  }
}

Note: Use highImpact or the roadblock properties (roadblockType, roadblockElementIds), not both. htag does not reject an extension 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.

frequencyCapLabel

A frequency-cap label for the creative. It must match [A-Za-z0-9_.:-]{1,64} and a corresponding cap must be configured with setFrequencyCaps.

{
  "frequencyCapLabel": "summer-2026"
}

Usage Examples

Basic Partial Roadblock

Block specific sidebar and footer ads when the main banner wins:

<div class="banner-ad">
  <img src="banner-creative.jpg" alt="Advertisement" />
  <!-- @@extend_bid_config:{"roadblockType":"PARTIAL","roadblockElementIds":["sidebar-ad","footer-banner"]}@@ -->
</div>

Full Page Takeover

Block all other ads in the preload group:

<div class="takeover-ad">
  <video src="takeover-video.mp4" autoplay muted></video>
  <!-- @@extend_bid_config:{"roadblockType":"ALL"}@@ -->
</div>

Companion Visibility Tracking

Create a roadblock that tracks visibility across companion placements:

<div class="main-creative">
  <iframe src="interactive-ad.html"></iframe>
  @@extend_bid_config:{"roadblockType":"PARTIAL","roadblockElementIds":["companion-1","companion-2"],"roadblockSubscribeToCompanionVisibility":true}@@
</div>

High-Impact Format

Configure a bid as a high-impact skin that blocks sky placements:

<div class="skin-creative">
  <div class="skin-wrapper">...</div>
  <!-- @@extend_bid_config:{"highImpact":{"group":"hi","companions":["sky_left","sky_right"]}}@@ -->
</div>

Conditional Roadblock

Different roadblock behavior based on creative variant:

<!-- Premium creative with full roadblock -->
<div class="premium-creative">
  <div class="rich-media-ad">...</div>
  @@extend_bid_config:{"roadblockType":"ALL"}@@
</div>

<!-- Standard creative with partial roadblock -->
<div class="standard-creative">
  <img src="standard-banner.jpg" alt="Ad" />
  @@extend_bid_config:{"roadblockType":"PARTIAL","roadblockElementIds":["competing-banner"]}@@
</div>

Integration with Existing Roadblocks

The bid config extension works seamlessly with htag’s existing roadblock functionality:

Profitability Calculation

A bid carrying a config extension goes through the same allocator as any other multi-slot bid: htag picks the combination of claiming bids that maximises total page revenue, counting the ordinary winners left on unclaimed placements. An extension does not give the bid priority — if what it would block is worth more than the bid, it simply is not selected. See Roadblock.

The exception is a creative that is also on the priority list, or one forced through ast_override_div: it is allocated before the revenue comparison, so the extension’s companions are blocked whatever it bid.

Conflict Resolution

Several claiming bids can win together, including two that block the same companion. They conflict only when they want the same main placement, when one’s companion is another’s main placement, or when both are high-impact bids of the same group.

Preload Groups

roadblockElementIds is intersected with the bid’s own preload group, so a companion outside that group is silently dropped and a placement with no preload group gets no companions at all. When that leaves nothing, the extension’s roadblock claims nothing and the bid competes as an ordinary single-placement bid. highImpact.companions is not filtered this way — it is used exactly as written, and a high-impact bid enters the allocator even with an empty list.

Best Practices

JSON Formatting

• Use valid JSON syntax in the macro
• Escape quotes when necessary: @@extend_bid_config:{\"roadblockType\":\"PARTIAL\"}@@
• Keep JSON compact to minimize ad content size

Element ID Management

• Use consistent, descriptive element IDs across your site
• Coordinate with your development team to ensure element IDs match placement configurations
• Test roadblock behavior across different page layouts

Performance Considerations

• The macro parsing adds minimal overhead to ad processing
• Invalid JSON in macros is logged but doesn’t break ad rendering
• Consider the impact of blocking multiple placements on overall revenue

Testing and Debugging

• Use htag’s debugging tools to verify roadblock behavior
• Test different creative variants to ensure proper macro functionality
• Monitor logs for macro parsing errors or warnings

Error Handling

The system gracefully handles various error conditions:

• Invalid JSON: Logged as an error, bid processes normally without extension
• Missing properties: Only valid properties are applied, invalid ones are ignored
• Wrong data types: Properties with incorrect types are ignored
• Empty configuration: Macro with no valid properties is ignored

Related Concepts

• Roadblock - Core roadblock functionality
• High Impact - Mutually exclusive ad format competition
• Placements - Understanding ad placement configuration
• Preload Groups - How placements are grouped for coordination