@amplitude/session-replay-browser 1.48.3 → 1.50.0

package/lib/esm/session-replay.js

@@ -41,6 +41,24 @@ var SessionReplay = /** @class */ (function () {
         // Cache the dynamically imported record function
         this.recordFunction = null;
         this.recordEventsInFlight = false;
+        /**
+         * When false, capture is paused by a customer `stop()` (or `shutdown()`) call.
+         * Focus/targeting/session-change paths still invoke `recordEvents()`, but
+         * `getShouldRecord()` will refuse to start rrweb until `start()` or a new `init()`.
+         */
+        this.recordingEnabled = true;
+        /**
+         * Bumped by `stop()` / `shutdown()` so an in-flight `_recordEvents()` that already
+         * passed `getShouldRecord()` cannot start rrweb after capture was paused.
+         */
+        this.recordingGeneration = 0;
+        /**
+         * Set by customer `start()` so coordinated child iframes self-start instead of
+         * waiting for a parent signal that may never be resent. Kept until recording
+         * actually starts so a gated `start()` (targeting, sampling, remote capture)
+         * still self-starts when those gates later pass.
+         */
+        this.startChildRecordingOnSetup = false;
         this.pendingEmitEvents = [];
         /** Current page URL, kept in sync with SPA navigations for URL-based masking */
         this.currentPageUrl = '';
@@ -77,6 +95,9 @@ var SessionReplay = /** @class */ (function () {
         };
         this.focusListener = function () {
             var _a;
+            if (!_this.recordingEnabled) {
+                return;
+            }
             if (_this.recordCancelCallback && _this.recordFunction) {
                 // Recording is already active. The on-focus full snapshot is tunable: when
                 // `captureFullSnapshotOnFocus` is false we skip it entirely so high focus-churn pages
@@ -332,6 +353,9 @@ var SessionReplay = /** @class */ (function () {
                         // Re-init should always tear down any previous URL-change subscription, even when the
                         // next config has no targeting config and we don't subscribe again.
                         (_a = this.urlChangeCleanup) === null || _a === void 0 ? void 0 : _a.call(this);
+                        // A new init always allows capture again. `stop()` only pauses the current instance.
+                        this.recordingEnabled = true;
+                        this.startChildRecordingOnSetup = false;
                         this.loggerProvider = new SafeLoggerProvider(options.loggerProvider || new Logger());
                         Object.prototype.hasOwnProperty.call(options, 'logLevel') &&
                             this.loggerProvider.enable(options.logLevel);
@@ -693,6 +717,10 @@ var SessionReplay = /** @class */ (function () {
             this.loggerProvider.warn("Session is not being recorded due to lack of config, please call sessionReplay.init.");
             return false;
         }
+        if (!this.recordingEnabled) {
+            this.loggerProvider.log("Session ".concat(this.identifiers.sessionId, " not being captured because recording was stopped."));
+            return false;
+        }
         if (!this.config.captureEnabled) {
             this.loggerProvider.log("Session ".concat(this.identifiers.sessionId, " not being captured due to capture being disabled for project or because the remote config could not be fetched."));
             return false;
@@ -885,15 +913,17 @@ var SessionReplay = /** @class */ (function () {
             });
         });
     };
+    SessionReplay.prototype.shouldAbandonRecordStart = function (generation) {
+        return !this.recordingEnabled || generation !== this.recordingGeneration;
+    };
     SessionReplay.prototype._recordEvents = function (shouldLogMetadata) {
         var _a, _b, _c, _d, _e, _f, _g, _h;
         if (shouldLogMetadata === void 0) { shouldLogMetadata = true; }
         return __awaiter(this, void 0, void 0, function () {
-            var config, shouldRecord, sessionId, recordFunction, networkLoggingConfig, trackUrl, ignoredUrls, interactionConfig, loggingConfig, hooks, ugcFilterRules, crossOriginIframesEnabled, coordinateChildren, childMode, _j, _k, _l, error_5;
-            var _m;
+            var config, shouldRecord, sessionId, generation, recordFunction, networkLoggingConfig, trackUrl, ignoredUrls, interactionConfig, loggingConfig, hooks, ugcFilterRules, crossOriginIframesEnabled, coordinateChildren, childMode, plugins, error_5;
             var _this = this;
-            return __generator(this, function (_o) {
-                switch (_o.label) {
+            return __generator(this, function (_j) {
+                switch (_j.label) {
                     case 0:
                         config = this.config;
                         shouldRecord = this.getShouldRecord();
@@ -902,16 +932,20 @@ var SessionReplay = /** @class */ (function () {
                             return [2 /*return*/];
                         }
                         this.stopRecordingEvents();
+                        generation = this.recordingGeneration;
                         return [4 /*yield*/, this.getRecordFunction()];
                     case 1:
-                        recordFunction = _o.sent();
+                        recordFunction = _j.sent();
                         // May be undefined if cannot import rrweb-record
-                        if (!recordFunction) {
+                        if (!recordFunction || this.shouldAbandonRecordStart(generation)) {
                             return [2 /*return*/];
                         }
                         return [4 /*yield*/, this.initializeNetworkObservers()];
                     case 2:
-                        _o.sent();
+                        _j.sent();
+                        if (this.shouldAbandonRecordStart(generation)) {
+                            return [2 /*return*/];
+                        }
                         networkLoggingConfig = (_b = config.loggingConfig) === null || _b === void 0 ? void 0 : _b.network;
                         trackUrl = getServerUrl(config.serverZone, config.trackServerUrl);
                         ignoredUrls = [SESSION_REPLAY_SERVER_URL, SESSION_REPLAY_EU_URL, SESSION_REPLAY_STAGING_URL, trackUrl];
@@ -937,9 +971,9 @@ var SessionReplay = /** @class */ (function () {
                             : {};
                         ugcFilterRules = (interactionConfig === null || interactionConfig === void 0 ? void 0 : interactionConfig.enabled) && interactionConfig.ugcFilterRules ? interactionConfig.ugcFilterRules : [];
                         this.loggerProvider.log("Session Replay capture beginning for ".concat(sessionId, "."));
-                        _o.label = 3;
+                        _j.label = 3;
                     case 3:
-                        _o.trys.push([3, 5, , 6]);
+                        _j.trys.push([3, 5, , 6]);
                         crossOriginIframesEnabled = !!((_g = config.crossOriginIframes) === null || _g === void 0 ? void 0 : _g.enabled);
                         coordinateChildren = ((_h = config.crossOriginIframes) === null || _h === void 0 ? void 0 : _h.coordinateChildren) !== false;
                         childMode = crossOriginIframesEnabled && isInIframe();
@@ -947,7 +981,12 @@ var SessionReplay = /** @class */ (function () {
                             // Child mode: don't self-start; wait for a start signal from the parent.
                             // (The previous listener, if any, was already removed by stopRecordingEvents above.)
                             this.crossOriginParentSignalCleanup = listenForParentSignals({
-                                onStart: function () { return _this._recordEventsInChildMode(recordFunction, sessionId, config, hooks); },
+                                onStart: function () {
+                                    if (!_this.recordingEnabled) {
+                                        return;
+                                    }
+                                    _this._recordEventsInChildMode(recordFunction, sessionId, config, hooks);
+                                },
                                 onStop: function () {
                                     try {
                                         // Only cancel the rrweb recording — do NOT call stopRecordingEvents() here,
@@ -962,34 +1001,43 @@ var SessionReplay = /** @class */ (function () {
                                     }
                                 },
                             });
+                            // Customer start() must not wait for a parent signal: the parent may already
+                            // be recording and will not send another start. Init still waits.
+                            if (this.startChildRecordingOnSetup) {
+                                this.startChildRecordingOnSetup = false;
+                                this._recordEventsInChildMode(recordFunction, sessionId, config, hooks);
+                            }
                             return [2 /*return*/];
                         }
-                        _j = this;
-                        _k = recordFunction;
-                        _l = [__assign({}, this.buildRRWebRecordOptions(config, hooks, function (event) {
-                                if (_this.shouldOptOut()) {
-                                    _this.loggerProvider.log("Opting session ".concat(sessionId, " out of recording due to optOut config."));
-                                    _this.stopRecordingEvents();
-                                    _this.sendEvents();
-                                    return;
-                                }
-                                if (event.type === RRWebEventType.Meta) {
-                                    event.data.href = getPageUrl(event.data.href, ugcFilterRules);
-                                }
-                                if (_this.eventCompressor) {
-                                    // Schedule processing during idle time if the browser supports requestIdleCallback
-                                    _this.eventCompressor.enqueueEvent(event, sessionId);
-                                }
-                                else {
-                                    // eventCompressor is not yet ready (concurrent call racing _init()).
-                                    // Buffer the event so it can be flushed once the compressor is initialized.
-                                    _this.pendingEmitEvents.push({ event: event, sessionId: sessionId });
-                                }
-                            }, 'Error while capturing replay: '))];
-                        _m = {};
+                        this.startChildRecordingOnSetup = false;
                         return [4 /*yield*/, this.getRecordingPlugins(loggingConfig)];
                     case 4:
-                        _j.recordCancelCallback = _k.apply(void 0, [__assign.apply(void 0, _l.concat([(_m.plugins = _o.sent(), _m.recordCrossOriginIframes = crossOriginIframesEnabled, _m)]))]);
+                        plugins = _j.sent();
+                        if (this.shouldAbandonRecordStart(generation)) {
+                            return [2 /*return*/];
+                        }
+                        this.recordCancelCallback = recordFunction(__assign(__assign({}, this.buildRRWebRecordOptions(config, hooks, function (event) {
+                            if (_this.shouldOptOut() || !_this.recordingEnabled) {
+                                _this.loggerProvider.log(_this.shouldOptOut()
+                                    ? "Opting session ".concat(sessionId, " out of recording due to optOut config.")
+                                    : "Session Replay capture stopping for ".concat(sessionId, "."));
+                                _this.stopRecordingEvents();
+                                _this.sendEvents();
+                                return;
+                            }
+                            if (event.type === RRWebEventType.Meta) {
+                                event.data.href = getPageUrl(event.data.href, ugcFilterRules);
+                            }
+                            if (_this.eventCompressor) {
+                                // Schedule processing during idle time if the browser supports requestIdleCallback
+                                _this.eventCompressor.enqueueEvent(event, sessionId);
+                            }
+                            else {
+                                // eventCompressor is not yet ready (concurrent call racing _init()).
+                                // Buffer the event so it can be flushed once the compressor is initialized.
+                                _this.pendingEmitEvents.push({ event: event, sessionId: sessionId });
+                            }
+                        }, 'Error while capturing replay: ')), { plugins: plugins, recordCrossOriginIframes: crossOriginIframesEnabled }));
                         if (crossOriginIframesEnabled && !childMode && coordinateChildren) {
                             if (!this.crossOriginIframeCoordinator) {
                                 this.crossOriginIframeCoordinator = new CrossOriginIframeCoordinator();
@@ -1002,7 +1050,7 @@ var SessionReplay = /** @class */ (function () {
                         }
                         return [3 /*break*/, 6];
                     case 5:
-                        error_5 = _o.sent();
+                        error_5 = _j.sent();
                         this.loggerProvider.warn('Failed to initialize session replay:', error_5);
                         return [3 /*break*/, 6];
                     case 6: return [2 /*return*/];
@@ -1013,7 +1061,7 @@ var SessionReplay = /** @class */ (function () {
     SessionReplay.prototype.buildRRWebRecordOptions = function (config, hooks, emit, errorLogPrefix) {
         var _this = this;
         var privacyConfig = config.privacyConfig;
-        return __assign(__assign({ emit: emit, inlineStylesheet: config.shouldInlineStylesheet, hooks: hooks, maskAllInputs: true, maskTextClass: MASK_TEXT_CLASS, blockClass: BLOCK_CLASS, blockSelector: this.getBlockSelectors(), applyBackgroundColorToBlockedElements: config.applyBackgroundColorToBlockedElements, maskInputFn: maskFn('input', privacyConfig, function () { return _this.currentPageUrl; }), maskTextFn: maskFn('text', privacyConfig, function () { return _this.currentPageUrl; }), maskAttributeFn: maskAttributeFn(privacyConfig, function () { return _this.currentPageUrl; }), maskTextSelector: this.getMaskTextSelectors() }, (config.fullSnapshotIntervalMs !== undefined && { checkoutEveryNms: config.fullSnapshotIntervalMs })), { recordCanvas: false, captureAdoptedStyleSheets: config.captureAdoptedStyleSheets, 
+        return __assign(__assign({ emit: emit, inlineStylesheet: config.shouldInlineStylesheet, inlineImages: config.inlineImages, hooks: hooks, maskAllInputs: true, maskTextClass: MASK_TEXT_CLASS, blockClass: BLOCK_CLASS, blockSelector: this.getBlockSelectors(), applyBackgroundColorToBlockedElements: config.applyBackgroundColorToBlockedElements, maskInputFn: maskFn('input', privacyConfig, function () { return _this.currentPageUrl; }), maskTextFn: maskFn('text', privacyConfig, function () { return _this.currentPageUrl; }), maskAttributeFn: maskAttributeFn(privacyConfig, function () { return _this.currentPageUrl; }), maskTextSelector: this.getMaskTextSelectors() }, (config.fullSnapshotIntervalMs !== undefined && { checkoutEveryNms: config.fullSnapshotIntervalMs })), { recordCanvas: false, captureAdoptedStyleSheets: config.captureAdoptedStyleSheets, 
             // Strip nodes that are never rendered by the rrweb replay player.
             // None of these affect visual fidelity; omitting them reduces snapshot size.
             slimDOMOptions: {
@@ -1072,6 +1120,31 @@ var SessionReplay = /** @class */ (function () {
         var _a;
         return (_a = this.identifiers) === null || _a === void 0 ? void 0 : _a.sessionId;
     };
+    SessionReplay.prototype.start = function () {
+        return returnWrapper(this._start());
+    };
+    SessionReplay.prototype._start = function () {
+        return __awaiter(this, void 0, void 0, function () {
+            return __generator(this, function (_a) {
+                switch (_a.label) {
+                    case 0:
+                        this.recordingEnabled = true;
+                        this.startChildRecordingOnSetup = true;
+                        return [4 /*yield*/, this.recordEvents()];
+                    case 1:
+                        _a.sent();
+                        return [2 /*return*/];
+                }
+            });
+        });
+    };
+    SessionReplay.prototype.stop = function () {
+        this.recordingEnabled = false;
+        this.startChildRecordingOnSetup = false;
+        this.recordingGeneration++;
+        this.stopRecordingEvents();
+        this.sendEvents();
+    };
     SessionReplay.prototype.flush = function (useRetry) {
         var _a;
         if (useRetry === void 0) { useRetry = false; }
@@ -1088,6 +1161,9 @@ var SessionReplay = /** @class */ (function () {
     };
     SessionReplay.prototype.shutdown = function () {
         var _a, _b;
+        this.recordingEnabled = false;
+        this.startChildRecordingOnSetup = false;
+        this.recordingGeneration++;
         (_a = this.urlChangeCleanup) === null || _a === void 0 ? void 0 : _a.call(this);
         (_b = this.crossOriginParentSignalCleanup) === null || _b === void 0 ? void 0 : _b.call(this);
         this.crossOriginParentSignalCleanup = null;