This skill defines how to correctly use Firebase Cloud Messaging (FCM) in Flutter applications.
\nUse this skill when:
\nflutter pub add firebase_messaging\niOS:
\nAndroid:
\nonCreate() and onResume().Web:
\nfirebase-messaging-sw.js in your web/ directory:importScripts(\"https://www.gstatic.com/firebasejs/10.7.0/firebase-app-compat.js\");\nimportScripts(\"https://www.gstatic.com/firebasejs/10.7.0/firebase-messaging-compat.js\");\n\nfirebase.initializeApp({ /* your config */ });\n\nconst messaging = firebase.messaging();\n\nmessaging.onBackgroundMessage((message) => {\n console.log(\"onBackgroundMessage\", message);\n});\nForeground messages:
\nFirebaseMessaging.onMessage.listen((RemoteMessage message) {\n print('Foreground message data: ${message.data}');\n if (message.notification != null) {\n print('Notification: ${message.notification}');\n }\n});\nBackground messages:
\n@pragma('vm:entry-point')\nFuture<void> _firebaseMessagingBackgroundHandler(RemoteMessage message) async {\n // Initialize Firebase before using other Firebase services in background\n await Firebase.initializeApp();\n print(\"Background message: ${message.messageId}\");\n}\n\nvoid main() {\n FirebaseMessaging.onBackgroundMessage(_firebaseMessagingBackgroundHandler);\n runApp(MyApp());\n}\nBackground handler rules:
\n@pragma('vm:entry-point') (Flutter 3.3.0+) to prevent removal during tree shaking in release mode.Firebase.initializeApp() before using any other Firebase services.NotificationSettings settings = await FirebaseMessaging.instance.requestPermission(\n alert: true,\n badge: true,\n sound: true,\n announcement: false,\n carPlay: false,\n criticalAlert: false,\n provisional: false,\n);\n\nprint('Authorization status: ${settings.authorizationStatus}');\nauthorizationStatus returns authorized if the user has not disabled notifications in OS settings.provisional: true) to let users choose notification types after receiving their first notification.Get FCM registration token (use to send messages to a specific device):
\nfinal fcmToken = await FirebaseMessaging.instance.getToken();\nWeb — provide VAPID key:
\nfinal fcmToken = await FirebaseMessaging.instance.getToken(\n vapidKey: \"BKagOny0KF_2pCJQ3m....moL0ewzQ8rZu\"\n);\nListen for token refresh:
\nFirebaseMessaging.instance.onTokenRefresh.listen((fcmToken) {\n // Send updated token to your application server\n}).onError((err) {\n // Handle error\n});\nApple platforms — ensure APNS token is available before FCM calls:
\nfinal apnsToken = await FirebaseMessaging.instance.getAPNSToken();\nif (apnsToken != null) {\n // Safe to make FCM plugin API requests\n}\nToken Lifecycle (Auth State):\nTokens 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.
\nawait FirebaseMessaging.instance.setForegroundNotificationPresentationOptions(\n alert: true,\n badge: true,\n sound: true,\n);\nonMessage stream and manually display a visual cue (using your own UI logic or a local notifications plugin).meta-data to your <application> block in AndroidManifest.xml:\n<meta-data\n android:name=\"com.google.firebase.messaging.default_notification_channel_id\"\n android:value=\"high_importance_channel\" />\nDisable auto-init — iOS (Info.plist):
FirebaseMessagingAutoInitEnabled = NO\nDisable auto-init — Android (AndroidManifest.xml):
<meta-data android:name=\"firebase_messaging_auto_init_enabled\" android:value=\"false\" />\n<meta-data android:name=\"firebase_analytics_collection_enabled\" android:value=\"false\" />\nRe-enable at runtime:
\nawait FirebaseMessaging.instance.setAutoInitEnabled(true);\n\n\nImportant: The iOS simulator does not display images in push notifications. Test on a physical device.
\n
Messaging.serviceExtension().populateNotificationContent() in the extension for image handling.FirebaseMessaging Swift package to your extension target.Firebase/Messaging pod to your Podfile.When a user taps a notification, the app opens (or is brought to the foreground). Handle the interaction in both cases:
\nApp was terminated:
\nRemoteMessage? initialMessage =\n await FirebaseMessaging.instance.getInitialMessage();\nif (initialMessage != null) {\n // Navigate based on message content\n}\nApp was in background:
\nFirebaseMessaging.onMessageOpenedApp.listen((RemoteMessage message) {\n // Navigate based on message content\n});\nAlways handle both scenarios to ensure a smooth user experience regardless of app state when the notification was received.
\n// Subscribe\nawait FirebaseMessaging.instance.subscribeToTopic(\"weather_alerts\");\n\n// Unsubscribe\nawait FirebaseMessaging.instance.unsubscribeFromTopic(\"weather_alerts\");\n\n\nNote:
\nsubscribeToTopic()andunsubscribeFromTopic()are not supported for web clients via the Flutter plugin.
The official Firebase documentation often obscures the exact steps for sending a test push notification. To fire a push (test or real) using the Firebase Console:
\n+ icon to add it.\n\nTo send real automated push notifications to production users, you must use a server implementation (via the FCM HTTP v1 API or the Firebase Admin SDK) rather than the console.
\n
The legacy FCM server key endpoint was deprecated in June 2024 — HTTP v1 is the only supported option for sending pushes.
\nTo authenticate server-to-server calls for HTTP v1, you need a Service Account:
\n.json file).FIREBASE_SERVICE_ACCOUNT) to your backend.To send an FCM HTTP v1 message, your backend must:
\nhttps://www.googleapis.com/auth/firebase.messaging, endpoint https://oauth2.googleapis.com/token).POST a JSON payload to https://fcm.googleapis.com/v1/projects/{project_id}/messages:send.Here is a minimal, complete working example using Node.js and the google-auth-library:
const { GoogleAuth } = require('google-auth-library');\n\n// Read the securely-stored service account JSON from environment\nconst credentials = JSON.parse(process.env.FIREBASE_SERVICE_ACCOUNT);\n\nasync function getAccessToken() {\n const auth = new GoogleAuth({\n credentials,\n scopes: ['https://www.googleapis.com/auth/firebase.messaging']\n });\n const client = await auth.getClient();\n const token = await client.getAccessToken();\n return token.token;\n}\n\nasync function sendPushNotification(fcmToken, title, body) {\n const accessToken = await getAccessToken();\n const projectId = credentials.project_id;\n const url = `https://fcm.googleapis.com/v1/projects/${projectId}/messages:send`;\n \n const payload = {\n message: {\n token: fcmToken,\n notification: {\n title: title,\n body: body,\n },\n // Target specific platform features (e.g., channel on Android, sound on iOS)\n android: {\n notification: {\n channel_id: 'high_importance_channel',\n }\n },\n apns: {\n payload: {\n aps: {\n sound: 'default',\n }\n }\n }\n }\n };\n\n const response = await fetch(url, {\n method: 'POST',\n headers: {\n 'Authorization': `Bearer ${accessToken}`,\n 'Content-Type': 'application/json'\n },\n body: JSON.stringify(payload)\n });\n\n return response.json();\n}\n