> For the complete documentation index, see [llms.txt](https://docs.groundcover.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.groundcover.com/getting-started/installation-and-updating/connect-rum.md).

# Connect RUM

{% hint style="info" %}
This capability is only available to BYOC deployments. Check out our [pricing page](https://www.groundcover.com/pricing) for more information about subscription plans and the available deployment modes.
{% endhint %}

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](https://www.npmjs.com/package/@groundcover/browser) 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

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

<table data-header-hidden><thead><tr><th width="148.84765625">Parameter</th><th>Description</th></tr></thead><tbody><tr><td><code>apiKey</code></td><td>A dedicated Ingestion Key of type <code>RUM</code> (Settings -> Access -> Ingestion Keys)</td></tr><tr><td><code>dsn</code></td><td>Your public groundcover endpoint in the format of <code>https://example.platform.grcv.io</code> , where <code>example.platform.grcv.io</code><br>is your <code>ingress.site</code> installation value.</td></tr><tr><td><code>cluster</code></td><td>Identifier for your cluster; helps filter RUM data by specific cluster.</td></tr><tr><td><code>environment</code></td><td>Environment label (e.g., <code>production</code>, <code>staging</code>) used for filtering data.</td></tr><tr><td><code>appId</code></td><td>Custom application identifier set by you; useful for filtering and segmenting data on a single application level later.</td></tr></tbody></table>

#### Advanced Configuration

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

```typescript
export interface SDKOptions {
  batchSize: number;
  batchTimeout: number;
  eventSampleRate: number;
  sessionSampleRate: number;
  debug: boolean;
  tracePropagationUrls: string[];
  excludedUrls: [];
  beforeSend: (event: Event) => boolean;
  enabledEvents: Array<"dom" | "network" | "exceptions" | "logs" | "pageload" | "navigation" | "performance">;
  sessionMaxDuration?: number; // optional; default 4h, range 1 minute – 8 hours (ms)

}
```

<table data-header-hidden><thead><tr><th width="210.55859375">Parameter</th><th>Description</th></tr></thead><tbody><tr><td><code>batchSize</code></td><td>Maximum number of events to collect before the SDK flushes a batch to groundcover (default: 10).</td></tr><tr><td><code>batchTimeout</code></td><td>Maximum time in milliseconds to wait before flushing a partially filled batch (default: 10000).</td></tr><tr><td><code>eventSampleRate</code></td><td>Fraction from 0 to 1 controlling what share of events within a sampled session are recorded (default: 1).</td></tr><tr><td><code>sessionSampleRate</code></td><td>Fraction from 0 to 1 controlling what share of user sessions are tracked at all (default: 1).</td></tr><tr><td><code>debug</code></td><td>When true, writes detailed SDK logs to the browser console for troubleshooting (default: false).</td></tr><tr><td><code>tracePropagationUrls</code></td><td>URL patterns (supports * wildcards) for outgoing requests that should receive distributed-tracing headers.</td></tr><tr><td><code>excludedUrls</code></td><td>URL strings or regexes for network requests the SDK should not instrument or record.</td></tr><tr><td><code>beforeSend</code></td><td>Optional callback that receives each event and returns false to drop it before it is sent.</td></tr><tr><td><code>enabledEvents</code></td><td>List of event categories to collect; an empty array enables all categories (default: all). Valid values: "dom", "network", "exceptions", "logs", "pageload", "navigation", "performance", "replay".</td></tr><tr><td><code>sessionMaxDuration</code></td><td>Max time before forcing an end to a session. Default is 4 hours.</td></tr></tbody></table>

You can pass the values by calling the init function:

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

Or via the updateConfig function:

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

### Identify Users

Link RUM data to specific users:

```typescript
groundcover.identifyUser({
  id: 'user-id',
  email: 'user@example.com',
});
```

### Send Custom Events

Instrument key user interactions:

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

### Capture Exceptions

Manually track caught errors:

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

### Send Logs

In addition to capturing console.log calls, you can also make a call to groundcover.logger\<level> to report logs that won't be visible to your users in the browser.

```typescript
groundcover.Logger<info>(
    "User entered new experience",
    { relaseId : 1.5.3 } 
)
```

### Source Maps

Source maps map minified/bundled code back to your original source files. With them, stack traces in RUM (e.g. in session details and exceptions) show your real file names, line numbers, and function names instead of bundle names and minified positions.

Pre-condition - source maps were enabled in your CI operation.

To enable source maps in your account, follow these steps, upload source maps from your CI job via the API

Add a call to this endpoint

```
POST /api/rum/sourcemaps
Content-Type: multipart/form-data   
```

Required form fields:

* `app_id` - your application identifier (alphanumeric, dots, hyphens, underscores), as provided in the RUM init call.
* `release_id` - the release/version being deployed (same character restrictions), as provided in the RUM init call.
* `file` - the source map file

Required headers:

* `Authorization` - groundcover api key - [here is how to generate one](/use-groundcover/remote-access-and-apis/api-keys.md#creation-and-storage)
* `X-Backend-Id` - the relevant BYOC backend, displayed in the api keys page

\
Here is an example of source maps uploading using curl:

```shellscript
curl -X POST "https://app.groundcover.com/api/rum/sourcemaps" \
-H "Authorization: Bearer <API_KEY>" \
-H "X-Backend-Id: $BACKEND_ID" \
-F "app_id=my-web-app" \
-F "release_id=1.2.3" \
-F "file=@./dist/main.js.map" 


```

Response (201):

```json
{
"status": "uploaded",
"app_id": "my-web-app",
"release_id": "1.2.3",
"filename": "main.js.map",
"size_bytes": 524288
}
```

\
Files will be stored in the selected provider at the path: `sourcemaps/<app_id>/<release_id>/<filename>` .\
\
Every new RUM trace that holds a stack trace will be automatically converted based on the source map.

### Session Replay

Enable session recording in order to replay your users behavior and see the actions that led to specific RUM events.

#### How to set it up?

{% hint style="info" %}
Session replay requires enabling the RUM SDK
{% endhint %}

Add the following instrumentation to your code:

```mts
groundcover.startReplayRecording();
```

For example, you can add the above once the user navigated to a specific page or upon a session start.

Add the following if there is a need to stop the recording, e.g. before a sensitive section in your app.

```typescript
groundcover.stopReplayRecording();
```

Recording will be stored on your BYOC server and will be deleted along with the RUM session, in accordance to your retention policy.

#### Viewing sessions

In the [summary page](https://app.groundcover.com/rum/summary), you will see an indication next to sessions with a recording.

<figure><img src="/files/CenWUozMBBzJdwjpHzfx" alt=""><figcaption></figcaption></figure>

Within the drawer, open the Session Replay tab to see the recording

<figure><img src="/files/Z55EGisOuYsbYojPj66A" alt=""><figcaption></figcaption></figure>

In case there is a need to mask elements in the session, add any of the following to your HTML

* `.rr-ignore` - no input events recorded
* `.rr-block` - elements will not be recorded, instead a placeholder will be shown
* `.rr-mask` - text will be replaced with `*`


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.groundcover.com/getting-started/installation-and-updating/connect-rum.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.