Ad Inserter Documentation

Advanced WordPress Ad Management Plugin

This page describes free Ad Inserter and Ad Inserter Pro which is an upgraded version of the freely available Ad Inserter. In addition to all the features in the free version, Ad Inserter Pro offers 64 code blocks, 6 custom viewports, export and import of settings, impression and click tracking, additional multisite options to limit settings on the sites, GEO tageting, scheduling and support via email.

Ad Inserter is a simple yet powerful WordPress ad management plugin to insert any ad or code into WordPress. Perfect for all kinds of ads including AdSense and Amazon. Simply enter any ad or HTML/Javascript/PHP code and select where and how you want to display it. It supports up to 16 (or 64 in Pro) code blocks. Code block is any code (for example AdSense ad) that has to be inserted (displayed) at some position. Each code block can be configured to insert code at almost any position supported by WordPress.

Features

ad inserter

Below is a complete description of all the functions of the plugin, but you can also download PDF user guide for Ad Inserter and Ad Inserter Pro

 

Follow us to get the latest tips and tricks

Quick Start

Ad Inserter is completely free! You can install it from Wordpress (Plugins / Add New / search for Ad Inserter). And if you need more than 16 code blocks, more than 3 viewports, multisite options, impression and click tracking, ad replacement when ad blocking is detected, country-level GEO targeting, scheduling or export/import of settings, you can upgrade to Ad Inserter Pro.

Check also some common settings. Please make sure you have also read troubleshooting section on the bottom of this page!

Few very important things you need to know in order to insert code and display some ad:

  • Each code block can be renamed. Click on the name to edit it.
  • Enable and use at least one insertion option (Automatic Insertion, manual insertions Widget, Shortcode, PHP function call)
  • Enable insertion on at least one Wordpress page type (Posts, Pages, Blog pages, Homepage, Category pages, Search Pages, Archive pages)
  • For Posts and Pages leave default blank selection value (no individual exceptions) unless you really know what are you doing (using individual exceptions)
  • If you don't see inserted code block turn on debugging functions: Label blocks, Show positions for automatic insertion (Ad Inserter menu item in the WordPress toolbar on the top of every post/page)
  • If you are using AdSense you may get blank (empty) ad blocks.

    This might be because there is some error in the code (wrong IDs), your AdSense account is not fully approved yet, your website was not accepted or your AdSense account is banned.

    In most cases once Google approves your account you'll get ads. You can also try Media net ads as good AdSense alternative for contextual ads.

media.net

 

Ad Inserter menu item in the WordPress toolbar on the top of every post/page:

ad inserter debugging functions

To show a list of all blocks click on the List button in the header row.

ad inserter block list button

This list shows all active code blocks. To show all blocks click on the top left button. To filter blocks enter keywords in the search field. You can also use php, shortcode and widget keywords to filter blocks that have enabled respective functions.

ad inserter block list

Settings

Each code block has 4 independent insertion options:

  • Automatic Insertion (before/after paragraph in all posts,...)
  • Widget (for widget positions)
  • Shortcode (for manual insertion in posts or pages)
  • PHP function call (to insert code blocks at any position in theme PHP files)

To rename code block click on the block name. To insert code block (and display ad) at some position you need to enable and use at least one insertion option.

Automatic Insertion

Automatic insertion means that the code block will be automatically inserted on all posts or pages according to the block settings. For each code block you can also define individual exceptions to prevent insertions on some posts or pages. There are at least two different ways to exclude posts or pages - check individual exceptions for more.

ad inserter automatic display

  • Disabled (no automatic insertion)
  • Insert Before Post (before post or posts on blog pages)
  • Insert Before Content (before post or page text)
  • Insert Before Paragraph (on posts, pages and blog pages)
  • Insert After Paragraph (on posts, pages and blog pages)
  • Insert After Content (after post or page text)
  • Insert After Post (after post or posts on blog pages)
  • Insert Before Excerpt (on blog pages)
  • Insert After Excerpt (on blog pages)
  • Insert Between Posts (on blog pages)
  • Insert Before Comments (on posts)
  • Insert Between Comments (on posts)
  • Insert After Comments (on posts)
  • Insert in page Footer (on all pages, before </body> tag)

ad inserter css

For single posts or pages insertion position Before Post usually means position above the post/page title, for blog pages Before Post position means position above all the posts on the blog page.

For single posts or pages insertion position After Post means position below the post/page after all the content, for blog pages After Post position means position below all the posts on the blog page.

Before and after Excerpt positions are available on blog pages only if your theme uses standard Wordpress excerpts. Otherwise you'll have to modify theme files and use PHP function adinserter in order to insert ads between excerpts.

Order of insertion positions in a typical post is the following:

  • [Before Post]
  • Post Title
  • [Before Content]
  • Paragraph 1
  • Paragraph 2
  • Paragraph ...
  • Paragraph n - 1
  • Paragraph n
  • [After Content]
  • Output of some other plugins
  • [Before Comments]
  • Comments
  • [After Comments]
  • Output of some other plugins
  • [After Post]
  • Page footer
  • [Footer]

Of course, the final order of items depends also on other plugins. Ad Inserter is by default called as one of the last plugins. You can change Plugin priority on the settings page (tab * / tab General).

Please use Show positions function to see available positions for automatic insertion (Ad Inserter menu item in the WordPress toolbar on the top of every post/page).

Custom Hooks

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). To define hooks go to tab * / tab 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. After you save settings you get new positions for automatic insertion.

ad inserter custom hook insertion positions

Block Alignment and Style

ad inserter block alignment

Each code block or ad can be alligned according to your needs. Normally, the code block is wrapped with a div with appropriate CSS style. Of course, you can customize or define your own CSS code for the wrapping div.

  • Default (simple div with thin margin around the block)
  • Align Left
  • Align Right
  • Center
  • Float Left (ad on left with wrapped text on right)
  • Float Right (ad on right with wrapped text on left)
  • Sticky Left (ad on the left, doesn't move when the page is scrolled, Pro only)
  • Sticky Right (ad on the right, doesn't move when the page is scrolled, Pro only)
  • Sticky Top (ad on the top, doesn't move when the page is scrolled, Pro only)
  • Sticky Bottom (ad on the bottom, doesn't move when the page is scrolled, Pro only)
  • No Wrapping (leaves ad code as it is, otherwise it is wrapped by a div)
  • Custom CSS (You can define custom CSS code for wrapping div)

ad inserter css

Check also detailed description of alignmens and styles.

Code Preview

Ad Inserter has a very useful function that can help you to check if the ad code is working and to see how it will look like when it will be inserted. Click on the Preview button to open Preview window. WARNING: Some adblockers may block code on the Ad Inserter preview window. If you see warning PAGE BLOCKED or you don't see your code and the widow elements are distorted, make sure you have disabled ad blockers.

On the top of the window there is visual CSS editor, four buttons, CSS code of the wrapping div (which can be edited manually) and Block Alignment and Style selection. You can hover the cursor over margin and padding values and change the value with mouse wheel or click on the button near value. The code block (or ad) style will resize to show current values.

Code preview

Below the settings there is a preview of the saved code between two dummy paragraphs. Here you can test various block alignments, visually edit margin and padding values of the wrapping div or write CSS code directly and watch live preview. Highlight button highlights background, wrapping div margin and code area, while Reset button restores all the values to those of the current block. You can resize the window (and refresh the page to reload ads) to check display with different screen widths. Once you are satisfied with alignment click on the Use button and the settings will be copied to the active block.

code preview highlighteed

Please note that the code displayed here is the code that is saved for this block, while block name, alignment and style are taken from the current block settings (may not be saved). No Wrapping style inserts the code as it is so margin and padding can't be set. However, you can use own HTML code for the block.

Please note that Preview window uses also Header and Footer code.

For all insertion positions you need to define Wordpress page types where the code blocks can be inserted (and ads displayed). PLEASE NOTE: Regardless of other settings you need to enable insertion on AT LEAST ONE PAGE TYPE.

Wordpress has basically two page types: blog pags and single pages. You can enable insertion for each page type. Check Page types page for more information.

ad inserter page types

Single pages are posts and static pages. They show one article or page. Ad Inserter labels:

  • Posts
  • Static Pages

Single pages have also additional setting for individual exceptions. If you are not using individual post/page exceptions (on post/page editor pages) then use default blank value. Even if you use lists to filter urls, IDs, categories or tags you should leave default blank value (meaning no individual post or page exceptions) as these settings affect only individual exceptions on editor pages.

ad inserter single page exceptions

Blog pages are pages that show few latest posts with excerpts (or full posts). Such blog pages are category pages, tag pages, archive pages and also homepage if set to show latest posts. If your theme has custom homepage or the homepage is set as static page then homepage is not blog page and automatic insertion will not be possible as on typical blog pages. Ad Inserter labels:

  • Homepage
  • Category pages
  • Search Pages
  • Archive pages

Because each page type has different page layout, all positions for automatic insertion are not available on all page types. The word content used in the context of automatic insertion means the content of post or static page (paragraphs that make the post or static page). Some themes use content hooks also on blog pages. In such cases you can also use content positions on blog pages. Use debugging functions to show available positions.

Available only on single pages:

  • Before/after paragraph
  • Before/after content
  • Before/between/after comments

Available only on blog pages:

  • Before/after excerpt (only if WP excerpts are used)
  • Between posts

Available on all page types (not all themes use them):

  • Before/after post

Insertion (located in the Misc section) is possible also for:

  • AMP pages
  • Ajax requests (e.g. for endless scroll)
  • Error 404 page (Error 404: Page not found)
  • RSS Feed

Please Note: For shortcodes and PHP function calls it is possible to ignore enabled page types and use them on any page. See down the page for details.

Individual Exceptions

You can disable insertion of ads on certain posts or pages. For each code block on posts or static pages you first define default insertion settings for posts/pages page type. For the complete overview please check Exceptions page.

ad inserter single page exceptions enabled

Then you can define individual post/page exceptions on the post/page editor page (check Ad Inserter Individual Exceptions meta box below each post). Exceptions work only on static page/post content (positions Before Content, Before Paragraph, After Paragraph, After Content). For one or few exceptions it is easier to first enable default insertion and no individual exceptions (blank selection) and then either white or black-list single url or few space-separated urls (click on the Lists button).

ad inserter exceptions

Post and static page exceptions are normally enabled only for administrators. You can define minimum user role for exceptions on plugin settings page (tab * / tab General):

ad inserter settings

Filter

You can also limit insertions by specifying a number or comma separated list of numbers or calls (insertions) as Filter (Misc button / tab Filter). This setting is a filter to limit/filter insertions when the theme inserts code block more than once (for example between posts or between comments). For example, when using Between posts automatic insertion, Filter set to 2, 4, 6 means insertion after posts 2, 4, and 6. You can also leave Filter number empty (means all insertions) and define maximum number of insertions (Button Misc, tab Insertion) which is equivalent to Filter 1, 2, 3, …, N.

Paragraphs

ad inserter paragraph number

Here you define paragraph number(s) for Automatic Insertion options Before and After Paragraph:

  • 0 means random paragraph position
  • value between 0 and 1 means relative position in post or page (e.g. 0.3 means paragraph 30% from top or bottom)
  • 1 or more means paragraph number

You can also specify comma separated list of paragraph numbers for multiple insertion.

Counting

ad inserter paragraph counting

Paragraphs can be counted from top or from bottom. It is also possible to count only paragraphs that contain/do not contain certain text or count only paragraphs that have some minimum or maximum number of words. If more than one text is defined (comma separated) and "contain" is selected then the paragraph must contain ALL texts.

Paragraphs are not counted inside special elements: <blockquote>, <figure>, <li>. Of course, there is an option to enable counting also inside these special elements and you can define these special elements - No Paragraph Counting Inside setting on the tab * / tab General.

Please Note: Paragraph processing works on every post or page according to settings. Therefore, if you enable insertion also on blog pages (home, category, archive, search pages) and your theme does not display post excerpts but complete posts, Ad Inserter will by default insert code blocks into ALL posts on the blog page (according to settings). To enable insertion only into specific post(s) on blog pages define Filter. You can also leave Filter empty (click Misc button, empty means all posts on the blog page) and define maximum number of insertions.

You can also define paragraph HTML tags. Normally only <p> tags are used. If your post contains also <div> or header tags, you can define comma separated list of tags used to count paragraphs (e.g. p, div, h2, h3).

WARNING: Each code block you insert in post adds one <div> block unless you use No wrapping style. Before Paragraph will insert code before <tag>, After Paragraph will insert code after closing </tag>. After Paragraph will work even if you specify tag names that have no closing tags (e.g. images using <img> tag) since Ad Inserter uses special processing for such cases. Use # as tag if paragraphs have no tags and are separated with the \r\n\r\n characters.

Minimum number of paragraphs / Minimum/Maximum page/post words: do not insert if the number of paragraphs or the number of words is below or above limit (used only for position Before or After selected paragraph).

Minimum number of words in paragraphs above: insert only if the number of words in paragraphs above is above some limit (used only for position Before or After selected paragraph).

Clearance

ad inserter paragraph clearance

You can define parameters to avoid insertion at paragraph positions where above or below is some unwanted element (heading, image, title). This is useful to avoid inserting ads where they may not look good or where it is not allowed.

You can define in how many paragraphs above and below should specified text be avoided. And if the text is found you can choose to either skip insertion or try to shift insertion position up or down up to the specified number of paragraphs.

On every post/page there is a toolbar on the top. Ad Inserter menu item has few functions to visualize tags and positions for automatic insertion:

ad inserter debugging functions

  • Show HTML tags: visualizes HTML tags
  • Show positions: shows available positions for automatic insertion. It uses paragraph tags for blocks configured for After or Before paragraph.

Additional Options for code blocks

PHP processing: Enabled or Disabled - Enable processing of PHP code. If there is a non-fatal error in the PHP code, it will not break the website.

  • Use [adinserter data='category'], [adinserter data='short-category'], [adinserter data='title'], [adinserter data='short-title'], [adinserter data='tag'], [adinserter data='smart-tag'] or [adinserter data='search-query'] shortcodes to insert actual post data into code blocks
  • Use [adinserter data='author'] shortcode for post author username or [adinserter data='author-name'] for post author name to insert post author data into code blocks (works only inside posts)
  • Use [adinserter data='country-iso2'] shortcode to insert country lowercase ISO Alpha-2 code (use [adinserter data='country-ISO2'] for uppercase country code) or [adinserter data='ip-address'] to insert IP address into code blocks (Pro only, works only with server-side Dynamic blocks)
  • Use [adinserter custom-field='CUSTOM_FIELD_NAME'] shortcode to insert custom fields as defined in posts

Ad rotation

To rotate different ad versions separate them with [ADINSERTER ROTATE] - Ad Inserter will randomly select one of the ad versions. For example, to rotate 3 different images you can use the following code:

<img style='height: 400px;' src="http://malsup.github.io/images/p1.jpg">
[ADINSERTER ROTATE]
<img style='height: 400px;' src="http://malsup.github.io/images/p2.jpg">
[ADINSERTER ROTATE]
<img style='height: 400px;' src="http://malsup.github.io/images/p3.jpg">

PLEASE NOTE: Previous versions of the plugin used the |rotate| separator for rotation. This separator will continue to work.

WARNING: If you are using caching ad rotation by default may not work as expected. Server-side rotation works only when the page is generated and Ad Inserter is called. In such cases please make sure you have disabled caching or use client-side rotation - but you need to be aware of how it works. Please check section Caching - Ad rotation for details.

Ad Inserter is perfect for displaying any kind of ads. It can also be used to display various versions of ad, for example AdSense ads using channels to test which format or color combination performs best – but please, in such case use server-side rotation.

Ad counting

To insert different ads when there are multiple insertions on the page, separate the ads with [ADINSERTER COUNT] - Ad Inserter will select one ad according to the insertion counter. For example, to insert 3 different images between first four posts on homepage (if supported by theme) you can set Automatic insertion to Between posts, set Filter to 1, 2, 3 and enable insertion on Homepage and then use the following code:

<img style='height: 400px;' src="http://malsup.github.io/images/p1.jpg">
[ADINSERTER COUNT]
<img style='height: 400px;' src="http://malsup.github.io/images/p2.jpg">
[ADINSERTER COUNT]
<img style='height: 400px;' src="http://malsup.github.io/images/p3.jpg">

Ad Inserter will insert image 1 between posts 1 and 2, image 2 between posts 2 and 3 and image 3 between posts 3 and 4.

PLEASE NOTE: Previous versions of the plugin used the |count| separator for counting. This separator will continue to work.

Buttons

Below the code there are buttons which toggle additional settings for code block.

ad inserter buttons

Misc

Insertion

ad inserter misc

The code block can be inserted for:

  • All users (default)
  • Logged in users
  • Not logged in users
  • Administrators (useful for testing/debugging)

WARNING: If you are using caching this may not work as expected. The check works only when the page is generated and Ad Inserter is called. Make sure you have disabled caching when you are using such settings. Check Caching section for details.

For each code block you can limit how many times on the page the code (or ad) will be inserted. There are two settings for this. Max N insertions: this is a simple limit for the first N insertions for the block. The other setting is Filter.

By default code blocks will not be inserted on AMP pages, Error 404 page (Page Not Found) and in RSS feeds. Check AMP Pages, Error Page or RSS Feed checkbox to enable insertion there. Ajax requests (e.g. for infinite scroll) are by default enabled, but you can uncheck it to disable insertion on Ajax calls.

Word Count

ad inserter misc word count

Here you can define minimum and maximum post/page word length. Empty value means no limit.

Filter

ad inserter misc filter

Here you can define which insertions are enabled - single number or comma separated numbers. %N filter item means filter every N-th insertion. Filter also works for paragraph counting. Leave Paragraph number empty, set filter to Paragraphs and define comma separated list of paragraph numbers where the code should be inserted (%N can also be used). Invert Filter inverts insertion – listed insertions are disabled.

This is useful in many cases where you can't remove unwanted insertions of the code with other settings:

  • If you need to insert ad before the first, third and fifth excerpt on the homepage you simply specify 1, 3, 5 for the filter.
  • If you need to insert an ad between the second and third comment and between the fourth and fifth comment on posts you set 2, 4 for the filter.
  • If you need to insert an ad every fifth comment on posts you set %5 for the filter.
  • In some WP themes hooks (that call Ad Inserter insertion functions) are called more than once. In such case you might get unwanted insertions. Simply set the filter to the number of the wanted call(s). Use debugging function Show positions on every post/page to show available positions for automatic insertion with counters.
  • If you use adinserter PHP function and you don't want that for each time the functoin is called on the page the code is inserted, you can simply filter calls.
  • If you olny need the first N calls (insertions) then leave filter to 0 and use Max N insertions instead (tab Insertion).

Please Note: Paragraph processing works on every post or page according to settings. Therefore, if you enable insertion also on blog pages (home, category, archive, search pages) and your theme does not display post excerpts but complete posts, Ad Inserter will by default insert code blocks into ALL posts on the blog page (according to settings). To enable insertion only into specific post(s) on blog pages define Filter. You can also leave Filter empty (means all insertions) and define maximum number of insertions (tab Insertion).

Scheduling

ad inserter misc scheduling

You can define when the code block will be inserted:

  • Insert immediately: no scheduling
  • Delay insertion for N days after publishing: waits for N days after the time when the post was published (available only for before/after content and before/after paragraph)
  • Insert between dates START_DATE and END_DATE (Pro only): inserts code only between START_DATE (including) and END_DATE (excluding) - on START_DATE it starts inserting, on END_DATE it ends inserting. You can also define fallback code block to be inserted when the original block expires.

General

ad inserter misc general

General tag: text used for [adinserter data='tag'] and [adinserter data='smart-tag'] shortcodes if the post has no tags - useful for contextual ads - works only inside posts/static pages!

Lists

Black lists and white lists are two ways of filtering insertion. White list means that insertion will be enabled only for the items on the white list, while black list means that insertion will be disabled for all the items on the black list.

ad inserter lists

Lists are used to limit insertion on pages/posts that have something in common (category, tag, taxonomy, url pattern) or to limit insertion based on visitor's data (referer, IP address, country, url parameter, cookie). Click on the Lists button to show lists editor. For complete description check Black and White Lists.

Devices

If you would like to insert ads for all devices then you don't have to use this function. Use it only if you would like to insert ads or codes only for specific devices (desktop, tablets, phones).

IMPORTANT: There are two types of device detection: server side and client-side.

ad inserter device detection

Client-side detection

  • Desktop devices
  • Tablet devices
  • Phone devices

Client-side detection of mobile/desktop devices works always as it is done in visitor's browser. CSS media queries and viewport (browser's screen) width are used to show or hide Ad Inserter code blocks.

PLEASE NOTE: In most cases you should use ONLY client-side detection type. Works perfectly with responsive designs as they use CSS media queries.

BUT BE CAREFUL: Some ad networks (like AdSense) limit ads per page. The ads are still inserted (loaded and counted) for all devices, but for unwanted devices they are hidden by the browser using CSS media queries based on viewport widths. Check Caching - Device detection for details.

ad inserter settings viewports

Up to 3 viewport names and widths can be defined on the Ad Inserter Settings tab * (Ad Inserter 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

Server-side detection

  • Desktop devices
  • Mobile devices (tablets and phones)
  • Tablet devices
  • Phone devices
  • Desktop and tablet devices
  • Desktop and phone devices

Server-side detection of mobile/desktop devices works only when Ad Inserter plugin is called. It is called by Wordpress when it needs to generate a page. However, when you are using caching, it saves created page for quicker serving. In such cases the user might get (saved) page for wrong device (used by some previous visitor who triggered page caching). To solve this issue use themes that generate separate pages for desktop and mobile devices or use Mobile Theme Switcher plugin. Server-side detection uses User-Agent string combined with specific HTTP headers to detect the environment.

PLEASE NOTE: Use server-side device type detection only when you need to insert (display and count) ONLY code blocks for specific device type. In all other cases switch it off.

PLEASE NOTE: If you are using No Wrapping style and need to hide code on some devices using client-side detection (CSS Media Queries) then you need to add appropriate class to your CSS code (ai-viewport-1, ai-viewport-2, ai-viewport-3). This doesn't apply to widgets as they always contain a wrapping div.

By default code blocks will not be inserted on Error 404 page (Page Not Found). Check Error '404 Page checkbox' to enable code block on error 404 page.

Manual Insertion

Manual insertion means inserting ads or codes at some particular position in post or static page (shortcodes), using widget at some widget position or modifying theme PHP file to insert ad code at some previously unavailable position.

ad inserter manual

  • Widget - Widgets for all code blocks are enabled by default - simply drag Ad Inserter widget to any widget position (e.g. Sidebar), select code block, save and you're done. Optionally you can enable Sticky widget - this means that this widget (and widgets below) will stay fixed in the sidebar when the page is scrolled, but please note that this may not work with all themes. You can also make other widgets sticky even if you don't use Ad Inserter widgets - drag Ad Inserter widget to the sidebar ABOVE the top widget that needs to be sticky, select Dummy Widget for Block, check Sticky and save widget. Use only one sticky widget in each sidebar! In general plugin settings (tab *) you can also define Sticky Widget Top Margin to precisely define top position where the first sticky widget will stick. There are two modes for sticky widgets (or sticky sidebars) available as Sticky widget mode in general plugin settings (tab *):

    • CSS mode
      This mode is the best approach but may not work with all themes. CSS mode works by changing sidebar CSS to position: sticky. This works in most themes but not all. If your widgets and sidebar aren't sticking as expected you can use JavaScript mode described below. If you would like to try to make CSS mode working the first thing to check are the rules applied to the sidebar parent containers. Specifically, look for any overflow property set on the parent. You can't use: overflow: hidden, overflow: scroll or overflow: auto on the parent of a position: sticky sidebar. If your theme is not using overflow and still having problems it's worth checking if a height is set on the parent. This may constrain the sticky positioning, stopping it from occurring. Remove the height and see if that fixes the problem.

    • JavaScript mode
      This mode should work with practically all themes but may reload ads on page load when sticky sidebar is initialized. Use only when CSS mode does not work.
  • Shortcode - Insert shortcode [adinserter block="BLOCK_NUMBER"] or [adinserter name="BLOCK_NAME"] into post or page HTML code to insert block with BLOCK_NAME name or BLOCK_NUMBER number at this position. PLEASE NOTE: Shortcodes IGNORE post/static page exception settings! To force checking individual post/page exceptions use shortcode [adinserter block="BLOCK_NUMBER" check="exceptions"]. You can also insert shortcode that ignores enabled page types with [adinserter block="BLOCK_NUMBER" ignore="page-type"]
  • PHP function call <?php if (function_exists ('adinserter')) echo adinserter (BLOCK_NUMBER); ?> - Insert code block BLOCK_NUMBER at any position in template file. You can also define Filter for PHP function - define which call(s) to the function will actually insert code. This is useful if you put a call to the adinserter function inside a loop in a template file (e.g. for homepage) and you need to insert ads only few times between posts. You can also use PHP function calls that ignore enabled page types <?php if (function_exists ('adinserter')) echo adinserter (BLOCK_NUMBER, 'page-type'); ?>

Other Notes

By default code blocks will not be inserted on Error 404 page (Page Not Found), AMP pages and in RSS feeds. Check Error Page, AMP Pages or RSS Feed checkbox to enable insertion there (buttom Misc / tab Insertion). Ajax requests (e.g. for infinite scroll) are by default enabled, but you can disable insertion on Ajax calls.

Additional options for code blocks:

PHP processing: Enabled or Disabled - Enable processing of PHP code. If there is an error in the PHP code, it will not break the website.

ad inserter php processing

To rotate different ad versions separate them with [ADINSERTER ROTATE] - Ad Inserter will randomly select one of the ads.

WARNING: If you are using caching and ad rotation please check section Caching - Ad rotation for details.

To insert different ad on each call (insertion) for the code block (when the page is create and plugin called) separate ads with [ADINSERTER COUNT] - Ad Inserter will sequentially select one of the ads.

In the code blocks you can use the following shortcodes:

  • [adinserter data='title'] - Title of the post
  • [adinserter data='short-title'] - Short title (first 3 words) of the post title
  • [adinserter data='category'] - Category of the post (or short title if there is no category)
  • [adinserter data='short-category'] - First words before "," or "and" of the category of the post (or short title if there is no category)
  • [adinserter data='tag'] - The first tag or general tag if the post has no tags (works only inside posts)
  • [adinserter data='smart-tag'] - Smart selection of post tag in the following order:
    • If there is no tag then the category is used;
    • If there is a two-word tag then it is used;
    • If the first tag is a substring of the second (or vice versa) then the first tag is not taken into account
    • If the first and second tags are single words then both words are used
    • First three words of the first tag
    • General tag
  • [adinserter data='search-query'] - Search engine query that brought visitor to your website (supports Google, Yahoo, Bing and Ask search engines), {smart_tag} is used when there is no search query. You need to disable caching to use this tag. Please note that most search queries are now encrypted.
  • [adinserter data='country-iso2'] - lowercase country ISO Alpha-2 code (based on visitor's IP address, Pro only, works only when server-side Dynamic blocks are used), use [adinserter data='country-ISO2'] for uppercase code.
  • [adinserter data='ip-address'] - IP address (Pro only, works only when server-side Dynamic blocks are used)
  • [adinserter data='author'] - post author username (works only inside posts)
  • [adinserter data='author-name'] - post author name (works only inside posts)
  • [adinserter custom-field='CUSTOM_FIELD_NAME'] - custom fields as defined in posts

The order of processing separator shortcodes is the following:

  1. [ADINSERTER COUNT]
  2. [ADINSERTER ROTATE]
  3. [ADINSERTER AMP]

This means that you can have AMP separator inside ROTATE options and they can be used as COUNT options.

Ad Inserter General Settings - Tab *

ad inserter settings

Wrapping divs for code blocks have code-block and code-block-N classes which can be used for custom styles. Class name code-block can be changed in Ad Inserter settings. 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-3.

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

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 exceptions editing in Post/Page editor.

Ad Inserter supports server-side and client-side dynamic blocks (ad rotation, IP address and country detection). 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 Caching for details.

No Paragraph Counting Inside: here you can define tags inside which paragraphs will not be counted.

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.

Here you can also define Sticky Widget Top Margin to precisely define top position where first sticky widget will stop.

Default Ad Inserter plugin 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.

Hooks

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. After you save settings you get new positions for automatic insertion.

ad inserter custom hook insertion positions

Support for Special Heade and Footer Code Blocks
  • Header code (code in the <header> 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 (set Style to No wrapping in such case!) 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.

ad inserter footer

Raw HTTP Header

You can also insert raw HTTP header lines using [ADINSERTER HTTP] 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 column. 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

GEO targeting Groups (Pro only)

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

ad inserter settings geo targeting

Multisite (Pro only)

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 Settings page, widgets and post/page exceptions for sites (except 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.

Ad Impression and Click Tracking

Ad Blocking Statistics

Ad Inserter Pro supports ad impression and click tracking. This enables you to monitor how many times each ad was displayed and how many times it was clicked. This can be used also for A/B tests to determine which ad gets more clicks. Please check Ad Impression and Click Tracking for details. Ad Inserter Pro supports also ad blocking detection and ad blocking statistics to monitor how many times ad blocking was used. Check Ad Impression and Click Tracking for details

ad inserter tracking statistics

Ad Blocking Detection

Ad Inserter supports ad blocking detection – possible actions with Ad Inserter:

  1. Show popup message – user can close the message and continue reading
  2. Show popup message – user can't close the message – navigation not possible
  3. Redirect to some page
  4. Replace ads with some other content or different ads (Pro only)
  5. Protect (hide or modify) the content (Pro only)
  6. Ad blocking statistics (Pro only)

Check Ad Blocking Detection for details.

Debugging

Ad Inserter has many debugging functions that can help you to diagnose the problem when you don't see your ads at expected positions. Each post/page has a WordPress toolbar on the top. If you don't see it check Ad Inserter Plugin settings tab * / Debugging and make sure Debugging functions in admin toolbar is checked. 

ad inserter debugging functions

WARNING: Make sure caching is disabled while debugging!

Ad Inserter menu item has the following debugging functions:

  • Label Blocks: Each inserted block is labeled with a thin red border and red bar with block number, name and counters. Blocks that use client-side detection and are hidden are shown with blue bar and viewport name - resize the browser to check display for other devices (or screen widths). If you see only red bar then this means that the block with your code is inserted but the code doesn't display anything.
  • Show Positions: Enable this function to show available positions for automatic insertion. Displayed positions are based on the theme layout and configured paragraph counting. You can choose between all paragraph tag lists (or counting parameters) used for blocks configured for Before or After paragraph. If you click on the Show Positions menu item you'll see default paragraph positions for p tags.
  • Show HTML tags: Enable this function to see HTML tags used in the post. Use this function to determine post structure in order to configure paragraph counting.
  • Disable insertion: Use this function to temporarily disable insertion of code blocks - everything else on the page will look like the code blocks were processed and inserted.
  • Log Processing: Use this function to log insertion process in order to determine why some code block was not inserted. The log is added as HTML comment at the end of the page - check page source

Example of page with enabled debugging functions:

ad inserter debugging

  • Code preview: click on the Preview button for each code block to see how the ad or code will look like. On the Preview window click on the Highlight button to highlight code. If you don't see display of the code here it is very likely that the code is not working properly. Here you can also adjust alignment and style for code block.
  • Debugger Widget: Place Debugger widget in some widget area to see basic WordPress page and Ad Inserter data (User status, Page Type, Post ID, Url, Referer, etc). With this widget you can also check saved block settings and client-side viewport name.

ad inserter debugger widget

WARNING: Make sure caching is disabled while debugging! All debugging functions you enable will be visible only to you! Post/page debugging works by adding url parameters to the url (web address):

  • Label Blocks: ai-debug-blocks=1 (use ai-debug-blocks=0 to turn it off)
  • Show Positions: ai-debug-positions=BLOCK_NUMBER, 0 means default counting of paragraphs with p tags, numbers between 1 and 16 use paragraph counting as configured for the block (use ai-debug-positions= to turn it off)
  • Show HTML tags: ai-debug-tags=1 (use ai-debug-tags=0 to turn it off)
  • Disable insertion: ai-debug-no-insertion=1 (use ai-debug-no-insertion=0 to turn it off)
  • Log Processing: ai-debug-processing=1 (use ai-debug-processing=0 to turn it off)
  • Country test: ai-debug-country=XX (replace XX with country ISO Alpha-2 code)
  • IP address test: ai-debug-ip-address=IP_ADDRESS
  • Ad blocking simulation: ai-debug-adb=1
  • Ad blocking detection status: ai-debug-adb-status=1

Country test and IP address test work only when you have enabled debugging on some page and debugging cookie is created.

When browsing other pages on the website debugging settings are temporarily saved (for the session). To disable all debugging functions click on the Ad Inserter top menu item in the toolbar (or use ai-debug=0)

ad inserter settings debugging

If you enable Remote debugging you can also allow other people using url parameters to see post/page with debugging data. Remote debugging option is located on the Ad Inserter Settings tab - Debugging tab below. Remote debugging enables other, non-logged in users by using url parameters to see Debugger widget and code insertion debugging (blocks, positions, tags, processing). Enable this option to allow other people to see Debugger widget, labeled blocks and positions in order to help you to diagnose problems. For logged in administrators debugging is always enabled.

Troubleshooting

Free Ad Inserter can be installed from Wordpress (Plugins / Add New / search for Ad Inserter). It contains most of the functionality of the Pro version. The main difference is the number of code blocks supported and support via email - see below for details. Before you purchase license for Ad Inserter Pro please check whether free Ad Inserter can be installed on your website, it works as expected, you are not experiencing issues and it fits your needs. If free Ad Inserter does not work, Ad Inserter Pro will also not work. If you are having issues with the free Ad Inserter please use Ad Inserter WP support forum and ask for help or advice there.

Plugin upload fails

Ad Inserter Pro must be installed from the file. You get the download link when you purchase the license. In some cases WordPress will not allow you to upload the plugin. This is very likely because your web hosting has set limitations on upload file size. In such case you can do the one following suggestions:

  • Upload the plugin manually with FTP or hosting cPanel File Manager - Extract the zip file and upload the ad-inserter folder to /wp-content/plugins/ folder of your website. Make sure you upload the innermost ad-inserter folder located inside the zip file and not the folder that may be created when you unzip the file. Inside the ad-inserter folder there should be plugin files and plugin subfolders.
  • Increase the upload file size limit - In the folder /wp-admin/ create file php.ini with the following content:
upload_max_filesize = 64M
post_max_size = 64M
  • Contact your hosting company to investigate the problem and install the plugin for you.
  • Contact us and provide hosting cPanel and Wordpress admin access and we'll try to help you.

Ads not displayed

One of the common problems is that you don't see the ad displayed where you expect it. In such case you should first check if ad blockers are disabled. Then you should check if the ad code is inserted. This can be done either by examining the source code of the page (make sure the caching is disabled) or by debugging function Label Blocks. If the code block is inserted then Ad Inserter works as expected, just the code doesn't display anything – you should check the code or ad network. Sometimes checking Javascript console may show error messages that can indicate the reason for no ads or blank ad blocks. If the code block is not inserted then you can use debugging functions that can help you to diagnose the problem – check Debugging for details.

If you are using AdSense you may get blank (empty) ad blocks. This might be because there is some error in the code (wrong IDs), your AdSense account is not fully approved yet, ad serving for the website is not enabled yet, your website was not accepted or your AdSense account is banned. In most cases once Google approves your account you'll get ads. You can also try Media net ads as good alternative for contextual ads.

media.net

Settings Page Blocked

ad inserter page blocked

First thing to check is Javascript console. Errors are the first indicator of what might be wrong. Some themes like to add async or defer tags to javascript files. This changes execution order of the scripts needed by Ad Inserter and you may get errors or partially loaded page. Your theme or other plugins SHOULD NOT MODIFY the code generated by Ad Inserter! Most of the scripts used are loaded from the bottom of the page and the order of script execution is important for the code to work properly. Make sure your theme does not add async or defer tags to javascript files.

Some Ad Blockers and security plugins may also block Ad Inserter settings page. If you don't see normal tabs for code blocks or there is no save button, make sure you have whitelisted Ad Inserter settings page.

You also get this warning when the settings page was not loaded properly due to some Javascript error. Check Javascript console in your browser.

WARNING: Text selection, Copy and Paste functions with the syntax highlighting editor do not work on mobile devices. If you need these functions you can temporarily switch to Simple editor using the button above the code box.

ad inserter simple editor

Caching on the backend side (Ad Inserter Settings page) may also cause some unwanted behavior if it is not done properly. The problem can occur when the plugin is updated since the new plugin also provides new javascript and CSS files. In order to prevent browsers from loading old js/css files the plugin appends version info as query parameter to js and css files needed.

For example, in the source code of the settings page it should be like this (note parameter ?ver=2.0.1):

<script type='text/javascript' src='http://example.com/wp-content/plugins/ad-inserter/js/ad-inserter.js?ver=2.0.1'></script>
<link rel='stylesheet' id='ai-admin-css' href='http://example.com/wp-content/plugins/ad-inserter/css/ad-inserter.css?ver=2.0.1' type='text/css' media='all' />

However, on some websites this version parameter is removed (very likely due to aggressive caching) and this may cause problems:

<script type='text/javascript' src='http://example.com/wp-content/plugins/ad-inserter/js/ad-inserter.js'></script>
<link rel='stylesheet' id='ai-admin-css' href='http://example.com/wp-content/plugins/ad-inserter/css/ad-inserter.css' type='text/css' media='all' />

Because of this the old cached files (css and js) are loaded which cause warnings and unpredictable behavior. If you are using caching make sure the caching software DOES NOT REMOVE VERSION INFO (QUERY STRING) parameter from the urls on the settings page. This is needed for browsers to reload the file when the plugin is updated.

Possible caching utilities that might affect query strings:

Cloudflare: Caching level / Deselect Ignore Query String as it may remove query strings

W3 Total Cache: Uncheck Browser cache / Remove query strings from static resources (although it should not cache backend settings page)

ad inserter incompatible javascript

You may get such warning if wrong (old) javascript or CSS file is loaded. In such cases clear browser's cache and all other caches used and reload the page (e.g. with Ctrl F5). Also make sure the caching software DOES NOT REMOVE VERSION INFO parameter from the url. Javascript file version and CSS file version must match plugin version number. Please note that the javascript file and CSS file are part of the plugin and are needed only for the settings page.

WARNING: If you are using caching, the inserted code may not appear immediately on the page. Make sure you have disabled caching when you are testing or debugging. Some caching plugins like WP Super Cache have an option to disable caching for known users.

PLEASE DON'T FORGET: If you are using caching some settings may not work as expected. For example, ad rotation, referer check, user check and server-side detection work only when the page is generated and Ad Inserter is called. In such cases please make sure you have disabled caching when you are using such settings.

Ad Blockers

There is no way to prevent Ad blockers. But they do not block Ad Inserter directly, they block the code you are inserting. There are to ways to try to avoid blocking:

  • In Ad Inserter settings you can rename (or remove) class name for the wrapping divs. This way it would be difficult to detect Ad inserter code blocks. Of course, inserted code could still be disabled by ad blockers. You can also use No wrapping style and your code would be inserted as it is. Again, ad codes would still be blocked, but any other "non-advert" code would not be blocked.
  • In the case there is some wrong blocking of non-advertising code (false positive) you can write to list creators to make an exclusion (more or less general) - these lists are used by ad blockers. One such popular list is https://easylist.to/

Heavy website load

Ad Inserter is built for speed. In normal cases it should not significantly increase page loading time. Of course, if you are using many code blocks this may increase processing time but still it should not cause any problem. In some cases the cause for long loading time may be processing of your PHP code used in some code blocks. However, it is very easy to determine how much time Ad Inserter uses to insert the code. Log in as admin and go to a page where you would like to check Ad Inserter processing time. Enable Log Processing (Ad Inserter menu item in top admin bar, check Debugging for details) and check page source at the bottom. Among other debugging data you should see the following lines:

PLUGIN CODE PROCESSING: 81.55 ms
USER CODE PROCESSING: 210.08 ms
TOTAL PROCESSING TIME: 291.63 ms

PLUGIN CODE PROCESSING time is time used by the plugin to insert code blocks.

USER CODE PROCESSING time is time used to process your PHP code in Ad Inserter code blocks. If you are not using PHP code then this time should be 0.

TOTAL PROCESSING TIME is total time used by the Ad Inserter plugin to process your PHP code and to insert the all the codes into the page.

Are you sure you want to do this?

You usually get page with this message when the security token on the settings page expires and you are trying to save the settings. In such case simply refresh the settings page, make changes and save them.

You may also get this message when WordPress encounters some error, for example when uploading fails because of too big file or when there are Javascript errors on the settings page.

License Expired

ad inserter pro license expired

This message means that the license for Ad Inserter Pro has expired. The plugin will continue to function normally, only the updates will not be available. Go to Plugins management page and click on Renew License to go to the page where you can renew or upgrade and renew the license.

License Overused

ad inserter pro license overused

This message means that you are using Ad Inserter Pro on more websites than what you are allowed according to the license type purchased. The plugin will continue to function with basic functionality, but the updates will not be available. Click on the upgrade the license text to go to the page where you can upgrade the license. In 24 hours after you upgrade the license the warning should dissapear. Of course, you can also unistall the plugin on some of the websites in order to keep the usage according to the license type. In such case please contact us.

Please note that if you are using www subdomain and you have www.example.com and example.com domains you need to redirect one domain to another (preferably www to non-www). Otherwise both domains will behave as independent websites and will consume one license each.

Caching

Keep in mind that just installing a caching plugin does not necessarily make your site faster. Doing a bit of optimization will get you a lot of speed increase without caching plugins. To further combat slowness you may want to re-evaluate the performance of your hosting package. Maybe you've outgrown it. In that case, upgrade to a better hosting solution.

Caching on the frontend side (what visitors see) in some cases does speed up page loading but may cause some unwanted behavior. When you are using caching and visitor visits some page, Wordpress creates that page, Ad Inseter is called to do the job, the created page is sent to the visitor and it is also saved for quicker serving later. The next time the page is visited, the visitor gets cached (saved) page. Because of this some Ad Inserter functions can not work because Ad Inserter is not called when the page is cached:

  • Block rotation with [ADINSERTER ROTATE]
  • User check
  • Server-side device detection
  • Referer check
  • GEO targeting (IP address check)
  • Debugging functions

When you need the functions listed above you have to switch off caching (if possible only on selected pages where needed).

However, Ad Inserter also supports some of the functions above even when caching is enabled:

  • Client-side ad rotation with [ADINSERTER ROTATE]
  • Client-side device detection
  • Client-side GEO targeting (country detection, Pro only)
  • Client-side IP address detection (Pro only)

All you have to do is to set enable and use client-side functions (executed in the visitor's browser). But you have to be careful as some adverts might not work properly or can't be used this way and you might violate their Terms of Service.

PLEASE NOTE: If you are using W3 Total Cache for caching then you can still use server-side ad rotation, IP address and country detection even when the pages are cached as Ad Inserter supports special features of this caching plugin. Check section W3 Total Cache for details.

WARNING: If you are using caching, the inserted code may not appear immediately on the page. Make sure you disable caching when you are testing or debugging. Some caching plugins like WP Super Cache have an option to disable caching for known users.

W3 Total Cache

If you are using W3 Total Cache for caching then you can still use server-side ad rotation, IP address and country detection even when the pages are cached as Ad Inserter supports special features of this caching plugin. To enable this mode go to Ad Inserter plugin settings tab * / tab General and set Dynamic blocks to Server-side with W3 Total Cache and configure W3 Total Cache for dynamic content.

ad inserter settings w3tc

When Dynamic blocks is set to Server-side with W3 Total Cache and you are using ad rotation, IP address or country detection, Ad Inserter inserts short PHP code with special tags in place of code block. When W3 Total Cache plugin loads cached page it executes this code before it serves the pages. So the page is stills served from the cache but the Ad Inserter blocks are dynamically created just before the page is served. Therefore, pages are served from the cache and the Ad Inserter code is still generated on the server-side.

Configure W3 Total Cache

How to fully set up W3 Total Cache is beyond the scope of this page. Check the W3 Total Cache manuals or contact its developer for help with that if you need it.

  • In General Settings set the Page Caching to Disk: Basic.
  • In Page Cache under Advanced enable Late Initialization.
  • If you use the Minify option add mfunc to the ignored comment stem field.

You need to flush the cache after making these changes.

Please note also the following:

  • Mixing static cached and dynamic content is a tricky thing to do and often causes all kinds of issues. Ad Inserter follows the guidelines from W3 Total Cache on this. If it doesn’t work it’s very likely you didn’t configure W3 Total Cache correctly. Alternatively, you can decide to use client-side option for dynamic blocks – your adverts will show up just fine and rotation and GEO targeting will still work.
  • In order to use dynamic content with W3 Total Cache, W3TC_DYNAMIC_SECURITY PHP constant needs to be defined. Usually it is located in the wp-confing.php file. This is a security string used when generating PHP code for dynamic content. If this constant is not defined, Ad Inserter will define and use it.
  • Do not use debugging functions when caching is activated.
  • When you make changes in settings of the W3 Total Cache purge all caches before you check page.
  • If you deactivate W3 Total Cache plugin, Ad Inserter will use Server-side instead of Server-side with W3 Total Cache setting for Dynamic blocks.
  • After you activate W3 Total Cache plugin go to General Settings and Save all settings.

Ad rotation

To use client-side rotation you have to enable it first. Go to Ad Inserter plugin settings tab * / tab General and set Dynamic blocks to Client-side.

ad inserter settings client side

Configure blocks normally and separate different versions with [ADINSERTER ROTATE] separator. When the page will be created and Ad Inserter called, it will generate hidden code for all block versions. When the page will be loaded in the browser, one randomly chosen version of the code will be displayed. For example, to rotate 3 images:

<img style='height: 400px;' src="http://malsup.github.io/images/p1.jpg">
[ADINSERTER ROTATE]
<img style='height: 400px;' src="http://malsup.github.io/images/p2.jpg">
[ADINSERTER ROTATE]
<img style='height: 400px;' src="http://malsup.github.io/images/p3.jpg">

Please note the following:

  • Client-side rotation works fine with banners, text ads and many ad networks including Amazon Associates. However, it should not be used with some ad networks including AdSense (hiding ad units is not allowed) because of the method used for client-side rotation: all options are present on the page but are hidden until the page is loaded and one option is made visible. Please check Terms of Service for your ad network.
  • Ad Inserter reserves space for code block based on the height of the first block version. If all the versions have the same height then you won't notice anything. However, if block versions have different
    heights then it makes sense to define fixed block height with Custom CSS to avoid content jumping when block option with different or initially unknown height is displayed. If the first option is some
    Javascript based ad (e.g. Amazon widget) you should wrap it with a div and define height, for example <div style="height: 300px;"> … </div>
  • Since the code (block option) is displayed only when the page is loaded, you may notice a very short delay (few 100 ms) before the code (or ad) is displayed.
  • Client-side rotation uses div elements to wrap the code(s). This is not important unless you use No wrapping style.

Device detection

Ad Inserter supports two types of device detection: server side and client-side. Each block has its own settings.

ad inserter device detection

Client-side detection of mobile/desktop devices works always as it is done in visitor's browser. CSS media queries and viewport (browser's screen) width are used to determine device type and show or hide Ad Inserter code blocks.

In most cases you should use ONLY client-side detection type. Works perfectly with responsive designs as they use CSS media queries.

Please note the following:

  • Client-side device detection works fine with all ads. However, it should be used with care as some ad networks like AdSense allow hiding of ad unit only if you're implementing a responsive ad unit. When
    client-side device detection is used the code block is always inserted on the page but the block is hidden unless it is enabled for the device (more precisely: for the viewport width). This means that the ads are always inserted (loaded and counted) for all devices, but for unwanted devices they are hidden by the browser using CSS media queries based on viewport widths.
  • Client-side rotation uses div elements to wrap the code(s). This is not important unless you use No wrapping style.
  • If you are using No Wrapping style and need to hide code on some devices using client-side detection (CSS Media Queries) then you need to add appropriate class to your CSS code (ai-viewport-1, aiviewport-2, ai-viewport-3). This doesn't apply to widgets as they always contain a wrapping div.

IP address and country detection (Pro only)

To use client-side IP address or country detection you have to enable it first. Go to Ad Inserter plugin settings tab * / tab General and set Dynamic blocks to Client-side.

ad inserter settings client side

Configure blocks normally and define lists of IP addresses or countries. When the page will be created and Ad Inserter Pro called, it will generate hidden block. When the page will be loaded in the browser, IP address and/or country of the visitor will be checked and if allowed the block will be displayed. Check also Lists.

Please note the following:

  • Client-side IP address and country detection works fine with banners, text ads and many ad networks including Amazon Associates. However, it should not be used with some ad networks including AdSense (hiding ad units is not allowed) because of the method used for client-side IP address and country detection: the code block is present on the page but it is hidden until the page is loaded and if allowed the block is then made visible. Please check Terms of Service for your ad network.
  • Page needs to access /wp-admin/admin-ajax.php page on your web server to get IP address and country. Make sure it is accessible and not password protected.
  • Since the code block (when allowed) is displayed only when the page is loaded, you may notice a very short delay (few 100 ms) before the code (or ad) is displayed.
  • When Ad Inserter Pro (using client-side detection of IP address and/or country) makes the block visible, the content below shifts downwards.
  • Client-side IP address and country detection uses div element to wrap the code. This is not important unless you use No wrapping style.

SUPPORT

If you experience problems with the Ad Inserter plugin you can ask for help on the support forum. However, before you ask please use debugging functions described above. In almost all cases it is possible to determine the nature of the problem just by checking the debugging data. Check also source code of the page. Some code for ads may not display anything, either because of errors in the ad code or because of ad network issues. In order to be able to diagnose the problem and suggest actions or fix a bug, please do the following:

  1. Enable Remote debugging (located on the Ad Inserter Settings tab - Debugging).
  2. Clearly describe the problem. Describe what does not work as expected.
  3. Describe the settings and code blocks used.
  4. Provide web addresses (links) of the pages where the code from the settings above is not inserted properly.

Unless you provide the items listed above nobody can check your website, can't reproduce the problem and consequently can't help. Once the problem is fixed you can disable Remote debugging. Thank you very much for understanding.

Ad Inserter is completely free! Please support plugin development if you like it: