Ad Inserter and Ad Inserter Pro Documentation

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, additional multisite options to limit settings on the sites, GEO tageting, scheduling and support via email.

Ad Inserter is a simple yet powerful Wordpress plugin to insert any ad or code into WordPress. Perfect for all kinds of ads. 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

  • 16 code blocks (64 code blocks in Pro)
  • Syntax highlighting editor
  • Code preview with visual CSS editor
  • Automatic insertion: before or after post / content / paragraph / excerpt
  • Insertion exceptions for posts and pages
  • Manual positions: widgets, shortcodes, PHP function call
  • Custom block alignments and styles
  • Clearance options to avoid insertion near images or headers
  • Desktop, tablet and phone server-side device detection
  • Client-side device detection (works with caching, 3 custom viewports, 6 in Pro)
  • Ad rotation (works also with caching)
  • PHP code processing
  • Black/White-list categories, tags, post IDs, urls, url parameters, referers
  • Black/White-list IP addresses or countries (works also with caching, Pro only)
  • Simple troubleshooting with many debugging functions
  • Visualize inserted code blocks,
  • Visualize available positions for automatic insertion, HTML tags, etc.
  • Visualize HTML tags
  • Export and import of settings (Pro only)
  • Multisite options to limit settings on the sites (Pro only)
  • GEO targeting (Pro only)
  • Scheduling with fallback option (Pro only)
  • Support via email (Pro only)

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

 

ad inserter

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, GEO targeting, scheduling or export/import of settings, you can upgrade to Ad Inserter Pro.

Some typical settings are described on the bottom of this page. 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:

  • Enable and use at least one insertion option (Automatic Insertion, 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 select default value On all Pages / On all Posts unless you really know what are you doing
  • If you don't see inserted code block turn on debugging functions: Label inserted blocks, Show available positions for automatic insertion (Ad Inserter menu item in the WordPress toolbar on the top of every post/page)

ad inserter debugging functions

Settings

Each code block has 4 independent insertion options:

  • Automatic Insertion
  • Widget
  • Shortcode
  • PHP function call

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 Options

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)

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]
  • Comments
  • Output of some other plugins
  • [After Post]

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

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

Block Alignment and Style

ad inserter block alignment

  • 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)

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.

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

ad inserter page types

Single pages:

  • Posts
  • Pages

Blog pages:

  • Homepage
  • Category pages
  • Search Pages
  • Archive pages

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

  • Ajax requests (e.g. for endless scroll)
  • 404 page (Error 404: Page not found)
  • 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.

You can also 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. Then you can define post/page exceptions on the post/page editor page (check Ad Inserter Exceptions meta box below each post). Exceptions work only on page/post content (positions Before Content, Before Paragraph, After Paragraph, After Content). For one or few exceptions it is easier to first enable insertion on All Posts/Pages page types and then either white or black-list single url or few space-separated urls (click on the Lists button).

ad inserter exceptions

For blog pages and insertion positions Before Excerpt / After Excerpt and Before Content / After Content you can also specify excerpt/post number or comma separated list of excerpt/post numbers as Filter (Misc button). For Before Post / After Post positions this setting is a filter to limit/filter insertions before or after post if the theme inserts code block more than once. You can also leave Filter number empty (means all posts on the blog page) and define maximum number of insertions.

Paragraphs

ad inserter paragraph number

Paragraph number 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

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 <blockquote> elements. Of course, there is an option to enable counting also inside <blockquote>.

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 not work if you specify tag names that have no closing tags (e.g. images using <img> tag)! 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).

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 Post/Static Page Options

ad inserter content words publishing delay

You can define post/page minimum and maximum word length.

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 {category}, {short_category}, {title}, {short_title}, {tag}, {smart_tag} or {search_query} tags to insert actual post data into code blocks
  • Use {author} for post author username or {author_name} for post author name to insert post author data into code blocks (works only inside posts)
  • Use {country_iso2} to insert country ISO Alpha-2 code or {ip_address} to insert IP address into code blocks (Pro only, works only with server-side Dynamic blocks)

Ad rotation

To rotate different ad versions separate them with |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">
|rotate|
<img style='height: 400px;' src="http://malsup.github.io/images/p2.jpg">
|rotate|
<img style='height: 400px;' src="http://malsup.github.io/images/p3.jpg">

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.

Buttons

Misc

ad inserter misc

Insert Block for:

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

For each code block you can also limit how many times on the page the code (or ad) will be inserted. There are two settings for this:

  • Max N insertions: simple limit for the first N calls for the block
  • Filter: define which calls (insertions) are wanted - single number or comma separated numbers

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

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 to 0 (means all posts on the blog page) and define maximum number of insertions.

General tag: text used for {tag} and {smart_tag} if the post has no tags - useful for contextual ads - works only inside posts/static pages!

Enable or disable Insertion on special places:

  • Ajax requests (e.g. for endless scroll, enabled by default)
  • 404 page (Error 404: Page not found)
  • Feed

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.

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.

Lists

ad inserter lists

Do not insert ads in certain categories e.g sport, news, science,... (black list) or insert ads only in certain categories (white list): leave category list empty and set it to Black list to insert ads in all categories.

WARNING: If category name contains commas or spaces, use category slug instead. Also make sure you have enabled insertion on Category pages.

Do not insert ads in posts with certain tags (black list) or insert ads only in posts with certain tags (white list). Leave tag list empty and set it to Black list to insert ads for all tags. Also make sure you have enabled insertion on Tag / Archive pages.

Do not insert ads in posts/pages with certain post IDs (black list) or insert ads only in posts with certain IDs (white list). Leave Post ID list empty and set it to Black list to insert ads for all IDs.

Do not insert ads on pages with certain urls (black list) or insert ads only on pages with certain urls (white list): leave url list empty and set it to Black list to insert ads for all urls. Url used here is everything starting form the / after the domain name. For example: if web address is http://domain.com/lorem-ipsum, url to white/black-list is /lorem-ipsum You can also use partial urls with *. To filter all urls starting with /url-start use /url-start*, to filter all urls that contain url-pattern use *url-pattern*, to filter all urls ending with url-end use *url-end. WARNING: Separate urls with SPACES.

Do not insert ads on pages with certain url query parameters (black list) or insert ads only on pages with certain url parameters (white list): leave url parameter list empty and set it to Black list to insert ads for any or no url parameters. You can specify either parameters or parameters with values. For example for url http://example.com?data=2&customer-id=22&device=0 you can define url parameters data, customer-id=22 to insert ad only for urls where there is data parameter and customer-id parameter with value 22. Separate parameters with comma.

Do not insert ads to users from certain referers (domains) e.g technorati.com, facebook.com,... (black list) or insert ads only for certain referrers (white list): use # for no referer (direct visit), leave referrers list empty and set it to Black list to insert ads for all referrers.

IP addresses (Pro only): Do not insert ads for certain IP addresses (black list) or insert ads only for certain IP addresses (white list). Leave list empty and set it to Black list to show ads for all IP addresses. List should contain comma separated IPv4 or IPv6 addresses. You can also use partial IP addresses (or ranges) with *. To filter all IP addresses starting with /ip-address-start use /ip-address-start*, to filter all IP addresses that contain ip-pattern use *ip-pattern*, to filter all IP addresses ending with ip-end use *ip-end.

Countries (Pro only): Do not insert ads for certain countries (black list) or insert ads only for certain countries (white list). Leave country list empty and set it to Black list to show ads for all countries. Country list should contain comma separated country ISO Alpha-2 codes. Click list to toggle country selection and then click on the countries on the left list to select countries - country codes will automatically be added to the list. You can also use 6 country groups which you can define on the Ad Inserter settings page (tab *, GEO targeting).

ad inserter pro lists

Country is determined from the IP address of the website visitor. IP address database is updated automatically each month. Ad Inserter Pro supports also CloudFlare geolocation.

PLEASE NOTE: country code EU means non-specific European Union location - use individual country codes to target EU countries (use GB for United Kingdom) and AP means non-specific Asia-Pacific location - use individual country codes to target this region.

WARNING: If you are using caching, IP address detection and GEO targeting by default may not work as expected. It works only when the page is generated and Ad Inserter is called or when client-side IP address and country detection is enabled. Check Caching - IP address and country detection (Pro only) for details.

Use debugger widget to show and debug referers, IP addersses or countries.

Devices

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

ad inserter manual

  • Widget - Widgets for all code blocks are enabled by default - simply drag Ad Inserter widget to any widget postition (e.g. Sidebar), select code block, save and you're done.
  • 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! 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) and in feeds. Check '404 Page' or 'Feed' checkbox to enable code block on error 404 page or in feed.

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.

To rotate different ad versions separate them with |rotate| - Ad Inserter will randomly select one of the ads.

WARNING: If you are using caching ad rotation may not work as expected. It works 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 |rotate|.

In the code blocks you can use the following {tags}:

  • {title} - Title of the post
  • {short_title} - Short title (first 3 words) of the post title
  • {category} - Category of the post (or short title if there is no category)
  • {short_category} - First words before "," or "and" of the category of the post (or short title if there is no category)
  • {tag} - The first tag or general tag if the post has no tags (works only inside posts)
  • {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
  • {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.
  • {country_iso2} - Country ISO Alpha-2 code (based on visitor's IP address, Pro only)
  • {ip_address} - IP address (Pro only)
  • {author} - Post author username (works only inside posts)
  • {author_name} Post author name (works only inside posts)

Ad Inserter 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 exceptions on posts/static pages are enabled only for administrators. You can define minimum user role for page/post Ad Inserter exceptions editing in Ad Inserter Settings (tab *).

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.

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.

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

Support for Special Code Blocks
  • Header scripts (scripts in the <header> section)
  • Footer scripts (scripts before the </body> tag)

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.

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.

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

Each post/page has a WordPress toolbar on the top. Ad Inserter menu item has the following debugging functions:

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

ad inserter debugging

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

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 the code is inserted. This can be checked 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. But 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.

ad inserter page blocked

Some Ad Blockers and security plugins may 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 checkbox above the code box.

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 parameter from the url. This is needed for browsers to reload the file when the plugin is updated.

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.

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 ltext to go to the page where you can upgrade the license. In 24 hours after you upgrade the license the warning should dissapear.

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 |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 |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 it’s 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 |rotate| tag. 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">
|rotate|
<img style='height: 400px;' src="http://malsup.github.io/images/p2.jpg">
|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.

Typical Settings

Settings for ad before the first paragraph on all posts

  • Automatic Insertion: Before Paragraph
  • On all Posts checked, other pages unchecked
  • Paragraph number: 1

Settings for ad before the second paragraph on all posts, but on the homepage only three ads in the first three post

  • Automatic Insertion: Before Paragraph
  • On all Posts checked, Homepage checked, other pages unchecked
  • Paragraph number: 2
  • Filter: 1, 2, 3 (in some cases 2, 4, 6 - depends on the theme and needs some testing)

Settings for ad wrapped with text of the third paragraph on all posts

  • Automatic Insertion: Before Paragraph
  • On all Posts checked, other pages unchecked
  • Block Alignment and Style: Float Left
  • Paragraph number: 3

Settings for centered ad in the middle of post paragraphs

  • Automatic Insertion: Before Paragraph
  • On all Posts checked, other pages unchecked
  • Block Alignment and Style: Center
  • Paragraph number: 0.5

Settings for ad above post excerpts on the Insurance category page

  • Automatic Insertion: Before Post
  • Category pages checked, other pages unchecked
  • Click Lists button to display lists
  • Categories: Insurance, White List checked

Settings for ad above the first and third post excerpts on the homepage

  • Automatic Insertion: Before Excerpt
  • Homepage checked, other pages unchecked
  • Filter: 1, 3

Settings for ad above the post excerpts on the Cars tag page

  • Automatic Insertion: Before Post
  • Archive pages checked, other pages unchecked
  • Click Lists button to display lists
  • Tags: Cars, White List checked

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: