swetrix 4.2.0 → 4.4.0

package/README.md

@@ -6,7 +6,7 @@
 
 [![NPM](https://img.shields.io/npm/v/swetrix)](https://www.npmjs.com/package/swetrix)
 [![Package size](https://img.shields.io/bundlephobia/minzip/swetrix)](https://bundlephobia.com/package/swetrix)
-[![JSDelivr hits](https://data.jsdelivr.com/v1/package/npm/swetrix/badge?style=rounded)](https://data.jsdelivr.com/v1/package/npm/swetrix/badge/stats)
+[![JSDelivr hits](https://data.jsdelivr.com/v1/package/npm/swetrix/badge?style=rounded)](https://www.jsdelivr.com/package/npm/swetrix)
 [![Contributions welcome](https://img.shields.io/badge/contributions-welcome-brightgreen.svg?style=flat)](https://github.com/swetrix/swetrix-js/issues)
 
 # Swetrix Tracking Script
@@ -65,6 +65,7 @@ init('YOUR_PROJECT_ID', {
   disabled: false,
   respectDNT: false,
   profileId: 'user-123',
+  preloadSessionReplay: false,
 })
 ```
 
@@ -75,6 +76,7 @@ init('YOUR_PROJECT_ID', {
 | `disabled` | When `true`, no data is sent. Useful for dev environments. | `false` |
 | `respectDNT` | When `true`, disables tracking for users with Do Not Track enabled. | `false` |
 | `profileId` | Profile ID for long-term user tracking (MAU/DAU). | `undefined` |
+| `preloadSessionReplay` | Preload the session replay recorder after `init()`. Recording only starts after `startSessionReplay()`. | `undefined` |
 
 ### `trackViews(options?)`
 
@@ -110,6 +112,7 @@ track({
   ev: 'signup',
   unique: true,
   meta: { plan: 'pro', source: 'landing' },
+  profileId: 'user-123',
 })
 ```
 
@@ -118,6 +121,7 @@ track({
 | `ev` | Event name (max 256 chars). | **required** |
 | `unique` | Only count once per session. | `false` |
 | `meta` | Key-value metadata (max 20 keys, 1000 chars total). | `{}` |
+| `profileId` | Optional profile ID. Overrides the global `profileId` for this event. | `undefined` |
 
 ### `trackErrors(options?)`
 
@@ -161,29 +165,101 @@ pageview({
 ### Feature Flags
 
 ```javascript
-// Get all flags
+// Get all flags. Results are cached for 5 minutes.
 const flags = await getFeatureFlags({ profileId: 'user-123' })
 
-// Get a single flag
+// Force a fresh fetch
+const freshFlags = await getFeatureFlags({ profileId: 'user-123' }, true)
+
+// Get a single flag. The third argument is an optional fallback value.
 const enabled = await getFeatureFlag('dark-mode', { profileId: 'user-123' })
+const enabledWithFallback = await getFeatureFlag('dark-mode', { profileId: 'user-123' }, false)
 
-// Clear cache
+// Clear the shared feature flag / experiment cache
 clearFeatureFlagsCache()
 ```
 
 ### A/B Experiments
 
 ```javascript
-// Get all experiments
+// Get all running experiment assignments. Results are cached for 5 minutes.
 const experiments = await getExperiments({ profileId: 'user-123' })
 
-// Get a specific experiment variant
-const variant = await getExperiment('checkout-redesign', { profileId: 'user-123' })
+// Force a fresh fetch
+const freshExperiments = await getExperiments({ profileId: 'user-123' }, true)
 
-// Clear cache
+// Get a specific experiment variant. The third argument is an optional fallback variant.
+const variant = await getExperiment('checkout-redesign-experiment-id', { profileId: 'user-123' })
+const variantWithFallback = await getExperiment('checkout-redesign-experiment-id', { profileId: 'user-123' }, 'control')
+
+// Clear the shared feature flag / experiment cache
 clearExperimentsCache()
 ```
 
+### `startSessionReplay(options?)`
+
+Start recording a session replay. Session replays use `total` privacy by default, which masks text and inputs and blocks media/canvas capture unless you explicitly choose another mode.
+
+If you use the npm package, rrweb is dynamically imported from your installed dependencies only when the recorder is preloaded or started. If you use the CDN/script-tag build, the standalone replay recorder is loaded with an async script tag.
+
+```javascript
+const replay = await startSessionReplay({
+  privacy: 'total',
+  maskAllText: true,
+  sampleRate: 0.25,
+  maxDurationMs: 10 * 60 * 1000,
+  idleTimeoutMs: 2 * 60 * 1000,
+  maxBytesPerChunk: 512 * 1024,
+})
+
+// Stop or flush manually when needed
+await replay.flush()
+await replay.stop()
+```
+
+| Option | Description | Default |
+|---|---|---|
+| `privacy` | Privacy mode: `total`, `normal`, or `none`. | `'total'` |
+| `maskAllText` | Mask all non-input text with asterisks. Defaults to `true` when `privacy` is `total`, otherwise `false`. | privacy-based |
+| `sampleRate` | Fraction of sessions to record (`0` to `1`). | `1` |
+| `maxDurationMs` | Stop recording after this duration. | `undefined` |
+| `idleTimeoutMs` | Stop recording after this much visitor inactivity. | `undefined` |
+| `flushIntervalMs` | Upload buffered replay events at this interval. | `5000` |
+| `maxEventsPerChunk` | Upload once this many events are buffered. | `100` |
+| `maxBytesPerChunk` | Upload once buffered replay events reach this approximate byte size. | `524288` |
+| `maxBytesPerEvent` | Drop a single replay event if it is larger than this many bytes. | `5242880` |
+| `recordIframes` | Allow iframe elements to be captured. Iframes are blocked by default to reduce replay size and avoid recording embedded third-party content. | `false` |
+| `rrweb` | Additional rrweb record options. | `undefined` |
+
+To mask text while keeping media less restricted than `total` privacy, combine `normal` privacy with `maskAllText`:
+
+```javascript
+await startSessionReplay({
+  privacy: 'normal',
+  maskAllText: true,
+})
+```
+
+By default, Swetrix blocks iframe elements from replay snapshots. If you own the iframe content and need it in the replay, opt in explicitly:
+
+```javascript
+await startSessionReplay({
+  privacy: 'normal',
+  recordIframes: true,
+})
+```
+
+Cross-origin iframe recording also requires rrweb's cross-origin iframe support and should only be enabled for domains you control:
+
+```javascript
+await startSessionReplay({
+  recordIframes: true,
+  rrweb: {
+    recordCrossOriginIframes: true,
+  },
+})
+```
+
 ### Session & Profile IDs
 
 ```javascript

package/dist/esnext/Lib.d.ts

@@ -1,3 +1,22 @@
+type RrwebEvent = Record<string, unknown>;
+type RrwebEmit = (event: RrwebEvent) => void;
+interface RrwebRecordOptions {
+    emit?: RrwebEmit;
+    [key: string]: unknown;
+}
+interface RrwebGlobal {
+    record?: (options: RrwebRecordOptions) => (() => void) | undefined;
+    Replayer?: unknown;
+}
+type SessionReplayPreloadOption = boolean | {
+    rrwebUrl?: string;
+};
+declare global {
+    interface Window {
+        rrweb?: RrwebGlobal;
+        __SWETRIX_RRWEB_LOADING__?: Promise<void>;
+    }
+}
 export interface LibOptions {
     /**
      * When set to `true`, localhost events will be sent to server.
@@ -19,6 +38,10 @@ export interface LibOptions {
      * If set, it will be used for all pageviews and events unless overridden per-call.
      */
     profileId?: string;
+    /**
+     * Preload session replay recorder code. Recording only starts after calling startSessionReplay().
+     */
+    preloadSessionReplay?: SessionReplayPreloadOption;
 }
 export interface TrackEventOptions {
     /** The custom event name. */
@@ -117,6 +140,25 @@ export interface ErrorActions {
     /** Stops the tracking of errors. */
     stop: () => void;
 }
+declare const SESSION_REPLAY_PRIVACY_VALUES: readonly ["total", "normal", "none"];
+export type SessionReplayPrivacy = (typeof SESSION_REPLAY_PRIVACY_VALUES)[number];
+export interface SessionReplayOptions {
+    privacy?: SessionReplayPrivacy;
+    rrweb?: RrwebRecordOptions;
+    flushIntervalMs?: number;
+    maxEventsPerChunk?: number;
+    maxBytesPerChunk?: number;
+    maxBytesPerEvent?: number;
+    sampleRate?: number;
+    maxDurationMs?: number;
+    idleTimeoutMs?: number;
+    maskAllText?: boolean;
+    recordIframes?: boolean;
+}
+export interface SessionReplayActions {
+    stop: () => Promise<void>;
+    flush: () => Promise<void>;
+}
 export interface PageData {
     /** Current URL path. */
     path: string;
@@ -169,6 +211,7 @@ export interface PageViewsOptions {
 export declare const defaultActions: {
     stop(): void;
 };
+export declare const defaultSessionReplayActions: SessionReplayActions;
 export declare class Lib {
     private projectID;
     private options?;
@@ -179,6 +222,9 @@ export declare class Lib {
     private activePage;
     private errorListenerExists;
     private cachedData;
+    private rrwebLoader;
+    private sessionReplayActions;
+    private sessionReplayInitPromise;
     constructor(projectID: string, options?: LibOptions | undefined);
     captureError(event: ErrorEvent): void;
     trackErrors(options?: ErrorOptions): ErrorActions;
@@ -187,10 +233,10 @@ export declare class Lib {
     trackPageViews(options?: PageViewsOptions): PageActions;
     getPerformanceStats(): IPerfPayload | {};
     /**
-     * Fetches all feature flags and experiments for the project.
-     * Results are cached for 5 minutes by default.
+     * Fetches all feature flags for the project.
+     * Results are cached for 5 minutes by default and share a cache with experiments.
      *
-     * @param options - Options for evaluating feature flags.
+     * @param options - Options for evaluating feature flags (`profileId` only).
      * @param forceRefresh - If true, bypasses the cache and fetches fresh data.
      * @returns A promise that resolves to a record of flag keys to boolean values.
      */
@@ -203,8 +249,8 @@ export declare class Lib {
      * Gets the value of a single feature flag.
      *
      * @param key - The feature flag key.
-     * @param options - Options for evaluating the feature flag.
-     * @param defaultValue - Default value to return if the flag is not found. Defaults to false.
+     * @param options - Options for evaluating the feature flag (`profileId` only).
+     * @param defaultValue - Optional default value to return if the flag is not found. Defaults to false.
      * @returns A promise that resolves to the boolean value of the flag.
      */
     getFeatureFlag(key: string, options?: FeatureFlagsOptions, defaultValue?: boolean): Promise<boolean>;
@@ -213,16 +259,16 @@ export declare class Lib {
      */
     clearFeatureFlagsCache(): void;
     /**
-     * Fetches all A/B test experiments for the project.
+     * Fetches variant assignments for running A/B test experiments returned by feature flag evaluation.
      * Results are cached for 5 minutes by default (shared cache with feature flags).
      *
-     * @param options - Options for evaluating experiments.
+     * @param options - Options for evaluating experiments (`profileId` only).
      * @param forceRefresh - If true, bypasses the cache and fetches fresh data.
      * @returns A promise that resolves to a record of experiment IDs to variant keys.
      *
      * @example
      * ```typescript
-     * const experiments = await getExperiments()
+     * const experiments = await getExperiments({ profileId: 'user-123' })
      * // experiments = { 'exp-123': 'variant-a', 'exp-456': 'control' }
      * ```
      */
@@ -231,13 +277,16 @@ export declare class Lib {
      * Gets the variant key for a specific A/B test experiment.
      *
      * @param experimentId - The experiment ID.
-     * @param options - Options for evaluating the experiment.
-     * @param defaultVariant - Default variant key to return if the experiment is not found. Defaults to null.
+     * @param options - Options for evaluating the experiment (`profileId` only).
+     * @param defaultVariant - Optional default variant key to return if the experiment is not found. Defaults to null.
      * @returns A promise that resolves to the variant key assigned to this user, or defaultVariant if not found.
      *
      * @example
      * ```typescript
-     * const variant = await getExperiment('checkout-redesign')
+     * const variant = await getExperiment('checkout-redesign', { profileId: 'user-123' })
+     *
+     * // Optional fallback variant:
+     * const variantWithFallback = await getExperiment('checkout-redesign', undefined, 'control')
      *
      * if (variant === 'new-checkout') {
      *   // Show new checkout flow
@@ -298,6 +347,10 @@ export declare class Lib {
      * ```
      */
     getSessionId(): Promise<string | null>;
+    startSessionReplay(options?: SessionReplayOptions): Promise<SessionReplayActions>;
+    private initialiseSessionReplay;
+    private shouldSampleSessionReplay;
+    private getSessionReplayPrivacy;
     /**
      * Gets the API base URL (without /log suffix).
      */
@@ -307,6 +360,19 @@ export declare class Lib {
     private trackPage;
     submitPageView(payload: Partial<IPageViewPayload>, unique: boolean, perf: IPerfPayload | {}, evokeCallback?: boolean): void;
     private canTrack;
+    private getSessionReplayUrl;
+    private getSessionReplayPreloadOption;
+    private getDefaultSessionReplayUrl;
+    private getTrackerScript;
+    private preloadSessionReplay;
+    private loadSessionReplayRecorder;
+    private loadSessionReplayPackage;
+    private loadSessionReplayScript;
+    private getSessionReplayRecordOptions;
+    private mergeSelectors;
+    private createReplayId;
+    private sendSessionReplayStart;
+    private sendSessionReplayChunk;
     private sendRequest;
 }
 export {};