Getting Started

インストール

AI-Assisted Setupを使用してプラグインをインストールできます。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 Setupを使用する場合は、以下のコマンドを実行してプラグインをインストールし、以下のプラットフォーム固有の指示に従ってください。

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

   iOS
   • App Store Connect でインアプリ製品とサブスクリプションを作成します。
     
   • StoreKit Local Testing または Sandbox テスターを使用して QA を実行します。
     
   • manifestの編集は必要ありません。製品が承認されていることを確認してください。
   Android
   • 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,
      }),
    });
  }
}

必要な購入オプション

オプション	プラットフォーム	__CAPGO_KEEP_0__
productIdentifier	__CAPGO_KEEP_1__	__CAPGO_KEEP_2__
productType	__CAPGO_KEEP_3__	PURCHASE_TYPE.INAPP __CAPGO_KEEP_4__ PURCHASE_TYPE.SUBS__CAPGO_KEEP_5__ INAPP__CAPGO_KEEP_6__ SUBS __CAPGO_KEEP_7__
planIdentifier	__CAPGO_KEEP_8__	__CAPGO_KEEP_9__
billingPlanType	__CAPGO_KEEP_10__	__CAPGO_KEEP_11__ '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

• iOS: Subscriptions include 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 for authoritative status. purchaseState must be PURCHASED と isAcknowledged なければ true.

API クイック リファレンス

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

ベスト プラクティス

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

Revenue の次のステップ

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

トラブルシューティング

製品が読み込まれない

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

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

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

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

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

Capgoを使用している場合、Getting Startedから続けてください。

__CAPGO_KEEP_0__を使用してデバイス上で実行中の課金エラーをログcat/Xcodeで確認してください。 __CAPGO_KEEP_0__を使用してデバイス上で実行中の課金エラーをログcat/Xcodeで確認してください。 to plan store approval and distribution, connect it with Using @capgo/native-purchases for the native capability in Using @capgo/native-purchases, @capgo/capacitor-in-app-review for the implementation detail in @capgo/capacitor-in-app-review, Using @capgo/capacitor-in-app-review for the native capability in Using @capgo/capacitor-in-app-review, @capgo/capacitor-native-market for the implementation detail in @capgo/capacitor-native-market, and Using @capgo/capacitor-native-market for the native capability in Using @capgo/capacitor-native-market.