=== 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.2
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, bounce-adjacent metrics, 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, Global Privacy Control, and a 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 and the raw IP is never stored. You should still mention the plugin in your privacy policy — the plugin generates suggested wording for you.

= 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.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.
