Cache-Safe Event Tracking

Cache-safe analytics is the only frontend event-tracking loader in Alpha Insights. It stores session identity in the browser (localStorage) and does not send PHP Set-Cookie headers for analytics on cached pages. That keeps full-page HTML cache compatible with session tracking.

Configure storage and attribution under Alpha Insights → Settings → General Settings → Alpha Analytics & Event Tracking.

How it works

Two scripts load on the storefront when WooCommerce event tracking is enabled:

• assets/js/analytics/wpd-ai-client.js — session ID, landing page, referral source, cookie sync
• assets/js/analytics/wpd-ai-event-tracking.js — page views, product clicks, forms, WooCommerce JS events

Session and attribution values live in localStorage first. Cookie names stay the same (wpd_ai_session_id, wpd_ai_landing_page, wpd_ai_referral_source) so checkout and server-side hooks can still read them. The localStorage key prefix is wpd_ai_v2_ (for example wpd_ai_v2_session_id). That prefix is intentional so existing visitor sessions continue after upgrades — do not rename it.

Cookie storage modes

• Checkout Only (Recommended): Session and attribution data stay in localStorage until the visitor reaches cart or checkout, or becomes engaged. Best for page caching.
• Immediate: Writes analytics cookies on first visit. May reduce cache hit rates if your cache varies on cookies.

Cache plugin notes

In Checkout Only mode, Alpha Insights registers compatibility hooks for WP Rocket and LiteSpeed Cache so wpd_ai_* cookies are not treated as cache-busting vary cookies. Configure Cloudflare or other CDNs to cache anonymous HTML separately from cart and checkout if needed.

A/B tests are different: a running A/B test must vary HTML, so targeted URLs miss page cache until you pause or complete the test. Analytics cookies stay cache-ignored. See Page Cache and Running Tests.

Server-side events

In Checkout Only mode, analytics cookies are written before add-to-cart requests and on cart or checkout pages. Session attribution is also loaded from the database when a matching session_id is available, so server-side hooks (add to cart, order completion) stay linked to the same visitor session.

Attribution

Landing page and referral source follow the Attribution Window setting (Session Only, or 1–30 days). When Override Attribution on New UTM Visit is True (the default), a new session that arrives with UTM tags or click IDs (gclid, fbclid, and similar) replaces the stored landing page and referral. Turn that setting off to keep first-touch attribution for the full window.

Developer filters

• wpd_ai_cache_safe_tracking_enabled — Returning false disables frontend analytics. There is no legacy PHP-cookie fallback.
• wpd_ai_cookie_storage_mode — Override storage mode (checkout_only or immediate).
• wpd_ai_override_attribution_on_new_utm — Override the UTM last-touch setting.
• wpd_ai_resolve_session_context — Modify resolved session context before DB writes. The previous wpd_ai_v2_resolve_session_context hook still runs after this one.
• wpd_ai_cache_ignore_cookies — Customize cookies ignored by cache compatibility hooks. The previous wpd_ai_v2_cache_ignore_cookies hook still runs after this one.
• wpd_ai_client_ip, wpd_ai_trust_proxy_headers, wpd_ai_cloudflare_ip_ranges — IP resolution. Previous wpd_ai_v2_* names still run after the current hooks.
• wpd_ai_event_table_columns — Customize allowed columns when preparing event rows for database insert.

Retired script handles wpd-ai-client-v2 and wpd-ai-event-tracking-v2 are registered as empty aliases of the current scripts. Dequeue the current handles (wpd-ai-client, wpd-ai-event-tracking) if you need to stop tracking.