Configuration

Everything the SDK can be told, and what it does when you tell it nothing.

Options

npm

import { init } from '@ritim/browser-sdk';

init({
  projectKey: 'P-ABC123',
  release: 'a1b2c3d',
  sampleRate: 0.25,
  trackSoftNavigations: true,
  captureInteractionText: false,
  debug: false,
});

Option	Type	Default	Meaning
projectKey	string	required	Public project key, P-XXXXXX.
release	string	inferred	Release identifier. See Releases.
endpoint	string	build-time	Override the compiled-in collector.
sampleRate	number	0.25	Client-side rate, 0–1. Clamped to that range.
trackSoftNavigations	boolean	true	false measures only the initial document load.
captureInteractionText	boolean	false	Include element text in interaction targets. See below.
debug	boolean	false	Log every payload to the console. Never enable in production.

The type is exported, so you can build the object elsewhere and keep it checked:

import { init, type RumInitOptions } from '@ritim/browser-sdk';

const options: RumInitOptions = { projectKey: 'P-ABC123' };
init(options);

Script tag

<script
  async
  src="https://cdn.ritim.io/latest/rum.min.js"
  data-project-key="P-ABC123"
  data-release="a1b2c3d"
  data-sample-rate="0.25"
></script>

Attribute	Default	Meaning
data-project-key	required	Public project key. Its presence is what triggers auto-init.
data-release	inferred	Release identifier. See Releases.
data-endpoint	build-time	Override the compiled-in collector.
data-sample-rate	0.25	Client-side rate, 0–1. Clamped to that range.
data-track-soft-navigations	true	false measures only the initial document load.
data-capture-interaction-text	false	Include element text in interaction targets. See below.
data-debug	false	Log every payload to the console. Never enable in production.

Boolean attributes are read loosely: anything other than false or 0 counts as true. A typo reads as “on” rather than throwing, because a script tag on a live site should degrade rather than break the page.

Sampling

sampleRate is a client-side rate: the SDK decides per page view whether to measure at all, so an unsampled view costs nothing beyond the bundle.

The default of 0.25 matches the default a new project gets in the dashboard. Three page views in four deliberately do nothing — correct for production, and the single most common reason a new install looks broken. Set it to 1 while verifying and put it back afterwards.

Values outside 0–1 are clamped rather than rejected.

Note

The collector applies the project’s own configured rate regardless of what the page claims, so raising this in the browser cannot raise your ingestion above what the project is set to.

Interaction text

Off by default. When on, an interaction on an element with no id reports a short text excerpt alongside the tag name:

captureInteractionText: false   →  button
captureInteractionText: true    →  button "Add to cart"

An id always wins — an element with one reports #add-to-cart either way, and the text is never read. The excerpt is whitespace-collapsed and truncated to fit a short field.

This turns DOM text into collected data

It is off by default because it is the one setting that changes what leaves the page. If your buttons render personal data — a name, an email, an order number — turning this on sends it. See Privacy.

Turning off soft navigations

npm

init({ projectKey: 'P-ABC123', trackSoftNavigations: false });

Script tag

<script
  async
  src="https://cdn.ritim.io/latest/rum.min.js"
  data-project-key="P-ABC123"
  data-track-soft-navigations="false"
></script>

This measures the initial document load and nothing after it. Reach for it when your app rewrites the URL for something that is not a view change — a filter panel that pushes state on every keystroke will otherwise produce a measurement per keystroke, and burn your event allowance doing it.

Precedence

Where two sources say the same thing, the more specific wins:

1. init({ … })
2. <meta name="rum-release"> — release only
3. data-* on the script tag
4. what the SDK can infer from the page — release only, see Releases

The two paths are not exclusive

Options passed to init() beat script tag attributes, and anything you leave out still falls through to the tag. That is what makes it possible to ship a tag with a project key and override just the sample rate from code.

Debug mode

Logs every payload to the console before it is sent. It is a development aid and nothing more: it does not change what is collected or where it goes, and leaving it on in production just puts your measurements in your visitors’ consoles.

npm

init({ projectKey: 'P-ABC123', debug: true });

Script tag

data-debug="true"