Skip to content

Web Application Integration

By collecting metrics data from web applications, analyze application performance in a visualized manner.

Prerequisites

Note

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

Start Integration

  1. Go to Synthetic Tests > Create > Web;
  2. Enter the application name;
  3. Input the application ID;

  4. Choose the integration method:

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

  6. Local Environment Deployment: After meeting the prerequisites, receive RUM data.

Integration Method

  1. Ensure that DataKit is installed and configured as publicly accessible with IP geolocation database installed;
  2. Obtain parameters such as applicationId, env, version from the console and start integrating the application;
  3. When integrating the SDK, set datakitOrigin to the domain name or IP of DataKit.
  1. Obtain parameters such as applicationId, clientToken, and site from the console and start integrating the application;
  2. No need to configure datakitOrigin when integrating the SDK; data will be sent by default to the public DataWay.

SDK Configuration

Integration Method
 Description
NPM Package the SDK code into the frontend project to ensure no impact on frontend performance. Some requests and error collections before SDK initialization might be missed.
CDN Asynchronous Loading Asynchronously load the SDK script via CDN, which does not affect page loading performance. Some requests and error collections before initialization might be missed.
CDN Synchronous Loading Synchronously load the SDK script via CDN, which collects all errors and performance metrics completely. However, it may affect page loading performance.

NPM Integration

Install and import the SDK in your frontend project:

npm install @cloudcare/browser-rum

Initialize the SDK in your 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', // Not mandatory, defaults to ddtrace. Currently supports 6 types: ddtrace, zipkin, skywalking_v3, jaeger, zipkin_single_header, w3c_traceparent
  allowedTracingOrigins: ['https://api.example.com', /https:\/\/.*\.my-api-domain\.com/], // Not mandatory, allows all requests where headers needed for tracing injection can be injected. Can be origin or regex
})
datafluxRum.startSessionReplayRecording()

CDN Synchronous Loading

Add the script in 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: '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', // Not mandatory, defaults to ddtrace. Currently supports 6 types: ddtrace, zipkin, skywalking_v3, jaeger, zipkin_single_header, w3c_traceparent
      allowedTracingOrigins: ['https://api.example.com', /https:\/\/.*\.my-api-domain\.com/], // Not mandatory, allows all requests where headers needed for tracing injection can be injected. Can be origin or regex
    })
  window.DATAFLUX_RUM && window.DATAFLUX_RUM.startSessionReplayRecording()
</script>

CDN Asynchronous Loading

Add the script in 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: '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', // Not mandatory, defaults to ddtrace. Currently supports 6 types: ddtrace, zipkin, skywalking_v3, jaeger, zipkin_single_header, w3c_traceparent
      allowedTracingOrigins: ['https://api.example.com', /https:\/\/.*\.my-api-domain\.com/], // Not mandatory, allows all requests where headers needed for tracing injection can be injected. Can be origin or regex
    })
    window.DATAFLUX_RUM && window.DATAFLUX_RUM.startSessionReplayRecording()
  })
</script>

Parameter Configuration

Initialization Parameters

Parameter
Type
Mandatory?
Default Value
 Description
applicationId String Yes Application ID created from Guance.
datakitOrigin String Yes DataKit data reporting Origin Annotation:
protocol (including: //), domain (or IP address)[and port number]
For example:
https://www.datakit.com;
http://100.20.34.3:8088.
clientToken String Yes Data reporting token in openway mode obtained from Guance console, mandatory (for public openway mode access).
site String Yes Data reporting address in public openway mode obtained from Guance console, mandatory (for public openway mode access).
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 Name of the current application's service, default is browser, supports custom configuration.
sessionSampleRate Number No 100 Percentage of metric data collection:
100 means full collection; 0 means no collection.
sessionOnErrorSampleRate Number No 0 Error session compensation sampling rate: if the session is not sampled by sessionSampleRate, but an error occurs during the session, then sample according to this ratio. Such sessions will start recording events at the time of the error 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: if the session is not sampled by sessionReplaySampleRate, but an error occurs during the session, then sample according to this ratio. Such replays will record up to one minute of events before the error occurs and continue until the session ends. SDK version requirement: >= 3.2.19.
trackSessionAcrossSubdomains Boolean No false Subdomains under the same domain share cache.
usePartitionedCrossSiteSessionCookie Boolean No false Whether to enable partitioned secure cross-site session cookie details
useSecureSessionCookie Boolean No false Use secure session cookie. This will disable sending RUM events over insecure (non-HTTPS) connections.
traceType Enum No ddtrace Configure the type of trace tool used, defaults to ddtrace if not configured. Currently supports 6 data types: ddtrace, zipkin, skywalking_v3, jaeger, zipkin_single_header, w3c_traceparent.

⚠
1. opentelemetry supports 4 types: zipkin_single_header, w3c_traceparent, zipkin, jaeger.
2. The effectiveness of this configuration depends on the allowedTracingOrigins configuration item.
3. Configuring the corresponding traceType requires support for the corresponding API services. About setting different Access-Control-Allow-Headers, refer to How APM Associates with RUM .
traceId128Bit Boolean No false Whether to generate traceID in 128-byte format, corresponding to traceType, currently supports types zipkin, jaeger.
allowedTracingOrigins Array No [] List of all requests where headers needed for tracing injection can be injected. Can be request origins or regex, origin: protocol (including: //), domain (or IP address)[and port number]. _For example:
["https://api.example.com", /https:\\/\\/._\\.my-api-domain\\.com/].*
allowedTracingUrls Array No [] Matching list for URLs associated with Apm requests. Can be request URL, regex, or match function, for 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 is sufficient.
trackUserInteractions Boolean No false Whether to enable user behavior collection.
actionNameAttribute String No Version requirement: >3.1.2. Add custom attributes to elements to specify the operation name. For specific usage, refer to details
beforeSend Function(event, context):Boolean No Version requirement: >3.1.2. Intercept and modify data, refer to details
storeContextsToLocal Boolean No Version requirement: >3.1.2. Whether to cache user-defined data locally in localstorage, such as: custom data added using setUser, addGlobalContext APIs.
storeContextsKey String No Version requirement: >3.1.18. Define the key stored in localstorage, default is empty, auto-generated. This parameter mainly distinguishes shared storage issues under the same domain with different sub-paths.
compressIntakeRequests Boolean No Compress RUM data request content to reduce bandwidth usage when sending large amounts of data, while reducing the number of data transmission requests. Compression is completed in the WebWorker thread. Refer to csp security policy here. SDK version requirement >= 3.2.0. Datakit version requirement >=1.60. Deployment Plan requirement >= 1.96.178
workerUrl String No Both sessionReplay and compressIntakeRequests complete data compression in the webwork thread, so by default, in the case of enabling csp secure access, worker-src blob: needs to be allowed; This configuration allows adding a self-hosted worker address. Refer to csp security policy here. SDK version requirement >= 3.2.0.
remoteConfiguration Boolean No Whether to enable remote configuration for data collection, default is disabled. Remote configuration allows dynamic modification of data collection configurations without releasing a new version. For example, sampling rates or whether to enable user behavior collection can be modified in remote configuration. Remote configuration functionality requires enabling environment variable settings in the Guance console. SDK version requirement >= 3.2.20. Datakit version requirement >=1.60. Guance Console How to Enable Environment Variable Functionality

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 and above.

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

  • Continuous Recording: Fully records session lifecycle data starting from the point of error trigger.
  • Precise Compensation: Ensures no omission of error scenarios through an independent sampling channel.

Configuration Scheme

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

Custom Adding Data TAG

Use the setGlobalContextProperty or setGlobalContext API to add custom tags to all RUM events Add Custom Tags.

// Add a single TAG using setGlobalContextProperty
window.DATAFLUX_RUM && window.DATAFLUX_RUM.setGlobalContextProperty('userName', 'John')

// Add multiple TAGs using setGlobalContext
window.DATAFLUX_RUM &&
  window.DATAFLUX_RUM.setGlobalContext({
    userAge: 28,
    userGender: 'Male',
  })

Track User Actions

Control Whether to Enable Action Collection

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

Customize Action Name

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

Use addAction API to Customize Actions

// 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 Add Errors

Use the addError API to customize and add error metric data Add Custom Errors.

// 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 Add User Identifiers

Use the setUser API to add identification attributes (such as ID, name, email) for 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 > 3.0.0 version).

Enable Recording

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

Prerequisite

SDK version requirement is 3.2.19 and above.

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

  • Retroactive Collection: Record a complete page snapshot for one minute before the error;
  • Continuous Recording: Continue recording from the time of the error until the session ends;
  • Intelligent Compensation: Ensure no omission of error scenarios 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 core SDK 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

});

// Forcefully enable screen recording engine (must be called)
window.DATAFLUX_RUM && window.DATAFLUX_RUM.startSessionReplayRecording();
</script>

Considerations

  • Session replay functionality does not cover iframe, video, audio, and canvas element playback;
  • To ensure normal access to static resources (such as fonts, images) during playback, CORS policy configuration may be required;
  • Ensure CSS rules can be accessed via the CSSStyleSheet interface to support CSS styles and mouse hover events.

Debugging Optimization

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

Feedback

Is this page helpful? ×