웹앱 푸시 알림 구현 완벽 가이드

1

라이브러리 설치

NPM을 사용하여 Flutter Bridge FCM 라이브러리와 Firebase SDK를 설치합니다.

npm install @fluttervuebridge/notifications firebase

또는 CDN을 사용할 수도 있습니다:

<!-- Firebase SDK -->
<script src="https://www.gstatic.com/firebasejs/10.7.1/firebase-app-compat.js"></script>
<script src="https://www.gstatic.com/firebasejs/10.7.1/firebase-messaging-compat.js"></script>

<!-- Flutter Bridge FCM -->
<script src="https://cdn.jsdelivr.net/npm/@fluttervuebridge/notifications@latest/dist/flutter-bridge-fcm.js"></script>
          

2

Firebase 프로젝트 설정

Firebase 콘솔에서 프로젝트를 생성하고 웹 앱을 등록합니다. Cloud Messaging에서 VAPID 키를 생성합니다.

// .env 파일
VITE_FIREBASE_API_KEY=your_api_key
VITE_FIREBASE_AUTH_DOMAIN=your_project.firebaseapp.com
VITE_FIREBASE_PROJECT_ID=your_project_id
VITE_FIREBASE_STORAGE_BUCKET=your_project.appspot.com
VITE_FIREBASE_MESSAGING_SENDER_ID=your_sender_id
VITE_FIREBASE_APP_ID=your_app_id
VITE_FIREBASE_VAPID_KEY=your_vapid_key
          

3

Service Worker 생성

푸시 알림을 백그라운드에서 받기 위해 Service Worker 파일을 생성합니다.

// public/firebase-messaging-sw.js
importScripts('https://www.gstatic.com/firebasejs/10.7.1/firebase-app-compat.js');
importScripts('https://www.gstatic.com/firebasejs/10.7.1/firebase-messaging-compat.js');

firebase.initializeApp({
  apiKey: "your_api_key",
  projectId: "your_project_id",
  messagingSenderId: "your_sender_id",
  appId: "your_app_id"
});

const messaging = firebase.messaging();

messaging.onBackgroundMessage((payload) => {
  console.log('Background message:', payload);
  const notificationTitle = payload.notification.title;
  const notificationOptions = {
    body: payload.notification.body,
    icon: payload.notification.icon
  };
  self.registration.showNotification(notificationTitle, notificationOptions);
});
          

4

서비스 초기화 및 권한 요청

애플리케이션에서 알림 서비스를 초기화하고 사용자에게 권한을 요청합니다.

import { getNotificationService } from '@fluttervuebridge/notifications';

// Firebase 설정
window.firebaseConfig = {
  apiKey: process.env.VITE_FIREBASE_API_KEY,
  authDomain: process.env.VITE_FIREBASE_AUTH_DOMAIN,
  projectId: process.env.VITE_FIREBASE_PROJECT_ID,
  storageBucket: process.env.VITE_FIREBASE_STORAGE_BUCKET,
  messagingSenderId: process.env.VITE_FIREBASE_MESSAGING_SENDER_ID,
  appId: process.env.VITE_FIREBASE_APP_ID,
  vapidKey: process.env.VITE_FIREBASE_VAPID_KEY
};

// 서비스 초기화
const service = getNotificationService();
await service.initialize();

// 권한 요청
const permission = await service.requestPermission();
if (permission === 'granted') {
  console.log('알림 권한이 승인되었습니다!');
}
          

5

FCM 토큰 발급 및 서버 등록

FCM 토큰을 발급받고 서버에 등록하여 개인별 푸시를 준비합니다.

// FCM 토큰 발급
const token = await service.getToken();
console.log('FCM Token:', token);

// 사용자별 토큰 등록 (서버 API 호출)
await service.registerUserToken('user123', 'https://your-server.com/api');

// 또는 직접 서버에 전송
await fetch('/api/fcm/register', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ userId: 'user123', token })
});
          

6

메시지 수신 리스너 등록

Foreground에서 푸시 메시지를 수신했을 때의 동작을 정의합니다.

// Foreground 메시지 수신
service.onMessageReceived((message) => {
  console.log('메시지 수신:', message);
  
  // 알림 표시
  service.showNotification({
    title: message.notification.title,
    body: message.notification.body,
    imageUrl: message.notification.imageUrl,
    clickAction: '/notifications'
  });
});

// 알림 클릭 이벤트
service.onNotificationTapped((payload) => {
  console.log('알림 클릭:', payload);
  // 특정 페이지로 이동
  window.location.href = payload.clickAction;
});
          

7

선택사항: 토픽 구독

특정 주제나 카테고리별로 알림을 받고 싶다면 토픽을 구독합니다.

// 토픽 구독 (서버 구현 필요)
await service.subscribeTopic('news');
await service.subscribeTopic('promotions');

// 구독 해제
await service.unsubscribeTopic('news');
          

⚠️ 토픽 구독은 서버에서 FCM Admin SDK를 사용하여 처리해야 합니다.

기능	Flutter WebView	웹 브라우저
사용 라이브러리	flutter-bridge.js (13KB)	flutter-bridge-fcm.js (50KB+)
FCM 처리 주체	Flutter 앱	웹 자체
Firebase SDK 필요	✗	✓
개인별 푸시	✓ (Flutter 경유)	✓ (직접)
토픽 구독	✓ (Flutter 경유)	✓ (직접)
Foreground 푸시	✓	✓
Background 푸시	✓	✓ (Service Worker)

🔔 웹앱 푸시 알림 구현 완벽 가이드

✨ 주요 기능

쉬운 설정

개인별 푸시

토픽 구독

크로스 플랫폼

실시간 푸시

Framework 독립적

📋 구현 단계