Create iOS Subscription Group

サブスクリプション グループは、iOS アプリで複数のサブスクリプション レベルを管理するために不可欠です。サブスクリプション グループのしくみを理解することは、アップグレード、ダウン グレード、クロス グレード機能を実装するために不可欠です。

サブスクリプション グループとは何か

サブスクリプション グループとは、ユーザーが選択できる関連するサブスクリプションの集合です。ユーザーは、グループ内で 1 つのサブスクリプションにのみサブスクライブできます。サブスクリプションを切り替えると、Apple は自動的に移行を処理します。

サブスクリプション グループの重要性

サブスクリプション グループを有効にする

• 段階的な価格設定: 基本、プレミアム、そして最高のプランを提示する
• 異なる期間: 月単位、年単位、そしてライフタイムのオプション
• アップグレード/ダウングレード ロジック: サブスクリプションの変更を自動的に処理する
• 簡略化された管理: 関連するサブスクリプションをグループ化する

サブスクリプション レベル

グループ内では、各サブスクリプションは、値の高い順 (レベル 1) から低い順にランク付けされる必要があります。このランク付けは、サブスクリプションの変更がどのように分類されるかを決定します:

レベル例

レベル1 (最高値)

• プレミアム 年額 ($99.99/年)
• アクティベート 月額 ($19.99/月)

レベル2 (中間値)

• スタンダード 年額 ($49.99/年)
• プレミアム 月額 ($9.99/月)

レベル3 __CAPGO_KEEP_0__

• ベース プラン (年額 $29.99)
• スタンダード 月額 (月額 $4.99)

__CAPGO_KEEP_1__

レベルランキングに基づいて、Appleは3種類のサブスクリプション変更を自動的に処理します。

1. アップグレード

より高いレベルのサブスクリプションに切り替える (例: レベル 2 → レベル 1). 動作: __CAPGO_KEEP_4__

__CAPGO_KEEP_5__

• 即時有効 直ちに
• ユーザーは 残り期間分の割引 残り期間
• 新しいサブスクリプションはすぐに始まります

例えば

// User currently has: Standard Monthly (Level 2)
// User upgrades to: Premium Annual (Level 1)
// Result: Immediate access to Premium, refund for unused Standard time

2. ダウングレード

より低いレベルの より低いレベルに サブスクリプション (例: level 1 → level 2).

動作:

• __CAPGO_KEEP_0__ 期限切れまでの現在のサブスクリプションを保持する
• 期限切れ後、自動で新しいサブスクリプションが開始される
• 例:

コピー

// 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)

期間が同じ → 上位のプランに切り替える

• 即時効果
• 例: プレミアム月額 (レベル 1) → アンリミテッド月額 (レベル 1)

サブスクリプション グループを作成する

1. サブスクリプションに移動

   App Store Connectで、アプリを選択し、 Monetize > サブスクリプション.

2. グループの作成

   「サブスクリプション グループ」に隣接する + グループの名前

3. 選択したサブスクリプションを含むサブスクリプションを反映した説明的な名前を選択してください:

   「プレミアム アクセス」

   • 「クラウド ストレージ プラン」
   • 「プロ機能」
   • __CAPGO_KEEP_0__

4. サブスクリプションを追加

   グループを作成した後、個別のサブスクリプションを追加します。各サブスクリプションにはレベルランキングがあります。

5. レベルランキングを設定

   サブスクリプションを、値が高い順 (1) から低い順に並びます。考慮する点は次のとおりです。

   • 年間プランは月額プランよりもランクが高い
   • 価格が高い層は価格が低い層よりも上にランク付けされる
   • プレミアム/最高ランクの層は一番上にランク付けされる

アプリ内での使用

ネイティブ購入プラグインは、サブスクリプション グループ ロジックを自動的に処理します。

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();
  }
});

ユーザーとのコミュニケーション

アップグレードの場合:

For Upgrades:

ダウングレードの場合:

For Downgrades:

クロスグレードの場合:

For Crossgrades:

“年間課金に切り替えます。次回の更新日 [date] に。”

サーバーモニタリング

App Store Server Notifications v2 を使用して、StoreKit の変更をデータベースに反映するために、Apple の App Store Server Notifications v2 または独自の受領検証バックエンドを使用します。サーバーノーティフィケーションをリスナーと組み合わせて、クライアントとバックエンドが同期されるようにします。 transactionUpdated ベストプラクティス

グループの組織

無関係な機能 (例：ストレージと広告の削除) を混ぜない

• __CAPGO_KEEP_0__
• __CAPGO_KEEP_0__
• __CAPGO_KEEP_0__

レベルランキング戦略

• 年間プラン → 月額と同じレベルでは上位
• 価格が高いレベル → 上位
• 価格だけではなく価値を考慮する

ユーザー体験

• 現在のサブスクリプションを明確に表示する
• グループ内のすべてのオプションを表示する
• 即時変更と再契約時に変更される変更を示す
• プランを簡単に切り替える

テスト

• すべてのアップグレードシナリオをテストする
• すべてのダウングレードシナリオをテストする
• クロスグレード動作を確認する
• ウェブホックの発火を確認する

共通シナリオ

シナリオ 1: 月額 3 つのレベル

Level 1: Ultimate Monthly ($19.99)
Level 2: Premium Monthly ($9.99)
Level 3: Basic Monthly ($4.99)

• 基本 → プレミアム: 即時アップグレード
• プレミアム → アンリミテッド: 即時アップグレード
• プレミアム → 絶対: 下位互換 (再契約時)
• ベーシック → 絶対: アップグレード (即時)

シナリオ 2: 混合期間プラン

Level 1: Premium Annual ($99.99/year)
Level 2: Premium Monthly ($9.99/month)

• 月 → 年: クロスグレード (再契約時)
• 年 → 月: 下位互換 (再契約時)

シナリオ 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)

この設定では、明確なアップグレード/ダウングレードロジックを維持しながら、最大限の柔軟性を提供します。

トラブルシューティング

__CAPGO_KEEP_0__がグループに表示されない:

• 正しいグループに割り当てられていることを確認してください
• 少なくとも「提出準備中」のステータスにあることを確認してください
• 製品IDが正しいことを確認してください

アップグレード/ダウングレードの挙動が間違っている:

• レベルランキングを確認してください (1 = 最高)
• サブスクリプションの階層が意味をなしていることを確認してください
• レベルが正しく設定されていることを確認してください

異なるグループの製品:

• ユーザーは同時に複数のグループにサブスクライブできる:
• これは意図的な動作です - 関連する製品は同じグループに残してください

getActiveProducts showing multiple subscriptions:

• Check if subscriptions are in different groups
• Verify user isn’t subscribed via Family Sharing
• Review subscription status in App Store Connect

Additional Resources

For more details, refer to the official documentation on subscription groups.

Keep going from Create iOS Subscription Group

If you are using Create iOS Subscription Group to plan store approval and distribution, connect it with Using @capgo/native-purchases for the native capability in Using @capgo/native-purchases, @capgo/capacitor-in-app-review for the implementation detail in @capgo/capacitor-in-app-review, Using @capgo/capacitor-in-app-review for the native capability in Using @capgo/capacitor-in-app-review, @capgo/capacitor-native-market for the implementation detail in @capgo/capacitor-native-market, and Using @capgo/capacitor-native-market for the native capability in Using @capgo/capacitor-native-market.