Getting Started

インストール

AI-Assisted セットアップを使用してプラグインをインストールできます。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.

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

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サブスクリプションが返された場合 pricingTerms12か月のコミットメントとともに月額請求オプションを表示できます。 billingPlanType: 'monthly' を purchaseProduct()を参照してください。 iOS 月額コミットメント請求プラン iOS

   Android
   • StoreKit Local TestingまたはSandboxテスターを使用してQAを実行します。
     
   • __CAPGO_KEEP_0__
     
   • manifestの編集は必要ありません。製品が承認されていることを確認してください。
   App Store Connectでインアプリ製品とサブスクリプションを作成します。
   • 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. App Store Connect / Google Play Console でのデフォルト値 INAPP. iOS とインアプリ購入では常に設定されます。 SUBS サブスクリプション用
planIdentifier	Google Play Console でのベース プラン ID。サブスクリプションの場合に必要ですが、iOS とインアプリ購入では無視されます。	iOS サブスクリプション
billingPlanType	StoreKit の請求プランを購入するために使用します。	使用 'monthly' 月額課金の場合、12か月のコミットメントの場合に product.pricingTerms オプションを表示します。
quantity	iOS	インアプリ購入のみ、デフォルトは 1Androidは常に1つのアイテムを購入します。
appAccountToken	iOS + Android	購入をユーザーにリンクするためのUUID/文字列。iOSでは必ずUUIDでなければなりませんが、Androidでは64文字までのオブfuscateされた文字列を受け入れます。
isConsumable	Android	自動的にトークンを消費するように設定します。消耗可能なアイテムの特権を付与した後、デフォルトは true 特権の状態を確認中 false.

「特権の状態を確認」セクション

Use getPurchases() for a cross-platform view of every transaction the stores report:

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

Platform behavior

• iOSiOS isActive, expirationDate, willCancel, and StoreKit 2 listener support. In-app purchases require server receipt validation.
• Android: isActive/expirationDate are not populated; call the Google Play Developer API with the purchaseToken __CAPGO_KEEP_0__ purchaseState must be PURCHASED と isAcknowledged なければ true.

API のクイックリファレンス

• isBillingSupported() – iOS / Google Play の利用可能性を確認する。
• getProduct() / getProducts() – 価格、ローカライズされたタイトル、説明、イントロオファー、iOS のサポートされている価格条件を取得する。
• purchaseProduct() – StoreKit 2 または Billing クライアントの購入フローを開始する、iOS の月額コミットメントの請求計画を含む。
• restorePurchases() – 歴史的な購入を再生し、現在のデバイスに Sync する。
• getPurchases() – iOS のすべてのトランザクションまたは Play Billing の購入をリストする。
• manageSubscriptions() – ネイティブのサブスクリプション管理 UI を開く。
• addListener('transactionUpdated') – アプリが起動したときに iOS のみの保留中の StoreKit 2 のトランザクションを処理する。

ベストプラクティス

1. Store の価格を表示 – Apple は、 product.title を表示することを要求しています。 product.priceStringをハードコードせずに。
2. を使用してください。 appAccountToken – ユーザー ID から、購入をアカウントにリンクするために使用するように UUID (v5) を決定論的に生成してください。
3. サーバー側で検証 – (iOS) / receipt (Android) をバックエンドに送信して検証してください。 purchaseToken エラーを優雅に処理してください
4. protectedTokens – ユーザーのキャンセル、ネットワークの失敗、非対応の請求環境を確認する
5. テストを徹底的に行う – iOS のサンドボックス ガイド と Android のサンドボックス ガイド.
6. 請求の復元と管理を提供する – UI ボタンを追加して restorePurchases() と manageSubscriptions().

Revenue の次のステップ

購入フローが正常に動作したら、 収益戦略ガイド 最初の有料チャネルを計画するには、製品スコープ、ASO、価格設定、壁紙の配置、分析、および脱落フィードバックを考慮してください。

トラブルシューティング

製品が読み込まれない

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

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

• ユーザーは途中でキャンセルできるため、呼び出しを囲んでフレンドリーなエラーメッセージを表面化してください。 try/catch Androidの場合、テストアカウントはPlay Store（内部トラック）からアプリをインストールするようにして、Billingが機能することを確認してください。
• __CAPGO_KEEP_0__
• __CAPGO_KEEP_0__

Subscription state incorrect

• Use getPurchases() to compare store data with your local entitlement cache.
• On Android, always query the Google Play Developer API with the purchaseToken to obtain expiration dates or refund status.
• On iOS, check isActive/expirationDate and validate receipts to detect refunds or revocations.

Keep going from Getting Started

If you are using If you are using 店舗承認と配布を計画し、 Using @capgo/native-purchases Using @capgo/native-purchases @capgo/capacitor-in-app-review Using @capgo/capacitor-in-app-review Using @capgo/capacitor-in-app-review Using @capgo/capacitor-in-app-review @capgo/capacitor-native-market Using @capgo/capacitor-native-market Using @capgo/capacitor-native-market for the native capability in Using @capgo/capacitor-native-market.