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

Privacy-first analytics plugin with lightweight event logging, REST ingestion, and cookieless-capable operation.

== Description ==

Minimal analytics for fast WordPress sites. Read the signal. Leave no trace. It tracks pageviews, engagement, referrers, UTM campaigns, and conversions without storing IP addresses or persistent cross-session identifiers. The admin dashboard is powered by REST endpoints and cached aggregates for fast reporting.

Sessions can be attributed server-side without persistent browser storage for cookieless operation. When the cookie-based session mode is active, Omea Analytics uses short-lived first-party cookies to improve session continuity; those cookies expire after inactivity and do not identify visitors across sessions.

== Features ==

- Privacy-first tracking with cookieless-capable operation.
- Server-side session attribution plus optional short-lived first-party session cookies.
- Pageviews, engagement time, scroll depth, referrers, and UTM campaigns.
- Daily aggregation with cron for fast dashboard queries.
- Conversion and event tracking (client-side + optional server-side hooks).
- Device classification at coarse, privacy-safe levels (type, OS/browser family, screen-size bucket).
- Optional country/city geolocation with multiple providers (see External services).
- REST API endpoints for dashboard, page detail, and filter metadata.

== 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 ==

- Cookieless operation is available. Cookie-based operation uses short-lived first-party session cookies only.
- IP addresses are used only for optional geolocation and are never stored.
- User agents are classified into coarse categories only and are not stored in full.
- Channel grouping follows GA4-style categories using referrers and UTM parameters.

== External services ==

By default, Omea Analytics makes no external requests: session attribution is fully server-side and country detection falls back to your host/CDN headers.

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? =
It can run without analytics cookies, and it can also use short-lived first-party cookies for session continuity when cookie-based operation is active. These cookies expire after inactivity and are not persistent cross-session identifiers.

= Does it store IP addresses or full user agents? =
No. IP addresses are used only for optional geolocation and are not stored. User agents are classified into coarse categories only.

= 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. Privacy-first analytics dashboard with traffic, engagement, conversion, and channel reporting.
2. Per-page report with channel breakdown, engagement time, scroll depth, bounce rate, and conversions.
3. Event and conversion configuration for client-side and server-side measurement.

== 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.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.
