How to Integrate Session Replay¶

Configuration¶

Enable Session Replay¶

Replace the NPM package with version > 3.0.0 via your previous SDK introduction method, or replace the original CDN link with https://static.truewatch.com/browser-sdk/v3/dataflux-rum.js. After SDK initialization init(), Session Replay Record data is not automatically collected; 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¶

Introduce the @cloudcare/browser-rum package, and ensure 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 Collection of Only Error-Related Session Replay Data (SDK Version Requirement ≥3.2.19)¶

Feature Description¶

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

1. Backtracking Collection: Record a complete page snapshot from 1 minute before the error occurred
2. Continuous Recording: Continue recording from the moment the error occurs until the session ends
3. Intelligent Compensation: Ensure 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 base 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 call)
window.DATAFLUX_RUM && window.DATAFLUX_RUM.startSessionReplayRecording();
</script>

Notes¶

Certain HTML Elements Are Invisible During Playback¶

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

FONT or IMG Cannot Be Rendered Correctly¶

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

Static resources may be unavailable during playback 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, it may require authentication, or the resource may only be accessible from an internal network.
• The static resource is blocked by the browser due to CORS (often web fonts).
• Since playback is based on the truewatch.com sandbox environment corresponding to the iframe, if certain static resources are not authorized for a specific domain name, your browser will block the request;
• Allow truewatch.com to access any font or image static resources that your website relies on through the Access-Control-Allow-Origin header to ensure these resources can be accessed for playback.

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

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

Unlike fonts and images, Session Replay Record attempts to utilize the CSSStyleSheet interface to bundle the various CSS rules applied as part of the recorded data. If it cannot be executed, it falls back to recording the links to the CSS files.

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

If the style file is hosted on a different domain than the web page, access to the CSS rules will be subject to the browser's cross-origin security checks, and the browser must be instructed to load the style file utilizing CORS using 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 be loaded correctly by setting the Access-Control-Allow-Origin header.

Further Reading¶