[](https://www.paypal.com/cgi-bin/webscr?cmd=_s-xclick&hosted_button_id=L3HKQCD9UA35A "Donate once-off to this project using Paypal")
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>
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.
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>
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.
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
## Supported Platforms
-**iOS** _(up to iOS8)_<br>
The current 0.8 branch supports the following platforms:
See [Local and Push Notification Programming Guide][ios_notification_guide] for detailed information and screenshots.
- __iOS__ _(including iOS8)_<br>
- __Android__ _(SDK >=7)_
-**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 partial support for WP8.0 has been dropped, but the Windows (Phone) 8.1 platform will be fully supported soon.
## Dependencies
Find out more informations [here][wiki_platforms] in our wiki.
[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.
All wiki pages contain samples, but for a quick overview the sample section may be the fastest way.
// All notifications have been cancelled
},scope);
```
### 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.
#### Further information
Find out more informations [here][wiki_samples] in our wiki.
- 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
Find out more about how to schedule single, multiple, delayed or repeating local notifications [here][wiki_schedule].<br>
To check if a notification with an ID was triggered, the `notification.local.isTriggered` interface can be used.<br>
Informations about events like _click_ or _trigger_ can be found [here][wiki_events].
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.
#### Further information
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]
- See [getTriggeredIds][gettriggeredIds] to retrieve a list of IDs for all scheduled local notifications.
### 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
## What's new
- See [setDefaults][setdefaults] to override the default values.
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.
```javascript
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
## Sample
- See the [add][add] interface and the [platform specific properties][platform_specific_properties] to get an overview about all available local notification properties.
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.
- See the [example][setdefaults_example] to override default values.
Your support is needed. If you use the plugin please send us a drop through the donation button.
```
See below to use the `android.R.drawable.ic_dialog_email` icon as the notification small icon.
Thank you!
```javascript
[](https://www.paypal.com/cgi-bin/webscr?cmd=_s-xclick&hosted_button_id=L3HKQCD9UA35A "Donate once-off to this project using Paypal")
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`.
