=== ClickGuardian — Click Fraud Protection ===
Contributors: clickguardian
Tags: click fraud, ppc, google ads, security, analytics
Requires at least: 6.3
Tested up to: 7.0
Requires PHP: 7.4
Stable tag: 1.0.0
License: GPLv2 or later
License URI: https://www.gnu.org/licenses/gpl-2.0.html

Detect and block click fraud on your Google Ads, Meta, and Microsoft Ads campaigns. Paste your Project ID and start protecting ad spend in minutes.

== Description ==

ClickGuardian analyses visitor behaviour, device signals and form interactions to identify fraudulent clicks, bots, and fake leads hitting your paid campaigns.

This plugin injects the ClickGuardian tracking script into your site and gives you a clean WordPress admin UI to configure it — no theme editing, no header code pasting.

**Features**

* One-field setup — paste your `proj_XXX` Project ID and go.
* Master on/off switch for tracking.
* Lead / form signal detection with built-in integrations for Gravity Forms, WPForms, and Contact Form 7.
* Exclude logged-in admins and any other user roles from tracking.
* Exclude specific URL paths (with wildcards).
* Test Connection button verifies your Project ID is accepted by the ingest API.
* Regional ingest (EU / US / Global) for latency-sensitive sites.
* Cookieless by design — no consent banner required for fraud prevention (GDPR Art 6(1)(f)).

**Requires a ClickGuardian account.** You can sign up and create a project at https://app.clickguardian.ai.

== External services ==

This plugin relies on two ClickGuardian services:

1. **Tracker script delivery** — `https://cdn.clickguardian.ai/v1/track.js`
   The tracker JavaScript is fetched from our CDN and runs in visitors' browsers. It collects behavioural signals (mouse, keyboard, form interaction) and anonymous technical fingerprints to identify fraudulent clicks. Storage: `sessionStorage` only, no cookies.

2. **Event ingest** — `https://ingest.clickguardian.ai/v1/ingest`
   The tracker POSTs compact JSON payloads containing the signals above, a pseudonymous session ID, timestamp, page URL, and your Project ID.

Data is processed under GDPR Article 6(1)(f) legitimate interest (fraud prevention).

* Terms: https://clickguardian.ai/legal/terms
* Privacy: https://clickguardian.ai/legal/privacy

The plugin does not send any data to these services except when a site visitor loads a page, and during the Test Connection action in the plugin settings (which sends one synthetic pageview to validate the Project ID).

== Source code and build tools ==

This plugin is open source (GPLv2+). The bundled file `admin/build/index.js` is generated from React sources shipped alongside it under `admin/app/`.

* Source: the human-readable React source for the admin UI is included in the plugin zip at `admin/app/` (entry point `admin/app/index.jsx`).
* Build tool: [@wordpress/scripts](https://www.npmjs.com/package/@wordpress/scripts) (webpack-based, GPL-compatible).
* Build command from the plugin directory: `npm install && npx wp-scripts build --webpack-src-dir=admin/app --output-path=admin/build`.

The bundle in `admin/build/index.js` contains no third-party libraries — it depends only on WordPress-provided script handles (`wp-element`, `wp-components`, `wp-i18n`), which WordPress core loads separately.

== Installation ==

1. Upload the plugin files to `/wp-content/plugins/clickguardian/`, or install directly from the WordPress Plugin Directory.
2. Activate "ClickGuardian" through the Plugins menu.
3. Go to **ClickGuardian** in the admin sidebar.
4. Paste your Project ID (format `proj_abc123xyz789`) from https://app.clickguardian.ai.
5. Click **Test connection** to confirm the ID is recognised.
6. Toggle individual features on/off as needed.

== Frequently Asked Questions ==

= Do I need a ClickGuardian account? =
Yes. The plugin is the delivery mechanism; the fraud detection service runs in our backend. Sign up at https://clickguardian.ai.

= Does this plugin set cookies? =
No. The tracker uses `sessionStorage` only. Sessions are pseudonymous.

= Is this GDPR-compliant? =
Fraud prevention is recognised as legitimate interest under GDPR Article 6(1)(f). We do not require consent banners for the tracker. Always consult your DPO for your specific compliance situation.

= Will this slow down my site? =
The tracker is loaded asynchronously (`async`), is under 15 KB gzipped, and runs off the critical rendering path.

= Can I exclude my own traffic? =
Yes — the "Don't track logged-in administrators" toggle is on by default, and you can exclude any other WordPress user roles.

= Does it work with page caching / Cloudflare? =
Yes. The tracker is a standard `<script>` tag in the page head; caching layers don't affect it.

== Screenshots ==

1. The Setup tab — paste your Project ID and test the connection.
2. Tracking options — master switch, lead detection, signal categories.
3. Exclusions — keep admins, roles, and specific paths out of tracking.
4. Forms — deep integration toggles for supported form plugins.

== Changelog ==

= 1.0.0 =
* Initial release.

== Upgrade Notice ==

= 1.0.0 =
Initial release.
