SDK overview

The Site Qwality client SDK is a single browser-side package: @siteqwality/rum. It collects Real User Monitoring data and, when a recording rule activates it, session replay. Every option and behavior is in the SDK reference. SDK 1.x is retired; install SDK 2.

There is no Site Qwality back-end library. Send back-end logs, traces and metrics through standard OpenTelemetry SDKs over OTLP/HTTP or the supported JSON and remote-write adapters, as in the platform guides, and keep server ingest credentials separate from the public RUM client token.

What it does

Capture	Tier
Page views, load timing and Web Vitals (LCP, FCP, CLS, INP, TTFB) with attribution	Observe: every sampled session
Errors with message, stack, causes and breadcrumbs (known browser noise filtered)	Observe
Failed requests, frustration signals and custom events	Observe
Clicks, taps and form actions, successful requests, resource timings, console entries and long animation frames	Analyze: activated by a recording rule
DOM snapshots and mutations (rrweb)	Replay: activated by a Replay recording rule

See what is collected when for the details.

The SDK can add a W3C traceparent header to fetch and XHR requests whose URLs match the application’s trace_urls setting, linking a user’s request to your back-end traces.

Install

Install the npm package or paste the CDN snippet into your page’s <head>, then call init with the RUM application’s applicationId and clientToken. The RUM quickstart walks through a first install, and the SDK reference has both snippets, the release channels and every init option.

init starts collection synchronously and returns a Promise you never need to await. A second call is ignored. With the npm package, calls to other methods before init() are ignored, except the opt-out methods. No public method throws: invalid input is ignored and internal failures are swallowed.

Public methods

The full list, including consent, opt-out, replay control and getStatus(), is under public methods.

`setUser(user)` / `clearUser()`

Identify the user. Call it after login, or as soon as you know who it is.

SiteQwalityRUM.setUser({
  id: 'usr_abc123',
  email: 'alice@example.com',
  name: 'Alice',
});

Field	Required	Description
`id`	optional	Your internal user ID. Shown on the session, searchable, and used by `identified` recording rule conditions.
`email`	optional	User’s email. Shown on the session and searchable, unless the application does not capture user emails.
`name`	optional	Display name, shown on the session.
`traits`	optional	Up to 20 string labels, such as `{ plan: 'pro' }`. Used by `attribute` recording rule conditions.

The user attaches to every batch sent after the call, page views included. Each call replaces the previous user; call clearUser() on logout.

`setGlobalAttribute(key, value)` / `removeGlobalAttribute(key)`

Attach a string attribute to every batch sent after the call, or stop attaching it.

SiteQwalityRUM.setGlobalAttribute('plan', 'pro');
SiteQwalityRUM.removeGlobalAttribute('plan');

`addError(error, context?)`

Track a custom error in addition to auto-captured errors.

try {
  await chargeCard();
} catch (err) {
  SiteQwalityRUM.addError(err, { feature: 'checkout', step: '3' });
  throw err;
}

Param	Type	Description
`error`	any	An `Error`, or any other value (recorded as text, with no stack).
`context`	`Record<string, string>`	Stored with the error. `sq.fingerprint` sets your own grouping.

Custom errors pass the same error filtering as captured ones.

`addAction(name, context?)`

Track a custom event, such as a business milestone. Custom events are recorded for every sampled session, whether or not a recording rule matched.

SiteQwalityRUM.addAction('checkout_completed', { variant: 'A' });

Param	Type	Description
`name`	`string`	Event name, up to 256 characters. Used by `event` recording rule conditions.
`context`	`Record<string, string>`	Stored with the event.

Naming clicks

Auto-captured clicks are named from the element’s data-sq-action-name, aria-label or text. Set data-sq-action-name on an element (or an ancestor) to name its clicks yourself, or turn on hiding element text in click names for the application. See click names.

Behavior worth knowing

Errors are filtered. Known browser noise is dropped, repeats are folded and limited, and a dropped error is never billed. Add your own filters with ignoreErrors, denyUrls and beforeSend. See error filtering.
Page views follow real URL changes, and Web Vitals always belong to the document’s initial view. See page views and Web Vitals.
Sessions are shared by tabs. A session ends after 15 minutes without activity or 4 hours in all. See sessions.
Recording rules are evaluated in the browser, and the decision lasts for the rest of the session, in every tab. See rule evaluation.
Frustration signals. Add data-sq-no-frustration to an element, or list selectors in the application settings, to exempt it from rage and dead clicks. See frustration signals.
Delivery is bounded. Batches are gzipped, retried with backoff, and capped by a hard request budget per session and page load. See batching and delivery.

TypeScript types

The SDK ships with TypeScript types. See exported types.

import type { InitOptions, UserContext } from '@siteqwality/rum';

Compatibility

Modern browsers. The bundles target ES2020, and there’s no IE11 support.
The CDN bundle is a classic script that defines a single global, window.SiteQwalityRUM (it also works when loaded with type="module").
The npm package is published as both ESM and CJS, with types. Transpile further via your bundler if you support older browsers.