Android 샌드박스 테스트 설정

이 플러그인의 설치 단계와 전체 마크다운 가이드가 포함된 설정 프롬프트를 복사하세요.

인앱 결제를 테스트하려면 Google Play Console에서 적절한 설정이 필요합니다. 이 가이드는 Android 앱의 샌드박스 테스트를 설정하는 방법을 안내합니다.

작업에 맞는 올바른 빌드 사용하기

시작하기 전에, 다음 세 가지 Android 빌드 유형을 구분하세요:

로컬 디버그/개발 빌드: 기기에서 UI 및 네이티브 통합을 확인하기에 적합합니다.
Play Console에 업로드된 서명된 릴리스 AAB: 실제 Google Play 결제 테스트를 위해 필요합니다.
Play 스토어를 통해 설치된 테스트 빌드: 테스터가 내부 또는 비공개 트랙을 통해 설치하는 빌드입니다. 구매 QA 시 이 빌드를 사용하세요.

Android Studio에서 APK를 사이드로딩만 하거나 adb Google Play Billing이 프로덕션 환경과 다르게 동작할 수 있습니다. 구독 및 인앱 결제 검증을 위해서는 항상 Google Play에서 설치한 빌드로 테스트하세요.

사전 요구사항

Google Play Console 개발자 계정. 아직 계정이 없다면 다음에서 시작하세요: Play Console 가입.
최종 Android 패키지 이름으로 Play Console에 생성된 앱 레코드
Play Console에서 생성한 인앱 상품 또는 구독 항목
라이선스 테스트에 추가할 수 있는 테스트용 Gmail 계정
업로드 가능한 상태의 서명된 release build

결제 설정을 시작하기 전에 Play Console에서 앱을 생성하고, 앱을 무료 또는 유료로 제공할지 결정하세요. Google에서는 유료 앱을 나중에 무료로 전환할 수 있지만, 한 번 무료로 제공된 앱은 다시 유료로 전환할 수 없습니다.

Android App Bundle (".aab) 신규 Play Store 앱의 경우:

bunx cap sync android
cd android
./gradlew bundleRelease

명령어를 실행하기 전에 Android release signing 설정이 완료되었는지 확인하세요. bundleReleasekeystore, signing config 또는 release password가 설정되지 않았다면, Android Studio에서 다음 메뉴를 통해 signed bundle을 생성하세요. Build > Generate Signed App Bundle / APK를 사용하면 해당 값들을 입력할 수 있습니다.

설정 프로세스

테스트 계정 추가

Play Console에서 다음 메뉴를 엽니다. 설정 > 라이선스 테스트 Android 테스트 기기에서 사용하는 기본 Google 계정을 추가하세요.

이렇게 하면 실제 결제가 진행되는 대신 Play 샌드박스 결제 흐름이 나타납니다.
테스트 트랙 선택

다음으로 이동: 테스트 및 출시 > 테스트 다음 트랙 중 하나를 선택하세요:
- 내부 테스트: QA 및 결제 스모크 테스트를 위한 가장 빠른 경로입니다. 새 번들은 보통 몇 분 내로 사용 가능합니다.
- 비공개 테스트: 더 광범위한 테스트에 적합하며, 2023년 11월 13일 이후 생성된 개인 개발자 계정은 프로덕션 출시 전 반드시 거쳐야 합니다.
첫 출시 시, Play에서는 내부 테스터에게 최대 48시간 동안 임시 앱 이름과 스토어 정보를 표시할 수 있습니다.
테스터 목록 생성

트랙을 연 후, 테스터 목록을 만들고 빌드를 받을 Google 계정을 추가하세요.

새로 만든 개인 계정으로 프로덕션 액세스를 준비 중이라면, 반드시 비공개 테스트(closed testing) 를 이용하고 최소 12명의 테스터가 14일 연속으로 참여하도록 유지해야 합니다.
서명된 릴리스 빌드 업로드

선택한 테스트 트랙에 새 릴리스를 생성하고 서명된 빌드를 업로드하세요. .aab.

새로운 Google Play 앱은 APK 대신 Android App Bundle을 사용해야 합니다. 업로드 후 릴리스를 저장하고, Play에서 표시하는 정책 또는 스토어 등록정보 차단 요소를 해결한 뒤 테스트 트랙에 릴리스를 게시하세요.
테스트 프로그램 참여

테스트 기기에서 opt-in URL을 열고 “테스터 되기” 버튼을 클릭하여 등록하세요.

로컬에서 내보낸 APK가 아닌, 해당 opt-in 과정을 통해 생성된 Play Store 목록에서 앱을 설치해야 합니다.
빌드 및 테스트

테스트 기기에서 Play Store를 통해 설치한 빌드를 실행하고 구매를 시도하세요. 다음과 같은 메시지가 표시되어야 합니다:

“테스트 주문입니다. 실제 결제는 이루어지지 않습니다.”

주의사항

결제 QA를 진행할 때는 Play 테스트 빌드를 설치하기 전에 사이드로딩된 앱 복사본을 모두 삭제하세요.
내부 테스트는 빠른 스모크 테스트에 유용하지만, 개인 계정의 신규 프로덕션 액세스 권한을 얻으려면 비공개 테스트 트랙이 중요합니다.
테스트 계정은 구매 시 비용이 청구되지 않습니다.
테스트 구매는 프로덕션 구매와 동일한 흐름을 사용합니다.
무료 체험 및 introductory offer를 포함한 모든 구독 기능을 테스트할 수 있습니다.
테스트 구독은 빠른 테스트를 위해 갱신 주기가 단축되어 있습니다.
기기 내 Play Store, 테스터 참여(opt-in) 흐름, 라이선스 테스트까지 세 곳 모두 동일한 Google 계정을 사용하세요.

문제 해결

테스트 모드에서 제품이 보이지 않는 경우:

앱이 테스트 트랙에 업로드되었는지 확인하세요.
테스트 계정이 라이선스 테스트에 추가되었는지 확인하세요.
Google Play Console에서 제품이 활성 상태인지 확인하세요.
로컬 사이드로딩이 아닌 Google Play를 통해 빌드가 설치되었는지 확인하세요

“Item not available” 에러 발생 시:

상품 생성 후 사용 가능해질 때까지 2~3시간 정도 기다려 주세요
앱의 패키지 이름이 Play Console의 이름과 일치하는지 확인하세요
테스트 계정으로 로그인되어 있는지 확인하세요
동일한 패키지 이름과 상품 카탈로그를 사용하는 서명된 release 빌드를 업로드했는지 확인하세요

테스트 구매가 실제 결제로 처리되는 경우:

해당 계정이 License testing에 추가되었는지 다시 한번 확인하세요
테스트 트랙의 빌드를 사용 중인지 확인하세요
구매 시 테스트 배너가 나타나는지 확인하세요

추가 리소스

Android Sandbox 테스트 설정에서 계속하기

사용 중이라면 Android 샌드박스 테스트 설정 스토어 승인 및 배포를 계획하려면, 다음 항목과 연결하세요 @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. 사용하기에서 네이티브 기능은