Browser SDK

Installation

npm install @debugbundle/sdk-browser

Quick Setup

import DebugBundle from '@debugbundle/sdk-browser';

DebugBundle.init({
  projectToken: 'tok_xxxx',   // Your project token (write-only)
  environment: 'production',
  service: 'my-spa',
});

Calling init() automatically:

• Hooks window.onerror and window.onunhandledrejection
• Registers beforeunload / visibilitychange for unload-safe flushing
• Starts breadcrumb capture (clicks, route changes, console, network)
• Fetches remote config once from the relay or API

Configuration

Transport Resolution

The Browser SDK resolves its transport endpoint in this order:

1. Explicit endpoint — If you set endpoint in config, the SDK uses it directly.
2. Same-origin relay — The SDK probes for a relay handler at /_debugbundle/browser on the current origin. If found, all events route through your backend.
3. Direct API — Falls back to https://api.debugbundle.com/v1/events.

The relay path is preferred because it avoids CORS, ad-blocker interference, and content security policy issues.

Breadcrumbs

Breadcrumbs are a chronological trail of user actions and system events leading up to an error. They attach automatically to every captured exception.

Captured Types

Manual Breadcrumbs

DebugBundle.addBreadcrumb({
  type: 'custom',
  category: 'checkout',
  message: 'Payment form submitted',
  data: { paymentMethod: 'card' },
});

Ring Buffer

The SDK maintains a fixed-size ring buffer (default: 50). When the buffer is full, the oldest breadcrumb is dropped. On exception capture, the entire buffer attaches to the error event.

Network Capture

When captureNetwork is enabled, the SDK intercepts fetch and XMLHttpRequest to log:

• Method and URL
• Response status code
• Duration (ms)
• Request/response content length

Network Filtering

Use networkFilter to control what gets captured:

DebugBundle.init({
  projectToken: 'tok_xxxx',
  captureNetwork: true,
  networkFilter: {
    denyUrls: [/analytics\.example\.com/, /\/health$/],
    allowUrls: [/\/api\//],
    captureRequestHeaders: ['content-type', 'x-request-id'],
    captureResponseHeaders: ['x-request-id'],
    captureRequestBody: false,
    captureResponseBody: false,
  },
});

Sensitive headers (authorization, cookie) are always redacted regardless of allowlist.

Session Controls

Session Sampling

sessionSampleRate determines whether an entire session is captured. The decision is made once when the session starts and persists for that session, so you get either full context or nothing.

DebugBundle.init({
  projectToken: 'tok_xxxx',
  sessionSampleRate: 0.1,  // Capture 10% of sessions
});

Per-Session Event Cap

maxEventsPerSession prevents runaway event volume from a single user session:

DebugBundle.init({
  projectToken: 'tok_xxxx',
  maxEventsPerSession: 50,  // Hard cap per session
});

Session API

// Get current session ID
const sessionId = DebugBundle.getSessionId();

// Reset session (e.g., on logout)
DebugBundle.resetSession();

Trace Correlation

The Browser SDK adds an X-DebugBundle-Trace-Id header to outgoing fetch requests. Your backend SDK reads this header to correlate frontend and backend events into a single incident timeline.

// Automatic — no setup needed if captureNetwork is enabled
// The header is added to all fetch requests to same-origin URLs

// To include cross-origin URLs:
DebugBundle.init({
  projectToken: 'tok_xxxx',
  traceOrigins: ['https://api.example.com'],
});

Device Context

Every event includes automatically collected device context from the browser runtime:

This metadata improves incident triage, but it also increases the amount of browser-identifying context attached to each event. In combination, fields such as user agent, screen size, viewport, language, touch capability, connection type, and color-scheme preference can contribute to browser fingerprinting.

If your privacy posture does not allow that level of client metadata, do not deploy the Browser SDK on those surfaces. There is no field-level device-context toggle today; the safe boundary is to keep capture server-side only or avoid browser instrumentation for the affected application.

Manual Capture

Exceptions

try {
  await riskyClientOperation();
} catch (error) {
  DebugBundle.captureException(error, {
    tags: { component: 'checkout-form' },
  });
}

Logs

DebugBundle.captureLog('Feature flag loaded', 'info', {
  tags: { feature: 'new-checkout' },
});

Context

DebugBundle.setContext('user', { id: '123', plan: 'team' });
DebugBundle.setContext('feature-flags', { newCheckout: true });

Unload-Safe Flushing

The SDK ensures events are delivered even when the user navigates away or closes the tab:

1. visibilitychange → hidden: Triggers immediate flush via navigator.sendBeacon()
2. beforeunload: Fallback flush via fetch() with keepalive: true
3. Beacon payload limit: If the payload exceeds the browser's beacon limit (~64 KB), the SDK splits into multiple beacon calls

No events are lost during normal page navigation, tab close, or browser quit.

Volume Control

The Browser SDK enforces the same storm suppression as the Node SDK:

Combined with sessionSampleRate and maxEventsPerSession, you have three independent layers of volume control.

Trigger Tokens

Trigger tokens let support teams or internal tools force-enable capture for a specific user session, even if that session was excluded by sampling.

// Append ?_dbtoken=<trigger-token> to any page URL
// or programmatically:
DebugBundle.activateTriggerToken('trg_xxxx');

When activated, the SDK overrides sessionSampleRate and enables full capture for the remainder of that session.

Safety Guarantees

The Browser SDK is designed to be invisible to your application:

• Never throws — All SDK code runs inside try/catch. Failures are swallowed silently.
• Never blocks rendering — Event capture and flush are asynchronous.
• Never mutates user data — Events are serialized from copies, never references.
• Minimal bundle size — Tree-shakeable, no heavy dependencies.
• CSP-friendly — No eval(), no inline scripts, no dynamic code generation.

Next Steps

• Node.js SDK — Server-side capture with framework and logger integrations
• SDKs Overview — Universal interface and language support matrix