=== Sentrixa Analytics ===
Contributors: sentrixa
Tags: analytics, statistics, privacy, gdpr, cookieless
Requires at least: 5.6
Tested up to: 7.1
Requires PHP: 7.4
Stable tag: 1.9.4
License: GPL-2.0-or-later
License URI: https://www.gnu.org/licenses/gpl-2.0.html

Privacy-first, self-hosted analytics: cookieless visitor tracking, visitor map, top countries, referrers and search terms, stored on your site.

== Description ==

Sentrixa Analytics is a complete, self-contained analytics engine for
WordPress, built by Sentrixa. Your visitor data is written to custom tables
in your own database and is never sent anywhere else.

**What you get**

* Headline numbers: visitors, visits, page views, average engaged time,
  bounce rate — each with a trend sparkline and a change vs. the previous
  period.
* A world visitor map (choropleth) and a top-10 countries list.
* Referrer breakdown: search engines, social media, other websites, direct,
  campaigns — with drill-down to named sources, referring domains and UTM
  campaigns.
* On-site search terms (what people type into your site's search box).
* A slot for Google Search Console query data, filled in automatically once
  Sentrixa SiteHub is connected (coming soon).
* Top pages, entry pages, exit pages, devices, browsers, operating systems.
* wp-admin **Dashboard widgets** so the key numbers are the first thing you
  see when you log in.
* A read REST API for the Sentrixa Sites mobile app.

**How the tracking works**

The plugin adds a tiny (~3 KB) first-party JavaScript beacon. It runs in the
visitor's browser, so it keeps working even when your pages are served from a
full-page cache (LiteSpeed, Cloudflare, WP Rocket, etc.) and PHP never runs —
which is where server-side analytics silently lose most of their data. A
no-JavaScript `<img>` pixel covers the small share of visitors without JS.

**Privacy**

* No cookies. No cross-site tracking. No fingerprinting.
* Unique visitors are counted with a salted hash of IP + user agent, where
  the salt is regenerated every day and never stored — so yesterday's visitors
  can't be recognised today and nobody can be re-identified from the data.
* The IP address is used only for the country lookup and that daily hash, then
  discarded. It is never written to the database.
* "Do Not Track" and Global Privacy Control are honoured by default.
* With the default settings no cookie/consent banner is required, but you
  should still mention analytics in your site's privacy policy.

**Country data**

IP-to-country lookups use the DB-IP IP-to-Country Lite database
(https://db-ip.com), licensed CC BY 4.0. It is bundled with the plugin and
refreshed monthly. No third-party service is contacted for a lookup.

== Installation ==

1. Upload the `sentrixa-analytics` folder to `/wp-content/plugins/`, or install
   the zip from Plugins → Add New → Upload.
2. Activate. Tracking starts immediately.
3. Open **Analytics** in the admin menu. Figures update within a couple of
   minutes of a visit.

**If WP-Cron is disabled on your host**, point a real cron job at:

    wp sentrixa-analytics rollup        # every 10 min
    wp sentrixa-analytics geoip-update  # daily (acts monthly)

== Screenshots ==

1. The dashboard: visitors, visits, page views, engaged time and bounce rate with trend lines, a traffic chart, the world visitor map and top countries.
2. How people found you: search engines, social media, referring sites and campaigns.
3. Your most-read pages, where visitors arrive and leave, and the devices, browsers and systems they use.
4. A "this week" widget on the WordPress dashboard.
5. The visitor map widget on the WordPress dashboard.
6. Settings: privacy-first tracking options, data retention and country lookup.

== Frequently Asked Questions ==

= Does this send my data to Sentrixa? =

No. Everything is stored in your own WordPress database. The only outbound
request the plugin makes is the monthly download of the free DB-IP country
database (which you can turn off).

= Why don't I see the exact words people typed into Google? =

Google stopped putting the search query in the referrer around 2011
("not provided"). The only place that data exists is Google Search Console.
Connect Search Console through Sentrixa SiteHub (coming soon) and those
queries appear on the dashboard. Your own site's search box terms are tracked
without any of that.

= Will it slow my site down? =

The front-end payload is one small static JavaScript file. Recording happens
on a separate lightweight REST request, not during page rendering.

== External services ==
Your visitor data stays in your own database and is never sent anywhere. The only optional external call:

* **Country database download** (repo.sentrixa.co.uk). Off by default. If you switch on "Update the country database automatically" under Analytics > Settings, the plugin periodically downloads a small prebuilt country-lookup file (based on DB-IP Lite, CC BY 4.0, https://db-ip.com). Only a plain request is made; no site or visitor data is sent. The service is provided by Sentrixa Systems Ltd: terms at https://sentrixa.co.uk/legal/plugin-and-website-terms/ and privacy policy at https://sentrixa.co.uk/privacy-policy/. A current database is already bundled with the plugin, and you can also update it manually with the button on the same screen.

== Changelog ==

= 1.9.4 =
* Database: every index now fits the legacy 767-byte InnoDB limit so tables are created on older MySQL/MariaDB. Existing installs migrate automatically.
* The database version is only recorded once all tables exist; if they cannot be created an administrator notice explains why.

= 1.9.3 =
* Plugin-wide unique prefix (sxanl_ / SXANL_) for all functions, classes, options, cron hooks and transients; existing settings and data are carried over automatically.
* Faster, quieter activation: it only creates the database tables and default settings. The bundled country database is copied into place shortly afterwards in the background, and nothing contacts an external server on activation.
* WP-CLI geoip-build now writes only inside the plugin's own uploads folder.

= 1.9.2 =
* Menu moved lower in the admin; GeoIP service terms and privacy links added to the readme; WP-CLI geoip-build checks its output path.

= 1.9.1 =
* The Sentrixa Sites app can now read and edit the shared Sentrixa site profile (business details, social profiles, Search Console codes) for the site.

= 1.9.0 =
* New shared Sentrixa site profile (Settings > Sentrixa site): business details, social profiles and Search Console / webmaster codes are entered once and shared by every Sentrixa plugin. On update, anything this plugin already held is copied into it; nothing is overwritten.
= 1.8.6 =
* The Sentrixa Sites app now adapts to the licence: posting from the app needs an active Sentrixa licence; viewing stats does not.

= 1.8.5 =
* New Settings > Sentrixa licence page (Sentrixa edition) to enter and check the licence key.

= 1.8.4 =
* Sentrixa-edition updates now require the site's Sentrixa licence key (constant SENTRIXA_LICENSE_KEY or option sentrixa_license_key).

= 1.8.3 =
* Dashboard widgets now use the plugin colours (the visitor map showed unvisited countries in black).

= 1.8.2 =
* The Google search terms panel no longer says "coming soon" and only mentions the Sentrixa Sites app in the Sentrixa edition.

= 1.8.1 =
* Code-quality pass for WordPress.org: the bundled country database is no longer a compressed file, file handling uses WordPress APIs, translator comments added. Tested up to WordPress 7.1.

= 1.8.0 =
* Two editions from one source: the WordPress.org edition contains the analytics engine, dashboards and widgets; the Sentrixa edition adds the Sentrixa Sites app integration (pairing, publishing, search-console and uptime feeds) and the self-hosted updater. The country-database download is now opt-in in the free edition.

= 1.7.1 =
* Posts published from the Sentrixa Sites app are now published last, after their categories, tags and featured image are saved, so auto-posting plugins (Sentrixa Social) see the finished post.

= 1.7.0 =
* New "Site uptime" Dashboard widget: whether the site is up, how long it has been up, uptime for 24 hours / 7 days / 30 days, a 48-hour strip and any recent downtime. The site is checked from outside every 5 minutes by Sentrixa Sites; also shown in the Sentrixa Sites app.

= 1.6.0 =
* Google Search Console query data can now be connected through the
  Sentrixa Sites app (Settings on each site) so the "Search terms"
  dashboard panel shows real Google search queries, not just an empty
  state.

= 1.5.8 =
* Country-database download verifies against a content hash and copes
  with hosts whose HTTP layer decompresses the response.

= 1.5.7 =
* The country database now updates by downloading a small, ready-built
  file from Sentrixa (checksum-verified) instead of fetching and
  parsing a large CSV on your server — reliable on every host.

= 1.5.6 =
* Country-database refresh now downloads the file into memory instead of
  streaming it, which some hosts don't handle — the refresh works there now.

= 1.5.5 =
* Country-database refresh: the downloaded file is checked before
  parsing, and malformed rows are skipped rather than aborting the
  whole update (fixes a rare hard failure on PHP 8.1+).

= 1.5.4 =
* Fix: refreshing the country database could hit the host's script time
  limit and fail with a blank screen. It now raises the limits, parses
  the CSV faster, and reports any problem as a normal admin notice.

= 1.5.3 =
* The "Today" hourly chart no longer counts page views with no visitor
  or session id towards the visitor / visit totals for the hour.

= 1.5.2 =
* Update check is now reliable on hosts that cache outbound requests
  (busts the cache, keeps the last good result if the check can't run).

= 1.5.1 =
* Verified the self-hosted update channel end to end — updating from the
  Plugins screen (and WordPress auto-updates) now pulls from Sentrixa.
* Packaging: the build scripts are no longer shipped inside the plugin.

= 1.5.0 =
* The "Today" view now shows an hour-by-hour traffic line instead of a single
  point, so you can see the shape of the day as it happens.
* Update channel: WordPress now checks Sentrixa for new plugin versions and
  offers them on the Plugins screen (with a "View details" changelog and the
  standard auto-update toggle). Settings → Analytics has a "Check for updates"
  button and an "install updates automatically" option (on by default).

= 1.4.0 =
* Fix: the analytics REST endpoints could be stored by a full-page cache
  (LiteSpeed), so a single date range on the dashboard / mobile app could
  freeze on old figures while every other range updated normally. The
  endpoints now instruct the cache never to store them, and updating the
  plugin purges anything already cached.
* Settings screen wording updated to match the near-real-time cadence.

= 1.3.0 =
* Near-real-time dashboard: a stats read now rebuilds today's summary on the
  spot (throttled to once every ~45s), and the background rollup runs every
  10 minutes instead of hourly. Figures are current to within a minute.

= 1.2.0 =
* The read API (/summary, /dashboard, /timeseries, /breakdown, /realtime,
  /geojson) now also accepts a paired connection (X-SXA-Connection +
  X-SXA-Key), so Sentrixa SiteHub can fetch a site's stats for the app.

= 1.1.0 =
* Publishing API for the forthcoming Sentrixa Sites mobile app (used via
  Sentrixa SiteHub): posts (list / read / create / update / trash), media
  upload, taxonomy terms (list / create), and a `/site` capabilities
  endpoint.
* Device pairing: Analytics -> Connect shows a one-time pairing code; a
  per-connection bearer secret is minted on claim and stored only as a hash.
  Connected devices are listed and can be disconnected. WP-CLI:
  `wp sentrixa-analytics pair-code` / `connections`.
* No change to tracking or the dashboard.

= 1.0.1 =
* Settings screen: "Rebuild summaries now" and "Update country database now"
  buttons, so the dashboard can be populated immediately after install and
  on hosts where WP-Cron is unreliable.

= 1.0.0 =
* Initial release: beacon + no-JS pixel tracker, cookieless visitor/session
  model, referrer classification, bot filtering, bundled DB-IP GeoIP with
  monthly refresh, hourly rollup + retention pruning, wp-admin Analytics
  screen with world map, dashboard widgets, on-site search terms, GSC
  ingest endpoint, read REST API, WP-CLI commands.
