App Store 구성 문제는 대부분 상품 승인, StoreKit 설정, bundle ID 불일치와 관련이 있습니다. 이 섹션에서는 가장 흔한 iOS 전용 문제를 다룹니다.

문제 1: 상품이 승인되지 않았거나 판매할 수 없음

오류 메시지

warning: RevenueCat SDK is configured correctly, but contains some issues you might want to address
Warnings:
• Your products are configured in RevenueCat but aren't approved in App Store Connect yet.
  This prevents users from making purchases in production.
  Please ensure all products are approved and available for sale in App Store Connect.

흔한 원인

1. 상품이 심사 대기 중: 상품을 제출했지만 아직 Apple의 승인을 받지 못한 경우입니다.
2. 상품이 거부됨: App 심사 과정에서 상품이 거부된 경우입니다.
3. 계약 누락: 유료 앱 계약(Paid Applications Agreement)에 서명하지 않은 경우입니다.
4. 은행/세금 정보 미완료: App Store Connect에서 재무 정보를 완료하지 않은 경우입니다.
5. 상품이 판매 불가 상태: 상품은 존재하지만 "Available for Sale"로 표시되지 않은 경우입니다.

해결 단계

1단계: App Store Connect에서 상품 상태 확인

1. App Store Connect로 이동합니다.
2. 해당 앱을 선택합니다.
3. In-App Purchases(일회성 구매) 또는 Subscriptions로 이동합니다.
4. 각 상품의 상태를 확인합니다.
   • Ready to Submit: 앱 바이너리와 함께 상품을 제출해야 합니다.
   • Waiting for Review: 제출 완료, Apple 승인 대기 중입니다.
   • Approved / Ready to Sell: 준비 완료입니다.
   • Rejected: 거부 사유를 확인하고 문제를 해결합니다.

2단계: 유료 앱 계약(Paid Applications Agreement) 서명

1. App Store Connect에서 진행합니다.
2. Agreements, Tax, and Banking을 클릭합니다.
3. 대기 중인 계약(빨간색 경고 아이콘)이 있는지 확인합니다.
4. "Paid Applications" 옆의 Request를 클릭합니다.
5. 약관을 작성하고 동의합니다.

3단계: 은행 및 세금 정보 완료

1. Agreements, Tax, and Banking에서 진행합니다.
2. Banking 섹션을 완료합니다(은행 계좌 정보 추가).
3. Tax Forms를 완료합니다(미국은 W-9, 미국 외 지역은 W-8BEN).
4. Apple의 확인을 기다립니다(24~48시간 소요될 수 있습니다).

4단계: 상품을 심사에 제출

1. 상품은 반드시 앱 바이너리와 함께 제출해야 합니다.
2. App Store Connect에서 앱 버전으로 이동합니다.
3. 해당 버전에 인앱 구매를 추가합니다.
4. 앱을 심사에 제출합니다.
5. 상품은 앱과 함께 심사됩니다.

5단계: 테스트에 StoreKit Configuration 사용(권장)

승인을 기다리는 대신 로컬 테스트에 StoreKit Configuration File을 사용합니다.

1. Xcode에서 File → New → File로 이동합니다.
2. StoreKit Configuration File을 선택합니다.
3. 일치하는 ID로 상품을 추가합니다.
4. 스킴 설정에서 StoreKit 구성 파일을 활성화합니다.
5. 시뮬레이터와 실제 기기에서 상품이 즉시 동작합니다.

문제 2: StoreKit Configuration File 문제

오류 메시지

Error: Product not found in StoreKit configuration
StoreKit.Error: Unknown product identifier

흔한 원인

1. 상품 ID 불일치: StoreKit 파일의 ID가 RevenueCat/App Store Connect와 일치하지 않는 경우입니다.
2. StoreKit 파일 미활성화: 구성 파일은 존재하지만 스킴에서 활성화되지 않은 경우입니다.
3. 샌드박스 대신 프로덕션 사용: 앱이 로컬 파일 대신 App Store Connect에서 가져오려고 시도하는 경우입니다.

해결 단계

1단계: 상품 ID 일치 여부 확인

1. Xcode에서 .storekit 파일을 엽니다.
2. 상품 ID가 다음과 정확히 일치하는지 확인합니다.
   • App Store Connect 상품 ID
   • RevenueCat 대시보드 상품 ID
3. ID는 대소문자를 구분하므로 한 글자도 빠짐없이 일치해야 합니다.

2단계: 스킴에서 StoreKit Configuration 활성화

1. Xcode에서 Product → Scheme → Edit Scheme으로 이동합니다.
2. 왼쪽 패널에서 Run을 선택합니다.
3. Options 탭으로 이동합니다.
4. StoreKit Configuration 아래에서 .storekit 파일을 선택합니다.
5. 다시 빌드하고 실행합니다.

3단계: 상품 세부 정보를 올바르게 구성

StoreKit 파일에서 각 상품에 다음 항목이 있는지 확인합니다.

• 올바른 Product ID
• 적절한 Type(소모성, 비소모성, 자동 갱신 구독)
• 유효한 Price 및 Locale
• 구독의 경우: Subscription Duration

문제 3: bundle ID 불일치

오류 메시지

Error: The bundle identifier does not match the app configured in RevenueCat
Error: Unable to fetch products for bundle ID: com.example.wrongapp

흔한 원인

1. RevenueCat의 bundle ID 오류: 대시보드에 잘못된 번들 식별자가 입력된 경우입니다.
2. 프로비저닝 프로파일 불일치: 다른 bundle ID용 프로파일을 사용하는 경우입니다.
3. 여러 앱 타겟: 잘못된 타겟의 bundle ID를 사용하는 경우입니다.

해결 단계

1단계: Xcode에서 bundle ID 확인

1. Xcode 내비게이터에서 프로젝트를 선택합니다.
2. 앱 타겟을 선택합니다.
3. General 탭으로 이동합니다.
4. Bundle Identifier 필드를 확인합니다.
5. 이 값을 정확히 복사합니다.

2단계: RevenueCat에서 bundle ID 확인

1. RevenueCat 대시보드로 이동합니다.
2. 해당 프로젝트로 이동합니다.
3. Apps & providers → App Store로 이동합니다.
4. bundle ID가 Xcode의 bundle ID와 정확히 일치하는지 확인합니다.
5. 필요하면 수정합니다.

3단계: 프로비저닝 프로파일 확인

1. Xcode에서 Signing & Capabilities 탭으로 이동합니다.
2. 프로비저닝 프로파일이 bundle ID와 일치하는지 확인합니다.
3. 자동 서명을 사용한다면 Xcode가 알아서 처리합니다.
4. 수동 서명을 사용한다면 Apple Developer 포털에서 올바른 프로파일을 내려받습니다.

문제 4: 샌드박스 테스트 문제

오류 메시지

Error: Cannot connect to iTunes Store
StoreKitError: Purchase failed - Invalid sandbox account

흔한 원인

1. 샌드박스 계정에 로그인하지 않음: 기기에 샌드박스 계정이 설정되지 않은 경우입니다.
2. 프로덕션 계정 사용: 샌드박스 테스터 대신 일반 Apple ID로 로그인한 경우입니다.
3. 샌드박스 계정 미생성: 샌드박스 테스터 계정이 존재하지 않는 경우입니다.
4. 잘못된 샌드박스 구성: 기기가 샌드박스 테스트에 맞게 제대로 설정되지 않은 경우입니다.

해결 단계

1단계: 샌드박스 테스터 계정 생성

1. App Store Connect로 이동합니다.
2. Users and Access로 이동합니다.
3. 왼쪽 사이드바에서 Sandbox Testers를 클릭합니다.
4. +를 클릭해 새 테스터를 추가합니다.
5. 세부 정보를 입력합니다(고유한 이메일을 사용하며, 실제 이메일일 필요는 없습니다).
6. 테스터를 저장합니다.

2단계: 프로덕션 App Store에서 로그아웃

1. iOS 기기에서 Settings로 이동합니다.
2. 상단의 이름을 탭합니다.
3. 아래로 스크롤해 Sign Out을 탭합니다.
4. 여기서 샌드박스 계정으로 로그인하지 않습니다. 앱이 표시하는 프롬프트를 기다립니다.

3단계: 프롬프트가 표시되면 로그인

1. 앱을 디버그 모드로 실행합니다.
2. 구매를 시도합니다.
3. Apple ID 입력 프롬프트가 표시되면 샌드박스 테스터 자격 증명을 사용합니다.
4. 기기는 이후 테스트 구매를 위해 이 정보를 기억합니다.

4단계: 더 빠른 테스트에 Test Store 사용(대안)

샌드박스 관련 번거로움 없이 더 안정적으로 테스트하려면 RevenueCat Test Store를 사용합니다.

• 샌드박스 계정이 필요 없습니다.
• 구매 결과가 결정적입니다.
• 시뮬레이터에서 동작합니다.
• Apple 서버에 의존하지 않습니다.

문제 5: 모든 필드를 채웠는데도 "Missing Metadata" 상태

증상

필수 필드를 모두 입력했다고 생각하는데도 App Store Connect에서 구독 상품이 "Missing Metadata"로 표시됩니다. 이 상태에서는 상품을 심사에 제출할 수 없습니다.

Missing Metadata 상태의 상품을 RevenueCat이 볼 수 있나요?

환경에 따라 다릅니다.

• 샌드박스 및 StoreKit Configuration: 가능합니다. "Missing Metadata" 상태의 상품도 샌드박스 환경과 StoreKit Configuration 파일에서 테스트할 수 있습니다.
• 프로덕션: 불가능합니다. 프로덕션에서 상품을 가져오려면 "Approved" 상태여야 합니다. "Missing Metadata" 상품은 심사에 제출할 수 없으므로, 문제를 해결하기 전까지는 프로덕션에 절대 반영되지 않습니다.

흔한 원인

"Missing Metadata" 상태는 답답할 만큼 모호합니다. 모든 항목이 완료된 것처럼 보이는 경우에도 발생하는 가장 흔한 원인은 다음과 같습니다.

1. 심사 스크린샷이 아직 처리 중: 가장 흔하게 숨어 있는 원인입니다. 스크린샷이 UI에 보이더라도 App Store Connect는 내부적으로 여전히 처리 중일 수 있습니다. 5~10분 기다린 후 페이지를 새로 고칩니다.
2. 구독 현지화 누락: 구독 Display Name과 Description을 최소 한 개 언어에 대해 추가해야 합니다. 구독 → App Store Localization 섹션으로 이동해 표시 이름과 설명을 추가합니다.
3. 심사 스크린샷 누락: 각 구독 상품에는 앱 내 구독을 보여 주는 스크린샷이 필요합니다. 이 스크린샷은 앱 버전 스크린샷이 아니라 구독의 Review Information 섹션에 업로드해야 합니다.
4. 구독 그룹 현지화 누락: Subscription Group 자체에도 현지화된 표시 이름이 필요합니다. 구독 그룹으로 이동해 App Store Localization 섹션을 확인합니다.
5. 가격 누락: 상품에 최소 한 개의 Subscription Price가 구성되어 있는지 확인합니다.

해결 단계

1단계: 심사 스크린샷 확인

가장 흔히 놓치는 부분입니다. 스크린샷이 App Store Connect에 보이더라도 여전히 처리 중일 수 있습니다.

1. App Store Connect에서 구독 상품으로 이동합니다.
2. Review Information → Screenshot으로 스크롤합니다.
3. 스크린샷이 보이면 삭제한 후 다시 업로드합니다.
4. 처리가 완료되도록 5~10분 기다립니다.
5. 페이지를 새로 고쳐 상태가 바뀌는지 확인합니다.

2단계: 구독 현지화 확인

1. App Store Connect에서 구독 상품으로 이동합니다.
2. App Store Localization을 클릭하고 최소 한 개 언어에 다음이 있는지 확인합니다.
   • Display Name(사용자에게 표시되는 이름)
   • Description(구독에 포함되는 내용)
3. Subscription Group 수준도 확인합니다. 그룹 이름을 클릭해 현지화된 Display Name과 선택 항목인 Custom Display Name이 있는지 확인합니다.

3단계: 모든 필수 필드 확인

다음 체크리스트로 빠진 항목이 없는지 확인합니다.

• ☐ Reference Name: 상품의 내부용 이름입니다.
• ☐ Product ID: RevenueCat과 일치하는 식별자입니다.
• ☐ Subscription Duration: 주간, 월간, 연간 등입니다.
• ☐ Subscription Price: 최소 한 개의 가격이 구성되어 있어야 합니다.
• ☐ App Store Localization: 최소 한 개 언어의 표시 이름과 설명입니다.
• ☐ Subscription Group Localization: 그룹의 표시 이름입니다.
• ☐ Review Information: 스크린샷이 업로드되고 처리가 완전히 끝났는지 확인합니다(5~10분 대기).
• ☐ Review Notes(선택 사항이지만 권장): Apple 심사자를 위한 간단한 설명입니다.

흔한 문제 빠른 참조

App Store 설정 빠른 체크리스트

다음 체크리스트로 App Store 구성을 점검합니다.

• ☐ 유료 앱 계약(Paid Applications Agreement)에 서명했습니다.
• ☐ 은행 정보를 완료했습니다.
• ☐ 세금 양식을 제출하고 확인받았습니다.
• ☐ App Store Connect에 상품을 생성했습니다.
• ☐ App Store Connect와 RevenueCat의 상품 ID가 일치합니다.
• ☐ 상품을 심사에 제출했습니다(또는 StoreKit Configuration을 사용 중입니다).
• ☐ "Missing Metadata" 상태가 없습니다(스크린샷 처리, 현지화, 가격 책정을 확인합니다).
• ☐ Xcode와 RevenueCat의 bundle ID가 일치합니다.
• ☐ 프로비저닝 프로파일이 bundle ID와 일치합니다.
• ☐ 샌드박스 테스터 계정을 생성했습니다.
• ☐ 올바른 샌드박스 자격 증명으로 테스트하고 있습니다.
• ☐ 테스트 기기에서 프로덕션 App Store에 로그인되어 있지 않습니다.