Web Application Access¶

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 Access Path¶

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

Prepare Access Information¶

1. Go to RUM > Application List > Create Application > Web.
2. Create the 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 Methods¶

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

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

Integrate the SDK¶

NPM Access¶

Install and import the SDK in the frontend project:

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

Initialize the SDK in the 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 script in the 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 script in 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.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 examples above use Public OpenWay. When using DataKit direct connection, remove site and clientToken, and configure datakitOrigin instead.

Verify Access¶

1. Open the page where the SDK has been integrated, 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 verify that a successful reporting request exists.
3. Check the Console to ensure 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, filter by service, env, version in the explorer, and confirm that View, Resource, or Action data exists.

Common Optional Configurations¶

After confirming basic data is received, enable additional capabilities as needed:

Trace Configuration (Optional)¶

When using 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 is still "ddtrace". CDN access has no module import; use the corresponding runtime string when explicitly configuring. After enabling traces, the API server must also allow the corresponding Trace headers. For details, refer to 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 will still inject Trace headers only for XHR and Fetch requests that match allowedTracingUrls. This configuration does not create or force-enable a RUM session, and does not 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, or high string presets, the Canvas automatic scheduling baseline is: sampling 2, target interval 250 ms per Canvas, cooldown 250 ms, unchanged backoff 3000 ms, failure backoff 5000 ms, maximum of 2 Canvases per round. The string presets replace these budgets and encoding quality simultaneously; multiple Canvases are also subject to fair rotation and global collection budget constraints. Explicit individual parameter values override the corresponding values from the preset. The complete preset matrix is available in the Canvas Recording Guide.

The above high-frequency scheduling baseline applies to Canvas 2D. When the WebGL plugin does not explicitly configure interval/cooldown, it continues to use a more conservative GPU read-back rhythm; explicit individual parameters override them separately.

site Parameter Handling¶

Runtime Session Control¶

RUM SDK 3.3.6 introduces startSession(). Calling this method 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. This override value applies to the current and subsequent automatically renewed sessions. Both the full RUM package and the lean RUM package support this API. For detailed semantics and usage scenarios, see Restart Session at Runtime.

Enable Advanced Capabilities on Demand¶

Collect Only Error Session Events¶

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

• Continuous recording: From the moment the error triggers, the session's full lifecycle data is recorded.
• Precise compensation: Through an independent sampling channel, ensuring no error scenarios are missed.

Configuration Example¶

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

The above example uses Public OpenWay. When using DataKit direct connection, replace the reporting address fields according to the basic access example.

Data Compression¶

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

Setting compressIntakeRequests: true enables the SDK to use deflate compression in a Web Worker to compress the reported data, reducing request payload sizes 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
  })

Important Notes¶

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

Custom Data and Events¶

The basic access page no longer reproduces all common APIs. Navigate to the corresponding page based on the business goal to get CDN, NPM, and full parameter examples:

• Tracking User Actions: Automatically collect clicks, define Action names, add custom Actions.
• Custom User Identity: Set the user after login, clear the 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 exceptions that have been caught or actively identified by the business.

Web Session Replay¶

Start Recording¶

After SDK initialization, call the startSessionReplayRecording() method to start session replay recording. You can choose to start it 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 will automatically:

• Retroactive capture: Records the full page snapshot from the 1 minute before the error.
• Continuous recording: Continues recording from the moment the error occurs until the session ends.
• Intelligent compensation: Ensures error scenarios are not 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()

Important Notes¶

• Session Replay does not record the playback of iframes, videos, or audio; Canvas is not captured by default and requires separate configuration of replayCanvasEnabled. WebGL/WebGL2 is available from SDK 3.3.7, requires the RUM main package version >= 3.3.7, and also requires installing and registering a compatible browser-rum-webgl plugin; it is recommended to use the same SDK release version for the plugin and the main package. See Canvas Recording Guide for details.
• To ensure normal access to static resources (e.g., fonts, images) during replay, you may need to configure CORS policies.
• Ensure that CSS rules are accessible via the CSSStyleSheet interface to support CSS styles and mouse hover events.

Verify Recording Status¶

Call window.DATAFLUX_RUM.isRecording() to check if the current page is recording, and confirm in the Session Replay explorer that the corresponding session has produced replay data. In production, adjust sessionReplaySampleRate according to business requirements.