App Lifecycle

Understanding the app lifecycle of a webOS TV app will help you have a rough sketch on how the app will work, before you start designing your app. This session explains the app lifecycle based on the possible states of an app and transitions between them.

States of an app

The states of an app for webOS TV can be one of the following: Not Launched, Launched (Foreground), Suspended (Background). An app’s state can and will be changed by user interactions or system events.

App life-cycle diagram
  • Not Launched: The app has not been launched or it has been terminated. In this state, if the app receives a webOSLaunch event or visibilityChange event (visible), it will be launched. A launched or suspended app can be terminated and turned to the Not Launched state by a user exiting it on the app UI, using ares-launch --close command, or selecting TERMINATE of App Manager on the Emulator.
  • Launched: The app is running in the foreground. In this state, the app will receive a webOSRelaunch or visibilityChange event (hidden). A launched app can be terminated or suspended at any time.
  • Suspended: The app is suspended in the background. The app can be suspended for a short time to do specific background tasks.
    If a suspended app receives a webOSRelaunch or visibilityChange event (visible), it will be turned back to the Launched state.

Launching an app

A web app is launched by the Application Manager service (com.webos.applicationManager). The Application Manager service can be invoked by one of the following:

  • The Launcher
  • Any webOS TV app
  • A webOS TV service or a custom JavaScript service running on webOS TV
  • CLI command ares-launch
  • App Manager on the Emulator

Handling app launch

webOS TV raises a webOSLaunch event to launch an app. A webOSLaunch event is raised by one of the following:

  • Click on the app icon
  • CLI command ares-launch
  • Calling of the launch() method of Application Manager on Luna Service API
  • Click on LAUNCH in App Manager on the Emulator

When a webOSLaunch event is raised, the app is launched and running in the foreground.

Handling app re-launch

If an app receives a webOSLaunch or visibilityChange event while it is already running, webOS TV raises a webOSRelaunch event, instead of starting the launch process from the beginning, to avoid unnecessary workloads.

A webOSRelaunch event can be raised by one of the following:

  • Using the CLI commandares-launch
  • Calling of launch() method of Application Manager on Luna Service API
  • Click on LAUNCH in App Manager on the Emulator

There is a property called handlesRelaunch in the appinfo.json file, which contains the app metada, that defines whether the app handles a webOSRelaunch event on its own or not. With this property, you can make your app to do something in the background before it is re-launched to the foreground. When app re-launch is needed, webOS TV raises a webOSRelaunch event, irrespective of the value of this handlesRelaunch property, but depending on the value of this property, your app's next move varies.

If the handlesRelaunch property of an app is set to:

  • false, the app does not handle relaunch and launch parameters on its own. It means that webOS TV displays the app in the full-screen mode in the foreground immediately after the webOSRelaunch event occurs.
  • true, the app handles the webOSRelaunch event in some way in the background before it becomes visible in the foreground. webOS TV displays the app in the full-screen mode in the foreground after palmSystem.activate() is called.
handlesRelaunch property Image that compares actions depending on the property value

Examples of apps handling the webOSRelaunch event are:

  • A browser that receives the webOSRelaunch event with a URL as its parameter and opens the URL in a new tab.
  • A download client that receives the webOSRelaunch event with a filename as a parameter and adds the file to its download queue.
  • An app that receives the webOSRelaunch event and launches the UI for its own in-app settings.

Adding event listener

An app can have an event listener to handle the webOSLaunch or webOSRelaunch event. When a specified event occurs, the event listener receives a notification and handle the event. Moreover, the added event listener receives an event parameter that holds launch parameters.

// webOSLaunch event
document.addEventListener('webOSLaunch', function(inData) {
    // Check the received parameters
    console.log(JSON.stringify(inData.detail));

    // Do something in the foreground
    ...
}, true);

// webOSRelaunch event
document.addEventListener('webOSRelaunch', function(inData) {
    // Check the received parameters
    console.log(JSON.stringify(inData.detail);

    // Do something in the background
    ...

    PalmSystem.activate();

    // Do something in the foreground
    ...
}, true);

Managing app visibility

After an app is launched, it can be either visible or hidden depending on user interactions and system events. When a launched app receives a visibilityChange event (hidden) , its state becomes suspended and its visbility becomes hidden.

An app's visibility can be changed to hidden by one of the following actions:

  • Another app is launched by the current app.
  • Another app is selected from the App Manager.

On the other hand, the visibility can be changed to visible by one of the following actions:

  • The app icon is clicked.
  • The app is selected on Recents.

A visibilityChange event is raised when the visibility of an app changes from visible to hidden or vice versa, and webOS TV sends an onwebkitvisibilitychange event to the app. The app can have an event listener to take actions when its visibility changes.

The below sample code shows how to add an event handler.

document.addEventListener(
  'visibilitychange',
  function () {
    if (document.hidden) doHiddenCleanup();
    else doShowingTasks();
  },
  true
);

The next sample code shows how to add an event handler for each standard web engine. For the backward compatibility, it is recommended you add an event listener for the standard web engine.

var hidden, visibilityChange;

if (typeof document.hidden !== 'undefined') {
  // To support the standard web browser engine
  hidden = 'hidden';
  visibilityChange = 'visibilitychange';
} else if (typeof document.webkitHidden !== 'undefined') {
  // To support the webkit engine
  hidden = 'webkitHidden';
  visibilityChange = 'webkitvisibilitychange';
}

document.addEventListener(
  visibilityChange,
  function () {
    if (document[hidden]) doHiddenCleanup();
    else doShowingTasks();
  },
  true
);

Terminating an app

An app in the launched or suspended state can be terminated by one of the following:

  • Click on X (close) button on the system UI
    Apps are not allowed to have its own close button, so users can shall click the X (close) button to terminate an app. See Closing Apps under System UI.
  • CLI command ares-launch --close
  • Click on TERMINATE of App Manager on the Emulator
No Headings