로그인, 데이터 저장, 푸시 알림이 필요한 앱을 만들려면 보통 서버를 직접 만들어야 한다. Firebase는 이 세 가지를 서버 없이 빌려 쓰게 해준다. 이 글은 Flutter에서 Firebase의 Authentication(로그인), Cloud Firestore(데이터베이스), Cloud Messaging(푸시)을 연결하는 법을 다룬다. 먼저 설정을 건너뛰고 로그인부터 써보면 어떻게 되는지 보자.

import 'package:firebase_auth/firebase_auth.dart';

Future<void> main() async {
  runApp(const MyApp());
}

// 어딘가에서
final user = FirebaseAuth.instance.currentUser; // 여기서 에러남

앱이 시작되자마자 이런 에러가 난다.

[core/no-app] No Firebase App '[DEFAULT]' has been created - call Firebase.initializeApp()

패키지를 설치했는데도 에러가 나는 건, 내 앱이 어느 Firebase 프로젝트에 연결되는지 아직 앱에 알려주지 않았기 때문이다.

원인: 앱과 Firebase 프로젝트를 이어주는 설정이 없다

Firebase를 쓰려면 Firebase 콘솔에서 만든 프로젝트 정보(앱 ID, API 키 등)가 앱에 들어 있어야 한다. 예전에는 Android용 google-services.json, iOS용 GoogleService-Info.plist를 손으로 내려받아 넣었는데, 지금은 FlutterFire CLI가 이 과정을 자동으로 해준다.

1단계: 프로젝트 연결하기

Firebase 콘솔에서 프로젝트를 하나 만들고, 터미널에서 순서대로 한다.

firebase login
dart pub global activate flutterfire_cli
flutterfire configure

• firebase login: Google 계정으로 Firebase에 로그인한다
• flutterfire_cli 설치: Firebase 설정을 대신 해주는 도구다
• flutterfire configure: 프로젝트를 고르면, 선택한 플랫폼(Android, iOS 등)마다 Firebase 앱을 만들고 lib/firebase_options.dart 파일을 생성한다. 플랫폼별 키가 이 파일에 모여 있다

그다음 Firebase 코어와 쓰려는 기능의 플러그인을 설치한다.

flutter pub add firebase_core firebase_auth cloud_firestore firebase_messaging

기능마다 플러그인이 하나씩이다. Authentication은 firebase_auth, Firestore는 cloud_firestore, Cloud Messaging은 firebase_messaging이다. 플러그인을 추가한 뒤에는 flutterfire configure를 다시 실행해서 설정을 최신으로 맞춰주는 게 안전하다.

2단계: main에서 초기화

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

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

로컬 저장소 글에서 본 패턴 그대로다. main을 async로 바꾸고, 플러그인을 쓰기 전에 WidgetsFlutterBinding.ensureInitialized()를 부른 뒤, await로 초기화가 끝나길 기다린다. DefaultFirebaseOptions.currentPlatform은 지금 실행 중인 플랫폼에 맞는 키를 골라준다. 이제 [core/no-app] 에러가 사라진다.

Authentication: 이메일로 로그인하기

Firebase 콘솔의 Authentication 메뉴에서 로그인 방법(이메일/비밀번호)을 켜야 한다. 켜지 않으면 operation-not-allowed 에러가 난다.

import 'package:firebase_auth/firebase_auth.dart';

final auth = FirebaseAuth.instance;

// 회원가입
await auth.createUserWithEmailAndPassword(email: email, password: password);

// 로그인
await auth.signInWithEmailAndPassword(email: email, password: password);

// 로그아웃
await auth.signOut();

로그인 상태가 바뀔 때마다 알려주는 Stream도 있다.

auth.authStateChanges() // Stream<User?>, 로그인하면 User, 로그아웃하면 null

비동기 UI 글에서 배운 StreamBuilder에 연결하면 로그인 여부에 따라 화면이 알아서 바뀐다.

StreamBuilder<User?>(
  stream: FirebaseAuth.instance.authStateChanges(),
  builder: (context, snapshot) {
    if (snapshot.hasData) return const HomePage();   // 로그인됨
    return const LoginPage();                         // 로그인 안 됨
  },
)

화면 이동 글의 go_router redirect에서 같은 상태를 보고 로그인 화면으로 보낼 수도 있다.

실패하면 FirebaseAuthException이 던져지고 e.code로 이유를 구분한다.

try {
  await auth.signInWithEmailAndPassword(email: email, password: password);
} on FirebaseAuthException catch (e) {
  final message = switch (e.code) {
    'invalid-credential' || 'wrong-password' || 'user-not-found' =>
      '이메일이나 비밀번호가 맞지 않아요',
    'email-already-in-use' => '이미 가입된 이메일이에요',
    'weak-password' => '비밀번호가 너무 짧아요',
    _ => '로그인에 실패했어요 (${e.code})',
  };
  // 에러 처리 글처럼 사용자에게 보여준다
}

로그인 실패의 code가 wrong-password, user-not-found, invalid-credential 중 어느 것으로 오는지는 프로젝트 설정과 버전에 따라 달라질 수 있어서, 위처럼 묶어서 처리하는 게 안전하다.

Firestore: 데이터 저장과 읽기

Firestore는 컬렉션(폴더) 안에 문서(Map 하나)가 쌓이는 데이터베이스다. 표가 아니라 JSON 같은 문서를 저장한다.

import 'package:cloud_firestore/cloud_firestore.dart';

final db = FirebaseFirestore.instance;

// 추가 (id는 자동 생성)
await db.collection('todos').add({'title': '우유 사기', 'done': false});

// 한 번 읽기
final snapshot = await db.collection('todos').get();
for (final doc in snapshot.docs) {
  print('${doc.id}: ${doc.data()}'); // data()는 Map<String, dynamic>
}

// 수정, 삭제
await db.collection('todos').doc(id).update({'done': true});
await db.collection('todos').doc(id).delete();

doc.data()가 Map<String, dynamic>이니, JSON 직렬화 글에서 만든 fromJson으로 모델로 바꿔 쓴다. 조건과 정렬도 된다.

db.collection('todos')
    .where('done', isEqualTo: false)
    .orderBy('title')
    .get();

로컬 저장소 글의 drift watch()처럼, Firestore도 값이 바뀔 때마다 새 목록을 흘려보내는 Stream이 있다.

StreamBuilder<QuerySnapshot<Map<String, dynamic>>>(
  stream: db.collection('todos').snapshots(),
  builder: (context, snapshot) {
    if (!snapshot.hasData) return const CircularProgressIndicator();
    final docs = snapshot.data!.docs;
    return ListView.builder(
      itemCount: docs.length,
      itemBuilder: (context, i) => ListTile(title: Text(docs[i]['title'])),
    );
  },
)

다른 기기에서 데이터를 추가해도 이 화면의 목록이 실시간으로 갱신된다. 이게 Firestore를 쓰는 큰 이유다.

삽질 포인트: permission-denied

코드는 맞는데 읽기나 쓰기가 permission-denied로 거부되는 경우가 가장 흔하다. Firestore는 콘솔의 보안 규칙으로 누가 읽고 쓸 수 있는지를 정한다. 개발 초기에 "테스트 모드"로 시작하면 모두에게 열려 있지만, 이 규칙은 기간이 지나면 만료되어 갑자기 모든 요청이 막힌다. 앱을 배포하기 전에는 request.auth != null처럼 로그인한 사용자만 허용하는 규칙으로 바꿔야 한다. 규칙 없이 열어둔 채로 두면 누구나 데이터를 읽고 지울 수 있다.

또 Firestore는 문서를 읽은 횟수로 비용이 매겨진다. snapshots()로 큰 컬렉션 전체를 구독하면 읽기 횟수가 불어나니, 필요한 만큼만 where, limit으로 줄여서 읽는다.

Cloud Messaging: 푸시 알림

import 'package:firebase_messaging/firebase_messaging.dart';

final messaging = FirebaseMessaging.instance;

// 알림 권한 요청 (iOS, 안드로이드 13 이상)
await messaging.requestPermission();

// 이 기기를 가리키는 토큰. 서버가 이 토큰으로 푸시를 보낸다
final token = await messaging.getToken();
print('FCM 토큰: $token');

앱이 켜져 있을 때 들어온 메시지는 Stream으로 받는다.

FirebaseMessaging.onMessage.listen((RemoteMessage message) {
  print('받음: ${message.notification?.title}');
});

앱이 꺼져 있을 때 알림을 눌러서 앱이 열리면 FirebaseMessaging.onMessageOpenedApp으로 받는다. 앱이 백그라운드에 있을 때 데이터를 처리하려면 핸들러를 따로 등록한다.

@pragma('vm:entry-point')
Future<void> _backgroundHandler(RemoteMessage message) async {
  await Firebase.initializeApp(options: DefaultFirebaseOptions.currentPlatform);
  print('백그라운드 메시지: ${message.messageId}');
}

Future<void> main() async {
  WidgetsFlutterBinding.ensureInitialized();
  await Firebase.initializeApp(options: DefaultFirebaseOptions.currentPlatform);
  FirebaseMessaging.onBackgroundMessage(_backgroundHandler);
  runApp(const MyApp());
}

핸들러는 클래스 안이 아니라 최상위 함수여야 한다. 앱과 별개의 환경에서 실행되기 때문에, 그 안에서 Firebase를 다시 초기화해야 한다. @pragma('vm:entry-point')는 릴리스 빌드에서 이 함수가 "안 쓰는 코드"로 지워지지 않게 하는 표시다.

삽질 포인트: 푸시가 안 온다

• iOS 시뮬레이터에서는 푸시를 받을 수 없다. 실제 기기가 필요하고, Apple 개발자 계정에서 만든 APNs 인증 키를 Firebase 콘솔에 등록해야 한다
• 안드로이드에서 앱이 켜져 있을 땐 알림이 화면에 자동으로 뜨지 않는다. onMessage로 받아서 직접 보여줘야 한다(보통 로컬 알림 패키지를 같이 쓴다). 앱이 꺼져 있거나 백그라운드일 때는 시스템이 알림을 띄워준다
• 토큰은 앱을 지웠다 다시 설치하는 등으로 바뀔 수 있어서, 서버에 저장한 토큰은 주기적으로 갱신해야 한다

계층 구조에서의 위치

Firebase 호출도 앞에서 배운 Service 계층에 둔다. 화면이 FirebaseFirestore.instance를 직접 부르는 건 화면이 서버를 직접 부르는 코드와 같다. TodoService가 Firestore를 감싸고, TodoRepository가 모델로 바꾸고, ViewModel이 화면용 상태로 만든다. 그러면 시험에서는 Firestore 대신 가짜 Repository를 끼울 수 있다.

Android, iOS와 비교하면

// Kotlin - Firebase Android SDK
val auth = Firebase.auth
auth.signInWithEmailAndPassword(email, password).await()
Firebase.firestore.collection("todos").snapshots() // Flow

// Swift - Firebase iOS SDK
try await Auth.auth().signIn(withEmail: email, password: password)
let snapshot = try await Firestore.firestore().collection("todos").getDocuments()

• 초기 설정: Flutter flutterfire configure와 Firebase.initializeApp / Android google-services.json과 Gradle 플러그인 / iOS GoogleService-Info.plist
• 로그인 상태: Flutter authStateChanges() Stream / Android AuthStateListener나 Flow / iOS addStateDidChangeListener
• 실시간 데이터: Flutter snapshots() Stream / Android snapshots() Flow / iOS addSnapshotListener
• 푸시: 세 곳 모두 같은 FCM이고, iOS는 APNs 키가 필요

세 플랫폼이 같은 Firebase 프로젝트를 쓰므로, 이미 만든 Kotlin이나 Swift 앱과 데이터와 사용자를 공유할 수도 있다. Flutter가 다른 점은 Stream과 await 같은 Dart의 도구로 같은 일을 표현한다는 것뿐이다.

정리

• 설정 없이 Firebase를 부르면 [core/no-app] 에러가 나므로, flutterfire configure로 firebase_options.dart를 만들고 main에서 Firebase.initializeApp(options: ...)을 await한다
• Firebase는 기능마다 플러그인이 하나씩이고 (firebase_auth, cloud_firestore, firebase_messaging), main에서 WidgetsFlutterBinding.ensureInitialized()가 먼저 필요하다
• 로그인은 콘솔에서 로그인 방법을 켜고 signInWithEmailAndPassword를 쓰며, authStateChanges()를 StreamBuilder에 연결하면 로그인 여부로 화면이 바뀐다. 실패는 FirebaseAuthException의 code로 구분한다
• Firestore는 컬렉션과 문서에 Map을 저장하고 snapshots()로 실시간 Stream을 받으며, 데이터는 fromJson으로 모델로 바꾼다
• permission-denied는 대개 보안 규칙 문제이고, 테스트 모드 규칙은 만료되므로 배포 전에 로그인한 사용자만 허용하는 규칙으로 바꾼다
• 푸시는 requestPermission, getToken, onMessage, 최상위 함수 onBackgroundMessage로 다루고, iOS는 실제 기기와 APNs 키가 필요하다
• Firebase 호출은 Service 계층에 두어서 화면과 분리한다

다음 글에서는 앱이 느려질 때 어디를 고쳐야 하는지, 성능 최적화(const, RepaintBoundary, DevTools)를 다뤄보겠다.