=== CitCom Customer Insights ===
Contributors: citcom0wpteam
Tags: analytics, user-tracking, crm, visitor-tracking, page-views
Requires at least: 6.2
Tested up to: 7.1
Requires PHP: 8.0
Stable tag: 2.6.1
License: GPLv2 or later
License URI: https://www.gnu.org/licenses/gpl-2.0.html

Comprehensive user behaviour analytics and CRM dashboard for WordPress and WooCommerce.

== Description ==

CitCom Customer Insights gives you a clear, sales-focused view of everyone who visits your site: logged-in users, anonymous guests, and returning visitors you recognise by email.

It brings page visits, sessions, devices, and history together in one clean admin dashboard, so you can understand who your visitors really are, before and after they register.

**Free Features**

* **Page visit & session tracking** – every page view is recorded and grouped into sessions with a configurable 30-minute inactivity timeout.
* **Unified user/guest list** – single admin table showing registered users and anonymous visitors side-by-side. Sortable by visits, sessions, last seen, device type, and more.
* **User & guest profile pages** – individual profile pages showing the full activity timeline: pages visited, session history, referrers, device, browser, and OS.
* **CRM Notes** – add, edit, and delete internal sales notes on any user profile.
* **Guest cookie management** – assigns a persistent browser cookie to anonymous visitors. On checkout the guest record is automatically merged into the customer account.
* **Email deduplication** – historical guest sessions are transferred to the user account when a matching billing email is detected at checkout, on login, or on account creation.
* **Device, browser & OS detection** – lightweight built-in user-agent parser; no third-party service or API key required.
* **Consent-aware tracking** – integrates with the WP Consent API and with Cookies Banner & Privacy Suite (WPConsent): when either is active, nothing is recorded until the visitor grants statistics consent.
* **Privacy tools built in** – visitor IP addresses are anonymised by default, recorded data is included in WordPress's personal data export and erasure tools (Tools → Export/Erase Personal Data), suggested privacy policy text is provided, and old data is pruned automatically after a configurable retention period.

**Pro Features**

* **WooCommerce stats on user profiles** – lifetime order value, total order count, average order value, and a full order history list (combined logged-in and guest orders matched by billing email).
* **WPC Smart Wishlist integration** – see every product a user has wishlisted on their profile, and see every user who has wishlisted a product on the product profile page.
* **Product Insights** – dedicated analytics for every WooCommerce product: views, unique viewers, purchases, revenue, and per-product profile pages.

[Upgrade to Pro →](https://citcom.co.uk/wp-plugins/customer-insights/)

== Installation ==

1. Upload the `citcom-customer-insights` folder to `/wp-content/plugins/` or install via the WordPress **Plugins → Add New** screen.
2. Activate the plugin through the **Plugins** menu.
3. Navigate to **Customer Insights** in the WordPress admin sidebar.
4. Optionally configure tracking preferences under **Customer Insights → Settings**.

No database changes are needed — the plugin creates its own tables automatically on activation.

== Frequently Asked Questions ==

= Does it work without WooCommerce? =

Yes. WooCommerce is optional. Without it, the WooCommerce stats tab is hidden on user profiles and the Product Insights section is unavailable.

= Does tracking require user consent? =

If a supported consent management plugin is active (any plugin implementing the **WP Consent API**, or **Cookies Banner & Privacy Suite** (WPConsent)), tracking is automatically gated behind the visitor's statistics consent. Without a consent plugin, visits are recorded by default — it is the site owner's responsibility to disclose this in their privacy policy; the plugin registers suggested policy text to help with that.

= Why does an iPad show as a Mac, or an Android tablet as a phone? =

Device, browser and operating system come from the browser's user-agent string, with no third-party service. Modern iPads identify themselves as Macs, and many Android tablets as phones, so those sessions are labelled that way. Windows 10 and 11 send the same identifier and are shown as "Windows 10/11".

= Will it slow my site down? =

Tracking is performed via a lightweight, non-blocking AJAX request. The visitor-facing script is a single dependency-free file of about 6 kB, loaded in the footer. Database writes are single-row inserts on a dedicated table with proper indexes.

= What data is stored? =

Page URL, page title, referrer, visit time, time on page, session records with device/browser/OS and an IP address (anonymised by default — last octet zeroed for IPv4), plus billing name and email for guests identified at WooCommerce checkout. Two cookies are used: `citccuin_session` (session lifetime) and `citccuin_guest_id` (one year, guests only). All data stays in your own database — nothing is ever sent to an external service.

= How do I delete a visitor's data? =

Data recorded by this plugin is included in WordPress's built-in privacy tools: **Tools → Export Personal Data** and **Tools → Erase Personal Data** (works for registered users and for guests identified by email). You can also delete everything at once from the Danger Zone on the Settings page, and old data is pruned automatically after the configured retention period.

== Screenshots ==

1. Customer Insights list: combined registered users and guests with sortable columns (the Wishlist, Orders and Lifetime Value columns shown are Pro features).
2. User profile, Activity tab: session timeline, page visits, and devices used.
3. User profile, WooCommerce tab: lifetime value, order count, and order list (Pro).
4. Product Insights list with views, viewers, purchases, and revenue (Pro).
5. Product profile with viewer and purchaser tabs (Pro).

== Changelog ==

= 2.6.1 =
* Fixed: Dates and times on every screen now show in your site's timezone using your WordPress date and time formats. Previously some were shown in UTC.
* Fixed: The dashboard's "today" and "last 7 days" figures now roll over at your site's midnight, and the queries behind them use the visit index. The figures are cached for five minutes.
* Fixed: "Total Guests Tracked" on the dashboard now counts the same guests the list shows: not yet converted to a user, with at least one page view.
* Fixed: Products Viewed on user and guest profiles groups by product, so tracking parameters in the URL no longer split one product into several rows.
* Fixed: Order links on profiles open the order whether or not WooCommerce High-Performance Order Storage is on. (Pro)
* Fixed: A note looks the same straight after you add or edit it as it does after a reload. Adding a note now checks the customer exists.
* Added: Each session on a profile shows where the visitor came from (the first outside referrer), for example a search engine.
* Added: A new capability, "citccuin_view_insights", controls who can see the customer list, profiles and notes. Roles that can edit users receive it automatically on update, so nobody loses access; tick other roles under "Who Can View Customer Insights" on the Settings page to grant view-only access (only roles that can already see the Users list are offered). Settings still need the Manage Options capability.
* Added: A short notice after installation pointing to the guest tracking setting, shown until the settings are saved once. New installs start with guest tracking off, IP anonymisation on and a 365-day retention period.
* Added: Every text in the plugin can now be translated, including the admin script; a translation template ships in the languages folder.
* Changed: Windows is labelled "Windows 10/11", since browsers do not say which. See the FAQ on tablet detection.
* Changed: Icon-only buttons on notes have accessible labels.

= 2.6.0 =
* Changed: The free and Pro versions are now built from one codebase. The free version contains no Pro code at all; the Pro version adds its features on top of the same free plugin.
* Changed (Pro): If your Pro licence expires or is cancelled you are no longer redirected away from the plugin's screens. Tracking, the customer list, profiles, notes and settings keep working as in the free version; WooCommerce stats, wishlist data and Product Insights pause until the licence is active again, and a notice on the plugin's pages tells you why.
* Changed (Pro): The guest tracking setting, role exclusions, data retention, IP anonymisation, delete-on-uninstall and the Danger Zone no longer need a licence. They have always been part of the free version.
* Changed (free): The Orders tab on guest profiles now says that order history is a Pro feature, instead of showing an empty list.
* Added: A short note on the Settings page describing what Pro adds, with a link.

= 2.5.3 =
* Fixed: The role and activity filters are back above the customer list. You can show all users, users and guests together, guests only, or a single role, and filter by recent activity.
* Fixed: The two guest cards on the dashboard are now hidden when guest tracking is switched off, instead of showing greyed out with a "DEACTIVATED" label.
* Fixed: Removed invisible characters at the start of some plugin files that could cause "headers already sent" warnings on some servers.
* Changed: Declared compatibility with WooCommerce High-Performance Order Storage and the cart and checkout blocks, so WooCommerce no longer lists the plugin as untested.
* Changed: The database structure is now checked only after a plugin update instead of on every page load. Existing data is not touched.
* Changed: The visitor's session token is no longer printed in the page source.
* Changed: The minimum PHP version is now 8.0. The plugin already needed PHP 8.0 to run; the stated requirement now matches.

= 2.5.2 =
* Changed: Confirmed compatibility with WordPress 7.1; full test pass of the dashboard, list table filters, settings, user/guest profiles, tracking endpoints, privacy export/erase, and scheduled data pruning.

= 2.5.1 =
* Changed: Reworded the plugin description and screenshot captions for clarity.

= 2.5.0 =
* Security/Review: all remaining database queries now pass table identifiers through the %i placeholder in $wpdb->prepare(); the user/guest list query was rebuilt as a fully parameterised statement.
* Changed: removed the last raw `<style>` output — all admin CSS/JS is loaded via wp_enqueue_style/wp_enqueue_script, and the Danger Zone confirmation moved from an inline onsubmit attribute into the admin script.
* Changed: stopped invoking the third-party WPConsent filter for cookie-name discovery; the name is read from WPConsent's settings with a cookie-scan fallback.
* Added: WordPress privacy integration — suggested privacy policy text, personal data exporter and eraser covering visits, sessions, guest records, CRM notes and last-login meta.
* Changed: IP anonymisation is now ON by default for new installs; client IP is read from REMOTE_ADDR only (use the citccuin_client_ip filter behind a trusted reverse proxy).
* Added: WooCommerce checkout guest enrichment/merge hooks are now registered in the free version, matching the documented behaviour.
* Fixed: the daily pruning cron event is now removed on deactivation and uninstall.
* Changed: CRM Notes are now listed as a free feature (they were always functional in the free version).

= 2.4.3 =
* Fixed: Added phpcs:disable annotations for DirectDatabaseQuery warnings in page-dashboard.php and page-settings.php to resolve WordPress Plugin Check findings.

= 2.4.2 =
* Fixed: Fatal error on user/guest profile pages — class_exists() guards added before CITCCUIN_WooCommerce and CITCCUIN_Wishlist calls in class-citccuin-admin.php.

= 2.4.1 =
* Fixed: register_menu() now captures page hooks so admin pages are correctly targeted by the load-{hook} action.

= 2.4.0 =
* Changed: Moved all top-level plugin functions into class static methods — removes the function_exists() guards that WP.org flagged in review.

= 2.3.0 =
* Fixed: Danger Zone (Clear All Tracking Data) is no longer hidden behind a Pro-only flag — the feature was already fully functional, only the UI was gated.
* Fixed: Naming consistency — third-party WPConsent hook usage now properly annotated; internal bootstrap functions renamed to the citccuin_ prefix.
* Fixed: All database queries that reference table names now use $wpdb->prepare() with the %i identifier placeholder instead of raw string concatenation.
* Changed: Requires at least WordPress 6.2 (needed for the %i placeholder used in the SQL fixes above).

= 2.1.10 =
* Fixed: Prevent "Cannot redeclare" fatal error when free and premium plugins are briefly both active during upgrade activation.

= 2.1.6 =
* Lite (WP.org): Removed Pro-only classes (WooCommerce stats, Wishlist, Product Insights, Freemius SDK). This version contains only the free tracking and CRM dashboard features.
* Changed: Plugin renamed to CitCom Customer Insights.
* Fixed: Updated Plugin URI.

= 2.1.5 =
* Fixed: Plugin Check compliance updates.

= 2.1.4 =
* Fixed: Plugin Check compliance — added inline phpcs:disable annotations to all plugin-owned class files.

= 2.1.3 =
* Fixed: Moved all PHPCS suppressions to inline phpcs:disable comments in view files and list table class. Restored missing global $wpdb declaration in dashboard view.

= 2.1.2 =
* Fixed: WordPress.org plugin check compliance — added phpcs.xml; added missing translators comments; fixed unescaped output; added phpcs:ignore annotations for read-only display params.

= 2.1.1 =
* Fixed: Data cleanup and cron removal execute correctly on plugin deletion.

= 2.1.0 =
* Added: Lite/Pro split — free tracking and CRM dashboard features available to all users. Pro features (WooCommerce stats, Wishlist, CRM Notes, Product Insights) available via upgrade.
* Added: CUI_Features class — centralised feature gates with inline upgrade notices on all Pro sections.

= 2.0.1 =
* Added: Wishlist tab on per-product profile page — lists every registered user who has saved that product, with avatar, name, email, and date added.
* Added: Wishlisted stat card on per-product profile showing total unique wishlister count.
* Added: Wishlisted column on the Product Insights list table, sortable by wishlister count (ascending and descending).

= 1.1.1 =
* Added: Product Insights — dedicated analytics list and per-product profile pages for WooCommerce products.
* Added: Product list with sortable columns: Views, Unique Viewers, Purchases, Revenue, Last Viewed.
* Added: Per-product profile with Viewers tab (registered users + guests) and Purchasers tab.
* Added: Category filter and "Popular (last 7 days)" quick-filter on the product list.
* Added: Branded Insights button injected into the native WooCommerce product list.

= 1.1.0 =
* Added: WPConsent integration — tracking automatically respects statistics consent when Cookies Banner & Privacy Suite is active.
* Added: JS tracker listens for wpconsent_consent_processed event to activate tracking mid-page after consent is given.
* Changed: Tracker script always enqueued; consent gate enforced server-side in the AJAX handler.

= 1.0.0 =
* Initial release.
* Page visit and session tracking for registered users and guests.
* Unified user/guest list table with sortable columns.
* Individual user and guest profile pages with activity timeline.
* Guest cookie management with checkout enrichment and guest-to-user transfer on login.
* Email-based deduplication and historical session merging.
* WooCommerce combined order stats (logged-in + guest orders by billing email).
* CRM Notes on user profiles.
* WPC Smart Wishlist integration.
* Device, browser, and OS detection via built-in user-agent parser.
* Settings page (guest tracking, role exclusions, data retention, IP anonymisation, Danger Zone).

== Upgrade Notice ==

= 2.6.1 =
Admin correctness release: times in your site's timezone, dashboard figures that roll over at midnight, session referrers, a view-only capability, translations. Recommended for all users.

= 2.6.0 =
The free and Pro versions now come from one codebase. Pro: an expired licence no longer locks you out; the plugin falls back to the free features until you renew.

= 2.5.3 =
Maintenance release: fixes a possible "headers already sent" warning, restores the customer list filters, and declares WooCommerce HPOS and checkout block compatibility. Requires PHP 8.0.

= 2.5.0 =
Privacy and review-compliance release: WordPress export/erase support, IP anonymisation on by default, fully parameterised SQL, cron cleanup on deactivation. Recommended for all users.

= 2.1.2 =
Maintenance release — resolves all WordPress.org Plugin Check tool findings. Recommended for anyone planning to submit to the WordPress Plugin Directory.

= 2.1.1 =
Maintenance release — no user-facing changes. Recommended for all users.

= 2.1.0 =
Introduces the Lite/Pro freemium model. Free features are unchanged. Fixes PHP warnings on sites where another Freemius-powered plugin is active.

= 2.0.1 =
Adds Wishlisted column (sortable) to the Product Insights list and a Wishlist tab on per-product profiles.
