/firebase-messaging

name: firebase-messaging
description: "Use when setting up Firebase Cloud Messaging, managing permissions and tokens, handling background/foreground notification taps, or dispatching messages server-side (HTTP v1)."
license: MIT

Firebase Cloud Messaging Skill

This skill defines how to correctly use Firebase Cloud Messaging (FCM) in Flutter applications.

When to Use

Use this skill when:

• 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

**iOS:**

• 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 authentication key matches your app's bundle ID.

**Android:**

• Devices must run **Android 4.4+** with Google Play services installed.
• Check for Google Play services compatibility in both `onCreate()` and `onResume()`.

**Web:**

• 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

**Foreground messages:**

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

**Background messages:**

@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());
}

Background handler rules:

• 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

**Get FCM registration token (use to send messages to a specific device):**

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

**Web — provide VAPID key:**

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

**Listen for token refresh:**

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

**Apple platforms — ensure APNS token is available before FCM calls:**

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

**Token Lifecycle (Auth State):** Tokens should be tied to user sessions. Save the token to your database when a user signs in, and **delete** the token (or remove it from the user's document) when they sign out. An FCM token is device-specific, not inherently tied to user auth data — failing to clear it on sign-out means the next user on that device might receive the previous user's notifications.

---

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**.
• **iOS foreground notifications:** Update presentation options to display notifications while the app is in the foreground:

  await FirebaseMessaging.instance.setForegroundNotificationPresentationOptions(
    alert: true,
    badge: true,
    sound: true,
  );

• **Android foreground notifications:** Notification messages arriving while the app is in the foreground won't display a visible notification by default. You must consume the payload via the `onMessage` stream and manually display a visual cue (using your own UI logic or a local notifications plugin).
• **Android default channel:** To set a default channel for background notifications, add this `meta-data` to your `<application>` block in `AndroidManifest.xml`:

  <meta-data
      android:name="com.google.firebase.messaging.default_notification_channel_id"
      android:value="high_importance_channel" />

---

6. Auto-Initialization Control

**Disable auto-init — iOS** (`