A bunch of local notification plugins for Cordova 3.x.x
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.
by Sebastián Katzer ([github.com/katzer](https://github.com/katzer))
### How they appear to the user
Users see notifications in the following ways:
- Displaying an alert or banner
- Badging the app’s icon
- Playing a sound
### Examples of Notification Usage
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 an platform independent javascript interface for [Cordova][cordova] based mobile applications to access the specific API on each platform.
## Supported Platforms
-**iOS**<br>
See [Local and Push Notification Programming Guide](http://developer.apple.com/library/ios/documentation/NetworkingInternet/Conceptual/RemoteNotificationsPG/Chapters/WhatAreRemoteNotif.html) for detailed informations and screenshots.
See [Local and Push Notification Programming Guide][ios_notification_guide] for detailed informations and screenshots.
-**Android***(SDK >=11)*<br>
See [Notification Guide](http://developer.android.com/guide/topics/ui/notifiers/notifications.html) for detailed informations and screenshots.
See [Notification Guide][android_notification_guide] for detailed informations and screenshots.
-**WP8**<br>
See [Local notifications for Windows Phone](http://msdn.microsoft.com/en-us/library/windowsphone/develop/jj207047.aspx) for detailed informations and screenshots.
See [Local notifications for Windows Phone][wp8_notification_guide] for detailed informations and screenshots.
<br>*Windows Phone 8.0 has no notification center. Instead local notifications are realized through live tiles updates.*
## Dependencies
Cordova will check all dependencies and install them if they are missing.
// window.plugin.notification.local is now available
},false);
```
### add()
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.<br>
All properties are optional. If no date object is given, the notification will pop-up immediately.
### 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 the previously one with the same ID.
All properties are optional. If no date object is given, the notification pops-up immediately.
**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.
#### Further informations
- See the [onadd][onadd] event of how a listener can be registered to be notified when a local notification has been scheduled.
- See the [ontrigger][ontrigger] event of how a listener can be registered to be notified when a local notification has been triggered.
- See the [onclick][onclick] event of how a listener can be registered to be notified when the user has been clicked on a local notification.
- See the [platform specific properties][platform_specific_properties] of which other properties are available too.
- See [getDefaults][getdefaults] of which property values are used by default and [setDefaults][setdefaults] of how to override them.
- See the [examples][examples] of how to schedule local notifications.
ongoing:Boolean,// Prevent clearing of notification (Android only)
});
```
**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.
### cancel()
The method cancels a notification which was previously added. It takes the ID of the notification as an argument.
### Cancel scheduled local notifications
Local notifications can be canceled through the `notification.local.cancel` interface.<br>
Note that only local notifications with an ID can be canceled.
#### Further informations
- See the [oncancel][oncancel] event of how a listener can be registered to be notified when a local notification has been canceled.
- See [getScheduledIds][getscheduledids] of how to retrieve a list of IDs of all scheduled local notifications.
```javascript
window.plugin.notification.local.cancel(String);
window.plugin.notification.local.cancel(ID);
```
### cancelAll()
The method cancels all notifications which were previously added by the application.
### Cancel all scheduled local notifications
All local notifications can be canceled through the `notification.local.cancelAll` interface.<br>
The method cancels all local notifications even if they have no ID.
#### Further informations
- See the [oncancel][oncancel] event of how a listener can be registered to be notified when a local notification has been canceled.
There are 4 different callback types available. For each of them one listener can be specified. The listener has to be a function and takes the following arguments:
- event: The Name of the event
- id: The ID of the notification
- json: A custom (JSON) string
### Check wether 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.
Overrides the default properties. The function takes an object as argument.
### 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 informations
- 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] of how to override default values.
**Note:** Local sound files must be placed into the res-folder and not into the assets-folder.
### Notification sound on iOS
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:** The right to play notification sounds in the notification center settings has to be granted.<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 has to be located in the root folder of the project
**Note:** The right to play notification sounds in the notification center settings has to be granted.<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.
### LiveTile background images on WP8
LiveTile's have the ability to display images for different sizes. These images can be defined through the `smallImage`, `image` and `wideImage` properties.<br>
An image must be defined as a relative or absolute URI.
LiveTile's 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 the default ones by canceling the notification.
```javascript
/**
* Displays the application icon as the livetile's background image
Each application on a device is limited to 64 scheduled local notifications. 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 aren't fired.
### No sound is played on iOS 7
The right to play notification sounds in the notification center settings has to be granted.
...
...
@@ -385,3 +521,29 @@ The launch mode for the main activity has to be set to `singleInstance`
## License
This software is released under the [Apache 2.0 License](http://opensource.org/licenses/Apache-2.0).
