Delivery by App State

## Who presents a notification, by app state A push that reaches a React Native app is presented by different parties depending on the app's state: - **Background or killed**: for a notification message with a title and body, the **operating system** shows it in the tray or as a banner; no JavaScript needs to run. - **Foreground**: the platform hands the notification to the **app**, which decides whether and how to present it. expo-notifications makes that decision a JavaScript callback. Its documented default is strict: **when no handler is set, or the handler does not respond in time, the notification is not shown**. That is why a team testing with the app open often concludes that "push is broken" when delivery is fine. ## setNotificationHandler `Notifications.setNotificationHandler(handler)` takes an object with: | Member | Required | Purpose | |---|---|---| | `handleNotification(notification)` | Yes | Resolves a `NotificationBehavior` for this notification | | `handleSuccess(id)` | No | Called after the behavior was applied | | `handleError(id, error)` | No | Called when the callback throws or times out | The behavior object has these fields: - `shouldShowBanner` — present it as a banner over the app; - `shouldShowList` — keep it in the notification list; - `shouldPlaySound` — play its sound; on Android, `false` also stops the heads-up drop-down from showing, whatever the priority; - `shouldSetBadge` — update the app icon badge, iOS only; - `priority` — an optional Android priority. `shouldShowAlert` still type-checks but is **deprecated**: expo-notifications logs a warning and asks for `shouldShowBanner` and/or `shouldShowList` instead. On iOS the flags map to the system's presentation options for foreground notifications. Passing `null` clears the handler, which returns the app to the default of showing nothing. ## The 3-second deadline `handleNotification` must resolve **within 3 seconds**, otherwise the notification is discarded and `handleError` receives a timeout error. Consequences: 1. Keep the callback cheap: read in-memory state, do not fetch from the network. 2. Do not wait on a slow storage read to decide; keep the needed state (such as the open conversation id) in memory. 3. Remember that a discarded notification is not retried later. ## Where to call it Call `setNotificationHandler` once, at **module scope** in a file that loads early (the app entry or root layout), not inside a screen. A handler set inside a screen exists only while that screen is mounted, so notifications arriving on other screens fall back to the default and vanish. ## A chat example The classic interview follow-up is the chat case: a message for the conversation the user is currently reading should not pop a banner, while a message for any other conversation should. The handler compares the notification's data with the conversation on screen and answers accordingly. The screen updates its own id in a module-level variable or store when it gains and loses focus. Separately, `Notifications.addNotificationReceivedListener` fires for notifications received while the app is running in the foreground. It does not decide presentation; it is for side effects such as incrementing an unread counter or refreshing the message list. ## Testing the handler Foreground behavior is easy to get wrong because developers usually test with the app open and the handler already set. A short manual matrix catches most defects: 1. App open on the conversation named in the push: no banner, no sound, message appears in the list. 2. App open on another screen: banner and sound. 3. App in the background: the OS shows the notification; the handler is not involved. 4. Handler deliberately slowed past 3 seconds in a debug build: the notification disappears and `handleError` fires. Running the matrix on both platforms matters, because iOS maps the flags to its presentation options while Android maps them to its own display rules, including the sound quirk above. ## Common mistakes - Expecting the OS to show foreground notifications automatically, as it does in the background. - Setting the handler inside one screen's effect. - Doing network work inside `handleNotification` and hitting the 3-second timeout. - Still returning only `shouldShowAlert` and relying on a deprecated field. - Confusing the handler (presentation) with the received listener (side effects).