🔔 Flutter Push Notifications (Foreground, Background, Terminated) — Complete Fix Guide

Push notifications in Flutter look easy…
until you actually try to implement them.

Everything seems fine - until:

• Notifications don't show in foreground
• Background handlers never trigger
• And terminated state? Completely broken.

If you've been there… yeah, same

We've faced all of this while working on a production app, and this guide is the exact setup that finally worked.

First - Understand Notification States (This is where most people go wrong)
Before writing a single line of code, you need to understand this:

👉 Each state behaves differently. And if you treat them the same, things will break.

Basic Setup

1. Add dependencies

// pubspec.yaml

firebase_core: ^4.6.0
firebase_messaging: ^16.1.3
flutter_local_notifications: ^21.0.0

2. Initialize Firebase

Before using FCM, initialize Firebase when your app starts:

await Firebase.initializeApp();

3. Request Notification Permission

This step is mandatory on iOS and Android 13+.

FirebaseMessaging messaging = FirebaseMessaging.instance;

await messaging.requestPermission(
  alert: true,
  badge: true,
  sound: true,
);

Why is this important?

Starting from Android 13, Android requires explicit notification permission, similar to iOS.

If permission is not granted, notifications won't appear.

Android Notification Channel (Must for Android)

Without this, notifications may not show or may appear silently.

const AndroidNotificationChannel channel = AndroidNotificationChannel(
  'high_importance_channel',
  'High Importance Notifications',
  description: 'This channel is used for important notifications.',
  importance: Importance.high,
);

final FlutterLocalNotificationsPlugin flutterLocalNotificationsPlugin =
    FlutterLocalNotificationsPlugin();

await flutterLocalNotificationsPlugin
    .resolvePlatformSpecificImplementation<
        AndroidFlutterLocalNotificationsPlugin>()
    ?.createNotificationChannel(channel);

---

iOS Foreground Notification Setup

iOS requires this to properly show notifications in foreground:

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

👉 Without this, notifications may not appear even if everything else is correct.

Foreground Notifications (Most Common Confusion)

The problem

You send a notification and nothing shows when the app is open. 
Feels like it's broken, right?

The reality

FCM does NOT display notifications in foreground.

The fix

You must show it manually using local notifications:

FirebaseMessaging.onMessage.listen((RemoteMessage message) {
  showLocalNotification(message);
});

💡 This is where most developers get stuck initially.

Background Notifications

This is where things start working automatically, but only if you do it right.

Works automatically IF your payload includes:

{
  "notification": {
    "title": "Hello",
    "body": "World"
  }
}

⚠️ Using data-only payload?

Then you MUST handle it manually:

FirebaseMessaging.onBackgroundMessage(_firebaseMessagingBackgroundHandler);

Future<void> _firebaseMessagingBackgroundHandler(RemoteMessage message) async {
  await Firebase.initializeApp(); // Required in background isolate
  print("Handling background message");
}

👉 Also, this function must be top-level.
(Not inside a class - easy mistake.)

Terminated State (Most Confusing Part)

This is where most implementations fail.

The issue

User taps notification → app opens → but nothing happens.

The fix

Handle the initial message:

RemoteMessage? initialMessage =
    await FirebaseMessaging.instance.getInitialMessage();

if (initialMessage != null) {
  handleNotificationClick(initialMessage);
}

Also listen when app is opened from background:

FirebaseMessaging.onMessageOpenedApp.listen((message) {
  handleNotificationClick(message);
});

👉 Without this, deep linking or navigation won't work.

Navigation Tip

handleNotificationClick() should:

• Read payload data
• Navigate to a specific screen

Local Notification Setup (Required for Foreground)

Without this, your foreground notifications will never show.

FlutterLocalNotificationsPlugin flutterLocalNotificationsPlugin =
    FlutterLocalNotificationsPlugin();

void showLocalNotification(RemoteMessage message) async {
  var androidDetails = AndroidNotificationDetails(
    'channel_id',
    'channel_name',
    importance: Importance.max,
    priority: Priority.high,
  );

  var generalNotificationDetails =
      NotificationDetails(android: androidDetails);

  await flutterLocalNotificationsPlugin.show(
    0,
    message.notification?.title,
    message.notification?.body,
    generalNotificationDetails,
  );
}

Common Mistakes (From Real Experience)

• Not asking notification permission (Android 13+ especially)
• Expecting foreground notifications to show automatically
• Using only data payload and expecting UI
• Background handler inside a class (won't work)
• Forgetting getInitialMessage()

👉 We've personally hit almost all of these 😅

Final Thoughts

Push notifications in Flutter are not plug-and-play.
They require:

• Proper setup
• Understanding of app states
• Correct payload structure

Key Takeaway

If your notifications are not working, 90% of the time:
👉 You didn't handle foreground manually
👉 OR your payload is wrong

If your notifications are not working on iOS or APNs token is not generating, check this:
👉 Flutter APNs Token Not Generating (Complete Fix Guide)

If this saved you hours of debugging, consider following for more Flutter deep dives.