Replay SDK

A JavaScript SDK for capturing and replaying user interactions on web pages.

Compile

Dev

clear && npm run dist

Prod

clear && npm run dist:prod

ES Module Usage (Recommended)

Install the package and import where you bootstrap your app:

npm install @malleon/replay

import { initReplay } from '@malleon/replay';

// Initialize as early as possible in your app bootstrap
initReplay('your-app-id', { release: '1.0.0', dist: 'production' });

ES modules do not auto-initialize, so you must call initReplay() explicitly—typically in your main entry point, router setup, or app initialization logic.

UMD Script Tag Usage

When loading the Replay SDK via a script tag (using replay.umd.js), the library auto-initializes as soon as it finds an appId. You can pass configuration in several ways.

Script URL Parameters

Add query parameters to your script src attribute:

<script src="https://malleon.io/assets/replay.umd.js?appId=your-app-id&release=1.0.0&dist=production"></script> (or your CDN)

| Parameter | Description | |-----------|-------------| | appId | (Required) Your application ID | | release | (Optional) Release or version string (e.g. 1.0.0) | | dist | (Optional) Distribution or environment (e.g. production, staging) | | skipReplayAutoInit | If present, disables auto-initialization so you can call initReplay() manually when ready |

Example: skip auto-init and manually initialize later:

<script src="https://malleon.io/assets/replay.umd.js?skipReplayAutoInit"></script> (or your CDN)
<script>
  // Your code sets appId when ready, then:
  window.waitForAppIdAndInitReplay();  // polls until appId found, then inits
  // Or call directly when you have the values:
  window.initReplay('your-app-id', { release: '1.0.0', dist: 'production' });
</script>

Auto-Initialization

When loaded via a UMD script tag without skipReplayAutoInit, the SDK automatically calls waitForAppIdAndInitReplay(), which polls every 100ms until it finds an appId, then initializes. No manual initReplay() call is needed.

The recommended ES module imports (import ... from 'replay') do not auto-initialize; you must call initReplay() explicitly.

Configuration Sources (Priority Order)

The SDK looks for appId, release, and dist in this order (first match wins):

1. Script URL — query params on the script tag’s src (appId, release, dist)
2. Window — window.__replay__appId, window.__replay__release, window.__replay__dist
3. Page URL — search params replayAppId, replayRelease, replayDist
4. Hash URL — same param names in the URL hash (e.g. #/path?replayAppId=xyz)
5. localStorage — keys __replay__appId, __replay__release, __replay__dist
6. sessionStorage — same keys

Example: set before the script loads for late-binding of appId:

<script>
  window.__replay__appId = 'your-app-id';
  window.__replay__release = '1.0.0';
  window.__replay__dist = 'production';
</script>
<script src="https://malleon.io/assets/replay.umd.js"></script> (or your CDN)

Example: use localStorage for persistence across page loads:

localStorage.setItem('__replay__appId', 'your-app-id');
localStorage.setItem('__replay__release', '1.0.0');
localStorage.setItem('__replay__dist', 'production');

Basic Usage

// Initialize replay for an app
initReplay('your-app-id');

// Add tags to the current replay
addTagToReplay('userType', 'premium', 'STR');
addTagToReplay('sessionId', 'abc123', 'STR');
addTagToReplay('isLoggedIn', true, 'BOOL');
addTagToReplay('loginTime', new Date(), 'DATETIME');
addTagToReplay('score', 95, 'NUM');

// Add multiple tags at once
addTagsToReplay([
  { name: 'browser', value: 'chrome', type: 'STR' },
  { name: 'device', value: 'desktop', type: 'STR' },
  { name: 'timestamp', value: new Date(), type: 'DATETIME' },
  { name: 'version', value: 2.1, type: 'NUM' }
]);

// Update user data for the replay
updateReplayUserData({
  userId: 'user123',
  username: 'john_doe',
  userEmail: '[email protected]',
  userRole: 'admin',
  userStatus: 'active'
});

API Reference

initReplay(appId: string, options?: { release?: string; dist?: string }): void

Initializes the replay system for the specified app ID. Must be called before using other functions. Optionally pass release and/or dist for version and environment tracking.

waitForAppIdAndInitReplay(): void

Polls until appId is available (from script URL, window, URL params, or storage), then calls initReplay. Useful when using skipReplayAutoInit but you want automatic init once config is set.

addTagToReplay(name: string, value: string | number | boolean | Date, type: TagType): Promise<void>

Adds a single tag to the current replay. The type parameter is required and must match one of the supported tag types.

addTagsToReplay(tags: ReplayTag[]): Promise<void>

Adds multiple tags to the current replay at once. Each tag must include a name, value, and type.

updateReplayUserData(userData: ReplayUserData): Promise<void>

Updates user metadata for the current replay. All fields are optional.

Types and Interfaces

All types and interfaces are exported from ./types/replay-types and can be imported for use in TypeScript projects:

import { TagType, ReplayTag, ReplayUserData } from './types/replay-types';

TagType

type TagType = 'STR' | 'LARGE_STR' | 'NUM' | 'DATETIME' | 'BOOL';

ReplayTag

interface ReplayTag {
  name: string;
  value: string | number | boolean | Date;
  type: TagType;
}

ReplayUserData

interface ReplayUserData {
  userId?: string;
  username?: string;
  userEmail?: string;
  userRole?: string;
  userStatus?: string;
}

Tag Types

The following tag types are supported:

• 'STR' - Short string values
• 'LARGE_STR' - Long string values
• 'NUM' - Numeric values
• 'DATETIME' - Date and time values
• 'BOOL' - Boolean values (true/false)

Note: The ReplayTag interface now uses name instead of key to match the backend TagInput class exactly, eliminating the need for field mapping.

Requirements

• Must call initReplay() first to initialize the replay system (or use UMD script tag with appId for auto-init)
• Functions will warn if called before initialization
• All functions are asynchronous and return promises
• Functions are also available globally on the window object
• Tag functions require a type parameter to specify the data type