> For the complete documentation index, see [llms.txt](https://docs.relevant-digital.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.relevant-digital.com/hb-manager/auction-behavior-and-optimization/dynamic-placement-insertion.md).

# Dynamic Placement Insertion

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.

{% hint style="info" %}
Dynamic Placement Insertion can increase the reported **Auction** metric. Auction splitting enables reporting on custom parameters.
{% endhint %}

### 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.

### Get 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.

**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.

{% hint style="success" %}
Start with one placement and one target selector. Add limits and restrictions after validating the result.
{% endhint %}

### 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="{{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:

```html
<div id="{{id}}" class="ad-wrapper" {{divAttribute}}="{{id}}">
  <div class="ad-label">Advertisement</div>
</div>
```

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**.

| 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.

Select **+ 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.

{% hint style="warning" %}
Wildcard insertion requires a prior static placement-path resolution on the site.
{% endhint %}

### 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**:

| 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

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 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](/hb-manager/auction-behavior-and-optimization/multivariate-a-b-testing-and-using-child-prebid-configurations.md).

### Related guides

* [Lazy Loading Ads in HB Manager](/hb-manager/auction-behavior-and-optimization/lazy-loading-ads-in-hb-manager.md)
* [Ad Refresh in HB Manager](/hb-manager/auction-behavior-and-optimization/ad-refresh-in-hb-manager.md)
* [Auction behavior and optimization](/hb-manager/auction-behavior-and-optimization.md)


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.relevant-digital.com/hb-manager/auction-behavior-and-optimization/dynamic-placement-insertion.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.