Firebase Cloud Messaging: Analysis and Solutions for onMessageReceived Not Called When App is in Background

Overview of Firebase Cloud Messaging Mechanism

Firebase Cloud Messaging (FCM), as a core service for push notifications in mobile applications, exhibits significant differences in message handling across various application states. When the app is in the foreground, FCM messages directly trigger the onMessageReceived callback method, allowing developers to process message content. However, when the app transitions to the background or is completely closed, the message processing logic undergoes fundamental changes.

Behavior Analysis of Background Message Handling

According to Firebase official documentation and practical testing, when an app is in the background, messages containing a notification field will not trigger the onMessageReceived method. The system automatically displays the notification in the notification center, while the data content within the message is passed through an Intent. This behavior is designed to optimize user experience by preventing frequent wake-ups of background applications that consume system resources.

Solution 1: Using the click_action Parameter

When an application needs to handle click events on background notifications, the click_action parameter can be specified in the server-side message. This parameter defines the Activity that should be launched when the user clicks the notification. In the target Activity, all data contained in the message can be retrieved using the getIntent().getExtras() method.

Server-side message format example:

{
  "notification": {
    "title": "Message Title",
    "body": "Message Content",
    "click_action": "TARGET_ACTIVITY"
  },
  "data": {
    "custom_key": "custom_value"
  },
  "to": "device_token"
}

Handling data in the target Activity:

@Override
protected void onCreate(Bundle savedInstanceState) {
    super.onCreate(savedInstanceState);
    
    Bundle extras = getIntent().getExtras();
    if (extras != null) {
        String customValue = extras.getString("custom_key");
        // Process the received data
    }
}

Solution 2: Using Pure Data Messages

Another more direct approach is to use pure data messages, avoiding the notification field entirely. Data messages trigger the onMessageReceived method regardless of whether the app is in the foreground or background. However, it is important to note that data messages use normal priority by default and may require explicit setting of "priority": "high" to ensure timely delivery.

Pure data message format:

{
  "data": {
    "id": "1",
    "message": "Important Notice",
    "timestamp": "2024-01-01 12:00:00"
  },
  "to": "device_token",
  "priority": "high"
}

Processing data in onMessageReceived:

@Override
public void onMessageReceived(RemoteMessage remoteMessage) {
    Log.i("FCM", "Message Received");
    
    Map<String, String> data = remoteMessage.getData();
    if (data != null) {
        String id = data.get("id");
        String message = data.get("message");
        // Process data and create custom notification
        createCustomNotification(id, message);
    }
}

Message Type Comparison and Selection Recommendations

Notification messages are suitable for scenarios requiring system-level notification displays, while data messages are better suited for business logic that requires internal application processing. Mixed messages (containing both notification and data fields) in the background state have their notification portion handled by the system, with the data portion passed through an Intent when the user clicks the notification.

Implementation Considerations

Proper configuration of Firebase messaging services in AndroidManifest.xml is crucial:

<service
    android:name=".FBMessagingService"
    android:exported="false">
    <intent-filter>
        <action android:name="com.google.firebase.MESSAGING_EVENT" />
    </intent-filter>
</service>

Additionally, ensure the application has necessary permissions and test message reception behavior across different Android versions, as system policies restricting background applications may affect message delivery.

Performance Optimization Recommendations

For frequent message pushes, it is recommended to use data messages and implement local notification management to reduce system resource consumption. Additionally, properly set message priority and time-to-live (TTL) to ensure important messages are delivered promptly.