cordova-plugin-local-notification

SAMPLE APP :point_right:

A notification is a message you display to the user outside of your app's normal UI. When you tell the system to issue a notification, it first appears as an icon in the notification area. To see the details of the notification, the user opens the notification drawer. Both the notification area and the notification drawer are system-controlled areas that the user can view at any time.

Notification components

• Header area
• Content area
• Action area

How notifications may be noticed

• Showing a status bar icon
• Appearing on the lock screen
• Playing a sound or vibrating
• Peeking onto the current screen
• Blinking the device's LED

Supported platforms

• Android 7.0+
• iOS 10+

Important Notice

Please make sure that you always read the tagged README for the version you're using.

Please report bugs or missing features.

Lacking features

Android

• Channels are not configurable. A default channel will be created with IMPORTANCE_DEFAULT, the id default-channel-id and the name Default channel. The name ist not translatable.

Basics

The plugin creates the object cordova.plugins.notification.local and is accessible after deviceready has been fired.

cordova.plugins.notification.local.schedule({
    title: 'My first notification',
    text: 'Thats pretty easy...',
    foreground: true
});

The plugin allows to schedule multiple notifications at once.

cordova.plugins.notification.local.schedule([
    { id: 1, title: 'My first notification' },
    { id: 2, title: 'My first notification' }
]);

Properties

A notification does have a set of configurable properties.

Not all of them are supported across all platforms.

The table is not complete regarding the support.

Property	Android	iOS	Comment
actions
attachments
autoClear
badge
channel	x	-	Don't use it, it is not functional. Since Android 8: Channel-ID of the chanel. In the future it will be renamed to channelId
clock
color
data
defaults
foreground
group
groupSummary
icon
iconType
id
launch
led
lockscreen
mediaSession
number
priority
progressBar	x	-	Natively not supported by iOS, see Stackoverflow
silent
smallIcon
sound	(x)	(x)	Property available but not useable. Cannot used to play a sound file. In Android it's only possible up to Android 7.1. Since Android 8, the channels take precedence and a channel would have to be created with a sound file, but this is not implemented yet. In iOS it would be possible, but must be implemented too.
sticky
summary
text
timeoutAfter
title
trigger
vibrate
wakeup

For their default values see:

cordova.plugins.notification.local.getDefaults();

To change some default values:

cordova.plugins.notification.local.setDefaults({
    led: { color: '#FF00FF', on: 500, off: 500 },
    vibrate: false
});

Actions

The plugin knows two types of actions: button and input.

cordova.plugins.notification.local.schedule({
    title: 'The big survey',
    text: 'Are you a fan of RB Leipzig?',
    attachments: ['file://img/rb-leipzig.jpg'],
    actions: [
        { id: 'yes', title: 'Yes' },
        { id: 'no',  title: 'No' }
    ]
});

    

Input

cordova.plugins.notification.local.schedule({
    title: 'Justin Rhyss',
    text: 'Do you want to go see a movie tonight?',
    actions: [{
        id: 'reply',
        type: 'input',
        title: 'Reply',
        emptyText: 'Type message',
    }, ... ]
});

It is recommended to pre-define action groups rather then specifying them with each new notification of the same type.

cordova.plugins.notification.local.addActions('yes-no', [
    { id: 'yes', title: 'Yes' },
    { id: 'no',  title: 'No'  }
]);

Once you have defined an action group, you can reference it when scheduling notifications:

cordova.plugins.notification.local.schedule({
    title: 'Justin Rhyss',
    text: 'Do you want to go see a movie tonight?',
    actions: 'yes-no'
});

Properties

Actions do have a set of configurable properties. Not all of them are supported across all platforms.

Property	Type	Android	iOS
id	button+input	x	x
title	button+input	x	x
launch	button+input	x	x
ui	button+input		x
needsAuth	button+input		x
icon	button+input	x
emptyText	input	x	x
submitTitle	input		x
editable	input	x
choices	input	x
defaultValue	input

Triggers

Notifications may trigger immediately or depend on calendar or location.

To trigger at a fix date:

cordova.plugins.notification.local.schedule({
    title: 'Design team meeting',
    text: '3:00 - 4:00 PM',
    trigger: { at: new Date(2017, 10, 27, 15) }
});

Or relative from now:

cordova.plugins.notification.local.schedule({
    title: 'Design team meeting',
    trigger: { in: 1, unit: 'hour' }
});

Repeating

Repeat relative from now:

cordova.plugins.notification.local.schedule({
    title: 'Design team meeting',
    trigger: { every: 'day', count: 5 }
});

Or trigger every time the date matches:

cordova.plugins.notification.local.schedule({
    title: 'Happy Birthday!!!',
    trigger: { every: { month: 10, day: 27, hour: 9, minute: 0 } }
});

Location based

To trigger when the user enters a region:

cordova.plugins.notification.local.schedule({
    title: 'Welcome to our office',
    trigger: {
        type: 'location',
        center: [x, y],
        radius: 15,
        notifyOnEntry: true
    }
});

Properties

The properties depend on the trigger type. Not all of them are supported across all platforms.

Type	Property	Type	Value	Android	iOS
Fix
	at	Date		x	x
Timespan
	in	Int		x	x
	unit	String	second	x	x
	unit	String	minute	x	x
	unit	String	hour	x	x
	unit	String	day	x	x
	unit	String	week	x	x
	unit	String	month	x	x
	unit	String	quarter	x	x
	unit	String	year	x	x
Repeat
	count	Int		x
	every	String	minute	x	x
	every	String	hour	x	x
	every	String	day	x	x
	every	String	week	x	x
	every	String	month	x	x
	every	String	quarter	x
	every	String	year	x	x
	before	Date		x
	firstAt	Date		x
Match
	count	Int		x
	every	Object	minute	x	x
	every	Object	hour	x	x
	every	Object	day	x	x
	every	Object	weekday	x	x
	every	Object	weekdayOrdinal		x
	every	Object	week		x
	every	Object	weekOfMonth	x	x
	every	Object	month	x	x
	every	Object	quarter		x
	every	Object	year	x	x
	before	Date		x
	after	Date		x
Location
	center	Array	[lat, long]		x
	radius	Int			x
	notifyOnEntry	Boolean			x
	notifyOnExit	Boolean			x
	single	Boolean			x

Progress

Notifications can include an animated progress indicator that shows users the status of an ongoing operation. Android only.

cordova.plugins.notification.local.schedule({
    title: 'Sync in progress',
    text: 'Copied 2 of 10 files',
    progressBar: { value: 20 }
});

Patterns

Split the text by line breaks if the message comes from a single person and just too long to show in a single line.

cordova.plugins.notification.local.schedule({
    title: 'The Big Meeting',
    text: '4:15 - 5:15 PM\nBig Conference Room',
    smallIcon: 'res://calendar',
    icon: 'https://encrypted-tbn0.gstatic.com/images?q=tbn:ANd9GcTzfXKe6Yfjr6rCtR6cMPJB8CqMAYWECDtDqH-eMnerHHuXv9egrw'
});

Summarizing

Instead of displaying multiple notifications, you can create one notification that summarizes them all.

cordova.plugins.notification.local.schedule({
    id: 15,
    title: 'Chat with Irish',
    icon: 'http://climberindonesia.com/assets/icon/ionicons-2.0.1/png/512/android-chat.png',
    text: [
        { message: 'I miss you' },
        { person: 'Irish', message: 'I miss you more!' },
        { message: 'I always miss you more by 10%' }
    ]
});

To add a new message to the existing chat:

cordova.plugins.notification.local.update({
    id: 15,
    text: [{ person: 'Irish', message: 'Bye bye' }]
});

Grouping

Your app can present multiple notifications as a single group:

• A parent notification displays a summary of its child notifications.
• The child notifications are presented without duplicate header information.

cordova.plugins.notification.local.schedule([
    { id: 0, title: 'Design team meeting', ... },
    { id: 1, summary: '[e-mail]', group: 'email', groupSummary: true },
    { id: 2, title: 'Please take all my money', ... group: 'email' },
    { id: 3, title: 'A question regarding this plugin', ... group: 'email' },
    { id: 4, title: 'Wellcome back home', ... group: 'email' }
]);

Permissions

Each platform may require the user to grant permissions first before the app is allowed to schedule notifications.

cordova.plugins.notification.local.hasPermission(function (granted) { ... });

If requesting via plug-in, a system dialog does pop up for the first time. Later its only possible to tweak the settings through the system settings.

cordova.plugins.notification.local.requestPermission(function (granted) { ... });

Checking the permissions is done automatically, however it's possible to skip that.

cordova.plugins.notification.local.schedule(toast, callback, scope, { skipPermission: true });

Events

The following events are supported: add, trigger, click, clear, cancel, update, clearall and cancelall.

cordova.plugins.notification.local.on(event, callback, scope);

To unsubscribe from events:

cordova.plugins.notification.local.un(event, callback, scope);

Note: You have to provide the exact same callback to cordova.plugins.notification.local.un as you provided to cordova.plugins.notification.local.on to make unsubscribing work. Hence you should define your callback as a separate function, not inline. If you want to use this inside of your callback, you also have to provide this as scope to cordova.plugins.notification.local.on.

Custom

The plugin also fires events specified by actions.

cordova.plugins.notification.local.schedule({
    title: 'Do you want to go see a movie tonight?',
    actions: [{ id: 'yes', title: 'Yes' }]
});

The name of the event is the id of the action.

cordova.plugins.notification.local.on('yes', function (notification, eopts) { ... });

Fire manually

Not an official interface, however its possible to manually fire events.

cordova.plugins.notification.local.core.fireEvent(event, args);

Launch Details

Check the launchDetails to find out if the app was launched by clicking on a notification.

document.addEventListener('deviceready', function () {
    console.log(cordova.plugins.notification.local.launchDetails);
}, false);

It might be possible that the underlying framework like Ionic is not compatible with the launch process defined by cordova. With the result that the plugin fires the click event on app start before the app is able to listen for the events.

Therefore its possible to fire the queued events manually by defining a global variable.

window.skipLocalNotificationReady = true

Once the app and Ionic is ready, you can fire the queued events manually.

cordova.plugins.notification.local.fireQueuedEvents();

Methods

All methods work asynchronous and accept callback methods. See the sample app for how to use them.

Method	Method	Method	Method	Method	Method
schedule	cancelAll	isTriggered	get	removeActions	un
update	hasPermission	getType	getAll	hasActions	fireQueuedEvents
clear	requestPermission	getIds	getScheduled	getDefaults
clearAll	isPresent	getScheduledIds	getTriggered	setDefaults
cancel	isScheduled	getTriggeredIds	addActions	on

Installation

The plugin can be installed via Cordova-CLI and is publicly available on NPM.

Execute from the projects root folder:

$ cordova plugin add cordova-plugin-local-notification

Or install a specific version:

$ cordova plugin add cordova-plugin-local-notification@VERSION

Or install the latest head version:

$ cordova plugin add https://github.com/katzer/cordova-plugin-local-notifications.git

Or install from local source:

$ cordova plugin add <path> --nofetch --nosave --link

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.

Made with :yum: from Leipzig

© 2013 appPlant GmbH

Changelog

Version 1.0.0 (17.08.2024)

This Release contains mainly changes and fixes for the Android platform.

• Make Plugin compatible with Android 12-14
• Support Android X
• Minimum supported Android version is 7.0 (SDK 24). The target SDK is increased to 34 (Android 14).
• Remove obsolete Windows platform
• Fix crash with target Android 12 (SDK 31) which occured because of a pendingIntent change and not using PendingIntent.FLAG_IMMUTABLE
• Fix click notifications in Android 12
• Declare SCHEDULE_EXACT_ALARM permission, which is necessary for scheduling exact alarms since Android 12 (API 31). It is only pre-granted on Android 12. On Android 13 and newer, the user must grant the permission in the "Alarms & Reminders"-setting, if you still want exact alarms. If the permission is not granted, notifications will be scheduled inexact, which is still ok for the normal case.
• Request POST_NOTIFICATIONS permission in Android 13 (API 33)
• New methods for exact alarms:
  • canScheduleExactAlarms(successCallback, scope) - Android only. Checks if the user has enabled the "Alarms & Reminders"-setting. If not, the notificiatons will be scheduled inexact, which is still ok and will only be delayed by some minutes.
    • On Android 12 the permission is granted by default
    • On Android 13 and newer, the permission is not granted by default and have to be explicitly enabled by the user.
    • On Android 11 and older, this method will always return true in the successCallback.
  • openAlarmSettings(successCallback, scope) - Android only. Opens the "Alarms & Reminders"-settings as an Activity when running on Android 12 (SDK 31) or later, where the user can enable exact alarms. On Android older then 12, it will just call the successCallback, without doing anything. This method will not wait for the user to be returned back to the app. For this, the resume-event can be used. The callback will just return OK, after starting the activity.
    • If the user grants permission, already inexact scheduled notifications will automatically be rescheduled as exact alarms, but only if the app is still available in background.
    • If exact alarms were alreay granted and the user revokes it, the app will be killed and all scheduled notifications will be canceld. The app have to schedule the notifications as inexact alarms again, when the app is opened the next time, see https://developer.android.com/develop/background-work/services/alarms/schedule#using-schedule-exact-permission.
  • openNotificationSettings(successCallback, scope) - Opens the notifications settings of the app on Android 8 and newer. This method will not wait for the user to be returned back to the app. For this, the resume-event can be used.
    • On Android, the callback will just return "OK", after starting the activity.
    • On Android older then 8, it opens the app details.
    • On iOS it's not possible to open the notification settings, it will open the app settings.
• Support sender image by new option personIcon
• Initialize the sender as empty String instead of "Me" (PR #1781)
• Reuse existing messages when using MessagingStyle (PR #1781). With this fix, users won't have to cache the messages in their Javascript code, the plugin will automatically check if there is an active notification with that ID and append the new messages to the existing ones. This will only be done when using MessagingStyle, which will be used, if the option text is filled with an Array instead of a String.
• Added count of messages in a notification, wenn using Array for text. (PR #1781)
  • Added option titleCount to modify the count text of messages in a notification. The placeholder %n% can be used for inserting the messages count. If nothing is set, the text (%n%) will be used.
• Use app name as a tag for the notify call (PR #1781)
• Use correct authority name (PR #1853)
• Replace compile() with implementation() in localnotification.gradle, because starting on Gradle 7.0 the compile-method is removed and will produce errors, like Could not find method compile() for arguments...
• Raise minimum Version for Cordova dependencies
  • Cordova to 12
  • cordova-android to 13

A lot of changes were adopted from moodlemobile. Thanks for the work!