Web SDK Integration Guide

RUM SDK supports multiple integration methods. Choose the one that best fits your project requirements.

Integration Methods

We provide three integration methods:

Method	Recommended For	Features
NPM	Modern web apps	Bundled with frontend code, no impact on page load
CDN Async	Performance-focused apps	Async loading, doesn’t affect page performance
CDN Sync	Complete data collection	Sync loading, captures all events

NPM and CDN async methods may miss errors, resources, and user actions triggered before SDK initialization. Use CDN sync for complete collection.

Integration Code

NPM Package
CDN Async
CDN Sync

Add @flashcatcloud/browser-rum to your package.json:

npm install @flashcatcloud/browser-rum

Then initialize in your app entry file:

import { flashcatRum } from "@flashcatcloud/browser-rum";

flashcatRum.init({
  applicationId: "<YOUR_APPLICATION_ID>",
  clientToken: "<YOUR_CLIENT_TOKEN>",
  service: "<SERVICE_NAME>",
  env: "<ENV_NAME>",
  version: "1.0.0",
  sessionSampleRate: 100
});

Add the following code snippet to the <head> tag of each HTML page you want to monitor:

<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.flashcat.cloud/browser-sdk/v0/flashcat-rum.js",
    "FC_RUM"
  );
  window.FC_RUM.onReady(function () {
    window.FC_RUM.init({
      applicationId: "<YOUR_APPLICATION_ID>",
      clientToken: "<YOUR_CLIENT_TOKEN>",
      service: "<SERVICE_NAME>",
      env: "<ENV_NAME>",
      version: "1.0.0",
      sessionSampleRate: 100
    });
  });
</script>

Add the following code snippet at the very beginning of the <head> tag (before any other <script> tags):

<script
  src="https://static.flashcat.cloud/browser-sdk/v0/flashcat-rum.js"
  type="text/javascript"
></script>
<script>
  window.FC_RUM &&
    window.FC_RUM.init({
      applicationId: "<YOUR_APPLICATION_ID>",
      clientToken: "<YOUR_CLIENT_TOKEN>",
      service: "<SERVICE_NAME>",
      env: "<ENV_NAME>",
      version: "1.0.0",
      sessionSampleRate: 100
    });
</script>

You can use window.FC_RUM to check if the SDK loaded successfully, allowing you to handle load failures.

Initialization Parameters

Required Parameters

applicationId

string

required

Application ID, obtained from the application management page

clientToken

string

required

Client Token, obtained from the application management page

service

string

required

Service name, used to distinguish different services

Optional Parameters

env

string

Environment identifier, such as production, staging, etc.

version

string

Application version number

sessionSampleRate

number

default:"100"

Percentage of sessions to track: 100 for all, 0 for none

sessionReplaySampleRate

number

default:"0"

Percentage of sessions with Session Replay enabled

Initial user tracking consent state, see User Tracking Consent

trackViewsManually

boolean

default:"false"

Whether to manually control view creation, see Override Default View Names

trackUserInteractions

boolean

default:"true"

Whether to automatically collect user interactions

trackResources

boolean

default:"true"

Whether to enable resource event collection

trackLongTasks

boolean

default:"true"

Whether to enable long task event collection

trackAnonymousUser

boolean

default:"true"

Whether to enable cross-session anonymous user ID collection

sessionReplayPrivacyLevel

'allow' | 'mask-user-input' | 'mask-all'

default:"mask-user-input"

Session replay privacy policy: allow collects all data except passwords, mask-user-input hides user input field content, mask-all hides all text

allowedTracingUrls

array

List of request URLs for injecting tracing headers, see Integrate RUM with Distributed Tracing

traceSampleRate

number

default:"100"

Percentage of requests to trace

proxy

string

Optional proxy URL, e.g., https://www.proxy.com/path

compressIntakeRequests

boolean

default:"false"

Whether to compress requests sent to Flashduty, done in Worker thread

storeContextsAcrossPages

boolean

default:"false"

Whether to store context in localStorage for cross-page persistence

Use Cases

Custom User Identification

Use flashcatRum.setUser() to add identification attributes for the current user:

flashcatRum.setUser({
  id: '1234',
  name: 'John Doe',
  email: 'john@doe.com',
  plan: 'premium'
});

Adding Custom Tags

After initializing RUM, use the setGlobalContextProperty API to add additional tags to all RUM events:

import { flashcatRum } from "@flashcatcloud/browser-rum";

flashcatRum.setGlobalContextProperty('activity', {
  hasPaid: true,
  amount: 23.42
});

Sending Custom Actions

Use the addAction API to create RUM actions with context attributes:

import { flashcatRum } from "@flashcatcloud/browser-rum";

function onCheckoutButtonClick(cart) {
  flashcatRum.addAction("checkout", {
    value: cart.value,
    items: cart.items
  });
}

Custom Error Reporting

You can attach local context to error objects via the dd_context property:

const error = new Error("Something went wrong");
error.dd_context = { component: "Menu", param: 123 };
throw error;

Verification

Check Network Requests

Open browser developer tools and check if there are data upload requests to https://browser.flashcat.cloud/api/v2/rum in the Network panel.

View Console Data

Access the Flashduty console to verify that RUM application data is displaying correctly.

Trigger User Interactions

Trigger some user interactions on the page (clicks, scrolls, etc.) to verify data collection is working.

Data typically appears in the console within 2-5 minutes.

Next Steps

Advanced Configuration

Learn about advanced SDK configuration features

Data Collection

Learn about data types collected by the SDK

Insights

View and analyze RUM data

Quick Start

Analytics

SDK Integration

Performance

Error Tracking

Explorer

Session Replay

Best Practices

Others

Integration Methods

Integration Code

Initialization Parameters

Required Parameters

Optional Parameters

Use Cases

Custom User Identification

Adding Custom Tags

Sending Custom Actions

Custom Error Reporting

Verification

Next Steps

Advanced Configuration

Data Collection

Insights

Quick Start

Analytics

SDK Integration

Performance

Error Tracking

Explorer

Session Replay

Best Practices

Others

​Integration Methods

​Integration Code

​Initialization Parameters

​Required Parameters

​Optional Parameters

​Use Cases

​Custom User Identification

​Adding Custom Tags

​Sending Custom Actions

​Custom Error Reporting

​Verification

​Next Steps

Advanced Configuration

Data Collection

Insights

Integration Methods

Integration Code

Initialization Parameters

Required Parameters

Optional Parameters

Use Cases

Custom User Identification

Adding Custom Tags

Sending Custom Actions

Custom Error Reporting

Verification

Next Steps