=== Vago Analytics ===
Contributors: biribazu
Tags: analytics, woocommerce, ecommerce, statistics, dashboard
Requires at least: 6.0
Tested up to: 7.0
Requires PHP: 7.4
Stable tag: 1.0.0
License: GPLv2 or later
License URI: https://www.gnu.org/licenses/gpl-2.0.html

Self-hosted store analytics — sessions, traffic, and conversion funnel — stored in its own SQLite database, not your WordPress database.

== Description ==

Vago Analytics is a self-hosted, privacy-respecting analytics dashboard for WordPress and WooCommerce stores. All data stays on your own server — nothing is sent to a third-party analytics service.

**Own database, not your WordPress database**

Every tracked pageview, click, and checkout event is written to a self-contained SQLite database file under `wp-content/uploads/vago-analytics/`, completely separate from your site's WordPress (MySQL) database. Your store's real data is never touched, and analytics traffic never adds load to the database your site already depends on for everything else.

**What it tracks**

* Unique visitors, pageviews, and a period-over-period Performance Summary
* Traffic sources (direct, organic, social, paid, referral, email) with UTM campaign tracking
* Conversion funnel: visit → product view → add to cart → cart → checkout → purchase, with step-to-step drop-off and automatic "biggest leak" detection
* Per-product performance table (views, add to cart, clicks, purchases, revenue, conversion rate)
* Path branches and top path patterns (WooCommerce stores only)
* Session-level detail with a chronological event trail per visitor
* Blog → product click-through performance
* Geographic breakdown (country/city) with known datacenter/hosting-IP traffic excluded from every report, not just flagged
* Device and browser breakdown
* On-site search keyword tracking
* Coupon attempt tracking (success/fail)

**Rule-based insights, never fabricated**

The dashboard surfaces real, thresholded signals — a funnel leak large enough to matter, a datacenter IP range large enough to be worth investigating — instead of a generic "AI insight" box. If nothing clears the bar, it says so plainly.

**External Access**

Open the same dashboard at a friendly URL outside of wp-admin (Settings → External Access), for anyone who needs to check analytics without any other admin access. Logging in there still uses the normal WordPress login (`wp_signon()`) — it's the same trust model as wp-admin, just without the wp-admin chrome around it.

**Built for WordPress.org from the start**

No CDN-loaded libraries — Chart.js and the MaxMind DB reader are bundled locally (MIT and Apache-2.0 licenses respectively). No external analytics service, no phoning home, no tracking of you as the site owner.

**External service: MaxMind GeoLite2 (optional, your own free key)**

City/country lookups are resolved from a MaxMind GeoLite2 City database, downloaded with your own free MaxMind license key (get one at [maxmind.com/en/geolite2/signup](https://www.maxmind.com/en/geolite2/signup)) and stored/read entirely on your own server — there is no per-visitor request to MaxMind or anyone else. The plugin only contacts `download.maxmind.com` when you first save a license key and, after that, on an automatic weekly refresh to keep city/region boundaries current, exactly the way MaxMind's own license requires. Skip the license key entirely and everything else in the plugin still works — city/country will simply show as unknown. See [MaxMind's GeoLite2 EULA](https://www.maxmind.com/en/geolite2/eula).

This product includes GeoLite2 data created by MaxMind, available from [https://www.maxmind.com](https://www.maxmind.com).

== Installation ==

1. Upload the `vago-analytics` folder to `/wp-content/plugins/`, or install through the WordPress plugin screen directly.
2. Activate the plugin through the "Plugins" screen in WordPress.
3. Go to the new "Vago Analytics" menu item in wp-admin to view the dashboard.
4. (Optional) Visit Settings → External Access to set up a friendly external URL for the dashboard.

== Nginx / LiteSpeed: protecting the analytics database ==

This plugin writes a `.htaccess` file into `wp-content/uploads/vago-analytics/` to block direct access to the SQLite database and GeoLite2 database files. Apache and LiteSpeed (LiteSpeed reads `.htaccess` natively for Apache compatibility) honor this automatically. **Nginx ignores `.htaccess` entirely** — if your site runs on Nginx, add a rule like this to your server block so those files stay private:

`
location ^~ /wp-content/uploads/vago-analytics/ {
    location ~* \.(db|db-wal|db-shm|mmdb)$ { deny all; return 404; }
}
`

The plugin also shows an admin notice automatically when it detects Nginx.

== Frequently Asked Questions ==

= Does this create new tables in my WordPress database? =

No. Sessions and events are stored in a SQLite database file inside `wp-content/uploads/vago-analytics/`, not in your WordPress (MySQL) database.

= Does this require anything unusual from my host? =

It requires the `pdo_sqlite` PHP extension, which is enabled by default on virtually all standard PHP installs (it has shipped with PHP since version 5.3). The plugin shows an admin notice if it's missing.

= Who can view the dashboard? =

Anyone with the `manage_options` capability (administrators, by default) — both in wp-admin and through the optional External Access URL.

= Does this send any data to a third-party service? =

No visitor data is ever sent anywhere — all tracked data stays in the SQLite database on your own server. The only outbound requests the plugin ever makes are to `download.maxmind.com`, to fetch the GeoLite2 City database file using the free license key you provide (Settings → Geolocation) — once when you save the key, and automatically once a week after that. No visitor IP or any other tracked data is included in that request; it's just downloading a database file. City/country lookups themselves happen entirely locally, reading that downloaded file — nothing about an individual visitor is ever sent to MaxMind or anyone else. If you don't add a license key, this request never happens and city/country simply show as unknown.

= Do I need a MaxMind account? =

Only if you want city/country data. It's free — sign up at [maxmind.com/en/geolite2/signup](https://www.maxmind.com/en/geolite2/signup), copy your license key into Settings → Geolocation, and click "Download / Refresh Database Now." Everything else in the plugin works without it.

= What happens to my existing tracked data if I upgrade from an earlier version that used MySQL tables? =

The plugin automatically migrates any existing session/event data from the old MySQL tables into the new SQLite database the first time it runs, then removes the old tables. No data is lost.

= Does this work without WooCommerce? =

Yes. Core traffic/session/funnel tracking works on any WordPress site. A handful of features (path branches, top path patterns, product performance) only appear when WooCommerce is active, since they depend on WooCommerce data.

== Changelog ==

= 1.0.0 =
* Initial release.
