senza-sdk 4.4.5 → 4.4.6

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "senza-sdk",
-    "version": "4.4.5",
+    "version": "4.4.6",
     "main": "./src/api.js",
     "description": "API for Senza application",
     "license": "MIT",

package/src/implementation/lifecycle.js

@@ -17,9 +17,15 @@ import { DEFAULT_REMOTE_PLAYER_CONFIRMATION_TIMEOUT, remotePlayer } from "./remo
 import {bus, Events} from "./eventBus";
 
 // Default values for autoBackground settings. These values are used if the UIStreamer settings are not provided.
-const DEFAULT_AUTO_BACKGROUND_VIDEO_DELAY = 30;
-const DEFAULT_AUTO_BACKGROUND_UI_DELAY = -1;
-const DEFAULT_AUTO_BACKGROUND_ENABLED = false;
+const DEFAULT_AUTO_BACKGROUND_VIDEO_DELAY = 10*60;
+const DEFAULT_AUTO_BACKGROUND_UI_DELAY = 10*60;
+const DEFAULT_AUTO_BACKGROUND_ENABLED = true;
+// Default values for autoSuspend settings
+const DEFAULT_AUTO_SUSPEND_ENABLED = false;
+const DEFAULT_AUTO_SUSPEND_PLAYING_DELAY = 60;
+const DEFAULT_AUTO_SUSPEND_IDLE_DELAY = 60;
+// Session storage key for tracking timer-triggered background state
+const BACKGROUND_TIMER_KEY = "senzaSDK_backgroundTriggeredByTimer";
 
 class Lifecycle extends LifecycleInterface {
     constructor() {
@@ -60,6 +66,81 @@ class Lifecycle extends LifecycleInterface {
          * @private
          */
         this._autoBackgroundOnUIDelay = DEFAULT_AUTO_BACKGROUND_UI_DELAY;
+
+        /**
+         * Timestamp of the last user activity
+         * @type {number}
+         * @private
+         */
+        this._lastActivityTimestamp = Date.now();
+
+        /**
+         * Auto suspend configuration
+         * @type {Object}
+         * @private
+         */
+        this._autoSuspend = {
+            enabled: DEFAULT_AUTO_SUSPEND_ENABLED,
+            timeout: {
+                playing: DEFAULT_AUTO_SUSPEND_PLAYING_DELAY,
+                idle: DEFAULT_AUTO_SUSPEND_IDLE_DELAY
+            }
+        };
+
+        /**
+         * Timer for auto suspend functionality
+         * @type {number|null}
+         * @private
+         */
+        this._suspendCountdown = null;
+
+        /**
+         * Timestamp when the application entered background state
+         * @type {number}
+         * @private
+         */
+        this._backgroundTimestamp = Date.now();
+
+        /**
+         * Flag to track if suspend was triggered by timer
+         * @type {boolean}
+         * @private
+         */
+        this._isSuspendTriggeredByTimer = false;
+
+    }
+
+    /**
+     * @private Gets the background triggered by timer flag from sessionStorage
+     * @returns {boolean}
+     */
+    get _isBackgroundTriggeredByTimer() {
+        try {
+            const value = typeof window !== "undefined" && window.sessionStorage ?
+                window.sessionStorage.getItem(BACKGROUND_TIMER_KEY) : null;
+            return value === "true";
+        } catch (error) {
+            sdkLogger.warn("Failed to read _isBackgroundTriggeredByTimer from sessionStorage:", error);
+            return false;
+        }
+    }
+
+    /**
+     * @private Sets the background triggered by timer flag in sessionStorage
+     * @param {boolean} value
+     */
+    set _isBackgroundTriggeredByTimer(value) {
+        try {
+            if (typeof window !== "undefined" && window.sessionStorage) {
+                if (value) {
+                    window.sessionStorage.setItem(BACKGROUND_TIMER_KEY, "true");
+                } else {
+                    window.sessionStorage.removeItem(BACKGROUND_TIMER_KEY);
+                }
+            }
+        } catch (error) {
+            sdkLogger.warn("Failed to write _backgroundTriggeredByTimer to sessionStorage:", error);
+        }
     }
 
     // List of event types that should use the _eventManager
@@ -76,6 +157,11 @@ class Lifecycle extends LifecycleInterface {
      * @param {Object} [uiStreamerSettings.autoBackground.timeout] - Timeout settings
      * @param {number|false} [uiStreamerSettings.autoBackground.timeout.playing=30] - Timeout in seconds when video is playing, false to disable
      * @param {number|false} [uiStreamerSettings.autoBackground.timeout.idle=false] - Timeout in seconds when in UI mode, false to disable
+     * @param {Object} [uiStreamerSettings.autoSuspend] - Auto suspend mode configuration
+     * @param {boolean} [uiStreamerSettings.autoSuspend.enabled=false] - Enable/disable auto suspend
+     * @param {Object} [uiStreamerSettings.autoSuspend.timeout] - Timeout settings
+     * @param {number} [uiStreamerSettings.autoSuspend.timeout.playing=60] - Timeout in seconds when video is playing
+     * @param {number} [uiStreamerSettings.autoSuspend.timeout.idle=60] - Timeout in seconds when in idle mode
      * @param {number} [uiStreamerSettings.remotePlayerConfirmationTimeout=5000] - Timeout in milliseconds for remote player operations
      * @param {number} [uiStreamerSettings.remotePlayerApiVersion=1] - Remote player API version
      */
@@ -171,6 +257,13 @@ class Lifecycle extends LifecycleInterface {
                     autoBackground: uiStreamerSettings.autoBackground
                 });
             }
+
+            // Apply autoSuspend settings if provided
+            if (uiStreamerSettings?.autoSuspend) {
+                this.configure({
+                    autoSuspend: uiStreamerSettings.autoSuspend
+                });
+            }
         }
     }
 
@@ -186,6 +279,17 @@ class Lifecycle extends LifecycleInterface {
             if (this._isAutoBackgroundEnabled() && this._isForegroundOrTransitioning()) {
                 this._startCountdown();
             }
+            // Track timestamp when entering background state
+            if (this._state === this.UiState.BACKGROUND) {
+                this._backgroundTimestamp = Date.now();
+            }
+            // Start suspend countdown when entering background state
+            if (this._isAutoSuspendEnabled() && this._state === this.UiState.BACKGROUND) {
+                this._startSuspendCountdown();
+            } else {
+                // Stop suspend countdown when leaving background state
+                this._stopSuspendCountdown();
+            }
             this.dispatchEvent(event);
         });
 
@@ -207,9 +311,14 @@ class Lifecycle extends LifecycleInterface {
         });
 
         typeof document !== "undefined" && document.addEventListener("keydown", () => {
+            // Track the timestamp of the last user activity
+            this._lastActivityTimestamp = Date.now();
+
             if (this._isAutoBackgroundEnabled()) {
-                if (this.state === this.UiState.BACKGROUND ||
-                    this.state === this.UiState.IN_TRANSITION_TO_BACKGROUND) {
+
+                if (this._isBackgroundTriggeredByTimer && (this.state === this.UiState.BACKGROUND ||
+                    this.state === this.UiState.IN_TRANSITION_TO_BACKGROUND)) {
+                    sdkLogger.log("Moving to foreground due to user interaction after auto background");
                     this.moveToForeground();
                 } else {
                     this._startCountdown();
@@ -223,6 +332,11 @@ class Lifecycle extends LifecycleInterface {
                 sdkLogger.log("Resetting auto background timer due to play mode change", event.detail.isPlaying);
                 this._startCountdown(event.detail.isPlaying);
             }
+            // Also restart suspend countdown if in background state
+            if (this._isAutoSuspendEnabled() && this._state === this.UiState.BACKGROUND) {
+                sdkLogger.log("Resetting auto suspend timer due to play mode change", event.detail.isPlaying);
+                this._startSuspendCountdown(event.detail.isPlaying);
+            }
         });
         sdkLogger.log("[Lifecycle] Added event listeners for system events");
     }
@@ -267,6 +381,30 @@ class Lifecycle extends LifecycleInterface {
         return this._autoBackgroundOnUIDelay;
     }
 
+    /**
+     * @private Checks if auto suspend is enabled.
+     * @returns {boolean}
+     */
+    _isAutoSuspendEnabled() {
+        return this._autoSuspend.enabled;
+    }
+
+    /**
+     * @private Gets the auto suspend playing delay.
+     * @returns {number}
+     */
+    _getAutoSuspendOnPlayingDelay() {
+        return this._autoSuspend.timeout.playing;
+    }
+
+    /**
+     * @private Gets the auto suspend idle delay.
+     * @returns {number}
+     */
+    _getAutoSuspendOnIdleDelay() {
+        return this._autoSuspend.timeout.idle;
+    }
+
     configure(config) {
         if (config?.autoBackground) {
             const { enabled, timeout } = config.autoBackground;
@@ -304,6 +442,39 @@ class Lifecycle extends LifecycleInterface {
                 this._stopCountdown();
             }
         }
+
+        if (config?.autoSuspend) {
+            const { enabled, timeout } = config.autoSuspend;
+
+            // Update enabled state
+            if (typeof enabled === "boolean") {
+                this._autoSuspend.enabled = enabled;
+            }
+            // Update timeouts
+            if (timeout) {
+                if (timeout.playing !== undefined) {
+                    if (typeof timeout.playing === "number") {
+                        this._autoSuspend.timeout.playing = timeout.playing;
+                    } else {
+                        sdkLogger.warn("Invalid autoSuspend.timeout.playing value, expected number");
+                    }
+                }
+                if (timeout.idle !== undefined) {
+                    if (typeof timeout.idle === "number") {
+                        this._autoSuspend.timeout.idle = timeout.idle;
+                    } else {
+                        sdkLogger.warn("Invalid autoSuspend.timeout.idle value, expected number");
+                    }
+                }
+            }
+
+            // Start or stop suspend countdown based on new configuration
+            if (this._isAutoSuspendEnabled() && this._state === this.UiState.BACKGROUND) {
+                this._startSuspendCountdown();
+            } else {
+                this._stopSuspendCountdown();
+            }
+        }
     }
 
     getConfiguration() {
@@ -314,6 +485,13 @@ class Lifecycle extends LifecycleInterface {
                     playing: this._autoBackgroundOnVideoDelay <= 0 ? false : this._autoBackgroundOnVideoDelay,
                     idle: this._autoBackgroundOnUIDelay <= 0 ? false : this._autoBackgroundOnUIDelay
                 }
+            },
+            autoSuspend: {
+                enabled: this._autoSuspend.enabled,
+                timeout: {
+                    playing: this._autoSuspend.timeout.playing,
+                    idle: this._autoSuspend.timeout.idle
+                }
             }
         };
     }
@@ -438,8 +616,9 @@ class Lifecycle extends LifecycleInterface {
                         this._startCountdown();
                     }
                 } else {
-                    this.moveToBackground();
+                    this.moveToBackground(true);
                 }
+
             }, timeoutDelay * 1000);
         } else {
             sdkLogger.debug("Countdown not started - delay is negative or zero");
@@ -457,6 +636,68 @@ class Lifecycle extends LifecycleInterface {
         }
     }
 
+    /**
+    * @private Start the suspend countdown timer when in background state
+    */
+    _startSuspendCountdown(isPlaying = remotePlayer._isPlaying) {
+        this._stopSuspendCountdown();
+
+        // Only start if we're in background state and auto suspend is enabled
+        if (this._state !== this.UiState.BACKGROUND || !this._isAutoSuspendEnabled()) {
+            return;
+        }
+
+        const timeoutDelay = isPlaying ? this._getAutoSuspendOnPlayingDelay() : this._getAutoSuspendOnIdleDelay();
+
+        // Only start countdown if delay is positive
+        if (timeoutDelay > 0) {
+            sdkLogger.debug("Starting suspend countdown timeout", timeoutDelay, isPlaying ? "(playing)" : "(idle)");
+            this._suspendCountdown = setTimeout(async () => {
+                sdkLogger.debug("Suspend countdown timeout reached, moving to suspended");
+                if (this._state === this.UiState.BACKGROUND) {
+                    // Create the event with cancelable: true
+                    const event = new Event("beforestatechange", { cancelable: true });
+                    event.state = this.UiState.SUSPENDED;
+                    // Use the event manager to dispatch the event and wait for all listeners
+                    await this._eventManager.dispatch("beforestatechange", event);
+                    // Check if any listener called preventDefault()
+                    if (event.defaultPrevented) {
+                        sdkLogger.info("moveToSuspended was prevented by a listener");
+                        // Restart the suspend countdown since the move was cancelled
+                        this._startSuspendCountdown();
+                    } else {
+                        try {
+                        // Set flag to indicate suspend was triggered by timer
+                            this._isSuspendTriggeredByTimer = true;
+                            await this.moveToSuspended();
+                        } catch (error) {
+                            sdkLogger.error("Failed to move to suspended:", error);
+                        }
+                    }
+
+                } else {
+                    sdkLogger.warn("suspend timer was called while not in background");
+                }
+
+            }, timeoutDelay * 1000);
+        } else {
+            sdkLogger.debug("Suspend countdown not started - delay is zero or negative");
+        }
+    }
+
+    /**
+    * @private Stop the suspend countdown timer
+    */
+    _stopSuspendCountdown() {
+        if (this._suspendCountdown) {
+            sdkLogger.debug("Stopping suspend countdown timer");
+            clearTimeout(this._suspendCountdown);
+            this._suspendCountdown = null;
+            // Reset the timer flag when stopping countdown
+            this._isSuspendTriggeredByTimer = false;
+        }
+    }
+
     /**
      * @private
      */
@@ -486,6 +727,12 @@ class Lifecycle extends LifecycleInterface {
     }
 
     moveToForeground() {
+        // Reset activity timestamp when moving to foreground
+        this._lastActivityTimestamp = Date.now();
+
+        // Clear the timer-triggered background flag when moving to foreground
+        this._isBackgroundTriggeredByTimer = false;
+
         if (window.cefQuery) {
             const inTransition = this._isInTransition();
             if (inTransition || this._isForegroundOrTransitioning()) {
@@ -566,6 +813,16 @@ class Lifecycle extends LifecycleInterface {
     }
 
     _moveToBackground() {
+        // Report metrics for time since last user activity when moving to background
+
+        const duration = (Date.now() - this._lastActivityTimestamp)/1000;
+
+        sdkLogger.metrics({
+            type: "backgroundTransitions",
+            isAutoBackground: this._isBackgroundTriggeredByTimer,
+            isPlaying: remotePlayer._isPlaying,
+            duration
+        });
         if (window.cefQuery) {
             // If audio sync is disabled, we only need to sync before remote player starts playing
             if (!isAudioSyncConfigured()) {
@@ -629,6 +886,8 @@ class Lifecycle extends LifecycleInterface {
                         const duration = Date.now() - timeBeforeSendingRequest;
                         logger.withFields({ duration }).log(`play failed after ${duration} ms. Error code: ${code}, error message: ${msg}`);
                         this._inTransitionToBackground = false;
+                        // Clear the timer flag even if the transition fails
+                        this._isBackgroundTriggeredByTimer = false;
                         timerId = clearTimer(timerId);
                         reject(new SenzaError(code, msg));
                     }
@@ -639,6 +898,8 @@ class Lifecycle extends LifecycleInterface {
                     timerId = setTimeout(() => {
                         logger.log(`play reached timeout of ${timeout} ms, canceling query id ${queryId}`);
                         this._inTransitionToBackground = false;
+                        // Clear the timer flag even if the transition times out
+                        this._isBackgroundTriggeredByTimer = false;
                         window.cefQueryCancel(queryId);
                         reject(new SenzaError(6000, `play reached timeout of ${timeout} ms`));
                     }, timeout, queryId);
@@ -649,7 +910,11 @@ class Lifecycle extends LifecycleInterface {
         return Promise.resolve(false);
     }
 
-    moveToBackground() {
+    moveToBackground(isTriggeredByTimer = false) {
+
+        // If the background transition is triggered by the auto background timer, set the flag
+        this._isBackgroundTriggeredByTimer = isTriggeredByTimer;
+
         if (window.cefQuery) {
             const inTransition = this._isInTransition();
             if (inTransition || this._state === this.UiState.BACKGROUND || this._state === this.UiState.IN_TRANSITION_TO_BACKGROUND) {
@@ -800,6 +1065,60 @@ class Lifecycle extends LifecycleInterface {
         return Promise.reject("disconnect is not supported if NOT running e2e");
     }
 
+    moveToSuspended() {
+        // Check if the current state is BACKGROUND
+        if (this._state !== this.UiState.BACKGROUND) {
+            const errorMsg = `moveToSuspended can only be called from BACKGROUND state. Current state: ${this._state}`;
+            sdkLogger.error(errorMsg);
+            return Promise.reject(errorMsg);
+        }
+
+        // Report metrics for time between background and suspend
+        const duration = (Date.now() - this._backgroundTimestamp) / 1000;
+
+        sdkLogger.metrics({
+            type: "suspendTransitions",
+            isAutoSuspend: this._isSuspendTriggeredByTimer,
+            isPlaying: remotePlayer._isPlaying,
+            duration
+        });
+
+        // Reset the timer flag after reporting metrics
+        const reason = this._isSuspendTriggeredByTimer ? "timer" : "appInitiated";
+        this._isSuspendTriggeredByTimer = false;
+
+        if (window.cefQuery) {
+            return new Promise((resolve, reject) => {
+                const FCID = getFCID();
+                const logger = sdkLogger.withFields({ FCID });
+                const message = {
+                    type: "suspend",
+                    reason,
+                    fcid: FCID
+                };
+                const request = { target: "TC",
+                    waitForResponse: false,
+                    message: JSON.stringify(message) };
+
+                logger.log("moveToSuspended: sending suspend message");
+                window.cefQuery({
+                    request: JSON.stringify(request),
+                    persistent: false,
+                    onSuccess: () => {
+                        logger.log("moveToSuspended request successfully sent");
+                        resolve(true);
+                    },
+                    onFailure: (code, msg) => {
+                        logger.error(`moveToSuspended failed: ${code} ${msg}`);
+                        reject(new SenzaError(code, msg));
+                    }
+                });
+            });
+        }
+        sdkLogger.warn("moveToSuspended is not supported if NOT running e2e");
+        return Promise.reject("moveToSuspended is not supported if NOT running e2e");
+    }
+
 
     addEventListener(type, listener, options) {
         if (Lifecycle._waitForListenersEvents.includes(type)) {

package/src/interface/lifecycle.js

@@ -100,10 +100,15 @@ class Lifecycle extends EventTarget {
      * Configure lifecycle settings
      * @param {Object} config - Configuration object
      * @param {Object} [config.autoBackground] - Auto background settings
-     * @param {boolean} [config.autoBackground.enabled] - Enable/disable auto background
+     * @param {boolean} [config.autoBackground.enabled=true] - Enable/disable auto background
      * @param {Object} [config.autoBackground.timeout] - Timeout settings
      * @param {number|false} [config.autoBackground.timeout.playing=30] - Timeout in seconds when video is playing, false to disable
-     * @param {number|false} [config.autoBackground.timeout.idle=false] - Timeout in seconds when in UI mode, false to disable
+     * @param {number|false} [config.autoBackground.timeout.idle=30] - Timeout in seconds when in UI mode, false to disable
+     * @param {Object} [config.autoSuspend] - Auto suspend settings
+     * @param {boolean} [config.autoSuspend.enabled=false] - Enable/disable auto suspend
+     * @param {Object} [config.autoSuspend.timeout] - Timeout settings
+     * @param {number} [config.autoSuspend.timeout.playing=60] - Timeout in seconds when video is playing before moving to suspended state
+     * @param {number} [config.autoSuspend.timeout.idle=60] - Timeout in seconds when in background mode before moving to suspended state
      */
     configure(config) {
         noop("lifecycle.configure", config);
@@ -114,9 +119,12 @@ class Lifecycle extends EventTarget {
      * @returns {Object} The current configuration object
      * @example
      * const config = lifecycle.getConfiguration();
-     * console.log(config.autoBackground.enabled); // true/false
+     * console.log(config.autoBackground.enabled); // true
      * console.log(config.autoBackground.timeout.playing); // 30
-     * console.log(config.autoBackground.timeout.idle); // false
+     * console.log(config.autoBackground.timeout.idle); // 30
+     * console.log(config.autoSuspend.enabled); // false
+     * console.log(config.autoSuspend.timeout.playing); // 60
+     * console.log(config.autoSuspend.timeout.idle); // 60
      */
     getConfiguration() {
         return {
@@ -126,6 +134,13 @@ class Lifecycle extends EventTarget {
                     playing: 0,
                     idle: 0
                 }
+            },
+            autoSuspend: {
+                enabled: false,
+                timeout: {
+                    playing: 0,
+                    idle: 0
+                }
             }
         };
     }
@@ -279,6 +294,17 @@ class Lifecycle extends EventTarget {
         return noop("lifecycle.disconnect");
     }
 
+    /**
+     * Use this api to move the application to suspended state.
+     * This method can only be called when the application is in BACKGROUND state.
+     * @return {Promise} Promise which is resolved when the suspend command has been successfully sent.
+     * Failure to process the suspend command will result in the promise being rejected.
+    * @alpha API has not yet been released
+    */
+    moveToSuspended() {
+        return noop("lifecycle.moveToSuspended");
+    }
+
     /**
      * Add event listener for lifecycle events
      * @param {string} type - The event type to listen for

package/src/interface/version.js

@@ -1 +1 @@
-export const version = "4.4.5";
+export const version = "4.4.6";