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

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:

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