Web Application Integration¶

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 Guance.

Choose an Integration Path¶

First, choose an entry point based on the application type to avoid configuring Views twice or accessing browser APIs during server-side rendering.

Prepare Integration Information¶

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

3. Choose the data ingestion method:

4. Public OpenWay: Obtain site and clientToken; no DataKit deployment is required.

5. DataKit direct connection: Prepare datakitOrigin; DataKit needs the RUM collector enabled, and must be configured to be publicly accessible with the IP geolocation database installed.

Ingestion Method¶

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

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

Integrate the SDK¶

NPM Integration¶

Install and import the SDK in your frontend project:

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

Initialize the SDK in your project:

import { datafluxRum } from "@cloudcare/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 following script to your HTML file:

<script
  src="https://static.guance.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 following script to your 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.guance.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 example above uses Public OpenWay. For DataKit direct connection, remove site and clientToken and configure datakitOrigin instead.

Slim RUM SDK¶

The slim version has been available since RUM SDK 3.3.3. It uses the same initialization approach 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 Integration¶

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

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

import { datafluxRum } from "@cloudcare/browser-rum-slim"

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 Integration¶

Synchronous and asynchronous loading are the same as with the full version; simply replace the script file name with the corresponding slim file. A synchronous loading example follows:

<script
  src="https://static.guance.com/browser-sdk/v3/dataflux-rum-slim.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>

Capability Differences from the Full Version¶

The slim version does not include the following capabilities:

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

The slim version forces sessionReplaySampleRate, sessionReplayOnErrorSampleRate, and replayCanvasEnabled off, and forces compressIntakeRequests to false. Do not pass these configurations when integrating, and you do not need to set workerUrl or replayCanvasWorkerUrl. If you later need Session Replay, Canvas recording, or compressed intake, switch the NPM package or CDN file back to the full version. Your other basic initialization parameters can continue to be used.

Verify the Integration¶

1. Open a page with the SDK integrated, and perform a page navigation, a button click, and an API request.
2. In the Network tab of the browser developer tools, filter for /v1/write/rum and confirm that a successful ingestion request exists.
3. Check the Console and confirm there are no 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, and in the Explorer filter by service, env, and version to confirm that View, Resource, or Action data exists.

Common Optional Configurations¶

After confirming that the basic data is successfully collected, enable other capabilities as needed:

Distributed Tracing Configuration (Optional)¶

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

import { TraceType } from "@cloudcare/browser-core"
import { datafluxRum } from "@cloudcare/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 remains "ddtrace". CDN integration does not involve module imports; when configuring explicitly, use the corresponding runtime string. After enabling distributed tracing, you also need to allow the corresponding Trace headers on your API server. For details, see How APM Correlates with RUM.

If a regular Session is not sampled but you still need to pass Trace headers 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 into 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 server still needs to allow the headers for the selected traceType; cross-origin requests also require correct CORS configuration.

Parameter Configuration¶

Initialization Parameters¶

When the low, medium, or high string presets are not used, the automatic scheduling baseline for Canvas is: sampling 2, a target interval of 250 ms per Canvas, cooldown 250 ms, unchanged backoff 3000 ms, failure backoff 5000 ms, and a maximum of 2 Canvases per run. String presets replace both these budgets and the encoding quality. Multiple Canvases are also subject to fair rotation and global collection budget limits. Explicit per-item configuration overrides the corresponding value in the preset. See the full preset matrix in Canvas Recording User Guide.

The high-frequency scheduling baseline above applies to Canvas 2D. When the WebGL plugin does not explicitly configure interval/cooldown, it continues to use a more conservative GPU readback cadence; only explicit per-item configuration overrides these individually.

site Parameter Handling¶

Runtime Session Control¶

RUM SDK 3.3.6 adds startSession(). When called, it immediately ends the current Session and restarts a Session according to the current sampling configuration, without waiting for the next user interaction:

datafluxRum.startSession()

You can also override the runtime sessionSampleRate at the same time:

datafluxRum.startSession({
  sessionSampleRate: 100,
})

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

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 full lifecycle data of the session is recorded.
• Precise compensation: an independent sampling channel ensures error scenarios are not 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 Public OpenWay. For DataKit direct connection, replace the ingestion URL fields with those from the basic integration example.

Data Compression¶

When collecting large numbers of static resources (such as JS, CSS, images, etc.) with full collection enabled, the SDK may generate a large amount of data after initialization, causing request backlog and potentially affecting the application thread state.

Setting compressIntakeRequests: true makes the SDK compress ingestion data using deflate in a Web Worker, reducing request size and the number of requests.

Configuration Example¶

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

Notes¶

1. The data compression logic runs in a Web Worker. If a CSP security policy is enabled, you need to allow blob: in worker-src. For more information, see CSP Security Policy Documentation.
2. The SDK supports specifying a self-hosted Worker URL through the workerUrl configuration option.
3. The SDK version used with this feature must be >= 3.2.

Custom Data and Events¶

The basic integration page no longer expands all public APIs. Go to the corresponding page for your business goal to get CDN, NPM, and full parameter examples:

• Track User Actions: automatically collect clicks, define Action names, and add custom Actions.
• Custom User Identification: set the user after login, and clear the user when logging out or switching accounts.
• Global Context: add stable business dimensions to all subsequent RUM events.
• Add Custom Actions: record business operations that cannot be expressed through page clicks.
• Report Custom Errors: report exceptions that have already been caught or are proactively identified by the business.

Web Session Replay¶

Enable Recording¶

After the SDK is initialized, call startSessionReplayRecording() to start Session Replay recording. You can choose to enable it under specific conditions, such as after user login. See Enable 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 complete page snapshot of the 1 minute before the error.
• Continuous recording: records continuously from the moment the error occurs until the session ends.
• Intelligent compensation: an independent sampling channel ensures error scenarios are not missed.

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 playback content inside iframes, videos, or audio. Canvas is not collected by default and requires replayCanvasEnabled to be configured separately. WebGL/WebGL2 is available from SDK 3.3.7, requires RUM main package version >= 3.3.7, and also requires installing and registering a compatible browser-rum-webgl plugin. It is recommended that the plugin and the main package use the same SDK release version. See Canvas Recording User Guide.
• To ensure static resources (such as fonts and images) can be accessed normally during replay, you may need to configure a CORS policy.
• Ensure that CSS rules are accessible through the CSSStyleSheet interface to support CSS styles and mouse 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 your business requirements.