=== Tiny Simple AdBlock Detector === Contributors: MythThrazz Donate link: https://marcindudek.dev/ Tags: adblock, ad blocker, detect, ads, content Requires at least: 5.0 Tested up to: 7.0 Requires PHP: 7.4 Stable tag: 1.2.0 License: GPLv2 or later License URI: http://www.gnu.org/licenses/gpl-2.0.html Detect ad blockers in 2 KB. Show or hide any content depending on whether your visitor uses an ad blocker — zero config, no external requests, no performance hit. == Description == Over 40% of internet users run an ad blocker. **Tiny Simple AdBlock Detector** gives you the power to respond — politely ask visitors to whitelist your site, gate premium content, or simply track awareness — all without touching a line of JavaScript yourself. ### How it works The plugin loads a tiny decoy script with a filename that ad blockers love to block. When the script gets blocked, a lightweight CSS class swap kicks in — revealing or hiding any element you've marked up. That's it. No jQuery, no external services, no tracking pixels, no cookie banners. ### Two CSS classes. Infinite possibilities. * `class="show-only-when-adblock"` — Element appears **only** when an ad blocker is active. * `class="hide-only-when-adblock"` — Element disappears when an ad blocker is active. Add them to any HTML element: a `
`, a Gutenberg block, an Elementor section, a WooCommerce notice — anything. ### Real-world examples * **"Please whitelist us"** — Show a polite banner only to ad-blocking visitors * **Content gating** — Hide exclusive articles or downloads from users blocking your ads * **Alternative monetization** — Show a "Support us on Patreon" box only when ads are blocked * **Analytics** — Pair with your analytics tool to track ad-blocker adoption rates on your site ### Why this plugin? * **Zero configuration** — Activate it and it works. No settings page, no wizard, no API key. * **Ridiculously lightweight** — Under 2 KB of JavaScript. Your visitors won't notice. * **No external requests** — Nothing leaves your server. Fully GDPR-friendly. * **Works with all major ad blockers** — uBlock Origin, AdBlock Plus, AdBlock, AdGuard, Brave Shield, Opera built-in blocker. * **Page builder compatible** — Works with Gutenberg, Elementor, Divi, WPBakery, Beaver Builder — anything that lets you add a CSS class. * **Built-in debug mode** — Append `?tsad_debug=1` to any URL to see live detection results. * **Translation-ready** — Includes Polish translation. PRs welcome for others. ### From the maker of WP Multi Tool This plugin is built by the same developer behind [WP Multi Tool](https://wpmultitool.com/) — the Swiss Army knife for WordPress developers and site administrators. If you manage multiple WordPress sites, check it out. == Installation == 1. Install through the WordPress plugin directory, or upload to `/wp-content/plugins/`. 2. Activate the plugin. That's it — it's already running. 3. Add `class="show-only-when-adblock"` or `class="hide-only-when-adblock"` to any HTML element. 4. (Optional) Visit the plugin's admin page for a quick reference and debug link. == Frequently Asked Questions == = Which ad blockers does it detect? = Tested and confirmed with: uBlock Origin, AdBlock Plus, AdBlock, AdGuard, Brave Shield, and Opera's built-in blocker. It works by exploiting how ad blockers filter script filenames — so it catches most blockers that follow standard filter lists. = Does it slow down my site? = No. The total JavaScript payload is under 2 KB (two tiny files), loaded asynchronously. It makes zero external HTTP requests. Your PageSpeed score won't budge. = Is it GDPR compliant? = Yes. The plugin doesn't collect, store, or transmit any user data. It doesn't set cookies, fingerprint browsers, or phone home. It's pure client-side CSS class toggling. = How do I test if it's working? = Append `?tsad_debug=1` to any page on your site. A debug panel will appear at the bottom showing detection status in real-time. You can also find this link on the plugin's admin page. = Can I use it with Elementor / Gutenberg / page builders? = Absolutely. Just add the CSS class in your page builder's "Advanced" → "CSS Classes" field. Works with Gutenberg, Elementor, Divi, WPBakery, Beaver Builder, and any builder that supports custom CSS classes. = What if someone uses a blocker you don't detect? = The detection relies on ad blockers blocking scripts with "ad-like" filenames (like `showads.js`). Very aggressive blockers or custom filter lists will definitely get caught. Very minimal or niche blockers might slip through — but those cover a tiny fraction of users. = Can I style the elements differently instead of show/hide? = The plugin uses `display: none` and `display: initial` by default. You can override this in your own CSS by targeting `.show-only-when-adblock` and `.hide-only-when-adblock` with higher specificity. == Screenshots == 1. Zero-config admin page — plugin works immediately after activation 2. Built-in debug mode showing real-time ad blocker detection on the frontend == Changelog == = 1.2.0 = * Tested and verified with WordPress 7.0 * Fixed hardcoded localhost URL in admin page — now uses dynamic site URL * Added proper version strings to enqueued scripts for cache busting * Updated plugin headers (Requires PHP, Requires at least) * Completely rewritten readme with real-world usage examples * Added plugin icon and banner * Added screenshots * Code cleanup: removed broken .min.js references = 1.1.0 = * Tested the functionality with the latest version of WordPress * Improved the UI * Added more complex testing = 1.0.1 = * Fixed the bug with the styling for class="hide-only-when-adblock" = 1.0.0 = * Initial release == Upgrade Notice == = 1.2.0 = Verified for WordPress 7.0. Fixed admin page URL bug, added cache busting, improved documentation.