@superwall/cli 1.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (85) hide show
  1. package/LICENSE +21 -0
  2. package/README.md +201 -0
  3. package/dist/actions-MB-eBY64.js +140 -0
  4. package/dist/api-BF7-toqM.js +151 -0
  5. package/dist/api-output-B5hh0q4V.js +20 -0
  6. package/dist/app-K6j9Es7h.js +189 -0
  7. package/dist/asc-CArSwo5D.js +539 -0
  8. package/dist/asc-products-YQ6Oc6YO.js +93 -0
  9. package/dist/auth-CY2cO_NF.js +139 -0
  10. package/dist/auth.d.ts +30 -0
  11. package/dist/auth.js +4 -0
  12. package/dist/billing-DWyfEQ6l.js +80 -0
  13. package/dist/bind-hslFhcTR.js +213 -0
  14. package/dist/chunk-DQxbwPpZ.js +30 -0
  15. package/dist/command-Kwx4ekbo.js +283 -0
  16. package/dist/create-Bbi8BOO1.js +410 -0
  17. package/dist/dev-D0lQDCQI.js +397 -0
  18. package/dist/devtools-8EgLo86w.js +3638 -0
  19. package/dist/doctor-ByeRdMcl.js +88 -0
  20. package/dist/drivers-DVAZgone.js +413 -0
  21. package/dist/entry.d.ts +9 -0
  22. package/dist/entry.js +495 -0
  23. package/dist/existing-CcJrIIAU.js +88 -0
  24. package/dist/feedback-Z0Wk7VC5.js +73 -0
  25. package/dist/git-3OX9u3xE.js +433 -0
  26. package/dist/hosted-CHwaUqLd.js +32 -0
  27. package/dist/integrate-DqOAqK7J.js +863 -0
  28. package/dist/json-C3hPIMkI.js +7 -0
  29. package/dist/login-Dr8UN_Gx.js +290 -0
  30. package/dist/migrate-D92bJTg6.js +114 -0
  31. package/dist/org-B2gy9Pmu.js +40 -0
  32. package/dist/params-Bvq0iqQK.js +52 -0
  33. package/dist/pipeline-CHHIg6BU.js +1056 -0
  34. package/dist/print-skill-BnZAk7dV.js +74 -0
  35. package/dist/promote-CRe9170G.js +88 -0
  36. package/dist/publish-DsODvrOD.js +35 -0
  37. package/dist/push-BDkZUC0v.js +35 -0
  38. package/dist/query-DIllrSnk.js +53 -0
  39. package/dist/resource-CdP1MDla.js +483 -0
  40. package/dist/resources-CVrWwA1K.js +233 -0
  41. package/dist/run-cGGBUMs5.js +89 -0
  42. package/dist/scan-BQexuUPO.js +236 -0
  43. package/dist/skills-DhuUs28u.js +64 -0
  44. package/dist/skills-xrfXt9u0.js +205 -0
  45. package/dist/spawn-DSoTXy_j.js +69 -0
  46. package/dist/spinner-gOxIMz-V.js +18 -0
  47. package/dist/storekit-Ddvs4Ynw.js +29 -0
  48. package/dist/telemetry-CcfrtXdf.js +204 -0
  49. package/dist/token-DHRH8cxi.js +102 -0
  50. package/dist/ui-C4ncRJqd.js +27703 -0
  51. package/dist/update-BiVeR024.js +137 -0
  52. package/dist/upgrade-DYWspApv.js +72 -0
  53. package/package.json +87 -0
  54. package/prompts/actions/dashboard-setup.xml +10 -0
  55. package/prompts/actions/integrate.xml +5 -0
  56. package/prompts/actions/migrate.xml +11 -0
  57. package/prompts/actions/placements-implement.xml +20 -0
  58. package/prompts/actions/placements-review.xml +18 -0
  59. package/prompts/actions/review-fix.xml +18 -0
  60. package/prompts/actions/review.xml +18 -0
  61. package/prompts/commandments.xml +17 -0
  62. package/prompts/context.xml +9 -0
  63. package/skills/README.md +118 -0
  64. package/skills/superwall-dashboard/SKILL.md +81 -0
  65. package/skills/superwall-dashboard/references/setup.md +101 -0
  66. package/skills/superwall-integrate/SKILL.md +76 -0
  67. package/skills/superwall-integrate/references/expo.md +269 -0
  68. package/skills/superwall-integrate/references/flutter.md +285 -0
  69. package/skills/superwall-integrate/references/ios.md +314 -0
  70. package/skills/superwall-integrate/references/react-native.md +245 -0
  71. package/skills/superwall-migrate/SKILL.md +83 -0
  72. package/skills/superwall-migrate/references/adapty.md +229 -0
  73. package/skills/superwall-migrate/references/qonversion.md +227 -0
  74. package/skills/superwall-migrate/references/revenuecat.md +414 -0
  75. package/skills/superwall-placements/SKILL.md +73 -0
  76. package/skills/superwall-placements/references/expo.md +161 -0
  77. package/skills/superwall-placements/references/flutter.md +139 -0
  78. package/skills/superwall-placements/references/ios.md +165 -0
  79. package/skills/superwall-placements/references/react-native.md +145 -0
  80. package/skills/superwall-placements/references/strategy.md +221 -0
  81. package/skills/superwall-review/SKILL.md +75 -0
  82. package/skills/superwall-review/references/expo.md +100 -0
  83. package/skills/superwall-review/references/flutter.md +99 -0
  84. package/skills/superwall-review/references/ios.md +108 -0
  85. package/skills/superwall-review/references/react-native.md +100 -0
@@ -0,0 +1,101 @@
1
+ # Dashboard setup - reference
2
+
3
+ Detailed recipes for the `superwall-dashboard` skill. Every command takes `--json`.
4
+
5
+ ## Scoping
6
+
7
+ | Resource | Scope | Flag |
8
+ | ---------------------- | ----------- | ---------------- |
9
+ | products, entitlements | project | `--project <id>` |
10
+ | campaigns, paywalls | application | `--app <id>` |
11
+
12
+ `superwall apps list --json` returns projects with nested `applications` (each has `id`,
13
+ `platform`, `bundle_id`, `public_api_key`). One project holds one app per platform, so with a
14
+ single app the CLI auto-scopes; agents always pass the flags explicitly.
15
+
16
+ ## Products
17
+
18
+ ### Create by hand (real pricing)
19
+
20
+ ```bash
21
+ superwall products create <identifier> \
22
+ --price 39.99 \ # major units; converted to cents for you
23
+ --currency USD \ # default USD
24
+ --period year \ # day | week | month | year
25
+ --period-count 1 \ # periods per cycle, default 1
26
+ --trial-days 7 \ # optional free-trial length
27
+ --entitlement pro \ # entitlement(s) to grant; repeat --entitlement for more
28
+ --name "Pro Yearly" \ # optional display name
29
+ --project <id> --json
30
+ ```
31
+
32
+ Use the **real store product identifiers** (the ones in App Store Connect / Google Play), e.g.
33
+ `com.app.pro.yearly`. The dashboard product identifier must match the store's or the SDK can't
34
+ resolve it on device.
35
+
36
+ ### Import from App Store Connect
37
+
38
+ There is **no** `products import` subcommand. Two ways to import:
39
+
40
+ 1. **Orchestrated (hands-off):** run `superwall integrate` - the CLI
41
+ walks App Store Connect and imports products interactively.
42
+ 2. **Agent-driven (you do it):** connect the key once, enumerate via the signed ASC proxy, then
43
+ create each product:
44
+
45
+ ```bash
46
+ # one-time: upload the ASC API key to Superwall's vault (nothing stored locally)
47
+ superwall asc keys set --key-id <KEY_ID> --issuer <ISSUER_ID> --key-file ./AuthKey_<KEY_ID>.p8 --json
48
+ superwall asc keys list --json # confirm connected; note the team id
49
+
50
+ # enumerate real products for the app (by bundle id or ASC app id)
51
+ superwall asc subscriptions com.app.bundle --json # renewing subs
52
+ superwall asc iaps com.app.bundle --json # one-time / non-renewing
53
+ superwall asc products com.app.bundle --json # everything
54
+ superwall asc apps --json # list ASC apps if unsure of the id
55
+
56
+ # create each returned productId, granting your entitlement
57
+ superwall products create com.app.pro.yearly --entitlement pro --project <id> --json
58
+ ```
59
+
60
+ Products imported this way carry only the identifier (and reference name); Xcode/StoreKit and
61
+ the stores remain the source of truth for pricing.
62
+
63
+ ### Generate a local `.storekit` file (for Xcode testing without sandbox)
64
+
65
+ ```bash
66
+ superwall products storekit --project <id> --out Superwall.storekit --json
67
+ ```
68
+
69
+ Seeds product identifiers into a StoreKit configuration file; Xcode refines pricing/types on import.
70
+
71
+ ## Entitlements
72
+
73
+ ```bash
74
+ superwall entitlements list --project <id> --json
75
+ superwall entitlements create pro --project <id> --json
76
+ ```
77
+
78
+ Default to a single coarse `pro` entitlement. Add more only for genuine tiers (e.g. `pro`,
79
+ `team`). Products grant entitlements via `--entitlement` at create time.
80
+
81
+ ## Campaigns + placements
82
+
83
+ ```bash
84
+ superwall campaigns list --project <id> --app <id> --json
85
+ superwall campaigns create "Onboarding" onboarding_complete --project <id> --app <id> --json
86
+ superwall campaigns placement <campaignId> another_placement --project <id> --app <id> --json
87
+ ```
88
+
89
+ - `create` takes a **description**, not an identifier - name it for the surface.
90
+ - A campaign can carry several related placements; call `campaigns placement` once per placement.
91
+ - Adding a placement that's already on the campaign is safe to skip - list first.
92
+
93
+ ## What the CLI cannot do (leave manual)
94
+
95
+ - **Design the paywall** - either as code with the superwall framework (`superwall create` scaffolds
96
+ a `superwall/` directory in the app; products are declared in the paywall's `config.ts`;
97
+ `superwall publish` ships it) or in the dashboard's paywall editor.
98
+ `superwall paywalls list --project <id> --app <id> --json` shows what exists.
99
+ - **Configure audiences / experiment splits** beyond the default - done in the dashboard.
100
+
101
+ Report these as the remaining manual steps.
@@ -0,0 +1,76 @@
1
+ ---
2
+ name: superwall-integrate
3
+ description: Install and configure the Superwall SDK in a mobile app for the first time. Supports iOS with SwiftUI or UIKit, Expo, bare React Native, and Flutter. Covers package installation, one configure call at launch, public API key handling, and purchase setup. Use superwall-placements to add paywall triggers.
4
+ ---
5
+
6
+ # Integrate the Superwall SDK
7
+
8
+ Get Superwall installed and configured with the smallest, cleanest set of edits.
9
+ Placements (paywall triggers) are a **separate step** - do not add `register()` /
10
+ `registerPlacement()` calls or example "Go Premium" buttons here. After this skill
11
+ succeeds, use the **superwall-placements** skill to add triggers.
12
+
13
+ ## Docs access
14
+
15
+ Superwall's docs are fetchable **as markdown** - always prefer fetching the current
16
+ page over relying on memory:
17
+
18
+ ```bash
19
+ curl -sL https://superwall.com/docs/llms.txt # index: discover any doc path
20
+ curl -sL https://superwall.com/docs/llms-full.txt # broad context across all SDKs
21
+ curl -sL https://superwall.com/docs/{path}.md # any page as markdown (append .md)
22
+ ```
23
+
24
+ Each SDK also has its own index - `curl -sL https://superwall.com/docs/{ios|expo|react-native|flutter}/llms.txt`.
25
+ Fetch the index to find the slug, then fetch `{path}.md`. Every reference file
26
+ below embeds the exact `curl` at each step so you can pull current detail when the
27
+ baked-in steps aren't enough. **Never invent an API** - if a symbol isn't in a
28
+ reference or a page you fetched, fetch and confirm.
29
+
30
+ ## Principles
31
+
32
+ - Make the smallest set of edits that yields a working, verifiable integration.
33
+ Don't refactor or reformat unrelated code.
34
+ - **Read a file before editing it**; match its existing style and conventions.
35
+ - **Detect the package manager / build system** from the project (lockfiles,
36
+ `Podfile`, `app.json`, `pubspec.yaml`, `Package.swift`) - never assume
37
+ npm/yarn/pnpm/bun/CocoaPods/SPM.
38
+ - **Never invent an API key.** Use the exact public key you were given (it starts
39
+ with `pk_`). Never commit a secret. The public key may be inlined where the
40
+ platform conventionally does so (e.g. iOS `configure()`); otherwise use the
41
+ platform's standard env/config mechanism.
42
+ - **Never invent an API.** Every symbol you write must come from the reference
43
+ file or the linked docs. If the docs are ambiguous, say so and link the page.
44
+ - Configure **once, at app launch**, as early in the launch path as possible.
45
+
46
+ ## Steps
47
+
48
+ 1. **Detect the framework** from the project files:
49
+
50
+ | Signal in the project | Framework | Read this reference |
51
+ | ------------------------------------------------------------- | ------------------- | ---------------------------- |
52
+ | `*.xcodeproj` / `Package.swift` / `*.swift`, no JS | iOS / Swift | `references/ios.md` |
53
+ | `app.json`/`app.config.js` with an `expo` key, `expo` in deps | Expo | `references/expo.md` |
54
+ | `package.json` with `react-native`, no `expo` config | React Native (bare) | `references/react-native.md` |
55
+ | `pubspec.yaml` | Flutter | `references/flutter.md` |
56
+
57
+ If both Expo and bare RN signals exist, treat it as **Expo**. If unsure, ask.
58
+
59
+ 2. **Read `references/<framework>.md` and follow it exactly.** Each reference is a
60
+ complete, verified playbook: install, configure, API key handling, verify,
61
+ pitfalls, and doc links.
62
+
63
+ 3. **Pick the purchase-handling path** (covered in each reference):
64
+ - **No existing IAP system** → default. No `PurchaseController`; Superwall
65
+ manages purchases, restoration, and subscription state.
66
+ - **RevenueCat / Adapty / Qonversion / custom StoreKit already present** →
67
+ implement a `PurchaseController` and keep `subscriptionStatus` in sync with
68
+ your source of truth. (For a full migration off another SDK, use the
69
+ **superwall-migrate** skill.)
70
+
71
+ ## Definition of done
72
+
73
+ 1. SDK installed and resolving (pods/SPM/gradle/pub resolved).
74
+ 2. Superwall configured exactly once at launch with the provided public `pk_` key.
75
+ 3. If a build command exists, build to verify it compiles.
76
+ 4. No placements added - that is the placements step.
@@ -0,0 +1,269 @@
1
+ # Integrate Superwall - Expo
2
+
3
+ You are integrating Superwall into an Expo app using the **`expo-superwall`**
4
+ package (the modern, recommended SDK - hooks + provider API). Get it installed and
5
+ configured. **Do not add paywall triggers (`usePlacement` / `registerPlacement`)**;
6
+ that is the separate **superwall-placements** skill.
7
+
8
+ **Requirements:** Expo SDK **53+**, iOS deployment target **15.1+** (**16.4+** for
9
+ Expo SDK 56+), Android **minSdkVersion 21+**. **Expo Go does not work** - you must
10
+ use a Development Build (custom dev client). See Pitfalls.
11
+
12
+ ## Checklist
13
+
14
+ - [ ] **0. Decide the purchase-handling path** (default / RevenueCat / custom).
15
+ - [ ] **1. Install** `expo-superwall` + `expo-build-properties`; produce a native build.
16
+ - [ ] **2. Configure** - wrap the root in `SuperwallProvider` with per-platform `pk_` keys.
17
+ - [ ] **3. API keys** via `EXPO_PUBLIC_*` env vars (public keys, never secrets).
18
+ - [ ] **4. Purchase handling** for the chosen path.
19
+ - [ ] **5. Build a dev client** (NOT Expo Go) - native module links.
20
+ - [ ] **6. Run** - logs show Superwall startup; StoreKit test config if testing purchases.
21
+ - [ ] **7. Post-integration** (identity, attributes, subscription state, deep links, analytics) - final section, then → **superwall-placements**.
22
+
23
+ ## Docs access - read the current page when baked steps aren't enough
24
+
25
+ Superwall's docs are fetchable **as markdown**. Fetch instead of guessing:
26
+
27
+ ```bash
28
+ curl -sL https://superwall.com/docs/expo/llms.txt # index: every Expo doc path
29
+ curl -sL https://superwall.com/docs/llms-full.txt # broad context across all SDKs
30
+ curl -sL https://superwall.com/docs/expo/quickstart/configure.md # any page + ".md"
31
+ ```
32
+
33
+ Pattern: fetch `expo/llms.txt` for the slug, then
34
+ `https://superwall.com/docs/expo/{path}.md`. Every `curl` here is verified working.
35
+ The Expo SDK is hooks-based (`useUser`, `usePlacement`, `useSuperwallEvents`) and
36
+ its component API (`SuperwallProvider`, `SuperwallLoading`/`SuperwallLoaded`,
37
+ `CustomPurchaseControllerProvider`) differs from the native SDKs - **never invent a
38
+ hook or prop**; fetch the SDK-reference page and confirm.
39
+
40
+ ## Quickstart walk
41
+
42
+ | Order | Slug | Covered by |
43
+ | ----- | --------------------------------------------- | ------------------------------ |
44
+ | 1 | `expo/quickstart/install` | Step 1 here |
45
+ | 2 | `expo/quickstart/configure` | Step 2 here |
46
+ | 3 | `expo/quickstart/present-first-paywall` | **superwall-placements** skill |
47
+ | 4 | `expo/quickstart/feature-gating` | **superwall-placements** skill |
48
+ | 5 | `expo/quickstart/in-app-paywall-previews` | placements / QA |
49
+ | 6 | `expo/quickstart/setting-user-properties` | Step 7 here |
50
+ | 7 | `expo/quickstart/tracking-subscription-state` | Step 7 here |
51
+ | 8 | `expo/quickstart/user-management` | Step 7 here |
52
+
53
+ SDK-reference index (components + hooks):
54
+ `curl -sL https://superwall.com/docs/expo/llms.txt`
55
+
56
+ ## Step 0 - Purchase-handling path (decide first)
57
+
58
+ > **Important:** Paths (b) and (c) require you to keep subscription status in sync
59
+ > yourself via `setSubscriptionStatus`. Path (a) does not.
60
+
61
+ - **(a) Default - Superwall handles StoreKit/Billing.** No existing IAP code.
62
+ Recommended, zero purchase code. Just use `SuperwallProvider`.
63
+ - **(b) RevenueCat stays the source of truth.** Keep RC purchasing and sync its
64
+ entitlements into Superwall. `curl -sL https://superwall.com/docs/expo/guides/using-revenuecat.md`
65
+ - **(c) Custom purchase controller.** The app has its own billing. Supply a
66
+ `PurchaseController` via `CustomPurchaseControllerProvider` and drive status.
67
+
68
+ For a full migration off another SDK, use the **superwall-migrate** skill.
69
+
70
+ ## Step 1 - Install
71
+
72
+ Detect the package manager from the lockfile. Use `expo install` so versions match
73
+ the Expo SDK.
74
+
75
+ ```bash
76
+ curl -sL https://superwall.com/docs/expo/quickstart/install.md
77
+ ```
78
+
79
+ ```bash
80
+ npx expo install expo-superwall
81
+ # or: pnpm dlx expo install expo-superwall / yarn dlx expo install expo-superwall / bunx expo install expo-superwall
82
+ ```
83
+
84
+ Also install and configure `expo-build-properties` to guarantee native minimums:
85
+
86
+ ```bash
87
+ npx expo install expo-build-properties
88
+ ```
89
+
90
+ Merge into the **existing** `plugins` array in `app.json` / `app.config.js` (don't
91
+ create a second one):
92
+
93
+ ```json
94
+ {
95
+ "expo": {
96
+ "plugins": [
97
+ ["expo-build-properties", {
98
+ "ios": { "deploymentTarget": "15.1" },
99
+ "android": { "minSdkVersion": 21 }
100
+ }]
101
+ ]
102
+ }
103
+ }
104
+ ```
105
+
106
+ (For Expo SDK 56+, set `"deploymentTarget": "16.4"`.)
107
+
108
+ `expo-superwall` is a native module, so produce a **native build**:
109
+
110
+ ```bash
111
+ npx expo run:ios # or: npx expo run:android
112
+ ```
113
+
114
+ For an **existing** project whose `ios/`/`android/` predate the install, regenerate
115
+ them (back up custom native code first):
116
+
117
+ ```bash
118
+ npx expo prebuild --clean
119
+ ```
120
+
121
+ ## Step 2 - Configure
122
+
123
+ Wrap the app root in `SuperwallProvider` with per-platform public keys. Place it at
124
+ the very top of the tree - the root `App` component, or `app/_layout.tsx` for
125
+ expo-router so it mounts once above every route.
126
+
127
+ ```bash
128
+ curl -sL https://superwall.com/docs/expo/quickstart/configure.md
129
+ ```
130
+
131
+ ```tsx
132
+ import { SuperwallProvider } from "expo-superwall";
133
+
134
+ export default function App() {
135
+ return (
136
+ <SuperwallProvider
137
+ apiKeys={{
138
+ ios: process.env.EXPO_PUBLIC_SUPERWALL_IOS_KEY!,
139
+ android: process.env.EXPO_PUBLIC_SUPERWALL_ANDROID_KEY!,
140
+ }}
141
+ >
142
+ {/* your existing app tree */}
143
+ </SuperwallProvider>
144
+ );
145
+ }
146
+ ```
147
+
148
+ `apiKeys` takes `ios` and optionally `android`. `SuperwallProvider` configures the
149
+ SDK on mount - **do not** also call a separate `configure()`. Optional behavior
150
+ goes through the `options` prop:
151
+
152
+ ```tsx
153
+ <SuperwallProvider apiKeys={{ ios: "...", android: "..." }} options={{ /* ... */ }}>
154
+ ```
155
+
156
+ To gate UI on SDK readiness, `SuperwallLoading` / `SuperwallLoaded` are available
157
+ (see the SDK-reference components).
158
+
159
+ ## Step 3 - API key handling
160
+
161
+ Use the **Public API Key(s)** (`pk_…`) from Dashboard ▸ Settings ▸ Keys - iOS and
162
+ Android apps each have their own key. Store as `EXPO_PUBLIC_`-prefixed env vars
163
+ (readable in JS at build time) in `.env` / `app.config.js`. Public keys aren't
164
+ secrets, but `EXPO_PUBLIC_*` keeps them out of source and lets environments differ.
165
+ **Never** put a secret/server key here.
166
+
167
+ ## Step 4 - Purchase handling (implements Step 0's choice)
168
+
169
+ ### (a) Default
170
+
171
+ Just use `SuperwallProvider` as above. Superwall manages purchases, restores, and
172
+ subscription status.
173
+
174
+ ### (b) RevenueCat / (c) custom
175
+
176
+ Supply a `PurchaseController` through `CustomPurchaseControllerProvider`. Read the
177
+ page before writing - the exact wiring differs between the hooks API and the compat
178
+ API:
179
+
180
+ ```bash
181
+ curl -sL https://superwall.com/docs/expo/guides/advanced-configuration.md
182
+ ```
183
+
184
+ The controller implements `purchaseFromAppStore(productId)`,
185
+ `purchaseFromGooglePlay(productId, basePlanId?, offerId?)`, and `restorePurchases()`:
186
+
187
+ ```tsx
188
+ export class MyPurchaseController extends PurchaseController {
189
+ async purchaseFromAppStore(productId: string): Promise<PurchaseResult> { /* ... */ }
190
+ async purchaseFromGooglePlay(
191
+ productId: string, basePlanId?: string, offerId?: string
192
+ ): Promise<PurchaseResult> { /* ... */ }
193
+ async restorePurchases(): Promise<RestorationResult> { /* ... */ }
194
+ }
195
+ ```
196
+
197
+ > **Important (paths b & c):** keep subscription status in sync whenever
198
+ > entitlements change. Via the `useUser` hook:
199
+ >
200
+ > ```tsx
201
+ > const { setSubscriptionStatus } = useUser();
202
+ > setSubscriptionStatus({ status: "ACTIVE", entitlements: [{ id: "pro" }] });
203
+ > // or: setSubscriptionStatus({ status: "INACTIVE" });
204
+ > ```
205
+ >
206
+ > Or via the shared instance:
207
+ > `Superwall.shared.setSubscriptionStatus(SubscriptionStatus.Active([new Entitlement("pro")]))`
208
+ > / `SubscriptionStatus.Inactive()`. For (b), map RevenueCat's active entitlements
209
+ > into that call. Confirm shapes against the advanced-configuration page.
210
+
211
+ ## Step 5 & 6 - Verify
212
+
213
+ 1. **Build a dev client** and run it: `npx expo run:ios` / `npx expo run:android`
214
+ (NOT Expo Go). Must compile with the native module linked.
215
+ 2. Watch Metro/Xcode/Android logs on launch for Superwall SDK startup.
216
+ > **Important:** Superwall does **not** refetch config on hot reload - fully
217
+ > restart the app after changing SDK setup.
218
+ 3. For iOS purchases in the simulator, read the StoreKit testing guide:
219
+ `curl -sL https://superwall.com/docs/expo/guides/testing-purchases.md`
220
+
221
+ ## Step 7 - Post-integration (wire what the app needs, then → placements)
222
+
223
+ The Expo SDK exposes these through the **`useUser`** hook and event hooks.
224
+
225
+ - **User identity - REQUIRED if the app has ANY auth/login system.** Not optional: without it every logged-in user is anonymous to Superwall, breaking user-scoped audiences, attribution, and cross-device status. Wire it the moment you see a login/logout flow (grep for signIn/login/logout/signOut/auth). `identify(userId)` on login, `signOut()` on logout. `userId`
226
+ should be a **UUID** (StoreKit compat), never an email/device id/guessable value.
227
+ `curl -sL https://superwall.com/docs/expo/quickstart/user-management.md`
228
+ ```tsx
229
+ const { identify, signOut } = useUser();
230
+ await identify(user.id);
231
+ signOut();
232
+ ```
233
+ - **User attributes** - `curl -sL https://superwall.com/docs/expo/quickstart/setting-user-properties.md`
234
+ - **Tracking subscription state** - read `subscriptionStatus` from `useUser`
235
+ (`status` is `"ACTIVE" | "INACTIVE" | "UNKNOWN"`); react to changes with
236
+ `useSuperwallEvents({ onSubscriptionStatusChange })`.
237
+ `curl -sL https://superwall.com/docs/expo/quickstart/tracking-subscription-state.md`
238
+ ```tsx
239
+ const { subscriptionStatus } = useUser();
240
+ if (subscriptionStatus?.status === "ACTIVE") { /* entitled */ }
241
+ ```
242
+ - **Deep links** - `curl -sL https://superwall.com/docs/expo/guides/handling-deep-links.md`
243
+ - **3rd-party analytics** - forward events via `useSuperwallEvents`.
244
+ `curl -sL https://superwall.com/docs/expo/guides/3rd-party-analytics.md`
245
+
246
+ ## Pitfalls
247
+
248
+ - **"Cannot find native module 'SuperwallExpo'" / paywalls don't load** → you're on
249
+ Expo Go. Build a dev client: `npx expo run:ios` / `run:android`, or
250
+ `eas build --profile development --platform ios`.
251
+ - **Existing app, native folders out of date** → `npx expo prebuild --clean` (back
252
+ up custom native code first).
253
+ - **EAS build missing the module** → fresh dev build:
254
+ `eas build --profile development --platform ios`.
255
+ - **Stale caches after install** → `npx expo start --clear`, reinstall
256
+ `node_modules`, `pod install --repo-update` in `ios/`.
257
+ - **Wrong Expo SDK** → `npx expo-doctor`; needs Expo SDK 53+.
258
+ - **Changes not taking effect** → hot reload doesn't re-configure Superwall; fully
259
+ restart.
260
+
261
+ ## Deeper docs
262
+
263
+ - Index: `curl -sL https://superwall.com/docs/expo/llms.txt`
264
+ - Install: https://superwall.com/docs/expo/quickstart/install
265
+ - Configure: https://superwall.com/docs/expo/quickstart/configure
266
+ - Configuring (options): https://superwall.com/docs/expo/guides/configuring
267
+ - Advanced purchasing / PurchaseController: https://superwall.com/docs/expo/guides/advanced-configuration
268
+ - Using RevenueCat: https://superwall.com/docs/expo/guides/using-revenuecat
269
+ - Debugging: https://superwall.com/docs/expo/guides/debugging