iOS Subscription Groupの作成

GitHub

インストール手順と、このプラグインの完全なMarkdownガイドを含むセットアッププロンプトをコピーします。

iOSアプリで複数のサブスクリプションプランを整理・管理するには、サブスクリプショングループが不可欠です。アップグレード、ダウングレード、およびクロスグレード機能を実装するには、その仕組みを理解しておく必要があります。

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

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

サブスクリプショングループが重要な理由

サブスクリプショングループにより、以下が可能になります：

段階的な価格設定: ベーシック、プレミアム、アルティメットなどのプラン提供
異なる契約期間: 月額、年額、買い切りオプション
アップグレード/ダウングレードのロジック: サブスクリプション変更の自動処理
管理の簡素化: 関連するサブスクリプションをグループ化

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

グループ内では、各サブスクリプションを価値の高い順（レベル1）から低い順にランク付けする必要があります。このランクによって、サブスクリプションの変更内容が以下のように分類されます：

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

レベルの例

レベル 1 (最高価値)

プレミアム年間プラン ($99.99/年)
Ultimate 月額 ($19.99/month)

レベル 2 (中程度の価値)

Standard 年額 ($49.99/year)
Premium 月額 ($9.99/month)

レベル 3 (最も低い価値)

Basic 年額 ($29.99/year)
Standard 月額 ($4.99/month)

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

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

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 time

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 switches

3. クロスグレード

別のサブスクリプションへの切り替え 同じティアレベルで.

挙動は期間によって異なります：

期間が異なる場合 → 次の挙動になります： ダウングレード

次回の更新日に適用されます
例：月額Premium (レベル1) → 年額Premium (レベル1)

期間が同じ → 次の挙動になります： アップグレード

即座に適用されます
例: Premium Monthly (Level 1) → Ultimate Monthly (Level 1)

サブスクリプショングループの作成

Subscriptionsへ移動

App Store Connectでアプリを選択し、以下へ進みます 収益化 > サブスクリプション.
グループを作成

クリック + 「Subscription Groups」の横にあるボタンから新しいグループを作成します。
グループ名を入力

含まれるサブスクリプションの内容がわかる名前を選択してください：
- 「Premium Access」
- 「Cloud Storage Plans」
- 「Pro Features」
サブスクリプションを追加

グループ作成後、個別のサブスクリプションを追加します。各サブスクリプションにはレベル（順位）を設定できます。
レベル（順位）の設定

価値の高い順（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機能をご利用いただけます。現在のサブスクリプションは日割り計算されます。」

ダウングレードの場合：

「[renewal date]まではPremium機能をご利用いただけます。その後、Standardに切り替わります。」

クロスグレードの場合：

「次回の更新日である[date]に、プランが年払いへ変更されます。」

サーバーモニタリング

AppleのApp Store Server Notifications v2、または独自のレシート検証バックエンドを使用して、StoreKitの変更をデータベースに反映させます。サーバー通知を transactionUpdated listenerと組み合わせることで、クライアントとバックエンドの両方の同期を保つことができます。

ベストプラクティス

グループ編成

関連するサブスクリプションは同じグループにまとめる
無関係な機能（例：ストレージと広告削除）を混ぜない
機能セットごとに別のグループを作成する

レベルランキング戦略

年額プラン → 同一ティア内では月額より高いレベルに設定
高価格ティア → より高いレベルに設定
価格だけでなく、提供価値を考慮する

ユーザー体験

現在のサブスクリプションを明示する
グループ内の利用可能な全オプションを表示する
即時適用か更新時適用かを明示する
プラン間の切り替えを容易にする

テスト

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

よくあるシナリオ

シナリオ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: 期間が混在するプラン

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 でサブスク状況を確認

Create iOS Subscription Group の続きから進める

使用している場合 iOSサブスクリプショングループの作成 ストアの承認と配信を計画するには、これを次と連携させてください： @capgo/native-purchases を使用する Using @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. の使用」のネイティブ機能については