How to Integrate Session Replay¶

Configuration¶

Enabling Session Replay¶

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

// Only collect operation data after user login
if (user.isLogin()) {
  DATAFLUX_RUM.startSessionReplayRecording()
}

If you need to stop Session Replay data collection, you can call stopSessionReplayRecording() to turn it off.

NPM¶

Import the @cloudcare/browser-rum package, ensuring the version of @cloudcare/browser-rum is > 3.0.0. To start recording, after initialization, please execute datafluxRum.startSessionReplayRecording().

import { datafluxRum } from '@cloudcare/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 address 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(), execute 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 Implement Session Replay Data Collection Only for Errors (SDK Version Requirement ≥3.2.19)¶

Feature Description¶

When a page error occurs, the SDK will automatically perform the following operations:

1. Retrospective Collection: Records a complete page snapshot from 1 minute before the error.
2. Continuous Recording: Continues recording from the moment the error occurs 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 SDK core configuration
window.DATAFLUX_RUM && window.DATAFLUX_RUM.init({
   // Required parameters
   applicationId: '<DATAFLUX_APPLICATION_ID>',
   datakitOrigin: '<DATAKIT_ORIGIN>',

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

   // Sampling strategy configuration
   sessionSampleRate: 100,          // Full basic session collection (100%)
   sessionReplaySampleRate: 0,       // Disable regular screen recording sampling
   sessionReplayOnErrorSampleRate: 100, // 100% sampling for error scenarios

   // Auxiliary functions
   trackInteractions: true          // Enable user behavior tracking
});

// Force enable the screen recording engine (must be called)
window.DATAFLUX_RUM && window.DATAFLUX_RUM.startSessionReplayRecording();
</script>

Canvas Recording Instructions¶

Canvas recording does not take effect automatically by default. For it to actually work, at least the following conditions must be met simultaneously:

• Session Replay has been sampled
• That is, sessionReplaySampleRate > 0, or hits sessionReplayOnErrorSampleRate
• startSessionReplayRecording() has been called
• replayCanvasEnabled: true has been configured
• The target element is indeed a 2d canvas

If using manual mode, it must also be actively called by the business code:

datafluxRum.snapshotCanvas(canvas)

Which Canvas-related Parameters Should Be Considered Required¶

During actual integration, it is recommended to consider the following items as required:

• sessionReplaySampleRate
• replayCanvasEnabled: true
• replayCanvasMode

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

• replayCanvasSampling
• 2: Recommended default value, suitable as a starting point for automatic snapshot on most pages.
• 1: More frequent automatic snapshots, higher cost.
• 'all': Higher-fidelity automatic recording, suitable for pages where drawing process restoration is more important.

Three Recommended Minimum 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,
  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 Scenario¶

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 will use the canvas worker.

For more details, see CSP Security Policy.

Notes¶

Certain HTML Elements Are Invisible 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 Cannot Render Correctly¶

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

Static resources may be unavailable during replay for the following reasons:

• The static resource no longer exists. For example, it was part of a previous deployment.
• The static resource is inaccessible. For example, authentication may be required, or the resource may only be accessible from an internal network.

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

• Since replay is based on the sandbox environment of the iframe corresponding to truewatch.com, if certain static resources are not authorized for specific domains, your browser will block the request.

• Ensure access to these resources for replay by allowing truewatch.com to access any font or image static resources your website depends on via the Access-Control-Allow-Origin header.

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 bundle the various CSS rules applied as part of the recorded data using the CSSStyleSheet interface. If this cannot be executed, it falls back to recording links to CSS files.

To get proper mouse hover support, CSS rules must be accessible via the CSSStyleSheet interface.

If style files are hosted on a different domain than the web page, access to CSS rules will be subject to the browser's cross-origin security checks, and you must specify the browser to load the style files using CORS with the crossorigin attribute.

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, the crossorigin attribute should be set to anonymous.

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

Additionally, authorize the example.com domain in assets.example.com. This allows resource files to load correctly by setting the Access-Control-Allow-Origin header.

Further Reading¶