Firebase Cloud Messaging (FCM) provides a reliable and battery-efficient connection between your server and devices. However, developers often encounter issues with FCM notifications, particularly when the onMessageReceived method is not called when the app is in the background. In this article, we'll explore why this happens and how to address it.

Understanding FCM Notification Types

Before diagnosing why onMessageReceived isn't triggered when the app is backgrounded, it's important to understand the types of messages FCM can send:

1. Notification Messages: These contain a predefined set of user-visible keys. When the app is in the background, the OS handles displaying these messages in the notification tray.
2. Data Messages: These are handled by the client app. They allow more flexibility as they're processed by the app's code and can still trigger onMessageReceived regardless of the app's state.

Why onMessageReceived

is Not Called

When an app is backgrounded, Android and iOS handle notifications differently. Here's why onMessageReceived may not be called:

Android

• Notification Messages: In Android, when your app is not in the foreground, notification messages are automatically shown in the system tray, and onMessageReceived does not get called. This is due to Android system's behavior that prevents apps from waking up too often without user intervention.
• Data Messages: This type of message will call onMessageReceived , whether the app is in the foreground or background, given that no notification payload is included. This allows for greater control over how to handle the message, such as displaying custom notifications or executing specific code logic.

iOS

• Notification Messages: On iOS, notification messages are handled by the operating system, similar to Android. When a message with a notification payload arrives, the system shows it in the notification center and will not call onMessageReceived .
• Data Messages: In contrast to Android, data messages on iOS will only call onMessageReceived when the app is in the foreground. This limitation is due to iOS's strict rules on background execution to conserve battery and optimize performance.

How to Ensure onMessageReceived

is Called

To have more consistent control over incoming messages using onMessageReceived , consider the following strategies:

Use Data Messages

• For Android, send only data messages by avoiding the notification key in your message payload. This allows your application to control what happens on message receipt, irrespective of the app's state.
• For iOS, though direct handling in the background is restricted, you can update the server or local storage upon receiving the message the next time the app is opened and seeks those updates.

Mixed Payload (Android Only)

• You can send a mixed payload of notification and data messages, but be aware that once a notification payload is included, onMessageReceived does not trigger when the app is in the background. Instead, handle additional logic within your notification service to manage data payloads separately.

Example of Sending Data-Only Messages

Here's how you can structure your FCM payload to ensure onMessageReceived is called: