跳过内容
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 + AndroidSKU/产品 ID
productType仅 AndroidPURCHASE_TYPE.INAPP 或 PURCHASE_TYPE.SUBS或 INAPP. 默认值 SUBS . 总是设置为
planIdentifier用于订阅仅 Android 订阅项
billingPlanTypeiOS 订阅使用 StoreKit billing 计划进行购买。使用 'monthly' 为每月付款设定 12 个月的承诺时 product.pricingTerms iOS
quantity仅限在应用内购买， 默认为. Android 总是购买一个项目。 1iOS + Android
appAccountTokeniOSUUID/字符串，用于将购买与您的用户关联。 iOS 需要 UUID； Android 可以接受最多 64 个字符的任何混淆字符串。
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,并且StoreKit 2监听器支持。应用内购买需要服务器接收验证。
  • Android: isActive/expirationDate 不被填充；请使用Google Play开发者API调用 purchaseToken 为了获得权威的状态。 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 – 根据用户 ID 确定生成 UUID (v5) 来将购买与帐户关联.
  3. 验证服务器端 – 发送 receipt (iOS) / purchaseToken （Android）将其发送到您的后端进行验证。
  4. 优雅地处理错误 – 检查用户取消、网络故障和不支持的计费环境。
  5. 彻底测试 – 遵循 iOS沙盒指南 并 Android沙盒指南.
  6. 提供恢复和管理 – 添加UI按钮，连接到 restorePurchases() 并 manageSubscriptions().

收入下一步

Revenue next steps

使用完成购买流程后，使用 Revenue Playbook 计划您的第一条付费渠道：产品范围、ASO、定价、付款墙位置、分析和流失反馈。

故障排除

故障排除

产品未加载

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

购买取消或卡住

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

订阅状态不正确

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

继续从 Getting Started

标题为“继续从 Getting Started”

If you are using 开始使用 为了计划商店审批和分发,连接它 使用@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原生能力。