Is there an existing issue for this?
Are you aware of the differences between iOS and Android background message handling?
Do you have an active Apple Developer account?
Are you using a physical iOS device to test background messages?
Have you enabled "Remote Notifications" & "Background Mode" (Checking options for "Background Processing" & "Remote Notifications") in your app's Xcode project?
Yes
Have you created an APNs key in your Apple Developer account & uploaded this APNs key to your Firebase console?
Yes
Have you disabled method swizzling for Firebase in your app?
FirebaseAppDelegateProxyEnabled
Are you sending messages to your app from the Firebase Admin SDK?
{
"message": {
"token": "<DEVICE_TOKEN>",
"notification": {
"title": "Cashback Alert",
"body": "Special offer inside"
},
"data": {
"title": "Cashback Alert",
"body": "Special offer inside",
"section": "order_history",
"category": "action_needed"
},
"apns": {
"headers": {
"apns-push-type": "alert",
"apns-priority": "10"
},
"payload": {
"aps": {
"alert": {
"title": "Cashback Alert",
"body": "Special offer inside"
},
"sound": "default",
"content-available": 1,
"mutable-content": 1
}
}
}
}
}
Have you requested permission from the user to receive notifications?
Have you used the 'Console' application on your macOS device to check if the iOS device's system is throttling your background messages?
Yes, Background notification is arrive
Additional context and comments
I am developing a Flutter application that uses Firebase Cloud Messaging (FCM) to receive push notifications. I want to save all received notifications to a local Hive database so users can view their notification history inside the app.
However, I am experiencing inconsistent behavior on iOS when sending notifications directly to a device token versus sending them through FCM Topics.
Sometimes notifications are saved to Hive as expected, but sometimes they are not. I cannot consistently reproduce the behavior or understand what determines whether the background message handler executes.
When notifications are sent directly to a device token, they generally work as expected. However, notifications sent through our production panel using FCM Topics may appear on the iOS lock screen without being saved to Hive.
Expected Behavior
Whenever a notification is received and the background handler is executed, the notification should be saved to Hive and appear in the notification history when the user opens the app.
Ideally, the notification history should remain consistent regardless of whether the notification is sent directly to a device token or through an FCM Topic.
Actual Behavior
Direct device token: Notifications sent using curl are displayed on iOS and saved to Hive as expected.
FCM Topic: Notifications sent through our production panel appear on the iOS lock screen, but they are sometimes missing from Hive when the app is opened.
Inconsistent execution: The behavior is not consistent. Sometimes notifications are processed and saved successfully, while other times they are displayed by iOS but the background handler does not appear to save them.
App terminated or closed: The notification may be displayed, but the notification history does not always contain the corresponding entry when the app is opened later.
I am unsure whether this is caused by iOS background execution restrictions, differences in the FCM payload, notification delivery behavior, or Flutter's background message handler.
FCM Payload
This is an example of the payload used when sending notifications directly to a device token:
{
"message": {
"token": "<DEVICE_TOKEN>",
"notification": {
"title": "Cashback Alert",
"body": "Special offer inside"
},
"data": {
"title": "Cashback Alert",
"body": "Special offer inside",
"section": "order_history",
"category": "action_needed"
},
"apns": {
"headers": {
"apns-push-type": "alert",
"apns-priority": "10"
},
"payload": {
"aps": {
"alert": {
"title": "Cashback Alert",
"body": "Special offer inside"
},
"sound": "default",
"content-available": 1,
"mutable-content": 1
}
}
}
}
}
For topic notifications, our production panel sends the message to an FCM Topic instead of specifying an individual device token.
Background Message Handler
I use the following background handler to initialize Firebase and Hive and save received notifications:
@pragma('vm:entry-point')
Future firebaseMessagingBackgroundHandler(
RemoteMessage message,
) async {
WidgetsFlutterBinding.ensureInitialized();
await Firebase.initializeApp();
await HiveSetup.init();
final box = await Hive.openBox(
'notifications',
);
// Convert the RemoteMessage into a NotificationModel.
// The notification model conversion code is omitted.
await box.put(message.messageId, notificationModel);
await box.flush();
}
The handler is registered using FirebaseMessaging.onBackgroundMessage(...) during application initialization.
Questions
Does iOS invoke firebaseMessagingBackgroundHandler for FCM Topic notifications in the same way as for notifications sent directly to a device token?
Why might a notification be displayed on the iOS lock screen without the Flutter background handler executing or saving the notification to Hive?
Does the behavior differ when the app is in the foreground, background, terminated, or force-quit by the user?
When the user force-quits the app, can iOS relaunch the Flutter background isolate to process an incoming notification?
If a notification arrives while the app is closed and the user later opens the app using the home screen icon instead of tapping the notification, is there a supported way to retrieve that notification and save it locally?
Are there differences in APNs payload configuration or headers that could explain why topic notifications behave differently from token-targeted notifications?
What is the recommended approach for maintaining a reliable notification history on iOS when background message delivery and execution are not guaranteed?
Additional Information
Framework: Flutter
Messaging: Firebase Cloud Messaging (FCM)
Local database: Hive
Platform: iOS
Notification delivery methods: Direct device token and FCM Topic
Observed issue: Intermittent background processing and missing local notification history
What I Have Tried
Sending notifications directly to device tokens using curl.
Sending notifications through FCM Topics using our production panel.
Including notification and data payloads.
Including the APNs headers apns-push-type: alert and apns-priority: 10.
Including content-available: 1 and mutable-content: 1 in the APNs payload.
Initializing Firebase and Hive inside the background message handler.
Expected Outcome
I would appreciate clarification on whether this behavior is expected on iOS and whether there is a reliable, recommended way to persist notifications locally.
In particular, I would like to understand why the behavior is inconsistent — sometimes notifications are saved successfully, while other times they are only displayed by iOS and never appear in the app's notification history — and whether this is related to FCM Topic delivery, APNs configuration, or iOS background execution limitations.
Thank you for your help!
Is there an existing issue for this?
Are you aware of the differences between iOS and Android background message handling?
Do you have an active Apple Developer account?
Are you using a physical iOS device to test background messages?
Have you enabled "Remote Notifications" & "Background Mode" (Checking options for "Background Processing" & "Remote Notifications") in your app's Xcode project?
Yes
Have you created an APNs key in your Apple Developer account & uploaded this APNs key to your Firebase console?
Yes
Have you disabled method swizzling for Firebase in your app?
FirebaseAppDelegateProxyEnabled
Are you sending messages to your app from the Firebase Admin SDK?
{
"message": {
"token": "<DEVICE_TOKEN>",
"notification": {
"title": "Cashback Alert",
"body": "Special offer inside"
},
"data": {
"title": "Cashback Alert",
"body": "Special offer inside",
"section": "order_history",
"category": "action_needed"
},
"apns": {
"headers": {
"apns-push-type": "alert",
"apns-priority": "10"
},
"payload": {
"aps": {
"alert": {
"title": "Cashback Alert",
"body": "Special offer inside"
},
"sound": "default",
"content-available": 1,
"mutable-content": 1
}
}
}
}
}
Have you requested permission from the user to receive notifications?
Have you used the 'Console' application on your macOS device to check if the iOS device's system is throttling your background messages?
Yes, Background notification is arrive
Additional context and comments
I am developing a Flutter application that uses Firebase Cloud Messaging (FCM) to receive push notifications. I want to save all received notifications to a local Hive database so users can view their notification history inside the app.
However, I am experiencing inconsistent behavior on iOS when sending notifications directly to a device token versus sending them through FCM Topics.
Sometimes notifications are saved to Hive as expected, but sometimes they are not. I cannot consistently reproduce the behavior or understand what determines whether the background message handler executes.
When notifications are sent directly to a device token, they generally work as expected. However, notifications sent through our production panel using FCM Topics may appear on the iOS lock screen without being saved to Hive.
Expected Behavior
Whenever a notification is received and the background handler is executed, the notification should be saved to Hive and appear in the notification history when the user opens the app.
Ideally, the notification history should remain consistent regardless of whether the notification is sent directly to a device token or through an FCM Topic.
Actual Behavior
Direct device token: Notifications sent using curl are displayed on iOS and saved to Hive as expected.
FCM Topic: Notifications sent through our production panel appear on the iOS lock screen, but they are sometimes missing from Hive when the app is opened.
Inconsistent execution: The behavior is not consistent. Sometimes notifications are processed and saved successfully, while other times they are displayed by iOS but the background handler does not appear to save them.
App terminated or closed: The notification may be displayed, but the notification history does not always contain the corresponding entry when the app is opened later.
I am unsure whether this is caused by iOS background execution restrictions, differences in the FCM payload, notification delivery behavior, or Flutter's background message handler.
FCM Payload
This is an example of the payload used when sending notifications directly to a device token:
{
"message": {
"token": "<DEVICE_TOKEN>",
"notification": {
"title": "Cashback Alert",
"body": "Special offer inside"
},
"data": {
"title": "Cashback Alert",
"body": "Special offer inside",
"section": "order_history",
"category": "action_needed"
},
"apns": {
"headers": {
"apns-push-type": "alert",
"apns-priority": "10"
},
"payload": {
"aps": {
"alert": {
"title": "Cashback Alert",
"body": "Special offer inside"
},
"sound": "default",
"content-available": 1,
"mutable-content": 1
}
}
}
}
}
For topic notifications, our production panel sends the message to an FCM Topic instead of specifying an individual device token.
Background Message Handler
I use the following background handler to initialize Firebase and Hive and save received notifications:
@pragma('vm:entry-point')
Future firebaseMessagingBackgroundHandler(
RemoteMessage message,
) async {
WidgetsFlutterBinding.ensureInitialized();
await Firebase.initializeApp();
await HiveSetup.init();
final box = await Hive.openBox(
'notifications',
);
// Convert the RemoteMessage into a NotificationModel.
// The notification model conversion code is omitted.
await box.put(message.messageId, notificationModel);
await box.flush();
}
The handler is registered using FirebaseMessaging.onBackgroundMessage(...) during application initialization.
Questions
Does iOS invoke firebaseMessagingBackgroundHandler for FCM Topic notifications in the same way as for notifications sent directly to a device token?
Why might a notification be displayed on the iOS lock screen without the Flutter background handler executing or saving the notification to Hive?
Does the behavior differ when the app is in the foreground, background, terminated, or force-quit by the user?
When the user force-quits the app, can iOS relaunch the Flutter background isolate to process an incoming notification?
If a notification arrives while the app is closed and the user later opens the app using the home screen icon instead of tapping the notification, is there a supported way to retrieve that notification and save it locally?
Are there differences in APNs payload configuration or headers that could explain why topic notifications behave differently from token-targeted notifications?
What is the recommended approach for maintaining a reliable notification history on iOS when background message delivery and execution are not guaranteed?
Additional Information
Framework: Flutter
Messaging: Firebase Cloud Messaging (FCM)
Local database: Hive
Platform: iOS
Notification delivery methods: Direct device token and FCM Topic
Observed issue: Intermittent background processing and missing local notification history
What I Have Tried
Sending notifications directly to device tokens using curl.
Sending notifications through FCM Topics using our production panel.
Including notification and data payloads.
Including the APNs headers apns-push-type: alert and apns-priority: 10.
Including content-available: 1 and mutable-content: 1 in the APNs payload.
Initializing Firebase and Hive inside the background message handler.
Expected Outcome
I would appreciate clarification on whether this behavior is expected on iOS and whether there is a reliable, recommended way to persist notifications locally.
In particular, I would like to understand why the behavior is inconsistent — sometimes notifications are saved successfully, while other times they are only displayed by iOS and never appear in the app's notification history — and whether this is related to FCM Topic delivery, APNs configuration, or iOS background execution limitations.
Thank you for your help!