## 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.