senza-sdk 4.4.8 → 4.4.10

package/package.json

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

package/src/implementation/lifecycle.js

@@ -101,12 +101,6 @@ class Lifecycle extends LifecycleInterface {
          */
         this._backgroundTimestamp = Date.now();
 
-        /**
-         * Flag to track if suspend was triggered by timer
-         * @type {boolean}
-         * @private
-         */
-        this._isSuspendTriggeredByTimer = false;
 
         this._isInTransitionToSuspended = false;
 
@@ -321,7 +315,7 @@ class Lifecycle extends LifecycleInterface {
                 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();
+                    this.moveToForeground(true);
                 } else {
                     this._startCountdown();
                 }
@@ -602,25 +596,9 @@ class Lifecycle extends LifecycleInterface {
         // Only start countdown if delay is positive
         if (timeoutDelay > 0) {
             sdkLogger.debug("Starting countdown timeout", timeoutDelay, isPlaying ? "(video)" : "(UI)");
-            this._countdown = setTimeout(async () => {
+            this._countdown = setTimeout(() => {
                 sdkLogger.debug("Countdown timeout reached, moving to background");
-
-                // Create the event with cancelable: true
-                const event = new Event("beforestatechange", { cancelable: true });
-                event.state = this.UiState.BACKGROUND;
-                // 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("moveToBackground was prevented by a listener");
-                    // Restart the countdown since the move was cancelled
-                    if (this._isForegroundOrTransitioning()) {
-                        this._startCountdown();
-                    }
-                } else {
-                    this.moveToBackground(true);
-                }
-
+                this.moveToBackground(true);
             }, timeoutDelay * 1000);
         } else {
             sdkLogger.debug("Countdown not started - delay is negative or zero");
@@ -657,30 +635,14 @@ class Lifecycle extends LifecycleInterface {
             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);
-                        }
+                    try {
+                        await this.moveToSuspended(true);
+                    } 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");
@@ -695,8 +657,6 @@ class Lifecycle extends LifecycleInterface {
             sdkLogger.debug("Stopping suspend countdown timer");
             clearTimeout(this._suspendCountdown);
             this._suspendCountdown = null;
-            // Reset the timer flag when stopping countdown
-            this._isSuspendTriggeredByTimer = false;
         }
     }
 
@@ -727,7 +687,7 @@ class Lifecycle extends LifecycleInterface {
         sdkLogger.warn("lifecycle getState is not supported if NOT running e2e");
     }
 
-    moveToForeground() {
+    async moveToForeground(isSystemTriggered = false) {
         if (!_isUiReady()) {
             sdkLogger.warn("lifecycle moveToForeground: UI is not ready yet. Make sure to call senza.uiReady() before calling lifecycle.moveToForeground()");
         }
@@ -747,6 +707,19 @@ class Lifecycle extends LifecycleInterface {
                 sdkLogger.warn(`lifecycle moveToForeground: No need to transition to foreground, state: ${this._state} transition: ${inTransition}`);
                 return Promise.resolve(false);
             }
+
+            // Fire beforestatechange event
+            const event = new Event("beforestatechange", { cancelable: true });
+            event.state = this.UiState.FOREGROUND;
+            event.isSystemTriggered = isSystemTriggered;
+            await this._eventManager.dispatch("beforestatechange", event);
+
+            // Check if any listener called preventDefault()
+            if (event.defaultPrevented) {
+                sdkLogger.info("moveToForeground was prevented by a listener");
+                return Promise.resolve(false);
+            }
+
             this._inTransitionToForeground = true;
             bus.dispatchEvent(new Event(Events.LifecycleForeground));
             const FCID = getFCID();
@@ -918,13 +891,13 @@ class Lifecycle extends LifecycleInterface {
         return Promise.resolve(false);
     }
 
-    moveToBackground(isTriggeredByTimer = false) {
+    async moveToBackground(isSystemTriggered = false) {
         if (this._isInTransitionToSuspended) {
             sdkLogger.error("lifecycle moveToBackground: Currently in transition to suspend, cannot move to background");
             return Promise.resolve(false);
         }
         // If the background transition is triggered by the auto background timer, set the flag
-        this._isBackgroundTriggeredByTimer = isTriggeredByTimer;
+        this._isBackgroundTriggeredByTimer = isSystemTriggered;
 
         if (window.cefQuery) {
             const inTransition = this._isInTransition();
@@ -932,6 +905,24 @@ class Lifecycle extends LifecycleInterface {
                 sdkLogger.warn(`lifecycle moveToBackground: No need to transition to background, state: ${this._state} transition: ${inTransition}`);
                 return Promise.resolve(false);
             }
+
+            // Fire beforestatechange event
+            const event = new Event("beforestatechange", { cancelable: true });
+            event.state = this.UiState.BACKGROUND;
+            event.isSystemTriggered = isSystemTriggered;
+            await this._eventManager.dispatch("beforestatechange", event);
+
+            // Check if any listener called preventDefault()
+            if (event.defaultPrevented) {
+                sdkLogger.info("moveToBackground was prevented by a listener");
+                // Clear the timer flag if the move was prevented
+                this._isBackgroundTriggeredByTimer = false;
+                // Restart the countdown if it was triggered by timer
+                if (isSystemTriggered && this._isForegroundOrTransitioning()) {
+                    this._startCountdown();
+                }
+                return Promise.resolve(false);
+            }
             if (remotePlayer._isSeekingByApplication) {
                 remotePlayer._targetSeekPlayingState = TargetPlayingState.PLAYING_ABR;
                 return Promise.resolve(true);
@@ -1076,7 +1067,7 @@ class Lifecycle extends LifecycleInterface {
         return Promise.reject("disconnect is not supported if NOT running e2e");
     }
 
-    moveToSuspended() {
+    async moveToSuspended(isSystemTriggered = false) {
         // 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}`;
@@ -1084,20 +1075,35 @@ class Lifecycle extends LifecycleInterface {
             return Promise.reject(errorMsg);
         }
 
+        // Fire beforestatechange event
+        const event = new Event("beforestatechange", { cancelable: true });
+        event.state = this.UiState.SUSPENDED;
+        event.isSystemTriggered = isSystemTriggered;
+        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 if it was triggered by timer
+            if (isSystemTriggered && this._isAutoSuspendEnabled()) {
+                this._startSuspendCountdown();
+            }
+            return Promise.resolve(false);
+        }
+
         this._isInTransitionToSuspended = true;
         // Report metrics for time between background and suspend
         const duration = (Date.now() - this._backgroundTimestamp) / 1000;
 
         sdkLogger.metrics({
             type: "suspendTransitions",
-            isAutoSuspend: this._isSuspendTriggeredByTimer,
+            isAutoSuspend: isSystemTriggered,
             isPlaying: remotePlayer._isPlaying,
             duration
         });
 
         // Reset the timer flag after reporting metrics
-        const reason = this._isSuspendTriggeredByTimer ? "timer" : "appInitiated";
-        this._isSuspendTriggeredByTimer = false;
+        const reason = isSystemTriggered ? "timer" : "appInitiated";
 
         if (window.cefQuery) {
             return new Promise((resolve, reject) => {

package/src/interface/lifecycle.js

@@ -16,18 +16,32 @@ import {
 /**
  * @event Lifecycle#beforestatechange
  * @description Fired before transitioning to a new state. This event is cancelable.<br>
- * Currently only fired when transitioning to BACKGROUND and SUSPENDED state (e.g., from autoBackground feature).<br>
+ * Fired when transitioning to FOREGROUND, BACKGROUND, or SUSPENDED state.<br>
  * The actual state transition will occur after all event listeners have completed processing.
- * Can be used to prevent automatic transitions to background state when using autoBackground feature, or for suspneded from autoSuspended feature .
- * @property {UiState} state - Indicates the target state the lifecycle is trying to transition to.
+ * Can be used to prevent automatic transitions (e.g., from autoBackground or autoSuspend features) or
+ * to perform cleanup operations before state changes.
+ * @property {UiState} state - Indicates the target state the lifecycle is trying to transition to (FOREGROUND, BACKGROUND, or SUSPENDED).
+ * @property {boolean} isSystemTriggered - Indicates whether the transition was triggered by the system (e.g., auto background timer, auto suspend timer) or by the application.
  * @property {boolean} cancelable - true, indicating the event can be cancelled using preventDefault()
  * @example
+ * // Prevent automatic background transition when user is actively interacting
  * lifecycle.addEventListener("beforestatechange", (e) => {
- *     if (e.state === lifecycle.UiState.BACKGROUND && userIsInteracting) {
- *         // Prevent transition to background
+ *     if (e.state === lifecycle.UiState.BACKGROUND && e.isSystemTriggered && userIsInteracting) {
+ *         console.log("Preventing automatic background transition");
  *         e.preventDefault();
  *     }
  * });
+ *
+ * @example
+ * // Save application state before moving to suspended
+ * lifecycle.addEventListener("beforestatechange", async (e) => {
+ *     if (e.state === lifecycle.UiState.SUSPENDED) {
+ *         console.log("Saving application state before suspend");
+ *         await saveApplicationState();
+ *     }
+ * });
+ *
+
  */
 
 /**

package/src/interface/version.js

@@ -1 +1 @@
-export const version = "4.4.8";
+export const version = "4.4.10";