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

Note Scheduling multiple notifications at once only works reliable when calling schedule([]) with an array of all notifications.

Each local 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 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 local 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	The interval at which to reschedule the local notification. That can be a value of second, minute, hour, day, week, month or year - Default: 0 (which means that the system triggers the local notification once)
at, firstAt	Date or Number	The date and time when the system should deliver the local notification. If the specified value is nil or is a date in the past, the local 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 local 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 icon that is shown in the ticker and notification - Default: res://icon
smallIcon	Uri	Uri of the resource (only res://) to use in the notification layouts. Different classes of devices may return different sizes - Default: res://ic_popup_reminder
every	String or Number	The interval at which to reschedule the local 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 local notification once)
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

Scheduling multiple notifications at once only works reliable when calling schedule([]) with an array of all notifications.

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 Delayed

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 Repeatedly

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 local notification has been scheduled and later triggered. The schedule event will be fired for each local notification if you call schedule(). The trigger event occurs when the local 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);
});

Permission

To use of local notifications on iOS 8 and above the user has to grant the permission before the app is allowed to schedule them. When trying to schedule a local notification for the first time, a special system dialog will popup.

Note that iOS will only prompt the user only once! Later the user needs to configure the settings manually.

Further Informations

Register for the click event to get informed on what local 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 local notification after it was scheduled. You can update every property except the id. Updating multiple local notification at once equivalent to scheduling multiple local notifications is also supported.

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