Lifecycle Events

The Lifecycle object object emits a number of events that your app can respond to. See the Lifecycle class documentation for complete details.

State changes

The lifecycle has three states:

• Foreground: the application is running and can update the screen
• Background: the application is running but cannot update the screen
• Suspended: the application is not running

The lifecycle object emits events both before and after changing between these states. This is the case regardless of whether the state is changing due to a function call or a timer. See Switching Modes for details.

Before state change

Before the state changes, the lifecycle object emits a beforestatechange event. The listener can be asynchronous, and Senza will wait up to ten seconds for the function to return before continuing. You can cancel the state change by calling preventDefault().

Here's an example listener that calls an async function to check if it should cancel the state change:

senza.lifecycle.addEventListener("beforestatechange", async (event) => {
  console.log("Lifecycle state will be:", event.state);
  if (event.state === senza.lifecycle.UiState.BACKGROUND) {
    let keepAlive = await shouldKeepAlive();
    if (keepAlive) {
      event.preventDefault();
    }
  }
});

On state change

After the state changes, the lifecycle object emits an onstatechange event:

senza.lifecycle.addEventListener("onstatechange", (event) => {
  console.log("Lifecycle state is now:", event.state);
});

This event is not sent when the app has moved to suspended mode, because the app is no longer running.

See the Stopwatch tutorial for an example that shows how to listen for lifecycle state changes.

User inactivity

To conserve server resources, Senza includes an automatic sleep feature that activates when the device hasn’t been used for an extended period. The viewer may have stopped watching, but they may also just be watching a long movie.

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.

senza.lifecycle.addEventListener("userinactivity", (event) => {
  showMessage(`Press any button in the next ${event.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.

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

User disconnected

When a user session ends—either due to user inactivity, switching to a different app, calling the disconnect function, or the device being powered off—the Senza platform triggers a userdisconnected event. This event signals that the current session is no longer active.

Because of the cloud-based architecture of the Senza platform, it offers a unique feature: the userdisconnected event is guaranteed to be delivered to your app, even if the user pulls the power cable from the device. This gives your app an opportunity to do anything it needs at the end of the session, such as sending an event summary to your analytics engine. The listener can be asynchronous, and Senza will wait up to ten seconds for the function to run.

senza.lifecycle.addEventListener("userdisconnected", async () => {
  console.log("User disconnected.");
	await sendAnalyticsSummary();
});

❗️

Note

This feature is disabled by default. Contact your Synamedia representative to enable this feature for your tenant if needed.