Adblock detection API reference

Enable it

Requires The AntiAdBlock Core script tag on a site in Detection API mode (Max or Business plan).

The Detection API comes with Max ($12.99 a month) and Business. Free runs the same engine with the notice: 5,000 detections a month, no payment method.

The script tag

The same tag runs both modes. Copy it from the Your script tag card in the site's Overview tab and paste it into the <head> of every page where you want a result, as early as you can. It loads with async, so it never blocks rendering.

<script async
  src="https://antiadblockcore.com/s/SITE_ID.js"
  data-aabc-site="SITE_ID"
  crossorigin="anonymous"></script>

The result payload

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

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

{
  "detected": false,
  "blockerType": null,
  "path": null,
  "browser": "firefox"
}

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

blockerType values

extension

an ad-blocking browser extension.

brave_shields

the Shields built into the Brave browser.

browser_protection

the browser's own protection, such as a strict tracking protection mode. On Firefox and Edge, network-only blocking is reported here too, the same way your dashboard reports it.

network_dns

blocking outside the browser, at network or DNS level, such as Pi-hole, AdGuard DNS or NextDNS. These visitors usually can't turn it off in one click, so treat them differently: asking them to allow your site only frustrates them.

unknown

a blocker was confirmed but not attributed to one of the types above.

TypeScript

export type AabcResult = Readonly<{
  detected: boolean;
  blockerType:
    | "extension"
    | "brave_shields"
    | "browser_protection"
    | "network_dns"
    | "unknown"
    | null;
  // a reference code; "FORCE" for the #aabc_force test
  path: string | null;
  browser:
    | "chromium"
    | "firefox"
    | "edge"
    | "brave"
    | "webkit"
    | "other";
}>;

declare global {
  interface Window {
    AABC_DETECTION?: AabcResult;
    AABC_ON_DETECT?: (result: AabcResult) => void;
  }
  interface WindowEventMap {
    "aabc:detection": CustomEvent<AabcResult>;
  }
}

The payload carries these four keys and nothing else. Because it is frozen, copy it (for example with { ...result }) before you add fields of your own.

Three ways to read the result

Use whichever fits your setup, or several: all three carry the same object. For each result, the snapshot is updated first, then the event fires, then the callback is called. When the decision matters, use the callback: the script calls your function directly.

1. snapshot
2. event
3. callback

<script>
window.addEventListener("aabc:detection", function (event) {
  // event.detail = { detected, blockerType, path, browser }
  var result = event.detail;
  if (result.detected) {
    // Your logic here.
  }
});
</script>

<script>
window.AABC_ON_DETECT = function (result) {
  if (result.detected &&
      result.blockerType !== "network_dns") {
    // Your logic here.
  }
};
</script>

var result = window.AABC_DETECTION;
if (result && result.detected) {
  // Your logic here.
}

When it fires

• Once per page, after the first full evaluation: roughly 0.1 to 3.6 seconds in, and never before DOMContentLoaded. Anything you register before DOMContentLoaded is in time; code that loads later should read the snapshot.
• It fires when detected is false too, so a page without a blocker gets an explicit answer, not silence.
• When the visitor comes back to the tab, the script checks again and sends a new result only if detected or blockerType changed. A change to false lets you remove a message you already showed. A re-check never counts as a second detection.
• A client-side route change doesn't produce a new result (see single-page apps).

When no result arrives

Testing

Single-page apps and frameworks

"use client";
import { useEffect, useState } from "react";
import type { AabcResult } from "./aabc-types";

export function useAdblockResult() {
  const [result, setResult] =
    useState<AabcResult | null>(null);
  useEffect(() => {
    const handle = (event: CustomEvent<AabcResult>) =>
      setResult(event.detail);
    window.addEventListener("aabc:detection", handle);
    if (window.AABC_DETECTION) {
      setResult(window.AABC_DETECTION);
    }
    return () =>
      window.removeEventListener("aabc:detection", handle);
  }, []);
  // null until a result arrives; stays null if none does
  return result;
}

"use client";
import { useAdblockResult } from "./use-adblock-result";

// in a client component
export function Download() {
  const result = useAdblockResult();
  if (result && result.detected) {
    return <YourMessage blockerType={result.blockerType} />;
  }
  // the default path, also while there is no result
  return <DownloadLink />;
}

The hook reads the snapshot, so it also catches a result that arrived before your component mounted, and it removes its listener on unmount. The same two steps, listen for the event and read the snapshot, work in Vue, Svelte or plain JavaScript.

Analytics

To see your ad-block rate in your own analytics, forward one result per page. With Google Tag Manager, push it to the data layer and send it with a GA4 event tag on a Custom Event trigger named aabc_detection, reading the fields with three Data Layer Variables:

<script>
(function () {
  function send(result) {
    window.dataLayer = window.dataLayer || [];
    window.dataLayer.push({
      event: "aabc_detection",
      aabc_detected: result.detected,
      aabc_blocker_type: result.blockerType || "none",
      aabc_browser: result.browser
    });
  }
  if (window.AABC_DETECTION) {
    send(window.AABC_DETECTION);
  } else {
    window.addEventListener(
      "aabc:detection",
      function (event) { send(event.detail); },
      { once: true }
    );
  }
})();
</script>

The snippet sends one result per page: the one already in the snapshot, or else the first to arrive, and the listener removes itself. Register aabc_detected, aabc_blocker_type and aabc_browser as event-scoped custom dimensions in GA4 to report on them. Without Tag Manager, send the same fields with gtag("event", "aabc_detection", { ... }). Pages with no result send nothing. Many ad blockers also block Google Tag Manager and GA4, so part of the blocked visits never reach your analytics; your AntiAdBlock Core dashboard still counts every detection.

Quota and plan changes

• A detection counts the same in both modes: one per page view where a blocker is found. Page views without one never count, and a re-check never counts twice.
• The quota belongs to the account and is shared across its sites. We email you at 80%; when it is used up, the script stays silent until the next cycle (see when no result arrives).
• Detections and blocker types keep flowing into your dashboard.
• If a plan change removes the Detection API, the site goes back to Recovery mode on its own, so visitors with a blocker see our notice again. You get an email and a note in your dashboard; your choice is kept and returns when you upgrade.

Contract history

1. October 17, 2026

   Documentation reviewed: more cases with no result (Recovery mode, used-up quota, paused site, tag on another domain, automated browsers), the TypeScript types and the React and analytics examples are added, and path is documented as a reference code with no fixed list of letters. The contract doesn't change.

2. August 2026

   First public version: the aabc:detection event, the AABC_ON_DETECT callback, the AABC_DETECTION snapshot and the four result fields.

Any change to the contract is listed here with its date.

Keep going

• Detection API integration guide

  The step-by-step walkthrough: a full example with a time limit, missing results and troubleshooting.

• Adblock detection API

  What you can build on the result, setup and plans.

• Plans and pricing

  The Detection API comes with Max and Business; every plan and price is public.

• Live demo

  A blocked visit, step by step, and an example site that runs the same engine with the notice.

Built and maintained by the AntiAdBlock Core team.