Skip to content

Core Explanation

Introduction

Below is a thought process for implementing configuring of the UIC ensuring you achieve maximum data capture and maximum session replay fidelity while still controlling performance and privacy/compliance risk.

Fidelity

What does “high-fidelity replay” mean for your visitor journeys?

On some sites it means every click and form change is present. On others it means the replay visually matches what users saw, including dynamic UI states.

Suggested starting position for success:

  • Replays show the correct screen transitions (including SPA route / hash changes)
  • Form input changes appear consistently, including edge browsers
  • Dynamic UI updates after click are captured (checkbox/radio states, validation messages, modals). The config uses delayed DOM capture on radios/checkboxes explicitly for this
  • No data loss at page unload / navigation close. The config focuses on queue transport settings and browser overrides

Inventory

Understand your sites architecture, the shape of your DOM determines your capture approach.

  • Is your site a SPA, MPA, or hybrid? If you rely on URL changes (path/hash) rather than full reloads, make sure screenview auto-detection and hashchange capture are enabled, as shown.
    • If you have a complex SPA with late hydration, adopt a delayed full DOM capture on load like delay: 1500 to avoid capturing an incomplete DOM.
  • Do you use iframes for key content? If important user journeys occur inside iframes, you should ensure event capture recurses into frames and DOM capture includes frames (recurseFrames: true, captureFrames: true).
    • If you have third-party frames (ads/chat) that create noise, consider a frames blacklist like framesBlacklist. But only blacklist after you’ve verified it doesn’t remove critical journey content.
  • Do you use Shadow DOM / Web Components? The UIC config attaches change events to shadows (attachToShadows: true for change) but does not capture Shadow DOM in snapshots (captureShadowDOM: false). That can produce “events without visuals” in replay if your UI lives in shadow trees.
    Thought process: if key UI is in Shadow DOM, consider enabling shadow DOM capture (or apply vendor-recommended replay rules) because events alone won’t guarantee visual fidelity.

Browser support

A high-fidelity configuration is always constrained by browser capabilities.

Legacy IE and form fidelity

The UIC as standard calls out a known gaps: legacy IE may not propagate change events reliably at the document level, so it sets a targeted selector for legacy IE (input, select, textarea, button). If you must support legacy IE, you should use targeted changeTarget to avoid missing form changes (which breaks session replay). In modern browsers, leaving it undefined may be fine because document-level change capture is sufficient (as the config comment states).

IE10 / IE11

Diff and privacy-pattern compatibility. The config disables diff capture in IE10 (diffEnabled: false) and adjusts triggers accordingly. It also disables privacyPatterns entirely on IE11.

  • Identify which browsers can support diff-based DOM capture reliably; if not, fall back to full snapshots or reduced triggers (as IE10 does).
  • Validate whether privacy patterns are safe and functional in each browser; if you disable them (like IE11 here), you must ensure compliance still holds via other privacy controls.

Firefox

Unload & fetch reliability. This UIC by default disables useFetch and turns off asyncReqOnUnload for Firefox due to fetch issues.

  • Test your site’s end-of-session delivery (tab close, navigation away, SPA route changes) per browser
  • If you see tail-loss in Firefox (or any browser), consider a targeted override like this one

Capture Events

Must-have replay events

The UIC config prioritises: click, change, focus, blur, navigation signals (load, unload, hashchange), and context (scroll, resize, orientationchange, touchstart/touchend).

  • For replay, click + change are usually non-negotiable (they drive most UI state)
  • For mobile, touch events can be necessary to interpret intent
  • For SPAs, hash/route detection is essential to segment the replay into meaningful views

Recurse frames and shadows

  • The UIC config uses recurseFrames: true for replay and usability events, increasing coverage in framed content
  • It uses attachToShadows: true for change, acknowledging modern component models

Enable these where your UI architecture needs it, however validate performance impact and whether you’ve excluded noisy / third-party frames first.

DOM Capture

DOM capture is the biggest driver of visual replay fidelity in the UIC config, it is enabled and uses diffs by default. It should be tuned to define when and how much the DOM captures

Baseline snapshot strategy

The UIC configuration by default captures:

  • A full DOM on load after 1500ms.
  • Snapshots on click and change.

  • A special rule: after clicking radio/checkbox, wait 100ms to capture the post-update state.

  • Identify which visitor actions cause DOM changes that must appear in replay (for example, expanding accordions, validation errors, dynamic pricing).

  • Ensure those actions are included as snapshot triggers (click/change are good defaults).
  • For controls with asynchronous UI updates (checkboxes, radios, toggles), add a small delay trigger like the file does to avoid capturing “pre-change” DOM.

Payload size

The config uses guardrails to control payload size without destroying fidelity.

  • maxMutations: 300 (too many mutations = capture full DOM instead of diff)
  • maxLength: 10000000 (oversized snapshots won’t be sent)
  • removeBase64: 50000 (strip large base64 images)

  • captureStyle: true and keepImports: true (retain CSS sources for visual fidelity)

  • If replays look “wrong,” missing CSS is a common culprit—so keep style/import capture as this file does.

  • If capture fails due to payload size, reduce base64 thresholds and refine triggers rather than disabling DOM capture altogether.
  • Watch for pages that exceed maxLength, those will silently drop snapshots and degrade replay.

Privacy and compliance

This config illustrates two privacy levers:

  1. Privacy allow/deny rules using targets and inversion (exclude: true)
  2. Privacy patterns that rewrite HTML via regex replacements (including targeted screenviews)

Your privacy posture

The UIC provides an inverted privacy intent (block everything, allow only targets) via exclude: true and a target whitelist such as #username. This can be used where privacy is a priority and a block first posture is required. Using specific targeting privacy can be reduced.

Thought process:

  • If you are in a regulated environment, start from “mask by default” and expose only what you need to understand journeys
  • If you are optimizing UX at scale, you may need to expose more DOM, but then privacy patterns must remove PII/PCI reliably

Using Privacy patterns

This UIC uses patterns to:

  • Replace large content regions on specific screenviews, and mask a user label on /
  • Normalize resource URLs (e.g., CSS link and contenthandler path) which can improve replay consistency

Thought process:

  • Apply regex DOM rewriting only where necessary; the config itself warns that regex on HTML can have performance impact
  • Prefer screenview-scoped patterns (as shown) so you don’t incur cost everywhere
  • Validate per browser: this config disables privacyPatterns on IE11—if you do that, ensure the remaining privacy settings still protect sensitive data

Session stitching

To ensure you can reliably reconstruct visitor journeys, the UIC config supports session ID derivation via query param or cookie, and hashes the value.

  • Identify where your session identifier lives (cookie, URL parameter, or both).

Note

You can change the name of the cookie value or use a specific existing value

  • Configure precedence, the UIC states query name takes precedence over cookie name
  • Hash identifiers when possible to reduce exposure while maintaining join capability (sessionValueNeedsHashing: true)
  • Align inactivity timeout 25 minutes by default with your application session timeout to avoid fragmented or over-merged replays

Delivery reliability

The UIC config file emphasises delivery mechanics using a queue with batching for maxEvents, timerInterval, maxSize and gzip encoding. It uses fetch by default, but has browser fallbacks for Firefox and IE.

  1. Validate endpoint URL correctness, the UIC default file shows a placeholder endpoint
  2. Decide on transport (fetch, beacon) based on your browser set; by default the UIC config sets useBeacon: false and useFetch: true, then overrides for problem browsers

Validate and prove

When aiming for maximum fidelity the UIC configuration should be tested with a repeatable test matrix, for example a golden journey.

Include areas such as:

  • Login (form fields + focus/blur + change)
  • Navigation (SPA route/hash changes, back/forward)
  • Dynamic UI (checkbox/radio toggles, modals, async validation) including the areas where delayed DOM capture is needed
  • Embedded content (iframes) if applicable
  • Mobile interactions (touchstart / touchend)

  • ...

  • Event fidelity: do you see the right events at the right time (click/change/scroll)?

  • Visual fidelity: does the DOM snapshot/diff reproduce the right state after each interaction (especially for dynamic controls and CSS fidelity)?

Tune and re-tune based on observed failures. For examples:

  • If UI changes aren’t reflected after click → add targeted delayed triggers (like the radio/checkbox rule)
  • If replays miss iframe content → ensure frame recursion and frame capture, and reconsider blacklists
  • If payloads drop → adjust snapshot frequency/targets and monitor maxLength impacts; keep gzip and size controls
  • If end-of-session events are missing = apply browser-specific unload transport overrides (like Firefox in the file)