Flutter Firebase Messaging: Handling Foreground and Background Messages

In today's mobile landscape, staying connected and engaging with your users is crucial. Push notifications offer a powerful way to deliver timely, relevant information and keep users informed and engaged with your app.

Firebase Cloud Messaging (FCM) provides a reliable and efficient solution for implementing push notifications in your Flutter app. By leveraging Firebase Messaging, you can send targeted messages to specific user segments or broadcast updates to your entire user base. But simply sending messages isn't enough, effectively handling those messages on both the user's device and within your app is equally important.

This blog will guide you through the process of handling both foreground and background messages in your Flutter app using Flutter Firebase Messaging. We'll delve into the different message types, explore platform-specific considerations, and equip you with the knowledge to implement robust notification handling in your Flutter application.

Whether you're a seasoned Flutter developer or just starting out, this blog will provide valuable insights and practical guidance to ensure your app delivers an exceptional user experience through effective push notifications.

Understanding Message Types: Notification vs. Data Messages

Firebase Cloud Messaging (FCM) offers two distinct message types: notification messages and data messages. Understanding their purpose and behavior in different app states is crucial for effective notification handling in your Flutter app.

A. Notification Messages:

These messages primarily aim to grab the user's attention with visual notifications displayed on their device.

• Foreground: When your app is in the foreground, notification messages won't automatically display a visual notification by default on both Android and iOS. However, the message payload containing information like title, body, and data is still accessible within your app through the onMessage stream. This allows you to customize how you want to handle the notification within your app's UI, like displaying a banner or updating data.
• Background: If your app is in the background when a notification message arrives, the system displays a visual notification on the user's device along with the provided content. Tapping on this notification typically launches the app to its default screen.

B. Data Messages:

Unlike notification messages, data messages focus solely on delivering payload data to your app, bypassing any visual notification on the user's device.

• Foreground: In the foreground, data messages are delivered through the onMessage stream, similar to notification messages. This allows you to process the received data payload and integrate it seamlessly into your app's functionality, such as updating real-time information or triggering specific actions.

• Background: When your app is in the background, data messages are handled differently depending on the platform. On Android, the data is delivered through the onMessageReceived method of a dedicated service (e.g., FirebaseMessagingService). For iOS and Web, the data is typically delivered through the platform's native messaging mechanisms.

By understanding the distinction between notification and data messages and their behavior in different app states, you can effectively leverage Flutter Firebase Messaging to deliver engaging notifications and enhance the user experience of your Flutter app.

Handling Foreground Messages in Flutter with Firebase Cloud Messaging

When your Flutter app is actively in the foreground, handling incoming messages from Firebase Cloud Messaging (FCM) involves a straightforward process. Here's how to handle them effectively:

A. Setting Up:

• Package Configuration: Ensure you have the firebase_messaging package installed and configured in your Flutter project. Refer to the official documentation for detailed setup instructions: https://pub.dev/packages/firebase_messaging
• onMessage Stream: Firebase Messaging provides the onMessage stream, which continuously listens for incoming messages. You can listen to this stream in your widget's initState method:

Copy
1
2
3
4
5
6
void initState() {
  super.initState();
  FirebaseMessaging.onMessage.listen((RemoteMessage message) {
    // Handle incoming message
  });
}

B. Processing the RemoteMessage:

The onMessage stream delivers a RemoteMessage object containing all the message details. You can access various properties like:

• message.data: A Map<String, dynamic> containing custom data sent from your server.
• message.notification: A RemoteNotification object if the message includes a notification (title, body, etc.). Here's an example of extracting the notification title and data payload:

Copy
1
2
3
4
5
6
7
8
void handleIncomingMessage(RemoteMessage message) {
  if (message.notification != null) {
    print('Notification Title: ${message.notification!.title}');
  }
  if (message.data.isNotEmpty) {
    print('Data Payload: ${message.data}');
  }
}

C. Taking Action:

Based on the message content, you can take various actions within your app:

• Update UI: Display the notification title or data in your app's UI elements like badges, lists, or snackbars.
• Trigger Actions: Based on the received data, trigger specific actions within your app, such as navigating to a different screen, updating real-time data, or triggering background processes.

Here's an example of updating a UI element (e.g., a badge) with the received data:

Copy
1
2
3
4
final badgeCount = int.tryParse(message.data['count'] ?? '0');
setState(() {
  _badgeCount = badgeCount;
});

By following these steps, you can effectively handle foreground messages in your Flutter app and leverage them to enhance your app's functionality and user experience.

Note: Handling background messages involves platform-specific approaches. We'll explore Android, iOS, and Web scenarios in the next part of the blog.

Handling Background Messages in Flutter with Firebase Cloud Messaging

While handling foreground messages is relatively straightforward, background messages require different approaches depending on the platform. Let's delve into how FCM handles background messages on Android, iOS, and Web:

A. Android:

Unlike other platforms, Android requires a dedicated service to handle background messages. This service, typically named FirebaseMessagingService, extends the platform's FirebaseMessagingService class:

Copy
1
2
3
4
5
6
7
class MyFirebaseMessagingService extends FirebaseMessagingService {
  @Override
  void onMessageReceived(RemoteMessage message) {
    super.onMessageReceived(message);
    // Handle incoming message
  }
}

The onMessageReceived method is called whenever a message arrives while the app is in the background. Here, you can process the message data similar to how you handled foreground messages in the previous section.

Important Note: Background services on Android have limitations. They have a restricted execution time, and extensive processing within this method might get interrupted by the system.

B. iOS and Web:

For iOS and Web platforms, FCM doesn't require a dedicated service like Android. Background message handling utilizes the platform's native messaging mechanisms.

iOS:

FCM delivers messages through Apple Push Notification service (APNs). You can handle them in your app delegate's didReceiveRemoteNotification method or utilize the flutter_local_notifications plugin for richer notification handling.

Web: FCM relies on browser-level Service Workers to manage background messages. You can register a service worker and handle messages in its onmessage event. For detailed guidance on iOS and Web background message handling, refer to the official documentation and relevant plugin resources:

• iOS: https://firebase.google.com/docs/cloud-messaging/ios/client
• Web: https://firebase.google.com/docs/cloud-messaging/js/client
• flutter_local_notifications: https://pub.dev/packages/flutter_local_notifications

By understanding these platform-specific considerations, you can ensure your Flutter app effectively handles both foreground and background messages, delivering a seamless user experience even when the app isn't actively in use.

Best Practices for User Interaction and Error Handling in Flutter Firebase Cloud Messaging

A. User Interaction:

1. Customizing Notification Behavior: Leverage the notification property of the RemoteMessage object to customize notification appearance (sound, vibration) and behavior on each platform. Refer to the official documentation for platform-specific APIs:

• Android: https://firebase.google.com/docs/cloud-messaging/android/client
• iOS: https://firebase.google.com/docs/cloud-messaging/ios/client

2. Handling User Taps: When a user taps a notification, you can utilize deep linking to navigate them to specific sections within your app. Use libraries like url_launcher or platform-specific deep linking solutions:

• Android: https://pub.dev/packages/url_launcher
• iOS: https://developer.apple.com/documentation/xcode/supporting-universal-links-in-your-app

Implement logic within your app to handle the deep link associated with the tapped notification and navigate the user accordingly.

3. Deep Linking: Deep linking allows you to create unique URLs that, when tapped within a notification, open specific sections within your app. This enhances the user experience by directing them to relevant content based on the notification they clicked.

B. Error Handling:

Importance: Errors can occur during various stages of message processing, such as subscribing to topics or retrieving the message payload. Implementing proper error handling is crucial to ensure your app functions reliably and provides informative messages to the user in case of issues.

Code Example:

Copy
1
2
3
4
5
6
7
8
9
void handleIncomingMessage(RemoteMessage message) async {
  try {
    // Process the message data
    print('Data Payload: ${message.data}');
  } catch (error) {
    print('Error handling message: $error');
    // Implement error handling logic (e.g., display an error message to the user)
  }
}

In this example, we wrap the message processing code within a try...catch block. If any exceptions occur during processing, the catch block catches the error object and allows you to implement appropriate error-handling logic, such as logging the error or displaying a user-friendly message.

By implementing these best practices, you can ensure your Flutter app provides a user-friendly and robust experience when interacting with Firebase Cloud Messaging notifications. Remember to tailor the approach to your specific app's requirements and handle potential errors gracefully to maintain a smooth user experience.

Conclusion:

Firebase Cloud Messaging offers a powerful and versatile tool for delivering targeted notifications to your Flutter app users. By understanding the different message types, handling them effectively in both foreground and background states, and implementing best practices for user interaction and error handling, you can elevate your app's user experience and engagement.

Remember, effective and engaging notifications rely on a balance between informing users and avoiding being intrusive. Experiment with different approaches, gather user feedback, and continuously refine your notification strategy to optimize user experience and retention.

This blog has provided a foundational understanding of Firebase Cloud Messaging in Flutter. For further exploration, delve deeper into the official documentation, explore platform-specific resources, and stay updated on the latest advancements in FCM and Flutter development.

Happy messaging!