[iOS] How to access the payload of a silent notification that led to the app being launched?

[just-doit]

I send silent notifications to a Flutter app.

If the app is running in the background, the onBackgroundMessage handler is called.

However, if the app is terminated it is launched, but neither is onBackgroundMessage called, nor does FirebaseMessaging.instance.getInitialMessage() return anything (returns null).

What is the intended method for accessing the payload of the message that triggered the app to launch?

I did some debugging and see

- (BOOL)application:(UIApplication *)application
    didReceiveRemoteNotification:(NSDictionary *)userInfo
          fetchCompletionHandler:(void (^)(UIBackgroundFetchResult result))completionHandler

being called, which calls [_channel invokeMethod:@"Messaging#onBackgroundMessage"..., but this is even before main() of my flutter code is being called.

[yhay81]

getInitialMessage() is not the fallback for a silent push. It only represents a notification that the user tapped to open the app, so null is expected when a content-available push cold-starts the process without a tap. FlutterFire's iOS implementation also only exposes the initial message when the initial notification ID matches the notification-opened-app ID: source.

The intended Dart entry point is still onBackgroundMessage. Register a top-level, tree-shake-safe handler during startup:

@pragma('vm:entry-point')
Future<void> firebaseMessagingBackgroundHandler(RemoteMessage message) async {
  await Firebase.initializeApp(); // pass options if your setup requires them
  await persistPayload(message.data);
}

Future<void> main() async {
  WidgetsFlutterBinding.ensureInitialized();
  await Firebase.initializeApp();
  FirebaseMessaging.onBackgroundMessage(firebaseMessagingBackgroundHandler);
  runApp(const App());
}

The native callback arriving before your Dart main() is normal during an iOS background launch. The plugin routes that callback to Messaging#onBackgroundMessage (current iOS path); therefore the handler should persist the data and must not depend on the UI already existing. On Apple platforms it runs in the app process, not a separate Dart isolate.

Also verify the delivery prerequisites:

• Push Notifications capability and Background Modes → Remote notifications are enabled.
• The APNs message is a real background push, for example:

"apns": {
  "headers": {
    "apns-push-type": "background",
    "apns-priority": "5"
  },
  "payload": { "aps": { "content-available": 1 } }
}

• The app was not force-quit/swiped away; iOS requires the user to reopen it before background messages resume.
• Test on a physical device and keep the handler short. Apple may throttle or omit silent pushes, so they are not a guaranteed process-launch mechanism.

These lifecycle constraints and handler requirements are documented in Firebase's Flutter receive guide.

If the Objective-C delegate consistently fires but the Dart handler does not with the minimal registration above on the latest firebase_messaging, that is not a case for getInitialMessage(); it is worth filing a plugin issue with the Flutter/plugin/iOS versions, exact FCM payload, and a minimal reproduction. The current native path explicitly invokes Messaging#onBackgroundMessage, so losing it after correct startup registration would be unexpected.

[just-doit]

Thank you very much for the detailed response.

What I don't understand is the following paragraph:

The native callback arriving before your Dart main() is normal during an iOS background launch. The plugin routes that callback to Messaging#onBackgroundMessage (current iOS path); therefore the handler should persist the data and must not depend on the UI already existing.

How can the plugin routine call Messaging#onBackgroundMessage if main() hasn't even been called yet, and therefore the method hasn't been assigned at all?
(In other words, FirebaseMessaging.onBackgroundMessage(firebaseMessagingBackgroundHandler); hasn't even been executed yet)

Another point I don't understand is this sentence in the prerequisites:

The app was not force-quit/swiped away; iOS requires the user to reopen it before background messages resume.

Does that basically mean that background messages can't be delivered at all on iOS if the app isn't running in the background? As a user, I wouldn't even notice if iOS killed the app when it's not in the foreground.

[abidiahmedcom]

Hi @just-doit,

To clarify the force-quit sentence: there's a difference between the user swiping the app away and iOS killing it on its own.

• User swipes app away (force-quit): iOS stops delivering silent pushes entirely. The user has to manually reopen the app before any background messages come through again.
• • iOS kills the app due to low memory (user did nothing): this is normal. iOS can still deliver silent pushes and will relaunch the app in the background to process them. The user never notices this happened.

So silent pushes DO work when the app "isn't running", as long as the user wasn't the one who closed it. Apple treats an iOS memory kill as a suspend, not a termination.

[just-doit]

Ah ok. Is this a limitation of iOS or flutter fire? If it's iOS, do you have any link to the relevant part of the documentation?

[abidiahmedcom]

It's an iOS limitation, not FlutterFire.

To clarify: the push notification itself (the banner, sound, badge) is always delivered and shown to the user, even after force-quit. iOS handles that at the system level. The user sees it, taps it, and the app opens.

What doesn't work after force-quit is silent background processing. When you send a push with only content-available: 1 (no alert/sound/badge), iOS won't wake the app to run your code if the user swiped it away. This is by design at the OS level.

Apple documents this in:

• Pushing background updates to your app: "If something force quits or kills the app, the system discards the held notification."
• App Programming Guide: Background Execution: "In most cases, the system does not relaunch apps after they are force quit by the user."

There's one exception: if iOS kills the app due to low memory (the user didn't swipe it away), silent pushes still work. iOS treats that as a suspend, not a termination, and will relaunch the app in the background to process the message. The user never notices this happened.