Switching Modes

When the cloud connector is connected to the streaming service, it can move between these modes:

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

When it is not connected to the streaming service, the following modes are possible:

• Reconnecting: not connected, but trying to reconnect
• Disconnected: not connected or trying to reconnect

Flow chart

This flow chart shows all of the ways that your app can move between states:

Transitions between states can happen in several ways:

1. Functions: your app can call methods of the Lifecycle object to explicitly move from one state to another.
2. Timers: your app can move between certain states automatically after a configurable period of inactivity.
3. Events: the platform may wake up your app to deliver events when certain things happen.

Functions

You can call the following methods of the Lifecycle object to explicitly move between states.

• To switch from foreground to background, call lifecycle.moveToBackground(). You would typically do this after a few seconds of inactivity. If video is playing in the Remote Player, it will start streaming directly to the cloud connector. Otherwise, it will freeze the screen and show the last frame from the browser.
• To switch from background to foreground, call lifecycle.moveToForeground(). The web browser's user interface will be shown again, and your app can resume updating the contents of the screen. Any updates that were made in background mode will also be visible.
• To switch from background to suspended, call lifecycle.moveToSuspended(). This will cause the app to stop running, so make sure to save the app's state to session storage. See Preserving State.

The Lifecycle object emits events both before and after state changes, allowing your app to do some work or even cancel the state change. This is the case regardless of whether you are using functions or timers. See Lifecycle Events for complete details.

Timers

The Lifecycle object has several timers for moving between states automatically.

Foreground to Background

Senza will switch from foreground to background mode automatically after a period of inactivity. This helps to make sure that your app doesn't stay in foreground mode for too long when the user is not actively interacting with it.

The Auto Background feature works just like moving to background manually, except on a timer. If video is playing in the Remote Player it will stream the video from the CDN; otherwise it will stop updating the screen. There are separate timeouts for each of these two cases. You can control whether the feature is enabled and set the timeouts like this:

senza.lifecycle.configure({
  autoBackground: {
    enabled: true,
    timeout: {playing: 30, idle: 15}
  }
});

By default, the feature is enabled and both timeouts are set to ten minutes. In practice, you'll want to set shorter timeouts, such as 15-60 seconds. See the lifecycle.configure() reference for more details.

In some cases you may wish to disable the Auto Background feature, for example if your app plays video exclusively in the browser, or you have a digital signage application that updates the page without any user interaction.

Background to Suspended

Senza can also switch from background to suspended mode automatically after a period of inactivity. This helps to conserve server resources by suspending your app.

The Auto Suspend interface is configured the same way as Auto Background, like this:

senza.lifecycle.configure({
  autoSuspend: {
    enabled: true,
    timeout: {playing: 120, idle: 60}
  }
});

The feature is disabled by default, and both timeouts are set to 60 seconds. You can enable this feature to reduce your app's consumption, but keep in mind that it will take a moment for your app to start up again, and it will have to restore its state from session storage.

User Inactivity

Senza includes an automatic sleep feature that activates when the device hasn’t been used for an extended period. After three hours with no button presses, the Lifecycle object will send a message to your app so that you can ask the viewer, "Are you still there?" They can then press any button to reset the timer; otherwise after 120 seconds the device will be disconnected. See Lifecycle Events for more details.

Events

There are several events that will cause the lifecycle state to change automatically:

• When the viewer presses a button on the remote control, the document object will fire akeydown event. What happens then depends upon how your app manages lifecycle states.
  • Your app can use timers to manage the lifecycle states automatically. In this case, key presses will move to the foreground. This minimizes the amount of code you need to write to take advantage of background mode.
  • Your app can use functions to manage the lifecycle states manually. In this case, key presses will not move to the foreground. You can check the lifecycle state and move to foreground manually if needed.
• When you are playing video directly in the Remote Player and the content ends, it will fire an ended event. If the app is suspended it will move to background mode. You will want to move to foreground mode to display the user interface or load and play another video. (If you are using the Senza Shaka Player, it will move back to foreground automatically when video ends.)
• If the Remote Player encounters an error, it will fire an error event. The control flow is the same as when content ends.
• JavaScript timers work in background mode as normal, but will not fire when the app is suspended. As a replacement, Senza offers an Alarm Manager that can wake up your app and deliver an event at a specific time.
• The Message Manager offers a way to broadcast a message such as an emergency alert to a single device or group of devices. It will wake up the app if it is suspended.