alphard-session-replay

Official Alphard Session Replay SDK for recording and replaying user sessions with automatic user identification.

Features

• ✅ Automatic User Identification - Detects and tracks users automatically
• ✅ Easy Integration - One-line setup with any framework
• ✅ Privacy First - Automatic masking of sensitive data
• ✅ Lightweight - Minimal performance impact
• ✅ Framework Agnostic - Works with React, Vue, Angular, vanilla JS, etc.

Installation

npm install alphard-session-replay

Quick Start

Basic Usage (with Auto-Identification)

import Alphard from 'alphard-session-replay';

Alphard.init({
  projectKey: 'YOUR_PROJECT_KEY',
  autoIdentify: true,
  getUserInfo: () => {
    // Return user info if available, or null
    const user = getCurrentUser();
    return user ? {
      id: user.id,
      name: user.name,
      email: user.email
    } : null;
  }
});

That's it! Sessions will be recorded AND users will be automatically identified.

Platform-Specific Examples

React / Next.js

import { useEffect } from 'react';
import { useUser } from '@clerk/clerk-react';
import Alphard from 'alphard-session-replay';

function App() {
  const { user } = useUser();
  
  useEffect(() => {
    Alphard.init({
      projectKey: process.env.NEXT_PUBLIC_ALPHARD_KEY!,
      autoIdentify: true,
      getUserInfo: () => user ? ({
        id: user.id,
        name: `${user.firstName} ${user.lastName}`,
        email: user.primaryEmailAddress?.emailAddress
      }) : null
    });
  }, [user]);

  return <YourApp />;
}

Vue.js

import { createApp } from 'vue';
import Alphard from 'alphard-session-replay';
import { useAuthStore } from './stores/auth';

const authStore = useAuthStore();

Alphard.init({
  projectKey: 'YOUR_PROJECT_KEY',
  autoIdentify: true,
  getUserInfo: () => {
    const user = authStore.currentUser;
    return user ? {
      id: user.id,
      name: user.name,
      email: user.email
    } : null;
  }
});

createApp(App).mount('#app');

Vanilla JavaScript

<script src="https://unpkg.com/alphard-session-replay"></script>
<script>
  Alphard.init({
    projectKey: 'YOUR_PROJECT_KEY',
    autoIdentify: true,
    getUserInfo: () => {
      if (window.currentUser) {
        return {
          id: window.currentUser.id,
          name: window.currentUser.name,
          email: window.currentUser.email
        };
      }
      return null;
    }
  });
</script>

Configuration Options

Alphard.init({
  // Required
  projectKey: string;
  
  // Auto-Identification
  autoIdentify?: boolean;              // Default: false
  getUserInfo?: () => UserInfo | null;
  
  // Privacy
  maskAllInputs?: boolean;             // Default: false
  maskSelectors?: string[];            // Default: []
  blockSelectors?: string[];           // Default: []
  
  // Sampling
  sampleRate?: number;                 // Default: 1.0 (100%)
  
  // Performance
  capturePageSnapshots?: boolean;      // Default: true
  snapshotOnRouteChange?: boolean;     // Default: true
  maxMousemoveFps?: number;            // Default: 10
  
  // Features
  captureConsole?: boolean;            // Default: false
  captureNetwork?: boolean;            // Default: false
  
  // Advanced
  apiUrl?: string;                     // Default: 'http://localhost:5001/api'
  consent?: boolean;                   // Default: true
  shouldRecord?: (userInfo) => boolean;
  
  // Callbacks
  onSessionStart?: (sessionId: string) => void;
  onSessionEnd?: (sessionId: string) => void;
});

API Reference

init(config: AlphardConfig)

Initialize Alphard Session Replay.

const replay = Alphard.init({
  projectKey: 'YOUR_PROJECT_KEY',
  autoIdentify: true,
  getUserInfo: () => getCurrentUser()
});

updateUser(userInfo: UserInfo | null)

Manually update user information (rarely needed with autoIdentify).

Alphard.updateUser({
  id: 'user_123',
  name: 'John Doe',
  email: '[email protected]'
});

getSessionId()

Get the current session ID.

const sessionId = Alphard.getSessionId();

stop()

Stop recording the current session.

Alphard.stop();

identify(userId: string, userData: object) (Legacy)

Legacy method for user identification. Use autoIdentify instead.

Alphard.identify('user_123', {
  name: 'John Doe',
  email: '[email protected]'
});

Privacy & Compliance

Automatic Privacy Protection

• ✅ Password fields automatically masked
• ✅ Credit card inputs hidden
• ✅ Sensitive form fields obscured

Additional Privacy Controls

Alphard.init({
  projectKey: 'YOUR_PROJECT_KEY',
  
  // Mask all text inputs
  maskAllInputs: true,
  
  // Mask specific elements
  maskSelectors: ['.sensitive', '.ssn', '[data-private]'],
  
  // Block entire sections
  blockSelectors: ['.payment-details', '.confidential']
});

GDPR Compliance

// Only initialize after user consent
if (userHasGivenConsent()) {
  Alphard.init({
    projectKey: 'YOUR_PROJECT_KEY',
    consent: true
  });
}

TypeScript Support

Full TypeScript definitions included:

import Alphard, { AlphardConfig, UserInfo } from 'alphard-session-replay';

const config: AlphardConfig = {
  projectKey: 'YOUR_PROJECT_KEY',
  autoIdentify: true,
  getUserInfo: (): UserInfo | null => {
    // Your user detection logic
  }
};

Alphard.init(config);

Troubleshooting

Sessions not appearing

1. Check Project Key is correct
2. Verify getUserInfo() returns user object (or null)
3. Check browser console for errors
4. Ensure consent: true is set

User names not showing

1. Ensure autoIdentify: true is enabled
2. Verify getUserInfo() returns correct user object
3. Add debug log: console.log('User:', getUserInfo())

Performance issues

1. Reduce sample rate: sampleRate: 0.5
2. Lower mouse tracking: maxMousemoveFps: 5
3. Disable console/network capture

License

MIT

Support

• Documentation: https://docs.alphard.com
• Email: [email protected]
• Issues: https://github.com/alphard/session-replay-sdk/issues