Dynamic Placement Insertion
Automatically insert HB Manager ad placements into page content with CSS selectors, spacing rules, and placement-level controls.
Dynamic Placement Insertion adds ad slots to page content using CSS selectors and rules. It removes the need to hardcode ad containers in your HTML.
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.
How it works
The system scans the page (DOM) for elements matching your configured CSS selectors.
For each match, it checks your spacing rules, restriction selectors, and count limits.
If everything checks out, an ad div is inserted at the position you specified (before, after, etc.).
Ad sizes are filtered based on available container width, so layouts don't break.
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.
Get started
All you need to get going:
Enable Dynamic Insertion on a placement.
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.
Path: 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.
Start with one placement and one target selector. Add limits and restrictions after validating the result.
Placement settings
Once enabled on a placement, these settings control its behavior. All have sensible defaults — only adjust what you need.
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="{{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.
Customize the HTML template
Add markup around the ad container when needed:
Available template variables include:
{{id}}— ad unit path.{{divId}}— complete DOM element ID.Any ad unit data field, such as
{{placementTypeName}}.
Target elements
Targets define where ads are inserted. Select + Add under Target elements to insert at.
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.
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.
Select + Add under Restriction selectors.
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.
Wildcard insertion requires a prior static placement-path resolution 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
For control across an entire site, configure Dynamic Placement Insertion at the Prebid configuration level. These settings apply to all placements on the site.
Path: Publisher Accounts → Edit Account → Site Prebid Configurations → Edit Configuration
Open your Prebid configuration and expand Dynamic placement insertion:
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
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:
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:
CSS Selector
.banner
Minimum pixel distance
100
URL Blocklist: don't insert on sports pages:
Blocked URL
*/sports/
Recommendations
Start with few targets. Scale after validating placement and page performance.
Use Live Preview before publishing changes.
Set spacing rules to prevent clustering and protect viewability.
Use precise selectors and containers to reduce unnecessary DOM scanning.
Measure revenue impact with multivariate A/B testing.
Related guides
Last updated
Was this helpful?