Documentation

Getting Started

Tracebck SDK is a lightweight browser library that records user sessions automatically. Sessions are sent to the Tracebck API and can be replayed in your dashboard. The SDK captures DOM mutations, mouse movements, clicks, scrolls, and network requests with minimal performance overhead.

Installation

npm / yarn

$ npm install tracebck-sdk

Script tag (CDN)

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

Quick Start

The minimal setup to start recording sessions:

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

// Initialize with your API key
init({
  apiKey: 'sk_your_api_key',
});

// Start recording a session
startSession({
  identifier: {
    type: 'email',
    value: '[email protected]',
  },
});

Configuration

The init() function accepts the following options:

init({
  apiKey: 'sk_your_api_key',
  maskAllInputs: true,
  captureNetwork: true,
  captureConsole: true,
  options: {
    sampling: {
      mousemove: false,       // Disable mouse tracking
      scroll: 150,            // Throttle scroll events (ms)
      input: 'last',          // Only record last input value
    },
    blockClass: 'no-record',  // Exclude elements with this class
  },
});

Starting a Session

The startSession() function creates a session on the server and begins recording DOM events. It must be called after init(). If a session is already active, it will be stopped automatically before starting the new one.

Parameters

Basic usage

startSession({
  identifier: {
    type: 'email',
    value: '[email protected]',
  },
});

With custom metadata

Attach any extra data to help you filter and understand sessions in the dashboard:

startSession({
  identifier: {
    type: 'custom',
    value: 'user_12345',
  },
  metadata: {
    plan: 'pro',
    companyId: 'acme-corp',
    source: 'onboarding',
  },
});

Auto-collected metadata

The SDK automatically captures the following metadata for every session. Your custom metadata is merged on top:

Privacy & Sensitive Data

Tracebck provides built-in privacy controls to protect sensitive user data during recording. You can mask text, hide entire elements, or block all inputs with minimal configuration.

Default behavior

By default, password fields are always masked automatically. All other inputs and text content are recorded as-is unless you opt in to masking.

Mask all inputs

Set maskAllInputs: true in init() to replace every input value with *** in the replay:

init({
  apiKey: 'sk_your_api_key',
  maskAllInputs: true,
});

Mask specific input types

If you don't want to mask every input, you can choose exactly which input types to mask via maskInputOptions inside options. Only password is masked by default — all others are opt-in:

init({
  apiKey: 'sk_your_api_key',
  options: {
    maskInputOptions: {
      password: true,  // already on by default
      email: true,
      tel: true,
      number: true,
      textarea: true,
    },
  },
});

Available types: text, email, tel, number, search, url, textarea, select, color, date, range, month, week, time.

CSS class controls

Add these CSS classes to any HTML element to control how it is recorded:

Example

<!-- Text will show as *** in replay -->
<div class="tracebck-mask">
  SSN: 123-45-6789
  Card: 4111-1111-1111-1111
</div>

<!-- Entire element hidden in replay -->
<section class="tracebck-block">
  Internal admin panel content
</section>

What the user sees vs. what is recorded

Custom class names

You can replace the default class names with your own via the options object:

init({
  apiKey: 'sk_your_api_key',
  options: {
    maskTextClass: 'sensitive',       // Instead of .tracebck-mask
    blockClass: 'no-record',         // Instead of .tracebck-block
    maskTextSelector: '[data-sensitive]', // CSS selector
    blockSelector: '[data-private]',   // CSS selector
  },
});

Network Privacy

When network capture is enabled, Tracebck records request and response data (URLs, headers, bodies) to help you debug issues. Sensitive headers are automatically stripped before any data leaves the browser.

Headers stripped by default

The following headers are always removed from captured network data, even if you don't configure anything:

Exclude URLs from capture

Use networkDenyUrls to skip network requests that match certain patterns. Supports strings (substring match) and regular expressions:

init({
  apiKey: 'sk_your_api_key',
  networkDenyUrls: [
    '/auth',               // Skip any URL containing "/auth"
    '/internal',           // Skip internal endpoints
    /\\.analytics\\.com/,    // Skip third-party analytics (regex)
  ],
});

Custom sanitization

For full control, use the sanitizeRequest callback. It receives each captured network event before it is recorded. Return the modified event, or null to drop it entirely:

init({
  apiKey: 'sk_your_api_key',
  sanitizeRequest: (event) => {
    // Drop payment requests entirely
    if (event.url.includes('/payments')) return null;

    // Strip response body from auth endpoints
    if (event.url.includes('/login')) {
      event.responseBody = null;
      event.requestBody = null;
    }

    return event;
  },
});

Event object reference

The sanitizeRequest callback receives an object with these fields:

Console Capture

Tracebck automatically captures console output (console.log, console.warn, console.error, console.info, console.debug), uncaught errors, and unhandled promise rejections. These are displayed in the Console panel alongside the session replay, so you can see exactly what happened in the browser when a user encountered an issue.

What is captured

Disabling console capture

Console capture is enabled by default. To disable it:

init({
  apiKey: 'sk_your_api_key',
  captureConsole: false,
});

Identifying Users

Pass an identifier and optional metadata when starting a session to associate recordings with specific users:

startSession({
  identifier: {
    type: 'email',       // 'email' or 'custom'
    value: '[email protected]',
  },
  metadata: {
    plan: 'pro',
    source: 'landing-page',
  },
});

Stopping a Session

Call stopSession() to end recording and flush any remaining events. The SDK also automatically flushes on page hide and visibility change events.

import { stopSession } from 'tracebck-sdk';

stopSession();

Script Tag Usage

If you are not using a bundler, you can include the SDK via a script tag. The IIFE build exposes a global Tracebck object on window.

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

  Tracebck.startSession({
    identifier: {
      type: 'email',
      value: '[email protected]',
    },
  });
</script>

Framework Examples

React

Initialize the SDK at your app entry point and start a session once the user is available:

// In your App.jsx or main entry
import { init, startSession } from 'tracebck-sdk';

init({ apiKey: 'sk_your_api_key' });

function App() {
  useEffect(() => {
    if (user) {
      startSession({
        identifier: { type: 'email', value: user.email },
      });
    }
  }, [user]);

  return <YourApp />;
}