integrating-superwall-expo

React Native Expo への Superwall の統合（expo-superwall）

このスキルが存在する理由

Superwall の Expo SDK（expo-superwall）はネイティブモジュールベースのため、Expo Go では動作せず、設定を誤ると「Cannot find native module 'SuperwallExpo'」のようなエラーが発生することがよくあります。このスキルでは、次の作業を確実かつ再現可能な手順で進められます。

• Expo SDK 53 以降で expo-superwall を正しくインストールして設定する
• プレースメント（リモートキャンペーン）を使ってペイウォールを表示し、機能のゲーティングを実装する
• ユーザーと属性を管理し、サブスクリプションのステータスを同期する（RevenueCat を含む）
• ディープリンク／ウェブチェックアウトを接続し、よくある統合時の問題を解決する

必須事項（最初に確認）

1. expo-superwall には Expo SDK 53 以降が必要です。
2. Expo Go はサポートされていません。Expo Development Build（npx expo run:ios|android または EAS dev client）を使用してください。
3. 最小 OS バージョンの要件：
   • iOS deployment target：15.1 以降
   • Android minSdkVersion：21 以降
4. Superwall の設定はホットリロード中に再取得されません。ダッシュボードを変更した後（ペイウォール／製品／キャンペーンなど）は、アプリを完全に再起動してください。

クイックスタートのチェックリスト（コピーしてチェック）

• Expo SDK のバージョンが 53 以降で、Expo Go を使用していないことを確認する
• パッケージをインストールする：expo-superwall（必要に応じて expo-build-properties も）
• expo-build-properties で iOS／Android の最小バージョンを設定する
• アプリを <SuperwallProvider> でラップする（<SuperwallLoading/>、<SuperwallError/>、<SuperwallLoaded/> も追加する）
• usePlacement().registerPlacement({ placement: "…" }) で最初のプレースメントを登録する
• （任意）feature: () => … コールバックを使って機能のゲーティングを実装する
• （任意）useUser() でユーザーを識別し、ユーザー属性を設定する
• （任意）サブスクリプションのステータスを同期する（組み込み機能を使うか、RevenueCat／カスタム課金を使う場合は手動で同期する）
• ネイティブ側を変更した後は開発クライアントを再ビルドする（必要に応じて npx expo prebuild --clean を実行する）
• 次のコマンドで検証する：node {baseDir}/scripts/check-setup.mjs

推奨される基本実装パターン

1) インストールとプラットフォームの最小バージョン

Superwall のインストールガイド（references/INSTALLATION.md）に従ってください。

2) アプリのルートで Superwall を設定する

アプリの最上位（通常は App.tsx またはルートレイアウト）で <SuperwallProvider /> を使用してください。エラーを確認できるよう、ローディング／エラー処理用のコンポーネントも追加してください。

references/CONFIGURATION.md と assets/snippets/App.tsx を参照してください。

3) プレースメントでペイウォールを表示し、機能をゲーティングする

usePlacement フックを使ってプレースメントを登録してください。これは次の機能を担う「単一の API」です。

• ペイウォールの表示
• 機能のゲーティング（ダッシュボードの「Gated／Non-Gated」の設定に応じて feature コールバックを実行する）
• React でのペイウォールのライフサイクル状態の追跡

references/PLACEMENTS_AND_GATING.md を参照してください。

4) ユーザー、属性、サブスクリプションの状態を管理する

• ログイン時に useUser().identify(userId) でユーザーを識別する
• useUser().signOut() でサインアウトする
• useUser().update({ … }) で属性を設定／マージする（解除するには null を渡す）

以下を参照してください。

• references/USER_MANAGEMENT.md
• references/SUBSCRIPTION_STATUS.md

5) ディープリンクとウェブチェックアウト（任意）

ダッシュボードからペイウォールのプレビューを表示する場合、ディープリンクでキャンペーン駆動型のペイウォールを表示する場合、またはウェブチェックアウトのフローを使う場合は、ディープリンクを接続し、受信した URL を Superwall に渡してください。

references/DEEP_LINKS.md を参照してください。

6) RevenueCat（任意、推奨される方法）

購入処理を RevenueCat に任せ、ペイウォール／実験を Superwall に任せる場合は、CustomPurchaseControllerProvider（フックベース）を使用し、エンタイトルメントの状態を Superwall に同期してください。

references/REVENUECAT.md を参照してください。

トラブルシューティングの手順（問題が発生した場合に使用）

Cannot find native module 'SuperwallExpo' が表示される場合や、ペイウォールがまったく表示されない場合：

1. セットアップチェッカーを実行します。
   • node {baseDir}/scripts/check-setup.mjs
2. Expo Go ではなく、開発ビルドを使用していることを確認します。
3. 既存のプロジェクトに expo-superwall を追加した場合は、ネイティブフォルダーを再生成します。
   • npx expo prebuild --clean （手動で加えたネイティブの変更は、最初にバックアップしてください）
4. ネイティブモジュールを追加した後、開発クライアントを再ビルドします（EAS またはローカル）。
5. 必要に応じてキャッシュをクリアし、依存関係を再インストールします。

完全なトリアージ用チェックリスト：references/TROUBLESHOOTING.md。

リポジトリで作業する際に期待される出力

実際のコードベースにこのスキルを適用する場合は、レビューしやすい小規模な変更を優先してください。

• package.json の依存関係の更新
• app.json / app.config.* のプラグインとプラットフォームターゲットの更新
• ルートプロバイダーの配線（App.tsx/RootLayout）
• 検証用の小さな「最初の配置」画面／ボタン
• オプション：src/superwall/placements.ts の定数と、RevenueCat のステータス同期用の src/superwall/sync.ts

開発ビルドのコマンドとトリガーする配置を含む、簡潔な「ローカルでのテスト方法」のメモを記載してください。

リファレンスマップ（必要な場合にのみ参照）

• インストールと前提条件：references/INSTALLATION.md
• プロバイダーとオプション：references/CONFIGURATION.md
• 配置、ゲーティング、表示結果：references/PLACEMENTS_AND_GATING.md
• ユーザーと属性：references/USER_MANAGEMENT.md
• サブスクリプションの状態：references/SUBSCRIPTION_STATUS.md
• イベントリスナーと分析データの転送：references/EVENTS_ANALYTICS.md
• ディープリンク、プレビュー、ウェブチェックアウト：references/DEEP_LINKS.md
• RevenueCat の統合：references/REVENUECAT.md
• デバッグ：references/TROUBLESHOOTING.md
• StoreKit のテスト：references/STOREKIT_TESTING.md
• ロケールの上書き：references/LOCALE.md
• Bare RN と Expo モジュール：references/BARE_REACT_NATIVE.md
• 移行／互換 API：references/MIGRATION_COMPAT.md