# JetBlocker 2.1 - User Guide

## Requirements
- WordPress 6.5 or later.
- Tested metadata: WordPress 7.0.2.
- PHP 8.0 or later.
- JavaScript enabled in the visitor browser.

## Installation
1. In WordPress Admin, open Plugins > Add New > Upload Plugin.
2. Upload the JetBlocker ZIP.
3. Activate JetBlocker.
4. Open JetBlocker from the WordPress admin menu.
5. Save the desired detection and recovery settings.
6. Clear WordPress/page/CDN caches after changing the plugin version or JavaScript settings.

## Important administrator testing behavior
JetBlocker can exempt users with the `manage_options` capability. When "Do not show to administrators" is enabled, a logged-in administrator will not see the detector during normal browsing even when an ad blocker is active.

Use the **Test detector on homepage** button on the JetBlocker settings screen. The generated URL contains a WordPress nonce and temporarily bypasses the administrator exemption for that administrator only.

You can also test as a logged-out visitor or in a private/incognito window.

## Detection sensitivity
### Standard
Uses local JavaScript canary and multiple cosmetic bait selectors. Lowest chance of false positives, but network-only privacy extensions may not be detected.

### Enhanced - recommended
Uses Standard checks plus a request to a well-known advertising script endpoint. This is intended to detect extensions that block advertising requests at the network layer, including many AdBlock/Ghostery configurations.

### Maximum
Uses Enhanced checks, delayed rescans, and inspection of existing advertising elements. Use when aggressive blockers are missed. It can increase false positives on sites with strict Content Security Policy rules or deliberately hidden ad containers.

## Action modes
- Notice only: non-blocking notification.
- Overlay message: modal-style anti-adblock popup with page lock.
- Recovery ads only: no popup; only first-party recovery creatives are enabled when blocking is detected.

## First-party revenue recovery
JetBlocker cannot guarantee that a third-party network such as AdSense will load when the visitor's blocker prevents that network request. The resilient approach is a first-party sponsor or house creative served by the WordPress site itself.

Wrap an existing ad shortcode:

`[jetblocker_recovery_slot][your_ad_shortcode][/jetblocker_recovery_slot]`

When blocking is detected, JetBlocker hides the primary content and reveals the configured first-party fallback.

Always render the first-party creative:

`[jetblocker_first_party]`

## Testing checklist
1. Confirm JetBlocker is enabled.
2. Set Action to Overlay message.
3. Set Detection sensitivity to Enhanced or Maximum.
4. If logged in as administrator, click Test detector on homepage or temporarily disable the administrator exemption.
5. Clear cache/minification/CDN cache.
6. Open browser developer tools and reload the page.
7. With Debug enabled, look for `[JetBlocker]` console entries.
8. Inspect `window.JetBlockerLastDetection` in the console for the latest signal results.

## Privacy note
Standard detection is local. Enhanced and Maximum detection attempt to request a Google advertising JavaScript URL as a detection canary. JetBlocker does not send its own analytics to a remote JetBlocker service. Local event counters are stored in the site's WordPress database.