iOS Subscription Group 생성
이 플러그인의 설치 단계와 전체 마크다운 가이드가 포함된 설정 프롬프트를 복사하세요.
구독 그룹은 iOS 앱에서 여러 구독 등급을 구성하고 관리하는 데 필수적입니다. 업그레이드, 다운그레이드, 크로스그레이드 기능을 구현하려면 작동 방식을 이해하는 것이 중요합니다.
구독 그룹이란?
“구독 그룹이란?” 섹션구독 그룹은 사용자가 그중에서 선택할 수 있는 관련 구독의 모음입니다. 사용자는 한 번에 그룹 내 구독 하나만 구독할 수 있습니다. 구독을 전환하면 Apple이 전환을 자동으로 처리합니다.
구독 그룹의 중요성
“구독 그룹의 중요성” 섹션구독 그룹은 다음을 가능하게 합니다:
- 단계별 가격: 기본, 프리미엄, 얼티밋 플랜 제공
- 다양한 기간: 월간, 연간, 평생 옵션
- 업그레이드/다운그레이드 로직: 구독 변경 사항 자동 처리
- 관리 간소화: 관련 구독을 하나의 그룹으로 묶음
구독 레벨
“구독 레벨” 섹션그룹 내 각 구독은 가장 높은 가치(레벨 1)부터 가장 낮은 가치 순으로 순위를 매겨야 합니다. 이 순위에 따라 구독 변경 사항의 분류 방식이 결정됩니다:

레벨 예시
“레벨 예시” 섹션레벨 1 (가장 높은 가치)
- 연간 프리미엄 ($99.99/년)
- Ultimate 월간 ($19.99/월)
레벨 2 (중간 가치)
- Standard 연간 ($49.99/년)
- Premium 월간 ($9.99/월)
레벨 3 (최저 가치)
- Basic 연간 ($29.99/년)
- Standard 월간 ($4.99/월)
구독 변경 유형
“구독 변경 유형” 섹션Apple은 등급 순위에 따라 세 가지 유형의 구독 변경을 자동으로 처리합니다:
1. 업그레이드
“1. 업그레이드” 섹션상위 등급의 구독으로 이동하는 경우 (예: 2등급 → 1등급).
동작:
- 즉시 적용됩니다
- 사용자는 남은 기간에 대한 일할 계산 환불을 받습니다
- 새 구독이 즉시 시작됩니다
예시:
// User currently has: Standard Monthly (Level 2)// User upgrades to: Premium Annual (Level 1)// Result: Immediate access to Premium, refund for unused Standard time2. 다운그레이드
“2. 다운그레이드” 섹션상위 등급의 하위 등급 구독(예: 레벨 1 → 레벨 2).
동작:
- 다음 갱신일에 적용됩니다
- 사용자는 기간이 끝날 때까지 현재 구독을 유지합니다
- 만료 후 새 구독이 자동으로 시작됩니다
예시:
// User currently has: Premium Annual (Level 1)// User downgrades to: Standard Monthly (Level 2)// Result: Premium access continues until annual renewal date, then switches3. 크로스그레이드
“3. 크로스그레이드” 섹션다른 구독으로 전환 동일한 티어 수준에서.
기간에 따라 동작이 달라집니다:
기간이 다른 경우 → 다음과 같이 동작: 다운그레이드
- 다음 갱신일에 적용됩니다
- 예: 월간 프리미엄 (레벨 1) → 연간 프리미엄 (레벨 1)
동일 기간 → 다음과 같이 동작: 업그레이드
- 즉시 적용
- 예시: Premium Monthly (Level 1) → Ultimate Monthly (Level 1)
구독 그룹 생성
“구독 그룹 생성” 섹션-
Subscriptions로 이동
App Store Connect에서 앱을 선택하고 다음으로 이동하세요: 수익화 > 구독.
-
그룹 생성
클릭 + “Subscription Groups” 옆에 있는 버튼으로 새 그룹을 만듭니다.
-
그룹 이름 지정
포함된 구독을 반영하는 설명적인 이름을 선택하세요:
- “프리미엄 액세스”
- “클라우드 스토리지 플랜”
- “Pro 기능”
-
구독 추가
그룹을 만든 후 개별 구독을 추가합니다. 각 구독에는 레벨 랭킹이 부여됩니다.
-
레벨 랭킹 설정
가장 높은 가치(1)부터 가장 낮은 가치 순으로 구독을 정렬하세요. 다음을 고려하세요:
- 연간 플랜은 월간 플랜보다 일반적으로 더 높은 랭킹을 받습니다
- 높은 가격의 티어가 낮은 가격의 티어보다 위에 표시됩니다
- Ultimate/premium 티어가 가장 위에 표시됩니다
앱에서 사용하기
“앱에서 사용하기” 섹션native-purchases 플러그인은 구독 그룹 로직을 자동으로 처리합니다:
import { NativePurchases, PURCHASE_TYPE } from '@capgo/native-purchases';
// Fetch all subscriptions in a groupconst { products } = await NativePurchases.getProducts({ productIdentifiers: ['premium_monthly', 'premium_annual', 'ultimate_monthly'], productType: PURCHASE_TYPE.SUBS,});
// Display current subscription using StoreKit transactionsconst { purchases } = await NativePurchases.getPurchases({ productType: PURCHASE_TYPE.SUBS,});
const activeSubs = purchases.filter((purchase) => purchase.isActive);
// Detect pending downgrade/cancellation (StoreKit sets willCancel === true)const pendingChange = purchases.find((purchase) => purchase.willCancel === true);if (pendingChange) { console.log('Subscription will stop auto-renewing on', pendingChange.expirationDate);}
// Purchase (StoreKit handles upgrades/downgrades automatically)await NativePurchases.purchaseProduct({ productIdentifier: 'premium_annual', productType: PURCHASE_TYPE.SUBS,});
// Listen for StoreKit updates (fires on upgrades/downgrades/refunds)NativePurchases.addListener('transactionUpdated', (transaction) => { console.log('Subscription updated:', transaction);});구독 변경 처리
“구독 변경 처리” 섹션변경 유형 감지
“변경 유형 감지” 섹션import { NativePurchases, PURCHASE_TYPE } from '@capgo/native-purchases';
// Get current subscription infoconst { purchases } = await NativePurchases.getPurchases({ productType: PURCHASE_TYPE.SUBS,});
const currentSubscription = purchases.find( (purchase) => purchase.subscriptionState === 'subscribed',);
if (currentSubscription) { // StoreKit reports if user cancelled auto-renew if (currentSubscription.willCancel) { console.log( `User cancelled. Access remains until ${currentSubscription.expirationDate}`, ); }
if (currentSubscription.isUpgraded) { console.log('User recently upgraded to this plan.'); }}
// Listen for automatic upgrades/downgradesNativePurchases.addListener('transactionUpdated', (transaction) => { console.log('Subscription changed!', transaction); if (transaction.subscriptionState === 'revoked') { revokeAccess(); } else if (transaction.isActive) { unlockPremiumFeatures(); }});사용자 커뮤니케이션
“사용자 커뮤니케이션” 섹션변경 사항은 항상 명확하게 안내하세요:
업그레이드 시:
“Premium 기능을 즉시 이용할 수 있습니다. 현재 구독 요금은 일할 계산됩니다.”
다운그레이드 시:
“[갱신일]까지 Premium 이용 권한이 유지되며, 이후 Standard로 전환됩니다.”
플랜 변경(Crossgrade) 시:
“다음 갱신일인 [날짜]에 연간 결제 플랜으로 변경됩니다.”
서버 모니터링
“서버 모니터링” 섹션Apple의 App Store Server Notifications v2 또는 자체 영수증 검증 백엔드를 사용해 StoreKit 변경 사항을 데이터베이스에 반영하세요. 서버 알림을 transactionUpdated 리스너와 함께 사용하면 클라이언트와 백엔드가 동기화된 상태를 유지합니다.
모범 사례
“권장 사항” 섹션그룹 구성
“그룹 구성” 섹션- 관련 구독은 같은 그룹에 두세요
- 서로 무관한 기능은 섞지 마세요 (예: 스토리지, 광고 제거)
- 기능 세트가 다르면 별도 그룹을 만드세요
레벨 랭킹 전략
“레벨 랭킹 전략” 섹션- 연간 플랜 → 같은 티어의 월간보다 높은 레벨
- 가격이 높은 티어 → 더 높은 레벨
- 가격만 보지 말고 가치를 고려하세요
사용자 경험
“User Experience” 섹션- 현재 구독을 명확하게 표시
- 그룹 내 사용 가능한 모든 옵션 표시
- 즉시 적용되는 변경과 갱신 시 적용되는 변경 구분
- 플랜 간 쉬운 전환 허용
테스트
“테스트” 섹션- 모든 업그레이드 시나리오 테스트
- 모든 다운그레이드 시나리오 테스트
- 크로스그레이드 동작 확인
- webhook 발생 확인
일반 시나리오
“일반적인 시나리오” 섹션시나리오 1: 3단계 월간 요금제
“시나리오 1: 3단계 월간 요금제” 섹션Level 1: Ultimate Monthly ($19.99)Level 2: Premium Monthly ($9.99)Level 3: Basic Monthly ($4.99)- Basic → Premium: 업그레이드 (즉시 적용)
- Premium → Ultimate: 업그레이드 (즉시 적용)
- Ultimate → Premium: 다운그레이드 (갱신 시 적용)
- Basic → Ultimate: 업그레이드 (즉시 적용)
시나리오 2: 혼합 기간 요금제
“시나리오 2: 혼합 기간 요금제” 섹션Level 1: Premium Annual ($99.99/year)Level 2: Premium Monthly ($9.99/month)- 월간 → 연간: 크로스그레이드 (갱신 시 적용)
- 연간 → 월간: 다운그레이드(갱신 시)
시나리오 3: 멀티 티어 및 멀티 기간
“시나리오 3: 멀티 티어 멀티 기간” 섹션Level 1: Ultimate Annual ($199/year)Level 2: Ultimate Monthly ($19.99/month)Level 3: Premium Annual ($99/year)Level 4: Premium Monthly ($9.99/month)Level 5: Basic Annual ($49/year)Level 6: Basic Monthly ($4.99/month)이 설정은 명확한 업그레이드/다운그레이드 로직을 유지하면서 최대의 유연성을 제공합니다.
문제 해결
“문제 해결” 섹션그룹에 구독이 표시되지 않는 경우:
- 올바른 그룹에 할당되었는지 확인하세요
- 최소 “제출 준비 완료” 상태인지 확인하세요
- 제품 ID가 올바른지 확인하세요
업그레이드/다운그레이드 동작 오류:
- 레벨 순위 검토 (1 = 최고)
- 구독 티어가 적절한지 확인
- 레벨이 올바르게 설정되었는지 확인
다른 그룹의 제품:
- 사용자는 여러 그룹에 동시에 구독할 수 있습니다
- 이것은 의도된 동작입니다 - 관련 제품을 같은 그룹에 유지하세요
getActiveProducts에 여러 구독이 표시되는 경우:
- 구독이 서로 다른 그룹에 있는지 확인
- 사용자가 Family Sharing을 통해 구독 중이 아닌지 확인
- App Store Connect에서 구독 상태 검토
추가 리소스
“추가 리소스” 섹션자세한 내용은 구독 그룹에 관한 Apple 공식 문서.
iOS Subscription Group 생성 단계부터 계속하기
섹션 제목: “Create iOS Subscription Group”에서 계속하기사용 중이라면 iOS Subscription Group 생성 스토어 승인 및 배포를 계획하려면, 다음 항목과 연결하세요 @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. 사용하기에서 네이티브 기능은