Detect Ads Blocker plugin Documentation

9 min read Last updated Sep 16, 2026 227 views

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

LaraClassifier / JobClass v19.0.0 or later
PHP 8.3+
No external dependencies: the add-on is fully self-contained

Note: This add-on does not require any database tables. All settings are stored in the core settings table.

Installation

Step 1: Upload the Add-on

In the admin panel, go to Admin → Extensions → Add-ons and click the Upload Add-on button. Select the add-on’s ZIP file: the system extracts it automatically and the add-on appears in the installed add-ons list.

Step 2: Activate the Add-on

Find Ad Blocker Detector in the list and click Activate. Its migrations, seeders (if any) and permissions are set up automatically.

Step 3: Configure

Navigate to Admin → Ad Blocker Detector to configure detection behavior and the visitor message. See Configuration.

Purchase Code (License Key)

Ad Blocker Detector is sold as a separate product, so it has its own purchase code (license key) — distinct from the purchase code of the main application and from the one of every other add-on. You are asked for it when you activate Ad Blocker Detector in Admin panel → Add-ons.

Our products are sold on three platforms. The way you receive a purchase code depends on where you bought the product.

Platform / Provider	How you get the purchase code	Where to find it again
bedigit.com Store In-site purchase (Shop)	Generated automatically when the order is paid, then sent by email — either in its own license email, or inside the order confirmation email.	My Account → My Licenses on bedigit.com
Gumroad	Created as soon as Gumroad notifies us of the sale, then sent in a separate email, in addition to the Gumroad receipt.	The license email, your Gumroad Library, and My Account → My Licenses on bedigit.com
Envato Market CodeCanyon	Issued by Envato, not by us, and never sent by email: you download it yourself from your Envato account.	Envato account → Downloads → License certificate & purchase code

Check your spam folder. For both bedigit.com Store and Gumroad purchases, the purchase code is delivered by email. Automated license emails are very often filtered, so if the message is not in your inbox, look in your spam / junk folder before contacting support, and add our sender address to your contacts or allow list.

1. bedigit.com Store (in-site purchase)

As soon as the order’s payment status becomes Paid, a license key is generated automatically for every licensed item in the order (one key per purchased unit — buying 3 units gives 3 distinct keys).
It is emailed to the address used on the order, either in a dedicated license email or inside the order confirmation email. Check your inbox and your spam / junk folder.
The key stays available in your account under My Account → My Licenses. Keys are masked in the list; open the license detail page to reveal and copy the full key, see the domains it is activated on, and deactivate a domain to free an activation slot.
The matching invoice is under My Account → My Orders.

2. Gumroad

A Gumroad purchase produces two separate emails: the Gumroad receipt (sent by Gumroad, giving access to the files) and a license key email (sent by bedigit.com) that contains your purchase code.
The license key email is generated as soon as Gumroad notifies us of the sale, so it normally arrives within seconds of the payment. Here too, check your inbox and your spam / junk folder.
When the Gumroad product uses Gumroad’s own license-key feature, the same key also appears in your Gumroad receipt and under Library → your purchase on gumroad.com.
Use the same email address on bedigit.com as on Gumroad: your keys are then linked to your account automatically and listed under My Account → My Licenses, even if you register after the purchase. You can also add a Gumroad key manually from My Account → My Gumroad Licenses.

3. Envato Market (CodeCanyon)

Envato purchase codes are issued and delivered by Envato Market, never emailed by us — so there is nothing to look for in your spam folder: you retrieve the code from your Envato account.
Log in to your Envato / CodeCanyon account, open the Downloads page, find the item, and choose License certificate & purchase code from the Download dropdown. The code is written in that certificate.
An Envato purchase code looks like 12345678-90ab-cdef-1234-567890abcdef (8-4-4-4-12 characters). It never changes, and renewing item support does not issue a new one.
Official Envato article: Where Is My Purchase Code?

Lost your purchase code? Search your mailbox (spam folder included) for “license” or “purchase code”, then check My Account → My Licenses on bedigit.com for Store and Gumroad purchases, or Downloads → License certificate on Envato. If it is still missing, open a ticket on our Help Center with your order number (Store), Gumroad sale ID or buyer email (Gumroad), or Envato username and item name (Envato).

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_dismiss is 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 element
aria-labelledby="abdTitle" linking to the title
aria-modal="true" for screen readers
aria-hidden="true" on bait elements
Color contrast meets WCAG AA standards

Updating

There are two ways to update this add-on: via the admin panel (recommended) or manually replacing files.

Method 1: Admin Panel Upload (Recommended)

Download the latest .zip file of this add-on.
Go to Admin panel → Add-ons and click the Upload button.
Select or drag the .zip file into the upload area.
A confirmation prompt will show the current and new version numbers. Click Replace to proceed.
Go to Admin panel → System Update (/admin/update) to apply any pending database migrations.

Method 2: Manual File Replacement

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_enabled is set to true in settings.
Make sure you are testing with an ad blocker installed and enabled.
Try reducing the detection_delay to 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 isAdminPanelRoute() 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.