🐛 [firebase_messaging] Background handler not working on iOS

[m-schmailzl]

Bug report

On iOS devices, the background handler set with FirebaseMessaging.onBackgroundMessage does not work.
On Android, the same code works fine.
I can receive messages while the app is in foreground.

I enabled Push notifications, Background fetch, Remote notifications and Background processing in Xcode.

I tried setting FirebaseAppDelegateProxyEnabled to false, but it did not solve the problem.

I am using the newest release 9.1.2 of firebase_messaging.

Steps to reproduce

Steps to reproduce the behavior:

1. Start the app
2. Close the app
3. Send a notification to the device
4. The notification is displayed but the handler is not called.

Expected behavior

The background handler is called.

Flutter doctor

Run flutter doctor and paste the output below:

Click To Expand

flutter doctor -v
[✓] Flutter (Channel stable, 2.0.5, on macOS 11.2.3 20D91 darwin-arm, locale de-DE)
    • Flutter version 2.0.5 at /Users/max/flutter
    • Framework revision adc687823a (9 days ago), 2021-04-16 09:40:20 -0700
    • Engine revision b09f014e96
    • Dart version 2.12.3

[✓] Android toolchain - develop for Android devices (Android SDK version 30.0.3)
    • Android SDK at /Users/max/Library/Android/sdk
    • Platform android-30, build-tools 30.0.3
    • 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.4, Build version 12D4e
    • CocoaPods version 1.10.1

[✓] Chrome - develop for the web
    • Chrome at /Applications/Google Chrome.app/Contents/MacOS/Google Chrome

[✓] 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.55.2)
    • VS Code at /Applications/Visual Studio Code.app/Contents
    • Flutter extension version 3.21.0

[✓] Connected device (2 available)
    • iPhone 6S (mobile) • ios • iOS 14.4.2
    • Chrome (web) • chrome • web-javascript • Google Chrome 90.0.4430.85

---

Flutter dependencies

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

Click To Expand

flutter pub deps -- --style=compact
Dart SDK 2.12.3
Flutter SDK 2.0.5
picturetransfer 1.2.5+1

dependencies:
- cached_network_image 3.0.0 [flutter flutter_cache_manager octo_image]
- device_info 2.0.0 [flutter device_info_platform_interface]
- dropdown_search 0.5.0 [flutter]
- email_validator 2.0.1
- ext_storage 1.0.3 [flutter]
- firebase_messaging 9.1.2 [firebase_core firebase_core_platform_interface firebase_messaging_platform_interface firebase_messaging_web flutter meta]
- flutter 0.0.0 [characters collection meta typed_data vector_math sky_engine]
- flutter_cache_manager 3.0.1 [clock collection file flutter http image path path_provider pedantic rxdart sqflite uuid]
- flutter_localizations 0.0.0 [flutter intl characters clock collection meta path typed_data vector_math]
- flutter_svg 0.21.0-nullsafety.0 [flutter meta path_drawing vector_math xml]
- font_awesome_flutter 9.0.0 [flutter]
- http 0.13.1 [http_parser meta path pedantic]
- image_downloader 0.30.0 [flutter]
- intl 0.17.0 [clock path]
- json_annotation 3.1.1
- package_info 2.0.0 [flutter]
- permission_handler 6.1.1 [flutter meta permission_handler_platform_interface]
- photo_view 0.11.1 [flutter]
- qr_code_scanner 0.4.0 [flutter]
- share 2.0.1 [meta mime flutter]
- shared_preferences 2.0.5 [meta flutter shared_preferences_platform_interface shared_preferences_linux shared_preferences_macos shared_preferences_web shared_preferences_windows]
- splashscreen 1.3.5 [flutter]
- url_launcher 6.0.2 [flutter url_launcher_platform_interface url_launcher_linux url_launcher_macos url_launcher_windows url_launcher_web]
- video_player 2.1.0 [meta video_player_platform_interface video_player_web flutter flutter_test]
- visibility_detector 0.2.0 [flutter]
- webview_flutter 2.0.2 [flutter]

dev dependencies:
- build_runner 1.11.5 [args async build build_config build_daemon build_resolvers build_runner_core code_builder collection crypto dart_style glob graphs http_multi_server io js logging meta mime path pedantic pool pub_semver pubspec_parse shelf shelf_web_socket stack_trace stream_transform timing watcher web_socket_channel yaml]
- flutter_launcher_icons 0.9.0 [args image path yaml]
- flutter_test 0.0.0 [flutter test_api path fake_async clock stack_trace vector_math async boolean_selector characters charcode collection matcher meta source_span stream_channel string_scanner term_glyph typed_data]
- json_serializable 3.5.1 [analyzer build build_config json_annotation meta path source_gen]

transitive dependencies:
- _fe_analyzer_shared 14.0.0 [meta]
- analyzer 0.41.2 [_fe_analyzer_shared args cli_util collection convert crypto glob meta package_config path pub_semver source_span watcher yaml]
- archive 3.1.2 [crypto path]
- args 2.0.0
- async 2.5.0 [collection]
- boolean_selector 2.1.0 [source_span string_scanner]
- build 1.6.2 [analyzer async convert crypto glob logging meta path]
- build_config 0.4.6 [checked_yaml json_annotation meta path pubspec_parse yaml]
- build_daemon 2.1.10 [built_collection built_value http_multi_server logging pedantic path pool shelf shelf_web_socket stream_transform watcher web_socket_channel]
- build_resolvers 1.5.3 [analyzer build crypto graphs logging meta path package_config pool pub_semver]
- build_runner_core 6.1.10 [async build build_config build_resolvers collection convert crypto glob graphs logging meta path package_config pedantic pool timing watcher yaml]
- built_collection 5.0.0
- built_value 8.0.3 [built_collection collection fixnum]
- characters 1.1.0
- charcode 1.2.0
- checked_yaml 1.0.4 [json_annotation source_span yaml]
- cli_util 0.3.0 [meta path]
- clock 1.1.0
- code_builder 3.7.0 [built_collection built_value collection matcher meta]
- collection 1.15.0
- convert 3.0.0 [typed_data]
- crypto 3.0.0 [collection typed_data]
- dart_style 1.3.12 [analyzer args path pub_semver source_span]
- device_info_platform_interface 2.0.1 [flutter meta plugin_platform_interface]
- fake_async 1.2.0 [clock collection]
- ffi 1.0.0
- file 6.1.0 [meta path]
- firebase_core 1.0.4 [firebase_core_platform_interface firebase_core_web flutter meta]
- firebase_core_platform_interface 4.0.0 [flutter meta plugin_platform_interface]
- firebase_core_web 1.0.2 [firebase_core_platform_interface flutter flutter_web_plugins js meta]
- firebase_messaging_platform_interface 2.1.2 [firebase_core flutter meta plugin_platform_interface]
- firebase_messaging_web 1.0.5 [firebase_core firebase_core_web firebase_messaging_platform_interface flutter flutter_web_plugins js meta]
- fixnum 1.0.0
- flutter_blurhash 0.6.0 [flutter meta pedantic]
- flutter_web_plugins 0.0.0 [flutter js characters collection meta typed_data vector_math]
- glob 2.0.0 [async collection file path pedantic string_scanner]
- graphs 0.2.0
- http_multi_server 2.2.0 [async]
- http_parser 4.0.0 [charcode collection source_span string_scanner typed_data]
- image 3.0.2 [archive meta xml]
- io 0.3.5 [meta path string_scanner]
- js 0.6.3
- logging 1.0.0
- matcher 0.12.10 [stack_trace]
- meta 1.3.0
- mime 1.0.0
- octo_image 1.0.0 [flutter flutter_blurhash]
- package_config 1.9.3 [path charcode]
- path 1.8.0
- path_drawing 0.5.0-nullsafety.0 [vector_math meta path_parsing flutter]
- path_parsing 0.2.0-nullsafety.0 [vector_math meta]
- path_provider 2.0.1 [flutter path_provider_platform_interface path_provider_macos path_provider_linux path_provider_windows]
- path_provider_linux 2.0.0 [path xdg_directories path_provider_platform_interface flutter]
- path_provider_macos 2.0.0 [flutter]
- path_provider_platform_interface 2.0.1 [flutter meta platform plugin_platform_interface]
- path_provider_windows 2.0.0 [path_provider_platform_interface meta path flutter ffi win32]
- pedantic 1.11.0
- permission_handler_platform_interface 3.1.1 [flutter meta plugin_platform_interface]
- petitparser 4.0.2 [meta]
- platform 3.0.0
- plugin_platform_interface 2.0.0 [meta]
- pool 1.5.0 [async stack_trace]
- process 4.1.0 [file path platform]
- pub_semver 2.0.0 [collection]
- pubspec_parse 0.1.8 [checked_yaml json_annotation pub_semver yaml]
- rxdart 0.26.0
- shared_preferences_linux 2.0.0 [flutter file meta path path_provider_linux shared_preferences_platform_interface]
- shared_preferences_macos 2.0.0 [shared_preferences_platform_interface flutter]
- shared_preferences_platform_interface 2.0.0 [flutter]
- shared_preferences_web 2.0.0 [shared_preferences_platform_interface flutter flutter_web_plugins meta]
- shared_preferences_windows 2.0.0 [shared_preferences_platform_interface flutter file meta path path_provider_platform_interface path_provider_windows]
- shelf 1.1.0 [async collection http_parser path stack_trace stream_channel]
- shelf_web_socket 0.2.4+1 [shelf stream_channel web_socket_channel]
- sky_engine 0.0.99
- source_gen 0.9.10+3 [analyzer async build dart_style glob meta path pedantic source_span]
- source_span 1.8.0 [charcode collection path term_glyph]
- sqflite 2.0.0+3 [flutter sqflite_common path]
- sqflite_common 2.0.0+2 [synchronized path meta]
- stack_trace 1.10.0 [path]
- stream_channel 2.1.0 [async]
- stream_transform 2.0.0
- string_scanner 1.1.0 [charcode source_span]
- synchronized 3.0.0
- term_glyph 1.2.0
- test_api 0.2.19 [async boolean_selector collection meta path source_span stack_trace stream_channel string_scanner term_glyph matcher]
- timing 0.1.1+3 [json_annotation]
- typed_data 1.3.0 [collection]
- url_launcher_linux 2.0.0 [flutter]
- url_launcher_macos 2.0.0 [flutter]
- url_launcher_platform_interface 2.0.2 [flutter plugin_platform_interface]
- url_launcher_web 2.0.0 [url_launcher_platform_interface meta flutter flutter_web_plugins]
- url_launcher_windows 2.0.0 [flutter]
- uuid 3.0.3 [crypto]
- vector_math 2.1.0
- video_player_platform_interface 4.1.0 [flutter meta flutter_test]
- video_player_web 2.0.0 [flutter flutter_web_plugins meta video_player_platform_interface]
- watcher 1.0.0 [async path pedantic]
- web_socket_channel 1.2.0 [async crypto stream_channel]
- win32 2.0.4 [ffi]
- xdg_directories 0.2.0 [meta path process]
- xml 5.0.2 [collection meta petitparser]
- yaml 3.1.0 [collection source_span string_scanner]

---

[markusaksli-nc]

Hi @IkhwanSI13
Sadly this is the expected (and documented) behavior on iOS due to the native constraints.
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.

Thank you

[m-schmailzl]

Sorry for the late reply, I have been on vacation.
My problem is that the background handler does not work at all, even when the App is still running.

[markusaksli-nc]

What is the notification payload you are sending and how are you sending it?

[m-schmailzl]

Here is an example of my payload. I replaced the URLs and removed sensitive data.

   "message":{
      "data":{
         "click_action":"FLUTTER_NOTIFICATION_CLICK",
         "camera":"6",
         "media": {},
      "notification":{
         "title":"Test",
         "body":"New message",
         "image":"http:\/\/example.com"
      },
      "android":{
         "collapse_key":"camera6",
         "priority":"HIGH",
         "restricted_package_name":"com.example",
         "notification":{
            "default_sound":true,
            "default_light_settings":true,
            "visibility":"PUBLIC",
            "vibrate_timings":[
               "0.5s",
               "1s"
            ]
         }
      },
      "apns":{
         "payload":{
            "aps":{
               "mutable-content":1
            }
         },
         "fcm_options":{
            "image":"http:\/\/example.com"
         }
      },
      "token":"---"
   }
}```

[markusaksli-nc]

If you want a notification to always trigger the background messaging handler you can add in aps

  "apns": {
    "payload": {
      "aps": {
        "content-available": 1
      }
    }
  }

Otherwise content-available will be automatically added to any data-only notification (if there is no notification key) automatically through the FCM v1 HTTP API.

In any case that key needs to be true for the notification to wake the process on iOS to trigger the handler.

[m-schmailzl]

Thank you, now it works as expected. I misunderstood the documentation.
"Data only messages are considered low priority by devices [...]. On Apple (iOS & macOS), set the content-available field to true."
I thought I don't need to set the flag because my messages are not data only.