Why Aren’t My Push Notifications Working? Troubleshooting Guide for App Developers
🎯 목적
푸시 노티피케이션은 재방문 유도, 트랜잭션 알림, 리텐션 개선의 핵심 도구입니다. 하지만 다계층(클라이언트·PNS·백엔드)으로 구성된 탓에 작은 설정 미스만으로도 “조용히 실패”하는 경우가 잦습니다. 본 문서는 실패 원인과 재현 가능한 점검 루틴(체크리스트/플레이북)을 제공합니다.
🌉 아키텍처 한눈에 보기
- 클라이언트: 앱이 OS의 PNS(APNs/FCM)에 등록 → 디바이스 토큰 발급 → 서버로 전달·갱신
- 서버: 토큰 저장·타게팅 결정·페이로드 생성 → PNS로 전송(FCM HTTP v1 OAuth / APNs JWT)
- PNS: 토큰과 환경(샌드박스/프로덕션)에 맞춰 디바이스로 전달
- 표시: OS 정책(권한·채널·중요도·배터리 최적화)과 앱 상태(포그라운드/백그라운드)에 따라 표시/무음 처리
🧨 왜 실패하는가? Top 10 원인과 핵심 포인트
- 🔑 인증/키 구성 오류
- APNs: p8 키(Team ID, Key ID, Bundle ID) 불일치, 토픽(apns-topic) 누락, 잘못된 환경 사용
- FCM: HTTP v1(OAuth2 서비스 계정) 미사용 또는 권한 범위 불일치
- 🙅 권한 미부여/차단
- iOS: 권한 미승인 시 표시 불가(토큰 등록은 별개)
- Android 13+: POST_NOTIFICATIONS 런타임 권한 필요, 채널 중요도 낮음(무음)
- 🧾 디바이스 토큰 문제
- 토큰 만료/변경/앱 재설치 후 무효: onNewToken(iOS: 토큰 리프레시)로 서버 갱신 필수
- 환경 혼용: 샌드박스 토큰에 프로덕션 게이트웨이 전송 등
- 🌐 환경 라우팅 불일치
- iOS: 개발/프로덕션 게이트웨이, 앱 서명 프로비저닝 일관성 필요
- 서버/CI: 빌드 타입·키 체인 분기 정확히 적용
- 📦 페이로드 오류
- APNs: aps 딕셔너리 필수, push-type 헤더(알림/백그라운드) 적합성 필요
- FCM: data-only vs notification 메시지 혼동, 키 예약어 충돌, 오타/JSON 스키마 위반
- ⏱️ TTL/우선순위/중복
- TTL 만료, collapse_key 오용으로 “뒤늦은 덮어쓰기” 발생
- Android: high priority 필요 시 normal 사용(절전 대기)
- 📵 OS/제조사 전원 정책
- Doze/배터리 최적화, 제조사별 백그라운드 제한(샤오미/화웨이 등)로 지연·드랍
- 🪪 채널/사운드/배지 설정 부재(Android)
- 채널 미생성·중요도 낮음 → 도착했지만 사용자 미인지