=== Visitrix – Lightweight Visitor Analytics ===
Contributors: akklex
Tags: analytics, statistics, visitors, traffic, stats
Requires at least: 6.2
Tested up to: 7.1
Requires PHP: 7.4
Stable tag: 1.2.0
License: GPLv2 or later
License URI: https://www.gnu.org/licenses/gpl-2.0.html

Lightweight self-hosted visitor statistics: traffic sources, search engines, devices, browsers, time on site and bounce rate. No external services.

== Description ==

Visitrix gives you a clean, informative traffic summary right in the WordPress admin – without third-party services or heavy scripts, and without cookies by default. Open **Statistics** in the admin menu and see where your visitors come from, what devices they use and how engaged they are.

= What you get =

* **Key metrics** – visits, visitors, pageviews, bounce rate, page depth, time on site and share of new visitors, each compared with the previous period.
* **Traffic chart** – by hour for short periods, by day for longer ones. Toggle visits, visitors, pageviews and new visitors.
* **Traffic sources** – direct traffic, search engines, social networks, messengers, AI assistants (ChatGPT, Perplexity, Gemini and others), links from other sites, ads (UTM tags, yclid, gclid) and internal traffic.
* **Search engines** – Google, Yandex, Bing, DuckDuckGo, Mail.ru, Baidu and others.
* **New and returning visitors** – bounce rate, page depth and time on site for each group, plus loyalty (how many times visitors came back).
* **Online now** – visitors active during the last 5 minutes.
* **Devices** – PC, smartphone or tablet, plus browsers and operating systems.
* **Content** – popular pages, landing pages and UTM campaigns.
* **Periods** – today, yesterday, 3 days, week, month or any custom date range.
* **Dashboard widget** with today's numbers.

= How metrics are calculated =

* A **visit** is a sequence of pageviews with no more than 30 minutes of inactivity. Arriving from a different external source starts a new visit.
* A **bounce** is a visit with a single pageview that lasted less than 15 seconds.
* **Time on site** is measured with lightweight engagement pings while the page is visible.
* A **new visitor** is a visitor whose first visit falls within the selected period; everyone else is returning. Each visitor belongs to exactly one group.
* With the **robot filter** (on by default) a visit is counted after the first real interaction: scroll, tap, click, key press or a second pageview.

= Lightweight =

* The tracker script is about 3 KB, loaded with `defer` and sent with `navigator.sendBeacon`, so it does not slow pages down.
* Works with page caching plugins – the front-end needs no nonces or PHP sessions.
* Two compact database tables with automatic cleanup of old records.
* The dashboard is plain JavaScript with built-in SVG charts – no external libraries, no CDN.

= Visitor identification =

Choose the mode that fits your privacy policy:

* **Without cookies** (default) – a random anonymous ID in localStorage.
* **Accurate** – the ID is also kept in a first-party HttpOnly cookie set by your own server. Returning visitors are recognized in Safari after 7+ days and across www/non-www.
* **Anonymous** – nothing is stored in the browser. Pageviews are grouped into visits with a hash of IP and user agent that changes daily; the IP itself is never stored.

Works with the **WP Consent API**: until a visitor allows statistics in your cookie banner, their visits are counted in the anonymous mode.

= Privacy =

* No cookies by default; nothing at all is stored in the anonymous mode.
* IP addresses are not stored.
* All data stays in your own database and is never sent to third parties.
* Optional respect for the browser Do Not Track signal.
* Suggested text is added to the WordPress Privacy Policy guide.

== Installation ==

1. Install the plugin from the **Plugins → Add New** screen, or upload the `visitrix` folder to `/wp-content/plugins/`.
2. Activate the plugin.
3. Open **Statistics** in the admin menu. Data appears after the first visits.
4. Optional: choose excluded roles and data retention in **Statistics → Settings**.

== Frequently Asked Questions ==

= Are my own visits counted? =

By default, visits from logged-in administrators are not tracked. You can choose excluded roles in the settings. To test tracking, open the site in a private window.

= Does it work with caching plugins? =

Yes. The tracker is a static script that sends data to the REST API, so cached pages are counted correctly.

= Do I need a cookie banner? =

Visitrix does not set cookies and does not store IP addresses, but it does store an anonymous identifier in localStorage. Requirements differ by country – please consult your legal adviser.

= Why are the numbers different from Google Analytics or Yandex Metrica? =

Every tool filters bots and counts sessions slightly differently. Visitrix counts only real browsers that execute JavaScript, and ad blockers usually do not block a first-party script, so numbers are often a bit higher.

= Why can a returning visitor be counted as new? =

The anonymous ID lives in the browser. A private window, cleared site data or another device make the visitor look new – other analytics tools have the same limitation. Safari also clears localStorage after 7 days without visits; switch to the **Accurate** mode in the settings to avoid that.

= How do I exclude my own visits? =

Logged-in administrators are not counted by default. To exclude a device where you are not logged in (for example, your phone), open **Statistics → Settings** on it and click **Do not count this browser**.

= Who can see the statistics? =

Users with the `manage_options` capability (administrators). Developers can change it with the `visitrix_view_capability` filter.

= Will deleting the plugin delete my statistics? =

Only if you enable "Delete all statistics and settings when the plugin is deleted" in the settings. By default the data is kept.

= Where can I get support? =

Use the support forum on WordPress.org or write to the developer in Telegram: [t.me/Alex_mlr_dev](https://t.me/Alex_mlr_dev).

== Screenshots ==

1. Traffic summary: key metrics with comparison to the previous period and the traffic chart.
2. Traffic sources, device types, search engines and browsers.
3. New and returning visitors and the detailed sources report.

== Additional Information ==

= Developer =

Visitrix is developed and maintained by [genius-bot.ru](https://genius-bot.ru).

* Website: [genius-bot.ru](https://genius-bot.ru)
* Telegram: [t.me/Alex_mlr_dev](https://t.me/Alex_mlr_dev) – questions, bug reports and feature requests.

= Requirements =

* WordPress 6.2 or later
* PHP 7.4 or later
* MySQL 5.7+ or MariaDB 10.3+
* WordPress REST API must be reachable (it is enabled by default)

= Languages =

Visitrix is fully translatable. Translations are delivered automatically from [translate.wordpress.org](https://translate.wordpress.org/projects/wp-plugins/visitrix/) – you can help translate it into your language.

= Data stored =

* `{prefix}visitrix_visits` – one row per visit: start time, duration, pageviews, source, landing page, UTM tags, device type, browser and OS.
* `{prefix}visitrix_hits` – one row per pageview: page path and title.
* `{prefix}visitrix_visitors` – one row per known visitor: anonymous ID, first and last visit, number of visits.

Records older than the retention period (365 days by default) are removed daily.

= Developer hooks =

* `visitrix_should_track` (filter) – return `false` to skip tracking on the current page.
* `visitrix_source_rules` (filter) – add or change search engines, social networks, messengers and AI services.
* `visitrix_view_capability` (filter) – capability required to view reports.
* `visitrix_client_ip` (filter) – client IP used for the anonymous daily hash (for sites behind a proxy).

== Changelog ==

= 1.2.0 =
* New: accurate new vs returning visitors – every visitor belongs to exactly one group, decided on the server.
* New: "Accurate" identification mode with a first-party cookie (works in Safari and across www/non-www).
* New: "Anonymous" mode without any browser storage.
* New: WP Consent API support.
* New: robot filter – visits are counted after the first real interaction.
* New: "Online now" and the loyalty report.
* New: "Do not count this browser" button in the settings.
* Fix: pages prerendered by the browser but never opened are no longer counted.
* Fix: when localStorage is blocked, the tracker falls back to sessionStorage instead of creating a new visitor on every page.

= 1.1.1 =
* Translations are now loaded from translate.wordpress.org.
* The admin menu item is placed after the core menu items.

= 1.1.0 =
* New: "New and returning visitors" report.
* New: "New visitors" line on the traffic chart.
* New: support link on the Plugins screen.

= 1.0.0 =
* Initial release.

== Upgrade Notice ==

= 1.2.0 =
More accurate new and returning visitors, robot filter, consent support and "Online now".

= 1.1.1 =
Compatibility improvements for the WordPress.org directory.

= 1.1.0 =
Adds the new and returning visitors report.
