Web Application Setup¶

After completing the configuration on this page, the Browser RUM SDK automatically collects page Views, resource requests, frontend errors, and user actions, and reports the data to TrueWatch.

Choose an Integration Path¶

First, select the entry point based on the application type to avoid duplicate View configurations or accessing browser APIs during server-side rendering.

Prepare Integration Information¶

1. Go to RUM > Application List > New Application > Web.
2. Create an application and obtain the applicationId, env, version, and other configurations generated by the console.

3. Choose the data reporting method:

4. Public OpenWay: Obtain site and clientToken; no need to deploy DataKit.

5. DataKit Direct Connection: Prepare datakitOrigin; DataKit must enable the RUM collector and be configured to be publicly accessible with the IP geolocation database installed.

Reporting Method¶

{
  applicationId: "<APPLICATION_ID>",
  datakitOrigin: "<DATAKIT_ORIGIN>"
}

{
  applicationId: "<APPLICATION_ID>",
  site: "<PUBLIC_OPENWAY_URL>",
  clientToken: "<CLIENT_TOKEN>"
}

Integrate the SDK¶

NPM Setup¶

Install and import the SDK in the frontend project:

npm install @truewatchtech/browser-rum @truewatchtech/browser-core

Initialize the SDK in the project:

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

datafluxRum.init({
  applicationId: "<APPLICATION_ID>",
  site: "<PUBLIC_OPENWAY_URL>",
  clientToken: "<CLIENT_TOKEN>",
  service: "web-app",
  env: "production",
  version: "1.0.0",
  sessionSampleRate: 100,
  trackUserInteractions: true
})

CDN Synchronous Loading¶

Add the script to the HTML file:

<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: "<APPLICATION_ID>",
      site: "<PUBLIC_OPENWAY_URL>",
      clientToken: "<CLIENT_TOKEN>",
      service: "web-app",
      env: "production",
      version: "1.0.0",
      sessionSampleRate: 100,
      trackUserInteractions: true
    })
</script>

CDN Asynchronous Loading¶

Add the script to the HTML file:

<script>
  ;(function (h, o, u, n, d) {
    h = h[d] = h[d] || {
      q: [],
      onReady: function (c) {
        h.q.push(c)
      },
    }
    d = o.createElement(u)
    d.async = 1
    d.src = n
    n = o.getElementsByTagName(u)[0]
    n.parentNode.insertBefore(d, n)
  })(
    window,
    document,
    "script",
    "https://static.truewatch.com/browser-sdk/v3/dataflux-rum.js",
    "DATAFLUX_RUM"
  )
  DATAFLUX_RUM.onReady(function () {
    DATAFLUX_RUM.init({
      applicationId: "<APPLICATION_ID>",
      site: "<PUBLIC_OPENWAY_URL>",
      clientToken: "<CLIENT_TOKEN>",
      service: "web-app",
      env: "production",
      version: "1.0.0",
      sessionSampleRate: 100,
      trackUserInteractions: true
    })
  })
</script>

The examples above use the Public OpenWay. For DataKit direct connection, remove site and clientToken and configure datakitOrigin instead.

Slim RUM SDK¶

The Slim RUM SDK is available starting from SDK version 3.3.3. It uses the same initialization method as the full version and supports standard RUM capabilities such as View, Resource, Long Task, Error, Action, user and global context, custom events, and distributed tracing. It is suitable for applications that do not need page recording and want to reduce frontend bundle size.

NPM Setup¶

Replace the standard RUM package with the slim package of the same version:

npm install @truewatchtech/browser-rum-slim @truewatchtech/browser-core

import { truewatchRum } from "@truewatchtech/browser-rum-slim"

truewatchRum.init({
  applicationId: "<APPLICATION_ID>",
  site: "<PUBLIC_OPENWAY_URL>",
  clientToken: "<CLIENT_TOKEN>",
  service: "web-app",
  env: "production",
  version: "1.0.0",
  sessionSampleRate: 100,
  trackUserInteractions: true
})

CDN Setup¶

The synchronous or asynchronous loading method is the same as the full version; just replace the script file name with the slim version. Below is a synchronous loading example:

<script
  src="https://static.truewatch.com/browser-sdk/v3/truewatch-rum-slim.js"
  type="text/javascript"
></script>
<script>
  window.TRUEWATCH_RUM &&
    window.TRUEWATCH_RUM.init({
      applicationId: "<APPLICATION_ID>",
      site: "<PUBLIC_OPENWAY_URL>",
      clientToken: "<CLIENT_TOKEN>",
      service: "web-app",
      env: "production",
      version: "1.0.0",
      sessionSampleRate: 100,
      trackUserInteractions: true
    })
</script>

Capability Differences from the Full Version¶

The slim version does not include the following capabilities:

• Session Replay, and the recording APIs startSessionReplayRecording(), stopSessionReplayRecording(), isRecording();
• Canvas 2D, WebGL/WebGL2 recording, and Canvas APIs such as snapshotCanvas();
• compressIntakeRequests upload compression and its associated Worker.

The slim version forces sessionReplaySampleRate, sessionReplayOnErrorSampleRate, and replayCanvasEnabled to be disabled, and forces compressIntakeRequests to false. Do not pass these configurations during integration, and do not set workerUrl or replayCanvasWorkerUrl. If you later need session replay, Canvas recording, or compressed upload, switch the NPM package or CDN file back to the full version; other basic initialization parameters can be reused.

Verify Integration¶

1. Open a page that has integrated the SDK and perform a page navigation, a button click, and an API request.
2. In the browser developer tools Network tab, filter for /v1/write/rum and confirm successful reporting requests.
3. Check the Console for initialization errors such as Application ID is not configured or datakitOrigin or site is not configured.
4. Go to RUM > Application List, open the corresponding Web application, filter by service, env, and version in the Explorer, and confirm that View, Resource, or Action data exists.

Common Optional Configurations¶

After basic data is confirmed successful, enable other capabilities as needed:

Tracing Configuration (Optional)¶

When using NPM + TypeScript, traceType must use the TraceType enum imported from the corresponding brand's browser-core package:

import { TraceType } from "@truewatchtech/browser-core"
import { datafluxRum } from "@truewatchtech/browser-rum"

datafluxRum.init({
  applicationId: "<APPLICATION_ID>",
  site: "<PUBLIC_OPENWAY_URL>",
  clientToken: "<CLIENT_TOKEN>",
  allowedTracingUrls: ["https://api.example.com"],
  traceType: TraceType.DDTRACE
})

The runtime value of TraceType.DDTRACE is still "ddtrace". CDN integration does not have module imports; use the corresponding runtime string when explicitly configuring. After enabling tracing, you also need to allow the corresponding Trace Header on the API server side. For details, refer to How APM Correlates with RUM.

If a regular session is not sampled but you still need to pass the Trace Header to the backend, you can explicitly enable allowTraceHeaderWithoutSession:

datafluxRum.init({
  applicationId: "<APPLICATION_ID>",
  site: "<PUBLIC_OPENWAY_URL>",
  clientToken: "<CLIENT_TOKEN>",
  sessionSampleRate: 0,
  sessionOnErrorSampleRate: 0,
  allowedTracingUrls: ["https://api.example.com"],
  allowTraceHeaderWithoutSession: true
})

When enabled, the SDK still injects Trace Headers only for XHR and Fetch requests that match allowedTracingUrls. This configuration does not create or force-enable a RUM Session, nor does it report View, Error, Resource, or Action data for unsampled sessions. The API service must still allow the request headers corresponding to the selected traceType; cross-origin requests also require proper CORS configuration.

Parameter Configuration¶

Initialization Parameters¶

When not using the low, medium, high string presets, the Canvas auto-scheduling baseline is: sampling 2, target interval 250 ms per Canvas, cooldown 250 ms, unchanged backoff 3000 ms, failure backoff 5000 ms, and a maximum of 2 Canvases per round. String presets replace these budgets and encoding quality simultaneously. Multiple Canvases are also subject to fair rotation and global collection budget constraints. Explicit per-parameter configurations override the corresponding values in the preset. For the full preset matrix, see the Canvas Recording Manual.

The high-frequency scheduling baseline above is for Canvas 2D. When the WebGL plugin does not have explicit interval/cooldown configurations, it continues to use a more conservative GPU readback pace. Explicit per-parameter configurations override these separately.

site Parameter Handling¶

Runtime Session Control¶

RUM SDK 3.3.6 introduces startSession(). Calling it immediately ends the current session and starts a new session according to the current sampling configuration, without waiting for the next user interaction:

datafluxRum.startSession()

You can also override the runtime sessionSampleRate:

datafluxRum.startSession({
  sessionSampleRate: 100,
})

The sampling rate must be between 0 and 100. The override value is used for this and subsequent auto-renewed sessions. Both the full RUM package and the slim RUM package support this API. For detailed semantics and use cases, see Runtime Restart Session.

Enable Advanced Capabilities as Needed¶

Collect Only Error Session Events¶

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

• Continuous recording: From the moment the error is triggered, the SDK records the full lifecycle data of the session.
• Precise compensation: Through an independent sampling channel, ensures no error scenarios are missed.

Configuration¶

window.DATAFLUX_RUM &&
  window.DATAFLUX_RUM.init({
    applicationId: "<APPLICATION_ID>",
    site: "<PUBLIC_OPENWAY_URL>",
    clientToken: "<CLIENT_TOKEN>",
    sessionSampleRate: 0,
    sessionOnErrorSampleRate: 100
  })

The example above uses the Public OpenWay. For DataKit direct connection, replace the reporting address fields as per the basic integration example.

Data Compression¶

When collecting a large number of static resources (e.g., JS, CSS, images) and enabling full collection, the SDK may generate a large amount of data after initialization, causing request queuing and potentially impacting the application thread state.

Setting compressIntakeRequests: true enables the SDK to compress reported data using deflate in a Web Worker, reducing request size and count.

Configuration Example¶

window.DATAFLUX_RUM &&
  window.DATAFLUX_RUM.init({
    applicationId: "<APPLICATION_ID>",
    site: "<PUBLIC_OPENWAY_URL>",
    clientToken: "<CLIENT_TOKEN>",
    compressIntakeRequests: true
  })

Notes¶

1. Data compression logic is executed in a Web Worker. If CSP security policies are enabled, you must allow blob: in the worker-src directive. For more information, see CSP Security Policy.
2. The SDK supports specifying a self-hosted worker URL via the workerUrl configuration option.
3. SDK version must be >= 3.2 to use this feature.

Custom Data and Events¶

This basic integration page does not repeat all common APIs. Navigate to the corresponding page based on your business goal to see CDN, NPM, and full parameter examples:

• Tracking User Actions: Automatically collect clicks, define Action names, add custom Actions.
• Custom User Identification: Set user after login, clear user on logout or account switch.
• Global Context: Add stable business dimensions to all subsequent RUM events.
• Add Custom Action: Record business operations that cannot be expressed through page clicks.
• Report Custom Error: Report already caught or business-identified exceptions.

Web Session Replay¶

Start Recording¶

After SDK initialization, call the startSessionReplayRecording() method to start session replay recording. You can start recording under specific conditions, such as after user login. Start Session Recording.

Collect Only Error-Related Session Replay Data¶

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

• Retroactive capture: Records a full page snapshot of the 1 minute before the error.
• Continuous recording: Continues recording from the error occurrence until the session ends.
• Intelligent compensation: Ensures no error scenarios are missed through an independent sampling channel.

Configuration Example¶

window.DATAFLUX_RUM &&
  window.DATAFLUX_RUM.init({
    applicationId: "<APPLICATION_ID>",
    site: "<PUBLIC_OPENWAY_URL>",
    clientToken: "<CLIENT_TOKEN>",
    sessionSampleRate: 100,
    sessionReplaySampleRate: 0,
    sessionReplayOnErrorSampleRate: 100
  })

window.DATAFLUX_RUM && window.DATAFLUX_RUM.startSessionReplayRecording()

Notes¶

• Session Replay does not record iframe, video, or audio playback content. Canvas is not captured by default and requires separate configuration of replayCanvasEnabled. WebGL/WebGL2 recording is available from SDK 3.3.7, requires RUM main package version >= 3.3.7, and an additional compatible browser-rum-webgl plugin must be installed and registered. It is recommended to use the same SDK release version for the plugin and the main package. For details, see Canvas Recording Manual.
• To ensure static resources (e.g., fonts, images) are accessible during replay, you may need to configure CORS policies.
• Ensure that CSS rules are accessible via the CSSStyleSheet interface to support CSS styles and hover events.

Verify Recording Status¶

Call window.DATAFLUX_RUM.isRecording() to check whether the current page is recording, and confirm in the session replay viewer that the corresponding session has generated replay data. In production, adjust sessionReplaySampleRate according to business requirements.