capacitor-in-app-purchases

Capacitor のアプリ内課金

Capacitor アプリでアプリ内課金とサブスクリプションを設定します。ストアの設定、プラグインの統合、購入フロー、レシートの検証、テストを対象とします。

前提条件

1. Capacitor 6、7、または8 のアプリ（Capawesome Purchases には Capacitor 8 以降が必要です。RevenueCat には Capacitor 8 以降が必要です）。
2. Node.js と npm がインストールされていること。
3. iOS の場合：有料の Apple Developer Program メンバーシップ、Xcode のインストール、および App Store Connect で作成したアプリ。
4. Android の場合：Google Play Developer アカウント、Android Studio のインストール、および Google Play Console で作成したアプリ。

エージェントの動作

• 手順を追って案内します。 ユーザーを一度に1つずつ手順に沿って案内してください。関連のない質問を一度に複数提示しないでください。
• 質問する前に自動検出します。 プロジェクトのプラットフォーム（android/、ios/）、package.json の依存関係、Capacitor のバージョンを確認してください。検出できない場合にのみユーザーに尋ねてください。
• 一度に1つだけ選択してもらいます。 手順でユーザーの入力が必要な場合は、その質問だけをして、回答を待ってから続行してください。
• 選択肢を明確に提示します。 自由形式の質問ではなく、具体的な選択肢（例：「どの購入プラグインを使いますか？（1）Capawesome Purchases （2）RevenueCat」）を提示してください。

MCP サーバー

現在のドキュメントを提供するホスト型 MCP サーバーが2つあります。そのため、どちらもこのスキルに含まれるガイダンスより常に最新です。

• Capawesome MCP サーバー — Capawesome プラグイン、Capawesome CLI、Capawesome Cloud。
• Capacitor MCP サーバー（非公式）— Capacitor 自体：CLI、capacitor.config ファイル、ネイティブの Android および iOS プロジェクト、公式プラグイン API。

どちらも search_docs と get_doc_page を公開しているため、いずれかを呼び出す前にトピックに応じたサーバーを選択してください。

• MCP ツールを利用できる場合は、トピックを担当するサーバーで search_docs を呼び出し、一致するページを get_doc_page で読んでから、以下のガイダンスを適用してください。両者の内容が異なる場合は、ドキュメントに従ってください。
• 利用できない場合は、以下のコマンドでサーバーを追加できることを一度だけ伝えてから、このスキルを続けてください。決して作業を止めないでください。

claude mcp add --transport http capawesome "https://mcp.capawesome.io/mcp"
claude mcp add --transport http capacitor "https://capacitor-mcp.capawesome.io/mcp"

ドキュメントの利用にアカウントやトークンは必要ありません。Capawesome Cloud ツールを含むセットアップ全体については、capawesome-mcp および capacitor-mcp スキルを参照してください。

手順

ステップ1：プロジェクトを分析する

プロジェクトファイルを読み、以下を自動検出してください。推測できる情報をユーザーに尋ねてはいけません。

1. プラットフォーム：存在するディレクトリ（android/、ios/）を確認します。これらが設定対象のプラットフォームです。
2. Capacitor のバージョン：package.json から @capacitor/core のバージョンを読み取ります。
3. 既存の購入プラグイン：package.json に @capawesome-team/capacitor-purchases、@revenuecat/purchases-capacitor、またはその他のアプリ内課金プラグインがすでに含まれているか確認します。見つかった場合はユーザーに伝え、既存のプラグインを使い続けるか、別のものに切り替えるかを尋ねてください。

ステップ2：App Store Connect で製品を設定する（iOS）

ios/ が存在しない場合はスキップします。

references/app-store-connect-setup.md を読み、App Store Connect でアプリ内課金製品とサブスクリプションを作成する手順をユーザーに案内してください。内容は以下のとおりです。

• 必須の開発者契約への同意
• ビジネス設定の確認（有料 App 契約、銀行口座、税務フォーム）
• アプリ内課金製品の作成（消耗型、非消耗型、サブスクリプション）
• サブスクリプショングループの設定
• 製品のステータス要件

ステップ 3：Google Play Console で商品を設定する（Android）

android/ が存在しない場合はスキップします。

references/google-play-console-setup.md を読み、Google Play Console でアプリ内購入商品を作成できるようユーザーを案内します。以下の内容を扱います。

• コンプライアンス要件とメタデータ要件を満たす
• アプリ内商品とサブスクリプションを作成する
• 価格と税の設定を構成する
• 商品を有効化する

ステップ 4：購入プラグインを選択する

使用するプラグインをユーザーに尋ねます。

1. Capawesome Purchases（@capawesome-team/capacitor-purchases）— 軽量で、サードパーティのバックエンドに依存しません。Capawesome Insiders ライセンスが必要です。サーバー側のレシート検証は開発者が担当します。
2. RevenueCat（@revenuecat/purchases-capacitor）— サーバー側のレシート検証、エンタイトルメント管理、分析、各種連携に対応したフル機能のバックエンドサービスです。RevenueCat アカウントが必要です。

デフォルトの推奨：レシート検証用のバックエンドがすでにあるアプリや、サードパーティへの依存を避けたい場合は Capawesome Purchases を推奨します。レシート検証とサブスクリプション分析をすぐに利用できるマネージドサービスが必要な場合は RevenueCat を推奨します。

ステップ 5：プラグインをインストールして設定する

ステップ 4 で選択したプラグインに応じて、次の手順に従います。

• Capawesome Purchases：references/capawesome-purchases-setup.md を読み、インストールとプラットフォーム設定の手順に従います。
• RevenueCat：references/revenuecat-setup.md を読み、インストールとプラットフォーム設定の手順に従います。

ステップ 6：購入フローを実装する

ユーザーが選択したプラグインに応じて、次の手順に従います。

• Capawesome Purchases：references/capawesome-purchases-implementation.md を読み、購入コードをプロジェクトに追加します。
• RevenueCat：references/revenuecat-implementation.md を読み、購入コードをプロジェクトに追加します。

インポートとコード構造は、ユーザーが使用するフレームワーク（Angular、React、Vue など）に合わせて調整します。

実装では、以下を扱います。

1. 商品詳細の取得
2. 商品の購入
3. 取引の完了（Capawesome）またはエンタイトルメントの確認（RevenueCat）
4. 購入の復元
5. アプリ起動時の未完了取引への対応
6. レシート検証の方法

ステップ 7：オプション機能を設定する

有効にするオプション機能をユーザーに尋ねます。

1. サブスクリプション管理 — サブスクリプションのステータスを表示し、更新と有効期限切れに対応します。
2. 導入オファーの利用資格 — ユーザーが導入価格の対象となるかを確認します（Capawesome Purchases のみ）。
3. サーバー通知 — サブスクリプションのライフサイクルイベントに関する App Store Server Notifications や Google Play Real-time Developer Notifications を設定します。

選択された機能ごとに、対応する実装リファレンスファイルを読み、関連するコードを適用します。

ステップ 8：購入をテストする

references/testing.md を読み、両プラットフォームでアプリ内購入をテストできるようユーザーを案内します。以下の内容を扱います。

• テストアカウントを使った iOS Sandbox テスト
• Xcode での iOS StoreKit Testing
• Google Play Console の内部テストトラックとライセンス テスト アカウントを使った Android テスト
• よくあるテスト上の落とし穴とデバッグのヒント

ステップ 9：同期して検証する

npx cap sync

各プラットフォームでビルドして実行し、購入が最初から最後まで正常に動作することを確認します。

npx cap run android
npx cap run ios

エラーへの対処

• 製品が表示されない：iOS では、App Store Connect で作成してから利用可能になるまで、数時間かかることがあります。製品のステータスが「Ready to Submit」または「Approved」であることを確認してください。Android では、製品のステータスが「Active」であり、アプリが少なくとも内部テストトラックにアップロードされていることを確認してください。
• Android で購入が失敗しても何も表示されない：アプリは Google Play からインストールする必要があります（APK を直接インストールしてはいけません）。アプリを内部テストトラックにアップロードし、「License Testing」にテストアカウントを追加して、Google Play からインストールしてください。
• iOS のサンドボックス購入が繰り返される、または失敗する：デバイスがサンドボックスのテストアカウントにサインインしていることを確認してください（iOS 14 以降では「設定」>「App Store」>「Sandbox Account」）。テストに本番用 Apple ID を使用しないでください。
• purchaseProduct() が Android でエラーを返す：google-services.json が存在し、Google Play Billing Library のバージョンに互換性があることを確認してください。android/variables.gradle の $googlePlayBillingVersion を確認してください。
• レシートの検証に失敗する：iOS では、transaction.verificationResult を使って JWS トークンを検証してください。Android では、Google Play Developer API に対して transaction.token、transaction.originalJson、transaction.signature を検証してください。
• 購入の復元を実行しても何も表示されない：iOS では、syncTransactions() を呼び出すとシステム認証ダイアログが表示されるため、明示的なユーザー操作（「購入を復元」ボタンのタップなど）に応じて呼び出す必要があります。Android では、何も表示されずに実行されます。
• finishTransaction() が呼び出されていない：一部のプラットフォームでは、未完了のトランザクションによって以降の購入がブロックされます。コンテンツを提供した後は、必ず finishTransaction() を呼び出してください。アプリの起動時に毎回、未完了のトランザクションを確認してください。
• 実行時にプラグインが見つからない：インストール後に npx cap sync を実行したことを確認してください。Capawesome Purchases では、Capawesome npm レジストリが設定されていることを確認してください。
• Capacitor のバージョンが一致しない：Capawesome Purchases と RevenueCat は、どちらも Capacitor 8 以降が必要です。package.json の @capacitor/core のバージョンを確認してください。

関連スキル

• capacitor-plugins — Capawesome Purchases プラグインや RevenueCat プラグインを含む、Capacitor プラグインの一般的なインストールと設定について説明します。
• capawesome-cloud — アプリ内購入の設定後に、アプリストアで公開する方法について説明します。
• capawesome-mcp — MCP クライアントをホスト型 Capawesome MCP サーバーに接続して、常に最新のドキュメントを参照し、Capawesome Cloud を管理します。