Ad Blocker Detector
Detect ad blocker browser extensions and display a full-page modal overlay prompting visitors to disable them before continuing to browse your site.
Dual Detection
Uses both DOM-based cosmetic filter detection and network-level request blocking detection for high accuracy.
Configurable Behavior
Control detection delay, whether users can dismiss the overlay, and customize the displayed text per language.
Auto-Injection
Global middleware automatically injects the detector into all front-end pages: no template changes needed.
Theme Override
Themes can provide their own detector overlay design by overriding the default view.
Use Cases
Ad-Supported Content Site
Your site relies on advertising revenue. When a visitor has an ad blocker enabled, the overlay appears and prompts them to disable it. You can block all access until they comply or allow them to dismiss the overlay and continue.
Freemium Model with Ads
Free users see ads, premium users do not. Use the detector to enforce the ad-viewing experience for free-tier visitors, while premium users are not affected (integrate with role/permission checks).
Publisher Compliance
Ad networks require a minimum number of ad impressions. The detector helps ensure your ad slots are actually rendered and visible to visitors.
Requirements
- Larapen CMS v1.0.0 or later
- PHP 8.3+
- No external dependencies: the add-on is fully self-contained
settings table.
Installation
Step 1: Place the Add-on
Copy or symlink the adsblockerdetector folder into your Larapen "extensions/addons" directory:
Step 2: Activate the Add-on
Go to Admin → Add-ons → Installed Add-ons and activate Ad Blocker Detector.
Step 3: Set Permissions
The add-on registers 2 permissions (see Permissions). Assign them to admin roles via Admin → Users → Roles & Permissions.
Step 4: Configure
Navigate to Admin → Ad Blocker Detector to configure behavior. See Configuration.
Configuration
All settings are managed in Admin → Ad Blocker Detector (stored in the
settings table, group adsblockerdetector).
| Setting | Description | Default |
|---|---|---|
adsblockerdetector_enabled |
Enable or disable ad blocker detection globally | true |
adsblockerdetector_detection_delay |
Delay in milliseconds before checking for ad blockers (100–5000) | 300 |
adsblockerdetector_allow_dismiss |
Whether users can close the overlay without disabling their ad blocker | false |
adsblockerdetector_title |
Custom overlay title per locale (JSON). Leave empty to use default translation. | empty |
adsblockerdetector_message |
Custom overlay message per locale (JSON). Leave empty to use default translation. | empty |
Default values come from the config file at config/adsblockerdetector.php. Database settings
override config defaults.
Admin: Settings
The settings page is accessible at Admin → Ad Blocker Detector
(route: admin.adsblockerdetector.settings.index).
General Settings
- Enable Ad Blocker Detection: Toggle the detector on or off globally.
- Detection Delay (ms): How long to wait before running detection (100–5000ms). Higher values reduce false positives but delay the overlay appearance.
- Allow Dismiss: When enabled, a “Continue anyway” button appears on the overlay, letting users bypass without disabling their ad blocker.
Custom Text
You can set a custom title and message for the overlay, per language. A language selector lets you enter text for each active language. Leave fields empty to use the default translations from the add-on’s language files.
Routes
| Method | URL | Name | Permission |
|---|---|---|---|
| GET | /admin/adsblockerdetector/settings |
admin.adsblockerdetector.settings.index |
adsblockerdetector.settings.view |
| PUT | /admin/adsblockerdetector/settings |
admin.adsblockerdetector.settings.update |
adsblockerdetector.settings.edit |
Overlay UI
When an ad blocker is detected, a full-page modal overlay appears with:
- A semi-transparent dark backdrop covering the entire viewport (z-index 99999).
- A centered white dialog box with a shield icon.
- A configurable title (default: “Ad Blocker Detected”).
- A configurable message explaining why ad blockers should be disabled.
- Step-by-step instructions for disabling the ad blocker.
- A primary “I’ve Disabled It” button that rechecks detection.
- An optional “Continue anyway” dismiss button (if
allow_dismissis enabled).
The overlay locks page scrolling by adding a .abd-locked class to <body>.
All styling is inline (no external CSS requests) and the overlay is fully responsive.
Accessibility
role="dialog"on the overlay elementaria-labelledby="abdTitle"linking to the titlearia-modal="true"for screen readersaria-hidden="true"on bait elements- Color contrast meets WCAG AA standards
Updating
Step 1: Replace Files
Replace the adsblockerdetector folder with the new version (or pull the latest if using a symlink).
Step 2: Clear Caches
Step 3: Verify
Visit a front-end page (not admin) and confirm the detector is working as expected. Check Admin → Ad Blocker Detector to verify settings are intact.
Troubleshooting
Overlay never appears
- Verify the add-on is activated in Admin → Add-ons.
- Check that
adsblockerdetector_enabledis set to true in settings. - Make sure you are testing with an ad blocker installed and enabled.
- Try reducing the
detection_delayto 100ms for testing. - Check the browser console for JavaScript errors.
False positives (overlay appears without ad blocker)
- Increase the
detection_delay(try 1000ms or higher). - Check if your Content Security Policy (CSP) is blocking the fetch request to
/ads/ad-banner.js. - Network-level blocking by corporate firewalls or DNS-level filters can trigger false positives.
Overlay appears on admin pages
- This should not happen. The middleware excludes admin routes. If it does, check that
is_admin_panel_route()is correctly defined in the core helpers.
“I’ve Disabled It” button does not work
- The ad blocker may still be active. The detector creates fresh bait elements on recheck.
- Some ad blockers require a full page reload after disabling. The detector will reload the page once the recheck passes.