Visitor Analytics — User Manual

Overview

Visitor Analytics is a self-hosted, privacy-aware visitor journey tracker. Page views, time-on-page, exit pages, configurable funnel, conversion goals, UTM attribution, bot detection. All data lives in your own database; nothing is sent to a third party.

Survives login — a visitor's pre-signin events and post-signin events share the same visitorId, so funnel analysis works across the auth boundary.

Since 0.8.0 the plugin also ships:

• Cart abandonment — detection, signed recovery links, Slack notification for high-value drops, admin dashboard.
• Product recommendations — also-viewed, personal, and trending endpoints driven by observed co-viewing behaviour.
• Site search analytics — top queries, zero-result queries (direct catalogue-gap intel), search-to-cart conversion.
• Journey drawer buffs — rage-click + dead-click hot-spot lists, per-session heuristic intent label.
• Drop-in storefront helper — one script tag from /ees/hulo.js and every event helper is on window.hulo.

Install

Or by hand:

Storefront integration

Option 1: drop-in helper (recommended)

The plugin serves a typed, batching event helper at /ees/hulo.js. One script tag, every event is on window.hulo:

The helper handles:

• Batching events (1.5s coalescing window) and flushing via sendBeacon on pagehide / beforeunload.
• Emitting a pageview on load automatically.
• Auto rage-click detection (≥3 pointerdowns within 500ms and 20px radius fires rage_click).
• Auto dead-click detection (click on non-interactive element with no URL / significant scroll change within 400ms fires dead_click).

Option 2: typed helpers in your storefront

Recommended for SSR frameworks (Qwik, Next, Remix, SolidStart) so the tracker code ships in your own bundle. Copy this into utils/visitor-tracking.ts:

See the plugin README for the full implementation including the send() batcher and the auto rage/dead-click detectors.

Where to call the helpers

Cart-restore route

The abandoned-cart admin dashboard mints a URL of the form https://shop.example.com/cart/restore?t=<token>. Add a route on your storefront that consumes it:

1. Read ?t= from the URL.
2. Call GET /ees/recover-cart?t=<token> — returns {{ ok: true, items: [...] }} or {{ error }}.
3. If the visitor already has items in their live cart, don't overwrite — show a friendly "you already have items in your cart" message.
4. Otherwise, re-add each {{ variantId, qty }} via your Vendure order API (typically addItemToOrder(productVariantId, quantity)).
5. Navigate to /cart.

The token is signed, time-bounded (default 72h), and non-reusable. If it's expired or already consumed, the endpoint returns {{ error: 'expired-or-invalid' }}.

Cart abandonment

Detects sessions that put items in the cart but never checked out. Turns them into AbandonedCart rows you can send a recovery email against.

Enable it

How the scanner works

A worker-only interval (5 minutes) walks recent cart_snapshot events, grouped by session. For each session:

• If checkout_completed landed later — no-op (or promote an existing abandoned row to converted).
• If the last cart_snapshot is older than windowMinutes and no fresh snapshot — open an abandoned_cart row (unique on sessionId — can't double-open).
• If the value clears slackMinValueMinor, POST a one-off notification to Slack (idempotent — notificationSent flag).

Admin dashboard

Under Analytics → Abandoned carts. Filters by status / min value / email / window; KPIs (open, recovered, converted, lost value); actions per row: mint recovery link (copies URL to clipboard), mark recovered / dismissed manually. CSV export.

Recovery link lifecycle

1. Admin clicks "Recovery link" on an abandoned row.
2. Backend mints a random opaque token and returns {{ url: '<storefront>/cart/restore?t=...' }}.
3. Admin drops the URL into a recovery email.
4. Recipient clicks — the storefront's /cart/restore route exchanges the token via /ees/recover-cart?t=... and re-adds the items.
5. Once the visitor completes the checkout, the scanner promotes the row to converted.

Product recommendations

Recommendations derived from observed co-viewing behaviour. The scanner walks recent product_view events per session, extracts every ordered pair, and increments a counter per (productIdA, productIdB, channelId) triple.

Endpoints

Storefront wiring

Site search analytics

Reads back over the visitor_event table where the storefront has fired search custom events. Zero new schema.

Storefront wiring

Endpoints

Journey drawer buffs

Rage-click + dead-click hot spots

The auto-detectors bundled with hulo.js fire rage_click / dead_click events with the offending element's CSS selector. Two admin endpoints aggregate them per URL:

• GET /ees/journey/rage-clicks?days=7 — pages where visitors are frustrated.
• GET /ees/journey/dead-clicks?days=7 — elements that look clickable but aren't.

Both are conservative heuristics — the signal is direction-of-frustration, not a metric to optimise against.

Per-session intent labels

GET /ees/journey/session-summary?visitorId=abc returns one row per session with a heuristic intent label:

Conversion goals

A conversion goal is a URL glob that, when matched by a pageview, counts that visitor as having completed the goal. Patterns support:

• * — match zero or more chars within a path segment
• ** — match zero or more segments (including /)
• everything else is a literal substring (case-insensitive)

Examples

Creating a goal

Once created, every matching pageview is tagged with the goalId on its visitor_event row. The admin stats endpoint at /ees/goals/stats?days=30 aggregates completions per goal.

Privacy controls

The plugin defaults to privacy-respecting behaviour. Toggle as needed:

Bot detection

Every event is checked against an embedded list of ~45 bot UA patterns: Googlebot, Bingbot, Facebook scrapers, monitoring probes (UptimeRobot, Datadog, Pingdom), HTTP libraries (curl, wget, axios, requests, node-fetch), headless browsers (HeadlessChrome, Puppeteer, Playwright).

By default these events are stored with isBot: true so you can see bot share but they're excluded from "real human" counts in the admin dashboards. Flip dropBotEvents: true to skip ingest entirely.

Admin UI tour

Other admin views:

• Funnel — drop-off per configured step
• Exit pages — where visitors leave
• Top events — custom event distribution
• Top pages — most-visited URLs
• Live — SSE-streamed real-time count
• Journey — full per-visitor timeline (drill from any of the views above)

HTTP endpoints

Public (browser-safe, CORS-permissive)

Admin (requires a Vendure admin session; ReadCustomer unless noted)

Troubleshooting

Visitors aren't being counted

Check the response of POST /ees/track — if skipped: 'dnt' the visitor is sending a Do-Not-Track header (and your honorDoNotTrack option is on, which it is by default). Set the option to false to override.

Goals don't seem to fire

The matcher only runs for type: 'pageview' events — custom events (type: 'event') don't trigger goals. Also, the goal cache refreshes every 60s; new goals start counting after that.

MaxMind geo isn't populating

The plugin uses the geolite2-redist package to download the GeoLite2 City DB on first use. If the download fails (network, sandboxed env), geo fields stay null. You can force a re-download with npx geolite2-redist refresh from your Vendure project root.