tracebck-sdk

Lightweight session recording SDK for Tracebck. Captures user interactions, DOM changes, and network requests for replay.

Installation

npm install tracebck-sdk

Or via CDN:

<script src="https://unpkg.com/tracebck-sdk/dist/index.iife.js"></script>

Quick Start

ES Modules

import { init, startSession, stopSession } from 'tracebck-sdk';

init({ apiKey: 'sk_your_api_key' });

startSession({
  identifier: { type: 'userId', value: 'user-123' }
});

// When done (e.g. on logout)
stopSession();

Script Tag

<script src="https://unpkg.com/tracebck-sdk/dist/index.iife.js"></script>
<script>
  Tracebck.init({ apiKey: 'sk_your_api_key' });

  Tracebck.startSession({
    identifier: { type: 'userId', value: 'user-123' }
  });
</script>

API

init(config)

Initializes the SDK. Must be called before startSession().

init({
  apiKey: 'sk_your_api_key',
  maskAllInputs: true,
  captureNetwork: true,
  flushInterval: 5000,
  options: { /* rrweb options */ }
});

| Option | Type | Default | Description | |--------|------|---------|-------------| | apiKey | string | required | Your project API key | | maskAllInputs | boolean | false | Replace all input values with * for privacy | | captureNetwork | boolean | true | Capture fetch and XHR requests | | networkDenyUrls | array | [] | URL patterns to exclude from network capture (strings or RegExp) | | sanitizeRequest | function | null | Callback to modify or drop captured network events | | flushInterval | number | 5000 | Interval in ms between event flushes | | options | object | {} | Additional rrweb options |

startSession(config)

Creates a session and starts recording. If a session is already active, it will be stopped first.

startSession({
  identifier: {
    type: 'email',
    value: '[email protected]'
  },
  metadata: {
    plan: 'premium',
    company: 'Acme'
  }
});

| Option | Type | Required | Description | |--------|------|----------|-------------| | identifier.type | string | No | Identifier type ('email', 'userId', etc.). Defaults to 'custom' | | identifier.value | string | Yes | Unique user identifier | | metadata | object | No | Custom metadata attached to the session |

Browser metadata (URL, referrer, userAgent, language, resolution) is captured automatically.

stopSession()

Stops recording, flushes remaining events, and closes the session. Sessions are also automatically stopped and flushed when the page is closed via pagehide.

rrweb Options

Pass additional recording options via the options field in init() to customize recording behavior.

Privacy

Block elements entirely (rendered as grey placeholders in replay):

options: {
  blockClass: 'tracebck-block',  // default: 'tracebck-block'
  blockSelector: '.secret-panel'
}

Mask text content (replaced with *):

options: {
  maskTextClass: 'tracebck-mask',
  maskTextSelector: '.sensitive'
}

Ignore DOM mutations:

options: {
  ignoreClass: 'tracebck-ignore'
}

Granular input masking:

options: {
  maskInputOptions: {
    email: true,
    tel: true,
    password: true  // true by default
  }
}

Performance

options: {
  sampling: {
    mousemove: 100,     // throttle mouse tracking to every 100ms (default: true)
    scroll: 200,        // throttle scroll events to 200ms (default: 150)
    input: 'last'       // only record final input value (default: 'last')
  },
  slimDOMOptions: 'all' // strip scripts, comments, meta tags from snapshots
}

Network Capture

When captureNetwork is enabled (default), the SDK intercepts fetch and XMLHttpRequest calls and records them as replay events. Requests to the Tracebck API are excluded automatically.

Captured per request: method, URL, status code, headers, body (text content types only, max 100KB), and duration.

Sensitive headers (Authorization, Cookie, Set-Cookie, Proxy-Authorization, X-Api-Key, X-CSRF-Token, X-XSRF-Token) are automatically stripped from captured requests for security.

Exclude URLs from capture:

init({
  captureNetwork: true,
  networkDenyUrls: [
    /analytics\.example\.com/,  // RegExp pattern
    'https://tracking.service'  // String pattern
  ]
});

Customize network events before capture:

init({
  captureNetwork: true,
  sanitizeRequest: (event) => {
    // Modify event if needed
    if (event.request?.url.includes('sensitive')) {
      event.request.body = '[REDACTED]';
    }
    // Return modified event, or null to drop it entirely
    return event.request?.url.includes('drop-me') ? null : event;
  }
});

Distribution

| Format | File | Usage | |--------|------|-------| | ESM | dist/index.js | import / bundlers | | CJS | dist/index.cjs | require() | | IIFE | dist/index.iife.js | <script> tag (exposes window.Tracebck) |

License

MIT