com.webos.service.applicationmanager

API Summary

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

Overview of the API

NA

    Methods

    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

    idOptionalString

    The application ID to be launched.

    launchPointIdOptionalString

    The launch point ID of the app.

    instanceIdOptionalString

    The instance ID of the app.

    paramsOptionalObject: 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"}
    keepAliveOptionalBoolean
    • 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

    returnValueRequiredBoolean

    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.
    errorCodeOptionalNumber

    The error code for the failed operation.

    errorTextOptionalString

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

    instanceIdOptionalString

    InstanceId of running application.

    launchPointIdOptionalString

    LaunchPointId of running application.

    appIdOptionalString

    ApplicationId of running application.

    displayIdOptionalNumber (uint32_t)

    DisplayId of running application.

    Example

    // One-time call

    // Launching app without parameter

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

     

    // Launching app with parameters

    # luna-send -n 1 -f luna://com.webos.service.applicationmanager/launch '{
       "id":"com.yourdomain.callee",
       "params": {
          "customParam1": "value1"
       }
    }'

    pause

    Description

    Pauses an application. The target app that gets pause call should handle itself to go background.

    Parameters

    Name

    Required

    Type

    Description

    idOptionalString

    The application ID of the app.

    launchPointIdOptionalString

    The launch point ID of the app.

    instanceIdOptionalString

    The instance ID of the app.

    paramsOptionalObject

    If params is used, it should contain information on the target application.

    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 the "errorCode" and "errorText" fields for details.
    errorCodeOptionalNumber (int8_t)

    The error code for the failed operation.

    errorTextOptionalString

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

    instanceIdOptionalString

    InstanceId of running application.

    launchPointIdOptionalString

    LaunchPointId of running application.

    appIdOptionalString

    ApplicationId of running application.

    displayIdOptionalNumber (int32_t)

    DisplayId of running application.

    Example

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

    Response:

    {
       "returnValue": true
    }

    close

    Description

    Closes an application.

    Parameters

    Name

    Required

    Type

    Description

    idOptionalString

    The application ID of the app.

    launchPointIdOptionalString

    The launch point ID of the app.

    instanceIdOptionalString

    The instance ID of the app.

    Call Returns

    Name

    Required

    Type

    Description

    returnValueRequiredBoolean
    • If the close method succeeds, returnValue will contain true.
    • If the close method fails, returnValue will contain false. The method may fail because of one of the error conditions described in the Error Codes Reference of this method. See the Error Codes Reference for more information.
    errorTextOptionalString

    The close method will return errorText only if it fails. See the Error Codes Reference of this method for more details.

    processIdOptionalString

    The process ID of the closed application.

    instanceIdOptionalString

    InstanceId of running application.

    launchPointIdOptionalString

    LaunchPointId of running application.

    appIdOptionalString

    ApplicationId of running application.

    displayIdOptionalNumber (int32_t)

    DisplayId of running application.

    Error Codes Reference

    Error Code

    Error Text

    Error Description

    NoneInvalid processId specified

    Invalid processId is specified.

    NoneNot string

    Invalid type value.

    NoneUnknown Process

    Unknown processId.

    Example

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

    closeByAppId

    Description

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

    Parameters

    Name

    Required

    Type

    Description

    idOptionalString

    The application ID to be closed.

    reasonOptionalString

    The reason why this app is closed. Subscribers who are watching app status will get the reason.

    NOTE: This parameter is only for reserved caller such as surfacemanager. Other services or apps should not use this parameter.

    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.

    instanceIdOptionalString

    InstanceId of running application.

    launchPointIdOptionalString

    LaunchPointId of running application.

    displayIdOptionalString

    DisplayId of running application.

    Error Codes Reference

    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"}'

    listApps

    Description

    The listApps method lists all of the registered applications.

    Client can get all installed application information by this API.

    Parameters

    Name

    Required

    Type

    Description

    subscribeOptionalBoolean

    Subscribe to the method. Possible values are:

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

    propertiesOptionalString array

    The value to be extracted from appinfo.json file.

    Call Returns

    Name

    Required

    Type

    Description

    returnValueRequiredBoolean

    returnValue will always contain true.

    appsRequiredObject array: appInfo

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

    subscribedOptionalBoolean

    Indicates if subscribed .

    • true - Subscribed.
    • false - Not subscribed

    Subscription 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.
    appsRequiredObject array: appInfo

    Either this, or app is required.

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

    appRequiredObject array: appInfo

    Either this, or apps is required.

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

    subscribedRequiredBoolean

    subscribed will always contain true.

    changeOptionalString

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

    “added”

    “updated”

    “removed”

    changeReasonOptionalString

    The reason why the target app is added/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": {

    ...

    }

    }

    running

    Description

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

    This API is one of key methods of applicationmanager.

    Parameters

    Name

    Required

    Type

    Description

    subscribeOptionalBoolean

    Subscribe to the method. Possible values are:

    • true - Enable subscription
    • false - Disable subscription.

    ​​Default value: false

    Call Returns

    Name

    Required

    Type

    Description

    returnValueRequiredBoolean

    returnValue will always contain true.

    subscribedOptionalBoolean

    Indicates if subscribed.

    • true - Subscribed.
    • false - Not subscribed
    runningRequiredObject array: running

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

    Subscription Returns

    Name

    Required

    Type

    Description

    returnValueRequiredBoolean

    returnValue will always contain true.

    subscribedOptionalBoolean

    Indicates if subscribed.

    • true - Subscribed.
    • false - Not subscribed
    runningRequiredObject array: running

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

    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

    }

    dev/closeByAppId

    Description

    The dev/closeByAppId method closes an application by app Id.

    Note: This method is available only in developer mode (devmode). To enable devmode, call 'com.webos.service.devmode' ('setDevMode') with value 'true'. 

    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.  See the "Error Codes Reference" section of this method for details.
    instanceIdOptionalString

    nstanceId of running application.

    launchPointIdOptionalString

    LaunchPointId of running application.

    displayIdOptionalNumber (int32_t)

    DisplayId of running application.

    Error Codes Reference

    Error Code

    Error Text

    Error Description

    Noneapp is not running

    The application that you want to close is not running.

    Noneno app description

    Passed id is invalid. That is, id parameter is empty.

    NoneNot string

    Passed value is an invalid type.

    Noneinvalid parameter

    Passed parameter is invalid.

    NoneOnly Dev app should be closed using /dev category_API

    In devmode, an application must be closed by dev/closeByAppId method.

    Example

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

    dev/listApps

    Description

    The dev/listApps method lists all of the registered applications.

    Note: 

    • This method is available only in developer mode (devmode). To enable devmode, call 'com.webos.service.devmode' ('setDevMode') with value 'true'. 
    • This method works for devmode app type.

    Parameters

    Name

    Required

    Type

    Description

    subscribeOptionalString

    Subscribe to the method. Possible values are:

    • true - Enable subscription
    • false - Disable subscription.

    ​​Default value: false

    propertiesOptionalString array

    The name of properties 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. See the API Error Codes Reference for more information.
    subscribedOptionalBoolean
    • If it is subscribed, subscribed will contain true.
    • If it is not subscribed, subscribed will contain false.
    appsRequiredObject array: appInfo

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

    Subscription 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. See the API Error Codes Reference for more information.
    appsRequiredObject array: appInfo

    Either this, or app will be returned.

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

    appRequiredObject array: appInfo

    Either this, or apps will be required.

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

    subscribedRequiredBoolean

    subscribed will always contain true.

    changeOptionalString

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

    • “added”
    • “updated”
    • “removed”
    changeReasonOptionalString

    The reason why the target app is added/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/dev/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": {

    ...

    }

    }

    dev/running

    Description

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

    Note: 

    • This method is available only in developer mode (devmode). To enable devmode, call 'com.webos.service.devmode' ('setDevMode') with value 'true'. 
    • This method works for devmode app type.

    Parameters

    Name

    Required

    Type

    Description

    subscribeOptionalBoolean

    Subscribe to the method. Possible values are:

    • true - Enable subscription
    • false - Disable subscription.

    ​​Default value: false

    Call Returns

    Name

    Required

    Type

    Description

    returnValueRequiredBoolean

    returnValue will always contain true.

    subscribedOptionalBoolean
    • If it is subscribed, subscribed will contain true.
    • If it is not subscribed, subscribed will contain false.
    runningRequiredObject array: running

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

    Subscription Returns

    Name

    Required

    Type

    Description

    returnValueRequiredBoolean

    returnValue will always contain true.

    subscribedOptionalBoolean
    • If it is subscribed, subscribed will contain true.
    • If it is not subscribed, subscribed will contain false.
    runningRequiredObject array: running

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

    Example

    Example response for a successful call:

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

    {

    "subscribed": true,

    "running": [

    {

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

    "webprocessid": "",

    "defaultWindowType": "card",

    "appType": "native",

    "processid": "1176"

    }

    ],

    "returnValue": true

    }

    getForegroundAppInfo

    Description

    Gets the information on the foreground application.

    The information comes from LSM. Please use extraInfo parameter to get raw responsePayload from LSM.

    Parameters

    Name

    Required

    Type

    Description

    extraInfoOptionalBoolean

    If enabled, the method returns an array of foreground applications.

    • true - To enable.
    • false - To disable.

    Default value: false.

    subscribeOptionalBoolean

    Subscribe to the method. Possible values are:

    • true - Enable subscription
    • false - Disable subscription.

    Default value: false

    Call Returns

    Name

    Required

    Type

    Description

    returnValueRequiredBoolean

    returnValue will always contain true.

    subscribedOptionalBoolean

    Indicates if subscribed.

    • true - Subscribed for changes
    • false - Not subscribed
    appIdRequiredString

    The application ID of the application running in the foreground.

    launchPointIdOptionalString

    The launch point ID of the app.

    instanceIdOptionalString

    The instance ID of the app.

    displayIdOptionalNumber

    The display ID of the app.

    windowIdRequiredString

    The window ID of the application running in the foreground. 

    processIdRequiredString

    The process ID of the application running in the foreground.

    foregroundAppInfoOptionalObject array: foregroundAppInfo

    An array of the foreground application.

    Subscription Returns

    Name

    Required

    Type

    Description

    returnValueRequiredBoolean

    returnValue will always contain true.

    subscribedRequiredBoolean

    subscribed will always contain true.

    appIdRequiredString

    The application ID of the application running in the foreground.

    launchPointIdOptionalString

    The launch point ID of the app. 

    instanceIdOptionalString

    The instance ID of the app. 

    displayIdOptionalNumber

    The display ID of the app. 

    windowIdRequiredString

    The window ID of the application running in the foreground. 

    processIdRequiredString

    The process ID of the application running in the foreground.

    foregroundAppInfoOptionalObject array: foregroundAppInfo

    An array of the foreground application.

    Example

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

    Response:

    {
       "appId":"bareapp",
       "returnValue":true,
       "windowId":"",
       "processId":""
    }

     

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

    Response:

    {
       "appId":"bareapp",
       "subscribed":true,
       "returnValue":true,
       "windowId":"",
       "processId":""
    }

     

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

    Response:

    {
       "subscribed":true,
       "foregroundAppInfo":[
          {

             "instanceId": "c057ba89-6de6-4807-a5fe-81e8af4aac700",
             "windowGroup":false,
             "appId":"bareapp",
             "windowType":"_WEBOS_WINDOW_TYPE_CARD",
             "params":{

             },
             "windowId":"",
             "processId":"719"
          }
       ],
       "returnValue":true
    }

    getAppLifeStatus

    Description

    The getAppLifeStatus method provides application's life cycle status.

    This API is useful to do something based on application's life cycle status.

    Parameters

    Name

    Required

    Type

    Description

    subscribeRequiredBoolean

    Subscribe to the method. Possible values are:

    • true - Enable subscription
    • false - Disable subscription.

    Default value: false

    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.
    subscribedRequiredBoolean

    Indicates if subscribed.

    • true - Subscribed for changes
    • false - Not subscribed
    errorTextOptionalString

    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

    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.
    subscribedRequiredString

    Indicates if subscribed.

    • true - Subscribed for changes
    • false - Not subscribed
    appIdOptionalString

    The ID of application whose status has been changed.

    launchPointIdOptionalString

    The launch point ID of the app.

    instanceIdOptionalString

    The instance ID of the app. 

    statusOptionalString

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

    • stop
    • launching
    • relaunching
    • foreground
    • background
    • closing
    typeOptionalString

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

    • web
    • native
    processIdOptionalString

    Process id of the app.

    displayIdOptionalNumber

    The display ID of the app. 

    reasonOptionalString

    In LAUNCHING/RELAUNCHING status, the reason means how the target app is launched.

    In CLOSING/STOP status, the reason means why the target app is closed.

    windowTypeOptionalString

    Window type of the app. This reason is replied only in FOREGROUND status.

    windowGroupOptionalBoolean

    Indicate that the app has window group or not. This reason is replied only in FOREGROUND status.

    windowGroupOwnerOptionalBoolean

    Indicate that the app is window group owner or not. This reason is replied only in FOREGROUND status.

    windowGroupOwnerIdOptionalString

    Indicate who is window group owner of the app. This reason is replied only in FOREGROUND status.

    backgroundStatusOptionalString

    Indicate whether the app is preloaded or not. This reason is replied only in BACKGROUND status.

    Error Codes Reference

    Error Code

    Error Text

    Error Description

    Nonesubscription 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"
    }

    getAppLifeEvents

    Description

    The getAppLifeEvents method provides application's event status in its life cycle.

    Parameters

    Name

    Required

    Type

    Description

    subscribeOptionalBoolean

    Subscribe for notifications. Possible values are:

    • true - Get notifications
    • false - Notifications are not required

    Default value: false

    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 the "errorCode" and "errorText" fields for details.
    subscribedRequiredBoolean

    Indicates if subscribed to get notified.

    • true - Get notifications
    • false - Notifications are not required​
    errorTextOptionalString

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

    errorCodeOptionalNumber (int8_t)

    The error code for the failed operation.

    Subscription 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 the "errorCode" and "errorText" fields for details.
    subscribedRequiredBoolean

    Indicates if subscribed to get notified.

    • true - Get notifications
    • false - Notifications are not required​
    appIdRequiredString

    The ID of application whose event has been changed.

    launchPointIdOptionalString

    The launch point ID of the app.

    instanceIdOptionalString

    The instance ID of the app.

    displayIdOptionalNumber

    The display ID of the app.

    eventRequiredString

    The application's status. The valid values are:

    • splash
    • preload
    • launch
    • foreground
    • background
    • pause
    • close
    • stop
    titleOptionalString

    The application title as it is shown in the Launcher and in the application window.

    Note: It is included only when event type is "splash".

    showSplashOptionalBoolean

    Indicates if splash image is shown. This value is set during app scanning. Possible values are:

    • true: Splash image is shown. 
    • false: Splash image is not shown. 

    Note: It is included only when event type is "splash".

    showSpinnerOptionalBoolean

    Indicates of spinner is shown. This value is set during app scanning. Possible values are:

    • true: Spinner is shown. 
    • false: Spinner is not shown. 

    Note: It is included only when event type is "splash".

    splashBackgroundOptionalString

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

    Note: It is included only when event type is "splash".

    preloadOptionalBoolean

    Current preload status. The value will be one of the following:

    • full
    • semi-full
    • partial
    • minimal

    Note: It is included only when event type is "preload".

    reasonOptionalString

    The reason how the target app is launched and why the target app is closed.

    Note: It is included only when event type is "launch/close/stop".

    windowTypeOptionalString

    Window type of the app.

    Note: It is included only when event type is "foreground".

    windowGroupOptionalString

    Indicate that the app has window group or not.

    Note: It is included only when event type is "foreground".

    windowGroupOwnerOptionalString

    Indicate that the app is window group owner or not.

    Note: It is included only when event type is "foreground".

    windowGroupOwnerIdOptionalString

    Indicate who is window group owner of the app.

    Note: It is included only when event type is "foreground".

    statusOptionalString

    Current background status. The value will be one of the followings:

    • preload
    • normal

    Note: It is included only when event type is "background".

    Example

    Example response for a successful call:

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

    {

    "subscribed": true,

    "returnValue": true

    }

     

    When livetv app is launched, outputs related to splash are shown like below.

    {

    "event": "splash",

    "title": "Live TV",

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

    "showSpinner": true,

    "showSplash": true,

    "returnValue": true,

    "splashBackground": "file:///usr/palm/applications/com.webos.app.livetv/assets/livetv.png"

    }

     

    Example response for a failed call:

    For error case, if subscribe filed is empty, below error text is shown.

    # luna-send -i -f luna://com.webos.service.applicationmanager/getAppLifeEvents '{}'
    {

    "subscribed": false,

    "errorCode": 1,

    "returnValue": false,

    "errorText": "subscription is required"

    }

    getAppBasePath

    Description

    The getAppBasePath method gets the path of the application.

    This API is useful to get base directory path of installed application.

    Parameters

    Name

    Required

    Type

    Description

    appIdRequiredString

    The application ID.

    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.

    basePathRequiredString

    The application path.

    errorTextOptionalString

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

    Error Codes Reference

    Error Code

    Error Text

    Error Description

    NoneNot allowed. Allow only for the info of calling app itself.

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

    NoneError parsing request:Missing required key

    Missing required key.

    NoneError 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.

    The information is generated from appinfo.json file.

    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 Codes Reference

    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

    }

    getAppStatus

    Description

    The getAppStatus method gets the application status and information.

    Parameters

    Name

    Required

    Type

    Description

    appIdRequiredString

    The application ID.

    appInfoOptionalObject: appInfo

    Information of the app.

    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 the "errorCode" and "errorText" fields for details.
    appIdRequiredString

    The target application ID. 

    eventRequiredString

    Indicates event according to the target app status.

    statusRequiredString

    Current app status. 

    existRequiredBoolean

    Indicates if target app is present on the device. Possible values are:

    • true: Target app exists on the device. 
    • false: Target app does not exist on the device. 
    launchableRequiredBoolean

    Indicates whether the target app could be launched or not. Possible values are:

    • true: Target app could be launched. 
    • false: Target app could not be launched. 
    appInfoOptionalObject: appInfo

    If the getAppStatus method succeeds and the parameter "appInfo" is true, the appInfo object contains information about the application.

    errorCodeOptionalNumber (int8_t)

    The error code for the failed operation.

    errorTextOptionalString

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

    Subscription 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 the "errorCode" and "errorText" fields for details.
    appIdRequiredString

    The target application ID. 

    eventRequiredString

    Indicates event according to the target app status.

    statusRequiredString

    Current app status. 

    existRequiredBoolean

    Indicates if target app is present on the device. Possible values are:

    • true: Target app exists on the device. 
    • false: Target app does not exist on the device.
    launchableRequiredBoolean

    Indicates whether the target app could be launched or not. Possible values are:

    • true: Target app could be launched. 
    • false: Target app could not be launched. 
    appInfoOptionalObject array: appInfo

    If the getAppStatus method succeeds and the parameter "appInfo" is true, the appInfo object contains information about the application.

    Example

    Example response for a successful call without appInfo:

    # luna-send -n 1 -f luna://com.webos.service.applicationmanager/getAppStatus '{"appId":"com.webos.app.browser"}'

    {

    "event": "nothing",

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

    "status": "launchable",

    "exist": true,

    "launchable": true,

    "returnValue": true

    }

     

    Example response for a successful call without appInfo:

    # luna-send -n 1 -f luna://com.webos.service.applicationmanager/getAppStatus '{"appId":"com.webos.app.browser", "appInfo":true}'

    {

    "event": "nothing",

    "appInfo": {

    ....

    "id": "com.webos.app.browser",

    "title": "Web Browser",

    ....

    },

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

    "status": "launchable",

    "exist": true,

    "launchable": true,

    "returnValue": true

    }

     

    Example response for a failed call:

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

    {

    "errorCode": 2,

    "returnValue": false,

    "errorText": "invalid parameters"

    }

    listLaunchPoints

    Description

    The listLaunchPoints method gets all of the launchpoints.

    LaunchPoint is virtual instance of application. The webOS provides shortcut based on launchPoint.

    Parameters

    Name

    Required

    Type

    Description

    subscribeOptionalBoolean

    Subscribe to the method. Possible values are:

    • true - Enable subscription
    • false - Disable subscription.

    ​​Default value: false

    Call Returns

    Name

    Required

    Type

    Description

    returnValueRequiredBoolean

    returnValue will always contain true.

    subscribedRequiredBoolean
    • If it is subscribed, subscribed will contain true.
    • If it is not subscribed, subscribed will contain false.
    launchPointsRequiredObject array: launchPoints

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

    Subscription Returns

    Name

    Required

    Type

    Description

    returnValueRequiredBoolean
    • 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.
    subscribedRequiredString

    subscribed will always contain true.

    launchPointOptionalObject

    launchPoint is returned if only one app's launchPoint is changed by updating/removing/installing.

    faviconOptionalString

    Favorite icon image displayed for the website.

    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

    }

    addLaunchPoint

    Description

    Adds a dynamic launchpoint. According to the information on launchpoint, application is displayed in the Launcher.

    If a parameter is not defined, SAM set the LP's parameter value same as appInfo's value.

    Parameters

    Name

    Required

    Type

    Description

    idRequiredString

    The launchpoint ID to be added.

    titleOptionalString

    The launchpoint title.

    iconOptionalString

    The path of the icon image displayed for the launchpoint.

    bgImageOptionalString

    The path of the background image displayed to the user when the user hovers over the launchpoint.

    bgColorOptionalString

    The background color for the launchpoint. It will be displayed when the bgImage is not provided or unable to display. A color can be specified as a hex value or as a HTML color name. 

    Format: color hex code (ex. #000000(black)) 

    http://www.color-hex.com/

    imageForRecentsOptionalString

    The path of the image displayed in the Recents tile.

    iconColorOptionalString

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

    Format: color hex code (ex. #000000(black)) 

    http://www.color-hex.com/

    largeIconOptionalString

    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.

    appDescriptionOptionalString

    A brief description for the launchpoint. The appDescription cannot exceed 60 characters.

    paramsOptionalObject: params

    If params is used, it should contain information on the launchpoint.

    bgImagesOptionalString array

    The paths of the background images displayed to the user when the user hovers over the launchpoint.

    tileSizeOptionalString

    The tile size on UI: normal or large. 
    The default value is normal. The large tile hints that UI should make this tile larger than normal (2x).
    Usually, large size may be used for promotional application. 

    unmovableOptionalBoolean
    • To enable unmovable, set unmovable to true. If it is set to true, the launchpoint position can not be moved by the user.
    • To disable unmovable, set unmovable to false.
    • The default value of unmovable is false.
    userDataOptionalString

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

    supportI18nTitleOptionalBoolean
    • If "supportI18nTitle" is set to true, i18n will be supported for title when any information of this launch point is changed.
    • If "supportI18nTitle" is set to false, i18n will be supported for title when any information of this launch point is changed.
    • The default value of supportI18nTitle is true
    policyCategoryOptionalString

    Indicate a category(group) of the launch point. The value should be the one of below mapping table.

    *$RESERVED_VALUE is for special callers to be controlled by LPM.

    defaultAny9
    *$RESERVED_VALUE$RESERVED_LP$RESERVED_POSITION

    Value

    Launch Point Type

    position

    faviconOptionalString

    The paths of favorite icon for the launchpoint.

    relaunchOptionalBoolean

    If it is set to true, the app will be fresh-launched(re-randering) whenever user clicks the launchpoint.

    Note: This parameter is deprecated in IvyLeague.

    Call Returns

    Name

    Required

    Type

    Description

    returnValueRequiredBoolean
    • If the addLaunchPoint method succeeds, returnValue will contain true.
    • If the addLaunchPoint method fails, returnValue will contain false. The method may fail because of one of the error conditions described in the Error Codes Reference of this method. See the Error Codes Reference for more information.
    launchPointIdRequiredString

    The launchpoint ID to be added.

    errorTextOptionalString

    The addLaunchPoint method will return errorText only if it fails. See the Error Codes Reference of this method for more details.

    Error Codes Reference

    Error Code

    Error Text

    Error Description

    Noneinvalid json request

    Invalid JSON request.

    Example

    Example response for a successful call:

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

    {

    "launchPointId": "178884",

    "returnValue": true

    }

     

    Example response for a failed call:

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

    {

    "returnValue": false,

    "errorText": "invalid json request"

    }

    updateLaunchPoint

    Description

    The updateLaunchPoint method updates a dynamic launchpoint.

    If a user changes the HDMI application icon to another icon like a game icon using Input Manager on a TV, the HDMI application icon is dynamically changed to the new icon on the launcher.

    Parameters

    Name

    Required

    Type

    Description

    launchPointIdRequiredString

    The launchpoint ID to be updated.

    Both launchPointId and one or more parameters (title, icon, etc) need to be passed from service user.

    titleOptionalString

    The launchpoint title.

    iconOptionalString

    The path of the icon image displayed for the launchpoint.

    bgImageOptionalString

    The path of the background image displayed to the user when the user hovers over the launchpoint.

    Format: color hex code (ex. #000000(black)) 

    http://www.color-hex.com/

    bgColorOptionalString

    The background color for the launchpoint. It will be displayed when the bgImage is not provided or unable to display. A color can be specified as a hex value or as a HTML color name. 

    imageForRecentsOptionalString

    The path of the image displayed in the Recents tile.

    iconColorOptionalString

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

    Format: color hex code (ex. #000000(black)) 

    http://www.color-hex.com/

    largeIconOptionalString

    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.

    appDescriptionOptionalString

    A brief description for the launchpoint. The appDescription cannot exceed 60 characters.

    paramsOptionalObject: params

    If params is used, it should contain information on the launchpoint which will be passed to the application.

    bgImagesOptionalString array

    The paths of the background images displayed to the user when the user hovers over the launchpoint.

    tileSizeOptionalString

    The tile size on UI: normal or large. 
    The default value is normal. The large tile hints that UI should make this tile larger than normal (2x).
    Usually, large size may be used for promotional application. 

    unmovableOptionalBoolean
    • To enable unmovable, set unmovable to true. If it is set totrue, the launchpoint position can not be moved by the user.
    • To disable unmovable, set unmovable to false.
    • The default value of unmovable is false.
    userDataOptionalString

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

    iconsOptionalObject array

    The list of icon images. The icons will be shown in launch point alternately.

    faviconOptionalString

    Favorite icon image displayed for the website.

    policyCategoryOptionalString

    Indicate a category(group) of the launch point. The value should be the one of below mapping table.

    *$RESERVED_VALUE is for special callers to be controlled by LPM.

    ValueLaunch Point Typeposition
    defaultAny9
    *$RESERVED_VALUE$RESERVED_LP$RESERVED_POSITION
    relaunchOptionalBoolean

    This indicates whether the target app is re-launched whenever the launch point is clicked. (Not fast-switching)

    Note: This parameter is deprecated in IvyLeague.

    Call Returns

    Name

    Required

    Type

    Description

    returnValueRequiredBoolean
    • If the updateLaunchPoint method succeeds, returnValue will contain true.
    • If the updateLaunchPoint method fails, returnValue will contain false. The method may fail because of one of the error conditions described in the Error Codes Reference of this method. See the Error Codes Reference for more information.
    errorTextOptionalString

    The updateLaunchPoint method will return errorText only if it fails. See the Error Codes Reference of this method for more details.

    Error Codes Reference

    Error Code

    Error Text

    Error Description

    Noneinvalid json request

    Invalid JSON request.

    Nonecannot find launch point info

    Cannot find launch point information for launchPointId.

    Example

    Example response for a successful call:

    # luna-send -n 1 -f luna://com.webos.service.applicationmanager/updateLaunchPoint '{"launchPointId":"178884", "title":"Test"}'

    {

    "returnValue": true

    }

     

    Example response for a failed call:

    # luna-send -n 1 -f luna://com.webos.service.applicationmanager/updateLaunchPoint '{"launchPointId":"178884"}'

    {

    "returnValue": false,

    "errorText": "Insufficient parameters"

    }

    removeLaunchPoint

    Description

    The removeLaunchPoint method removes a dynamic launchpoint.

    It can cause application uninstall.

    Parameters

    Name

    Required

    Type

    Description

    launchPointIdRequiredString

    The launchpoint ID to be removed.

    Call Returns

    Name

    Required

    Type

    Description

    returnValueRequiredBoolean
    • If the removeLaunchPoint method succeeds, returnValue will contain true.
    • If the removeLaunchPoint method fails, returnValue will contain false. The method may fail because of one of the error conditions described in the Error Codes Reference of this method. See the Error Codes Reference for more information.
    errorTextOptionalString

    The removeLaunchPoint method will return errorText only if it fails. See the Error Codes Reference of this method for more details.

    Error Codes Reference

    Error Code

    Error Text

    Error Description

    Noneinvalid json request

    Invalid JSON request.

    Nonecannot find launch point info

    Cannot find launch point information for launchPointId.

    Example

    Example response for a successful call:

    # luna-send -n 1 -f luna://com.webos.service.applicationmanager/removeLaunchPoint '{"launchPointId":"178884"}'

    {

    "returnValue": true

    }

     

    Example response for a failed call:

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

    {

    "returnValue": false,

    "errorText": "invalid json request"

    }

    registerApp

    Description

    The registerApp method registers a native application. This method should be called by launched native application to indicate if it is ready to receive several events. Each event is communicated via the ls message connection and the reply will be delivered only to the app that is performing the action.

    Parameters

    None

    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. 
    eventRequiredString

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

    Subscription Returns

    Name

    Required

    Type

    Description

    eventRequiredString

    It indicates one of events the app should handle.

    returnValueRequiredBoolean

    Indicates the status of operation. Possible values are:

    • true - Indicates that the operation was successful.
    • false - Indicates that the operation failed. 
    parametersOptionalObject: params

    Information to be delivered to the registered app.

    reasonOptionalString

    The reason why this app is launch/closed.

    appIdOptionalString

    Id of the registered app. 

    Example

    # luna-send -i -f luna://com.webos.service.applicationmanager/registerApp '{}'

    {

    "event":"registered",

    "returnValue":true

    }

     

    //event is returned when an app status is changed.

    {

    "event":"pause",

    "reason":"keepAlive",

    "parameters":{},

    "returnValue":true

    }

    lockApp

    Description

    The lockApp method locks an application. Once it is locked, the application cannot be launched.

    NOTE: This method is only called by appinstalld. Do not use this method in your application.

    Parameters

    Name

    Required

    Type

    Description

    idRequiredString

    The application ID to be locked.

    lockRequiredBoolean
    • To lock the application, set lock to true. If it is set to true, the application won't be launched.
    • To unlock the application, set lock to false.

    Call Returns

    Name

    Required

    Type

    Description

    returnValueRequiredBoolean
    • If the lockApp method succeeds, returnValue will contain true.
    • If the lockApp method fails, returnValue will contain false. The method may fail because of one of the error conditions described in the Error Codes Reference of this method. See the Error Codes Reference for more information.
    lockedRequiredBoolean
    • If the application is locked, locked will contain true.
    • If the application is unlocked, locked will contain false.
    idRequiredString

    The application ID which is locked or unlocked.

    errorTextOptionalString

    The lockApp method will return errorText only if it fails. See the Error Codes Reference of this method for more details.

    Error Codes Reference

    Error Code

    Error Text

    Error Description

    NoneMissing required key

    Missing required key.

    NoneParameters 'id'(string) or 'lock'(bool) is missing

    Parameters 'id'(string) or 'lock'(bool) is missing.

    Nonewas not found OR Unsupported Application Type

    Was not found or an unsupported application type.

    Objects

    appInfo

    The object contains information about the application.

    Name

    Required

    Type

    Description

    idRequiredString

    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.

    mainRequiredString

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

    titleRequiredString

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

    iconRequiredString

    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\".

    largeIconOptionalString

    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.

    typeRequiredString

    The application type; web or pdk.

    splashBackgroundOptionalString

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

    vendorOptionalString

    The application owner used in the launcher and deviceinfo dialogs.

    transparentOptionalBoolean

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

    versionOptionalString

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

    handlesRelaunchOptionalBoolean

    This indicates whether the application is relaunched or not when a user executes application that is already running.

    requiredMemoryOptionalNumber (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.

    iconColorOptionalString

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

    appDescriptionOptionalString

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

    launchPoints

    The object contains the array of launchpoints.

    Name

    Required

    Type

    Description

    lptypeRequiredString

    The launchpoint type: default, bookmark, group.

    idRequiredString

    The application ID of the launchpoint.

    launchPointIdRequiredString

    The unique launchpoint ID.

    removableRequiredBoolean

    This indicates whether the application is removable or not.

    titleRequiredString

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

    iconRequiredString

    The image displayed for the application.

    iconColorRequiredString

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

    largeIconRequiredString

    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.

    appDescriptionRequiredString

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

    paramsOptionalObject: params

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

    userDataOptionalString

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

    params

    The object contains the parameters for the target application. You should specify correct parameters for each application. As each application has different parameters, the parameters of params cannot be defined.

    foregroundAppInfo

    The object contains sorted foreground applications in ascending order.

    Name

    Required

    Type

    Description

    instanceIdOptionalString

    InstanceId of running application.

    appIdRequiredString

    The application ID.

    windowIdRequiredString

    The window ID of the application running in the foreground.

    processIdRequiredString

    The process ID of the application running in the foreground.

    displayIdOptionalNumber

    The display ID of application.

    running

    This object contains the array of the running applications.

    Name

    Required

    Type

    Description

    idRequiredString

    The application ID.

    launchPointIdOptionalString

    The launch point ID of the app. 

    instanceIdOptionalString

    The instance ID of the app.

    displayIdOptionalNumber

    The display ID of the app.

    processIdRequiredString

    The process ID of the application.

    webprocessidRequiredString

    The webprocess ID of the application.

    defaultWindowTypeRequiredString

    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
    appTypeRequiredString

    The application type.

    Contents