.
├─ public
│  ├─ index.html                 # PWA 메타 태그, manifest 링크, 아이콘 설정
│  ├─ manifest.json              # PWA 앱 정보(이름, 아이콘, start_url, display 등)
│  ├─ offline.html               # 네트워크 끊겼을 때 보여줄 오프라인 전용 페이지
│  ├─ firebase-messaging-sw.js   # Service Worker: 캐시 + 오프라인 + FCM 백그라운드 알림 처리
│  ├─ icon-192x192.png           # PWA 아이콘 (앱 아이콘/홈 화면용)
│  └─ icon-512x512.png           # PWA 아이콘 (고해상도, 스플래시 등)
│
└─ src
   ├─ notifications
   │  ├─ firebase.ts             # Firebase 앱/메시징 초기화, 권한 요청, 포그라운드 알림 설정
   │  ├─ registerFCMToken.ts     # 발급된 FCM 토큰을 서버 API로 등록하는 모듈
   │  ├─ useNotification.ts      # "알림 받기" 버튼용 훅 (권한 요청 + 토큰 발급 + 서버 등록)
   │  └─ useInitializeFCM.ts     # PWA 실행 시 FCM 초기화 훅 (Service Worker 등록 + 토큰 요청)
   │
   └─ shared
      └─ utils
         └─ firebase.ts          # 공용 Firebase 초기화, Messaging 지원 여부 체크, 토큰/리스너 유틸
 

const token = await getToken(messaging, {
  vapidKey: process.env.FCM_VAPID_KEY,
  serviceWorkerRegistration: registration,
});

await api.post('/push-notifications', {
  deviceEndpoint: token,
});

messaging.onBackgroundMessage((payload) => {
  self.registration.showNotification(title, {
    body,
    icon,
    data: payload.data,
  });
});

self.addEventListener('notificationclick', (event) => {
  const urlToOpen = event.notification.data?.redirectUrl || '/';
  // 이미 열린 탭 포커스 or 새 창 열기
});

{
  "id": "/",
  "name": "Moment",
  "short_name": "Moment",
  "description": "매일의 소중한 순간을 기록하고 공유하는 플랫폼",
  "start_url": "/",
  "scope": "/",
  "display": "standalone",
  "theme_color": "#0a0a0f",
  "background_color": "#0a0a0f",
  "orientation": "portrait",
  "gcm_sender_id": "138468882061",
  "icons": [
    {
      "src": "/icon-192x192.png",
      "sizes": "192x192",
      "type": "image/png",
      "purpose": "any"
    },
    {
      "src": "/icon-512x512.png",
      "sizes": "512x512",
      "type": "image/png",
      "purpose": "any"
    },
    {
      "src": "/icon-192x192.png",
      "sizes": "192x192",
      "type": "image/png",
      "purpose": "maskable"
    },
    {
      "src": "/icon-512x512.png",
      "sizes": "512x512",
      "type": "image/png",
      "purpose": "maskable"
    }
  ]
}

<link rel="manifest" href="/manifest.json" crossorigin="use-credentials" />
<meta name="theme-color" content="#0a0a0f" />
<meta name="apple-mobile-web-app-capable" content="yes" />
<meta name="apple-mobile-web-app-status-bar-style" content="black-translucent" />
<meta name="apple-mobile-web-app-title" content="Moment" />
<meta name="mobile-web-app-capable" content="yes" />
<link rel="icon" sizes="192x192" href="/icon-192x192.png" />
<link rel="apple-touch-icon" sizes="192x192" href="/icon-192x192.png" />
<link rel="apple-touch-icon" sizes="512x512" href="/icon-512x512.png" />

const CACHE_NAME = 'moment-cache-v1';
const urlsToCache = ['/manifest.json', '/icon-192x192.png', '/icon-512x512.png', '/offline.html'];
 
self.addEventListener('install', (event) => {
  event.waitUntil(
    caches
      .open(CACHE_NAME)
      .then((cache) => cache.addAll(urlsToCache))
      .then(() => self.skipWaiting()),
  );
});
 
self.addEventListener('activate', (event) => {
  event.waitUntil(self.clients.claim());
});

self.addEventListener('fetch', (event) => {
  // API 요청 및 외부 도메인은 캐싱 X
  if (
    event.request.url.includes('api.connectingmoment.com') ||
    !event.request.url.startsWith(self.location.origin)
  ) {
    return;
  }
 
  // SPA 라우팅: 페이지 전환(navigate) 요청은 네트워크 실패 시 offline.html로 대체
  if (event.request.mode === 'navigate') {
    event.respondWith(fetch(event.request).catch(() => caches.match('/offline.html')));
  } else {
    // 정적 리소스: 캐시 우선, 없으면 네트워크
    event.respondWith(
      caches.match(event.request).then((response) => response || fetch(event.request)),
    );
  }
});

<h1>인터넷 연결이 끊어졌습니다</h1>
<p>네트워크 연결을 확인한 뒤 다시 시도해 주세요.</p>
<button onclick="window.location.reload()">다시 시도</button>

messaging.onBackgroundMessage((payload) => {
  const notificationTitle = payload.notification?.title || '새 알림';
 
  const notificationOptions = {
    body: payload.notification?.body || '내용 없음',
    icon: '/icon-512x512.png',
    data: payload.data,
    tag: payload.data.eventId || 'default',
    requireInteraction: true,
    renotify: false,
  };
 
  self.registration.showNotification(notificationTitle, notificationOptions);
});

self.addEventListener('notificationclick', (event) => {
  event.notification.close();
  const urlToOpen = event.notification.data?.redirectUrl || '/';
 
  event.waitUntil(
    clients.matchAll({ type: 'window' }).then((clientList) => {
      for (const client of clientList) {
        if (client.url.startsWith(self.location.origin)) {
          client.navigate(urlToOpen);
          return client.focus();
        }
      }
 
      if (clients.openWindow) {
        return clients.openWindow(urlToOpen);
      }
    }),
  );
});

// src/shared/utils/firebase.ts
import { getApps, initializeApp } from 'firebase/app';
import { getMessaging, getToken, isSupported, Messaging, onMessage } from 'firebase/messaging';
 
const firebaseConfig = {
  /* Firebase 콘솔에서 발급받은 설정 */
};
 
const app = getApps().length ? getApps()[0] : initializeApp(firebaseConfig);
 
let messagingPromise: Promise<Messaging | null> | null = null;
 
export const getMessagingIfSupported = (): Promise<Messaging | null> => {
  if (messagingPromise) return messagingPromise;
 
  messagingPromise = (async () => {
    if (typeof window === 'undefined') return null;
    const supported = await isSupported().catch(() => false);
    if (!supported) return null;
    return getMessaging(app);
  })();
 
  return messagingPromise;
};

export const requestFCMPermissionAndToken = async (): Promise<string | null> => {
  if (typeof window === 'undefined') return null;
 
  const permission = await Notification.requestPermission();
  if (permission !== 'granted') {
    console.warn('[FCM] 알림 권한이 거부되었습니다.');
    return null;
  }
 
  const messaging = await getMessagingIfSupported();
  if (!messaging) {
    console.warn('[FCM] Messaging을 지원하지 않습니다.');
    return null;
  }
 
  const registration = await navigator.serviceWorker.ready;
 
  const token = await getToken(messaging, {
    vapidKey: process.env.FCM_VAPID_KEY,
    serviceWorkerRegistration: registration,
  });
 
  return token ?? null;
};

// src/notifications/registerFCMToken.ts
import { api } from '@/app/lib/api';
 
export const registerFCMToken = async (registrationToken: string) => {
  return await api.post<void>('/push-notifications', {
    deviceEndpoint: registrationToken,
  });
};

// src/notifications/useNotification.ts
export const useNotification = () => {
  const [permission, setPermission] = useState<NotificationPermission>('default');
  const [isLoading, setIsLoading] = useState(false);
 
  const handleNotificationClick = () => {
    return new Promise<boolean>((resolve) => {
      if (permission === 'granted') {
        alert('이미 알림을 받고 있습니다.');
        resolve(true);
        return;
      }
 
      setIsLoading(true);
 
      Notification.requestPermission()
        .then(async (permissionResult) => {
          setPermission(permissionResult);
 
          if (permissionResult === 'granted') {
            try {
              await navigator.serviceWorker.register('/firebase-messaging-sw.js');
 
              const messagingInstance = await getMessagingInstance();
              const token = await getToken(messagingInstance, {
                vapidKey: process.env.FCM_VAPID_KEY,
              });
 
              if (token) {
                await registerFCMToken(token);
                alert('알림 설정이 완료되었습니다.');
                resolve(true);
              } else {
                alert('알림 설정에 실패했습니다.');
                resolve(false);
              }
            } catch (error) {
              Sentry.captureException(error);
              alert('알림 설정에 실패했습니다.');
              resolve(false);
            }
          }
        })
        .catch(() => {
          resolve(false);
        })
        .finally(() => {
          setIsLoading(false);
        });
    });
  };
 
  useEffect(() => {
    if ('Notification' in window) {
      setPermission(Notification.permission);
    }
  }, []);
 
  return { permission, isLoading, handleNotificationClick };
};

const { permission, isLoading, handleNotificationClick } = useNotification();
 
// ...
<button disabled={isLoading} onClick={() => handleNotificationClick()}>
  {permission === 'granted' ? '알림 설정 완료' : '알림 받기'}
</button>;

// src/notifications/useInitializeFCM.ts
import { isDevice, isPWA } from '../utils/device';
import { requestFCMPermission, setupForegroundMessage } from './firebase';
 
export const useInitializeFCM = () => {
  useEffect(() => {
    const initializeFCM = async () => {
      if (!('serviceWorker' in navigator) || (isDevice() && !isPWA())) return;
 
      try {
        await navigator.serviceWorker.register('/firebase-messaging-sw.js');
        const token = await requestFCMPermission();
 
        if (token) {
          await setupForegroundMessage();
        }
      } catch (error) {
        Sentry.captureException(error);
      }
    };
 
    initializeFCM();
  }, []);
};

 ┌───────────────────────────────────────────────────────────┐
 │                        백엔드 서버                        │
 │   - 댓글 생성, 알림 이벤트 발생                           │
 │   - 유저 ↔ FCM 토큰 매핑 저장                            │
 │   - FCM API 호출 (이 토큰들에 푸시 보내줘)               │
 └───────────────▲───────────────────────────────────────────┘
                 │
                 │ (푸시 요청)
                 │
 ┌───────────────┴───────────────────────────────────────────┐
 │                  Firebase Cloud Messaging                 │
 │   - 서버에서 받은 요청 기반으로                           │
 │   - 각 브라우저/디바이스로 Web Push 전달                  │
 └───────────────▲───────────────────────────────────────────┘
                 │ (Web Push)
                 │
        ┌────────┴────────┐
        │                 │
        │                 │
┌───────┴─────────────────▼──────────────────────────────────┐
│         Service Worker (firebase-messaging-sw.js)          │
│                                                            │
│  [푸시 관련]                                               │
│    - onBackgroundMessage(payload)                          │
│    - showNotification(title, options)                      │
│    - notificationclick → redirectUrl로 탭 이동/새 창 열기  │
│                                                            │
│  [네트워크/오프라인 관련]                                   │
│    - install: offline.html, manifest, icon 캐싱           │
│    - fetch:                                                │
│        · API/외부 도메인 → 그냥 네트워크                   │
│        · navigate 요청 → 네트워크 실패 시 offline.html     │
│        · 정적 리소스 → 캐시 우선, 없으면 네트워크          │
└───────▲─────────────────▲──────────────────────────────────┘
        │                 │
        │                 │ (알림 클릭 시 탭 포커스/오픈)
        │                 │
┌───────┴─────────────────┴──────────────────────────────────┐
│                 브라우저 / PWA (React 앱)                  │
│                                                            │
│  - index.html                                              │
│      · manifest.json 링크                                  │
│      · PWA 메타 태그 (theme-color, apple-* 등)             │
│                                                            │
│  - manifest.json                                           │
│      · name, short_name, icons, display=standalone         │
│      · gcm_sender_id (FCM 연동 정보)                       │
│                                                            │
│  - React 코드                                              │
│      · useNotification()                                   │
│          · Notification.requestPermission()                │
│          · getToken(messaging, VAPID)                      │
│          · /push-notifications 로 토큰 서버 전송           │
│      · useInitializeFCM()                                  │
│          · Service Worker 등록                             │
│          · PWA 환경에서 FCM 초기화                         │
└───────▲────────────────────────────────────────────────────┘
        │
        │ (화면/알림 UI)
        │
┌───────┴────────────────────────────────────────────────────┐
│                         사용자                             │
│  - 브라우저로 접속                                        │
│  - 홈 화면에 설치(PWA)                                    │
│  - "알림 받기" 동의                                       │
│  - OS 알림(상태바/잠금화면/알림센터) 확인                 │
│  - 알림 클릭 → 바로 해당 Moment 상세 화면                 │
└────────────────────────────────────────────────────────────┘