Superwall
Use Superwall campaigns to control the onboarding and quota paywalls.
Prerequisites
Complete RevenueCat setup and run a development build. The app uses RevenueCat entitlements to decide Pro access.
How it fits with RevenueCat
| RevenueCat paywalls | Superwall placements | |
|---|---|---|
| Paywall design | RevenueCat dashboard | Superwall dashboard |
| Onboarding and quota triggers | Included | Included |
| RevenueCat purchase handling | Included | Requires the integration below |
The boilerplate mounts Superwall when the key for the current platform,
EXPO_PUBLIC_SUPERWALL_API_KEY_APPLE or EXPO_PUBLIC_SUPERWALL_API_KEY_GOOGLE, is set. It
does not connect Superwall’s purchase controller or synchronize its subscription
status with RevenueCat. Add that integration before selling through a Superwall
paywall.
Placements
presentPaywall from @/services/paywall passes these names to Superwall:
| Placement | Trigger |
|---|---|
onboarding_end | The user finishes or skips the final onboarding step. |
quota_exceeded | An AI request needs the upgrade flow, such as an exhausted free quota. |
Without Superwall, onboarding opens RevenueCat’s paywall and the quota placement
opens an upgrade sheet. When Superwall is enabled, both use its
registerPlacement call.
The Profile screen’s Paywall component uses RevenueCat directly. Change that
screen separately if you want Superwall there too.
Setup
Create a Superwall app
Create an app in the Superwall dashboard and copy its public API key. Add the store products used by your paywall.
Add the key
EXPO_PUBLIC_SUPERWALL_API_KEY_APPLE="<your-ios-public-key>"
EXPO_PUBLIC_SUPERWALL_API_KEY_GOOGLE="<your-android-public-key>"For cloud builds, add it to the EAS environment selected by the build profile.
src/provider/PaywallProvider.tsx passes this key to both iOS and
Android. If Superwall gives you different platform keys, update its
apiKeys mapping and the key-based adapter selection in
src/services/paywall/paywall.ts.
Connect RevenueCat purchase handling
Follow Superwall’s RevenueCat integration guide to handle purchases and restores through RevenueCat and synchronize subscription status.
Add this around the existing Superwall provider in
src/provider/PaywallProvider.tsx. Keep RevenueCat configured by
RevenueCatProvider, and use the same Supabase user ID for both services.
Verify that the Pro entitlement checked by NativeExpress is the entitlement your Superwall products grant.
Configure the campaigns
Add the placements onboarding_end and quota_exceeded to your
campaigns. Attach a paywall and set an audience that includes your test user.
The placement names must match the code exactly.
Reload the app
Restart the development server after editing .env.local. The
expo-superwall native module is already included in the boilerplate’s
development build. Rebuild when changing native dependencies or when testing
updated environment values in a standalone build.
Verify
Complete onboarding and trigger the quota placement. Confirm the intended paywall appears for each campaign.
Complete a sandbox purchase and a restore. Check the customer’s RevenueCat record, the Pro status in Profile and a paid AI action. A displayed paywall alone does not verify purchase handling.
Turning it off
Remove both EXPO_PUBLIC_SUPERWALL_API_KEY_* variables and restart the development server. For
standalone builds, remove it from the build environment and rebuild.
The provider then skips Superwall, and the placement service uses RevenueCat’s paywall and the quota sheet.