🔥 Flutter Local Notification & Firebase Push 완전 정복 (2025 최신)

Flutter 앱을 만들다 보면 푸시 알림은 필수죠.
이번 글에서는 Local Notification부터 Firebase FCM Push까지 한 번에 정리해드립니다.

---

✅ 1️⃣ Flutter Local Notification이란?

Local Notification은 앱 내부에서 스케줄링한 알림입니다.
예: ToDo 알림, 예약 알림, 정기 알림 등.

// pubspec.yaml에 추가
flutter_local_notifications: ^15.0.0

// 초기화 예시
final FlutterLocalNotificationsPlugin flutterLocalNotificationsPlugin = FlutterLocalNotificationsPlugin();

void main() async {
  WidgetsFlutterBinding.ensureInitialized();

  const AndroidInitializationSettings initializationSettingsAndroid =
    AndroidInitializationSettings('@mipmap/ic_launcher');

  const InitializationSettings initializationSettings = InitializationSettings(
    android: initializationSettingsAndroid,
  );

  await flutterLocalNotificationsPlugin.initialize(initializationSettings);

  runApp(MyApp());
}

TIP: AndroidManifest.xml에 권한 등록 필수!

<uses-permission android:name="android.permission.POST_NOTIFICATIONS" />

---

✅ 2️⃣ Local Notification 보내기

void showNotification() async {
  const AndroidNotificationDetails androidPlatformChannelSpecifics =
    AndroidNotificationDetails(
      'your_channel_id',
      'your_channel_name',
      importance: Importance.max,
      priority: Priority.high,
    );

  const NotificationDetails platformChannelSpecifics =
    NotificationDetails(android: androidPlatformChannelSpecifics);

  await flutterLocalNotificationsPlugin.show(
    0,
    '테스트 알림',
    '이것은 Local Notification 예시입니다.',
    platformChannelSpecifics,
  );
}

버튼에 연결해서 테스트해보세요!

---

✅ 3️⃣ Firebase Push Notification (FCM) 연동

Local Notification은 내부 알림.
하지만 서버에서 유저에게 보내려면 Firebase Cloud Messaging (FCM)을 사용합니다.

// pubspec.yaml에 추가
firebase_messaging: ^14.0.0

// Firebase 초기화 예시
void main() async {
  WidgetsFlutterBinding.ensureInitialized();
  await Firebase.initializeApp();

  FirebaseMessaging.onBackgroundMessage(_firebaseMessagingBackgroundHandler);

  runApp(MyApp());
}

Future<void> _firebaseMessagingBackgroundHandler(RemoteMessage message) async {
  await Firebase.initializeApp();
  print("Handling a background message: ${message.messageId}");
}

실행 중 수신 & 표시

FirebaseMessaging.onMessage.listen((RemoteMessage message) {
  print('Got a message whilst in the foreground!');
  print('Message data: ${message.data}');

  if (message.notification != null) {
    print('Message also contained a notification: ${message.notification}');
  }
});

TIP: 실제 푸시 전송은 Firebase Console에서 테스트 가능.

---

✅ 4️⃣ Local Notification + FCM 함께 쓰기

실무에서는 FCM 수신 시 Local Notification으로 직접 표시 처리하는 경우가 많습니다.

FirebaseMessaging.onMessage.listen((RemoteMessage message) {
  RemoteNotification? notification = message.notification;
  AndroidNotification? android = message.notification?.android;

  if (notification != null && android != null) {
    flutterLocalNotificationsPlugin.show(
      notification.hashCode,
      notification.title,
      notification.body,
      const NotificationDetails(
        android: AndroidNotificationDetails(
          'your_channel_id',
          'your_channel_name',
          importance: Importance.max,
          priority: Priority.high,
        ),
      ),
    );
  }
});

---

✅ 5️⃣ 자주 발생하는 에러와 해결법

• 푸시가 수신되는데 표시가 안 됨 → Android 13 이상은 POST_NOTIFICATIONS 권한 필수
• Firebase 초기화 누락 → main()에서 반드시 Firebase.initializeApp() 호출
• 백그라운드 수신 안 됨 → Background Handler 함수 꼭 등록

---

📌 정리

• Local Notification: flutter_local_notifications
• Push Notification: Firebase Messaging
• 실무는 둘을 같이 쓰는 케이스 많음