Browsonic SDK Documentation

Introduction

Browsonic SDK is a lightweight, zero-dependency JavaScript library that automatically captures frontend errors and anomalies in real time. It is published on the public npm registry as @browsonic/sdk under the Apache 2.0 licence.

What it captures

Key features

Installation

Install with your preferred package manager.

npm

npm install @browsonic/sdk

pnpm

pnpm add @browsonic/sdk

yarn

yarn add @browsonic/sdk

Quick Start

Get up and running in under two minutes.

Basic setup

import { getBrowsonic } from '@browsonic/sdk';

const sdk = getBrowsonic();
sdk.init({
  apiEndpoint: 'https://api.browsonic.com',
  appKey: 'your-app-key',
  apiKey:  'pk_live_…', // mint in dashboard (required when trackPageViews is on, which is the default)
});

// That's it. Errors are now captured automatically.

React integration

import React from 'react';
import ReactDOM from 'react-dom/client';
import { getBrowsonic } from '@browsonic/sdk';
import App from './App';

const sdk = getBrowsonic();
sdk.init({
  apiEndpoint:   import.meta.env.VITE_BROWSONIC_API,
  appKey:        import.meta.env.VITE_BROWSONIC_APP_KEY,
  apiKey:        import.meta.env.VITE_BROWSONIC_API_KEY,
  environment:   import.meta.env.MODE,
  clientVersion: import.meta.env.VITE_GIT_SHA,
  debug:         import.meta.env.DEV,
});

ReactDOM.createRoot(document.getElementById('root')!).render(
  <React.StrictMode>
    <App />
  </React.StrictMode>
);

Framework-specific adapters (@browsonic/react, @browsonic/vue, @browsonic/svelte, @browsonic/angular, @browsonic/nextjs, @browsonic/astro, @browsonic/remix) add router instrumentation and navigation breadcrumbs on top of the core SDK. See the framework adapter guides for install and quick-start code for each one.

Configuration

Every option init() honours on @browsonic/sdk 3.27, grouped by purpose. Defaults are the SDK's own; the server can lower sampleRate and the replay ceiling at runtime, never raise them.

Required

Environment & release

Sampling & consent

Page views & App Atlas

Timeline & network

Redaction

Web Vitals, replay & widget

Transport & diagnostics

Hooks

Ignore rules & guards

Accepted, but no longer configurable

Since SDK 3.25.0 these keys are internal constants. init() still accepts them for compatibility, names the ones you set once on the console, and ignores them — each was a tuning number no deployment could get right (a 1 ms flush interval or a batch size of 0 used to switch error tracking off with a single console line as the only sign):flushIntervalMs, requestTimeoutMs, maxBatchSize, cooldownMs, maxPayloadBytes, errorStormThreshold, errorStormWindowMs, errorStormCooldownMultiplier, internalDiagnosticsIntervalMs, maxStackFrames, maxQueueSize, maxValueLength, maxTelemetryEntries.

Complete example

import { COMMON_THIRD_PARTY_PATTERNS } from '@browsonic/sdk';

sdk.init({
  // Required
  apiEndpoint: 'https://api.browsonic.com',
  appKey:      'my-production-app',
  apiKey:      'pk_live_…',

  // Environment
  environment:   'production',
  clientVersion: 'v2.1.0',
  debug:         false,

  // Batching
  flushIntervalMs: 10000,
  maxBatchSize:    25,

  // Deduplication
  cooldownMs: 60000,

  // Capture
  captureLevels: ['warn', 'error'],

  // Queue
  maxQueueSize: 300,
  persistQueue: true,

  // Privacy
  redactKeys: ['token', 'password', 'secret'],

  // Ignore Rules (filter noise)
  ignoreExtensions:   true,
  ignoreScriptErrors: true,
  ignorePatterns:     COMMON_THIRD_PARTY_PATTERNS,
  ignoreMessages:     ['ResizeObserver loop'],
});

API Reference

All methods available on the SDK instance.

captureMessage(message, level?)

Capture a message manually. level defaults to info.

sdk.captureMessage('User completed checkout', 'info');
sdk.captureMessage('Payment failed', 'error');

captureError(error)

Capture an Error instance manually.

try {
  await riskyOperation();
} catch (error) {
  sdk.captureError(error as Error);
}

setUser(user) · clearUser()

Attach a user context to all subsequent events. Sensitive keys (token / password / secret / auth) are redacted before transport.

sdk.setUser({
  id: 'user-123',
  email: 'user@example.com',
  plan: 'premium',
});

// On logout
sdk.clearUser();

addMetadata(key, value) · removeMetadata(key) · clearMetadata()

Attach custom key/value pairs to every subsequent event.

sdk.addMetadata('feature', 'checkout');
sdk.addMetadata('cartValue', 99.99);
sdk.addMetadata('isNewUser', true);

sdk.removeMetadata('feature');
sdk.clearMetadata();

identify(subscriber) · clearIdentity()

Declares which subscriber this browser belongs to — the person behind the account — and keys the cross-app user journey (Professional).setUser describes the account in your own system;identify names the person.

trackPageView(route?, options?)

Reports a page view, optionally with a route template such as/users/:id. Automatic with trackPageViews; use it with manualPageViews: true when your router owns navigation.

addBreadcrumb(breadcrumb) · setTag(key, value) · setContext(name, ctx) · setExtra(key, value)

Attach a manual timeline entry, an indexed key/value, a named object of structured context, or a free-form value to every subsequent event. Each has a matching remove… / clear….

newSession() · getSessionHealth() · markSessionCrashed()

Sessions end after 30 minutes without telemetry, on destroy()and on clearIdentity(); newSession() ends one in place. getSessionHealth() answers 'ok','errored' or 'crashed';markSessionCrashed() declares the session unrecoverable.

enterCriticalPath(options) · exitCriticalPath() · isInCriticalPath()

Marks a business-critical flow (checkout, sign-up) so errors inside it are weighted and surfaced as such.

register(plugin) · updateConfig(partial)

register adds an opt-in plugin and must be called beforeinit(). updateConfig changes config at runtime; keys a collector snapshots at install are refused with a console message.

Lifecycle: flush(), pause(), resume(), destroy()

Event Types

Built-in event types captured by the SDK.

Wire format

interface BrowsonicEvent {
  eventId:    string;          // Unique UUID
  timestamp:  string;          // ISO 8601
  type:       EventType;
  level:      EventLevel;
  message:    string;
  stack?:     string | null;
  context:    EventContext;    // url, referrer, pageAge
  telemetry?: Timeline;        // events leading up to error
  metadata?:  MetadataEntry[];
}

interface EventBatch {
  batchId:        string;
  timestamp:      string;
  appKey:         string;
  environment:    string;
  clientVersion?: string;
  sessionId:      string;
  sessionContext: SessionContext;
  user?:          UserContext;
  events:         BrowsonicEvent[];
}

Telemetry Timeline

Chronological events leading up to each error — the debugging context that turns a stack trace into a story.

Categories

How it works

1. The SDK collects events in a ring buffer (FIFO, configurable size).
2. When an error fires, the last N events ship with the error payload.
3. The dashboard renders the timeline in the Timeline tab of each event.
4. It answers the only question that matters: what happened right before this error?

Configuration

sdk.init({
  apiEndpoint: 'https://api.browsonic.com',
  appKey: 'my-app',
  apiKey: 'pk_live_…',

  // Telemetry Timeline
  maxTelemetryEntries: 50,    // ring buffer size (default 20)
  includeTelemetry:    true,  // attach with errors (default true)

  // Network telemetry
  captureXHR:        true,
  networkTelemetry: true,

  // Navigation
  trackNavigation: true,

  // Visitor (see Visitor Tracking)
  trackVisitor: false,        // OFF by default for privacy
});

Visitor Tracking

Track user interactions (clicks, inputs) in a privacy-safe manner.

What is collected

What is never collected

• Actual input values (e.g. "john@example.com").
• Password field content — completely skipped.
• Credit card numbers.
• Any typed text content.

Configuration

sdk.init({
  trackVisitor: true,
  visitor: {
    click: true,           // track click events
    input: true,           // track input events
    inputThrottleMs: 500,  // throttle (default 500 ms)
  },
});

Session Replay

Reconstruct what the user saw and did in the moments around an error — a DOM-level recording that plays back next to the stack trace. Session Replay is an opt-in plugin; it is not part of the default SDK.

Setup

Import the plugin from the @browsonic/sdk/replaysub-path and register it before init(), exactly like any other plugin.

import { getBrowsonic } from '@browsonic/sdk';
import { sessionReplayPlugin } from '@browsonic/sdk/replay';

const sdk = getBrowsonic();

// Register the plugin BEFORE init().
sdk.register(sessionReplayPlugin());

sdk.init({
  apiEndpoint: 'https://api.browsonic.com',
  appKey: 'web',
  apiKey: 'pk_live_…',
  clientVersion: '1.0.0',
});

Masking defaults

Recording is privacy-first by default — matching Sentry parity. You have to loosen masking deliberately; you never have to remember to turn it on.

sdk.register(sessionReplayPlugin({
  maskAllText:   true,  // default — mask every text node (Sentry parity)
  maskAllInputs: true,  // default — password inputs stay masked even if false
  blockAllMedia: true,  // default — images / video / canvas become placeholders
  blockSelector: '.pii', // extra elements to block, rendered as a sized box
}));

Recordings are kept for 90 days on Professional and30 days on Enterprise, in a per-workspace store of5 GiB (Professional) or 10 GiB(Enterprise) — the numbers your workspace is on are shown underSettings → Session Replay. When the store passes 90 % the SDK is told to record a smaller sample, and at 100 % it stops recording rather than upload segments ingest would refuse; the dashboard says so on the Replay page.

The active sample ceiling is controlled from the dashboard underSettings → Session Replay — there is no server-bypassing replay switch in the browser.

Web Vitals

Report Core Web Vitals from real sessions. Like Session Replay, it is an opt-in plugin: the collector is a small native PerformanceObserver, but it changes what the SDK reports, so you turn it on consciously.

Setup

webVitalsPlugin is exported from the main@browsonic/sdk entry. Register it beforeinit().

import { getBrowsonic, webVitalsPlugin } from '@browsonic/sdk';

const sdk = getBrowsonic();

// Register BEFORE init(). Not in the default plugin set —
// you opt in explicitly.
sdk.register(webVitalsPlugin());

sdk.init({
  apiEndpoint: 'https://api.browsonic.com',
  appKey: 'web',
  apiKey: 'pk_live_…',
  clientVersion: '1.0.0',
});

What it collects

Each sample carries the route it was measured on, and since SDK 3.27 the attribution above plus long-animation-frame breadcrumbs, so a slow score points at a component rather than a page.

Samples surface in the dashboard on the Performance page. A per-session cap (maxSamples, default 30) guards against runaway observers in long-lived SPAs.

Source Maps

Ship minified bundles and still read original TypeScript in every stack frame. @browsonic/build-tools provides bundler plugins for Vite, Webpack, Rollup and esbuild that emit and upload source maps to Browsonic at build time.

Vite plugin

Emit hidden source maps (generated, uploaded, but not referenced from the shipped bundle) and add the plugin. Webpack, Rollup and esbuild use the matching sub-path (@browsonic/build-tools/webpack, /rollup,/esbuild).

import { defineConfig } from 'vite';
import { browsonicSourceMaps } from '@browsonic/build-tools/vite';

export default defineConfig({
  // Emit hidden maps: symbolication works, but the map URL is
  // NOT referenced from the shipped bundle.
  build: { sourcemap: 'hidden' },
  plugins: [
    browsonicSourceMaps({
      appKey:  'web',
      release: '1.0.0', // MUST equal the SDK's clientVersion
      // token: process.env.BROWSONIC_SOURCEMAP_TOKEN (default)
      baseUrl: 'https://api.browsonic.com',
    }),
  ],
});

Upload token

Uploads authenticate with a dedicated source-map token. It is abuild-time secret — read fromBROWSONIC_SOURCEMAP_TOKEN when thetoken option is omitted. Never inline it into browser code. If the token is missing, the plugin prints a warning and skips the upload rather than failing the build.

# Build-time secret — mint under Settings → Source Maps in the
# dashboard. Never expose this in the browser bundle.
export BROWSONIC_SOURCEMAP_TOKEN=bsm_…

Privacy & Security

How Browsonic handles sensitive data and what compliance posture you inherit by default.

Data collection summary

Privacy-safe defaults

Automatic redaction

These keys are automatically redacted inlocalStorage, sessionStorage, cookies, and user context:

const DEFAULT_REDACT_KEYS = [
  'token', 'password', 'authorization',
  'secret', 'key', 'credential', 'auth',
];

sdk.init({
  redactKeys: [
    ...DEFAULT_REDACT_KEYS,
    'ssn',
    'creditCard',
    'bankAccount',
  ],
  redactCookieNames: ['session_id', 'csrf_token'],
});

Pattern-based redaction

In addition to key-based redaction, the SDK scans free-text values (error messages, telemetry payloads, captured network metadata) and replaces matches with [REDACTED]:

HTTP header filtering

Network telemetry captures only headers on an explicit allowlist — everything else is dropped. A hard blocklist (authorization, cookie, set-cookie, token, api-key, password, …) is dropped even if a user tries to add it to the allowlist. Header values are also passed through pattern redaction as defense in depth.

Compliance

For the full security policy — how to report a vulnerability, response targets, scope and the current state of npm release provenance — see the security page.

Troubleshooting

Common issues and how to resolve them.

SDK not capturing events

1. Check initialization — sdk.getState() should return "running".
2. Enable debug mode: sdk.updateConfig({ debug: true }).
3. Verify captureLevels includes the event type you expect.

Events not reaching the server

1. Check pending count — sdk.getPendingCount().
2. Force flush — await sdk.flush().
3. Verify apiEndpoint is correct and CORS is configured.
4. Check the Network tab for 4xx / 5xx responses.

High event volume

1. Increase cooldown — cooldownMs: 300000 (5 minutes).
2. Reduce capture levels — captureLevels: ['error'].
3. Increase flush interval — flushIntervalMs: 60000.