How to Integrate Session Replay¶

Configuration¶

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

The defaults in the table apply when you do not use the low, medium, or high string presets. String presets override quality, sampling, interval, cooldown, unchanged/failure backoff, and max-per-run simultaneously. Explicitly configuring a single item overrides the corresponding value from the preset. To change only the 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 and requires the RUM main package version >= 3.3.7. It is recommended to use the same SDK release version for the WebGL plugin and the main package.

Enabling Session Replay¶

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

// Only collect data 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 is > 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 original CDN URL https://static.truewatch.com/browser-sdk/v2/dataflux-rum.js with https://static.truewatch.com/browser-sdk/v3/dataflux-rum.js, and after executing DATAFLUX_RUM.init(), call DATAFLUX_RUM.startSessionReplayRecording().

<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 collection: Records a complete page snapshot for 1 minute before the error occurs.
2. Continuous recording: Continues recording from the moment of the error until the session ends.
3. Intelligent compensation: Ensures complete coverage of error scenarios through a dedicated sampling channel.

Configuration Example¶

<script
  src="https://static.truewatch.com/browser-sdk/v3/dataflux-rum.js"
  type="text/javascript"
></script>
<script>
// Initialize 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 collection (100%)
   sessionReplaySampleRate: 0,       // Disable regular replay sampling
   sessionReplayOnErrorSampleRate: 100, // 100% sampling for error scenarios

   // Supplementary features
   trackInteractions: true          // Enable user behavior tracking
});

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

Canvas Recording Notes¶

Canvas recording is not enabled by default. To make it work, at least the following conditions must be met simultaneously:

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

If using manual mode, the business code must explicitly call:

datafluxRum.snapshotCanvas(canvas)

Which Canvas-Related Parameters Should Be Considered Required¶

In practice, consider the following items as required:

• sessionReplaySampleRate
• replayCanvasEnabled: true
• replayCanvasMode

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

• replayCanvasSampling
• Positive number: selects the automatic snapshot path; starting from 2 is recommended.
• 'all': higher-fidelity automatic recording, suitable for pages that emphasize drawing process restoration.
• 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 complete capabilities of Canvas 2D, WebGL/WebGL2, optional plugin integration, and performance recommendations, refer to the Canvas Recording Guide. The WebGL plugin must use the same SDK version as the RUM main package, and the RUM init() must be completed before the WebGL engine creates a context or caches drawing methods.

Important Notes¶

Certain HTML Elements Are Not Visible During Playback¶

Session Replay does not support the following HTML elements: iframe, video, audio. Session Replay does not support Web Components and Shadow DOM.

FONT or IMG Are Not Rendered Correctly¶

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

Static resources may not be available during replay for the following reasons:

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

• The static 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 certain 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 website depends on by setting the Access-Control-Allow-Origin header, ensuring these resources can be loaded for replay.

For more information, refer to Cross-Origin Resource Sharing.

CSS Styles Not Applied Correctly or Hover Events Not Replayed¶

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

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

If style files are hosted on a different domain than the webpage, access to CSS rules is subject to the browser's cross-origin security checks. You must specify that the browser load the style file using the crossorigin attribute with CORS.

For example, if your application is on the example.com domain and relies 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 properly loaded by setting the Access-Control-Allow-Origin header.

Further Reading¶