revenuecat-testing-setup

revenuecat-testing-setup：RevenueCat の購入に使うテスト環境をセットアップする

実際に課金せずに RevenueCat の購入をテストしたい場合は、このスキルを使用してください。各ストアには専用のテストチャネルがあり、チャネルごとに忠実度と反復にかかるコストが異なります。

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. 共通の概念（すべてのプラットフォーム）

開発中に実際に課金することはできません

各ストアには専用のテストチャネルがあります。適切なチャネルは、何をテストしたいかによって異なります。

忠実度と反復コストで比較したテストチャネル

忠実度が高いほど、実際の購入パイプラインをより多く検証できます。低いほど、より速く反復できます。

• RevenueCat Test Store（忠実度最低、反復最速、決定論的）。RevenueCat がホストする仮想ストアです。SDK はダッシュボードの test_… API キーで設定します。購入時には Test Store のダイアログが開き、Successful Purchase、Failed Purchase、または Cancel の結果を手動で選択できます。購入によってエンタイトルメントが発生し、CustomerInfo が更新され、ダッシュボードに表示されますが、Apple や Google への呼び出しは行われません。ペイウォールの反復、統合テスト、CI のスモークテストに最適です。
• iOS StoreKit Configuration File（忠実度低、Apple の仮想環境）。Xcode がストアをローカルでスタブ化します。App Store Connect とのやり取りなしに、購入が即座に成功します。StoreKit 固有の動作を確認したい場合に便利です。このモードでの RevenueCat のトランザクションは、SDK のバージョンや意図されたルーティングによってダッシュボードに表示される場合とされない場合があるため、ダッシュボードのテストとしては忠実ではありません。
• iOS Sandbox（実際の Sandbox Apple ID）／Android Internal Testing（ライセンステスター）。実際のストアバックエンド、実際の RevenueCat ダッシュボードへの取り込み、実際のレシートを使用します。ビルドやインストールに加え、Play の反映や App Store Connect による製品の登録を待つ必要があるため、反復には時間がかかります。
• TestFlight（iOS）／Closed Testing または Open Testing（Android）。本番環境に非常に近い動作をします。レシートは本番形式です。トランザクションは Sandbox ビューではなく、RevenueCat の本番ダッシュボードに反映されます。
• 本番環境。実際に課金されます。テストには使用しないでください。

質問に答えられる範囲で最も忠実度の低い方法から始め、その後、必要に応じて段階を上げてください。UI やペイウォールの反復には高速なチャネルを使います。「エンタイトルメントが実際に切り替わるか」は、Sandbox または内部テストで確認します。

Test Store：Sandbox より先に利用する場面

RevenueCat の Test Store は、ダッシュボードでプロジェクトごとに設定する合成ストアプロバイダーです。App Store や Google Play にアクセスすることなく、RevenueCat のバックエンドに実際のレコード（CustomerInfo の更新、エンタイトルメントの遷移、ダッシュボードのトランザクション）を作成します。この速度の代償は、忠実度です。Test Store では、「承認と購入を依頼」の承認フロー、地域別の価格設定、サーバー側のレシート検証の詳細、ストアレベルの審査や却下のフロー、サブスクリプションの完全な更新サイクル（Test Store では短縮された時間で最大 5 回更新されます）はシミュレートされません。

UI をすばやく反復したい場合、結果が確定的な統合テストを書きたい場合、または CI チェックを実行したい場合は、Test Store を使用します。ストア側の動作をテストする場合は、App Store Sandbox または Google Play Internal Testing に移行してください。

セットアップ。 ダッシュボードで、Apps and providers → Test configuration セクション → Test Store → Create / Enable の順に移動します。Test Store API キーは、test_ プレフィックス付きで Project Settings → API keys に表示されます。デバッグビルドではテストキーを、リリースビルドでは本番キー（appl_… / goog_…）を使用するよう SDK を設定します。プラットフォームごとのキー切り替えパターンは、各プラットフォームのファイルを参照してください。

Test Store キーを本番環境に含めてはいけません。リリースバイナリが Test Store に接続できないよう、ビルド設定でキーを制御してください。

Sandbox のトランザクションはダッシュボードに別々に表示されます

RevenueCat ダッシュボードには、Sandbox と Production の表示を切り替えるトグルがあります。Sandbox での購入は Sandbox にのみ表示されます。テストトランザクションが表示されない場合、SDK が報告していない（API キー、configure の呼び出し、ネットワークを確認してください）か、RevenueCat のバックエンドに接続しない StoreKit 構成ファイルで購入が行われています。

Sandbox での更新の高速化

Sandbox では、サブスクリプションの更新が高速化されたテスト用の時間軸で実行されます。これにより、数週間ではなく数分で更新ロジックをテストできます。

• iOS Sandbox の更新間隔（Apple のドキュメントに基づく）：日単位 → 3 分ごと、週単位 → 3 分ごと、月単位 → 5 分ごと、2 か月 → 10 分ごと、3 か月 → 15 分ごと、6 か月 → 30 分ごと、年単位 → 1 時間ごと。サブスクリプションは最大 6 回自動更新され、その後期限切れになります。
• Android Sandbox の更新間隔は、Google Play Console → Subscriptions testing に記載されています。ライセンステスターのサブスクリプションも、同じ高速化された時間軸で更新されます。

初回購入フローには新しいテストユーザーを使用する

購入履歴はテストアカウント（Sandbox の Apple ID またはライセンステスターの Gmail）に紐付けられ、保持されます。すでに利用したことのあるアカウントで「初回購入」ロジック、初回限定オファー、または無料トライアルをテストすると、誤解を招く結果になります。初回購入のシナリオを正確にテストするには、新しい Sandbox テスターを作成してください。

デバイスではなくダッシュボードで確認する

デバイスで購入が成功しても、RevenueCat に記録されたとは限りません。必ず次の点を確認してください。

1. トランザクションが RevenueCat ダッシュボードの Sandbox 表示にあること。
2. 想定した appUserID がトランザクションを所有していること。
3. そのユーザーで、想定したエンタイトルメントが有効になっていること。

デバイスでは成功と表示されても、ダッシュボードに何も表示されない場合、問題はストアではなく設定経路にあります。

3. 実装

検出されたプラットフォームに対応するファイルを読んでください。

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

4. 確認

テスト環境は、次の手順を一度完了すればセットアップできます。

1. テストユーザーによるテスト購入が、最初から最後まで成功する。
2. トランザクションが RevenueCat ダッシュボードの Sandbox 表示に、ログイン時に使用した appUserID に紐付けられて表示される。
3. 購入完了後、想定したエンタイトルメントが customerInfo で有効になっている。
4. アプリを新規インストールした状態で購入を復元すると、同じテストユーザーにエンタイトルメントが復元される。

この 4 つの手順のいずれかに失敗した場合、環境の準備はできていません。一般的な根本原因については、revenuecat-troubleshoot スキルで説明しています。