From 659778295ff1d85e720586a99acfab1eaa6294d5 Mon Sep 17 00:00:00 2001
From: Jesse Wang <jesse.wang@amplitude.com>
Date: Thu, 21 Aug 2025 14:50:34 -0700
Subject: [PATCH] perf(session replay): enable option to delay initialization

---
 .../src/session-replay.ts                     |  1 +
 .../src/typings/session-replay.ts             |  9 +++++
 .../src/config/local-config.ts                |  4 +++
 .../src/config/types.ts                       | 19 ++++++++++
 .../session-replay-browser/src/constants.ts   |  1 +
 .../src/session-replay.ts                     | 35 +++++++++++++++++++
 6 files changed, 69 insertions(+)

diff --git a/packages/plugin-session-replay-browser/src/session-replay.ts b/packages/plugin-session-replay-browser/src/session-replay.ts
index 6b6693798..da6fc3d80 100644
--- a/packages/plugin-session-replay-browser/src/session-replay.ts
+++ b/packages/plugin-session-replay-browser/src/session-replay.ts
@@ -89,6 +89,7 @@ export class SessionReplayPlugin implements EnrichmentPlugin<BrowserClient, Brow
         shouldInlineStylesheet: this.options.shouldInlineStylesheet,
         version: { type: 'plugin', version: VERSION },
         performanceConfig: this.options.performanceConfig,
+        delayRecordInitialization: this.options.delayRecordInitialization,
         storeType: this.options.storeType,
         experimental: this.options.experimental,
         userProperties: userProperties,
diff --git a/packages/plugin-session-replay-browser/src/typings/session-replay.ts b/packages/plugin-session-replay-browser/src/typings/session-replay.ts
index 138a2f6a3..0093c55b3 100644
--- a/packages/plugin-session-replay-browser/src/typings/session-replay.ts
+++ b/packages/plugin-session-replay-browser/src/typings/session-replay.ts
@@ -22,6 +22,11 @@ export interface SessionReplayPerformanceConfig {
   timeout?: number;
 }
 
+export interface SessionReplayDelayRecordInitializationConfig {
+  enabled: boolean;
+  timeout?: number;
+}
+
 /**
  * UGC filter rule.
  */
@@ -79,6 +84,10 @@ export interface SessionReplayOptions {
    * @see {@link StandaloneSessionReplayOptions.performanceConfig}
    */
   performanceConfig?: SessionReplayPerformanceConfig;
+  /**
+   * @see {@link StandaloneSessionReplayOptions.delayRecordInitialization}
+   */
+  delayRecordInitialization?: SessionReplayDelayRecordInitializationConfig;
   /**
    * @see {@link StandaloneSessionReplayOptions.storeType}
    */
diff --git a/packages/session-replay-browser/src/config/local-config.ts b/packages/session-replay-browser/src/config/local-config.ts
index 0a2337798..b6a43607c 100644
--- a/packages/session-replay-browser/src/config/local-config.ts
+++ b/packages/session-replay-browser/src/config/local-config.ts
@@ -4,6 +4,7 @@ import {
   DEFAULT_SAMPLE_RATE,
   DEFAULT_SERVER_ZONE,
   DEFAULT_URL_CHANGE_POLLING_INTERVAL,
+  DEFAULT_DELAY_RECORD_INITIALIZATION_CONFIG,
 } from '../constants';
 import { SessionReplayOptions, StoreType } from '../typings/session-replay';
 import {
@@ -12,6 +13,7 @@ import {
   PrivacyConfig,
   SessionReplayPerformanceConfig,
   SessionReplayVersion,
+  SessionReplayDelayRecordInitializationConfig,
 } from './types';
 import { SafeLoggerProvider } from '../logger';
 import { validateUGCFilterRules } from '../helpers';
@@ -35,6 +37,7 @@ export class SessionReplayLocalConfig extends Config implements ISessionReplayLo
   version?: SessionReplayVersion;
   storeType: StoreType;
   performanceConfig?: SessionReplayPerformanceConfig;
+  delayRecordInitialization?: SessionReplayDelayRecordInitializationConfig;
   experimental?: { useWebWorker: boolean };
   applyBackgroundColorToBlockedElements?: boolean;
   omitElementTags?: {
@@ -66,6 +69,7 @@ export class SessionReplayLocalConfig extends Config implements ISessionReplayLo
     this.shouldInlineStylesheet = options.shouldInlineStylesheet;
     this.version = options.version;
     this.performanceConfig = options.performanceConfig || DEFAULT_PERFORMANCE_CONFIG;
+    this.delayRecordInitialization = options.delayRecordInitialization || DEFAULT_DELAY_RECORD_INITIALIZATION_CONFIG;
     this.storeType = options.storeType ?? 'idb';
     this.applyBackgroundColorToBlockedElements = options.applyBackgroundColorToBlockedElements ?? false;
     this.enableUrlChangePolling = options.enableUrlChangePolling ?? false;
diff --git a/packages/session-replay-browser/src/config/types.ts b/packages/session-replay-browser/src/config/types.ts
index fcc9d42bc..79e453b62 100644
--- a/packages/session-replay-browser/src/config/types.ts
+++ b/packages/session-replay-browser/src/config/types.ts
@@ -129,6 +129,11 @@ export interface SessionReplayLocalConfig extends IConfig {
    * to be done during the browser's idle periods.
    */
   performanceConfig?: SessionReplayPerformanceConfig;
+  /**
+   * Delay record initialization configuration. If enabled, we will defer record function initialization
+   * to be done during the browser's idle periods.
+   */
+  delayRecordInitialization?: SessionReplayDelayRecordInitializationConfig;
   /**
    * Specifies how replay events should be stored. `idb` uses IndexedDB to persist replay events
    * when all events cannot be sent during capture. `memory` stores replay events only in memory,
@@ -253,4 +258,18 @@ export interface SessionReplayPerformanceConfig {
   timeout?: number;
 }
 
+export interface SessionReplayDelayRecordInitializationConfig {
+  /**
+   * If enabled, we will defer record function initialization
+   * to be done during the browser's idle periods.
+   */
+  enabled: boolean;
+  /**
+   * Optional timeout in milliseconds for the `requestIdleCallback` API.
+   * If specified, this value will be used to set a maximum time for the browser to wait
+   * before executing the deferred record function initialization, even if the browser is not idle.
+   */
+  timeout?: number;
+}
+
 export type SessionReplayType = 'standalone' | 'plugin' | 'segment';
diff --git a/packages/session-replay-browser/src/constants.ts b/packages/session-replay-browser/src/constants.ts
index 3da93c9a2..b1463be7a 100644
--- a/packages/session-replay-browser/src/constants.ts
+++ b/packages/session-replay-browser/src/constants.ts
@@ -9,6 +9,7 @@ export const DEFAULT_SAMPLE_RATE = 0;
 export const DEFAULT_SERVER_ZONE = ServerZone.US;
 export const DEFAULT_PERFORMANCE_CONFIG = { enabled: true };
 export const DEFAULT_URL_CHANGE_POLLING_INTERVAL = 1000;
+export const DEFAULT_DELAY_RECORD_INITIALIZATION_CONFIG = { enabled: false };
 
 export const SESSION_REPLAY_DEBUG_PROPERTY = `${DEFAULT_EVENT_PROPERTY_PREFIX} Session Replay Debug`;
 
diff --git a/packages/session-replay-browser/src/session-replay.ts b/packages/session-replay-browser/src/session-replay.ts
index 97394ae0e..ef3506ddb 100644
--- a/packages/session-replay-browser/src/session-replay.ts
+++ b/packages/session-replay-browser/src/session-replay.ts
@@ -331,6 +331,7 @@ export class SessionReplay implements AmplitudeSessionReplay {
             sessionTargetingMatch: this.sessionTargetingMatch,
             event: eventForTargeting,
             targetingParams: targetingParams,
+            config: this.config.targetingConfig,
           },
           null,
           2,
@@ -531,6 +532,40 @@ export class SessionReplay implements AmplitudeSessionReplay {
     }
     this.stopRecordingEvents();
 
+    const shouldUseIdleCallback = config?.delayRecordInitialization?.enabled;
+    if (shouldUseIdleCallback) {
+      this.loggerProvider.debug('Scheduling record function initialization during idle time.');
+      this.scheduleIdleRecordInitialization(shouldLogMetadata, config, sessionId);
+    } else {
+      this.loggerProvider.debug('Initializing record function immediately.');
+      await this.initializeRecording(shouldLogMetadata, config, sessionId);
+    }
+  }
+
+  private scheduleIdleRecordInitialization(
+    shouldLogMetadata: boolean,
+    config: SessionReplayJoinedConfig,
+    sessionId: string | number,
+  ) {
+    const timeout = config?.delayRecordInitialization?.timeout || 2000;
+
+    const globalScope = getGlobalScope();
+    if (globalScope?.requestIdleCallback) {
+      globalScope.requestIdleCallback(
+        () => {
+          this.loggerProvider.debug('Initializing record function during idle time.');
+          void this.initializeRecording(shouldLogMetadata, config, sessionId);
+        },
+        { timeout },
+      );
+    }
+  }
+
+  private async initializeRecording(
+    shouldLogMetadata: boolean,
+    config: SessionReplayJoinedConfig,
+    sessionId: string | number,
+  ) {
     const recordFunction = await this.getRecordFunction();
 
     // May be undefined if cannot import rrweb-record