Microsoft Clarity Session Recording Architecture: Data Boundaries, DOM Tracking, and Operational Checks

Problem: Session replay gaps and PII exposure

When the Clarity tracking script is blocked by ad-blockers or runs into browser buffer limits, session recordings can have missing intervals. Meanwhile, if sensitive form fields aren't explicitly marked, plaintext values can travel to Clarity's endpoints.

Useful takeaway

By configuring the data-clarity-mask attribute on input elements and monitoring the session heartbeat event, you can close recording gaps and prevent PII from leaving your domain.

Requirements

• A page that includes the Clarity JavaScript agent (https://clarity.microsoft.com/clarity.js)
• Browser support for DOM MutationObserver (all modern browsers; it's a browser API that watches for DOM changes)
• Network access to Clarity's ingestion endpoint (default: https://consent.services.microsoft.com and https://api.clarity.ms)

Smallest suitable design

Add the Clarity script in the page head, enable session recording, and add data-clarity-mask to any input that may contain personally identifiable information. The agent automatically redacts these values before transmission.

Trust and data boundaries

Clarity's client-side masking layer operates entirely in the browser. The agent evaluates the data-clarity-mask attribute on focused or blurred inputs and replaces the raw value with a placeholder in the event stream that is sent to Clarity. The raw value never leaves the user's device. This boundary means you, as the site owner, are responsible for applying the attribute to every sensitive field; omitting it can leak PII.

Operational checks

After deploying Clarity, open the browser's Network tab and filter for requests to clarity.ms. Look for a heartbeat or session-start payload that includes a masked flag on known fields. Additionally, run Lighthouse with the Clarity script active and compare the Performance score against a baseline; a delta under 2% indicates the agent is not measurably degrading main-thread work.

Failure modes and conditions that would change the design

1. Ad-blocker interference: Extensions such as uBlock Origin can block the Clarity script, causing session gaps. If your audience includes heavy ad-blocker users, consider a fallback analytics method or a first-party script loader.
2. Buffer overflow on high-frequency DOM updates: Pages that perform hundreds of DOM mutations per second (e.g., real-time charts, heavy animation loops) may overflow the internal event buffer, resulting in truncated recordings. Monitoring the agent's console warnings for buffer overflow can surface this.
3. Visual inaccuracy with complex animations: Heavy CSS animations or React state changes that don't fire standard DOM events may produce replay differences compared to the live page. If visual fidelity is critical, evaluate a video-based replay solution.

Concrete example: verifying data masking

Open Chrome DevTools, go to the Network tab, and reload the page. Filter the name column for clarity. Click a request and inspect the payload body. You should see JSON structures where password-type inputs have values like masked. If you see the actual password, the data-clarity-mask attribute is missing from that input. Add an input with the attribute and re-verify.

Diagnostic decision: measuring performance overhead

Run lighthouse https://your-site.com --preset=desktop once with the Clarity script present and once without (disable the script via DevTools > Network conditions > Offline or by blocking the script URL). Compare the total blocking time and interactive metrics. If the difference is less than 50 ms, the agent's DOM mutation listener is not introducing perceptible latency.

Limitations

Masking only works when the data-clarity-mask attribute is present. Automatic detection of new input types is not guaranteed. Additionally, the replay engine reconstructs UI state from an event log; rapid layout shifts or WebGL-based content may not render identically in the replay player.

Practical way to check the result

After adding masking attributes, use the network-tab check described above. For performance, re-run Lighthouse and confirm the delta stays within your acceptable threshold. If buffer-overflow warnings appear in the Clarity console, consider thinning the mutation-observation scope or disabling recording on the most volatile page sections.