[](https://www.paypal.com/cgi-bin/webscr?cmd=_s-xclick&hosted_button_id=L3HKQCD9UA35A "Donate once-off to this project using Paypal")
Cordova Local-Notification Plugin
==================================
=================================
The essential purpose of local notifications is to enable an application to inform its users that it has something for them — for example, a message or an upcoming appointment — when the application isn’t running in the foreground.<br>
They are scheduled by an application and delivered on the same device.
Local notifications are ideally suited for applications with time-based behaviors, such as calendar and to-do list applications. Applications that run in the background for the limited period allowed by iOS might also find local notifications useful.<br>
For example, applications that depend on servers for messages or data can poll their servers for incoming items while running in the background; if a message is ready to view or an update is ready to download, they can then present a local notification immediately to inform their users.
### Plugin's Purpose
The purpose of the plugin is to create a platform-independent javascript interface for [Cordova][cordova]-based mobile applications to access the specific API on each platform.
## Supported Platforms
-**iOS** _(up to iOS8)_<br>
See [Local and Push Notification Programming Guide][ios_notification_guide] for detailed information and screenshots.
-**Android***(SDK >=7)*<br>
See [Notification Guide][android_notification_guide] for detailed information and screenshots.
-**WP8**<br>
See [Local notifications for Windows Phone][wp8_notification_guide] for detailed information and screenshots.
<br>*Windows Phone 8.0 has no notification center. Instead local notifications are realized through live tiles updates.*
The current 0.8 branch supports the following platforms:
- __iOS__ _(including iOS8)_<br>
- __Android__ _(SDK >=7)_
The partial support for WP8.0 has been dropped, but the Windows (Phone) 8.1 platform will be fully supported soon.
## Dependencies
[Cordova][cordova] will check all dependencies and install them if they are missing.
// window.plugin.notification.local is now available
},false);
```
### Determine if the app does have the permission to show local notifications
If the permission has been granted through the user it can be retrieved through the `notification.local.hasPermission` interface.<br/>
The method takes a callback function as its argument which will be called with a boolean value. Optional: the scope of the callback function can be defined through a second argument.
#### Further information
- The method is supported on each platform, however it's only relevant for iOS8 and above.
// console.log('Permission has been granted: ' + granted);
});
```
### Register permission for local notifications
Required permissions can be registered through the `notification.local.registerPermission` interface.<br/>
The method takes a callback function as its argument which will be called with a boolean value. Optional: the scope of the callback function can be defined through a second argument.
#### Further information
- The method is supported on each platform, however its only relevant for iOS8 and above.
- The user will only get a prompt dialog for the first time. Later it's only possible to change the setting via the notification center.
// console.log('Permission has been granted: ' + granted);
});
```
### Schedule local notifications
Local notifications can be scheduled through the `notification.local.add` interface.<br>
The method takes a hash as an argument to specify the notification's properties and returns the ID for the notification.<br>
Scheduling a local notification will override an earlier one with the same ID.
All properties are optional. If no date object is given, the notification pops-up immediately.
**Note:** The notification ID must be a string which can be converted to a number (that is, `isNaN()` returns false for). If the ID has an invalid format, it will silently be changed to `0` and will override an earlier one with the same ID.
#### Further information
- See the [onadd][onadd] event for registering a listener to be notified when a local notification has been scheduled.
- See the [ontrigger][ontrigger] event for registering a listener to be notified when a local notification has been triggered.
- See the [onclick][onclick] event for registering a listener to be notified when the user has been clicked on a local notification.
- See the [platform specific properties][platform_specific_properties] too list which other properties are available too.
- See [getDefaults][getdefaults] to examine which property values are used by default and [setDefaults][setdefaults] how to override them.
- See [examples][examples] for scheduling local notifications.
```javascript
window.plugin.notification.local.add({
id:String,// A unique id of the notification
date:Date,// This expects a date object
message:String,// The message that is displayed
title:String,// The title of the message
repeat:String,// Either 'secondly', 'minutely', 'hourly', 'daily', 'weekly', 'monthly' or 'yearly'
badge:Number,// Displays number badge to notification
sound:String,// A sound to be played
json:String,// Data to be passed through the notification
autoCancel:Boolean,// Setting this flag and the notification is automatically cancelled when the user clicks it
ongoing:Boolean,// Prevent clearing of notification (Android only)
},callback,scope);
```
### Cancel scheduled local notifications
Local notifications can be cancelled through the `notification.local.cancel` interface.<br>
Note that only local notifications with an ID can be cancelled.
#### Further information
- See the [oncancel][oncancel] event for registering a listener to be notified when a local notification has been cancelled.
- See [getScheduledIds][getscheduledids] to retrieve a list of IDs for all scheduled local notifications.
### Check whether a notification with an ID is scheduled
To check if a notification with an ID is scheduled, the `notification.local.isScheduled` interface can be used.<br>
The method takes the ID of the local notification as an argument and a callback function to be called with the result. Optional: the scope of the callback can be assigned too.
## I want to get a quick overview
All wiki pages contain samples, but for a quick overview the sample section may be the fastest way.
#### Further information
- See [getScheduledIds][getscheduledids] to retrieve a list of IDs for all scheduled local notifications.
The plugin supports scheduling local notifications in various ways with a single interface. It also allows you to update, clear or cancel them. There are different interfaces to query for local notifications and a complete set of events to hook into the life cycle of local notifications.
### Check whether a notification with an ID was triggered
To check if a notification with an ID was triggered, the `notification.local.isTriggered` interface can be used.<br>
The method takes the ID of the local notification as an argument and a callback function to be called with the result. Optional: the scope of the callback can be assigned too.
Find out more about how to schedule single, multiple, delayed or repeating local notifications [here][wiki_schedule].<br>
Informations about events like _click_ or _trigger_ can be found [here][wiki_events].
#### Further information
- See [getTriggeredIds][gettriggeredIds] to retrieve a list of IDs for all scheduled local notifications.
To get a deep overview we recommend to read about all the topics in our [wiki][wiki] and try out the [Kitchen Sink App][wiki_kitchensink]
Find out more informations [here][wiki_kitchensink] in our wiki.
### Get the default values of the local notification properties
The default values of the local notification properties can be retrieved through the `notification.local.getDefaults` interface.<br>
The method returns an object of values for all available local notification properties on the platform.
#### Further information
- See [setDefaults][setdefaults] to override the default values.
## What's new
We are proud to announce our newest release version 0.8.x. Beside the hard work at the office and at the weekends it contains a lot of goodies, new features and easy to use APIs.
Find out more informations [here][wiki_changelog] in our wiki.
### Set the default values of the local notification properties
The default values of the local notification properties can be set through the `notification.local.setDefaults` interface.<br>
The method takes an object as argument.
#### Further information
- See the [add][add] interface and the [platform specific properties][platform_specific_properties] to get an overview about all available local notification properties.
- See the [example][setdefaults_example] to override default values.
## Sample
The sample demonstrates how to schedule a local notification which repeats every week. The listener will be called when the user has clicked on the local notification.
You can package the audio data in an *aiff*, *wav*, or *caf* file. Then, in Xcode, add the sound file to your project as a nonlocalized resource of the application bundle. You may use the *afconvert* tool to convert sounds.
**Note:** To play notification sounds, permission needs to be granted in the notification center settings.<br>
**Note:** Custom sounds must be under 30 seconds when played. If a custom sound is over that limit, the default system sound is played instead.
```javascript
/**
* Plays the `beep.mp3` which must be located in the root folder of the project
LiveTiles have the ability to display images for different sizes. These images can be defined through the `smallImage`, `image` and `wideImage` properties.
**Note:** An image must be defined as a relative or absolute URI. They can be restored to default by cancelling the notification.
```javascript
/**
* Displays the application icon as the LiveTile's background image
The LED color can be specified through the `led` property. By default the color value is white (FFFFFF). It is possible to change that value by setting another hex code.
Each application on a device is limited to 64 scheduled local notifications.<br>
The system discards scheduled notifications in excess of this limit, keeping only the 64 notifications that will fire the soonest. Recurring notifications are treated as a single notification.
### Events aren't fired on iOS
After deploying/replacing the app on the device via Xcode, no callback for previously scheduled local notifications are fired.
### No sound is played on iOS 7
Users must grant permission in the notification center settings for notification sounds to be played.
### Adding a notification on WP8
An application can only display one notification at a time. Each time a new notification is added, the application's LiveTile 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 must be renamed to `version`.
[](https://www.paypal.com/cgi-bin/webscr?cmd=_s-xclick&hosted_button_id=L3HKQCD9UA35A "Donate once-off to this project using Paypal")
## Contributing
...
...
@@ -549,35 +108,16 @@ The launch mode for the main activity has to be set to `singleInstance`
This software is released under the [Apache 2.0 License][apache2_license].
<description>The purpose of the plugin is to create an platform independent javascript interface for Cordova based mobile applications to access the specific Notification API on each platform.</description>
<description>The plugin supports scheduling local notifications in various ways with a single interface. It also allows you to update, clear or cancel them. There are different interfaces to query for local notifications and a complete set of events to hook into the life cycle of local notifications. To get a deep overview we recommend to read about all the topics in our wiki and try out the Kitchen Sink App</description>
