Skip to content

Configuration

The nveal.init() method accepts a configuration object. Below is a quick-reference table of every available option, followed by in-depth use-case explanations for each group.

Quick Reference

Option Type Default Description
apiKey string — Required. Your project's API key.
apiBaseUrl string Nveal servers Override the API endpoint (e.g. for a proxy).
metadata Record<string, string \| number \| boolean> {} Custom key-value data attached to every session.
maskAllInputs boolean true Mask all input field values in the recording.
maskAllText boolean false Mask all visible text on the page.
maskPII boolean true Auto-detect and block known PII fields (passwords, credit cards, SSNs).
blockSelector string — CSS selector for elements to show as empty placeholders.
ignoreSelector string — CSS selector for elements to exclude entirely from recording.
idleTimeoutMs number 300000 (5 min) Milliseconds of inactivity before the SDK pauses sending events.
onReady () => void — Callback fired when the SDK has initialised successfully.
network boolean \| object false Optional. Enable and configure network (XHR/fetch) recording. Read more
recordConsole boolean false Optional. Enable recording of console outputs. Read more
recordCanvas boolean false Optional. Enable recording of <canvas> elements.
sampling SamplingConfig — Optional. Fine-grained event sampling controls.
onError (error: Error) => void — Callback fired if the SDK encounters an error.

Privacy Controls

Nveal is built privacy-first. All privacy options stack — you can combine them for maximum protection.

PII Auto-Detection (maskPII)

Enabled by default. The SDK automatically detects fields that typically contain sensitive data — passwords, credit card numbers, social security numbers, and similar — and blocks them entirely from the recording. The field appears as a placeholder in the replay; the value is never sent to Nveal's servers.

nveal.init({
  apiKey: 'YOUR_API_KEY',
  maskPII: true, // Default: true — recommended to leave on
});

Use case: A fintech app with a payment form. Even if a developer forgets to manually block the credit card field, maskPII: true ensures it is never captured.

Mask All Inputs (maskAllInputs)

Replaces every character typed into any input, textarea, or select element with a * in the recording. The user's keystrokes are never stored.

nveal.init({
  apiKey: 'YOUR_API_KEY',
  maskAllInputs: true,  // Default: true
});

Use case: A healthcare portal where any field could contain PHI (protected health information). Masking all inputs provides a blanket compliance guarantee.

Mask All Text (maskAllText)

Replaces all visible text on the page with * characters. This is the most aggressive privacy setting and should only be used for highly sensitive pages.

nveal.init({
  apiKey: 'YOUR_API_KEY',
  maskAllText: true,  // Default: false
});

Use case: A banking account summary page where balances, account numbers, and names are all displayed. Enable maskAllText on this specific page only using the start/stop API.

Blocking Elements (blockSelector)

Replaces a matched element's content with an empty placeholder in the replay. The element's size and position are preserved, but nothing inside is visible. Accepts any valid CSS selector.

nveal.init({
  apiKey: 'YOUR_API_KEY',
  blockSelector: '#credit-card-form, .sensitive-data, [data-nveal-block]',
});

Use case: An e-commerce checkout page where you want to replay the full shopping flow but never capture the payment section. Block the #payment-form element.

Tip

You can also add the attribute data-nveal-block directly to any HTML element and it will be automatically blocked — no code change needed.

Ignoring Elements (ignoreSelector)

Completely removes matched elements from the recording. Unlike blockSelector, ignored elements leave no placeholder — they are as if they never existed in the DOM.

nveal.init({
  apiKey: 'YOUR_API_KEY',
  ignoreSelector: '.chat-widget, #support-bubble',
});

Use case: A third-party live chat widget that is irrelevant to your UX analysis. Ignoring it keeps replays clean and reduces data volume.

Session Metadata (metadata)

Attach custom key-value data to every session. This data is searchable and filterable in the Nveal Dashboard, making it easy to find sessions for a specific user, plan, or environment.

nveal.init({
  apiKey: 'YOUR_API_KEY',
  metadata: {
    userId: 'user_12345',
    plan: 'pro',
    environment: 'production',
    appVersion: '3.2.1',
  },
});

Use case: A SaaS product wants to find all sessions from users on the "trial" plan who reached the upgrade page. Filter sessions in the dashboard by plan: 'trial' and page: '/upgrade'.

Note

You can also add metadata dynamically after initialization using the nveal.setMetadata() method — useful for metadata that is only available after login.

Idle Detection

When a user stops interacting with the page (no mouse, keyboard, scroll, or touch events), the SDK automatically pauses sending events to the server to save bandwidth. Events continue to buffer locally and are flushed as soon as activity resumes.

In the session replay, the idle gap is preserved as a fast-forward section — you'll see the timer skip ahead rather than a frozen screen. This keeps replays accurate without wasting storage on empty time.

nveal.init({
  apiKey: 'YOUR_API_KEY',
  idleTimeoutMs: 120000, // Pause after 2 minutes of inactivity (default: 5 minutes)
});

Set idleTimeoutMs: 0 to disable idle detection entirely and always stream events.

Tip

Lowering idleTimeoutMs is useful for apps where sessions are typically short and focused (e.g. checkout flows, onboarding). The default 5-minute value is well-suited for dashboards and content-heavy pages where users often read without interacting.

Sampling (sampling)

Fine-grained control over how often events are recorded. This is highly useful for optimizing performance and reducing bandwidth on high-traffic pages.

nveal.init({
  apiKey: 'YOUR_API_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)
  },
});

Use case: A complex canvas or WebGL game UI where the user is constantly moving the mouse. Throttling mousemove to 50 keeps the recording smooth while drastically reducing the number of events. Setting input: 'last' is great for long forms where you only care about what was submitted, not every typo.

Canvas Recording (recordCanvas)

Nveal natively supports recording <canvas> element mutations by taking periodic base64 snapshots. No extra plugins are required.

nveal.init({
  apiKey: 'YOUR_API_KEY',
  recordCanvas: true, // Default: false
});

Use case: A charting dashboard or drawing application. Enabling recordCanvas ensures that you can see exactly what graphs or images the user generated on the canvas, which would otherwise appear blank in standard DOM replays.

onReady

Called once the SDK has successfully validated the API key and begun recording.

nveal.init({
  apiKey: 'YOUR_API_KEY',
  onReady: () => {
    console.log('Nveal is recording. Session ID:', nveal.getSessionKey());
  },
});

onError

Called if the SDK fails to initialize — for example, if the API key is invalid or the domain is not allowlisted.

nveal.init({
  apiKey: 'YOUR_API_KEY',
  onError: (error) => {
    // Send to your own error tracking system
    myErrorTracker.capture(error, { source: 'nveal-sdk' });
  },
});

Advanced: API Proxy (apiBaseUrl)

Override the default Nveal API endpoint. This is useful if you route SDK traffic through your own server or a CDN worker to prevent ad-blockers from intercepting requests.

nveal.init({
  apiKey: 'YOUR_API_KEY',
  apiBaseUrl: 'https://telemetry.your-company.com',
});

Your proxy must forward requests to https://api.nveal.com and pass through the x-api-key header.