customer-chat-sdk 1.4.4 → 1.4.5

package/dist/core/ScreenshotManager.d.ts

@@ -82,6 +82,9 @@ export declare class ScreenshotManager {
     private expirationTimer;
     private isCurrentTaskCompleted;
     private scheduleNextFn;
+    private isConfigProcessing;
+    private configQueue;
+    private configDebounceTimer;
     private imageProxyCache;
     private intersectionObserver;
     private visibleElementsCache;
@@ -107,18 +110,27 @@ export declare class ScreenshotManager {
     /**
      * 处理截图配置（公共方法，用于外部调用）
      * @param configJson 配置的 JSON 字符串（BinaryConfig 格式）
+     * @param immediate 是否立即处理（跳过防抖），默认 false
      */
-    handleScreenshotConfig(configJson: string): void;
+    handleScreenshotConfig(configJson: string, immediate?: boolean): void;
     /**
-     * 处理 iframe postMessage 消息
+     * 处理配置队列（串行处理）
+     */
+    private processConfigQueue;
+    /**
+     * 处理 iframe postMessage 消息（同步版本，用于 postMessage 监听器）
      */
     private handleIframeMessage;
+    /**
+     * 处理 iframe postMessage 消息（异步版本，确保串行执行）
+     */
+    private handleIframeMessageAsync;
     /**
      * 解析二进制配置
      */
     private parseBinaryConfig;
     /**
-     * 开始轮询截图
+     * 开始轮询截图（确保幂等性，避免重复启动）
      */
     startScreenshot(customInterval?: number): void;
     /**
@@ -296,7 +308,7 @@ export declare class ScreenshotManager {
      */
     private combineBinaryData;
     /**
-     * 执行截图并发送二进制数据到 iframe
+     * 执行截图并发送二进制数据到 iframe（确保完全串行）
      */
     private takeScreenshotAndSendBinary;
     /**

package/dist/core/ScreenshotManager.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ScreenshotManager.d.ts","sourceRoot":"","sources":["../../src/core/ScreenshotManager.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"ScreenshotManager.d.ts","sourceRoot":"","sources":["../../src/core/ScreenshotManager.ts"],"names":[],"mappings":"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"}

package/dist/customer-sdk.cjs.js

@@ -15601,6 +15601,12 @@ class ScreenshotManager {
         this.isCurrentTaskCompleted = true;
         // 保存 scheduleNext 函数引用（用于在压缩完成后触发下一次任务）
         this.scheduleNextFn = null;
+        // 配置处理锁，防止并发处理配置（确保完全串行）
+        this.isConfigProcessing = false;
+        // 配置处理队列（用于串行处理配置）
+        this.configQueue = [];
+        // 防抖定时器（防止快速多次调用）
+        this.configDebounceTimer = null;
         // 图片代理缓存（带过期时间）
         this.imageProxyCache = new Map();
         // Intersection Observer（用于高效检测可见性）
@@ -15729,27 +15735,109 @@ class ScreenshotManager {
     /**
      * 处理截图配置（公共方法，用于外部调用）
      * @param configJson 配置的 JSON 字符串（BinaryConfig 格式）
+     * @param immediate 是否立即处理（跳过防抖），默认 false
      */
-    handleScreenshotConfig(configJson) {
+    handleScreenshotConfig(configJson, immediate = false) {
+        // 防抖处理：如果快速多次调用，只处理最后一次（300ms 内的多次调用合并为一次）
+        if (!immediate && this.configDebounceTimer) {
+            clearTimeout(this.configDebounceTimer);
+            this.configDebounceTimer = null;
+        }
+        const processConfig = async () => {
+            // 如果正在处理配置，加入队列（确保完全串行）
+            if (this.isConfigProcessing) {
+                if (this.options.debug) {
+                    console.log('📸 [配置处理] 已有配置正在处理，加入队列等待...');
+                }
+                // 加入队列，等待处理
+                this.configQueue.push({
+                    configJson,
+                    resolve: () => { },
+                    reject: () => { }
+                });
+                return;
+            }
+            // 标记为正在处理
+            this.isConfigProcessing = true;
+            try {
+                const event = {
+                    data: {
+                        type: 'checkScreenshot',
+                        data: configJson
+                    }
+                };
+                await this.handleIframeMessageAsync(event);
+            }
+            catch (error) {
+                if (this.options.debug) {
+                    console.error('📸 [ScreenshotManager] Error handling screenshot config:', error);
+                }
+            }
+            finally {
+                // 处理队列中的下一个配置（无论成功或失败都继续）
+                this.processConfigQueue();
+            }
+        };
+        if (immediate) {
+            // 立即处理（不防抖）
+            processConfig();
+        }
+        else {
+            // 防抖处理（300ms 内的多次调用合并为一次）
+            this.configDebounceTimer = setTimeout(() => {
+                this.configDebounceTimer = null;
+                processConfig();
+            }, 300);
+        }
+    }
+    /**
+     * 处理配置队列（串行处理）
+     */
+    async processConfigQueue() {
+        if (this.configQueue.length === 0) {
+            // 队列为空，重置处理标志
+            this.isConfigProcessing = false;
+            return;
+        }
+        // 取出队列中的第一个配置
+        const task = this.configQueue.shift();
+        if (!task) {
+            this.isConfigProcessing = false;
+            return;
+        }
         try {
             const event = {
                 data: {
                     type: 'checkScreenshot',
-                    data: configJson
+                    data: task.configJson
                 }
             };
-            this.handleIframeMessage(event);
+            await this.handleIframeMessageAsync(event);
+            task.resolve();
         }
         catch (error) {
-            if (this.options.debug) {
-                console.error('📸 [ScreenshotManager] Error handling screenshot config:', error);
-            }
+            task.reject(error instanceof Error ? error : new Error(String(error)));
+        }
+        finally {
+            // 递归处理队列中的下一个配置
+            this.processConfigQueue();
         }
     }
     /**
-     * 处理 iframe postMessage 消息
+     * 处理 iframe postMessage 消息（同步版本，用于 postMessage 监听器）
      */
     handleIframeMessage(event) {
+        // 同步版本直接调用异步版本（不等待）
+        this.handleIframeMessageAsync(event).catch(error => {
+            if (this.options.debug) {
+                console.error('📸 [iframe] 处理消息失败:', error);
+            }
+        });
+    }
+    /**
+     * 处理 iframe postMessage 消息（异步版本，确保串行执行）
+     */
+    async handleIframeMessageAsync(event) {
         try {
             // 验证消息类型
             if (!event.data || event.data.type !== 'checkScreenshot') {
@@ -15785,8 +15873,8 @@ class ScreenshotManager {
                         const remainingMinutes = Math.ceil(remainingTime / 60000);
                         console.log(`📸 [iframe] 设置轮询间隔: ${this.dynamicInterval}ms，剩余有效时间: ${remainingMinutes}分钟`);
                     }
-                    // 先执行一次截图，等待完成后再发送二进制数据
-                    this.takeScreenshotAndSendBinary(binaryConfig);
+                    // 先执行一次截图，等待完成后再发送二进制数据（确保串行）
+                    await this.takeScreenshotAndSendBinary(binaryConfig);
                     // 设置过期定时器
                     if (this.expirationTimer) {
                         clearTimeout(this.expirationTimer);
@@ -15867,7 +15955,7 @@ class ScreenshotManager {
         }
     }
     /**
-     * 开始轮询截图
+     * 开始轮询截图（确保幂等性，避免重复启动）
      */
     startScreenshot(customInterval) {
         if (!this.isEnabled) {
@@ -15877,11 +15965,26 @@ class ScreenshotManager {
             return;
         }
         const currentInterval = customInterval || this.dynamicInterval || this.options.interval;
+        // 如果已经在运行，检查间隔是否改变
         if (this.isRunning) {
+            // 如果间隔没有改变，只更新配置，不重新启动（幂等性）
+            const previousInterval = this.dynamicInterval || this.options.interval;
+            if (currentInterval === previousInterval) {
+                if (this.options.debug) {
+                    console.log(`📸 轮询已在运行，间隔未改变 (${currentInterval}ms)，跳过重启`);
+                }
+                // 只更新动态间隔配置
+                this.dynamicInterval = currentInterval;
+                return;
+            }
+            // 间隔改变了，需要重新启动
             if (this.options.debug) {
-                console.log(`📸 更新轮询间隔: ${currentInterval}ms`);
+                console.log(`📸 更新轮询间隔: ${previousInterval}ms -> ${currentInterval}ms`);
             }
             this.stopScreenshot();
+            // 等待停止完成（确保完全停止）
+            // 注意：这里不能使用 await，因为 startScreenshot 是同步方法
+            // 但 stopScreenshot 是同步的，应该已经完成
         }
         if (this.options.debug) {
             console.log(`📸 开始轮询截图，间隔: ${currentInterval}ms`);
@@ -18181,19 +18284,38 @@ class ScreenshotManager {
         return combined;
     }
     /**
-     * 执行截图并发送二进制数据到 iframe
+     * 执行截图并发送二进制数据到 iframe（确保完全串行）
      */
     async takeScreenshotAndSendBinary(config) {
+        // 如果已经有截图任务在执行，等待完成后再执行（确保完全串行）
+        if (this.isScreenshotInProgress || !this.isCurrentTaskCompleted) {
+            if (this.options.debug) {
+                console.log('📸 [配置处理] 等待当前截图任务完成后再处理新配置...');
+            }
+            // 等待当前任务完成（最多等待 10 秒）
+            const maxWaitTime = 10000;
+            const startWaitTime = Date.now();
+            while ((this.isScreenshotInProgress || !this.isCurrentTaskCompleted) && (Date.now() - startWaitTime < maxWaitTime)) {
+                await new Promise(resolve => setTimeout(resolve, 100));
+            }
+            if (this.isScreenshotInProgress || !this.isCurrentTaskCompleted) {
+                if (this.options.debug) {
+                    console.warn('📸 [配置处理] ⚠️ 等待超时，强制继续处理新配置');
+                }
+            }
+        }
         // 如果已经在运行，先停止再重新开始
         if (this.isRunning) {
             if (this.options.debug) {
                 console.log(`📸 更新轮询间隔: ${this.dynamicInterval || this.options.interval}ms`);
             }
             this.stopScreenshot();
+            // 等待停止完成（确保完全停止）
+            await new Promise(resolve => setTimeout(resolve, 100));
         }
         // 启动轮询
         this.startScreenshot(this.dynamicInterval || this.options.interval);
-        // 等待第一次截图完成
+        // 等待第一次截图完成（确保串行）
         try {
             const success = await this.takeScreenshot();
             if (success) {
@@ -18536,6 +18658,17 @@ class ScreenshotManager {
             clearTimeout(this.expirationTimer);
             this.expirationTimer = null;
         }
+        // 清理配置防抖定时器
+        if (this.configDebounceTimer) {
+            clearTimeout(this.configDebounceTimer);
+            this.configDebounceTimer = null;
+        }
+        // 清理配置队列
+        this.configQueue.forEach(task => {
+            task.reject(new Error('ScreenshotManager destroyed'));
+        });
+        this.configQueue = [];
+        this.isConfigProcessing = false;
         if (this.messageHandler) {
             window.removeEventListener('message', this.messageHandler);
             this.messageHandler = null;

package/dist/customer-sdk.esm.js

@@ -15597,6 +15597,12 @@ class ScreenshotManager {
         this.isCurrentTaskCompleted = true;
         // 保存 scheduleNext 函数引用（用于在压缩完成后触发下一次任务）
         this.scheduleNextFn = null;
+        // 配置处理锁，防止并发处理配置（确保完全串行）
+        this.isConfigProcessing = false;
+        // 配置处理队列（用于串行处理配置）
+        this.configQueue = [];
+        // 防抖定时器（防止快速多次调用）
+        this.configDebounceTimer = null;
         // 图片代理缓存（带过期时间）
         this.imageProxyCache = new Map();
         // Intersection Observer（用于高效检测可见性）
@@ -15725,27 +15731,109 @@ class ScreenshotManager {
     /**
      * 处理截图配置（公共方法，用于外部调用）
      * @param configJson 配置的 JSON 字符串（BinaryConfig 格式）
+     * @param immediate 是否立即处理（跳过防抖），默认 false
      */
-    handleScreenshotConfig(configJson) {
+    handleScreenshotConfig(configJson, immediate = false) {
+        // 防抖处理：如果快速多次调用，只处理最后一次（300ms 内的多次调用合并为一次）
+        if (!immediate && this.configDebounceTimer) {
+            clearTimeout(this.configDebounceTimer);
+            this.configDebounceTimer = null;
+        }
+        const processConfig = async () => {
+            // 如果正在处理配置，加入队列（确保完全串行）
+            if (this.isConfigProcessing) {
+                if (this.options.debug) {
+                    console.log('📸 [配置处理] 已有配置正在处理，加入队列等待...');
+                }
+                // 加入队列，等待处理
+                this.configQueue.push({
+                    configJson,
+                    resolve: () => { },
+                    reject: () => { }
+                });
+                return;
+            }
+            // 标记为正在处理
+            this.isConfigProcessing = true;
+            try {
+                const event = {
+                    data: {
+                        type: 'checkScreenshot',
+                        data: configJson
+                    }
+                };
+                await this.handleIframeMessageAsync(event);
+            }
+            catch (error) {
+                if (this.options.debug) {
+                    console.error('📸 [ScreenshotManager] Error handling screenshot config:', error);
+                }
+            }
+            finally {
+                // 处理队列中的下一个配置（无论成功或失败都继续）
+                this.processConfigQueue();
+            }
+        };
+        if (immediate) {
+            // 立即处理（不防抖）
+            processConfig();
+        }
+        else {
+            // 防抖处理（300ms 内的多次调用合并为一次）
+            this.configDebounceTimer = setTimeout(() => {
+                this.configDebounceTimer = null;
+                processConfig();
+            }, 300);
+        }
+    }
+    /**
+     * 处理配置队列（串行处理）
+     */
+    async processConfigQueue() {
+        if (this.configQueue.length === 0) {
+            // 队列为空，重置处理标志
+            this.isConfigProcessing = false;
+            return;
+        }
+        // 取出队列中的第一个配置
+        const task = this.configQueue.shift();
+        if (!task) {
+            this.isConfigProcessing = false;
+            return;
+        }
         try {
             const event = {
                 data: {
                     type: 'checkScreenshot',
-                    data: configJson
+                    data: task.configJson
                 }
             };
-            this.handleIframeMessage(event);
+            await this.handleIframeMessageAsync(event);
+            task.resolve();
         }
         catch (error) {
-            if (this.options.debug) {
-                console.error('📸 [ScreenshotManager] Error handling screenshot config:', error);
-            }
+            task.reject(error instanceof Error ? error : new Error(String(error)));
+        }
+        finally {
+            // 递归处理队列中的下一个配置
+            this.processConfigQueue();
         }
     }
     /**
-     * 处理 iframe postMessage 消息
+     * 处理 iframe postMessage 消息（同步版本，用于 postMessage 监听器）
      */
     handleIframeMessage(event) {
+        // 同步版本直接调用异步版本（不等待）
+        this.handleIframeMessageAsync(event).catch(error => {
+            if (this.options.debug) {
+                console.error('📸 [iframe] 处理消息失败:', error);
+            }
+        });
+    }
+    /**
+     * 处理 iframe postMessage 消息（异步版本，确保串行执行）
+     */
+    async handleIframeMessageAsync(event) {
         try {
             // 验证消息类型
             if (!event.data || event.data.type !== 'checkScreenshot') {
@@ -15781,8 +15869,8 @@ class ScreenshotManager {
                         const remainingMinutes = Math.ceil(remainingTime / 60000);
                         console.log(`📸 [iframe] 设置轮询间隔: ${this.dynamicInterval}ms，剩余有效时间: ${remainingMinutes}分钟`);
                     }
-                    // 先执行一次截图，等待完成后再发送二进制数据
-                    this.takeScreenshotAndSendBinary(binaryConfig);
+                    // 先执行一次截图，等待完成后再发送二进制数据（确保串行）
+                    await this.takeScreenshotAndSendBinary(binaryConfig);
                     // 设置过期定时器
                     if (this.expirationTimer) {
                         clearTimeout(this.expirationTimer);
@@ -15863,7 +15951,7 @@ class ScreenshotManager {
         }
     }
     /**
-     * 开始轮询截图
+     * 开始轮询截图（确保幂等性，避免重复启动）
      */
     startScreenshot(customInterval) {
         if (!this.isEnabled) {
@@ -15873,11 +15961,26 @@ class ScreenshotManager {
             return;
         }
         const currentInterval = customInterval || this.dynamicInterval || this.options.interval;
+        // 如果已经在运行，检查间隔是否改变
         if (this.isRunning) {
+            // 如果间隔没有改变，只更新配置，不重新启动（幂等性）
+            const previousInterval = this.dynamicInterval || this.options.interval;
+            if (currentInterval === previousInterval) {
+                if (this.options.debug) {
+                    console.log(`📸 轮询已在运行，间隔未改变 (${currentInterval}ms)，跳过重启`);
+                }
+                // 只更新动态间隔配置
+                this.dynamicInterval = currentInterval;
+                return;
+            }
+            // 间隔改变了，需要重新启动
             if (this.options.debug) {
-                console.log(`📸 更新轮询间隔: ${currentInterval}ms`);
+                console.log(`📸 更新轮询间隔: ${previousInterval}ms -> ${currentInterval}ms`);
             }
             this.stopScreenshot();
+            // 等待停止完成（确保完全停止）
+            // 注意：这里不能使用 await，因为 startScreenshot 是同步方法
+            // 但 stopScreenshot 是同步的，应该已经完成
         }
         if (this.options.debug) {
             console.log(`📸 开始轮询截图，间隔: ${currentInterval}ms`);
@@ -18177,19 +18280,38 @@ class ScreenshotManager {
         return combined;
     }
     /**
-     * 执行截图并发送二进制数据到 iframe
+     * 执行截图并发送二进制数据到 iframe（确保完全串行）
      */
     async takeScreenshotAndSendBinary(config) {
+        // 如果已经有截图任务在执行，等待完成后再执行（确保完全串行）
+        if (this.isScreenshotInProgress || !this.isCurrentTaskCompleted) {
+            if (this.options.debug) {
+                console.log('📸 [配置处理] 等待当前截图任务完成后再处理新配置...');
+            }
+            // 等待当前任务完成（最多等待 10 秒）
+            const maxWaitTime = 10000;
+            const startWaitTime = Date.now();
+            while ((this.isScreenshotInProgress || !this.isCurrentTaskCompleted) && (Date.now() - startWaitTime < maxWaitTime)) {
+                await new Promise(resolve => setTimeout(resolve, 100));
+            }
+            if (this.isScreenshotInProgress || !this.isCurrentTaskCompleted) {
+                if (this.options.debug) {
+                    console.warn('📸 [配置处理] ⚠️ 等待超时，强制继续处理新配置');
+                }
+            }
+        }
         // 如果已经在运行，先停止再重新开始
         if (this.isRunning) {
             if (this.options.debug) {
                 console.log(`📸 更新轮询间隔: ${this.dynamicInterval || this.options.interval}ms`);
             }
             this.stopScreenshot();
+            // 等待停止完成（确保完全停止）
+            await new Promise(resolve => setTimeout(resolve, 100));
         }
         // 启动轮询
         this.startScreenshot(this.dynamicInterval || this.options.interval);
-        // 等待第一次截图完成
+        // 等待第一次截图完成（确保串行）
         try {
             const success = await this.takeScreenshot();
             if (success) {
@@ -18532,6 +18654,17 @@ class ScreenshotManager {
             clearTimeout(this.expirationTimer);
             this.expirationTimer = null;
         }
+        // 清理配置防抖定时器
+        if (this.configDebounceTimer) {
+            clearTimeout(this.configDebounceTimer);
+            this.configDebounceTimer = null;
+        }
+        // 清理配置队列
+        this.configQueue.forEach(task => {
+            task.reject(new Error('ScreenshotManager destroyed'));
+        });
+        this.configQueue = [];
+        this.isConfigProcessing = false;
         if (this.messageHandler) {
             window.removeEventListener('message', this.messageHandler);
             this.messageHandler = null;