[Flutter] iOS 시뮬레이터에서 인앱 구독 테스트하기 (StoreKit Configuration)

개요

인앱 구독 로직을 고치고 나면 결제 흐름을 직접 눈으로 확인하고 싶어집니다. 하지만 실기기와 샌드박스 계정을 준비하는 건 번거롭고, 시뮬레이터에서 그냥 실행하면 상품 조회부터 실패하거나 Apple 계정 로그인 창이 뜨기도 합니다.

Xcode 의 StoreKit Configuration 파일 을 쓰면 App Store 에 접속하지 않고 로컬에서 가짜 스토어를 띄울 수 있습니다. 상품 조회, 결제 시트, 구매 복원이 모두 시뮬레이터 안에서 동작하고, 결제해도 실제로 과금되지 않습니다.

이 글에서는 Flutter 앱(in_app_purchase 패키지)의 자동 갱신 구독을 이 방법으로 테스트한 과정을 정리합니다.

시뮬레이터로 확인할 수 있는 것과 없는 것

먼저 범위를 분명히 해 두겠습니다. StoreKit Configuration 파일로 만든 거래는 Apple 이 아니라 Xcode 가 로컬에서 서명 합니다. 그래서 앱이 영수증을 자체 서버로 보내 Apple 에 검증하는 구조라면, 서버 검증은 통과하지 못합니다.

확인할 수 있는 것

상품 정보 조회와 가격 표시
결제 시트 표시, 결제 취소, 로컬 결제 성공
구매 복원(restorePurchases()) 호출과 그 결과(구독이 없을 때의 안내 등)
앱 시작 시 백그라운드에서 복원을 호출해도 다이얼로그나 로그인 창이 뜨지 않는지

확인할 수 없는 것

서버 검증을 통과한 뒤의 흐름 (구독자로 표시, 재설치 후 자동 복구 등)
실제 App Store 계정·샌드박스 환경에서의 동작

뒤쪽은 실기기와 샌드박스 계정으로 따로 확인해야 합니다.

StoreKit Configuration 파일 만들기

Flutter 프로젝트의 ios/Runner.xcworkspace 를 Xcode 로 엽니다. 메뉴에서 File › New › File from Template… 을 선택하고, 검색창에 storekit 을 입력하면 StoreKit Configuration File 템플릿이 나옵니다.

Xcode - StoreKit Configuration File 템플릿

Next 를 누르면 파일 이름과 저장 위치를 정합니다. 이때 두 가지를 확인합니다.

Sync this file with an app in App Store Connect: 체크하면 App Store Connect 에 등록된 상품을 가져옵니다. Xcode 에 개발자 계정이 로그인되어 있어야 합니다. 이 글에서는 체크하지 않고 상품을 직접 추가했습니다.
Targets: Runner 타깃은 체크 해제 합니다. 이 파일은 테스트 설정일 뿐이라 앱 번들에 들어갈 필요가 없습니다.

구독 상품 추가하기

만든 .storekit 파일을 열고, 편집기 왼쪽 아래의 + 버튼에서 Add Auto-Renewable Subscription 을 선택합니다. 구독 그룹 이름을 정하면 그룹 안에 구독 상품이 하나 생깁니다.

Xcode - StoreKit Configuration 편집기에서 자동 갱신 구독 설정

오른쪽에서 다음 항목을 채웁니다.

항목	값
Reference Name	관리용 이름 (예: `Monthly`)
Product ID	앱 코드에서 조회하는 상품 ID 와 정확히 같은 값
Subscription Duration	구독 주기 (예: 1 Month)
Price	표시할 가격 (예: 3.00)

스크린샷의 product.id 는 예시 값입니다. 여기에는 앱이 InAppPurchase.instance.queryProductDetails() 로 조회하는 실제 상품 ID 를 넣어야 합니다. 값이 다르면 상품 조회 결과가 비어서 결제 화면을 열 수 없습니다.

스킴에 연결하기

메뉴에서 Product › Scheme › Edit Scheme… 을 열고, 왼쪽에서 Run 을 고른 뒤 Options 탭으로 이동합니다. StoreKit Configuration 드롭다운에서 방금 만든 파일을 선택합니다.

Xcode - Edit Scheme 의 StoreKit Configuration 설정

파일 이름이 빨간 글씨 로 보이면 Xcode 가 그 경로에서 파일을 찾지 못한 것입니다. 이 상태로 실행하면 설정이 적용되지 않고 시뮬레이터가 실제 스토어에 접속하려 하므로, Apple 계정 로그인 창이 뜰 수 있습니다. 아래 주의할 점을 참고해 파일을 프로젝트에 추가한 뒤 다시 선택합니다.

실행하고 확인하기

시뮬레이터를 선택하고 Xcode 의 ▶ 버튼으로 앱을 실행합니다. 이 글에서는 Xcode 에서 실행해서 확인했습니다.

앱에서 결제 버튼을 누르면 Xcode 라고 표시된 결제 확인 시트가 뜹니다. 로그인 창이 아니라 이 시트가 뜬다면 StoreKit Configuration 이 제대로 적용된 것입니다. 시트에는 “For testing purposes only. You will not be charged…” 라는 문구가 함께 표시됩니다.

iOS 시뮬레이터 - Xcode 환경의 구독 결제 확인 시트

Subscribe 를 누르면 [Environment: Xcode] 가 적힌 완료 알림이 뜹니다.

iOS 시뮬레이터 - Xcode 환경의 결제 완료 알림

이 외에 이번에 확인한 시나리오는 다음과 같습니다.

앱 시작 시 조용한 복원: 앱을 처음 실행하고 몇 초 기다려도 다이얼로그나 로그인 창이 뜨지 않는다. 시뮬레이터에서 앱을 삭제하고 다시 실행하면 재설치 상황도 만들 수 있다.
결제 취소: 결제 확인 시트를 닫아도 에러 없이 원래 화면으로 돌아온다.
사용자의 구매 복원: 구독이 없는 상태에서 “구매 복원” 을 누르면 구독이 없다는 안내가 뜬다.
결제 후 서버 검증: 로컬 결제는 성공하지만, 서버 검증을 통과하지 못하므로 앱은 구독자로 바뀌지 않는다. 앞에서 설명한 한계 그대로다.

Manage Transactions 로 거래 다루기

앱이 실행 중일 때 Debug › StoreKit › Manage Transactions… 를 열면, 시뮬레이터에서 일어난 거래 목록을 볼 수 있습니다.

Xcode - StoreKit Manage Transactions

여기서 거래를 선택해 삭제하거나 환불 처리할 수 있습니다. 테스트를 처음부터 다시 하고 싶을 때는 거래를 삭제하면 “구매한 적 없는 사용자” 상태로 돌아갑니다.

거래 옆에 ⚠ 아이콘이 붙어 있으면, 선택했을 때 다음 메시지가 표시됩니다.

This transaction has not been finished by calling finish()

앱이 아직 거래를 마무리하지 않았다는 뜻입니다. in_app_purchase 에서는 completePurchase() 를 호출해야 iOS 쪽에서 finish() 가 불립니다. 서버 검증이 끝난 뒤에 completePurchase() 를 호출하는 앱이라면, 검증이 끝나기 전에는 이렇게 미완료로 남습니다. 마무리되지 않은 거래는 iOS 가 다음 실행 때 앱에 다시 전달합니다.

주의할 점

파일 경로가 빨간 글씨일 때

스킴 파일(.xcscheme)을 손으로 수정해 경로를 넣으면, 경로 표기가 맞지 않아 빨간 글씨가 될 수 있습니다. 이때는 Xcode 왼쪽 Project Navigator 에서 Runner 폴더를 우클릭해 Add Files to “Runner”… 를 선택하거나, Finder 에서 .storekit 파일을 Runner 폴더로 끌어다 놓아 프로젝트에 추가합니다. 그다음 스킴의 StoreKit Configuration 에서 파일을 다시 선택하면 정상 색으로 바뀝니다.

의도하지 않은 변경이 생길 수 있다

파일을 Xcode 로 추가하면 다음 변경이 함께 생길 수 있습니다.

추가 옵션에 따라 파일이 프로젝트 폴더로 복사 된다.
Xcode 가 그 파일을 git 의 커밋 대상에 자동으로 추가 한다.
타깃 체크가 켜져 있으면 .storekit 파일이 앱 번들 리소스에 포함되고, project.pbxproj 가 수정된다. 이때 Xcode 가 프로젝트 파일 형식(objectVersion 등)까지 함께 바꾸기도 한다.

로컬 테스트용 설정을 팀 저장소에 올리고 싶지 않다면, 테스트가 끝난 뒤 git status 로 변경을 확인하고 되돌립니다.

git status --short
git checkout -- ios/Runner.xcodeproj/project.pbxproj
git checkout -- ios/Runner.xcodeproj/xcshareddata/xcschemes/Runner.xcscheme

반대로 팀에서 같이 쓰고 싶다면, 타깃 체크를 해제한 상태로 .storekit 파일과 스킴 변경을 커밋해 두는 방법도 있습니다.

정리

StoreKit Configuration 파일을 만들고 앱과 같은 상품 ID 로 구독 상품을 추가한다.
Edit Scheme › Run › Options 의 StoreKit Configuration 에 연결한다. 빨간 글씨면 파일을 찾지 못한 것이다.
결제 시트에 Xcode 표시가 보이면 로컬 스토어로 동작하는 것이다.
상품 조회, 결제·취소, 구매 복원, 시작 시 백그라운드 복원은 시뮬레이터에서 확인할 수 있다.
거래가 Xcode 서명이라 서버 영수증 검증은 통과하지 못한다. 그 뒤의 흐름은 실기기와 샌드박스 계정으로 확인한다.
Manage Transactions 로 거래를 삭제·환불해 상태를 되돌릴 수 있고, ⚠ 표시는 finish() 가 아직 호출되지 않은 거래다.