@nveal/browser

A lightweight, privacy-first session recording SDK for web applications. Capture user sessions and replay them for debugging, analytics, and user experience research.

Getting Your SDK Key

You need an SDK key to use this package. Sign up at nveal.com to create a project and get your API key.

Installation

npm

npm install @nveal/browser

yarn

yarn add @nveal/browser

pnpm

pnpm add @nveal/browser

CDN (Script Tag)

<script src="https://cdn.nveal.com/v1/nveal.js"></script>

Quick Start

ES Modules (React, Vue, Svelte, Angular, etc.)

import { nveal } from '@nveal/browser';

nveal.init({
  apiKey: 'YOUR_SDK_KEY', // Get yours at nveal.com
  metadata: { userId: 'user-123', orderId: 'order-456' },
});

Script Tag

<script src="https://cdn.nveal.com/v1/nveal.js"></script>
<script>
  Nveal.init({
    apiKey: 'YOUR_SDK_KEY',
    metadata: { userId: 'user-123' },
  });
</script>

Configuration

Pass a configuration object to nveal.init(). Only apiKey is required — everything else has sensible defaults.

Full Configuration Reference

| Option | Type | Default | Description | |---|---|---|---| | apiKey | string | required | Your Nveal SDK key from nveal.com | | apiBaseUrl | string | Nveal service URL | Custom API base URL | | metadata | Record<string, string \| number \| boolean> | {} | Custom metadata attached to the session | | recordCanvas | boolean | false | Record <canvas> elements | | recordConsole | boolean | false | Record console logs (log, warn, error, etc.) | | maskAllInputs | boolean | true | Mask all input field values in the recording | | maskAllText | boolean | false | Mask all visible text content | | maskPII | boolean | true | Auto-block PII-sensitive fields (passwords, credit cards, SSNs) | | blockSelector | string | — | CSS selector for elements to block (content hidden, structure preserved) | | ignoreSelector | string | — | CSS selector for elements to completely exclude | | sampling | SamplingConfig | — | Fine-grained event sampling (see Sampling) | | eventBatchSize | number | 50 | Number of events per batch before sending | | batchInterval | number | 5000 | Flush interval in milliseconds | | idleTimeoutMs | number | 300000 (5 min) | Pause flushing after this period of inactivity | | idleBufferCap | number | 500 | Max buffered events during idle (oldest dropped first) | | sessionTimeoutMs | number | 1800000 (30 min) | Start a new session after this inactivity period | | onReady | () => void | — | Callback when recording starts | | onError | (error: Error) => void | — | Callback when an error occurs |

Example: Full Configuration

import { nveal } from '@nveal/browser';

nveal.init({
  apiKey: 'YOUR_SDK_KEY',

  // Metadata
  metadata: { userId: 'user-123', plan: 'pro' },

  // Recording options
  recordCanvas: true,
  recordConsole: true,

  // Privacy
  maskAllInputs: true,
  maskPII: true,
  blockSelector: '.sensitive-data',
  ignoreSelector: '.do-not-record',

  // Performance
  eventBatchSize: 30,
  batchInterval: 3000,
  idleTimeoutMs: 300000,

  // Sampling
  sampling: {
    mousemove: 50,
    scroll: 150,
    input: 'last',
  },

  // Callbacks
  onReady: () => console.log('Nveal recording started'),
  onError: (err) => console.error('Nveal error:', err),
});

API Reference

nveal.init(config)

Initialize and start recording. Validates the SDK key with the Nveal service before recording begins.

await nveal.init({
  apiKey: 'YOUR_SDK_KEY',
  metadata: { userId: 'user-123' },
  onReady: () => console.log('Recording started'),
});

nveal.stop()

Stop recording and flush any remaining buffered events to the server.

await nveal.stop();

nveal.setMetadata(key, value)

Add or update session metadata at runtime. Useful for attaching information that becomes available after init (e.g., after login).

nveal.setMetadata('orderId', 'order-789');
nveal.setMetadata('checkoutStep', 3);

nveal.getSessionKey()

Returns the current session key, or null if not recording.

const sessionKey = nveal.getSessionKey();
console.log('Session:', sessionKey);

nveal.isActive()

Check whether a recording session is currently active.

if (nveal.isActive()) {
  console.log('Recording is running');
}

nveal.addCustomEvent(tag, payload)

Emit a custom event that will be captured in the recording timeline. Use this to capture non-DOM events like alerts, confirms, toasts, or application-level actions.

// Capture an alert before showing it
nveal.addCustomEvent('browser-alert', { message: 'Payment confirmed!' });
alert('Payment confirmed!');

// Capture a custom application event
nveal.addCustomEvent('checkout-step', { step: 3, total: 99.99 });

During replay, listen for these events using rrweb's custom-event listener:

replayer.on('custom-event', (event) => {
  if (event.data.tag === 'browser-alert') {
    showMockAlert(event.data.payload.message);
  }
});

Sampling Configuration

Reduce event volume for better performance on high-traffic pages:

nveal.init({
  apiKey: 'YOUR_SDK_KEY',
  sampling: {
    mousemove: 50,       // Throttle mouse movements to 50ms intervals
    scroll: 150,         // Throttle scroll events to 150ms
    input: 'last',       // Only record final input value (not every keystroke)
    media: 500,          // Throttle media interaction events
    mouseInteraction: {
      Click: true,       // Record clicks
      DblClick: true,    // Record double-clicks
      MouseDown: false,  // Skip mouse-down events
      MouseUp: false,    // Skip mouse-up events
      Focus: true,       // Record focus changes
      Blur: true,        // Record blur events
      TouchStart: true,  // Record touch start
      TouchEnd: true,    // Record touch end
    },
  },
});

Privacy & PII Protection

Nveal ships with privacy-first defaults. No configuration needed for basic protection.

Default Behavior

• All input fields are masked (maskAllInputs: true) — form values are replaced with * characters in the recording.
• PII auto-blocking is enabled (maskPII: true) — fields matching common sensitive patterns (passwords, credit card numbers, SSNs, etc.) are completely blocked from the recording.

Customizing Privacy Settings

nveal.init({
  apiKey: 'YOUR_SDK_KEY',

  // Input masking
  maskAllInputs: true,    // Mask all form field values
  maskAllText: false,     // Keep visible text readable

  // PII protection
  maskPII: true,          // Auto-block sensitive fields

  // Element-level control
  blockSelector: '.sensitive-data',    // Block specific elements (placeholder shown)
  ignoreSelector: '.do-not-record',    // Completely exclude elements from recording
});

Using CSS Selectors

You can also use HTML attributes to control recording per-element:

<!-- This element will be blocked (replaced with placeholder) -->
<div class="sensitive-data">Credit card details here</div>

<!-- This element will be completely ignored -->
<div class="do-not-record">Internal admin controls</div>

Idle Detection

The SDK automatically detects user inactivity and pauses event flushing to save bandwidth. Events continue to be buffered locally and are sent when the user returns.

| Option | Default | Description | |---|---|---| | idleTimeoutMs | 300000 (5 min) | Pause flushing after this idle period | | idleBufferCap | 500 | Max events to buffer during idle (oldest dropped first) | | sessionTimeoutMs | 1800000 (30 min) | Start a new session after prolonged inactivity |

During replay, idle periods appear as fast-forwarded time gaps — the session timeline stays clean and focused on actual user activity.

TypeScript Support

Full TypeScript type definitions are included out of the box. Import types directly:

import type { NvealConfig, SamplingConfig } from '@nveal/browser';

const config: NvealConfig = {
  apiKey: 'YOUR_SDK_KEY',
  recordCanvas: true,
};

Browser Compatibility

The SDK targets ES2020 and works in all modern browsers:

| Browser | Minimum Version | |---|---| | Chrome | 80+ | | Firefox | 78+ | | Safari | 14+ | | Edge | 80+ |

Bundle Formats

| Format | File | Use Case | |---|---|---| | ESM | dist/index.esm.js | Modern bundlers (Vite, Webpack 5, Rollup) | | CJS | dist/index.cjs.js | Node.js / CommonJS environments | | UMD | dist/nveal.umd.js | Script tags, CDN usage |

Development

# Install dependencies
npm install

# Build all formats (ESM, CJS, UMD)
npm run build

# Watch mode for development
npm run dev

# Type check
npm run typecheck

Changelog

See CHANGELOG.md for a detailed history of changes.

License

Copyright (c) 2026 Nveal. All rights reserved. This is proprietary software.