创建 iOS 订阅组

订阅组对于在 iOS 应用中组织和管理多个订阅层级至关重要。理解其工作方式，是实现升级、降级和同级切换功能的关键。

什么是订阅组？

订阅组是一组相关订阅，用户可在其中选择。用户同一时间只能订阅组内的一个订阅。当用户更换订阅时，Apple 会自动处理过渡。

为什么订阅组很重要

订阅组可以实现：

• 分层定价: 提供基础版、高级版和终极版方案
• 不同的订阅周期: 月度、年度及终身选项
• 升级/降级逻辑: 自动处理订阅变更
• 简化管理: 将相关的订阅组合在一起

订阅等级

在同一个组内，每个订阅应按价值从高到低（等级 1）进行排序。此排序决定了订阅变更的分类方式：

等级示例

等级 1 (最高价值)

• 高级年度订阅 ($99.99/年)
• 终极月度订阅 ($19.99/月)

等级 2 (中等价值)

• 标准年度订阅 ($49.99/年)
• 高级月度订阅 ($9.99/月)

等级 3 (最低价值)

• 基础年度订阅 ($29.99/年)
• 标准月度订阅 ($4.99/月)

订阅变更类型

Apple 会根据等级排名自动处理三种订阅变更类型：

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 (Level 1) → 按年 Premium (Level 1)

时长相同 → 表现类似于 升级

• 立即生效
• 示例：Premium Monthly (Level 1) → Ultimate Monthly (Level 1)

创建订阅组

1. 导航到“订阅”

   在 App Store Connect 中，选择您的 App 并前往 盈利 > 订阅.

2. 创建组

   点击 + 点击“Subscription Groups”旁边的按钮来创建新组。

3. 为订阅组命名

   请选择一个能体现其包含订阅内容的描述性名称：

   • “高级访问权限”
   • “Cloud Storage Plans”
   • “专业版功能”

4. 添加订阅项目

   创建订阅组后，请向其中添加具体的订阅项目。每个订阅项目都需要设置等级排名。

5. 设置等级排名

   将订阅项目按价值从高（1）到低进行排序。请考虑：

   • 年付方案的排名通常高于月付方案
   • 高价档位的排名应高于低价档位
   • Ultimate/premium 等级排名最高

在 App 中使用

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 权限，直到 [renewal date]，之后切换到 Standard。”

对于同级变更：

“您的方案将在下次续订（[date]）时改为按年计费。”

服务端监控

使用 Apple 的 App Store Server Notifications v2 或您自己的收据验证后端，将 StoreKit 的变更同步到您的数据库中。将服务器通知与 transactionUpdated listener 配合使用，以确保客户端和后端保持同步。

最佳实践

分组管理

• 将相关的订阅项放在同一分组中
• 不要混淆不相关的功能（例如：存储空间与广告移除）
• 为不同的功能集创建独立的分组

层级排序策略

• 年费方案 → 等级高于月费方案（同档位时）
• 价格更高的档位 → 等级更高
• 考虑价值，而不仅仅是价格

用户体验

• 清晰展示当前订阅状态
• 展示该分组下的所有可用选项
• 标明哪些变更立即生效，哪些在续订时生效
• 支持在不同方案间轻松切换

测试

• 测试所有升级场景
• 测试所有降级场景
• 验证同级方案切换 (crossgrade) 行为
• 检查 webhook 是否正常触发

常见场景

场景 1：三档月度订阅方案

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”状态
• 确保 Product ID 正确

升降级行为异常：

• 检查等级排名（1 = 最高）
• 确认订阅层级是否合理
• 检查等级设置是否正确

来自不同组的产品：

• 用户可以同时订阅多个组
• 这是有意为之 - 请将相关产品放在同一组

getActiveProducts 显示多个订阅：

• 检查订阅是否属于不同组
• 确认用户不是通过“家人共享”订阅的
• 在 App Store Connect 中检查订阅状态

更多资源

欲了解更多详情，请参阅 关于订阅组的 Apple 官方文档.

从“创建 iOS 订阅组”继续

如果你正在使用 创建 iOS 订阅组 要规划商店审核与分发，请将其与 使用 @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. 时的原生能力