Documentación de la API de detección de adblock

Cómo se activa

La API de detección es un ajuste de cada sitio. Antes de escribir código:

Plan

Max o Business. En Free y Pro la opción aparece bloqueada.

Dónde

en tu panel, entra en el sitio, abre Configuración y, en Modo del script, elige Detection API. Cada sitio empieza en Recuperación, el modo con aviso, también en Max y Business. El ajuste Modo del script se desbloquea cuando el dominio está verificado.

Etiqueta

no cambia. La que ya tienes en el <head> deja de mostrar el aviso y entrega el resultado; el cambio llega en menos de un minuto a las páginas que se abran después.

Aviso

en este modo no se muestra, y su código ni siquiera viaja con el script.

Restablecer

si restableces la personalización del aviso a sus valores por defecto, el sitio vuelve también al modo con aviso y el evento deja de emitirse.

Bajada de plan

si tu plan deja de incluir la API, el sitio vuelve solo al aviso, con una notificación en el panel y un correo. Tu elección se guarda y vuelve si mejoras el plan.

Varios sitios

cada uno elige su modo. Uno puede usar la API y otro seguir con el aviso, con la misma cuenta y la misma cuota.

Requisitos La etiqueta de AntiAdBlock Core en el <head> de un sitio en modo Detection API (plan Max o Business).

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

Con la entrega first-party, la tuya carga desde tu subdominio: cópiala siempre de tu panel.

El resultado (payload)

Cada resultado es un objeto congelado con exactamente cuatro claves. Es el mismo objeto en el evento, en el callback y en la instantánea. No lo modifiques: si necesitas añadir datos, haz una copia.

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

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

En el primer ejemplo, path va elidido: lleva una letra de referencia interna.

• network_dns: el bloqueo ocurre fuera del navegador (Pi-hole, AdGuard DNS, NextDNS) y no se quita con un clic. Pedirle al visitante que lo desactive solo le frustra: dale otro mensaje.
• En Firefox y Edge, un bloqueo solo de red llega como browser_protection. Es la misma clasificación que ves en tu panel.

export type AabcResult = Readonly<{
  detected: boolean;
  blockerType:
    | "extension"
    | "brave_shields"
    | "browser_protection"
    | "network_dns"
    | "unknown"
    | null;
  // una letra de referencia interna, o "FORCE" en la prueba
  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>;
  }
}

Tres formas de leer el resultado

Elige la que encaje con tu montaje, o combínalas. Para el evento y el callback, coloca tu código antes de nuestra etiqueta; si no controlas el orden, lee la instantánea.

<script>
window.addEventListener("aabc:detection", function (event) {
  // d = { detected, blockerType, path, browser }
  var d = event.detail;
  if (d.detected) {
    // tu lógica
  }
});
</script>

<script>
window.AABC_ON_DETECT = function (d) {
  if (d.detected && d.blockerType !== "network_dns") {
    // tu lógica
  }
};
</script>

var d = window.AABC_DETECTION;
if (d && d.detected) {
  // tu lógica
}

El resultado vive en el navegador del visitante: úsalo para decidir la experiencia de tu web. Lo que tenga que aguantar sí o sí, como un contenido de pago, decídelo en tu servidor.

Cuándo se emite

• Una vez por página abierta, tras la primera evaluación completa: por lo general entre unos 0,1 y 3,6 segundos, y siempre después de DOMContentLoaded.
• También cuando no hay bloqueo: detected: false es una respuesta explícita, no silencio.
• Cuando la ventana vuelve a estar activa (por ejemplo, al volver a la pestaña), el script comprueba otra vez y solo emite si cambian detected o blockerType. Un cambio a false te deja retirar un mensaje que ya mostraste.
• En los cambios de ruta de una aplicación de una sola página no se emite: mira SPA y React.

Sin respuesta no significa sin bloqueador

<script>
(function () {
  var hecho = false, espera;
  function decide(d) {
    if (hecho) return;
    hecho = true;
    clearTimeout(espera);
    if (d && d.detected) {
      // tu respuesta al bloqueo
    } else {
      // sin respuesta (d === null) o sin bloqueo:
      // tu camino normal
    }
  }
  if (window.AABC_DETECTION) {
    return decide(window.AABC_DETECTION);
  }
  window.addEventListener("aabc:detection", function (e) {
    decide(e.detail);
  }, { once: true });
  espera = setTimeout(function () { decide(null); }, 4000);
})();
</script>

Ajusta la espera a tu flujo: cuando el script responde, el resultado suele llegar en menos de 4 segundos.

Cómo probar la integración

Fuerza un positivo

añade #aabc_force a cualquier URL de tu sitio y recarga la página (cambiar solo el hash no vuelve a cargar el script). En el modo API, el script devuelve detected: true y path: "FORCE" sin mostrar nada. Si tu navegador no bloquea nada, esa página vista no cuenta como detección.

Mira el resultado

escribe window.AABC_DETECTION en la consola de tu navegador.

Confirma que llega

en Modo del script, tu panel muestra el último evento recibido de tu web.

Si no llega nada, ni con #aabc_force

repasa Sin respuesta (sitio activo, modo guardado, tu dominio, cuota).

Pruebas automáticas

un navegador headless no recibe resultado. En tus tests, llama a tu propio manejador con un objeto del contrato.

Con un bloqueador de verdad

la demo en vivo abre una web de ejemplo con el script completo, en el modo con aviso.

Aplicaciones de una sola página (SPA) y React

El resultado se emite al abrir la página y, si cambia el veredicto, cuando la ventana vuelve a estar activa; no en un cambio de ruta del lado del cliente. La etiqueta va una sola vez en el <head> del documento; en Next.js, en el layout raíz (dónde va la etiqueta en tu plataforma). En React, Next.js, Vue o Angular, lee window.AABC_DETECTION al montar y escucha el evento en window, quitando el listener al desmontar.

"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 hasta que llega un resultado, y null si no llega
  return result;
}

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

// en un componente de cliente
export function Download() {
  const result = useAdblockResult();
  if (result && result.detected) {
    return <YourMessage blockerType={result.blockerType} />;
  }
  // camino por defecto, también mientras no hay resultado
  return <DownloadLink />;
}

Mientras devuelva null, sigue tu camino normal. En el App Router de Next.js, el hook va en un módulo con "use client", como en el ejemplo.

Enviar el resultado a tu analítica

El resultado es un objeto normal de JavaScript: mándalo a Google Analytics 4 o a tu herramienta como un evento. Con Google Tag Manager, empújalo al dataLayer, dispara con él una etiqueta de evento de GA4 (activador de evento personalizado aabc_detection) y crea en GA4 las dimensiones personalizadas de esos parámetros para verlos en los informes:

<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>

• Con gtag.js en lugar de Tag Manager: gtag("event", "aabc_detection", { … }) con los mismos parámetros.
• El fragmento manda un resultado por página: el que ya está en la instantánea o, si no, el primero que llega, y el listener se quita solo.
• Muchos bloqueadores también frenan la analítica, así que una parte de las visitas con bloqueador no le llegará. Tu panel cuenta las detecciones igual.

Cuota, panel y plan

Cuota

una detección es una página vista en la que se detecta un bloqueador y cuenta igual en los dos modos; las páginas vistas sin bloqueador no cuentan. Es de la cuenta, sumada entre sitios, y te avisamos por correo al llegar al 80 %.

Cuota agotada

el script deja de responder hasta tu siguiente periodo (ver Sin respuesta).

Panel

las detecciones y el tipo de bloqueo siguen llegando a tu panel, igual que con el aviso.

Plan

Max (12,99 USD al mes, 1,5 millones de detecciones, 3 sitios) o Business (29,99 USD al mes, 5 millones de detecciones, 5 sitios).

Historial del contrato

Si cambia algo del contrato (nombres, campos, valores o cuándo se emite), lo anotamos aquí con su fecha.

1. 17 de octubre de 2026

   documentación revisada. Se añaden más casos sin respuesta (modo Recuperación, cuota agotada, sitio en pausa, etiqueta en otro dominio), los tipos para TypeScript y los ejemplos de React y de analítica, y path se documenta como un código de referencia sin lista cerrada de letras. El contrato no cambia.

2. agosto de 2026

   primera versión pública. Evento aabc:detection, callback window.AABC_ON_DETECT, instantánea window.AABC_DETECTION y un resultado de cuatro campos (detected, blockerType, path, browser).

Siguientes pasos

• API de detección de adblock

  Qué es, para qué sirve y qué plan necesitas.

• Guía de integración paso a paso

  Un ejemplo completo y la resolución de problemas.

• Precios en USD

  La API está en Max y Business; todos los planes son públicos.

• Demo en vivo

  El script completo en una web de ejemplo.

Plan Free: 5.000 detecciones al mes, sin método de pago

La construye y la mantiene el equipo de AntiAdBlock Core.