Detection API reference
Detection API reference
The contract for consuming AntiAdBlock Core as a headless detector. The same multi-signal engine runs, emits one result, and renders nothing. Your code decides the rest.
Enabling it
The Detection API is a per-site setting on the Max and Business plans. Switch a site to it from the Script mode card in your dashboard. No new tag is needed: your existing async script tag starts emitting the result instead of showing the recovery overlay.
The result payload
Every result is a frozen object with exactly four keys. It reaches your code through the aabc:detection event, the AABC_ON_DETECT callback, or the AABC_DETECTION snapshot described below.
| Field | Type | Values |
|---|---|---|
| detected | boolean | true, falseWhether an ad blocker was confirmed on this visit. |
| blockerType | string | null | extension, brave_shields, browser_protection, network_dns, unknown, nullWhat is doing the blocking. null when detected is false. Network and DNS blocking happens outside the browser and usually cannot be turned off in one click. |
| path | string | null | A, B, C, FORCE, nullWhich detection threshold confirmed the result. null when detected is false. FORCE is the manual test trigger below. |
| browser | string | chromium, firefox, edge, brave, webkit, otherThe visitor's browser family, useful for tailoring your own response. |
Example
{ "detected": true, "blockerType": "extension", "path": "A", "browser": "chromium" }Three ways to read the result
Pick whichever fits your setup. The callback is the most robust: a direct call cannot be intercepted by other scripts on the page, while a DOM event can.
aabc:detection
Window event. Add the listener before our script tag so it is ready when the result fires.
window.addEventListener("aabc:detection", function (event) {
var d = event.detail; // { detected, blockerType, path, browser }
if (d.detected) {
// Your logic here.
}
});window.AABC_ON_DETECT
Callback. Define this global and we call it with the same object. Recommended for reliability.
window.AABC_ON_DETECT = function (d) {
// { detected, blockerType, path, browser }
if (d.detected) {
// Your logic here.
}
};window.AABC_DETECTION
Snapshot. The last result is kept on window for listeners that attach late, common in single-page apps.
var d = window.AABC_DETECTION;
if (d && d.detected) {
// Your logic here.
}When it fires
- Once per page load, after the first full evaluation. The probes run between roughly 0.1 and 3.6 seconds, always after DOMContentLoaded.
- It fires even when detected is false, so an un-blocked visit is an explicit answer, not silence.
- Focus re-checks re-emit only when detected or blockerType changes. A flip to false lets you retract a message you already showed.
Silence is not "no ad blocker"
If a site is unverified, a kill switch is on, or the visitor is flagged as a bot, no event is emitted at all. Treat the absence of a result as "no answer" and take your normal, un-gated path by default. In other words, fail open.
Testing it
Add #aabc_force to any URL on your site to force a positive result (detected: true, path: "FORCE") with no overlay. It is a way to exercise your own handler without installing an ad blocker.
Single-page apps
The result fires on page load and on focus re-checks, not on a client-side route change. In a single-page app, read window.AABC_DETECTION after navigation to get the last known result, and register your listener once on the window.