Flutter Push Notifications with FCM: The Complete 2026 Implementation Guide

# Install FlutterFire CLI (one time)
dart pub global activate flutterfire_cli

# Configure your project
flutterfire configure --project=your-firebase-project-id

# This generates firebase_options.dart automatically

dependencies:
 firebase_core: ^3.8.1
 firebase_messaging: ^15.2.1
 flutter_local_notifications: ^18.0.1

import 'package:firebase_core/firebase_core.dart';
import 'package:firebase_messaging/firebase_messaging.dart';
import 'firebase_options.dart';

@pragma('vm:entry-point')
Future<void> _firebaseMessagingBackgroundHandler(RemoteMessage message) async {
 await Firebase.initializeApp(options: DefaultFirebaseOptions.currentPlatform);
 // Handle background message — keep this lightweight
 debugPrint('Background message: ${message.messageId}');
}

Future<void> main() async {
 WidgetsFlutterBinding.ensureInitialized();
 await Firebase.initializeApp(options: DefaultFirebaseOptions.currentPlatform);

 // Register the background handler BEFORE runApp
 FirebaseMessaging.onBackgroundMessage(_firebaseMessagingBackgroundHandler);

 runApp(const MyApp());
}

class NotificationPermissionHandler {
 final FirebaseMessaging _messaging = FirebaseMessaging.instance;

 Future<bool> requestPermission() async {
 final settings = await _messaging.requestPermission(
 alert: true,
 badge: true,
 sound: true,
 provisional: false, // Set true for iOS quiet notifications
 announcement: false,
 carPlay: false,
 criticalAlert: false,
 );

 switch (settings.authorizationStatus) {
 case AuthorizationStatus.authorized:
 debugPrint('User granted full notification permission');
 return true;
 case AuthorizationStatus.provisional:
 debugPrint('User granted provisional permission');
 return true;
 case AuthorizationStatus.denied:
 debugPrint('User denied notification permission');
 return false;
 case AuthorizationStatus.notDetermined:
 debugPrint('Permission not yet requested');
 return false;
 }
 }
}

<manifest xmlns:android="http://schemas.android.com/apk/res/android">
 <uses-permission android:name="android.permission.POST_NOTIFICATIONS" />
 <!-- ... rest of manifest -->
</manifest>

import 'package:flutter_local_notifications/flutter_local_notifications.dart';
import 'package:firebase_messaging/firebase_messaging.dart';

class NotificationService {
 static final FlutterLocalNotificationsPlugin _localNotifications =
 FlutterLocalNotificationsPlugin();

 static Future<void> initialize() async {
 const androidSettings = AndroidInitializationSettings('@mipmap/ic_notification');

 const iosSettings = DarwinInitializationSettings(
 requestAlertPermission: false,
 requestBadgePermission: false,
 requestSoundPermission: false,
 );

 const initSettings = InitializationSettings(
 android: androidSettings,
 iOS: iosSettings,
 );

 await _localNotifications.initialize(
 initSettings,
 onDidReceiveNotificationResponse: _onNotificationTap,
 );

 // Listen for foreground messages
 FirebaseMessaging.onMessage.listen(_handleForegroundMessage);
 }

 static Future<void> _handleForegroundMessage(RemoteMessage message) async {
 final notification = message.notification;
 if (notification == null) return;

 await _localNotifications.show(
 message.hashCode,
 notification.title,
 notification.body,
 NotificationDetails(
 android: AndroidNotificationDetails(
 'high_importance_channel',
 'High Importance Notifications',
 channelDescription: 'Used for critical app notifications',
 importance: Importance.high,
 priority: Priority.high,
 icon: '@mipmap/ic_notification',
 ),
 iOS: const DarwinNotificationDetails(
 presentAlert: true,
 presentBadge: true,
 presentSound: true,
 ),
 ),
 payload: message.data['route'],
 );
 }

 static void _onNotificationTap(NotificationResponse response) {
 final route = response.payload;
 if (route != null && route.isNotEmpty) {
 // Navigate using your router — I use GoRouter
 navigatorKey.currentState?.pushNamed(route);
 }
 }
}

@pragma('vm:entry-point')
Future<void> _firebaseMessagingBackgroundHandler(RemoteMessage message) async {
 // You MUST re-initialize Firebase in the background isolate
 await Firebase.initializeApp(options: DefaultFirebaseOptions.currentPlatform);

 // Keep processing minimal — the OS can kill long-running handlers
 final type = message.data['type'];

 switch (type) {
 case 'order_update':
 await _updateLocalOrderCache(message.data);
 break;
 case 'chat_message':
 await _incrementUnreadBadge();
 break;
 default:
 debugPrint('Unhandled background message type: $type');
 }
}

Future<void> _updateLocalOrderCache(Map<String, dynamic> data) async {
 // Use a lightweight storage solution — SharedPreferences or Hive
 final prefs = await SharedPreferences.getInstance();
 final orderId = data['order_id'] as String?;
 final status = data['status'] as String?;
 if (orderId != null && status != null) {
 await prefs.setString('order_${orderId}_status', status);
 }
}

Future<void> _incrementUnreadBadge() async {
 final prefs = await SharedPreferences.getInstance();
 final current = prefs.getInt('unread_count') ?? 0;
 await prefs.setInt('unread_count', current + 1);
}

class AndroidChannelManager {
 static final FlutterLocalNotificationsPlugin _plugin =
 FlutterLocalNotificationsPlugin();

 static Future<void> createChannels() async {
 final androidPlugin = _plugin.resolvePlatformSpecificImplementation<
 AndroidFlutterLocalNotificationsPlugin>();
 if (androidPlugin == null) return;

 // Critical notifications — orders, payments, security alerts
 await androidPlugin.createNotificationChannel(
 const AndroidNotificationChannel(
 'critical_channel',
 'Critical Alerts',
 description: 'Order updates, payment confirmations, and security alerts',
 importance: Importance.high,
 playSound: true,
 enableVibration: true,
 ),
 );

 // Social notifications — messages, comments, likes
 await androidPlugin.createNotificationChannel(
 const AndroidNotificationChannel(
 'social_channel',
 'Social Updates',
 description: 'Messages, comments, and social activity',
 importance: Importance.defaultImportance,
 playSound: true,
 ),
 );

 // Marketing — promotions, offers, news
 await androidPlugin.createNotificationChannel(
 const AndroidNotificationChannel(
 'marketing_channel',
 'Promotions & News',
 description: 'Special offers, app updates, and news',
 importance: Importance.low,
 playSound: false,
 ),
 );
 }
}

class NotificationRouter {
 static final GlobalKey<NavigatorState> navigatorKey = GlobalKey<NavigatorState>();

 static Future<void> initialize() async {
 // Handle notification tap when app was terminated (cold start)
 final initialMessage = await FirebaseMessaging.instance.getInitialMessage();
 if (initialMessage != null) {
 _handleNotificationNavigation(initialMessage.data);
 }

 // Handle notification tap when app is in background
 FirebaseMessaging.onMessageOpenedApp.listen((RemoteMessage message) {
 _handleNotificationNavigation(message.data);
 });
 }

 static void _handleNotificationNavigation(Map<String, dynamic> data) {
 final route = data['route'] as String?;
 final id = data['id'] as String?;

 if (route == null) return;

 switch (route) {
 case 'order_detail':
 navigatorKey.currentContext?.goNamed('orderDetail', pathParameters: {'id': id ?? ''});
 break;
 case 'chat':
 navigatorKey.currentContext?.goNamed('chat', pathParameters: {'threadId': id ?? ''});
 break;
 case 'product':
 navigatorKey.currentContext?.goNamed('product', pathParameters: {'productId': id ?? ''});
 break;
 default:
 navigatorKey.currentContext?.go('/');
 }
 }
}

// Notification message — OS handles display automatically
{
 "message": {
 "token": "device_fcm_token",
 "notification": {
 "title": "Order Shipped",
 "body": "Your order #1234 is on the way!"
 },
 "data": {
 "route": "order_detail",
 "id": "1234"
 }
 }
}

// Data-only message — your handler controls everything
{
 "message": {
 "token": "device_fcm_token",
 "data": {
 "type": "order_update",
 "title": "Order Shipped",
 "body": "Your order #1234 is on the way!",
 "route": "order_detail",
 "id": "1234"
 }
 }
}

class TopicManager {
 final FirebaseMessaging _messaging = FirebaseMessaging.instance;

 /// Subscribe user to relevant topics based on their preferences
 Future<void> syncTopics(UserPreferences prefs) async {
 // Always subscribe to app-wide announcements
 await _messaging.subscribeToTopic('app_updates');

 // Category-based subscriptions
 if (prefs.wantsPromotions) {
 await _messaging.subscribeToTopic('promotions');
 } else {
 await _messaging.unsubscribeFromTopic('promotions');
 }

 if (prefs.wantsNewsAlerts) {
 await _messaging.subscribeToTopic('news_${prefs.preferredLanguage}');
 }

 // Location-based topics for geo-relevant content
 if (prefs.city != null) {
 await _messaging.subscribeToTopic('city_${prefs.city!.toLowerCase()}');
 }
 }

 /// Unsubscribe from all topics on logout
 Future<void> clearAllTopics() async {
 await _messaging.unsubscribeFromTopic('app_updates');
 await _messaging.unsubscribeFromTopic('promotions');
 // Unsubscribe from any locale/city topics too
 }
}

// Cloud Function (TypeScript) — send notification on order status change
import * as functions from 'firebase-functions/v2';
import * as admin from 'firebase-admin';

admin.initializeApp();

export const onOrderStatusChange = functions.firestore
 .onDocumentUpdated('orders/{orderId}', async (event) => {
 const before = event.data?.before.data();
 const after = event.data?.after.data();

 if (!before || !after) return;
 if (before.status === after.status) return;

 const userId = after.userId as string;
 const orderId = event.params.orderId;
 const newStatus = after.status as string;

 // Fetch user's FCM token from their profile
 const userDoc = await admin.firestore()
 .collection('users')
 .doc(userId)
 .get();

 const fcmToken = userDoc.data()?.fcmToken;
 if (!fcmToken) return;

 const statusMessages: Record<string, string> = {
 'confirmed': 'Your order has been confirmed!',
 'preparing': 'Your order is being prepared',
 'shipped': 'Your order is on the way!',
 'delivered': 'Your order has been delivered',
 };

 const body = statusMessages[newStatus] || `Order updated to: ${newStatus}`;

 // Send data-only message for full client control
 await admin.messaging().send({
 token: fcmToken,
 data: {
 type: 'order_update',
 title: `Order #${orderId}`,
 body: body,
 route: 'order_detail',
 id: orderId,
 status: newStatus,
 },
 android: {
 priority: 'high',
 },
 apns: {
 payload: {
 aps: {
 'content-available': 1,
 },
 },
 },
 });
 });

class FCMTokenManager {
 final FirebaseMessaging _messaging = FirebaseMessaging.instance;
 final FirebaseFirestore _firestore = FirebaseFirestore.instance;

 Future<void> initializeToken(String userId) async {
 // Get current token and save it
 final token = await _messaging.getToken();
 if (token != null) {
 await _saveToken(userId, token);
 }

 // Listen for token refresh events
 _messaging.onTokenRefresh.listen((newToken) {
 _saveToken(userId, newToken);
 });
 }

 Future<void> _saveToken(String userId, String token) async {
 await _firestore.collection('users').doc(userId).set({
 'fcmTokens': {
 _getDeviceId(): {
 'token': token,
 'updatedAt': FieldValue.serverTimestamp(),
 'platform': Platform.isIOS ? 'ios' : 'android',
 },
 },
 }, SetOptions(merge: true));
 }

 String _getDeviceId() {
 // Use a package like device_info_plus for a stable device identifier
 // Or generate a UUID on first install and store in SharedPreferences
 return 'device_${DateTime.now().millisecondsSinceEpoch}';
 }

 Future<void> removeToken(String userId) async {
 // Call this on logout to prevent phantom notifications
 final token = await _messaging.getToken();
 if (token != null) {
 await _firestore.collection('users').doc(userId).update({
 'fcmTokens.${_getDeviceId()}': FieldValue.delete(),
 });
 }
 await _messaging.deleteToken();
 }
}

Future<void> showRichNotification(Map<String, dynamic> data) async {
 final imageUrl = data['image_url'] as String?;
 BigPictureStyleInformation? bigPicture;

 if (imageUrl != null) {
 try {
 final response = await http.get(Uri.parse(imageUrl));
 bigPicture = BigPictureStyleInformation(
 ByteArrayAndroidBitmap.fromBase64String(
 base64Encode(response.bodyBytes),
 ),
 contentTitle: data['title'],
 summaryText: data['body'],
 );
 } catch (e) {
 // Fall back to text-only if image download fails
 debugPrint('Failed to download notification image: $e');
 }
 }

 await FlutterLocalNotificationsPlugin().show(
 DateTime.now().millisecondsSinceEpoch ~/ 1000,
 data['title'] as String?,
 data['body'] as String?,
 NotificationDetails(
 android: AndroidNotificationDetails(
 data['channel'] as String? ?? 'default_channel',
 'Default Notifications',
 importance: Importance.high,
 priority: Priority.high,
 styleInformation: bigPicture,
 actions: <AndroidNotificationAction>[
 const AndroidNotificationAction('view', 'View',
 showsUserInterface: true),
 const AndroidNotificationAction('dismiss', 'Dismiss'),
 ],
 ),
 iOS: DarwinNotificationDetails(
 presentAlert: true,
 presentBadge: true,
 presentSound: true,
 attachments: imageUrl != null
 ? [DarwinNotificationAttachment(imageUrl)]
 : null,
 ),
 ),
 payload: '${data["route"]}:${data["id"]}',
 );
}

// Temporary — remove before shipping
final token = await FirebaseMessaging.instance.getToken();
debugPrint('FCM Token: $token');
// Copy this from your debug console

# Get an access token (requires gcloud CLI and a service account)
ACCESS_TOKEN=$(gcloud auth print-access-token)

# Send a data-only test message
curl -X POST \
 "https://fcm.googleapis.com/v1/projects/YOUR_PROJECT_ID/messages:send" \
 -H "Authorization: Bearer $ACCESS_TOKEN" \
 -H "Content-Type: application/json" \
 -d '{
 "message": {
 "token": "PASTE_DEVICE_TOKEN_HERE",
 "data": {
 "type": "test",
 "title": "Test Notification",
 "body": "Testing deep link to order",
 "route": "order_detail",
 "id": "test-123"
 }
 }
 }'

/// Production notification service that handles all FCM lifecycle events
class ProductionNotificationService {
 final FirebaseMessaging _messaging = FirebaseMessaging.instance;
 final FlutterLocalNotificationsPlugin _localPlugin =
 FlutterLocalNotificationsPlugin();

 // Stream controller for notification taps — consumed by your router
 final StreamController<Map<String, dynamic>> _navigationStream =
 StreamController<Map<String, dynamic>>.broadcast();

 Stream<Map<String, dynamic>> get onNotificationTap => _navigationStream.stream;

 Future<void> initialize() async {
 // 1. Create Android notification channels
 await _createChannels();

 // 2. Initialize local notifications plugin
 await _initializeLocalNotifications();

 // 3. Check terminated-state deep link
 final initialMessage = await _messaging.getInitialMessage();
 if (initialMessage != null) {
 _navigationStream.add(initialMessage.data);
 }

 // 4. Listen for background tap events
 FirebaseMessaging.onMessageOpenedApp.listen((message) {
 _navigationStream.add(message.data);
 });

 // 5. Listen for foreground messages
 FirebaseMessaging.onMessage.listen(_showForegroundNotification);

 // 6. Set foreground presentation options for iOS
 await _messaging.setForegroundNotificationPresentationOptions(
 alert: false, // We handle display ourselves
 badge: true,
 sound: false,
 );
 }

 Future<void> _createChannels() async {
 final android = _localPlugin.resolvePlatformSpecificImplementation<
 AndroidFlutterLocalNotificationsPlugin>();
 if (android == null) return;

 const channels = [
 AndroidNotificationChannel('orders', 'Order Updates',
 description: 'Order status notifications',
 importance: Importance.high),
 AndroidNotificationChannel('messages', 'Messages',
 description: 'Chat messages',
 importance: Importance.high),
 AndroidNotificationChannel('promotions', 'Promotions',
 description: 'Deals and offers',
 importance: Importance.low),
 ];

 for (final channel in channels) {
 await android.createNotificationChannel(channel);
 }
 }

 Future<void> _initializeLocalNotifications() async {
 await _localPlugin.initialize(
 const InitializationSettings(
 android: AndroidInitializationSettings('@mipmap/ic_notification'),
 iOS: DarwinInitializationSettings(),
 ),
 onDidReceiveNotificationResponse: (response) {
 final payload = response.payload;
 if (payload != null) {
 final parts = payload.split(':');
 _navigationStream.add({'route': parts[0], 'id': parts.length > 1 ? parts[1] : ''});
 }
 },
 );
 }

 Future<void> _showForegroundNotification(RemoteMessage message) async {
 final data = message.data;
 final channelId = _getChannelId(data['type']);

 await _localPlugin.show(
 DateTime.now().millisecondsSinceEpoch ~/ 1000,
 data['title'] ?? message.notification?.title ?? 'Notification',
 data['body'] ?? message.notification?.body,
 NotificationDetails(
 android: AndroidNotificationDetails(
 channelId, channelId,
 importance: Importance.high,
 priority: Priority.high,
 ),
 iOS: const DarwinNotificationDetails(presentAlert: true, presentSound: true),
 ),
 payload: '${data["route"]}:${data["id"]}',
 );
 }

 String _getChannelId(String? type) {
 switch (type) {
 case 'order_update': return 'orders';
 case 'chat_message': return 'messages';
 case 'promo': return 'promotions';
 default: return 'orders';
 }
 }

 void dispose() {
 _navigationStream.close();
 }
}