TruBlock Product Documentation

1.What is TruBlock™? #

TruBlock™ is Adtoniq’s technology platform for bringing you accurate and reliable ad block detection and analytics upon which you can build solutions for addressing the needs of today’s ad block users. TruBlock™ analytics gives you one of three critically important numbers you need to evaluate the revenue potential locked up in your blocked web: How many ad blocked users do you really have? You can read more about how to calculate the value of your blocked web here.

Once you install Adtoniq, our servers will contact your content management system at least once per day with secure updates designed to ensure that your ad block detection solution continues to work 100%. This is similar to the way your antivirus software works, that receives regular updates as new virus threats evolve, only we’re defending you against evolving ad block threats as opposed to evolving viruses.

2.How to install Adtoniq TruBlock™ #

You can install Adtoniq TruBlock in a few minutes by following these steps:

  1. Inside your WordPress admin interface, click on Plugins
  2. Click Add New and search the marketplace for TruBlock
  3. Once you see Adtoniq TruBlock, click Install Now, then click Activate
  4. Click on the Adtoniq TruBlock gear icon and complete the registration form
  5. Confirm your email address
  6. Start viewing your analytics!

The video below shows all these steps in detail.

 

3.TruBlock Analytics Explained #

TruBlock™ Analytics

TruBlock™ is our platform for accurately detecting and recording information about your ad blocked audience. Once you install Adtoniq on your website, it records ad block analytics on every page view, except for those requests that come from robots that identify themselves as such, such as search engines like Google. This information is stored securely on Adtoniq’s servers. We are currently researching how to best filter out evil bots that hide their intentions, but at this time Adtoniq may report page views from evil bots.

Monthly & Realtime Adblock Rate

capture

You can view your analytics by clicking on the Adtoniq gear icon on the left side of your WordPress administrative interface. Adtoniq breaks down your traffic into three groups color coded red, yellow, and green. Green is your unblocked audience, those with no ad blocker enabled. Note that these users may in fact have an ad blocker installed, but may have whitelisted your website. Yellow and red represent two parts of your blocked audience. Yellow represents ad blocked users who have opted into acceptable ads, and red represents those users who have opted out of acceptable ads.

Both graphs show a rolling time window. The graph on the left shows the last 30 days as of the moment the page loads, and the realtime graph shows the last 30 minutes and is updated in realtime every few seconds to show current traffic on your site.

Acceptable Ads

acceptableadslogoAcceptableAds is an advertising standard supported by many ad blockers that seeks “to create a sustainable middle ground between the user’s choice to use ad blockers and the continued need to support free online content with advertisements.” Because the most popular ad blockers come with AcceptableAds enabled by default, it is likely that a significant percentage of your ad blocked audience already has acceptable ads enabled. But exactly how many of your ad blocked viewers actually have acceptable ads enabled? How can you know if you don’t measure it?

Adtoniq measures the exact number of your viewers that have acceptable ads enabled, so that you can make sound business decisions around whether or how you as a publisher want to support Acceptable Ads.

4.Understanding TruBlock [shortcodes] #

WordPress shortcodes provide the building blocks so you can communicate with your ad blocked audience, offer choices, and take actions such as protecting content or taking a subscription or micropayment. This page shows how all the Adtoniq shortcodes work by providing very simple live demonstrations of them along with one line of source code for that example. This is where you can get creative and think about how to best meet the needs of your ad blocked audience. Do you want to protect content on your site? Encourage users to sign up for a subscription, or to whitelist you, or maybe enable acceptable ads?

To see all the shortcodes in action, you’ll need to refresh this page once with your adblocker enabled, then again with it disabled, then again with acceptable ads enabled, and so on.

You can find another demonstration of these short codes on the ad block test page.

 

The following WordPress shortcodes are available. Inside the cyan colored box you’ll find a live running example of each shortcode. You may need to wait a few seconds to see the shortcode values appear, as they need to wait until the adblock detection cycle is complete.


adtoniq_message_adblocked

Content placed inside this shortcode will be displayed to all users with an ad blocker enabled, whether it is a browser extension, dedicated ad block browser, or network-based ad blocker. This content is not displayed to users who have white-listed you or who are otherwise not blocking you.

What's inside the cyan box above:
[adtoniq_message_adblocked]Won't you consider white-listing us?[/adtoniq_message_adblocked]

adtoniq_message_nonblocked

Content placed inside this shortcode will be displayed to all users with no ad blocker enabled, including those users who have white-listed you..

What’s inside the cyan box above:

[adtoniq_message_nonblocked]Thank you for not using an ad blocker.[/adtoniq_message_nonblocked]

adtoniq_message_adblocked_acceptable

Content placed inside this shortcode will be displayed to all users with an ad blocker enabled that is configured to allow acceptable ads.

What’s inside the cyan box above:

[adtoniq_message_adblocked_acceptable]
Thank you for allowing us to display acceptable ads
[/adtoniq_message_adblocked_acceptable]

adtoniq_message_adblocked_noacceptable

Content placed inside this shortcode will be displayed to all users with an ad blocker enabled that is configured to block (not allow) acceptable ads.

What’s inside the cyan box above:

[adtoniq_message_adblocked_noacceptable]
Won't you consider allowing acceptable ads?
[/adtoniq_message_adblocked_noacceptable]

5.Get full control using the TruBlock JavaScript API #

The Adtoniq JavaScript API provides a callback mechanism for your JavaScript code so that you can be alerted of various Adtoniq events. Each function takes one parameter, which is the callback function to invoke. The following functions are available:

adtoniq.addAdBlockerCallback

The addAdBlockerCallback function is called when the ad block detection phase is completed. The callback function is passed four boolean parameters which indicate the results of the ad block detection phase and give you fine grained control over how you’d like to respond:

  1. blocksNetworkServices is true if the ad blocker blocks network connections to common services such as ad servers
  2. hidesElements is true if the ad blocker hides or collapses elements on the page like ad units or messages
  3. allowsAcceptableAds is true if the ad blocker is configured to allow acceptable ads
  4. allowsAnalytics is true if the ad blocker is configured to allow analytics services such as Google Analytics to run

For example, if your user is preventing ads from running, you might choose a range of responses to that, ranging from asking them to whitelist you, to offering a subscription, or restricting or metering content.

If page elements are being hidden on your pages, this is typically ad units on the page that have been hidden. You can choose to dynamically fill these locations with other content, with the understanding that this content may only be displayed to ad blocked users if you so choose.

If the ad blocker allows acceptable ads, you may choose to replace your normal ad units with acceptable ads from your choice of ad network.

If allowsAnalytics is true, you know that this blocker is allowing analytics services such as Google Analytics to run. If this is false, you may choose to interact with the ad blocked user, offering them an incentive for letting you track them, along with one or more ways to opt out of being tracked.

adtoniq.addNoAdBlockerCallback

The addNoAdBlockerCallback function is used to add a callback function when no ad blocker is detected. The callback function is passed no parameters.

You could use this function to display a thank you message to your readers for not blocking your content.

adtoniq.onBlocked

The onBlocked function is used to add a callback function as soon as the first ad block detection signal is received. This will usually be much faster than addAdBlockerCallback because it will fire on the first ad block detection signal, as opposed to waiting for all signals to arrive. If you want to interact with your ad blocked audience without waiting for all the signals to come in, you should hook this event. The callback function is passed no parameters.

adtoniq.onAnalyticsBlocked

The onAnalyticsBlocked function is used to add a callback function if the ad blocker is actively blocking analytics from running. If you want to interact with this segment of your ad blocked audience, you should hook this event.

The callback function is passed no parameters.

6.How to create your own TruBlock test page #

To create our own ad block test page on your own WordPress server, you can use the Adtoniq WordPress shortcodes to show the correct content. Copy and paste the code below into the Text mode of your WordPress page editor: Make sure you use Text mode of the editor and not the Visual mode, or this will not work properly.

<h1 style="text-align: center;">
 <span style="color: #ff0000;">
   [adtoniq_message_adblocked_noacceptable]
     You are using an ad blocker with acceptable ads disabled
     <img class="wp-image-630 size-medium aligncenter"
     src="//tech.adtoniq.com/wp-content/uploads/2016/11/Stop.png"
     alt="Stop" width="300" height="300" />
   [/adtoniq_message_adblocked_noacceptable]
 </span>
</h1>
<h1 style="text-align: center;">
 <span style="color: #003300;">
   [adtoniq_message_nonblocked]
     You are NOT using an ad blocker
     <img class="wp-image-629 size-medium aligncenter"
     src="//tech.adtoniq.com/wp-content/uploads/2016/11/Go.png"
     alt="Go" width="300" height="232" />
   [/adtoniq_message_nonblocked]
 </span>
</h1>
<h1 style="text-align: center;">
 <span style="color: #ff6600;">
   [adtoniq_message_adblocked_acceptable]
     You are using an ad blocker with acceptable ads enabled
     <img class="wp-image-629 size-medium aligncenter"
     src="//tech.adtoniq.com/wp-content/uploads/2016/11/Acceptable-Ads.png"
     alt="Go" width="300" height="232" />
   [/adtoniq_message_adblocked_acceptable]
 </span>
</h1>

7.About Adtoniq quotas and pricing plans #

Coming soon…

8.About updating your Adtoniq JavaScript #

Coming soon

9.How Adtoniq supports private / test servers #

Coming soon…

10.Performance impact of Adtoniq on your website #

Companies today should look at their webpage load time as a key performance indicator, and we understand that this is important, so we have designed Adtoniq to ensure it will have minimal impact on your performance. When you add Adtoniq to your website, it will inject 11K or more of JavaScript inline into your pages for ad block detection and analytics. The exact amount of JavaScript injected depends on which optional Adtoniq modules you are using – some modules require additional JavaScript. TruBlock makes no asynchronous calls to load additional information. At 3G mobile speeds, this can add up to a few milliseconds to your page load time, which is not noticeable, and at WIFI speeds makes no measurable difference in your page load time.

Adtoniq will consume less than 1 ms of CPU processing time to detect ad blockers and send analytics.

Adtoniq uses one AJAX call to send analytics information to its servers. The total size of data sent in the AJAX call is about 500 bytes and has no effect on performance.

 

Methodology

It is important to ensure that we can tell our customers how much latency we add to the page load time for a customer’s website. The focus for this test is comparing two scenarios, as we are asking customers to migrate from the first scenario to the second scenario:

  1. Website using standard Google Analytics script, no Adtoniq
  2. Website using Adtoniq for GA, AdBlock enabled and blocking GA

In our testing, we tested how how long it takes for the DOMContentLoaded event to fire in the Chrome web browser with and without Adtoniq. The DOMContentLoaded event is fired when the initial HTML document has been completely loaded and parsed, without waiting for stylesheets, images, and subframes to finish loading.

The test is performed once with no network throttling on a fast network connection (>= 100Mbps) and a second time with band-width throttled 1.5Mbps connection simulating a 3G network.

The test was performed using the Chrome browser on a fast Windows 10 computer. AdBlock was used, and configured to block Google Analytics.

The browser cache was disabled for all tests.

Test Results

1.5Mbps, 3G Good network throttling:

With no ad blocker, standard GA script, no Adtoniq plugins
Load event: 1,421ms
Size: 208KB

With ad blocker blocking GA, Adtoniq plugins
Load event: 1,419ms
Size: 218KB

Fast network (no throttling)

With no ad blocker, standard GA script, no Adtoniq plugins
Load event: 420ms
Size: 208KB

With ad blocker blocking GA, Adtoniq plugins
Load event: 550ms
Size: 218KB

Analysis of Results

The analysis shows that using Adtoniq for Google Analytics introduces about 1/10th of a second latency on fast network connections, and no measurable latency on a slower 3G connection. The total data downloaded increases by 10KB, which is mostly the Adtoniq JavaScript.

11.How to estimate your ad block losses #

Most times an ad blocked user shows up on your website, you are prevented from running critical services you deployed on your website for the purpose of generating revenue or monetizing that user or otherwise supporting your business. You can calculate the financial impact this has on your business by using the Adtoniq revenue loss calculator.

To use this calculator, you need to calculate the average revenue per page view that a user is worth to you. If you generate ad revenue per page view, this would be the RPM (Revenue Per Mille) number you get from your ad server. Use the Price Adjust field to enter a discount for your blocked web, to estimate your total monthly blocked revenue.

12.How to get customer support #

Have a problem or question about using Adtoniq? We have a few ways for you to contact us:

  1. Use the chat widget on the bottom of the screen
  2. Contact support@adtoniq.com to enter a support ticket into our customer support system
  3. Call us at 415.340.1949

Our support hours are 6am – 6pm Pacific Standard Time.

Help Guide Powered by Documentor
Suggest Edit