=== Vireo Analytics – Privacy-First WordPress Analytics ===
Contributors: rebelcode, jeangalea
Tags: analytics, statistics, privacy, gdpr, google-analytics-alternative
Requires at least: 6.9
Tested up to: 7.0
Requires PHP: 7.4
Stable tag: 0.4.4
License: GPLv3 or later
License URI: https://www.gnu.org/licenses/gpl-3.0.html

Privacy-first WordPress analytics. Clean dashboard, no cookies, no consent banners, no third-party tracking.

== Description ==

Vireo Analytics is a self-hosted, privacy-first analytics plugin for WordPress. It gives you the numbers that actually matter — pageviews, visitors, top content, referrers, countries, devices — without cookies, without a consent banner, and without sending a single byte to a third party. All data stays in your own database.

**The numbers you see are the numbers that matter.** Most analytics tools count uptime monitors (StatusCake, UptimeRobot, Pingdom), SEO crawlers (Ahrefs, Semrush), AI bots (GPTBot, ClaudeBot, PerplexityBot), and headless browsers as "visitors" — quietly inflating your stats by 20-40%. Vireo Analytics filters them out at the tracker level with a 30+ pattern bot database and Cloudflare signal detection. What you see is real humans reading your content.

It's designed to be a drop-in replacement for Jetpack Stats or Google Analytics for site owners who want clarity over dashboards full of noise. If you're already running Koko Analytics, Vireo Analytics can import your existing history in one click. If you're moving off Jetpack Stats, the built-in importer pulls up to 14 months of historical data from the Jetpack API.

**Features**

* Clean, fast dashboard with pageviews, unique visitors, and trend charts.
* Top content, top referrers, countries, and device breakdowns.
* Cookie-free tracking — no consent banner needed for basic analytics.
* Daily-rotating salted hashes for visitor identity — GDPR-compatible out of the box.
* Server-side tracking that works with caching plugins — every pageview gets counted, even on cached pages.
* Admin-bar sparkline showing today's traffic at a glance.
* Per-post analytics column on the Posts list screen.
* Custom events API for tracking button clicks, form submissions, and other interactions.
* 404 tracking so you can spot broken inbound links.
* Weekly email digest delivered to your inbox.
* CSV export of any dashboard view.
* One-click import from Koko Analytics and Jetpack Stats.
* Bot filtering via an up-to-date user-agent database.
* Honours Do Not Track and Global Privacy Control: visitors who ask not to be tracked are not tracked, with no setting to turn on.
* Per-site "exclude logged-in admins" setting.


== Installation ==

1. Upload the plugin files to `/wp-content/plugins/vireo-analytics/`, or install via Plugins → Add New and search for "Vireo Analytics".
2. Activate the plugin through the Plugins menu.
3. Visit **Vireo Analytics → Overview** to see your dashboard. First pageviews will appear within a minute.

If you already have analytics data from Koko Analytics or Jetpack Stats, you'll see a one-click import banner on the Overview page. Imports run in the background and can be paused or resumed at any time.

== Frequently Asked Questions ==

= Is this GDPR-compliant? =

Yes. Vireo Analytics doesn't set cookies, doesn't use localStorage for tracking, and hashes visitor identifiers with a salt that rotates every 24 hours. No consent banner is required for basic analytics. Country-level geolocation is derived from the IP on the server; the raw IP is never written to the analytics tables, and the short-lived buffer file holding it is deleted as soon as the aggregator processes it, usually within a minute. You should still mention the plugin in your privacy policy.

= What exactly does the "Visitors" number mean? =

Within a single day it's a true unique count: one person is counted once no matter how many pages they read. Over a longer range it's the sum of the daily counts, so someone who visited on three days in the month counts three times.

That isn't laziness, it's the privacy model. A visitor is identified by a hash of their IP and browser, salted with a secret that is thrown away and regenerated every night. Tomorrow the same person produces a completely different hash, so there is nothing that can link them back to today. That's what makes cookie-free, consent-free tracking legitimate rather than a technicality. The cost is that "unique people this month" is a question the data genuinely cannot answer, and we'd rather say so than print a number that looks precise and isn't.

Pageviews are exact over any range.

= Does it honour Do Not Track and Global Privacy Control? =

Yes, and it's on by default. If a visitor's browser sends `DNT: 1` or `Sec-GPC: 1`, the tracker refuses to fire for them, and the collection endpoint refuses the pageview even if something sends one anyway. Those visits are not recorded anywhere. This costs you some traffic in the dashboard, which is the point: an opt-out you can switch off isn't an opt-out. If you have a specific reason to override it, the `vireo_honor_opt_out` filter can return false.

= How does it compare to Koko Analytics? =

Vireo Analytics started with deep respect for Koko's approach and covers the same ground: cookie-free, self-hosted, clean dashboard. Where they differ: Vireo Analytics includes per-post analytics columns on the Posts list screen, 404 tracking with referrer attribution, an admin-bar sparkline, and a more aggressive bot filter. Both are excellent; pick whichever fits how you work.

= Why are my numbers lower than [other plugin]? =

You're probably used to inflated numbers. Most other analytics plugins count uptime monitors (StatusCake, UptimeRobot, Pingdom), SEO crawlers (Ahrefs, Semrush, MJ12), AI indexing bots (GPTBot, ClaudeBot, PerplexityBot), and various testing tools as "visitors". Vireo Analytics filters all of those out — the numbers you see are real humans reading your content. On most sites this strips 20-40% of what other tools report. We think that's the right tradeoff; if you disagree there's a filter (`va_bot_ua_pattern`) to relax the pattern.

= Can I migrate from Jetpack Stats? =

Yes. The built-in importer pulls up to 14 months of historical data from the Jetpack Stats API (requires an active Jetpack connection). The Overview page will show a one-click banner the first time Jetpack Stats is detected on the site.

= Can I migrate from Google Analytics? =

Not directly — Google Analytics doesn't expose a backfill API that's compatible with our schema. You can run both plugins side by side for a week to confirm the numbers match, then remove GA.

= Does it work with caching plugins? =

Yes. Tracking runs on every page load via a lightweight POST beacon, including cached pages. When you first activate the plugin, you may need to wait for your cache to regenerate before every page starts tracking — once that happens, tracking is universal.

= How does it compare to Google Analytics? =

Google Analytics shows you more (segmentation, audiences, attribution modelling) but requires a cookie banner, sends your visitors' data to Google, and has become increasingly complex. Vireo Analytics answers "how many people visited what, from where, on what device" — which is what most WordPress site owners actually look at. For site owners who don't need enterprise-grade attribution modelling, the tradeoff is usually worth it.

= Does it track logged-in admins? =

By default, no. There's a setting at **Vireo Analytics → Settings** to enable admin tracking if you want to see your own visits (useful for testing).

= How long is data kept? =

Raw visitor hashes and referrer rows are aggregated into daily rollups after 24 hours. Daily rollups are kept indefinitely unless you set a retention limit in **Settings → Retention**. The default retention is 730 days (two years).

= Will it slow down my site? =

The tracking beacon is fired asynchronously after the page is interactive, using the browser's `navigator.sendBeacon()` API where available. The pageview is recorded server-side via a lightweight admin-ajax handler. On a well-hosted site you will not notice a difference.

== External services ==

This plugin includes an optional one-click importer for historical Jetpack Stats data. When (and only when) a site owner runs that importer from **Vireo Analytics → Tools → Import**, the plugin calls the WordPress.com Stats API at `https://stats.wordpress.com/csv.php` to retrieve the site's existing pageview, referrer, and top-post history.

What is sent:

* The site's existing Jetpack `blog_id` (read from the connected Jetpack install).
* The Jetpack API key (read from the connected Jetpack install).
* A requested date range and table name (e.g. `views`, `referrers`, `topposts`).

What is not sent: no visitor data, no user data, no site content, no credentials beyond the Jetpack API key the site already holds.

When it is sent: only while the import is actively running, in response to a site owner clicking "Run Import". No background or recurring calls are made.

The Stats API is provided by Automattic Inc. (WordPress.com).

* Terms of Service: https://wordpress.com/tos/
* Privacy Policy: https://automattic.com/privacy/

The importer is entirely optional. Sites that never run it never contact any third-party service.

== Screenshots ==

1. Main dashboard overview with 30-day chart and top pages.
2. Country breakdown with interactive world map.
3. Settings page.
4. One-click import banner for existing Koko Analytics or Jetpack Stats data.
5. Admin bar sparkline — traffic at a glance on every admin page.

== Changelog ==

= 0.4.4 =
* Fixed: automated scanners could get themselves listed as broken links on your site by faking the page they came from. A referrer is now only believed when it could plausibly be a real page — it cannot be the missing page itself, and it cannot be another address that is also missing.

= 0.4.3 =
* Changed: the 404 report is now two reports. Pages on your site that link somewhere missing are listed as broken links, with the page doing the linking so you know where to go and fix it. Everything else — mostly automated scanners looking for software you don't run — is listed separately. Previously they were mixed, and on a typical site the handful of real broken links were buried under thousands of probes.

= 0.4.2 =
* New: goal completions now fire an action carrying which visitor completed which goal and when, so add-ons can measure things the daily totals can't answer — whether the same person completed one goal and then another, which is what a funnel is.

= 0.4.1 =
* Fixed: a flood of requests for pages that don't exist could grow the 404 report without limit. Those hits are now rate-limited the same way the tracker is, and there's a cap on how many distinct new paths get recorded per day (filterable, and you can turn it off). Broken links you already know about keep counting as before.
* Fixed: the analytics abilities used by AI agents and other Abilities API clients were declared read-only in the wrong place, so WordPress treated them as if they changed your site. Asking for them over GET returned an error, and agents were told a request for your traffic numbers might modify something. They are now correctly marked read-only.

= 0.4.0 =
* New: you can rearrange the dashboard. Grab the handle above any card and drag it where you want it, or tab to the handle and use the arrow keys. Your layout is saved to your own account, so it doesn't change anyone else's, and a Reset layout link puts it back.
* Changed: Top Pages, Top Referrers and Top Countries now sit above the traffic chart. The chart mostly restates the totals you've already read at the top of the page, and it was pushing the tables you actually came for below the fold.

= 0.3.4 =
* New: the dashboard now opens with a plain-language line telling you what matters, before the chart and tables. On a quiet or brand-new site it says so honestly instead of leaving you to read a wall of numbers.
* New: a short note under the pageviews explains why Vireo's totals sit below what server-log or pixel tools report: it counts real browsers only, so bots that never run JavaScript are never counted. Dismissable, and it stays dismissed.

= 0.3.3 =
* New: the plugin now ships in nine languages: Spanish, German, French, Italian, Dutch, Portuguese (Portugal and Brazil), Russian and Japanese. Every screen is covered, including the analytics dashboard.
* Fixed: the dashboard's JavaScript never loaded translations, so the chart tooltips and screen-reader labels, the world-map tooltip and the settings-page messages stayed in English whatever the site language. Those strings now translate like everything else (loaded via wp_set_script_translations).

= 0.3.2 =
* Fixed: the "What changed" panel mixed pages and traffic sources in one list, which double-counted the same change and read as a jumble. Pages and sources are now shown as two separate labelled groups, so you can tell "which of my content moved" from "which sources moved". Your own domain no longer shows up as a referrer.

= 0.3.1 =
* New: countries now set themselves up. Most sites are behind a host or CDN (Cloudflare, Kinsta, CloudFront) that already knows each visitor's country, and the plugin now uses that automatically, with nothing to install. The settings page tells you when this is the case instead of asking you to go and fetch a database.
* New: for sites without that, one button installs a free country database (DB-IP, no account, no license key). This replaces the old four-step MaxMind process, which is still available as an advanced option for anyone who prefers it.
* Fixed: the date-range tabs and the other toggles rendered as plain grey text with no button shape until selected. They now sit on a track with the selected option as a raised pill, so they read as buttons.

= 0.3.0 =
* New: a "What changed" panel that tells you why your traffic moved, instead of leaving you to work it out from five leaderboards. It names the pages and referrers that gained and lost the most, and says which one is actually responsible for the change. It won't guess: if the drop is spread thinly across the whole site, it says so rather than blaming whichever page happens to be top of a list.
* New: the dashboard now warns you when the data itself is wrong. If tracking stops recording, or every visitor's country comes back unknown, or 404s spike, it says so. A tracker that has quietly stopped working looks exactly like a site with no visitors, and nothing used to tell you which one you were looking at.
* Changed: browsers, operating systems and device types are now one Technology card with tabs, instead of three near-identical cards taking a full row.
* Changed: 404s, campaigns and site search moved into a collapsed section at the bottom. They're useful when you want them and noise when you don't.
* Changed: comparison is no longer a Pro feature. It was already showing everyone the numbers while pretending the toggle was locked.
* Improved: changing the date range or a filter no longer reloads the whole admin page. It swaps the cards in place, so switching from Last 30 to Last 90 is instant.
* Improved: every card now expresses change the same way. Percentages on lists, percentage points on shares, so "Chrome -1,568" next to a 58.2% bar no longer reads as a 1,568-point collapse in share.
* Fixed: Direct traffic was always reported as zero. Direct visits have no referrer, so nothing could ever land in that bucket, even though direct is usually the biggest source on a site.
* Fixed: the traffic chart can now be read with a keyboard. Arrow keys step through the days and each one is announced, where the values were previously only reachable with a mouse.
* Fixed: the chart's vertical axis now follows whichever metric you're looking at. Switching to Visitors used to squash the bars against a ceiling that belonged to Pageviews.
* Fixed: the prior period is now drawn as a thin reference line rather than a solid bar. On any day traffic fell, the old bar stood taller than the real one and dominated the chart.
* Fixed: a stray PHP notice on every front-end page load, which on sites with debugging switched on could break the login screen.

= 0.2.10 =
* Fixed: the traffic chart was stretched sideways. It was drawn at a fixed width and then scaled up to fill the card, so on a wide screen everything in it, including the date labels, came out squashed horizontally. It's now drawn at the size it's actually displayed at, and redraws when the window resizes.
* Fixed: the "Start fresh" link on the welcome banner rendered as a bordered box with underlined link text inside it. It was using two WordPress button classes that undo each other.

= 0.2.9 =
* Fixed: on sites with full-page caching, traffic could silently stop being counted. Whether a visitor was a bot, or had asked not to be tracked, was decided when the page was built, and that page then got cached and served to everyone else. If a crawler happened to be the request that filled the cache, the tracker was left out of the cached page and every real visitor served it afterwards went uncounted. The page now always carries the tracker and those decisions are made at the point the visit is recorded, which can't be cached. Do Not Track and bot filtering work exactly as before.

= 0.2.8 =
* Fixed: the dashboard could render as raw, unstyled HTML. Its stylesheet was served from a copy the plugin wrote into your uploads folder, so anything that made that copy unreachable — a host rule, a CDN rewrite, tightened permissions — left the page with no styling at all. The stylesheet now loads from the plugin folder, alongside its JavaScript, where it can't go missing. Old copies in uploads are cleaned up on update.
* Countries now work without a MaxMind database on most sites. If your host resolves the visitor's country for you (Cloudflare, CloudFront, and hosts running the nginx GeoIP module all do), Vireo uses that and you don't need to download anything. The MaxMind file is now only a fallback for sites whose host doesn't provide one.

= 0.2.7 =
* No functional changes. The directory listing now says what the plugin actually does, so people searching for privacy-friendly analytics can find it.

= 0.2.6 =
* Security: the tracking endpoint is now rate limited on every site. The limiter only worked when a persistent object cache (Redis, Memcached) was installed and quietly did nothing otherwise, which is most sites, leaving the public endpoint open to being flooded. It now falls back to APCu, then to lightweight counter files. It still writes nothing to the database on public requests.
* Fixed: retrying an import chunk could count it twice. Imports are applied additively and the browser retries a chunk when a response is lost, which can happen after the data has already been written. The server now records which chunks it has applied and refuses to apply one twice.
* Security: the WordPress.com API key used by the Jetpack importer no longer lingers. It was kept in the options table indefinitely if an import failed or was abandoned, it survived uninstalling the plugin, and it was written back into the import form's HTML. It now expires on its own, is cleared when an import fails, is removed on uninstall, and is never rendered into the page.

= 0.2.5 =
* Fixed: traffic was filed under the wrong day on any site not set to UTC. Days were bucketed in UTC while the dashboard's date ranges were built in your site's timezone, so evening visits could land on tomorrow and "Today" would be missing hours it should have had. The admin bar and the dashboard could also disagree about what "today" was. Everything now uses your site's day, and the visitor salt rotates on the same boundary.
* Note: the changeover creates a one-off seam. Traffic recorded before this update stays bucketed as it was, so the day either side of the upgrade may look slightly off. It settles immediately after.
* Changed: the Visitors figure no longer describes itself as "unique this period" for multi-day ranges, because it isn't. Within a day it's a true unique count; across a range it's the sum of the daily counts. See the FAQ for why the privacy model makes a true multi-day unique count impossible.
* Fixed: a failed database write could silently throw traffic away. The pageview buffer was deleted as soon as it had been read, before the rollups were written, so a deadlock or a dropped connection during the write lost that minute of traffic for good. The buffer is now kept until the database has confirmed the writes, and anything a crashed run left behind is replayed on the next one.

= 0.2.4 =
* Fixed: unique visitor counts were inflated. The aggregator processes pageviews in batches, and it only recognised a repeat visitor within a single batch, so someone reading several pages was often counted as several visitors. Visitors are now tracked across the whole day, so the count is a real unique count. This affects every visitor figure: site, per-post, per-referrer, country, device, and hourly.
* Note: your visitor numbers will drop after this update, on some sites by a lot. Nothing has been lost. The old numbers were counting the same people more than once. Pageviews are unchanged and were always correct.
* Fixed: the per-post referrer table was never covered by the retention setting and grew without limit.

= 0.2.3 =
* Fixed: the tracker is no longer held back by delay-JavaScript optimisers. Perfmatters, WP Rocket, LiteSpeed Cache, and FlyingPress delay scripts until the visitor interacts with the page, so visits that ended without a click or scroll were never counted. Vireo now excludes its own scripts from those optimisers automatically, no configuration needed. If you run one of them, expect your numbers to rise: that is traffic you always had and were not seeing.
* Fixed: the dashboard rendered unstyled on Apache. The hashed dashboard stylesheet was written inside the plugin's data directory, which carries a deny-all rule that Apache also applies to everything beneath it, so the stylesheet was blocked. It now lives in its own directory outside the protected one.
* Fixed: the dashboard overflowed horizontally at 1280px wide, clipping the countries card.

= 0.2.2 =
* Beacon rate limiter now keeps its per-IP state in a persistent object cache only, so public tracker requests never write to the options table.

= 0.2.1 =
* Removed third-party favicon requests from the dashboard, no remote calls remain.
* Tracker reads its runtime config from the database instead of generated PHP files.
* Added nonce verification to the dashboard view filters.
* Prefixed all internal identifiers with vireo_.

= 0.2.0 =
* Initial public release.
* Self-hosted, cookie-free analytics dashboard.
* Importers for Koko Analytics and Jetpack Stats.
* Weekly email digest.
* Custom events API.
* 404 tracking.
* CSV export from any dashboard view.
* Admin-bar sparkline + per-post analytics columns.

== Upgrade Notice ==

= 0.2.2 =
Performance fix from the plugin review: the tracker's rate limiter no longer writes to the options table on sites without a persistent object cache.

= 0.2.1 =
Privacy and hardening fixes from the plugin review: no third-party requests, no generated PHP files, nonce-checked admin filters.

= 0.2.0 =
Initial public release.
