Getting Started

1. 安装包

   bun add @capgo/native-purchases

2. 同步本地项目

   bunx cap sync

3. 查看计费支持

   import { NativePurchases } from '@capgo/native-purchases';
   
   const { isBillingSupported } = await NativePurchases.isBillingSupported();
   if (!isBillingSupported) {
     throw new Error('Billing is not available on this device');
   }

4. 直接从商店中加载产品

   import { NativePurchases, PURCHASE_TYPE } from '@capgo/native-purchases';
   
   const { products } = await NativePurchases.getProducts({
     productIdentifiers: [
       'com.example.premium.monthly',
       'com.example.premium.yearly',
       'com.example.one_time_unlock'
     ],
     productType: PURCHASE_TYPE.SUBS, // Use PURCHASE_TYPE.INAPP for one‑time products
   });
   
   products.forEach((product) => {
     console.log(product.title, product.priceString);
   });

5. 实现购买和恢复流程

   import { NativePurchases, PURCHASE_TYPE } from '@capgo/native-purchases';
   
   const monthlyPlanId = 'monthly-plan'; // Base Plan ID from Google Play Console
   
   const transaction = await NativePurchases.purchaseProduct({
     productIdentifier: 'com.example.premium.monthly',
     planIdentifier: monthlyPlanId,        // REQUIRED for Android subscriptions, ignored on iOS
     productType: PURCHASE_TYPE.SUBS,
     quantity: 1,
   });
   
   console.log('Transaction ID', transaction.transactionId);
   
   await NativePurchases.restorePurchases();

   iOS 月度承诺计划

   如果支持的 iOS 订阅返回 pricingTerms您可以显示一个月度计费选项，带有 12 个月的承诺，并传递 billingPlanType: 'monthly' 到 purchaseProduct(). 请参见 iOS 月度承诺计费计划 为获取完整流程，请查看。

   iOS
   • 在 App Store Connect 中创建应用内产品和订阅。
     
   • 使用 StoreKit Local Testing 或 Sandbox 测试者进行 QA。
     
   • 不需要修改清单。确保您的产品已通过审批。
   Android
   • 在 Google Play Console 中创建应用内产品和订阅。
     
   • 上传至少一个内部测试版本并添加许可测试者。
     
   • 添加 AndroidManifest.xml:

   <uses-permission android:name="com.android.vending.BILLING" />

购买服务示例

import { NativePurchases, PURCHASE_TYPE, Transaction } from '@capgo/native-purchases';
import { Capacitor } from '@capacitor/core';

class PurchaseService {
  private premiumProduct = 'com.example.premium.unlock';
  private monthlySubId = 'com.example.premium.monthly';
  private monthlyPlanId = 'monthly-plan'; // Base Plan ID (Android only)

  async initialize() {
    const { isBillingSupported } = await NativePurchases.isBillingSupported();
    if (!isBillingSupported) throw new Error('Billing unavailable');

    const { products } = await NativePurchases.getProducts({
      productIdentifiers: [this.premiumProduct, this.monthlySubId],
      productType: PURCHASE_TYPE.SUBS,
    });

    console.log('Loaded products', products);

    if (Capacitor.getPlatform() === 'ios') {
      NativePurchases.addListener('transactionUpdated', (transaction) => {
        this.handleTransaction(transaction);
      });
    }
  }

  async buyPremium(appAccountToken?: string) {
    const transaction = await NativePurchases.purchaseProduct({
      productIdentifier: this.premiumProduct,
      productType: PURCHASE_TYPE.INAPP,
      appAccountToken,
    });

    await this.processTransaction(transaction);
  }

  async buyMonthly(appAccountToken?: string) {
    const transaction = await NativePurchases.purchaseProduct({
      productIdentifier: this.monthlySubId,
      planIdentifier: this.monthlyPlanId, // REQUIRED for Android subscriptions
      productType: PURCHASE_TYPE.SUBS,
      appAccountToken,
    });

    await this.processTransaction(transaction);
  }

  async restore() {
    await NativePurchases.restorePurchases();
    await this.refreshEntitlements();
  }

  async openManageSubscriptions() {
    await NativePurchases.manageSubscriptions();
  }

  private async processTransaction(transaction: Transaction) {
    this.unlockContent(transaction.productIdentifier);
    this.validateOnServer(transaction).catch(console.error);
  }

  private unlockContent(productIdentifier: string) {
    // persist entitlement locally
    console.log('Unlocked', productIdentifier);
  }

  private async refreshEntitlements() {
    const { purchases } = await NativePurchases.getPurchases({
      productType: PURCHASE_TYPE.SUBS,
    });
    console.log('Current purchases', purchases);
  }

  private async handleTransaction(transaction: Transaction) {
    console.log('StoreKit transaction update:', transaction);
    await this.processTransaction(transaction);
  }

  private async validateOnServer(transaction: Transaction) {
    await fetch('/api/validate-purchase', {
      method: 'POST',
      body: JSON.stringify({
        transactionId: transaction.transactionId,
        receipt: transaction.receipt,
        purchaseToken: transaction.purchaseToken,
      }),
    });
  }
}

必需购买选项

选项	平台	描述
productIdentifier	iOS + Android	在 App Store Connect / Google Play Console 中配置的 SKU/产品 ID。
productType	仅 Android	PURCHASE_TYPE.INAPP 或 PURCHASE_TYPE.SUBS. 默认为 INAPP. 总是设置为 SUBS 订阅时
planIdentifier	__CAPGO_KEEP_0__	__CAPGO_KEEP_1__
billingPlanType	__CAPGO_KEEP_2__	__CAPGO_KEEP_3__ 'monthly' __CAPGO_KEEP_4__ product.pricingTerms __CAPGO_KEEP_5__
quantity	__CAPGO_KEEP_6__	__CAPGO_KEEP_7__ 1__CAPGO_KEEP_8__
appAccountToken	__CAPGO_KEEP_9__	__CAPGO_KEEP_10__
isConsumable	__CAPGO_KEEP_11__	设置为 true 自动消费授权后消耗的令牌。默认为 false.

检查授权状态

使用 getPurchases() 查看每个商店报告的所有交易的跨平台视图：

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

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

purchases.forEach((purchase) => {
  if (purchase.isActive && purchase.expirationDate) {
    console.log('iOS sub active until', purchase.expirationDate);
  }

  const isAndroidIapValid =
    ['PURCHASED', '1'].includes(purchase.purchaseState ?? '') && purchase.isAcknowledged;

  if (isAndroidIapValid) {
    console.log('Grant in-app entitlement for', purchase.productIdentifier);
  }
});

平台行为

• iOS: 订阅包括 isActive, expirationDate, willCancel，和 StoreKit 2 监听器支持。内购需要服务器接收验证。
• Android: isActive/expirationDate 不提供此信息，请使用Google Play Developer API进行查询 purchaseToken 为获取最新信息，请访问官方网站。 purchaseState 必须 PURCHASED 和 isAcknowledged 必须 true.

API快速参考指南

• isBillingSupported() – 检查StoreKit / Google Play的可用性。
• getProduct() / getProducts() – 获取价格、本地化标题、描述、推广活动和支持的iOS定价条款。
• purchaseProduct() – 初始化StoreKit 2或Billing客户端购买流程，包括iOS月度承诺付款计划。
• restorePurchases() – 重放历史购买并同步到当前设备。
• getPurchases() – iOS 或 Play Billing 的所有交易列表.
• manageSubscriptions() – 打开本地订阅管理 UI.
• addListener('transactionUpdated') – 当应用启动时，处理待处理的 StoreKit 2 交易（仅限 iOS）。

最佳实践

1. 显示商店价格 – Apple 需要显示 product.title 且 product.priceString；绝不硬编码.
2. 使用 appAccountToken – 根据用户 ID 确定生成 UUID (v5) 以便将购买与帐户关联.
3. 在服务器端验证 – 发送 receipt (iOS) / purchaseToken (Android) 到您的后端进行验证。
4. 处理错误 – 检查用户取消、网络故障和不支持的计费环境。
5. 进行彻底的测试 – 遵循 iOS sandbox 指南 和 Android sandbox 指南.
6. 提供恢复 & 管理 – 添加 UI 按钮，连接到 restorePurchases() 和 manageSubscriptions().

收入下一步

购买流程完成后，使用 收入手册 规划您的第一个付费渠道：产品范围、ASO、定价、付费墙位置、分析和流失反馈。

故障排除

产品未加载

• 确保bundle ID/应用程序ID与商店配置匹配。
• 确认产品ID处于激活状态并已批准（App Store）或激活（Google Play）。
• 创建产品后等待几小时；商店传播不是即时的。

购买已取消或卡住

• 用户可以在流程中取消;.wrap调用在 try/catch 并显示友好的错误消息。
• 对于 Android，确保测试帐户从 Play Store（内部跟踪）安装应用程序，以便Billing正常工作。
• 在设备上运行时，检查logcat/Xcode以查找billing错误。

订阅状态不正确

• 使用 getPurchases() 来比较商店数据与您的本地权利缓存。
• On Android, always query the Google Play Developer API with the purchaseToken 来获取过期日期或退款状态。
• 在 iOS 上，检查 isActive/expirationDate 并验证收据以检测退款或撤销

继续从 Getting Started

如果您正在使用 Getting Started 来规划商店审批和分发，连接它到 使用 @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 的本地能力