Clarity session recording fails to start on SPA navigation

Answer to the Core Question

Clarity starts a session when its snippet is first executed on a page load. In a SPA the snippet runs only once – the initial load of index.html (or the root shell). Subsequent client‑side route changes do not trigger a new session unless the snippet is re‑executed or the page is fully reloaded.

What Triggers a New Session?

• Full browser navigation (reload, back/forward to a different URL, or opening a new tab).
• Explicit re‑injection of the Clarity script into the DOM (e.g., a router that mounts a component containing the snippet).
• When the snippet’s internal timer expires due to inactivity – the default timeout is 30 minutes, but this is not documented as a hard limit.

Is There a Public API to Control Sessions?

No, Clarity’s public API only exposes clarity('set', 'key', 'value') for custom tags and clarity('set', 'userId', id) for user identification. There is no documented method to force a session restart or to signal a virtual page view that would keep the same session alive across routes.

Recommended Pattern for SPA

1. Place the snippet once – include it in the top‑level HTML (e.g., public/index.html in React, app.vue root in Vue, or the shell in Angular). Ensure the router never re‑injects the script.
2. Let the SPA handle navigation – use history.pushState or the framework’s router to change the URL. Clarity will automatically record a virtual page view via its internal listener on popstate and pushState events, but the session remains the same.
3. Use custom tags for route context – after each route change, fire clarity('set', 'page', window.location.pathname) or a similar tag. This keeps the session continuous while still providing per‑page attribution.
4. Verify session continuity – open DevTools, inspect network requests to https://www.clarity.ms/.... The sessionId in the payload should stay constant across route changes.

What to Check If You Observe a Session Reset

1. Search the DOM for <script>...clarity('set', ...)</script> after navigation. If the snippet appears again, remove it from routed components.
2. Inspect the clarity.js file in the network panel. Confirm it is loaded only once.
3. Look at the beacon payload. A new sessionId indicates a new session has started.

Missing Diagnostic Detail

To refine the recommendation, please confirm whether your SPA framework re‑mounts the root component (and thus re‑runs the snippet) on each navigation. If that is the case, the solution would involve moving the snippet out of the component tree.