Cache-Safe Event Tracking (Beta)

Alpha Insights includes an opt-in beta tracking module designed for full-page cache compatibility. Enable it under Alpha Insights → Settings → General Settings → Alpha Analytics & Event Tracking → Cache-Safe Event Tracking (Beta).

How it works

• Default OFF: The existing tracking system runs unchanged (including PHP session cookies).
• Beta ON: A separate v2 module stores session identity in the browser (localStorage) and never sends PHP Set-Cookie headers for analytics.
• Checkout sync: In checkout_only mode (recommended), analytics cookies are written only on cart/checkout pages so order attribution continues to work.

Cookie storage modes

• Checkout Only (Recommended): Session and attribution data stay in localStorage until the visitor reaches cart or checkout. Best for page caching.
• Immediate: Writes analytics cookies on first visit (similar to legacy behavior). May reduce cache hit rates.

Cache plugin notes

When using checkout_only mode, Alpha Insights registers compatibility hooks for WP Rocket and LiteSpeed Cache to avoid treating wpd_ai_* cookies as cache-busting vary cookies. Configure Cloudflare or other CDNs to cache anonymous HTML separately from cart/checkout if needed.

Server-side events

In checkout_only mode, analytics cookies are written before add-to-cart requests and on cart/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.

Developer filters

• wpd_ai_cache_safe_tracking_enabled — Force enable/disable beta mode.
• wpd_ai_cookie_storage_mode — Override storage mode (checkout_only or immediate).
• wpd_ai_v2_resolve_session_context — Modify resolved session context before DB writes.
• wpd_ai_v2_cache_ignore_cookies — Customize cookies ignored by cache compatibility hooks.
• wpd_ai_event_table_columns — Customize allowed columns when preparing event rows for database insert (v2).

Sunset path

To promote v2: enable by default, then remove the legacy tracking module. To abandon v2: delete includes/analytics-v2/ and assets/js/analytics-v2/, remove the beta setting, and remove the legacy constructor guard.