=== Omea Analytics ===
Contributors: cultmetrics
Requires at least: 6.0
Tested up to: 7.1
Requires PHP: 8.1
Stable tag: 0.6.0
License: GPLv2 or later
License URI: https://www.gnu.org/licenses/gpl-2.0.html

Cookieless, privacy-first analytics for WordPress: no cookies, no browser storage, no IP addresses stored, bot traffic filtered out.

== Description ==

Minimal analytics for fast WordPress sites. Read the signal. Leave no trace. Omea Analytics counts visits, pageviews, engagement, scroll depth, sources, UTM campaigns and conversions without cookies or any browser storage – the same approach as Matomo's cookieless mode – so it works from the first page, before and without a cookie banner.

A visit is recognised on your own server by a one-way hash of the IP address, browser and language with a random key that is replaced every day. Nothing identifies a visitor across days, and the IP address itself is never stored. Everything stays in your WordPress database; nothing is sent to third parties.

== Features ==

- Cookieless by design: no cookies, localStorage or other browser storage.
- Visits recognised with a daily-rotating salted hash; a visit ends after 30 minutes without activity.
- Bot traffic excluded: crawlers, scripts, automated browsers and vulnerability scanners are filtered before anything is stored, with a counter of what was filtered.
- Pageviews, engagement time, scroll depth, referrers (host and path) and UTM campaigns.
- Conversions from page visits, clicks, form submissions and events; WooCommerce purchases, checkouts and add-to-carts on the server – without storing who did them.
- Optional "record nothing before Statistics consent" mode for the strictest setups (WordPress Consent API).
- Country and city from a local database on your server (DB-IP or MaxMind) or your host/CDN headers.
- Daily aggregation for fast dashboards; visit-level data deleted after the retention period you choose.

== Installation ==

1. Upload the plugin through the Plugins screen, or copy the plugin folder into `wp-content/plugins/`.
2. Activate **Omea Analytics** from the WordPress Plugins screen.
3. Visit the Omea Analytics settings screen to configure tracking and (optionally) geolocation.

The plugin ships with all compiled assets and required libraries; no build tools are needed to run it.

== Privacy ==

- No cookies and no browser storage. (Only if Omea Consent Pro is installed, it may set a short-lived hand-over cookie for ad-platform conversions, after Marketing consent.)
- IP addresses are never stored. The IP is used, on your server only, to look up the country and city and as part of the daily visit hash.
- The visit hash uses a random key that is replaced every day and the old one deleted, so visits can't be linked across days or traced back to an IP address.
- Stored per pageview: page path (no query string), referrer host and path, UTM parameters, coarse device type, OS and browser family, screen-size bucket, country and city. No coordinates.
- Server-side events (purchases, sign-ups) never store user, order or contact ids.
- Before Statistics consent you choose: measure cookieless (default – many data protection authorities, such as France's CNIL, accept cookieless audience measurement like this without consent; check the guidance in your country) or record nothing until the visitor allows statistics (enforced on the server too).
- Visit-level data is deleted after the retention period; daily totals per page are kept without visitor data.

== External services ==

Omea Analytics makes no external requests while it measures: visits are recognised on your server, and the country and city come from a local database file or your host/CDN headers. Until a database has been downloaded, only the headers are used.

Geolocation beyond header-based country detection is optional and only active when you explicitly select a local database provider on the settings screen:

- **DB-IP City Lite** — when enabled, the site administrator can download the free monthly DB-IP City Lite database from https://download.db-ip.com/free/. The download is administrator-initiated. Lookups then run locally against the downloaded database. See https://db-ip.com/ for their terms.
- **MaxMind GeoLite2** — when enabled, the site administrator can download the GeoLite2 database from MaxMind (https://www.maxmind.com/) using their own MaxMind account credentials. The download is administrator-initiated and lookups run locally. The database is not bundled or redistributed by this plugin. See https://www.maxmind.com/en/geolite2/eula for their terms.

None of these providers are contacted unless you opt in on the settings screen.

== Frequently Asked Questions ==

= Does this plugin set cookies? =
No. Omea Analytics uses no cookies and no browser storage at all.

= Does it store IP addresses or full user agents? =
No. The IP address is used only on your server, for the country/city lookup and the daily visit hash, and is never stored. User agents are reduced to device type, OS and browser family.

= How are bots kept out? =
Pageviews are counted by the browser tracker, so bots that don't run JavaScript never appear. Crawlers, scripts, automated browsers and vulnerability scanners that do are filtered out before anything is stored. Settings › Tracking shows how many were filtered, and can remove bot visits already in your history.

= Old data isn't deleted on my site – why? =
The cleanup runs with WordPress' scheduler (WP-Cron), which only runs when someone visits the site. On a quiet site, or if WP-Cron is disabled, set up a real cron job that calls `wp-cron.php` (for example every 15 minutes) – most hosts offer this in their control panel. Settings › General shows when the last cleanup ran.

= Can I disable tracking for admins? =
Yes. The settings screen includes an option to skip tracking for administrators.

= How do conversions work? =
Conversions can be recorded from client-side events or server-side hooks. You can configure per-event rules in the settings.

== Screenshots ==

1. Dashboard: sessions, pageviews, conversions and engagement against the previous period, top pages, sources, devices and countries.
2. Page stats: pageviews over time, scroll depth, engagement time, where visitors came from and went next.
3. Conversions: goals from page visits, clicks, forms and custom events, events seen on your site and server-side WordPress events.

== Channel grouping ==

Omea Analytics assigns each session a channel_group aligned with GA4 defaults (see https://support.google.com/analytics/answer/9756891):
- Source category detection uses referrer/source/medium and known domains (search, social, video, shopping, email, referral, direct, paid-other). Medium "social/paidsocial" forces social; medium empty + no referrer → direct.
- Channel mapping:
  - Search: medium/utm_medium contains paid|cpc|ppc|ads → paid_search, else organic_search.
  - Social: medium/utm_medium contains paid/cpc/ppc/ads/paidsocial → paid_social, else organic_social.
  - Video: paid → paid_video, else organic_video.
  - Shopping: organic_shopping.
  - Email → email; Referral → referral; Direct → direct; Paid other → paid_other; fallback → other.
- Known sources include major engines (google, bing, yahoo, duckduckgo, baidu, yandex, etc.), social (facebook, instagram, twitter/x, linkedin, pinterest, tiktok, reddit, etc.), video (youtube, vimeo, twitch), and marketplaces (amazon, ebay, etsy, etc.).
- Session channel upgrades: a session initially marked direct can upgrade to a richer channel when later events include UTMs/referrers (e.g., facebook + utm_medium=paidsocial → paid_social).

== Changelog ==

= 0.6.0 =
* Cookieless by design: no cookies or browser storage. Visits are recognised by a daily-rotating salted hash (Matomo-style); the IP address is never stored.
* Pageviews always come from the browser tracker – works with page caching, and bots that don't run JavaScript are never counted.
* Bot traffic excluded: crawlers, scripts, automated browsers and vulnerability scanners are filtered, with a 30-day counter and a one-click cleanup of bot visits already in your history.
* New: choose what happens before Statistics consent – measure cookieless (default) or record nothing (now enforced on the server too, and the page is counted as soon as the visitor allows statistics).
* Data minimisation: referrers without query strings, no coordinates, no user/order/contact ids in server-side events, geolocation debug never stores the IP or request headers.
* Hardened event endpoint: own-site hits only, rate limit per visitor, smaller batches, no location data in responses, proxy headers trusted only from private/known proxies.
* Retention now also clears visit links from daily totals and conversions; uninstall removes downloaded geolocation databases.
* Faster: schema checks run once per version instead of on every request; bot counts use atomic updates in their own table.
* Settings › General shows when old data was last cleaned up.

= 0.5.0 =
* New: Conversions screen – count a visit to a thank-you page, a click, a form submission or an event as a conversion, with an optional value. Turn any logged event into a conversion in one click.
* New: Server-side events moved to the Conversions screen; WooCommerce purchases, checkouts and add-to-carts are listed automatically when WooCommerce is active.
* New: One JavaScript API for all Omea plugins – omea.trackEvent('name') and data-omea-event="name".
* New: Works together with Omea Consent Pro, which can send the same conversions to ad platforms with the visitor's consent.
* Redesigned admin screens.

= 0.4.0 =
* Clarified privacy documentation for cookieless-capable and short-lived cookie-based operation.
* Session attribution moved server-side; removed persistent client-side browser storage.
* Admin dashboard assets now load only on Omea Analytics screens.
* Chart.js and the geo chart library are served locally only (no CDN fallback).
* Removed verbose debug logging from the frontend tracker and admin bundles.
* Documented optional external geolocation services and refreshed privacy details.

= 0.2.1 =
* Initial public release candidate with REST-driven dashboard, aggregation, and settings UI.
