跳过内容
Capgo - Capacitor 应用程序的实时更新 Capgo

开始

GitHub

安装

名为“安装”的部分

您可以使用我们的AI辅助设置来安装插件。将Capgo技能添加到您的AI工具中，使用以下命令：

终端窗口
npx skills add https://github.com/Cap-go/capgo-skills --skill capacitor-plugins

然后使用以下提示:

Use the `capacitor-plugins` skill from `Cap-go/capgo-skills` to install the `@capgo/native-purchases` plugin in my project.

如果您更喜欢手动设置，请按照以下命令安装插件并遵循以下平台特定的说明:

  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();
    • 在 App Store Connect 中创建应用内产品和订阅。
    • 使用 StoreKit 本地测试或沙盒测试者进行 QA。
    • 无需修改清单。确保您的产品已获得批准。

应用内购买服务示例

应用内购买服务示例
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,
      }),
    });
  }
}

必填购买选项

必填购买选项
选项平台描述
productIdentifieriOS + Android在 App Store Connect 或 Google Play Console 中配置的 SKU/产品 ID
productType仅限 AndroidPURCHASE_TYPE.INAPP 或 PURCHASE_TYPE.SUBS. 默认值 INAPP. 始终设置为 SUBS 用于订阅
planIdentifierAndroid 订阅Google Play Console 中的基本计划 ID。用于订阅，忽略 iOS 和内购。
billingPlanTypeiOS 订阅StoreKit billing 计划用于购买。使用 'monthly' 当 product.pricingTerms exposes 该选项时，使用
quantityiOS仅用于内购，默认为 1. Android 总是购买一个项目。
appAccountTokeniOS + Android购买 ID
isConsumableAndroid设置为 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: 订阅包括
  • Android: isActive/expirationDate 不提供;请使用Google Play开发者API获取最新信息。 purchaseToken 请参阅Google Play开发者__CAPGO_KEEP_0__以获取最新信息。 purchaseState 必须 PURCHASED 和 isAcknowledged 必须 true.

API快速参考

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

最佳实践

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

收入下一步

收入下一步

在购买流程正常工作后，使用 收入指南 解决方案

问题

确保包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/原生付款 使用 @capgo/native-purchases @capgo/capacitor内购评论 使用 @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 的原生能力