Session replay masking granularity change in Microsoft Clarity

Answer

The default‑mask (mask‑then‑unmask) approach provides stronger privacy guarantees because sensitive UI is hidden before any capture occurs, reducing the chance of inadvertent PII collection.

Likely explanation vs. confirmed facts

Confirmed facts (from Clarity documentation):

• Clarity supports two patterns: (a) mask the whole page then unmask safe regions, or (b) leave the page unmasked and mask only sensitive regions.
• The mask‑then‑unmask pattern hides sensitive data before the first snapshot, limiting early exposure.
• Masking rules are evaluated at capture time; if markup is added after the initial capture (e.g., SPA route changes, third‑party scripts), new elements are not masked unless they carry a data‑clarity‑mask attribute or the mask selector is reapplied.
• Clarity automatically re‑evaluates masks on DOM mutations caused by its own snippet, but reliance on external observers or delayed injections can leave gaps.

Likely explanation:

When a page uses a default‑unmask setup, any content rendered before the mask is applied (including data injected by tag managers or SPA routers) may be captured and transmitted before masking takes effect. Conversely, a default‑mask setup protects that early content but can hide useful interactions if the safe‑area selectors are too broad or miss dynamically added safe regions.

Steps needed for this case

1. Implement the mask‑then‑unmask strategy: add a page‑wide mask via Clarity’s UI or by setting data‑clarity‑mask="true" on the <body> element.
2. Define precise safe‑area selectors (CSS selectors) for regions that must remain visible for heatmaps and replays (e.g., navigation, non‑sensitive forms). Keep these selectors as narrow as practical to avoid over‑unmasking.
3. For any content that is added after the initial render (SPA route changes, third‑party widgets, tag‑manager injected elements), ensure each new node either:
   • includes the attribute data‑clarity‑mask="false" to explicitly unmask it, or
   • is covered by an existing safe‑area selector.
4. If you rely on a tag manager to load the Clarity snippet, verify that the snippet executes before any potentially sensitive DOM mutations; otherwise, initialize Clarity manually after the tag manager loads and immediately apply the mask.
5. On SPA route changes, trigger a mask re‑evaluation by calling Clarity’s API (if available) or by dispatching a simple DOM mutation (e.g., toggling a class on the <body>) to force Clarity to re‑apply its masking logic.

Verification steps

1. Enable debug mode: clarity({ debug: true }) and watch the console for messages like “Element masked” or “Element unmasked” during initial load and after each route change.
2. In the Network tab, inspect the replay payload; masked sections should appear as opaque rectangles or be omitted from the HTML snapshot, confirming that no plain‑text PII is transmitted.
3. Create a test page with a known sensitive element (e.g., an input containing a fake credit‑card number). Verify that heatmaps and replays show the element masked both on initial load and after navigating to a new SPA route.
4. Add a temporary mutation observer that logs when new nodes are added; confirm that each new node either carries data‑clarity‑mask or is covered by an existing safe‑area selector.

Missing diagnostic detail

If you are loading the Clarity snippet via a tag manager that may delay its execution, please confirm whether the snippet runs before any sensitive DOM mutations. This detail changes the recommendation: if the snippet is delayed, you should initialize Clarity manually after the tag manager loads and apply the mask immediately.