API Reference

The nveal object provides several methods to control the recording session programmatically.

Methods

init(config)

Initializes the SDK and starts recording.

Parameters: - config: NvealConfig (See Configuration)

Returns: Promise<void>

await nveal.init({
  apiKey: 'your-api-key',
  onReady: () => console.log('Nveal is ready!'),
});

---

stop()

Stops the recording session and flushes any pending events to the server.

Returns: Promise<void>

await nveal.stop();

---

setMetadata(key, value)

Adds or updates metadata for the current session. This is useful for associating sessions with specific users or events.

Parameters: - key: string - value: string | number | boolean

nveal.setMetadata('userId', 'user_12345');
nveal.setMetadata('plan', 'premium');

---

getSessionKey()

Retrieves the unique identifier for the current session. This can be used to link Nveal sessions with your own logging or support systems.

Returns: string | undefined

const sessionId = nveal.getSessionKey();
console.log(`Current Session: ${sessionId}`);

---

isActive()

Checks if the recording is currently active.

Returns: boolean

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

---

addCustomEvent(tag, payload)

Emits 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.

Parameters: - tag: string - payload: any (Usually an object)

Returns: void

// 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, you can listen for these events using the player's custom-event listener to render mock overlays or track milestones.

Type Definitions

NvealConfig

interface NvealConfig {
  apiKey: string;
  apiBaseUrl?: string;
  metadata?: Record<string, string | number | boolean>;
  recordCanvas?: boolean;
  recordConsole?: boolean;
  blockSelector?: string;
  ignoreSelector?: string;
  maskAllText?: boolean;
  maskAllInputs?: boolean;
  sampling?: SamplingConfig;
  batchSize?: number;
  batchInterval?: number;
  onReady?: () => void;
  onError?: (error: Error) => void;
}