iOS Firebase 푸시 알림 설정 오류 해결 후기 (APNs 설정, Debug/Release 차이)

iOS Firebase 푸시 알림 설정 오류 해결 후기 (APNs 설정, Debug/Release 차이)

Flutter 앱을 개발하면서 iOS 푸시 알림이 동작하지 않는 문제를 겪었고, 여러 시행착오 끝에 원인을 파악하고 해결할 수 있었습니다. 이 글은 그 경험을 공유하는 기록입니다.

---

문제 현상

firebase_messaging/apns-token-not-set 오류 발생. 아래 이슈들이 번갈아가면서 발생했습니다. 개발 환경은 디버그/릴리즈 두 모드 다 테스트를 진행한 상태였습니다.

콘솔 로그:

Error in application:didFailToRegisterForRemoteNotificationsWithError:
응용 프로그램을 위한 유효한 'aps-environment' 인타이틀먼트 문자열을 찾을 수 없습니다.

Firebase Functions 로그:

완료 알림 전송 실패: { error: 'Auth error from APNS or Web Push Service', code: 'messaging/third-party-auth-error' }

---

원인 분석

1. APNs 키 설정 문제

기존에 등록된 APNs 키는 production 전용이었습니다. 
✅ Firebase FCM은 오직 production 환경만 지원하며, 디버그 환경(sandbox)에서는 작동하지 않습니다.
➡️ 따라서 sandbox + production 겸용 키를 발급받아도 디버그 환경에서 Firebase 푸시는 구조적으로 수신되지 않습니다. 그것도 모르고 디버그 환경에서 계속 고생하다 결국 키까지 다시 생성하면서 오전 내내 삽질을 하였습니다... 

 

 

 

 

2. Debug 빌드로 테스트 중

알림 설정은 보통 Runner-Release.entitlements에만 적용되어 있고, Runner-Debug.entitlements에는 누락되어 있는 경우가 많습니다.
Debug 모드로 빌드하면 aps-environment entitlement가 포함되지 않아 푸시 등록이 실패합니다.
➡️ 다만 위에서 설명했듯이, Firebase FCM은 디버그 빌드에서 작동하지 않으므로, 이 설정을 추가하더라도 푸시는 수신되지 않습니다.

---

해결 방법

✅ APNs Key 새로 생성 및 등록

• Apple Developer → Certificates, Identifiers & Profiles
• Keys 메뉴에서 새로운 APNs Key 생성
  • 이름은 자유롭게
  • Platform은 선택 없음 (.p8 키는 항상 universal)
• 생성된 키를 Firebase Console의 iOS 앱 설정에 등록

✅ Release 모드로 빌드하여 테스트

flutter build ios --release

• Release 모드에선 Runner-Release.entitlements가 적용되어 정상 작동함
• 실제 기기에 릴리즈 빌드를 설치해서 테스트해야 FCM 푸시 확인 가능

✅ Debug 빌드에서도 등록 에러 방지

Xcode에서 Push Notification Capabilities를 추가해도 .entitlements 파일이 자동으로 갱신되지 않을 수 있음. 아래 조건에서 수동 수정 필요:

• entitlements 파일이 복수 존재함 (예: Runner.entitlements, Runner-Debug.entitlements)
• Build Settings > Code Signing Entitlements에 수동 설정이 다르게 되어 있음
• Git에서 변경 불가 상태
• Xcode 버그 등

이 경우에는 Runner-Debug.entitlements에 다음 항목을 수동으로 추가:

<key>aps-environment</key>
<string>development</string>

단, 위 설정은 등록 오류 방지용일 뿐, FCM 푸시는 릴리즈 환경에서만 동작함에 유의.

---

요약

항목	설명
APNs Key	production 전용으로 생성 (sandbox는 Firebase에서 사용하지 않음)
Firebase 설정	새 키로 교체 (production 전용이면 충분)
빌드 모드	Release에서만 푸시 동작, Debug는 FCM 푸시 불가
권한 상태	AuthorizationStatus.authorized 이더라도 APNs 토큰 없으면 실패
최종 해결	새 키 등록 + Release 빌드로 테스트 → 정상 수신 확인

---

Firebase로 iOS 푸시 알림을 구현할 때는 반드시 릴리즈 빌드로 테스트해야 하며, 디버그 모드에서는 FCM 푸시가 동작하지 않는다는 점을 명심해야 합니다. sandbox + production 겸용 키는 Firebase FCM에선 의미 없으니 production 전용이면 충분합니다.