@dysonic/web-replay-sdk-pc

PC/browser replay SDK. Records user sessions via rrweb, captures network requests, route changes, and errors automatically, then exports a ReplayEnvelope that can be played back in a browser viewer.

Installation

npm install @dysonic/web-replay-sdk-pc

Quick Start

import { createLiveWebSdk } from '@dysonic/web-replay-sdk-pc';

const sdk = createLiveWebSdk({
  appName: 'my-app',
  appVersion: '1.0.0',
  maxMinutes: 5,
  reporter: {
    async report({ envelope, reason, extra }) {
      await fetch('/api/replay', {
        method: 'POST',
        body: JSON.stringify({ envelope, reason, extra }),
      });
    },
  },
});

sdk.init();

// Later, when a user reports a bug:
const envelope = await sdk.reportIssue('User clicked submit but nothing happened');

API

createLiveWebSdk(config)

Creates and returns a BrowserSdkInstance. Recording does not begin until init() is called.

interface LiveWebSdkConfig {
  appName: string;
  appVersion: string;
  maxMinutes?: number;          // default: 5, max: 10
  maxBytes?: number;            // default: 5 MB
  maskRules?: MaskRule[];       // CSS-selector-based field masking
  now?: () => number;           // injectable clock (useful in tests)
  reporter?: Reporter;          // called by reportIssue()
  // rrweb options:
  recordCanvas?: boolean;
  inlineStylesheet?: boolean;
  maskAllInputs?: boolean;
  sampling?: Record<string, unknown>;
}

Instance methods

| Method | Description | |---|---| | init() | Start rrweb recording and browser hook registration. Idempotent. | | pause() | Pause buffering (rrweb keeps running). | | resume() | Resume buffering. | | reportIssue(reason?, extra?) | Flush the buffer, call the reporter, and return the ReplayEnvelope. | | destroy() | Tear down all hooks, stop rrweb, clear the buffer. |

Automatic instrumentation

init() registers the following browser hooks transparently:

• window.fetch — records method, URL, HTTP status, and duration.
• XMLHttpRequest — records method, URL, HTTP status, and duration.
• history.pushState / replaceState / popstate — records route changes.
• window.error — records uncaught exceptions.
• unhandledrejection — records unhandled promise rejections.
• document.visibilitychange — records tab visibility transitions.

All hooks are fully removed on destroy().

rrweb adapter

If you need lower-level control, create a standalone rrweb adapter:

import { createLiveRrwebAdapter, createRrwebAdapter } from '@dysonic/web-replay-sdk-pc';
import { record } from 'rrweb';

// Convenience wrapper — uses the live rrweb record() function
const liveAdapter = createLiveRrwebAdapter({ maskAllInputs: true });

// Generic wrapper — supply your own record() implementation
const customAdapter = createRrwebAdapter({ record, rrwebOptions: { maskAllInputs: true } });

Viewer utilities

mountReplayPlayer(target, envelope, options?)

Mounts an rrweb-player instance into a DOM element.

import { mountReplayPlayer } from '@dysonic/web-replay-sdk-pc';

mountReplayPlayer(document.getElementById('player')!, envelope, {
  width: 1024,
  height: 576,
  autoPlay: false,
  showController: true,
});

createReplayHtml(envelope, options?)

Generates a self-contained HTML string that embeds the session and an rrweb-player. Useful for exporting standalone replay files.

import { createReplayHtml } from '@dysonic/web-replay-sdk-pc';

const html = createReplayHtml(envelope, {
  title: 'Bug Report — Checkout Flow',
  rrwebPlayerScriptUrl: 'https://cdn.jsdelivr.net/npm/rrweb-player@latest/dist/index.js',
  rrwebPlayerStyleUrl: 'https://cdn.jsdelivr.net/npm/rrweb-player@latest/dist/style.css',
});

File utilities

import {
  parseReplayFile,
  exportReplayFile,
  createOfflineViewerDocument,
} from '@dysonic/web-replay-sdk-pc';

const envelope = parseReplayFile(jsonString);   // JSON string → ReplayEnvelope
const json = exportReplayFile(envelope);         // ReplayEnvelope → formatted JSON string
const html = createOfflineViewerDocument(envelope); // ReplayEnvelope → standalone HTML

License

MIT