Implementación

11 min de lecturaPor El Equipo de AntiAdBlock Core

API de detección: ejecuta tu propia lógica en cada detección de adblock

Disponible en Max y Business, la Detection API convierte nuestro script en un detector sin interfaz: el mismo motor, sin overlay, y un evento JavaScript que tu código consume para redirigir, limitar o medir como quieras. Esta es la referencia completa de integración, de la etiqueta al payload.

Qué es la Detection API

Cada sitio en AntiAdBlock Core funciona en uno de dos modos de script. Recovery es el modo por defecto: el script detecta el bloqueador y muestra nuestro overlay de recuperación, que guía al visitante para desactivarlo. Detection API es la alternativa sin interfaz: el mismo motor de detección se ejecuta en cada página vista, pero no se pinta nada. En su lugar, el script entrega el resultado a tu propio JavaScript.

Elige la Detection API cuando ya tienes en mente tu propia reacción: redirigir a los visitantes con bloqueador a una página concreta, mostrar tu propio muro o mensaje, alimentar tu analítica con el resultado, o pasárselo a tu backend para que tu servidor decida qué servir. Si lo que quieres es convertir las visitas bloqueadas en ingresos sin trabajo por tu parte, quédate en Recovery; la comparativa recuperación vs detección trata esa decisión a fondo.

El modo se elige por sitio, así que una misma cuenta puede llevar el overlay en un dominio y la API en otro. Está disponible en los planes Max y Business, y las detecciones, las estadísticas y la cuota se comportan exactamente igual en los dos modos.

Paso 1: instala la etiqueta de script

La integración tiene dos partes, y esta es obligatoria: nuestra etiqueta de script es la pieza que ejecuta la detección. Tu código nunca detecta nada por sí mismo; solo consume el resultado. Por eso la etiqueta debe seguir instalada tal cual la genera tu panel, en todas las páginas donde quieras una respuesta.

Encontrarás tu etiqueta en el panel, dentro de la pestaña Resumen de tu sitio, en la card Tu etiqueta de script, con botón de copiado. Tiene esta forma, con tu id real de sitio en los dos huecos:

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

Pégala dentro del <head> de tus páginas, lo más arriba que puedas. Carga con async, así que nunca bloquea tu renderizado ni tus propios scripts. Además está ligada al dominio: solo se ejecuta en el host verificado al que pertenece, de modo que una copia de tu etiqueta pegada en otro dominio no hace nada.

Si tu web envía una Content-Security-Policy, permite el origen https://antiadblockcore.com en script-src y connect-src, e idealmente también en img-src y style-src. El detector carga varios recursos cebo para sondear al bloqueador, y una política que corte esas sondas puede degradar la señal.

Paso 2: activa el modo Detection API en el sitio

Abre tu panel, entra en el sitio y ve a la pestaña Configuración. La primera card es Modo del script, con dos opciones: Recovery y Detection API. Elige Detection API y confirma. Esa es toda la activación: sin cambios de código, sin etiqueta nueva, sin redeploy.

El cambio se aplica a las nuevas cargas de página en cuestión de segundos. Desde ese momento el overlay de recuperación deja de mostrarse en ese sitio y el script empieza a emitir el evento aabc:detection. La misma card muestra un chip de Último evento, que indica cuándo reportó el script por última vez desde tu web; es la vía más rápida de confirmar el cableado de punta a punta.

Si la opción aparece con candado, tu plan actual no incluye la capacidad; se desbloquea en Max y superiores. Y si algún día bajas de plan por debajo de eso, el sitio vuelve automáticamente al overlay de Recovery para no quedarse nunca desprotegido; tu preferencia de modo se guarda y se restaura cuando la capacidad vuelva.

Paso 3: recibe el resultado en tu código

El script te entrega el resultado por tres vías. Las tres llevan el mismo payload, así que puedes usar la que encaje con tu arquitectura, o varias a la vez.

Primera, un CustomEvent llamado aabc:detection, despachado en window (no en document). Es el encaje natural cuando tu código usa eventos estándar:

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

Segunda, un callback plano: si window.AABC_ON_DETECT es una función en el momento de la emisión, el script la llama directamente con el mismo objeto detail. Defínelo antes de nuestra etiqueta para que exista cuando llegue el resultado:

<script>
  window.AABC_ON_DETECT = function (d) {
    if (d.detected) {
      // Tu lógica aquí
    }
  };
</script>

Tercera, un snapshot: window.AABC_DETECTION guarda siempre el último objeto detail. El código que se ejecuta después de que el evento ya se haya emitido, un módulo cargado tarde por ejemplo, puede leerlo sin haber perdido el momento.

El orden importa para las dos primeras: registra tu listener o define tu callback antes de nuestra etiqueta en el HTML. Si no controlas el orden, apóyate en el snapshot como respaldo, igual que hace el patrón de más abajo.

Referencia del payload

Cada emisión lleva un objeto detail congelado con cuatro campos:

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

detected es un booleano, y el false se entrega de forma explícita: cuando el script termina su pasada y no encuentra bloqueador, el evento se emite igualmente con detected a false. Siempre que el script se ejecuta obtienes una respuesta; nunca tienes que deducir el negativo del silencio.

blockerType clasifica qué está bloqueando, y es null cuando detected es false. Valores posibles: extension (un bloqueador instalado como uBlock Origin o AdBlock Plus), brave_shields (el bloqueo integrado del navegador Brave), network_dns (bloqueo que ocurre fuera del navegador, a nivel de DNS o de red: AdGuard DNS, Pi-hole, algunas operadoras), browser_protection (el modo de protección propio de un navegador, como la protección estricta contra rastreadores) y unknown cuando el motor detecta bloqueo pero no puede atribuirlo. El grupo network_dns importa comercialmente: esos visitantes no suelen poder apagar su bloqueo con un clic, así que trátalos distinto en tu flujo si muestras instrucciones.

browser es una familia de navegador a grano grueso, por comodidad: chromium, firefox, edge, brave, webkit u other. Te ahorra parsear el user-agent para ramificaciones simples, y es lo que te permite emparejar blockerType con las instrucciones correctas.

path es un identificador interno de la ruta de detección. No necesitas ramificar sobre él; inclúyelo si registras resultados; agiliza el diagnóstico con soporte.

Tiempos del evento y aplicaciones de página única

El motor se ejecuta una vez por carga completa de página y suele resolver poco después de que la página se asiente. Diseña para una decisión por documento.

En una misma página puede emitir más de una vez: la detección corre en pasadas, y si una pasada posterior cambia el resultado (detected cambia, o blockerType se refina de unknown a algo concreto) el evento vuelve a emitirse con el detail actualizado. El snapshot guarda siempre la última versión. El patrón práctico: actúa con el primer evento, y relee el snapshot más tarde solo si la clasificación te importa.

En aplicaciones de página única el evento no se re-emite en los cambios de ruta del lado cliente; no hay re-chequeo por navegación virtual. Toma el resultado una vez por carga real de página y guárdalo para la sesión, o fuerza una recarga completa donde necesites una respuesta fresca.

Cómo tratar la ausencia de resultado

Hay situaciones en las que el script no emite nada: el bloqueador del visitante impidió cargar nuestro script, el tráfico es un rastreador o una automatización (la detección guarda silencio a propósito con los bots, así que tu SEO nunca se ve afectado), el sitio aún no está verificado, o la cuota mensual se agotó. El silencio significa por tanto "sin respuesta", nunca "sin bloqueador".

Por eso, cualquier flujo que espere el resultado necesita una espera acotada con decisión por defecto. Este es el patrón de referencia; consulta primero el snapshot, así funciona también cuando tu código llega tarde:

<script>
  (function () {
    var decidido = false;
    function decidir(d) {
      if (decidido) return;
      decidido = true;
      // d === null  -> sin respuesta a tiempo: aplica tu ruta por defecto
      // d.detected  -> tu decisión, con d.blockerType / d.browser
    }
    if (window.AABC_DETECTION) return decidir(window.AABC_DETECTION);
    window.addEventListener("aabc:detection", function (e) { decidir(e.detail); });
    setTimeout(function () { decidir(null); }, 3000);
  })();
</script>

Elige el timeout que encaje con tu flujo; unos tres segundos cubren conexiones lentas. Con este patrón, una página vista que no obtiene respuesta aplica simplemente tu ruta por defecto, y tu página nunca espera más allá del límite que tú fijes.

Ejemplo completo de integración

El siguiente head mínimo redirige a los visitantes bloqueados a una página de aviso. El handler se define primero, después nuestra etiqueta; el id del sitio sale de tu panel:

<head>
  <!-- 1. Tu handler, definido ANTES de nuestra etiqueta -->
  <script>
    window.AABC_ON_DETECT = function (d) {
      if (d.detected) {
        window.location.replace("/aviso-adblock");
      }
    };
  </script>

  <!-- 2. La etiqueta de AntiAdBlock Core, tal cual la genera tu panel -->
  <script async
    src="https://antiadblockcore.com/s/YOUR_SITE_ID.js"
    data-aabc-site="YOUR_SITE_ID"
    crossorigin="anonymous"></script>
</head>

Cambia la redirección por lo que necesite tu producto: activa un flag que lea tu aplicación, muestra tu propio modal, o envía el resultado a tu backend con fetch y deja que el servidor decida en la siguiente petición. El contrato es siempre el mismo: nuestra etiqueta detecta, tu código reacciona.

Consideraciones de seguridad

Un CustomEvent viaja por la página como cualquier otro evento, lo que significa que otros scripts de tu página, incluidos los scriptlets de los bloqueadores, pueden en teoría interceptarlo, pararlo o incluso despachar uno falso. Para un uso casual el riesgo es pequeño, pero si tu flujo toma una decisión que te importa, prefiere window.AABC_ON_DETECT: nuestro script invoca tu función directamente, sin nada en medio que pueda tragarse o falsificar la llamada.

En cualquier caso, trata la señal del lado cliente como una comodidad, no como una frontera de seguridad. Todo lo que ejecuta un navegador puede manipularlo quien tiene el navegador delante. La imposición que debe aguantar de verdad, una puerta de contenido de pago por ejemplo, va en tu servidor; y los números canónicos de detección son los de tu panel, calculados con ingesta del lado servidor, no lo que afirme un cliente individual.

Efecto en estadísticas, cuota y ajustes del sitio

La facturación no cambia: tu cuota cuenta detecciones de adblock, una por página vista identificada como bloqueada, y las páginas vistas sin bloqueador nunca consumen nada. Un sitio en modo Detection API consume exactamente lo mismo que consumiría en Recovery.

Tu panel sigue funcionando igual. Las detecciones, el desglose por tipo de bloqueador y la gráfica de actividad diaria se rellenan como siempre. El KPI de recuperación sigue informando, con un cambio de significado: como nuestro overlay ya no se muestra, las recuperaciones miden ahora el resultado de tu propio flujo, los visitantes que volvieron con el bloqueador apagado tras lo que tú les mostraras.

La personalización del overlay y el ajuste de visitantes con bloqueo de red se guardan pero quedan inertes mientras el sitio esté en este modo, porque no hay overlay al que aplicarlos. Devuelve el sitio a Recovery y se aplican de nuevo tal cual estaban guardados.

Pruebas y resolución de problemas

Para verificar la integración: instala un bloqueador como uBlock Origin en tu propio navegador, abre tu web y escribe window.AABC_DETECTION en la consola de DevTools. Deberías ver el objeto detail con detected a true. Después desactiva el bloqueador, recarga y comprueba que recibes detected a false. El chip de Último evento en la card Modo del script confirma que el servidor vio reportar a tu script.

Si no llega ningún evento, comprueba lo siguiente en orden: el sitio está verificado y activo en tu panel; la etiqueta está presente en el HTML servido (mira el código fuente, no te fíes de la plantilla del framework); el sitio está guardado en modo Detection API; tu plan incluye la capacidad; tu listener o callback está registrado antes de nuestra etiqueta, o estás leyendo el snapshot; no estás probando con automatización headless, que se ignora a propósito; y tu Content-Security-Policy, si la tienes, permite nuestro origen. Si recibes eventos pero la detección te parece rara en un montaje concreto, apunta el campo path y lee cómo funciona la detección por dentro antes de escribirnos, e incluye ambas cosas en el ticket.

Preguntas frecuentes

¿Se emite el evento cuando no se encuentra bloqueador?

Sí. Cuando el motor termina y no encuentra nada, el evento se emite igualmente con detected a false y blockerType a null. Siempre que el script se ejecuta obtienes una respuesta explícita; el silencio solo ocurre cuando el script no pudo ejecutarse o guardó silencio a propósito, y por eso tu código debe tratar el silencio como "sin respuesta".

¿Las detecciones en este modo cuentan para mi cuota?

Sí, idéntico a Recovery: una detección por página vista identificada con bloqueador. Las páginas vistas sin bloqueador no cuentan en ningún modo.

¿Puedo llevar el overlay en un sitio y la Detection API en otro?

Sí. El modo es un ajuste por sitio, así que cada sitio de tu cuenta elige de forma independiente en su pestaña de Configuración.

¿Qué pasa si bajo de plan por debajo de Max?

El sitio vuelve automáticamente al modo Recovery y el overlay se muestra de nuevo, para que nunca quede desprotegido. Tu preferencia de Detection API se guarda y se restaura si la capacidad vuelve.

¿Funciona en aplicaciones de página única?

Una vez por carga completa de página. El evento no se re-emite en los cambios de ruta del lado cliente, así que toma el resultado cuando cargue el documento y guárdalo, o fuerza una recarga real donde necesites un chequeo fresco.

¿Puedo apoyarme en el evento para proteger contenido de pago?

No. Es una señal del lado cliente y todo lo del lado cliente puede manipularlo el visitante. Úsalo para decisiones de experiencia y medición, prefiere AABC_ON_DETECT por robustez, y deja la imposición real en tu servidor.