com.webos.notification

API Summary

Manage system notifications.

Overview of the API

Enables apps or services to manage system notifications.

Methods

closeAlert

Description

Close the currently displayed alert notification.

Parameters

Name

Required

Type

Description

alertIdRequiredString

The id of the alert notification to close.

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

NoneMessage is not parsed

 This message implies that a JSON message parsing error occured. One of the following situations can cause the parsing error:

  • The Request object was not formatted correctly.
  • One or more of the required fields are missing.
  • One or more of the values provided were not the expected data type, for example a string was expected, however the app passed a number instead.
NoneAlert Id can't be Empty

This message implies that the alertId field in the message is empty or missing.

NoneAlert Id parse error

       This message implies that the alertId is not formatted properly.

Example

# luna-send -n 1 -f luna://com.webos.notification/closeAlert '{"alertId":"com.webos.app.test-1435191041311"}'

closeToast

Description

Remove a toast notification from the database.

Parameters

Name

Required

Type

Description

toastIdOptionalString

The id of the toast notification to remove from the database. 

Note: Either toastId or sourceId is required.

sourceIdOptionalString

The id of the app/service to remove from the database.

Note: Either toastId or sourceId is required.

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

NoneToast Id parse error

 This message implies that the toastId is not formatted properly. 

NoneBoth Toast Id and Source Id can't be Empty

This messages implies that neither toastId or sourceId field in the message is empty or missing.

NoneMessage is not parsed

This message implies that a JSON message parsing error occured. One of the following situations can cause the parsing error:

  • The Request object was not formatted correctly.
  • One or more of the required fields are missing.
  • One or more of the values provided were not the expected data type, for example a string was expected, however the app passed a number instead.

Example

Sample code with toastId provided:

# luna-send -n 1 -f -a com.webos.app.test luna://com.webos.notification/closeToast '{"toastId" : "com.webos.app.test-1433221930402"}'

Sample code with sourceId provided:

# luna-send -n 1 -f -a com.webos.app.test luna://com.webos.notification/closeToast '{"sourceId" : "com.webos.app.test"}'

createAlert

Description

Create a system alert notification.

Parameters

Name

Required

Type

Description

iconUrlOptionalString

The file path of the alert icon. The file path must be local to the device.

titleOptionalString

A brief title for the alert notification. 

messageRequiredString

A detailed message for the alert notification.

modalOptionalBoolean

Possible values are:

  • true: To display a modal alert notification
  • false: To display a non-modal alert notification

Note: The default value is false.

buttonsRequiredObject array: button

Defines the button label, and onclick action. Button specification is given in an array. An example is:

"buttons":[
        {"label":"button1", "onclick":"luna://com.webos.service.applicationmanager/launch", "params":{"id":"com.webos.app.settings"}},
        {"label":"button2", "focus":true},
        {"label":"button3"}
]

oncloseOptionalObject: onclose

Defines the close action to be performed when an alert is closed.

typeOptionalString

Defines the button type in the alert:

  • "confirm"
  • "warning"
isSysReqOptionalBoolean

Indicates whether the notification has come from an app or system

  • true : notification comes from system
  • false : notification comes from an app
onfailOptionalObject: onfail

Action to be performed on failure to create an alert.

Call Returns

Name

Required

Type

Description

alertIdOptionalString

The id of the created alert notification. This would be sourceId + "-" + Timestamp.

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

NoneUnknown Source

This message implies that the system was unable to retrieve the app's source id from the system bus message.

NonePermission Denied

This message implies that the app does not have permission to create system alerts.

NoneMessage is not parsed

This message implies that a JSON message parsing error occured. One of the following situations can cause the parsing error:

  • The Request object was not formatted correctly.
  • One ore more of the required fields are missing.
  • One or more of the values provided were not the expected data type, for example a string was expected, however the app passed a number instead.
NoneMessage can't be empty

This message implies that the field message in the request message is empty.

NoneInvalid Service Uri in the onclick

This message implies that the service URI given in the onclick object is invalid.

Example

# luna-send -n 1 -f -a com.webos.app.test luna://com.webos.notification/createAlert '{
      "message":"hello world",
      "buttons":[
        {
            "label":"launch",
            "onclick":"luna://com.webos.service.applicationmanager/launch",
            "params":
            {
                "id":"youtube.leanback.v4"
            }
        }
      ]
}'

createToast

Description

Create a toast notification.

Parameters

Name

Required

Type

Description

sourceIdRequiredString

The id of the application or service that creates the toast notification.

iconUrlOptionalString

The file path of the alert icon. The file path must be local to the device.

NOTE​: The icon must be 80 x 80 and in the PNG format.

messageRequiredString

The detailed message to be displayed as part of the toast notification. The message can be up to 60 characters long.

onclickOptionalObject: onclick

Defines the toast action.  An example is: 

{"appId":"com.webos.app.test"}

noactionOptionalBoolean

Indicates no action is required. Possible values are:

  • true: If no action is required
  • false: If action is defined.

Note: The default value is false.

staleOptionalBoolean

Possible values are:

  • true: To indicate the toast notification is old and does not need to be displayed.
  • false: If the toast notification is current and should be displayed.

Note: The default value is false.

persistentOptionalBoolean

Indicates whether the toast message should be saved in the database. If persistent is set to true, the toast message will be saved in the database.

isSysReqOptionalBoolean

Defines notification comes from app or system

  • true : notification comes from system
  • false : notification comes from app
scheduleOptionalObject: schedule

Creates a toast notification as a persistent message and defines its schedule. 

typeOptionalString

Defines the toast type.

extraOptionalObject array: image

Defines extra toast resource.

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

The id of the created toast notification. This would be sourceId + "-" + Timestamp.

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

NoneUnknown Source

This message implies that the system was unable to retrieve the app source id from the System Bus message.

NoneMessage is not parsed

This message implies that a JSON message parsing error occured. One of the following situations can cause the parsing error:

  • The Request object was not formatted correctly.
  • One ore more of the required fields are missing.
  • One or more of the values provided were not the expected data type, for example a string was expected, however the app passed a number instead.
NoneInvalid id specified

This message implies that the app is is missing from the requested message.

NoneInvalid source id specified

This message implies that the app Id given in the requested message does not match with the system bus caller Id.

NoneMessage can't be empty

This message implies that the message​ field in the requested message is empty.

Example

Example for a successful call:

# luna-send -n 1 -f -a com.webos.app.test luna://com.webos.notification/createToast '{
      "sourceId":"com.webos.app.test",
      "onclick": {"appId":"com.webos.app.test"},
      "message":"hello world",
      "noaction": false,
      "persistent":true
}'

Response:

{

"toastId": "com.webos.app.test-1435192659892",

"returnValue": true

}

 

Example for a failed call:

# luna-send -n 1 -f luna://com.webos.notification/createToast '{
      "sourceId":"com.webos.app.test",
      "onclick": {"appId":"com.webos.app.test"},
      "message":"hello world",
      "noaction": false,
      "persistent":true
}'

Response:

{

"returnValue": false,

"errorText": "Unknown Source"

}

Objects

schedule

Create a toast notification as a persistent message and define its schedule.

Name

Required

Type

Description

expireOptionalNumber (int64_t)

If this field is set, the created persistent message will be automatically removed after the specified amount of time has passed.

The value should be the number of seconds that have elapsed since 00:00:00 UTC, 1 Jan 1970.

onclose

Contains close action when alert is closed with close button or automatically

Name

Required

Type

Description

uriOptionalString

Luna API to be called when an alert window is closed.

paramsOptionalObject

Contains parameters to be passed when uri is called.

onclick

Contains action information when user a clicks the toast

Name

Required

Type

Description

appIdOptionalString

Application Id to be launched

paramsOptionalObject

Contains parameters when appId is launched.

button

Contains alert button information

Name

Required

Type

Description

labelRequiredString

The text on the button.

onclickOptionalString

Luna API to be called when a button is clicked.

onClickOptionalString

Same as onclick

paramsOptionalObject

Parameters for a service call.

buttonTypeOptionalString

The type of the button. It can be either ok or cancel.

focusOptionalBoolean

Set to true if button has default focus.

onfail

Action to be performed on failure to create alert from view side (LSM).

Name

Required

Type

Description

uriRequiredString

Luna API to be called when an alert window is closed.

paramsRequiredObject

Parameters for the above URI.

image

Defines extra toast image.

Name

Required

Type

Description

uriOptionalString

Image resource URI.

Contents