Skip to content
SDKs

Browser SDK

Capture frontend errors, user activity, and session replay.

Watch the Browser SDK video

A 2:43 walkthrough of this guide’s documented setup, examples, and SDK options. Includes the documented test error and a moving, privacy-masked session replay. British male narration and captions are included.

2:43 · English narration · Captions includedOpen video

Jump to a chapter

Read the video transcript
Install and initialize

Install the Browser SDK with the command shown in the guide. Import Reelay in main dot T S, then call init once before your app renders. For Cloud, use the HTTPS API endpoint shown here; for Enterprise, use your Agent’s HTTPS URL. Pass your node ID and ingest key from the dashboard. These are the same configuration fields and placeholders as the documentation.

Capture and verify errors

Uncaught errors and unhandled promise rejections are captured automatically, along with click, navigation, console, and fetch breadcrumbs. For a caught error, use the guide’s save Order example: call capture Exception in the catch block. Capture Message reports a message as a synthetic error event. To verify setup, throw the documented Reelay test error in staging, then check Errors in the dashboard.

Session replay and privacy

Replay keeps the last thirty to sixty seconds of activity in memory and uploads a clip only when an error occurs. Here is the recorded activity for the documented test error. The replay moves through the Browser guide, with page text masked. Input values and page text are masked by default. Replay is enabled by default; set replay to false to disable it.

Built-in scrubbing redacts common secrets. Review what your application puts in URLs, logs, breadcrumbs, and the DOM, and add scrub Patterns for your own secret formats. Before Send can inspect or drop an event; return null to drop it. Error sample rate defaults to one. Performance sampling defaults to zero, so set traces Sample Rate above zero for Web Vitals and page-load transactions.

Backend links and source maps

Allowed fetch requests receive a Reelay session ID header. A positive trace sample rate also adds traceparent. Same-origin requests are allowed by default. For a separate API origin, use the documented trace Propagation Targets list and allow both headers in your API’s CORS configuration. This list replaces the default: include window location origin explicitly, and never add third-party origins.

For production source maps, generate maps during the build and inject debug IDs before deploying the bundles. The guide shows this inject command. Uploads need authentication supported by your deployment, and private maps should stay off a public CDN. Check the documented Enterprise uploader compatibility note. The API reference also covers custom breadcrumbs, reading the session ID, flushing pending events, and uninstalling listeners.

Install

Install the package, then call init once before your app renders. Use https://api.usereelay.com as the endpoint for Cloud, or your Enterprise Agent's HTTPS URL.

Install
npm install @usereelay/browser
main.ts
import * as Reelay from "@usereelay/browser";
Reelay.init({
endpoint: "https://api.usereelay.com",
nodeId: "<your-node-id>",
ingestKey: "<your-ingest-key>",
});

Verify it works

Throw a test error in staging, then check Errors in the dashboard.

Test
setTimeout(() => { throw new Error("Reelay test"); }, 0);

What gets captured

  • Uncaught errors and unhandled promise rejections.
  • Click, navigation, console, and fetch breadcrumbs.
  • Session replay (masked by default, shipped only when an error occurs).
  • Web Vitals and page-load transactions, only when tracesSampleRate is set above 0.

Report a caught error

Manual capture
try {
await saveOrder();
} catch (error) {
Reelay.captureException(error);
}
Reelay.captureMessage("Checkout used the fallback path");

Link to your backend

The SDK adds a reelay-session-id header to allowed fetch requests so backend errors link to the browser session. When tracesSampleRate is above 0, a W3C traceparent header is added too. Same-origin requests are allowed by default. For a separate API origin, list it in tracePropagationTargets and allow both headers in the API's CORS config.

Cross-origin API
Reelay.init({
endpoint: "https://api.usereelay.com",
nodeId: "<your-node-id>",
ingestKey: "<your-ingest-key>",
tracePropagationTargets: [
window.location.origin,
"https://api.example.com",
],
});

Options

OptionUse
endpointHTTPS ingest URL. Required.
nodeId, ingestKeyNode credentials from the dashboard. Required by the backend.
release, commitShaDeployed version and full Git SHA. Embed at build time.
sampleRateFraction of errors to send (0–1). Default: 1.
beforeSendInspect or drop an event before sending. Return null to drop.
scrubPatterns, redactedFieldsExtra regexes and field names to redact.
replayError-buffered session replay. Default: true.
maskAllTextMask page text in replay. Default: true.
tracePropagationTargetsOrigins allowed to receive trace headers.
tracesSampleRatePerformance sampling (0–1). Default: 0 (off).
profilingJS self-profiling. Chromium only. Default: false.
debugDiagnostic callback.

Replay and privacy

Replay keeps the last 30–60 seconds of activity in memory and uploads a clip only when an error occurs. Input values and page text are masked by default. Set replay: false to disable.

Built-in scrubbing redacts common secrets, but review what your app puts in URLs, logs, breadcrumbs, and the DOM. Add scrubPatterns for your own secret formats.

Example project

A complete Browser integration is available in the example workbench.

Production source maps

Minified browser stacks point at generated bundles. Source maps let a compatible ingestion and symbolication workflow recover original filenames and line numbers. Generate maps during your build and inject debug IDs into the bundles before deploying them.

The SDK includes the reelay-sourcemaps tool. Its inject command updates the local artifacts; an upload step must use the endpoint and authentication supported by your deployment. Keep private source maps off a public CDN when they contain source you do not want to publish.

Inject debug IDs into build artifacts
npx reelay-sourcemaps inject ./dist

SDK API reference

Function or methodPurpose
init(options)Initialize the client and listeners. Later calls reuse the client.
getClient()Return the active BrowserClient, or undefined before initialization.
captureException(error)Report a handled exception; returns its event ID or an empty string if dropped.
captureMessage(message)Report a message as a synthetic error event.
client.sessionIdRead the current browser session identifier.
client.addBreadcrumb(crumb)Add a custom, scrubbed breadcrumb to the recent-activity buffer.
client.flush()Drain the pending event queue. Returns a promise.
client.uninstall()Remove listeners and restore wrapped browser functions.