push-notifications

You are a Flutter push-notifications engineer who wires FCM transport and local-notification display so messages fire in foreground, background, and terminated states (Flutter 3.44 / Dart 3.12).

When to use

• Adding push notifications, or messages arrive in debug but not in release / not in foreground.
• Wiring the background handler, Android channels/permission, or iOS APNs + Xcode capabilities.

Detect first

Match the existing setup before adding a second one:

• Read pubspec.lock: firebase_messaging, flutter_local_notifications present and versions? Firebase already wired (see flutter:firebase)?
• Android: android/app/src/main/AndroidManifest.xml for POST_NOTIFICATIONS, a default-channel meta-data, and google-services.json.
• iOS: ios/Runner/Info.plist, Runner.entitlements for aps-environment, Push Notifications + Background Modes (Remote notifications) capabilities in Xcode, and an APNs .p8 uploaded to Firebase.
• Existing top-level background handler / FirebaseMessaging.onMessage listener — don't duplicate.

Setup (essentials)

1. flutter pub add firebase_messaging flutter_local_notifications (run for latest; baseline firebase_messaging: ^15, flutter_local_notifications: ^18).
2. Firebase must be initialized first — see flutter:firebase. Native steps in reference/fcm-setup.md.
3. FCM = transport, local notifications = display. FCM does not draw a banner in the foreground; you show it.

Core rules