Lifecycle

The application lifecycle has four states:

• Foreground: when the user interface is displayed
• Background: when the remote player is playing full screen video
• Transition to Foreground: in process of switching to the user interface
• Transition to Background: in process of switching to the remote player

State Management

In background mode, after a period of time the application is unloaded to save resources. It will be reloaded on the next key press, end-of-stream event, error event or request of a DRM license (either content or renewal).

In order for the user to resume where they left off, your app should preserve its state as follows:

1. Before switching to the background, save the current state to local storage or session storage.
2. After switching to the foreground, restore the state from local or session storage if the app has been restarted.

📘

State Storage

See the guide on Preserving State to learn more about persistency of storage across UI release and reboots.

The sections below explain the Client Library APIs for App Lifecycle management.

Modules

lifecycle ⇒ Lifecycle

Classes

Lifecycle

Lifecycle is a singleton class that manages the application lifecycle states.

Typedefs

ConnectReason : Object

The reason the ui app has been loaded

UiState : Object

The ui lifecycle state

lifecycle ⇒ Lifecycle

Returns: Lifecycle - pointer to the Lifecycle singleton
Example

import { lifecycle } from "senza-sdk";

Lifecycle

Lifecycle is a singleton class that manages the application lifecycle states.

Kind: global class
Emits: event:onstatechange, event:userinactivity, event:userdisconnected

• Lifecycle
  • .state ⇒ UiState
  • .connectReason ⇒ ConnectReason
  • .triggerEvent ⇒ Object
  • .autoBackground : boolean
  • .autoBackgroundDelay : integer
  • .autoBackgroundOnUIDelay : integer
  • ._moveToUiStandby()
  • .getState() ⇒ UiState
  • .moveToForeground() ⇒ Promise
  • .moveToBackground() ⇒ Promise
  • .switchTenant(tenantId) ⇒ Promise
  • .exitApplication() ⇒ Promise
  • "onstatechange"
  • "userinactivity"
  • "userdisconnected"

lifecycle.state ⇒ UiState

Getter for returning the ui lifecycle state

Kind: instance property of Lifecycle
Returns: UiState - the current application lifecycle state

lifecycle.connectReason ⇒ ConnectReason

Getter for returning the application connection reason

Kind: instance property of Lifecycle
Returns: ConnectReason - the application connection reason

lifecycle.triggerEvent ⇒ Object

Getter for returning the event that triggered the reloading of the ui after ui has been released

Kind: instance property of Lifecycle
Returns: Object - trigger event
Properties

lifecycle.autoBackground : boolean

Controls the autoBackground feature

When enabled, the application will automatically move to the background state after a configurable
period of inactivity. The delay depends on whether video is playing (autoBackgroundDelay)
or the UI is idle (autoBackgroundOnUIDelay).
The application will return to the foreground state when a key is pressed.

Kind: instance property of Lifecycle

lifecycle.autoBackgroundDelay : integer

The number of seconds of user inactivity before the application moves to the background state while playing video.
This setting is used when remotePlayer is in playing state.

Kind: instance property of Lifecycle
Default: 30

lifecycle.autoBackgroundOnUIDelay : integer

The number of seconds of user inactivity before the application moves to the background state while in the UI (not playing).
This setting is used when remotePlayer is not in playing state.

Kind: instance property of Lifecycle
Default: 30

lifecycle._moveToUiStandby()

This method moves the application into standby mode, i.e. last ui frame is displayed and ui resources are released.
It should be called whenever the application wishes to go into standby mode and release resources.

Kind: instance method of Lifecycle
Example

lifecycle._moveToUiStandby();

lifecycle.getState() ⇒ UiState

Deprecated

Kind: instance method of Lifecycle
Returns: UiState - the current application lifecycle state
Example

try {
    const state = await lifecycle.getState();
    console.log("current state is", state);
} catch (e) {
    console.error("getState failed", e);
}

lifecycle.moveToForeground() ⇒ Promise

Once playback starts on the remote player,
the application is moved from foreground to inTransitionToBackground and eventually to background.
The application will need to call moveToForeground when it receives an event that needs the UI to be displayed again,
for example a key press, a playback end-of-file or a playback error.

Kind: instance method of Lifecycle
Returns: Promise - Promise which is resolved when the moveToForeground command has been successfully processed.
Failure to process the moveToForeground command will result in the promise being rejected.

lifecycle.moveToBackground() ⇒ Promise

This method moves the application to the background.
It should be called after remotePlayer.play().
As a consequence, remote player playback will be displayed in full screen.

Kind: instance method of Lifecycle
Returns: Promise - Promise which is resolved when the moveToBackground command has been successfully processed.
Failure to process the moveToBackground command will result in the promise being rejected.
Example

remotePlayer.load("https://example.com/video.mp4", 0);
remotePlayer.play();
lifecycle.moveToBackground();

lifecycle.switchTenant(tenantId) ⇒ Promise

Use this api to switch to another tenant (other than the home tenant) which will launch the application associated with the tenantId. The tenantId must be configured in the
Senza platform. Switching to the home tenant should use the exitApplication().

Kind: instance method of Lifecycle
Returns: Promise - Promise which is resolved when the switchTenant command has been successfully processed.
Failure to process the switchTenant command will result in the promise being rejected.

lifecycle.exitApplication() ⇒ Promise

Use this api to exit the application which will redirect the browser to the home tenant application.

Kind: instance method of Lifecycle
Returns: Promise - Promise which is resolved when the exitApplication command has been successfully processed.
Failure to process the exitApplication command will result in the promise being rejected.

"onstatechange"

Fired after transition from one state to another.

The flow is: foreground --> inTransitionToBackground --> background --> inTransitionToForeground --> foreground

Kind: event emitted by Lifecycle
Properties

Example

lifecycle.addEventListener("onstatechange", (e) => {
    console.log("new state is", e.state);
});

"userinactivity"

Fired after the user has been inactive (i.e. no key presses) for a configurable number of seconds.

Kind: event emitted by Lifecycle
Alpha: API has not yet been released
Properties

Example

lifecycle.addEventListener("userinactivity", (e) => {
    console.log(`Application will be unloaded in ${e.timeout} seconds`);
});

"userdisconnected"

Fired when the user session ends .
This event is useful for cleaning up application state or saving data before the application closes.

Kind: event emitted by Lifecycle

Alpha: API has not yet been released

Example

lifecycle.addEventListener("userdisconnected", () => {
    console.log("User session ended, cleaning up application state");
    // Perform any necessary cleanup here
});

ConnectReason : Object

The reason the ui app has been loaded

Kind: global typedef
Properties

UiState : Object

The ui lifecycle state

Kind: global typedef
Properties