revenuecat-troubleshoot

revenuecat-troubleshoot：RevenueCat 統合の問題を診断する

ユーザーから、RevenueCat の動作が期待どおりでないと報告された場合に、このスキルを使用します。たとえば、オファリングが空である、商品が表示されない、購入が成功したのにエンタイトルメントが有効にならない、ペイウォールが表示されない、サンドボックス取引がダッシュボードに届かないといったケースです。

このスキルでは、次の 2 つの観点を組み合わせます。

1. コード側の診断 — デバッグログを有効にし、共通チェックリストを確認してから、プラットフォーム固有の項目を調べます。
2. ダッシュボードの調査 — RevenueCat MCP サーバーまたは rc CLI（revenuecat-cli スキルを参照）を使って、プロジェクト、アプリ、商品、エンタイトルメント、オファリング、ウェブフックを確認し、修正案を提示します。

順番に進めます。ほとんどの報告は、プラットフォーム固有の項目に進む前に解決します。

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. コード側で確認する共通チェックリスト

次の9項目を順番に確認します。ほとんどの問題は、手順1〜5で解決します。

1. デバッグログを有効にして再現します。 SDK は処理内容をログに記録します。報告される問題のおよそ80％は、ログ出力だけで原因を特定できます。各プラットフォームのファイルに、logLevel を debug に設定する方法が記載されています。
2. API キーのプラットフォームがアプリと一致していることを確認します。 iOS アプリでは appl_… の公開 SDK キーを使用する必要があります。Android アプリでは goog_…（Amazon の場合は amzn_…）を使用する必要があります。キーが一致しない場合、最初のネットワークリクエストで認証エラーが発生します。iOS では INVALID_CREDENTIALS エラーコード、Android では PurchasesErrorCode.InvalidCredentialsError として表示されます。list-app-public-api-keys RevenueCat MCP ツールを使用して、プロジェクトの API キーを一覧表示します。
3. バンドル ID／パッケージ名が RevenueCat プロジェクトで設定したものと一致していることを確認します。 list-apps RevenueCat MCP ツールを使用して、アプリを一覧表示します。登録されている bundle_id（iOS／App Store）または package_name（Android／Play ストア／Amazon Appstore）は、大文字と小文字も含め、ビルドしたアプリと完全に一致する必要があります。一致しない場合、アプリが認識されず、オファリングが空で返されます。
4. RevenueCat プロジェクトのオファリングを確認します。 list-offerings RevenueCat MCP ツールを使用して、limit: 100 と expand=items.package.product を渡し、プロジェクトのオファリングを一覧表示します。デフォルトの20件のページでは現在のオファリングが含まれないことがあり、ページの一部だけを取得した場合、現在のオファリングがないプロジェクトと同じように見えます。is_current: true のオファリングには、少なくとも1つのパッケージが含まれている必要があります。また、各パッケージはストア商品を参照している必要があります。パッケージが0個のオファリングでは、getOfferings が成功しても availablePackages リストは空になります。
5. ストア商品が公開可能な状態であることを確認します。 商品は App Store Connect で「Ready to Submit」、または Google Play Console で「Active」になっている必要があります。下書き状態の商品は、サンドボックスでもストアから返されません。RevenueCat からオファリングが届いているのに商品を解決できないことが SDK ログに示されている場合、ほぼ間違いなくこれが原因です。get-product-store-state RevenueCat MCP ツールを使用して、App Store Connect または Google Play Console における商品の状態（フィールド store_status）を確認します。ストアの状態を読み取るだけでなく修正または変更するには、revenuecat-store-state スキルに従ってください。
6. テストアカウントを確認します。 iOS：デバイスで「設定」→「App Store」→「Sandbox Account」から Sandbox Apple ID にサインインしている必要があります（iOS 14以降では、最初のサンドボックスプロンプトの後に設定します）。Android：テスターの Gmail アカウントを Google Play Console →「Setup」→「License testing」に追加する必要があります。また、アプリはサイドロードではなく、Play テストトラックのオプトインリンクからインストールする必要があります（トラックの種類については、以下の Android チェックリストを参照してください）。
7. ネットワークを確認します。 企業の VPN、キャプティブポータル、一部の DNS フィルターは、RevenueCat API やストア API を気付かれない形でブロックします。さらに詳しく調べる前に、別のネットワークを試してください。
8. appUserID を確認します。 logIn(appUserID) がユーザーの想定と異なる ID で呼び出されている場合、エンタイトルメントは別の RC ユーザーに紐付いているため、見つからないように見えます。Purchases.shared.appUserID（iOS）／Purchases.sharedInstance.appUserID（Android）を出力し、想定どおりの ID か確認してください。
9. リセットして再試行します。 アプリをアンインストールし、サンドボックス／テスターアカウントに再度サインインしてから、正しい配布経路で再インストールし、アプリを再起動します。

3. RevenueCat MCP または rc CLI を使ったダッシュボードの確認

上記の手順3、4、または5でダッシュボードの設定に問題があると考えられる場合、ユーザーがまだ動作するアプリを持っていない場合、または修正が反映されたことを確認する必要がある場合に使用します。

重要： API キーは複数のプロジェクトにアクセスできる場合があります。必ず最初に list-projects を呼び出してください。複数のプロジェクトが返された場合は、どのプロジェクトを確認するかユーザーに尋ねてください。

フェーズ A：コンテキストの収集

1. 症状 — 「具体的に何が動作していませんか？どのようなエラーメッセージが表示されていますか？どのプラットフォーム（iOS、Android、Web）ですか？」
2. ユーザーの状態 — 「新規購入と既存のサブスクライバーのどちらで発生していますか？Sandbox と本番環境のどちらですか？」

フェーズ B：体系的な診断

MCP ツールまたはそれに相当する rc CLI コマンド（revenuecat-cli スキルを参照）を使って、以下のチェックリストを順に確認します。各 list-* ツールは rc <noun> list に対応します（例：list-offerings → rc offerings list、list-apps → rc apps list）。list-app-public-api-keys は rc apps keys <app-id> に、get-product-store-state は rc products show <product-id> --store-state に対応します。

チェック 1：プロジェクトの概要

list-projects → ask user to select project if multiple
list-apps (with selected project_id)

• プロジェクトが存在し、アプリが登録されていることを確認します。

チェック 2：製品

list-products
get-product-store-state

• 各ストアアイテムに対応する製品が存在します。
• ストア識別子が App Store Connect／Play Console と完全に一致しています。
• 製品タイプ（サブスクリプションまたは買い切り）が正しく設定されています。
• Play Store：サブスクリプションには product_id:base_plan_id 形式を使用し、買い切り製品には product_id のみを使用します。
• ストアの状態：store_status.status = ok です。

list-products の期間が null でも、製品の設定に問題があるとは限りません（まだ購入されていないだけの場合があります）。ストアの設定は get-product-store-state で判断してください。

チェック 3：エンタイトルメント

list-entitlements
get-products-from-entitlement (for each entitlement)

• 各アクセスレベルにエンタイトルメントが存在します。
• エンタイトルメントに製品が紐付けられています。
• 孤立した製品（どのエンタイトルメントも付与しない製品）がありません。

チェック 4：オファリング

list-offerings (limit: 100)
list-packages (for the offering with is_current: true)

• is_current: true のオファリングが少なくとも 1 つ存在します。
• パッケージに製品が含まれています。
• パッケージ識別子に標準的な規則（$rc_monthly など）が使用されています。

チェック 5：Webhook（サーバー側の問題が疑われる場合）

list-webhook-integrations

• Webhook URL が正しく、アクセス可能です。
• 環境（本番環境または Sandbox）が一致しています。

チェック 6：SDK の互換性（SDK のバージョンに依存する機能に問題がある場合）

ペイウォールコンポーネント、実験への登録、エクスポージャートラッキング、カスタマーセンターの動作、アプリ内通貨、オファリング機能は、最小 SDK バージョンに依存します。SDK バージョンについて主張する前に、revenuecat-sdk-compatibility スキルを読み込んでください。

• list-sdk-feature-gates で機能のゲートを確認しました。
• プロジェクトでの SDK の採用状況に関する主張は、list-sdk-versions で確認しました。
• レポートでは、必要な SDK バージョンとプロジェクトで確認されたバージョンを区別しています。

フェーズ C：報告と修正案の提示

Diagnostic Report
=================
Project: {project_name}

Checks Passed: ✅
  - Project exists and is accessible
  - 2 apps configured (iOS, Android)
  - 4 products found

Issues Found: ⚠️

1. CRITICAL: Product not attached to entitlement
   Product: annual_premium (prod123)
   Fix: Attach this product to an entitlement

2. WARNING: Offering has empty package
   Offering: default / Package: $rc_annual has no products
   Fix: Attach annual_premium to this package

3. INFO: No webhook configured
   Optional but recommended for server-side access control

Recommended Actions:
1. Attach annual_premium to "premium" entitlement
2. Attach annual_premium to $rc_annual package

Would you like me to fix issues #1 and #2 now?

修正可能な問題ごとに、ユーザーに確認してから MCP 経由で実行します。

• attach-products-to-entitlement
• attach-products-to-package

4. プラットフォーム固有の手順

検出されたプラットフォームに対応するファイルを読みます。それぞれのファイルには、上記で扱っていないプラットフォーム固有の注意点（StoreKit 設定ファイル、Gradle／desugaring、Metro のキャッシュ、Expo の prebuild など）が記載されています。

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

5. 修正の確認

次の条件を満たすまで、問題が修正されたと判断しないでください。

1. 以前エラーが表示されていたログに、期待する成功メッセージ（オファリングが少なくとも 1 つのパッケージとともに返された、購入が完了した、エンタイトルメントが有効になった）が表示されること。
2. ダッシュボードに変更が反映されていること。購入の場合は、Customers ページの Sandbox ビューを確認し、取引が正しい appUserID に紐付いていることを確認します。
3. 元の報告にある再現手順が正常に完了すること。

ユーザーがローカルで再現できない場合は、アプリの起動から問題が発生する瞬間までの完全なデバッグログを送ってもらいます。通常、SDK 自体の出力で十分です。

---

参考：SDK のエラーコード

よくあるエラー

エラーコード	考えられる原因	解決策
INVALID_APP_USER_ID	使用できない文字が含まれている、または空文字列	英数字、アンダースコア、ハイフンのみを使用してください
INVALID_CREDENTIALS	API キーが間違っている、またはバンドル ID が一致しない	API キーがアプリと一致することを確認してください
NETWORK_ERROR	ネットワークに接続されていない、またはファイアウォールの問題	ネットワークを確認し、RevenueCat のドメインが許可されていることを確認してください
STORE_PROBLEM	ストアの停止、設定の問題、iOS 18.x のバグ	ストアのステータスを確認し、設定を確認してください。下記の「既知の iOS の問題」も参照してください
SIGNATURE_VERIFICATION_FAILED	レシートの改ざん、または設定エラー	In-App Purchase Key（iOS）またはサービスの認証情報を確認してください

購入エラー

エラーコード	解決策
RECEIPT_ALREADY_IN_USE	restorePurchases() を呼び出すか、顧客を同期してください
PRODUCT_NOT_AVAILABLE_FOR_PURCHASE	App Store Connect / Play Console で商品のステータスを確認してください
PURCHASE_NOT_ALLOWED	ペアレンタルコントロールと支払い方法を確認してください
PRODUCT_ALREADY_PURCHASED	同期するために restorePurchases() を呼び出してください

リファレンス：デバッグログの解釈

開発者にデバッグログを有効にするよう依頼してください：

• iOS：Purchases.logLevel = .debug
• Android：Purchases.logLevel = LogLevel.DEBUG

ログの絵文字インジケーター：🍎 Apple/StoreKit · 🤖 Google Play · 📦 Amazon · 😿 RevenueCat バックエンド。

リファレンス：既知のプラットフォームの問題

iOS

iOS 18.0–18.3.2：StoreKit デーモン接続の失敗

• 症状：実機での購入の約 25% で STORE_PROBLEM（NSCocoaErrorDomain Code 4097）が発生します。
• 対処法：iOS 18.4 以降にアップグレードしてください。

iOS 18.4–18.5 シミュレーター：商品が読み込まれない

• 症状：サンドボックスを使用しているシミュレーターで、商品が空で返されます。
• 影響範囲：シミュレーターのみ。実機と本番環境には影響しません。
• 対処法：実機でテストするか、iOS 26 以降のシミュレーターを備えた Xcode 26 以降を使用してください。

Android

ProxyBillingActivity NullPointerException

• 通常、LG Nexus 5X またはルート化されたデバイスでの自動テストや Play ストアのリリース前レポートによって発生します。
• クラッシュレポートツールでは無視するか、通知を抑制しても問題ありません。

NoCoreLibraryDesugaringException / NoClassDefFoundError

• 対処法：build.gradle でコアライブラリのデシュガリングを有効にするか、minSdk を引き上げてください。

リファレンス：プラットフォーム設定チェックリスト

iOS

• App Store Connect で有料アプリ契約に署名し、銀行口座の詳細をすべて入力してください。また、契約が期限切れでないことを確認してください（ステータスを確認してください。変更の反映には最大 24 時間かかります）。
• Apple Developer Program のメンバーシップが有効で、有効な支払い方法が登録され、自動更新がオンになっていることを確認してください。
• In-App Purchase Key を RevenueCat にアップロードしてください（StoreKit 2 / SDK 5.x 以降）。
• App-Specific Shared Secret も RevenueCat に追加してください。いずれかの認証情報が不足すると、商品やオファリングが読み込まれなくなる可能性があります。
• 商品のステータスが「Ready to Submit」または「Approved」になっていることを確認してください。
• Xcode、App Store Connect、RevenueCat でバンドル ID が完全に一致していることを確認してください。
• 新しい商品は、反映まで 24 時間お待ちください。

Android

• アプリをクローズドテストトラック以上に公開します（内部テストでは機能しません）。
• Play Console でテストアカウントをライセンスを受けたテスターとして追加します。
• サービスアカウントの認証情報（JSON）を Finance 権限付きで RevenueCat にアップロードします。
• サブスクリプションには product_id:base_plan_id 形式を使用します。買い切り商品では product_id のみを使用します。
• 新しい商品は、反映されるまで24時間待ちます。

参考：App Store のリジェクトに関するトラブルシューティング

「Issues fetching products」 — 初回の提出時には、アプリとともに商品を審査に提出する必要があります。App Store Connect で商品を作成し、アプリと商品を一緒に提出してください。

「Error during purchase」（Sandbox） — Apple のサンドボックスが停止している可能性があります。審査担当者に伝え、テスト購入が機能することを示す RevenueCat のサンドボックスダッシュボードのスクリーンショットを提供し、再試行を依頼してください。

「Content not unlocked after purchase」 — RevenueCat で商品とエンタイトルメントの接続を確認してください。購入後にアプリが getCustomerInfo() を呼び出すことを確認してください。

参考：よくある問題

ユーザーが購入したのにエンタイトルメントがない — 商品とエンタイトルメントの関連付けを確認し、ストア識別子が完全に一致していることを確認してください。

Offering が空で返される — current Offering が存在すること、パッケージに商品が関連付けられていること、商品がアプリのストアに存在することを確認してください。

Webhook がイベントを受信しない — URL がインターネットからアクセス可能で、200 OK を返すことを確認してください。webhook.site でテストしてください。

サブスクリプションのステータスが同期されない — SDK は CustomerInfo を5分間（フォアグラウンド時）キャッシュします。強制的に更新します：

// iOS
Purchases.shared.getCustomerInfo(fetchPolicy: .fetchCurrent) { ... }

// Android
Purchases.sharedInstance.getCustomerInfoWith(CacheFetchPolicy.FETCH_CURRENT) { ... }

起動時に SDK がクラッシュする（iOS / Xcode 26） — ほかのネットワークライブラリより先に RevenueCat を初期化してください。

起動時に SDK がクラッシュする（Android） — コアライブラリのデシュガリングを有効にするか、minSdk を24以上に引き上げてください。