Getting Started

复制一个包含安装步骤和完整 Markdown 指南的配置提示。

        Set up this Capacitor plugin in the project.

Use the package manager already used by the project.
Install these package(s): `@capgo/native-purchases`
Run the required Capacitor sync/update step after installation.
Read this markdown guide for the full setup steps: https://raw.githubusercontent.com/Cap-go/website/refs/heads/main/apps/docs/src/content/docs/docs/plugins/native-purchases/getting-started.mdx
Use that guide for platform-specific steps, native file edits, permissions, config changes, imports, and usage setup.
If that guide references other docs pages, read them too.

安装

您可以使用我们的 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.

如果您prefer手动设置，请运行以下命令并按照以下平台特定的说明进行安装：

安装包
终端窗口
```
bun add @capgo/native-purchases
```
同步本地项目
终端窗口
```
bunx cap sync
```

查看计费支持

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

const { isBillingSupported } = await NativePurchases.isBillingSupported();
if (!isBillingSupported) {
  throw new Error('Billing is not available on this device');
}

直接从商店加载产品

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

实现购买和恢复流程
```
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订阅返回 pricingTerms，您可以显示一个月度计费选项，具有12个月的承诺，并传递 billingPlanType: 'monthly' 到 purchaseProduct()。见 iOS月度承诺计费计划，了解完整流程。
- iOS
- Android
- 在App Store Connect中创建应用内产品和订阅。
- 使用StoreKit Local Testing或Sandbox测试者进行QA。
- 无需修改清单。确保您的产品已获得批准。
- 在 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 only	`PURCHASE_TYPE.INAPP` 或 `PURCHASE_TYPE.SUBS`. 默认为 `INAPP`. 始终设置为 `SUBS` 用于订阅
`planIdentifier`	Google Play Console 中的基本计划 ID。用于订阅，忽略 iOS 和内购	StoreKit billing plan to purchase。使用
`billingPlanType`	for monthly billing with a 12-month commitment when	__CAPGO_KEEP_0__ `'monthly'` __CAPGO_KEEP_1__ `product.pricingTerms` 暴露该选项。
`quantity`	iOS	仅限内购， `1`。 Android 总是购买一个项目。
`appAccountToken`	iOS + Android	UUID/字符串将购买与您的用户关联。 iOS 必须为 UUID； Android 可以接受最多 64 个字符的任何混淆字符串。
`isConsumable`	Android	设置为 `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监听器支持。
在应用内购买需要服务器收据验证。: isActive/expirationDate are not populated; call the Google Play Developer API with the purchaseToken 不被填充；请使用Google Play开发者__CAPGO_KEEP_0__ 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）。

最佳实践

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

收入下一步

标题购买流程工作后使用的收入手册为您的第一条付费通道制定计划：产品范围、ASO、定价、付费墙位置、分析和流失反馈。

故障排除

产品未加载

确保bundle 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”

Getting Started 规划商店批准和分发，连接它 to plan store approval and distribution, connect it with 使用 @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 的原生能力