How to Integrate Session Replay¶

Configuration¶

The default interval/cooldown values in the table apply to Canvas 2D. If the WebGL plugin does not explicitly configure these two items, it retains a more conservative GPU read-back pace to avoid amplifying readPixels cost by default.

The defaults in the table apply when the low, medium, or high string presets are not used. String presets replace quality, sampling, interval, cooldown, unchanged/failure backoff, and max-per-run simultaneously; explicit individual configuration items override the corresponding values from the preset. To change only image quality, pass a number between 0 and 1 to replayCanvasQuality. See the full matrix in the Canvas Recording Guide.

Canvas 2D recording configuration is available from SDK 3.3.0. WebGL Replay is available from SDK 3.3.7, requires the RUM main package version >= 3.3.7, and it is recommended that the WebGL plugin and the main package use the same SDK release version.

Enabling Session Replay¶

Using your previous SDK integration method, upgrade the NPM package to version > 3.0.0, or replace the CDN link with https://static.truewatch.com/browser-sdk/v3/dataflux-rum.js. The SDK does not automatically collect Session Replay Record data after init(); you need to call startSessionReplayRecording to start data collection. This is useful for capturing Session Replay Records only under specific conditions, for example:

// Collect data only after the user logs in
if (user.isLogin()) {
  DATAFLUX_RUM.startSessionReplayRecording()
}

To stop collecting Session Replay data, call stopSessionReplayRecording().

NPM¶

Import the @truewatchtech/browser-rum package and ensure its version > 3.0.0. To start recording, call datafluxRum.startSessionReplayRecording() after initialization.

import { datafluxRum } from '@truewatchtech/browser-rum'

datafluxRum.init({
  applicationId: '<DATAFLUX_APPLICATION_ID>',
  datakitOrigin: '<DATAKIT ORIGIN>',
  service: 'browser',
  env: 'production',
  version: '1.0.0',
  sessionSampleRate: 100,
  sessionReplaySampleRate: 70,
  trackInteractions: true,
})

datafluxRum.startSessionReplayRecording()

CDN¶

Replace the CDN URL https://static.truewatch.com/browser-sdk/v2/dataflux-rum.js with https://static.truewatch.com/browser-sdk/v3/dataflux-rum.js, and call DATAFLUX_RUM.startSessionReplayRecording() after DATAFLUX_RUM.init().

<script
src="https://static.truewatch.com/browser-sdk/v3/dataflux-rum.js"
type="text/javascript"
></script>
<script>
window.DATAFLUX_RUM &&
window.DATAFLUX_RUM.init({
    applicationId: '<DATAFLUX_APPLICATION_ID>',
    datakitOrigin: '<DATAKIT ORIGIN>',
    service: 'browser',
    env: 'production',
    version: '1.0.0',
    sessionSampleRate: 100,
    sessionReplaySampleRate: 100,
    trackInteractions: true,
})

window.DATAFLUX_RUM && window.DATAFLUX_RUM.startSessionReplayRecording()
</script>

How to Collect Only Error-Related Session Replay Data (SDK version ≥3.2.19)¶

Feature Description¶

When an error occurs on the page, the SDK automatically performs the following:

1. Retrospective Capture: Records a complete page snapshot from 1 minute before the error.
2. Continuous Recording: Continues recording from the moment of the error until the session ends.
3. Intelligent Compensation: Ensures full coverage of error scenarios through an independent sampling channel.

Configuration Example¶

<script
  src="https://static.truewatch.com/browser-sdk/v3/dataflux-rum.js"
  type="text/javascript"
></script>
<script>
// Initialize the SDK core configuration
window.DATAFLUX_RUM && window.DATAFLUX_RUM.init({
   // Required parameters
   applicationId: '<DATAFLUX_APPLICATION_ID>',
   datakitOrigin: '<DATAKIT_ORIGIN>',

   // Environment identifiers
   service: 'browser',
   env: 'production',
   version: '1.0.0',

   // Sampling strategy configuration
   sessionSampleRate: 100,               // Full base session capture (100%)
   sessionReplaySampleRate: 0,            // Disable regular replay sampling
   sessionReplayOnErrorSampleRate: 100,   // 100% sampling for error scenarios

   // Auxiliary features
   trackInteractions: true                // Enable user interaction tracking
});

// Forcefully enable the replay engine (must be called)
window.DATAFLUX_RUM && window.DATAFLUX_RUM.startSessionReplayRecording();
</script>

Canvas Recording Notes¶

Canvas recording does not take effect automatically by default. To make it work, at least the following conditions must all be met:

• Session Replay sampling is active – i.e., sessionReplaySampleRate > 0, or sessionReplayOnErrorSampleRate is hit.
• startSessionReplayRecording() has been called.
• replayCanvasEnabled: true is configured.
• The target element is a Canvas 2D; WebGL/WebGL2 additionally requires the WebGL Replay plugin registration.

If using manual mode, your application code must also explicitly call:

datafluxRum.snapshotCanvas(canvas)

Which Canvas-Related Parameters Should Be Considered Required¶

When integrating, treat the following items as required:

• sessionReplaySampleRate
• replayCanvasEnabled: true
• replayCanvasMode

If replayCanvasMode === 'auto', explicitly configure:

• replayCanvasSampling
• Positive integer: selects the automatic snapshot path; starting from 2 is recommended.
• 'all': higher-fidelity automatic recording, suitable for pages that prioritize restoring the drawing process.
• replayCanvasAutoInterval
• Controls the scheduling interval for automatic snapshots; the numeric sampling value itself does not control Canvas 2D frequency.

Three Recommended Minimal Configurations¶

Manual Recording¶

datafluxRum.init({
  applicationId: 'Your Application ID',
  datakitOrigin: '<DataKit Domain Name or IP>',
  sessionReplaySampleRate: 100,

  replayCanvasEnabled: true,
  replayCanvasMode: 'manual',
  replayCanvasQuality: 'medium'
})

datafluxRum.startSessionReplayRecording()

Automatic Snapshot¶

datafluxRum.init({
  applicationId: 'Your Application ID',
  datakitOrigin: '<DataKit Domain Name or IP>',
  sessionReplaySampleRate: 100,

  replayCanvasEnabled: true,
  replayCanvasMode: 'auto',
  replayCanvasSampling: 2,
  replayCanvasAutoInterval: 250,
  replayCanvasQuality: 'medium'
})

datafluxRum.startSessionReplayRecording()

Automatic High-Fidelity Recording¶

datafluxRum.init({
  applicationId: 'Your Application ID',
  datakitOrigin: '<DataKit Domain Name or IP>',
  sessionReplaySampleRate: 100,

  replayCanvasEnabled: true,
  replayCanvasMode: 'auto',
  replayCanvasSampling: 'all',
  replayCanvasQuality: 'medium'
})

datafluxRum.startSessionReplayRecording()

CSP Scenarios¶

If the site's CSP does not allow worker-src blob:, you can configure:

datafluxRum.init({
  // ...
  replayCanvasWorkerUrl: '/canvas-worker.js'
})

Note:

• replayCanvasWorkerUrl only affects canvas snapshot encoding.
• It does not replace workerUrl.
• Not all canvas frames use the canvas worker.

For more details, see CSP Security Policy.

For the full capability boundaries, optional plugin integration, and performance recommendations for Canvas 2D, WebGL/WebGL2, see the Canvas Recording Guide. The WebGL plugin must use the same SDK version as the RUM main package, and RUM.init() must be completed before the WebGL engine creates a context or caches drawing methods.

Wujie Micro-Frontend and Open Shadow DOM¶

Starting from RUM SDK 3.3.11, Session Replay can recognize native form elements and Canvas created by an iframe JavaScript realm and then mounted into an open ShadowRoot on the current page. This structure is common in Wujie micro-frontends: the elements retain the iframe realm's prototype but are already part of the accessible Shadow DOM content on the current page.

• User input and change events for input, textarea, select can be included in replays; after the element enters the Replay DOM, modifications to value, checked, selectedIndex properties via JavaScript can also be recorded.
• The DOM structure within an open ShadowRoot and subsequent DOM changes can be included in replays.
• Canvas still requires replayCanvasEnabled: true and follows the capture modes and budgets described earlier in this page. When replayCanvasSampling: 'all' enables Canvas command capture, Canvas in the current page realm continues to capture drawing commands, while cross-iframe realm Canvas automatically falls back to bitmap snapshots.
• Shadow DOM with mode: 'closed', and content still inside the iframe's internal document, are not within this support scope.

The term "iframe realm" here only indicates that the element was created by the iframe's JavaScript environment; it does not mean the SDK will record the iframe's internal document. Only content that has been mounted into an accessible open ShadowRoot on the current page will enter Session Replay as regular page DOM.

Notes¶

Some HTML Elements Are Not Visible During Playback¶

Session Replay does not record the internal document of an iframe, nor does it capture media content from video or audio; the elements themselves and the play/pause state of media can still be recorded. The current implementation supports accessible open Shadow DOM; Shadow DOM with mode: 'closed' cannot be guaranteed to be captured. Complete recording of Web Components depends on whether the Shadow Root is open and the types of content used internally.

FONT or IMG Cannot Be Rendered Correctly¶

Session Replay is not a video; it reconstructs an iframe based on DOM snapshots. Therefore, replay depends on various static resources of the page: fonts and images.

Static resources may be unavailable during replay due to the following:

• The resource no longer exists (e.g., it was part of a previous deployment).
• The resource is not accessible (e.g., it requires authentication or is only available from an internal network).

• The resource is blocked by the browser due to CORS (typically web fonts).

• During replay, the iframe runs in the sandbox environment of truewatch.com. If some static resources are not authorized for that specific domain, your browser will block the request.

• Allow truewatch.com to access any font or image static resources your site depends on by setting the Access-Control-Allow-Origin header, ensuring these resources are available for replay.

For more information, see Cross-Origin Resource Sharing.

CSS Styles Not Applied Correctly or Mouse Hover Events Not Replayed¶

Unlike fonts and images, Session Replay Record attempts to use the CSSStyleSheet interface to bundle applied CSS rules as part of the recording data. If that fails, it falls back to recording the CSS file link.

For correct hover support, CSS rules must be accessible via the CSSStyleSheet interface.

If the stylesheet file is hosted on a different domain than the web page, access to CSS rules is subject to the browser's cross-origin security checks. You must specify that the browser loads the stylesheet using the crossorigin attribute and CORS.

For example, if your application is on the example.com domain and depends on a CSS file on assets.example.com via a <link> element, set the crossorigin attribute to anonymous:

<link rel="stylesheet" crossorigin="anonymous"
      href="https://assets.example.com/style.css">

Additionally, authorize the example.com domain on assets.example.com. This allows the resource file to be loaded correctly by setting the Access-Control-Allow-Origin header.

Further Reading¶