Version 1.2.3

Stable release:

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+ (minimum version by cordova-android 13.0.0) with a minimum WebView Version 60 (Android 8 is shipped with a WebView version 58 and must be updated with Google Play Store before)
• iOS 11.3+ (minimum version by cordova-ios 7.0.0)

Installation

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

NPM

Execute from the projects root folder:

$ cordova plugin add cordova-plugin-local-notification

Install a specific version:

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

Git

Install the latest head version:

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

Install from a branch:

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

Install from a tag:

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

Install from a specific commit:

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

Local

Install from local source:

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

Upgrade Notice

Version 0.9.0-beta.3 (13.02.2018)

• Last version which supports cordova-android older than 13.0.0 and supports minimum cordova-android version 6.0.0 which is Android version 4.1
• Last version which supports the Windows platform

Version 1.0.0 (17.08.2024)

• Removed Windows platform
• Support for Android 12-14 and uses AndroidX
• Raised minimum cordova-androidversion from 6.0.0 to 13.0.0, which raised the minimum Android version from 4.1 SDK 16 to 7.0 SDK 24
• Raised minimum cordova-ios version from 4.3.0 to 7.0.0
• Raised minimum Cordova version from 3.6.0 to 12.0.0
• Raised minimum cordova-plugin-device version from 2.0.0 to 3.0.0

Updates in version 1.1.0 (23.12.2024)

• Proper handling of Android channels
• Properties were renamed for the Android platform, see Changed properties.

Android

The Default channel id was changed from default-channel-id to default_channel. If you upgrade to this version and schedule notifications, there will be two channels from then on, the old one and the new one. You can remove the old one with deleteChannel.

iOS

iOSForeground is true by default

Updates in version 1.1.1

Android

The property vibrate was renamed to androidChannelEnableVibration.

iOS

A notification will be always showed in the notification center like on Android. Happens also if iOSForeground is false.

Updates in Version 1.1.4

Android

Notifications with an old trigger.at date will be shown when you schedule them. Before they were ignored.

Updates in Version 1.1.8

• Notifications with trigger.at date more than 5 seconds in the past will be ignored. iOS did always ignore passed notifications.
• If no id of a notification is set, it will default to 1 instead of 0.

Basics

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

You can schedule a single notification as follows:

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

You have always to set an unique ID for every notification. The plugin does not automatically set an ID. If you do not set an ID, it will default to 1. If you reuse an ID of a previous scheduled notification, the previous one will be canceled.

The plugin allows to schedule multiple notifications at once:

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

Notification Limits

On each platform are limits about how much notifications can be scheduled:

• iOS: 64
• Android: 500

Repeating notifications count as 1 notification.

Properties

A notification does have a set of configurable properties. See all properties.

Permissions

On iOS and Android 13+ permissions must be requested from the user before notifications can be posted. This is done automatically, when scheduling a notification. If you want do it manually, you can use requestPermission. Please keep in mind, that the user can still change the permission later in the system. If you want to check, if you have still the permission to post notifications, use hasPermission.

On Android, the permissions must be requested since Android 13. In earlier versions no permissions must be granted.

Android specials

Notification channels

Since Android 8 notification channels must be created to post noitifications. A default channel will be created for you, if you do not create one. You can also create your own channel by createChannel or when scheduling a notification. For deleting a channel use deleteChannel.

Inexact alarms since Android 12

Since Android 12 alarms will be scheduled inexact by default. On Android 12 (API level 31) and higher, the system invokes the alarm within one hour of the supplied trigger time, unless any battery-saving restrictions are in effect such as battery saver or Doze. Most apps can schedule tasks and events using inexact alarms to complete several common use cases. If your app's core functionality depends on a precisely-timed alarm — such as for an alarm clock app or a calendar app — then it's OK to use an exact alarm instead.

See Schedule exact alarms, if you want use exact alarms.

See Android documentation for more information.

App hibernation / App unused

If your app runs on Android 12 and newer and the user doesn't interact with your app for 3 months, the system places your app in a hibernation state which will cancel all pending notifications and revokes permissions. When the user interacts with your app again, the app exits hibernation and the notifications will be re-scheduled. It doesn't count as app usage if the user dismisses a notification. If the app is hibernated, the user will get informed about it:

The documentation says that permissions are also revoked, but testing the hibernation behavior on an Android 15 emulator showed, that the app keeps the permission to post notifications.

Notes

• Android introduced this behavior in Android 11 and additionally backported this to Android 6 to 10 through the Google Play Store but only the permissions are revoked and not the pending notifications. Because permissions are only needed since Android 13, this does not affect this plugin. Since Android 12 notifications are also canceled besides revoking the permissions.
• You can manually test the hibernation behavior, see App hibernation > Manually invoke hibernation behavior.
• To see a complete list, what counts as app usage and what not, see App hibernation > App usage.
• 3 months are based on executing adb shell device_config get permissions \ auto_revoke_unused_threshold_millis2 which will return 7776000000 milliseconds on an Android 15 Emulator which are nearly 3 months (~2.96 months).

Manage App hibernation

You can get the status of the setting by calling getUnusedAppRestrictionsStatus. To redirect the user to the setting, call openManageUnusedAppRestrictions. Before opening the setting, you can inform the user about this behavior and explain which setting he has to deactivate. When opening the settings, the system will not scroll to the right entry and the setting is named differently on different Android versions:

Sample Android 12:

On other Android versions it is named differently:

Android 13/14:

Android 15:

Doze and Standby

Android has two power-saving features that extend battery life for users by managing how apps behave when a device isn't connected to a power source: Doze and App Standby. Doze reduces battery consumption by deferring background CPU and network activity for apps when the device is unused for long periods of time. App Standby defers background network activity for apps with no recent user activity.

To fire notifications when the device is in doze mode, you can schedule notifications with the property androidAllowWhileIdle.

App Standby does not affect you when showing a notification.

You can read everything about it in the Android documentatation.

Alarm rescheduling

App Update

Android removes all alarms when the app is updated. The plugin reschedules all alarms by a BroadcastReceiver listening to ACTION_MY_PACKAGE_REPLACED.

Device reboot

Android removes all alarms when the device reboots. The plugin reschedules all alarms by a BroadcastReceiver listening to ACTION_BOOT_COMPLETED, but only after the device has been unlocked.

User grants exact alarms

If you use SCHEDULE_EXACT_ALARM for scheduling exact alarms and the user permits the permission in the "Alarms & Reminders", inexact alarms will be rescheduled as exact alarms. This is done by a BroadcastReceiver listening to ACTION_SCHEDULE_EXACT_ALARM_PERMISSION_STATE_CHANGED. This action will not be called if the user revokes the permission. All exact alarms will be canceled then.

Android 15: Alarms get canceled on Force stop

Since Android 15 all pending alarms will get canceled if the user force stops an app, this is a change by Google, see https://developer.android.com/about/versions/15/behavior-changes-all#enhanced-stop-states. The alarms will be re-registered, if the user starts the app again. If the user clears the app from the app stack the alarms will not get canceled.

Keep in mind, that force stopping is only known by advised users and if they do it, they have a reason to do this and they should be aware, that the app will no longer function correctly as the System also states when clicking on Force stop by showing an alert with the message If you force stop an app, it may misbehave.

Actions

You can add actions to a notification, which can be a button or an input. Before you can use them you have to create an action group with some actions.

// Creates an action group with the id 'YES_NO_CATEGORY' and two actions.
cordova.plugins.notification.local.addActions('YES_NO_CATEGORY', [
    {
        id: 'YES_ACTION', // Action id
        title: 'Yes', // Action button title
        launch: true // Click on action will open the app
    },
    {
        id: 'NO_ACTION',
        title: 'No'
    }
]);

To see which properties can be set see Action properties.

By default a click on an action will not open the app. To launch the app when a notification was clicked, set launch: true.

Note for Android: If launch is not set and the app is killed, the event will be hold back in a background process of the app to wait for the next time the app starts, but could be lost, if the system kills the app background process.

If the type of an action is not set, it defaults to button.

After the action group is defined, you can assign it to a notification:

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

On iOS the actions are not visible by default. You have to long press on the notification to see them.

Action Input

Create an action group with an action input:

cordova.plugins.notification.local.addActions('REPLY_NO_CATEGORY', [
    {
        id: 'REPLY_ACTION',
        type: 'input',
        title: 'Reply',
        emptyText: 'Type message',
        launch: true // Will open the app
    },
    {
        id: 'NO_ACTION',
        title: 'No'
    }
]);

To see which properties can be set for an action input see Action properties.

Schedule notification with the defined action group:

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

| iOS | Android | | :----------- | :----------- | | | |

Read input data

You have to subscribe to the event of the action id. The parameter event in the event callback will contain the input data of the user:

cordova.plugins.notification.local.on('REPLY_ACTION', (notification, event) => {
    // User made an input, event.text contains the input
    console.log("user input data=" + event.text);
});

Android sepcifics

When a notification has an input action, it can't be cleared from the statusbar (see Stackoverflow or plugin issue #2080). Google recommends to update the notification after the user made an input and show the reply without the actions. This plugin does this, but without showing the reply of the user and directly clear the notification after the update. Because the notiification will be updated after the input, you will get also an update event for that notification.

Handle action events

See Subscribe to an action event.

Action properties

Common

These common properties can be specified for an action of type button or input:

| Property | Android | iOS | Description | | :----------- | :------ | :-- | :---------- | | id | x | x | Action id. Also needed to listen to the action event. | | title | x | x | Title of the action button | | launch | x | x | If the app should be launched, when the user clicks on an action button or sends the input of an action input. Default is false. | | ui | | x | Can be set to decline which will display the action button with special highlighting to indicate that it performs a destructive task. Sets natively UNNotificationActionOptionDestructive. | | needsAuth | | x | If set to true the action can be performed only on an unlocked device. When the user selects an action with this option, the system prompts the user to unlock the device. After unlocking, the system notifies your app of the selected action. You might use option to perform actions that require accessing data that is encrypted while the device is locked. Sets natively UNNotificationActionOptionAuthenticationRequired. | | icon | x | | Is not supported anymore for normal notifications since Android 7, see Google Blog article for notifications on Android 7. It will be only used on Android Wear. |

Action input properties

These properties can additionally be specified for an input action:

| Property | Android | iOS | Description | | :----------- | :------ | :-- | :---------- | | emptyText | x | x | Placeholder text for input field. | | submitTitle | | x | Title for submit button. Defaults to Submit. | | editable | x | | Specifies whether the user can provide arbitrary text values. If you specify false, you must provide a non-null and non-empty array for choices. Default is true. | | choices | x | | A String array of pre-defined choices for users input. You must provide a non-null and non-empty array if you disabled free form input by setting editable to false. |

Triggers

Notifications may trigger immediately or depend on calendar or location.

Fixed date

Trigger at a fixed date:

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

| Property | Type | Value | Android | iOS | | :------------ | :------ | :--------------- | :------ | :-- | | at | Date | | x | x |

Relative

Relative from now:

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

| Property | Type | Value | Android | iOS | | :------------ | :------ | :--------------- | :------ | :-- | | in | Int | | x | x | | unit | String | second, minute, hour, day, week, month, quarter, year | x | x |

Repeating

Repeat relative from now:

cordova.plugins.notification.local.schedule({
    id: 1,
    title: 'Design team meeting',
    trigger: { every: 'day', count: 5 } // count is only supported by Android
});

| Property | Type | Value | Android | iOS | Note | | :------------ | :------ | :--------------- | :------ | :-- | :--- | | before | Date | | x | | | | firstAt | Date | | x | | | | count | Int | | x | | | | every | String | minute, hour, day, week, month, quarter , year | x | x | |

Trigger every time the date matches:

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

| Property | Type | Value | Android | iOS | Note | | :------------ | :------ | :--------------- | :------ | :-- | :--- | | before | Date | | x | | | | after | Date | | x | | | | count | Int | | x | | | | every | Object | minute, hour, day, weekday, weekdayOrdinal , week , weekOfMonth, month, quarter | x | x | |

Location based

iOS only

To trigger when the user enters a region:

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

| Property | Type | Value | Android | iOS | Note | | :------------ | :------ | :--------------- | :------ | :-- | :--- | | center | Array | [lat, long] | | x | | | radius | Int | | | x | | | notifyOnEntry | Boolean | | | x | | | notifyOnExit | Boolean | | | x | | | single | Boolean | | | x | |

Progress

Android only

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

cordova.plugins.notification.local.schedule({
    id: 1,
    title: 'Sync in progress',
    text: 'Copied 2 of 10 files',
    androidProgressBar: {
        value: 20, // Default 0
        maxValue: 100, // Default 100
        indeterminate: false // Default false
    }
});

Calls NotificationCompat.Builder#setProgress(int,int,boolean)

Indeterminate Progress

Use indeterminate mode for the progress bar when you do not know how long an operation will take. It shows a cyclic animation without a specific amount of progress indicated.

See ProgressBar#indeterminate-progress

Determinate Progress

Use determinate mode for the progress bar when you want to show that a specific quantity of progress has occurred. For example, the percent remaining of a file being retrieved, the amount records in a batch written to database, or the percent remaining of an audio file that is playing.

See ProgressBar#determinate-progress

Patterns

Android only

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({
    id: 1,
    title: 'The Big Meeting',
    text: '4:15 - 5:15 PM\nBig Conference Room',
    androidSmallIcon: 'res://ic_menu_my_calendar',
    androidLargeIcon: 'res://large_icon'
});

Summarizing

Android only

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',
    androidLargeIcon: 'res://large_icon',
    androidMessages: [
        { person: 'Me', message: 'I miss you' },
        { person: 'Irish', message: 'I miss you more!' },
        { person: 'Me', message: 'I always miss you more by 10%' }
    ]
});

To add a new message to the existing chat:

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

For displaying the messages, NotificationCompat.MessagingStyle will be used.

Properties for androidMessages

androidMessags: [
    {
        message: "The message", // Default is `null`
        date: 1234567890, // Timestamp in milliseconds for e.g. by Date.getTime(), default is System.currentTimeMillis()
        person: "Michael", // Default is `null`
        personIcon: "www/personIcon.png" // Default is `null`
    }
]

Property personIcon

Will be drawn as a circle icon.

Possible values:

• res://personIcon.png - Resource from the app bundle, see documentation
• www/personIcon.png - Resource from the www folder, see documentation
• shared://personIcon.png - Resource from the shared folder, see documentation

Grouping

Android only

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: 1,
        title: 'Design team meeting',
        ...
    },
    {
        id: 2,
        androidSummary: '[email protected]',
        androidGroup: 'email',
        androidGroupSummary: true
    },
    {
        id: 3,
        title: 'Please take all my money',
        ...,
        androidGroup: 'email'
    },
    {
        id: 4,
        title: 'A question regarding this plugin',
        ...,
        androidGroup: 'email'
    },
    {
        id: 5,
        title: 'Wellcome back home',
        ...,
        androidGroup: 'email'
    }
]);

Android channels

Default channel

The following settings will be used for the default Android channel.

{
    androidChannelId: "default_channel",
    androidChannelName: "Default channel",
    androidChannelImportance: "IMPORTANCE_DEFAULT"
}

You can change the defaults by calling setDefaults or you can overwrite them, when scheduling a notification or creating a channel.

The default channel id was changed in version 1.1.0 from default-channel-id to default_channel.

Create channel by posting a notification

A channel can be created directly when posting a notification:

cordova.plugins.notification.local.schedule({
    id: 1,
    title: 'My first notification',
    androidChannelId: "my_channel_01",
    androidChannelName: "My Channel Name"
});

If you omit some channel properties the default channel properties will be used.

Android: Schedule exact alarms

Since Android 12 notifications will be scheduled inexact by default. On Android 12 (API level 31) and higher, the system invokes the alarm within one hour of the supplied trigger time, unless any battery-saving restrictions are in effect such as battery saver or Doze. Most apps can schedule tasks and events using inexact alarms to complete several common use cases. If your app's core functionality depends on a precisely-timed alarm — such as for an alarm clock app or a calendar app — then it's OK to use an exact alarm instead.

See Android documentation for more information.

You have two options, to schedule exact alarms.

Exact alarms: User grants permission

You must add the SCHEDULE_EXACT_ALARM permission to AndroidManifest.xml. You can do this with your config.xml.

First add the Android xml namespace to your widget tag:

<widget ... xmlns:android="http://schemas.android.com/apk/res/android">

Then add the following config-file declaration to your config.xml:

<config-file target="AndroidManifest.xml" parent="/manifest">
    <uses-permission android:name="android.permission.SCHEDULE_EXACT_ALARM" />
</config-file>

This tells Android that your app wants to have the permission to schedule exact alarms.

| | | | :--- | :--- | | | After declaring SCHEDULE_EXACT_ALARM as permission, your app have a new entry in the app settings called Alarms & reminders, where the user can enable/disable exact alarms. | | | Clicking on this entry will open the setting to enable/disable exact alarms. This screen will also been shown if you call openAlarmSettings |

On Android 12 SCHEDULE_EXACT_ALARM is pre-granted. On Android 13 and newer the user has to permit this in the "Alarms & Reminders" setting, which you can open by openAlarmSettings. You can use the resume event of Cordova to check if exact alarms are permitted by canScheduleExactAlarms. If you have already posted inexact alarms, before the user granted the exact alarm permission, inexact alarms will be automatically rescheduled by this plugin as exact alarms. The downside is, when the user revokes the exact alarm permission, your app will be killed and all exact alarms will be canceled without rescheduling them as inexact alarms. You have to reschedule them the next time the user starts your app. You can read everything about it in the Android documentation.

Exact alarms: Define your app as a Calender or Alarm Clock app

This is a very special case you should think about. When you declare your app as a calendar or alarm clock app, the app have to fullfill the requirements and must be approved by Google in the Play Store. Google could remove the app from the store if the app is found to be misusing the permission.

Calendar or alarm clock apps need to send calendar reminders, wake-up alarms, or alerts when the app is no longer running. These apps can request the USE_EXACT_ALARM permission. The USE_EXACT_ALARM permission will be granted on install, and apps holding this permission will be able to schedule exact alarms just like apps with the SCHEDULE_EXACT_ALARM permission. The advantage is, that this permission can't be revoked by the user.

To declare the USE_EXACT_ALARM permission in the AndroidManifest.xml, you can do this with your config.xml.

First add the Android xml namespace to your widget tag:

<widget ... xmlns:android="http://schemas.android.com/apk/res/android">

Then add the following config-file declaration to your config.xml:

<config-file target="AndroidManifest.xml" parent="/manifest">
    <uses-permission android:name="android.permission.SCHEDULE_EXACT_ALARM" android:maxSdkVersion="32" />
    <uses-permission android:name="android.permission.USE_EXACT_ALARM" />
</config-file>

The permission SCHEDULE_EXACT_ALARM must be decared to be backward compatible with Android 12. The is why the permission is limited by android:maxSdkVersion="32", see StackOverflow or the documentation of USE_EXACT_ALARM.

The permission USE_EXACT_ALARM exists since Android 13 and will be used from then on.

Events

The following events are supported: add, trigger, click, clear, cancel, update, clearall and cancelall. Clicks on actions will trigger an event for the action id.

Subscribe to an event

cordova.plugins.notification.local.on('click', (notification, event) => {
    // A notification was clicked
});

Subscribe to an action event

If you want to listen when an action was clicked or an input was made, you have to subscribe to the action id:

Example:

// Define an action group with the action ids 'YES_ACTION' and 'NO_ACTION'
cordova.plugins.notification.local.addActions('YES_NO_CATEGORY', [
    {
        id: 'YES_ACTION',
        title: 'Yes'
    },
    {
        id: 'NO_ACTION',
        title: 'No'
    }
]);

// Subscribe to the action click event for 'YES_ACTION'
cordova.plugins.notification.local.on('YES_ACTION', (notification, event) => {
    // yes action was clicked
});

Note: A click on an action will not open the app by default. In Android, the event will be hold back in a background process of the app to wait for the next time the app starts, but could be lost, if the system kills the app background process. To avoid this, define the action with property launch: true.

Content of event parameter

The event parameter of the event callback can contain the following properties:

| Property | Type | Android | iOS | Description | | :----------- | :----------- | :------ | :-- | :---------- | | event | String | x | x | Contains the event name like click, clear or the action id, if an action was clicked. | | foreground | Boolean | x | x | If the app was in foreground, when the event was fired. | | queued | Boolean | x | x | If the event was hold, because deviceready was not yet fired. | | notification | int | x | x | Notification id | | text | String | x | x | Contains the input data of a user made to an input action. |

Unsubscribe from an event

To unsubscribe from an event, you have to use the same callback you used for subscribing to the event.

Example:

const clickEventCallback = (notification, event) => {
    // Click event was triggered
};

// Register to the click event with the given callback
cordova.plugins.notification.local.on('click', clickEventCallback);

// Unregister from the click event
cordova.plugins.notification.local.un('click', clickEventCallback);

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.

Note: This list has still to be documented.

| Method | Android | iOS | Comment | | :------------------------------| :-------| :-- | :------------------------ | | addActions | x | x | Defines some actions in a group to re-use them. See Actions. | | cancel | x | x | | | cancelAll | x | x | | | canScheduleExactAlarms | x | - | Checks if exact alarms are permitted. Since Android 13 inexact alarms are permitted by default. | | clear | x | x | On Android, it clears a already posted notification from the statusbar. | | clearAll | x | x | | | createChannel | x | - | Creates a channel for Android to post notifications on. | | deleteChannel | x | - | Delete a channel by an id. | | fireQueuedEvents | x | x | Fire queued events once the device is ready and all listeners are registered. This is done automatically, when deviceready is fired. Calls the Plugin with a ready action. | | get | | | | | getAll | | | | | getDefaults | x | x | Gets the default for notification properties. See getDefaults | | getIds | | | | | getScheduled | | | | | getScheduledIds | | | | | getTriggered | | | | | getTriggeredIds | | | | | getType | | | | | getUnusedAppRestrictionsStatus | x | - | Gets the status of the unused app restrictions status | | hasActions | x | x | Checks if an action group exists by id like hasActions('YES_NO_CATEGORY', (hasActions) => {}, this) | | hasPermission | x | x | Checks if the app has permission to post notifications. | | iOSClearBadge | - | x | Clears the badge | | isPresent | | | | | isScheduled | | | | | isTriggered | | | | | on | x | x | Listen to an Event | | openAlarmSettings | x | - | Supported since Android 12. Opens the "Alarms & Reminders"-settings, where the user can manually enable exact alarms. | | openManageUnusedAppRestrictions | x | - | Opens the unused app restriction settings directly in the app. | | openNotificationSettings | x | (x) | Opens the notifications settings since Android 8. On iOS it opens the app settings. | | removeActions | x | x | Removes actions by a group id like removeActions('YES_NO_CATEGORY', () => {}, this) which were previously created by addActions | | requestPermission | x | x | Request permission to post notifications. This is called automatically when scheduling notifications. | | schedule | x | x | Schedules a single notification or multiple notifications. Accepts an object or an Array. | | setDefaults | x | x | Overwrites default values of notifications. Gets the default for notification properties. | | un | x | x | Unlisten to an Event | | update | x | x | Updates a single notification or multiple notifications. The notification id has to be set to update a notification. Accepts an obect or an Array. |

canScheduleExactAlarms

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 11 and older, this method will always return true in the successCallback.
• 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.

createChannel

Android only

Creates a channel, if it not already exists. A channel is not changeable, after it is created. This is a restriction by Android. If a notification does not specify a androidChannelId a default channel will be used.

For setting the channel, use androidChannelId when scheduling a notification.

Overview of all properties for a channel:

cordova.plugins.notification.local.createChannel({
    androidChannelId: "my_channel_01", // string, to separate something in the id, use "_" instead of "-"
    androidChannelName: "My Channel Name", // string, defaults to "Default Channel"
    androidChannelDescription: "Description of channel", // string (optional)
    androidChannelImportance: "IMPORTANCE_DEFAULT", // string (optional)
    androidChannelEnableLights: true, // boolean (optional), default is false
    androidChannelEnableVibration: true, // boolean (optional), default is false
    sound: 'www/audio/ring.mp3', // string (optional)
    androidChannelSoundUsage: 5 // int (optional), default is USAGE_NOTIFICATION
  }, successCallback, this)

Property documentation:

• androidChannelId
• androidChannelImportance
• androidChannelEnableLights
• androidChannelEnableVibration
• sound
• androidChannelSoundUsage

deleteChannel

Android only

Deletes a Android channel.

Example:

cordova.plugins.notification.local.deleteChannel("my_channel_id", successCallback, this)

These will delete all associated notificiations for this channel. If you create a new channel with the same id, the deleted channel will be un-deleted with all of the same settings it had before it was deleted, see NotificationManagerCompat.deleteNotificationChannel

getDefaults

Returns the default values of all properties on each platform.

Example:

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

getUnusedAppRestrictionsStatus

Returns the status of unused app restrictions also called app hibernation, which was introduced in Android 11 and is backported to Android 6 through the Google Play Store. From Android 6 to 11, only permissions gets revoked, what does not affect notifications, because notifications needs requesting permissions only since Android 13. But because since Android 12 also notifications get canceled, the status is relevant for Android 12 and later. When unused app restrictions are active, it will return API_30_BACKPORT (on Android 6 to 10), API_30 on Android 11 or API_31on Android 12 and later. If it is disabled, DISABLED will be returned.

Sample:

cordova.plugins.notification.local.getUnusedAppRestrictionsStatus(
    (status) => {
        // Shortcode for getting possibile status codes for status
        const statusCodes = cordova.plugins.notification.local.androidUnusedAppRestrictionsStatusCodes;

        // app hibernation is active on Android 12 and later
        if (status == statusCodes.API_31) {

        }
    },
    this
);

Possible status codes:

| Name | Value | Description | | :---------------------- | :-------- | ----------------------- | | ERROR | 0 | The status of Unused App Restrictions could not be retrieved from this app e.g. if the user is in locked device boot mode. Check the logs for the reason. | | FEATURE_NOT_AVAILABLE | 1 | There are no available Unused App Restrictions for this app. This would happen on devices older then Android 6, but this plugin supports minimum Android 7. | | DISABLED | 2 | Any available Unused App Restrictions on the device are disabled for this app. In other words, this app is exempt from having its permissions automatically removed or being hibernated. | | API_30_BACKPORT | 3 | Unused App Restrictions introduced by Android API 30 (Android 11), and since made available on earlier (API 23-29 = Android 6 to 10) devices are enabled for this app: permission auto-reset. Note: This value is only used on API 29 (Android 10) or earlier devices. | | API_30 | 4 | Unused App Restrictions introduced by Android API 30 (Android 11) are enabled for this app: permission auto-reset. Note: This value is only used on API 30 (Android 11) or later devices. | | API_31 | 5 | Unused App Restrictions introduced by Android API 31 (Android 12) are enabled for this app: permission auto-reset and app hibernation. Note: This value is only used on API 31 (Android 12) or later devices. |

hasPermission

Checks if the app has permissions to post notifications.

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

iOSClearBadge

Clears the badge.

openAlarmSettings

Android only. Since Android 12 (SDK 31).

Opens the Alarms & reminders setting as an Activity when running on Android 12 (SDK 31) or later, where the user can enable exact alarms.

This is only available, if SCHEDULE_EXACT_ALARM is declared as permission in the AndroidManifest.xml.

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 be rescheduled as exact alarms.
• If exact alarms were already granted and the user revokes it, the app will be killed and all scheduled notifications will be canceled. 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.
• On Android older then 12, it will just call the successCallback, without doing anything.

openManageUnusedAppRestrictions

Opens the unused app restriction settings directly in your app. The successCallback will be called if the user returns to your app.

Sample:

cordova.plugins.notification.local.openManageUnusedAppRestrictions((result) => {
    // User has returned from the settings
}, this);

You can check in the successCallback what the user selected, by calling getUnusedAppRestrictionsStatus.

openNotificationSettings

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.

requestPermission

Request permission to post notifications. This is called automatically by the plugin when scheduling notifications, but you can also request it manually before scheduling notifications:

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

If this method is called, a dialog will be shown to the user to ask for the permission.

The user can still allow/deny the permission through the system settings.

To check if permissions are granted, without calling this method, use hasPermission.

setDefaults

Changes default values of properties.

Example:

cordova.plugins.notification.local.setDefaults({
    androidChannelId: "my_channel_01",
    title: "My default Title"
});

Properties

Changed properties

List of changed properties on newer plugin versions.

Changes since version 1.1.0

There were some properties renamed. You can still use the old ones, but you will get a deprecation warning in the log and they will be removed in future versions.

| Old Property | New Property | | :---------------------- | :-------------------------- | | autoClear | androidAutoCancel | | badge | badgeNumber | | channelDescription | androidChannelDescription | | channelId | androidChannelId | | channelImportance | androidChannelImportance | | channelName | androidChannelName | | clock | Use for clock: boolean = androidShowWhen: boolean and for clock: 'chronometer' = androidUsesChronometer: true | | color | androidColor | | defaults | androidDefaults | | description | androidChannelDescription | | foreground | iOSForeground | | group | androidGroup | | groupSummary | androidGroupSummary | | icon | androidLargeIcon | | iconType | androidLargeIconType | | importance | androidChannelImportance | | lockscreen | androidLockscreen | | mediaSession | Property was removed | | onlyAlertOnce | androidOnlyAlertOnce | | prio | Use androidChannelImportance, androidAlarmType and androidAllowWhileIdle instead. | | priority | Use androidChannelImportance, androidAlarmType and androidAllowWhileIdle instead. | | progressBar | androidProgressBar | | smallIcon | androidSmallIcon | | sticky | androidOngoing | | soundUsage | androidChannelSoundUsage | | ongoing | androidOngoing | | summary | androidSummary | | text as Array | androidMessages | | timeoutAfter | androidTimeoutAfter | | titleCount | androidTitleCount | | wakeup | androidWakeUpScreen |

Changes on androidProgressBar

The default value changed from:

{enabled: false, value:0, maxValue:100, indeterminate:false}

to

null

The property androidProgressBar.enabled is not supported anymore. Just set androidProgressBar: null to disable the progressbar.

Changes on sound

The property sound takes no longer additionally a boolean, now only a string, which points to a sound file.

• The value sound: true is replaced with sound: 'default'
• The value sound: false is replaced with sound: null

Changes since version 1.1.1

There were some properties renamed. You can still use the old ones, but you will get a deprecation warning in the log and they will be removed in future versions.

| Old Property | New Property | Reason | | :---------------------- | :---------------------------- | ----------------------- | | vibrate | androidChannelEnableVibration | The vibration cannot be controlled on iOS. So this is a Android only property and can only be set on a channel. See androidChannelEnableVibration|

Common properties

These properties can be used on all platforms, but some may behave differently on each platform.

| Property | Default | Comment | | :----------------------| :-----------------|:--------------------------| | actions | [] | Actions of a notification | | attachments | [] | List of resources, to attach to the notification. | | badgeNumber | Android: 1, iOS: -1 | Sets the badge for the application. The behaviour differs on Android and iOS. | | data | null | Custom data for the notification. Can be used, when the notification is send back to the app, e.g. by clicking on it. | | id | 1 | ID of a notification as number. | | launch | true | If a click on the notification should launch the app. | | priority | 0 (=PRIORITY_DEFAULT) | Deprecated. Use androidChannelImportance, androidAlarmType and androidAllowWhileIdle | | silent | false | iOS: Don't show a notification, make no sound, no vibration, when app is in foreground. Android: Don't show a notification (Does not create a Builder. Must be tested if that works) | | text | "" | Text of the notification. Android features: 1. If the text contains line breaks (\n) the notification style NotificationCompat.InboxStyle will be used. 2. If the text is longer then 44 chars, the notifications style NotificationCompat.BigTextStyle will be used. | | sound | default | Sets the sound of a notification. On iOS it also turns on/off the vibration. | | title | "" (Sets the app name) | Title of the notification. Has to be a String. If it is empty, the app name will be used. | | trigger | {at: new Date(), type : "calendar"}| Notifications may trigger depend on time or location (iOS only) |

Android properties

These properties are only available on Android.

| Property | Default | Comment | | :----------------------| :-----------------|:--------------------------| | androidAlarmType | RTC_WAKEUP | | | androidAllowWhileIdle | false | Alarm will be allowed to execute even when the system is in low-power idle (a.k.a. doze) modes. | | androidAutoCancel | true | Make this notification automatically dismissed when the user touches it | | androidChannelDescription | null | Sets the description of a notification channel. | | androidChannelEnableLights | false | Can be true or falseand sets whether notifications posted to a notification channel should display notification lights, on devices that support that feature. | | androidChannelEnableVibration | false | Enables the vibration of a channel. | | androidChannelId | default_channel | Specifies the channel id to be posted on. | | androidChannelImportance | IMPORTANCE_DEFAULT | Sets the importance of a notification channel | | androidChannelName | Default channel | Set the channelName for the notification to be posted on. See Android Notification Channels for more information. | | androidChannelSoundUsage | 5 (=USAGE_NOTIFICATION) | Sets the androidChannelSoundUsage of a notification channel. | | androidColor | null | The notification background color for the small icon in the notification style. | | androidGroup | null | Set this notification to be part of a group of notifications sharing the same key. Grouped notifications may display in a cluster or stack on devices which support such rendering. To make this notification the summary for its group, also call setGroupSummary(boolean). A sort order can be specified for group members by using setSortKey(String) (not implemented yet). Calls Notification.Builder#setGroup(java.lang.String) | | androidGroupSummary | false | Set this notification to be the group summary for a group of notifications. Grouped notifications may display in a cluster or stack on devices which support such rendering. Requires a group key also be set using setGroup(String). The group summary may be suppressed if too few notifications are included in the group. Calls Notification.Builder#setGroupSummary(boolean) | | androidLargeIcon | null | Add a large icon to the notification content view. | | androidLargeIconType | square | Can be square or circle | | androidLockscreen | true | If the entire notification should be shown on all lockscreens and while screen sharing. If the value is true, Notification#VISIBILITY_PUBLIC will be set, otherwise Notification#VISIBILITY_SECRET. Sets Notification#visibility. | | androidMessages | null | Array of messages to summarize notifications. NotificationCompat.MessagingStyle will be used. | | androidOngoing | false | Set whether this is an ongoing notification. Ongoing notifications cannot be dismissed by the user on locked devices, or by notification listeners, and some notifications (call, device management, media) cannot be dismissed on unlocked devices. | | androidOnlyAlertOnce | false | Set this flag if you would only like the sound, vibrate and ticker to be played if the notification is not already showing (see documentation). | | androidProgressBar | null | See documentation | | androidShowWhen | true | If the Notification should show the when date. Before Version 1.1.0 called clock. | | androidSmallIcon | res://ic_popup_reminder (=Bell icon) | Set the small icon resource, which will be used to represent the notification in the status bar. | | androidSummary | null | | | androidTimeoutAfter | 0 | Specifies a duration in milliseconds after which this notification should be canceled, if it is not already canceled. 0 means no automatic cancellation. | | androidTitleCount | %n% | Additional text added to the title for displaying the number of messages if there is more than one. Only used, if using MessagingStyle. Use %n% in the string for specifying the location of the number. | | androidUsesChronometer | false | Show the Notification#when field as a stopwatch. Instead of presenting when as a timestamp, the notification will show an automatically updating display of the minutes and seconds since when. Useful when showing an elapsed time (like an ongoing phone call). Was former handeld by clock: 'chronometer' | | androidWakeUpScreen | true | If the screen should go on, when a notification arrives | | androidDefaults | 0 | Android 7 only. Sets the default notification options that will be used only on Android 7. Bitwise-or of: DEFAULT_SOUND, DEFAULT_VIBRATE, DEFAULT_LIGHTS. | | led | false | Android 7 only. Can be a Hex-String like #FF00FF or {color: '#FF00FF', on: 500, off: 500} and sets the led of a notification. Replaced by androidChannelEnableLights. |

iOS properties

These properties are only available on iOS.

| Property | Default value | Comment | | :--------------------------------------- | :-------------------- | :------------------------ | | iOSForeground | true | Displays a notification banner, when app is in foreground. |

Some notes:

• A progressbar is natively not supported by iOS, see Stackoverflow
• The vibration cannot be turned off separately. It can only be turned off, if no sound is set.

Default values

Default values for the properties can be get by getDefaults. Values can be changed by setDefaults

Available properties

Property androidAllowWhileIdle

Default: false

Alarm will be allowed to execute even when the system is in low-power idle (a.k.a. doze) modes.

This type of alarm must only be used for situations where it is actually required that the alarm go off while in idle -- a reasonable example would be for a calendar notification that should make a sound so the user is aware of it. When the alarm is dispatched, the app will also be added to the system's temporary power exemption list for approximately 10 seconds to allow that application to acquire further wake locks in which to complete its work.

This executes AlarmManager.setAndAllowWhileIdle or AlarmManager.setExactAndAllowWhileIdle depending on canScheduleExactAlarms.

Property androidAlarmType

Default: RTC_WAKEUP

If the alarm should be scheduled on a specific time or in relevance to the time, when the device was booted and if the alarm should wakeup the device cpu (not the screen). See also the Android documentation Choose an alarm type.

| Value | Support | Description | |:-----------------|:--------|:------------| | [RTC_WAKEUP](https://developer.android.com