` declarations for these helpers, and the helper does not use the direct `ACTION_REQUEST_IGNORE_BATTERY_OPTIMIZATIONS` request path. Whitelisting the app in vendor settings can restore normal reboot delivery and reduce background foreground-service kills on affected devices, but this remains subject to OEM firmware and user/device policy β so this helper is a mitigation path for **both** trigger-notification reliability and foreground-service reliability on OEM devices.
A typical integration that combines both layers looks like this:
```typescript
import notifee from 'react-native-notify-kit';
import { Alert, Platform } from 'react-native';
if (Platform.OS === 'android') {
const info = await notifee.getPowerManagerInfo();
if (info.activity) {
// The user is on a device with a known vendor autostart activity.
// Prompt them once (e.g. on first run, or after a scheduled notification
// fails to fire on time), explaining why exact timing depends on this
// permission.
Alert.alert(
'Allow background activity',
'Your device restricts background apps by default. To reliably receive scheduled notifications, please enable autostart for this app.',
[
{ text: 'Open settings', onPress: () => notifee.openPowerManagerSettings() },
{ text: 'Later', style: 'cancel' },
],
);
}
}
```
For the authoritative vendor-by-vendor matrix of autostart, battery optimization, and background-restriction behavior, see [dontkillmyapp.com](https://dontkillmyapp.com/).
> **Scope note:** the cold-start recovery path is best-effort. It runs as soon as Android invokes `InitProvider.onCreate` (before `Application.onCreate`), but may still be delayed by minutes or hours on a device where the user never opens your app after a reboot. For use cases that require guaranteed sub-second timing (alarm clocks, time-sensitive reminders, calendar events), also declare `USE_EXACT_ALARM` in your manifest (see the [note above](#bugs-fixed-from-upstream-notifee)) and prompt the user to whitelist your app via the vendor settings helper.
>
> **Defense in depth:** the cold-start `BOOT_COUNT` path and the traditional `RebootBroadcastReceiver` path both funnel into the same `NotifeeAlarmManager.rescheduleNotifications` entry point, which is guarded by a process-wide `AtomicBoolean` β whichever path runs first wins the reschedule cycle, and the second logs `Reschedule already in progress, skipping duplicate request` and exits cleanly. On real devices the two paths often _both_ fire, for a subtle reason observed during Step 6 smoke testing: when the system force-stops your app (during an install, crash recovery, or a `pm clear` from a QA tool) and then Android re-delivers `BOOT_COMPLETED` as soon as the package is launched again, the reboot receiver runs at the same time as `InitProvider.onCreate`'s cold-start check. You get both paths for free β proof of the race guard's design. On an OEM device that suppresses `BOOT_COMPLETED` outright, only the cold-start path runs. Either way the zombie re-fire loop is broken.
### Trigger Notification Reliability
This fork defaults to AlarmManager for trigger notifications on Android, instead of WorkManager.
This ensures scheduled notifications are delivered reliably even when the app is killed.
The original Notifee used WorkManager by default, which is battery-friendly but unreliable
for time-sensitive notifications β Android may defer or drop WorkManager tasks based on
battery optimization, Doze mode, and OEM power management.
This path also handles normal reboot recovery. Android clears `AlarmManager` registrations
during reboot, but NotifyKit persists local trigger notifications and re-arms them after boot.
Future one-shot `TriggerType.TIMESTAMP` triggers are supported by this recovery path; a trigger
does not need to be recurring or daily only to survive reboot, and push notifications are not
required for local scheduled trigger recovery. If exact-alarm access is missing, NotifyKit falls
back to an inexact alarm so the trigger is retained, but exact fire timing is not guaranteed.
If you need battery-friendly scheduling where exact timing is not critical (e.g., daily digest
notifications), you can opt out:
```typescript
await notifee.createTriggerNotification(notification, {
type: TriggerType.TIMESTAMP,
timestamp: Date.now() + 60000,
alarmManager: false, // Uses WorkManager instead
});
```
#### AlarmType guide
When `alarmManager` is enabled (the default), the `alarmManager.type` field selects which
`android.app.AlarmManager` primitive is used to schedule the trigger. This fork supports all
five `AlarmType` values β including `SET_ALARM_CLOCK`, which upstream Notifee tracked in
[invertase/notifee#655](https://github.com/invertase/notifee/issues/655) and merged via
[#749](https://github.com/invertase/notifee/pull/749).
| AlarmType | Exact? | Wakes device? | Doze bypass? | Status bar icon | When to use |
| -------------------------------- | ------ | ------------- | ------------ | --------------- | ------------------------------------------------------------------------------ |
| `SET` | No | Yes | No | No | Non-critical reminders that can slip by several minutes (daily digest). |
| `SET_AND_ALLOW_WHILE_IDLE` | No | Yes | Yes | No | Non-critical reminders that must still fire while the device is in Doze. |
| `SET_EXACT` | Yes | Yes | No | No | Time-sensitive reminders when the app is reasonably sure not to be in Doze. |
| `SET_EXACT_AND_ALLOW_WHILE_IDLE` | Yes | Yes | Yes | No | **Fork default.** Time-sensitive reminders that must fire even in Doze. |
| `SET_ALARM_CLOCK` | Yes | Yes | Yes | **Yes** | True alarm-clock / recovery-timer use cases β highest priority, OEM-resilient. |
`SET_ALARM_CLOCK` is the strongest Android guarantee available for a scheduled notification:
- **Status-bar alarm-clock icon.** The system renders the alarm-clock glyph in the status bar
until the trigger fires, signalling to the user that an alarm is pending.
- **Least susceptible to OEM power management.** Vendor aggressive-kill policies (Xiaomi MIUI,
Oppo ColorOS, Huawei EMUI, Vivo FuntouchOS β documented in the "OEM Background Restrictions"
section and on [dontkillmyapp.com](https://dontkillmyapp.com/)) generally respect
`setAlarmClock` even when they would otherwise drop `setExactAndAllowWhileIdle`. This is the
same mechanism the stock Clock app uses.
- **Intended for the same reliability problem as [invertase/notifee#734](https://github.com/invertase/notifee/issues/734).**
If your use case is a time-sensitive reminder, a rest-timer between gym sets, a cooking timer,
or any recovery-timer scenario where a missed notification is user-visible damage, prefer
`SET_ALARM_CLOCK` over the fork default.
```typescript
import notifee, { AlarmType, TriggerType } from 'react-native-notify-kit';
await notifee.createTriggerNotification(
{
title: 'Rest complete',
body: 'Next set is ready.',
android: { channelId: 'timers' },
},
{
type: TriggerType.TIMESTAMP,
timestamp: Date.now() + 90_000,
alarmManager: {
type: AlarmType.SET_ALARM_CLOCK,
},
},
);
```
**Exact-alarm permission on Android 12+.** `SET_EXACT`, `SET_EXACT_AND_ALLOW_WHILE_IDLE`,
and `SET_ALARM_CLOCK` all require exact-alarm access through `SCHEDULE_EXACT_ALARM` or
`USE_EXACT_ALARM`. This affects exact fire timing, not trigger persistence. If permission is
not granted, Notifee falls back to `setAndAllowWhileIdle` (inexact) instead of crashing or
dropping the trigger. Apps that require exact timing should check
`getNotificationSettings().android.alarm`, explain the permission, and guide users with
`openAlarmPermissionSettings()`. `SET_ALARM_CLOCK` can be considered for alarm-clock or
timer-like use cases within Android and Google Play policy constraints.
### Timers: foreground service or `SET_ALARM_CLOCK`?
A common question for this fork: **should a rest / cooking / recovery timer be a foreground service, or a scheduled trigger notification?** For most timer use cases the answer is the trigger path β and specifically `SET_ALARM_CLOCK`.
| Timer characteristic | Recommended approach |
| ----------------------------------------------------------------------- | -------------------------------------------------------------------------- |
| Fires once at a known time, no live UI update while app is backgrounded | **`SET_ALARM_CLOCK` trigger** (see [AlarmType guide](#alarmtype-guide)) |
| Fires repeatedly at known intervals | **`SET_ALARM_CLOCK` trigger** with app-side scheduling of the next cycle |
| Needs a live ticking notification UI while app is backgrounded | Foreground service (`mediaPlayback` if audio, otherwise reconsider the UX) |
| Streams audio, music, or guided voice | Foreground service with `mediaPlayback` |
| Continuous background work (location, Bluetooth) | Foreground service with the matching type from the matrix above |
**Why `SET_ALARM_CLOCK` is usually the right choice for timers:**
- **OEM-resilient.** Vendor aggressive-kill policies (Xiaomi MIUI, Oppo ColorOS, Huawei EMUI, Vivo FuntouchOS, Samsung OneUI) generally respect `setAlarmClock` even when they drop `setExactAndAllowWhileIdle` and kill foreground services. This is the same primitive the stock Clock app uses.
- **No `foregroundServiceType` to pick.** You avoid the Doze / Play-policy / Android 15 timeout maze entirely.
- **No risk of Play Store rejection** for misusing `mediaPlayback` on a silent timer.
- **No wake lock to manage.** The library's foreground-service path does not acquire a wake lock on your behalf β under Doze on a non-exempt `foregroundServiceType`, the CPU can still suspend with the screen off. `SET_ALARM_CLOCK` wakes the device at fire time regardless of Doze state.
**When a foreground service _is_ the right choice:**
- You need the notification to tick every second while the app is backgrounded (metronome with audio, VoIP call, active GPS track). A `SET_ALARM_CLOCK` trigger fires once at the scheduled time, not continuously.
- You need actual audio playback β use `mediaPlayback`.
- You need continuous location updates β use `location`.
For the specific use case in [invertase/notifee#410](https://github.com/invertase/notifee/issues/410) (rest timer between workout sets, screen off, OEM device), `SET_ALARM_CLOCK` is the recommended path. Pair it with `openPowerManagerSettings()` for defense in depth on OEM devices β see the [OEM Background Restrictions](#oem-background-restrictions) section above.
### Android: `pressAction` defaults to opening the app on tap
On Android, `pressAction` now defaults to `{ id: 'default', launchActivity: 'default' }` when omitted from the notification payload. This means tapping a notification opens the app's main activity by default β matching iOS behavior and eliminating a common footgun where trigger notifications appeared to work but tapping them did nothing after an app kill.
You can still provide an explicit `pressAction` to customize tap behavior:
```typescript
await notifee.displayNotification({
title: 'Hello',
body: 'Tap to open',
android: {
channelId: 'default',
pressAction: { id: 'default', launchActivity: 'default' }, // same as the default
},
});
```
To create a non-tappable notification (e.g. purely informative notifications from a background service), pass `pressAction: null` explicitly:
```typescript
await notifee.displayNotification({
title: 'Sync in progress',
body: 'Uploading files...',
android: {
channelId: 'default',
pressAction: null, // notification displays but tapping does nothing
},
});
```
## New APIs
### Full-Screen Intent availability (Android)
Use `getNotificationSettings()` to check whether the app currently has access to use Full-Screen Intents:
```typescript
import notifee, { AndroidNotificationSetting } from 'react-native-notify-kit';
const settings = await notifee.getNotificationSettings();
if (settings.android.fullScreenIntent === AndroidNotificationSetting.DISABLED) {
// Full-Screen Intent access is currently unavailable.
}
```
`AndroidNotificationSetting.ENABLED` reports Full-Screen Intent access; it does not guarantee that a particular
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.
### `setNotificationConfig` (iOS)
Controls whether Notifee intercepts remote (push) notification tap events on iOS.
When using React Native Firebase Messaging alongside Notifee, call this at app startup
to let Firebase handle remote notification taps:
```typescript
import notifee from 'react-native-notify-kit';
await notifee.setNotificationConfig({
ios: { handleRemoteNotifications: false },
});
```
With `handleRemoteNotifications: false`:
- Remote notifications (FCM) β handled by Firebase Messaging (`onNotificationOpenedApp`, `getInitialNotification`)
- Local Notifee notifications β still handled by Notifee (unchanged)
Default is `true` (backward compatible β Notifee handles everything, same as original Notifee behavior).
## Advanced
### Troubleshooting
#### Scheduled Android trigger notifications do not fire after reboot
Android removes `AlarmManager` registrations during reboot. NotifyKit persists local trigger
notifications and re-arms them through `app.notifee.core.RebootBroadcastReceiver` after a
normal reboot, with a cold-start `BOOT_COUNT` recovery path for devices that delay or suppress
`BOOT_COMPLETED`. If triggers do not return after reboot, check the generated app rather than
only the source manifest:
- Verify the final merged manifest contains `android.permission.RECEIVE_BOOT_COMPLETED`,
`android.permission.SCHEDULE_EXACT_ALARM`, `app.notifee.core.RebootBroadcastReceiver` with
`android.intent.action.BOOT_COMPLETED`, `app.notifee.core.NotificationAlarmReceiver`, and
`io.invertase.notifee.NotifeeInitProvider`.
- For Expo CNG/prebuild apps, these entries normally arrive from the NotifyKit library manifest
through manifest merge. A custom boot-receiver config plugin is usually unnecessary and can
break recovery if it replaces the receiver declaration or intent filters.
- Use package-specific logcat output. Do not rely only on `adb logcat -s NOTIFEE`; reboot
recovery logs use native tags such as `RebootReceiver`, `NotifeeAlarmManager`, `InitProvider`,
and `AlarmPermissionReceiver`, while Android broadcast logs include your real application ID.
- Compare `adb shell dumpsys alarm` before and after reboot, filtered by your real package name,
to confirm the pending alarm disappears during reboot and is re-armed afterward.
- Check exact-alarm permission if timing is late. Without permission, NotifyKit falls back to an
inexact alarm: the trigger is retained, but exact fire timing is not guaranteed.
- Check OEM autostart and background restrictions, especially on Xiaomi/Redmi, Oppo/Realme,
Huawei/Honor, Vivo/iQOO, and Samsung devices.
- Validate with 1-5 future one-shot `TriggerType.TIMESTAMP` triggers before scaling up to large
batches such as 50 active triggers.
#### Small icon not showing in Android release builds (falls back to launcher icon)
From 10.1.0, when the resource ID for `android.smallIcon` cannot be resolved at runtime, the library logs a warning and falls back to your app's launcher icon instead of failing the notification display. If you see your launcher icon in a notification where you expected a custom small icon, filter logcat for the `NOTIFEE` tag to find the resolution failure.
Three causes account for the vast majority of reports:
**Asset only in `src/debug/res/`.** When you add a drawable from Android Studio with the "Image Asset" wizard, the IDE sometimes places it under the `debug` variant only. The resource exists in debug builds but disappears in release. Copy or move the asset into `android/app/src/main/res/drawable-*/` (and the density buckets) so it participates in the release build.
**R8 / ProGuard resource shrinking.** Release builds with `shrinkResources true` in the app's `build.gradle` can strip drawables that R8 judges unreferenced from code. Declare the asset as keep in `android/app/src/main/res/raw/keep.xml`:
```xml
```
**Naming mismatch.** Android resource names are case-sensitive and only accept `[a-z0-9_]`. A string like `smallIcon: 'icNotification'` will not resolve `ic_notification.png`. Rename the `smallIcon` value to match the file on disk exactly.
For the full procedure on creating a small-icon asset via Android Studio, see [docs/react-native/android/appearance.mdx](docs/react-native/android/appearance.mdx).
#### Custom sounds for push notifications in background or killed state
If you've set `android.sound` and `ios.sound` in `displayNotification(...)` and the custom sound plays only when the app is in foreground, this is expected platform behavior β not a library bug. When a **remote push** (FCM/APNs) arrives while the app is killed, your JavaScript code never runs, so anything you configured client-side is ignored.
The fix is to set the sound in the push payload **server-side**:
- **Android (FCM)**: set `AndroidNotification.sound` in the FCM payload to the name of a sound file bundled in `android/app/src/main/res/raw/`. Make sure the `NotificationChannel` was created with the same sound β the channel sound is immutable after creation, so changing the sound requires creating a channel under a new `channelId`.
- **iOS (APNs)**: either set `aps.sound` directly to the name of a sound file bundled in your app, or β if you need richer rewriting (image attachments, dynamic content) β install the Notification Service Extension and ship the sound under `notifee_options.ios.sound` in the push payload. See [`docs/react-native/ios/remote-notification-support.mdx`](docs/react-native/ios/remote-notification-support.mdx).
An advanced alternative on Android is to switch the backend to an FCM **data-only** payload and call `notifee.displayNotification()` from a headless task β this lets the JS-side `android.sound` win, at the cost of running JS on every push. Most apps should prefer the server-side payload approach.
**Local notifications are different.** This limitation only affects **remote pushes** delivered by FCM/APNs while the app is killed. Notifications scheduled locally via `notifee.displayNotification()` or `notifee.createTriggerNotification()` β for example, a timer firing after the user closed the app β _do_ honor the JS-side `sound` parameter, because the library itself wakes up and presents the notification (via `AlarmManager` on Android or `UNUserNotificationCenter` on iOS). The usual platform rules still apply: on Android the `NotificationChannel` sound is immutable after creation and wins over the per-notification `sound`; on iOS the sound file must be bundled in the app (`.wav`/`.aiff`/`.caf`, under 30 seconds, in the main bundle). For reliable local timer notifications on OEM devices that aggressively kill background work, prefer `AlarmType.SET_ALARM_CLOCK` β see the [Timers: foreground service or `SET_ALARM_CLOCK`?](#timers-foreground-service-or-set_alarm_clock) section.
Reference: [invertase/notifee#927](https://github.com/invertase/notifee/issues/927).
#### Silent pushes and background fetch β handled by Firebase, not by this library
`react-native-notify-kit` hooks into `UNUserNotificationCenterDelegate` on iOS to display notifications and dispatch tap/delivery events to JS. It does **not** hook into `application:didReceiveRemoteNotification:fetchCompletionHandler:` β the iOS entry point for silent pushes (`content-available: 1` with no visible alert) and background fetch. Those paths belong to [`@react-native-firebase/messaging`](https://rnfirebase.io/messaging/usage) via `setBackgroundMessageHandler`.
If a silent push arrives while the app is killed and its only job is to trigger JS code (no notification displayed), subject to iOS's background budget it is handled entirely by Firebase's path β `notifee.onBackgroundEvent` will not fire, by design. If the silent push's JS handler then calls `notifee.displayNotification()`, the subsequent user tap on the displayed notification does flow through Notifee and fires `onBackgroundEvent` normally.
Relates to upstream [invertase/notifee#597](https://github.com/invertase/notifee/issues/597) for apps with slow startup. For remote notifications that should fire `onBackgroundEvent` reliably on iOS, use [FCM Mode](docs/fcm-mode.mdx) β see also the note on [#1133](https://github.com/invertase/notifee/issues/1133) in the FCM Mode guide.
#### `Could not resolve app.notifee:core:+` β does not apply to this fork
If you arrived here from a Google search for this error, note: the error is specific
to `@notifee/react-native` (the archived upstream package), where the native core was
distributed as a pre-compiled AAR inside a bundled Maven repo at
`node_modules/@notifee/react-native/android/libs/`. The fork eliminated that
distribution model in 9.2.0 β the core compiles from source as part of the bridge
module, so there is no Maven coordinate to resolve, no `extraMavenRepos` to configure
on Expo, and no `FAIL_ON_PROJECT_REPOS` conflict on RN 0.74+. Migrating from
`@notifee/react-native` to `react-native-notify-kit` removes the error with no
additional `build.gradle` patching, no Android config plugin for this Maven issue,
and no Expo `extraMavenRepos` entry.
References: upstream issues [#1079](https://github.com/invertase/notifee/issues/1079),
[#1226](https://github.com/invertase/notifee/issues/1226),
[#1262](https://github.com/invertase/notifee/issues/1262).
### Manual warmup control
The library automatically pre-warms the foreground service notification path during app startup via `InitProvider`. **Most apps do not need to do anything extra.** However, in certain edge cases the automatic warmup may not be sufficient:
- **Lazy-loaded library** β if `react-native-notify-kit` is code-split or lazy-loaded, `InitProvider` runs but the TurboModule/JS bridge side isn't initialized yet.
- **Post-splash-screen warmup** β apps that want to defer warmup to after the splash screen instead of during `Application.onCreate()`.
- **Low-end devices** β rare cases where the `InitProvider` warmup hasn't finished by the time the user triggers the first notification.
For these cases, call `prewarmForegroundService()` at a moment of your choosing:
```typescript
import notifee from 'react-native-notify-kit';
// Call after splash screen, during onboarding, or before the user
// is likely to trigger a foreground service notification.
await notifee.prewarmForegroundService();
```
**Key facts:**
- **Idempotent** β safe to call multiple times; class loading after the first call is a no-op from ART's perspective.
- **iOS no-op** β resolves immediately on iOS (Android-only optimization).
- **Does NOT start a foreground service** β it only performs class loading and Binder proxy warming. No Google Play policy risk.
- **Best-effort** β internal failures are logged and swallowed; the promise always resolves.
To verify whether calling this method provides a measurable benefit for your app, capture a Perfetto trace with the `notifee:*` trace sections enabled and compare the `notifee:displayNotification` duration with and without the prewarm call.
### Regenerating the Baseline Profile
The library ships a Baseline Profile (`packages/react-native/android/src/main/baseline-prof.txt`) that instructs ART to AOT-compile the notification hot path at install time. This profile should be regenerated after significant changes to the notification display code path.
**Prerequisites:**
- A physical device connected via adb (Pixel 9 Pro XL with Android 16+ recommended) or a running emulator with API 33+
- The smoke app must be buildable (`yarn install` in the repo root)
**Command:**
```bash
bash scripts/generate-baseline-profile.sh
```
The script runs the macrobenchmark test in `apps/smoke/android/baselineprofile/`, captures the profile on the connected device, filters it to library-only rules, and copies it to the library's `src/main/baseline-prof.txt`. Review the generated file for unexpected entries, then commit it.
## Documentation
The full `react-native-notify-kit` documentation is hosted on docs.page and is kept in sync with this repo. It covers the public API, platform guides, FCM Mode, the server SDK, and the `init-nse` CLI.
- [Overview](https://docs.page/marcocrupi/react-native-notify-kit/react-native/overview)
- [Reference](https://docs.page/marcocrupi/react-native-notify-kit/react-native/reference)
### Android
The APIs for Android allow for creating rich, styled and highly interactive notifications. Below you'll find guides that cover the supported Android features.
| Topic | |
| -------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------- |
| [Appearance](https://docs.page/marcocrupi/react-native-notify-kit/react-native/android/appearance) | Change the appearance of a notification; icons, colors, visibility etc. |
| [Behaviour](https://docs.page/marcocrupi/react-native-notify-kit/react-native/android/behaviour) | Customize how a notification behaves when it is delivered to a device; sound, vibration, lights etc. |
| [Channels & Groups](https://docs.page/marcocrupi/react-native-notify-kit/react-native/android/channels) | Organize your notifications into channels & groups to allow users to control how notifications are handled on their device. |
| [Foreground Service](https://docs.page/marcocrupi/react-native-notify-kit/react-native/android/foreground-service) | Long running background tasks can take advantage of an Android Foreground Service to display an on-going, prominent notification. |
| [Grouping & Sorting](https://docs.page/marcocrupi/react-native-notify-kit/react-native/android/grouping-and-sorting) | Group and sort related notifications in a single notification pane. |
| [Interaction](https://docs.page/marcocrupi/react-native-notify-kit/react-native/android/interaction) | Allow users to interact with your application directly from the notification, with actions. |
| [Progress Indicators](https://docs.page/marcocrupi/react-native-notify-kit/react-native/android/progress-indicators) | Show users a progress indicator of an on-going background task, and learn how to keep it updated. |
| [Styles](https://docs.page/marcocrupi/react-native-notify-kit/react-native/android/styles) | Style notifications to show richer content, such as expandable images/text, or message conversations. |
| [Timers](https://docs.page/marcocrupi/react-native-notify-kit/react-native/android/timers) | Display counting timers on your notification, useful for on-going tasks such as a phone call, or event time remaining. |
### iOS
Below you'll find guides that cover the supported iOS features.
| Topic | |
| -------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------- |
| [Appearance](https://docs.page/marcocrupi/react-native-notify-kit/react-native/ios/appearance) | Change how the notification is displayed to your users. |
| [Badges](https://docs.page/marcocrupi/react-native-notify-kit/react-native/ios/badges) | Manage the app icon badge count on iOS devices. |
| [Behaviour](https://docs.page/marcocrupi/react-native-notify-kit/react-native/ios/behaviour) | Control how notifications behave when they are displayed on a device; sound, critical alerts, etc. |
| [Categories](https://docs.page/marcocrupi/react-native-notify-kit/react-native/ios/categories) | Create & assign categories to notifications. |
| [Interaction](https://docs.page/marcocrupi/react-native-notify-kit/react-native/ios/interaction) | Handle user interaction with your notifications. |
| [Permissions](https://docs.page/marcocrupi/react-native-notify-kit/react-native/ios/permissions) | Request permission from your application users to display notifications. |
| [Remote Notification Support](https://docs.page/marcocrupi/react-native-notify-kit/react-native/ios/remote-notification-support) | Handle and display remote notifications with Notification Service Extension. |
## Trademark Notice
"Notifee" is a trademark of Invertase. This project is not affiliated with, endorsed by, or sponsored by Invertase. The name "Notifee" is used solely to describe the origin and compatibility of this fork, as permitted under nominative fair use.
## License
- See [LICENSE](/LICENSE). This fork remains licensed under Apache-2.0.
---
Originally built by Invertase. This fork is independently maintained by Marco Crupi.
- Officially recommended by Invertase as the community-maintained fork (April 2026)
- Maintained fork of Notifee β actively developed and published as `react-native-notify-kit`
- New Architecture only (TurboModules)
- Expo CNG / prebuild support for development builds. Expo Go is not supported.
- iOS FCM Mode Notification Service Extension automation via config plugin.
- Android foreground service manifest configuration via config plugin, with explicit opt-in for foreground service types.
- Android Expo FCM smoke validation using RNFirebase data-only messages and `notifee.handleFcmMessage`.
- Minimum supported React Native: `>=0.73`
- Development target: React Native `0.85.3`
- License: `Apache-2.0`
- Full changelog: [CHANGELOG.md](CHANGELOG.md)
The native core (NotifeeCore) is compiled from source as part of the bridge module (since 9.2.0) and the public API is **100% compatible** with the original `@notifee/react-native` β migration is a safe, drop-in replacement.
## Installation
```bash
yarn add react-native-notify-kit
# or
npm install react-native-notify-kit
```
For iOS, run `cd ios && pod install` after installing.
## Migration from @notifee/react-native
If you're coming from the original Notifee package, migrating takes just a few steps:
1. **Swap the package:**
```bash
yarn remove @notifee/react-native
yarn add react-native-notify-kit
```
2. **Update imports** β find and replace across your codebase:
```diff
- import notifee from '@notifee/react-native';
+ import notifee from 'react-native-notify-kit';
```
The default export is still called `notifee`, so your application code stays the same β only the import path changes.
3. **Reinstall pods** (iOS):
```bash
cd ios && pod install
```
No native code changes are required. The public API is fully compatible with `@notifee/react-native`.
## Quick Start
```ts
import notifee, { AndroidImportance } from 'react-native-notify-kit';
// 1. Request permission (required on Android 13+ and iOS)
await notifee.requestPermission();
// 2. Create a channel (Android only, required for Android 8+)
await notifee.createChannel({
id: 'default',
name: 'Default Channel',
importance: AndroidImportance.HIGH,
});
// 3. Display a notification
await notifee.displayNotification({
title: 'Hello',
body: 'This is a local notification',
android: { channelId: 'default' },
});
```
> **Note:** The default export name `notifee` is kept intentionally for backward compatibility. If you're migrating from `@notifee/react-native`, a simple find-and-replace of the import path is all you need.
### 4. Handle events
In your `index.js` (before `AppRegistry.registerComponent`):
```ts
import notifee from 'react-native-notify-kit';
// Background/killed state events
notifee.onBackgroundEvent(async ({ type, detail }) => {
console.log('Background event:', type, detail.notification?.id);
});
```
In your React component:
```ts
import { useEffect } from 'react';
import notifee, { EventType } from 'react-native-notify-kit';
useEffect(() => {
return notifee.onForegroundEvent(({ type, detail }) => {
if (type === EventType.PRESS) {
console.log('Notification pressed:', detail.notification?.id);
}
});
}, []);
```
> **Android event reliability:** Registering `onForegroundEvent()` initializes the native event relay. Pending events received while the `ReactContext` is unavailable are buffered. If the context becomes unavailable after a flush takes its buffer snapshot, undelivered events are requeued so a later native event relay flush can deliver them without duplication in the validated recovery path, while preserving FIFO, the 10-event capacity, and drop-oldest behavior. No application code changes or warm-up calls such as `getDisplayedNotifications()` are required; continue registering foreground and background handlers at the recommended points shown above. This hardens the Android event path investigated in [react-native-notify-kit#47](https://github.com/marcocrupi/react-native-notify-kit/issues/47) and relates to the event reliability and buffering problem tracked in [invertase/notifee#1279](https://github.com/invertase/notifee/issues/1279); the scenarios are not necessarily identical.
> **Which handler fires when (iOS):**
>
> - Tap a notification while the app is **active in foreground** β `onForegroundEvent` receives `PRESS`.
> - Tap a notification while the app is **in background or killed** β `onBackgroundEvent` receives `PRESS`, even though iOS immediately brings the app to the foreground right after. At the moment iOS delivers the tap to the delegate, `UIApplication.applicationState` is `Inactive`, not `Active`, so the event is routed to the background handler.
> - Foreground delivery of a Notifee-owned notification β `onForegroundEvent` receives `DELIVERED`.
>
> Register **both** handlers if you need to react to taps in every app state. Resolves the confusion reported in upstream [invertase/notifee#1155](https://github.com/invertase/notifee/issues/1155).
### Android notification numbers and launcher badges
For notifications displayed through `notifee.displayNotification()`, use `android.badgeCount` to associate a number with
an individual Android notification:
```ts
await notifee.createChannel({
id: 'messages',
name: 'Messages',
badge: true,
});
await notifee.displayNotification({
id: 'messages',
title: 'New messages',
body: 'You have 5 unread messages',
android: {
channelId: 'messages',
badgeCount: 5,
},
});
```
`android.badgeCount` belongs to that notification and maps conceptually to AndroidX
`NotificationCompat.Builder.setNumber(...)`. Display the notification again with the same `id` and a new `badgeCount`
to update or replace it. The notification number itself is not limited to API level 26.
On Android 8.0 (API level 26) and above, `badge: true` allows notifications in the channel to contribute to launcher
badging; it does not set a count. Launcher and OEM behavior determines whether a number, only a notification dot, or a
different aggregation is shown, so a numeric badge on the app icon is not guaranteed.
Unlike the global iOS `notifee.setBadgeCount()` API, Android has no equivalent standard public API independent of posted
notifications. `badgeCount: 0` neither cancels the posted notification nor provides a portable way to clear a global
Android badge. See [Android Appearance: Badges](https://docs.page/marcocrupi/react-native-notify-kit/react-native/android/appearance#badges)
for complete details.
## Notifee FCM Mode (NEW in 10.0.0, Expo CNG in 10.4.0)
**Use `react-native-notify-kit` as the sole FCM display layer on both Android and iOS**: one developer API, no duplicate notifications on Android, no silent-push drops on iOS. Ship a server SDK payload, let the client handle it in one line, and set up the iOS Notification Service Extension with the Expo config plugin or, for bare React Native, the `init-nse` CLI. On Android, FCM Mode remains data-only: RNFirebase receives the message and calls `notifee.handleFcmMessage`.
```bash
# server: build the payload
import { buildNotifyKitPayload } from 'react-native-notify-kit/server';
await admin.messaging().send(buildNotifyKitPayload({ token, notification: { title, body, android, ios } }));
# client (Android + iOS): one line in setBackgroundMessageHandler / onMessage
await notifee.handleFcmMessage(remoteMessage);
# iOS NSE setup for bare React Native
npx react-native-notify-kit init-nse && cd ios && pod install
```
Need to inspect or patch a reconstructed notification before displayβfor example, to apply your own Android BigPicture image? Use `notifee.buildFcmNotification(remoteMessage)`, modify the returned notification, then call `displayNotification()` yourself. Do not also call `handleFcmMessage` for that message. See the [FCM Mode guide](docs/fcm-mode.mdx) for the complete build-only flow and iOS display-policy considerations.
### Expo CNG / development builds
Expo CNG / development builds are supported. Expo Go is not supported because this library requires native modules and native notification targets/capabilities.
On iOS, add the config plugin to your Expo config and run prebuild; the plugin generates and wires the Notification Service Extension used by NotifyKit FCM Mode.
```ts
export default {
expo: {
name: 'MyApp',
slug: 'my-app',
ios: {
bundleIdentifier: 'com.example.myapp',
},
plugins: [
[
'react-native-notify-kit',
{
ios: {
notificationServiceExtension: true,
},
},
],
],
},
};
```
On Android, FCM Mode stays data-only. Configure Firebase and RNFirebase in the app, create the Android channel used by your payloads, then call `notifee.handleFcmMessage(remoteMessage)` from RNFirebase `onMessage` and `setBackgroundMessageHandler`. The Expo smoke app validates foreground and background delivery with the `android-expo-smoke` scenario on a real device.
Android foreground service manifest configuration is also available through the NotifyKit config plugin, but it is explicit opt-in:
```ts
export default {
expo: {
plugins: [
[
'react-native-notify-kit',
{
android: {
foregroundService: {
types: ['shortService'],
},
},
},
],
],
},
};
```
The plugin does not configure Firebase, does not add `USE_EXACT_ALARM`, does not add `USE_FULL_SCREEN_INTENT`, and does not choose a foreground service type by default.
See the full guide: **[docs/fcm-mode.mdx](docs/fcm-mode.mdx)** β covers architecture, server SDK reference, client API, NSE setup, payload schema, migration, troubleshooting, and known limitations.
## Push Notifications (Firebase)
This library handles notification **display and management**. For receiving push notifications, pair it with [`@react-native-firebase/messaging`](https://rnfirebase.io/messaging/usage):
Firebase setup remains the consumer app's responsibility. The NotifyKit Expo config plugin does not install or configure Firebase, does not copy `google-services.json`, and does not patch Gradle for Firebase.
> **New in 10.0.0:** for a turnkey FCM integration that handles both platforms (no duplicate on Android, APNs-reliable on iOS), use **[Notifee FCM Mode](docs/fcm-mode.mdx)** instead of the manual pattern below. The sections that follow still apply for basic Firebase setup (google-services plugin, permissions, APNs capability).
### Android setup
1. Add Firebase dependencies to your app:
```bash
yarn add @react-native-firebase/app @react-native-firebase/messaging
```
2. Add the google-services plugin to `android/build.gradle`:
```gradle
classpath("com.google.gms:google-services:4.4.2")
```
3. Apply the plugin in `android/app/build.gradle`:
```gradle
apply plugin: "com.google.gms.google-services"
```
4. Download `google-services.json` from [Firebase Console](https://console.firebase.google.com/) and place it in `android/app/`.
5. Add `POST_NOTIFICATIONS` permission to `AndroidManifest.xml` (required for Android 13+):
```xml