=== GreenOrb Statistics – Privacy-Friendly Analytics & Visitor Stats ===
Contributors: phillip2532
Tags: analytics, statistics, visitors, stats, privacy
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

Honest analytics for WordPress: bots filtered out, data stays in your own database. Views, visitors, sessions and geography in your dashboard.

== Description ==

GreenOrb Statistics is a self-hosted, privacy-friendly analytics plugin for WordPress. Your visitor data stays in your own database — there are no third-party tracking services and no external calls to render your reports. It is built as independent modules, so you only run the tracking you actually use.

= Highlights =

* **Page views & visitors** — raw pageviews with a configurable cooldown, unique visitors, sessions, engaged sessions, and bounce rate.
* **Time on page** — engaged time measured with the Page Visibility API (heartbeat-based) and gated on real activity: idle tabs stop counting shortly after the last scroll/mouse/key interaction, while playing audio or video keeps counting. Server-side caps stop background tabs inflating durations.
* **Referrers & traffic sources** — referrers, UTM campaigns, search terms, affiliates, and outbound-link clicks.
* **Devices** — device type, browser, and operating-system breakdowns.
* **Geography** — country (and optional city) detection via Cloudflare headers, MaxMind, or the free DB-IP Lite database. No account or API key required for the DB-IP option.
* **Content reports** — popular posts, authors, taxonomies, entry/exit pages, journeys, and per-post detail.
* **Dashboard widget & admin bar** — a 30-day sparkline, "today so far," and a live "online now" count at a glance.
* **Email reports** — scheduled summaries delivered to your inbox.
* **Tracked clicks** — count clicks on any element, by CSS selector or a `data-greenorb-track` attribute.
* **Annotations** — mark events on your charts.
* **CSV export** — export any report.
* **Writes your privacy policy** — adds a settings-aware section to WordPress's Privacy Policy Guide describing exactly what is recorded, what is not, and your own retention setting, so the published policy matches how the plugin is actually configured.

= Also available in Pro =

These are part of GreenOrb Statistics Pro and are not included in the free plugin:

* **WooCommerce** — revenue overview, product performance, sales funnel, and order insights.
* **Goals & conversions** — custom conversion goals, conversion paths, and landing-page conversion rates.
* **Web Vitals** — Core Web Vitals (LCP, CLS, INP) collected from real visits.
* **Media plays & downloads** — SoundCloud / YouTube play detection and titles.
* **Form tracking** — submissions from Contact Form 7, WPForms, Gravity Forms, Elementor, and Divi.
* **Traffic spike alerts** — get notified when traffic jumps unexpectedly.
* **SPA tracking** — pushState / client-side navigation for single-page themes.
* **Ask AI** — ask questions about your statistics in plain English, plus a weekly AI summary.

= Privacy first =

* Data is stored only in your WordPress database — nothing is sent to an external analytics service. See "External services" below for the short list of optional, non-visitor-data calls the plugin can make.
* Optional IP anonymization and configurable data retention (default 365 days), with never-pruned monthly rollups so year-on-year comparisons survive pruning.
* Plays nicely with consent managers (e.g. Complianz) and includes GDPR-oriented settings.

= Bot filtering =

Automated traffic is filtered using an open-source bot-signature list, with a headless-user-agent check and an optional per-IP daily hit cap. A daily behaviour scan additionally flags the bots that pass every filter — automated real-browser traffic with many sessions on one page and no interaction events — so you can see exactly which "visitors" aren't people.

= Credits & attributions =

Bundled third-party code, with each project's full licence text included alongside it in the plugin:

* Bot detection uses the open-source bot-signature list from the **Matomo device-detector** project (https://github.com/matomo-org/device-detector) — LGPL v3, text at `includes/lib/MatomoBots/LICENSE.txt`.
* Charts are rendered with **Chart.js** (https://www.chartjs.org/), bundled locally — MIT, text at `assets/js/vendor/LICENSE.txt`.
* The world map uses **jQVMap** (https://github.com/manifestinteractive/jqvmap) — dual MIT / GPL, text at `assets/js/jqvmap/LICENSE.txt`.
* Country/city geolocation can optionally use the free **DB-IP Lite** database (https://db-ip.com/) or **MaxMind GeoLite2** (https://www.maxmind.com/). Neither is bundled — the site owner downloads them, under those providers' own terms.

GreenOrb Statistics is licensed GPL v2 or later. The "or later" is what allows the LGPL v3 component above to be distributed as part of the whole, so do not narrow the licence to bare GPL v2.

== External services ==

GreenOrb Statistics stores all of your analytics data in your own WordPress database and never sends visitor data anywhere. It does, however, contact the following third-party services in the specific situations described below. Nothing here runs on plugin activation, and none of it is required for the plugin to work.

= jsDelivr (CDN) =

**What it is:** A free open-source CDN, used to fetch two files that would otherwise go stale: the Matomo device-detector bot list, and the DB-IP Lite geolocation database.

**What is sent, and when:** Only a standard HTTP request — your server's IP address, and a User-Agent identifying the plugin and its version. No visitor data and no site data are ever sent. This happens only when:

* You tick **"Keep the bot signature list up to date automatically"** under Settings → Bots. This is **off by default**; once on, the check runs weekly. Bot detection works without it, using the copy bundled with the plugin.
* You tick **"Keep the geolocation database up to date automatically"** under Settings → Geography. This is **off by default**; once on, the check runs weekly.
* You press a **Download** button on the Geography settings screen, or choose the DB-IP option in the setup wizard.

Service provided by jsDelivr: [terms of use](https://www.jsdelivr.com/terms), [privacy policy](https://www.jsdelivr.com/terms/privacy-policy-jsdelivr-net).

= DB-IP =

**What it is:** The provider of the free DB-IP Lite city database, which turns a visitor's IP address into a country and city on your own server. The file is downloaded once (via jsDelivr, above) and every lookup after that is local — no per-visitor request is ever made to DB-IP.

**What is sent, and when:** Nothing beyond the download request described above. Visitor IP addresses are never sent to DB-IP.

Service provided by DB-IP: [terms of service](https://db-ip.com/tos.php), [privacy policy](https://db-ip.com/privacy.php).

= MaxMind GeoLite2 =

**What it is:** An alternative geolocation database, for site owners who already have a MaxMind account.

**What is sent, and when:** Only if you enter a MaxMind licence key under Settings → Geography. Your server then sends that key to MaxMind to download the database. Downloads happen when you press the button, and weekly thereafter if you have enabled automatic updates. Lookups are local; visitor IP addresses are never sent to MaxMind.

Service provided by MaxMind: [GeoLite2 EULA](https://www.maxmind.com/en/geolite2/eula), [privacy policy](https://www.maxmind.com/en/privacy_policy).

= YouTube =

**What it is:** Used for media-play tracking on pages that embed a YouTube video.

**What is sent, and when:**

* When a page on your site contains a YouTube embed, the visitor's browser loads YouTube's IFrame Player API so the plugin can tell when the video is played. This is the same connection the embed itself already makes; the visitor's browser contacts YouTube directly, and your server is not involved.
* Normally the title comes from the player itself, in the visitor's browser, and your server makes no request at all. Only if you tick **"Look up missing track and video titles"** under Settings → Tracking — which is **off by default** — will your server fall back to one request to YouTube's oEmbed endpoint for the rare play whose title didn't arrive. Only the public video ID is sent, and the result is cached permanently, so it happens at most once per video.

If your site has no YouTube embeds, neither request is ever made.

Service provided by Google/YouTube: [terms of service](https://www.youtube.com/t/terms), [privacy policy](https://policies.google.com/privacy).

= SoundCloud =

**What it is:** Used for media-play tracking on pages that embed a SoundCloud player.

**What is sent, and when:**

* When a page on your site contains a SoundCloud embed, the visitor's browser loads SoundCloud's Widget API so the plugin can tell when the track is played. The visitor's browser contacts SoundCloud directly, and your server is not involved.
* Normally the title comes from the player itself, in the visitor's browser, and your server makes no request at all. Only if you tick **"Look up missing track and video titles"** under Settings → Tracking — which is **off by default** — will your server fall back to one request to SoundCloud's oEmbed endpoint for the rare play whose title didn't arrive. Only the public track URL is sent, and the result is cached permanently, so it happens at most once per track.

If your site has no SoundCloud embeds, neither request is ever made.

Service provided by SoundCloud: [terms of use](https://soundcloud.com/terms-of-use), [privacy policy](https://soundcloud.com/pages/privacy).

== Installation ==

1. Upload the `greenorb-statistics` folder to `/wp-content/plugins/`, or install the ZIP via **Plugins → Add New → Upload Plugin**.
2. Activate the plugin through the **Plugins** screen in WordPress.
3. Open **GreenOrb Statistics** in the admin menu to view your reports. Tracking begins automatically once the plugin is active.
4. (Optional) Visit the **Settings** tabs to configure privacy, data retention, bot filtering, and geography.

== Frequently Asked Questions ==

= Does this send my visitors' data to a third party? =

No. All tracking and reporting happens on your own server, your data is stored only in your WordPress database, and no external call is ever made to render a report.

The plugin does contact a small number of third parties, none of which are sent visitor data, and all of which are itemised under "External services" above.

Three of them are jobs your server does, and none of them run unless you turn them on or press a button: refreshing the bot-signature list, downloading the geolocation database, and looking up the title of an embedded YouTube or SoundCloud track.

The one exception is not your server and is not optional in the same way: on a page that embeds a YouTube video or a SoundCloud player, the visitor's browser loads that provider's player API so plays can be detected. This contacts only the provider whose player is already embedded on that page — no host your visitor's browser wasn't already reaching — and it doesn't happen at all on pages with no such embed, or for a visitor who has declined statistics consent.

= Does it work with caching plugins? =

Yes. View tracking is recorded server-side and via a lightweight front-end script, so it works alongside page caching.

= Do I need an API key for geolocation? =

No. The free DB-IP Lite database works without an account or key, and Cloudflare's country header is used automatically when your site is proxied through Cloudflare. MaxMind GeoLite2 is also supported if you prefer it.

Geolocation is off until you ask for it: no database is downloaded on activation. Choose the geography step in the setup wizard, or press Download on Settings → Geography, and lookups then happen entirely on your own server.

= Does it require WooCommerce? =

No. The plugin works on any WordPress site. WooCommerce reporting is a Pro feature, and even in Pro it only loads when WooCommerce is active.

= What is the difference between the free plugin and Pro? =

The free plugin is a complete analytics tool: page views, visitors, sessions, journeys, referrers and campaigns, devices, geography, content and author reports, bot filtering, tracked clicks, email reports, the dashboard widget, annotations, and CSV export. Pro adds the modules listed under "Also available in Pro" above — WooCommerce revenue reporting, goals, Web Vitals, media, forms, spike alerts, SPA tracking, and Ask AI.

= Where is my data stored? =

In custom tables in your site's database (prefixed `greenorb_statistics_`). Uninstalling the plugin removes its data according to your settings.

== Screenshots ==

1. The Overview dashboard: views, visitors, sessions and bounce rate for today, this week, the last 30 days and all time.
2. The Visitors report: unique, new and returning visitors, with views and visitors charted against the previous period.
3. The Geography report: countries, top country and continent, with a shaded visitor world map.
4. The Bot Filtering report: exactly how much automated traffic was rejected before counting, and the reason for every rejection.
5. The Referrers report: search, social, AI and other referral traffic, with a breakdown by search engine.

== Changelog ==

= 1.0.0 =
* Initial public release.

== Upgrade Notice ==

= 1.0.0 =
Initial public release of GreenOrb Statistics.
