Enabling Microsoft Clarity Session Recording: A Practical Guide

Why Enable Clarity?

Microsoft Clarity offers free, lightweight session recordings that let you see exactly how users interact with your site—clicks, scrolls, keystrokes, and more—without hurting page load speed. The core of the feature is a tiny JavaScript snippet that you embed in every page you want to track. Once installed, Clarity automatically captures user sessions, generates heatmaps, and stores the data for up to 30 days.

How to Add the Snippet

The snippet is a single <script> tag that you drop just before the closing </head> tag of your HTML. It loads an external script asynchronously from clarity.ms, sets the project ID, and starts recording after DOMContentLoaded fires.

// Replace YOUR_PROJECT_ID with the ID from your Clarity dashboard
<script type="text/javascript">
  (function(c,l,a,r,i,t,y){
    c[a]=c[a]||function(){(c[a].q=c[a].q||[]).push(arguments)};
    t=l.createElement(r);t.async=1;t.src="https://www.clarity.ms/tag/"+i;
    y=l.getElementsByTagName(r)[0];y.parentNode.insertBefore(t,y);
  })(window, document, "clarity", "script", "YOUR_PROJECT_ID");
</script>

**Placement matters**: the snippet must be in the <head> so it runs before the page’s main content loads. If you place it after heavy analytics scripts that block rendering, Clarity may miss early interactions.

Verifying the Snippet Loads

Open DevTools, go to the Network tab, reload the page, and look for a request to clarity.ms/collect with a 200 status. The request payload should contain your project ID.

Capturing Full SPA Sessions

Single‑page applications (SPAs) change the URL without reloading the page. Clarity only starts a new session on a full page load, so internal navigation may not be captured. To fix this, call clarity.start() manually whenever the route changes:

// Example for a framework like React Router
router.afterEach(() => {
  if (window.clarity) {
    window.clarity.start();
  }
});

Doing this ensures each navigation event is treated as a new session and the full interaction history is recorded.

Tracking Custom Events

Clarity automatically records clicks, scrolls, and keypresses, but custom events (e.g., a modal opening) need explicit calls:

// Track a button click with a custom payload
document.getElementById('signup').addEventListener('click', () => {
  if (window.clarity) {
    window.clarity.track('signup_click', {source: 'hero'});
  }
});

Limitations to Keep in Mind

Limit	Impact
Free accounts sample after 5,000 sessions/day	Only a subset of sessions is stored; others are discarded.
Data retention 30 days	Older sessions are automatically purged.
No automatic masking of sensitive input	Keystrokes in payment forms may be recorded unless you mask them.
Requires HTTPS for full functionality	Some features may not work over HTTP.

Common Mistakes & How to Avoid Them

• Placing the snippet after blocking scripts – Move it before any heavy JS to ensure early events are captured.
• Forgetting to call clarity.start() in SPAs – Add a hook on route changes.
• Not excluding internal traffic – In the Clarity dashboard, add your internal IP ranges so they don’t pollute analytics.
• Assuming all custom events fire automatically – Use clarity.track() for any non‑standard interactions.
• Modifying the snippet’s integrity hash or project ID – This will break data transmission.

Security & Privacy Checklist

• Enable data masking for sensitive fields using the clarity.mask() API if you track payment forms.
• Review your privacy policy to ensure compliance with GDPR, CCPA, or other regulations.
• Use the Clarity dashboard’s IP exclusion feature to prevent internal traffic from being recorded.

Final Verification Steps

1. Deploy the snippet to a staging environment.
2. Open the page, perform a few interactions, then stop the server.
3. Check the Clarity dashboard for a new session that matches the timestamp.
4. Replay the session to confirm clicks, scrolls, and keystrokes are visible.

Once you see the session recorded and replayed correctly, the implementation is complete. From there, you can start using heatmaps and session analytics to improve user experience.