@dev-2-dev/websdk-plugin-session-tracker 0.9.0

package/README.md

@@ -0,0 +1,183 @@
+# Session Tracker Plugin for DevToDev WebSDK
+
+A powerful session recording plugin that automatically captures user interactions on your website using advanced screen recording technology. This plugin integrates seamlessly with the DevToDev WebSDK to provide comprehensive session replay capabilities.
+
+## What is Session Recording?
+
+Session recording captures everything a user does on your website - clicks, scrolls, form inputs, and page navigation - allowing you to replay their exact session later. This helps you:
+
+- **Debug Issues**: See exactly what users experienced when they encountered errors
+- **Improve UX**: Understand how users interact with your product
+- **Optimize Conversion**: Identify friction points in user journeys
+- **Support Users**: Reproduce and resolve support tickets more effectively
+
+## Features
+
+- **Automatic Recording**: Records user sessions automatically with minimal configuration
+- **Privacy Controls**: Built-in options to mask sensitive data like passwords
+- **Reliable Delivery**: Ensures session data is sent even when users close the browser
+
+## Installation
+
+### Using NPM
+
+```bash
+npm install @dev-2-dev/websdk-plugin-session-tracker
+```
+
+### Using Yarn
+
+```bash
+yarn add @dev-2-dev/websdk-plugin-session-tracker
+```
+
+## Quick Start
+
+The plugin integrates automatically with the DevToDev WebSDK. Simply enable it in your WebSDK configuration:
+
+```typescript
+import { DTDAnalytics } from '@dev-2-dev/websdk';
+import { D2DWebSessionTracker } from '@dev-2-dev/websdk-plugin-session-tracker';
+
+const sessionTracker = new D2DWebSessionTracker();
+const sdk = new DTDAnalytics();
+
+sdk.initialize('your-app-id');
+sdk.registerPlugin(sessionTracker);
+```
+
+That's it! Session recording will start automatically for eligible sessions based on your DevToDev dashboard configuration.
+
+## Configuration
+
+You can customize the session recording behavior in two ways:
+
+### 1. Recording Options (Constructor Config)
+
+Configure privacy and recording behavior when creating the tracker instance:
+
+```typescript
+import { D2DWebSessionTracker } from '@dev-2-dev/websdk-plugin-session-tracker';
+
+const sessionRecordingConfig = {
+  recordCanvas: true, // Record canvas elements
+  maskAllInputs: false, // Mask all input fields
+  maskInputOptions: {
+    password: true, // Always mask password fields (default: true)
+    email: true, // Mask email fields (default: true)
+    text: false, // Don't mask text inputs (default: false)
+  },
+  blockClass: 'sensitive-field', // Block elements with this class
+};
+
+const sessionTracker = new D2DWebSessionTracker(sessionRecordingConfig);
+```
+
+### 2. Disabling from SDK Config
+
+You can disable session recording through the SDK's `webSessions` configuration:
+
+```typescript
+import { DTDAnalytics } from '@dev-2-dev/websdk';
+
+const sdk = new DTDAnalytics({
+  appId: 'your-app-id',
+  webSessions: {
+    enabled: false, // Disable session recording
+  },
+});
+```
+
+### Configuration Options
+
+These options are passed to the `D2DWebSessionTracker` constructor:
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `recordCanvas` | boolean | `true` | Record canvas elements |
+| `maskAllInputs` | boolean | `false` | Mask all input fields |
+| `maskInputOptions` | object | See below | Selective input masking options |
+| `blockClass` | string | `'sensitive-field'` | CSS class name to block elements from recording |
+
+**Mask Input Options:**
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `password` | boolean | `true` | Always mask password fields |
+| `email` | boolean | `true` | Mask email fields |
+| `text` | boolean | `false` | Mask text inputs |
+
+**Example: Privacy Configuration**
+
+```typescript
+// Option 1: Mask all inputs
+const sessionTracker = new D2DWebSessionTracker({
+  maskAllInputs: true,
+});
+
+// Option 2: Selective masking
+const sessionTracker = new D2DWebSessionTracker({
+  maskAllInputs: false,
+  maskInputOptions: {
+    password: true,  // Mask passwords
+    email: true,     // Mask emails
+    text: false,     // Don't mask text inputs
+  },
+});
+
+// Option 3: Block specific elements
+// Add the 'sensitive-field' class to exclude elements from recording
+```
+
+```html
+<!-- Add the 'sensitive-field' class to exclude elements from recording -->
+<div class="sensitive-field">
+  <p>This content will not be recorded</p>
+</div>
+
+<input type="password" class="sensitive-field" />
+<input type="email" class="sensitive-field" />
+```
+
+## How It Works
+
+1. **Automatic Recording**: When enabled, the plugin automatically starts recording user sessions based on your DevToDev dashboard settings (recording chance, daily/monthly limits).
+
+2. **Event Collection**: The plugin captures user interactions, DOM changes, and page events in real-time.
+
+3. **Batch Upload**: Session data is automatically sent to DevToDev servers in batches when:
+   - A batch size limit is reached (default: 50 events)
+   - A time interval passes (default: 30 seconds)
+   - A maximum batch size is reached (default: 1MB)
+   - The session ends (user closes tab/window)
+
+4. **Storage**: Session data is securely stored in DevToDev's infrastructure and can be accessed through your dashboard.
+
+## Session Recording Controls
+
+The plugin respects configuration settings from your DevToDev dashboard:
+
+- **Recording Chance**: Percentage of sessions to record (e.g., 10% of all sessions)
+- **Daily Limit**: Maximum number of sessions to record per day
+- **Monthly Limit**: Maximum number of sessions to record per month
+- **Active/Blocked**: Global enable/disable toggle
+
+These settings help you control costs and ensure you're only recording the sessions you need.
+
+## Performance Impact
+
+The session tracker plugin is designed to have minimal impact on your website's performance:
+
+- Lightweight recording engine
+- Efficient event batching reduces network requests
+- Automatic session limits prevent memory issues
+- Non-blocking uploads don't affect user experience
+- Optimized DOM observation for minimal overhead
+
+## Support
+
+For issues, questions, or feature requests, please contact DevToDev support or visit our [documentation](https://docs.devtodev.com/).
+
+## License
+
+MIT