创建 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.跨级

切换到同一级别的另一个订阅。

行为取决于持续时间：

不同的持续时间 → 行为类似于降级

在下一个续订日期生效
示例：每月保费（第 1 级）→ 年保费（第 1 级）

相同的持续时间 → 行为类似于升级

立即生效
示例：高级每月（级别 1）→ 终极每月（级别 1）

创建订阅组

导航至订阅

在 App Store Connect 中，选择您的应用并转到 获利 > 订阅。
创建群组

单击“订阅组”旁边的 ****** 以创建新组。
为组命名

选择一个反映其包含的订阅的描述性名称：
- “高级访问”
- “云存储计划”
- “专业功能”
添加订阅

创建组后，向其中添加个人订阅。每个订阅都会有一个级别排名。
设置等级排名将订阅从最高值 (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();
  }
});

用户沟通

始终清楚地传达变更行为：

对于升级：

“您将立即访问高级功能。我们将按比例分配您当前的订阅。”

对于降级：

“您将保留高级访问权限直到[续订日期]，然后切换到标准访问权限。”

对于跨年级：

“您的计划将在 [日期] 的下一次续订时更改为按年计费。”

服务器监控

使用 Apple 的 App Store 服务器通知 v2 或您自己的收据验证后端来镜像数据库中的 StoreKit 更改。将服务器通知与 transactionUpdated 侦听器配对，以便客户端和后端保持同步。

最佳实践

团体组织

将相关订阅保留在同一组中
不要混合不相关的功能（例如存储和广告删除）
为不同的功能集创建单独的组

等级排名策略

年度计划 → 比月度计划更高的级别（同级别）
价格较高的等级→更高级别
考虑价值，而不仅仅是价格

用户体验

清楚地显示当前订阅
显示组中所有可用选项
指出哪些更改是立即更改，哪些是更新时更改
允许在计划之间轻松切换

测试

测试所有升级场景
测试所有降级场景
验证跨级行为
检查 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)

每月→每年：Crossgrade（续订时）
年度 → 每月：降级（续订时）

场景 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 显示多个订阅：

检查订阅是否在不同的组中
验证用户未通过家庭共享订阅
在 App Store Connect 中查看订阅状态

其他资源

有关更多详细信息，请参阅有关订阅组的官方 Apple 文档。