=== ClickShield – Click Fraud Protection for Google Ads ===
Contributors: tareqhamdey
Tags: click fraud, google ads, bot detection, invalid traffic, ppc
Requires at least: 5.8
Tested up to: 7.1
Requires PHP: 7.4
Stable tag: 1.0.0
License: GPLv2 or later
License URI: https://www.gnu.org/licenses/gpl-2.0.html

See which Google Ads clicks are fake. An explainable Fraud Score (0–100) for every visit, with clear reasons, without slowing your site.

== Description ==

ClickShield analyses every visit to your WordPress site and flags fake clicks, bots and suspicious traffic that waste your Google Ads budget.

Instead of a black box, every visit gets a **Fraud Score from 0 to 100** and a list of plain-language reasons:

> Fraud Score: 87
> – 6 Google Ads clicks from this IP in the last hour (+30)
> – No JavaScript executed on 5 ad visits (+12)
> – Automation tool User-Agent (python-requests) (+30)

**Important:** ClickShield protects and analyses your *website*. It cannot stop a click from being charged inside Google Ads. Filtering clicks before they reach your site is handled by Google Ads' own invalid-click systems. Use the evidence ClickShield collects (GCLIDs, IPs, reasons) to request invalid-click credits or to add IP exclusions in Google Ads.

= What the free version does =

* **Google Ads traffic detection** – gclid, wbraid, gbraid, gad_source, dclid, UTM (cpc/ppc/paid) and ad referrers. Ad visitors are shown separately from organic, direct, referral, social and email traffic.
* **Multi-signal Fraud Detection Engine**
  * Velocity: requests per minute / hour, rapid page navigation.
  * Repeated ad clicks: new clicks per hour / 24h, "left and came back through a new ad after X minutes", same landing page, same browser across several IPs.
  * Client fingerprint: automation tools, headless browsers, header inconsistencies, `navigator.webdriver`.
  * Fake crawlers: Googlebot, Bingbot and others are verified with reverse + forward DNS, never by User-Agent alone.
  * Behaviour: JavaScript execution, time on page, scroll depth and interaction *counts*.
* **Built to avoid false positives** – each signal category is capped. A VPN, a mobile network, a shared IP, a quick exit or an ad blocker is never enough on its own. Shared IPs and mobile networks automatically down-weight IP-based signals.
* **Modern dashboard** – visits, Google Ads visits, suspicious visits and suspicious ad clicks, with daily, weekly, monthly and yearly charts, traffic sources, top countries and cities, most frequent IPs, suspicious User-Agents and Fraud Score distribution.
* **Traffic Log** – filter and search every visit and open a detail panel with the full score breakdown, IP profile and recent activity.
* **Monitor mode** – ClickShield logs and scores traffic and never interrupts your visitors.

= Performance =

* Custom database tables with proper indexes. Visit logs are never stored in `wp_options`.
* The page-load path is one primary-key lookup. Extra queries run only for Google Ads landings.
* Writes happen after the page has been sent to the visitor (`fastcgi_finish_request`).
* Aggregation and cleanup run in WP-Cron.
* Compatible with full-page caching: a tiny deferred beacon analyses cached page views.

= Privacy =

* Choose how IPs are stored: full, anonymized, or salted hash only.
* No passwords, form contents, keystrokes or mouse paths are ever collected.
* Landing pages are stored without their query string.
* Automatic deletion after 7–365 days.
* A suggested privacy-policy text is added to **Settings → Privacy**.

= ClickShield Pro =

The free version tells you which clicks are fraudulent and why. **ClickShield Pro** acts on it:

* Level 2: challenge page (built-in or Cloudflare Turnstile).
* Level 3: automatic temporary blocks.
* Whitelist and blacklist: IP, IP range, ASN, country, User-Agent.
* Datacenter, VPN and Tor detection, IP intelligence, and coordinated cluster detection.
* Reports with CSV and JSON exports, suspicious-GCLID export and a Google Ads IP exclusion list.
* Email alerts, Cloudflare firewall integration, honeypot and security event log.

== Installation ==

1. Install from **Plugins → Add New** (search "ClickShield"), or upload the `clickshield` folder to `/wp-content/plugins/`.
2. Activate the plugin.
3. Open **ClickShield → Dashboard**. Data appears as soon as visitors arrive.
4. If your site is behind Cloudflare or a load balancer, check **Settings → Advanced → Client IP source**.

== Frequently Asked Questions ==

= Will it block my visitors? =
No. The free version only monitors and scores traffic. Blocking and challenges are available in ClickShield Pro.

= Can it stop Google from charging me for fake clicks? =
No plugin can. ClickShield detects and documents fraudulent visits on your site. You can use that evidence with Google Ads (invalid-click investigations, IP exclusions).

= Does it slow down my site? =
No noticeable impact. Analysis is a couple of indexed lookups, writes are deferred until after the response, and heavy work runs in the background.

= Does it work with caching plugins? =
Yes. For cached pages, a small deferred beacon records the visit.

= Does it send data to third parties? =
No. The free version makes no external HTTP requests. Crawler verification uses your server's DNS resolver.

== External services ==

The free version of ClickShield does not connect to any external service.

== Screenshots ==

1. Dashboard with KPIs, traffic & fraud trend and traffic sources.
2. Traffic Log with Fraud Score and reasons.
3. Visit detail: score breakdown, IP profile and recent activity.
4. Settings.

== Changelog ==

= 1.0.0 =
* Initial release.

== Upgrade Notice ==

= 1.0.0 =
Initial release.
