Skip to content

Web Application Integration

By collecting metrics data from web applications, analyze application performance visually.

Prerequisites

Note

If you have already enabled the RUM Headless service, the prerequisites are automatically configured, and you can directly integrate the application.

Start Integration

  1. Go to User Access Monitoring > Create Application > Web;
  2. Enter the application name;
  3. Enter the application ID;

  4. Choose the application integration method:

  5. Public DataWay: Directly receives RUM data without installing the DataKit collector.

  6. Local Environment Deployment: Receives RUM data after meeting the prerequisites.

Integration Methods

  1. Ensure DataKit is installed and configured to be accessible via the public network and install the IP Geolocation Library;
  2. Obtain applicationId, env, version and other parameters from the console, and start integrating the application;
  3. When integrating the SDK, set datakitOrigin to the domain or IP of DataKit.
  1. Obtain applicationId, clientToken, and site parameters from the console, and start integrating the application;
  2. When integrating the SDK, there is no need to configure datakitOrigin, as data will be sent to the public DataWay by default.

SDK Configuration

Integration Method
 Description
NPM Package the SDK code into the frontend project to ensure frontend performance is not affected. May miss requests and error collections before SDK initialization.
CDN Asynchronous Loading Asynchronously introduce the SDK script via CDN, without affecting page loading performance. May miss requests and error collections before initialization.
CDN Synchronous Loading Synchronously introduce the SDK script via CDN, to fully collect all errors and performance metrics. However, it may affect page loading performance.

NPM Integration

Install and introduce the SDK in the frontend project:

npm install @cloudcare/browser-rum

Initialize the SDK in the project:

import { datafluxRum } from "@cloudcare/browser-rum"
datafluxRum.init({
  applicationId: "<Application ID>",
  site: "http://172.16.212.186:9529",
  clientToken: "a993f53a8ea04bc6b9350e5e670a3a3b",
  env: "production",
  version: "1.0.0",
  service: "browser",
  sessionSampleRate: 100,
  sessionReplaySampleRate: 70,
  compressIntakeRequests: true,
  trackInteractions: true,
  traceType: "ddtrace", // Optional, defaults to ddtrace, currently supports ddtrace, zipkin, skywalking_v3, jaeger, zipkin_single_header, w3c_traceparent 6 types
  allowedTracingOrigins: ["https://api.example.com", /https:\/\/.*\.my-api-domain\.com/], // Optional, list of all requests allowed to inject trace collector required headers. Can be the origin of the request or a regular expression
})
datafluxRum.startSessionReplayRecording()

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: "http://172.16.212.186:9529",
      clientToken: "a993f53a8ea04bc6b9350e5e670a3a3b",
      env: "production",
      version: "1.0.0",
      service: "browser",
      sessionSampleRate: 100,
      sessionReplaySampleRate: 70,
      compressIntakeRequests: true,
      trackInteractions: true,
      traceType: "ddtrace", // Optional, defaults to ddtrace, currently supports ddtrace, zipkin, skywalking_v3, jaeger, zipkin_single_header, w3c_traceparent 6 types
      allowedTracingOrigins: ["https://api.example.com", /https:\/\/.*\.my-api-domain\.com/], // Optional, list of all requests allowed to inject trace collector required headers. Can be the origin of the request or a regular expression
    })
  window.DATAFLUX_RUM && window.DATAFLUX_RUM.startSessionReplayRecording()
</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: "http://172.16.212.186:9529",
      clientToken: "a993f53a8ea04bc6b9350e5e670a3a3b",
      env: "production",
      version: "1.0.0",
      service: "browser",
      sessionSampleRate: 100,
      sessionReplaySampleRate: 70,
      compressIntakeRequests: true,
      trackInteractions: true,
      traceType: "ddtrace", // Optional, defaults to ddtrace, currently supports ddtrace, zipkin, skywalking_v3, jaeger, zipkin_single_header, w3c_traceparent 6 types
      allowedTracingOrigins: ["https://api.example.com", /https:\/\/.*\.my-api-domain\.com/], // Optional, list of all requests allowed to inject trace collector required headers. Can be the origin of the request or a regular expression
    })
    window.DATAFLUX_RUM && window.DATAFLUX_RUM.startSessionReplayRecording()
  })
</script>

Parameter Configuration

Initialization Parameters

Parameter
Type
Required
Default
 Description
applicationId String Yes Application ID created from Guance.
datakitOrigin String Yes DataKit data reporting Origin note:
Protocol (including ://), domain (or IP address) [and port number]
Example:
https://www.datakit.com;
http://100.20.34.3:8088.
clientToken String Yes Token for reporting data via openway, obtained from the Guance console, required (public openway integration).
site String Yes Address for reporting data via public openway, obtained from the Guance console, required (public openway integration).
env String No Current environment of the web application, such as prod: production environment; gray: gray environment; pre: pre-release environment; common: daily environment; local: local environment.
version String No Version number of the web application.
service String No Current application service name, defaults to browser, supports custom configuration.
sessionSampleRate Number No 100 Percentage of metrics data collection:
100 means full collection; 0 means no collection.
sessionOnErrorSampleRate Number No 0 Error session compensation sampling rate: When a session is not sampled by sessionSampleRate, if an error occurs during the session, it will be collected at this rate. Such sessions will start recording events from the time the error occurs and continue until the session ends. SDK version requirement>= 3.2.19
sessionReplaySampleRate Number No 100 Session Replay data collection percentage:
100 means full collection; 0 means no collection.
sessionReplayOnErrorSampleRate Number No 0 Session Replay error session replay compensation sampling rate: When a session is not sampled by sessionReplaySampleRate, if an error occurs during the session, it will be collected at this rate. Such replays will record events up to one minute before the error occurs and continue until the session ends. SDK version requirement>= 3.2.19
trackSessionAcrossSubdomains Boolean No false Share cache across subdomains under the same domain.
usePartitionedCrossSiteSessionCookie Boolean No false Whether to enable partitioned secure cross-site session cookie Details
useSecureSessionCookie Boolean No false Use secure session cookies. This will disable RUM events sent over insecure (non-HTTPS) connections.
traceType Enum No ddtrace Configure the type of trace tool, if not configured, defaults to ddtrace. Currently supports ddtrace, zipkin, skywalking_v3, jaeger, zipkin_single_header, w3c_traceparent 6 types.

⚠
1. opentelemetry supports zipkin_single_header, w3c_traceparent, zipkin, jaeger 4 types.
2. The configuration takes effect depending on the allowedTracingOrigins configuration.
3. Configuring the corresponding traceType requires corresponding API services. For setting different Access-Control-Allow-Headers, refer to APM How to Associate RUM.
traceId128Bit Boolean No false Whether to generate traceID in 128 bytes, corresponding to traceType, currently supports types zipkin, jaeger.
allowedTracingOrigins Array No [] List of all requests allowed to inject trace collector required headers. Can be the origin of the request or a regular expression, origin: Protocol (including ://), domain (or IP address) [and port number]. _Example:
["https://api.example.com", /https:\\/\\/._\\.my-api-domain\\.com/].
allowedTracingUrls Array No [] List of URLs matching requests associated with Apm. Can be the URL of the request, a regular expression, or a match function. Example: ["https://api.example.com/xxx", /https:\/\/.*\.my-api-domain\.com\/xxx/, function(url) {if (url === 'xxx') { return false} else { return true }}] This parameter is an extension of the allowedTracingOrigins configuration, either one can be configured.
trackUserInteractions Boolean No false Whether to enable user interaction collection.
actionNameAttribute String No Version requirement:>3.1.2. Add custom attributes to elements to specify the name of the action. For specific usage, refer to
beforeSend Function(event, context):Boolean No Version requirement:>3.1.2. Data interception and modification, refer to
storeContextsToLocal Boolean No Version requirement:>3.1.2. Whether to cache user-defined data to local localstorage, such as custom data added by setUser, addGlobalContext API.
storeContextsKey String No Version requirement:>3.1.18. Define the key stored in localstorage, default is empty, automatically generated, this parameter is mainly to distinguish the problem of sharing store under the same domain but different sub-paths.
compressIntakeRequests Boolean No Compress RUM data request content to reduce bandwidth usage when sending large amounts of data, and also reduce the number of requests sent. Compression is done in the WebWorker thread. For CSP security policy, refer to CSP Security. SDK version requirement>= 3.2.0. datakit version requirement >=1.60. Deployment version requirement >= 1.96.178
workerUrl Sring No sessionReplay and compressIntakeRequests data compression are both done in the webwork thread, so by default, when CSP security access is enabled, you need to allow worker-src blob:; This configuration allows adding self-hosted worker address. For CSP security policy, refer to CSP Security. SDK version requirement>= 3.2.0.
remoteConfiguration Boolean No Whether to enable the remote configuration function for data collection, default is not enabled. The remote configuration function can dynamically modify data collection configuration items without releasing a new version. For example, you can modify the sampling rate, whether to enable user interaction collection, etc. in the remote configuration. The remote configuration function needs to be enabled in the Guance console environment variable settings. SDK version requirement>= 3.2.20. datakit version requirement >=1.60.Guance How to enable environment variable function in console

site Parameter Handling

Node Name Address
China Zone 1 (Hangzhou) https://rum-openway.guance.com
China Zone 2 (Ningxia) https://aws-openway.guance.com
China Zone 4 (Guangzhou) https://cn4-openway.guance.com
China Zone 6 (Hong Kong) https://cn6-openway.guance.one
Overseas Zone 1 (Oregon) https://us1-openway.guance.com
Europe Zone 1 (Frankfurt) https://eu1-openway.guance.one
Asia Pacific Zone 1 (Singapore) https://ap1-openway.guance.one
Africa Zone 1 (South Africa) https://za1-openway.guance.com
Indonesia Zone 1 (Jakarta) https://id1-openway.guance.com

Use Cases

Collect Only Error Session Events

Prerequisite

SDK version requirement: 3.2.19 or higher.

When a page triggers an error, the SDK will automatically execute:

  • Continuous recording: From the time the error occurs, fully record the entire lifecycle data of the session.
  • Precise compensation: Ensure no error scenarios are missed through an independent sampling channel.

Configuration Example

<script
  src="https://static.guance.com/browser-sdk/v3/dataflux-rum.js"
  type="text/javascript"
></script>
<script>
// Core configuration initialization
window.DATAFLUX_RUM && window.DATAFLUX_RUM.init({

   ...
   // Precise collection strategy
   sessionSampleRate: 0,             // Disable regular session collection
   sessionOnErrorSampleRate: 100, // Full collection of error sessions

});

</script>

Data Compression

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

To mitigate this, the following optimization measures can be taken:

  • Delayed Reporting: Delay the collection timing through asynchronous methods or NPM integration to avoid generating too many requests during the initialization phase.
  • Data Compression: Use the zlib algorithm to compress the collected data before reporting, effectively reducing the request volume and number of requests.

Data compression operations are performed in Web Worker, and will not block or affect the performance of the browser's main thread.

Configuration Example

Enable compressIntakeRequests: true in the initialization configuration to enable compression:

<script
  src="https://static.guance.com/browser-sdk/v3/dataflux-rum.js"
  type="text/javascript"
></script>
<script>
  window.DATAFLUX_RUM && window.DATAFLUX_RUM.init({
    ...
    compressIntakeRequests: true, // Enable data compression
  });
</script>

Notes

  1. The data compression logic is executed in Web Worker. If CSP security policy is enabled, you need to allow blob:; in worker-src. For more information, refer to CSP Security Policy Description.
  2. The SDK supports specifying a self-hosted Worker address through the workerUrl configuration.
  3. The SDK version using this feature needs to be >= 3.2.

Custom Adding Data TAG

Use setGlobalContextProperty or setGlobalContext API to add custom tags to all RUM events.

// Use setGlobalContextProperty to add a single TAG
window.DATAFLUX_RUM && window.DATAFLUX_RUM.setGlobalContextProperty("userName", "Zhang San")

// Use setGlobalContext to add multiple TAGs
window.DATAFLUX_RUM &&
  window.DATAFLUX_RUM.setGlobalContext({
    userAge: 28,
    userGender: "Male",
  })

Tracking User Interactions

Control Whether to Enable Action Collection

Control whether to collect user click behavior through the trackUserInteractions initialization parameter.

Custom Action Name

  • Customize the Action name by adding the data-guance-action-name attribute or data-custom-name (depending on the actionNameAttribute configuration) to the clickable element.

Use addAction API to Customize Action

// CDN Synchronous Loading
window.DATAFLUX_RUM &&
  window.DATAFLUX_RUM.addAction("cart", {
    amount: 42,
    nb_items: 2,
    items: ["socks", "t-shirt"],
  })

// CDN Asynchronous Loading
window.DATAFLUX_RUM.onReady(function () {
  window.DATAFLUX_RUM.addAction("cart", {
    amount: 42,
    nb_items: 2,
    items: ["socks", "t-shirt"],
  })
})

// NPM
import { datafluxRum } from "@cloudcare/browser-rum"
datafluxRum &&
  datafluxRum.addAction("cart", {
    amount: 42,
    nb_items: 2,
    items: ["socks", "t-shirt"],
  })

Custom Adding Error

Use the addError API to customize adding Error metrics data Add Custom Error.

// CDN Synchronous Loading
const error = new Error("Something wrong occurred.")
window.DATAFLUX_RUM && DATAFLUX_RUM.addError(error, { pageStatus: "beta" })

// CDN Asynchronous Loading
window.DATAFLUX_RUM.onReady(function () {
  const error = new Error("Something wrong occurred.")
  window.DATAFLUX_RUM.addError(error, { pageStatus: "beta" })
})

// NPM
import { datafluxRum } from "@cloudcare/browser-rum"
const error = new Error("Something wrong occurred.")
datafluxRum.addError(error, { pageStatus: "beta" })

Custom User Identification

Use the setUser API to add identification attributes (such as ID, name, email) to the current user Add Custom User Information.

// CDN Synchronous Loading
window.DATAFLUX_RUM &&
  window.DATAFLUX_RUM.setUser({
    id: "1234",
    name: "John Doe",
    email: "john@doe.com",
  })

// CDN Asynchronous Loading
window.DATAFLUX_RUM.onReady(function () {
  window.DATAFLUX_RUM.setUser({ id: "1234", name: "John Doe", email: "john@doe.com" })
})

// NPM
import { datafluxRum } from "@cloudcare/browser-rum"
datafluxRum.setUser({ id: "1234", name: "John Doe", email: "john@doe.com" })

Web Session Replay

Prerequisite

Ensure that the SDK version you are using supports the session replay feature (usually version > 3.0.0).

Start Recording

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

Prerequisite

SDK version requirement: 3.2.19 or higher.

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

  • Backtracking Collection: Record a complete page snapshot up to 1 minute before the error;
  • Continuous Recording: Continue recording from the time the error occurs until the session ends;
  • Intelligent Compensation: Ensure no error scenarios are missed through an independent sampling channel.

Configuration Example

<script
  src="https://static.guance.com/browser-sdk/v3/dataflux-rum.js"
  type="text/javascript"
></script>
<script>
// Initialize SDK core configuration
window.DATAFLUX_RUM && window.DATAFLUX_RUM.init({
   ....

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

});

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

Notes

  • The session replay feature does not cover iframes, videos, audio, and canvas element playback;
  • To ensure that static resources (such as fonts, images) can be accessed normally during replay, you may need to configure the CORS policy;
  • Ensure that CSS rules are accessible through the CSSStyleSheet interface to support CSS styles and mouse hover events.

Debugging and Optimization

  • Use the logs and monitoring tools provided by the SDK for debugging to improve application performance;
  • Adjust the sessionSampleRate and sessionReplaySampleRate parameters according to business needs.

Feedback

Is this page helpful? ×