=== HULO Visitor Analytics ===
Contributors: huloglobal
Tags: analytics, statistics, cookieless, privacy, visitors
Requires at least: 6.5
Tested up to: 7.1
Requires PHP: 8.1
Stable tag: 0.1.0
License: GPLv2 or later
License URI: https://www.gnu.org/licenses/gpl-2.0.html

Cookieless, self-hosted visitor analytics for WordPress: sessions, sources, searches, rage clicks and visitor journeys, stored on your own site.

== Description ==

HULO Visitor Analytics shows how people find and move through your WordPress site, without sending anything to a third party. Every number is stored in your own WordPress database.

Works on any WordPress site. With WooCommerce it also tracks the shopper journey from product page to order.

**What you get, free and without limits**

* **Cookieless by default.** Visitors are counted with a salted, one-way hash of IP address and browser that changes every day. Nothing is written to the visitor's device. You can switch to browser storage, or to "cookieless until consent", driven by your own consent banner (see the FAQ).
* **Sessions and page views**: visitors, sessions, page views, average time on page, bounce rate and conversion rate, each compared with the previous period, plus a daily chart.
* **Journey funnel**: visited → viewed two or more pages → searched or submitted a form → converted. With WooCommerce it becomes the shopper funnel: visited the shop → viewed a product → added to cart → reached checkout → placed an order (classic and block cart and checkout).
* **Conversions**: a session converts when it leads to a WooCommerce order or a payment taken with HULO Payments.
* **Traffic sources**: UTM campaigns, referrers and direct traffic, with the conversions each source brought in.
* **Pages**: top pages, landing pages and exit pages.
* **Audience**: country, device, browser and operating system. Countries come from your CDN or web server (Cloudflare, CloudFront, Vercel, Fastly or a GeoIP module); with WooCommerce, its local geolocation database is used as a fallback. Nothing is looked up externally.
* **Behaviour**: on-site searches, searches with no results, rage clicks, dead clicks and form submissions.
* **Visitor journeys**: every session as a timeline (pages, searches, forms, time on page) with a one-word label such as Purchased, Left with a cart or Bounced.
* **Custom events** from your theme or other code: `window.huloVisitorAnalytics.event('newsletter_signup')`.
* **Dashboard widget** with the last seven days.

**Privacy built in**

* Respects Do Not Track and Global Privacy Control.
* Optional consent gate: nothing is sent until the visitor consents to statistics. Any consent banner can drive it with one line of JavaScript or a cookie, no adapter needed.
* IP addresses are never stored, only hashed with a salt that is thrown away daily.
* Administrators (and shop managers) are not tracked. Bots are flagged and kept out of every figure, or dropped entirely.
* Data older than the retention period (400 days by default) is deleted automatically.
* Suggested privacy-policy text is added under Settings → Privacy.

**Light on the front end and cache-friendly**

One small deferred script (no jQuery, no dependencies) and an inline configuration that is the same for every visitor of a page, so full-page caches keep working. Events are batched and sent with `sendBeacon` to your site's own REST API. The endpoint accepts same-origin requests only, is size-capped and rate-limited per (hashed) IP.

= Pro =

[HULO Visitor Analytics Pro](https://huloglobal.com/wordpress-plugins/visitor-analytics/) is a separate add-on that adds:

* Conversion goals: a page reached, a form submitted, or a HULO Payments payment succeeded, with values
* A live visitors view
* CSV export
* A weekly e-mail report
* With WooCommerce: abandoned-cart detection, reminder e-mails with one-click unsubscribe, links that rebuild the basket, and Slack alerts

Try Pro free for 14 days, no card.

== Installation ==

1. Install this plugin from Plugins → Add New, or upload the zip, and activate it.
2. Open HULO → Visitor Analytics. Tracking starts immediately on every page; open your site in a private window to see your first visit.
3. Optional: choose the visitor identification mode and privacy options on the Settings tab.

If your site is behind Cloudflare or another proxy, pick the header that carries the visitor's IP address on the Settings tab so visitors are told apart correctly.

== Frequently Asked Questions ==

= Do I need WooCommerce? =

No. Everything works on any WordPress site. When WooCommerce is active, the shopper funnel, product names in journeys and order conversions switch on too.

= Does it use cookies? =

No, not by default. In "browser storage" mode, or after consent in "cookieless until consent" mode, it keeps a random visitor id in localStorage so returning visitors are recognised across days.

= How do I connect my consent banner? =

Either way works, without any add-on:

* **JavaScript:** call `window.huloVisitorAnalytics.consent(true)` when the visitor accepts statistics, and `window.huloVisitorAnalytics.consent(false)` when they decline or withdraw consent (this also forgets the stored visitor id). The choice is remembered in the browser.
* **Cookie:** if your banner sets a first-party cookie, enter its name on the Settings tab and the value that means consent (for example cookie `cookie_consent`, value `statistics`). The value can be the whole cookie or one entry in a list such as `necessary,statistics`. The cookie is checked by the tracker and again by the server.

Consent matters in two settings: the "cookieless until consent" identification mode, and the "send nothing until consent" option.

= Why are countries empty? =

Countries are read from headers your CDN or web server adds (for example Cloudflare's CF-IPCountry). Turn that on at your CDN, or enable a GeoIP module on the server. The Settings tab says whether a country header was seen.

= Does it work with page caching? =

Yes. The page HTML contains no per-visitor data and no nonce. The beacon goes to the REST API, which caches do not store.

= Does it slow my site down? =

The script is about 7 kB unminified (under 3 kB gzipped), loads deferred in the footer and sends at most one small request every couple of seconds while a visitor is active. Reports run only in the admin.

= Does it send data anywhere? =

No. The plugin makes no external requests. Everything stays in your database.

= Is it compatible with WooCommerce HPOS and the Cart and Checkout blocks? =

Yes, both are declared and tested when WooCommerce is active.

= Can I delete the data? =

Tick "Delete all analytics data when the plugin is deleted" on the Settings tab before deleting the plugin. Otherwise data is kept for the retention period.

== Screenshots ==

1. Overview: visitors, sessions, page views, daily chart and the journey funnel.
2. Traffic sources, top pages and audience.
3. Behaviour: searches, no-result searches, rage and dead clicks.
4. A visitor journey timeline.
5. Settings: cookieless mode, consent and privacy options.

== Changelog ==

= 0.1.0 =
* First release: cookieless tracking beacon, sessions and page views, journey funnel (shopper funnel with WooCommerce), conversions from WooCommerce orders and HULO Payments payments, traffic sources, pages, audience, searches, rage and dead clicks, form submissions, visitor journeys, custom events, dashboard widget, retention and privacy tools.
