cordova-plugin-badge

Shows the count of unread messages as a badge on the app icon.

Downloads in past

Stats

StarsIssuesVersionUpdatedCreatedSize
cordova-plugin-badge
403270.8.84 years ago7 years agoMinified + gzip package size for cordova-plugin-badge in KB

Readme

SAMPLE APP :pointright:

Cordova Badge Plugin
npm version Code Climate PayPayl donate button
Cordovacordova plugin to access and modify the badge number of the app icon on various mobile platforms including iOS, Android and Windows.

How they appear to the user

Users see notifications in the following ways:
  • Badging the app’s icon
  • Progress indicator (OSX based on https://github.com/hokein/DockProgressBar)

Supported Platforms

Installation

The plugin can be installed via Cordova-CLICLI and is publicly available on NPMnpm.
Execute from the projects root folder:
$ cordova plugin add cordova-plugin-badge
Or install a specific version:
$ cordova plugin add cordova-plugin-badge@VERSION
Or install the latest head version:
$ cordova plugin add https://github.com/katzer/cordova-plugin-badge.git
Or install from local source:
$ cordova plugin add <path> --nofetch --nosave

Usage

The plugin creates the object cordova.plugins.notification.badge and is accessible after deviceready has been fired.
document.addEventListener('deviceready', function () {
    // cordova.plugins.notification.badge is now available
}, false);

Set the badge number

Badge numbers cannot be negative. The maximum might be restricted by the OS. A callback is optional and will be invoked with the current badge number.
cordova.plugins.notification.badge.set(10);

<img height="150px" src="images/ios.png">
    
<img height="150px" src="images/android.png">
    
<img height="150px" src="images/windows.png">


There's built-in support to increase the badge number:
cordova.plugins.notification.badge.increase(1, function (badge) {
    // badge is now 11 (10 + 1)
});

To decrease the badge number:
cordova.plugins.notification.badge.decrease(2, function (badge) {
    // badge is now 9 (11 - 2)
});

And to clear out the badge number:
cordova.plugins.notification.badge.clear();

Get the badge number

The default value is 0. The badge number wont get lost after reboot or app restart.
cordova.plugins.notification.badge.get(function (badge) {
    ...
});

Note: Modifying the badge number outside of the plugin does result into wrong behaivor!

Configurations

To clear the badge number automatically if the user taps the app icon:
cordova.plugins.notification.badge.configure({ autoClear: true });

OSX supports additional indicators. Other than to badge these are circular and download.
cordova.plugins.notification.badge.configure({ indicator: 'circular' });

<img src="images/osx-badge.png">
    
<img src="images/osx-circular.png">
    
<img src="images/osx-download.png">

Permissions

The plugin might ask for granting permissions to modify the badge number. That's done automatically but it's also possible to request them manually:
cordova.plugins.notification.badge.requestPermission(function (granted) {
    ...
});

<img height="200px" src="images/ios-permission.png">


To check if they have been granted already:
cordova.plugins.notification.badge.hasPermission(function (granted) {
    ...
});

Quirks

On Android not all launchers support badges. In order to set badges the plugin uses ShortcutBadgershortcutbadger. Check out their website to see which launchers are supported.
If you're using PhoneGap Build please make sure you specify gradle as your Android build tool in config.xml:
<preference name="android-build-tool" value="gradle" />

To specify a custom version of ShortcutBadger follow this guidegradle-guide. The name of the property is appShortcutBadgerVersion.
# In <your-project>/platforms/android/gradle.properties
appShortcutBadgerVersion=1.1.22

Contributing

  1. Fork it
  2. Create your feature branch (git checkout -b my-new-feature)
  3. Commit your changes (git commit -am 'Add some feature')
  4. Push to the branch (git push origin my-new-feature)
  5. Create new Pull Request

License

This software is released under the Apache 2.0 Licenseapache2license.
Made with :yum: from Leipzig
© 2013 appPlant GmbHappplant