diff --git a/docs/apis/local-notifications.md b/docs/apis/local-notifications.md
index f0936aa6..728788ff 100644
--- a/docs/apis/local-notifications.md
+++ b/docs/apis/local-notifications.md
@@ -1,8 +1,8 @@
---
title: Local Notifications Capacitor Plugin API
description: The Local Notifications API provides a way to schedule device notifications locally (i.e. without a server sending push notifications).
-custom_edit_url: https://github.com/ionic-team/capacitor-plugins/blob/next/local-notifications/README.md
-editApiUrl: https://github.com/ionic-team/capacitor-plugins/blob/next/local-notifications/src/definitions.ts
+custom_edit_url: https://github.com/ionic-team/capacitor-local-notifications/blob/main/README.md
+editApiUrl: https://github.com/ionic-team/capacitor-local-notifications/blob/main/src/definitions.ts
sidebar_label: Local Notifications
---
@@ -50,7 +50,7 @@ The Local Notifications can be configured with the following options:
| ------------------------- | -------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----- |
| **`smallIcon`** | string | Set the default status bar icon for notifications. Icons should be placed in your app's `res/drawable` folder. The value for this option should be the drawable resource ID, which is the filename without an extension. Only available for Android. | 1.0.0 |
| **`iconColor`** | string | Set the default color of status bar icons for notifications. Only available for Android. | 1.0.0 |
-| **`sound`** | string | Set the default notification sound for notifications. It sets the default channel sound and can't be changed unless the app is uninstalled. If the audio file is not found, it will result in no sound. Only available for Android. | 1.0.0 |
+| **`sound`** | string | Set the default notification sound for notifications. On Android 8+ it sets the default channel sound and can't be changed unless the app is uninstalled. If the audio file is not found, it will result in the default system sound being played on Android 7.x and no sound on Android 8+. Only available for Android. | 1.0.0 |
| **`presentationOptions`** | LocalNotificationPresentationOption[] | This is an array of strings you can combine. Possible values in the array are: - `badge`: badge count on the app icon is updated (default value) - `sound`: the device will ring/vibrate when the notification is received - `banner`: the notification is displayed as a banner - `list`: the notification is displayed in the notification center An empty array can be provided if none of the options are desired. Only available for iOS. | 8.2.0 |
### Examples
@@ -102,13 +102,18 @@ If the device has entered [Doze](https://developer.android.com/training/monitori
* [`schedule(...)`](#schedule)
+* [`update(...)`](#update)
* [`getPending()`](#getpending)
* [`registerActionTypes(...)`](#registeractiontypes)
* [`cancel(...)`](#cancel)
+* [`cancelAll()`](#cancelall)
* [`areEnabled()`](#areenabled)
* [`getDeliveredNotifications()`](#getdeliverednotifications)
* [`removeDeliveredNotifications(...)`](#removedeliverednotifications)
+* [`removeDeliveredNotificationsById(...)`](#removedeliverednotificationsbyid)
* [`removeAllDeliveredNotifications()`](#removealldeliverednotifications)
+* [`getByIds(...)`](#getbyids)
+* [`getAll(...)`](#getall)
* [`createChannel(...)`](#createchannel)
* [`deleteChannel(...)`](#deletechannel)
* [`listChannels()`](#listchannels)
@@ -136,6 +141,11 @@ schedule(options: ScheduleOptions) => Promise
Schedule one or more local notifications.
+Starting on version 8.3.0 this requests the notification permission it needs
+before scheduling if it has not been granted yet (Android 13+
+`POST_NOTIFICATIONS`, iOS `UNUserNotificationCenter` authorization). Apps
+that already call `requestPermissions()` beforehand are unaffected.
+
| Param | Type |
| ------------- | ----------------------------------------------------------- |
| **`options`** | ScheduleOptions |
@@ -147,6 +157,28 @@ schedule(options: ScheduleOptions) => Promise
--------------------
+### update(...)
+
+```typescript
+update(options: ScheduleOptions) => Promise
+```
+
+Update one or more previously scheduled local notifications, matched by `id`.
+
+Notifications whose `id` is not currently scheduled are ignored. Like
+`schedule`, this requests the notification permission if needed.
+
+| Param | Type |
+| ------------- | ----------------------------------------------------------- |
+| **`options`** | ScheduleOptions |
+
+**Returns:** Promise<ScheduleResult>
+
+**Since:** 8.3.0
+
+--------------------
+
+
### getPending()
```typescript
@@ -198,6 +230,19 @@ Cancel pending notifications.
--------------------
+### cancelAll()
+
+```typescript
+cancelAll() => Promise
+```
+
+Cancel all pending (scheduled) notifications.
+
+**Since:** 8.3.0
+
+--------------------
+
+
### areEnabled()
```typescript
@@ -245,6 +290,28 @@ Remove the specified notifications from the notifications screen.
--------------------
+### removeDeliveredNotificationsById(...)
+
+```typescript
+removeDeliveredNotificationsById(options: RemoveByIdsOptions) => Promise
+```
+
+Remove the specified delivered notifications from the notifications screen,
+matched by `id`.
+
+Id-based counterpart of `removeDeliveredNotifications`, so callers that only
+have identifiers (e.g. the OutSystems `ClearNotifications` action) can map to
+a single method call.
+
+| Param | Type |
+| ------------- | ----------------------------------------------------------------- |
+| **`options`** | RemoveByIdsOptions |
+
+**Since:** 8.3.0
+
+--------------------
+
+
### removeAllDeliveredNotifications()
```typescript
@@ -258,6 +325,49 @@ Remove all the notifications from the notifications screen.
--------------------
+### getByIds(...)
+
+```typescript
+getByIds(options: GetByIdsOptions) => Promise
+```
+
+Get the notifications matching the supplied identifiers, whether they are
+still scheduled (pending) or already delivered.
+
+| Param | Type |
+| ------------- | ----------------------------------------------------------- |
+| **`options`** | GetByIdsOptions |
+
+**Returns:** Promise<GetNotificationsResult>
+
+**Since:** 8.3.0
+
+--------------------
+
+
+### getAll(...)
+
+```typescript
+getAll(options?: GetAllOptions | undefined) => Promise
+```
+
+Get all notifications known to the plugin, optionally filtered by state.
+
+When `state` is omitted both scheduled and delivered notifications are
+returned. `SCHEDULED` returns pending notifications; `TRIGGERED` returns
+delivered notifications.
+
+| Param | Type |
+| ------------- | ------------------------------------------------------- |
+| **`options`** | GetAllOptions |
+
+**Returns:** Promise<GetNotificationsResult>
+
+**Since:** 8.3.0
+
+--------------------
+
+
### createChannel(...)
```typescript
@@ -441,9 +551,10 @@ Remove all listeners for this plugin.
#### ScheduleResult
-| Prop | Type | Description | Since |
-| ------------------- | ------------------------------------------ | ------------------------------------ | ----- |
-| **`notifications`** | LocalNotificationDescriptor[] | The list of scheduled notifications. | 1.0.0 |
+| Prop | Type | Description | Since |
+| ------------------- | ----------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----- |
+| **`notifications`** | LocalNotificationDescriptor[] | The list of scheduled notifications. | 1.0.0 |
+| **`warning`** | ScheduleWarning | Set when at least one notification in this call had `isExactNotification` `true` (the default) but the exact-alarm permission was not granted: it was scheduled as an inexact alarm instead. Absent on `update()` calls and whenever every applicable notification got its requested exactness. | 8.3.0 |
#### LocalNotificationDescriptor
@@ -455,6 +566,16 @@ The object that describes a local notification.
| **`id`** | number | The notification identifier. | 1.0.0 |
+#### ScheduleWarning
+
+A non-fatal warning returned alongside a successful result.
+
+| Prop | Type | Description | Since |
+| ------------- | ------------------- | -------------------------------------------- | ----- |
+| **`code`** | string | The `OS-PLUG-LNOT-NNNN` warning code. | 8.3.0 |
+| **`message`** | string | A human-readable description of the warning. | 8.3.0 |
+
+
#### ScheduleOptions
| Prop | Type | Description | Since |
@@ -464,31 +585,36 @@ The object that describes a local notification.
#### LocalNotificationSchema
-| Prop | Type | Description | Since |
-| ----------------------- | --------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----- |
-| **`title`** | string | The title of the notification. | 1.0.0 |
-| **`body`** | string | The body of the notification, shown below the title. | 1.0.0 |
-| **`largeBody`** | string | Sets a multiline text block for display in a big text notification style. | 1.0.0 |
-| **`summaryText`** | string | Used to set the summary text detail in inbox and big text notification styles. Only available for Android. | 1.0.0 |
-| **`id`** | number | The notification identifier. On Android it's a 32-bit int. So the value should be between -2147483648 and 2147483647 inclusive. | 1.0.0 |
-| **`schedule`** | Schedule | Schedule this notification for a later time. | 1.0.0 |
-| **`sound`** | string | Name of the audio file to play when this notification is displayed. Include the file extension with the filename. The file should be in the app bundle. Recommended format is `.wav`. Only available for iOS. For Android, use channelId of a channel configured with the desired sound. If the sound file is not found, (i.e. empty string or wrong name) the default system notification sound will be used. If not provided, it will produce no sound. | 1.0.0 |
-| **`smallIcon`** | string | Set a custom status bar icon. If set, this overrides the `smallIcon` option from Capacitor configuration. Icons should be placed in your app's `res/drawable` folder. The value for this option should be the drawable resource ID, which is the filename without an extension. Only available for Android. | 1.0.0 |
-| **`largeIcon`** | string | Set a large icon for notifications. Icons should be placed in your app's `res/drawable` folder. The value for this option should be the drawable resource ID, which is the filename without an extension. Only available for Android. | 1.0.0 |
-| **`iconColor`** | string | Set the color of the notification icon. Only available for Android. | 1.0.0 |
-| **`attachments`** | Attachment[] | Set attachments for this notification. | 1.0.0 |
-| **`actionTypeId`** | string | Associate an action type with this notification. | 1.0.0 |
-| **`extra`** | any | Set extra data to store within this notification. | 1.0.0 |
-| **`threadIdentifier`** | string | Used to group multiple notifications. Sets `threadIdentifier` on the [`UNMutableNotificationContent`](https://developer.apple.com/documentation/usernotifications/unmutablenotificationcontent). Only available for iOS. | 1.0.0 |
-| **`relevanceScore`** | number | The score the system uses to determine if the notification is the featured notification when the system groups the app's notifications. The value must be between 0 and 1, where 0 is the least relevant and 1 is the most relevant. The default value is 0. Sets `relevanceScore` on the [`UNMutableNotificationContent`](https://developer.apple.com/documentation/usernotifications/unmutablenotificationcontent). Only available for iOS. | 8.1.0 |
-| **`interruptionLevel`** | InterruptionLevel | The interruption level that indicates the priority and delivery timing of a notification. Sets `interruptionLevel` on the [`UNMutableNotificationContent`](https://developer.apple.com/documentation/usernotifications/unmutablenotificationcontent). Only available for iOS. | 8.1.0 |
-| **`group`** | string | Used to group multiple notifications. Calls `setGroup()` on [`NotificationCompat.Builder`](https://developer.android.com/reference/androidx/core/app/NotificationCompat.Builder) with the provided value. Only available for Android. | 1.0.0 |
-| **`groupSummary`** | boolean | If true, this notification becomes the summary for a group of notifications. Calls `setGroupSummary()` on [`NotificationCompat.Builder`](https://developer.android.com/reference/androidx/core/app/NotificationCompat.Builder) with the provided value. Only available for Android when using `group`. | 1.0.0 |
-| **`channelId`** | string | Specifies the channel the notification should be delivered on. If channel with the given name does not exist then the notification will not fire. If not provided, it will use the default channel. Calls `setChannelId()` on [`NotificationCompat.Builder`](https://developer.android.com/reference/androidx/core/app/NotificationCompat.Builder) with the provided value. Only available for Android. | 1.0.0 |
-| **`ongoing`** | boolean | If true, the notification can't be swiped away. Calls `setOngoing()` on [`NotificationCompat.Builder`](https://developer.android.com/reference/androidx/core/app/NotificationCompat.Builder) with the provided value. Only available for Android. | 1.0.0 |
-| **`autoCancel`** | boolean | If true, the notification is canceled when the user clicks on it. Calls `setAutoCancel()` on [`NotificationCompat.Builder`](https://developer.android.com/reference/androidx/core/app/NotificationCompat.Builder) with the provided value. Only available for Android. | 1.0.0 |
-| **`inboxList`** | string[] | Sets a list of strings for display in an inbox style notification. Up to 5 strings are allowed. Only available for Android. | 1.0.0 |
-| **`silent`** | boolean | If true, notification will not appear while app is in the foreground. Only available for iOS. | 5.0.0 |
+| Prop | Type | Description | Default | Since |
+| ------------------------- | --------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------ | ----- |
+| **`title`** | string | The title of the notification. | | 1.0.0 |
+| **`body`** | string | The body of the notification, shown below the title. | | 1.0.0 |
+| **`largeBody`** | string | Sets a multiline text block for display in a big text notification style. | | 1.0.0 |
+| **`summaryText`** | string | Used to set the summary text detail in inbox and big text notification styles. Only available for Android. | | 1.0.0 |
+| **`id`** | number | The notification identifier. On Android it's a 32-bit int. So the value should be between -2147483648 and 2147483647 inclusive. | | 1.0.0 |
+| **`schedule`** | Schedule | Schedule this notification for a later time. | | 1.0.0 |
+| **`sound`** | string | Name of the audio file to play when this notification is displayed. Include the file extension with the filename. On iOS, the file should be in the app bundle. On Android, the file should be in res/raw folder. Recommended format is `.wav` because is supported by both iOS and Android. Only available for iOS and Android 7.x. For Android 8+ use channelId of a channel configured with the desired sound. If the sound file is not found, (i.e. empty string or wrong name) the default system notification sound will be used. If not provided, it will produce the default sound on Android and no sound on iOS. | | 1.0.0 |
+| **`smallIcon`** | string | Set a custom status bar icon. If set, this overrides the `smallIcon` option from Capacitor configuration. Icons should be placed in your app's `res/drawable` folder. The value for this option should be the drawable resource ID, which is the filename without an extension. Only available for Android. | | 1.0.0 |
+| **`largeIcon`** | string | Set a large icon for notifications. Icons should be placed in your app's `res/drawable` folder. The value for this option should be the drawable resource ID, which is the filename without an extension. Only available for Android. | | 1.0.0 |
+| **`iconColor`** | string | Set the color of the notification icon. Only available for Android. | | 1.0.0 |
+| **`attachments`** | Attachment[] | Set attachments for this notification. | | 1.0.0 |
+| **`actionTypeId`** | string | Associate an action type with this notification. | | 1.0.0 |
+| **`extra`** | any | Set extra data to store within this notification. | | 1.0.0 |
+| **`threadIdentifier`** | string | Used to group multiple notifications. Sets `threadIdentifier` on the [`UNMutableNotificationContent`](https://developer.apple.com/documentation/usernotifications/unmutablenotificationcontent). Only available for iOS. | | 1.0.0 |
+| **`summaryArgument`** | string | The string this notification adds to the category's summary format string. Sets `summaryArgument` on the [`UNMutableNotificationContent`](https://developer.apple.com/documentation/usernotifications/unmutablenotificationcontent). Only available for iOS. | | 1.0.0 |
+| **`relevanceScore`** | number | The score the system uses to determine if the notification is the featured notification when the system groups the app's notifications. The value must be between 0 and 1, where 0 is the least relevant and 1 is the most relevant. The default value is 0. Sets `relevanceScore` on the [`UNMutableNotificationContent`](https://developer.apple.com/documentation/usernotifications/unmutablenotificationcontent). Only available for iOS. | | 8.1.0 |
+| **`interruptionLevel`** | InterruptionLevel | The interruption level that indicates the priority and delivery timing of a notification. Sets `interruptionLevel` on the [`UNMutableNotificationContent`](https://developer.apple.com/documentation/usernotifications/unmutablenotificationcontent). Only available for iOS. | | 8.1.0 |
+| **`group`** | string | Used to group multiple notifications. Calls `setGroup()` on [`NotificationCompat.Builder`](https://developer.android.com/reference/androidx/core/app/NotificationCompat.Builder) with the provided value. Only available for Android. | | 1.0.0 |
+| **`groupSummary`** | boolean | If true, this notification becomes the summary for a group of notifications. Calls `setGroupSummary()` on [`NotificationCompat.Builder`](https://developer.android.com/reference/androidx/core/app/NotificationCompat.Builder) with the provided value. Only available for Android when using `group`. | | 1.0.0 |
+| **`channelId`** | string | Specifies the channel the notification should be delivered on. If channel with the given name does not exist then the notification will not fire. If not provided, it will use the default channel. Calls `setChannelId()` on [`NotificationCompat.Builder`](https://developer.android.com/reference/androidx/core/app/NotificationCompat.Builder) with the provided value. Only available for Android 8+. | | 1.0.0 |
+| **`ongoing`** | boolean | If true, the notification can't be swiped away. Calls `setOngoing()` on [`NotificationCompat.Builder`](https://developer.android.com/reference/androidx/core/app/NotificationCompat.Builder) with the provided value. Only available for Android. | | 1.0.0 |
+| **`autoCancel`** | boolean | If true, the notification is canceled when the user clicks on it. Calls `setAutoCancel()` on [`NotificationCompat.Builder`](https://developer.android.com/reference/androidx/core/app/NotificationCompat.Builder) with the provided value. Only available for Android. | | 1.0.0 |
+| **`inboxList`** | string[] | Sets a list of strings for display in an inbox style notification. Up to 5 strings are allowed. Only available for Android. | | 1.0.0 |
+| **`silent`** | boolean | If true, notification will not appear while app is in the foreground. Only available for iOS. | | 5.0.0 |
+| **`badge`** | number | The number to display on the app icon badge when this notification is delivered. On iOS this sets the badge count on the [`UNMutableNotificationContent`](https://developer.apple.com/documentation/usernotifications/unmutablenotificationcontent). On Android this calls `setNumber()` on [`NotificationCompat.Builder`](https://developer.android.com/reference/androidx/core/app/NotificationCompat.Builder). | | 8.3.0 |
+| **`foreground`** | boolean | Whether the notification should be presented while the app is in the foreground. On iOS `true` forces the notification to be shown even while the app is foregrounded, while `false` suppresses it (it is still delivered to the `localNotificationReceived` listener). This is independent of `silent`; when both are provided, `foreground` takes precedence. On Android it raises the notification priority so it can present as a heads-up notification. | | 8.3.0 |
+| **`isExactNotification`** | boolean | Whether this notification should be scheduled with an exact alarm. Only available for Android. Defaults to `true`: on `schedule()` (API 31+), if the app isn't yet allowed to schedule exact alarms the system "Alarms & reminders" settings screen is opened so the user can grant it — regardless of `isExactMandatory`. If the user still declines, the notification falls back to an inexact alarm (unless `isExactMandatory` is also set, in which case the call is rejected instead); a fallback like this sets `ScheduleResult.warning`. `update()` never prompts and falls back silently. Set to `false` to schedule this notification as inexact outright, regardless of permission state. | true | 8.3.0 |
+| **`isExactMandatory`** | boolean | Whether an exact alarm is mandatory for this notification. Only available for Android, and only meaningful when `isExactNotification` is `true` (the default) and on `schedule()` calls. If the exact-alarm permission is denied and any notification being scheduled has this set to `true`, the whole `schedule()` call is rejected instead of falling back to an inexact alarm. Has no effect on `update()`: it never enforces this, and simply falls back to inexact like a non-mandatory notification would. | false | 8.3.0 |
#### Schedule
@@ -687,6 +813,34 @@ An action that can be taken when a notification is displayed.
| **`sound`** | string | Sound that was used when the notification was displayed. Only available for iOS. | 4.0.0 |
+#### RemoveByIdsOptions
+
+| Prop | Type | Description | Since |
+| --------- | --------------------- | --------------------------------------------------------- | ----- |
+| **`ids`** | number[] | The identifiers of the delivered notifications to remove. | 8.3.0 |
+
+
+#### GetNotificationsResult
+
+| Prop | Type | Description | Since |
+| ------------------- | -------------------------------------- | --------------------------------------------- | ----- |
+| **`notifications`** | LocalNotificationSchema[] | The list of notifications matching the query. | 8.3.0 |
+
+
+#### GetByIdsOptions
+
+| Prop | Type | Description | Since |
+| --------- | --------------------- | ------------------------------------------------- | ----- |
+| **`ids`** | number[] | The identifiers of the notifications to retrieve. | 8.3.0 |
+
+
+#### GetAllOptions
+
+| Prop | Type | Description | Since |
+| ----------- | --------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------ | ----- |
+| **`state`** | NotificationState | Filter the returned notifications by state. When omitted, both scheduled and delivered notifications are returned. | 8.3.0 |
+
+
#### Channel
| Prop | Type | Description | Default | Since |
@@ -763,6 +917,16 @@ The interruption level that indicates the priority and delivery timing of a noti
'active' | 'critical' | 'passive' | 'timeSensitive'
+#### NotificationState
+
+The notification state used to filter `getAll`.
+
+- `SCHEDULED`: notifications that are pending delivery.
+- `TRIGGERED`: notifications that have already been delivered.
+
+'SCHEDULED' | 'TRIGGERED'
+
+
#### Importance
The importance level. For more details, see the [Android Developer Docs](https://developer.android.com/reference/android/app/NotificationManager#IMPORTANCE_DEFAULT)
diff --git a/scripts/api-v8.mjs b/scripts/api-v8.mjs
index b5e087a0..50534a0a 100644
--- a/scripts/api-v8.mjs
+++ b/scripts/api-v8.mjs
@@ -206,8 +206,8 @@ const pluginApis = [
isCore: false,
isExperimental: false,
npmScope: '@capacitor',
- editUrl: 'https://github.com/ionic-team/capacitor-plugins/blob/main/local-notifications/README.md',
- editApiUrl: 'https://github.com/ionic-team/capacitor-plugins/blob/main/local-notifications/src/definitions.ts',
+ editUrl: 'https://github.com/ionic-team/capacitor-local-notifications/blob/main/README.md',
+ editApiUrl: 'https://github.com/ionic-team/capacitor-local-notifications/blob/main/src/definitions.ts',
},
{
id: 'motion',
diff --git a/scripts/api.mjs b/scripts/api.mjs
index ade8b12a..6a884f6c 100644
--- a/scripts/api.mjs
+++ b/scripts/api.mjs
@@ -213,8 +213,9 @@ const pluginApis = [
isCore: false,
isExperimental: false,
npmScope: '@capacitor',
- editUrl: 'https://github.com/ionic-team/capacitor-plugins/blob/next/local-notifications/README.md',
- editApiUrl: 'https://github.com/ionic-team/capacitor-plugins/blob/next/local-notifications/src/definitions.ts',
+ editUrl: 'https://github.com/ionic-team/capacitor-local-notifications/blob/main/README.md',
+ editApiUrl: 'https://github.com/ionic-team/capacitor-local-notifications/blob/main/src/definitions.ts',
+ tag: 'latest',
},
{
id: 'motion',
diff --git a/versioned_docs/version-v8/apis/local-notifications.md b/versioned_docs/version-v8/apis/local-notifications.md
index 2c68d100..728788ff 100644
--- a/versioned_docs/version-v8/apis/local-notifications.md
+++ b/versioned_docs/version-v8/apis/local-notifications.md
@@ -1,8 +1,8 @@
---
title: Local Notifications Capacitor Plugin API
description: The Local Notifications API provides a way to schedule device notifications locally (i.e. without a server sending push notifications).
-custom_edit_url: https://github.com/ionic-team/capacitor-plugins/blob/main/local-notifications/README.md
-editApiUrl: https://github.com/ionic-team/capacitor-plugins/blob/main/local-notifications/src/definitions.ts
+custom_edit_url: https://github.com/ionic-team/capacitor-local-notifications/blob/main/README.md
+editApiUrl: https://github.com/ionic-team/capacitor-local-notifications/blob/main/src/definitions.ts
sidebar_label: Local Notifications
---
@@ -102,13 +102,18 @@ If the device has entered [Doze](https://developer.android.com/training/monitori
* [`schedule(...)`](#schedule)
+* [`update(...)`](#update)
* [`getPending()`](#getpending)
* [`registerActionTypes(...)`](#registeractiontypes)
* [`cancel(...)`](#cancel)
+* [`cancelAll()`](#cancelall)
* [`areEnabled()`](#areenabled)
* [`getDeliveredNotifications()`](#getdeliverednotifications)
* [`removeDeliveredNotifications(...)`](#removedeliverednotifications)
+* [`removeDeliveredNotificationsById(...)`](#removedeliverednotificationsbyid)
* [`removeAllDeliveredNotifications()`](#removealldeliverednotifications)
+* [`getByIds(...)`](#getbyids)
+* [`getAll(...)`](#getall)
* [`createChannel(...)`](#createchannel)
* [`deleteChannel(...)`](#deletechannel)
* [`listChannels()`](#listchannels)
@@ -136,6 +141,11 @@ schedule(options: ScheduleOptions) => Promise
Schedule one or more local notifications.
+Starting on version 8.3.0 this requests the notification permission it needs
+before scheduling if it has not been granted yet (Android 13+
+`POST_NOTIFICATIONS`, iOS `UNUserNotificationCenter` authorization). Apps
+that already call `requestPermissions()` beforehand are unaffected.
+
| Param | Type |
| ------------- | ----------------------------------------------------------- |
| **`options`** | ScheduleOptions |
@@ -147,6 +157,28 @@ schedule(options: ScheduleOptions) => Promise
--------------------
+### update(...)
+
+```typescript
+update(options: ScheduleOptions) => Promise
+```
+
+Update one or more previously scheduled local notifications, matched by `id`.
+
+Notifications whose `id` is not currently scheduled are ignored. Like
+`schedule`, this requests the notification permission if needed.
+
+| Param | Type |
+| ------------- | ----------------------------------------------------------- |
+| **`options`** | ScheduleOptions |
+
+**Returns:** Promise<ScheduleResult>
+
+**Since:** 8.3.0
+
+--------------------
+
+
### getPending()
```typescript
@@ -198,6 +230,19 @@ Cancel pending notifications.
--------------------
+### cancelAll()
+
+```typescript
+cancelAll() => Promise
+```
+
+Cancel all pending (scheduled) notifications.
+
+**Since:** 8.3.0
+
+--------------------
+
+
### areEnabled()
```typescript
@@ -245,6 +290,28 @@ Remove the specified notifications from the notifications screen.
--------------------
+### removeDeliveredNotificationsById(...)
+
+```typescript
+removeDeliveredNotificationsById(options: RemoveByIdsOptions) => Promise
+```
+
+Remove the specified delivered notifications from the notifications screen,
+matched by `id`.
+
+Id-based counterpart of `removeDeliveredNotifications`, so callers that only
+have identifiers (e.g. the OutSystems `ClearNotifications` action) can map to
+a single method call.
+
+| Param | Type |
+| ------------- | ----------------------------------------------------------------- |
+| **`options`** | RemoveByIdsOptions |
+
+**Since:** 8.3.0
+
+--------------------
+
+
### removeAllDeliveredNotifications()
```typescript
@@ -258,6 +325,49 @@ Remove all the notifications from the notifications screen.
--------------------
+### getByIds(...)
+
+```typescript
+getByIds(options: GetByIdsOptions) => Promise
+```
+
+Get the notifications matching the supplied identifiers, whether they are
+still scheduled (pending) or already delivered.
+
+| Param | Type |
+| ------------- | ----------------------------------------------------------- |
+| **`options`** | GetByIdsOptions |
+
+**Returns:** Promise<GetNotificationsResult>
+
+**Since:** 8.3.0
+
+--------------------
+
+
+### getAll(...)
+
+```typescript
+getAll(options?: GetAllOptions | undefined) => Promise
+```
+
+Get all notifications known to the plugin, optionally filtered by state.
+
+When `state` is omitted both scheduled and delivered notifications are
+returned. `SCHEDULED` returns pending notifications; `TRIGGERED` returns
+delivered notifications.
+
+| Param | Type |
+| ------------- | ------------------------------------------------------- |
+| **`options`** | GetAllOptions |
+
+**Returns:** Promise<GetNotificationsResult>
+
+**Since:** 8.3.0
+
+--------------------
+
+
### createChannel(...)
```typescript
@@ -441,9 +551,10 @@ Remove all listeners for this plugin.
#### ScheduleResult
-| Prop | Type | Description | Since |
-| ------------------- | ------------------------------------------ | ------------------------------------ | ----- |
-| **`notifications`** | LocalNotificationDescriptor[] | The list of scheduled notifications. | 1.0.0 |
+| Prop | Type | Description | Since |
+| ------------------- | ----------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----- |
+| **`notifications`** | LocalNotificationDescriptor[] | The list of scheduled notifications. | 1.0.0 |
+| **`warning`** | ScheduleWarning | Set when at least one notification in this call had `isExactNotification` `true` (the default) but the exact-alarm permission was not granted: it was scheduled as an inexact alarm instead. Absent on `update()` calls and whenever every applicable notification got its requested exactness. | 8.3.0 |
#### LocalNotificationDescriptor
@@ -455,6 +566,16 @@ The object that describes a local notification.
| **`id`** | number | The notification identifier. | 1.0.0 |
+#### ScheduleWarning
+
+A non-fatal warning returned alongside a successful result.
+
+| Prop | Type | Description | Since |
+| ------------- | ------------------- | -------------------------------------------- | ----- |
+| **`code`** | string | The `OS-PLUG-LNOT-NNNN` warning code. | 8.3.0 |
+| **`message`** | string | A human-readable description of the warning. | 8.3.0 |
+
+
#### ScheduleOptions
| Prop | Type | Description | Since |
@@ -464,32 +585,36 @@ The object that describes a local notification.
#### LocalNotificationSchema
-| Prop | Type | Description | Since |
-| ----------------------- | --------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----- |
-| **`title`** | string | The title of the notification. | 1.0.0 |
-| **`body`** | string | The body of the notification, shown below the title. | 1.0.0 |
-| **`largeBody`** | string | Sets a multiline text block for display in a big text notification style. | 1.0.0 |
-| **`summaryText`** | string | Used to set the summary text detail in inbox and big text notification styles. Only available for Android. | 1.0.0 |
-| **`id`** | number | The notification identifier. On Android it's a 32-bit int. So the value should be between -2147483648 and 2147483647 inclusive. | 1.0.0 |
-| **`schedule`** | Schedule | Schedule this notification for a later time. | 1.0.0 |
-| **`sound`** | string | Name of the audio file to play when this notification is displayed. Include the file extension with the filename. On iOS, the file should be in the app bundle. On Android, the file should be in res/raw folder. Recommended format is `.wav` because is supported by both iOS and Android. Only available for iOS and Android 7.x. For Android 8+ use channelId of a channel configured with the desired sound. If the sound file is not found, (i.e. empty string or wrong name) the default system notification sound will be used. If not provided, it will produce the default sound on Android and no sound on iOS. | 1.0.0 |
-| **`smallIcon`** | string | Set a custom status bar icon. If set, this overrides the `smallIcon` option from Capacitor configuration. Icons should be placed in your app's `res/drawable` folder. The value for this option should be the drawable resource ID, which is the filename without an extension. Only available for Android. | 1.0.0 |
-| **`largeIcon`** | string | Set a large icon for notifications. Icons should be placed in your app's `res/drawable` folder. The value for this option should be the drawable resource ID, which is the filename without an extension. Only available for Android. | 1.0.0 |
-| **`iconColor`** | string | Set the color of the notification icon. Only available for Android. | 1.0.0 |
-| **`attachments`** | Attachment[] | Set attachments for this notification. | 1.0.0 |
-| **`actionTypeId`** | string | Associate an action type with this notification. | 1.0.0 |
-| **`extra`** | any | Set extra data to store within this notification. | 1.0.0 |
-| **`threadIdentifier`** | string | Used to group multiple notifications. Sets `threadIdentifier` on the [`UNMutableNotificationContent`](https://developer.apple.com/documentation/usernotifications/unmutablenotificationcontent). Only available for iOS. | 1.0.0 |
-| **`summaryArgument`** | string | The string this notification adds to the category's summary format string. Sets `summaryArgument` on the [`UNMutableNotificationContent`](https://developer.apple.com/documentation/usernotifications/unmutablenotificationcontent). Only available for iOS. | 1.0.0 |
-| **`relevanceScore`** | number | The score the system uses to determine if the notification is the featured notification when the system groups the app's notifications. The value must be between 0 and 1, where 0 is the least relevant and 1 is the most relevant. The default value is 0. Sets `relevanceScore` on the [`UNMutableNotificationContent`](https://developer.apple.com/documentation/usernotifications/unmutablenotificationcontent). Only available for iOS. | 8.1.0 |
-| **`interruptionLevel`** | InterruptionLevel | The interruption level that indicates the priority and delivery timing of a notification. Sets `interruptionLevel` on the [`UNMutableNotificationContent`](https://developer.apple.com/documentation/usernotifications/unmutablenotificationcontent). Only available for iOS. | 8.1.0 |
-| **`group`** | string | Used to group multiple notifications. Calls `setGroup()` on [`NotificationCompat.Builder`](https://developer.android.com/reference/androidx/core/app/NotificationCompat.Builder) with the provided value. Only available for Android. | 1.0.0 |
-| **`groupSummary`** | boolean | If true, this notification becomes the summary for a group of notifications. Calls `setGroupSummary()` on [`NotificationCompat.Builder`](https://developer.android.com/reference/androidx/core/app/NotificationCompat.Builder) with the provided value. Only available for Android when using `group`. | 1.0.0 |
-| **`channelId`** | string | Specifies the channel the notification should be delivered on. If channel with the given name does not exist then the notification will not fire. If not provided, it will use the default channel. Calls `setChannelId()` on [`NotificationCompat.Builder`](https://developer.android.com/reference/androidx/core/app/NotificationCompat.Builder) with the provided value. Only available for Android 8+. | 1.0.0 |
-| **`ongoing`** | boolean | If true, the notification can't be swiped away. Calls `setOngoing()` on [`NotificationCompat.Builder`](https://developer.android.com/reference/androidx/core/app/NotificationCompat.Builder) with the provided value. Only available for Android. | 1.0.0 |
-| **`autoCancel`** | boolean | If true, the notification is canceled when the user clicks on it. Calls `setAutoCancel()` on [`NotificationCompat.Builder`](https://developer.android.com/reference/androidx/core/app/NotificationCompat.Builder) with the provided value. Only available for Android. | 1.0.0 |
-| **`inboxList`** | string[] | Sets a list of strings for display in an inbox style notification. Up to 5 strings are allowed. Only available for Android. | 1.0.0 |
-| **`silent`** | boolean | If true, notification will not appear while app is in the foreground. Only available for iOS. | 5.0.0 |
+| Prop | Type | Description | Default | Since |
+| ------------------------- | --------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------ | ----- |
+| **`title`** | string | The title of the notification. | | 1.0.0 |
+| **`body`** | string | The body of the notification, shown below the title. | | 1.0.0 |
+| **`largeBody`** | string | Sets a multiline text block for display in a big text notification style. | | 1.0.0 |
+| **`summaryText`** | string | Used to set the summary text detail in inbox and big text notification styles. Only available for Android. | | 1.0.0 |
+| **`id`** | number | The notification identifier. On Android it's a 32-bit int. So the value should be between -2147483648 and 2147483647 inclusive. | | 1.0.0 |
+| **`schedule`** | Schedule | Schedule this notification for a later time. | | 1.0.0 |
+| **`sound`** | string | Name of the audio file to play when this notification is displayed. Include the file extension with the filename. On iOS, the file should be in the app bundle. On Android, the file should be in res/raw folder. Recommended format is `.wav` because is supported by both iOS and Android. Only available for iOS and Android 7.x. For Android 8+ use channelId of a channel configured with the desired sound. If the sound file is not found, (i.e. empty string or wrong name) the default system notification sound will be used. If not provided, it will produce the default sound on Android and no sound on iOS. | | 1.0.0 |
+| **`smallIcon`** | string | Set a custom status bar icon. If set, this overrides the `smallIcon` option from Capacitor configuration. Icons should be placed in your app's `res/drawable` folder. The value for this option should be the drawable resource ID, which is the filename without an extension. Only available for Android. | | 1.0.0 |
+| **`largeIcon`** | string | Set a large icon for notifications. Icons should be placed in your app's `res/drawable` folder. The value for this option should be the drawable resource ID, which is the filename without an extension. Only available for Android. | | 1.0.0 |
+| **`iconColor`** | string | Set the color of the notification icon. Only available for Android. | | 1.0.0 |
+| **`attachments`** | Attachment[] | Set attachments for this notification. | | 1.0.0 |
+| **`actionTypeId`** | string | Associate an action type with this notification. | | 1.0.0 |
+| **`extra`** | any | Set extra data to store within this notification. | | 1.0.0 |
+| **`threadIdentifier`** | string | Used to group multiple notifications. Sets `threadIdentifier` on the [`UNMutableNotificationContent`](https://developer.apple.com/documentation/usernotifications/unmutablenotificationcontent). Only available for iOS. | | 1.0.0 |
+| **`summaryArgument`** | string | The string this notification adds to the category's summary format string. Sets `summaryArgument` on the [`UNMutableNotificationContent`](https://developer.apple.com/documentation/usernotifications/unmutablenotificationcontent). Only available for iOS. | | 1.0.0 |
+| **`relevanceScore`** | number | The score the system uses to determine if the notification is the featured notification when the system groups the app's notifications. The value must be between 0 and 1, where 0 is the least relevant and 1 is the most relevant. The default value is 0. Sets `relevanceScore` on the [`UNMutableNotificationContent`](https://developer.apple.com/documentation/usernotifications/unmutablenotificationcontent). Only available for iOS. | | 8.1.0 |
+| **`interruptionLevel`** | InterruptionLevel | The interruption level that indicates the priority and delivery timing of a notification. Sets `interruptionLevel` on the [`UNMutableNotificationContent`](https://developer.apple.com/documentation/usernotifications/unmutablenotificationcontent). Only available for iOS. | | 8.1.0 |
+| **`group`** | string | Used to group multiple notifications. Calls `setGroup()` on [`NotificationCompat.Builder`](https://developer.android.com/reference/androidx/core/app/NotificationCompat.Builder) with the provided value. Only available for Android. | | 1.0.0 |
+| **`groupSummary`** | boolean | If true, this notification becomes the summary for a group of notifications. Calls `setGroupSummary()` on [`NotificationCompat.Builder`](https://developer.android.com/reference/androidx/core/app/NotificationCompat.Builder) with the provided value. Only available for Android when using `group`. | | 1.0.0 |
+| **`channelId`** | string | Specifies the channel the notification should be delivered on. If channel with the given name does not exist then the notification will not fire. If not provided, it will use the default channel. Calls `setChannelId()` on [`NotificationCompat.Builder`](https://developer.android.com/reference/androidx/core/app/NotificationCompat.Builder) with the provided value. Only available for Android 8+. | | 1.0.0 |
+| **`ongoing`** | boolean | If true, the notification can't be swiped away. Calls `setOngoing()` on [`NotificationCompat.Builder`](https://developer.android.com/reference/androidx/core/app/NotificationCompat.Builder) with the provided value. Only available for Android. | | 1.0.0 |
+| **`autoCancel`** | boolean | If true, the notification is canceled when the user clicks on it. Calls `setAutoCancel()` on [`NotificationCompat.Builder`](https://developer.android.com/reference/androidx/core/app/NotificationCompat.Builder) with the provided value. Only available for Android. | | 1.0.0 |
+| **`inboxList`** | string[] | Sets a list of strings for display in an inbox style notification. Up to 5 strings are allowed. Only available for Android. | | 1.0.0 |
+| **`silent`** | boolean | If true, notification will not appear while app is in the foreground. Only available for iOS. | | 5.0.0 |
+| **`badge`** | number | The number to display on the app icon badge when this notification is delivered. On iOS this sets the badge count on the [`UNMutableNotificationContent`](https://developer.apple.com/documentation/usernotifications/unmutablenotificationcontent). On Android this calls `setNumber()` on [`NotificationCompat.Builder`](https://developer.android.com/reference/androidx/core/app/NotificationCompat.Builder). | | 8.3.0 |
+| **`foreground`** | boolean | Whether the notification should be presented while the app is in the foreground. On iOS `true` forces the notification to be shown even while the app is foregrounded, while `false` suppresses it (it is still delivered to the `localNotificationReceived` listener). This is independent of `silent`; when both are provided, `foreground` takes precedence. On Android it raises the notification priority so it can present as a heads-up notification. | | 8.3.0 |
+| **`isExactNotification`** | boolean | Whether this notification should be scheduled with an exact alarm. Only available for Android. Defaults to `true`: on `schedule()` (API 31+), if the app isn't yet allowed to schedule exact alarms the system "Alarms & reminders" settings screen is opened so the user can grant it — regardless of `isExactMandatory`. If the user still declines, the notification falls back to an inexact alarm (unless `isExactMandatory` is also set, in which case the call is rejected instead); a fallback like this sets `ScheduleResult.warning`. `update()` never prompts and falls back silently. Set to `false` to schedule this notification as inexact outright, regardless of permission state. | true | 8.3.0 |
+| **`isExactMandatory`** | boolean | Whether an exact alarm is mandatory for this notification. Only available for Android, and only meaningful when `isExactNotification` is `true` (the default) and on `schedule()` calls. If the exact-alarm permission is denied and any notification being scheduled has this set to `true`, the whole `schedule()` call is rejected instead of falling back to an inexact alarm. Has no effect on `update()`: it never enforces this, and simply falls back to inexact like a non-mandatory notification would. | false | 8.3.0 |
#### Schedule
@@ -688,6 +813,34 @@ An action that can be taken when a notification is displayed.
| **`sound`** | string | Sound that was used when the notification was displayed. Only available for iOS. | 4.0.0 |
+#### RemoveByIdsOptions
+
+| Prop | Type | Description | Since |
+| --------- | --------------------- | --------------------------------------------------------- | ----- |
+| **`ids`** | number[] | The identifiers of the delivered notifications to remove. | 8.3.0 |
+
+
+#### GetNotificationsResult
+
+| Prop | Type | Description | Since |
+| ------------------- | -------------------------------------- | --------------------------------------------- | ----- |
+| **`notifications`** | LocalNotificationSchema[] | The list of notifications matching the query. | 8.3.0 |
+
+
+#### GetByIdsOptions
+
+| Prop | Type | Description | Since |
+| --------- | --------------------- | ------------------------------------------------- | ----- |
+| **`ids`** | number[] | The identifiers of the notifications to retrieve. | 8.3.0 |
+
+
+#### GetAllOptions
+
+| Prop | Type | Description | Since |
+| ----------- | --------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------ | ----- |
+| **`state`** | NotificationState | Filter the returned notifications by state. When omitted, both scheduled and delivered notifications are returned. | 8.3.0 |
+
+
#### Channel
| Prop | Type | Description | Default | Since |
@@ -764,6 +917,16 @@ The interruption level that indicates the priority and delivery timing of a noti
'active' | 'critical' | 'passive' | 'timeSensitive'
+#### NotificationState
+
+The notification state used to filter `getAll`.
+
+- `SCHEDULED`: notifications that are pending delivery.
+- `TRIGGERED`: notifications that have already been delivered.
+
+'SCHEDULED' | 'TRIGGERED'
+
+
#### Importance
The importance level. For more details, see the [Android Developer Docs](https://developer.android.com/reference/android/app/NotificationManager#IMPORTANCE_DEFAULT)