Create iOS Subscription Group

このプラグインのインストール手順とフルマークダウンガイドを含むセットアッププロンプトをコピーします。

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

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

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

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

サブスクリプショングループにより

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

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

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

サブスクリプショングループ階層

レベル例

(最高値) プレミアム年間 ($99.99/年)

アウトレーチャー月額 ($19.99/月)
レベル 2

(中間値) スタンダード年間 ($49.99/年)

レベル例
プレミアム月額 ($9.99/月)

レベル 3 (最低値)

ベーシック年額 ($29.99/年)
スタンダード月額 ($4.99/月)

サブスクリプション変更の種類

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

1. アップグレード

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

動作:

__CAPGO_KEEP_0__ __CAPGO_KEEP_1__
__CAPGO_KEEP_2__ __CAPGO_KEEP_3__ __CAPGO_KEEP_4__
__CAPGO_KEEP_5__

__CAPGO_KEEP_6__

// 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. ダウングレード

Moving to a lower-tier subscription (e.g., level 1 → level 2).

Behavior:

Takes effect at next renewal date
User keeps current subscription until period ends
New subscription starts automatically after expiration

Example:

// User currently has: Premium Annual (Level 1)
// User downgrades to: Standard Monthly (Level 2)
// Result: Premium access continues until annual renewal date, then switches

3. Crossgrade

別のサブスクリプションに切り替える 同じレベルで.

期間が異なる場合の挙動は

期間が異なる → 以下の挙動が同じ 下げる

次回の更新日以降に効果が生じる
例：月額プレミアム（レベル1） → 年額プレミアム（レベル1）

同じ期間 → 以下の挙動が同じ 上げる

効果は即時
Example: Premium Monthly (Level 1) → Ultimate Monthly (Level 1)

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

サブスクリプションに移動する

App Store Connectで、自分のアプリを選択し、 Monetize > サブスクリプション.
グループを作成する

グループを作成する + サブスクリプショングループの右側にある「+」をクリックして、新しいグループを作成する
グループの名前を付けます

サブスクリプショングループに含まれるサブスクリプションを反映した、説明的な名前を選択してください:
- “プレミアムアクセス”
- “クラウドストレージプラン”
- “プロ機能”
サブスクリプションを追加

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

サブスクリプションを値の高いものから低いものまで並べる。考慮する点は:
- 年間プランは月額プランよりもランクが高い
- 価格が高い層は価格が低い層よりも上にランク付けされる
- プレミアム/最高ランクの層は一番上にランク付けされる

アプリ内での使用

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

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

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

常に変更の動作を明確に伝えます:

アップグレードの場合:

「プレミアム機能に即時アクセスできます。現在のサブスクリプションを割引します。」

ダウングレードの場合:

“[renewal date] までプレミアムアクセスを維持し、その後標準に切り替わります。”

クロスグレード用:

“次回の更新時点で、[date] から年間課金プランに変更されます。”

サーバーモニタリング

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

「ベストプラクティス」

「グループの組織」

For Crossgrades:
別の機能を組み合わせないでください（例：ストレージと広告の削除）
異なる機能セットごとに別のグループを作成してください

レベルランキング戦略

年間プラン → 月額プランと同じレベルでは高レベル
価格が高いプラン → 高レベル
価格だけではなく価値を考慮してください

ユーザー体験

現在のサブスクリプションを明示的に表示してください
グループ内で利用可能なすべてのオプションを表示してください
即時変更と再契約時に変更される変更を区別してください
プランを簡単に切り替える

テスト

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

共通シナリオ

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

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

トラブルシューティング

グループ内で表示されないサブスクリプション:

正しいグループに割り当てられていることを確認してください
「Ready to Submit」ステータス以上であることを確認してください
製品IDが正しいことを確認してください

アップグレード/ダウングレードの不正な動作:

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

異なるグループの製品:

複数のグループに同時に登録することができます
関連する製品を同じグループに保つため、意図的に行っています

getActiveProducts: 複数のサブスクリプションを表示

サブスクリプションが異なるグループにあるかどうかを確認する
ファミリーシェアリングを介してサブスクリプションされていないことを確認する
App Store Connectでサブスクリプションの状態を確認する

追加リソース

詳細については、サブスクリプショングループに関する公式のAppleドキュメントを参照してください.