App Lifecycle

This article provides the following descriptions, related app lifecycle:

App Discovery

The LG Content Store (LG Store) is the only way for users to install or update apps on their  LG Smart+ TVs. The LG Content Store supports the following app discovery models:

  • Search: Users can search for apps in the LG Content store by explicitly typing in a search query string.

  • Recommendations: webOS TV recommends apps based on previous behavior, for example: past downloads.

  • Categories: Users discover apps in the LG Content Store by browsing app categories.

Installation

Users can download apps from the LG Content Store to their  LG Smart+ TV. webOS TV automatically installs the app once the download is completed.

Managing App State Changes

Web apps can be launched, suspended or terminated by user interactions or system events, and be in one of the states: Not Launched, Launched (Foreground), Suspended (Background).

App_Lifecycle_changed.png 

  • Not Launched: The app has not been launched or has been terminated. The launched app or suspended apps can be terminated by exiting from app UI, using ares-launch --close command or TERMINATE button of App Manager on Emulator. However, the web app can be launched by receiving the webOSLaunch event or visibilityChange event.

  • Launched: The app is running in the foreground and receiving events (webOSRelaunchvisibilityChange). The app can be terminated or suspended at any time.

  • Suspended: The app is in the background. The app can be suspended for a short time to do specific background tasks. The app can be launched by receiving the webOSRelaunch event or visibilityChange event. 

Launching an App

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

  • The Launcher

  • Any webOS TV app

  • A webOS TV service or a custom JavaScript service running on webOS TV

  • Using the CLI command ares-launch

  • App Manager on Emulator

Handling an App Launch

webOS TV fires the webOSLaunch event when the app is not running and is launched. The webOSLaunch event is fired within the app along with any parameters that may have been supplied by the launch process.

webOSLaunch event is fired by: 

  • Clicking on the app icon

  • Using the CLI command ares-launch

  • Calling launch() method of Application Manager on Luna Service API

  • Clicking on the LAUNCH button of App Manager on Emulator

Then, the app is launched and running in the foreground. However, the app can be also terminated by:

  • Exiting from app UI

  • Using the CLI command ares-launch --close

  • Clicking on the TERMINATE button of App Manager on Emulator   

Handling an App Re-launch

If the app is already running, webOS TV prevents it from being launched again. webOS TV fires a webOSRelaunch event. The webOSRelaunch is fired within the app along with any parameters that may have been supplied by the launch process. The app can choose to run in the foreground if needed.

A webOSRelanunch event is fired by:

  • Using the CLI command ares-launch

  • Calling launch() method of Application Manager on Luna Service API

  • Clicking on the LAUNCH button of App Manager on Emulator

Whenever the app is re-launched, webOS TV fires a webOSRelaunch event irrespective of whether the application has set the handlesRelaunch property to true or not inside its appinfo.json. In some cases, however, you want to make your app do something in the background before coming up to the foreground. In this case, the handlesRelaunch property is used. Let's have a look at this property in more detail.

If the app sets the handlesRelaunch property to:

  • false, the app is expected not to know anything about handling relaunch and launch parameters on its own. webOS displays the app in the full-screen mode in the foreground immediately after the webOSRelaunch event occurs.

  • true, it is expected to react to being re-launched, in some way and handles the webOSRelaunch event in the background before being visible to the foreground. webOS displays the app in the full-screen mode in the foreground immediately after palmSystem.activate() is called. Examples of apps using the webOSRelaunch event could be

    • A browser on receiving the webOSRelaunch event with a URL as its parameter could open the URL in a new tab. 

    • A download client on receiving the webOSRelaunch event with a filename as a parameter could add the file to its download queue.

    • An app on receiving the webOSRelaunch event could launch the UI for its own InApp Settings.

handlesRelaunch.png

Apps can add an event listener to handle the webOSLaunch or webOSRelaunch event. When a specified event occurs, the function receives a notification and handle the event. And the added event handler receives event parameter which 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);
If the handlesRelaunch property is not provided or is set to false for the suspended app, the current instance of the app is killed, and a new instance is launched with the new parameters. 

Managing App Visibility

The app, once launched, can be either visible or hidden based on user interaction, or system events. The app is suspended when it is hidden. The app can be hidden by any of the following actions:

  • Another app is launched from the current app

  • Another app is selected from the App Manager, sending the current app to the background

Also, the app can be visible by any of the following actions:

  • The app icon is clicked

  • The app is switched from the Recents

The visibilityChange event is fired when the app changes its state from visible to hidden or vice versa. webOS TV sends an onwebkitvisibilitychange event to the app. The app can have an event handler to manage the actions for its visible or hidden state.

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

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

The below sample code shows how to add an event handler for each standard web engine. For the backward compatibility, adding an event handler for the standard web engine is recommended.

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

Apps in the launched or suspended state can be terminated by:

  • Clicking on X close button on system UI
    Apps are not allowed to have a close button itself. Users can close the app by clicking the X button for app termination. See App Close in Overview of System UI.

  • Using the CLI command ares-launch --close

  • Clicking on the TERMINATE button of App Manager on Emulator

Navigation