A bunch of local notification plugins for Cordova 3.x.x
by Sebastián Katzer (github.com/katzer)
-
iOS
See Local and Push Notification Programming Guide for detailed informations and screenshots. -
Android (SDK >=11)
See Notification Guide for detailed informations and screenshots. -
WP8
See Local notifications for Windows Phone for detailed informations and screenshots.
Windows Phone 8.0 has no notification center. Instead local notifications are realized through live tiles updates.
Cordova will check all dependencies and install them if they are missing.
- org.apache.cordova.device (since v0.6.0)
Through the Command-line Interface:
cordova plugin add https://github.com/katzer/cordova-plugin-local-notifications.git
Through the Command-line Interface:
cordova plugin rm de.appplant.cordova.plugin.local-notification
Add the following xml to your config.xml to always use the latest version of this plugin:
<gap:plugin name="de.appplant.cordova.plugin.local-notification" />
or to use this exact version:
<gap:plugin name="de.appplant.cordova.plugin.local-notification" version="0.6.2" />
More informations can be found here.
- [bugfix:] App throws an error on iOS if
message
is null. - [bugfix:] Removed extra line break on iOS if
title
is null or empty. - [bugfix:] Notification on iOS will be canceled if a new one with the same ID was added.
- [feature:] Added
autoCancel
flag. - [bugfix:]
cancel
on iOS did not work. - [enhancement:] Added 'hourly' as a new repeat time aliase.
- [feature:] Repeat with custom intervals on Android.
- [bugfix:] Black screen on Android.
- [bugfix:] App throws an error on reboot on Android.
- Calling
cancel
on Android with an invalid String as ID does not throw an error anymore.
- Release under the Apache 2.0 license.
- Release under the LGPL 2.1 license.
- [feature:] Sound can be specified on Android.
- [enhancement:] Adding notifications on Android does not block the ui thread anymore.
- [bugfix:] The app did stop/crash after removing them from recent apps list.
- [enhancement:] Adding notifications on iOS does not block the ui thread anymore.
- [bugfix:] Added missing
RECEIVE_BOOT_COMPLETED
permission on Android. - [enhancement:] Rework the code for Android. Thanks to samsara (samsarayg).
- [bugfix:]
cancel
on iOS did not work do to wrong param type. - [enhancement:]
cancel
&cancelAll
remove the notification(s) from notification center as well on Android. - [bugfix:] Missing background callback on Android.
- [bugfix:] Android notification is not shown when the app is not running.
- Added WP8 support
Based on the LiveTiles WP8 plugin made by Jesse MacFadyen (purplecabbage) - [enhancement:] The
add()
function now returns the id of the created notification. - [feature:] Added new
title
property. - [bugfix:]
cancel
on iOS did not work do to wrong dict key. - [enhancement:] All notifications on Android display the app icon by default.
- [feature:] Icon can be specified on Android.
- Added Android support
Based on the LocalNotifications Android plugin made by Daniël (dvtoever)
- Added iOS support
Based on the LocalNotifications iOS plugin made by Rodrigo Moyle
The plugin creates the object window.plugin.notification.local
with the following methods:
The method allows to add a custom notification. It takes an hash as an argument to specify the notification's properties and returns the ID for the notification.
All properties are optional. If no date object is given, the notification will pop-up immediately.
window.plugin.notification.local.add({
id: String, // A unique id of the notifiction
date: Date, // This expects a date object
message: String, // The message that is displayed
title: String, // The title of the message
repeat: String, // Has the options of 'hourly', 'daily', 'weekly', 'monthly', 'yearly'
badge: Number, // Displays number badge to notification
sound: String, // A sound to be played (iOS & Android)
autoCancel: Boolean, // Setting this flag and the notification is automatically canceled when the user clicks it
foreground: String, // A javascript function to be called if the app is running
background: String, // A javascript function to be called if the app is in the background
});
Note: On Android the notification id needs to be a string which can be converted to a number. If the ID has an invalid format, it will be ignored, but canceling the notification will fail.
The method cancels a notification which was previously added. It takes the ID of the notification as an argument.
window.plugin.notification.local.cancel(String);
The method cancels all notifications which were previously added by the application.
window.plugin.notification.local.cancelAll();
var now = new Date().getTime(),
_60_seconds_from_now = new Date(now + 60*1000);
window.plugin.notification.local.add({
id: 1, // is converted to a string
title: 'Reminder',
message: 'Dont forget to buy some flowers.',
repeat: 'weekly',
date: _60_seconds_from_now,
foreground: 'foreground',
background: 'background'
});
function foreground (id) {
console.log('I WAS RUNNING ID='+id)
}
function background (id) {
console.log('I WAS IN THE BACKGROUND ID='+id)
}
window.plugin.notification.local.add({ message: 'Great app!' });
window.plugin.notification.local.add({ sound: null });
By default all notifications will display the app icon. But an specific icon can be defined through the icon
property.
/**
* Displays the <package.name>.R.drawable.ic_launcher icon
*/
window.plugin.notification.local.add({ icon: 'ic_launcher' });
/**
* Displays the android.R.drawable.ic_dialog_email icon
*/
window.plugin.notification.local.add({ icon: 'ic_dialog_email' });
The sound must be a absolute or relative Uri pointing to the sound file. The default sound is RingtoneManager.TYPE_NOTIFICATION
.
/**
* Plays the `beep.mp3` sound if the notification pop's up
*/
window.plugin.notification.local.add({ sound: 'android.resource://' + package_name + '/raw/beep' });
/**
* Plays the `RingtoneManager.TYPE_ALARM` sound
*/
window.plugin.notification.local.add({ sound: 'TYPE_ALARM' });
Note: Local sound files must be placed into the res-folder and not into the assets-folder.
The sound must be located in your project's resources and must be a caf file.
/**
* Plays the sound if the notification pop's up
*/
window.plugin.notification.local.add({ sound: 'sub.caf' });
Note: The right to play notification sounds in the notification center settings has to be granted.
LiveTile's have the ability to display images for different sizes. These images can be defined through the smallImage
, image
and wideImage
properties.
An image must be defined as a relative or absolute URI.
/**
* Displays the application icon as the livetile's background image
*/
window.plugin.notification.local.add({ image: 'appdata:ApplicationIcon.png' })
All images can be restored to the default ones by canceling the notification.
To specify a custom interval, the repeat
property can be assigned with an number in minutes.
/**
* Schedules the notification quarterly every 15 mins
*/
window.plugin.notification.local.add({ repeat: 15 });
## Quirks
### No sound is played on iOS 7
The right to play notification sounds in the notification center settings has to be granted.
### Adding a notification on WP8
An application can only display one notification at a time. Each time a new notification has to be added, the application live tile's data will be overwritten by the new ones.
### TypeError: Cannot read property 'currentVersion' of null
Along with Cordova 3.2 and Windows Phone 8 the `version.bat` script has to be renamed to `version`.
On Mac or Linux
mv platforms/wp8/cordova/version.bat platforms/wp8/cordova/version
On Windows
ren platforms\wp8\cordova\version.bat platforms\wp8\cordova\version
### App restarts on Android after notification was clicked
The launch mode for the main activity has to be set to `singleInstance`
```xml
<activity ... android:launchMode="singleInstance" ... />
- Fork it
- Create your feature branch (
git checkout -b my-new-feature
) - Commit your changes (
git commit -am 'Add some feature'
) - Push to the branch (
git push origin my-new-feature
) - Create new Pull Request
This software is released under the Apache 2.0 License.