TraceScout

Session Recording API

Control session recording programmatically with these methods.

Starting Recording

TraceScout.startSessionRecording()

Start recording user interactions.

const session = TraceScout.startSessionRecording({
  maskAllInputs: false,
  blockClass: 'sensitive-data'
});

console.log(session);
// {
//   sessionId: "ts_1234567890_abc123",
//   startTime: 1234567890123,
//   status: "recording",
//   stop: Function
// }

Options

| Option | Type | Description | |--------|------|-------------| | maskAllInputs | boolean | Override global input masking | | blockClass | string | Override block class |

Return Value

| Property | Type | Description | |----------|------|-------------| | sessionId | string | Unique session identifier | | startTime | number | Recording start timestamp | | status | string | Current status: 'recording' | | stop | function | Stop this recording |

Stopping Recording

TraceScout.stopSessionRecording()

Stop the current recording and get session summary.

const result = TraceScout.stopSessionRecording();

console.log(result);
// {
//   sessionId: "ts_1234567890_abc123",
//   startTime: 1234567890123,
//   duration: 45000,
//   totalEvents: 156,
//   events: [...],
//   status: "stopped"
// }

Return Value

| Property | Type | Description | |----------|------|-------------| | sessionId | string | Session identifier | | startTime | number | Recording start timestamp | | duration | number | Duration in milliseconds | | totalEvents | number | Total events recorded | | events | array | All recorded events | | status | string | Current status: 'stopped' |

Recording Status

TraceScout.getSessionRecordingStatus()

Get the current recording status.

const status = TraceScout.getSessionRecordingStatus();

console.log(status);
// {
//   available: true,
//   isRecording: true,
//   sessionId: "ts_1234567890_abc123",
//   eventCount: 45,
//   startTime: 1234567890123
// }

Exporting Sessions

TraceScout.exportSessionData()

Export session data in various formats.

// As JSON string (default)
const jsonData = TraceScout.exportSessionData('json');

// As JavaScript object
const objectData = TraceScout.exportSessionData('object');

// As downloadable Blob
const blob = TraceScout.exportSessionData('blob');

TraceScout.exportChunkedSessionData()

Export chunked session data (production mode).

const chunkedData = TraceScout.exportChunkedSessionData('json');

// {
//   sessionId: "ts_1234567890_abc123",
//   startTime: 1234567890123,
//   chunks: [
//     {
//       chunkId: "ts_1234567890_abc123_chunk_0",
//       chunkIndex: 0,
//       events: [...],
//       eventCount: 25,
//       startTime: 1234567890123,
//       endTime: 1234567890456,
//       size: 45678
//     }
//   ],
//   totalChunks: 3,
//   totalEvents: 156
// }

Chunk Management

TraceScout.getSessionChunks()

Get all chunks from the current session.

const chunks = TraceScout.getSessionChunks();
console.log(`Total chunks: ${chunks.length}`);

TraceScout.flushCurrentChunk()

Manually flush the current chunk (uploads immediately).

TraceScout.flushCurrentChunk();

Upload Queue

TraceScout.getUploadQueueStats()

Get upload queue statistics.

const stats = TraceScout.getUploadQueueStats();

// {
//   totalUploaded: 15,
//   totalFailed: 2,
//   totalBytes: 2048576,
//   averageUploadTime: 1250,
//   lastUploadTime: 1234567890456,
//   queueSize: 3,
//   failedQueueSize: 0,
//   isOnline: true,
//   isUploading: false
// }

TraceScout.pauseUploads() / TraceScout.resumeUploads()

Control upload queue processing.

// Pause during low bandwidth
TraceScout.pauseUploads();

// Resume when ready
TraceScout.resumeUploads();

TraceScout.clearUploadQueue()

Clear all pending uploads.

const clearedCount = TraceScout.clearUploadQueue();
console.log(`Cleared ${clearedCount} pending uploads`);

Storage Management

TraceScout.getSessionStorageStats()

Get local storage statistics.

const storageStats = TraceScout.getSessionStorageStats();

// {
//   totalSize: 25165824,        // 24MB
//   sessionCount: 5,
//   totalEvents: 1250,
//   totalChunks: 45,
//   maxStorageSize: 104857600,  // 100MB
//   maxSessions: 20,
//   storageUsagePercent: 24
// }

TraceScout.getStoredSessions()

Get all locally stored sessions.

const sessions = TraceScout.getStoredSessions();

TraceScout.clearSessionStorage()

Clear all local session storage.

TraceScout.clearSessionStorage();

Custom Events

TraceScout.addCustomEvent()

Add a custom event to the session recording.

TraceScout.addCustomEvent('user_action', {
  action: 'button_click',
  buttonId: 'submit-form',
  page: '/checkout'
});

This creates a type 5 (custom) event in the recording:

{
  type: 5,
  data: {
    tag: 'user_action',
    payload: {
      action: 'button_click',
      buttonId: 'submit-form',
      page: '/checkout'
    }
  },
  timestamp: 1234567890123
}

Example: Manual Recording Control

// Initialize without auto-start
TraceScout.init({
  apiKey: 'ts_api_xxx',
  organizationId: 'xxx',
  projectId: 'xxx',
  environment: 'production',
  autoStartRecording: false
});

// Start recording on user action
document.getElementById('start-btn').addEventListener('click', () => {
  TraceScout.startSessionRecording();
});

// Stop and export on another action
document.getElementById('stop-btn').addEventListener('click', async () => {
  const session = TraceScout.stopSessionRecording();
  console.log(`Recorded ${session.totalEvents} events`);
  
  // Export and send to your server
  const data = TraceScout.exportSessionData('json');
  await fetch('/api/sessions', {
    method: 'POST',
    body: data
  });
});

See Also

PreviousTraceScout.init()NextCustom Events