=== Vireo Analytics ===
Contributors: rebelcode, jeangalea
Tags: analytics, statistics, privacy, gdpr, stats
Requires at least: 6.9
Tested up to: 7.0
Requires PHP: 7.4
Stable tag: 0.2.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.

= 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`, Vireo Analytics doesn't load the tracker for them and the collection endpoint refuses the pageview even if a beacon reaches it from a cached page. Those visits are not counted 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.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.
