본문 바로가기

iOS Subscription Group 생성

GitHub

구독 그룹은 iOS 앱에서 여러 구독 등급을 구성하고 관리하는 데 필수적입니다. 업그레이드, 다운그레이드, 크로스그레이드 기능을 구현하려면 작동 방식을 이해하는 것이 중요합니다.

구독 그룹은 사용자가 그중에서 선택할 수 있는 관련 구독의 모음입니다. 사용자는 한 번에 그룹 내 구독 하나만 구독할 수 있습니다. 구독을 전환하면 Apple이 전환을 자동으로 처리합니다.

구독 그룹의 중요성

“구독 그룹의 중요성” 섹션

구독 그룹은 다음을 가능하게 합니다:

  • 단계별 가격: 기본, 프리미엄, 얼티밋 플랜 제공
  • 다양한 기간: 월간, 연간, 평생 옵션
  • 업그레이드/다운그레이드 로직: 구독 변경 사항 자동 처리
  • 관리 간소화: 관련 구독을 하나의 그룹으로 묶음

그룹 내 각 구독은 가장 높은 가치(레벨 1)부터 가장 낮은 가치 순으로 순위를 매겨야 합니다. 이 순위에 따라 구독 변경 사항의 분류 방식이 결정됩니다:

구독 그룹 계층 구조

레벨 1 (가장 높은 가치)

  • 연간 프리미엄 ($99.99/년)
  • Ultimate 월간 ($19.99/월)

레벨 2 (중간 가치)

  • Standard 연간 ($49.99/년)
  • Premium 월간 ($9.99/월)

레벨 3 (최저 가치)

  • Basic 연간 ($29.99/년)
  • Standard 월간 ($4.99/월)

Apple은 등급 순위에 따라 세 가지 유형의 구독 변경을 자동으로 처리합니다:

상위 등급의 구독으로 이동하는 경우 (예: 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 time

상위 등급의 하위 등급 구독(예: 레벨 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 switches

다른 구독으로 전환 동일한 티어 수준에서.

기간에 따라 동작이 달라집니다:

기간이 다른 경우 → 다음과 같이 동작: 다운그레이드

  • 다음 갱신일에 적용됩니다
  • 예: 월간 프리미엄 (레벨 1) → 연간 프리미엄 (레벨 1)

동일 기간 → 다음과 같이 동작: 업그레이드

  • 즉시 적용
  • 예시: Premium Monthly (Level 1) → Ultimate Monthly (Level 1)
  1. Subscriptions로 이동

    App Store Connect에서 앱을 선택하고 다음으로 이동하세요: 수익화 > 구독.

  2. 그룹 생성

    클릭 + “Subscription Groups” 옆에 있는 버튼으로 새 그룹을 만듭니다.

  3. 그룹 이름 지정

    포함된 구독을 반영하는 설명적인 이름을 선택하세요:

    • “프리미엄 액세스”
    • “클라우드 스토리지 플랜”
    • “Pro 기능”
  4. 구독 추가

    그룹을 만든 후 개별 구독을 추가합니다. 각 구독에는 레벨 랭킹이 부여됩니다.

  5. 레벨 랭킹 설정

    가장 높은 가치(1)부터 가장 낮은 가치 순으로 구독을 정렬하세요. 다음을 고려하세요:

    • 연간 플랜은 월간 플랜보다 일반적으로 더 높은 랭킹을 받습니다
    • 높은 가격의 티어가 낮은 가격의 티어보다 위에 표시됩니다
    • Ultimate/premium 티어가 가장 위에 표시됩니다

native-purchases 플러그인은 구독 그룹 로직을 자동으로 처리합니다:

import { NativePurchases, PURCHASE_TYPE } from '@capgo/native-purchases';
// Fetch all subscriptions in a group
const { products } = await NativePurchases.getProducts({
productIdentifiers: ['premium_monthly', 'premium_annual', 'ultimate_monthly'],
productType: PURCHASE_TYPE.SUBS,
});
// Display current subscription using StoreKit transactions
const { 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 info
const { 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/downgrades
NativePurchases.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 리스너와 함께 사용하면 클라이언트와 백엔드가 동기화된 상태를 유지합니다.

  • 관련 구독은 같은 그룹에 두세요
  • 서로 무관한 기능은 섞지 마세요 (예: 스토리지, 광고 제거)
  • 기능 세트가 다르면 별도 그룹을 만드세요
  • 연간 플랜 → 같은 티어의 월간보다 높은 레벨
  • 가격이 높은 티어 → 더 높은 레벨
  • 가격만 보지 말고 가치를 고려하세요
  • 현재 구독을 명확하게 표시
  • 그룹 내 사용 가능한 모든 옵션 표시
  • 즉시 적용되는 변경과 갱신 시 적용되는 변경 구분
  • 플랜 간 쉬운 전환 허용
  • 모든 업그레이드 시나리오 테스트
  • 모든 다운그레이드 시나리오 테스트
  • 크로스그레이드 동작 확인
  • 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. 사용하기에서 네이티브 기능은