Analytics: Visitor Events, Conversions & Attribution

The platform tracks visitor behavior in one table, vse_visitor_events, covering both page-view traffic and named conversion events. This doc covers the conventions for recording events and the reporting that consumes them.

Event types

Constants on VisitorEvent (data/visitor_events_class.php):

Recording events

Bot filtering

Before any row is inserted, save_visitor_event() short-circuits on SessionControl::crawlerDetect($USER_AGENT). The filter is a case-insensitive substring match against a list of known bot patterns (Googlebot, bingbot, facebookexternalhit, Ahrefs, Semrush, curl, python-requests, etc.), plus any request with an empty UA.

Historical note: The filter was silently reporting every real bot as not a bot for a long time due to a reversed strpos() — so bot traffic was being counted in vse_visitor_events. When the filter was fixed, page-view totals typically drop by 20–40% on small sites as bot traffic stops being recorded. If you compare pre- and post-fix analytics numbers, expect that discontinuity.

The same filter gates A/B test counters — see ab_testing.md.

Recording events

The canonical call is on SessionControl:

$session->save_visitor_event($type, $is_404 = FALSE, $ref_type = NULL, $ref_id = NULL, $meta = NULL);

• $type — a VisitorEvent::TYPE_* constant
• $ref_type / $ref_id — a polymorphic reference to the entity the event is about (e.g. 'order' + ord_order_id)
• $meta — free-form metadata for diagnostic rows (e.g. attempted coupon code for TYPE_COUPON_ATTEMPT)

UTM auto-attribution

save_visitor_event() stamps UTM values onto every event row:

1. Page views pull UTM from the current request query string; values are also mirrored to $_SESSION['utm_*'] on first touch for later reuse.
2. Conversion events (non-page-view types) fall back to the session UTM when the request has no query string — so a PURCHASE event fired from a POST handler still carries the original source.

Conversion hook sites

• ShoppingCart::clear_cart() — cart emptied
• cart_charge_logic.php — after the PURCHASE event fires

Attribution reporting

Admin page: Statistics → Attribution (/admin/admin_analytics_attribution)

Filters: date range, optional source filter, optional campaign filter, include-test-orders toggle.

Sections:

1. Channels overview — grouped by vse_source with visits, signups, list signups, cart-adds, checkouts, purchases, revenue, conversion rate
2. Time-series chart — daily visits by top-5 sources (Chart.js 2.8.0)
3. Campaign drilldown — grouped by (source, campaign) to spot which campaign within a channel is producing results

Query conventions

Every Part E query enumerates specific vse_type values — no bare COUNT(*) against vse_visitor_events, no vse_type >= N range filters. The conversion set is:

WHERE vse_type IN (TYPE_CART_ADD, TYPE_CHECKOUT_START, TYPE_PURCHASE,
                   TYPE_SIGNUP, TYPE_LIST_SIGNUP)

Source normalization happens in the query (LOWER(vse_source)) so reddit / Reddit / REDDIT collapse. NULL sources are coalesced to '(direct)'. Test orders are excluded from revenue unless the admin checks "Include test orders".

Attribution model

Implicit last-touch on the event row: the UTM that was in session when the conversion fired. Multi-touch models (first-touch / linear / time-decay / data-driven) are not implemented. The speculative design for those is in specs/FUTURE_attribution_models.md.

Adding a new event type

1. Add a const TYPE_X = N to VisitorEvent
2. Wire the call site(s) via SessionControl::save_visitor_event(VisitorEvent::TYPE_X, ...)
3. If the event is a conversion that should appear in attribution reports, add its column to the Part E channels/campaigns queries (conditional SUM(CASE WHEN vse_type = :type_x THEN 1 ELSE 0 END))
4. If the event uses a reference entity, document the ref_type string and target table