Press enter to see results or esc to cancel.

Limit Insertion with Black and White Lists

Black lists and white lists are two ways to limit 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. Click on the Lists button to show available lists.

ad inserter buttons

Lists are used to limit insertion on pages or posts that have something in common (category, tag, taxonomy, url pattern) or to limit insertion based on visitor’s data (cookie, referrer, client, IP address, country).

ad inserter lists

  • Leave list empty and set it to Black List to disable the list filtering (default setting).
  • If you white-list items on the list, at least one of the items on the list must be present to enable insertion (item1 OR item2 OR item3…).
  • If you black-list items on the list, at least one of the items on the list must be present to disable insertion (item1 OR item2 OR item3…) i.e. no item on the list should be present to enable insertion.
  • List item separator is comma.
  • For categories and tags use slugs (name used in the url – web address).
  • Click on the small button next to list to open list editor. For categories, tags, taxonomies, post IDs and countries you can select items from the list of the available items. For urls, url parameters, cookies, referrers and IP addresses you can enter one item per line in the editor.
  • If there is more than one non-empty list defined for the same code block please note the following: all lists must pass the check for insertion (list1 AND list2 AND list3…).

PRO Ad Inserter Pro supports another very powerful feature to insert part of block code depending on list conditions as described above. check Multiple list checks inside single block for details.

It is also possible to black or whitelist two or more items at the same time.

If you are using lists you don’t need to define individual post/page exceptions – leave Use exceptions unchecked unless you are using individual post/page exceptions:

ad inserter single page exceptions

Categories

List categories (category slugs) where you want insertion (white list) or don’t want insertion (black list). The list can be used for posts and category pages. Click on the small button left of the list to open category selection.

Tags

List tags (tag slugs) where you want insertion (white list) or don’t want insertion (black list). The list can be used for posts and tag / archive pages. Click on the small button left of the list to open tag selection.

ad inserter lists tags

Taxonomies, Users and Post Types

List taxonomies (taxonomy slugs) where you want insertion (white list) or don’t want insertion (black list). You can use the following comma separated taxonomy slugs: taxonomy, term or taxonomy:term. Click on the small button left of the list to open taxonomy selection.

This list works in addition to Categories and Tags lists as categories and tags are default taxonomies. Therefore, it is possible to have categories and tags in one list, for example category:category_slug, post_tag:tag_slug. This way you can list categories and tags at the same time. Of course, if you black-list some category with Categories list or tag with Tags list then even if Taxonomies list is empty those categories or tags would be black-listed.

Users and User Roles

You can also use Taxonomies list to filter users with user:username or user roles with user-role:role. This can be used to not insert ads for certain users or user roles (black list) or to insert ads only for certain users or user roles (white list). For example, to filter all users with Administrator role use user-role:administrator, to filter user with username editor2 use user:editor2.

User taxonomies work only when caching is not used.

Post Types

In Taxonomies list you can also define post types: post-type:POST_TYPE. For example to black-list portfolio post types you should black-list post-type:portfolio.

Post IDs

List post/page IDs where you want insertion (white list) or don’t want insertion (black list). Use this list only if you need to specify post IDs or there are only few posts to include/exclude, otherwise use individual exceptions when there are more posts to filter. Click on the small button left of the list to open post/page ID selection.

In some cases you may need to blacklist or whitelist all posts and only few pages or vice versa. For this purpose the ID selection contains two special IDs for this purpose:

  • posts – means all posts
  • pages – means all static pages

For example, to whitelist all posts and page with ID 3 you should whitelist posts, 3.

Urls

List urls where you want insertion (white list) or don’t want insertion (black list). 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. Separate urls with commas. Use this list only if you need to include/exclude few urls or when urls are not posts or pages, otherwise if you need to filter posts or pages use post IDs or individual exceptions instead. Click on the small button left of the list to open url editor.

Url Parameters and Cookies

List url query parameters or cookies where you want insertion (white list) or don’t want insertion (black list). You can specify either parameters (or cookie names) only 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.

The same applies also to cookies (use cookie_name or cookie_name=value). Click on the small button left of the list to open url parameter editor.

If you are using caching (very likely) you also need to set Dynamic blocks to Client-side insert (tab / tab General) in order to check url parameters and cookies in visitor’s browser and not when the page is generated.

How to show ads based on visitors’ consent?

Ad Inserter supports inserting (showing) ads based on cookies or cookie values. You can define cookie conditions by black/white-listing Url parameters (where also cookies are checked).

If you are using caching (very likely) you also need to set Dynamic blocks to Client-side insert (tab / tab General) in order to check cookies in visitor’s browser and not when the page is generated.

For example, If you are using one of the following plugins for cookie consent you need to whitelist the following cookie and value in Url parameters list:

GDPR Cookie Consent White-list viewed_cookie_policy=yes
Cookie Notice for GDPR White-list cookie_notice_accepted=true
Cookie Consent White-list catAccCookies=1

How to remember visitors’ url parameter?

Url parameters in links on external pages (for example, used for different ad campaigns) will normally work only for the first page visited. When the visitor will click any link on your website, the url parameter in the url will be lost. However, the status can easily be remembered with a cookie so you can display ads for this user even when the url parameter is not present anymore.

Referrers

List referrers (domains) where you want insertion (white list) or don’t want insertion (black list). Use # for no referer (direct visit). Click on the small button left of the list to open referer editor. You can also use partial domains with *. To filter all domains starting with domain-start use domain-start*, to filter all domains that contain domain-pattern use *domain-pattern*, to filter all domains ending with domain-end use *domain-end.

If you are using caching (very likely) you also need to set Dynamic blocks to Client-side insert (tab / tab General) in order to check referers in visitor’s browser and not when the page is generated.

How to remember visitors’ referrer?

Referrer will normally work only for the first page visited when coming from another site. When the visitor will click any link on your website, the referrer will become the current page. However, the status of this user can easily be remembered with a cookie so you can display or hide ads for this user even when the referrer is now your website.

Clients

Here you can list clients (operating systems, browsers, device names) where you want insertion (white list) or don’t want insertion (black list). Click on the small button left of the list to open client list selection.

Clients are determined from the HTTP User Agent data – a data sent in the request header that contains a characteristic string that allows the network protocol peers to identify the application type, operating system, software vendor or software version of the requesting software user agent.

For example, desktop Chrome browser version 77.0.3865.90 on Windows 7 platform sends the following User Agent string:

Mozilla/5.0 (Windows NT 6.1; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/77.0.3865.90 Safari/537.36

If you are using caching (very likely) you also need to set Dynamic blocks to Client-side insert (tab / tab General) in order to check clients in visitor’s browser and not when the page is generated.

PRO IP Addresses

List IP addresses where you want insertion (white list) or don’t want insertion (black list). 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. Click on the small button left of the list to open IP address editor.

If you are using caching (very likely) you also need to set Dynamic blocks to Client-side insert (tab / tab General) in order to check IP addresses in visitor’s browser and not when the page is generated.

PRO Countries

List countries where you want insertion (white list) or don’t want insertion (black list). Country list should contain comma separated country ISO Alpha-2 codes. You can also use country groups which you can define on the Ad Inserter plugin settings page (tab / tab Geolocation). Click on the small button left of the list to open country selection.

ad inserter pro lists

Country is determined from the IP address of the visitor. IP address database is updated automatically each month. If you have Business or Corporate Pro license you can choose between Webnet77 (default) and MaxMind geolocation database (Ad Inserter Pro will download and use GeoLite2 data created by MaxMind). Ad Inserter Pro supports also CloudFlare geolocation.

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.

If you are using caching (very likely) you also need to set Dynamic blocks to Client-side insert (tab / tab General) in order to check countries in visitor’s browser and not when the page is generated.

Use Debugging tools widget to show and debug referrers, IP addresses or countries. When you are using client-side dynamic blocks, debugging function Label blocks also shows referrer, IP address or country data for each block that has Referrers, IP addresses or Countries list set.

ad inserter client side list  debugging

PRO Country subdivisions and cities

If you have Business or Corporate Pro license and you have selected MaxMind geolocation database, you can refine country list with country subdivisions (states, regions, provinces, municipalities) and cities.

In addition to country code you can add optional subdivision or city to any list item using the following format: CC:subdivision:city. The following list item formats are possible:

  • CC – selects country with country code CC
  • CC:subdivision:city – selects country with subdivision and city
  • CC:subdivision – selects country with subdivision
  • CC::city – selects country with city

Of course, you can also select available subdivisions and cities from list. Click on the Countries label left of the list to toggle Countries / Cities list selection.

ad inserter country list toggle

The list label changes to Cities and when you click on the small button left of list subdivision:city selection opens:

ad inserter city list selection

This selection contains all subdivisions and cities for which IP address data was found to be reliable. For some countries like US the list contains all states and major cities, for other countries only major cities are included. Since the complete list is huge and you normally need only items from one country, the selection on the left lists up to 500 items. To limit selection use filter. For example, enter country code with colon to list items from that country (us: will filter items for US). For each country subdivisions are listed first so in this case you get all US states on the top. Of course, you can narrow the filter with subdivisions (us:ca will filter items for California in US). You can also use more than one filter term.

When you click on the item in the left list the item is selected, transferred to the right selection and also included in the Cities list above. You can also click on the Cities list label to go back to country selection, although, you will rarely need a list with city items from more than one country.

Please note that when you include country or country:subdivision in the list, it makes no sense to include also cities. For example, list US, US:CA:, US:CA:los angeles makes no sense as when you select US as country you also select all subdivisions and cities in that country. So if you need to target Los Angeles you should select only US:CA:los angeles.

PRO Multiple list checks inside single block

Ad Inserter Pro supports another very powerful feature to insert part of block code depending on list conditions as described above. For example, the following code

[ADINSERTER CHECK country="US"]

<img src="https://via.placeholder.com/728x150/ff000f/00ffd1.png?text=US">

[ADINSERTER CHECK country="^US"]

<img src="https://via.placeholder.com/728x150/0000ff/00ffd1.png?text=WORLD">

would insert banner according to the country: for US the first one, for the rest of the world the second one. This can be very handy when you need to insert at some position a code that depends on some parameter. Normally you would use multiple blocks with different list settings and the same insertions settings. However, with the [ADINSERTER CHECK] separator you can list multiple codes with different conditions. Normally the check attribute condition="value1, value2" means white list. To blacklist values add ^ character in front of the first value: condition="^value1, value2" – this means blacklisting value1, value2. The following CHECK conditions (lists) are available:

  • category
  • tag
  • taxonomy
  • id
  • url
  • url-parameter
  • referrer
  • ip-address
  • country

You can use the same values as described above for lists. Each CHECK separator can have more than one condition but only one condition type per check.

[ADINSERTER CHECK country="US" url-parameter="ref=affiliate"]

<img src="https://via.placeholder.com/728x150/ff000f/00ffd1.png?text=US affiliate">

[ADINSERTER CHECK country="^US"]

<img src="https://via.placeholder.com/728x150/0000ff/00ffd1.png?text=WORLD">

You can also preview each code option, preview window supports separator selection for such cases (CHECK, COUNT and ROTATE code separators).

ad inserter code preview separators