Skip to content

Core Explanation

Introduction

The UIC's role is to ensure the visitors session data is captured and sent through to Discover, the DNCA or Collector (12.2.2 onwards). The UIC:

  1. Defines what user interactions and browser events are captured (clicks, changes, scrolls, touch, etc.).
  2. Controls sessionization (timeouts, session ID derivation).
  3. Enables DOM Capture with diffs to reconstruct the page for replay with high fidelity (full snapshots + incremental diffs, with browser fallbacks).
  4. Defines privacy masking rules that directly affect what is visible during replay.
  5. Controls transport/queuing/encoding so events reliably reach the endpoint without loss (batch sizes, intervals, gzip, fetch/unload behaviour, browser-specific overrides).

Session replay fidelity will depend mainly on:

  • Capturing the right events
  • Capturing the right DOM state at the right times
  • Successfully delivering the captured payload under real-world browser constraints

The core configuration of the UIC file starts at config = // DCX UIC CONFIGURATION BEGINS HERE, and is located towards the end of the file and described in the next section sequentially.

Config

“changeTarget” logic

The config calculates a changeTarget selector only for legacy IE using DCX.getFlavor() === "w3c" and DCX.utils.isLegacyIE.

With legacy IE (IE6–IE9 and IE9 legacy mode), change event propagation can be unreliable at the document level; therefore it becomes mandatory to attach change / focus / blur to specific form controls. Without this, form interactions may be missing, which causes session replay fidelity issues. For example the visitor changes a dropdown selection, however session replay never reflects it.

The changeTarget is used for replay event capture for change, focus, and blur with recurseFrames: true.

Session boundaries and stability

Configuration is required to understand where sessions start and end. Additionally, where the session remains continuous and coherent despite navigation, SPA route changes, visitor idle time, browser quirks, or transport failures. UIC configuration contains several parameters that directly control both and covered in the next section.

Parameter Value Why it matters
inactivityTimeout: 25 * 60 * 1000` 25 Minutes. Session replay depends on consistent session boundaries. If inactivity timeout is too short, sessions fragment (harder to understand journeys). Too long, unrelated journeys merge. The config explicitly notes it should be set “a few minutes lower than session timeout on the application.”
screenviewAutoDetect: true Enables automatic detection via URL path and hash. Replay needs correct “page boundaries” and navigation steps. Auto-detection improves coverage especially in SPAs where full page loads don’t happen.
framesBlacklist: ["#iframe1"] Blocks capture from a top-level iframe matching that selector. If critical UX happens inside an iframe, session replay fidelity will drop (missing DOM/events). If it’s a third-party iframe (chat, ads), blacklisting improves performance and reduces noise. This is a deliberate fidelity vs. scope trade-off.

Event capture configuration

The UIC config defines event capture in two places:

  • core.modules.*.events (what listeners are attached)
  • modules.replay.domCapture.triggers (when DOM snapshots/diffs happen)

Replay events (reconstructing actions)

core.modules.replay.events captures:

  • change (with target: changeTarget, recurseFrames: true, attachToShadows: true)
  • click (recurseFrames: true)
  • hashchange (target window)
  • focus, blur (target: changeTarget, recurseFrames)
  • load, unload, resize, scroll, orientationchange (target window)
  • touchstart, touchend (mobile interactions)

Replay requires a timeline of inputs + navigations + viewport changes. This mix covers: user intent (click/change), navigation transitions (hashchange/load/unload), and context (scroll/resize/orientation). recurseFrames: true increases fidelity for sites using iframes by capturing events inside them (except where blacklisted). attachToShadows: true on change events is a direct fidelity boost for web components / Shadow DOM form controls.

Usability events (heatmaps / behavioural signals)

core.modules.usability.events captures:

  • click, mousemove, mouseout, submit (all with recurseFrames: true except as shown).

These events are typically used for UX analysis, (hesitation, hover intent, form submission attempts). They don’t directly rebuild DOM state but enrich interpretation.

Note

modules.usability.hoverThreshold: 2000 is set in milliseconds (e.g. 2 seconds). This filters out incidental mouse movement so “hover” signals correlate better with attention, improving usefulness without flooding.

Performance events

core.modules.performance.events captures load and unload on window. Additionally, modules.performance.calculateRenderTime: true and a renderTimeThreshold: 600000.

Accurate replay analysis often pairs with performance context (“did rage clicks happen because the page hung?”). Render time capture supports that correlation.

DOM Capture

DOM Capture + diffs are enabled by default

  • services.domCapture.diffEnabled: true

  • modules.replay.domCapture.enabled: true

  • DOM capture provides the visual state necessary for session replay. Without snapshots /diffs, only event logs are captured and cannot reconstruct the website accurately. Diff capture reduces payload size by sending incremental changes, better for better scalability while maintaining fidelity.

Trigger strategy

Triggers are configured to happen on:

  1. load → fullDOMCapture: true, delay: 1500ms
  2. click on radio/checkbox → delay: 100ms
  3. click (general)
  4. change (general)

The full DOM on load provides a baseline snapshot (essential for session replay start-of-view fidelity). The 1500ms delay is a practical mitigation for late DOM rendering/hydration (common in SPAs), reducing the chance of capturing an incomplete initial state.

The 100ms delayed snapshot for radios/checkboxes assists with session replay fidelity on dynamic radio buttons & checkboxes. These controls often update UI state asynchronously (class toggles, conditional content). Capturing slightly after click increases the chance the DOM reflects the post-interaction state.

Capturing on click and change provides high coverage for interaction-driven UI updates (modal opens, validation messages, dynamic content).

Key DOM capture options

Options:

Parameter Value Why it matters
maxMutations 300 Switch to full DOM if threshold hit. A safety that prevent runaway diffs and oversized snapshots from killing performance or failing delivery, at the cost of potentially skipping some very large DOM states.
maxLength 10000000 Do not send snapshot if exceeded. A safety that prevent runaway diffs and oversized snapshots from killing performance or failing delivery, at the cost of potentially skipping some very large DOM states.
captureFrames true Include child iframes. Boosts fidelity where UI is embedded in iframes (balanced by framesBlacklist
captureShadowDOM false Is a potential fidelity gap for web-component-heavy sites: you can capture events in shadows (attachToShadows: true) but if the DOM snapshots don’t include shadow trees, replay may not render shadow-based UI faithfully.
sendShadodomScript false
captureStyle true In-line style tags. Materially improve visual accuracy (CSS availability is essential for replay looking like the original
keepImports true Link/import tags. materially improve visual accuracy (CSS availability is essential for replay looking like the original
removeComments true
removeScripts false Scripts retained
removeBase64 50000 Strip embedded base64 images above 50KB. Provides bandwidth control that can slightly reduce visual fidelity (missing large embedded images), but prevents massive payloads and improves delivery success.
captureJSS false (React/JSS capture disabled)

Transport & queuing

Transport & queuing: preventing data loss (fidelity depends on delivery)

Queue behaviour

Options:

Parameter Value Why it matters
asyncReqOnUnload true
useBeacon false
useFetch true Aligns with modern transport, but unload delivery is tricky across browsers—hence browser-specific overrides below.
maxEvents 20 See below
timerInterval 30000 See below
maxSize 300000` See below
encoder gzip reduces payload size, increasing probability of successful upload (especially with DOM snapshots).

Session replay fidelity collapses if events/snapshots are dropped. Batching (maxEvents, timerInterval, maxSize) aims to balance timeliness vs network overhead.

Encoding implementation

encoder.gzip.encode: "window.pako.gzip" and default encoding is set to gzip. This requires pako to be present globally (at the top of the UIC file). If window.pako is missing, payload encoding can fail—leading to dropped data and reduced replay completeness.

Browser-specific fallbacks

Firefox override

If user agent contains Firefox:

  • asyncReqOnUnload = false
  • useFetch = false

This is to address FETCH issues. Disabling fetch / unload async reduces the chance of partial or failed sends on navigation / close. Without this is is possible to lose the end of a session, which may contain significant events.

IE10 override

IE10 override with no DOM diff support.

document.documentMode === 10, useFetch = false, useBeacon = false, disable worker, and diffEnabled = false. Set's triggers change to: click on links/buttons, change, and load with 500ms delay.

IE10 is treated as not supporting diffs, so the UIC config explicitly turns diffs off and narrows capture triggers. This prevents broken session replays due to unsupported diff logic while still capturing enough snapshots to reconstruct.

IE11 override

document.documentMode === 11 disables fetch/beacon/worker and sets services.message.privacyPatterns = [] (disables privacy patterns)

This is a fidelity vs. compliance trade-off. Disabling privacy patterns may restore session replay stability / performance in IE11, but it can also expose data that would otherwise be masked (depending on other privacy rules).

Privacy & masking

Privacy & masking: directly influences what is visible in replay

Password masking

maskVisiblePasswords: false

If the website UI uses show password patterns (e.g. visible password fields), setting this false can allow sensitive values to appear in captured DOM/replay unless other privacy rules prevent it. This can increase session replay fidelity but raises data exposure risk.

Inverted privacy

  • exclude: true (comment notes inverse privacy: “block everything, add targets that needs to be exposed”)

Inverse privacy can heavily reduce session replay fidelity by masking most of the page, but is typically used for mask all compliance approach.

Session ID

Option:

  • sessionValueNeedsHashing: true
  • sessionQueryName: "sessionID", sessionQueryDelim: ";"
  • sessionCookieName: "jsessionid" (only used if query name not present)
  • sessionDataEnabled: false (do not expose session data to third-party scripts)

A stable session identifier is essential for session replay continuity and data attribution to a session. Supporting both query-param and cookie-based session ID derivation increases robustness. Hashing the session value reduces exposure of raw identifiers in captured data streams while preserving datta attribution. Disabling session data exposure reduces the risk that other scripts can read Discover session identifiers.

Rage clicks & menu clicks

Rage clicks are a strong signal of UX frustration or unresponsive UI. Pairing this data with session lists, reporting and ultimately focused session replay and usability overlays lets business users jump understand where to place resources.

Options:

Parameter Value
rageClicks.enabled true
clickInterval 4000
rageMin 5

When enabled a minimum of 5 clicks occurring within a 4 second timeframe will be recorded as a rage click.