diff --git a/src/@awesome-cordova-plugins/plugins/local-notifications/index.ts b/src/@awesome-cordova-plugins/plugins/local-notifications/index.ts index 8cd8af29b..d0708ff84 100755 --- a/src/@awesome-cordova-plugins/plugins/local-notifications/index.ts +++ b/src/@awesome-cordova-plugins/plugins/local-notifications/index.ts @@ -16,6 +16,75 @@ export enum ELocalNotificationTriggerUnit { WEEK_OF_MONTH = 'weekOfMonth', } +/** + * ANDROID ONLY + * Values for the `androidAlarmType` property. + * + * @see https://developer.android.com/develop/background-work/services/alarms/schedule#type + */ +export enum ELocalNotificationAndroidAlarmType { + RTC_WAKEUP = 'RTC_WAKEUP', + RTC = 'RTC', + /** Not supported */ + ELAPSED_REALTIME_WAKEUP = 'ELAPSED_REALTIME_WAKEUP', + /** Not supported */ + ELAPSED_REALTIME = 'ELAPSED_REALTIME', +} + +/** + * ANDROID ONLY + * Values for the `androidChannelImportance` property. + * + * @see https://developer.android.com/develop/ui/views/notifications#importance + */ +export enum ELocalNotificationAndroidChannelImportance { + IMPORTANCE_NONE = 'IMPORTANCE_NONE', + IMPORTANCE_MIN = 'IMPORTANCE_MIN', + IMPORTANCE_LOW = 'IMPORTANCE_LOW', + IMPORTANCE_DEFAULT = 'IMPORTANCE_DEFAULT', + IMPORTANCE_HIGH = 'IMPORTANCE_HIGH', + IMPORTANCE_MAX = 'IMPORTANCE_MAX', +} + +/** + * ANDROID ONLY + * Status codes returned by `getUnusedAppRestrictionsStatus`. + */ +export enum ELocalNotificationAndroidUnusedAppRestrictionsStatus { + /** + * The status of Unused App Restrictions could not be retrieved from this app e.g. + * if the app's target SDK version <30 or the user is in locked device boot mode. + */ + ERROR = 0, + + /** There are no available Unused App Restrictions for this app. */ + FEATURE_NOT_AVAILABLE = 1, + + /** + * Any available Unused App Restrictions on the device are disabled for this app. + * In other words, this app is exempt from having its permissions automatically removed or being hibernated. + */ + DISABLED = 2, + + /** + * Unused App Restrictions introduced by Android API 30, and since made available on earlier (API 23-29) devices + * are enabled for this app: permission auto-reset. Only used on API 29 or earlier devices. + */ + API_30_BACKPORT = 3, + + /** + * Unused App Restrictions introduced by Android API 30 are enabled for this app: permission auto-reset. + * Only used on API 30 or later devices. + */ + API_30 = 4, + + /** + * Unused App Restrictions introduced by Android API 31 are enabled for this app: + * permission auto-reset and app hibernation. Only used on API 31 or later devices. + */ + API_31 = 5, +} + export interface ILocalNotificationEvery { /** * The minute. @@ -175,6 +244,8 @@ export interface ILocalNotificationAction { /** * Make this notification show when app in foreground. + * + * @deprecated Not read by the plugin since it no longer maps to a native option. Use `launch` to bring the app to the foreground on selection instead. */ foreground?: boolean; @@ -196,10 +267,17 @@ export interface ILocalNotificationAction { needsAuth?: boolean; /** - * The resource path of the action icon + * ANDROID ONLY + * The resource path of the action icon. Not supported anymore for normal notifications since Android 7, + * it will only be used on Android Wear. */ icon?: string; + /** + * Placeholder text for the input field of an action of type 'input'. + */ + emptyText?: string; + /** * ANDROID ONLY * An array of pre-defined choices for users input @@ -227,11 +305,14 @@ export interface ILocalNotificationAction { export interface ILocalNotificationProgressBar { /** * Is the progress bar enabled? + * + * @deprecated Not supported anymore. Setting `androidProgressBar` to an object enables it, `null`/omitting it disables it. */ enabled?: boolean; /** * The current value + * Default: 0 */ value?: number; @@ -244,6 +325,7 @@ export interface ILocalNotificationProgressBar { /** * ANDROID ONLY * Show an indeterminate progress bar + * Default: false */ indeterminate?: boolean; @@ -252,6 +334,8 @@ export interface ILocalNotificationProgressBar { * Gets or sets an optional string to be displayed instead of the * default percentage string. If this isn't provided, something * like "70%" will be displayed. + * + * @deprecated Windows is no longer a supported platform of this plugin. */ description?: string; @@ -261,38 +345,137 @@ export interface ILocalNotificationProgressBar { * on the left. * This string should reflect the status of the operation, * like "Downloading..." or "Installing..." + * + * @deprecated Windows is no longer a supported platform of this plugin. */ status?: string; } +/** + * ANDROID ONLY + * A single message of the `androidMessages` property, used to summarize/group notifications. + * + * @see https://github.com/katzer/cordova-plugin-local-notifications#summarizing + */ +export interface ILocalNotificationAndroidMessage { + /** + * The message text. + * Default: null + */ + message?: string; + + /** + * Timestamp in milliseconds, e.g. by Date.getTime(). + * Default: System.currentTimeMillis() + */ + date?: number; + + /** + * The name of the person who sent the message. + * Default: null + */ + person?: string; + + /** + * The icon of the person, drawn as a circle icon. + * Default: null + */ + personIcon?: string; +} + +/** + * ANDROID ONLY + * Options for `createChannel`. + * + * @see https://github.com/katzer/cordova-plugin-local-notifications#createchannel + */ +export interface ILocalNotificationChannel { + /** + * The id of the channel. Use Snake Case (lowercase, words separated by underscores). + */ + androidChannelId: string; + + /** + * The name of the channel. + * Default: "Default channel" + */ + androidChannelName?: string; + + /** + * The description of the channel. + */ + androidChannelDescription?: string; + + /** + * The importance of the channel. + * Default: IMPORTANCE_DEFAULT + */ + androidChannelImportance?: ELocalNotificationAndroidChannelImportance; + + /** + * Whether notifications posted to this channel should display notification lights. + * Default: false + */ + androidChannelEnableLights?: boolean; + + /** + * Whether notifications posted to this channel should vibrate. + * Default: false + */ + androidChannelEnableVibration?: boolean; + + /** + * The sound to play for notifications posted to this channel. + */ + sound?: string; + + /** + * The audio usage of the channel's sound. + * Default: 5 (USAGE_NOTIFICATION) + */ + androidChannelSoundUsage?: number; +} + export interface ILocalNotification { /** * A unique identifier required to clear, cancel, update or retrieve the local notification in the future - * Default: 0 + * Default: 1 */ id?: number; /** * First row of the notification - * Default: Empty string (iOS) or the app name (Android) + * Default: Empty string, the app name will be used if empty */ title?: string; /** * Second row of the notification * Default: Empty string + * + * @deprecated Passing an array is deprecated since upstream 1.1.0. Use `androidMessages` instead. */ text?: string | string[]; /** * The number currently set as the badge of the app icon in Springboard (iOS) or at the right-hand side of the local notification (Android) * Default: 0 (which means don't show a number) + * + * @deprecated Renamed to `badgeNumber` in upstream 1.1.0. */ badge?: number; + /** + * Overwrites `badge`. + * Sets the badge for the application. The behaviour differs between platforms: + * Android: increments the badge by the specified number. Default: 1 + * iOS: sets the badge directly. -1 leaves it unchanged, 0 clears it. Default: -1 + */ + badgeNumber?: number; + /** * Uri of the file containing the sound to play when an alert is displayed - * Default: res://platform_default + * Default: 'default' */ sound?: string; @@ -306,29 +489,72 @@ export interface ILocalNotification { * ANDROID ONLY * Uri of the icon that is shown in the ticker and notification * Default: res://icon + * + * @deprecated Renamed to `androidLargeIcon` in upstream 1.1.0. */ icon?: string; + /** + * ANDROID ONLY + * Add a large icon to the notification content view. + * Default: null + */ + androidLargeIcon?: string; + + /** + * ANDROID ONLY + * Can be `square` or `circle`. + * Default: 'square' + */ + androidLargeIconType?: 'square' | 'circle'; + /** * ANDROID ONLY * Uri of the resource (only res://) to use in the notification layouts. Different classes of devices may return different sizes * Default: res://ic_popup_reminder + * + * @deprecated Renamed to `androidSmallIcon` in upstream 1.1.0. */ smallIcon?: string; + /** + * ANDROID ONLY + * Set the small icon resource, which will be used to represent the notification in the status bar. + * Default: res://ic_popup_reminder + */ + androidSmallIcon?: string; + /** * ANDROID ONLY * RGB value for the background color of the smallIcon. * Default: Androids COLOR_DEFAULT, which will vary based on Android version. + * + * @deprecated Renamed to `androidColor` in upstream 1.1.0. */ color?: string; + /** + * ANDROID ONLY + * The notification background color for the small icon, as a hex string like `#FF0000`. + * Default: null + */ + androidColor?: string; + /** * ANDROID ONLY * Use the default notification vibrate. + * + * @deprecated Renamed to `androidChannelEnableVibration` in upstream 1.1.1. */ vibrate?: boolean; + /** + * ANDROID ONLY + * Enables the vibration of a notification channel. + * Default: false + */ + androidChannelEnableVibration?: boolean; + /** * ANDROID ONLY * Define the blinking of the LED on the device. @@ -339,15 +565,41 @@ export interface ILocalNotification { * If set to an array, the value of the key 0 will be used as the color, * the value of the key 1 will be used as the 'on' timing, the value of * the key 2 will be used as the 'off' timing + * Only supported on Android 7, replaced by `androidChannelEnableLights` on newer versions. */ led?: { color: string; on: number; off: number } | any[] | boolean | string; + /** + * ANDROID ONLY + * Whether notifications posted to a channel should display notification lights. + * Default: false + */ + androidChannelEnableLights?: boolean; + /** * Notification priority. * Integers between -2 and 2, whereas -2 is minimum and 2 is maximum priority + * Default: 0 (PRIORITY_DEFAULT) + * + * @deprecated Use `androidChannelImportance`, `androidAlarmType` and `androidAllowWhileIdle` instead since upstream 1.1.0. */ priority?: number; + /** + * ANDROID ONLY + * If the alarm should be scheduled on a specific time or in relevance to the time the device was booted, + * and if the alarm should wake up the device cpu (not the screen). + * Default: RTC_WAKEUP + */ + androidAlarmType?: ELocalNotificationAndroidAlarmType; + + /** + * ANDROID ONLY + * Alarm will be allowed to execute even when the system is in low-power idle (a.k.a. doze) modes. + * Default: false + */ + androidAllowWhileIdle?: boolean; + /** * Is a silent notification */ @@ -362,15 +614,34 @@ export interface ILocalNotification { /** * ANDROID ONLY * Wakeup the device. (default is true) + * + * @deprecated Renamed to `androidWakeUpScreen` in upstream 1.1.0. */ wakeup?: boolean; + /** + * ANDROID ONLY + * If the screen should go on, when a notification arrives. + * Default: true + */ + androidWakeUpScreen?: boolean; + /** * ANDROID ONLY * Specifies a duration in milliseconds after which this notification should be canceled, if it is not already canceled. + * + * @deprecated Renamed to `androidTimeoutAfter` in upstream 1.1.0. */ timeoutAfter?: number | false; + /** + * ANDROID ONLY + * Specifies a duration in milliseconds after which this notification should be canceled, if it is not already canceled. + * `0` means no automatic cancellation. + * Default: 0 + */ + androidTimeoutAfter?: number | false; + /** * Actions id or actions */ @@ -394,39 +665,107 @@ export interface ILocalNotification { * 'clock': Show the when date in the content view * 'chronometer': Show a stopwatch * + * @deprecated Since upstream 1.1.0. Use `androidShowWhen: boolean` for `clock: boolean` and `androidUsesChronometer: true` for `clock: 'chronometer'`. */ clock?: boolean | string; + /** + * ANDROID ONLY + * If the Notification should show the when date. + * Default: true + */ + androidShowWhen?: boolean; + + /** + * ANDROID ONLY + * Show the Notification#when field as a stopwatch, instead of a timestamp. + * Default: false + */ + androidUsesChronometer?: boolean; + /** * Shows a progress bar * Setting a boolean is a shortcut for {enabled: true/false} respectively + * + * @deprecated Renamed to `androidProgressBar` in upstream 1.1.0. */ progressBar?: ILocalNotificationProgressBar | boolean; + /** + * ANDROID ONLY + * Shows a progress bar. See https://github.com/katzer/cordova-plugin-local-notifications#progress + * Default: null + */ + androidProgressBar?: ILocalNotificationProgressBar; + /** * ANDROID ONLY * If multiple notifications have the same group your app can present * them as a single group. + * + * @deprecated Renamed to `androidGroup` in upstream 1.1.0. */ group?: string; + /** + * ANDROID ONLY + * Set this notification to be part of a group of notifications sharing the same key. + * Default: null + */ + androidGroup?: string; + /** * ANDROID ONLY * If set to 'true' this notification could use 'summary' to summarize * the contents of the whole group + * + * @deprecated Renamed to `androidGroupSummary` in upstream 1.1.0. */ groupSummary?: boolean; + /** + * ANDROID ONLY + * Set this notification to be the group summary for a group of notifications. Requires `androidGroup` also being set. + * Default: false + */ + androidGroupSummary?: boolean; + /** * ANDROID ONLY * Summary of the whole notification group. Should be used in conjuntion * with 'groupSummary' set to true + * + * @deprecated Renamed to `androidSummary` in upstream 1.1.0. */ summary?: string; + /** + * ANDROID ONLY + * Used as summary text for the InboxStyle, BigPictureStyle or BigTextStyle notification, depending on which is used. + * Default: null + */ + androidSummary?: string; + + /** + * ANDROID ONLY + * Array of messages to summarize notifications, uses NotificationCompat.MessagingStyle. + * Default: null + */ + androidMessages?: ILocalNotificationAndroidMessage[]; + + /** + * ANDROID ONLY + * Additional text added to the title for displaying the number of messages, when using MessagingStyle. + * Use `%n%` in the string for specifying the location of the number. + * Default: '%n%' + */ + androidTitleCount?: string; + /** * ANDROID ONLY * Sets the number of items this notification represents. + * + * @deprecated Removed upstream in 1.1.0 and no longer part of the plugin's options. */ number?: number; @@ -435,46 +774,137 @@ export interface ILocalNotification { * Set whether this is an "ongoing" notification. * Ongoing notifications cannot be dismissed by the user, * so your application or service must take care of canceling them. + * + * @deprecated Renamed to `androidOngoing` in upstream 1.1.0. */ sticky?: boolean; + /** + * ANDROID ONLY + * Set whether this is an ongoing notification. Ongoing notifications cannot be dismissed by the user on locked devices. + * Default: false + */ + androidOngoing?: boolean; + + /** + * ANDROID ONLY + * Set this flag if you would only like the sound, vibrate and ticker to be played if the notification is not already showing. + * Default: false + */ + androidOnlyAlertOnce?: boolean; + /** * ANDROID ONLY * Make this notification automatically dismissed when the user touches it. + * + * @deprecated Renamed to `androidAutoCancel` in upstream 1.1.0. */ autoClear?: boolean; + /** + * ANDROID ONLY + * Make this notification automatically dismissed when the user touches it. + * Default: true + */ + androidAutoCancel?: boolean; + /** * ANDROID ONLY * If set to true the notification will be show in its entirety on all lockscreens. * If set to false it will not be revealed on a secure lockscreen. + * + * @deprecated Renamed to `androidLockscreen` in upstream 1.1.0. */ lockscreen?: boolean; + /** + * ANDROID ONLY + * If the entire notification should be shown on all lockscreens and while screen sharing. + * Default: true + */ + androidLockscreen?: boolean; + /** * ANDROID ONLY * Set the default notification options that will be used. * The value should be one or more of the following fields combined with * bitwise-or: DEFAULT_SOUND, DEFAULT_VIBRATE, DEFAULT_LIGHTS. + * + * @deprecated Renamed to `androidDefaults` in upstream 1.1.0. */ defaults?: number; + /** + * ANDROID ONLY + * Android 7 only. Sets the default notification options that will be used only on Android 7. + * Default: 0 + */ + androidDefaults?: number; + /** * ANDROID ONLY * Specifies the channel the notification should be delivered on. + * + * @deprecated Renamed to `androidChannelId` in upstream 1.1.0. */ channel?: string; + /** + * ANDROID ONLY + * Specifies the channel id to be posted on. Use Snake Case (lowercase, words separated by underscores). + * Default: 'default_channel' + */ + androidChannelId?: string; + + /** + * ANDROID ONLY + * Sets the `channelName` for the notification to be posted on. + * Default: 'Default channel' + */ + androidChannelName?: string; + + /** + * ANDROID ONLY + * Sets the `description` of a notification channel. + * Default: null + */ + androidChannelDescription?: string; + + /** + * ANDROID ONLY + * Sets the importance of a notification channel. + * Default: IMPORTANCE_DEFAULT + */ + androidChannelImportance?: ELocalNotificationAndroidChannelImportance; + + /** + * ANDROID ONLY + * Sets the audio usage of a notification channel's sound. + * Default: 5 (USAGE_NOTIFICATION) + */ + androidChannelSoundUsage?: number; + /** * ANDROID ONLY * Set the token for the media session + * + * @deprecated Removed upstream in 1.1.0. This option and MediaStyle are no longer supported. */ mediaSession?: string; /** * Make this notification show when app in foreground. + * + * @deprecated Renamed to `iOSForeground` in upstream 1.1.0. */ foreground?: boolean; + + /** + * IOS ONLY + * Displays notification in foreground, when app is active. + * Default: true + */ + iOSForeground?: boolean; } /** @@ -530,7 +960,7 @@ export interface ILocalNotification { plugin: 'cordova-plugin-local-notification', pluginRef: 'cordova.plugins.notification.local', repo: 'https://github.com/katzer/cordova-plugin-local-notifications', - platforms: ['Android', 'iOS', 'Windows'], + platforms: ['Android', 'iOS'], }) @Injectable() export class LocalNotifications extends AwesomeCordovaNativePlugin { @@ -554,6 +984,19 @@ export class LocalNotifications extends AwesomeCordovaNativePlugin { return; } + /** + * ANDROID ONLY + * Checks if the user has enabled the "Alarms & Reminders" setting, required for exact alarms. + * On Android 11 and older this always resolves true, on Android 12 it's granted by default, + * on Android 13 and newer it has to be explicitly enabled by the user. + * + * @returns {Promise} + */ + @Cordova() + canScheduleExactAlarms(): Promise { + return; + } + /** * Schedules a single or multiple notifications * @@ -665,9 +1108,10 @@ export class LocalNotifications extends AwesomeCordovaNativePlugin { * Get the type (triggered, scheduled) for the notification. * * @param {number} id The ID of the notification. + * @returns {Promise} */ @Cordova() - getType(id: number): Promise { + getType(id: number): Promise { return; } @@ -723,24 +1167,24 @@ export class LocalNotifications extends AwesomeCordovaNativePlugin { } /** - * Get a scheduled notification object + * Get all scheduled notification objects. * - * @param notificationId {any} The id of the notification to get - * @returns {Promise} + * @param notificationId {any} Optional. No longer used upstream, kept only for backward compatibility. + * @returns {Promise} */ @Cordova() - getScheduled(notificationId: any): Promise { + getScheduled(notificationId?: any): Promise { return; } /** - * Get a triggered notification object + * Get all triggered notification objects. * - * @param notificationId The id of the notification to get - * @returns {Promise} + * @param notificationId {any} Optional. No longer used upstream, kept only for backward compatibility. + * @returns {Promise} */ @Cordova() - getTriggered(notificationId: any): Promise { + getTriggered(notificationId?: any): Promise { return; } @@ -803,12 +1247,40 @@ export class LocalNotifications extends AwesomeCordovaNativePlugin { return; } + /** + * ANDROID ONLY + * Creates a notification channel, if it doesn't already exist. A channel can't be changed after creation. + * + * @param options {ILocalNotificationChannel} The channel to create + * @returns {Promise} + */ + @Cordova() + createChannel(options: ILocalNotificationChannel): Promise { + return; + } + + /** + * ANDROID ONLY + * Deletes a notification channel by id. 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. + * + * @param channelId {string} The id of the channel to delete + * @returns {Promise} + */ + @Cordova() + deleteChannel(channelId: string): Promise { + return; + } + /** * Get all scheduled notification objects * * @returns {Promise>} + * @deprecated Duplicate of `getScheduled()`, kept for backward compatibility. Use `getScheduled()` instead. */ - @Cordova() + @Cordova({ + methodName: 'getScheduled', + }) getAllScheduled(): Promise { return; } @@ -817,16 +1289,78 @@ export class LocalNotifications extends AwesomeCordovaNativePlugin { * Get all triggered notification objects * * @returns {Promise>} + * @deprecated Duplicate of `getTriggered()`, kept for backward compatibility. Use `getTriggered()` instead. + */ + @Cordova({ + methodName: 'getTriggered', + }) + getAllTriggered(): Promise { + return; + } + + /** + * Opens the notification settings of the app. On Android 8+ it opens the app's notification settings, + * on older Android versions it opens the app details. On iOS it's not possible to open the notification + * settings directly, so it opens the app settings instead. + * + * @returns {Promise} */ @Cordova() - getAllTriggered(): Promise { + openNotificationSettings(): Promise { + return; + } + + /** + * ANDROID ONLY + * Since Android 12 (SDK 31). Opens the "Alarms & Reminders" setting, where the user can manually + * enable exact alarms. Requires the SCHEDULE_EXACT_ALARM permission to be declared in the AndroidManifest.xml. + * + * @returns {Promise} + */ + @Cordova() + openAlarmSettings(): Promise { + return; + } + + /** + * IOS ONLY + * Clears the badge of the app icon. + * + * @returns {Promise} + */ + @Cordova() + iOSClearBadge(): Promise { + return; + } + + /** + * ANDROID ONLY + * Returns the status of the unused app restrictions (app hibernation), introduced in Android 11 + * and backported to Android 6 through the Google Play Store. + * + * @returns {Promise} + */ + @Cordova() + getUnusedAppRestrictionsStatus(): Promise { + return; + } + + /** + * ANDROID ONLY + * Redirects the user to manage their unused app restriction settings. The returned promise resolves once + * the user returns to the app; use `getUnusedAppRestrictionsStatus` to check the resulting status. + * + * @returns {Promise} + */ + @Cordova() + openManageUnusedAppRestrictions(): Promise { return; } /** * Sets a callback for a specific event * - * @param eventName {string} The name of the event. Available events: schedule, trigger, click, update, clear, clearall, cancel, cancelall. Custom event names are possible for actions + * @param eventName {string} The name of the event. Available events: add, trigger, click, update, clear, clearall, cancel, cancelall. Custom event names are possible for actions * @returns {Observable} */ @Cordova({ @@ -841,7 +1375,7 @@ export class LocalNotifications extends AwesomeCordovaNativePlugin { /** * Not an official interface, however its possible to manually fire events. * - * @param eventName The name of the event. Available events: schedule, trigger, click, update, clear, clearall, cancel, cancelall. Custom event names are possible for actions + * @param eventName The name of the event. Available events: add, trigger, click, update, clear, clearall, cancel, cancelall. Custom event names are possible for actions * @param args Optional arguments */ @Cordova({