Superwall
Change your paywall design from a dashboard instead of shipping a build.
Superwall is optional, and sits on top of RevenueCat rather than replacing it.
Your agent can create the placements and paywalls below for you. See agent tools.
How it fits with RevenueCat
RevenueCat is always in charge of purchases and entitlements, and tells your app (and the edge functions) whether a user is Pro. Superwall only decides which paywall screen to show, and when.
| Without Superwall | With Superwall | |
|---|---|---|
| Purchases & entitlements | RevenueCat | RevenueCat |
| Paywall UI | RevenueCat’s own paywall | Superwall, configured on their dashboard |
| Changing the paywall | New app build | Dashboard change, no build |
If EXPO_PUBLIC_SUPERWALL_KEY is unset, the Superwall SDK is never mounted and paywalls come from RevenueCat.
Placements
NativeExpress presents paywalls through a single function, presentPaywall(placement) in src/lib/paywall.tsx. There are two placements:
| Placement | Triggered when |
|---|---|
onboarding_end | The user finishes (or skips) the last onboarding step |
quota_exceeded | The user runs out of free AI messages |
Without Superwall, onboarding_end opens RevenueCat’s paywall directly and quota_exceeded opens a bottom sheet with an upgrade button that then opens RevenueCat’s paywall. With Superwall configured, both route through Superwall’s registerPlacement instead.
Setup
Create a Superwall app
Sign up at superwall.com , create an app, and copy the public API key from Settings → Keys.
Add the key to your environment file
EXPO_PUBLIC_SUPERWALL_KEY=""NativeExpress passes the same key for both iOS and Android. If you use separate Superwall apps per platform, edit src/provider/SuperwallProvider.tsx and split the apiKeys object.
Create the two placements on the dashboard
In Superwall, add placements named exactly onboarding_end and quota_exceeded, and attach a paywall to each. The names must match one-to-one, because NativeExpress passes them through unchanged.
Rebuild
expo-superwall includes native code, so a JS reload is not enough:
yarn ios
# or
yarn androidVerify
Finishing onboarding shows your Superwall paywall instead of RevenueCat’s. If you still see the RevenueCat paywall, the key is missing from the build, because environment variables are inlined at build time and need a rebuild after you add one.
Turning it off
Remove EXPO_PUBLIC_SUPERWALL_KEY from your environment file and rebuild. Nothing else needs to change, because src/provider/SuperwallProvider.tsx checks for the key and skips mounting the SDK entirely when it is absent.