Getting Started

インストール手順とこのプラグインの全マークダウンガイドを含むセットアップ用の質問をコピーしてください。

        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.

インストール

CapgoのAIアシストセットアップを使用してプラグインをインストールできます。AIツールにCapgoスキルを追加するには、以下のコマンドを使用してください:

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.

__CAPGO_KEEP_1__の場合、プラグインをインストールするには、以下のコマンドを実行し、下記のプラットフォーム固有の指示に従ってください。

__CAPGO_KEEP_2__をインストール
__CAPGO_KEEP_3__画面
```
bun add @capgo/native-purchases
```
__CAPGO_KEEP_4__
__CAPGO_KEEP_3__画面
```
bunx cap sync
```

__CAPGO_KEEP_5__を確認

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

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

__CAPGO_KEEP_6__を直接読み込む

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でインアプリ製品とサブスクリプションを作成します。
- 少なくとも内部テストビルドをアップロードし、ライセンステスターを追加してください。
- Add the billing permission to 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` サブスクリプションのための Android
`planIdentifier`	Google Play Console から取得する基本プラン ID。サブスクリプションの場合に必須、iOS とインアプリ購入の場合に無視されます。']}	Base Plan ID from Google Play Console. Required for subscriptions, ignored on iOS and in-app purchases.
`billingPlanType`	iOS サブスクリプション	StoreKit の課金プランを購入に使用します。月額課金に 12 か月のコミットメントがある場合に、そのオプションを表示します。 `'monthly'` iOS `product.pricingTerms` iOS のみのインアプリ購入に使用します。デフォルトは
`quantity`	Android	Android は常に 1 つのアイテムを購入します。 `1`iOS + Android
`appAccountToken`	購入をユーザーにリンクするための UUID/文字列。iOS では必ず UUID でなければなりませんが、Android は 64 文字までのオブフュージド文字列を受け入れます。	Android
`isConsumable`	自動的にトークンを消費するように設定します。消耗可能な場合に、特権を付与した後に。	デフォルトは `true` to auto-consume tokens after granting entitlement for consumables. Defaults to `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 are not populated; call the Google Play Developer API with the purchaseToken __CAPGO_KEEP_0__ quick reference purchaseState __CAPGO_KEEP_0__ quick reference PURCHASED StoreKit / Google Play の利用可能性を確認します。 isAcknowledged 価格、ローカライズされたタイトル、説明、イントロオファー、および iOS のサポートされる価格条件を取得します。 true.

API quick reference

isBillingSupported() iOS のすべての取引または Play Billing の購入をリストします。
getProduct() / getProducts() ネイティブのサブスクリプション管理UIを開きます。
purchaseProduct() – check for StoreKit / Google Play availability.
restorePurchases() – fetch price, localized title, description, intro offers, and supported iOS pricing terms.
getPurchases() – initiate StoreKit 2 or Billing client purchase flow, including iOS monthly commitment billing plans.
manageSubscriptions() – replay historical purchases and sync to current device.
addListener('transactionUpdated') – iOS のみで、StoreKit 2 の保留中のトランザクションをアプリが起動したときに処理する。

ベストプラクティス

店舗価格を表示 – Apple は表示を必要とし、 product.title 、; どの場合もハードコードしない。 product.priceString使用
– ユーザー ID から決定論的に UUID (v5) を生成して、購入をアカウントにリンクする。 appAccountToken サーバー側の検証
– (iOS) / 送信 – receipt __CAPGO_KEEP_0__ purchaseToken (Android)をあなたのバックエンドに検証する。
エラーを優雅に処理する –ユーザーのキャンセル、ネットワークの失敗、非対応の請求環境を確認する。
徹底的なテスト –以下の指示に従って iOSサンドボックスガイドと Androidサンドボックスガイド.
復元と管理を提供する –UIボタンを追加して restorePurchases() と manageSubscriptions().

Revenueの次のステップに接続する

購入フローの動作が確認されたら、売上プレイブック最初の有料チャネルを計画するために、製品スコープ、ASO、価格、壁の配置、分析、そして脱落フィードバックを含む。

トラブルシューティング

製品が読み込まれない

バンドルID/アプリケーションIDがストアの設定と一致していることを確認する。
製品IDがアクティブで承認済み（App Store）または有効化済み（Google Play）であることを確認する。
製品を作成した後数時間待つ。ストアのプロパゲーションは即時ではない。

購入がキャンセルされたり、止まったり

ユーザーはフローの途中でキャンセルできるので、呼び出しをラップする try/catch と表面に親切なエラーメッセージを表示します。
Androidの場合、Play Store（内部トラック）からアプリをインストールするテストアカウントを確保して、請求が正常に動作するようにします。
デバイス上で実行している場合、Billingエラーを検出するにはlogcat/Xcodeを確認してください。

サブスクリプションの状態が不正です

使用 getPurchases() ストアデータをローカルエンタイトルメントキャッシュと比較するには使用してください。
Androidの場合、常にGoogle Play Developer APIに問い合わせて、有効期限切れ日または払い戻しステータスを取得します。 purchaseToken iOSの場合、払い戻しまたは取り消しを検出するにはとを確認して、有効なレシートを検証してください。
Getting Startedから続けてください isActive/expirationDate Getting Startedから続けてくださいというセクションのタイトルです。

Getting Startedから続けてください

あなたが使用している場合 Getting Started ストアの承認と配布を計画するには、 @capgo/native-purchasesを使用して native capabilityの@capgo/native-purchasesの場合 @capgo/capacitor-in-app-reviewを使用して @capgo/capacitor-in-app-reviewの実装詳細 @capgo/capacitor-in-app-reviewを使用して native capabilityの@capgo/capacitor-in-app-reviewの場合 @capgo/capacitor-native-marketを使用して @capgo/capacitor-native-marketの実装詳細 @capgo/capacitor-native-marketを使用して native capability in Using @capgo/capacitor-native-market.