com.webos.service.applicationmanager

API Summary

Provides methods for managing application life cycle, application information, LaunchPoint list.

Overview of the API

(click to expand)

See Summary.


Open All


closeByAppId

Description

The closeByAppId method closes an application by appId in the system manager.

Parameters

Name

Required

Type

Description

idRequiredString

The application ID to be closed.

Call Returns

Name

Required

Type

Description

returnValueRequiredBoolean

Indicates the status of operation. Possible values are:

  • true - Indicates that the operation was successful.
  • false - Indicates that the operation failed. Check "errorText" field for details.
errorTextOptionalString

Indicates the reason for the failure of the operation. See the "Error Codes Reference" section of this method for details.

appIdOptionalString

The application ID of the closed application.

Error References

Error Code

Error Text

Error Description

Noneinvalid parameter

invalid parameter.

Noneno app description

Invalid appId is specified. That is, the 'id' parameter is empty.

NoneNot string

Invalid type value.

Noneapp is not running

Application is not running.

Example

# luna-send -n 1 -f luna://com.webos.service.applicationmanager/closeByAppId '{"id":"com.webos.app.test"}'


getAppBasePath

Description

The getAppBasePath method gets the path of the application.

Parameters

Name

Required

Type

Description

appId Required String

The application ID.

Call Returns

Name

Required

Type

Description

returnValue Required Boolean

Indicates the status of operation. Possible values are:

  • true - Indicates that the operation was successful.
  • false - Indicates that the operation failed. Check "errorText" field for details.
appId Required String

The application ID.

basePath Required String

The application path.

errorText Optional String

Indicates the reason for the failure of the operation. See the "Error Codes Reference" section of this method for details.

Error References

Error Code

Error Text

Error Description

None Not allowed. Allow only for the info of calling app itself.

Not allowed. Allow only for the information of calling application itself.

None Error parsing request:Missing required key

Missing required key.

None Error parsing request:Not string

Invalid type value.

Example

# luna-send -n 1 -a "bareapp" -f luna://com.webos.service.applicationmanager/getAppBasePath '{ "appId": "bareapp" }'


getAppInfo

Description

The getAppInfo method gets the application information.

Parameters

Name

Required

Type

Description

idRequiredString

The application ID.

propertiesOptionalString

The value to be extracted from appinfo.json file.

Call Returns

Name

Required

Type

Description

returnValueRequiredBoolean

Indicates the status of operation. Possible values are:

  • true - Indicates that the operation was successful.
  • false - Indicates that the operation failed. Check "errorText" field for details.
appIdRequiredString

The application ID.

appInfoRequiredObject: appInfo

If the getAppinfo method succeeds, the appInfo object contains information about the application.

errorTextOptionalString

Indicates the reason for the failure of the operation. See the "Error Codes Reference" section of this method for details.

Error References

Error Code

Error Text

Error Description

NoneInvalid appId specified

Invalid appId is specified. That is, the 'id' parameter is empty.

Noneparameters must contain a 'id' (string)

Parameters must contain an 'id' (string).

NoneInvalid appId specified OR Unsupported Application Type

Invalid appId is specified or an unsupported application type.

Example

Example response for a successful call:

luna-send -n 1 -f luna://com.webos.service.applicationmanager/getAppInfo '{"id":"com.webos.app.test"}'

{

"appInfo": {

...

},

"appId": "com.webos.app.test",

"returnValue": true

}


getAppLifeStatus

Description

The getAppLifeStatus method provides application's life cycle status.

Parameters

Name

Required

Type

Description

subscribe Required Boolean

Subscribe to the method. Possible values are:

  • true - Enable subscription
  • false - Disable subscription.

Default value: false

Call Returns

Name

Required

Type

Description

returnValue Required Boolean

Indicates the status of operation. Possible values are:

  • true - Indicates that the operation was successful.
  • false - Indicates that the operation failed. Check "errorText" field for details.
subscribed Required Boolean

Indicates if subscribed.

  • true - Subscribed for changes
  • false - Not subscribed
errorText Optional String

Indicates the reason for the failure of the operation. See the "Error Codes Reference" section of this method for details.

Subscription Returns

Name

Required

Type

Description

appId Optional String

The ID of application whose status has been changed.

status Optional String

The application's status. The value will be one of the followings:

  • stop
  • launching
  • relaunching
  • foreground
  • background
  • closing
type Optional String

The application type. The value will be one of the followings:

  • web
  • native

Error References

Error Code

Error Text

Error Description

None subscription is needed

"subscribe": true parameter is needed.

Example

Example response for a successful call:

AppLifeStatus can be subscribed by below command,

 # luna-send -i -f luna://com.webos.service.applicationmanager/getAppLifeStatus '{"subscribe":true}'

{

"subscribed": true,

"returnValue": true

}

 

When barenativeqt is launched, outputs are shown like below.

{
   

    "reason": "",
   

    "appId": "barenativeqt",
   

    "status": "launching",
   

    "type": "native"

}

 

When barenativeqt is closed, below outputs are shown.

{
   

    "reason": "undefined",
   

    "appId": "barenativeqt",
   

    "status": "stop",
   

    "processId": "932",
   

    "type": "native"
}


getForegroundAppInfo

Description

The getForegroundAppInfo method gets the information on the foreground application.

Parameters

Name

Required

Type

Description

extraInfo Optional Boolean
  • To enable extraInfo, set extraInfo to true. If it is set to true, the getForegroundAppInfo method will return array of foreground applications.
  • To disable extraInfo, set extraInfo to false.
  • The default value of extraInfo is false.
subscribe Optional Boolean

Subscribe to the method. Possible values are:

  • true - Enable subscription
  • false - Disable subscription.

Default value: false

Call Returns

Name

Required

Type

Description

returnValue Required Boolean

returnValue will always contain true.

appId Required String

The application ID of the application running in the foreground.

windowId Required String

The window ID of the application running in the foreground. 

processId Required String

The process ID of the application running in the foreground.

foregroundAppInfo Optional Object array: foregroundAppInfo

If the getForegroundAppInfo method succeeds, the array of the foreground application will be returned.

processId of foregroundAppInfo would be empty string if input parameter "extraInfo" is set to false. 

subscribed Optional Boolean

Indicates if subscribed.

  • true - Subscribed for changes
  • false - Not subscribed

Subscription Returns

Name

Required

Type

Description

returnValue Required Boolean

returnValue will always contain true.

appId Required String

The application ID of the application running in the foreground.

windowId Required String

The window ID of the application running in the foreground. 

processId Required String

The process ID of the application running in the foreground.

subscribed Required Boolean

subscribed will always contain true.

foregroundAppInfo Optional Object array: foregroundAppInfo

If the getForegroundAppInfo method succeeds, the array of the foreground application will be returned. 

processId of foregroundAppInfo would be empty string if input parameter "extraInfo" is set to false. 

Example

Example response for a successful call:

luna-send -n 1 -f luna://com.webos.service.applicationmanager/getForegroundAppInfo '{}'

{

"appId": "bareapp",

"returnValue": true,

"windowId": "",

"processId": ""

}

 

luna-send -i -f luna://com.webos.service.applicationmanager/getForegroundAppInfo '{"subscribe":true}'

{

"appId": "bareapp",

"subscribed": true,

"returnValue": true,

"windowId": "",

"processId": ""

}

 

luna-send -i -f luna://com.webos.service.applicationmanager/getForegroundAppInfo '{"subscribe":true, "extraInfo" : true}'


{

    "subscribed": true,

    "foregroundAppInfo": [

        {

            "windowGroup": false,

            "appId": "bareapp",

            "windowType": "_WEBOS_WINDOW_TYPE_CARD",

            "params": {

            },

            "windowId": "",

            "processId": "719"

        }

    ],

    "returnValue": true

}


launch

Description

The launch method launches an application which corresponds to the given application ID. You can use this method to open your service or app. For example, user can download a content with your service in a background. When downloading a content is completed, your service needs to launch your app again.

You can give parameter in JSON object when launching an application. This method could be called multiple times for the same application with different parameters. Application should handle these overtime requests. Generally, application is re-launched for every request.

Parameters

Name

Required

Type

Description

id Required String

The application ID to be launched.

params Optional Object: params

If params is used, it should contain information on the target application. You should specify correct parameters for each application. See the following parameter examples:

  • YouTube application: "params":{ "contentTarget" : "https://www.youtube.com/tv?v=9bZkp7q19f0"}
  • Today application: "params":{"type":"showRecordedList"}
target Optional String

A specific URL that is used in the browser application. It is automatically included under params object. The id parameter is substituted with the target parameter. If application ID is not specified, the target is open with an appropriate application.

keepAlive Optional Boolean
  • To run the application in the background, set keepAlive to true
  • To terminate the application, set keepAlive to false.
  • The default value of keepAlive is false.

Note: Only applicable to web app. Do not use keepAlive for native app launching. An web App, which is launched with this parameter, can be killed when memory status is low or critical.

Call Returns

Name

Required

Type

Description

returnValue Required Boolean

Indicates the status of operation. Possible values are:

  • true - Indicates that the operation was successful.
  • false - Indicates that the operation failed. Check the "errorCode" and "errorText" fields for details.
errorCode Optional Number

The error code for the failed operation.

errorText Optional String

Indicates the reason for the failure of the operation. See the "Error Codes Reference" section of this method for details.

Example

// One-time call

// Launching app without parameter

webOS.service.request("luna://com.webos.service.applicationmanager", {

method: "launch",

parameters: { "id": "com.yourdomain.callee" },

onComplete: function (inResponse) {

var isSucceeded = inResponse.returnValue;

if (isSucceeded){

console.log("The app is launched");

// To-Do something

} else {

console.log("Failed to launch the app");

// To-Do something

return;

}

}

});

 

// Launching app with parameters

webOS.service.request("luna://com.webos.service.applicationmanager", {

method: "launch",

parameters: {

"id": "com.yourdomain.callee",

"params": {

"customParam1": "value1",

"customParam2": "value2"

}

},

onComplete: function (inResponse) {

var isSucceeded = inResponse.returnValue;

if (isSucceeded){

console.log("The app is launched");

// To-Do something

} else {

console.log("Failed to launch the app");

// To-Do something

return;

}

}

});

 

[Luna-send command example]

luna-send -n 1 -f luna://com.webos.service.applicationmanager/launch '{"id":"bareapp"}'


listApps

Description

The listApps method lists all of the registered applications.

Parameters

Name

Required

Type

Description

subscribe Optional Boolean

Subscribe to the method. Possible values are:

  • true - Enable subscription
  • false - Disable subscription.
  • Default value: false

properties Optional String array

The value to be extracted from appinfo.json file.

Call Returns

Name

Required

Type

Description

returnValue Required Boolean

returnValue will always contain true.

apps Required Object array: appInfo

If the listApps method succeeds, the array of the applications will be returned.

subscribed Optional Boolean

Indicates if subscribed .

  • true - Subscribed.
  • false - Not subscribed

Subscription Returns

Name

Required

Type

Description

returnValue Required Boolean

Indicates the status of operation. Possible values are:

  • true - Indicates that the operation was successful.
  • false - Indicates that the operation failed.
apps Required Object array: appInfo

Either this, or app is required.

apps is returned when all apps' information has been changed by language change.

app Required Object array: appInfo

Either this, or apps is required.

app is returned the information of an app which has been installed/updated/removed.

subscribed Required Boolean

subscribed will always contain true.

change Optional String

The reason why the app’s information has been changed. The value will be one of the followings:

“added”

“updated”

“removed”

Example

Example response for a successful call:

This method returns information for all apps at first.

luna-send -i -f luna://com.webos.service.applicationmanager/listApps '{"subscribe":true}'

{

"subscribed": true,

"apps": [

{

....

}

],

"returnValue": true

}

 

When an app is update/removed/installed, the method returns only changed app's information

{

"subscribed": true,

"change": "removed",

"returnValue": true,

"app": {

...

}

}


listLaunchPoints

Description

The listLaunchPoints method gets all of the launchpoints.

Parameters

Name

Required

Type

Description

subscribe Optional Boolean

Subscribe to the method. Possible values are:

  • true - Enable subscription
  • false - Disable subscription.

​​Default value: false

Call Returns

Name

Required

Type

Description

subscribed Required Boolean
  • If it is subscribed, subscribed will contain true.
  • If it is not subscribed, subscribed will contain false.
returnValue Required Boolean

returnValue will always contain true.

launchPoints Required Object array: launchPoints

If the listLaunchPoints method succeeds, the array of the launchpoints will be returned.

launchPoints is returned when all apps' launchPoint information is changed by language change.

If only one app's launchPoint is changed by updating/removing/installing, "id", "lptype", etc. field will be returned instead of launchPoints.

Subscription Returns

Name

Required

Type

Description

subscribed Required String

subscribed will always contain true.

returnValue Optional Boolean
  • If the listLaunchPoints method succeeds, returnValue will contain true.
  • If the listLaunchPoints method fails, returnValue will contain false. The method may fail because of one of the error conditions described in the API Error Codes Reference of this service. See the API Error Codes Reference for more information.
launchPoints Optional Object array: launchPoints

If the listLaunchPoints method succeeds, the array of the launchpoints will be returned.

launchPoints is returned when all apps' launchPoint information is changed by language change.

If only one app's launchPoint is changed by updating/removing/installing, "id", "lptype", etc. field will be returned instead of launchPoints.

lptype Optional String

The launchpoint type: default, bookmark, group.

id Optional String

The application ID of the launchpoint.

removable Optional String

This indicates whether the application is removable or not.

launchPointId Optional String

The unique launchpoint ID.

title Optional String

The application title as it is shown in the Launcher and in the application window. The application title is unique, set once.

icon Optional String

The image displayed for the application.

iconColor Optional String

The background color for the application tile. The application tile is displayed in the Home, the Launcher, and the Recent screen.

largeIcon Optional String

The path of the large icon (130x130 pixels) displayed in the top left corner of the screen, when the user hovers over an application tile in the Launcher. This file path is relative to the appinfo.json file.

appDescription Optional String

A short description for the application. The appDescription cannot exceed 60 characters.

params Optional Object array: params

The params object contains information on the target application. You should specify correct parameters for each application.

userData Optional String

The additional data that may be used for analytical purposes. The userData will simply be logged when the user interacts with it in Launcher.

Example

Example response for a successful call:

luna-send -n 1 -f luna://com.webos.service.applicationManager/listLaunchPoints '{"subscribe":true}'

{

    "subscribed": true,
 

    "launchPoints": [
    

    {
    

        "id": "bareapp",

        ...
    

    },

    

    ...
   

],
   

"returnValue": true

}


registerNativeApp

Description

The registerNativeApp method registers a native application. This method is called by a native application to indicate if it is ready to receive relaunch message. Each relaunch message is communicated via the subscription reply.

Parameters

None

Call Returns

Name

Required

Type

Description

returnValue Required Boolean

Indicates the status of operation. Possible values are:

  • true - Indicates that the operation was successful.
  • false - Indicates that the operation failed.
message Required String

If a native application is successfully registered, message will contain registered.

errorText Optional String

Indicates the reason for the failure of the operation. See the "Error Codes Reference" section of this method for details.

Error References

Error Code

Error Text

Error Description

None Service name is empty. Please use your own service ID.

Caller's service name is empty.

Example

Example response for a successful call:

luna-send -n 1 -f luna://com.webos.service.applicationManager/launch '{"id":"barenativeqt"}'

{

"returnValue": true,

}

luna-send -n 1 -f -a "barenativeqt" luna://com.webos.service.applicationManager/registerNativeApp '{}'

{

"returnValue": true,

"message": "registered"

}


running

Description

The running method lists background/foreground applications and their process IDs that are running on webOS platform.

Parameters

Name

Required

Type

Description

subscribe Optional Boolean

Subscribe to the method. Possible values are:

  • true - Enable subscription
  • false - Disable subscription.

​​Default value: false

Call Returns

Name

Required

Type

Description

returnValue Required Boolean

returnValue will always contain true.

running Required Object array: running

If the running method succeeds, the array of the running applications will be returned.

subscribed Optional Boolean

Indicates if subscribed.

  • true - Subscribed.
  • false - Not subscribed

Subscription Returns

Name

Required

Type

Description

returnValue Required Boolean

returnValue will always contain true.

running Required Object array: running

If the running method succeeds, the array of the running applications will be returned.

subscribed Optional Boolean

Indicates if subscribed.

  • true - Subscribed.
  • false - Not subscribed

Example

Example response for a successful call:

luna-send -i -f luna://com.webos.service.applicationmanager/running '{"subscribe":true}'
{
   

    "subscribed": true,
   

    "running": [
        

       {
    

            "id": "bareapp",
    

            ...
    

        }
   

    ],
   

    "returnValue": true

}


Objects

appInfo

The object contains information about the application.

Name

Required

Type

Description

id Required String

The application ID, e.g., \"com.newco.app.myApp\". Every application has a unique ID, created from reverse DNS naming conventions. The launcher uses the ID to uniquely identify application and displays it with the title above. The application ID is unique, set once, and cannot be changed after publishing the application.

main Required String

The launchpoint for the application. This is a file path relative to the appinfo.json file and needs to point to an HTML file.

title Required String

The application title as it is shown in the Launcher and in the application window. The application title is unique, set once.

icon Required String

The path of the icon image displayed for the application. This file path is relative to the appinfo.json file. The default is \"icon.png\".

largeIcon Optional String

The path of the large icon (130x130 pixels) displayed in the top left corner of the screen, when the user hovers over an application tile in the Launcher. This file path is relative to the appinfo.json file.

type Required String

The application type; web or pdk.

splashBackground Optional String

The background image to be shown while application is loading, e.g., splash-background.png.

vendor Optional String

The application owner used in the launcher and deviceinfo dialogs, e.g., My Company.

transparent Optional Boolean

This indicates whether the web application's background is transparent or not.

version Optional String

The application version number, in the dot-notation format, e.g., 3.0.2500.

requiredMemory Optional Number (int8_t)

The memory consumption is increasing quickly while launching. OOM can occur before system (Memory Manager) try to acquire adequate memory for the application. 

The requiredMemory describes the maximum usage of memory, in megabytes, while an application is launching. This is not same as the maximum memory usage while the application is running.

iconColor Optional String

The background color for the application tile. The application tile is displayed in the Home, the Launcher, and the Recent screen.

appDescription Optional String

A short description for the application. The appDescription cannot exceed 60 characters.

foregroundAppInfo

The object contains sorted foreground applications in ascending order.

Name

Required

Type

Description

appId Required String

The application ID.

windowId Required String

The window ID of the application running in the foreground.

processId Required String

The process ID of the application running in the foreground.

launchPoints

The object contains the array of launchpoints.

Name

Required

Type

Description

lptype Required String

The launchpoint type: default, bookmark, group.

id Required String

The application ID of the launchpoint.

removable Required Boolean

This indicates whether the application is removable or not.

launchPointId Required String

The unique launchpoint ID.

title Required String

The application title as it is shown in the Launcher and in the application window. The application title is unique, set once.

icon Required String

The image displayed for the application.

iconColor Required String

The background color for the application tile. The application tile is displayed in the Home, the Launcher, and the Recent screen.

largeIcon Required String

The path of the large icon (130x130 pixels) displayed in the top left corner of the screen, when the user hovers over an application tile in the Launcher. This file path is relative to the appinfo.json file.

appDescription Required String

A short description for the application. The appDescription cannot exceed 60 characters.

params Optional Object: params

The params object contains information on the target application. You should specify correct parameters for each application.

userData Optional String

The additional data that may be used for analytical purposes. The userData will simply be logged when the user interacts with it in Launcher.

running

This object contains the array of the running applications.

Name

Required

Type

Description

id Required String

The application ID.

processId Required String

The process ID of the application.

webprocessid Required String

The webprocess ID of the application.

defaultWindowType Required String

The default window type of the application.

Used by WAM (WebAppMgr) to launch a window with a special window type setting.

The value will be one of the followings:

  • card
  • minimal
  • overlay
  • popup
appType Required String

The application type.


Except as noted, this content is licensed under Creative Commons Attribution 4.0 and sample code is licensed under Apache License 2.0.