创建 iOS 订阅组

GitHub

复制一个包含安装步骤和本插件的完整 Markdown 指南的设置提示.

订阅组对于在 iOS 应用中组织和管理多个订阅级别至关重要。了解它们的工作原理对于实现升级、降级和交叉级别功能至关重要。

什么是订阅组?

一个订阅组是用户可以选择的相关订阅的集合。用户只能在一个组内订阅一个订阅。他们切换订阅时，苹果会自动处理转换。

为什么订阅组很重要

订阅组使得：

阶梯式定价：提供基本、精英和终极计划
不同时间段：月度、年度和终身选项
升级/降级逻辑：自动处理订阅变化
简化管理: 分组相关订阅

订阅等级

在一个组内，每个订阅应该按从最高价值（等级1）到最低价值的顺序排列。这个排列决定了订阅变化的分类：

订阅组层级

等级示例

等级1 (最高价值)

年度高级版（$99.99/年）
月度最高版（$19.99/月）

等级2 (Medium Value)

年度标准版 ($49.99/年)
月度高级版 ($9.99/月)

等级 3 (最低值)

年度基本版 ($29.99/年)
月度标准版 ($4.99/月)

订阅变更类型

苹果会自动处理三个订阅级别的变更类型：

1. 升级

升级到更高级别的订阅（例如，级别 2 → 级别 1）。 行为： 立即生效

用户收到剩余时间的部分退款

新订阅立即开始 示例：
复制到剪贴板 protectedTokens targetLanguage
texts

Behavior:

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

同时长 → 与升级

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

创建订阅组

前往订阅

在 App Store Connect 中，选择您的应用并转到 收入 > 订阅.
创建组

点击 + 订阅组
创建新组

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

在创建组后，添加单个订阅到它中。每个订阅将有一个级别排名。
设置级别排名

按从最高价值（1）到最低价值的顺序排列订阅。考虑：
- 年度计划通常比月度计划排名更高
- 价格更高的等级排在价格更低的等级之上
- 最终/高级等级排名最高

在您的应用中使用

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

用户沟通

始终清晰地传达变化行为：

For Upgrades:

您将立即获得高级功能的访问权。我们将根据您的当前订阅进行折扣。

降级:

您将保留高级访问权直到 [renewal date]，然后切换到标准。

跨级别升级:

您的计划将在下一次续订时 [date] 更改为年度计费。

服务器监控

使用 Apple 的 App Store Server Notifications v2 或您的自己的收据验证后端来反映 StoreKit 的更改。将服务器通知与监听器配对，以便客户端和后端保持同步。 transactionUpdated 最佳实践

标题：最佳实践

标题：组组织

将相关订阅放在同一组中
不要混杂无关的功能（例如，存储和广告移除）
为不同功能集创建单独的组

等级排名策略

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

用户体验

清晰显示当前订阅
显示所有可用选项
标识哪些变更立即生效，哪些在续费时生效
方便地在计划之间切换

测试

测试所有升级场景
测试所有降级场景
验证跨级别升级行为
检查 webhook 触发

常见场景

场景 1：每月三层计划

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

基本 → 高级: 立即升级
高级 → 最终: 立即升级
最终 → 高级: 在续费时降级
基本 → 最终: 立即升级

Scenario 2: 混合时长计划

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

月度 → 年度: 在续费时升级
年度 → 月度: 在续费时降级

Scenario 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中检查订阅状态

继续从创建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 的本地能力