Repository files navigation

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.

• Header area
• Content area
• Action area

• 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

• 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)

The plugin can be installed viaCordova-CLI and is publicly available onNPM.

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

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

Install from local source:

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

• Last version which supportscordova-android older than13.0.0 and supports minimumcordova-android version6.0.0 which is Android version4.1
• Last version which supports the Windows platform

• Removed Windows platform
• Support for Android 12-14 and uses AndroidX
• Raised minimumcordova-androidversion from6.0.0 to13.0.0, which raised the minimum Android version from4.1SDK 16 to7.0SDK 24
• Raised minimumcordova-ios version from4.3.0 to7.0.0
• Raised minimum Cordova version from3.6.0 to12.0.0
• Raised minimumcordova-plugin-device version from2.0.0 to3.0.0

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

TheDefault channel id was changed fromdefault-channel-id todefault_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 withdeleteChannel.

iOSForeground istrue by default

The propertyvibrate was renamed toandroidChannelEnableVibration.

A notification will be always showed in the notification center like on Android. Happens also ifiOSForeground isfalse.

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

• Notifications withtrigger.at date more than 5 seconds in the past will be ignored. iOS did always ignore passed notifications.
• If noid of a notification is set, it will default to1 instead of0.

The plugin creates the objectcordova.plugins.notification.local and is accessible after thedeviceready 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 to1. 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'}]);

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

• iOS: 64
• Android: 500

Repeating notifications count as 1 notification.

A notification does have a set of configurable properties. Seeall properties.

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 userequestPermission. 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, usehasPermission.

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

Since Android 8 notification channels must be created to post noitifications. Adefault channel will be created for you, if you do not create one. You can also create your own channel bycreateChannel or whenscheduling a notification. For deleting a channel usedeleteChannel.

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.

SeeSchedule exact alarms, if you want use exact alarms.

SeeAndroid documentation for more information.

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.

• 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, seeApp hibernation > Manually invoke hibernation behavior.
• To see a complete list, what counts as app usage and what not, seeApp hibernation > App usage.
• 3 months are based on executingadb shell device_config get permissions \ auto_revoke_unused_threshold_millis2 which will return7776000000 milliseconds on an Android 15 Emulator which are nearly 3 months (~2.96 months).

You can get the status of the setting by callinggetUnusedAppRestrictionsStatus. To redirect the user to the setting, callopenManageUnusedAppRestrictions. 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:

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

App Standby does not affect you when showing a notification.

You can read everything about it in theAndroid documentatation.

Android removes all alarms when the app is updated. The plugin reschedules all alarms by aBroadcastReceiver listening toACTION_MY_PACKAGE_REPLACED.

Android removes all alarms when the device reboots. The plugin reschedules all alarms by aBroadcastReceiver listening toACTION_BOOT_COMPLETED, but only after the device has been unlocked.

If you useSCHEDULE_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 aBroadcastReceiver listening toACTION_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.

Since Android 15 all pending alarms will get canceled if the user force stops an app, this is a change by Google, seehttps://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 onForce stop by showing an alert with the messageIf you force stop an app, it may misbehave.

You can add actions, which can be a button or an input to a notification. Before you can use them you have to pre-define them:

cordova.plugins.notification.local.addActions('YES_NO_CATEGORY',[{id:'YES_ACTION',title:'Yes'},{id:'NO_ACTION',title:'No'}]);

Then you have to assign the defined actions when scheduling 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.

Icons on action buttons are not possible. Android had supported it, but stopped this inAndroid 7.

The plugin knows two types of actionsbutton andinput. If you do not specifiy a type, an action is by default a button.

You can define an action as input.

Register actions:

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

Schedule with registered actions:

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

OS native documentation:

• Android:https://developer.android.com/develop/ui/views/notifications/build-notification#reply-action

You can subscribe to an action event.

Example:

cordova.plugins.notification.local.addActions('YES_NO_CATEGORY',[{id:'YES_ACTION',title:'Yes'},{id:'NO_ACTION',title:'No'}]);

You have to subscribe to the action id:

cordova.plugins.notification.local.on('YES_ACTION',(notification,eopts)=>{// Your code});

To unsubcribe seeEvents.

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

Notifications may trigger immediately or depend on calendar or location.

Trigger at a fixed date:

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

Relative from now:

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

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

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

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 0maxValue:100,// Default 100indeterminate:false// Default false}});

CallsNotificationCompat.Builder#setProgress(int,int,boolean)

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.

SeeProgressBar#indeterminate-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.

SeeProgressBar#determinate-progress

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

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.

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`}]

Will be drawn as a circle icon.

Possible values:

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

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:'me@gmail.com',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'}]);

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 callingsetDefaults or you can overwrite them, when scheduling a notification orcreating a channel.

The default channel id was changed in version 1.1.0 fromdefault-channel-id todefault_channel.

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 thedefault channel properties will be used.

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.

SeeAndroid documentation for more information.

You have two options, to schedule exact alarms.

You must add theSCHEDULE_EXACT_ALARM permission toAndroidManifest.xml. You can do this with yourconfig.xml.

First add the Android xml namespace to yourwidget tag:

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

Then add the followingconfig-file declaration to yourconfig.xml:

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

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

	After declaringSCHEDULE_EXACT_ALARM as permission, your app have a new entry in the app settings calledAlarms & 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 callopenAlarmSettings

On Android 12SCHEDULE_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 byopenAlarmSettings. You can use theresume event of Cordova to check if exact alarms are permitted bycanScheduleExactAlarms. 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 theAndroid documentation.

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 theUSE_EXACT_ALARM permission. TheUSE_EXACT_ALARM permission will be granted on install, and apps holding this permission will be able to schedule exact alarms just like apps with theSCHEDULE_EXACT_ALARM permission. The advantage is, that this permission can't be revoked by the user.

To declare theUSE_EXACT_ALARM permission in theAndroidManifest.xml, you can do this with yourconfig.xml.

First add the Android xml namespace to yourwidget tag:

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

Then add the followingconfig-file declaration to yourconfig.xml:

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

The permissionSCHEDULE_EXACT_ALARM must be decared to be backward compatible with Android 12. The is why the permission is limited byandroid:maxSdkVersion="32", seeStackOverflow or the documentation ofUSE_EXACT_ALARM.

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

The following events are supported:add,trigger,click,clear,cancel,update,clearall andcancelall andaction events.

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 tocordova.plugins.notification.local.un as you provided tocordova.plugins.notification.local.on to make unsubscribing work.Hence you should define your callback as a separate function, not inline. If you want to usethis inside of your callback, you also have to providethis asscope tocordova.plugins.notification.local.on.

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

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

Check thelaunchDetails 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 likeIonic 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();

All methods work asynchronous and accept callback methods.

Note: This list has still to be documented.

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 returntrue in thesuccessCallback.
• 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.

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 aandroidChannelId adefault channel will be used.

For setting the channel, useandroidChannelId 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 falseandroidChannelEnableVibration:true,// boolean (optional), default is falsesound:'www/audio/ring.mp3',// string (optional)androidChannelSoundUsage:5// int (optional), default is USAGE_NOTIFICATION},successCallback,this)

Property documentation:

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

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, seeNotificationManagerCompat.deleteNotificationChannel

Returns the default values of all properties on each platform.

Example:

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

Returns the status of unused app restrictions also calledapp 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 returnAPI_30_BACKPORT (on Android 6 to 10),API_30 on Android 11 orAPI_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 statusconststatusCodes=cordova.plugins.notification.local.androidUnusedAppRestrictionsStatusCodes;// app hibernation is active on Android 12 and laterif(status==statusCodes.API_31){}},this);

Possible status codes:

Checks if the app has permissions to post notifications.

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

Clears the badge.

Android only. Since Android 12 (SDK 31).

Opens theAlarms & 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, ifSCHEDULE_EXACT_ALARM is declared as permission in theAndroidManifest.xml.

This method will not wait for the user to be returned back to the app. For this, theresume-event can be used. The callback will just returnOK, 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, seehttps://developer.android.com/develop/background-work/services/alarms/schedule#using-schedule-exact-permission.
• On Android older then 12, it will just call thesuccessCallback, without doing anything.

Opens the unused app restriction settings directly in your app. ThesuccessCallback 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 thesuccessCallback what the user selected, by callinggetUnusedAppRestrictionsStatus.

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

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

Changes default values of properties.

Example:

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

List of changed properties on newer plugin versions.

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.

The default value changed from:

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

to

null

The propertyandroidProgressBar.enabled is not supported anymore.Just setandroidProgressBar: null to disable the progressbar.

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

• The valuesound: true is replaced withsound: 'default'
• The valuesound: false is replaced withsound: null

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.

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

These properties are only available on Android.

These properties are only available on iOS.

• 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 for the properties can be get bygetDefaults.Values can be changed bysetDefaults

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 executesAlarmManager.setAndAllowWhileIdle orAlarmManager.setExactAndAllowWhileIdle depending oncanScheduleExactAlarms.

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 documentationChoose an alarm type.

Default:false

Can betrue orfalseand sets whether notifications posted to anotification channel should display notification lights, on devices that support that feature.

Android documentation:https://developer.android.com/reference/android/app/NotificationChannel#enableLights(boolean)

Default:false

Sets the vibration of anotification channel by settingNotificationChannel#enableVibration(boolean). On Android 7 this sets the vibration of a notification directly.

Default:default_channel

Sets thechannelId for the notification to be posted on. UseSnake Case for the id, which means, the id should be written in lowercase and words should be separated by underscores (_) and not hyphens (-) or whitespaces.

Default:"IMPORTANCE_DEFAULT"

The property can have one of the following values:

See theAndroid documentation about this property.

See alsoNotificationChannel#NotificationChannel(java.lang.String,%20java.lang.CharSequence,%20int)

Default:5 (=USAGE_NOTIFICATION)

The property can have one of the following values:

SeeAndroid Documentation

Default:null

The notification background color for the small icon. The color will only be applied on the notification style and not on the status bar.Set as Hex-String like#FF0000. CallsNotification.Builder#setColor, which setsNotification#color.

Default:null

Add a large icon to the notification content view. In the platform template, this image will be shown either on the right of the notification, with an aspect ratio of up to 16:9, or (when the notification is grouped) on the left in place of the small icon. CallsNotification.Builder#setLargeIcon(android.graphics.Bitmap).

Examples:

• res://myLargeIcon.png - Resource from the app bundle, seedocumentation
• www/myLargeIcon.png -www folder, seedocumentation
• shared://myLargeIcon.png - Shared folder, seedocumentation, Android only

Default:res://ic_popup_reminder (=Bell icon)

Sets the small icon resource, which will be used to represent the notification in the status bar. Since Android 8, the icon must be a monochrome icon, which can only use a white color on a transparent background. The icon will be colored by the system in respective circumstances. You can also use a vector drawable, but only for ares:\\ paths. You can get vector drawables onGoogle Fonts Icons as example or for using it. Just select the download for Android. To know, what vector drawables are, see the Android documentationVector drawables overview.

The platform template for the expanded view will draw this icon in the left, unless a large icon has also been specified, in which case the small icon will be moved to the right-hand side. CallsNotification.Builder#setSmallIcon(int).

Example:res://myIcon.png - Resource from the app bundle, seedocumentation

Onlyres:// paths are allowed.

Default:null

Used in the following cases:

1. ForNotificationCompat.InboxStyle#setSummaryText(java.lang.CharSequence), when usingNotificationCompat.InboxStyle, which happens, when thetext property has line breaks.
2. ForNotificationCompat.BigPictureStyle#setSummaryText(java.lang.CharSequence), whenNotificationCompat.BigPictureStyle is used, which happens, whenattachments are used. IfandroidSummary is not set,text will be used.
3. ForNotificationCompat.BigTextStyle#setSummaryText(java.lang.CharSequence), whenNotificationCompat.BigTextStyle is used, which happens, if thetext property is longer then 44 characters.

Default:[]

List of resources, to attach to the notification.

Only the first entry will be used as abigPicture ofNotificationCompat.BigPictureStyle.

Support resource patterns:

• res://
• shared://
• www

Example folded and unfolded:

The notification will be automatically unfolded in the notification center if your app presents only one notification. On the lockscreen the notification is always folded.

The visual and audio attachments to display alongside the notification’s main content, see documentation ofUNMutableNotificationContent.attachments.

Support resource patterns:

• file:/// - Absolute file path
• res:// - App resource
• www
• base64:// - Base64 string

If you attach an image, the image will shown as a small image to the right in the notification and will be expanded when you press long on the notification.

Example folded and unfolded:

cordova.plugins.notification.local.schedule({id:1,title:'Get a fan!',text:'RB Leipzig is looking for a new fan! Click here to apply!',attachments:['www/img/rb-leipzig.png']});

Default:

• Android:1 - Each notification increments the badge count by 1
• iOS:-1 - Does not set any badge

Set the badge count. The behavior differs on Android and iOS.

Sets the number of items a notification represents. If the value is1, each notification increments the badge of the application by one. If 3 notifications are posted, the badge count will be3.

On newer Android versions, the badge count will be presented as a dot and shows the number, if you long press on the app icon.

For using the badge, see the Android documentationModify a notification badge.

CallsNotificationCompat.Builder#setNumber(int).

A notification does not increment the badge, it sets the badge count directly. If 3 notifications are posted with the value of1, the badge count will be1 and not3.

Specials of this value:

• -1: The badge will not be changed.
• 0: The badge will be cleared.

SetsUNMutableNotificationContent#badge.

You can clear the badge with the functioniOSClearBadge.

The badge will also be cleared, if you callclearAll orcancelAll.

Default:1

ID of a notification as number. This has to be unique for every notification. If you do not set an ID, it will default to 1. If you use an ID of a previous scheduled notification again, the previous one will be canceled.

Default:true

Displays a notification banner when the app is in foreground, otherwise the notification would only make a noise (sound and vibrate), change the badge, but is not shown as a banner. Since iOS 14, the notification is always displayed in the Notification Center, no matter how this option is set to be consistent with Android. Renamed fromforeground toiOSForeground and changed totrue by default in Version1.1.0.

Default:0 (=PRIORITY_DEFAULT)

Deprecated since Android 8.

Replaced byandroidChannelImportance, which sets also thepriority value for notifications on Android 7.

This property had aditional functionality for the plugin, which is replaced byandroidAlarmType andandroidAllowWhileIdle.

When the value wasPRIORITY_MIN(=-2), the alarm was scheduled withRTC.This can now be achieved by settingandroidAlarmType toRTC andandroidAllowWhileIdle to false.

When the value wasPRIORITY_DEFAULT(=0), which was set as the default for this plugin, the alarm was scheduled withRTC_WAKEUP. This can now be set byandroidAlarmType.

When the value wasPRIORITY_MAX(=2), the alarm was scheduled byAlarmManager.setAndAllowWhileIdle orAlarmManager.setExactAndAllowWhileIdle. This can now be set byandroidAllowWhileIdle.

Default:default

The valuedefault sets the system default sound for a notification. The valuenull will disable the sound.On Android it sets the sound of a notification channel. On iOS it enables/disables also the vibration.

Example:

• res://mySound.wav - Resource from the app bundle, seedocumentation
• shared://mySound.wav - Shared folder, seedocumentation, Android only
• www/mySound.wav -Documentation

Before Android 8 it sets the sound of a notification. Since Android 8 it sets the sound of anotification channel.

Enables/disables also the vibration. If no sound is set, no vibration will occur.

You can package the audio data in anaiff,wav, orcaf file. Sound files must be less than 30 seconds in length.If the sound file is longer than 30 seconds, the system plays the default sound instead. SeeUNNotificationSound - Prepare Sound Resources.

The system looks in the following folders for the file:

• The/Library/Sounds directory of the app’s container directory.
• The/Library/Sounds directory of one of the app’s shared group container directories.
• The main bundle of the current executable.

See documentationUNNotificationSound#soundNamed.

If a property can take a resource, the following patterns could be used. Not all patterns are available for every property.

Example:file://myImage.png

Looks for a file in thewww folder.file://myImage.png is equivalent towww/myImage.png.

Example:www/myImage.png

Looks for a file in thewww folder.

Example:res://myImage.png

Defines a resource for Android or iOS. In Android it looks in the app'sres folder, in iOS it looks for a file in the root of the app package.

Gets a resource from theres directory of your app or the system resources. Normally, when getting a resource file on Android, the resource name should not contain the file extension likeres://myImage, but, to be compatible with iOS, you can also include the extension likeres://myImage.png. An explanation what theresdirectory is, can be read in the Android documentationProviding Resources.

The property, which you use, defines, in which subfolder ofres the resource should be:

• For a graphic:drawable andmipmap
• For a sound:raw

The plugin trys first to get the resource from you app package, if it does not find one there, it trys to get it from thesystem resources.

If you want to use a system resource, you have to use a valid resource identifier, which you can look for inAndroid Code Search. An example would beic_popup_reminder, which you would set withres://ic_popup_reminder.

To make files files available in theres directory, you can use theresource-file tag inconfig.xml like:

<platformname="android">    <resource-filesrc="res/drawable/myImage.png"target="app/src/main/res/drawable/myImage.png" />    <resource-filesrc="res/raw/mySound.wav"target="app/src/main/res/raw/mySound.wav" /></platform>

The directory structure for this example would be:

|- res   |- drawable       |- myImage.png    |- raw       |- mySound.wav|- config.xml|- plugins|- platforms...

Looks for a file in the root of the app package.

For e.g.:res://AppIcon60x60@3x.png would point toYourApp.ipa/AppIcon60x60@3x.png on a release build orYourApp.app/AppIcon60x60@3x.png on a debug build. The app container is a zip file. On a mac, you can right click on your app container and chooseShow package contents.

To copy files to the app bundle, use theresource-file tag in yourconfig.xml like:

<platformname="ios">    <resource-filesrc="res/myAudio.wav"target="myAudio.wav" /></platform>

The directory structure for the example would be:

|- res   |- myAudio.wav|- config.xml|- plugins|- platforms...

Example:shared://myImage.png

Android only.

A shared file in[Installed-App-Path]/files/shared_files. This is necessary to get useable Uris for asset files, which are the files of thewww directory. You can also use theshared_files directory, to store files created on runtime. To access the directory, you can usecordova.file.dataDirectory of the plugincordova-plugin-file and write to the foldershared_files. The foldershared_files will be created on plugin initialization.

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

This software is released under theApache 2.0 License.

Made with 😋 from Leipzig and since 2024 from Cuxhaven

© 2013-2023appPlant GmbH
© 2024-2025Manuel Beck