com.webos.notification

API Summary

Manage system notifications.

Overview of the API

(click to expand)

Enables apps or services to manage system notifications.


Open All


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 References

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

toastId Optional String

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

Note: Either toastId or sourceId is required.

sourceId Optional String

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

Note: Either toastId or sourceId is required.

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. 
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 Toast Id parse error

 This message implies that the toastId is not formatted properly. 

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

None Message 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-1433221

930402"}'

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

iconUrl Optional String

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

title Optional String

A brief title for the alert notification. 

message Required String

A detailed message for the alert notification.

modal Optional Boolean

Possible values are:

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

Note: The default value is false.

buttons Required Object 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.applicationManager/launch", "params":{"id":"com.webos.app.settings"}},
        {"label":"button2", "focus":true},
        {"label":"button3"}
]

onclose Optional Object: onclose

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

type Optional String

Defines the button type in the alert:

  • "confirm"
  • "warning"
isSysReq Optional Boolean

Indicates whether the notification has come from an app or system

  • true : notification comes from system
  • false : notification comes from an app
onfail Optional Object: onfail

Action to be performed on failure to create an alert.

Call Returns

Name

Required

Type

Description

alertId Optional String

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

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

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

None Permission Denied

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

None Message 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.
None Message can't be empty

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

None Invalid 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.applicationManager/launch",

"params":{"id":"youtube.leanback.v4"}

}

]

}'


createToast

Description

Create a toast notification.

Parameters

Name

Required

Type

Description

sourceId Required String

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

iconUrl Optional String

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.

message Required String

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

onclick Optional Object: onclick

Defines the toast action.  An example is: 

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

noaction Optional Boolean

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.

stale Optional Boolean

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.

persistent Optional Boolean

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.

isSysReq Optional Boolean

Defines notification comes from app or system

  • true : notification comes from system
  • false : notification comes from app
schedule Optional Object: schedule

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

type Optional String

Defines the toast type.

extra Optional Object array: image

Defines extra toast resource.

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.
toastId Optional String

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

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 Unknown Source

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

None Message 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.
None Invalid id specified

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

None Invalid source id specified

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

None Message can't be empty

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

Example

Example response 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

}'

{

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

"returnValue": true

}

 

Example response 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

}'

{

"returnValue": false,

"errorText": "Unknown Source"

}


Objects

schedule

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

Name

Required

Type

Description

expire Optional Number (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

uri Optional String

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

params Optional Object

Contains parameters to be passed when uri is called.

onclick

Contains action information when user a clicks the toast

Name

Required

Type

Description

appId Optional String

Application Id to be launched

params Optional Object

Contains parameters when appId is launched.

button

Contains alert button information

Name

Required

Type

Description

label Required String

The text on the button.

onclick Optional String

Luna API to be called when a button is clicked.

params Optional Object

Parameters for a service call.

buttonType Optional String

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

focus Optional Boolean

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

uri Required String

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

params Required Object

Parameters for the above URI.

image

Defines extra toast image.

Name

Required

Type

Description

uri Optional String

Image resource URI.


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