iOS 샌드박스 테스트 구성
이 플러그인의 설치 단계와 전체 마크다운 가이드가 포함된 설정 프롬프트를 복사하세요.
iOS에서 인앱 구매를 테스트하려면 App Store Connect와 테스트 기기에서 올바르게 설정해야 합니다. 이 가이드에서는 샌드박스 테스트를 시작하는 데 필요한 모든 내용을 다룹니다.
사전 요구사항
“사전 준비 사항” 섹션- Apple Developer Program: 연례 갱신이 포함된 활성 멤버십
- 계약: 은행 및 세금 정보 입력이 완료된 “유료 애플리케이션 계약” 서명
- Xcode 프로젝트: 올바른 번들 식별자와 기능 설정 완료
설정 프로세스
“설정 프로세스” 섹션-
유료 앱 계약 서명
App Store Connect에서 다음 경로로 이동하세요 계약, 세금 및 금융 그리고 완료하세요:
- 유료 애플리케이션 계약에 서명하세요
- 은행 정보를 추가하세요
- 세금 양식을 작성하세요
Apple이 정보를 승인할 때까지 기다리세요 (24~48시간 소요).
-
Sandbox 테스트 사용자 생성
App Store Connect에서 다음으로 이동하세요: 사용자 및 액세스 > Sandbox 테스터.
Members 섹션에서 + 버튼을 클릭해 새 Sandbox 테스터를 생성하세요.
중요: 아직 Apple ID에 연결되지 않은 이메일 주소를 사용하세요. 이메일 별칭(alias)을 사용할 수 있습니다:
- Gmail:
youremail+test@gmail.com - iCloud:
youremail+test@icloud.com

- Gmail:
-
테스트 기기 설정 (iOS 12 이상)
iOS 12부터는 결제 테스트를 위해 iTunes 계정에서 로그아웃할 필요가 없습니다.
iOS 기기에서:
- 열기 설정
- 탭하세요 App Store
- 맨 아래로 스크롤
- 탭하세요 Sandbox 계정
- Sandbox 테스트 계정으로 로그인하세요
-
Xcode 프로젝트 설정
Xcode 프로젝트에 다음이 있는지 확인하세요:
Bundle Identifier
- Developer Center의 식별자와 일치해야 합니다
- App Store Connect의 식별자와 일치해야 합니다
In-App Purchase 권한 설정
- Xcode에서 프로젝트를 선택하세요
- 다음으로 이동: Signing & Capabilities
- 클릭 + Capability 추가
- 추가 인앱 결제
-
인앱 구매 상품 생성하기
App Store Connect에서 앱으로 이동한 뒤 인앱 구매 상품(구독, 소모품 등)을 생성하세요.
샌드박스 테스트를 하려면 상품이 최소 “Ready to Submit” 상태여야 합니다.
-
구현 테스트하기
테스트 기기에서 앱을 빌드하고 실행하세요. 구매를 시도하면 다음과 같은 화면이 보여야 합니다:
[Environment: Sandbox]
이 확인 메시지는 샌드박스 환경에 있음을 나타내며 실제 결제가 이루어지지 않습니다.
주의사항
“중요 사항” 섹션Sandbox 환경 특성
“샌드박스 환경 특성” 섹션- 실제 결제 없음: 샌드박스 모드에서는 모든 구매가 무료입니다
- 구독 기간 단축: 테스트를 위해 구독 기간이 단축됩니다
- 1주 구독 = 3분
- 1개월 구독 = 5분
- 2개월 구독 = 10분
- 3개월 구독 = 15분
- 6개월 구독 = 30분
- 1년 구독 = 1시간
- 자동 갱신 제한: 샌드박스에서 구독은 최대 6회까지 자동 갱신됩니다
- 즉시 취소: 취소된 구독은 즉시 만료됩니다
Sandbox 계정 관리
“샌드박스 계정 관리” 섹션- 서로 다른 시나리오를 위해 여러 테스트 계정을 생성하세요
- 테스트 계정은 테스트 기기에서만 사용하세요
- 샌드박스 테스트에는 개인 Apple ID를 사용하지 마세요
- 테스트 계정은 지역에 관계없이 모든 제품을 구매할 수 있습니다
Sandbox 테스트 사용법
“샌드박스 테스트 사용” 섹션import { NativePurchases, PURCHASE_TYPE } from '@capgo/native-purchases';
const { isBillingSupported } = await NativePurchases.isBillingSupported();if (!isBillingSupported) { throw new Error('StoreKit not supported on this device');}
// Fetch products (automatically uses sandbox when available)const { products } = await NativePurchases.getProducts({ productIdentifiers: ['premium_monthly'], productType: PURCHASE_TYPE.SUBS,});
// Make test purchaseconst transaction = await NativePurchases.purchaseProduct({ productIdentifier: 'premium_monthly', productType: PURCHASE_TYPE.SUBS,});
console.log('Test purchase successful!', transaction.transactionId);검증
“검증” 섹션제대로 설정하면 다음을 확인할 수 있습니다:
- 샌드박스 배너 구매 시: “[Environment: Sandbox]”
- 제품 로드 성공
- 구매 완료 실제 결제 없이
- 영수증 검증 정상적으로
- 구독 갱신 자동으로 (가속된 속도로)
문제 해결
“문제 해결” 섹션상품이 로드되지 않을 때:
- Bundle Identifier가 App Store Connect와 일치하는지 확인
- 계약서 서명 및 승인 여부 확인
- 상품이 최소 “Ready to Submit” 상태인지 확인
- 상품 생성 후 2~3시간 정도 기다려 주세요
“Cannot connect to iTunes Store” 오류:
- Sandbox 계정 설정이 올바른지 확인하세요
- 기기의 인터넷 연결 상태를 확인하세요
- Sandbox 계정에서 로그아웃했다가 다시 로그인해 보세요
- 앱을 재실행하세요
결제가 아무런 반응 없이 실패하는 경우:
- Xcode 콘솔에서 에러 메시지를 확인하세요
- In-App Purchase capability가 활성화되어 있는지 확인하세요
- Sandbox 계정 이메일이 실제 Apple ID가 아닌지 확인하세요
- 새 Sandbox 테스트 계정을 만들어 보세요
영수증 검증 오류:
- 테스트 시 샌드박스 리시트 검증 엔드포인트 사용
- 프로덕션 엔드포인트:
https://buy.itunes.apple.com/verifyReceipt - 샌드박스 엔드포인트:
https://sandbox.itunes.apple.com/verifyReceipt - native-purchases 플러그인이 이를 자동으로 처리합니다
구독 기간이 잘못되었습니다:
- 샌드박스에서는 구독이 가속됩니다
- 예상 기간은 위의 변환 차트를 참고하세요
- 샌드박스에서 구독은 최대 6회 자동 갱신됩니다
“이 Apple ID는 아직 iTunes Store에서 사용되지 않았습니다”:
- 새로운 샌드박스 계정에서 정상적인 현상입니다
- 계정을 활성화하려면 구매를 진행하세요
- 최초 사용 시에만 발생
모범 사례
“권장 사항” 섹션- 여러 테스트 계정 생성 다양한 테스트 시나리오를 위해
- 모든 구독 기간 테스트 동작 확인을 위해
- 취소 및 갱신 플로우 테스트
- 수신 영수증 검증 정상 작동 여부 확인
- 구매 복원 테스트 기능
- 구독 업그레이드/다운그레이드 확인 동작 방식
- 불안정한 네트워크 환경에서 테스트
Production vs. Sandbox 환경 비교
“Production vs. Sandbox” 섹션| 기능 | Sandbox | 프로덕션 |
|---|---|---|
| 실제 결제 | 아니요 | 지원 |
| 구독 기간 | 가속 | 일반 |
| 자동 갱신 제한 | 6회 | 무제한 |
| 취소 적용 시점 | 즉시 | 기간 만료 |
| 영수증 엔드포인트 | Sandbox URL | 프로덕션 URL |
| 테스트 계정만 | 지원 | 아니요 |
추가 리소스
“추가 리소스” 섹션자세한 내용은 Apple StoreKit 공식 문서의 샌드박스 테스트 항목을 참조하세요.
iOS 샌드박스 테스트 구성에서 계속하기
“iOS 샌드박스 테스트 구성에서 계속하기” 섹션사용 중이라면 iOS 샌드박스 테스트 구성 스토어 승인 및 배포를 계획하려면, 다음 항목과 연결하세요 @capgo/native-purchases 사용하기 @capgo/native-purchases 사용 시 네이티브 기능을 위해, @capgo/capacitor-in-app-review @capgo/capacitor-in-app-review의 구현 세부 사항에 대해서는, @capgo/capacitor-in-app-review 사용하기 @capgo/capacitor-in-app-review 사용하기에서 네이티브 기능은, @capgo/capacitor-native-market @capgo/capacitor-native-market의 구현 세부 사항에 대해서는, 그리고 @capgo/capacitor-native-market 사용하기 @capgo/capacitor-native-market. 사용하기에서 네이티브 기능은