Expo RevenueCat plus Superwall Integration
Use this skill to add or repair a modern RevenueCat plus Superwall stack in a React Native Expo app.
What this skill should do
- Choose the correct monetisation architecture before editing code.
- Integrate with the repository's existing app shell, auth layer, and state management.
- Prefer safe, production-ready defaults over the shortest possible demo.
- Leave the user with code changes plus a clear list of remaining dashboard, store, and testing steps.
Critical rules
- Treat this as an Expo development-build integration, not an Expo Go integration.
- Target Expo SDK 53 or newer.
- Target iOS deployment target 15.1 or newer and Android min SDK 23 or newer.
- Use public SDK keys only in the client.
- Configure RevenueCat exactly once.
- Mount Superwall near the app root exactly once.
- Use the same stable, non-guessable, non-PII user identifier in RevenueCat and Superwall when the product has authentication.
- Never use email addresses as RevenueCat or Superwall user IDs.
- Do not call
syncPurchases() on every launch. Use it only for deliberate migration or account-recovery scenarios.
restorePurchases() is user-triggered. Do not hide it inside startup code.
- On Android, ensure the launch mode is
standard or singleTop.
- Prefer a full app restart after Superwall dashboard changes during Expo development.
First actions
Inspect the repository before editing:
package.json
app.json, app.config.js, or app.config.ts
App.tsx or app/_layout.tsx
- any existing auth provider
- any existing purchase, paywall, or entitlement code
Run the validator if Python is available:
python3 scripts/validate_expo_setup.py
- or
python3 scripts/validate_expo_setup.py --project-root /path/to/app
Answer these six preflight questions before choosing code:
- Is the app login-first, login-optional, or guest-first
- Is there existing purchase completion logic already in the repo
- Does Google Play use multiple base plans or offers
- Are App Store Server Notifications, Google server notifications, webhooks, or backend attribution in scope
- Is the entitlement model single-tier or multi-tier
- Does the product need strict account ownership, or easy restore across account confusion
Open only the references you need:
- Core workflow:
references/implementation-playbook.md
- Architecture choice:
references/architecture-decision-tree.md
- Identity and restores:
references/identity-and-restore-behaviour.md
- Android offers:
references/android-base-plans-offers-and-pending.md
- iOS UUID and server notifications:
references/ios-uuid-appaccounttoken-and-server-notifications.md
- Observability and verification:
references/observability-and-entitlement-verification.md
- Test planning:
references/testing-matrix.md
- Dashboard alignment:
references/dashboard-checklist.md
- Failure modes:
references/troubleshooting.md
Architecture choice
Default for most new Expo apps
Choose Architecture A: CustomPurchaseControllerProvider when:
- Superwall is the paywall surface.
- RevenueCat is the purchase and entitlement source of truth.
- The app does not already have its own mature purchase completion pipeline.
- You want the cleanest modern Expo integration.
Use:
references/architecture-decision-tree.md
references/examples/monetization.shared.tsx
references/examples/app.example.tsx
references/examples/expo-router-layout.example.tsx
references/examples/custom-purchase-controller.android-offers.tsx
Use the migration path when the repo already owns purchase completion
Choose Architecture B: purchasesAreCompletedBy / observer-mode migration when:
- The app already finishes transactions itself.
- The user explicitly wants to keep existing IAP code.
- You are layering RevenueCat analytics, entitlements, or dashboards onto an existing billing implementation.
- You must import historical purchases carefully.
Use:
references/architecture-decision-tree.md
references/examples/observer-mode-migration.tsx
references/identity-and-restore-behaviour.md
Shared implementation workflow
1. Audit the repo
Collect these facts before changing code:
- Expo SDK version
- package manager
- router style: Expo Router or plain
App.tsx
- whether
expo-superwall, react-native-purchases, and expo-build-properties are already installed
- current iOS deployment target and Android min SDK
- whether the app has auth
- whether the repo already has RevenueCat, Superwall, StoreKit, Google Play Billing, or
react-native-iap code
- whether the project already ships one-time products in addition to subscriptions
2. Align dashboards before deep code edits
Confirm the conceptual setup first:
- RevenueCat project exists for iOS and Android
- store products exist
- entitlements exist
- offerings exist where needed
- Superwall project exists
- Superwall public keys exist for both platforms
- placements and campaigns exist
- product IDs and entitlement IDs match the intended runtime mapping
Use references/dashboard-checklist.md.
3. Install only the packages you actually need
Base stack:
npx expo install expo-superwall react-native-purchases expo-build-properties
Optional only if the user explicitly wants RevenueCat UI screens such as a customer center:
npx expo install react-native-purchases-ui
Do not add react-native-purchases-ui just because RevenueCat is installed.
4. Update Expo config
Add or repair expo-build-properties and set platform minimums. Preserve the repository's config style and existing plugins.
5. Configure RevenueCat once
- Use the correct public key for the current platform.
- Configure once on startup.
- If the app always requires a known user ID, prefer configuring with that ID instead of creating an anonymous state first.
- If the app allows guests, configure without an App User ID and later call
logIn() when auth resolves.
6. Mount providers once near the root
For Architecture A, the normal order is:
- configure RevenueCat
- mount
CustomPurchaseControllerProvider
- mount
SuperwallProvider
- show
SuperwallLoading
- render the app inside
SuperwallLoaded
- mount one subscription sync component inside the loaded tree
7. Sync RevenueCat entitlements into Superwall
When Superwall is not directly owning purchase state, map RevenueCat entitlements into setSubscriptionStatus.
- Fetch
CustomerInfo on launch or when premium UI opens.
- Subscribe to
addCustomerInfoUpdateListener.
- Map active entitlement IDs into Superwall entitlements.
- Prefer syncing the full entitlement set, not just a boolean.
8. Sync identities deliberately
- Reuse the app's real auth state.
- For login-first apps, prefer configuring RevenueCat with a custom App User ID from the start.
- For guest-first apps, configure anonymously, then on login call
Purchases.logIn(userId) and identify(userId).
- If switching from one known account to another, call
logIn(newUserId) directly. Do not force a pointless logout first.
- Only call
logOut() if the product truly supports an anonymous post-logout state.
See references/identity-and-restore-behaviour.md and references/examples/auth-sync.example.tsx.
9. Register placements from premium entry points
- Use business-action placement names such as
upgrade_pro, remove_limits, or export_pdf.
- Prefer placement-driven gating and dashboard audiences over hard-coded paywall branching.
- Use
getPresentationResult() only when you need to inspect what Superwall would do before presenting.
10. Add observability
- Forward Superwall events into the app's analytics pipeline.
- Keep debug logs enabled in development only.
- Consider checking RevenueCat trusted entitlement verification in high-risk apps.
See references/observability-and-entitlement-verification.md.
11. Test with a matrix, not one happy path
Always verify:
- cold start on iOS and Android
- purchase success
- cancel flow
- pending flow where relevant
- restore
- guest to logged-in transition
- account switch
- reinstall
- dashboard changes after a full restart
- entitlement unlock in UI
- webhook or server-notification identity consistency when relevant
Use references/testing-matrix.md.
What to avoid
- Do not use
expo-superwall/compat for new work.
- Do not promise real Superwall support inside Expo Go.
- Do not call
restorePurchases() automatically during startup.
- Do not call
syncPurchases() on every launch.
- Do not use emails, IDFA, device IDs, or hardcoded strings as billing IDs.
- Do not leave duplicate purchase flows in place.
- Do not ship Android API 21 just because Superwall alone supports it; the combined stack needs Android 23 or newer.
Final answer expectations
When you finish editing a repo, your response should include:
- the files changed
- the chosen architecture and why
- any manual RevenueCat, Superwall, App Store Connect, or Play Console steps still required
- any assumptions about entitlements, product IDs, placements, restore behaviour, or account model
- any migration debt intentionally left in place
- how to run and test the development build
1---
2name: expo-revenuecat-superwall-integration
3description: Adds, repairs, or migrates a production-grade RevenueCat plus Superwall integration in a React Native Expo app for iOS and Android. Chooses between CustomPurchaseControllerProvider and purchasesAreCompletedBy or observer-mode migration, wires Expo config and development builds, syncs identities and entitlements, handles Android base plans and offers, iOS UUID appAccountToken quirks, restore behaviour, analytics, testing, and troubleshooting. Use when the user asks to add subscriptions, paywalls, RevenueCat, Superwall, entitlements, restore flows, account switching, or monetisation migration in an Expo app. Do not use for bare React Native, RevenueCat-only UI work, or web-only billing.
4license: MIT
5compatibility: Designed for coding agents editing a React Native Expo repository. Best for Expo SDK 53 or newer apps using development builds, iOS deployment target 15.1 or higher, and Android min SDK 23 or higher.
6metadata:
7 source: https://skillmd.com/skills/tristanmanchester/expo-revenuecat-superwall-integration
8 author: OpenAI
9 version: "2.0.0"
10 category: mobile-monetization
11 stack: react-native-expo
12 platforms:
13 - ios
14 - android
15 integrations:
16 - revenuecat
17 - superwall
18---
19
20# Expo RevenueCat plus Superwall Integration
21
22Use this skill to add or repair a modern RevenueCat plus Superwall stack in a React Native Expo app.
23
24## What this skill should do
25
26- Choose the correct monetisation architecture before editing code.
27- Integrate with the repository's existing app shell, auth layer, and state management.
28- Prefer safe, production-ready defaults over the shortest possible demo.
29- Leave the user with code changes plus a clear list of remaining dashboard, store, and testing steps.
30
31## Critical rules
32
33- Treat this as an Expo development-build integration, not an Expo Go integration.
34- Target Expo SDK 53 or newer.
35- Target iOS deployment target 15.1 or newer and Android min SDK 23 or newer.
36- Use public SDK keys only in the client.
37- Configure RevenueCat exactly once.
38- Mount Superwall near the app root exactly once.
39- Use the same stable, non-guessable, non-PII user identifier in RevenueCat and Superwall when the product has authentication.
40- Never use email addresses as RevenueCat or Superwall user IDs.
41- Do not call `syncPurchases()` on every launch. Use it only for deliberate migration or account-recovery scenarios.
42- `restorePurchases()` is user-triggered. Do not hide it inside startup code.
43- On Android, ensure the launch mode is `standard` or `singleTop`.
44- Prefer a full app restart after Superwall dashboard changes during Expo development.
45
46## First actions
47
481. Inspect the repository before editing:
49 - `package.json`
50 - `app.json`, `app.config.js`, or `app.config.ts`
51 - `App.tsx` or `app/_layout.tsx`
52 - any existing auth provider
53 - any existing purchase, paywall, or entitlement code
54
552. Run the validator if Python is available:
56 - `python3 scripts/validate_expo_setup.py`
57 - or `python3 scripts/validate_expo_setup.py --project-root /path/to/app`
58
593. Answer these six preflight questions before choosing code:
60 - Is the app login-first, login-optional, or guest-first
61 - Is there existing purchase completion logic already in the repo
62 - Does Google Play use multiple base plans or offers
63 - Are App Store Server Notifications, Google server notifications, webhooks, or backend attribution in scope
64 - Is the entitlement model single-tier or multi-tier
65 - Does the product need strict account ownership, or easy restore across account confusion
66
674. Open only the references you need:
68 - Core workflow: `references/implementation-playbook.md`
69 - Architecture choice: `references/architecture-decision-tree.md`
70 - Identity and restores: `references/identity-and-restore-behaviour.md`
71 - Android offers: `references/android-base-plans-offers-and-pending.md`
72 - iOS UUID and server notifications: `references/ios-uuid-appaccounttoken-and-server-notifications.md`
73 - Observability and verification: `references/observability-and-entitlement-verification.md`
74 - Test planning: `references/testing-matrix.md`
75 - Dashboard alignment: `references/dashboard-checklist.md`
76 - Failure modes: `references/troubleshooting.md`
77
78## Architecture choice
79
80### Default for most new Expo apps
81
82Choose **Architecture A: CustomPurchaseControllerProvider** when:
83
84- Superwall is the paywall surface.
85- RevenueCat is the purchase and entitlement source of truth.
86- The app does not already have its own mature purchase completion pipeline.
87- You want the cleanest modern Expo integration.
88
89Use:
90- `references/architecture-decision-tree.md`
91- `references/examples/monetization.shared.tsx`
92- `references/examples/app.example.tsx`
93- `references/examples/expo-router-layout.example.tsx`
94- `references/examples/custom-purchase-controller.android-offers.tsx`
95
96### Use the migration path when the repo already owns purchase completion
97
98Choose **Architecture B: purchasesAreCompletedBy / observer-mode migration** when:
99
100- The app already finishes transactions itself.
101- The user explicitly wants to keep existing IAP code.
102- You are layering RevenueCat analytics, entitlements, or dashboards onto an existing billing implementation.
103- You must import historical purchases carefully.
104
105Use:
106- `references/architecture-decision-tree.md`
107- `references/examples/observer-mode-migration.tsx`
108- `references/identity-and-restore-behaviour.md`
109
110## Shared implementation workflow
111
112### 1. Audit the repo
113
114Collect these facts before changing code:
115
116- Expo SDK version
117- package manager
118- router style: Expo Router or plain `App.tsx`
119- whether `expo-superwall`, `react-native-purchases`, and `expo-build-properties` are already installed
120- current iOS deployment target and Android min SDK
121- whether the app has auth
122- whether the repo already has RevenueCat, Superwall, StoreKit, Google Play Billing, or `react-native-iap` code
123- whether the project already ships one-time products in addition to subscriptions
124
125### 2. Align dashboards before deep code edits
126
127Confirm the conceptual setup first:
128
129- RevenueCat project exists for iOS and Android
130- store products exist
131- entitlements exist
132- offerings exist where needed
133- Superwall project exists
134- Superwall public keys exist for both platforms
135- placements and campaigns exist
136- product IDs and entitlement IDs match the intended runtime mapping
137
138Use `references/dashboard-checklist.md`.
139
140### 3. Install only the packages you actually need
141
142Base stack:
143
144- `npx expo install expo-superwall react-native-purchases expo-build-properties`
145
146Optional only if the user explicitly wants RevenueCat UI screens such as a customer center:
147
148- `npx expo install react-native-purchases-ui`
149
150Do not add `react-native-purchases-ui` just because RevenueCat is installed.
151
152### 4. Update Expo config
153
154Add or repair `expo-build-properties` and set platform minimums. Preserve the repository's config style and existing plugins.
155
156### 5. Configure RevenueCat once
157
158- Use the correct public key for the current platform.
159- Configure once on startup.
160- If the app always requires a known user ID, prefer configuring with that ID instead of creating an anonymous state first.
161- If the app allows guests, configure without an App User ID and later call `logIn()` when auth resolves.
162
163### 6. Mount providers once near the root
164
165For Architecture A, the normal order is:
166
1671. configure RevenueCat
1682. mount `CustomPurchaseControllerProvider`
1693. mount `SuperwallProvider`
1704. show `SuperwallLoading`
1715. render the app inside `SuperwallLoaded`
1726. mount one subscription sync component inside the loaded tree
173
174### 7. Sync RevenueCat entitlements into Superwall
175
176When Superwall is not directly owning purchase state, map RevenueCat entitlements into `setSubscriptionStatus`.
177
178- Fetch `CustomerInfo` on launch or when premium UI opens.
179- Subscribe to `addCustomerInfoUpdateListener`.
180- Map active entitlement IDs into Superwall entitlements.
181- Prefer syncing the full entitlement set, not just a boolean.
182
183### 8. Sync identities deliberately
184
185- Reuse the app's real auth state.
186- For login-first apps, prefer configuring RevenueCat with a custom App User ID from the start.
187- For guest-first apps, configure anonymously, then on login call `Purchases.logIn(userId)` and `identify(userId)`.
188- If switching from one known account to another, call `logIn(newUserId)` directly. Do not force a pointless logout first.
189- Only call `logOut()` if the product truly supports an anonymous post-logout state.
190
191See `references/identity-and-restore-behaviour.md` and `references/examples/auth-sync.example.tsx`.
192
193### 9. Register placements from premium entry points
194
195- Use business-action placement names such as `upgrade_pro`, `remove_limits`, or `export_pdf`.
196- Prefer placement-driven gating and dashboard audiences over hard-coded paywall branching.
197- Use `getPresentationResult()` only when you need to inspect what Superwall would do before presenting.
198
199### 10. Add observability
200
201- Forward Superwall events into the app's analytics pipeline.
202- Keep debug logs enabled in development only.
203- Consider checking RevenueCat trusted entitlement verification in high-risk apps.
204
205See `references/observability-and-entitlement-verification.md`.
206
207### 11. Test with a matrix, not one happy path
208
209Always verify:
210
211- cold start on iOS and Android
212- purchase success
213- cancel flow
214- pending flow where relevant
215- restore
216- guest to logged-in transition
217- account switch
218- reinstall
219- dashboard changes after a full restart
220- entitlement unlock in UI
221- webhook or server-notification identity consistency when relevant
222
223Use `references/testing-matrix.md`.
224
225## What to avoid
226
227- Do not use `expo-superwall/compat` for new work.
228- Do not promise real Superwall support inside Expo Go.
229- Do not call `restorePurchases()` automatically during startup.
230- Do not call `syncPurchases()` on every launch.
231- Do not use emails, IDFA, device IDs, or hardcoded strings as billing IDs.
232- Do not leave duplicate purchase flows in place.
233- Do not ship Android API 21 just because Superwall alone supports it; the combined stack needs Android 23 or newer.
234
235## Final answer expectations
236
237When you finish editing a repo, your response should include:
238
239- the files changed
240- the chosen architecture and why
241- any manual RevenueCat, Superwall, App Store Connect, or Play Console steps still required
242- any assumptions about entitlements, product IDs, placements, restore behaviour, or account model
243- any migration debt intentionally left in place
244- how to run and test the development build