SessionRecorder - MentiQ Analytics SDK

Overview

The SessionRecorder class provides session recording capabilities using rrweb. It captures DOM events, user interactions, and network activity for later playback.

Session recording requires the rrweb package to be installed: npm install rrweb

Constructor

Creates a new SessionRecorder instance.

new SessionRecorder(
  config: AnalyticsConfig,
  sessionId: string,
  recordingConfig?: RecordingConfig
)

config

AnalyticsConfig

required

Analytics configuration object

sessionId

string

required

Current session ID

recordingConfig

RecordingConfig

Recording-specific configuration

Show properties

maxDuration

number

default:"300000"

Maximum recording duration in milliseconds (default: 5 minutes)

checkoutEveryNms

number

default:"30000"

Take a full snapshot every N milliseconds (default: 30 seconds)

blockClass

string

default:"mentiq-block"

CSS class to block elements from recording

ignoreClass

string

default:"mentiq-ignore"

CSS class to ignore elements

maskAllInputs

boolean

default:"true"

Mask all input values for privacy

maskTextClass

string

default:"mentiq-mask"

CSS class to mask text content

inlineStylesheet

boolean

default:"true"

Inline stylesheets in recordings

collectFonts

boolean

default:"true"

Collect font information

sampling

object

Event sampling configuration

Show properties

mousemove

boolean | number

default:"50"

Sample mousemove events (true/false or interval in ms)

mouseInteraction

boolean | Record<string, boolean>

default:"true"

Sample mouse interaction events

scroll

number

default:"150"

Sample scroll events every N milliseconds

input

'last' | 'all'

default:"last"

Sample input events (only last value or all changes)

Example

import { SessionRecorder } from 'mentiq-sdk';

const recorder = new SessionRecorder(
  {
    apiKey: 'your-api-key',
    projectId: 'your-project-id',
    endpoint: 'https://api.mentiq.io'
  },
  'session-123',
  {
    maxDuration: 600000, // 10 minutes
    maskAllInputs: true,
    blockClass: 'sensitive-data',
    sampling: {
      mousemove: 100,
      scroll: 200
    }
  }
);

Methods

start

Start recording the session.

recorder.start(): void

Behavior

Initializes rrweb and begins capturing events
Sets up automatic upload every 10 seconds
Automatically stops after maxDuration is reached
Does nothing if recording is already active
Only works in browser environments

Example

recorder.start();

Starting a recording will dynamically import the rrweb library. Make sure it’s installed in your project.

stop

Stop recording and upload remaining events.

recorder.stop(): void

Behavior

Stops the rrweb recording
Clears the upload interval
Uploads any remaining events with is_final: true
Resets recording state

Example

recorder.stop();

pause

Pause the recording without stopping it completely.

recorder.pause(): void

Behavior

Stops capturing events temporarily
Clears the upload interval
Does not upload remaining events
Does nothing if not currently recording

Example

// Pause during sensitive operations
recorder.pause();

resume

Resume a paused recording.

recorder.resume(): void

Behavior

Restarts recording from where it was paused
Calls start() internally
Does nothing if already recording

Example

// Resume after sensitive operation
recorder.resume();

isActive

Check if recording is currently active.

recorder.isActive(): boolean

return

boolean

True if recording is active, false otherwise

Example

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

getEventCount

Get the number of events currently queued for upload.

recorder.getEventCount(): number

return

number

Number of events in the upload queue

Example

const count = recorder.getEventCount();
console.log(`${count} events pending upload`);

clearEvents

Clear all queued events without uploading them.

recorder.clearEvents(): void

This will discard events permanently. Use with caution.

Example

// Clear events if user opts out
recorder.clearEvents();

Privacy & Security

Masking Sensitive Data

By default, SessionRecorder masks all input values to protect user privacy. You can control this behavior:

const recorder = new SessionRecorder(config, sessionId, {
  maskAllInputs: true, // Mask all inputs
  maskTextClass: 'sensitive', // Mask elements with this class
  blockClass: 'no-record' // Completely block these elements
});

Example HTML

<!-- This input will be masked -->
<input type="password" />

<!-- This text will be masked -->
<div class="sensitive">Secret information</div>

<!-- This element won't be recorded at all -->
<div class="no-record">Credit card number</div>

PCI Compliance

For PCI compliance, ensure sensitive payment information is blocked:

<!-- Block entire payment form -->
<form class="mentiq-block">
  <input type="text" name="card-number" />
  <input type="text" name="cvv" />
</form>

Automatic Upload

Recordings are automatically uploaded to the MentiQ API:

Upload Interval: Every 10 seconds during recording
Endpoint: POST /api/v1/sessions/:sessionId/recordings
Final Upload: When stop() is called, remaining events are uploaded with is_final: true

Upload Payload

{
  "events": [...], // Array of rrweb events
  "duration": 123, // Recording duration in seconds
  "start_url": "https://example.com/page",
  "user_id": "user-123",
  "is_final": false,
  "event_offset": 0 // Number of events already uploaded
}

Performance Optimization

Sampling

Reduce performance impact by sampling events:

const recorder = new SessionRecorder(config, sessionId, {
  sampling: {
    mousemove: 100,     // Sample every 100ms
    scroll: 150,        // Sample every 150ms
    input: 'last',      // Only record final input value
    mouseInteraction: true
  }
});

Maximum Duration

Limit recording length to control data volume:

const recorder = new SessionRecorder(config, sessionId, {
  maxDuration: 300000 // Stop after 5 minutes
});

Checkpoints

Take full DOM snapshots periodically:

const recorder = new SessionRecorder(config, sessionId, {
  checkoutEveryNms: 30000 // Full snapshot every 30 seconds
});

Complete Example

import { Analytics, SessionRecorder } from 'mentiq-sdk';

// Initialize analytics
const analytics = new Analytics({
  apiKey: 'your-api-key',
  projectId: 'your-project-id',
  enableSessionRecording: false // Manual control
});

// Create custom recorder
const recorder = new SessionRecorder(
  analytics.config,
  analytics.getSessionId(),
  {
    maxDuration: 600000,
    maskAllInputs: true,
    blockClass: 'no-record',
    maskTextClass: 'mask-text',
    sampling: {
      mousemove: 50,
      scroll: 150,
      input: 'last'
    }
  }
);

// Start recording on user consent
function startRecordingWithConsent() {
  if (userHasConsented()) {
    recorder.start();
  }
}

// Pause during sensitive operations
function handleSensitiveForm() {
  recorder.pause();
  // ... handle form
  recorder.resume();
}

// Stop on page unload
window.addEventListener('beforeunload', () => {
  recorder.stop();
});

// Check status
console.log('Recording active:', recorder.isActive());
console.log('Events queued:', recorder.getEventCount());

Types

RecordingConfig

interface RecordingConfig {
  maxDuration?: number;
  checkoutEveryNms?: number;
  blockClass?: string;
  ignoreClass?: string;
  maskAllInputs?: boolean;
  maskTextClass?: string;
  inlineStylesheet?: boolean;
  collectFonts?: boolean;
  sampling?: {
    mousemove?: boolean | number;
    mouseInteraction?: boolean | Record<string, boolean | undefined>;
    scroll?: number;
    input?: 'last' | 'all';
  };
}

RRWebEvent

interface RRWebEvent {
  type: number;
  data: any;
  timestamp: number;
  delay?: number;
}

Browser Compatibility

SessionRecorder requires:

Modern browsers with MutationObserver support
localStorage for state management
Fetch API for uploads

Session recording only works in browser environments. Server-side rendering environments will log a warning if debug mode is enabled.

Core API

Hooks

Components

Types

​Overview

​Constructor

​Example

​Methods

​start

​Behavior

​Example

​stop

​Behavior

​Example

​pause

​Behavior

​Example

​resume

​Behavior

​Example

​isActive

​Example

​getEventCount

​Example

​clearEvents

​Example

​Privacy & Security

​Masking Sensitive Data

​Example HTML

​PCI Compliance

​Automatic Upload

​Upload Payload

​Performance Optimization

​Sampling

​Maximum Duration

​Checkpoints

​Complete Example

​Types

​RecordingConfig

​RRWebEvent

​Browser Compatibility

Build docs developers (and LLMs) love

Overview

Constructor

Example

Methods

start

Behavior

Example

stop

Behavior

Example

pause

Behavior

Example

resume

Behavior

Example

isActive

Example

getEventCount

Example

clearEvents

Example

Privacy & Security

Masking Sensitive Data

Example HTML

PCI Compliance

Automatic Upload

Upload Payload

Performance Optimization

Sampling

Maximum Duration

Checkpoints

Complete Example

Types

RecordingConfig

RRWebEvent

Browser Compatibility