@web-reel/recorder

@web-reel/recorder

Lightweight session recording SDK based on rrweb

📦 Installation

npm install @web-reel/recorder

That's it! rrweb and idb will be automatically installed as dependencies.

🚀 Quick Start

Download Mode (Default)

import { WebReelRecorder } from '@web-reel/recorder';

const recorder = new WebReelRecorder({
  env: 'test',
  appId: 1,
  projectName: 'my-app',
  deviceId: 'user-123',
});

// Export session data as ZIP file (default, smaller size)
await recorder.exportLog();

// Or export as JSON
await recorder.exportLog(true, 'json');

Upload Mode (New!)

import { WebReelRecorder } from '@web-reel/recorder';

const recorder = new WebReelRecorder({
  env: 'test',
  appId: 1,
  projectName: 'my-app',
  deviceId: 'user-123',
  // Upload configuration
  uploadEndpoint: '/api/sessions',
  platform: 'web',
  jiraId: 'ISSUE-123',
});

// Upload session directly to server
await recorder.uploadLog();

When uploadEndpoint is configured, the floating button will automatically switch to upload mode with an upload icon.

Import Session Data

// Import session data from file
const fileInput = document.querySelector('input[type="file"]');
fileInput.addEventListener('change', async (e) => {
  const file = e.target.files[0];
  await recorder.importLog(file);
});

📖 Full Documentation

See docs/usage.md for complete documentation.

🔧 Features

• ✅ DOM events recording via rrweb
• ✅ Network request capture (fetch & XHR)
• ✅ Console logs recording
• ✅ IndexedDB storage
• ✅ ZIP export (60-80% compression)
• ✅ Direct upload to server API
• ✅ Import/Export sessions
• ✅ Automatic mode switching (download/upload)
• ✅ JSON export (legacy support)
• ✅ SSR compatible (Next.js, Nuxt, etc.)
• ✅ TypeScript support
• ✅ Webpack 5 compatible
• ✅ Zero polyfills required

📝 Configuration Options

Option	Type	Required	Description
env	'test' | 'online'	Yes	Environment identifier
appId	number	Yes	Application ID
projectName	string	Yes	Unique project identifier
deviceId	string	No	Device identifier
disabledDownLoad	boolean	No	Hide the floating button (default: false)
recordInterval	number	No	Log retention in days (default: 2)
enableStats	boolean	No	Enable statistics upload (default: false)
uploadEndpoint	string	No	API endpoint for upload (e.g. '/api/sessions')
uploadHeaders	Record<string, string>	No	Custom headers for upload requests
platform	string	No	Platform identifier for metadata (e.g. 'web', 'mobile')
jiraId	string	No	Jira ticket ID for metadata

🌐 Server API Integration

The recorder can upload sessions directly to your server. Your server should implement the following endpoint:

POST /api/sessions

Request format: multipart/form-data

Field	Type	Required	Description
file	File	Yes	ZIP file containing session data
platform	String	No	Platform identifier
device_id	String	No	Device identifier
jira_id	String	No	Jira ticket ID

Response format:

{
  "success": true,
  "session": {
    "id": 123,
    "created_at": "2024-01-15T10:30:00.000Z"
  }
}

See the main project documentation for complete API specification.

📄 License

MIT