Cordova LocalNotification-Plugin

A bunch of local notification plugins for Cordova 3.x.x

by Sebastián Katzer (github.com/katzer)

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)

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

# stable version:
cordova plugin add de.appplant.cordova.plugin.local-notification

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 this exact version:

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

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.

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:

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.
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
    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)
});

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.

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

cancelAll()

The method cancels all notifications which were previously added by the application.

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

onadd() | ontrigger() | onclick() | oncancel()

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

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

Note: The ontrigger callback is only invoked in background if the app is not suspended!

getDefaults()

Gives an overview about all available notification properties for the platform and their default values. The function returns an object.

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

setDefaults ()

Overrides the default properties. The function takes an object as argument.

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

Examples

Will fire 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, // is converted to a string
    title:   'Reminder',
    message: 'Dont forget to buy some flowers.',
    repeat:  'weekly',
    date:    _60_seconds_from_now
});

Pop's up immediately

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

Plays no sound if the notification pop's up

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

Callback registration

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

Pass data through the notification

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 for autoCancel

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.

/**
 * 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' });

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.

/**
 * 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' });

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.

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

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

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.