Notifications
You can provide notifications to the user about application events.
This feature is supported in mobile and wearable applications only.
The main features of the Notification API include:
-
Creating simple notifications
You can create a simple notification that provides the user information about their events.
-
Creating progress notifications
You can create a progress notification that informs the user about the progress of an activity.
-
Managing notifications
-
Managing notification templates
You can create a template that can be reused in multiple notifications.
To display a notification, you need to create a Notification
object (in mobile and wearable applications), or its subtype.
Note
TheStatusNotification
subtype (in mobile and wearable applications) is deprecated since Tizen 4.0. To display notifications in the status bar, use theUserNotification
subtype (in mobile and wearable applications).
Prerequisites
To use the Notification API (in mobile and wearable applications), the application has to request permission by adding the following privilege to the config.xml
file:
<tizen:privilege name="http://tizen.org/privilege/notification"/>
Creating Simple Notifications
Learning how to create notifications allows you to design interactive applications that provide the user information about their events:
-
Define the notification properties of the
UserNotificationInit
interface (in mobile and wearable applications):/* Application control */ var appControl = new tizen.ApplicationControl('http://tizen.org/appcontrol/operation/create_content', null, 'image/jpg', null, null); var notificationGroupDict = { /* Notification content */ content: 'This is a simple notification.', images: { /* Path to the notification icon */ iconPath: 'images/image1.jpg' }, actions: { /* Path to the sound file to be played when the notification is displayed */ soundPath: 'music/Over the horizon.mp3', /* Device vibrates when the notification is displayed */ vibration: true, /* Application control to be launched when the user selects the notification */ appControl: appControl } };
The path in the
iconPath
andsoundPath
parameters means a relative file location defined in the Filesystem API (in mobile and wearable applications). The path is not an absolute file location, but instead uses a virtual root location (such asimages
inimages/image1.jpg
). -
To be able to display the notification, create a
UserNotification
object (in mobile and wearable applications) with the notification type, title, and the additional notification properties defined in the previous step.var notification = new tizen.UserNotification('SIMPLE', 'Simple notification', notificationGroupDict);
-
To post the notification, use the
post()
method of theNotificationManager
interface (in mobile and wearable applications):tizen.notification.post(notification);
Creating Progress Notifications
Learning how to create progress notifications allows you to design interactive applications that inform the user about the progress of an activity:
-
Define the notification properties of the
UserNotificationInit
interface (in mobile and wearable applications):/* Application control */ var appControl = new tizen.ApplicationControl('http://tizen.org/appcontrol/operation/create_content', null, 'image/jpg', null, null); var notificationGroupDict = { content: 'This is a progress notification.', images: { iconPath: 'images/image1.jpg' }, actions: { vibration: false, appControl: appControl }, textContents: { progressType: 'PERCENTAGE', progressValue: 0 }, };
The path in the
iconPath
parameter means a file location defined in the Filesystem API (in mobile and wearable applications). The path is not an absolute file location, but instead uses a virtual root location (such asimages
inimages/image1.jpg
). -
To be able to display the notification, create a
UserNotification
object (in mobile and wearable applications) with the notification type, title, and the additional notification properties defined in the previous step:var notification = new tizen.UserNotification('PROGRESS', 'Progress notification', notificationGroupDict);
-
Define a function which uses the
update()
method of theNotificationManager
interface (in mobile and wearable applications) to update the posted notification every second:function updateProgressNotification(progress) { if (progress <= 100) { notification.textContents.progressValue = progress; tizen.notification.update(notification); setTimeout(function() { updateProgressNotification(progress + 10); }, 1000); } else { tizen.notification.remove(notification.id); } }
-
To post the notification, use the
post()
method of theNotificationManager
interface. If the progress value is set, the progress bar is displayed in the notification. The progress value can change the amount of progress as it moves forward or backward.The application must keep the progress value for its job, because the saved value in the notification panel can be different (rounded) from the exact progress value.
tizen.notification.post(notification); updateProgressNotification(0);
Managing Notifications
Learning how to manage notifications allows you to design interactive applications that provide the user information about their events:
-
To retrieve notifications:
-
To retrieve a previously posted notification, use the
getNotification()
method of theNotificationManager
interface (in mobile and wearable applications with the notification ID as a parameter:var myId = notification.id; var myNotification = tizen.notification.getNotification(myId);
-
To retrieve all previously posted notifications, use the
getAllNotifications()
method, which returns all the notifications as an array:var notifications = tizen.notification.getAllNotifications(); var index = 0; /* For each notification, write the ID and title in the console log */ for (index = 0; index < notifications.length; index++) { console.log(notifications[index].id); console.log(notifications[index].title); }
-
-
To update a previously posted notification, use the
update()
method by specifying the updated notification object:myNotification.content = 'My notification'; tizen.notification.update(myNotification);
-
To remove notifications:
-
To remove a previously posted notification, use the
remove()
method with the notification ID as a parameter:tizen.notification.remove(myNotification.id);
-
To remove all notifications previously posted by the current application, use the
removeAll()
method:tizen.notification.removeAll();
-
Managing Notification Templates
Learning how to manage notification templates allows you to create a template from an existing notification, and reuse that template later to quickly create other notifications with the same pattern:
-
To create a template:
-
Create a simple or progress notification to be used as a template.
You do not need to post the notification to save it as a template./* Assume that myNotification is a valid tizen.UserNotification object */ var myNotification;
-
Save the template with the
saveNotificationAsTemplate()
method of theNotificationManager
interface (in mobile and wearable applications):try { var templateName = 'importantNoti'; tizen.notification.saveNotificationAsTemplate(templateName, myNotification); } catch (e) { console.log('Error ' + e.message + ' occurred'); }
-
-
To use the template when creating a new notification, use the
createNotificationFromTemplate()
method of theNotificationManager
interface:try { var newTemplateNotification = tizen.notification.createNotificationFromTemplate(templateName); console.log('Content of new notification: ' + newTemplateNotification.content); } catch (e) { console.log('Error ' + e.message + ' occurred'); }
This method returns a
UserNotification
object (in mobile and wearable applications), even if the template was created based on aStatusNotification
object (in mobile and wearable applications).
Related Information
- Dependencies
- Tizen 2.4 and Higher for Mobile
- Tizen 2.3.1 and Higher for Wearable