04. Scheduling

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.

Semantic

Local notifications are mostly time-based and are scheduled by the application and delivered on the same device. If triggered they will be visible in the notification center and present to the user.

Interface

The plugin allows to schedule a single or multiple notifications at once through schedule(). These notifications can be time-based or trigger immediately.

The schedule interface takes a hash as an argument to specify the notification's properties or an array of hashes. and optionally a callback function and a scope as second and third argument. The default scope does point to the plugin.

Each notification requires a numerical ID. If not provided that ID will be 0. Scheduling a local notification will replace an earlier one with the same ID.

The following table gives an overview about all available notification properties. Each property is optional and does have its (platform-specific) default value.

Property	Type	Description
id	Number	A unique identifier required to clear, cancel, update or retrieve the notification in the future - Default: 0
title	String	First row of the notification - Default: Empty string (iOS) or the app name (Android)
text	String	Second row of the notification - Default: Empty string
every	String or Number	The interval at which to reschedule the notification. That can be a value of minutes or one of second, minute, hour, day, week, month or year - Default: 0 (which means that the system triggers the notification once)
at, firstAt	Date or Number	The date and time when the system should deliver the notification. If the specified value is nil or is a date in the past, the notification is delivered immediately. - Default: now ~ new Date()
badge	Number	The number currently set as the badge of the app icon in Springboard (iOS) or at the right-hand side of the notification (Android) - Default: 0 (which means don't show a number)
sound	Uri	Uri of the file containing the sound to play when an alert is displayed - Default: res://platform_default
data	String	Arbitrary data, objects will be encoded to JSON string - Default: null

Android provides some additional properties as listet below.

Property	Type	Description
icon	Uri	Uri of the resource icon that is shown in the ticker and notification - Default: res://ic_popup_reminder
smallIcon	Uri	Uri of the resource icon to use in the notification layouts. Different classes of devices may return different sizes - Default: res://ic_popup_reminder
ongoing	Boolean	Ongoing notifications differ from regular notifications in the following ways: - They are sorted above the regular notifications in the notification panel - They do not have an 'X' close button, and are not affected by the "Clear all" button - Default: false
led	String	ARGB value that you would like the LED on the device to blink - Default: FFFFFF

Schedule Single

cordova.plugins.notification.local.schedule({
    id: 1,
    text: "Single Notification",
    sound: isAndroid ? 'file://sound.mp3' : 'file://beep.caf',
    data: { secret:key }
});

Schedule Multiple

cordova.plugins.notification.local.schedule([{
    id: 1,
    text: "Multi Notification 1",
    sound: isAndroid ? 'file://sound.mp3' : 'file://beep.caf',
    data: { secret:key }
},{
    id: 2,
    title: "Local Notification Example",
    text: "Multi Notification 2",
    icon: "http://sciactive.com/pnotify/includes/github-icon.png"
}]);

Schedule Repeatedly

var now             = new Date().getTime(),
    _5_sec_from_now = new Date(now + 5*1000);

cordova.plugins.notification.local.schedule({
    text: "Delayed Notification",
    at: _5_sec_from_now,
    led: "FF0000",
    sound: null
});

Schedule Delayed

cordova.plugins.notification.local.schedule({
    text: "Delayed Notification",
    firstAt: monday,
    every: "day",
    icon: "file://img/logo.png"
}, callback);

Events

There are two event types to get informed when a notification has been scheduled and later triggered. The schedule event will be fired for each notification if you call schedule(). The trigger event occurs when the notification has reached it's trigger date and has been added to the notification center.

schedule Event

cordova.plugins.notification.local.on("schedule", function(notification) {
    alert("scheduled: " + notification.id);
});

trigger Event

cordova.plugins.notification.local.on("trigger", function(notification) {
    alert("triggered: " + notification.id);
});

Further Informations

Register for the click event to get informed on what notification the user has taped. The event will also get fired after launch when the app was not running.

cordova.plugins.notification.local.on("click", function(notification) {
    alert("clicked: " + notification.id);
});

Use update() to update a notification after it was scheduled. You can update every property except the id. Updating multiple notification at once equivalent to scheduling multiple notifications is also supported.

cordova.plugins.notification.local.update({
    id: 1,
    title: "Updated Notification"
});