Configuring Microsoft Clarity Masking and CSP So Recordings Stay Useful

What you are trying to end up with

You want Clarity session recordings that show real UI failures — a checkout button that never fires, a modal that traps focus — while your Content Security Policy (CSP) stays strict and no customer text or input value leaves the browser in readable form. Those three goals pull against each other, so the useful work is deciding masking granularity and CSP allowances before you turn recording on for real traffic.

Prerequisites

• Edit access to the site's HTML template or tag manager, and to the response headers that set CSP.
• A Clarity project and its project ID (the short alphanumeric string in the snippet).
• A staging or low-traffic route where you can complete a test journey.
• Browser DevTools open on the Network tab, with "Preserve log" enabled so the trace survives navigation.

Step 1: Load the snippet and prove it is not blocked

Clarity ships as a single asynchronous script tag. Place it in the document head or load it through your tag manager so it runs on every route you want recorded.

<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", "PROJECT_ID");
</script>

Replace PROJECT_ID with your own. The loader is a stub queue: calls made before the real script arrives are buffered in window.clarity.q and replayed, so you do not need to defer your own instrumentation.

Now check the Network tab for two separate things: the script request to the clarity.ms host returning 200, and the outbound collection request the script makes afterwards. A restrictive script-src blocks the first. A restrictive connect-src blocks the second, and that failure is quiet — the page looks fine and the dashboard simply stays empty.

Add only the hosts you actually observe. The commonly reported pair is https://www.clarity.ms for the script and https://c.bing.com for collection, but treat that list as needing verification against current Microsoft documentation and your own trace before you ship it, since third-party endpoints are not guaranteed to be stable.

Step 2: Choose masking granularity deliberately

Clarity applies masking in the browser, before the payload is sent, which is what makes it a compliance control rather than a display filter. Project settings offer site-wide masking modes; the exact labels and which one is the default have changed over time, so read the current wording in your project before relying on it.

The practical decision is to start from the strictest site-wide mode and unmask specific regions you need to debug, rather than the reverse. Element-level attributes override the project default:

<div data-clarity-mask="True">...</div>
<div data-clarity-unmask="True">Order total: $42.00</div>

Confirm the accepted attribute values in current documentation; casing has been a source of confusion historically. Two rules of thumb that hold up:

• Never unmask an element that can contain user-typed free text, an email, an address, or a payment field.
• Do unmask stable, developer-authored labels — error messages, step names, button text — because those are what make a replay diagnosable. A recording where every label is a grey block cannot tell you which step failed.

If you use the identify API to attach your own user or session identifier, pass an opaque internal ID. Passing an email address as the friendly name reintroduces exactly the PII that masking removed.

Step 3: Run a scripted test journey

1. Open the site in a private window with no extensions that block analytics.
2. Walk a fixed path: landing page, one scroll to the bottom, one click on a primary call-to-action, one form submission, and one deliberate error (submit with a required field empty).
3. Note the wall-clock time you started.
4. Wait, then check the Recordings tab. A short delay is normal; if nothing appears well beyond the window Microsoft documents, treat it as a configuration fault rather than a traffic problem.

Expected checks

Check	Where	Pass condition
Script loads	Network tab	200 from the clarity.ms host, no CSP violation in the console
Collection beacon sends	Network tab	Request to the collection host is not blocked
Project is receiving	Clarity dashboard	Project reports an active/receiving state
Replay reconstructs	Recordings tab	Your test session appears and plays back
Masking holds	Replay of the form step	Typed values are not readable; labels are

None of these are guaranteed output — read the actual values in your own environment rather than assuming the table describes what you will see.

Recovery options

• CSP violation in the console: add the blocked host to the directive named in the violation message, then reload. Do not widen to a blanket wildcard; that defeats the policy you are trying to keep.
• No session appears: temporarily disable tag managers or consent tooling that may be suppressing the snippet, retest, then re-enable one at a time.
• Replay shows grey blocks where you need detail: unmask the specific container element, not the whole page, and re-run the test journey.
• Replay diverges from what users see: heavy client-side DOM replacement can produce playback discrepancies. Cross-check the same step with a heatmap or funnel rather than trusting the replay alone.
• Rollback: removing the snippet tag stops new collection; it does not delete sessions already recorded. If you need existing data removed, use the project's data controls and confirm retention behaviour against Microsoft's current terms.

Limitations worth stating up front

Clarity reconstructs the DOM and replays events; it is not a video of the screen, so anything drawn outside the DOM — canvas, WebGL, some cross-origin iframes — may not appear. Heatmaps aggregate clicks and scrolls across many sessions, so a bright spot means attention, not success. And the tool answers "what did people do", not "why" — pair it with a quantitative analytics tool if you need to separate a rare bug from a common one.