본문 바로가기
Capgo - Capacitor 앱 빌드, 배포 및 업데이트 Capgo

iOS 샌드박스 테스트 구성

GitHub

iOS에서 인앱 결제를 테스트하려면 App Store Connect와 테스트 기기에 적절한 설정이 필요합니다. 이 가이드는 sandbox 테스트를 시작하는 데 필요한 모든 과정을 다룹니다.

사전 요구사항

“사전 준비 사항” 섹션
  • Apple Developer Program: 연간 갱신이 포함된 활성 멤버십
  • 계약 사항: 은행 및 세금 정보 입력이 완료된 “Paid Applications Agreement” 서명 완료
  • Xcode 프로젝트: 올바른 bundle identifier 및 capabilities 설정 완료

설정 프로세스

“Setup Process” 섹션

  1. Paid Applications Agreement 서명하기

    App Store Connect에서 다음으로 이동: 계약, 세금 및 금융 정보 다음 단계를 완료하세요:

    • Paid Applications Agreement 서명
    • 은행 정보 추가
    • 세금 양식 작성

    Apple의 정보 승인을 기다리세요 (24~48시간 소요될 수 있음).

  2. Sandbox 테스트 사용자 생성

    App Store Connect에서 다음으로 이동하세요: 사용자 및 액세스 > Sandbox 테스터.

    Members 섹션에서 + 버튼을 클릭하여 새로운 sandbox tester를 생성합니다.

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

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

    Sandbox 테스터 생성

  3. 테스트 기기 설정 (iOS 12 이상)

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

    iOS 기기에서:

    1. 열기 설정
    2. 탭하세요 App Store
    3. 맨 아래로 스크롤
    4. 탭하세요 Sandbox 계정
    5. Sandbox 테스트 계정으로 로그인하세요

  4. Xcode 프로젝트 설정

    Xcode 프로젝트에 다음 사항이 포함되어 있는지 확인하세요:

    Bundle Identifier

    • Developer Center의 식별자와 일치해야 합니다
    • App Store Connect의 식별자와 일치해야 합니다

    In-App Purchase 권한 설정

    1. Xcode에서 프로젝트를 선택하세요
    2. 다음으로 이동: Signing & Capabilities
    3. 클릭 + Capability
    4. 추가 인앱 결제

  5. 인앱 결제 상품 생성하기

    App Store Connect에서 앱을 선택한 후, 인앱 결제 상품(구독, 소모품 등)을 생성하세요.

    샌드박스 테스트를 하려면 상품 상태가 최소 “Ready to Submit”이어야 합니다.

  6. 구현 사항 테스트하기

    테스트 기기에서 앱을 빌드하고 실행하세요. 결제를 시도하면 다음과 같은 화면이 나타납니다:

    [환경: Sandbox]

    이 확인 메시지는 현재 sandbox 환경임을 나타내며, 실제 비용이 결제되지 않습니다.

주의사항

“주의 사항” 섹션

Sandbox 환경의 특징

“Sandbox 환경의 특징” 섹션
  • 실제 결제 없음: sandbox 모드에서는 모든 구매가 무료입니다
  • 구독 기간 단축: 빠른 테스트를 위해 구독 기간이 단축됩니다
    • 1주일 구독 = 3분
    • 1개월 구독 = 5분
    • 2개월 구독 = 10분
    • 3개월 구독 = 15분
    • 6개월 구독 = 30분
    • 1년 구독 = 1시간
  • 자동 갱신 제한: Sandbox 환경에서는 구독이 최대 6회까지 자동 갱신됩니다
  • 즉시 취소: 취소된 구독은 즉시 만료됩니다

Sandbox 계정 관리

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

Sandbox Testing 사용하기

“Sandbox Testing 사용하기” 섹션
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);

검증

“Verification” 섹션

설정이 올바르면 다음과 같은 현상이 나타납니다:

  1. Sandbox 배너 구매 시: “[Environment: Sandbox]” 표시
  2. 제품 로드 성공적으로 완료
  3. 결제 완료 실제 비용 청구 없이
  4. 영수증 검증 정상 처리
  5. 구독 갱신 자동 진행 (가속화된 속도)

문제 해결

“문제 해결” 섹션

상품을 불러올 수 없는 경우:

  • 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 테스트 계정을 만들어 보세요

영수증 검증 오류:

  • 테스트 시 sandbox 영수증 검증 엔드포인트 사용
  • Production 엔드포인트: https://buy.itunes.apple.com/verifyReceipt
  • Sandbox 엔드포인트: https://sandbox.itunes.apple.com/verifyReceipt
  • native-purchases 플러그인이 이를 자동으로 처리합니다

구독 기간이 잘못된 경우:

  • sandbox에서는 구독 기간이 단축됨에 유의하세요
  • 예상 기간은 위의 변환 차트를 참조하세요
  • sandbox에서 구독은 최대 6회까지 자동 갱신됩니다

“이 Apple ID는 아직 iTunes Store에서 사용된 적이 없습니다.”:

  • 새 sandbox 계정에서는 정상적인 현상입니다
  • 구매를 진행하여 계정을 활성화하세요
  • 최초 사용 시에만 발생합니다

모범 사례

“권장 사항” 섹션
  1. 여러 테스트 계정 생성 다양한 테스트 시나리오용
  2. 모든 구독 기간 테스트 동작 확인을 위해
  3. 구독 취소 및 갱신 프로세스 테스트
  4. 영수증 검증 정상 작동 확인
  5. 구매 복원 기능 테스트
  6. 구독 업그레이드/다운그레이드 동작 확인 동작
  7. 네트워크 환경이 좋지 않은 상태에서 테스트

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. 사용하기에서 네이티브 기능은