iOS 샌드박스 테스트 구성

iOS에서 인앱 구매를 테스트하려면 App Store Connect 및 테스트 기기에서 적절한 구성이 필요합니다. 이 가이드는 샌드박스 테스트를 시작하는 데 필요한 모든 것을 다룹니다.

사전 요구 사항

• Apple Developer Program: 연간 갱신이 포함된 활성 멤버십
• 계약: 은행 및 세금 정보가 완료된 “유료 애플리케이션 계약” 서명
• Xcode 프로젝트: 적절한 번들 식별자 및 기능으로 구성됨

Note

은행 및 세금 설정 승인은 몇 시간에서 며칠이 걸릴 수 있습니다. 테스트 전에 충분한 시간을 두고 완료하세요.

설정 프로세스

1. 유료 애플리케이션 계약 서명

   App Store Connect에서 계약, 세금 및 은행 정보로 이동하여 다음을 완료하세요:

   • 유료 애플리케이션 계약 서명
   • 은행 정보 추가
   • 세금 양식 작성

   Apple의 승인을 기다리세요 (24~48시간 소요 가능).

2. 샌드박스 테스트 사용자 생성

   App Store Connect에서 사용자 및 액세스 > 샌드박스 테스터로 이동하세요.

   + 버튼을 클릭하여 새 샌드박스 테스터를 생성하세요.

   중요: Apple ID와 연결되지 않은 이메일 주소를 사용하세요. 이메일 별칭을 사용할 수 있습니다:

   • Gmail: youremail+test@gmail.com
   • iCloud: youremail+test@icloud.com

   

3. 테스트 기기 구성 (iOS 12+)

   iOS 12부터는 구매를 테스트하기 위해 iTunes 계정에서 로그아웃할 필요가 없습니다.

   iOS 기기에서:

   1. 설정 열기
   2. App Store 탭
   3. 하단으로 스크롤
   4. 샌드박스 계정 탭
   5. 샌드박스 테스트 계정으로 로그인

   Tip

   이것은 iTunes 계정에서 로그아웃하는 이전 방법보다 훨씬 편리합니다!

4. Xcode 프로젝트 구성

   Xcode 프로젝트에 다음이 있는지 확인하세요:

   번들 식별자

   • Developer Center의 식별자와 일치해야 함
   • App Store Connect의 식별자와 일치해야 함

   인앱 구매 기능

   1. Xcode에서 프로젝트 선택
   2. 서명 및 기능으로 이동
   3. + 기능 클릭
   4. 인앱 구매 추가

5. 인앱 구매 제품 생성

   App Store Connect에서 앱으로 이동하여 인앱 구매 제품(구독, 소비품 등)을 생성하세요.

   제품은 샌드박스 테스트를 위해 최소 “제출 준비 완료” 상태여야 합니다.

6. 구현 테스트

   테스트 기기에서 앱을 빌드하고 실행하세요. 구매를 시도하면 다음이 표시됩니다:

   [Environment: Sandbox]

   이 확인 메시지는 샌드박스 환경에 있으며 실제 돈이 청구되지 않음을 나타냅니다.

중요 사항

샌드박스 환경 특성

• 실제 요금 없음: 샌드박스 모드에서는 모든 구매가 무료입니다
• 가속화된 구독: 빠른 테스트를 위해 구독 기간이 단축됩니다
  • 1주 구독 = 3분
  • 1개월 구독 = 5분
  • 2개월 구독 = 10분
  • 3개월 구독 = 15분
  • 6개월 구독 = 30분
  • 1년 구독 = 1시간
• 자동 갱신 제한: 샌드박스에서 구독은 최대 6회 자동 갱신됩니다
• 즉시 취소: 취소된 구독은 즉시 만료됩니다

샌드박스 계정 관리

• 다양한 시나리오를 위해 여러 테스트 계정 생성
• 테스트 계정은 테스트 기기에서만 사용
• 샌드박스 테스트에는 개인 Apple ID 사용 금지
• 테스트 계정은 지역에 관계없이 모든 제품을 구매할 수 있습니다

샌드박스 테스트 사용

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 purchase
const transaction = await NativePurchases.purchaseProduct({
  productIdentifier: 'premium_monthly',
  productType: PURCHASE_TYPE.SUBS,
});

console.log('Test purchase successful!', transaction.transactionId);

확인

올바르게 구성되면 다음을 확인할 수 있습니다:

1. 구매 중 샌드박스 배너: “[Environment: Sandbox]”
2. 제품이 성공적으로 로드됨
3. 실제 요금 없이 구매 완료
4. 영수증 검증 정상 작동
5. 구독 자동 갱신 (가속화된 속도로)

문제 해결

제품이 로드되지 않음:

• 번들 식별자가 App Store Connect와 일치하는지 확인
• 계약이 서명되고 승인되었는지 확인
• 제품이 최소 “제출 준비 완료” 상태인지 확인
• 제품 생성 후 2~3시간 대기

“iTunes Store에 연결할 수 없습니다”:

• 샌드박스 계정이 올바르게 구성되었는지 확인
• 기기가 인터넷에 연결되어 있는지 확인
• 샌드박스 계정에서 로그아웃했다가 다시 로그인 시도
• 앱 재시작

구매가 자동으로 실패함:

• Xcode 콘솔에서 오류 메시지 확인
• 인앱 구매 기능이 활성화되었는지 확인
• 샌드박스 계정 이메일이 실제 Apple ID가 아닌지 확인
• 새 샌드박스 테스트 계정 생성 시도

영수증 검증 오류:

• 테스트에서 샌드박스 영수증 검증 엔드포인트 사용
• 프로덕션 엔드포인트: https://buy.itunes.apple.com/verifyReceipt
• 샌드박스 엔드포인트: https://sandbox.itunes.apple.com/verifyReceipt
• native-purchases 플러그인이 자동으로 처리

잘못된 구독 기간:

• 샌드박스에서 구독이 가속화된다는 점 기억
• 예상 기간은 위의 변환 차트 사용
• 샌드박스에서 구독은 최대 6회 자동 갱신

“이 Apple ID는 아직 iTunes Store에서 사용되지 않았습니다”:

• 새 샌드박스 계정에서는 정상적인 메시지입니다
• 구매를 진행하여 계정 활성화
• 첫 사용 시에만 발생

모범 사례

1. 다양한 테스트 시나리오를 위해 여러 테스트 계정 생성
2. 동작을 확인하기 위해 모든 구독 기간 테스트
3. 취소 및 갱신 흐름 테스트
4. 영수증 검증이 올바르게 작동하는지 확인
5. 구매 복원 기능 테스트
6. 구독 업그레이드/다운그레이드 동작 확인
7. 열악한 네트워크 조건에서 테스트

프로덕션 vs. 샌드박스

기능	샌드박스	프로덕션
실제 요금	없음	있음
구독 기간	가속화됨	정상
자동 갱신 제한	6회	무제한
취소 효과	즉시	기간 종료
영수증 엔드포인트	샌드박스 URL	프로덕션 URL
테스트 계정만	예	아니오

추가 리소스

자세한 내용은 샌드박스 테스트에 대한 공식 Apple StoreKit 문서를 참조하세요.