Notification API

The Notification API provides a way to notify users of events that happen in an application. In Tizen Wearable Profile, only icon, title, content, time are guaranteed to be displayed. Some other attributes can be supported additionally depending on the device.

For more information on the Notification features, see Notification Guide.

Since: 2.3.1

Table of Contents


Summary of Interfaces and Methods

Interface Method
NotificationObject
NotificationManager
void post (Notification notification)
void update (Notification notification)
void removeAll ()
Notification
StatusNotificationInit
StatusNotification
NotificationDetailInfo

1. Type Definitions

1.1. NotificationId

A notification ID.
  typedef DOMString NotificationId;

Since: 2.3.1

1.2. NotificationType

A notification type.
  enum NotificationType { "STATUS" };

Since: 2.3.1

The following notification type is supported:

  • STATUS - The posted status notification is displayed on the status bar and the notification tray. The status notification consists of an icon, title, content, and time. The status notification can have an application control to launch the specific application when selected by the user.

1.3. StatusNotificationType

A status notification type.
  enum StatusNotificationType { "SIMPLE", "THUMBNAIL", "ONGOING", "PROGRESS" };

Since: 2.3.1

The following status notification types are supported:

  • SIMPLE - A basic status notification type that is removed automatically when selected by the user. All simple status notifications can be removed by user interaction.
  • THUMBNAIL - The thumbnail status notification posts a thumbnail-format notification which includes several thumbnail image paths. The thumbnail status notification is also removed by user selection.
  • ONGOING - A status notification type that informs the user whether an application is running or not. However, an ongoing status notification should be removed by the application that posted the notification
  • PROGRESS - A status notification that displays information on the progress of a job. However, this status notification should be removed by the application that posted the notification.

1.4. NotificationProgressType

A notification progress type.
  enum NotificationProgressType { "PERCENTAGE", "BYTE" };

Since: 2.3.1

The following notification progress types are supported:

  • "BYTE" - The progress is indicated in bytes.
  • "PERCENTAGE" -The progress is indicated in percentage.

2. Interfaces

2.1. NotificationObject

Defines what is instantiated by the Tizen object.
  [NoInterfaceObject] interface NotificationObject {
    readonly attribute NotificationManager notification;
  };
  Tizen implements NotificationObject;

Since: 2.3.1

The tizen.notification object allows access to the Notification API.

Attributes

  • readonly NotificationManager notification
    Object representing a notification manager.

    Since: 2.3.1

2.2. NotificationManager

Notification manager interface that provides access to the API.
  [NoInterfaceObject] interface NotificationManager {
    void post(Notification notification) raises(WebAPIException);
    void update(Notification notification) raises(WebAPIException);
    void remove(NotificationId id) raises(WebAPIException);
    void removeAll() raises(WebAPIException);
    Notification get(NotificationId id) raises(WebAPIException);
    Notification[] getAll() raises(WebAPIException);
  };

Since: 2.3.1

The NotificationManager interface provides access to the notification object.

Methods

post
Posts a notification to display.
void post(Notification notification);

Since: 2.3.1

Privilege level: public

Privilege: http://tizen.org/privilege/notification

Parameters:

  • notification: A notification to post.

Exceptions:

  • WebAPIException
    • with error type InvalidValuesError, if any of the input parameters contain an invalid value.

    • with error type SecurityError, if the application does not have the privilege to call this method.

    • with error type TypeMismatchError, if any input parameter is not compatible with the expected type for that parameter.

    • with error type UnknownError, if any other error occurs.

Code example:

try
{
  var appControl = new tizen.ApplicationControl(
      "http://tizen.org/appcontrol/operation/create_content", null, "image/jpg", null);
  var notificationDict =
  {
    content: "This is a simple notification.",
    iconPath: "images/image1.jpg",
    soundPath: "music/Over the horizon.mp3",
    vibration: true,
    appControl: appControl
  };

  var notification =
      new tizen.StatusNotification("SIMPLE", "Simple notification", notificationDict);

  tizen.notification.post(notification);
}
catch (err)
{
  console.log(err.name + ": " + err.message);
}
update
Updates a previously posted notification.
void update(Notification notification);

Since: 2.3.1

Privilege level: public

Privilege: http://tizen.org/privilege/notification

Parameters:

  • notification: A notification to update.

Exceptions:

  • WebAPIException
    • with error type InvalidValuesError, if any of the input parameters contain an invalid value.

    • with error type SecurityError, if the application does not have the privilege to call this method.

    • with error type TypeMismatchError, if any input parameter is not compatible with the expected type for that parameter.

    • with error type UnknownError, if any other error occurs.

Code example:

try
{
  /* Uses a variable for the previously posted notification. */
  notification.content = "My notification";
  tizen.notification.update(notification);
}
catch (err)
{
  console.log(err.name + ": " + err.message);
}
remove
Removes a previously posted notification.
void remove(NotificationId id);

Since: 2.3.1

Privilege level: public

Privilege: http://tizen.org/privilege/notification

Parameters:

  • id: A previously posted notification ID to remove.

Exceptions:

  • WebAPIException
    • with error type NotFoundError, if NotificationId is not found in the previously posted notification.

    • with error type SecurityError, if the application does not have the privilege to call this method.

    • with error type TypeMismatchError, if any input parameter is not compatible with the expected type for that parameter.

    • with error type UnknownError, if any other error occurs.

Code example:

try
{
  /* Uses a variable for the previously posted notification. */
  tizen.notification.remove(notification.id);
}
catch (err)
{
  console.log(err.name + ": " + err.message);
}
removeAll
Removes all notifications that have been posted by the current application.
void removeAll();

Since: 2.3.1

Privilege level: public

Privilege: http://tizen.org/privilege/notification

Exceptions:

  • WebAPIException
    • with error type SecurityError, if the application does not have the privilege to call this method.

    • with error type UnknownError, if any other error occurs.

Code example:

try
{
  tizen.notification.removeAll();
}
catch (err)
{
  console.log(err.name + ": " + err.message);
}
get
Gets a notification that has previously been posted by the current application. Note that the obtained notification's progressType is PERCENTAGE

Since: 2.3.1

Parameters:

  • id: A previously posted notification ID.

Return value:

    Notification: Notification posted previously by the current application.

Exceptions:

  • WebAPIException
    • with error type NotFoundError, if NotificationId is not found in the previously posted notifications.

    • with error type UnknownError, if any other error occurs.

Code example:

try
{
  /* Uses a variable for the previously posted notification. */
  /* Saves the notification ID for future use. */
  var myId = notification.id;

  var myNotification = tizen.notification.get(myId);
}
catch (err)
{
  console.log(err.name + ": " + err.message);
}
getAll
Gets all notifications that have previously been posted by the current application. Note that the obtained notification's progressType is PERCENTAGE
Notification[] getAll();

Since: 2.3.1

Return value:

    Notification[]: All notifications previously been posted by the current application.

Exceptions:

  • WebAPIException
    • with error type UnknownError, if any other error occurs.

Code example:

try
{
  var notifications = tizen.notification.getAll();

  for (var index = 0; index < notifications.length; index++)
  {
    console.log(notifications[index].id);
    console.log(notifications[index].title);
    console.log(notifications[index].statusType);
    console.log(notifications[index].type);
    console.log(notifications[index].content);
    console.log(notifications[index].postedTime);
    console.log(notifications[index].iconPath);
    console.log(notifications[index].soundPath);
    console.log(notifications[index].vibration);
    console.log(notifications[index].appControl);
  }
}
catch (err)
{
  console.log(err.name + ": " + err.message);
}

2.3. Notification

The Notification interface offers common attributes to represent the Notification object.
  [NoInterfaceObject] interface Notification {
    readonly attribute NotificationId id;
    readonly attribute NotificationType type;
    readonly attribute Date postedTime;
    attribute DOMString title;
    attribute DOMString? content;
  };

Since: 2.3.1

Attributes

  • readonly NotificationId id
    The Notification identifier. Before the notification is posted, this value is undefined.

    Since: 2.3.1

  • readonly NotificationType type
    The Notification type.

    Since: 2.3.1

  • readonly Date postedTime
    The time when the notification is posted. Before the notification is posted, this value is undefined.

    Since: 2.3.1

  • DOMString title
    The title to display in a notification.

    Since: 2.3.1

  • DOMString content [nullable]
    The content to display in a notification.

    Since: 2.3.1

2.4. StatusNotificationInit

The properties of StatusNotification, to pass to the constructor.
  dictionary StatusNotificationInit {
    DOMString? content;
    DOMString? iconPath;
    DOMString? soundPath;
    boolean? vibration;
    ApplicationControl? appControl;
    ApplicationId? appId;
    NotificationProgressType? progressType;
    unsigned long? progressValue;
    long? number;
    DOMString? subIconPath;
    NotificationDetailInfo[]? detailInfo;
    DOMString? ledColor;
    unsigned long ledOnPeriod;
    unsigned long ledOffPeriod;
    DOMString? backgroundImagePath;
    DOMString[]? thumbnails;
  };

Since: 2.3.1

2.5. StatusNotification

The StatusNotification interface represents a status notification and offers additional attributes to represent a notification displayed in the notification tray.
  [Constructor(StatusNotificationType statusType, DOMString title, optional StatusNotificationInit? notificationInitDict)]
  interface StatusNotification : Notification {
    readonly attribute StatusNotificationType statusType;
    attribute DOMString? iconPath;
    attribute DOMString? subIconPath;
    attribute long? number;
    attribute NotificationDetailInfo[]? detailInfo;
    attribute DOMString? ledColor;
    attribute unsigned long ledOnPeriod;
    attribute unsigned long ledOffPeriod;
    attribute DOMString? backgroundImagePath;
    attribute DOMString[]? thumbnails;
    attribute DOMString? soundPath;
    attribute boolean vibration;
    attribute ApplicationControl? appControl;
    attribute ApplicationId? appId;
    attribute NotificationProgressType progressType;
    attribute unsigned long? progressValue;
  };

Since: 2.3.1

All notifications must have a title attribute.

Constructors

Constructor (StatusNotificationType, DOMString, StatusNotificationInit?)
StatusNotification(StatusNotificationType statusType, DOMString title, optional StatusNotificationInit? notificationInitDict);

Attributes

  • readonly StatusNotificationType statusType
    The status notification type.

    Since: 2.3.1

  • DOMString iconPath [nullable]
    The icon path to display in the notification.

    Since: 2.3.1

  • DOMString subIconPath [nullable]
    The sub icon path to display in the notification.

    Since: 2.3.1

  • long number [nullable]
    The number of events to display in the notification.

    Since: 2.3.1

  • NotificationDetailInfo[] detailInfo [nullable]
    Appends lines of the detail information to the notification. This attribute is available in a simple status notification. By default, this attribute is initialized with an empty array. The maximum number of detail information elements in the array is 2.

    Since: 2.3.1

  • DOMString ledColor [nullable]
    Sets the notification LED indicator color property. The color is a numerical RGB value(#rrggbb). The format of an RGB value in hexadecimal notation is a "#" immediately followed by exactly six hexadecimal characters(0-9, A-F). The color format is case-insensitive. The LED indicator color will show that it's a close approximation. LED will only light on when the screen is off. To turn the LED off, set "#000000" or null to ledColor. This method has effects when the device has notification LED.

    Since: 2.3.1

    Code example:

    try
    {
      var notificationDict =
      {
        content: "This is a simple notification.",
        iconPath: "images/image1.jpg",
        soundPath: "music/Over the horizon.mp3",
        vibration: true,
        ledColor: "#FFFF00",
        ledOnPeriod: 1000,
        ledOffPeriod: 500
      };
    
      var notification =
          new tizen.StatusNotification("SIMPLE", "Simple notification", notificationDict);
    
      tizen.notification.post(notification);
    }
    catch (err)
    {
      console.log(err.name + ": " + err.message);
    }
    
  • unsigned long ledOnPeriod
    The milliseconds for which the light is on. The light continuously toggles on (ledOnPeriod) and off (ledOffPeriod). By default, this attribute is set to 0

    Since: 2.3.1

  • unsigned long ledOffPeriod
    The milliseconds for which the light is off. By default, this attribute is set to 0.

    Since: 2.3.1

  • DOMString backgroundImagePath [nullable]
    The image path to use as the background of the notification. This attribute is available on simple or thumbnail status notifications.

    Since: 2.3.1

  • DOMString[] thumbnails [nullable]
    The image paths associated with the thumbnail status notification. By default, this attribute is initialized with an empty array. The maximum number of thumbnail path elements in the array is 4.

    Since: 2.3.1

  • DOMString soundPath [nullable]
    The path of a sound file to play when the notification is shown.

    Since: 2.3.1

  • boolean vibration
    Checks whether to vibrate when the notification is shown. By default, this attribute is set to false.

    Since: 2.3.1

  • ApplicationControl appControl [nullable]
    Holds the application control to launch an application when the notification is selected from the notification tray.

    Since: 2.3.1

  • ApplicationId appId [nullable]
    Holds the application ID to launch when the notification is selected from the notification tray.

    Since: 2.3.1

    Code example:

    try
    {
      /* Gets the current application information with tizen.application.getAppInfo. */
      var myappInfo = tizen.application.getAppInfo();
    
      var notificationDict =
      {
        content: "This is a simple notification.",
        iconPath: "images/image1.jpg",
        soundPath: "music/Over the horizon.mp3",
        vibration: true,
        appId: myappInfo.id
      };
    
      var notification =
          new tizen.StatusNotification("SIMPLE", "Simple notification", notificationDict);
    
      tizen.notification.post(notification);
    }
    catch (err)
    {
      console.log(err.name + ": " + err.message);
    }
    
  • NotificationProgressType progressType
    Defines the type for an ongoing notification's progress. By default, this attribute is set to PERCENTAGE.

    Since: 2.3.1

  • unsigned long progressValue [nullable]
    Defines the current notification progress value (PERCENTAGE or BYTE), depending on the progressType

    If progressValue is set, the progressbar will be displayed in the notification. The progressValue can change the amount of progress as it moves forward or backward. It gets the progress value of the current notification. If 0, the indeterminate progressbar will be shown. This attribute is only available for StatusNotification of type PROGRESS.

    Applications should keep the progress value for its job because the saved value in the notification status tray would be different from the exact progress value.

    Range of progressValue: percent (0 to 100).

    Since: 2.3.1

    Code example:

    try
    {
      var appControl = new tizen.ApplicationControl(
          "http://tizen.org/appcontrol/operation/create_content", null, "image/jpg", null);
    
      var notificationDict =
      {
        content: "This is a progress notification.",
        iconPath: "images/image2.jpg",
        soundPath: "music/Over the horizon.mp3",
        vibration: true,
        appControl: appControl,
        progressValue: 20
      };
      /* Constructs the progress notification. */
      var notification =
          new tizen.StatusNotification("PROGRESS", "Progress notification", notificationDict);
      /* Posts the notification. */
      tizen.notification.post(notification);
    
      /* Updates the progress value of the notification. */
      notification.progressValue = 59;
      tizen.notification.update(notification);
    }
    catch (err)
    {
      console.log(err.name + ": " + err.message);
    }
    

2.6. NotificationDetailInfo

The NotificationDetailInfo object that contains the detail information of the notification.
  [Constructor(DOMString mainText, optional DOMString? subText)]
  interface NotificationDetailInfo {
    attribute DOMString mainText;
    attribute DOMString? subText;
  };

Since: 2.3.1

Code example:

var detailInfo1 = new tizen.NotificationDetailInfo("Missed Call from James", "Feb 11 2013");
notification.detailInfo = [detailInfo1];

Constructors

Constructor (DOMString, DOMString?)
NotificationDetailInfo(DOMString mainText, optional DOMString? subText);

Attributes

  • DOMString mainText
    The main content of the detail information. This attribute is available on simple status notifications.

    Since: 2.3.1

  • DOMString subText [nullable]
    The secondary content of the detail information.

    By default, this attribute is set to null.

    Since: 2.3.1

3. Related Feature

Method tizen.systeminfo.getCapability() can be used in application runtime to check whether this API is supported.

  • http://tizen.org/feature/led
  • For more information, see Application Filtering.

    4. Full WebIDL

    module Notification {
      typedef DOMString NotificationId;
      enum NotificationType { "STATUS" };
      enum StatusNotificationType { "SIMPLE", "THUMBNAIL", "ONGOING", "PROGRESS" };
      enum NotificationProgressType { "PERCENTAGE", "BYTE" };
      dictionary StatusNotificationInit {
        DOMString? content;
        DOMString? iconPath;
        DOMString? soundPath;
        boolean? vibration;
        ApplicationControl? appControl;
        ApplicationId? appId;
        NotificationProgressType? progressType;
        unsigned long? progressValue;
        long? number;
        DOMString? subIconPath;
        NotificationDetailInfo[]? detailInfo;
        DOMString? ledColor;
        unsigned long ledOnPeriod;
        unsigned long ledOffPeriod;
        DOMString? backgroundImagePath;
        DOMString[]? thumbnails;
      };
      Tizen implements NotificationObject;
      [NoInterfaceObject] interface NotificationObject {
        readonly attribute NotificationManager notification;
      };
      [NoInterfaceObject] interface NotificationManager {
        void post(Notification notification) raises(WebAPIException);
        void update(Notification notification) raises(WebAPIException);
        void remove(NotificationId id) raises(WebAPIException);
        void removeAll() raises(WebAPIException);
        Notification get(NotificationId id) raises(WebAPIException);
        Notification[] getAll() raises(WebAPIException);
      };
      [NoInterfaceObject] interface Notification {
        readonly attribute NotificationId id;
        readonly attribute NotificationType type;
        readonly attribute Date postedTime;
        attribute DOMString title;
        attribute DOMString? content;
      };
      [Constructor(StatusNotificationType statusType, DOMString title, optional StatusNotificationInit? notificationInitDict)]
      interface StatusNotification : Notification {
        readonly attribute StatusNotificationType statusType;
        attribute DOMString? iconPath;
        attribute DOMString? subIconPath;
        attribute long? number;
        attribute NotificationDetailInfo[]? detailInfo;
        attribute DOMString? ledColor;
        attribute unsigned long ledOnPeriod;
        attribute unsigned long ledOffPeriod;
        attribute DOMString? backgroundImagePath;
        attribute DOMString[]? thumbnails;
        attribute DOMString? soundPath;
        attribute boolean vibration;
        attribute ApplicationControl? appControl;
        attribute ApplicationId? appId;
        attribute NotificationProgressType progressType;
        attribute unsigned long? progressValue;
      };
      [Constructor(DOMString mainText, optional DOMString? subText)]
      interface NotificationDetailInfo {
        attribute DOMString mainText;
        attribute DOMString? subText;
      };
    };