revenuecat-migrate

revenuecat-migrate：RevenueCat への移行または SDK のアップグレード

アプリ内課金をすでに提供しているアプリに RevenueCat を導入する場合、または RevenueCat SDK のメジャーバージョンをアップグレードする場合に、このスキルを使用します。

この 2 つの経路には共通する概念もありますが、リスクは異なります。コードに手を加える前に、どちらに該当するかを特定してください。

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. 移行経路を特定する

ユーザーに確認するか、コードベースから判断します。

• 経路 A：導入。 アプリには、StoreKit または Google Play Billing を直接使用して実装した、動作中のアプリ内課金がすでにあります。RevenueCat をその上に追加します。
• 経路 B：バージョンアップグレード。 アプリはすでに RevenueCat を使用しており、ユーザーはメジャーバージョンを次のバージョンに上げようとしています（例：v4 から v5、v7 から v8）。

両方の経路を同時に実行する場合もあります（例：最新のメジャーバージョンで RC を導入する）。まず経路 A を実行し、必要に応じて経路 B を実行してください。

3. 共通の概念

オブザーバーモード（経路 A）

オブザーバーモードは、購入コードを書き換えずに RevenueCat を導入するための重要な仕組みです。SDK は、既存の StoreKit / Billing コードが処理するトランザクションを監視し、検証のために RevenueCat バックエンドへ送信して、サブスクライバーの状態を更新します。ただし、トランザクションの開始や完了は行いません。既存の購入 UI、レシート検証、トランザクションの完了処理はそのまま維持します。

設定時に次のように指定します。

• iOS：Configuration.Builder に purchasesAreCompletedBy: .myApp と storeKitVersion: .storeKit1（または .storeKit2）を設定します。これらは別々のパラメーターであり、単一の関連値ではありません。
• Android：PurchasesConfiguration.Builder に purchasesAreCompletedBy(PurchasesAreCompletedBy.MY_APP) を設定します。
• Flutter：PurchasesConfiguration に const PurchasesAreCompletedByMyApp(storeKitVersion: StoreKitVersion.storeKit2) を渡します。
• React Native：設定呼び出しで purchasesAreCompletedBy: { type: PURCHASES_ARE_COMPLETED_BY_TYPE.MY_APP, storeKitVersion: STOREKIT_VERSION.STOREKIT_2 } を渡します。

デフォルトでは RevenueCat が完了処理を担います（REVENUECAT / .revenueCat）。この場合、SDK がフロー全体を管理します。

オブザーバーモードで安定稼働したら、後から任意で、独自の購入処理を取り除き、purchasesAreCompletedBy のオーバーライドを削除して、全面的な RevenueCat モードに切り替えることができます。

トランザクションを二重に処理しない

purchasesAreCompletedBy を myApp に設定すると、RevenueCat は iOS でトランザクションを完了せず、Android で承認もしません。既存のコードで引き続き処理する必要があります。古いトランザクション完了処理を残したまま myApp フラグを削除すると、トランザクションが二重に承認され、サブスクライバーの状態に不整合が生じる可能性があります。

完了処理／承認を担うのは、必ずどちらか一方だけにしてください。どちらが担うかを決め、もう一方を削除してください。

ユーザーの継続性（パス A）

アプリに独自の認証システムがすでにある場合は、RevenueCat の設定後に Purchases.logIn(existingAppUserID) を呼び出します。これにより、以前の購入履歴が取り込み時に適切な RevenueCat ユーザーに関連付けられます。この手順を省略すると、既存の購入が匿名の RC ユーザーに記録され、後からアプリの実際のユーザー記録と照合できなくなります。

アプリに認証済みユーザーという概念がない場合に限り、この手順を省略してください。

バージョンの更新で必須フィールドが変わります（パス B）

メジャーバージョンのアップグレードでは、設定の構造が変わり、非推奨 API が削除され、リリースごとに変わる形でデフォルトの動作が変更されます。このスキルでは、バージョンごとの差分を複製していません。SDK リポジトリにある正式な情報源を確認してください。

• CHANGELOG：GitHub の該当する SDK リポジトリにあります。現在インストールしているバージョンからアップグレード先までの項目を確認してください。
• 移行ガイド：SDK リポジトリで *MIGRATION*.md に一致するファイル、または migrations/ ディレクトリを検索してください。メジャーバージョンのアップグレードでは、通常、専用のガイドが用意されています。リポジトリの GitHub リリースページにあるメジャーバージョンのリリースノートからリンクされていることが多いです。
• リリースノート：リポジトリの GitHub リリースページにある各メジャーバージョンのリリースノートには、破壊的変更の概要が記載されています。

SDK リポジトリのドキュメントを正式な情報源として扱ってください。ここに記載するバージョン固有の差分は、時間とともに古くなります。移行先のプラットフォームファイルには、参照すべき正確なリポジトリが記載されています。

まず計画を立ててから移行する

すべてのプラットフォームで、次の順序で作業してください。

1. ブランチを作成し、新しいメジャーバージョンに SDK を更新します。
2. CHANGELOG の非推奨項目と削除項目を参考に、コンパイルエラーを修正します。
3. 初回起動時の SDK ログを読み、実行時の動作を修正します。
4. マージする前に、既存のテストスイートと手動のサンドボックスシナリオを実行します。

4. 実装

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

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

各プラットフォームファイルには、そのプラットフォームの両方の移行パスが記載されています。

5. 検証

次のすべてを満たすまでは、移行が完了したと宣言しないでください。

1. 新しい SDK バージョンでアプリがビルドでき、気になる非推奨 API に関する警告がないこと。
2. サンドボックスでの購入が成功し、想定した appUserID とともに、取引が RevenueCat ダッシュボードの Sandbox ビューに表示されること。
3. 移行前からの既存のサブスクライバーがアプリを起動し、エンタイトルメントの状態が正しいこと。パス A では、これによりオブザーバーモードでの取り込みが機能したことを確認できます。パス B では、バージョン更新によって状態が失われなかったことを確認できます。
4. リリース前に、デバッグログレベルの上書きを削除していること。