cordova-plugin-local-notifications

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.
They are scheduled by an application and delivered on the same device.

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.
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 based mobile applications to access the specific API on each platform.

Supported Platforms

• 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.

Dependencies

Cordova will check all dependencies and install them if they are missing.

• org.apache.cordova.device (since v0.6.0)

Installation

The plugin can either be installed into the local development environment or cloud based through PhoneGap Build.

Adding the Plugin to your project

Through the Command-line Interface:

# ~~ from master ~~
cordova plugin add https://github.com/katzer/cordova-plugin-local-notifications.git && cordova prepare

# ~~ stable version ~~
cordova plugin add de.appplant.cordova.plugin.local-notification && cordova prepare

Removing the Plugin from your project

Through the Command-line Interface:

cordova plugin rm de.appplant.cordova.plugin.local-notification

PhoneGap Build

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 an specific version:

<gap:plugin name="de.appplant.cordova.plugin.local-notification" version="0.7.2" />

More informations can be found here.

Release Notes

Version 0.7.3 (not yet released)

• [bugfix:] cancel callbacks have not been fired after all notifications have been canceled on iOS.
• [change:] The oncancel callback will be called at last if autoCancel is set to true (iOS).
• [bugfix:] Callbacks for non-repeating notifications were not called if they were not created in the current app instance on iOS.
• [enhancement:] Added 'secondly' and 'minutely' as new repeat time aliases.
• [bugfix:] sound:null didnt work for Android. The default sound was played.
• [feature:] New interface isScheduled to check wether a notification with an ID is pending.
• [feature:] New interface getScheduledIds to retrieve a list with all currently pending notifications.
• [enhancement:] Support for bigview style notifications for Android devices.
• [bugfix:] Sound didnt play properly on iOS/Android.
• [bugfix:] click event on iOS wasn't fired if app was not running.

Version 0.7.2 (09.02.2014)

• [enhancement:] Avoid blocking the main thread (on Android) (dpogue).
• [bugfix:] onadd was called each time after a repeating message was triggered (Android)
• [change:] Reset badge with cancelAll.
• [bugfix:] onclick instead of ontrigger was called on "slow" iOS devices.

Version 0.7.1 (31.01.2014)

• [bugfix:] ongoing attribute was ignored.
• [bugfix:] oncancel wasnt fired if autoCancel was set to true.
• [bugfix:] App throwed an error at restart if a callback was registered.

Version 0.7.0 (22.01.2014)

Note: The new way of callback registration will be not compatible with previous versions! See #62

• [feature:] Added new callback registration interface and new callback types.
• [feature:] Added the ability to override notifications default properties.
• [bugfix:] Fixed build failure if iOS/MacOS/Xcode were to old (#68).
• [change] The message and not the title will be used as the ticker text.

Version 0.7.0beta1 (17.01.2014)

• [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.
• [enhancement:] Repeat with custom intervals on Android.
• [change:] Callbacks are called with the ID as a number and not as a string.
• [enhancement:] The background callback on Android is called, even the app is not running when the notification is tapped.
• [enhancement:] Notifications are repeated more precisely.
• [feature:] Added json property to pass custom data through the notification.
• [enhancement:] Added Android specific property smallImage.
• [enhancement:] Added Android specific property ongoing.
• [enhancement:] Setting launchMode to singleInstance isn't necessary anymore.

Version 0.6.3 (12.12.2013)

• [bugfix:] Black screen on Android.
• [bugfix:] App throws an error on reboot on Android.
• [enhancement:] Calling cancel on Android with an invalid String as ID does not throw an error anymore.

Version 0.6.2 (04.12.2013)

• Release under the Apache 2.0 license.

Version 0.6.1 (04.12.2013)

• 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_COMPLETEDpermission 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.

Version 0.6.0 (16.11.2013)

• 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.

Version 0.4.0 (06.10.2013)

• Added Android support
  Based on the LocalNotifications Android plugin made by Daniël (dvtoever)

Version 0.2.0 (11.08.2013)

• Added iOS support
  Based on the LocalNotifications iOS plugin made by Rodrigo Moyle

Using the plugin

The plugin creates the object window.plugin.notification.local with the following methods:

Plugin initialization

The plugin and its methods are not available before the deviceready event has been fired.

document.addEventListener('deviceready', function () {
    // window.plugin.notification.local is now available
}, false);

Schedule local notifications

Local notifications can be scheduled through the notification.local.add interface.
The method takes a hash as an argument to specify the notification's properties and returns the ID for the notification.
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 event of how a listener can be registered to be notified when a local notification has been scheduled.
• See the ontrigger event of how a listener can be registered to be notified when a local notification has been triggered.
• See the 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 of which other properties are available too.
• See getDefaults of which property values are used by default and setDefaults of how to override them.

• See the examples of how to schedule local notifications.

  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,  // 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 canceled when the user clicks it
  ongoing:    Boolean, // Prevent clearing of notification (Android only)
  });
  

Cancel scheduled local notifications

Local notifications can be canceled through the notification.local.cancel interface.
Note that only local notifications with an ID can be canceled.

Further informations

• See the oncancel event of how a listener can be registered to be notified when a local notification has been canceled.

• See getScheduledIds of how to retrieve a list of IDs of all scheduled local notifications.

  window.plugin.notification.local.cancel(ID);
  

Cancel all scheduled local notifications

All local notifications can be canceled through the notification.local.cancelAll interface.
The method cancels all local notifications even if they have no ID.

Further informations

• See the oncancel event of how a listener can be registered to be notified when a local notification has been canceled.

  window.plugin.notification.local.cancelAll();
  

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.
The method takes the ID of the local notification as an argument and a callback function to be called with the result.

Further informations

• See getScheduledIds of how to retrieve a list of IDs of all scheduled local notifications.

  window.plugin.notification.local.isScheduled(id, function (isScheduled) {
  // console.log('Notification with ID ' + id + ' is scheduled: ' + isScheduled);
  });
  

Retrieve the IDs from all currently scheduled local notifications

To retrieve the IDs from all currently scheduled local notifications, the notification.local.isScheduled interface can be used.
The method takes a callback function to be called with the result as an array of IDs.

window.plugin.notification.local.getScheduledIds( function (scheduledIds) {
    // alert('Scheduled IDs: ' + scheduledIds.join(' ,'));
});

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.
The method returns an object of values for all available local notification properties on the platform.

Further informations

• See setDefaults of how to override the default values.

  window.plugin.notification.local.getDefaults(); // => Object
  

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.
The method takes an object as argument.

Further informations

• See the add interface and the platform specific properties to get an overview about all available local notification properties.

• See the example of how to override default values.

  window.plugin.notification.local.setDefaults(Object);
  

Get notified when a local notification has been scheduled

The notification.local.onadd interface can be used to get notified when a local notification has been scheduled.

The listener has to be a function and takes the following arguments:

• id: The ID of the notification
• state: Either background or foreground
• json: A custom (JSON encoded) string

Note: The event is only being invoked in background if the app is not suspended!

Further informations

• See the ontrigger event of how a listener can be registered to be notified when a local notification has been triggered.

  window.plugin.notification.local.onadd = function (id, state, json) {};
  

Get notified when a local notification has been triggered

The notification.local.ontrigger interface can be used to get notified when a local notification has been triggered.

The listener has to be a function and takes the following arguments:

• id: The ID of the notification
• state: Either background or foreground
• json: A custom (JSON encoded) string

Note: The event is only being invoked in background if the app is running and is not suspended!

Further informations

• See the onclick event of how a listener can be registered to be notified when the user has been clicked on a local notification.

  window.plugin.notification.local.ontrigger = function (id, state, json) {};
  

Get notified when the user has been clicked on a local notification

The notification.local.onclick interface can be used to get notified when the user has been clicked on a local notification.

The listener has to be a function and takes the following arguments:

• id: The ID of the notification
• state: Either background or foreground
• json: A custom (JSON encoded) string

Note: The event is only being invoked in background if the app is not suspended!

Further informations

• The autoCancel property can be used to either automatically cancel the local notification or not after it has been clicked by the user.

  window.plugin.notification.local.onclick = function (id, state, json) {};
  

Get notified when a local notification has been canceled

The notification.local.oncancel interface can be used to get notified when a local notification has been canceled.

The listener has to be a function and takes the following arguments:

• id: The ID of the notification
• state: Either background or foreground
• json: A custom (JSON encoded) string

Note: The event is not being invoked if the local notification has been cleared in the notification center.

Further informations

• The autoCancel property can be used to either automatically cancel the local notification or not after it has been clicked by the user.

• See cancel and cancelAll of how to cancel local notifications manually.

  window.plugin.notification.local.oncancel = function (id, state, json) {};
  

Examples

Scheduling a repeating local notification in the future

The following example shows how to schedule a local notification which will be triggered every week on this day, 60 seconds from now.

var now                  = new Date().getTime(),
    _60_seconds_from_now = new Date(now + 60*1000);

window.plugin.notification.local.add({
    id:      1,
    title:   'Reminder',
    message: 'Dont forget to buy some flowers.',
    repeat:  'weekly',
    date:    _60_seconds_from_now
});

Scheduling an immediately triggered local notification

The example below shows how to schedule a local notification which will be triggered immediatly.

window.plugin.notification.local.add({ message: 'Great app!' });

Schedule a silent local notification

By default the system sound for local notifications will be used. To turn off any sound the sound property has to be set to NULL.

window.plugin.notification.local.add({ sound: null });

Assign user data to the notification

If needed local notifications can be scheduled with any user data. That data can be accessed on each event listener. But cannot be modified later.

window.plugin.notification.local.add({
    id:         1,
    message:    'I love BlackBerry!',
    json:       JSON.stringify({ test: 123 })
});

window.plugin.notification.local.onclick = function (id, state, json) {
    console.log(id, JSON.parse(json).test);
}

Change the default value of local notification properties

The following example shows how to override the default value of the autoCancel property.

window.plugin.notification.local.setDefaults({ autoCancel: true });

Platform specifics

Small and large icons on Android

By default all notifications will display the app icon. But an specific icon can be defined through the icon and smallIcon properties.

/**
 * 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({ smallIcon: 'ic_dialog_email' });

Notification sound on Android

The sound must be a absolute or relative Uri pointing to the sound file. The default sound is RingtoneManager.TYPE_NOTIFICATION.

Note: Local sound files must be placed into the res-folder and not into the assets-folder.

/**
 * Plays the `beep.mp3` which has to be located in the res folder
 */
window.plugin.notification.local.add({ sound: 'android.resource://' + package_name + '/raw/beep' });

/**
 * Plays a remote sound
 */
window.plugin.notification.local.add({ sound: 'http://remotedomain/beep.mp3' });

/**
 * Plays a sound file which has to be located in the android_assets folder
 */
window.plugin.notification.local.add({ sound: '/www/audio/beep.mp3' });

/**
 * Plays the `RingtoneManager.TYPE_ALARM` sound
 */
window.plugin.notification.local.add({ sound: 'TYPE_ALARM' });

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.
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.

/**
 * Plays the `beep.mp3` which has to be located in the root folder of the project
 */
window.plugin.notification.local.add({ sound: 'beep.caf' });

/**
 * Plays the `beep.mp3` which has to be located in the www folder
 */
window.plugin.notification.local.add({ sound: 'www/sounds/beep.caf' });

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.

Note: An image must be defined as a relative or absolute URI. They can be restored to the default ones by canceling the notification.

/**
 * Displays the application icon as the livetile's background image
 */
window.plugin.notification.local.add({ image: 'appdata:ApplicationIcon.png' })

Custom repeating interval on Android

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

Local Notification limit on iOS

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.

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

Black screen (or app restarts) on Android after a notification was clicked

The launch mode for the main activity has to be set to singleInstance

<activity ... android:launchMode="singleInstance" ... />

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.

© 2013-2014 appPlant UG, Inc. All rights reserved