Documentation

System - Ad Block Reactor Documentation

System - Ad Block Reactor Documentation

Installation

  1. Download the latest package from the System - Ad Block Reactor extension page.
  2. In Joomla Administrator → Extensions → Manage → Install → Upload Package File.
  3. Enable the plugin: Extensions → Plugins → Search "Ad Block Reactor" → Enable System - Ad Block Reactor.

One unified system plugin handles detection, reporting, content reactions, and AJAX communication—no additional plugins required.

How It Works

On the frontend, the plugin loads a lightweight, deferred detector script that employs multiple evasion-resistant techniques:

  • Randomized DOM bait classes (changes every page load)
  • Self-hosted transparent GIF probe
  • Web worker-based network bait fetching real ad scripts, with PerformanceObserver analysis to defeat stubs and fake responses using the browser's own network metrics.

Detection completes quickly and dispatches:

  • SystemAdBlockReactorDetected when blocking is active
  • SystemAdBlockReactorCleared when no blocker is detected

If Report/ACL is enabled, status changes trigger an AJAX call to store the result in session userstate and optionally apply ACL changes (with optional page reload).

Plugin Parameters

General

  • Ignore Groups Members of selected user groups bypass all detection and reactions (useful for administrators or testers).

Detection Settings

  • Timeout Base delay (in milliseconds) before considering bait checks complete. Default: 1000ms.
  • Use Random Bait Generates a unique bait class name on each page load to evade static cosmetic filters.
  • Use Network Bait Enables the most reliable layer: worker-based fetch of real ad scripts with metrics analysis.
  • Use Mutation Observer Monitors DOM bait for removal, hiding, or style changes that indicate blocker activity.
  • Reload Page on Change Automatically reloads the page after a status change is reported (ensures content reactions and ACL changes apply immediately).

Reporting & ACL

  • Report/ACL Enables server-side reporting via AJAX. On status change, updates session state and dynamically adjusts user viewing access levels.
  • Blocked Ads ACL Viewing Access Level added to the user when an ad blocker is detected.
  • Clear ACL Viewing Access Level added when no ad blocker is detected (and Blocked Ads ACL removed).

Content Reactions (com_content articles only – requires Report/ACL enabled and blocker detected)

  • Reaction Method
    • Do Nothing (default)
    • Truncate Article
    • Redirect
    • View Counter
  • Truncate At
    • Readmore – Uses the article’s introtext only
    • After HTML Tag – Custom breakpoint
  • HTML Tag & HTML Tag Occurrence Tag (e.g., <p>) and which occurrence (e.g., 3rd) to truncate after.
  • Append Text Optional HTML/message appended after truncation.
  • Redirect To Menu item to redirect to.
  • Redirect Message & Redirect Message Type System message displayed before redirect (Message, Notice, Warning, or Error).
  • Maximum Views (View Counter mode) Number of allowed article views before automatic redirect. Counter data is exposed to JavaScript for custom UI.

JavaScript

  • Javascript Actions Custom JavaScript commands executed when a blocker is detected (run individually in order).
  • Change Actions Custom JavaScript executed whenever the blocker status changes. Current status available via window.adblockreactor.vars.lastReport (true = blocked, false = cleared).
  • Custom Javascript (legacy field, still supported) Additional code executed on detection; status via window.adblockreactor.vars.isblocked.

Powerful ACL Usage Examples

  1. Create two Viewing Access Levels (Users → Viewing Access Levels):
    • “Ad Blocker Detected”
    • “Ad Blocker Cleared / Compliant”
  2. Assign the respective levels in Blocked Ads ACL and Clear ACL.
  3. Use these levels to control visibility of modules, menu items, articles, etc.

Common setups:

  • Module with self-hosted fallback/house ads → visible only to Blocked Ads ACL
  • “Thank you for supporting us!” module + subscription offer → visible only to Clear ACL
  • Premium content or discounts → hide from Blocked Ads ACL, show to Clear ACL

JavaScript Event Hooks

JavaScript
window.addEventListener('SystemAdBlockReactorDetected', () => {
    console.log('Ad blocker detected');
    // Show modal, fire GA4 event, etc.
});

window.addEventListener('SystemAdBlockReactorCleared', () => {
    console.log('No ad blocker / whitelisted');
    // Thank-you message, upsell, etc.
});

For View Counter mode:

JavaScript
const counter = Joomla.getOptions('plg_system_adblockreactor_counter') || {};
console.log(`Views used: ${counter.count} of ${counter.max}`);

Troubleshooting

  • Detection not firing? Open browser console → check for errors loading /media/plg_system_adblockreactor/js/abr.js or worker.
  • False positives? Temporarily disable Use Network Bait to isolate.
  • Caching issues? Detection is client-side; reactions apply after reload triggered by status change.
  • Guests vs logged-in: Both fully supported.

Changelog Highlights (2025 Modern Release)

  • Fully Joomla 4/5/6 native
  • Single unified plugin
  • Advanced worker + PerformanceObserver network detection
  • Per-load random bait classes
  • Streamlined, clearly labeled parameters
  • Enhanced ACL flexibility with Clear ACL support