From 500d53b042e7e40a4b8dcce94ff49872cd0666b4 Mon Sep 17 00:00:00 2001 From: pinpong Date: Wed, 28 Oct 2026 07:02:22 +0700 Subject: [PATCH 1/2] feat(android): add shouldShowRequestPermissionRationale() --- CHANGELOG.md | 4 + README.md | 23 ++++++ docs/react-native/android/permissions.mdx | 21 +++++ .../reference/Interface.ModuleWithStatics.mdx | 76 +++++++++++++------ packages/react-native/README.md | 23 ++++++ .../__tests__/NotifeeApiModule.test.ts | 21 +++++ .../io/invertase/notifee/NotifeeApiModule.kt | 11 +++ .../ios/RNNotifee/NotifeeApiModule.mm | 5 ++ packages/react-native/jest-mock.js | 1 + packages/react-native/src/NotifeeApiModule.ts | 8 ++ .../src/__mocks__/NotifeeNativeModule.ts | 1 + .../src/specs/NativeNotifeeModule.ts | 1 + packages/react-native/src/types/Module.ts | 17 +++++ 13 files changed, 190 insertions(+), 22 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 8b641a36..20155600 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -7,6 +7,10 @@ and this project adheres to [Semantic Versioning](https://semver.org/). ## [Unreleased] +### Added + +- **Android / permissions**: add `shouldShowRequestPermissionRationale()`, which wraps `Activity.shouldShowRequestPermissionRationale` for `POST_NOTIFICATIONS`. It tells apps whether Android 13+ shows the notification dialog once more after a denial, so they can explain first and ask again, or point to the system settings when the dialog will not come back. It resolves `false` before the first request, after the second denial, below API 33, without a current Activity and on iOS. + ## [10.9.1] - 2026-10-24 ### Fixed diff --git a/README.md b/README.md index 8bd75870..b4679c23 100644 --- a/README.md +++ b/README.md @@ -923,6 +923,29 @@ if (settings.android.fullScreenIntent === AndroidNotificationSetting.DISABLED) { notification will be presented full-screen. See [Android Behaviour: Full-screen](https://docs.page/marcocrupi/react-native-notify-kit/react-native/android/behaviour#full-screen) for the full requirements and presentation behavior. +### `shouldShowRequestPermissionRationale` (Android) + +After the first denial on Android 13+, `getNotificationSettings()` reports `AuthorizationStatus.DENIED` both when the +system would show the `POST_NOTIFICATIONS` dialog once more and when only the system settings can turn notifications +on. `shouldShowRequestPermissionRationale()` tells the two apart: + +```typescript +import notifee, { AuthorizationStatus } from 'react-native-notify-kit'; + +const { authorizationStatus } = await notifee.getNotificationSettings(); + +if (authorizationStatus === AuthorizationStatus.DENIED) { + if (await notifee.shouldShowRequestPermissionRationale()) { + // explain why notifications help, then call notifee.requestPermission() + } else { + // the dialog will not come back, offer notifee.openNotificationSettings() + } +} +``` + +It resolves `false` before the first request, below API 33, without a current Activity and on iOS. See +[Android Permissions: Asking again after a denial](https://docs.page/marcocrupi/react-native-notify-kit/react-native/android/permissions#asking-again-after-a-denial). + ### `setNotificationConfig` (iOS) Controls whether Notifee intercepts remote (push) notification tap events on iOS. diff --git a/docs/react-native/android/permissions.mdx b/docs/react-native/android/permissions.mdx index 4d5407e7..b7317f84 100644 --- a/docs/react-native/android/permissions.mdx +++ b/docs/react-native/android/permissions.mdx @@ -66,6 +66,27 @@ async function checkNotificationPermission() { If you determine notifications are disabled, you may want to offer the user the ability to open notification settings to enable it. The [`openNotificationSettings`](/react-native/reference/opennotificationsettings) API may be used to implement this feature. +#### Asking again after a denial + +On Android 13+, the system shows the `POST_NOTIFICATIONS` dialog at most twice. After the first denial, `getNotificationSettings` reports `AuthorizationStatus.DENIED` both when Android would show the dialog once more and when only the system settings can turn notifications on. Call `shouldShowRequestPermissionRationale` to tell the two apart. After the first denial it resolves `true` while the next `requestPermission()` call still shows the dialog, which is the moment the [Android guidelines](https://developer.android.com/training/permissions/requesting#explain) want the app to explain why it needs notifications before it asks. After the second denial it resolves `false`, then only the system settings can turn notifications on. It also resolves `false` before the first request, below API 33 and on iOS. + +```js +import notifee, { AuthorizationStatus } from 'react-native-notify-kit'; + +async function offerNotifications() { + const { authorizationStatus } = await notifee.getNotificationSettings(); + if (authorizationStatus !== AuthorizationStatus.DENIED) { + return; + } + + if (await notifee.shouldShowRequestPermissionRationale()) { + // explain why notifications help, then call notifee.requestPermission() + } else { + // the dialog will not come again, offer notifee.openNotificationSettings() + } +} +``` + ### Channels & Channels Groups To check whether the user has enabled notifications for specific channels or channel groups, call either [`getChannel`](/react-native/reference/getchannel) or [`getChannelGroups`](/react-native/reference/getchannelgroups). Both of these functions will return a respective object with `blocked` attributes in it. diff --git a/docs/react-native/reference/Interface.ModuleWithStatics.mdx b/docs/react-native/reference/Interface.ModuleWithStatics.mdx index c3148ddc..55e693a5 100644 --- a/docs/react-native/reference/Interface.ModuleWithStatics.mdx +++ b/docs/react-native/reference/Interface.ModuleWithStatics.mdx @@ -6,7 +6,7 @@ # Interface: ModuleWithStatics -Defined in: [packages/react-native/src/types/Module.ts:735](https://github.com/marcocrupi/react-native-notify-kit/blob/main/packages/react-native/src/types/Module.ts#L735) +Defined in: [packages/react-native/src/types/Module.ts:752](https://github.com/marcocrupi/react-native-notify-kit/blob/main/packages/react-native/src/types/Module.ts#L752) ## Extends @@ -18,7 +18,7 @@ Defined in: [packages/react-native/src/types/Module.ts:735](https://github.com/m > **SDK_VERSION**: `string` -Defined in: [packages/react-native/src/types/Module.ts:732](https://github.com/marcocrupi/react-native-notify-kit/blob/main/packages/react-native/src/types/Module.ts#L732) +Defined in: [packages/react-native/src/types/Module.ts:749](https://github.com/marcocrupi/react-native-notify-kit/blob/main/packages/react-native/src/types/Module.ts#L749) Returns the current Notify Kit SDK version in use. @@ -32,7 +32,7 @@ Returns the current Notify Kit SDK version in use. > **buildFcmNotification**(`remoteMessage`): [`Notification`](react-native/reference/Interface.Notification) | `null` -Defined in: [packages/react-native/src/types/Module.ts:694](https://github.com/marcocrupi/react-native-notify-kit/blob/main/packages/react-native/src/types/Module.ts#L694) +Defined in: [packages/react-native/src/types/Module.ts:711](https://github.com/marcocrupi/react-native-notify-kit/blob/main/packages/react-native/src/types/Module.ts#L711) Builds a notification from an FCM remote message without displaying it. @@ -440,7 +440,7 @@ to create a trigger. > **decrementBadgeCount**(`decrementBy?`): `Promise`<`void`> -Defined in: [packages/react-native/src/types/Module.ts:548](https://github.com/marcocrupi/react-native-notify-kit/blob/main/packages/react-native/src/types/Module.ts#L548) +Defined in: [packages/react-native/src/types/Module.ts:565](https://github.com/marcocrupi/react-native-notify-kit/blob/main/packages/react-native/src/types/Module.ts#L565) Decrements the badge count for this application on the current device by a specified value. @@ -579,7 +579,7 @@ to create a notification for both Android & iOS. > **getBadgeCount**(): `Promise`<`number`> -Defined in: [packages/react-native/src/types/Module.ts:514](https://github.com/marcocrupi/react-native-notify-kit/blob/main/packages/react-native/src/types/Module.ts#L514) +Defined in: [packages/react-native/src/types/Module.ts:531](https://github.com/marcocrupi/react-native-notify-kit/blob/main/packages/react-native/src/types/Module.ts#L531) Get the current badge count value for this application on the current device. @@ -800,7 +800,7 @@ but you will also receive a `onForegroundEvent` > **getNotificationCategories**(): `Promise`<[`IOSNotificationCategory`](react-native/reference/Interface.IOSNotificationCategory)\[]> -Defined in: [packages/react-native/src/types/Module.ts:496](https://github.com/marcocrupi/react-native-notify-kit/blob/main/packages/react-native/src/types/Module.ts#L496) +Defined in: [packages/react-native/src/types/Module.ts:513](https://github.com/marcocrupi/react-native-notify-kit/blob/main/packages/react-native/src/types/Module.ts#L513) Gets the currently set notification categories on this Apple device. @@ -824,7 +824,7 @@ ios > **getNotificationSettings**(): `Promise`<[`NotificationSettings`](react-native/reference/Interface.NotificationSettings)> -Defined in: [packages/react-native/src/types/Module.ts:505](https://github.com/marcocrupi/react-native-notify-kit/blob/main/packages/react-native/src/types/Module.ts#L505) +Defined in: [packages/react-native/src/types/Module.ts:522](https://github.com/marcocrupi/react-native-notify-kit/blob/main/packages/react-native/src/types/Module.ts#L522) Get the current notification settings for this application on the current device. On Android 13+ (API 33+), `authorizationStatus` returns `AuthorizationStatus.NOT_DETERMINED` before @@ -846,7 +846,7 @@ All properties on the `IOSNotificationSettings` interface response return as `AU > **getPowerManagerInfo**(): `Promise`<[`PowerManagerInfo`](react-native/reference/Interface.PowerManagerInfo)> -Defined in: [packages/react-native/src/types/Module.ts:632](https://github.com/marcocrupi/react-native-notify-kit/blob/main/packages/react-native/src/types/Module.ts#L632) +Defined in: [packages/react-native/src/types/Module.ts:649](https://github.com/marcocrupi/react-native-notify-kit/blob/main/packages/react-native/src/types/Module.ts#L649) API used to get best-effort information about the device and its power manager settings, including manufacturer, model, version and a known activity candidate. @@ -934,7 +934,7 @@ API used to return the trigger notifications that are pending. > **handleFcmMessage**(`remoteMessage`): `Promise`<`string` | `null`> -Defined in: [packages/react-native/src/types/Module.ts:706](https://github.com/marcocrupi/react-native-notify-kit/blob/main/packages/react-native/src/types/Module.ts#L706) +Defined in: [packages/react-native/src/types/Module.ts:723](https://github.com/marcocrupi/react-native-notify-kit/blob/main/packages/react-native/src/types/Module.ts#L723) Processes an FCM remote message produced by the Notify Kit server SDK and displays a Notify Kit notification according to the embedded `notifee_options`. @@ -965,7 +965,7 @@ intentional no-op (iOS background, `fallbackBehavior: 'ignore'`, > **hideNotificationDrawer**(): `void` -Defined in: [packages/react-native/src/types/Module.ts:684](https://github.com/marcocrupi/react-native-notify-kit/blob/main/packages/react-native/src/types/Module.ts#L684) +Defined in: [packages/react-native/src/types/Module.ts:701](https://github.com/marcocrupi/react-native-notify-kit/blob/main/packages/react-native/src/types/Module.ts#L701) API used to hide the notification drawer, for example, when the user presses one of the quick actions on the notification, you may wish to hide the drawer. @@ -1002,7 +1002,7 @@ android > **incrementBadgeCount**(`incrementBy?`): `Promise`<`void`> -Defined in: [packages/react-native/src/types/Module.ts:538](https://github.com/marcocrupi/react-native-notify-kit/blob/main/packages/react-native/src/types/Module.ts#L538) +Defined in: [packages/react-native/src/types/Module.ts:555](https://github.com/marcocrupi/react-native-notify-kit/blob/main/packages/react-native/src/types/Module.ts#L555) Increments the badge count for this application on the current device by a specified value. @@ -1035,7 +1035,7 @@ ios > **isBatteryOptimizationEnabled**(): `Promise`<`boolean`> -Defined in: [packages/react-native/src/types/Module.ts:597](https://github.com/marcocrupi/react-native-notify-kit/blob/main/packages/react-native/src/types/Module.ts#L597) +Defined in: [packages/react-native/src/types/Module.ts:614](https://github.com/marcocrupi/react-native-notify-kit/blob/main/packages/react-native/src/types/Module.ts#L614) API used to check if battery optimization is enabled for your application. @@ -1220,7 +1220,7 @@ android > **openBatteryOptimizationSettings**(): `Promise`<`void`> -Defined in: [packages/react-native/src/types/Module.ts:586](https://github.com/marcocrupi/react-native-notify-kit/blob/main/packages/react-native/src/types/Module.ts#L586) +Defined in: [packages/react-native/src/types/Module.ts:603](https://github.com/marcocrupi/react-native-notify-kit/blob/main/packages/react-native/src/types/Module.ts#L603) API used to open the Android System settings for the application. @@ -1291,7 +1291,7 @@ android > **openPowerManagerSettings**(): `Promise`<`void`> -Defined in: [packages/react-native/src/types/Module.ts:663](https://github.com/marcocrupi/react-native-notify-kit/blob/main/packages/react-native/src/types/Module.ts#L663) +Defined in: [packages/react-native/src/types/Module.ts:680](https://github.com/marcocrupi/react-native-notify-kit/blob/main/packages/react-native/src/types/Module.ts#L680) API used to best-effort open known Android System power manager settings for the device. @@ -1337,7 +1337,7 @@ android > **prewarmForegroundService**(): `Promise`<`void`> -Defined in: [packages/react-native/src/types/Module.ts:448](https://github.com/marcocrupi/react-native-notify-kit/blob/main/packages/react-native/src/types/Module.ts#L448) +Defined in: [packages/react-native/src/types/Module.ts:465](https://github.com/marcocrupi/react-native-notify-kit/blob/main/packages/react-native/src/types/Module.ts#L465) Pre-warms the foreground service notification path by eagerly loading critical classes and warming the `INotificationManager` Binder proxy on a background thread. @@ -1372,7 +1372,7 @@ android > **registerForegroundService**(`task`): `void` -Defined in: [packages/react-native/src/types/Module.ts:420](https://github.com/marcocrupi/react-native-notify-kit/blob/main/packages/react-native/src/types/Module.ts#L420) +Defined in: [packages/react-native/src/types/Module.ts:437](https://github.com/marcocrupi/react-native-notify-kit/blob/main/packages/react-native/src/types/Module.ts#L437) API used to register a foreground service on Android devices. @@ -1411,7 +1411,7 @@ android > **requestPermission**(`permissions?`): `Promise`<[`NotificationSettings`](react-native/reference/Interface.NotificationSettings)> -Defined in: [packages/react-native/src/types/Module.ts:478](https://github.com/marcocrupi/react-native-notify-kit/blob/main/packages/react-native/src/types/Module.ts#L478) +Defined in: [packages/react-native/src/types/Module.ts:495](https://github.com/marcocrupi/react-native-notify-kit/blob/main/packages/react-native/src/types/Module.ts#L495) Request specific notification permissions for your application on the current device. @@ -1458,7 +1458,7 @@ and all of the properties on the `ios` interface response return as `AUTHORIZED` > **setBadgeCount**(`count`): `Promise`<`void`> -Defined in: [packages/react-native/src/types/Module.ts:526](https://github.com/marcocrupi/react-native-notify-kit/blob/main/packages/react-native/src/types/Module.ts#L526) +Defined in: [packages/react-native/src/types/Module.ts:543](https://github.com/marcocrupi/react-native-notify-kit/blob/main/packages/react-native/src/types/Module.ts#L543) Set the badge count value for this application on the current device. @@ -1491,7 +1491,7 @@ ios > **setFcmConfig**(`config`): `Promise`<`void`> -Defined in: [packages/react-native/src/types/Module.ts:716](https://github.com/marcocrupi/react-native-notify-kit/blob/main/packages/react-native/src/types/Module.ts#L716) +Defined in: [packages/react-native/src/types/Module.ts:733](https://github.com/marcocrupi/react-native-notify-kit/blob/main/packages/react-native/src/types/Module.ts#L733) Configures defaults for [buildFcmNotification](#buildfcmnotification) and [handleFcmMessage](#handlefcmmessage). Call once at app startup, typically in `index.js` before `registerComponent`. @@ -1520,7 +1520,7 @@ synchronously. > **setNotificationCategories**(`categories`): `Promise`<`void`> -Defined in: [packages/react-native/src/types/Module.ts:487](https://github.com/marcocrupi/react-native-notify-kit/blob/main/packages/react-native/src/types/Module.ts#L487) +Defined in: [packages/react-native/src/types/Module.ts:504](https://github.com/marcocrupi/react-native-notify-kit/blob/main/packages/react-native/src/types/Module.ts#L504) Set the notification categories to be used on this Apple device. @@ -1548,7 +1548,7 @@ ios > **setNotificationConfig**(`config`): `Promise`<`void`> -Defined in: [packages/react-native/src/types/Module.ts:574](https://github.com/marcocrupi/react-native-notify-kit/blob/main/packages/react-native/src/types/Module.ts#L574) +Defined in: [packages/react-native/src/types/Module.ts:591](https://github.com/marcocrupi/react-native-notify-kit/blob/main/packages/react-native/src/types/Module.ts#L591) API used to configure iOS notification handling behavior. @@ -1593,11 +1593,43 @@ ios --- +### shouldShowRequestPermissionRationale() + +> **shouldShowRequestPermissionRationale**(): `Promise`<`boolean`> + +Defined in: [packages/react-native/src/types/Module.ts:420](https://github.com/marcocrupi/react-native-notify-kit/blob/main/packages/react-native/src/types/Module.ts#L420) + +API used to find out whether Android shows the notification permission dialog once +more after the user denied it. + +Android 13 (API 33) and later show the `POST_NOTIFICATIONS` dialog at most twice. After +the first denial this resolves `true`, the moment the Android guidelines want the app to +explain why it needs notifications before it calls `requestPermission` again. After the +second denial it resolves `false`, from then on only the system settings can turn +notifications on. Wraps `Activity.shouldShowRequestPermissionRationale`. + +It also resolves `false` before the first request, below API 33, without a current +Activity and on iOS. + +#### Returns + +`Promise`<`boolean`> + +#### Platform + +android + +#### Inherited from + +`Module.shouldShowRequestPermissionRationale` + +--- + ### stopForegroundService() > **stopForegroundService**(): `Promise`<`void`> -Defined in: [packages/react-native/src/types/Module.ts:428](https://github.com/marcocrupi/react-native-notify-kit/blob/main/packages/react-native/src/types/Module.ts#L428) +Defined in: [packages/react-native/src/types/Module.ts:445](https://github.com/marcocrupi/react-native-notify-kit/blob/main/packages/react-native/src/types/Module.ts#L445) Call this to stop the foreground service that is running diff --git a/packages/react-native/README.md b/packages/react-native/README.md index 1a758cf4..9b0579ee 100644 --- a/packages/react-native/README.md +++ b/packages/react-native/README.md @@ -923,6 +923,29 @@ if (settings.android.fullScreenIntent === AndroidNotificationSetting.DISABLED) { notification will be presented full-screen. See [Android Behaviour: Full-screen](https://docs.page/marcocrupi/react-native-notify-kit/react-native/android/behaviour#full-screen) for the full requirements and presentation behavior. +### `shouldShowRequestPermissionRationale` (Android) + +After the first denial on Android 13+, `getNotificationSettings()` reports `AuthorizationStatus.DENIED` both when the +system would show the `POST_NOTIFICATIONS` dialog once more and when only the system settings can turn notifications +on. `shouldShowRequestPermissionRationale()` tells the two apart: + +```typescript +import notifee, { AuthorizationStatus } from 'react-native-notify-kit'; + +const { authorizationStatus } = await notifee.getNotificationSettings(); + +if (authorizationStatus === AuthorizationStatus.DENIED) { + if (await notifee.shouldShowRequestPermissionRationale()) { + // explain why notifications help, then call notifee.requestPermission() + } else { + // the dialog will not come back, offer notifee.openNotificationSettings() + } +} +``` + +It resolves `false` before the first request, below API 33, without a current Activity and on iOS. See +[Android Permissions: Asking again after a denial](https://docs.page/marcocrupi/react-native-notify-kit/react-native/android/permissions#asking-again-after-a-denial). + ### `setNotificationConfig` (iOS) Controls whether Notifee intercepts remote (push) notification tap events on iOS. diff --git a/packages/react-native/__tests__/NotifeeApiModule.test.ts b/packages/react-native/__tests__/NotifeeApiModule.test.ts index 54ca0681..06f647ba 100644 --- a/packages/react-native/__tests__/NotifeeApiModule.test.ts +++ b/packages/react-native/__tests__/NotifeeApiModule.test.ts @@ -287,6 +287,27 @@ describe('Notifee Api Module', () => { }); }); + describe('shouldShowRequestPermissionRationale', () => { + test('on iOS resolves false without a native call', async () => { + setPlatform('ios'); + + const res = await apiModule.shouldShowRequestPermissionRationale(); + + expect(res).toBe(false); + expect(mockNotifeeNativeModule.shouldShowRequestPermissionRationale).not.toBeCalled(); + }); + + test('on Android resolves the native answer', async () => { + setPlatform('android'); + mockNotifeeNativeModule.shouldShowRequestPermissionRationale.mockResolvedValueOnce(true); + + const res = await apiModule.shouldShowRequestPermissionRationale(); + + expect(res).toBe(true); + expect(mockNotifeeNativeModule.shouldShowRequestPermissionRationale).toBeCalledTimes(1); + }); + }); + describe('requestPermission', () => { test('passes Android full-screen intent access through from the native module', async () => { setPlatform('android'); diff --git a/packages/react-native/android/src/main/kotlin/io/invertase/notifee/NotifeeApiModule.kt b/packages/react-native/android/src/main/kotlin/io/invertase/notifee/NotifeeApiModule.kt index ec4b6fb6..a2650eba 100644 --- a/packages/react-native/android/src/main/kotlin/io/invertase/notifee/NotifeeApiModule.kt +++ b/packages/react-native/android/src/main/kotlin/io/invertase/notifee/NotifeeApiModule.kt @@ -276,6 +276,17 @@ class NotifeeApiModule(reactContext: ReactApplicationContext) : } } + override fun shouldShowRequestPermissionRationale(promise: Promise) { + val activity = getReactApplicationContext().getCurrentActivity() + if (Build.VERSION.SDK_INT < Build.VERSION_CODES.TIRAMISU || activity == null) { + promise.resolve(false) + return + } + promise.resolve( + activity.shouldShowRequestPermissionRationale(Manifest.permission.POST_NOTIFICATIONS), + ) + } + override fun openNotificationSettings(channelId: String?, promise: Promise) { Notifee.getInstance() .openNotificationSettings(channelId, getReactApplicationContext().getCurrentActivity()) { e, _ -> diff --git a/packages/react-native/ios/RNNotifee/NotifeeApiModule.mm b/packages/react-native/ios/RNNotifee/NotifeeApiModule.mm index dfefbea7..33f97cf8 100644 --- a/packages/react-native/ios/RNNotifee/NotifeeApiModule.mm +++ b/packages/react-native/ios/RNNotifee/NotifeeApiModule.mm @@ -420,6 +420,11 @@ - (void)openNotificationSettings:(NSString *_Nullable)channelId resolve(nil); } +- (void)shouldShowRequestPermissionRationale:(RCTPromiseResolveBlock)resolve + reject:(RCTPromiseRejectBlock)reject { + resolve(@(NO)); +} + - (void)openBatteryOptimizationSettings:(RCTPromiseResolveBlock)resolve reject:(RCTPromiseRejectBlock)reject { resolve(nil); diff --git a/packages/react-native/jest-mock.js b/packages/react-native/jest-mock.js index 91246e51..b713e125 100644 --- a/packages/react-native/jest-mock.js +++ b/packages/react-native/jest-mock.js @@ -146,6 +146,7 @@ export default { onBackgroundEvent: jest.fn(() => jest.fn()), onForegroundEvent: jest.fn(() => jest.fn()), openNotificationSettings: jest.fn(), + shouldShowRequestPermissionRationale: jest.fn(async () => false), requestPermission: jest.fn(async () => testNotificationSettings), registerForegroundService: jest.fn(() => jest.fn()), setNotificationCategories: jest.fn(async () => {}), diff --git a/packages/react-native/src/NotifeeApiModule.ts b/packages/react-native/src/NotifeeApiModule.ts index c0932e42..20b78c79 100644 --- a/packages/react-native/src/NotifeeApiModule.ts +++ b/packages/react-native/src/NotifeeApiModule.ts @@ -553,6 +553,14 @@ export default class NotifeeApiModule extends NotifeeNativeModule implements Mod return Promise.resolve(); }; + public shouldShowRequestPermissionRationale = (): Promise => { + if (isAndroid) { + return this.native.shouldShowRequestPermissionRationale(); + } + + return Promise.resolve(false); + }; + public requestPermission = ( permissions: IOSNotificationPermissions = {}, ): Promise => { diff --git a/packages/react-native/src/__mocks__/NotifeeNativeModule.ts b/packages/react-native/src/__mocks__/NotifeeNativeModule.ts index 15c5ffec..4cba04cf 100644 --- a/packages/react-native/src/__mocks__/NotifeeNativeModule.ts +++ b/packages/react-native/src/__mocks__/NotifeeNativeModule.ts @@ -38,6 +38,7 @@ export const mockNotifeeNativeModule = { onBackgroundEvent: jest.fn(), onForegroundEvent: jest.fn(), openNotificationSettings: jest.fn(), + shouldShowRequestPermissionRationale: jest.fn(async () => false), requestPermission: jest.fn(), registerForegroundService: jest.fn(), setNotificationCategories: jest.fn(), diff --git a/packages/react-native/src/specs/NativeNotifeeModule.ts b/packages/react-native/src/specs/NativeNotifeeModule.ts index 874577aa..0265053c 100644 --- a/packages/react-native/src/specs/NativeNotifeeModule.ts +++ b/packages/react-native/src/specs/NativeNotifeeModule.ts @@ -44,6 +44,7 @@ export interface Spec extends TurboModule { isChannelBlocked(channelId: string): Promise; openAlarmPermissionSettings(): Promise; openNotificationSettings(channelId: string | null): Promise; + shouldShowRequestPermissionRationale(): Promise; openBatteryOptimizationSettings(): Promise; isBatteryOptimizationEnabled(): Promise; getPowerManagerInfo(): Promise; diff --git a/packages/react-native/src/types/Module.ts b/packages/react-native/src/types/Module.ts index 8ca86454..2ca1f5af 100644 --- a/packages/react-native/src/types/Module.ts +++ b/packages/react-native/src/types/Module.ts @@ -402,6 +402,23 @@ export interface Module { */ openNotificationSettings(channelId?: string): Promise; + /** + * API used to find out whether Android shows the notification permission dialog once + * more after the user denied it. + * + * Android 13 (API 33) and later show the `POST_NOTIFICATIONS` dialog at most twice. After + * the first denial this resolves `true`, the moment the Android guidelines want the app to + * explain why it needs notifications before it calls `requestPermission` again. After the + * second denial it resolves `false`, from then on only the system settings can turn + * notifications on. Wraps `Activity.shouldShowRequestPermissionRationale`. + * + * It also resolves `false` before the first request, below API 33, without a current + * Activity and on iOS. + * + * @platform android + */ + shouldShowRequestPermissionRationale(): Promise; + /** * API used to register a foreground service on Android devices. * From a65ba2e5745e5842ca02afbdd438e3cc039fbaba Mon Sep 17 00:00:00 2001 From: pinpong Date: Wed, 28 Oct 2026 07:10:20 +0700 Subject: [PATCH 2/2] docs: explain NOT_DETERMINED before the first permission request --- README.md | 4 +++- docs/react-native/android/permissions.mdx | 2 +- packages/react-native/README.md | 4 +++- 3 files changed, 7 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index b4679c23..5c014daf 100644 --- a/README.md +++ b/README.md @@ -943,7 +943,9 @@ if (authorizationStatus === AuthorizationStatus.DENIED) { } ``` -It resolves `false` before the first request, below API 33, without a current Activity and on iOS. See +It resolves `false` before the first request, below API 33, without a current Activity and on iOS. Before the +first `requestPermission()` call `getNotificationSettings()` reports `AuthorizationStatus.NOT_DETERMINED` on +Android 13+, so the `DENIED` check above already skips that case. See [Android Permissions: Asking again after a denial](https://docs.page/marcocrupi/react-native-notify-kit/react-native/android/permissions#asking-again-after-a-denial). ### `setNotificationConfig` (iOS) diff --git a/docs/react-native/android/permissions.mdx b/docs/react-native/android/permissions.mdx index b7317f84..77cbb502 100644 --- a/docs/react-native/android/permissions.mdx +++ b/docs/react-native/android/permissions.mdx @@ -68,7 +68,7 @@ If you determine notifications are disabled, you may want to offer the user the #### Asking again after a denial -On Android 13+, the system shows the `POST_NOTIFICATIONS` dialog at most twice. After the first denial, `getNotificationSettings` reports `AuthorizationStatus.DENIED` both when Android would show the dialog once more and when only the system settings can turn notifications on. Call `shouldShowRequestPermissionRationale` to tell the two apart. After the first denial it resolves `true` while the next `requestPermission()` call still shows the dialog, which is the moment the [Android guidelines](https://developer.android.com/training/permissions/requesting#explain) want the app to explain why it needs notifications before it asks. After the second denial it resolves `false`, then only the system settings can turn notifications on. It also resolves `false` before the first request, below API 33 and on iOS. +On Android 13+, the system shows the `POST_NOTIFICATIONS` dialog at most twice. After the first denial, `getNotificationSettings` reports `AuthorizationStatus.DENIED` both when Android would show the dialog once more and when only the system settings can turn notifications on. Call `shouldShowRequestPermissionRationale` to tell the two apart. After the first denial it resolves `true` while the next `requestPermission()` call still shows the dialog, which is the moment the [Android guidelines](https://developer.android.com/training/permissions/requesting#explain) want the app to explain why it needs notifications before it asks. After the second denial it resolves `false`, then only the system settings can turn notifications on. It also resolves `false` before the first request, below API 33 and on iOS. Before the first `requestPermission()` call, `getNotificationSettings` reports `AuthorizationStatus.NOT_DETERMINED` on Android 13+, so the `DENIED` check in the example below already rules that case out. ```js import notifee, { AuthorizationStatus } from 'react-native-notify-kit'; diff --git a/packages/react-native/README.md b/packages/react-native/README.md index 9b0579ee..37e12c17 100644 --- a/packages/react-native/README.md +++ b/packages/react-native/README.md @@ -943,7 +943,9 @@ if (authorizationStatus === AuthorizationStatus.DENIED) { } ``` -It resolves `false` before the first request, below API 33, without a current Activity and on iOS. See +It resolves `false` before the first request, below API 33, without a current Activity and on iOS. Before the +first `requestPermission()` call `getNotificationSettings()` reports `AuthorizationStatus.NOT_DETERMINED` on +Android 13+, so the `DENIED` check above already skips that case. See [Android Permissions: Asking again after a denial](https://docs.page/marcocrupi/react-native-notify-kit/react-native/android/permissions#asking-again-after-a-denial). ### `setNotificationConfig` (iOS)