integrating-superwall-expo（整合超级墙博览会）

Integrating Superwall in React Native Expo (expo-superwall)

Why this skill exists

Superwall’s Expo SDK (expo-superwall) is *native-module based*, so Expo Go won’t work and setup mistakes often look like “Cannot find native module 'SuperwallExpo'”. This skill provides a reliable, repeatable workflow to:

• install + configure expo-superwall correctly in Expo SDK 53+
• present paywalls via placements (remote campaigns) and implement feature gating
• manage users + attributes, and keep subscription status in sync (including RevenueCat)
• wire deep links / web checkout, and troubleshoot the common integration failures

Non‑negotiables (check first)

1. Expo SDK 53+ is required for expo-superwall.
2. Expo Go is not supported. Use an Expo Development Build (npx expo run:ios|android or EAS dev client).
3. Target minimum OS versions:

- iOS deployment target: 15.1+ - Android minSdkVersion: 21+

1. Superwall config does not refetch during hot reload. After dashboard changes (paywalls/products/campaigns), fully restart the app.

Fast path checklist (copy/paste and tick)

• Confirm Expo SDK version (>=53) and you are *not* using Expo Go
• Install packages: expo-superwall (+ expo-build-properties if needed)
• Set iOS/Android minimum versions via expo-build-properties
• Wrap app with <SuperwallProvider> (+ <SuperwallLoading/>, <SuperwallError/>, <SuperwallLoaded/>)
• Register a first placement with usePlacement().registerPlacement({placement: "…"})
• (Optional) Implement feature gating via feature: () => … callback
• (Optional) Identify user + set user attributes with useUser()
• (Optional) Sync subscription status (built-in, or manual when using RevenueCat/custom billing)
• Rebuild dev client after native changes (npx expo prebuild --clean if needed)
• Validate with: node {baseDir}/scripts/check-setup.mjs

Default implementation pattern (recommended)

1) Install + platform targets

Follow the Superwall install guide in references/INSTALLATION.md.

2) Configure Superwall at the root

Use <SuperwallProvider /> at the top of your app (typically in App.tsx or your root layout). Add loading/error handling components so failures are visible.

See references/CONFIGURATION.md and assets/snippets/App.tsx.

3) Present paywalls & gate features via placements

Use the usePlacement hook to register placements. This is the “one API” that powers:

• presenting paywalls
• feature gating (run feature callback depending on dashboard “Gated/Non‑Gated”)
• tracking paywall lifecycle state in React

See references/PLACEMENTS_AND_GATING.md.

4) Manage users, attributes, and subscription state

• Identify on login with useUser().identify(userId)
• Sign out with useUser().signOut()
• Set/merge attributes with useUser().update({…}) (pass null to unset)

See:

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

5) Deep links & web checkout (optional)

If you want paywall previews from the dashboard, campaign-driven paywalls from deep links, or web checkout flows, wire deep links and forward incoming URLs to Superwall.

See references/DEEP_LINKS.md.

6) RevenueCat (optional, recommended approach)

If you want RevenueCat to own purchases while Superwall owns paywalls/experiments, use CustomPurchaseControllerProvider (hooks-based) and sync entitlement state to Superwall.

See references/REVENUECAT.md.

Troubleshooting playbook (use when things don’t work)

If you hit Cannot find native module 'SuperwallExpo', or paywalls never show:

1. Run the setup checker:

- node {baseDir}/scripts/check-setup.mjs

1. Confirm you’re on a dev build, not Expo Go.
2. If you added expo-superwall to an existing project, regenerate native folders:

- npx expo prebuild --clean *(backs up any manual native edits first)*

1. Rebuild the dev client (EAS or local) after adding native modules.
2. Clear caches and reinstall deps as needed.

Full triage checklist: references/TROUBLESHOOTING.md.

Output expectations when performing work in a repo

When applying this skill to a real codebase, prefer a small, reviewable set of changes:

• package.json dependency updates
• app.json / app.config.* plugin + platform target updates
• Root provider wiring (App.tsx/RootLayout)
• A small “first placement” screen/button for verification
• Optional: src/superwall/placements.ts constants and src/superwall/sync.ts for RevenueCat status sync

Include a short “How to test locally” note (dev build commands + which placement to trigger).

Reference map (read only when needed)

• Install + prerequisites: references/INSTALLATION.md
• Provider + options: references/CONFIGURATION.md
• Placements, gating, presentation results: references/PLACEMENTS_AND_GATING.md
• Users + attributes: references/USER_MANAGEMENT.md
• Subscription state: references/SUBSCRIPTION_STATUS.md
• Event listeners + analytics forwarding: references/EVENTS_ANALYTICS.md
• Deep links, previews, web checkout: references/DEEP_LINKS.md
• RevenueCat integration: references/REVENUECAT.md
• Debugging: references/TROUBLESHOOTING.md
• StoreKit testing: references/STOREKIT_TESTING.md
• Locale override: references/LOCALE.md
• Bare RN + Expo modules: references/BARE_REACT_NATIVE.md
• Migration / compat API: references/MIGRATION_COMPAT.md