@malleon/replay 1.0.13 → 1.0.14

package/README.md

@@ -8,6 +8,89 @@ clear && npm run dist
 ## Prod
 clear && npm run dist:prod
 
+## ES Module Usage (Recommended)
+
+Install the package and import where you bootstrap your app:
+
+```bash
+npm install @malleon/replay
+```
+
+```javascript
+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:
+
+```html
+<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:
+```html
+<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:
+
+```html
+<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:
+
+```javascript
+localStorage.setItem('__replay__appId', 'your-app-id');
+localStorage.setItem('__replay__release', '1.0.0');
+localStorage.setItem('__replay__dist', 'production');
+```
+
 ## Basic Usage
 
 ```javascript
@@ -41,8 +124,11 @@ updateReplayUserData({
 
 ## API Reference
 
-### `initReplay(appId: string): void`
-Initializes the replay system for the specified app ID. Must be called before using other functions.
+### `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.
@@ -99,7 +185,7 @@ The following tag types are supported:
 
 ## Requirements
 
-- Must call `initReplay()` first to initialize the replay system
+- 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

package/dist/index.d.ts

@@ -4,6 +4,10 @@ declare global {
         __REPLAY_STARTED__?: boolean;
         __REPLAY_DISABLED__?: boolean;
         __replay__appId?: string;
+        __replay__release?: string;
+        __replay__dist?: string;
+        initReplay?: typeof initReplay;
+        waitForAppIdAndInitReplay?: typeof waitForAppIdAndInitReplay;
         addTagsToReplay?: typeof addTagsToReplay;
         addTagToReplay?: typeof addTagToReplay;
         updateReplayUserData?: typeof updateReplayUserData;