iOS 月度承诺计费方案

Apple 支持按月扣费但要求客户承诺 12 个月期限的订阅。当 StoreKit 和当前运行的操作系统支持此计费计划时， @capgo/native-purchases 它会展示定价条款，允许你在购买时选择按月计费计划，并在交易和续订信息中返回承诺元数据。

适用于用户倾向于按月支付，但您仍希望获得年度承诺期带来的留存和可预测性的场景。

要求

• 在 App Store Connect 或 Xcode 的 StoreKit Testing 中配置“按月支付、12 个月承诺期”的计费方案。
• 使用包含 StoreKit 的 Xcode SDK 构建 iOS 应用 pricingTerms 以及 billingPlanType.
• 在支持 StoreKit 承诺计费方案的 iOS 版本上运行。
• 对于不返回承诺定价条款的设备或商店地区，请保留标准计费选项。

注意

JavaScript API 在所有平台上调用都是安全的。不支持的平台只是不会返回 pricingTerms，而 Android 会忽略 billingPlanType.

加载并展示价格条款

调用 getProducts() 照常。对于受支持的 iOS 订阅产品，每个产品可以包含 pricingTerms.

import { NativePurchases, PURCHASE_TYPE } from '@capgo/native-purchases';

const { products } = await NativePurchases.getProducts({
  productIdentifiers: ['com.example.app.premium.yearly'],
  productType: PURCHASE_TYPE.SUBS,
});

const premiumYearly = products.find(
  (product) => product.identifier === 'com.example.app.premium.yearly',
);
const monthlyCommitment = premiumYearly?.pricingTerms?.find(
  (term) => term.billingPlanType === 'monthly',
);

渲染商店提供的数值，而非硬编码的价格：

字段	用途
billingDisplayPrice	向用户展示的周期性计费金额，例如月费。
billingPeriod	所展示价格对应的计费周期。
commitmentInfo.priceString	按用户所在商店格式化后的承诺总价。
commitmentInfo.period	完整的承诺期。
subscriptionOffers	与定价期限绑定的入门或促销优惠。

付费墙文案示例：

function commitmentLabel(term: NonNullable<typeof monthlyCommitment>) {
  const total = term.commitmentInfo?.priceString;
  return total
    ? `${term.billingDisplayPrice} billed monthly, ${total} total commitment`
    : term.billingDisplayPrice;
}

购买月度承诺计划

当用户选择月度承诺计划时，传入 billingPlanType: 'monthly'.

const transaction = await NativePurchases.purchaseProduct({
  productIdentifier: 'com.example.app.premium.yearly',
  productType: PURCHASE_TYPE.SUBS,
  billingPlanType: 'monthly',
  appAccountToken: userStoreUuid,
});

使用 billingPlanType: 'upFront' 仅在需要显式选择标准预付费计费方案时传入。如果省略 billingPlanType，StoreKit 会使用该产品的默认购买行为。

提示

让 paywall 状态与用户点击的定价周期保持一致。如果 pricingTerms 缺失时，隐藏承诺选项并显示常规订阅购买按钮。

读取承诺元数据

StoreKit 提供时，交易会包含计费计划和承诺进度：

if (transaction.billingPlanType === 'monthly') {
  console.log('Current billing period:', transaction.commitmentInfo?.billingPeriodNumber);
  console.log('Total billing periods:', transaction.commitmentInfo?.totalBillingPeriods);
  console.log('Commitment ends:', transaction.commitmentInfo?.expirationDate);
  console.log('Commitment total:', transaction.commitmentInfo?.price);
}

续订信息可能包含下一承诺状态：

const { purchases } = await NativePurchases.getPurchases({
  productType: PURCHASE_TYPE.SUBS,
  onlyCurrentEntitlements: true,
});

for (const purchase of purchases) {
  const commitment = purchase.renewalInfo?.commitmentInfo;
  if (!commitment) continue;

  console.log('Renews into another commitment:', commitment.willAutoRenew);
  console.log('Next billing plan:', commitment.renewalBillingPlanType);
  console.log('Next renewal date:', commitment.renewalDate);
}

使用顶层 expirationDate 以及 isActive 用于权益决策的字段。使用 commitmentInfo.expirationDate 向客户说明完整的承诺周期。

App Store 审核备注

• 购买前同时显示订阅续费价格和承诺期总价。
• 在购买按钮附近明确标注承诺期长度。
• 使用 product.title, product.priceString, pricingTerms[].billingDisplayPrice，以及 pricingTerms[].commitmentInfo.priceString 从 StoreKit 获取，而非使用硬编码价格。
• 在付费墙或账户页面提供恢复购买和管理订阅操作。

相关指南

• 创建 iOS 订阅
• 配置 iOS 沙盒测试
• iOS App Store 审核指南

从 iOS 月度承诺计费计划继续

如果你正在使用 iOS 月度承诺计费计划 要规划付款和购买，请将其与 使用 @capgo/native-purchases 关于“使用 @capgo/native-purchases”中的原生能力， Capgo 定价 关于 Capgo 定价中的产品工作流， 支付系统 了解支付系统的实现细节， @capgo/native-purchases 有关 @capgo/native-purchases 中的实现细节，以及 快速入门 有关 Getting Started 中的实现细节，请参阅