Firebase Cloud Messaging Skill

When to Use

• Setting up push notifications with FCM in a Flutter project.
• Handling messages in foreground, background, and terminated states.
• Managing notification permissions and FCM tokens.
• Configuring platform-specific notification display behavior.

1. Setup and Configuration

flutter pub add firebase_messaging

• Enable Push Notifications and Background Modes in Xcode.
• Upload your APNs authentication key to Firebase before using FCM.
• Do not disable method swizzling — it is required for FCM token handling.
• Ensure the bundle ID for your APNs certificate matches your app's bundle ID.

• Devices must run Android 4.4+ with Google Play services installed.
• Check for Google Play services compatibility in both

  onCreate()

  and

  onResume()

  .

• Create and register a service worker file named

  firebase-messaging-sw.js

  in your

  web/

  directory:

importScripts("https://www.gstatic.com/firebasejs/10.7.0/firebase-app-compat.js");
importScripts("https://www.gstatic.com/firebasejs/10.7.0/firebase-messaging-compat.js");

firebase.initializeApp({ /* your config */ });

const messaging = firebase.messaging();

messaging.onBackgroundMessage((message) => {
  console.log("onBackgroundMessage", message);
});

2. Message Handling

FirebaseMessaging.onMessage.listen((RemoteMessage message) {
  print('Foreground message data: ${message.data}');
  if (message.notification != null) {
    print('Notification: ${message.notification}');
  }
});

@pragma('vm:entry-point')
Future<void> _firebaseMessagingBackgroundHandler(RemoteMessage message) async {
  // Initialize Firebase before using other Firebase services in background
  await Firebase.initializeApp();
  print("Background message: ${message.messageId}");
}

void main() {
  FirebaseMessaging.onBackgroundMessage(_firebaseMessagingBackgroundHandler);
  runApp(MyApp());
}

• Must be a top-level function (not anonymous, not a class method).
• Annotate with

  @pragma('vm:entry-point')

  (Flutter 3.3.0+) to prevent removal during tree shaking in release mode.
• Cannot update app state or execute UI-impacting logic — runs in a separate isolate.
• Call

  Firebase.initializeApp()

  before using any other Firebase services.

3. Permissions

NotificationSettings settings = await FirebaseMessaging.instance.requestPermission(
  alert: true,
  badge: true,
  sound: true,
  announcement: false,
  carPlay: false,
  criticalAlert: false,
  provisional: false,
);

print('Authorization status: ${settings.authorizationStatus}');

• iOS / macOS / Web / Android 13+: Must request permission before receiving FCM payloads.
• Android < 13:

  authorizationStatus

  returns

  authorized

  if the user has not disabled notifications in OS settings.
• Android 13+: Track permission requests in your app — there's no way to determine if the user chose to grant/deny.
• Use provisional permissions on iOS (

  provisional: true

  ) to let users choose notification types after receiving their first notification.

4. Token Management

final fcmToken = await FirebaseMessaging.instance.getToken();

final fcmToken = await FirebaseMessaging.instance.getToken(
  vapidKey: "BKagOny0KF_2pCJQ3m....moL0ewzQ8rZu"
);

FirebaseMessaging.instance.onTokenRefresh.listen((fcmToken) {
  // Send updated token to your application server
}).onError((err) {
  // Handle error
});

final apnsToken = await FirebaseMessaging.instance.getAPNSToken();
if (apnsToken != null) {
  // Safe to make FCM plugin API requests
}

5. Platform-Specific Behavior

• iOS: If the user swipes away the app from the app switcher, it must be manually reopened for background messages to work again.
• Android: If the user force-quits from device settings, the app must be manually reopened.
• Android foreground notifications: Create a "High Priority" notification channel to display notifications while the app is in the foreground.
• iOS foreground notifications: Update presentation options to display notifications while the app is in the foreground.

6. Auto-Initialization Control

Info.plist

FirebaseMessagingAutoInitEnabled = NO

AndroidManifest.xml

<meta-data android:name="firebase_messaging_auto_init_enabled" android:value="false" />
<meta-data android:name="firebase_analytics_collection_enabled" android:value="false" />

await FirebaseMessaging.instance.setAutoInitEnabled(true);

• The auto-init setting persists across app restarts once set.

7. iOS Image Notifications

Important: The iOS simulator does not display images in push notifications. Test on a physical device.

• Add a Notification Service Extension in Xcode.
• Use

  Messaging.serviceExtension().populateNotificationContent()

  in the extension for image handling.
• Swift: add the

  FirebaseMessaging

  Swift package to your extension target.
• Objective-C: add the

  Firebase/Messaging

  pod to your Podfile.

References

• Firebase Cloud Messaging Flutter documentation
• Receive messages in Flutter