=== Kantan Analytics ===
Contributors: inglewood
Tags: analytics, statistics, privacy, heatmap, user journey
Requires at least: 5.0
Tested up to: 7.0
Stable tag: 2.11.0
Requires PHP: 7.0
License: GPLv2 or later
License URI: https://www.gnu.org/licenses/gpl-2.0.html

Lightweight, self-hosted analytics with click tracking, scroll depth, and user journey visualization. No cookies, no external services.

== Description ==

Kantan Analytics is a self-hosted WordPress analytics plugin that tracks visitors, sessions, journeys, and conversions — without cookies, external services, or data ever leaving your server. Every metric lives in your own database. You own it.

Most analytics tools either bury you in dashboards or ship your visitors' data to a third party. Kantan does neither. The dashboard installs in under five minutes, runs in the WordPress admin sidebar you already use, and answers the questions you actually have: which pages convert, where visitors come from, who keeps coming back, and what changed this week.

= Privacy by architecture =

* **No cookies.** Browser localStorage only — no consent banner required in most jurisdictions, no cross-site tracking possible.
* **No IP storage.** Country and region are resolved from an offline GeoIP database at tracking time; the raw IP is never written to disk.
* **No external services.** Every metric stays in your WordPress database. Nothing is phoned home — Kantan can't see your data even if we wanted to.
* **Configurable retention.** Raw session detail purges on the schedule you set (default 90 days). Daily aggregates live in a local SQLite file forever.
* **Bots and admins filtered.** Logged-in admins, common bots, and IPs you specify are excluded before anything is recorded — your numbers reflect actual humans.

= What it tracks =

* **Sessions, pageviews, bounce, duration** — trended across any date range, with device, browser, OS, and screen-resolution breakdowns
* **Traffic sources & UTM capture** — organic, direct, referral, social, paid; UTM parameters captured on first touch and attached to every conversion in the session
* **Click heatmaps & scroll depth** — recorded per-page, per-element, no external script
* **User journeys with named visitors** — every visitor gets a persistent ID and a generated three-part name (e.g. "Roaming Copper Wren") so long journeys are actually legible across return visits
* **Page-to-page flow** — see exactly which path your best visitors walk, and where the rest drop off
* **Conversion tracking** — phone, email, directions, bookings, plus auto-detection of form submissions from Contact Form 7, WPForms, Gravity Forms, Formidable, Ninja Forms, Forminator, and others
* **Long-term aggregate storage** — daily totals kept indefinitely in a local SQLite file even when raw rows are purged on schedule, so five-year trend lines don't require holding five years of personal data

= AI-readable analytics =

Kantan ships with a downloadable Claude Code agent that reads your data through the WordPress REST API using an application password you generate. Ask it questions in plain English — "Which conversions came from organic traffic last month?", "Who are my five most engaged returning visitors?", "Draft me a paragraph about this week's biggest spike." It reads; you approve. Nothing it sees leaves your terminal unless you ask.

= Built for self-hosting =

* **Free forever**, GPL v2
* No accounts, no signups, no SaaS dashboard
* Runs on any standard WordPress install (5.0+, PHP 7.0+)
* ~2 MB plugin, 5–50 MB/year of data depending on traffic
* Extensible sidebar tab system — companion plugins like Kantan SEO snap in alongside the analytics tabs

== Installation ==

1. Upload the plugin folder to the `/wp-content/plugins/` directory, or install it through the Plugins screen in WordPress.
2. Activate the plugin through the 'Plugins' menu in WordPress.
3. The database tables are created automatically on activation.
4. View your analytics at Analytics in the admin menu.

== Frequently Asked Questions ==

= Does this use cookies? =

No. Kantan uses browser localStorage to recognise returning visitors, never cookies. No consent banner is required in most jurisdictions, and no cross-site tracking is possible.

= Where is the data stored? =

All data is stored in your WordPress database in `wp_kantan_*` tables, with daily aggregates in a local SQLite file under `wp-content/uploads/kantan/`. Nothing is sent to external servers.

= How is traffic source detected? =

The tracking script categorizes referrers automatically:

* Organic: Google, Bing, Yahoo, DuckDuckGo, Baidu
* Social: Facebook, Twitter, Instagram, LinkedIn, Pinterest, TikTok
* Referral: Other external sites
* Direct: No referrer or same domain

UTM parameters override referrer-based detection when present, and they stay attached to the visitor through every page and conversion in the session.

= Does this slow down my site? =

No. The tracking script loads asynchronously after page content and uses `sendBeacon` for exit tracking. There are no blocking requests, no third-party domains, and no external CDNs. Performance impact is well under 10ms.

= Is this GDPR / CCPA / ePrivacy compliant? =

Kantan is designed to be the easiest analytics tool to deploy under modern privacy law: no cookies, no IP storage, no third-party processors, no cross-site tracking, and no personal data leaves your server. In most jurisdictions you do not need a consent banner to use it. We're not lawyers — confirm with yours — but architecturally the tool is built for privacy-first compliance rather than retrofitting it.

= Will this work with caching plugins (WP Rocket, W3 Total Cache, etc.)? =

Yes. The tracking script is loaded via standard `wp_enqueue_script` and runs client-side, so cached pages still record visits correctly. The only thing to watch for is plugins that delay or defer JavaScript so aggressively that visitors leave before the script fires — exclude `kantan-analytics/assets/tracking.js` from any "delay JS until interaction" rule and you'll be fine.

= Can I import data from Google Analytics? =

Not currently. Kantan starts tracking the moment you activate it, and historical GA data has a different structure that doesn't map cleanly. If GA→Kantan import is something you need, drop us a note at https://trykantan.com.

= What happens to my data if I deactivate the plugin? =

Nothing — your data stays in the database. Deactivating just stops new tracking and hides the dashboard. If you uninstall (delete) the plugin, the tables remain unless you explicitly drop them; this is standard WordPress behavior and lets you reactivate without losing history.

= How do I exclude my own visits, or specific staff IPs? =

Logged-in admins are excluded by default. The Settings tab also lets you exclude specific IP addresses (one per line). Common bot user-agents are filtered automatically.

= What's the Claude Code agent? =

A downloadable `.md` file from the dashboard that turns any Claude Code terminal session into a read-only analyst for your site. It uses a WordPress application password you generate, calls the REST API, and answers questions in plain English. It only reads — nothing it sees leaves your terminal unless you ask.

= Does this work with WordPress multisite? =

Yes — install at the network level or per-site. Each site gets its own tables and its own dashboard. There's no aggregated network-wide view yet; that's on the roadmap.

== Privacy ==

Kantan Analytics is built to collect the minimum needed to give you useful visitor insight, and to keep all of it on your own server.

**What is recorded:** page views, click positions (as percentages, not pixels), scroll depth, in-session navigation paths, traffic source and referrer, UTM parameters, conversions (form submissions, phone/email/directions clicks), and approximate device, browser, operating system, and screen resolution parsed from the request.

**What is not recorded:** Kantan does not set cookies and does not store visitor IP addresses. Country and region are resolved from an offline database at the moment of the visit, after which the raw IP is discarded. No data is transmitted to Kantan, the plugin author, or any third-party service.

**Retention:** detailed session records are deleted automatically after a configurable window (default 90 days). Only anonymous daily aggregate totals are retained beyond that, in a local SQLite file.

**Disclosure helper:** Kantan registers suggested text with WordPress' built-in Privacy Policy tool (Settings → Privacy), so you can add an accurate disclosure to your site's policy in one click.

== Screenshots ==

1. Overview dashboard — sessions, pageviews, bounce rate, and duration with trend charts and sparklines.
2. Interactions — click region heatmap, scroll-depth distribution, and top-clicked elements.
3. Journeys — page-by-page navigation paths for named, persistent visitors.
4. Realtime — visitors active in the last five minutes with current page and traffic source.
5. Settings — retention, IP exclusion, conversion link rules, and the Claude Code agent download.

== Changelog ==

= 2.11.0 =
* New: Conversions tab — see your conversions by type and by traffic source, with a recent-conversion log, right in the dashboard. Surfaces the conversion data Kantan already tracks via Settings → Conversion Links.
* Dashboard assets (Tailwind CSS and Chart.js) are now bundled with the plugin instead of loaded from a CDN — the admin dashboard makes no third-party requests and works fully offline.
* New: Kantan contributes suggested text to WordPress' built-in Privacy Policy generator (Settings → Privacy), reflecting your configured data-retention window.

= 2.10.0 =
* New: Realtime tab — shows visitors active in the last 5 minutes with their current page, traffic source, session age, and "last seen" age. Auto-refreshes every 30 seconds with a visible countdown and a manual "Refresh now" button. Pauses polling when the browser tab is hidden.
* New: Live visitor count badge next to the "Realtime" item in the dashboard nav. Visible from every tab — the same 30s poll that drives the Realtime tab also keeps the badge current, with a pulsing green dot when at least one visitor is active.
* New: REST endpoint `GET /kantan/v1/realtime?window=5` — returns `{ count, window_minutes, visitors, timestamp }`. Each visitor row includes the most recent pageview (current page), generated display name, traffic source, session age, and seconds since last activity.

= 2.9.9 =
* New: UTM parameters now surface on the Journeys tab alongside each named visitor's session timeline — see campaign, source, and medium for pre-conversion visits (previously only visible aggregated on the UTM tab). REST `/visitors` and `/journeys` endpoints also expose the new fields, so the Claude Code agent and recommendations engine can attribute behavior to campaigns.

= 2.9.8 =
* Fix: conversion link matching corrected — hostname was being searched inside the full URL string (always -1); now checks href.startsWith(rule.domain) OR rule.domain contains hostname. Affected all conversion link click tracking since the feature launched.
* New: Conversion Backfill tool added to Settings. Scans historical click data and creates approximate conversion records for sessions likely missed by the bug. Matches anchor text against each rule's label; backfilled records carry a `_backfill` type suffix. Idempotent — safe to run multiple times.

= 2.9.7 =
* Author renamed from "Kinda Useful Plugins" to "Try Kantan" across plugin header, readme, and updater comment.
* readme description and FAQ rewritten — full feature pitch with subsection structure; FAQ expanded from 4 to 10 items (caching, GDPR/CCPA, GA import, deactivation, multisite, agent, etc.).

= 2.9.6 =
* Fix: conversions endpoint now returns correct visitor_id for pre-2.9.4 records; query uses COALESCE(c.visitor_id, a.visitor_id) to recover attribution from the joined session record when the conversion row has a null visitor_id.
* Fix: version constant bumped to match header (was stuck at 2.9.4).

= 2.9.5 =
* Sidebar nav groups now accordion — clicking a group label collapses or expands it. The active group always starts expanded; inactive groups start collapsed. Keeps the nav usable on laptops when many SEO sub-tabs are registered.

= 2.9.4 =
* Persistent visitor attribution for conversions: `visitor_id` column added to `wp_kantan_conversions` so attribution survives beyond the 90-day raw-data retention window.
* Form integrations now inject `kantan_visitor_id` alongside `kantan_session_id` on all detected forms (CF7, WPForms, Gravity, Formidable, Ninja, Elementor Pro, Fluent, Forminator).
* Schema migration runs automatically on update — no manual action required.

= 2.9.3 =
* Update channel migrated to trykantan.com. Plugin URIs, SEO upgrade link, and auto-updater endpoint now point to the new domain.

= 2.9.0 =
* New: Split test tracking integration — pageviews can now record `test_id` and `variant_id` from a companion split-testing plugin.
* New: `kantan_pageview_tracked` action hook fired after each pageview insert.
* Database migration to add `test_id` and `variant_id` columns to the pageviews table.

= 2.8.0 =
* New: Clickable page URLs throughout dashboard — opens SEO page detail modal or upsell.
* New: Sparkline mini-charts on Overview stat cards.
* Surface recommendations engine on Overview, Interactions, and Journeys tabs.

= 2.7.0 =
* New: IP address exclusion for analytics filtering.
* Rebuilt Journeys tab with visitor profiles and generated names.

= 2.6.0 =
* New: Admin exclusion and bot filtering.
* New: Interactions endpoint for click heatmap and scroll depth data.
* New: Device breakdown endpoint and queries.
* Switched dashboard to left sidebar nav with grouped tabs.

= 2.0.0 =
* New: Click tracking, scroll depth tracking, and user journey analysis.
* New: Entry/exit page tracking and top-clicked-elements report.
* New: Automatic daily cleanup with configurable retention.

= 1.0.0 =
* Initial release: core visitor tracking and admin dashboard.

== Upgrade Notice ==

= 2.11.0 =
New Conversions tab; dashboard assets bundled locally (no CDN); privacy-policy text added to Settings → Privacy. Safe upgrade — no manual steps.

= 2.10.0 =
Adds a Realtime tab and live visitor-count badge. Safe upgrade — no manual steps.
