Skip to content
  • There are no suggestions because the search field is empty.

Dynamic Placement Insertion

This article explains how to set up and configure Dynamic Insertion to automatically place ads into your page content based on CSS selectors and rules.

What is Dynamic Placement Insertion?

Dynamic Placement Insertion automatically places ad slots into your page content — without you having to hardcode ad divs into your HTML. Instead, you define CSS selectors and rules, and the system figures out where and how to insert ads based on those rules.

This is especially useful for content-heavy pages like articles, comment sections, and forums, where page structure varies and manually placing ads isn't practical. It also lets your team define insertion rules that apply consistently across your whole network.

Note: Dynamic Placement Insertion can inflate the Auction metric in your reports. This is expected: it happens because of auction splitting, which lets you report on custom params.

How It Works

  1. The system scans the page (DOM) for elements matching your configured CSS selectors.
  2. For each match, it checks your spacing rules, restriction selectors, and count limits.
  3. If everything checks out, an ad div is inserted at the position you specified (before, after, etc.).
  4. Ad sizes are filtered based on available container width, so layouts don't break.
  5. If multiple placements could match the same element, one is chosen based on priority.

If continuous background scanning is turned on, the system keeps re-scanning the page at a set interval. This is helpful for pages where content loads dynamically (like infinite scroll), since it can insert ads beyond what's currently in the viewport.

Getting Started

All you need to get going:

  1. Enable Dynamic Insertion on a placement.
  2. Add at least one target with a valid CSS selector.

That's it! The system will start inserting ads using the default settings. Everything else in this article is optional fine-tuning.

Where to find it: Publisher Accounts > Edit Account > Open Website > Open Placement > Built-in Settings > Dynamic Placement Insertion Settings

Expand the Dynamic Placement Insertion settings, toggle Enable dynamic insertion, and add a target selector (e.g. article > p). Save, and the placement starts inserting on the next page load.

Placement Settings

Once enabled on a placement, these settings control its behavior. All have sensible defaults — only adjust what you need.

Setting What it does
Enable dynamic insertion Turns Dynamic Placement Insertion on/off for this placement.
Priority Decides which placement wins when multiple match the same element. Priority 1 is highest and wins most often. Priority 2 is half as likely to be picked as Priority 1. Ties are broken randomly. Default: 1
Max inserts per page view Caps how many times this placement can appear on one page. Leave blank to use the global setting. Range: 1–30
Max allowed layout growth (%) Limits how much the page layout can grow when an ad is inserted. The system test-places each ad size and measures the height change; if it exceeds this % of the ad's height, that size is skipped. Set to 0 to block any growth. Range: 0–100, Default: 10
Platforms Restrict the placement to specific devices (Desktop, Mobile, Tablet). Leave blank for all platforms.
HTML Template for insertion The markup used to create the ad div. Default: <div id=""></div>. Can be customized, see below.
Target elements to insert at Defines where ads get placed. See Target Elements.
Shared spacing containers Enforces spacing across side-by-side containers. See Shared Spacing Containers.
Restriction selectors Elements ads should stay away from. See Restriction Selectors.
URL Blocklist Pages where this placement should never insert. See URL Blocklist.

Customizing the HTML Template

You can add extra markup around the ad div, for example:

HTML

<div id="" class="ad-wrapper" ="">   <div class="ad-label">Advertisement</div> </div>

Available template variables: (ad unit path), (full DOM element ID), and any field from the ad unit data (e.g. ).

 

Target Elements

Targets define where on the page ads get inserted. Add one by clicking + Add under Target elements to insert at.

Field Description
CSS Selector for target element Identifies candidate elements. E.g. p for all paragraphs, or .article > p:nth-of-type(3n) for every third paragraph in an article.
Minimum distance between ad-slots The minimum gap required between two dynamically inserted ads, so they don't cluster together.
Distance unit type Pixels, or Percent of viewport height.
Position of insert Where the ad lands relative to the matched element: After (most common), Before, Before First (first child), After Last (last child).

Container Settings

Containers let you scope and cap insertions within a specific parent element.

Field Description
Container CSS Selector The parent element to scope within, e.g. article or .content-section. The target selector will only match elements inside this container.
Max inserts per container Caps insertions within a single instance of the container. E.g. with container article and a max of 6, each article gets at most 6 ads — capped further by the global max if that's lower.

Restriction Selectors

Use these to keep ads a safe distance away from specific elements like headers, comment sections, or other sensitive content.

Add one by clicking + Add under Restriction selectors.

Field Description
CSS Selector for restriction element The element to avoid, e.g. .banner.
Minimum pixel distance The required minimum distance from that element.

Shared Spacing Containers

Use this to enforce spacing rules across sections that sit side by side on the page (e.g. columns in a grid), even when they're in separate DOM containers. If two ads share a common ancestor matching a spacing container selector, the spacing rule still applies between them.

URL Blocklist

Block Dynamic Placement Insertion on specific pages using URL patterns. Wildcards are supported.

Example: */sports/ blocks Dynamic Placement Insertion on any URL containing /sports/.

Path Resolution

Dynamic placements match against ad unit paths and where they occur on the page:

  • Exact match: the ad unit path exactly matches a resolved path on the page.
  • Wildcard match: uses * to match patterns (e.g. 3377764/*-box_banner), resolved based on previous static placement path resolutions.

Limitation: Wildcard-based dynamic insertion won't work if the wildcard path has never resolved to any static placement on the site. 

Shadow DOM Support

Dynamic Placement Insertion can insert ads inside Shadow DOMs and iframes if Shadow DOM support is enabled. Shadow roots are cached per context for faster querying, but note that enabling Shadow DOM requires extra DOM traversal, which has some performance impact.

 

Site-Level Configuration (Optional)

For control across an entire site, configure Dynamic Placement Insertion at the Prebid configuration level. These settings apply to all placements on the site.

Where to find it: Publisher Accounts > Edit Account > Site Prebid Configurations > Edit Configuration

Open your Prebid configuration and expand Dynamic placement insertion:

Setting Description
Enable continuous background scan If off, insertions are only found on first page load and on subsequent load_prebid calls. If on, the system re-scans every N milliseconds, backing off exponentially when no new insertion points are found.
Max dynamic inserts per page view Global cap across all placements. Range: 1–30
Scan interval (ms) How often the system checks for new insertion opportunities.
Look-ahead distance (px) How far below the current viewport the system looks for insertion candidates.
Global restrictor selectors CSS selectors that block insertion across all placements, e.g. div[id^="my_blocking_id"] to avoid custom div IDs.

Reporting Impact

Dynamic Placement Insertion may inflate the Auction metric in your reports. This happens because each dynamically inserted ad triggers auction splitting via AdUnit custom params — so the reported auction count depends on how many unique custom params are in play.

To track performance specifically, the system can set a custom parameter on dynamically inserted slots, so you can filter and segment Dynamic Placement Insertion results in your HB Analytics reports.

Debug Tools

Available in Live Preview mode only (to avoid leaving debug code in your live tag).

Debug Panel (Live Preview)

Lets you adjust settings in real time and preview the effect without saving:

  • Max inserts per page view
  • Look-ahead distance (px)
  • Scan interval (ms)
  • Debug flags (show borders, enable tracing, skip excluded check)
  • Max anchors per scan / max chunk duration (ms)
  • Per-placement settings (priority, max inserts, template, targets, restrictions)

Click Re-apply to test changes, or Clear All to reset.

Example Configuration

A typical setup for inserting ads into article content:

Target: insert an ad after every paragraph inside an article, with 100px minimum spacing, capped at 6 per article:

Setting Value
CSS Selector article > p
Minimum distance 100
Distance unit type Pixels
Position of insert After
Container CSS Selector article
Max per container 6

Restriction: stay at least 100px away from any banner:

Setting Value
CSS Selector .banner
Minimum pixel distance 100

URL Blocklist: don't insert on sports pages:

Setting Value
Blocked URL */sports/

Recommendations

  • Start with a small number of target placements and scale up gradually.
  • Use the debug tools to check behavior before going live.
  • Run an A/B test comparing pages with and without Dynamic Placement Insertion to measure the revenue impact.
  • Set sensible spacing rules to avoid ad stacking, which hurts viewability and UX.
  • Avoid overly broad CSS selectors: they make the system test more elements than necessary.
  • Use CSS containers to avoid scanning entire pages.
  • Expect the Auction metric to increase after enabling Dynamic Placement Insertion: this is normal, due to auction splitting.