iOS Background Notification Handler Hanging / App Not Quitting

[padge]

Right now, my iOS app is handling background notifications, but after the message is processed, the app remains "open" (in headless mode) for an extended period of time.

For example, when I finally open the app 30 minutes after receiving a message, I can see an in-memory log indicating the app was launched in Headless mode 30 minutes earlier and that the background message was handled. Shouldn't the OS kill the app after around 30 seconds?

The issue that arises from this is instead of the splash screen appearing, a blank white screen is displayed for a few seconds until the app is ready to render. Before I added the isHeadless check, my app would get completely stuck on the white screen.

I've implemented a workaround by manually showing the splash screen image using <Image />, but there's still a brief flash of a white screen before the image is shown. Plus it introduces a minor maintenance headache having two places to update the splash screen (background color fallback mainly).

Currently, I have the following Background Mode capabilities enabled: Background Fetch and Remote Notification.

Any idea what could be causing the app to keep running in headless mode?

Thanks for your help!

---

I'm using these dependencies (among others) on an Expo "bare" React Native project:

"@notifee/react-native": "7.8.2",
"@react-native-firebase/analytics": "21.0.0",
"@react-native-firebase/app": "21.0.0",
"@react-native-firebase/auth": "21.0.0",
"@react-native-firebase/messaging": "21.0.0",
"@react-native-firebase/remote-config": "21.0.0",
"expo": "^50.0.0",
"expo-splash-screen": "~0.26.5",
"react-native": "0.73.6",

My index.tsx file:

import { registerRootComponent } from "expo";
import messaging from "@react-native-firebase/messaging";
import AsyncStorage from "@react-native-async-storage/async-storage";
import App from "./src/App";
import { logs } from "./src/utils/logger";

messaging().setBackgroundMessageHandler(async (message) => {
  logs.APP.debug(
    `[Messaging] Background message received at ${new Date().toISOString()}`,
    message,
  );
  const start = Date.now();
  try {
    const currentMessages = await AsyncStorage.getItem("backgroundMessages");
    const messages = currentMessages ? JSON.parse(currentMessages) : [];
    messages.push(message);
    await AsyncStorage.setItem("backgroundMessages", JSON.stringify(messages));
  } catch (e) {
    logs.APP.error(`Error saving background message`, e);
  }
  const end = Date.now();
  logs.APP.debug(
    `[Messaging] Background task completed at: ${new Date().toISOString()}`,
    `(took ${end - start}ms).`,
  );
});

function HeadlessCheck({ isHeadless }: { isHeadless?: boolean }) {
  if (isHeadless) {
    logs.APP.debug(`HeadlessCheck - IS HEADLESS, returning null.`);
    return null;
  }

  logs.APP.debug(`HeadlessCheck - NOT headless, returning App.`);
  return <App />;
}

registerRootComponent(HeadlessCheck);

And a snippet of my App.tsx snippet to show how the splash screen is handled:

import * as SplashScreen from "expo-splash-screen";

export function App() {
  useEffect(() => {
    SplashScreen.preventAutoHideAsync();
  }, []);

  // ...

  const onLayoutRootView = useCallback(async () => {
    if (ready) {
      await SplashScreen.hideAsync();
    }
  }, [ready]);

  if (!ready) {
    return <SplashScreenFallback />;
  }

  return (
    <View style={{ flex: 1 }} onLayout={onLayoutRootView}>
      {/* ... */}
    </View>
  )
}

[padge]

Edit: I tried to hide the splash screen when headless and thought it was fixed but it actually wasn't - using expo-splash-screen it actually throws an error when trying to hide the splash screen in headless mode.

[padge]

Just to note, I tried upgrading to Expo SDK 51 and the issue still remains.

Edit: I tested it again and it seems to work fine if I have many apps open in the background, iOS must kill my app sooner in that case (I waited 1 minute). However if I have no apps open in the background, the issue still remains even after 5 minutes of waiting.

[padge]

So I ended up switching to light + dark splash screens to overcome the "white flash" when showing the splash screen manually (previously only had dark), and now that I know iOS will quit the app when headless, this is less of a concern to me now. I thought something was broken when the app was still "warm" 30 minutes after receiving a message when in the "quit" state, but I guess iOS just leaves the app running if no other apps are competing for resources.

[padge]

Okay so another issue is when transitioning from Headless to Non-Headless, is that the system color scheme isn't being respected and is always returning "light".

Edit: I found a relevant bug report which links to this PR facebook/react-native#46021 which thankfully resolved the color scheme issue.

[padge]

I'm content with where things are at now to close this. Hopefully this back and forth I had with myself is helpful to someone 😆.