AntiAdBlock.Core

Detection API // for developers

The adblock detection API that sends the result to your code

The AntiAdBlock Core adblock detection API runs our maintained, multi-signal detection with no popup and nothing else on screen. On each page a visitor opens, your JavaScript gets one result through the aabc:detection event, the AABC_ON_DETECT callback or the AABC_DETECTION snapshot: whether a blocker was found, what kind, and the browser. It comes with the Max and Business plans.

Start free Read the API reference

Included in Max ($12.99 a month) and Business. Try the same engine on Free: 5,000 detections a month, no payment method.

  1. A visit
  2. Detection nothing on screen
  3. aabc:detection AABC_ON_DETECT() AABC_DETECTION
  4. Your code you decide

event.detail

detected: true,blockerType: "extension",path: "…",browser: "chromium"

Illustration only. No detection runs on this page.

What an adblock detection API does

An adblock detection API (or ad blocker detection API) tells your own code, page by page, whether the visitor is blocking ads, so your product can respond in its own way instead of showing a vendor's popup. In AntiAdBlock Core it is a script mode you choose per site. Recovery, the default, shows our notice. Detection API runs the same engine from the same tag, shows nothing and hands the result to your code.

It is a JavaScript API in the visitor's browser: no REST endpoint, no API key and no package, just your site's tag and a listener.

Two modes, one tag
Recovery mode defaultDetection API mode Max and Business
Visitor seesOur noticeOnly what your code shows
Who respondsThe noticeYour code
Notice in the scriptYesNot included
PlansEvery planMax and Business

Same engine // same tag // same quota

One result per page, in four fields

Every result is a read-only object with exactly four keys, and it uses the same blocker types as your dashboard.

The Detection API result payload
FieldValuesWhat it tells you
detectedtrue, falseWhether an ad blocker was confirmed on this page. false is sent too, so a page without a blocker gets an explicit answer.
blockerTypeextension, brave_shields, browser_protection, network_dns, unknown, nullWhat is doing the blocking: an extension, Brave Shields, the browser's own protection, or network and DNS filtering such as Pi-hole. unknown: confirmed but not attributed. null when detected is false.
pathan internal reference letter, FORCE in the test, or nullA reference code to quote in support tickets; FORCE marks a test, null when detected is false. Don't branch on it.
browserchromium, firefox, edge, brave, webkit, otherThe browser family, so your message can match it. Always set.
The same object, key by key

{detected: true, // booleanblockerType: "extension", // string | nullpath: "…", // string | nullbrowser: "chromium" // string}

Blocker found
{
  "detected": true,
  "blockerType": "extension",
  "path": "…",
  "browser": "chromium"
}
No blocker
{
  "detected": false,
  "blockerType": null,
  "path": null,
  "browser": "firefox"
}

In the first example, path is elided: it holds an internal reference letter.

Types, timing and the edge cases are in the reference:

Read the adblock detection API reference

Read it with an event, a callback or a snapshot

All three carry the same object. Register the listener or define the callback before our tag; the snapshot is there for code that runs later.

aabc:detection
<script>
window.addEventListener("aabc:detection", function (event) {
  // event.detail = { detected, blockerType, path, browser }
  var result = event.detail;
  if (result.detected) {
    // Your logic: your own message, a gated section,
    // an analytics event.
  }
});
</script>
window.AABC_ON_DETECT
<script>
window.AABC_ON_DETECT = function (result) {
  if (result.detected &&
      result.blockerType !== "network_dns") {
    document.documentElement.classList.add("adblock-on");
  }
};
</script>

Recommended when the decision matters: the script calls your function directly.

window.AABC_DETECTION
var result = window.AABC_DETECTION;
if (result && result.detected) {
  // Code that runs late, such as a single-page app view.
}

Undefined until the first result, then always the latest one.

What you can build on the result

The result drives your interface and your numbers. Each rule starts from the result:

Condition // what your code does

  1. if (detected)

    Your own message. Your words and your design, where it fits the page.

  2. if (detected)

    A gated download or section. Keep the download button or the rest of the article behind your explanation or your own registration wall.

  3. if (detected)

    A player on hold. Pause video or audio behind your message.

  4. blockerType === "network_dns"

    A lighter note. Pi-hole or a DNS filter can't be switched off in one click: show a short note, or nothing.

  5. every result

    Your analytics. Your ad-block rate by section, device or country.

  6. no result

    Your normal page. No answer is not "no blocker": fail open and keep your default path.

A result in the browser shapes the experience; anything that must hold, such as paid articles, belongs on your server.

See what a missing result means

Set it up in three steps

  1. Tag

    Add the tag

    Copy your tag from the Your script tag card in the site's Overview tab and paste it into the <head> of every page, or use our WordPress plugin. A new site gets first-party delivery by default: once its DNS record is live, the tag loads from your own subdomain, for maximum detection. See where the tag goes on each platform.

  2. Mode

    Switch the site to Detection API

    On Max or Business, open the site, go to the Configuration tab and choose Detection API in the Script mode card, available once your domain is verified. The tag stays the same, and pages opened after the change use the new mode within a minute.

  3. Code

    Add your code, then test it

    Put your callback or listener before the tag. Add #aabc_force to any URL on your site and reload the page to get detected: true with path: "FORCE" and nothing on screen.

Your page, in this order
<script>
window.AABC_ON_DETECT = function (result) {
  // Your logic here.
};
</script>
<script async
  src="https://antiadblockcore.com/s/SITE_ID.js"
  data-aabc-site="SITE_ID"
  crossorigin="anonymous"></script>

01 // your code 02 // the tag

Example with SITE_ID. Copy your own tag from the dashboard: with first-party delivery, its src is on your own subdomain.

Start free Follow the integration guide

The step-by-step guide adds a full example with a time limit, single-page apps and troubleshooting.

Which plans include the Detection API

The Detection API comes with Max and Business. It stays off until you switch it on for a site, so one site can run the API while another keeps the notice, on the same account and quota.

Plans // Detection API

  1. Free

    $0 no payment method

    • 5,000 detections a month
    • one site

    Detection API not included (Recovery mode only)

  2. Pro

    $5 a month

    • 100,000 detections a month
    • 2 sites

    Detection API not included (Recovery mode only)

  3. Max

    $12.99 a month

    • 1,500,000 detections a month
    • 3 sites

    Detection API included

  4. Business

    $29.99 a month

    • 5,000,000 detections a month
    • 5 sites

    Detection API included

A detection is a page view where a blocker is found, in either mode; page views without one never count. For example, with 20 to 30% of visitors blocking ads, Max covers about 5 to 7.5 million page views a month. The quota is shared across your sites and we email you at 80%. If it runs out, the script goes quiet until your next cycle and your code takes its default path. If a plan change removes the API, the site goes back to Recovery mode and shows our notice again.

To try it first, Free gives you 5,000 detections a month with the notice on and no payment method. Prices are flat and in US dollars.

Start free Compare plans

A maintained service instead of a detection library

A package from npm is code you ship and keep current yourself. The BlockAdBlock library on GitHub, for example, published its latest version, 3.2.1, in March 2016 and its last commit in December 2018 (checked on 11 October 2026; see AntiAdBlock Core vs BlockAdblock).

Keeping detection current

BlockAdBlock on GitHub

  1. latest version, 3.2.1
  2. last commit
  3. checked

AntiAdBlock Core Detection API

We do, daily

A detection library compared with the AntiAdBlock Core Detection API
A detection library in your bundleAntiAdBlock Core Detection API
Keeps detection currentYou, or its maintainerWe do, daily
What your code receivesWhatever the library returnsdetected, blockerType, browser and path
Brave Shields and DNS blockingDepends on the librarySeparate blockerType values
When it can't answerDepends on the libraryNo result, documented: fail open
What you installA package you updateOne async tag, no package
Your numbersYour own loggingDetections and blocker types in your dashboard
PriceUsually freeMax and Business plans

Thinking of writing your own checks? Our guide detect adblock with JavaScript without maintaining the detection explains why copy-paste detection stops working and how to read a maintained result instead. Choosing a detector for a site rather than for your code? See the four kinds of adblock detector.

See the engine at work first

The live demo walks through a blocked visit with the notice and links to an example site that runs the real script in its default mode. It is the same engine the Detection API runs; only what happens after the result is different.

Watch the live demo

Adblock detection API: questions developers ask

What is an adblock detection API?

It is a way for your own code to learn, page by page, whether the visitor is blocking ads, so you decide the response. With AntiAdBlock Core it is a script mode: the same detection runs with nothing on screen, and your JavaScript receives detected, blockerType, browser and path through an event, a callback or a snapshot. It comes with the Max and Business plans.

What does the visitor see in Detection API mode?

Nothing from us: no popup, no notice and no prompt to allow ads. In this mode the notice isn't even part of the script your visitors download. They see only what your code decides to show, which can be nothing if you just want to measure. The mode is set per site on the Max and Business plans, and the tag stays the same.

Is it a REST API?

No. It is a JavaScript API in the visitor's browser: there is no REST endpoint, no API key and no package to install. Your site's tag runs the detection and hands the result to your own code through the aabc:detection event, the AABC_ON_DETECT callback or the AABC_DETECTION snapshot.

Is there a JavaScript event when an ad blocker is detected?

Yes. The script dispatches aabc:detection on window after its first full evaluation of each page, never before DOMContentLoaded, with the result in event.detail. It fires when no blocker is found too, with detected set to false, and again only if the result changes when the visitor returns to the tab. Without a listener, define window.AABC_ON_DETECT or read window.AABC_DETECTION; the aabc:detection event reference has the details.

Can I try the Detection API for free?

Not the API itself: it comes with Max and Business. The Free plan, 5,000 detections a month with no payment method, runs the same engine with the notice and the live dashboard, so you see your ad-block rate on your own traffic first. On Max or Business, you switch the site to Detection API in its Script mode card and keep the same tag.

Which blocker types does the result report?

blockerType is extension, brave_shields, browser_protection, network_dns or unknown, and null when nothing was detected. network_dns is blocking outside the browser, such as Pi-hole or a DNS filter: those visitors usually can't turn it off with one click, so asking them to allow your site only frustrates them. On Firefox and Edge, blocking that happens only at the network level is reported as browser_protection, as in your dashboard.

Can I send the result to Google Analytics?

Yes. Read the result once per page and push the fields to your data layer, or send them as a GA4 event. Many ad blockers also block analytics tags, so part of the blocked visits never reach GA4: use it for trends by page, device or country, and your AntiAdBlock Core dashboard for the full count of detections and blocker types. The API reference has a ready snippet for Google Tag Manager.

How do I use it with React or Next.js?

Add the tag once (in Next.js, inside the head of the root layout) and read the result in a client component: window.AABC_DETECTION holds the latest result and the aabc:detection event delivers new ones. The result arrives when a page is opened or reloaded, not on client-side route changes, so keep the last result in your app state. The API reference has a small React hook.

Put the result in your own code

Start on Free to see your ad-block rate, then switch a site to the Detection API on Max or Business.

Start free Read the API reference

Free plan with no payment method // prices in USD // cancel from your dashboard

Built and maintained by the AntiAdBlock Core team. Page reviewed on .