Web SDK Advanced Configuration

This document introduces advanced configuration options for Web RUM SDK, helping you customize data collection behavior based on your business needs.

Flashduty RUM provides various advanced configuration options:

Protect Sensitive Data

Mask personally identifiable information and sensitive data

Associate User Sessions

Link user sessions with internal user identifiers

Reduce Data Volume

Lower RUM data collection through sampling

Enrich Context

Add rich contextual information to data

Override Default RUM View Names

Flashduty RUM automatically generates view events when users visit new pages or when URLs change in SPAs. View names are calculated from the current page URL by default, with variable IDs (path segments containing numbers) automatically removed. For example, /dashboard/1234 and /dashboard/9a are normalized to /dashboard/?. You can manually track view events and specify custom names by setting the trackViewsManually option.

Configure Manual View Tracking

Enable Manual Tracking

Set trackViewsManually to true during initialization:

rum-init.js

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

flashcatRum.init({
  applicationId: "<YOUR_APPLICATION_ID>",
  clientToken: "<YOUR_CLIENT_TOKEN>",
  trackViewsManually: true
});

Call startView Method

Call the startView method on each new page or route change:

flashcatRum.startView({
  name: "checkout",
  service: "purchase",
  version: "1.2.3",
  context: {
    payment: "Done"
  }
});

string

View name, defaults to page URL path

string

Service name, defaults to the service specified when creating the RUM application

string

Application version, defaults to the version specified when creating the RUM application

object

Additional context for the view, applied to the view and its child events

React Router Integration

React Router v6 Example

RumTracker.jsx

import { matchRoutes, useLocation } from "react-router-dom";
import { routes } from "path/to/routes";
import { flashcatRum } from "@flashcatcloud/browser-rum";
import { useEffect } from "react";

export default function App() {
  let location = useLocation();

  useEffect(() => {
    const routeMatches = matchRoutes(routes, location.pathname);
    const viewName = routeMatches && computeViewName(routeMatches);
    if (viewName) {
      flashcatRum.startView({ name: viewName });
    }
  }, [location.pathname]);

  // ...
}

function computeViewName(routeMatches) {
  let viewName = "";
  for (let index = 0; index < routeMatches.length; index++) {
    const routeMatch = routeMatches[index];
    const path = routeMatch.route.path;
    if (!path) continue;

    if (path.startsWith("/")) {
      viewName = path;
    } else {
      viewName += viewName.endsWith("/") ? path : `/${path}`;
    }
  }
  return viewName || "/";
}

Set View Name

Use the setViewName method to update the current view’s name without starting a new view:

flashcatRum.setViewName("Checkout");

Control Initial View Web Vitals Collection

The Web SDK collects Web Vitals and initial view performance metrics by default, including FCP, LCP, FID, and loading time. These metrics use the page navigation start time as their baseline, which works for pages that real users open directly. If your page loads before it becomes visible to the user, such as when it is prerendered by the browser, opened in a background tab, or initialized early by a host container, initial view metrics can be calculated from an unrelated navigation start time. This can make FCP, LCP, or loading time look abnormally high. Set trackWebVitals to false during initialization to disable only Web Vitals and initial view performance metrics on the initial load view.

rum-init.js

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

flashcatRum.init({
  applicationId: "<YOUR_APPLICATION_ID>",
  clientToken: "<YOUR_CLIENT_TOKEN>",
  trackWebVitals: false
});

Parameter	Type	Default	Description
`trackWebVitals`	boolean	`true`	Whether to collect Web Vitals and initial view performance metrics for the initial load view. When set to `false`, the SDK no longer collects FCP, LCP, FID, and loading time for the initial load view

trackWebVitals only affects Web Vitals and initial view performance metrics on the initial load view. Resource, long task, user action, error, and later view events continue to be collected according to their own configuration options.

Enrich and Control RUM Data

Using the beforeSend callback function, you can intercept and modify events before they are sent to Flashduty:

Enrich events: Add additional context attributes
Modify events: Change event content or mask sensitive information
Discard events: Selectively discard specific RUM events

Context Types

Different event types correspond to different contexts:

Event Type	Context
View	`Location` object
Action	Triggering `Event` and handling stack
Resource (XHR)	`XMLHttpRequest`, `PerformanceResourceTiming`, and handling stack
Resource (Fetch)	`Request`, `Response`, `PerformanceResourceTiming`, and handling stack
Resource (Other)	`PerformanceResourceTiming`
Error	`Error` object
Long Task	`PerformanceLongTaskTiming`

Enrich RUM Events

Add context attributes to events, such as adding response header data to resource events:

flashcatRum.init({
  applicationId: "<YOUR_APPLICATION_ID>",
  clientToken: "<YOUR_CLIENT_TOKEN>",
  beforeSend: (event, context) => {
    if (event.type === "resource" && event.resource.type === "fetch") {
      event.context.responseHeaders = Object.fromEntries(
        context.response.headers
      );
    }
    return true;
  }
});

Modify RUM Event Content

For example, mask email addresses from view URLs:

flashcatRum.init({
  applicationId: "<YOUR_APPLICATION_ID>",
  clientToken: "<YOUR_CLIENT_TOKEN>",
  beforeSend: (event) => {
    event.view.url = event.view.url.replace(/email=[^&]*/, "email=REDACTED");
  }
});

Modifiable Attributes

Attribute	Description
`view.url`	Current page URL
`view.referrer`	Previous page URL
`view.name`	Current view name
`service`	Application service name
`version`	Application version
`action.target.name`	Interacted element (auto-collected actions only)
`error.message`	Error message
`error.stack`	Error stack or supplementary information
`error.resource.url`	Resource URL that triggered the error
`resource.url`	Resource URL
`context`	Attributes added via context API or manual event generation

Discard RUM Events

Return false in beforeSend to discard specific RUM events:

flashcatRum.init({
  applicationId: "<YOUR_APPLICATION_ID>",
  clientToken: "<YOUR_CLIENT_TOKEN>",
  beforeSend: (event) => {
    if (shouldDiscard(event)) {
      return false;
    }
  }
});

View events cannot be discarded.

User Sessions

By adding user information to RUM sessions, you can:

Track specific user browsing paths
Understand which users are most affected by errors
Monitor performance for key users

User Attributes

The following are optional user attributes; we recommend providing at least one:

string

Unique user identifier

string

User-friendly name, displayed by default in RUM UI

string

User email, displayed if no name is provided

User Session API

Set User
Get User
Update Property
Remove Property
Clear User

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

const user = flashcatRum.getUser();

flashcatRum.setUserProperty("name", "John Doe");

flashcatRum.removeUserProperty("name");

flashcatRum.clearUser();

After user session information changes, subsequent RUM events will contain the updated information. After logout (calling clearUser), the last view still retains user information, but subsequent views and session-level data will not.

Sampling

By default, Flashduty RUM collects data from all sessions. You can set the sampling rate via the sessionSampleRate parameter to reduce the number of collected sessions:

flashcatRum.init({
  applicationId: "<YOUR_APPLICATION_ID>",
  clientToken: "<YOUR_CLIENT_TOKEN>",
  sessionSampleRate: 90  // Collect 90% of sessions
});

By default, sessions missed by ordinary sampling do not collect page views or related telemetry. Enabling on-error capture below allows buffered data to be uploaded when an error occurs.

On-error session capture

Web SDK 0.3.0 and later can capture sessions and replays that report an error in addition to ordinary sampling. Both options are booleans, default to false, and apply only to sessions not selected by the corresponding sample rate. Sessions already selected keep their normal collection behavior.

Option	Applies to	On the first error
`sessionOnError`	Sessions not selected by `sessionSampleRate`	Uploads up to the last minute of buffered RUM events, then continues normal collection and upload
`sessionReplayOnError`	Collected sessions whose replay was not selected by `sessionReplaySampleRate`	Uploads up to the last minute of buffered replay, then continues normal recording and upload

For example, keep 20% of ordinary sessions and capture error sessions and their replays from the remainder:

flashcatRum.init({
  applicationId: "<YOUR_APPLICATION_ID>",
  clientToken: "<YOUR_CLIENT_TOKEN>",
  sessionSampleRate: 20,
  sessionReplaySampleRate: 0,
  sessionOnError: true,
  sessionReplayOnError: true
});

Buffer first, upload on error: sessions missed by ordinary sampling collect into memory from the start and retain a limited history. The first qualifying error releases that history. The lookback is at most one minute, not a guaranteed full minute, and cannot recover data from before SDK initialization or recording started.
No error means no storage or charge: if a session retained by sessionOnError never reports an error, neither its events nor its replay are uploaded, and it incurs no session charge. With only sessionReplayOnError enabled, candidate replays without errors are not uploaded or charged, but RUM sessions selected by ordinary sampling are still uploaded and billed normally.
Each captured session counts once: ordinary sampling and on-error capture do not count the same session twice. On-error sessions count as actual sessions in statistics, without extrapolation by 1 / sessionSampleRate, and repeated errors do not count them again.
A RUM error event triggers capture: examples include automatically captured JavaScript errors and errors reported with addError(). Errors discarded by beforeSend or rate limiting, and the SDK’s own errors, do not trigger capture. A failed request or HTTP 5xx resource event alone does not trigger capture.

At sessionSampleRate: 100, sessionOnError has no additional effect; at sessionReplaySampleRate: 100, sessionReplayOnError has no additional effect. If sessionSampleRate is 0 and sessionOnError is off, enabling only sessionReplayOnError cannot collect any sessions. To keep only error sessions and their replays, set both sample rates to 0 and enable both on-error options.

Known limitations

SPA replays do not look back across views: the replay reaches back only to the start of the view where the error occurred, up to one minute. RUM events can look back up to one minute across views.
Leaving immediately after an error can lose history: closing or navigating away within seconds of the first error can lose part of a large upload (roughly above 64 KiB) because browsers limit data sent at page exit. Compression does not guarantee delivery. The SDK sends views and errors first; older other events and the final view update may be lost.
Buffering replay still has a performance cost: a large, frequently changing DOM can overflow the buffer and repeatedly trigger full snapshots, adding main-thread work and shortening the available replay history. Prefer enabling only sessionOnError on such pages.
Manual recording has no earlier replay history: if you control recording with startSessionReplayRecording(), explicitly set startSessionReplayRecordingManually: true. In particular, with remote configuration enabled, the recorder may start automatically even when the initial replay sample rate is 0. Do not rely on a rate of 0 to wait for consent. Actions before manual recording starts cannot be recovered.
Withdrawing consent does not cancel an already-triggered upload: if a session has already reported an error, withdrawing tracking consent still uploads its buffered data collected while consent was granted.

You can also change both options through remote configuration. To comply with privacy regulations like GDPR and CCPA, Flashduty RUM allows setting user tracking consent state during initialization:

State	Behavior
`"granted"`	Start collecting data and send to Flashduty
`"not-granted"`	Do not collect any data

flashcatRum.init({
  applicationId: "<YOUR_APPLICATION_ID>",
  clientToken: "<YOUR_CLIENT_TOKEN>",
  trackingConsent: "not-granted"
});

acceptCookieBannerButton.addEventListener("click", function () {
  flashcatRum.setTrackingConsent("granted");
});

Consent state is not synchronized or persisted across tabs. You need to provide the user’s decision during initialization or via setTrackingConsent.

View Context

You can add or modify context for the current view and its child events using these APIs:

Specify When Starting View
Add/Modify Property
Replace Context

flashcatRum.startView({
  name: "checkout",
  context: {
    hasPaid: true,
    amount: 23.42
  }
});

flashcatRum.setViewContextProperty("activity", {
  hasPaid: true,
  amount: 23.42
});

flashcatRum.setViewContext({
  originalUrl: "shopist.io/department/chairs"
});

Error Context

When catching errors, 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;

Global Context

Global context is attached to all RUM events:

// Add property
flashcatRum.setGlobalContextProperty("activity", {
  hasPaid: true,
  amount: 23.42
});

// Remove property
flashcatRum.removeGlobalContextProperty("codeVersion");

// Replace global context
flashcatRum.setGlobalContext({
  codeVersion: 34
});

// Clear global context
flashcatRum.clearGlobalContext();

// Read global context
const context = flashcatRum.getGlobalContext();

Context Lifecycle

By default, global context and user context are stored in current page memory:

Not persisted after full page refresh
Not shared between different tabs or windows

Enable the storeContextsAcrossPages option to store context in localStorage:

flashcatRum.init({
  applicationId: "<YOUR_APPLICATION_ID>",
  clientToken: "<YOUR_CLIENT_TOKEN>",
  storeContextsAcrossPages: true
});

Not recommended to store personally identifiable information in context, as localStorage data persists beyond user session lifetime
Incompatible with trackSessionAcrossSubdomains option
localStorage capacity is limited to 5 MiB

Micro-frontend Support

Flashduty RUM supports micro-frontend architectures by using stack trace mechanisms to identify event sources. Override service and version attributes in beforeSend based on stack information:

const SERVICE_REGEX = /some-pathname\/(?<service>\w+)\/(?<version>\w+)\//;

flashcatRum.init({
  applicationId: "<YOUR_APPLICATION_ID>",
  clientToken: "<YOUR_CLIENT_TOKEN>",
  beforeSend: (event, context) => {
    const stack = context?.handlingStack || event?.error?.stack;
    const { service, version } = stack?.match(SERVICE_REGEX)?.groups || {};

    if (service && version) {
      event.service = service;
      event.version = version;
    }

    return true;
  }
});

The following events cannot be attributed to specific sources: auto-collected action events, non-XHR/Fetch resource events, view events, CORS and CSP violation events.

Integrate RUM with Distributed Tracing

Integrating RUM with distributed tracing allows you to correlate web application requests with their corresponding backend traces, enabling complete end-to-end tracing.

Usage

Use the allowedTracingUrls parameter to configure API service domains for your application:

NPM
CDN Sync
CDN Async

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,
  allowedTracingUrls: [
    "https://api.example.com",
    /https:\/\/.*\.my-api-domain\.com/,
    (url) => url.startsWith("https://api.example.com")
  ],
  traceSampleRate: 20
});

<script
  src="https://static.flashcat.cloud/browser-sdk/v0.3.0/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,
    allowedTracingUrls: [
      "https://api.example.com",
      /https:\/\/.*\.my-api-domain\.com/
    ]
  });
</script>

<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.3.0/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,
      allowedTracingUrls: [
        "https://api.example.com",
        /https:\/\/.*\.my-api-domain\.com/
      ]
    })
  })
</script>

allowedTracingUrls matches full URLs and accepts the following types:

Type	Description
String	Matches any URL starting with this value
RegExp	Uses regular expression’s `test()` method to check for matches
Function	Receives URL as parameter, returns `true` for a match

Tracing Protocol

Distributed tracing is implemented by adding corresponding header fields:

traceparent: [version]-[trace id]-[parent id]-[trace flags]

version: Currently 00
trace id: 128-bit trace ID, 32 characters in hexadecimal
parent id: 64-bit span ID, 16 characters in hexadecimal
trace flags: Indicates sampling; 01 means sampled, 00 means not sampled

tracestate: dd=s:[sampling priority];o:[origin]

sampling priority: 1 means trace is sampled
origin: Always RUM, indicating collection via RUM SDK

Example:

traceparent: 00-00000000000000008448eb211c80319c-b7ad6b7169203331-01
tracestate: dd=s:1;o:rum

Verification

After adding configuration, check requests sent from your application. If they correctly carry the corresponding headers, the configuration is correct.

If your HTTP requests involve cross-origin issues, ensure requests can pass cross-origin checks. Make sure the corresponding server has cross-origin configuration and supports preflight requests.

Important Notes

Ensure correct configuration of applicationId and clientToken to avoid data upload failures
Adjust sampling rates and privacy settings based on application needs, balancing data volume and compliance
For micro-frontends or complex frontend frameworks, implement startView logic at the framework routing level

SDK Integration Guide

Learn how to quickly integrate the RUM SDK

Data Collection

Learn about data types and attributes collected by the SDK

Troubleshooting

Solve common issues and debugging tips

For more details about RUM SDK, visit the Flashduty SDK GitHub Repository.

Protect Sensitive Data

Associate User Sessions

Reduce Data Volume

Enrich Context

​Override Default RUM View Names

​Configure Manual View Tracking

​React Router Integration

​Set View Name

​Control Initial View Web Vitals Collection

​Enrich and Control RUM Data

​Context Types

​Enrich RUM Events

​Modify RUM Event Content

​Modifiable Attributes

​Discard RUM Events

​User Sessions

​User Attributes

​User Session API

​Sampling

​On-error session capture

​Known limitations

​User Tracking Consent

​Example: Handling User Consent

​View Context

​Error Context

​Global Context

​Context Lifecycle

​Micro-frontend Support

​Integrate RUM with Distributed Tracing

​Usage

​Tracing Protocol

​Verification

​Important Notes

​Related Documentation

SDK Integration Guide

Data Collection

Troubleshooting

Override Default RUM View Names

Configure Manual View Tracking

React Router Integration

Set View Name

Control Initial View Web Vitals Collection

Enrich and Control RUM Data

Context Types

Enrich RUM Events

Modify RUM Event Content

Modifiable Attributes

Discard RUM Events

User Sessions

User Attributes

User Session API

Sampling

On-error session capture

Known limitations

User Tracking Consent

Example: Handling User Consent

View Context

Error Context

Global Context

Context Lifecycle

Micro-frontend Support

Integrate RUM with Distributed Tracing

Usage

Tracing Protocol

Verification

Important Notes

Related Documentation