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

```typoscript
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:

```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);
}
```

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

{% hint style="info" %}
Please note that this feauture is in gradual release phases. Please be in touch with teh groundcover team to ensure it's enabled in your account
{% endhint %}

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&#x20;

Add a call to this endpoint&#x20;

```
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](https://docs.groundcover.com/use-groundcover/remote-access-and-apis/api-keys#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();
```

&#x20; 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="https://2771001740-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FUHgqKYgCiRKdOpWQdi52%2Fuploads%2F6MVTaL6knDbYJLfqrM23%2Fimage.png?alt=media&#x26;token=5c1c99dd-7f25-458f-ab2d-e1dd9609d912" alt=""><figcaption></figcaption></figure>

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

<figure><img src="https://2771001740-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FUHgqKYgCiRKdOpWQdi52%2Fuploads%2FHNh4Yf6XfkvqBxPTsl3l%2Fimage.png?alt=media&#x26;token=a917a84a-8502-48df-8404-d7a4ce0bcfbc" 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 `*`