iOS 릴리즈(Archive)는 “빌드가 되느냐”보다 “배포용으로 문제 없느냐”가 핵심이라서, Cordova 플러그인 하나가 Info.plist/Entitlements/서명 설정을 건드리면 마지막에 크게 삐끗하기 쉽습니다. 아래는 릴리즈 실수 방지 관점에서, 플러그인/권한/서명까지 한 번에 묶어 점검하는 순서입니다.

릴리즈 서명과 권한 체크를 상징하는 봉투와 체크마크

체크리스트대로만 훑어도 App Store Connect 업로드 직전의 불필요한 왕복을 꽤 줄일 수 있어요.

1) 릴리즈용 “플러그인 목록”부터 고정하기 (의존성 변동 차단)

릴리즈 직전에 가장 위험한 건, 별 생각 없이 cordova plugin add를 다시 하거나, plugin version이 슬쩍 바뀌는 상황입니다. 같은 플러그인이라도 버전에 따라 필요한 권한 문구(Info.plist)나 entitlements가 달라질 수 있어요.

  • 현재 플러그인 목록/버전 스냅샷 저장: cordova plugin ls 결과를 릴리즈 노트에 남깁니다.
  • package.json/config.xml 정합성 확인: 한쪽만 수정되어 “빌드 환경마다 설치되는 플러그인이 다르게” 되는 상태를 피합니다.
  • git clean 상태 확인: platforms/ios, plugins/가 매번 재생성되는 팀이라면, 릴리즈 직전에는 재생성 타이밍을 고정(누가, 언제, 어떤 node/cordova 버전으로)합니다.

여기서 목표는 “이 Archive가 어떤 플러그인 조합으로 만들어졌는지”를 명확히 하는 겁니다. 원인 추적이 쉬워져요.

2) 권한(Info.plist) 문구 누락을 먼저 잡기: ‘Missing Info.plist key’류 예방

카메라/마이크/사진/위치 같은 민감 권한은 권한 요청 코드가 실행되기 전에 이미 검증 대상이 됩니다. App Store 심사, 또는 런타임 크래시(권한 호출 순간)로 돌아오기도 하고요.

Info.plist 권한 문구 누락을 점검하는 문서와 체크카드

  • 사용하는 플러그인 기준으로 역으로 체크: “앱이 무엇을 쓰지?”가 아니라 “플러그인이 무엇을 요구하지?”로 확인합니다.
  • Info.plist에 해당 키가 존재하는지 확인: 예) NSCameraUsageDescription, NSMicrophoneUsageDescription, NSPhotoLibraryUsageDescription, NSLocationWhenInUseUsageDescription 등
  • 문구가 빈 값이 아닌지 확인: 자동 생성된 placeholder가 남아 있거나 빈 문자열이면 리젝 사유가 되기 쉽습니다.

팁 하나만 더: 릴리즈 빌드는 Debug와 달리 “권한을 실제로 밟는 화면”이 QA에서 빠지기 쉬워요. 권한 요청이 발생하는 플로우를 테스트 시나리오에 강제로 포함시키는 게 안전합니다.

3) Entitlements 점검: Push/Keychain/Associated Domains는 ‘빌드는 되는데 업로드에서 막힘’이 흔함

Entitlements는 Xcode의 Signing 설정과 맞물리면서, 로컬 빌드/실기기 설치까지는 되는데 Archive/업로드에서만 문제를 만드는 경우가 있습니다. 특히 아래 조합이 자주 이슈를 만듭니다.

Push와 Keychain entitlements를 상징하는 잠금 패널 연결도

  • Push Notifications: aps-environment가 개발/배포로 엇갈리거나, 프로비저닝에 capability가 빠진 경우
  • Keychain Sharing: 키체인 그룹이 entitlements에만 있고, 실제 App ID capability와 불일치하는 경우
  • Associated Domains: applinks 도메인 추가 후, 팀/프로파일/빌드 설정에 반영이 덜 된 경우

체크 방법은 단순하게 가는 게 좋습니다. Xcode에서 Target > Signing & Capabilities에 켠 항목이 실제 배포용 프로비저닝 프로파일에도 포함돼 있는지, 그리고 Release 구성에서만 빠져 있지 않은지 확인하세요.

4) Code Signing 체크리스트: ‘Automatic’에 맡겨도 마지막에 확인할 것들

서명은 팀마다 운영 방식이 달라서 “정답”은 없지만, 릴리즈 실수는 패턴이 비슷합니다. 아래는 Cordova iOS 릴리즈에서 특히 자주 보는 실수 포인트예요.

  • Bundle Identifier가 배포용 App ID와 완전히 일치하는지 (와일드카드/테스트 ID가 남아있지 않은지)
  • Release 구성에만 다른 서명 설정이 들어가 있지 않은지 (Debug는 자동, Release는 수동 같은 혼합)
  • Provisioning Profile이 만료/폐기되지 않았는지 (새 인증서로 갱신했는데 옛 프로파일을 쓰는 경우)
  • Apple Distribution 인증서가 키체인에 올바르게 설치되어 있는지 (중간에 팀 변경/맥 변경 시 누락)
  • 같은 프로젝트를 여러 사람이 만질 때 Signing 관련 xcconfig/빌드 세팅이 커밋으로 고정되어 있는지

릴리즈에서 중요한 건 “누가 빌드해도 같은 결과”입니다. Automatic Signing을 쓰더라도, 최소한 Archive 전에 위 항목을 한 번씩 눈으로 확인하는 게 좋습니다.

5) 플러그인별 iOS 네이티브 설정 확인: config.xml/pods 훑는 빠른 루틴

플러그인은 JS 코드만 추가되는 게 아니라, iOS 쪽 설정을 같이 바꾸기도 합니다. 그래서 릴리즈 전에는 “플러그인 설치가 제대로 반영됐는지”를 빠르게 확인하는 루틴이 필요해요.

  • config.xml의 preference/feature 변경이 의도대로인지 확인 (특히 WKWebView, ATS 관련)
  • CocoaPods 사용 시 pod install 결과가 최신인지 (Podfile.lock 변동 여부 확인)
  • 특정 플러그인이 요구하는 iOS Deployment Target 상향이 반영됐는지 확인
  • 플러그인 문서에 있는 iOS 추가 설정(예: URL scheme, background mode)이 Release 설정에서도 동일한지 확인

여기서도 포인트는 “릴리즈는 Debug와 다르게 돌아간다”는 점입니다. Debug에서만 되는 설정(예: 개발용 URL scheme, 개발용 entitlement)이 섞여 있지 않게 분리하세요.

6) Archive 전 최종 체크리스트(요약): 10분 안에 훑는 버전

  • 플러그인 버전 고정: cordova plugin ls 스냅샷 저장
  • 권한 문구: 필요한 NS*UsageDescription 키 존재 + 문구 자연스러운지
  • Entitlements: Push/Keychain/Associated Domains 등 capability 불일치 없는지
  • 서명: Bundle ID, Team, Distribution 인증서, 배포용 프로비저닝 만료 여부
  • Release 구성: Debug와 서명/빌드 세팅이 의도치 않게 다른지
  • Pods/네이티브 의존성: Podfile.lock/Deployment Target 변경 누락 없는지

이 요약 체크리스트만 릴리즈 담당자가 매번 동일하게 수행해도, ‘마지막 1~2시간에 터지는’ 종류의 문제를 확실히 줄일 수 있습니다.

마무리

Cordova iOS 릴리즈에서 플러그인 문제는 대개 “플러그인 자체 버그”라기보다, Info.plist/Entitlements/서명 같은 배포 조건이 맞물리면서 생기는 경우가 많습니다.

릴리즈 직전엔 기능 테스트보다도, 위 체크리스트처럼 배포 조건을 먼저 고정해두면 실수가 크게 줄어듭니다.