웹 푸시 알림 삽질기: Firebase FCM 적용 중 알림이 안 뜰 때 해결법

지난 글 [웹에서 Firebase Cloud Messaging(FCM) 푸시 알림 적용하기]에서는 기본 세팅(프로젝트 설정, VAPID 키, 토큰 발급 등)까지 정리했었다.
“여기까지 하면 바로 알림 오겠지~” 하고 신나게 테스트했는데…

 

👉 로그는 찍히는데 알림이 안 뜨는 사태 발생 😱

 

이번 글은 그때 했던 삽질 기록 + 해결 팁을 남겨둔다.
혹시 저처럼 똑같이 헤매는 분들께 도움이 되길 🙏

 

---

1. 문제 상황

• 서비스워커 등록은 잘 됐음 → DevTools에서도 Activated 확인
• 푸시 이벤트도 들어옴 → 콘솔에 [SW] Push Received: 로그 찍힘

 

근데 알림 UI는 전혀 안 뜸…

 

“이게 뭐야? 푸시 이벤트는 잡히는데 정작 사용자한테는 아무 것도 안 보이네?”

 

---

2. 삽질의 여정 🥲

(1) Service Worker 코드 누락

처음엔 messaging.onBackgroundMessage만 등록해두고,
정작 push 이벤트 핸들러에서 showNotification을 호출 안 하고 있었음.
즉, 이벤트는 잡았는데 “알림을 띄워라” 라는 명령을 안 한 셈…

 

(2) Firebase 콘솔 메뉴 헷갈림

콘솔에서 “새 캠페인 만들기” 눌렀다가 한참 삽질.
이건 마케팅 캠페인용이고, 토큰 직접 넣어서 테스트하려면 “테스트 메시지 전송” 버튼을 써야 한다.

 

(3) 브라우저 권한 문제

알림이 안 뜨는데 알고 보니 사이트 알림 권한이 차단됨 🤦‍♂️
주소창 왼쪽 🔒 아이콘 → 사이트 설정 → 알림 허용 필수!

 

(4) macOS 시스템 권한 문제

제일 오래 걸린 부분.
macOS에서 시스템 설정 → 알림 → Chrome 알림 허용이 꺼져 있었던 것.
이거 켜주니까 그제야 알림이 보였다. (여기서 제일 허무하게 웃음 나옴 😂)

 

---

3. 해결 방법

✅ Service Worker 코드 수정

/* global self, importScripts */
importScripts('https://www.gstatic.com/firebasejs/10.12.2/firebase-app-compat.js');
importScripts('https://www.gstatic.com/firebasejs/10.12.2/firebase-messaging-compat.js');

firebase.initializeApp({ /* firebaseConfig */ });
const messaging = firebase.messaging();

// 백그라운드 메시지
messaging.onBackgroundMessage((payload) => {
  const { title, body, icon } = payload.notification || {};
  self.registration.showNotification(title || '알림', { body, icon });
});

// 일반 push 이벤트 리스너
self.addEventListener('push', (event) => {
  console.log('[SW] Push Received:', event);
  const data = event.data?.json() || {};
  const { title, body, icon } = data.notification || {};
  event.waitUntil(
    self.registration.showNotification(title || '알림', { body, icon })
  );
});

 

✅ DevTools 푸시 버튼으로 테스트

Application → Service Workers → 푸시 버튼 눌러보기
→ 콘솔에 [SW] Push Received: 찍히고 알림이 뜨면 정상

 

✅ Firebase 콘솔에서 테스트 메시지 보내기

Cloud Messaging → 테스트 메시지 전송 → 발급받은 토큰 입력 → 전송
→ 알림이 잘 뜨면 성공 🎉

 

✅ 권한 확인

• 브라우저: 사이트 알림 허용
• macOS/Windows: 시스템 알림 권한 허용

 

---

4. 체크리스트 ✅

앞으로는 삽질 안 하려고, 내가 확인하는 순서를 정리했다.

• Service Worker 등록 상태 확인 (Activated)
• push 이벤트 핸들러 + showNotification 코드 있는지 확인
• Firebase 콘솔 → “테스트 메시지 전송” 사용하기
• 브라우저 알림 권한 허용했는지 확인
• OS 알림 권한 허용했는지 확인

 

---

마무리

결국 알림이 안 뜨는 원인은 코드 누락 + 권한 문제였다.
다른 분들도 비슷하게 막히면, 위 체크리스트부터 하나씩 확인하면 된다.

 

👉 다음 글에서는 알림은 잘 뜨는데 중복으로 뜨는 문제와 브라우저 상태별 동작 차이를 다뤄보겠다..