Dynamic Targeting with DOM Selectors

Use our dynamic targeting feature to keep full control over the outstream player placement.

Instead of manually placing the outstream player in your HTML, dynamic targeting allows you to use DOM selectors to:

1. Place the outstream player after the preferred HTML element; or
2. Append the outstream player to the preferred HTML element.

This feature is particularly useful when:

• You use a CMS (such as WordPress) where you cannot manually insert HTML into the middle of an article;
• Your pages are dynamically generated and the content structure may vary;
• You want consistent ad placement relative to content (e.g., always after the 3rd paragraph) across many pages without editing each page template.

1.0 | Select a Targeting Mode

To apply dynamic targeting for your outstream ad unit:

• Open “Ad Services”;
• In the left panel, click “Ad Units”;
• Select an existing outstream ad unit or create a new one (learn more about creating an ad unit);
• Scroll down to “Placement Options”:

By default, the player will be placed at script position:

To enable dynamic targeting, select one of the following options:

• After matching DOM element: Place the player directly after the first element matching the provided DOM selector.
• Append to matching DOM element: Append the player directly to the first element matching the provided DOM selector.
• Halfway matching DOM elements: Place the player after the number of items matching the DOM selector divided by two (rounded down). For example: when 7 elements match the selector, the player will be placed after the 3rd element.
• After matching DOM element below the fold: The placement logic searches for the last matching element whose top edge starts above the page fold (i.e., the last element that is at least partially visible in the initial viewport without scrolling). The player is placed after that element. Note: if no matching elements start above the fold, the player will not be placed.
• After matching DOM element below the fold, or the last element found: Same as above, with the exception that if no matching elements start above the fold, the player will be placed after the last matching element found instead.

When using one of the dynamic placement options listed above, simply place the embed code at the bottom of the page. When the code is executed, the ad unit will be placed based on the specified DOM selector.

2.0 | Select a DOM Element

A DOM selector enables you to target HTML elements based on their:

• Type
  • <p>
  • <div>
  • Etc.
• Attributes
  • ID (e.g. #content)
  • Class (e.g. .article-section)
  • Etc.
• Position in the DOM
  • :nth-of-type(n)
  • :last-of-type
  • Etc.

Our player supports standard CSS selectors as listed by MDN documentation. In the Placement options, enter your DOM selector:

3.0 | Select a DOM Element: Using Developer Tools

If you’re unsure and need to find a specific element on an existing page, use your browser’s developer tools to find the selector for your element:

• Open developer tools in your browser;
• In the developer tools panel, click the “Selector” button;

• Select the element you’d like to target;
• In the Elements tab of the developer tools: right-click to open the “Copy” options and select “Copy selector”;

• Keep in mind: the value copied to your clipboard is the most specific selector of your target element. This selector may therefore not match elements on other pages.

4.0 | Select a DOM Element: Example

Let’s say we want to place an outstream ad unit within the article content. The screenshots below walk through how to narrow down to the ideal selector.

In the screenshot below, the selected element #content div is too large. When placing the outstream ad unit after the #content div, it would appear at the very bottom of the page, below the fold (generally not what we’re looking for).

In the screenshot below, we have selected a div nested one layer deeper with the following selector: .siteorigin-widget-tinymce.textwidget. This element is still too large, resulting in an ad unit placed too low on the page.

In the screenshot below, we have arrived at an element nested one layer deeper, specifically the third <p> element on the page: an optimal placement for our use case.

Outstream ad units will most likely be placed on many pages with various content lengths. Some pages might therefore not contain more than 3 <p> elements. In those cases, we would like the outstream ad unit to be placed after the last <p> element as a fallback.

In the Placement options:

• Select “After matching DOM element”
• Provide the following DOM selector: p:nth-of-type(3), p:last-of-type

Syntax explanation:

• p:nth-of-type(3): The 3rd <p> element within its parent container will be targeted (indexing starts at 1). Read more.
• , (comma): A comma creates a selector union: both selectors are always evaluated, and all matching elements are collected. Because the player uses the first match in document order, p:nth-of-type(3) takes priority when it exists. When it does not match anything, p:last-of-type becomes the only match and acts as a fallback.
• p:last-of-type: The last <p> element within its parent container will be targeted. Read more.

Additional examples:

#article-identifier p.paragraph

• # is used for DOM element id attributes
• . is used for DOM element class attributes
• p is used to select all <p> elements

div.article p:nth-of-type(4), div.article p:last-of-type

• div.article p:nth-of-type(4) will select the 4th <p> element within <div class="article">
• , div.article p:last-of-type will select the last <p> element within <div class="article">; acts as a fallback when p:nth-of-type(4) matches nothing