Flutter 푸시 알림 FCM 연동하다 막혔던 부분과 해결법

Flutter로 푸시 알림을 연동하다가 생각보다 삽질을 많이 했어요. 특히 FCM이 뭔지, 어떻게 설정하는지 막연했던 초보 입장에서 이 부분이 너무 헷갈리더라고요.

이 글에서 Flutter 앱에 Firebase Cloud Messaging(FCM)을 붙이고, 푸시 알림을 받기까지 제가 겪은 삽질과 해결 과정을 진짜 솔직하게 공유할게요. 용어가 생소한 분도 이해할 수 있게 최대한 쉽게 설명해봤어요.

개발 환경 / 버전 정보

제가 사용한 주요 환경은 Flutter 3.7.0이고, Firebase는 프로젝트 생성 시 최신 버전 기준으로 설정했어요. Android Studio에서 개발했고, Android 13 기기와 iOS 16 시뮬레이터에서 테스트했습니다.

FCM이 대체 뭔지부터 알았어요

사실 이 부분이 제일 막막했는데 FCM은 Firebase Cloud Messaging의 줄임말이에요. 쉽게 말하면 구글이 제공하는 무료 푸시 알림 서비스인 거죠. Flutter 앱에 FCM을 연동하면 나중에 서버에서 메시지 보내면 앱에서 푸시 알림을 받을 수 있어요.

저도 처음엔 "푸시 알림을 왜 이렇게 복잡하게 설정하지?" 싶었는데, 한번 Firebase 프로젝트와 앱 설정만 제대로 해놓으면 나중에 메시지 보내기는 의외로 간단해지더라고요.

Flutter FCM 연동 이렇게 하면 됩니다

FCM을 연결하려면 크게 세 가지를 해야 해요. Firebase 프로젝트 만들기, 앱에 Firebase 설정값 넣기, Flutter 앱에서 firebase_messaging 패키지로 메시지 받기 설정하기. 하나씩 설명할게요.

// pubspec.yaml에 firebase_messaging 추가하기
dependencies:
  flutter:
    sdk: flutter
  firebase_core: ^2.2.0
  firebase_messaging: ^14.2.1

firebase_core 패키지는 Firebase 기능을 Flutter 프로젝트에 초기화할 때 꼭 필요한 기본 패키지고, firebase_messaging이 FCM에 특화된 패키지예요.

// main.dart 예시
import 'package:flutter/material.dart';
import 'package:firebase_core/firebase_core.dart';
import 'package:firebase_messaging/firebase_messaging.dart';

void main() async {
  WidgetsFlutterBinding.ensureInitialized();
  await Firebase.initializeApp();
  runApp(MyApp());
}

class MyApp extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      home: Scaffold(
        appBar: AppBar(title: Text('FCM 테스트')),
        body: Center(
          child: Text('푸시 알림 준비 완료!'),
        ),
      ),
    );
  }
}

Firebase.initializeApp()이 없으면 당연히 FCM 못 받아요. 그래서 main 함수가 async인 것도 꼭 기억하세요!

막혔던 부분: Android, iOS 설정이 완전 달랐어요

그런데 여기서 막혔던 게 Android와 iOS 설정이 너무 달라서 헷갈렸어요. Android는 구글 서비스 json 파일 넣고, iOS는 APNs 인증서 등록 등 별도의 절차가 있었거든요.

특히 iOS가 처음엔 "푸시 알림이 안 와요" 하면서 한 3시간 삽질했는데, 원인은 Xcode에서 Capabilities 탭에 들어가서 푸시알림 권한을 직접 켜줘야 했기 때문이에요.

푸시 권한 요청은 이렇게 하시면 돼요

Flutter에서 iOS와 Android 둘 다 사용자에게 푸시 수신 권한을 물어봐야 하는데, firebase_messaging 패키지로 쉽게 처리할 수 있어요. 권한을 받지 않으면 알림이 안 옵니다.

FirebaseMessaging messaging = FirebaseMessaging.instance;

// 권한 요청
NotificationSettings settings = await messaging.requestPermission(
  alert: true,
  badge: true,
  sound: true,
);

if (settings.authorizationStatus == AuthorizationStatus.authorized) {
  print('사용자가 푸시 권한을 허용했어요');
} else if (settings.authorizationStatus == AuthorizationStatus.denied) {
  print('푸시 권한 거부됨');
}

이 코드를 앱 처음 실행 시점에 넣으면 권한 팝업이 뜨고, 사용자가 허용해야 정상적으로 푸시 알림이 옵니다.

푸시 토큰 확인과 메시지 수신 테스트

알림을 받으려면 Firebase에서 발급하는 디바이스 토큰이 필요해요. 이 토큰으로 특정 기기에 메시지를 보낼 수 있거든요.

아래처럼 토큰을 확인할 수 있는데, 제일 처음에 토큰이 잘 나오는지 로그 꼭 찍어보세요.

String? token = await FirebaseMessaging.instance.getToken();
print('FCM 토큰: $token');

이 토큰을 Firebase 콘솔이나 서버에 입력해야 메시지를 보낼 수 있어요.

메시지 받는 방법도 간단한데 조건이 있어요

앱이 켜져 있을 때 수신하려면 onMessage 이벤트를 처리하면 돼요. 이 부분도 firebase_messaging에서 제공하는 API로 할 수 있습니다.

FirebaseMessaging.onMessage.listen((RemoteMessage message) {
  print('Foreground 메시지 도착: ${message.messageId}');
  if (message.notification != null) {
    print('알림 제목: ${message.notification!.title}');
    print('알림 내용: ${message.notification!.body}');
  }
});

이렇게 하면 앱이 포그라운드(앞에 있을 때)에서 메시지를 받을 수 있어요. 백그라운드에서는 시스템 화면에 자동으로 알림이 표시되고, 사용자가 누르면 앱이 켜지면서 onMessageOpenedApp 이벤트로 처리할 수 있어요.

여기서 삽질했던 부분들

실제로 막혔던 에러 중 하나는 iOS 시뮬레이터에서는 푸시 알림이 절대 안 온다는 사실이었어요. 그래서 한참 원인을 찾다가 "시뮬레이터는 푸시를 지원하지 않는다"는 걸 알게 됐죠. 이거 안 알아서 시간 꽤 날렸어요.

// iOS 시뮬레이터에서는 아래와 같은 메시지만 뜰 뿐
// 실제 푸시 알림은 수신 불가

또 한 가지는 AndroidManifest.xml에 권한 설정을 안 해서 푸시가 안 오던 경우였어요. 아래 권한이 꼭 들어가 있어야 해요.

<uses-permission android:name="android.permission.INTERNET" />
<uses-permission android:name="android.permission.WAKE_LOCK" />
<uses-permission android:name="com.google.android.c2dm.permission.RECEIVE" />

이 부분을 빼먹으면 FCM 연동이 제대로 안 됩니다.

심화: 백그라운드 메시지는 이렇게 처리해요

FCM에서 백그라운드 상태에서 메시지를 받으려면 별도로 백그라운드 핸들러를 등록해야 해요. 이것도 처음엔 "이게 왜 필요하지?" 싶었는데, 직접 구현해보니 앱이 꺼져있는 상태에서 메시지를 받아야 하니까 당연한 것 같더라고요.

// 백그라운드 메시지 핸들러 함수
Future _firebaseMessagingBackgroundHandler(RemoteMessage message) async {
  print('백그라운드 메시지 수신: ${message.messageId}');
}

// main 함수 내 등록
FirebaseMessaging.onBackgroundMessage(_firebaseMessagingBackgroundHandler);

이렇게 하면 앱이 백그라운드에 있을 때 푸시 알림이 와도 작업 처리가 가능해져요.

자주 물어보시는 것들

Q. Flutter FCM 설정 후에도 알림이 안 오면 어디부터 확인할까요?

A. 가장 먼저 토큰이 정상적으로 출력되는지 로그부터 확인하세요. 그리고 권한요청, Android/iOS 설정도 꼼꼼히 살펴보고, Firebase 콘솔에서 테스트 메시지를 직접 보내보는 게 좋아요.

Q. iOS 시뮬레이터에서 푸시 알림 받을 수 있을까요?

A. 안타깝지만 안 됩니다. 실제 기기에서만 가능하니 꼭 기기로 테스트하세요!

Flutter에서 FCM 연동은 조금 낯설고 복잡해 보이지만, 한번 알고 나니까 오히려 서버에서 푸시 보내는 건 간단하더라고요. 이 글에서 공유한 팁들로 막힘없이 진행하시길 바랍니다.