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 will recommend apps based on previous behavior, for example: past downloads.
  • Categories: Users may 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 will automatically install 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: A web app has not been launched or has been terminated. A 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, a web app can be launched by receiving the webOSLaunch event or visibilityChange event.
  • Launched: A web app is running in the foreground and receiving events (webOSRelaunchvisibilityChange). App can be terminated or suspended at any time.
  • Suspended: A web app is in the background. An app can be suspended for a short time to do specific background tasks. A web app can be launched by receiving the webOSRelaunch event or visibilityChange event. 

Launching an App

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

  • The Launcher
  • Any type of 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 an 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 an 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, a web 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 a web app is re-launched, webOS TV will fire 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 more detail.

 

If the app sets the handlesRelaunch property to:

  • false, the app is expected to not know anything about handling relaunch and launch parameters on its own. webOS will display the app in the full screen mode in the foreground immediately after 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 will display 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


The apps can add an event listener to handle the webOSLaunch or webOSRelaunch event. When a specified event occurs, function will receive a notification and handle the event. And the added event handler recieves 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

An app, once launched, can be either visible or hidden based on user interaction, or system events. An app is suspended when it is hidden. An 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, an app can be visible by any of the following actions:

  • An app icon is clicked
  • An app is switched from the Recents

 

The visibilityChange event will be fired when a web app changes 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 for webkit used in webOS.

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 and webkit. 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 suspeded state can be terminated by:

  • Clicking on X close button on system UI
    An app is not allowed to have a close button itself. Users can close an app by clicking 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