Lifecycle Integration

The Senza platform operates in two modes:

1. In foreground mode, your web app runs in a browser in the cloud, and the user interface is streamed to the cloud connector as a video.
2. In background mode, video content is streamed directly from the CDN to the cloud connector.

When your app is running in the browser in foreground mode, it consumes CPU and GPU resources that count towards your platform usage minutes. In background mode, the browser consumes fewer resources, so time spent does not count towards your platform usage. Therefore you'll want to adapt your app to use background mode as much as possible.

Background mode is primarily used for playing video streams, but you can also switch to background mode if you are not playing a video. If the remote player does not have a video loaded, or the video is not currently playing, the cloud connector will continue to display the last frame rendered by the web browser. (Coming soon)

When to use foreground mode

When the user is interacting with your app

In this case your web app runs as normal in the browser in the cloud. When the user presses buttons on the remote control, user input events are sent to your app as key presses, and your app can update the interface in real time to respond to their commands.

When you want to combine video with other elements

Your app may want to present video full screen combined with other HTML user interface elements layered on top, such as playback controls, content metadata, or augmented experiences. In this case you would stay in foreground mode so that the browser can composite the video and other elements.

When content on the screen is changing

In non-interactive use cases such as digital signage, your app may need to update the content on the screen periodically or display animations. Any time your app needs to update the contents of the web page, you'll need to do so in foreground mode.

When to use background mode

When the user is watching full screen video

When your app is ready to play video without other user interface elements, switch to background mode. Video will then stream directly to the cloud connector.

During periods of inactivity

Users may interact with your app intermittently; for example, they may walk away from the TV to make a cup of tea. You can save resources by switching to background mode after a period of inactivity. Depending upon the functionality of your app, you could:

• continue playing a video that the user has been watching
• play another video, like a screen saver on a computer
• switch to background mode without playing a video, which will simply freeze the screen

When the content on screen isn't changing

In non-interactive use cases, if your app will display the same content on screen for a period of time without needing to update it, you can switch to background mode to save resources. If you want to update the screen later after a period of time, you can set a timer or use the Alarm Manager to switch back to foreground mode.

Switching modes

The client library inlcudes a lifecycle object that can be used to switch between the two modes. You can simply call lifecycle.moveToBackground() and lifecycle.moveToForeground().

When the user starts watching a video full screen you can move to background mode, perhaps after a delay of a few seconds in case they want to continue interacting with your app.

When your app is in background mode and the user presses a button on the remote control, you'll want to switch back to foreground mode so that your app can respond to their input.

For non-interactive apps, you can move back to foreground after a pre-determined amount of time using a timer or the Alarm Manager.

If you are using the client library's Shaka Player subclass for playing video, it will also move back to foreground automatically when the video ends.

Auto background

If you would like your app to enter background mode whenever the user is not actively interacting with it, you can enable auto-background mode. This will switch to the background after a period of inactivity that you can define:

lifecycle.autoBackground = true;
lifecycle.autoBackgroundDelay = 30;

In the simplest case, you can turn the feature on when your app starts up so that it is enabled all of the time. Alternatively, you can turn auto-background on and off or modify the delay while your app is running depending upon the user interaction modes.

User inactivity

To conserve power and server resources, Senza includes an automatic sleep feature that activates when the device hasn’t been used for an extended period.

This can happen in scenarios where:

• The TV has been turned off
• The user switches to a different HDMI input
• The viewer simply dozes off during a late-night movie

However, not all inactivity means disengagement — your user might be fully immersed in a long film (think Titanic) without needing to interact with your app.

To balance these cases, Senza tracks user activity and, by default, will attempt to disconnect the session after three hours of inactivity. Before doing so, it sends a message to your app that asks, "Are you still there?" If the user responds by pressing any button, the inactivity timer resets. If they don’t, the session will disconnect after the specified countdown.

lifecycle.addEventListener("userinactivity", (e) => {
    showMessage(`Are you still there? Press any button in the next ${e.timeout} seconds to keep watching.`);
});

To test this feature in your app without waiting the full three hours, you can manually simulate an inactivity warning by dispatching a fake event.

lifecycle.dispatchEvent(new CustomEvent("userinactivity", {detail: {timeout: 30}}));

See the Lifecycle documentation for further information.

User disconnected

When a user session ends—either due to prolonged inactivity, switching away from the app, or explicitly exiting—the Senza platform triggers a userdisconnected event. This event signals that the current session is no longer active and that your app should begin cleaning up any associated resources.

Handling this event ensures that your app doesn't continue to run background processes or maintain stale state once the user is gone. It’s also a good point to reset UI elements, release memory, or disconnect from any services that are no longer needed.

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

Example Apps

• Playing Video: A step-by-step guide to the reference implementation.
• Program Guide: Demonstrates how to integrate a full featured app with just a few lines of code.