Press enter to see results or esc to cancel.

Plugin Settings

Plugin settings are located on the last tab . This tab contains sub-tabs depending on the plugin type (free or Pro).

ad inserter plugin settings

General

Tab General contains general plugin settings and additional settings for insertion.

ad inserter settings

PRO License key

Here you need to enter license key for Ad Inserter Pro you got in the email.

Plugin priority

Default Ad Inserter plugin priority (processing order) is 99999. It is used to specify the order in which the plugin functions are executed. Lower numbers correspond with earlier execution. You can change this value if you have problems with the processing order of other plugins.

Output buffering

Insertion position Above header and server-side insertion Before/After HTML element need special code processing and are available only when you enable Output buffering, however, this may not work with all themes. Output buffering means that the code generated by the WordPress (including your theme and plugins) is buffered (saved) and then processed.

To check if your theme supports output buffering enable it here, then go to homepage and enable Show positions debugging function (Ad Inserter menu in top admin bar). If you see OUTPUT BUFFERING (and ABOVE HEADER) bar then output buffering works as expected.

ad inserter output buffering

Syntax highlighting theme

You can choose between many syntax highlighting themes (light and dark).

Minimum user role for individual exceptions editing

By default Ad Inserter individual exceptions on posts/static pages are enabled only for administrators. You can define minimum user role for page/post Ad Inserter individual exceptions editing in Posts/pages editor.

Sticky widget mode

There are two modes for sticky widgets (or sticky sidebars) available as Sticky widget mode. CSS mode is the best approach but may not work with all themes. Use JavaScript mode only when CSS mode does not work. Check Widgets for more.

Sticky widget top margin

Here you can define sticky widget top margin to precisely define top position where the first sticky widget will stop.

Dynamic blocks

Ad Inserter supports server-side and client-side dynamic blocks (blocks that change like ad rotation and block that are black or white-listed by IP address, cookie, referrer or country). If you are using caching you should use client-side (or server-side using W3 Total Cache if you are using this caching plugin) but you need to be aware of how it works. Please check section Caching for details.

When you set Dynamic blocks to client-side the plugin will generate code that will be executed in the visitor’s browser. Ad Inserter supports two client-side methods for dynamic blocks: Client-side show and Client-side insert. Both generate Javascript code to run in the browser. Client-side show uses CSS to hide unwanted code while Client-side insert uses Javascript to insert code when needed or enabled.

Client-side show is fine with banners as they are all loaded and only shown when needed but some adverts (like AdSense) might not work properly or can’t be used this way and you might violate their Terms of Service – use Client-side insert mode in such case. On the other hand, Client-side insert can’t work with some ad codes (e.g. some Amazon ads) that use old JavaScript method document.write which can’t be used asynchronously (after the page is loaded and created).

Functions for paragraph counting

Standard PHP functions for paragraph counting are faster and work in most cases, use Multibyte functions only if paragraphs are not counted properly on non-english pages.

Multibyte PHP functions for paragraph counting are much slower than standard ones. Use them only when insertion between paragraphs does not work properly on non-english pages.

No paragraph counting inside

Here you can define tags inside which paragraphs (in posts on pages) will not be counted when using Before/After paragraph automatic insertion.

Ad label

Ad label defines text (or HTML code) which can be displayed above ads. To enable ad label above the ad go to block for this ad, click on the Misc button and then on the Display tab check Ad label.

ad inserter misc display

If you configured only text for Ad label then the following code will be added above ad code:

<div class="code-block-label">AD_LABEL_TEXT</div>

Optionally you can define style for labels (assuming block class name is code-block):

<style>
.code-block-label {
  font-size: 12px;
}
</style>

You can put this style code into your theme’s style.css file or in the Header section.  Instead of defining only label text you can also define HTML code for ad label, for example: <div style="font-size: 12px;">Advertisement</div>

Max blocks per page

Here you can limit maximum number of blocks per page. If you want some block to count for maximum blocks per page enable Max blocks per page for that block (button Misc / tab Insertion). Some themes call the_content hook more than once. This hook is used for insertions into post/page content. In such case the blocks might be inserted (from the plugin perspective) more than configured – usually only the last call is the wanted call for insertion. To have accurate counter for block insertions in such cases you need to eliminate insertion in unwanted calls of the_content hook. Try one of the following options:

  • check Insert only in the loop (button Misc / tab Insertion)
  • set Filter for Content processing to the wanted call of the_content hook (button Misc / tab Filter)

PRO Main content element

Stick to the content horizontal position displays sticky ads next to the left or right edge of page content (as sidebar). In most cases the plugin will automatically calculate page content width (assuming that the content is centered horizontally) and position ads automatically. However, some themes may require to define Main content element manually. Here you can enter either CSS selector (#id or .class) of the main (outermost) page element or content width in pixels (numerical value only).

PRO Lazy loading offset

This offset defies how close to the viewport (in pixels) lazy loading ad must be in order to be loaded. Lazy loading can be enabled on tab Display (button Misc).

Block class name

Block class name defines class that is used in wrapping divs. Wrapping divs for code blocks have code-block and code-block-n classes which can be used for custom styles. Both classes can be disabled if needed. If you are using client-side device detection (CSS media queries) then the wrapping div for the code block will have also some of the following classes: ai-viewport-1, ai-viewport-2,… ai-viewport-n.

<div class="code-block code-block-n" style="margin: 8px 0; clear: both;">
 BLOCK CODE
</div>

By default each code block uses inline styles for alignment. You can disable them to use alignment classes instead.

Viewports

Viewport settings are located on the last tab 

ad inserter plugin settings

Viewports are used for client-side device detection and for responsive AdSense ads – ad sizes fixed by viewport.

ad inserter settings viewports

Up to 3 viewport names and widths can be defined (PRO supports up to 6 viewports). Default values are:

  • Desktop: 980 pixels or more
  • Tablet: from 768 pixels to 979 pixels
  • Phone: less than 768 pixels

Hooks

Custom hook settings are located on the last tab 

ad inserter plugin settings

Ad Inserter supports also automatic insertion at custom positions where hooks are used using the do_action () WordPress function. The number of custom hooks depends on the license type (free Ad Inserter supports 2 custom hooks).

ad inserter custom hooks

Hook name is a name that is used in the Automatic insertion selection, action is the name that is used in the do_action () WordPress function used in the theme and priority is the hook priority (lower number means earlier processing). You can use ANY hook that is implemented by your theme or added by plugins. Of course you can create a child theme and implement your own hooks. After you save settings you get new positions for automatic insertion.

ad inserter custom hook insertion positions

Header and Footer

Header and Footer code settings are located on the last tab 

ad inserter plugin settings

  • Header code (code in the <head> section)
  • Footer code (code before the </body> tag)

You can also use shortcodes for code blocks to insert page-specific code, for example, to insert the code only on specific pages (either use [adinserter code="BLOCK_NUMBER"] or set block style to No wrapping to insert only block code without wrapping div) and you can use [ADINSERTER AMP] to separate code for normal and AMP pages – the code above the separator will be inserted on normal pages, the code below the separator will be inserted on AMP pages.

Don’t forget to enable header/footer code – button next to PHP button.

Example of Header code (code in the <head> section):

ad inserter header

Example of Footer code (code before the </body> tag):

ad inserter footer

Page-specific Header and Footer code

Normally the code for Header and Footer will be inserted on all pages. In some cases you may need to insert code in header or footer only on specific pages or to exclude insertion on some pages. There are basically two approaches for this. In both cases you need to configure one code block with the code you need to insert. Set Alignment and Style to No wrapping (this code needs no wrapping div), enable wanted page types (normally all page types should be enabled: posts, pages, homepage,…) and configure other block settings to limit insertions (in most cases you’ll need lists for this).

  • Approach with shortcodes: set Automatic insertion to Disabled, enable shortcode for this code block (button Manual) and put shortcode for the code of this block into Header or Footer code window: [adinserter code="N"]. This shortcode for block N will insert only the block code without wrapping div. If you are using individual exceptions please note that shortcodes IGNORE post/static page exception settings! To force checking individual post/page exceptions use shortcode [adinserter code="N" check="exceptions"].
  • Approach with Automatic insertion: set Automatic insertion to Header (code in the <head></head> section) or Footer (code before the </body> tag). Normally, position for automatic insertion Header does not exist and needs to be created. Go to tab  / tab Hooks and create and enable hook with name Header and action wp_head. After you save settings you’ll get Header position for automatic insertion for each code block. Please note that this Header position for automatic insertion has nothing to do with the header of your theme. This is HTML page header – code in the invisible <head></head> section.
Raw HTTP Header

You can also insert raw HTTP header lines using [ADINSERTER HTTP] shortcode separator. Header code above the separator will be inserted into HTTP header. You can also use PHP code and functions for HTTP header (header (), setcookie (),…). Each raw header line must contain colon. For example, the following header code block:

<?php
header ('AI-PHP-header1: PHP1');
header ('AI-PHP-header2: TWO');
echo 'AI-PHP-header3: A?';
setcookie ('utm_test', 'ad_inserter', time() + (1 * 60), COOKIEPATH);
?>
AI-header1: test1
AI-header2: test2
TEST
[ADINSERTER HTTP]
<!-- NORMAL HEADER CODE -->
[ADINSERTER AMP]
<!-- AMP HEADER CODE -->

would insert the following raw HTTP header lines:

AI-PHP-header1: PHP1
AI-PHP-header2: TWO
AI-PHP-header3: A?
Set-Cookie: utm_test=ad_inserter; expires=Sat, 14-Oct-2017 18:56:09 GMT; Max-Age=60; path=/
AI-header1: test1
AI-header2: test2

PRO Geolocation

Geolocation settings are located on the last tab 

ad inserter plugin settings

Geolocation (or GEO targeting) means determining visitor’s country and display targeted ads. Country is determined from the IP address of the website visitor. IP/country address database is updated automatically each month. If you have Business or Corporate Pro license you can choose between Webnet77 (default) and MaxMind geolocation database (Ad Inserter Pro will download and useGeoLite2 data created by MaxMind). Ad Inserter Pro supports also CloudFlare geolocation.

ad inserter geolocation

Default Webnet77 database is lightweight (around 2 MB) but slightly less accurate than MaxMind. If you select MaxMind database and enable automatic updates Ad Inserter Pro will download and use GeoLite2 database (around 60 MB, data created by MaxMind).

When you select MaxMind for geolocation database (Business or Corporate Pro license) and save settings, Ad Inserter Pro will show additional options and display a warning message because the database file will not be found. Now you can either manually download and extract the file (useful if you use commercial MaxMind database) or set Automatic database updates to Enabled. In such case Ad Inserter Pro will download GeoLite2 database and the warning should disappear. Default database location is in the uploads folder but you can define any location on the server. If you use absolute path it must start with a slash.

ad inserter geolocation maxmind

In some cases MaxMind may limit downloading and you may get error message when the plugin tries to download the file. In such case you can manually download the file, extract it (use any gzip tool) and upload GeoLite2-City.mmdb file to your hosting server to the configured location.

MaxMind GeoLite2 database (gziped) for manual download:
http://geolite.maxmind.com/download/geoip/database/GeoLite2-City.mmdb.gz

GEO targeting Groups

You can define up to 6 country groups for easier GEO targeting of individual code blocks.

ad inserter geolocation groups

PRO Exceptions

Exceptions settings are located on the last tab 

ad inserter plugin settings

Here you can open page with exceptions, open editor to edit exceptions, clear exceptions for specific block, clear exceptions for specific post/page or clear all exceptions (click on the cross in the top right corner).

ad inserter exceptions editing pro

PRO Tracking

Tracking settings are located on the last tab 

ad inserter tracking settings

To globally enable tracking click on the button with green icon and save settings. There are two independent tracking modes: Internal and External.

  • Internal tracking means using internal plugin statistics. Each event (impression or click) is sent to to the plugin (Ajax request) and you can use internal statistics described below to analyze impressions, clicks, CTR, A/B tests. This may introduce additional load to your database on websites with high traffic.
  • External tracking means using tracking via Google Analytics or Matomo (formerly Piwik) events. Each event (impression, click or ad blocking) is sent to the external tracking service where you can analyze them. Make sure you have Google Analytics or Matomo tracking code installed. You can place the tracking code into Header code (tab ⚙ / tab Header). To analyze events go to your tracking service (Google Analytics or Matomo) admin pages and look for events with category Ad Inserter Pro.

You can also track all pageviews (with internal tracking) and ad blocking statistics by device (internal and external tracking are supported). Check below for details. If you would like to test tracking and check statistics while you are logged in set Track Logged In Users to Enabled. Choose (if available) Click Detection method according to the explanation above:

  • Standard click detection can detect clicks only on banners with links and is available in all versions of Ad Inserter Pro.
  • Advanced click detection can detect clicks on any ad code (including Javascript <iframe> ads) but is not available in all versions of Ad Inserter Pro.

If you are using only banners then choose Standard click detection as it is the most reliable method to detect clicks. Use Advanced method only if you need to detect clicks on AdSense, Amazon, Media Net or other Javascript based ads, for example, to run A/B test with AdSense and Amazon Native Shopping Ads to determine which ad has the highest CTR.

Clear All Statistics Data clears all impression and click data for all code blocks. Use it only when you need to delete all statistics.

Ad Blocking

Ad blocking detection settings are located on the last tab 

ad inserter plugin settings

Ad blocking detection needs to be enabled for any ad blocking action to work. To enable Ad blocking detection click on the right button to turn it green.

Ad blocking detection needs to be enabled even if you will not use general actions available here (popup message or page redirection) but you will only replace ads or protect content.

ad inserter ad blocking detection

Ad blocking detection has some additional parameters that you may need. Action here is a general action that is fired immediately when ad blocking is detected. Possible actions are None, Popup message and Page redirection.

When the user using ad blocker comes to your website you can delay action until few pages are visited. Delay action is the number of pages that the visitor must visit before the action triggers. Leave empty for immediate action.

When the action is triggered and the visitor for example closes the popup message the action will not trigger again during the No Action Period. This is a period in days (saved in cookie) when the user can browse the website without any warning or redirection. Leave empty to always trigger action every time the page is visited.

Delay action and No Action Period affect only actions set here. Ad replacement and content protection are not affected by these settings.

In order to improve or customize ad blocking detection Ad Inserter supports custom CSS selectors that are checked in order to detect ad blocking. This is an advanced feature and must be used with care – you need to know some HTML and CSS basics in order to use it.

CSS selector can be any class name or id that can identify your ad that may be blocked. Blocking is detected by checking ad height. If it is 0 it means that ad blocking prevented the ad from showing. For example, you have the following ad:

<div id="header-ad">
  <a href="http://example.com/"><img src="http://example.com/assets/banner_300x250.jpg" /></a>
</div>

To use this banner for ad blocking detection use #header-ad for custom CSS selector.

Ad Inserter Pro has additional ad blocking detection algorithms. In case there are problems with ad blocking detection you can switch to Standard mode.

Popup Message

Popup message is a typical action when you want to inform visitor that ad blocking was detected and he needs to do something. Message is normally displayed over semi-transparent overlay which covers the page. You can configure the message text (including HTML), message CSS and overlay CSS.

ad inserter ad blocking message

Check Undismissible message to prevent the visitor from closing the popup window.

This is very annoying and should be used with care! You are preventing the user from visiting your website!

To test the message click on the Preview button. A preview window will open. Here you can change text and CSS and watch live preview of the message.

ad inserter ad blocking message preview

To undo changes click on the Reset button to revert back to the saved code. To get default settings for message click on the Default button. Use + – buttons to increase or decrease the number of dummy paragraphs under message.

Once you are happy with the message click on Use to copy the settings to the Ad Inserter page. Click on Save settings to save them.

Redirection

When ad blocking is detected you can redirect visitor to any existing static page or custom url. Custom url can be absolute or relative.

ad inserter ad blocking redirection

Popup message and redirection

In some cases you may want to show popup message with a link to some page explaining the problem. It is not enough to include a link to the page in the popup message because when the visitor will click on the link he will be redirected to that page but popup message will again appear. To prevent this put shortcode [adinserter adb="no-action"] into the page to prevent ad blocking actions on that page.

PRO Multisite

Multisite settings are located on the last tab 

ad inserter plugin settings

Tab Multisite is available only on the main site of multisite installation!

Ad Inserter supports multisite WordPress installations. Normally, the plugin is available with settings and widgets to all the sites on the network. Ad Inserter Pro supports options to disable Ad Inserter Pro settings page, widgets and post/page exceptions for sites (except for the main one).

ad inserter settings multisite

It is also possible to use settings for the main site (blog) on all network blogs – in such case the Settings Page option is disabled.

Debugging

Debugging settings are located on the last tab 

ad inserter plugin settings

Ad Inserter has many debugging functions that can help you to diagnose the problem when you don’t see your ads at expected positions. When you are logged in as administrator each post or page has a WordPress admin toolbar on the top with Ad Inserter menu item. Check Debugging documentation for details.

ad inserter debugging functions

If you don’t see admin toolbar on the top go to WordPress Users > Your profile and make sure Show Toolbar when viewing site is checked. Also make sure Debugging functions in admin toolbar is checked.

ad inserter settings debugging

Remote debugging enables other people using url parameters to see your pages with debugging data: debugger widget, labeled blocks, positions for automatic insertion, labeled tags and processing log. For logged in administrators debugging is always enabled.

Enable this option to allow other people to see debugging data in order to help you to diagnose issues with Ad Inserter.