Smart Recording

Produck SDK uses a smart recording strategy inspired by PostHog (opens in a new tab) and Amplitude (opens in a new tab). Instead of recording every session in full and sending all data to your server, the SDK intelligently decides what to capture and when to send it.

This dramatically reduces bandwidth, storage costs, and performance impact — while ensuring you always have replay data for the sessions that matter.

How It Works

┌─────────────────────────────────────────────────────┐
│                  User Session                        │
│                                                     │
│  rrweb events → [Circular Buffer (last ~30s)]       │
│                       │                             │
│          ┌────────────┼────────────┐                │
│          ▼            ▼            ▼                │
│     No trigger    Trigger fires   Session ends      │
│     (discard)    (flush buffer)   (check duration)  │
│                       │                    │        │
│                  Send to server    <5s? → discard    │
│                  + continue full         ≥5s? keep  │
└─────────────────────────────────────────────────────┘

The Problem with Always-On Recording

Traditional session replay SDKs record every session:

• 🔴 High bandwidth — DOM mutations, mouse moves, scrolls sent continuously
• 🔴 Storage costs — most sessions are uninteresting (bounces, bots, idle tabs)
• 🔴 Performance impact — serializing DOM on every mutation
• 🔴 Privacy risk — more data captured = more exposure

The Smart Recording Solution

Result: You only store replays for sessions where something interesting happened, with ~30 seconds of context leading up to the trigger.

Recording Modes

'buffered' (Default — Recommended)

rrweb runs in the browser, but events are stored in a circular buffer in memory (default: last 500 events ≈ 30 seconds). No data is sent to your server until a trigger fires.

When a trigger fires:

1. The buffered events are flushed as a retroactive batch (you get context before the trigger)
2. Recording switches to full mode for the rest of the session
3. All subsequent events are sent normally

If no trigger fires, the events are silently discarded when the user leaves — zero network cost.

<ProduckProvider
  config={{
    sdkKey: 'your-key',
    smartRecording: {
      mode: 'buffered',
      triggers: ['chat_opened', 'error', 'rage_click', 'conversion'],
    },
  }}
>

'lightweight'

No rrweb replay at all. Only user-flow events (clicks, navigation, form submissions) are tracked. Minimal bandwidth, minimal performance impact.

Use this when you only need tracking data, not session replays.

smartRecording: {
  mode: 'lightweight',
}

'full'

Classic always-on recording. Every session is recorded and sent in full. This is the old default behavior.

Use this sparingly — for debugging, development, or when you have specific compliance needs.

smartRecording: {
  mode: 'full',
}

'off'

No recording of any kind. User-flow tracking can still be enabled separately.

smartRecording: {
  mode: 'off',
}

Triggers

Triggers determine what events cause the buffer to flush and full recording to begin. You can configure which triggers are active:

Custom Triggers

You can trigger recording from your own code:

// When user reaches checkout
sdk.triggerRecording();
 
// The SDK fires the 'custom' trigger, flushing the buffer

Rage Click Detection

The SDK automatically detects rage clicks — rapid repeated clicks on the same area, indicating user frustration. Configurable:

smartRecording: {
  triggers: ['rage_click'],
  rageClickWindow: 1000,    // Time window in ms (default: 1000)
  rageClickThreshold: 3,     // Min clicks to trigger (default: 3)
}

Circular Buffer

The circular buffer keeps the last N events in memory using a fixed-size ring buffer. When a trigger fires, you get the context leading up to the interesting moment.

smartRecording: {
  bufferSize: 500,  // ~30 seconds of typical activity
}

The buffer overwrites oldest events when full, so memory usage is constant regardless of session length.

Bounce Filtering

Sessions shorter than a minimum duration are automatically discarded. This filters out:

• Users who immediately bounce
• Bots and crawlers
• Accidental page loads

smartRecording: {
  minimumSessionDuration: 5000,  // 5 seconds (default)
}

Set to 0 to disable bounce filtering.

Server-Side Configuration

The SDK can fetch recording configuration from your server, giving you centralized control over recording behavior without deploying SDK changes.

smartRecording: {
  fetchServerConfig: true,  // Enabled by default
}

The SDK calls POST /api/v1/sdk/recording-config on init. Your server can respond with:

{
  "enabled": true,
  "mode": "buffered",
  "samplingRate": 0.5,
  "quotaRemaining": 1000,
  "triggers": ["chat_opened", "error", "rage_click"],
  "minimumSessionDuration": 5000,
  "maxEventsPerSession": 10000,
  "alwaysRecordSegments": [
    { "field": "tags.plan", "operator": "equals", "value": "enterprise" }
  ],
  "neverRecordSegments": [
    { "field": "email", "operator": "contains", "value": "@internal.com" }
  ]
}

What the server can control:

If the endpoint returns a non-200 response or is unreachable, the SDK gracefully falls back to client-side config.

User Segment Targeting

Target recording based on user attributes set via sdk.identify():

smartRecording: {
  userSegments: {
    // Always record enterprise customers in full
    alwaysRecord: [
      { field: 'tags.plan', operator: 'equals', value: 'enterprise' },
      { field: 'domain', operator: 'contains', value: 'bigcorp.com' },
    ],
    // Never record internal team
    neverRecord: [
      { field: 'email', operator: 'contains', value: '@yourcompany.com' },
    ],
  },
}

Segment Rule Operators

Supported Fields

• email — User's email
• identifier — User's unique ID
• domain — User's domain (extracted from email)
• name — User's display name
• tags.* — Any custom tag (e.g., tags.plan, tags.role, tags.company)

Max Events Cap

Prevent runaway recording from consuming excessive resources:

smartRecording: {
  maxEventsPerSession: 10000,  // Default: 10,000 events
}

When the cap is reached, recording stops for that session.

Full Configuration Reference

<ProduckProvider
  config={{
    sdkKey: 'your-key',
    
    smartRecording: {
      // Recording mode
      mode: 'buffered',                    // 'buffered' | 'lightweight' | 'full' | 'off'
      
      // What triggers buffer flush
      triggers: [
        'chat_opened',
        'error',
        'rage_click',
        'conversion',
        // 'slow_page',
        // 'form_abandoned',
        // 'custom',
      ],
      
      // Circular buffer size (events)
      bufferSize: 500,                     // Default: 500 (~30s)
      
      // Discard sessions shorter than this
      minimumSessionDuration: 5000,        // Default: 5000ms (5s)
      
      // Hard cap on events per session
      maxEventsPerSession: 10000,          // Default: 10,000
      
      // Fetch config from server on init
      fetchServerConfig: true,             // Default: true
      
      // Rage click detection
      rageClickWindow: 1000,              // Default: 1000ms
      rageClickThreshold: 3,              // Default: 3 clicks
      
      // Slow page detection threshold
      slowPageThreshold: 3000,            // Default: 3000ms
      
      // User segment targeting (client-side)
      userSegments: {
        alwaysRecord: [],                 // Always record these users in full
        neverRecord: [],                  // Never record these users
      },
    },
  }}
>

Migration from Always-On Recording

If you were previously using recording: { enabled: true } (the old default), no action is needed — the SDK now defaults to smartRecording.mode: 'buffered' which is a transparent upgrade.

To opt back into always-on recording:

smartRecording: {
  mode: 'full',
}

To disable recording entirely:

smartRecording: {
  mode: 'off',
}
// or
recording: { enabled: false },

Related

• Installation — SDK setup guide
• Core Concepts — How the SDK works
• FAQ — Common questions