Badge API

The Badge API provides Badge management functionality. It provides functions for creating and updating a badge. The application with new unread information has a number in the upper right hand corner of the app icon. This number is called a badge. For example, when a new message is received the badge count appears on the app icon. The badge remains until the message is read by the user.

For more information about how to use Badge API, see Badge Guide.

Since: 2.3

Table of Contents

Summary of Interfaces and Methods

Interface Method
BadgeManagerObject
BadgeManager
void setBadgeCount (ApplicationId appId, long count)
void addChangeListener (ApplicationId[] appIdList, BadgeChangeCallback successCallback)
BadgeChangeCallback
void onsuccess (ApplicationId appId, long count)

1. Interfaces

1.1. BadgeManagerObject

The BadgeManagerObject interface defines what is instantiated in the tizen object. 
  [NoInterfaceObject] interface BadgeManagerObject {
    readonly attribute BadgeManager badge;
  };
  Tizen implements BadgeManagerObject;

Since: 2.3

There is a tizen.badge object that allows accessing the functionality of the Badge API.

Attributes

  • readonly BadgeManager badge
    Object representing a badge manager object.

    Since: 2.3

1.2. BadgeManager

The BadgeManager interface manages Badge functionality. It provides functions for creating and updating a badge, and registering for badge change events. 
  [NoInterfaceObject] interface BadgeManager {
    readonly attribute long maxBadgeCount;
    void setBadgeCount(ApplicationId appId, long count) raises(WebAPIException);
    long getBadgeCount(ApplicationId appId) raises(WebAPIException);
    void addChangeListener(ApplicationId[] appIdList, BadgeChangeCallback successCallback) raises(WebAPIException);
    void removeChangeListener(ApplicationId[] appIdList) raises(WebAPIException);
  };

Since: 2.3

Attributes

  • readonly long maxBadgeCount
    Maximum length of a badge number.

    Since: 2.3

    Code example:

    console.log("Maximum length of a badge number is " + tizen.badge.maxBadgeCount);

Methods

setBadgeCount
Sets the badge count for the designated application. Only applications with the same author signature can have their badge count modified. 
void setBadgeCount(ApplicationId appId, long count);

Since: 2.3

Privilege level: public

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

Parameters:

  • appId: ID of the application to update the badge.
  • count: Number to display as the badge on the application icon
    To remove the badge, set the value of this param to 0.

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 or if the author signature does not match that of the designated application.

    • with error type UnknownError, if the method cannot be completed because of an unknown error.

Code example:

var app = tizen.application.getCurrentApplication();
var appid = app.appInfo.id;
tizen.badge.setBadgeCount(appid, 3);
getBadgeCount
Gets the badge count for the designated application. 
long getBadgeCount(ApplicationId appId);

Since: 2.3

Privilege level: public

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

Parameters:

  • appId: ID of the designated application.

Return value:

    long: Count of the badge.

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 UnknownError, if the method cannot be completed because of an unknown error.

Code example:

var app = tizen.application.getCurrentApplication();
var appid = app.appInfo.id;
var count = tizen.badge.getBadgeCount(appid);
addChangeListener
Adds a listener to receive a notification when the badge number for the designated application changes. 
void addChangeListener(ApplicationId[] appIdList, BadgeChangeCallback successCallback);

Since: 2.3

Privilege level: public

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

Parameters:

  • appIdList: Array of the ID of the designated application.
  • successCallback: Callback method to be invoked when a badge number change notification is received.

Exceptions:

  • WebAPIException

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

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

    • 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:

/* Assume that at least two applications are installed. */

function onListInstalledApps(appsInfo)
{
  function watcher(appId, count)
  {
    console.log(appId + " badge number were updated: " + count);
  }

  /* Registers to be notified when the badge number changes. */
  tizen.badge.addChangeListener([appsInfo[0].id, appsInfo[1].id], watcher);
}

tizen.application.getAppsInfo(onListInstalledApps);
removeChangeListener
Unsubscribes from receiving notifications for badge number changes. 
void removeChangeListener(ApplicationId[] appIdList);

Since: 2.3

Nothing will be done for app ids which do not have any registered listeners.

Privilege level: public

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

Parameters:

  • appIdList: Array of the ID of the designated application.

Exceptions:

  • WebAPIException

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

    • 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:

/* Assume that at least two applications are installed. */

function onListInstalledApps(appsInfo)
{
  function watcher(appId, count)
  {
    console.log(appId + " badge number were updated: " + count);
  }

  /* Registers to be notified when the badge number changes. */
  tizen.badge.addChangeListener([appsInfo[0].id, appsInfo[1].id], watcher);

  /* Cancels the watch operation. */
  tizen.badge.removeChangeListener([appsInfo[0].id, appsInfo[1].id]);
}

tizen.application.getAppsInfo(onListInstalledApps);

1.3. BadgeChangeCallback

The BadgeChangeCallback interface specifies a set of methods that are invoked every time a badge number change occurs. 
  [Callback=FunctionOnly, NoInterfaceObject] interface BadgeChangeCallback {
    void onsuccess(ApplicationId appId, long count);
  };

Since: 2.3

Methods

onsuccess
Called when the badge number of a specified application is updated. 
void onsuccess(ApplicationId appId, long count);

Since: 2.3

Parameters:

  • appId: ID of the designated application.
  • count: Count of the badge.

Code example:

/* Logs the number of badge changes. */
function watcher(appId, count)
{
  console.log(appId + " -> badge number updates: " + count);
}

/* Gets Application's ID. */
var appId = tizen.application.getCurrentApplication().appInfo.id;

/* Assume that the application "TestSample.main" has been installed. */
var targetAppId = "TestSample.main";

/* Registers to be notified when the badge number changes for either */
/* this or targetAppId application. */
tizen.badge.addChangeListener([appId, targetAppId], watcher);

2. Full WebIDL

module Badge {
  Tizen implements BadgeManagerObject;
  [NoInterfaceObject] interface BadgeManagerObject {
    readonly attribute BadgeManager badge;
  };
  [NoInterfaceObject] interface BadgeManager {
    readonly attribute long maxBadgeCount;
    void setBadgeCount(ApplicationId appId, long count) raises(WebAPIException);
    long getBadgeCount(ApplicationId appId) raises(WebAPIException);
    void addChangeListener(ApplicationId[] appIdList, BadgeChangeCallback successCallback) raises(WebAPIException);
    void removeChangeListener(ApplicationId[] appIdList) raises(WebAPIException);
  };
  [Callback=FunctionOnly, NoInterfaceObject] interface BadgeChangeCallback {
    void onsuccess(ApplicationId appId, long count);
  };
};
Except as noted, this content - excluding the Code Examples - is licensed under Creative Commons Attribution 3.0 and all of the Code Examples contained herein are licensed under BSD-3-Clause.
For details, see the Content License.