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 |
---|---|---|---|
alertId | Required | String | The id of the alert notification to close. |
Call Returns
Name | Required | Type | Description |
---|---|---|---|
returnValue | Required | Boolean | Indicates the status of operation. Possible values are:
|
errorText | Optional | String | 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 |
---|---|---|
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:
|
None | Alert Id can't be Empty | This message implies that the alertId field in the message is empty or missing. |
None | Alert Id parse error |
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:
|
errorText | Optional | String | 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 |
---|---|---|
None | Toast Id parse error | |
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:
|
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 |
---|---|---|---|
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:
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":[ |
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:
|
isSysReq | Optional | Boolean | Indicates whether the notification has come from an app or system
|
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:
|
errorText | Optional | String | 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 |
---|---|---|
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:
|
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.service.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:
Note: The default value is false. |
stale | Optional | Boolean | Possible values are:
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
|
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:
|
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 Codes Reference
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:
|
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 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 |
---|---|---|---|
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. |
onClick | Optional | String | Same as onclick. |
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. |