Connect RUM

This capability is only available to organizations subscribed to our Enterprise plan.

groundcover’s Real User Monitoring (RUM) SDK allows you to capture front-end performance data, user events, and errors from your web applications.

Start capturing RUM data by installing the browser SDK in your web app.

This guide will walk you through installing the SDK, initializing it, identifying users, sending custom events, capturing exceptions, and configuring optional settings.

Install the SDK

npm install @groundcover/browser
# or
yarn add @groundcover/browser

Initialize the SDK

Initialization

import groundcover from '@groundcover/browser';

groundcover.init({
  apiKey: 'your-ingestion-key',
  cluster: 'your-cluster',
  environment: 'production',
  dsn: 'your-dsn',
  appId: 'your-app-id',
});

Configuration Parameters

apiKey	A dedicated Ingestion Key of type RUM (Settings -> Access -> Ingestion Keys)
dsn	Your public groundcover endpoint in the format of example.platform.grcv.io . It's your ingress.site installation value.
cluster	Identifier for your cluster; helps filter RUM data by specific cluster.
environment	Environment label (e.g., production, staging) used for filtering data.
appId	Custom application identifier set by you; useful for filtering and segmenting data on a single application level later.

Advanced Configuration

You can customize SDK behavior (event sampling, data masking, enabled events). The following properties are customizable:

export interface SDKOptions {
  batchSize: number;
  batchTimeout: number;
  eventSampleRate: number;
  sessionSampleRate: number;
  environment: string;
  debug: boolean;
  tracePropagationUrls: string[];
  beforeSend: (event: Event) => boolean;
  enabledEvents: Array<"dom" | "network" | "exceptions" | "logs" | "pageload" | "navigation" | "performance">;
  excludedUrls: [];
}

You can pass the values by calling the init function:

groundcover.init({
  apiKey: 'your-ingestion-key',
  cluster: 'your-cluster',
  environment: 'production',
  dsn: 'your-dsn',
  appId: 'your-app-id',
  options: {
    batchSize: 50,
    sessionSampleRate: 0.5, // 50% sessions sampled
    eventsSampleRate: 0.5,
  },
});

Or via the updateConfig function:

groundcover.updateConfig({
   batchSize: 20,
});

Identify Users

Link RUM data to specific users:

groundcover.identifyUser({
  id: 'user-id',
  email: '[email protected]',
});

Send Custom Events

Instrument key user interactions:

groundcover.sendCustomEvent({
  event: 'PurchaseCompleted',
  attributes: { orderId: 1234, amount: 99.99 },
});

Capture Exceptions

Manually track caught errors:

try {
  performAction();
} catch (error) {
  groundcover.captureException(error);
}