Badge API (Samsung Extension)

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. This badge remains until the message is read by the user.

Deprecated. The Samsung extension Badge API(webapis.badge) is deprecated since Tizen 2.3. It is recommended to use the Tizen Public Badge API(tizen.badge since Tizen 2.3) instead.

Since: 2.2.1.3

Table of Contents


Summary of Interfaces and Methods

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

1. Type Definitions

1.1. ApplicationId

The unique ID for an installed application.
    typedef DOMString ApplicationId;

Since: 2.2.1.3

2. Interfaces

2.1. BadgeManagerObject

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

Since: 2.2.1.3

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

2.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);


        long getBadgeCount(ApplicationId appId);


        void addChangeListener(ApplicationId[]appIdList, BadgeChangeCallback successCallback);
        

        void removeChangeListener(ApplicationId[] appIdList);
    };

Since: 2.2.1.3

Attributes

  • readonly long maxBadgeCount
    Maximum length of a badge number.

    Since: 2.2.1.3

Methods

setBadgeCount
Sets the badge count for the designated application. Only applications with the same author signature can have their badge count modified.

Deprecated. The Samsung extension Badge API(webapis.badge) is deprecated since Tizen 2.3. It is recommended to use the Tizen Public Badge API(tizen.badge since Tizen 2.3) instead.

void setBadgeCount(ApplicationId appId, long count);
             

Since: 2.2.1.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:

 try {
     webapis.badge.setBadgeCount("AVbg1ZHu6l.BadgeSample", 3);
 } catch(e) {
     console.log("Error Exception, error name : " + e.name + ", error message : " + e.message);
 }
 
getBadgeCount
Gets the badge count for the designated application.

Deprecated. The Samsung extension Badge API(webapis.badge) is deprecated since Tizen 2.3. It is recommended to use the Tizen Public Badge API(tizen.badge since Tizen 2.3) instead.

long getBadgeCount(ApplicationId appId);
             

Since: 2.2.1.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:

 try {
     var count = webapis.badge.getBadgeCount("AVbg1ZHu6l.BadgeSample");
 } catch(e) {
     console.log("Error Exception, error name : " + e.name + ", error message : " + e.message);
 }
 
addChangeListener
Adds a listener to receive a notification when the badge number for the designated application changes.

Deprecated. The Samsung extension Badge API(webapis.badge) is deprecated since Tizen 2.3. It is recommended to use the Tizen Public Badge API(tizen.badge since Tizen 2.3) instead.

void addChangeListener(ApplicationId[] appIdList, BadgeChangeCallback successCallback);
             

Since: 2.2.1.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:

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

  // Registers to be notified when the badge number changes
  webapis.badge.addChangeListener(["AVbg1ZHu6l.BadgeSample", "BDb5tZJe47.TestSample"], watcher);
 
removeChangeListener
Unsubscribes from receiving notifications for badge number changes.

Deprecated. The Samsung extension Badge API(webapis.badge) is deprecated since Tizen 2.3. It is recommended to use the Tizen Public Badge API(tizen.badge since Tizen 2.3) instead.

void removeChangeListener(ApplicationId[] appIdList);
             

Since: 2.2.1.3

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:

  // Receives badge number changes
  function watcher(appId, count) {
      console.log(appId + ' badge number were updated : ' + count);
  }

  // Registers to be notified when the badge number changes
  webapis.badge.addChangeListener(["AVbg1ZHu6l.BadgeSample", "BDb5tZJe47.TestSample"], watcher);

  // Cancels the watch operation
  webapis.badge.removeChangeListener(["AVbg1ZHu6l.BadgeSample", "BDb5tZJe47.TestSample"]);
 

2.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.2.1.3

Methods

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

Since: 2.2.1.3

Parameters:

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

3. Related Feature

It is recommended to design feature related code in a modular way.

To guarantee the running of this application on a device with Badge feature, define the following requirements in the config file:

  • http://developer.samsung.com/tizen/feature/samsung_extension
  • 4. Full WebIDL

     module Badge{
    
    
        typedef DOMString ApplicationId;
      
    
        [NoInterfaceObject] interface BadgeManagerObject {
             readonly attribute BadgeManager badge;
        };
        WebAPIs implements BadgeManagerObject;
    
    
        [NoInterfaceObject] interface BadgeManager {
    
            readonly attribute long maxBadgeCount;
            
    
            void setBadgeCount(ApplicationId appId, long count);
    
    
            long getBadgeCount(ApplicationId appId);
    
    
            void addChangeListener(ApplicationId[]appIdList, BadgeChangeCallback successCallback);
            
    
            void removeChangeListener(ApplicationId[] appIdList);
        };
    
    
        [Callback=FunctionOnly, NoInterfaceObject]
        interface BadgeChangeCallback {
    
            void onsuccess(ApplicationId appId, long count);
        };
    };