> For the complete documentation index, see [llms.txt](https://docs.exoclick.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.exoclick.com/publishers/adblock/neverblock.md).

# Neverblock

## Overview

### Anti-Adblock

NeverBlock is a proven ad block circumventing solution that maximizes your revenues instantly.

Our unique technology ensures that your advertisements still get shown even if a user has ad blocking software installed and switched on.

NeverBlock’s advanced technology bypasses ad blockers to recapture all your ad revenue and works on all browsers (including Safari, Chrome, Internet Explorer, Mozilla, etc.) and on all platforms and devices (desktop, smartphone, tablet).

This solution is free to all ExoClick clients and is a simple process of placing a line of code on your website.

In this documentation we will cover four different implementations of Neverblock. These four implementations are:

* **NeverBlock PHP** - The standard solution, easiest to implement and most commonly used. It will be covered most extensively in this documentation.
* **NeverBlock API** - When an unsupported language is required, the API provides endpoints required to get the advertisements directly. To be used when manual solutions are required.
* **NeverBlock Proxy** - A cross platform application with the purpose of handling API requests and caching of advertisements. This service runs in the background to provide the user with a more direct endpoint through which to fetch advertisements.
* **WordPress Plugin** - A WordPress plugin developed to easily integrate NeverBlock ad zones into your WordPress site.

## NeverBlock PHP - Automatic installation

### Purpose

The NeverBlock Phar Installer is a tool that assists in the installation of the NeverBlock PHP (version 3.0) solution. This can be done instead of the steps covered in [Manual installation](https://docs.exoclick.com/publishers/adblock/neverblock.md#neverblock-php-manual-installation). It will install the files in the specified directory, or a default **nb** directory. Some of the configuration will be handled by the installer, regarding [file renaming](https://docs.exoclick.com/publishers/adblock/neverblock.md#renaming-the-files-mandatory) and [identification keys](https://docs.exoclick.com/publishers/adblock/neverblock.md#identification-keys).

### Download the installer

The latest version can be downloaded using the following link:

* [neverBlockInstaller.phar.zip – v1.13](https://59878909-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FGoSwRYjxsR1XS6va6yLj%2Fuploads%2FEb1X61WoFuzi12igYPH7%2FneverBlockInstaller.phar.zip?alt=media) (NeverBlock version 3.14)

### Run the installer

Once the phar has been downloaded, place it in the directory where you want the NeverBlock files kept. When running the installer you can specify the path you wish to install the files, or let it run as default. There is also an optional parameter to define the logfile used, the purpose of which is described in the [Logfile](https://docs.exoclick.com/publishers/adblock/neverblock.md#logfile) section.

```bash
# Create and install files under default 'nb' directory 
./neverBlockInstaller.phar
```

Optional parameters:

```bash
# Create and install files under the specific directory
./neverBlockInstaller.phar --path=specific/path 

# Install files into current directory
./neverBlockInstaller.phar --path=.

# Path to logfile
./neverBlockInstaller.phar --logfile=path/logfile

# Path to writable_path (In case APC/APCu is not installed.)
./neverBlockInstaller.phar --writable_path=path/writable_path
```

### Analysing the response

Once executed we will be presented with a response similar to what can be seen below. We can analyse this in two separate sections, the diagnostic results, and the required scripts.

![](https://59878909-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FGoSwRYjxsR1XS6va6yLj%2Fuploads%2FREPgeFazdOI16fYxh5YQ%2Fneverblock_phar_1.png?alt=media)

**Diagnosis results**

Once the phar has been run it will show you the results of some tests of the configuration. Note that the **IP detection** will require the **diag.php** to be run manually. For more details regarding these results and running manually see sections Run the diag.php and Possible diag.php results.

**Required scripts**

Below the diagnosis results we see two scripts, the names of which have been automatically generated. These scripts show us the names of our **frontend\_loader.js** and **backend\_loader.php**, and will be the paths to use when [Displaying ads](https://docs.exoclick.com/publishers/adblock/neverblock.md#adding-zones-to-a-page).

## NeverBlock PHP - Manual installation

### Download the files

The installation and majority of configuration can be handled by the [phar installer](https://docs.exoclick.com/publishers/adblock/neverblock.md#neverblock-php-automatic-installation). Manual installation can be done as follows.

The latest version (v3.14) can be downloaded using these links:

* [latest.zip – v3.14](https://59878909-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FGoSwRYjxsR1XS6va6yLj%2Fuploads%2FQc4BPMTtFCJkiX8CABYV%2Flatest.zip?alt=media)
* [latest.tar.gz – v3.14](https://59878909-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FGoSwRYjxsR1XS6va6yLj%2Fuploads%2FbDMaTz3tFwlPsZMsexJe%2Flatest.tar.gz?alt=media)

Or using the following commands:

```bash
$ wget -q -O latest.tar.gz "https://59878909-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FGoSwRYjxsR1XS6va6yLj%2Fuploads%2FbDMaTz3tFwlPsZMsexJe%2Flatest.tar.gz?alt=media"
$ tar -xf latest.tar.gz
$ rm latest.tar.gz
```

The files that will be needed from this folder are:

* **backend\_loader.php**
* **frontend\_loader.js**
* **diag.php**

### Renaming the files (mandatory)

To ensure the files are not blocked immediately by ad blockers it will be a requirement to rename the files.

![](https://59878909-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FGoSwRYjxsR1XS6va6yLj%2Fuploads%2F55HNQN8HKZBXTikeTbzu%2Fneverblock_installation_3.png?alt=media)

One of the tests in **diag.php** checks the existence of the **backend\_loader.php**, so the references in this test must be updated to match your newly named file. The below example uses the same configuration shown in the previous image. At the top of page update the following line:

```php
define("BACKEND_LOADER_PHP", "ba_lo.php");
```

### Placing the files on your server

The files mentioned above should be placed on the server where you wish to show your ads.

Copy the files into a chosen directory:

![](https://59878909-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FGoSwRYjxsR1XS6va6yLj%2Fuploads%2FsdZ2WF3MEXnQhvQW4Vj4%2Fneverblock_installation_1.png?alt=media)

### Run the diag.php

Now that our NeverBlock files are on our server we will use the **diag.php** file to verify everything is okay so far. This can be done by going to the URL where the diag.php file is. Using the previous screenshot as an example ours would be the following - `https://www.my-example-site.com/nb/diag.php`

If everything has been correct so far you should see the following (we will configure the log file under [Logfile](https://docs.exoclick.com/publishers/adblock/neverblock.md#logfile)):

![](https://59878909-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FGoSwRYjxsR1XS6va6yLj%2Fuploads%2FAInyqxCuza4Y04YbLhth%2Fneverblock_installation_2.png?alt=media)

If you see different results there may be additional configuration needed.

### Possible diag.php results

**PHP Version:** If the PHP version is unsupported you will be notified. For the standard NeverBlock solution PHP version 5.2 or higher is required.

**Backend loader script presence:** If this fails the **backend\_loader.php** cannot be found by **diag.php**. This may be due to a filename change or a path issue.

**Error reporting:** This may show as a warning. This warning will not prevent the NeverBlock solution from working.

**Cache presence** and **cURL library:** In the event of cache and cURL not present you will receive warnings. This will not prevent NeverBlock from working, but we do recommend these to be configured.

* The PHP [cURL](https://www.php.net/manual/en/book.curl.php) extension *(highly recommended)*
* The PHP [APCu](https://www.php.net/manual/en/book.apcu.php) extension, or a file cache (see [Caching](https://docs.exoclick.com/publishers/adblock/neverblock.md#caching))

**IP Detection:** If there is an error about the IP matching, this is covered under [Passing IPs](https://docs.exoclick.com/publishers/adblock/neverblock.md#passing-ips-using-cloudflare-etc).

**Ad requests:** If the requests take longer than expected you may be prompted to increase the **REQUEST\_TIMEOUT\_MS** and **CONNECT\_TIMEOUT\_MS** settings. Doing this is covered under [Configuring constants](https://docs.exoclick.com/publishers/adblock/neverblock.md#configuring-constants).

## NeverBlock PHP - Configuration

### Passing IPs (using Cloudflare etc.)

In case you are using some service, such as CloudFlare, that is between the user and your actual servers, the ip detected in **backend\_loader.php** may be detected as invalid. This might cause the clicks or impressions of the ads to be registered incorrectly. To fix this, you can substitute the `$_SERVER["REMOTE_ADDR"]` passed to *UserEnvironment* class in **backend\_loader.php** with the correct value passed on by your caching/proxying service.

In the case of Cloudflare we would pass the `$_SERVER["HTTP_CF_CONNECTING_IP"]` parameter. An example shown below.

```php
isset($_SERVER['HTTP_CF_CONNECTING_IP']) ? $_SERVER['HTTP_CF_CONNECTING_IP'] : $_SERVER['REMOTE_ADDR']
```

Once this is done our *UserEnvironment* will look like the following:

```php
$userEnvironment = new UserEnvironment(
    isset($_SERVER['HTTP_CF_CONNECTING_IP']) ? $_SERVER['HTTP_CF_CONNECTING_IP'] : $_SERVER['REMOTE_ADDR'],
    isset($_SERVER['HTTP_X_FORWARDED_FOR']) ? $_SERVER['HTTP_X_FORWARDED_FOR'] : null,
    isset($_SERVER['HTTP_USER_AGENT']) ? $_SERVER['HTTP_USER_AGENT'] : null,
    isset($_SERVER['HTTP_REFERER']) ? $_SERVER['HTTP_REFERER'] : null,
    isset($_SERVER['HTTP_ACCEPT_LANGUAGE']) ? $_SERVER['HTTP_ACCEPT_LANGUAGE'] : null
);
```

When using another service such Apache or NGINX we can use `isset($_SERVER['HTTP_X_REAL_IP']) ? $_SERVER['HTTP_X_REAL_IP'] : $_SERVER['REMOTE_ADDR']` as shown in the following:

```php
$userEnvironment = new UserEnvironment(
    isset($_SERVER['HTTP_X_REAL_IP']) ? $_SERVER['HTTP_X_REAL_IP'] : $_SERVER['REMOTE_ADDR'],
    isset($_SERVER['HTTP_X_FORWARDED_FOR']) ? $_SERVER['HTTP_X_FORWARDED_FOR'] : null,
    isset($_SERVER['HTTP_USER_AGENT']) ? $_SERVER['HTTP_USER_AGENT'] : null,
    isset($_SERVER['HTTP_REFERER']) ? $_SERVER['HTTP_REFERER'] : null,
    isset($_SERVER['HTTP_ACCEPT_LANGUAGE']) ? $_SERVER['HTTP_ACCEPT_LANGUAGE'] : null
);
```

We can now re-run **diag.php**, if this was causing the *IP Detection* test to fail we should now have successful results.

### Logfile

This was an optional configuration during [Automatic installation](https://docs.exoclick.com/publishers/adblock/neverblock.md#neverblock-php-automatic-installation). If you wish to log request time outs and other errors, a writable log file can be created. In this example the logfile has been put into the same directory as our other NeverBlock files.

![](https://59878909-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FGoSwRYjxsR1XS6va6yLj%2Fuploads%2FziEt1tnKzsL0ED073dZh%2Fneverblock_configuration_2.png?alt=media)

Once this file is created (remember to ensure it’s writable) we will update the **backend\_loader.php** to set the path. At the top of the file `LOGFILE` will be set to **NULL** and should be updated to set the path to the new logfile like so:

```php
define('LOGFILE', 'logfile');
```

Once this is done we can re-run the **diag.php**. If the file was created and path set correctly we will now see the following.

![](https://59878909-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FGoSwRYjxsR1XS6va6yLj%2Fuploads%2Fpl5roLivXkej6m3X5gyu%2Fneverblock_configuration_3.png?alt=media)

### Caching

This was an optional configuration during [Automatic installation](https://docs.exoclick.com/publishers/adblock/neverblock.md#neverblock-php-automatic-installation). Caching can significantly improve response times for ads. If you do not have APC or APCu, which are supported by **backend\_loader.php** by default, it is recommended to set up a file cache. For this you need to set up a directory writable by php and set its path as a value for the **WRITABLE\_PATH** constant in the **backend\_loader.php**. If this constant is set - file cache will be used by default instead any other caches (even if you have APC or APCu).

```php
define('WRITABLE_PATH', '/path/to/my/writeable_folder');
```

### Identification keys

If you have used the [Automatic installation](https://docs.exoclick.com/publishers/adblock/neverblock.md#neverblock-php-automatic-installation) this has already been done during installation. These keys are used for encryption to prevent tampering with banner urls. It is strongly recommended to change values for both *KEY\_1* and *KEY\_2* in the **backend\_loader.php** to some unique strings.

```php
define('KEY_1', "t8Sn7cvBv2n8duxUyrtUxqd6i+gAywzoNo72ItPEtdU=");
define('KEY_2', "zCeopESQfMDIVekZkytm52lbdnQ2iC2RgLuh3RAhexU=");
```

### Cookies

Cookies are used to make sure NeverBlock is working as expected.

* **yuo1** - the default name of this cookie is **yuo1**, and this name can be configured in **frontend\_loader.js**. This cookie can also be disabled by setting [no\_cookie: true](https://docs.exoclick.com/publishers/adblock/neverblock.md#how-do-i-configure-neverblock-from-a-different-domain).
* **zone-closed-** - This cookie ensures that the zone stays closed if the user has closed it with adBlock enabled and then disabled the adBlock.

### Configuring constants

There are some constants defined in **backend\_loader.php**. It’s recommended to keep them as they are, but in some cases it can be useful to change some of the configurations.

* **CONNECT\_TIMEOUT\_MS** - the connection timeout in milliseconds used for curl/fsock requests.
* **REQUEST\_TIMEOUT\_MS** - the whole request timeout in milliseconds (also includes time from CONNECT\_TIMEOUT\_MS) used for curl/fsock requests.
* **LOGFILE** - a path to a writable file to log the messages, like some errors and cases when requests time out.
* **ALLOW\_MULTI\_CURL** - when possible, script tries to use curl\_multi\_exec. If this is a burden on cpu - this can be turned off.

APC/APCu and file cache settings:

* **WRITABLE\_PATH** - path to writable directory, that will contain cache files. (if this is set - file cache will become default cache to use)
* **CACHE\_INTERVAL\_BANNERS** - cache lifetime for banner images (in seconds), if set to 0 images will NOT be cached.
* **CACHE\_INTERVAL\_SCRIPTS** - cache lifetime for javascripts, if set to 0 they will NOT be cached.
* **CACHE\_KEYS\_LIMIT\_BANNERS** - the limit for number of allowed banner images to store in cache (to not overuse publisher resources), if set to 0 there will be no limit, so all the images will be cached.

If you setup some apache/nginx rewrite rules to access **backend\_loader.php** through some other URIs:

* **LINK\_URL\_PREFIX** - if is set, this will become the new URI for click links on frontend (the hash of url for redirection appended to it)
* **BANNER\_URL\_PREFIX** - if is set, this will become the new uri for banner images on frontend (the hash for specific banner appended to it)
* **KEY\_1** - secret key to prevent tampering with banner urls (they are now passed back to backend loader in request)
* **KEY\_2** - secret key to prevent tampering with banner urls (they are now passed back to backend loader in request)

## NeverBlock PHP - Displaying ads

### Adding zones to a page

These snippets are for NeverBlock 3.14 and later. On older versions, use getexoloader instead of getmsgloader.

{% hint style="info" %}
If you are using a single page application then [Dynamic loading](https://docs.exoclick.com/publishers/adblock/neverblock.md#dynamic-loading-single-page-applications) will be mandatory to implement.
{% endhint %}

The following ad formats are supported:

* Banners
* Native Ads
* Sticky Banners
* Instant Messages

{% hint style="info" %}
Multi-Format ads are not yet supported. However, you can still use NeverBlock with the single Banners that you have set up for use in Multi-Format ads. This way you can use Multi-Format ads for standard users, and NeverBlock-enabled banners to target users with ad blockers.
{% endhint %}

Please note this script will show ads only when a user has an Ad Blocker installed and enabled. Do not remove any existing standard advertising tags.

In this example we will be using the configuration described in [Renaming the files](https://docs.exoclick.com/publishers/adblock/neverblock.md#renaming-the-files-mandatory). Ensure your path and filenames match your configuration.

**Step 1 - Placing frontend\_loader.js on the page**

Inside the `<body>` tag on your page at the very top add the following:

```html
<script type="text/javascript" src="/nb/fro_lo.js"></script>
```

This should be included on the page only once. It should also be above all other zone scripts.

**Step 2 - Adding a NeverBlock zone**

The following code snippets are to declare your ad zones. They should be put in the DOM where you want the zone to be displayed. You can add multiple banner blocks like this on a page. **Be careful not to place them in divs with classes or specific style elements relevant to showing ads**, as these divs will be targeted by adblockers (E.g. `class="ad-footer"`, `style="width:300px;height:250px;"`).

To add an ad zone do the following (make sure to replace the value for idzone with your zone id):

```html
<script type="text/javascript">
    (function () {
        function randStr(e,t){for(var n="",r=t||"ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz",o=0;o<e;o++)n+=r.charAt(Math.floor(Math.random()*r.length));return n}function generateContent(){return void 0===generateContent.val&&(generateContent.val="document.dispatchEvent("+randStr(4*Math.random()+3)+");"),generateContent.val}try{Object.defineProperty(document.currentScript,"innerHTML",{get:generateContent}),Object.defineProperty(document.currentScript,"textContent",{get:generateContent})}catch(e){}var myEl={el:null};try{var event=new CustomEvent("getmsgloader",{detail:myEl})}catch(e){(event=document.createEvent("CustomEvent")).initCustomEvent("getmsgloader",!1,!1,myEl)}window.document.dispatchEvent(event);var ExoLoader=myEl.el;
        
        //Code to add zones can be placed multiple times on page
        ExoLoader.addZone({"idzone":"111"});
        
        //If you want to use sub id, add a numeric sub parameter to object, passed to addZone
        //ExoLoader.addZone({"idzone":"111", "sub": "1"});
    })();
</script>
```

**Step 3 - Serving the ads (backend\_loader.php)**

After all the *addZone()* declarations have been included we want to serve the ads. To do this we will use the *serve* function. It serves data for all previously declared ad zones and **should typically be called only once on the page**. The **max number of zones that can be called on a page is 20**. Exceptions for this are when dynamically loading a page, described in [Dynamic loading](https://docs.exoclick.com/publishers/adblock/neverblock.md#dynamic-loading-single-page-applications).

```html
<script type="text/javascript">
    (function () {
        function randStr(e,t){for(var n="",r=t||"ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz",o=0;o<e;o++)n+=r.charAt(Math.floor(Math.random()*r.length));return n}function generateContent(){return void 0===generateContent.val&&(generateContent.val="document.dispatchEvent("+randStr(4*Math.random()+3)+");"),generateContent.val}try{Object.defineProperty(document.currentScript,"innerHTML",{get:generateContent}),Object.defineProperty(document.currentScript,"textContent",{get:generateContent})}catch(e){}var myEl={el:null};try{var event=new CustomEvent("getmsgloader",{detail:myEl})}catch(e){(event=document.createEvent("CustomEvent")).initCustomEvent("getmsgloader",!1,!1,myEl)}window.document.dispatchEvent(event);var ExoLoader=myEl.el;
        
        ExoLoader.serve({"script_url":"/nb/ba_lo.php"});
    })();
</script>
```

### Dynamic loading (single page applications)

It is possible to pass a container reference to the DOM element to which the banner will be appended. This means when the serve is called it will know where to place the ad zone. This is done as follows:

```html
<script type="text/javascript">
    (function () {
        function randStr(e,t){for(var n="",r=t||"ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz",o=0;o<e;o++)n+=r.charAt(Math.floor(Math.random()*r.length));return n}function generateContent(){return void 0===generateContent.val&&(generateContent.val="document.dispatchEvent("+randStr(4*Math.random()+3)+");"),generateContent.val}try{Object.defineProperty(document.currentScript,"innerHTML",{get:generateContent}),Object.defineProperty(document.currentScript,"textContent",{get:generateContent})}catch(e){}var myEl={el:null};try{var event=new CustomEvent("getmsgloader",{detail:myEl})}catch(e){(event=document.createEvent("CustomEvent")).initCustomEvent("getmsgloader",!1,!1,myEl)}window.document.dispatchEvent(event);var ExoLoader=myEl.el;
        
        ExoLoader.addZone({"idzone":"111", "container": document.getElementById('banner1_and_placeholder')});
    })();
</script>
```

It is also possible to call the *serve()* with force flag to serve the ads at the moment you choose (e.g. in a function after rendering part of the page) instead of on page load:

```html
<script type="text/javascript">
    (function () {
        function randStr(e,t){for(var n="",r=t||"ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz",o=0;o<e;o++)n+=r.charAt(Math.floor(Math.random()*r.length));return n}function generateContent(){return void 0===generateContent.val&&(generateContent.val="document.dispatchEvent("+randStr(4*Math.random()+3)+");"),generateContent.val}try{Object.defineProperty(document.currentScript,"innerHTML",{get:generateContent}),Object.defineProperty(document.currentScript,"textContent",{get:generateContent})}catch(e){}var myEl={el:null};try{var event=new CustomEvent("getmsgloader",{detail:myEl})}catch(e){(event=document.createEvent("CustomEvent")).initCustomEvent("getmsgloader",!1,!1,myEl)}window.document.dispatchEvent(event);var ExoLoader=myEl.el;
        
        ExoLoader.addZone({"idzone":"111"});
        ExoLoader.addZone({"idzone":"222"});
        ExoLoader.addZone({"idzone":"333"});
        ExoLoader.serve({"script_url":"/nb/ba_lo.php", "force": true});
    })();
</script>
  ...
<script type="text/javascript">
    (function () {      
        function randStr(e,t){for(var n="",r=t||"ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz",o=0;o<e;o++)n+=r.charAt(Math.floor(Math.random()*r.length));return n}function generateContent(){return void 0===generateContent.val&&(generateContent.val="document.dispatchEvent("+randStr(4*Math.random()+3)+");"),generateContent.val}try{Object.defineProperty(document.currentScript,"innerHTML",{get:generateContent}),Object.defineProperty(document.currentScript,"textContent",{get:generateContent})}catch(e){}var myEl={el:null};try{var event=new CustomEvent("getmsgloader",{detail:myEl})}catch(e){(event=document.createEvent("CustomEvent")).initCustomEvent("getmsgloader",!1,!1,myEl)}window.document.dispatchEvent(event);var ExoLoader=myEl.el;

        ExoLoader.addZone({"idzone":"444", "container": document.getElementById('banner4_placeholder')});
        ExoLoader.serve({"script_url":"/nb/ba_lo.php", "force": true});
    })();
</script>
```

The *serve()* can be called multiple times. After each *serve()* call the ExoLoader will be cleared of previous *addZone()* calls. So only the banners you call *addZone()* for after a serve will show in the next *serve()*.

### Domain base

If you are an existing ExoClick customer then you may have regular ad zones on your site. If you are using a domain other than \*.exoclick.com (e.g **ads.exosrv.com**) then you should set the *domain\_base* of the detector object (`ExoLoader.getDetector()`) to “exosrv.com” before the first addZone call. This is done as shown below:

```html
<script type="text/javascript" src="/nb/fro_lo.js"></script>
<script type="text/javascript">
    (function () {
        function randStr(e,t){for(var n="",r=t||"ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz",o=0;o<e;o++)n+=r.charAt(Math.floor(Math.random()*r.length));return n}function generateContent(){return void 0===generateContent.val&&(generateContent.val="document.dispatchEvent("+randStr(4*Math.random()+3)+");"),generateContent.val}try{Object.defineProperty(document.currentScript,"innerHTML",{get:generateContent}),Object.defineProperty(document.currentScript,"textContent",{get:generateContent})}catch(e){}var myEl={el:null};try{var event=new CustomEvent("getmsgloader",{detail:myEl})}catch(e){(event=document.createEvent("CustomEvent")).initCustomEvent("getmsgloader",!1,!1,myEl)}window.document.dispatchEvent(event);var ExoLoader=myEl.el;
        
        ExoLoader.getDetector().domain_base = "exosrv.com";
    })();
</script>
...
<!-- First addZone call -->
<script type="text/javascript">
    (function () {
        function randStr(e,t){for(var n="",r=t||"ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz",o=0;o<e;o++)n+=r.charAt(Math.floor(Math.random()*r.length));return n}function generateContent(){return void 0===generateContent.val&&(generateContent.val="document.dispatchEvent("+randStr(4*Math.random()+3)+");"),generateContent.val}try{Object.defineProperty(document.currentScript,"innerHTML",{get:generateContent}),Object.defineProperty(document.currentScript,"textContent",{get:generateContent})}catch(e){}var myEl={el:null};try{var event=new CustomEvent("getmsgloader",{detail:myEl})}catch(e){(event=document.createEvent("CustomEvent")).initCustomEvent("getmsgloader",!1,!1,myEl)}window.document.dispatchEvent(event);var ExoLoader=myEl.el;
        
        ExoLoader.addZone({"idzone":"111"});
    })();
</script>
```

### No ads showing

If there are no ads showing first check the diag.php file to see if any of the configurations are incorrect. If all tests are successful create a test page with just one zone to ensure it works in isolation. At this point if no ads are showing see the [Help](https://docs.exoclick.com/publishers/adblock/neverblock.md#neverblock-php-help) section for additional details.

## NeverBlock PHP - Help

### My ads aren’t showing. What should I do?

**Verify that you are using the latest version of the adblock solution code.**

We are constantly working on improving the solution based on our tests, client feedback and changes of the adblockers. Older versions can still have certain issues that we already fixed, so please make sure you are using the most up to date one before proceeding to check other points below.

**Have you run diag.php?**

It could hint you if there is an issue with your backend loader configuration.

**Check the “Network” tab in Chrome/FF “Developer tools” toolbar.**

Is your **frontend\_loader.js** loading properly?

**Maybe you need to specify a different path?**

* Try a full path to it in src instead of “/frontend\_loader.js”
* Check that *ExoLoader.addZone()* is called **before** *ExoLoader.serve()*
* Check the “Console” tab in Chrome/FF “Developer tools” toolbar. There could be errors related to **frontend\_loader.js**
* Run `ExoLoader.getDebug();` in javascript console to see what is happening. The output looks like this:

```
2016-08-05T09:29:21.804Z: addZone() banner 2140951 added
2016-08-05T09:29:21.918Z: serve() called
2016-08-05T09:29:22.049Z: renderBannerZones() called
2016-08-05T09:29:22.049Z: renderBannerZone() #0 called for zone 2140951
2016-08-05T09:29:22.051Z: serve() hosted script loaded
```

**Check the zone ids.**

Make sure the zone with the idzone you are providing exists and it is your zone.

**Are you putting ad codes in iframes?**

Content of iframes loads after the main page. If you call *addZone()* in iframe and call *serve()* on main page, the *serve()* will be executed before *addZone()*, and it won’t work. There are two ways with iframes:

1. Include everything within an iframe: all codes from steps 1, 2 and 3 of [Adding zones to a page](https://docs.exoclick.com/publishers/adblock/neverblock.md#adding-zones-to-a-page) have to be inside it. But then if there are several iframes like this on a page, there might be a conflict, since this solution uses a cookie. If the cookie name is the same the ads in iframes can get mixed up. You can rename a cookie before calling serve, like this:

```javascript
(function () {
    function randStr(e,t){for(var n="",r=t||"ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz",o=0;o<e;o++)n+=r.charAt(Math.floor(Math.random()*r.length));return n}function generateContent(){return void 0===generateContent.val&&(generateContent.val="document.dispatchEvent("+randStr(4*Math.random()+3)+");"),generateContent.val}try{Object.defineProperty(document.currentScript,"innerHTML",{get:generateContent}),Object.defineProperty(document.currentScript,"textContent",{get:generateContent})}catch(e){}var myEl={el:null};try{var event=new CustomEvent("getmsgloader",{detail:myEl})}catch(e){(event=document.createEvent("CustomEvent")).initCustomEvent("getmsgloader",!1,!1,myEl)}window.document.dispatchEvent(event);var ExoLoader=myEl.el;

    ExoLoader.cookie_name = "exo_zones1";

    ExoLoader.serve({"script_url":"http://yoursite/backend_loader1.php"});
})();
```

The downside is that you will need to have several backend loaders, in which you will set different cookie names as well:

```php
define('ADS_COOKIE_NAME', 'exo_zones1');
```

2. Have the code from step 1 (the frontend loader file include) in the main page of your site. Inside iframes call the addZone. To correctly retrieve the ExoLoader object you will need to update the standard call to use **window\.top**.document.dispatchEvent, also into addZone pass the **doc** param that will point to the document property of your iframe:

```javascript
(function () {
    function randStr(e,t){for(var n="",r=t||"ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz",o=0;o<e;o++)n+=r.charAt(Math.floor(Math.random()*r.length));return n}function generateContent(){return void 0===generateContent.val&&(generateContent.val="document.dispatchEvent("+randStr(4*Math.random()+3)+");"),generateContent.val}try{Object.defineProperty(document.currentScript,"innerHTML",{get:generateContent}),Object.defineProperty(document.currentScript,"textContent",{get:generateContent})}catch(e){}var myEl={el:null};try{var event=new CustomEvent("getmsgloader",{detail:myEl})}catch(e){(event=document.createEvent("CustomEvent")).initCustomEvent("getmsgloader",!1,!1,myEl)}
    window.top.document.dispatchEvent(event); var ExoLoader=myEl.el;

    ExoLoader.addZone({"idzone": 111, "doc": window.document});
    ExoLoader.addZone({"idzone": 111, "doc": window.document});
})();
```

Also inside the last iframe call serve():

```javascript
(function () {
    function randStr(e,t){for(var n="",r=t||"ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz",o=0;o<e;o++)n+=r.charAt(Math.floor(Math.random()*r.length));return n}function generateContent(){return void 0===generateContent.val&&(generateContent.val="document.dispatchEvent("+randStr(4*Math.random()+3)+");"),generateContent.val}try{Object.defineProperty(document.currentScript,"innerHTML",{get:generateContent}),Object.defineProperty(document.currentScript,"textContent",{get:generateContent})}catch(e){}var myEl={el:null};try{var event=new CustomEvent("getmsgloader",{detail:myEl})}catch(e){(event=document.createEvent("CustomEvent")).initCustomEvent("getmsgloader",!1,!1,myEl)}
    window.top.document.dispatchEvent(event);var ExoLoader=myEl.el;

    ExoLoader.serve({script_url: "/backend_loader.php"});
})();
```

**Are you using a js framework for your site frontend?**

Confirm you are not overriding the innerHTML of the elements in which you have the *addZone()* calls. The *addZone()* call puts a DOM placeholder in the place where it is called. If it is overwritten by something, the script won’t be able to populate it with ad data.

**Is the backend\_loader.php returning empty response?**

If yes, check the php error log for possible related errors. After opening a page with the ExoLoader codes, open: `http://yoursite/backend_loader.php?exoDebug=exoDebug`. If any *curl/fsock* timeout errors are seen, you might need to increase values of **CONNECT\_TIMEOUT\_MS** and **REQUEST\_TIMEOUT\_MS** in the **backend\_loader.php**.

### The ads are showing, but the statistics show no clicks or no impressions

**Are you using CloudFlare or are your web-servers proxied by something else?**

The NeverBlock requests for ads are not going to our server directly from end user browser, so we are relying on the **backend\_loader.php** on the publisher side to pass us user ip. We are getting it as `$_SERVER['REMOTE_ADDR']` in this script from php global variable. If the publisher infrastructure is configured in a way that it doesn’t have a correct user ip value there could be an invalid impression/click issue. To fix please see [Passing IPs](https://docs.exoclick.com/publishers/adblock/neverblock.md#passing-ips-using-cloudflare-etc).

### When in Private Mode in Firefox (or other browser) both NB and normal ads are showing

**Please check that the domain\_base setting is configured correctly.**

[Here](https://docs.exoclick.com/publishers/adblock/neverblock.md#domain-base) you can find an example of how to configure the domain base. The issue is that in some browsers, most often FF, the Private Mode blocks requests to some domains. Exoclick.com, for example, has been blacklisted. So if the normal zone code contains “exoclick.com” domain, the Private Mode acts as an adblocker and NB solution should in fact be displaying ads. But our other domains may not be blocked by Private Mode. To avoid double ads, in order for NB detector to correctly detect if the normal ads are being blocked right now or not, it needs to know which domain they are requested from.

### How do I configure NeverBlock from a different domain?

1. In *frontend\_loader.js*, go to the function `serve: function(params)` and uncomment the params set.
2. Add another domain and set `force: true` and `no_cookie: true`:

```javascript
    params = {
                 script_url: 'https://yourotherdomain.com/backend_loader.php',
                 force: true,
                 no_cookie: true
             }
```

3. Next reference the NeverBlock path with the new domain in the page.

Frontend\_loader:

```html
<script type="text/javascript" src="https://yourotherdomain.com/frontend_loader.js"></script>
```

Backend\_loader:

```html
<script type="text/javascript">
(function () {      
    function randStr(e,t){for(var n="",r=t||"ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz",o=0;o<e;o++)n+=r.charAt(Math.floor(Math.random()*r.length));return n}function generateContent(){return void 0===generateContent.val&&(generateContent.val="document.dispatchEvent("+randStr(4*Math.random()+3)+");"),generateContent.val}try{Object.defineProperty(document.currentScript,"innerHTML",{get:generateContent}),Object.defineProperty(document.currentScript,"textContent",{get:generateContent})}catch(e){}var myEl={el:null};try{var event=new CustomEvent("getmsgloader",{detail:myEl})}catch(e){(event=document.createEvent("CustomEvent")).initCustomEvent("getmsgloader",!1,!1,myEl)}window.document.dispatchEvent(event);var ExoLoader=myEl.el;

    ExoLoader.serve({"script_url":"https://yourotherdomain.com/backend_loader.php"});
        
})();
</script>
```

### What if there is a false positive Ad Block detection?

Sometimes users who have AdBlock disabled still see NB ads displayed together with their normal ads. This may happen because NB attempts to include a honeypot real live ad serving script on the page to check whether it gets blocked or not. Sometimes on slow connections it takes too long to load that script, and the NB may consider that it was blocked, so it will make decision to request the ads. Because of the way some ad blockers work it’s not possible to tell whether the load is not finished yet, or it will never complete because of a blocker. It is not a problem for most sites and users. If it happens to a significant portion of your user base, we suggest setting a bigger timeout on NB detection using **setTimeout** function on the **ExoLoader**, like this:

```html
<script type="text/javascript">
    (function () {
        function randStr(e,t){for(var n="",r=t||"ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz",o=0;o<e;o++)n+=r.charAt(Math.floor(Math.random()*r.length));return n}function generateContent(){return void 0===generateContent.val&&(generateContent.val="document.dispatchEvent("+randStr(4*Math.random()+3)+");"),generateContent.val}try{Object.defineProperty(document.currentScript,"innerHTML",{get:generateContent}),Object.defineProperty(document.currentScript,"textContent",{get:generateContent})}catch(e){}var myEl={el:null};try{var event=new CustomEvent("getmsgloader",{detail:myEl})}catch(e){(event=document.createEvent("CustomEvent")).initCustomEvent("getmsgloader",!1,!1,myEl)}window.document.dispatchEvent(event);var ExoLoader=myEl.el;
          
        ExoLoader.setTimeout(200);
        ExoLoader.addZone({"idzone":"111"});
    })();
</script>
```

## NeverBlock API

Neverblock uses a simple endpoint to proxy requests to the ExoClick syndication servers.

This endpoint is documented below and you are free to use it to create your own custom integration in your language of choice.

### API v1

This version of API supports all the formats currently available for the neverblock solution (banners, sticky banners, native ads, instant messages).

**Single zone request**

```
https://syndication-adblock.exoclick.com/ads-multi.php?v=1&zones[0][idzone]=123456&user_ip=8.8.8.8
```

**Multi zone request**

```
https://syndication-adblock.exoclick.com/ads-multi.php?v=1&zones[0][idzone]=123456&zones[1][idzone]=654321&zones[2][idzone]=135790&user_ip=8.8.8.8
```

The requests above are similar, except that multi zone requests need to be structured with an incremental array notation (*i.e. zones\[0]\[idzone], zones\[1]\[idzone],…*) as demonstrated.

{% hint style="info" %}
Multi zone requests are limited to a maximum of **20** zones per request.
{% endhint %}

**Parameters**

The following parameters should be set for **all** requests:

* **zones\[N]\[idzone]** - *zone id to be requested*
* **user\_ip** - *end users IP (used for targeting)*

**Headers**

The following headers should be set for **all** requests:

* **X-Forwarded-For** - *Originating IP address of client*
* **Referer** - *Referring website address*
* **User-Agent** - *Client identifier*
* **Accept-Language** - *Client language and locale*

**Response**

The JSON payloads returned from the above examples are as follows.

Single zone response:

```json
{
  "zones": [
    {
      "idzone":"123456",
      "type":"sticky_banner",
      "data": {
          "image":"http:\\/\\/static.exoclick.com\\/library\\/238804\\/29d31cb0a21c35619a8e34a52b895a1d18fe4eae.gif",
          "url":"http:\\/\\/main.dynsrvaba.com\\/click.php?data=IHwyMTY4Mzk5fHxodHRwJTNBJTJGJTJGd3d3LnNreXBlLmNvbXx8fDB8fDE1MTcyNTI1NzF8b2xkLnhoYW1zdGVyLmNvbXwxMC40Mi4wLjF8fDE4MTAwMjM1fDI4MjkyNTN8NTA4fHw0MXwyfDE1fDB8MHx8NDY4eDYwfDF8MHx8NWE2YjY1MTBhYWFlODEuNDg3MjYwNzIxNDY0MzgzNjM2fDB8fDF8MHx8MXwwfDB8ICB8fDF8MHwwfDB8MHwwfDB8MHx8fDB8T0t8YzcwYTVmNDcwZDQzMDFjMjIzNDExNTRjZWMzNDIyZTg%3D",
          "v_pos":"top",
          "h_pos":"left",
          "frequency_period":"1440",
          "width":"468",
          "height":"60"
      }
    }
  ],
  "renderers":{"sticky_banner":"http:\\/\\/ads.exoclick.com\\/nb\\/sticky_banner.js"}
}
```

Multi zone response:

```json
{
  "zones": [
    {
      "idzone": "123456",
      "type": "banner",
      "data": {
        "image": "http://static.exoclick.com/library/238804/98fe7c6aee5b7348ee3b1329a48e16b418c20251.gif",
        "url": "http://main.dynsrvaba.com/click.php?data=IHwyMTY4Mzk1fHxodHRwJTNBJTJGJTJGd3d3LnlhbmRleC5ydXx8fDB8fDE1MTcyNTM2MzV8b2xkLnhoYW1zdGVyLmNvbXwxMC40Mi4wLjF8fDE4MTAwMjI5fDI4MjkyNDV8NTA4fHw0MXwyfDE1fDB8MHx8MzAweDI1MHwxfDB8fDVhNmI2NTEwYWFhZTgxLjQ4NzI2MDcyMTQ2NDM4MzYzNnwwfHwxfDB8fDF8MHwwfCAgfHwxfDB8MHwwfDB8MHwwfDB8fHwwfE9LfGY5MDQwMGEyNzE4MDIyYjBkZDNmMjg0MmM0NGVhYzA2"
      }
    },
    {
      "idzone": "654321",
      "type": "instant_message",
      "data": {
        "image": "http://static.exoclick.com/library/238804/43a77757d684abc5ee93d8169c09f3b1c9bfb650.gif",
        "url": "http://main.dynsrvaba.com/click.php?data=IHwyMTY4Mzg5fHxodHRwJTNBJTJGJTJGd3d3LnlhbmRleC5ydXx8fDB8fDE1MTcyNTM2MzZ8b2xkLnhoYW1zdGVyLmNvbXwxMC40Mi4wLjF8fDE4MTAwMjIzfDI4MjkyNDl8NTA4fHw0MXwyfDE1fDB8MHx8MjUweDE1MHwxfDB8fDVhNmI2NTEwYWFhZTgxLjQ4NzI2MDcyMTQ2NDM4MzYzNnwwfHwxfDB8fDF8MHwwfCAgfHwxfDB8MHwwfDB8MHwwfDB8fHwwfE9LfDNmNzNkOWU3OGEwM2NkNGQ5MjI5ZGRiNDhkODJiYjdk",
        "frequency_period": "1440"
      }
    },
    {
      "idzone": "135790",
      "type": "sticky_banner",
      "data": {
        "image": "http://static.exoclick.com/library/238804/29d31cb0a21c35619a8e34a52b895a1d18fe4eae.gif",
        "url": "http://main.dynsrvaba.com/click.php?data=IHwyMTY4Mzk5fHxodHRwJTNBJTJGJTJGd3d3LnNreXBlLmNvbXx8fDB8fDE1MTcyNTM2MzZ8b2xkLnhoYW1zdGVyLmNvbXwxMC40Mi4wLjF8fDE4MTAwMjM1fDI4MjkyNTd8NTA4fHw0MXwyfDE1fDB8MHx8NDY4eDYwfDF8MHx8NWE2YjY1MTBhYWFlODEuNDg3MjYwNzIxNDY0MzgzNjM2fDB8fDF8MHx8MXwwfDB8ICB8fDF8MHwwfDB8MHwwfDB8MHx8fDB8T0t8YjFmZjRiMjMyMTkyOTJkNDZjYzMyMDFhYzA2N2YxYjY%3D",
        "v_pos": "top",
        "h_pos": "right",
        "frequency_period": "1440",
        "width": "468",
        "height": "60"
      }
    }
  ],
  "renderers": {
    "banner": "http://ads.vagrant.test/nb/banner.js",
    "instant_message": "http://ads.vagrant.test/nb/im.js",
    "sticky_banner": "http://ads.vagrant.test/nb/sticky_banner.js"
  }
}
```

**Response data**

The following values can be extracted from the **zones** object per each zone in the returned JSON payload for the purpose of ad serving:

* **idzone**: Zone identifier (useful for distinguishing zone requests when processing)
* **type**: Type of ad, in **renderers** it’s possible to get the corresponding default renderer script for it. (Default renderer script expects ExoLoader object to be present in its scope)
* **data**: The ad data specific to the given ad type. Most commonly **image** and **url** can be found for banner and banner-like types, some of them have additional parameters.

In case you use the API it’s up to you to write the code generating the DOM to be displayed on front-end, based on provided data. Our default renderers are the scripts that have this responsibility as part of the default neverblock solution (php + javascript installation). They can be used with the ExoLoader js object only, which internally stores the post-processed responses in its own format and has several helper functions that renderers use and expect to be defined.

### API v0

This version of API supports only banners. It will return *false* for any zones of different type.

**Single zone request**

```
https://syndication-adblock.exoclick.com/ads-multi.php?zones[0][idzone]=123456&user_ip=8.8.8.8
```

**Multi zone request**

```
https://syndication-adblock.exoclick.com/ads-multi.php?zones[0][idzone]=123456&zones[1][idzone]=654321&zones[2][idzone]=135790&user_ip=8.8.8.8
```

The requests above are similar, except that multi zone requests need to be structured with an incremental array notation (*i.e. zones\[0]\[idzone], zones\[1]\[idzone],…*) as demonstrated.

{% hint style="info" %}
Multi zone requests are limited to a maximum of **20** zones per request.
{% endhint %}

**Parameters**

The following parameters should be set for **all** requests:

* **zones\[N]\[idzone]** - *zone id to be requested*
* **user\_ip** - *end users IP (used for targeting)*

**Headers**

The following headers should be set for **all** requests:

* **X-Forwarded-For** - *Originating IP address of client*
* **Referer** - *Referring website address*
* **User-Agent** - *Client identifier*
* **Accept-Language** - *Client language and locale*

**Response**

The JSON payloads returned from the above examples are as follows.

Single zone response:

```json
[ 
   { 
      "idzone":"123456",
      "url":"https:\\/\\/main.dynsrvaba.com\\/click.php?data=IHwyMDMyMTU4fHxodHRwJTNBJTJGJTJGdC5mcnR5aC5jb20lMkZhZmZfYyUzRm9mZmVyX2lkJTNEMTQ0NyUyNmFmZl9pZCUzRDE3MyUyNmFmZl9zdWIyJTNEJTdCY29udmVyc2lvbnNfdHJhY2tpbmclN0RfJTdCem9uZV9pZCU3RCUyNm5vcG9wfHx8MHx8MTUwODQzMTUzM3xwZXJmZWN0Z2lybHMubmV0fDg3LjE5OC4yNDkuMTU0fHwxNzI3ODUyMnwxMzc2NzAyfDUwOHx8NDF8M3wxNnwwfDB8fDMwMHgyNTB8MXwxfHw1ODU4MjRmYWFhMWFmMy41NzE5MDExODUzMzAwNDgxOXwxODcyNHx8MXwwfHwxfDB8MHwgIHx8MXwwfDB8MHwxfDc1MjEzMTR8MHwyOTY0NTc0fHx8T0t8NTM0YmY0MDdmMmUxMDM3NGZiZTBjMDIyZjZjNTFiNTE%3D",
      "imgurl":"https:\\/\\/static.exoclick.com\\/banners\\/148652\\/17918070509411500_1_xacd.gif"
   }
]
```

Multi zone response:

```json
[{
	"idzone": "123456",
	"url": "http:\\/\\/main.dynsrvaba.com\\/click.php?data=IHwyMDMyNDAyfHxodHRwJTNBJTJGJTJGb3B0aW1pc2VyLnRtdHJjay5jb20lMkYlM0Zncm91cF9pZCUzRDE2ODQlMjZzdWJpZCUzRCU3QmNvbnZlcnNpb25zX3RyYWNraW5nJTdEJTI2a2V5d29yZCUzRCU3QnpvbmVfaWQlN0R8fHwxODE4MTgxODE4MTh8fDE1MDg3NzIxOTl8b2xvbG8uY29tfDg3LjE5OC4yNDkuMTU0fHwxNzI4MDI0MHwyMTM3MjM3fDUwOHx8NDF8MnwxNnwwfDB8fDMwMHgyNTB8MXwwfHw1OTViODM5N2Q2YjZmOC45MjExMDU0MjE5MjgyOTYwMzN8MTg3MjR8fDF8MHx8MXwyNTc3OHwzNjQxOHwgIHx8MXwwfDB8MHwwfDc1MjEzMTR8MHwyOTY0NTc0fHx8T0t8M2RhMTYyNWM2YzJiOTI3ZDdmZjc3YzEyMDIzMDBkZTU%3D",
	"imgurl": "http:\\/\\/static.exoclick.com\\/banners\\/510942\\/17918091848105800_1_xacd.gif"
}, {
	"idzone": "654321",
	"url": "http:\\/\\/main.dynsrvaba.com\\/click.php?data=IHwyMDMyNDAyfHxodHRwJTNBJTJGJTJGb3B0aW1pc2VyLnRtdHJjay5jb20lMkYlM0Zncm91cF9pZCUzRDE2ODQlMjZzdWJpZCUzRCU3QmNvbnZlcnNpb25zX3RyYWNraW5nJTdEJTI2a2V5d29yZCUzRCU3QnpvbmVfaWQlN0R8fHwxODE4MTgxODE4MTh8fDE1MDg3NzIxOTl8b2xvbG8uY29tfDg3LjE5OC4yNDkuMTU0fHwxNzI4MDIyMnwyMTM3MjM3fDUwOHx8NDF8MnwxNnwwfDB8fDMwMHgyNTB8MXwwfHw1OTViODM5N2Q2YjZmOC45MjExMDU0MjE5MjgyOTYwMzN8MTg3MjR8fDF8MHx8MXwyNTc3OHwzNjQxOHwgIHx8MXwwfDB8MHwwfDc1MjEzMTR8MHwyOTY0NTc0fHx8T0t8NjdhMDM3Zjc2OGIyYTVmMWRhYjhkYTk0Njk4YTQ0ZWY%3D",
	"imgurl": "http:\\/\\/static.exoclick.com\\/banners\\/510942\\/17918091847332100_1_xask.gif"
}, {
	"idzone": "135790",
	"url": "http:\\/\\/main.dynsrvaba.com\\/click.php?data=IHwxNzU4MjI3fHxodHRwcyUzQSUyRiUyRnd3dy5jYXJ0b29udHViZS5jb20lMkZwMiUyRmluZGV4LnBocCUzRnQlM0RFWC0zMDB4MjUwLUlFLURlc2stUk9OfHx8MTgxODE4MTgxODE4fHwxNTA4NzcyMTk5fG9sb2xvLmNvbXw4Ny4xOTguMjQ5LjE1NHx8MTY3MDczNTZ8MjEzNzIzN3w1MDh8fDQxfDJ8MTZ8MHwwfHwzMDB4MjUwfDF8MHx8NTk1YjgzOTdkNmI2ZjguOTIxMTA1NDIxOTI4Mjk2MDMzfDE4NzI0fHwxfDB8fDF8MHwwfCAgfHwxfDB8MHwwfDB8NzUyMTMxNHwwfDI5NjQ1NzR8fHxPS3xkZmM4MTcwYzMyZjhkMDhmM2FhNTMxMjA4MjIyNThhMw%3D%3D",
	"imgurl": "http:\\/\\/static.exoclick.com\\/banners\\/41682\\/17713113437719500_1_xacd.gif"
}]
```

**Response data**

The following values can be extracted from the returned JSON payload for the purpose of ad serving:

* **url**: Click URL to be used to wrap the banner image
* **imgurl**: Banner image source URL
* **idzone**: Zone identifier (useful for distinguishing zone requests when processing)

## NeverBlock Proxy

### What is it?

NeverBlock Proxy is a cross platform application with the purpose of handling API requests and caching of advertisements. This service runs in the background to provide the user with a more direct endpoint through which to fetch advertisements. It is not recommended to choose NeverBlock Proxy over the standard NeverBlock PHP solution, as it is not as extensive.

Occasionally adblockers will aggressively target sites which means NeverBlock PHP will no longer work. If this is the case for your site then consider NeverBlock Proxy.

### Download NeverBlock Proxy

Download a pre-built archive for your specific platform:

* [neverblock-proxy\_v1.0.1\_darwin\_386.tar.gz](https://59878909-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FGoSwRYjxsR1XS6va6yLj%2Fuploads%2FpB7pWeraYosbq5FPjHpj%2Fneverblock-proxy_v1.0.1_darwin_386.tar.gz?alt=media)
* [neverblock-proxy\_v1.0.1\_darwin\_amd64.tar.gz](https://59878909-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FGoSwRYjxsR1XS6va6yLj%2Fuploads%2FWUivayFhNymy71fk3QJ8%2Fneverblock-proxy_v1.0.1_darwin_amd64.tar.gz?alt=media)
* [neverblock-proxy\_v1.0.1\_linux\_386.tar.gz](https://59878909-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FGoSwRYjxsR1XS6va6yLj%2Fuploads%2FDqC6cGd0LKpq0Vc7iRNJ%2Fneverblock-proxy_v1.0.1_linux_386.tar.gz?alt=media)
* [neverblock-proxy\_v1.0.1\_linux\_amd64.tar.gz](https://59878909-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FGoSwRYjxsR1XS6va6yLj%2Fuploads%2FtSRLFwzdmRH5bOF2zhoG%2Fneverblock-proxy_v1.0.1_linux_amd64.tar.gz?alt=media)
* [neverblock-proxy\_v1.0.1\_windows\_386.tar.gz](https://59878909-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FGoSwRYjxsR1XS6va6yLj%2Fuploads%2FmujYyqexiNC9pI2EQ0hp%2Fneverblock-proxy_v1.0.1_windows_386.tar.gz?alt=media)
* [neverblock-proxy\_v1.0.1\_windows\_amd64.tar.gz](https://59878909-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FGoSwRYjxsR1XS6va6yLj%2Fuploads%2FwaGUbLehUE4YWdFO9yEx%2Fneverblock-proxy_v1.0.1_windows_amd64.tar.gz?alt=media)
* [neverblock-proxy\_v1.0.1\_freebsd\_386.tar.gz](https://59878909-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FGoSwRYjxsR1XS6va6yLj%2Fuploads%2FgOcXuPP3IYYs0sRouWld%2Fneverblock-proxy_v1.0.1_freebsd_386.tar.gz?alt=media)
* [neverblock-proxy\_v1.0.1\_freebsd\_amd64.tar.gz](https://59878909-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FGoSwRYjxsR1XS6va6yLj%2Fuploads%2FcgLlblKswcpvrkqYq7Om%2Fneverblock-proxy_v1.0.1_freebsd_amd64.tar.gz?alt=media)
* [Source code (zip)](https://59878909-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FGoSwRYjxsR1XS6va6yLj%2Fuploads%2Fjs3iKFWD2UJ9wHao2JbJ%2Fneverblock-proxy-1.0.1.zip?alt=media)
* [Source code (tar.gz)](https://59878909-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FGoSwRYjxsR1XS6va6yLj%2Fuploads%2FUaPDpukcQjp8WNZEFHAc%2Fneverblock-proxy-1.0.1.tar.gz?alt=media)

The files necessary to run NeverBlock ads are:

* **neverblock-conf.toml**
* **redirect.html**
* **neverblock-proxy**

### Proxy configuration

**Put the files on the server**

Once the files have been downloaded you can put them in a directory on your server as shown in the below screenshot:

![](https://59878909-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FGoSwRYjxsR1XS6va6yLj%2Fuploads%2FSBQwdGZNe43QO6HCTXRW%2Fneverblock_nbproxy_1.png?alt=media)

**Create the cache**

Create a writable directory which will store the downloaded files. This can be created in the same folder, as we will be setting the path at a later point.

![](https://59878909-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FGoSwRYjxsR1XS6va6yLj%2Fuploads%2FdLKtaVP6n20wZWlsL5uf%2Fneverblock_nbproxy_2.png?alt=media)

**Update mandatory configuration**

At the top of the **neverblock-conf.toml** there is a section marked *Mandatory*. In this section we will set our paths based on the configuration shown in the above screenshots. Be aware that it will be unique to your configuration.

```toml
#####################
#     Mandatory     #
#####################

## Cache path (CAUTION: ALL files here will be purged at regular intervals!)
cache_path = "nb-cache/"

## Relative path to cache from web serving root (i.e "images/cache/", will default to cache_path if not set)
www_cache_path = "nb-proxy/nb-cache/"

## Path & filename to redirect html file (relative to web serving root - i.e. "misc/redirect.html")
www_redirect_path = "nb-proxy/redirect.html"
```

**Start the service**

Start the binary from a cmd prompt / terminal - this must be done inside the directory where it resides. This will start the service and you should now be able to make curl requests to localhost on port 8080.

### Usage

A cURL request is used to get the zones. This request can be implemented in any chosen language. The cURL request will return a JSON payload with a click URL as well as a relevant image path. The image has also been downloaded to your specified path. When passing the **user\_ip** be aware of the points made in [Passing IPs](https://docs.exoclick.com/publishers/adblock/neverblock.md#passing-ips-using-cloudflare-etc). The structure of this request is as follows:

```bash
curl -X POST http://localhost:8080/serve \
    -H "Content-Type: application/json" \
    -d '{
  "user_ip": "8.8.8.8",
  "user_agent": "curl/7.43.0",
  "language": "en;q=0.9",
  "referer": "https://example.com",
  "zones": [
    {
      "idzone": "1813348"
    },
    {
      "idzone": "1813348"
    },
    {
      "idzone": "1813348"
    }
  ]
}'
```

Using this structure we can see an example of this being used for PHP:

```php
$ip = $_SERVER['REMOTE_ADDR'];
if (array_key_exists('HTTP_X_FORWARDED_FOR', $_SERVER)) {
    $ip = array_shift(explode(',', $_SERVER['HTTP_X_FORWARDED_FOR']));
}

$referer = "";
if (array_key_exists('HTTP_REFERER', $_SERVER)) {
    $referer = array_shift(explode(',', $_SERVER['HTTP_REFERER']));
}

$language = "";
if (array_key_exists('HTTP_ACCEPT_LANGUAGE', $_SERVER)) {
    $language = array_shift(explode(',', $_SERVER['HTTP_ACCEPT_LANGUAGE']));
}
    
$data = [
    "user_ip" => $ip,
    "user_agent" => $_SERVER['HTTP_USER_AGENT'],
    "language" => $language,
    "referer" => $referer,
    "zones" => [
        ["idzone" => "1813348"],
        ["idzone" => "1813348"],
        ["idzone" => "1813348"]
    ]
];

$request = json_encode($data);

$ch = curl_init('http://localhost:8080/serve');
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, "POST");
curl_setopt($ch, CURLOPT_POSTFIELDS, $request);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, array(
    'Content-Type: application/json',
    'Content-Length: ' . strlen($request))
);

$result = json_decode(curl_exec($ch), true);
print_r($result);
```

### Optional configuration

There are a number of optional configs in **neverblock-conf.toml**:

* **debug** - Enable debug mode
* **port** - Service listening port
* **log** - Application log
* **http\_timeout** - HTTP Request Timeout (secs)
* **cache\_ttl** - Time to live (mins) for the cached files
* **cache\_purge\_frequency** - Cache purge run interval (mins)
* **syndication** - Exoclick Syndication URL. See [Domain base](https://docs.exoclick.com/publishers/adblock/neverblock.md#domain-base) for details on when to change this

### Flags

Flags are available to override the configuration file:

```bash
heisenberg:neverblock-proxy craig$ ./neverblock-proxy -h
Neverblock-Proxy - the AdBlock trafficker

Usage:
  neverblock-proxy [flags]

Flags:
  -c, --cache-path string    Image Cache path
  -C, --config-file string   Config file
  -l, --log string           Log file
  -p, --port string          Service port
```

## WordPress plugin

### Plugin installation

The plugin can be downloaded using the following link:

* [neverblock\_wp.zip – v1.13](https://59878909-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FGoSwRYjxsR1XS6va6yLj%2Fuploads%2FFlNcVzwtfnwWcuWWe6eW%2Fneverblock_wp.zip?alt=media) (NeverBlock version 3.14)

Installing the NeverBlock plugin for WordPress is no different to any other plugin. In the menu select **Plugins** -> **Upload Plugin** -> select the NeverBlock plugin to install.

![](https://59878909-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FGoSwRYjxsR1XS6va6yLj%2Fuploads%2FFyBwRaXNSVoZZO46rsnn%2Fneverblock_wp_1.png?alt=media)

**Step 1 - Introduction**

The first page of the installation wizard will not require any input.

**Step 2 - System Requirements**

In this step we will see the results of tests on the configuration. The results that you see may vary depending on your setup.

![](https://59878909-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FGoSwRYjxsR1XS6va6yLj%2Fuploads%2FigUqsco4QT753tqfflea%2Fneverblock_wp_2.png?alt=media)

For more details regarding each of these tests, the results, and running manually see these sections: Run the diag.php and Possible diag.php results.

**Step 3 - Plugin Settings**

In the configuration section of NeverBlock PHP there is a section on [Configuring constants](https://docs.exoclick.com/publishers/adblock/neverblock.md#configuring-constants). Step 3 of the installation wizard allows you to configure these settings. Details on each of these settings are covered in the related section, and are also described in the screenshot below.

![](https://59878909-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FGoSwRYjxsR1XS6va6yLj%2Fuploads%2FZJxj1ZfINzStqP6JmgnP%2Fneverblock_wp_3.png?alt=media)

These configurations can be changed at any point after installation.

**Step 4 - Done**

Once installation is complete you will see the **NeverBlock** option in your menu. Here we can choose to change the plugin settings when needed:

![](https://59878909-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FGoSwRYjxsR1XS6va6yLj%2Fuploads%2FLyIk36QD848C12vTaTHS%2Fneverblock_wp_4.png?alt=media)

### Adding zones in WordPress

There are two ways in which NeverBlock zones can be added to your WordPress page.

**Shortcodes**

In TinyMCE, when creating/editing a post just add it as follows, ensuring that you use the correct idzone:

```
[neverblock idzone=123456]
```

Alternatively, use the following as an example for a theme template:

```php
<?php echo do_shortcode('[neverblock idzone=123456]') ?>
```

Note that there is an optional `container_id` attribute that can be used to reference an id of a DOM node. This will append it to the related div. The div has to be present before the shortcode for this to work otherwise NeverBlock will not find the element.

```
<div id="my-ad-container-id"></div>
[neverblock idzone=123456 container_id="my-ad-container-id"]
```

**Regular scripts**

When editing a theme template you can use the standard scripts outlined in [Displaying ads](https://docs.exoclick.com/publishers/adblock/neverblock.md#adding-zones-to-a-page).

## Changelog

Please refer to the CHANGELOG file contained within the software package.

### NeverBlock PHP changelog

**3.14 (21.10.2026)**

* NeverBlock backend loader fails to serve ads locally even after fixing deprecated PHP notices and IP detection
* Since 3.14, the loader event is getmsgloader. If you upgrade to 3.14, update your snippet. The old snippet (getexoloader) fails with the error: Cannot read properties of undefined (reading 'addZone').

**3.12 (10.01.2025)**

* Fix Neverblock > diag.php always returns “Can’t access service to compare IPs” in IP detection

**3.11 (11.07.2023)**

* Fixed compatibility with php 5.2 and above

**3.10 (12.01.2022)**

* Add a parameter that may be used for forward compatibility
* Add support of webp format

**3.9 (03.12.2021)**

* Add detection timeout to avoid false positives on slow connections

**3.8 (10.06.2021)**

* Remove popunder-related code (inline is the preferred way) and unnecessary cookie

**3.7 (05.07.2019)**

* Some measures against “anti-cv” filter

**3.6 (16.05.2019)**

* Remove js object reference, which is sometimes blocked
* New ip detection API in diag (supports ipv6)

**3.5 (14.03.2019)**

* Add functionality to remove partially blocked ads
* Add no\_cookie param to allow having backend\_loader.php on different domain
* Add acpu cache support

**3.4 (09.07.2018)**

* Improve detection (wait for page load)

**3.3 (25.05.2018)**

* Update documentation link for passing IPs
* Fix window\.ExoLoader override with error by some blockers (uBlock)
* Replace old IP detection service

**3.2 (15.03.2018)**

* Fix error with php <= 5.3

**3.1 (07.03.2018)**

* Auto-randomize banner and link parameter names, add more flexible control
* Fix js error if serve() called multiple times

**3.0 (30.01.2018)**

* Introduced concept of requested renderers
* Added new ad formats: native ad, sticky banner, web & mobile instant message
* Dynamic ExoLoader object naming in case it’s made immutable by adblockers
* Small changes to facilitate phar installer and wordpress plugin
* PHP version auto-checked for multi curl

**2.25 (12.10.2017)**

* Fix check for response body text change in diag ads request
* Log errors returned from ad server
* Fix ip detection diagnostics (use setup from backend\_loader.php)

**2.24 (15.08.2017)**

* Check ip detection in diagnostics script
* Ability to host backend\_loader.php on different domain

**2.22 (13.06.2017)**

* Detection: Do not allow site box-sizing styling influence the DOM trap parameters

**2.21 (09.06.2017)**

* Solve issue with false positives during adblock detection

**2.20 (01.06.2017)**

* Changed blocker detection
* Fix issue with several serve() runs overriding each other’s cookie

**2.19 (24.05.2017)**

* Solve issue with exchange campaigns and 404 banner
* Small fixes for 5.2 php version

**2.18 (07.04.2017)**

* Send correct header for javascript in case of strict headers validation

**2.17 (27.03.2017)**

* Fix the interface error for older php versions in backend\_loader.php
* Fix frontend\_loader.php open link issue when LINK\_URL\_PREFIX specified

**2.16 (14.03.2017)**

* Allow adding zones dynamically. Not only on page load
* Add container reference as addZone parameter

**2.15 (08.03.2017)**

* Add file cache.
* Decrease the amount of transferred data.
* Load banners through `<img>`, instead of base64 background style.

**2.14 (30.09.2016)**

* Fix resolveMulti to always return array

**2.13 (14.09.2016)**

* Properly pass post params for openLink

**2.12 (12.09.2016)**

* Completely move inline styles to css classes

**2.11 (09.09.2016)**

* Fix document.contains undefined issue in IE

**2.10 (07.09.2016)**

* Fix problems with ipv6 connectivity + curl
* Fix issues with incorrect click links because of server-side aliases

**2.9 (02.09.2016)**

* Change the open link mechanism to redirect through backend loader

**2.8 (30.08.2016)**

* Resolve the https ads issue with outside of curl DNS resolution and caching

**2.7 (22.08.2016)**

* Switch ad endpoints to https to avoid mixed content problems

**2.6 (17.08.2016)**

* More generic DOM placeholder for banners
* Fix issue with headers
* Separate errors from debug messages in frontend loader
* Troubleshooting instructions

**2.5 (02.08.2016)**

* Introduce log for timed out requests and other errors
* Fix js error when something overwrites DOM placeholder for ad

**2.4 (22.07.2016)**

* Better timeouts
* Diagnostics file and better debugging

**2.3 (20.07.2016)**

* Fix minor issue with making request to backend loader, when no zones were added

**2.2 (15.07.2016)**

* New domain for ads-endpoint with better load balancing

**2.1 (27.06.2016)**

* Fix incompatibility with Prototype framework

**2.0 (14.06.2016)**

* Open release
* Single request for multiple ads
* Unified loader for banners

### NeverBlock Proxy changelog

**1.0.1**

* Allow Language and Referer to be passed in request
* Updated examples

**1.0.0**

* Initial release


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.exoclick.com/publishers/adblock/neverblock.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
