Newer
Older
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
<p align="left"><b><a href="https://github.com/katzer/cordova-plugin-badge/tree/example">SAMPLE APP</a> :point_right:</b></p>
# Cordova Badge Plugin <br> [](https://badge.fury.io/js/cordova-plugin-badge) [](https://codeclimate.com/github/katzer/cordova-plugin-badge) [](https://www.paypal.com/cgi-bin/webscr?cmd=_s-xclick&hosted_button_id=L3HKQCD9UA35A "Donate once-off to this project using Paypal")
[Cordova][cordova] plugin to access and modify the badge number of the app icon on various mobile platforms including iOS, Android and Windows.
<img height="150px" align="right" hspace="19" vspace="12" src="http://4.bp.blogspot.com/-GBwBSN92DvU/UB8Kut7Oz0I/AAAAAAAAJKs/mJgBmj1RKqU/s1600/whatsapp+wp8+10.png"></img>
### 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
- __Android / Amazon FireOS__ (via [ShortcutBadger][shortcut_badger])
- __Browser__ (via [favico.js][favico_js])
- __iOS 10+__
- __OSX__
- __Windows__ (Phone and Desktop)
## Installation
The plugin can be installed via [Cordova-CLI][CLI] and is publicly available on [NPM][npm].
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.
```js
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.
```js
cordova.plugins.notification.badge.set(10);
```
<p align="center">
<img height="150px" src="images/ios.png">
<img height="150px" src="images/android.png">
<img height="150px" src="images/windows.png">
</p>
There's built-in support to increase the badge number:
```js
cordova.plugins.notification.badge.increase(1, function (badge) {
// badge is now 11 (10 + 1)
});
```
To decrease the badge number:
```js
cordova.plugins.notification.badge.decrease(2, function (badge) {
// badge is now 9 (11 - 2)
});
```
And to clear out the badge number:
```js
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.
```js
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:
```js
cordova.plugins.notification.badge.configure({ autoClear: true });
```
OSX supports additional indicators. Other than to `badge` these are `circular` and `download`.
```js
cordova.plugins.notification.badge.configure({ indicator: 'circular' });
```
<p align="center">
<img src="images/osx-badge.png">
<img src="images/osx-circular.png">
<img src="images/osx-download.png">
</p>
## 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:
```javascript
cordova.plugins.notification.badge.requestPermission(function (granted) {
...
});
```
<p align="center">
<img height="200px" src="images/ios-permission.png">
</p>
To check if they have been granted already:
```javascript
cordova.plugins.notification.badge.hasPermission(function (granted) {
...
});
```
## Quirks
On Android not all launchers support badges. In order to set badges the plugin uses [ShortcutBadger][shortcut_badger]. 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:
```xml
<preference name="android-build-tool" value="gradle" />
```
To specify a custom version of _ShortcutBadger_ follow this [guide][gradle-guide]. The name of the property is `appShortcutBadgerVersion`.
```gradle
// In <your-project>/platforms/android/build-extras.gradle
ext.appShortcutBadgerVersion = '1.1.18'
```
## 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 License][apache2_license].
Made with :yum: from Leipzig
© 2013 [appPlant GmbH][appplant]
[cordova]: https://cordova.apache.org
[shortcut_badger]: https://github.com/leolin310148/ShortcutBadger
[favico_js]: http://lab.ejci.net/favico.js/
[CLI]: http://cordova.apache.org/docs/en/edge/guide_cli_index.md.html#The%20Command-line%20Interface
[npm]: https://www.npmjs.com/package/cordova-plugin-badge
[gradle-guide]: https://cordova.apache.org/docs/en/latest/guide/platforms/android/#configuring-gradle
[apache2_license]: http://opensource.org/licenses/Apache-2.0
[appplant]: http://appplant.de