revenuecat-purchase-flow

revenuecat-purchase-flow：パッケージの購入と購入の復元

RevenueCat の購入フローを実装する場合にこのスキルを使用します。オファリングの取得、purchase の呼び出し、キャンセルやエラーへの対処、「復元」アクションの公開を扱います。ペイウォール UI の描画（revenuecat-paywall で扱います）や機能の利用制限（revenuecat-entitlements-gate で扱います）は対象外です。

アプリにまだペイウォールがなく、ユーザーからカスタムのペイウォールを求められていない場合は、まずペイウォールの構築方法を決めてください（integrate-revenuecat のセクション 5c）。デフォルトは RevenueCat Paywall で、購入処理も行います。

1. プラットフォームを検出する

作業ディレクトリを調べ、上から順に最初に一致したものを選びます。

1. React Native：package.json に react-native-purchases のエントリがあるか、依存関係に react-native がある場合 → platforms/react-native.md を読みます。expo も依存関係にある場合は、Expo プロジェクトとして扱います。
2. Flutter：プロジェクトルートに pubspec.yaml がある場合 → platforms/flutter.md を読みます。
3. Kotlin Multiplatform：build.gradle.kts に kotlin { … } のマルチプラットフォーム・ソースセットブロックがあるか、com.revenuecat.purchases:purchases-kmp* に依存している場合 → platforms/kmp.md を読みます。
4. Android（ネイティブ）：build.gradle(.kts) で com.android.application を適用していて、KMP ではない場合 → platforms/android.md を読みます。
5. iOS（ネイティブ）：プロジェクトルートに Package.swift、*.xcodeproj、*.xcworkspace、または Podfile がある場合 → platforms/ios.md を読みます。

複数の条件に一致する場合（例：Flutter プロジェクト内に ios/ フォルダーがある場合）は、ビルドを管理している最も外側のプロジェクトを選びます。それでも判断できない場合は、設定したいプラットフォームをユーザーに尋ねます。

2. 共通の概念（すべてのプラットフォーム）

• フロー。 getOfferings() を呼び出し、現在のオファリングから Package を選び、purchase(package) を呼び出します。正常に完了すると、返される customerInfo には購入内容がすでに反映されています。customerInfo.entitlements.active["<id>"] を読み取り、アクセス権を確認します。
• ユーザーによるキャンセルはアプリケーションエラーではありません。 SDK ごとに処理方法が異なります。iOS では purchaseCancelledError コードをスローし、Android では PurchasesErrorCode.PurchaseCancelledError を含む PurchasesException をスローします。Flutter では同じコードを含む PlatformException が返され、React Native では e.userCancelled === true が設定されます。この場合は何も表示せずに終了します。アラートは表示しないでください。
• メッセージを表示すべきエラー。 支払いの拒否、ネットワークエラー、ストアが利用できない場合、レシートがすでに使用されている場合です。それ以外はログに記録し、ユーザーが再試行できるようにします。購入に失敗したのに、成功したように見せてはいけません。
• 購入コールバック内でコンテンツのロックを解除しないでください。 顧客情報を更新し、エンタイトルメントのリスナー（revenuecat-entitlements-gate を参照）にゲート対象の UI を切り替えさせます。これにより、アクセス権の情報源を一元化し、購入フローと復元フローの不整合を防げます。
• restorePurchases() はユーザーの操作であり、自動的に実行する手順ではありません。 ストアに現在のレシートを問い合わせ、RevenueCat に同期します。ペイウォールや設定画面に、常に表示される「購入を復元」ボタンを設置して呼び出せるようにします。iOS では法的要件として、このボタンが必要です。
• 購入は一度に 1 件のみ。 二重請求を防ぐため、購入処理中はペイウォールの購入ボタンを無効にします。

3. 実装

検出結果に対応するプラットフォームファイルを読みます。

• platforms/ios.md
• platforms/android.md
• platforms/kmp.md
• platforms/flutter.md
• platforms/react-native.md

各プラットフォームファイルには、購入関数と復元関数の完全な実装が記載されています。

4. 検証

以下を満たすまでは、フローが動作すると断言しないでください。

1. 現在のプランのパッケージをサンドボックスで購入すると、エンドツーエンドで成功し、ユーザーの利用権限が有効に切り替わる。
2. ストアの購入シートをキャンセルしても、エラーアラートが表示されず、UI が読み込み中のままにならない。
3. 同じ有効なサブスクリプションを 2 回目に購入しようとしても、適切に処理される（StoreKit / Play Billing では productAlreadyPurchased / receiptAlreadyInUse の経路が発生しますが、フローがクラッシュしない）。
4. 同じストアアカウントにサインインした状態で新規インストール後に復元ボタンを押すと、利用権限が復元され、UI が更新される。