🐛 [firebase_messaging] Background handler never invoked on iOS

[mikeroneer]

Bug report

Describe the bug
According to https://firebase.flutter.dev/docs/messaging/usage/#message-types, the background handler should be invoked for notification messages, data messages or a combination of both when the app is in the background or terminated. In our project, it is not invoked in any of those cases. For the sake of completeness it is worth to mention that the onMessage stream fires properly when the app is in foreground and also the notification handled by the FCM-SDK is shown when the app is in background/terminated. It's just the onBackgroundMessage which is never invoked.

We are aware of the content_available flag, however, the issue does not just relate to silent (data only) messages.

Steps to reproduce

Steps to reproduce the behavior:

1. run the simplified code snipped below
2. (optional) add a breakpoint in the background handler
3. put the app into background/terminate it
4. send a notification/data message via FCM (Firebase console or API call)
5. result: "Handling a background message..." is not printed in the console, nor does the debugger stop in the _firebaseMessagingBackgroundHandler

Expected behavior

onBackgroundMessage is invoked when the app is in background or terminated.

Sample project

Future<void> _firebaseMessagingBackgroundHandler(RemoteMessage message) async {
  print('Handling a background message: ${message.messageId}');
}

Future<void> main() async {
  WidgetsFlutterBinding.ensureInitialized();
  await Firebase.initializeApp();

  FirebaseMessaging.onBackgroundMessage(_firebaseMessagingBackgroundHandler);

  final token = await FirebaseMessaging.instance.getToken();
  print('Push notification token: $token');

  FirebaseMessaging.onMessage.listen((RemoteMessage message) {
    print('Got a message whilst in the foreground!');
    print('Message data: ${message.data}');

    if (message.notification != null) {
      print('Message also contained a notification: ${message.notification}');
    }
  });
}

Edit: Payload (suggested by @markusaksli-nc)

We have tried quite a lot of different payload combinations, with both, containing a data object only and a notification object respectively. We have also tried addressing the recipient via a topic (which is our intended use case) as well as with the unique device token. Background modes (Background fetch and Remote Notifications) are enabled too. On the server side, we are using the Java SDK, however, we have also tried sending a POST request directly via Google's OAuth 2.0 Playground.

The following indicates a sample payload:

{
   "topic": "test-topic",
   "message": {
      "data": {
         "data-item": "my-data-item"
      },
      "apns": {
         "payload": {
            "aps": {
               "content-available": 1
            },
         }
      },
   },
}

---

Additional context

• Test device with iOS 14.5.1 installed
• iOS project was configured according to https://firebase.flutter.dev/docs/messaging/apple-integration
• firebase_messaging: ^10.0.0

---

Flutter doctor

Run flutter doctor and paste the output below:

Click To Expand

Doctor summary (to see all details, run flutter doctor -v):
[✓] Flutter (Channel stable, 2.0.3, on macOS 11.3 20E232 darwin-x64, locale en-AT)
[✓] Android toolchain - develop for Android devices (Android SDK version 30.0.3)
[✓] Xcode - develop for iOS and macOS
[✓] Chrome - develop for the web
[✓] Android Studio (version 4.1)
[✓] IntelliJ IDEA Ultimate Edition (version 2020.3.1)
[✓] VS Code (version 1.56.2)
[✓] Connected device (3 available)

---

Flutter dependencies

Run flutter pub deps -- --style=compact and paste the output below:

Click To Expand

Dart SDK 2.12.2
Flutter SDK 2.0.3

dependencies:
- firebase_analytics 8.1.0 [firebase_analytics_platform_interface firebase_analytics_web firebase_core flutter meta]
- firebase_core 1.2.0 [firebase_core_platform_interface firebase_core_web flutter meta]
- firebase_crashlytics 2.0.4 [firebase_core firebase_core_platform_interface firebase_crashlytics_platform_interface flutter stack_trace]
- firebase_messaging 10.0.0 [firebase_core firebase_core_platform_interface firebase_messaging_platform_interface firebase_messaging_web flutter meta]
...
transitive dependencies:
- firebase 9.0.1 [http http_parser js]
- firebase_analytics_platform_interface 2.0.1 [flutter meta]
- firebase_analytics_web 0.3.0+1 [firebase firebase_analytics_platform_interface flutter flutter_web_plugins meta]
- firebase_core_platform_interface 4.0.1 [collection flutter meta plugin_platform_interface]
- firebase_core_web 1.1.0 [firebase_core_platform_interface flutter flutter_web_plugins js meta]
- firebase_crashlytics_platform_interface 3.0.4 [collection firebase_core flutter meta plugin_platform_interface]
- firebase_messaging_platform_interface 3.0.0 [firebase_core flutter meta plugin_platform_interface]
- firebase_messaging_web 2.0.0 [firebase_core firebase_core_web firebase_messaging_platform_interface flutter flutter_web_plugins js meta]
...

---

[markusaksli-nc]

Hi @mikeroneer
Could you provide the exact payload you are sending through FCM?
Thank you

[ifanger]

I'm facing the same issue here.
The background handler on iOS never worked for me in any version. (now I'm using 10.0.1)
I have tried to implement a feature on my app that I need to use the background handler but it's working only for Android.

I've created a test Cloud Function just to test again, but it didn't work:

await admin.messaging().sendToDevice(
    'token',
    {
      data: { remoteConfig: 'stale' },
    },
    { contentAvailable: true, priority: 'high' }
  );

My handler:

void main() {
  WidgetsFlutterBinding.ensureInitialized();
  await Firebase.initializeApp();
  FirebaseMessaging.onBackgroundMessage(firebaseBackgroundMessageHandler);
  //etc
}

Future<void> firebaseBackgroundMessageHandler(RemoteMessage message) async {
  print("Message received");
  await Firebase.initializeApp();
  final _notificationService =
      NotificationService(StorageRepository(), UserRepository());

  await _notificationService.onMessageReceived(message);
}

Seems like everything is ok on my setup, I'm receiving notifications, only silent notifications doesn't work in iOS in background/terminated.
Background Modes (Background fetch and Remote Notifications) are enabled too.

[ronaldmaymone]

I was having this issue too. Just fixed by deleting the old key "FirebaseAppDelegateProxyEnabled" from my info.plist. My json notification payload contains both notification, data and the apns payload with content-available : 1.
Don't know if this is your case but just leaving something that helped.

[ifanger]

I was having this issue too. Just fixed by deleting the old key "FirebaseAppDelegateProxyEnabled" from my info.plist. My json notification payload contains both notification, data and the apns payload with content-available : 1.
Don't know if this is your case but just leaving something that helped.

Thanks for the help!
Unfortunately my Info.plist doesn't contains this key :/

[luvishq]

Any updates on this?

[nicodumdum]

Also looking forward for an update to this. Having the exact same issue/behavior on same test device and plugin version. Notification works just fine in app foreground. However, when the app is in background, the notification appears in the notification center but my background handler function by the FirebaseMessaging.onBackgroundMessage was not triggered.

pubspec

firebase_core: ^1.2.1
firebase_messaging: ^10.0.1

flutter doctor

[✓] Flutter (Channel stable, 2.2.1, on macOS 11.2.3 20D91 darwin-x64, locale en-US)
    • Flutter version 2.2.1 at /Users/aaa/Documents/flutter
    • Framework revision 02c026b03c (10 days ago), 2021-05-27 12:24:44 -0700
    • Engine revision 0fdb562ac8
    • Dart version 2.13.1

[✓] Android toolchain - develop for Android devices (Android SDK version 30.0.2)
    • Android SDK at /Users/aaa/Library/Android/sdk
    • Platform android-30, build-tools 30.0.2
    • Java binary at: /Applications/Android Studio.app/Contents/jre/jdk/Contents/Home/bin/java
    • Java version OpenJDK Runtime Environment (build 1.8.0_242-release-1644-b3-6915495)
    • All Android licenses accepted.

[✓] Xcode - develop for iOS and macOS
    • Xcode at /Applications/Xcode.app/Contents/Developer
    • Xcode 12.5, Build version 12E262
    • CocoaPods version 1.10.1

[✗] Chrome - develop for the web (Cannot find Chrome executable at /Applications/Google Chrome.app/Contents/MacOS/Google Chrome)
    ! Cannot find Chrome. Try setting CHROME_EXECUTABLE to a Chrome executable.

[✓] Android Studio (version 4.1)
    • Android Studio at /Applications/Android Studio.app/Contents
    • Flutter plugin can be installed from:
      🔨 https://plugins.jetbrains.com/plugin/9212-flutter
    • Dart plugin can be installed from:
      🔨 https://plugins.jetbrains.com/plugin/6351-dart
    • Java version OpenJDK Runtime Environment (build 1.8.0_242-release-1644-b3-6915495)

[✓] VS Code (version 1.56.2)
    • VS Code at /Applications/Visual Studio Code.app/Contents
    • Flutter extension version 3.23.0

[✓] Connected device (1 available)
    • Nico’s iPhone (mobile) • 00008030-000A5C843E86402E • ios • iOS 14.5.1

! Doctor found issues in 1 category.

[mikeroneer]

Hi @mikeroneer
Could you provide the exact payload you are sending through FCM?
Thank you

Hi @markusaksli-nc, I've updated the initial thread.

[ch-muhammad-adil]

Also looking forward for an update to this. Having the exact same issue/behavior on same test device and plugin version. Notification works just fine in app foreground. However, when the app is in background, the notification appears in the notification center but my background handler function by the FirebaseMessaging.onBackgroundMessage was not triggered.

pubspec

firebase_core: ^1.2.1
firebase_messaging: ^10.0.1

flutter doctor

[✓] Flutter (Channel stable, 2.2.1, on macOS 11.2.3 20D91 darwin-x64, locale en-US)
    • Flutter version 2.2.1 at /Users/aaa/Documents/flutter
    • Framework revision 02c026b03c (10 days ago), 2021-05-27 12:24:44 -0700
    • Engine revision 0fdb562ac8
    • Dart version 2.13.1

[✓] Android toolchain - develop for Android devices (Android SDK version 30.0.2)
    • Android SDK at /Users/aaa/Library/Android/sdk
    • Platform android-30, build-tools 30.0.2
    • Java binary at: /Applications/Android Studio.app/Contents/jre/jdk/Contents/Home/bin/java
    • Java version OpenJDK Runtime Environment (build 1.8.0_242-release-1644-b3-6915495)
    • All Android licenses accepted.

[✓] Xcode - develop for iOS and macOS
    • Xcode at /Applications/Xcode.app/Contents/Developer
    • Xcode 12.5, Build version 12E262
    • CocoaPods version 1.10.1

[✗] Chrome - develop for the web (Cannot find Chrome executable at /Applications/Google Chrome.app/Contents/MacOS/Google Chrome)
    ! Cannot find Chrome. Try setting CHROME_EXECUTABLE to a Chrome executable.

[✓] Android Studio (version 4.1)
    • Android Studio at /Applications/Android Studio.app/Contents
    • Flutter plugin can be installed from:
      🔨 https://plugins.jetbrains.com/plugin/9212-flutter
    • Dart plugin can be installed from:
      🔨 https://plugins.jetbrains.com/plugin/6351-dart
    • Java version OpenJDK Runtime Environment (build 1.8.0_242-release-1644-b3-6915495)

[✓] VS Code (version 1.56.2)
    • VS Code at /Applications/Visual Studio Code.app/Contents
    • Flutter extension version 3.23.0

[✓] Connected device (1 available)
    • Nico’s iPhone (mobile) • 00008030-000A5C843E86402E • ios • iOS 14.5.1

! Doctor found issues in 1 category.

Facing same issue and almost having same configurations.

[frestoinc]

Interestingly, these are my findings on real phones:

iOS14.5.1 -> onMessage and onBackgroundMessage works; onBackgroundMessage doesn't invoke when app terminated
iOS14.6 -> onMessage and onBackgroundMessage works; onBackgroundMessage doesn't invoke when app terminated
iOS13.7 -> onMessage works; onBackgroundMessage doesn't invoke
iOS13.1.3 -> onMessage works; onBackgroundMessage doesn't invoke

anyone with similar findings?

[markusaksli-nc]

Well firstly onBackgroundMessage is not expected to work when the app has been terminated on iOS as this is a native limitation. This is also documented in https://firebase.flutter.dev/docs/messaging/usage#receiving-messages

On iOS, if the user swipes away the application from app Switcher, it must be manually reopened again for background messages to start working again.

That being said, you mentioned that the call is not fired when the app is in the background as well? Have you tried checking the device logs for any relevant errors? Have you requested and allowed permissions on the device?

[frestoinc]

Well firstly onBackgroundMessage is not expected to work when the app has been terminated on iOS as this is a native limitation. This is also documented in https://firebase.flutter.dev/docs/messaging/usage#receiving-messages

On iOS, if the user swipes away the application from app Switcher, it must be manually reopened again for background messages to start working again.

That being said, you mentioned that the call is not fired when the app is in the background as well? Have you tried checking the device logs for any relevant errors? Have you requested and allowed permissions on the device?

Yup all permissions granted. Same code base for all 4 devices. Oops forogt to mentioned for 13.7 and 13.1.3 notification immediately shown upon launching app from background.

[mikeroneer]

Interestingly, these are my findings on real phones:

iOS14.5.1 -> onMessage and onBackgroundMessage works; onBackgroundMessage doesn't invoke when app terminated
iOS14.6 -> onMessage and onBackgroundMessage works; onBackgroundMessage doesn't invoke when app terminated
iOS13.7 -> onMessage works; onBackgroundMessage doesn't invoke
iOS13.1.3 -> onMessage works; onBackgroundMessage doesn't invoke

anyone with similar findings?

We only have a testing device with iOS 14.5.1, where onBackgroundMessage is never invoked, neither when the app is in background nor terminated (which is another thing to discuss anyways).

@markusaksli-nc all permissions have been granted, yes.

[markusaksli-nc]

Well, I haven't been able to reproduce this but based on the number of reports I'm going to label this. Please try to go through the device logs (console app on mac) to see if there are any relevant messages that could point to an issue in handling the message.

[outailounni]

i actually receive the notification even when the app is terminated.
But the second one !
the first one is always missed, gone then after the second one i always receive them

[rouddy]

same issue here.
i tried with various methods whatever i can search.

so i tried with example source in flutterfire gitbub repository

i changed like below files with our info

- GoogleService-Info.plist
- Runner.pbxproj (Bundle Identifier)

but it doesn't worked too.

i guess you have tested the example source many time.
so i wonder that i missed some apns setting or fcm settings.
what should i check?

i sent fcm message with cloud messaging page firebase console (https://console.firebase.google.com/u/0/project/[Project-Name]/notification)

flutter doctor

Doctor summary (to see all details, run flutter doctor -v):
[✓] Flutter (Channel stable, 2.2.2, on macOS 11.4 20F71 darwin-x64, locale ko-KR)
[!] Android toolchain - develop for Android devices (Android SDK version 30.0.3)
    ✗ Android license status unknown.
      Run `flutter doctor --android-licenses` to accept the SDK licenses.
      See https://flutter.dev/docs/get-started/install/macos#android-setup for more details.
[✓] Xcode - develop for iOS and macOS
[✓] Chrome - develop for the web
[✓] Android Studio (version 4.2)
[✓] VS Code (version 1.55.2)
[✓] Connected device (5 available)

my iOS device os version is 14.6

[elsystm]

@HaveANiceDay33 We have ditched the idea of handling notifications on iOS silently and we made a native notification extension on iOS to handle rich notifications with mutable-content tag, everything is going smooth so far with notification localization and click handling on Flutter side.

Sadly this is the only way so far to be able to receive notifications reliably on iOS.

I know maintaining two code bases for the same scenario for different platforms is not the ideal solution especially if you have chosen Flutter in the first place, but I encourage everyone facing the same problem not to waste their time trying to fix it if they're tight on the delivery schedule.

[Andreylk4774]

@elsystm

@HaveANiceDay33 We have ditched the idea of handling notifications on iOS silently and we made a native notification extension on iOS to handle rich notifications with mutable-content tag, everything is going smooth so far with notification localization and click handling on Flutter side.

Sadly this is the only way so far to be able to receive notifications reliably on iOS.

I know maintaining two code bases for the same scenario for different platforms is not the ideal solution especially if you have chosen Flutter in the first place, but I encourage everyone facing the same problem not to waste their time trying to fix it if they're tight on the delivery schedule.

Can you show the extension code? Now you can always run flutter code after receiving a FCM notification, even when the app is killed by the user?

[sandeepv10494]

Can anyone please suggest to me any workaround solution specific to ios for this issue?

[sp-sivaprasad]

FirebaseMessaging.onMessageOpenedApp.listen((RemoteMessage message) {
Fluttertoast.showToast(
msg: " from onMessageOpenedApp : " + message.data['screen'],
);
}).onData((data) {
print('NOTIFICATION MESSAGE TAPPED');
print('data from stream: ${data.data}');
Fluttertoast.showToast(
msg: " from onMessageOpenedApp : data from stream: ${data.data}",
);
});

FirebaseMessaging.instance.getInitialMessage().then((value) {
  Fluttertoast.showToast(
    msg: " from getInitialMessage : $value ",
  );
});

background handler doesn't executed for me else, but these codes does. Anyone can try these methods to get codes executed when app is terminated and / or background

[waqadArshad]

@HaveANiceDay33 We have ditched the idea of handling notifications on iOS silently and we made a native notification extension on iOS to handle rich notifications with mutable-content tag, everything is going smooth so far with notification localization and click handling on Flutter side.

Sadly this is the only way so far to be able to receive notifications reliably on iOS.

I know maintaining two code bases for the same scenario for different platforms is not the ideal solution especially if you have chosen Flutter in the first place, but I encourage everyone facing the same problem not to waste their time trying to fix it if they're tight on the delivery schedule.

@elsystm can you please help me with that native implementation? Can you at least share some code samples or some resources to help us with that?

Thanks by the way!

[google-oss-bot]

Hey @mikeroneer. We need more information to resolve this issue but there hasn't been an update in 7 weekdays. I'm marking the issue as stale and if there are no new updates in the next 7 days I will close it automatically.

If you have more information that will help us get to the bottom of this, just add a comment!

[benfgit]

Issue continues on iOS 15.5. and firebase_messaging: 11.4.4. Works well on Android.

[hatemragab]

any updates about it?

[Pelmeshka102]

FirebaseMessaging.onMessageOpenedApp.listen((RemoteMessage message) { Fluttertoast.showToast( msg: " from onMessageOpenedApp : " + message.data['screen'], ); }).onData((data) { print('NOTIFICATION MESSAGE TAPPED'); print('data from stream: ${data.data}'); Fluttertoast.showToast( msg: " from onMessageOpenedApp : data from stream: ${data.data}", ); });

FirebaseMessaging.instance.getInitialMessage().then((value) {
  Fluttertoast.showToast(
    msg: " from getInitialMessage : $value ",
  );
});

background handler doesn't executed for me else, but these codes does. Anyone can try these methods to get codes executed when app is terminated and / or background

This answer helps me. Just use getInitialMessage

[russellwheatley]

Just to be clear on this issue; I have tested background message handling on iOS multiple times, and it hasn't failed to work. I've created a PR for updating the messaging example app with a set of instructions for you to follow. I would be grateful if you are experiencing an issue, if you could test the example app by following the instructions, and let me know if you're able to receive messages in your background handler.

I will ultimately be closing this issue as it doesn't serve any purpose except to confuse users about the state of onBackgroundMessage for iOS.

[kmvignesh]

Me also faced the same issue. To fix this did the following changes.
Step 1
In info.plist file we have added following configuration

<key>GoogleUtilitiesAppDelegateProxyEnabled</key>
<false/>
<key>FirebaseAppDelegateProxyEnabled</key>
<false/>

Step 2
Extra keys in the payload also causing issue. so removed unnecessary keys from payload. eg: apns-push-type,apns-topic

var message = new MulticastMessage()
{
    Tokens = deviceTokens.ToList(),
    Data = new Dictionary<string, string>()
{
    {"entity_name", notificationEntityName}
},

    Apns = new ApnsConfig
    {
        Aps = new Aps { ContentAvailable = true },
        Headers = new Dictionary<string, string>
        {
            { "apns-priority", "5" }
        }
    }
};

Now able to receive data only notification and onBackgroundMessage is getting called.

[DennisKragekjaer]

+1

[rulefahd]

It doesnt work on termination mode all the time, it might work for 1-2 hours, then it will stop completely

[waqadArshad]

@rulefahd if you are talking about iOS, I agree that data-only messages would stop getting received. but for the android part, you have to follow a specific payload structure to be able to keep receiving the notifications in the terminated state even.

Here is an example that is working for me on android. I have tested it myself.

 let payload;
 var options;

payload = {
      notification: {},
     // the data in the data field is my custom data and you can put whatever you want, here.
      data: { 
        imageUrl: requesterImageUrl,
        chatRoomId: chatRoomId,
        screenName: "voiceScreen",
        voiceCall: "voiceCall",
        callerName: requesterName,
        callsDocId: callsDocId,
        senderId: requesterId,
        receiverId: requestedId,
        callInitTime: callInitTime,
      },
    };

    options = {
      priority: "high",
      contentAvailable: true,
    };
    await admin
      .messaging()
      .sendToDevice(token_o, payload, options)
      .then((value) => {
        functions.logger.log(
          "Notification for AudioCall is sent to the Receiver"
        );
      })
      .catch((e) => {
        functions.logger.log(e.toString());
      });

[waqadArshad]

@rulefahd as for iOS, there is no easy way of doing this. The bottom line is that you cannot achieve an always working terminated state notification using FCM. You would have to use a native Swift or Objective-C implementation to be able to do that. I implemented that using PushKit as I was doing this for call implementation. if you need anything else, please feel free to ask.

[arthas1888]

At last it works with the last release, I tested successfully with next json body

               {
                  "priority": "high",
                  "data": {
                      "key": "value"
                  },                     
                  "content_available": true,
                  "apns": {
                      "headers": {
                          "apns-priority": "5"
                      }
                  },
                  "to": "firebase_token_xxxxx"
              }

[m2sahin]

{
"priority": "high",
"data": {
"key": "value"
},
"content_available": true,
"apns": {
"headers": {
"apns-priority": "5"
}
},
"to": "firebase_token_xxxxx"
}

It works when you throw it down, yes, but when the application is completely closed, the notification does not come at all.

[hatemragab]

I see PR #9292 fix the problem is it available in pub dev or not yet?

[m2sahin]

I see PR #9292 fix the problem is it available in pub dev or not yet?

firebase_messaging 12.0.2 is the latest version but now I'm getting the same error. I hope the problem is fixed soon, it's very annoying.

[hatemragab]

I see PR #9292 fix the problem is it available in pub dev or not yet?

firebase_messaging 12.0.2 is the latest version but now I'm getting the same error. I hope the problem is fixed soon, it's very annoying.

Yes i don't this bug fixed in change log
Can any one send how to import the package from the GitHub master branch?

[darshankawar]

Yes i don't this bug fixed in change log
Can any one send how to import the package from the GitHub master branch?

@hatemragab the PR is just an update to the example app to show the background handlers work as intended. There’s nothing to release. The example app is updated so users can see that the API works and if there is a problem, it is something wrong with their setup.

If you look at the PR, all the files updated are in the example/ directory and also a documentation update.

[sameer320]

I also facing this issue.