TraceScout.init()

Initialize TraceScout with your configuration. This should be called once, as early as possible in your application.

Basic Usage

TraceScout.init({
  apiKey: 'ts_api_xxx',
  organizationId: 'organization-uuid',
  projectId: 'project-uuid',
  environment: 'production'
});

Required Options

| Option | Type | Description | |--------|------|-------------| | apiKey | string | Your project API key (starts with ts_api_) | | organizationId | string | UUID of your organization | | projectId | string | UUID of your project | | environment | string | Environment name: 'development', 'staging', or 'production' |

Session Recording Options

TraceScout.init({
  // Required options...
  
  // Session Recording
  enableSessionRecording: true,      // Enable/disable recording
  enableSessionChunking: true,       // Enable intelligent chunking
  enableSessionUploads: true,        // Enable background uploads
  autoStartRecording: false,         // Auto-start (dev only)
  
  // Chunking Configuration
  sessionChunkDuration: 60000,       // Chunk every 60 seconds
  sessionMaxChunkSize: 1000000,      // Max 1MB per chunk
});

| Option | Type | Default | Description | |--------|------|---------|-------------| | enableSessionRecording | boolean | true | Enable session recording | | enableSessionChunking | boolean | true | Enable intelligent chunking | | enableSessionUploads | boolean | true | Enable background uploads | | autoStartRecording | boolean | false | Auto-start recording | | sessionChunkDuration | number | 60000 | Chunk interval in ms | | sessionMaxChunkSize | number | 1000000 | Max chunk size in bytes |

Privacy Options

TraceScout.init({
  // Required options...
  
  // Privacy Controls
  recordingMaskAllInputs: true,              // Mask all inputs
  recordingBlockClass: 'tracescout-block',   // Block elements with class
  recordingIgnoreClass: 'tracescout-ignore', // Ignore interactions
  recordingMaskTextClass: 'tracescout-mask', // Mask text content
  
  // Recording Behavior
  recordingRecordCanvas: false,              // Record canvas elements
  recordingCollectFonts: false,              // Collect font data
  recordingInlineStylesheet: true,           // Inline stylesheets
});

Privacy by Default

We recommend enabling recordingMaskAllInputs in production to prevent capturing sensitive user data.

Upload Configuration

TraceScout.init({
  // Required options...
  
  // Upload Settings
  sessionUploadEndpoint: '/api/sessions/upload',
  uploadBatchSize: 3,                  // Batch 3 chunks per upload
  uploadMaxRetries: 5,                 // Retry failed uploads
  uploadRetryDelay: 2000,              // Initial retry delay
  enableUploadCompression: true,       // Compress chunks
  enableOfflineQueue: true,            // Queue when offline
  
  // Authentication
  uploadAuthToken: 'bearer-token',     // Auth token for uploads
  uploadHeaders: {                     // Custom headers
    'X-API-Key': 'your-api-key',
  },
});

Storage Configuration

TraceScout.init({
  // Required options...
  
  // Local Storage
  maxSessionStorageSize: 100 * 1024 * 1024,  // 100MB max
  maxStoredSessions: 20,                      // Keep max 20 sessions
  sessionStorageKey: '__tracescout_sessions__',
});

Event Callbacks

TraceScout.init({
  // Required options...
  
  // Callbacks
  onChunkCreated: (chunk) => {
    console.log(`Chunk created: ${chunk.chunkId}`);
  },
  
  onChunkUploaded: (chunk, response) => {
    console.log(`✅ Uploaded: ${chunk.chunkId}`);
  },
  
  onChunkUploadFailed: (chunk, error) => {
    console.error(`❌ Failed: ${chunk.chunkId}`, error);
  },
  
  onNetworkChange: (isOnline) => {
    console.log(`Network: ${isOnline ? 'Online' : 'Offline'}`);
  },
});

Advanced Configuration

TraceScout.init({
  // Required options...
  
  // Advanced Recording
  recordingConfig: {
    sampling: {
      scroll: 150,      // Throttle scroll events
      mousemove: 50,    // Throttle mousemove
      input: 'last'     // Only record last input value
    },
    recordCrossOriginIframes: false,
    slimDOMOptions: {
      comment: true,
      script: true,
      headFavicon: true,
    }
  },
  
  // Event Processing
  deduplicationWindowMs: 30000,
  maxQueueSize: 1000,
  retryIntervalMs: 5000,
  maxRetries: 3,
  batchSize: 10,
});

Complete Example

TraceScout.init({
  // Identity
  apiKey: 'ts_api_xxx',
  organizationId: 'organization-uuid',
  projectId: 'project-uuid',
  environment: 'production',
  
  // Session Recording
  enableSessionRecording: true,
  enableSessionChunking: true,
  enableSessionUploads: true,
  sessionChunkDuration: 60000,
  sessionMaxChunkSize: 1000000,
  
  // Privacy
  recordingMaskAllInputs: true,
  recordingBlockClass: 'sensitive-data',
  
  // Uploads
  uploadBatchSize: 3,
  uploadMaxRetries: 5,
  enableUploadCompression: true,
  enableOfflineQueue: true,
  
  // Storage
  maxSessionStorageSize: 100 * 1024 * 1024,
  maxStoredSessions: 20,
  
  // Callbacks
  onChunkUploaded: (chunk, response) => {
    console.log(`✅ Chunk ${chunk.chunkId} uploaded`);
  },
});

Return Value

TraceScout.init() returns a Promise that resolves when initialization is complete:

await TraceScout.init({...});
console.log('TraceScout ready!');

Or use the callback style:

TraceScout.init({...}).then(() => {
  console.log('TraceScout ready!');
});