Bid Config Extension

Overview

The Bid Config Extension feature allows advertisers to dynamically configure roadblock behavior directly within their ad content using embedded macros. This enables fine-grained control over how ads interact with other placements on the page without requiring changes to the base Htag configuration. When a bid wins an auction, Htag automatically scans the ad content for special macro patterns and applies the embedded configuration to extend the bid’s roadblock behavior.

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 to extend the bid’s roadblock behavior
4. Processes roadblock logic using the combined configuration

This allows advertisers to create dynamic roadblock campaigns that adapt their behavior based on 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.

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>

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

Htag continues to make intelligent profitability decisions. A bid with config extension will only win if its CPM is higher than the sum of CPMs from placements it would block.

Conflict Resolution

When multiple roadblock bids (including those with config extensions) target overlapping placements, Htag selects the most profitable option.

Preload Groups

Config extensions respect existing preload group boundaries. Roadblock behavior is limited to placements within the same preload group.

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
• Placements - Understanding ad placement configuration
• Preload Groups - How placements are grouped for coordination