@signal-js/browser

Signal SDK for browsers — session replay, network monitoring, and analytics.

Installation

npm install @signal-js/browser
# or
pnpm add @signal-js/browser
# or
yarn add @signal-js/browser

CDN

<!-- Full bundle (includes rrweb) -->
<script src="https://unpkg.com/@signal-js/browser/dist/signal-full.global.js"></script>
<script>
  const signal = SignalSDK.createSignal({ endpoint: '...', apiKey: '...', projectId: '...' });
  signal.start();
</script>

Quick Start

import { createSignal } from '@signal-js/browser';

const signal = createSignal({
  endpoint: 'https://your-api.com/events',
  apiKey: 'your-api-key',
  projectId: 'your-project-id',
  enableSessionReplay: true,
  enableNetworkCapture: true,
  enableConsoleCapture: true,
});

await signal.start();
signal.capture('button_clicked', { buttonId: 'submit' });

window.addEventListener('beforeunload', () => signal.flush());

Features

Session Replay

Records user interactions using rrweb.

createSignal({
  enableSessionReplay: true,
  sessionRecordingMasking: { maskAllInputs: true },
});

Network Capture

createSignal({
  enableNetworkCapture: true,
  networkCaptureOptions: {
    recordHeaders: true,
    recordBody: ['application/json'],
    sensitiveHeaders: ['authorization', 'cookie'],
    urlDenyList: [/analytics\.google\.com/],
    payloadSizeLimitBytes: 100000,
  },
});

Console Capture

createSignal({
  enableConsoleCapture: true,
  consoleCaptureOptions: {
    levels: ['warn', 'error'],
    captureErrors: true,
    captureUnhandledRejections: true,
  },
});

Configuration

| Option | Type | Default | Description | |--------|------|---------|-------------| | endpoint | string | - | HTTP endpoint for events | | apiKey | string | - | API key for authentication | | projectId | string | - | Project identifier | | compression | boolean | true | Enable gzip compression | | flushInterval | number | 2000 | Flush interval (ms) | | maxBatchSize | number | 50 | Max events per batch | | sessionIdleTimeoutSeconds | number | 1800 | Session idle timeout | | maxSessionLengthSeconds | number | 86400 | Max session length | | enableSessionReplay | boolean | true | Enable rrweb recording | | enableNetworkCapture | boolean | true | Enable network capture | | enableConsoleCapture | boolean | true | Enable console capture | | debug | boolean | false | Enable debug logging |

API

SignalJS

• start(): Promise<void> — Start recording
• stop(): void — Stop recording
• flush(): Promise<void> — Flush pending events
• capture(eventName: string, properties?: object): void — Capture custom event
• identify(distinctId: string, traits?: object): void — Identify user
• group(groupType: string, groupKey: string, properties?: object): void — Associate with group
• pauseRecording(): void / resumeRecording(): void — Pause/resume replay
• dispose(): Promise<void> — Shutdown SDK

Subpath exports

• Main: @signal-js/browser → SDK with rrweb bundled (CJS, ESM, IIFE as SignalSDK). Use this for NPM/bundlers.
• Full: @signal-js/browser/full → Same as main (SDK + rrweb). Use for CDN when you want the same bundle as main.
• Recorder only: @signal-js/browser/recorder → rrweb recorder only (~300KB). Use if you load the SDK separately and want to load rrweb from another script (e.g. /static/recorder.js).

Bundle sizes (approx.)

| File | Description | |------|-------------| | dist/signal.js | SDK + rrweb bundled (~345KB ESM, ~347KB CJS). Default entry; use for NPM. | | dist/signal-full.js | Same as signal.js (SDK + rrweb). Alternative entrypoint; use for CDN. | | dist/recorder.js | rrweb only (~300KB). For loading recorder separately. |

Why both signal.js and signal-full.js? Both include the SDK and rrweb. The main entry (signal) is for NPM/bundlers; signal-full is an alternative entrypoint (e.g. for CDN or when you want to import @signal-js/browser/full). You can use either; they are equivalent. The recorder bundle is for advanced use when you load rrweb from a separate script.

Browser support

Chrome 80+, Firefox 78+, Safari 14+, Edge 80+.

License

MIT