スタートガイド

インストール

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.

手動セットアップを希望する場合は、以下のコマンドを実行してプラグインをインストールし、下記のプラットフォーム別の手順に従ってください：

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と
   • App Store ConnectでApp内課金とサブスクリプションを作成します。
     
   • QAにはStoreKit Local TestingまたはSandboxテスターを使用してください。
     
   • マニフェストの編集は不要です。製品が承認されていることを確認してください。
   Androidでは
   • Google Play Console でアプリ内アイテムとサブスクリプションを作成します。
     
   • 少なくとも内部テスト用の build をアップロードし、ライセンス テスターを追加してください。
     
   • billing 権限を以下に追加します： 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/Product ID。
productType	Android のみ	PURCHASE_TYPE.INAPP または PURCHASE_TYPE.SUBS. デフォルトは INAPP. 常に設定: SUBS サブスクリプション用。
planIdentifier	Android のサブスクリプション	Google Play Console の Base Plan ID。サブスクリプションに必須です（iOS とアプリ内課金では無視されます）。
billingPlanType	iOS のサブスクリプション	購入する StoreKit の billing plan。使用: 'monthly' 12ヶ月の継続利用を条件とした月額請求の場合 product.pricingTerms そのオプションが表示されます。
quantity	iOSと	アプリ内課金のみが対象で、デフォルトは 1。Androidは常に1つのアイテムを購入します。
appAccountToken	iOS + Android	購入をユーザーに紐付けるUUIDまたは文字列。iOSではUUIDが必須ですが、Androidでは64文字までの難読化された文字列が使用可能です。
isConsumable	Androidでは	を true に設定すると、消耗品（consumables）の権限付与後にトークンを自動的に消費します。デフォルトは false.

Entitlementステータスの確認

使用する 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 Developer API を使用して、 purchaseToken 正確なステータスを確認してください。 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 のみ）。

ベストプラクティス

1. ストアの価格を表示する – Appleの規定により表示が必須です product.title と product.priceString; ハードコードは避けてください。
2. 使用する appAccountToken – ユーザーIDからUUID (v5) を決定論的に生成し、購入情報をアカウントに紐付けます。
3. サーバーサイドで検証する – 送信: receipt (iOS) / purchaseToken (Android) をバックエンドに送り、検証を行います。
4. エラーを適切にハンドリングする – ユーザーによるキャンセル、ネットワークエラー、およびサポートされていない決済環境を確認します。
5. 徹底的なテスト – 次の手順に従ってください： iOS sandboxガイド と Android sandboxガイド.
6. オファーの復元と管理 – 次の機能に紐付けたUIボタンを追加します： restorePurchases() と manageSubscriptions().

Revenueの次のステップ

購入フローが正常に動作したら、次を使用してください： 収益化プレイブック 最初の有料ファンネルを計画するために：プロダクトの範囲、ASO、価格設定、ペイウォールの配置、分析、およびチャーン（解約）フィードバックを検討しましょう。

トラブルシューティング

プロダクトが読み込まれない場合

• Bundle ID / Application ID がストアの設定と一致していることを確認してください。
• Product ID が有効で、承認済み（App Store）またはアクティブ（Google Play）であることを確認してください。
• プロダクト作成後、数時間待機してください。ストアへの反映には時間がかかる場合があります。

購入がキャンセルされた、または進行が止まった場合

• ユーザーはフローの途中でキャンセルできます。呼び出しを try/catch でラップし、適切なエラーメッセージを表示するようにしてください。
• Androidの場合、Billingを動作させるために、テストアカウントがPlay Store（内部テストトラック）からアプリをインストールしていることを確認してください。
• 実機で実行中に課金エラーが発生した場合は、logcatまたはXcodeを確認してください。

サブスクリプションの状態が正しくない

• 使用する getPurchases() ストアのデータとローカルのentitlementキャッシュを比較するために、
• Androidでは、必ずGoogle Play Developer APIを purchaseToken 有効期限や返金ステータスを取得するために使用してください。
• iOSでは、以下を確認してください： isActive/expirationDate レシートの検証を行い、返金や権限の取り消しを検知します。

Getting Startedの続きを進める

使用している場合 スタートガイド ストアの承認と配信を計画するには、これを次と連携させてください： @capgo/native-purchases を使用する 「Using @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. の使用」のネイティブ機能については