@superwall/cli 2.0.0 → 2.1.1

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 (142) hide show
  1. package/README.md +3 -2
  2. package/dist/{apple-CkKlHBZ9.js → apple-BHbX0jbn.js} +13 -13
  3. package/dist/auth.d.ts +1 -1
  4. package/dist/auth.js +3 -3
  5. package/dist/{billing-XCZU_T46.js → billing-4zhIBFRQ.js} +3 -3
  6. package/dist/{bind-drne__Ys.js → bind-CHLHmxgA.js} +4 -4
  7. package/dist/{build-Gpdq5QXP.js → build-5PQeSnNN.js} +6 -6
  8. package/dist/{client-DP6Rc0t_.js → client-BIvOmWPC.js} +7 -3
  9. package/dist/{create-BBrtgUgS.js → create-BSNIFsnN.js} +6 -6
  10. package/dist/{create-Cwc3SRWJ.js → create-VK-pNfN7.js} +23 -23
  11. package/dist/create-oj3zXvHZ.js +19 -0
  12. package/dist/{doctor-C9ldpPFC.js → doctor-9JS96QkX.js} +6 -6
  13. package/dist/{drivers-DNrx4LWA.js → drivers-BamBJ10Y.js} +3 -3
  14. package/dist/entry.js +20 -21
  15. package/dist/{environment-DF1qKlny.js → environment-eV7LEnSN.js} +15 -2
  16. package/dist/{existing-78LWSsqS.js → existing-C8dSYHGk.js} +2 -2
  17. package/dist/{held-Cy8Wl4D1.js → held-BMisHn8F.js} +6 -6
  18. package/dist/held-DeJW2gUk.js +16 -0
  19. package/dist/{integrate-DcJhpXy8.js → integrate-VWtTNPCr.js} +22 -22
  20. package/dist/login-2JHCG6c1.js +16 -0
  21. package/dist/{login-D0lh3_JI.js → login-BimbukE5.js} +5 -5
  22. package/dist/{login-B2TsCE2H.js → login-BmwG14LC.js} +1 -1
  23. package/dist/{lookup-D-nmmAbw.js → lookup-k9EeOiZr.js} +2 -2
  24. package/dist/{migrate-Cfec564E.js → migrate-C86h6jeF.js} +22 -22
  25. package/dist/{notification-url-YDbq6FMA.js → notification-url-BVaTgWZ5.js} +2 -2
  26. package/dist/{open-Ba2vBl1_.js → open-0tDCQOXC.js} +10 -10
  27. package/dist/{org-D0g_q3mv.js → org-DUwdrKPV.js} +2 -2
  28. package/dist/{paths-DxSLdpOI.js → paths-BCbjCLP5.js} +1 -1
  29. package/dist/{playbook-DIeb7hne.js → playbook-oov9yV0q.js} +10 -10
  30. package/dist/{promote-COD4fYdz.js → promote-DPGPamkE.js} +16 -16
  31. package/dist/push-Chp21y3a.js +22 -0
  32. package/dist/{push-CncywhkQ.js → push-Cz4lJ8Qd.js} +27 -14
  33. package/dist/{registry-DSrosOYs.js → registry-CTczUigi.js} +525 -179
  34. package/dist/{resources-Dqr01Dep.js → resources-B1qKDVXd.js} +18 -6
  35. package/dist/{run-C9qg_QlC.js → run-DTPsVmFw.js} +2 -2
  36. package/dist/scan-B1SkkUi7.js +4 -0
  37. package/dist/{scan-DLrsrFS9.js → scan-Bb48xZqB.js} +1 -1
  38. package/dist/{scope-V336uz8j.js → scope-B6UYGuwn.js} +4 -4
  39. package/dist/{selection-Rdw-ZUoG.js → selection-BbNk9r1q.js} +10 -4
  40. package/dist/server-CwrZ-I1r.js +22 -0
  41. package/dist/{server-D0tGG8C4.js → server-EYBMKAG1.js} +10 -8
  42. package/dist/{session-D_nEWKXT.js → session-Crg9X-FI.js} +41 -13
  43. package/dist/session-DItGa4z0.js +6 -0
  44. package/dist/{session-CFAmMhem.js → session-xG9E8J2N.js} +1 -1
  45. package/dist/skills/superwall-framework/SKILL.md +43 -7
  46. package/dist/skills/superwall-framework/references/cli.md +1 -0
  47. package/dist/skills/superwall-framework/references/examples.md +1 -0
  48. package/dist/skills/superwall-framework/references/layout.md +34 -1
  49. package/dist/skills/superwall-framework/references/migrate-from-editor.md +16 -3
  50. package/dist/{skills-BvFOa4y6.js → skills-BdMKE2uO.js} +5 -4
  51. package/dist/{skills-DMG4bpKk.js → skills-Dg3k6TRC.js} +8 -8
  52. package/dist/{spinner-CneRK5rk.js → spinner-Ba3XhlMb.js} +3 -3
  53. package/dist/{storage-s2Dnz-yl.js → storage-DIkYajce.js} +1 -1
  54. package/dist/{storekit-yY_kS2iR.js → storekit-C2UzIIMs.js} +3 -3
  55. package/dist/storekit-DHNxDDpA.js +16 -0
  56. package/dist/{telemetry-DtG92m5O.js → telemetry-CVP8O6Y3.js} +1 -1
  57. package/dist/{token-DzRh7dI1.js → token-IWv2httm.js} +1 -1
  58. package/dist/tools-skills/animate-onboarding/SKILL.md +467 -0
  59. package/dist/tools-skills/animate-onboarding/references/engine.md +494 -0
  60. package/dist/tools-skills/animate-onboarding/references/framework/Question.tsx +71 -0
  61. package/dist/tools-skills/animate-onboarding/references/framework/README.md +40 -0
  62. package/dist/tools-skills/animate-onboarding/references/framework/answers.ts +19 -0
  63. package/dist/tools-skills/animate-onboarding/references/framework/flow.ts +80 -0
  64. package/dist/tools-skills/animate-onboarding/references/framework/handoffs.ts +869 -0
  65. package/dist/tools-skills/animate-onboarding/references/framework/layout.tsx +113 -0
  66. package/dist/tools-skills/animate-onboarding/references/framework/motion.css +559 -0
  67. package/dist/tools-skills/animate-onboarding/references/framework/useStoryRouter.ts +48 -0
  68. package/dist/tools-skills/animate-onboarding/references/handoffs.md +375 -0
  69. package/dist/tools-skills/animate-onboarding/references/imageReady.ts +92 -0
  70. package/dist/tools-skills/animate-onboarding/references/morphFrame.ts +356 -0
  71. package/dist/tools-skills/animate-onboarding/references/performance.md +41 -0
  72. package/dist/tools-skills/animate-onboarding/references/web-runtime/README.md +17 -0
  73. package/dist/tools-skills/animate-onboarding/references/web-runtime/handoffs.ts +858 -0
  74. package/dist/tools-skills/animate-onboarding/references/web-runtime/story-motion.css +301 -0
  75. package/dist/tools-skills/mobile-design/SKILL.md +447 -0
  76. package/dist/tools-skills/mobile-design/references/responsive.md +162 -0
  77. package/dist/tools-skills/onboarding-questions/SKILL.md +231 -0
  78. package/dist/tools-skills/onboarding-questions/references/arpu-questions.md +139 -0
  79. package/dist/tools-skills/onboarding-questions/references/craft.md +142 -0
  80. package/dist/tools-skills/onboarding-questions/references/example-reflective.md +117 -0
  81. package/dist/tools-skills/superwall/SKILL.md +263 -0
  82. package/dist/tools-skills/superwall/references/api.md +303 -0
  83. package/dist/tools-skills/superwall/references/asa.md +166 -0
  84. package/dist/tools-skills/superwall/references/asc.md +95 -0
  85. package/dist/tools-skills/superwall/references/dashboard-links.md +57 -0
  86. package/dist/tools-skills/superwall/references/data-analytics.md +896 -0
  87. package/dist/tools-skills/superwall/references/docs.md +51 -0
  88. package/dist/tools-skills/superwall/references/sdk-integration.md +104 -0
  89. package/dist/tools-skills/superwall/references/sdk-source.md +18 -0
  90. package/dist/tools-skills/superwall/workflows/dashboard/playbook.md +76 -0
  91. package/dist/tools-skills/superwall/workflows/dashboard/setup.md +100 -0
  92. package/dist/tools-skills/superwall/workflows/integrate/android.md +292 -0
  93. package/dist/tools-skills/superwall/workflows/integrate/expo.md +272 -0
  94. package/dist/tools-skills/superwall/workflows/integrate/flutter.md +285 -0
  95. package/dist/tools-skills/superwall/workflows/integrate/ios.md +314 -0
  96. package/dist/tools-skills/superwall/workflows/integrate/playbook.md +83 -0
  97. package/dist/tools-skills/superwall/workflows/integrate/react-native.md +246 -0
  98. package/dist/tools-skills/superwall/workflows/migrate/adapty.md +229 -0
  99. package/dist/tools-skills/superwall/workflows/migrate/playbook.md +78 -0
  100. package/dist/tools-skills/superwall/workflows/migrate/qonversion.md +227 -0
  101. package/dist/tools-skills/superwall/workflows/migrate/revenuecat.md +414 -0
  102. package/dist/tools-skills/superwall/workflows/placements/android.md +175 -0
  103. package/dist/tools-skills/superwall/workflows/placements/expo.md +161 -0
  104. package/dist/tools-skills/superwall/workflows/placements/flutter.md +139 -0
  105. package/dist/tools-skills/superwall/workflows/placements/ios.md +165 -0
  106. package/dist/tools-skills/superwall/workflows/placements/playbook.md +69 -0
  107. package/dist/tools-skills/superwall/workflows/placements/react-native.md +145 -0
  108. package/dist/tools-skills/superwall/workflows/placements/strategy.md +222 -0
  109. package/dist/tools-skills/superwall/workflows/review/android.md +120 -0
  110. package/dist/tools-skills/superwall/workflows/review/expo.md +100 -0
  111. package/dist/tools-skills/superwall/workflows/review/flutter.md +99 -0
  112. package/dist/tools-skills/superwall/workflows/review/ios.md +108 -0
  113. package/dist/tools-skills/superwall/workflows/review/playbook.md +70 -0
  114. package/dist/tools-skills/superwall/workflows/review/react-native.md +100 -0
  115. package/dist/tools-skills/superwall-editor/SKILL.md +113 -0
  116. package/dist/tools-skills/superwall-editor/references/cli.md +135 -0
  117. package/dist/tools-skills/superwall-editor/references/design.md +51 -0
  118. package/dist/tools-skills/superwall-editor/references/native-elements.md +171 -0
  119. package/dist/tools-skills/superwall-editor/references/workflow.md +65 -0
  120. package/dist/tools-skills/superwall-editor/scripts/sw-editor.sh +662 -0
  121. package/dist/tools-skills/wwdc/SKILL.md +22 -0
  122. package/dist/tools-skills/wwdc/references/docs.md +52 -0
  123. package/dist/tools-skills/wwdc/scripts/wwdc.sh +266 -0
  124. package/dist/tools.d.ts +4 -2
  125. package/dist/tools.js +561 -161
  126. package/dist/{upgrade-Bt4Ouw1y.js → upgrade-1t3aQUxh.js} +1 -1
  127. package/dist/{upgrade-Cqy5orjb.js → upgrade-DLf0LJDh.js} +2 -2
  128. package/package.json +2 -2
  129. package/dist/create-Yvf2gStM.js +0 -19
  130. package/dist/held-Ddw1XSsr.js +0 -16
  131. package/dist/kinds-GFXB3sYu.js +0 -11
  132. package/dist/login-BoBe8Psl.js +0 -16
  133. package/dist/push-CtD4FZQV.js +0 -22
  134. package/dist/scan-Cv5uOwVY.js +0 -4
  135. package/dist/send-BxD9yf6F.js +0 -150
  136. package/dist/server-z1LH94R_.js +0 -22
  137. package/dist/session-1AV_Bs_d.js +0 -6
  138. package/dist/storekit-DafAnGkM.js +0 -16
  139. /package/dist/{devtools-ByZ6XYnn.js → devtools-pBl_vt03.js} +0 -0
  140. /package/dist/{reports-DdPq4blM.js → reports-D_qbl7_u.js} +0 -0
  141. /package/dist/{screenshot-file-0UETadF8.js → screenshot-file-tVBfUEIi.js} +0 -0
  142. /package/dist/{storage-DYvmIOHa.d.ts → storage-CerJ5KLP.d.ts} +0 -0
@@ -0,0 +1,272 @@
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. Run from the app root after installing its lockfile dependencies;
74
+ the commands below use the project's installed Expo CLI. Do not download another
75
+ Expo CLI version when the local binary is missing: restore the project dependencies.
76
+
77
+ ```bash
78
+ curl -sL https://superwall.com/docs/expo/quickstart/install.md
79
+ ```
80
+
81
+ ```bash
82
+ ./node_modules/.bin/expo install expo-superwall
83
+ # or: pnpm exec expo install expo-superwall / yarn expo install expo-superwall
84
+ ```
85
+
86
+ Also install and configure `expo-build-properties` to guarantee native minimums:
87
+
88
+ ```bash
89
+ ./node_modules/.bin/expo install expo-build-properties
90
+ ```
91
+
92
+ Merge into the **existing** `plugins` array in `app.json` / `app.config.js` (don't
93
+ create a second one):
94
+
95
+ ```json
96
+ {
97
+ "expo": {
98
+ "plugins": [
99
+ ["expo-build-properties", {
100
+ "ios": { "deploymentTarget": "15.1" },
101
+ "android": { "minSdkVersion": 21 }
102
+ }]
103
+ ]
104
+ }
105
+ }
106
+ ```
107
+
108
+ (For Expo SDK 56+, set `"deploymentTarget": "16.4"`.)
109
+
110
+ `expo-superwall` is a native module, so produce a **native build**:
111
+
112
+ ```bash
113
+ ./node_modules/.bin/expo run:ios # or: ./node_modules/.bin/expo run:android
114
+ ```
115
+
116
+ For an **existing** project whose `ios/`/`android/` predate the install, regenerate
117
+ them (back up custom native code first):
118
+
119
+ ```bash
120
+ ./node_modules/.bin/expo prebuild --clean
121
+ ```
122
+
123
+ ## Step 2 - Configure
124
+
125
+ Wrap the app root in `SuperwallProvider` with per-platform public keys. Place it at
126
+ the very top of the tree - the root `App` component, or `app/_layout.tsx` for
127
+ expo-router so it mounts once above every route.
128
+
129
+ ```bash
130
+ curl -sL https://superwall.com/docs/expo/quickstart/configure.md
131
+ ```
132
+
133
+ ```tsx
134
+ import { SuperwallProvider } from "expo-superwall";
135
+
136
+ export default function App() {
137
+ return (
138
+ <SuperwallProvider
139
+ apiKeys={{
140
+ ios: process.env.EXPO_PUBLIC_SUPERWALL_IOS_KEY!,
141
+ android: process.env.EXPO_PUBLIC_SUPERWALL_ANDROID_KEY!,
142
+ }}
143
+ >
144
+ {/* your existing app tree */}
145
+ </SuperwallProvider>
146
+ );
147
+ }
148
+ ```
149
+
150
+ `apiKeys` takes `ios` and optionally `android`. `SuperwallProvider` configures the
151
+ SDK on mount - **do not** also call a separate `configure()`. Optional behavior
152
+ goes through the `options` prop:
153
+
154
+ ```tsx
155
+ <SuperwallProvider apiKeys={{ ios: "...", android: "..." }} options={{ /* ... */ }}>
156
+ ```
157
+
158
+ To gate UI on SDK readiness, `SuperwallLoading` / `SuperwallLoaded` are available
159
+ (see the SDK-reference components).
160
+
161
+ ## Step 3 - API key handling
162
+
163
+ Use the **Public API Key(s)** (`pk_…`) from Dashboard ▸ Settings ▸ Keys - iOS and
164
+ Android apps each have their own key. Store as `EXPO_PUBLIC_`-prefixed env vars
165
+ (readable in JS at build time) in `.env` / `app.config.js`. Public keys aren't
166
+ secrets, but `EXPO_PUBLIC_*` keeps them out of source and lets environments differ.
167
+ **Never** put a secret/server key here.
168
+
169
+ ## Step 4 - Purchase handling (implements Step 0's choice)
170
+
171
+ ### (a) Default
172
+
173
+ Just use `SuperwallProvider` as above. Superwall manages purchases, restores, and
174
+ subscription status.
175
+
176
+ ### (b) RevenueCat / (c) custom
177
+
178
+ Supply a `PurchaseController` through `CustomPurchaseControllerProvider`. Read the
179
+ page before writing - the exact wiring differs between the hooks API and the compat
180
+ API:
181
+
182
+ ```bash
183
+ curl -sL https://superwall.com/docs/expo/guides/advanced-configuration.md
184
+ ```
185
+
186
+ The controller implements `purchaseFromAppStore(productId)`,
187
+ `purchaseFromGooglePlay(productId, basePlanId?, offerId?)`, and `restorePurchases()`:
188
+
189
+ ```tsx
190
+ export class MyPurchaseController extends PurchaseController {
191
+ async purchaseFromAppStore(productId: string): Promise<PurchaseResult> { /* ... */ }
192
+ async purchaseFromGooglePlay(
193
+ productId: string, basePlanId?: string, offerId?: string
194
+ ): Promise<PurchaseResult> { /* ... */ }
195
+ async restorePurchases(): Promise<RestorationResult> { /* ... */ }
196
+ }
197
+ ```
198
+
199
+ > **Important (paths b & c):** keep subscription status in sync whenever
200
+ > entitlements change. Via the `useUser` hook:
201
+ >
202
+ > ```tsx
203
+ > const { setSubscriptionStatus } = useUser();
204
+ > setSubscriptionStatus({ status: "ACTIVE", entitlements: [{ id: "pro" }] });
205
+ > // or: setSubscriptionStatus({ status: "INACTIVE" });
206
+ > ```
207
+ >
208
+ > Or via the shared instance:
209
+ > `Superwall.shared.setSubscriptionStatus(SubscriptionStatus.Active([new Entitlement("pro")]))`
210
+ > / `SubscriptionStatus.Inactive()`. For (b), map RevenueCat's active entitlements
211
+ > into that call. Confirm shapes against the advanced-configuration page.
212
+
213
+ ## Step 5 & 6 - Verify
214
+
215
+ 1. **Build a dev client** and run it: `./node_modules/.bin/expo run:ios` / `run:android`
216
+ (NOT Expo Go). Must compile with the native module linked.
217
+ 2. Watch Metro/Xcode/Android logs on launch for Superwall SDK startup.
218
+ > **Important:** Superwall does **not** refetch config on hot reload - fully
219
+ > restart the app after changing SDK setup.
220
+ 3. For iOS purchases in the simulator, read the StoreKit testing guide:
221
+ `curl -sL https://superwall.com/docs/expo/guides/testing-purchases.md`
222
+
223
+ ## Step 7 - Post-integration (wire what the app needs, then → placements)
224
+
225
+ The Expo SDK exposes these through the **`useUser`** hook and event hooks.
226
+
227
+ - **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`
228
+ should be a **UUID** (StoreKit compat), never an email/device id/guessable value.
229
+ `curl -sL https://superwall.com/docs/expo/quickstart/user-management.md`
230
+ ```tsx
231
+ const { identify, signOut } = useUser();
232
+ await identify(user.id);
233
+ signOut();
234
+ ```
235
+ - **User attributes** - `curl -sL https://superwall.com/docs/expo/quickstart/setting-user-properties.md`
236
+ - **Tracking subscription state** - read `subscriptionStatus` from `useUser`
237
+ (`status` is `"ACTIVE" | "INACTIVE" | "UNKNOWN"`); react to changes with
238
+ `useSuperwallEvents({ onSubscriptionStatusChange })`.
239
+ `curl -sL https://superwall.com/docs/expo/quickstart/tracking-subscription-state.md`
240
+ ```tsx
241
+ const { subscriptionStatus } = useUser();
242
+ if (subscriptionStatus?.status === "ACTIVE") { /* entitled */ }
243
+ ```
244
+ - **Deep links** - `curl -sL https://superwall.com/docs/expo/guides/handling-deep-links.md`
245
+ - **3rd-party analytics** - forward events via `useSuperwallEvents`.
246
+ `curl -sL https://superwall.com/docs/expo/guides/3rd-party-analytics.md`
247
+
248
+ ## Pitfalls
249
+
250
+ - **"Cannot find native module 'SuperwallExpo'" / paywalls don't load** → you're on
251
+ Expo Go. Build a dev client: `./node_modules/.bin/expo run:ios` / `run:android`, or
252
+ `eas build --profile development --platform ios`.
253
+ - **Existing app, native folders out of date** → `./node_modules/.bin/expo prebuild --clean` (back
254
+ up custom native code first).
255
+ - **EAS build missing the module** → fresh dev build:
256
+ `eas build --profile development --platform ios`.
257
+ - **Stale caches after install** → `./node_modules/.bin/expo start --clear`, reinstall
258
+ `node_modules`, `pod install --repo-update` in `ios/`.
259
+ - **Wrong Expo SDK** → `npx -y expo-doctor@1.20.4`; needs Expo SDK 53+.
260
+ Check the pinned doctor's Node `engines` requirement before running it.
261
+ - **Changes not taking effect** → hot reload doesn't re-configure Superwall; fully
262
+ restart.
263
+
264
+ ## Deeper docs
265
+
266
+ - Index: `curl -sL https://superwall.com/docs/expo/llms.txt`
267
+ - Install: https://superwall.com/docs/expo/quickstart/install
268
+ - Configure: https://superwall.com/docs/expo/quickstart/configure
269
+ - Configuring (options): https://superwall.com/docs/expo/guides/configuring
270
+ - Advanced purchasing / PurchaseController: https://superwall.com/docs/expo/guides/advanced-configuration
271
+ - Using RevenueCat: https://superwall.com/docs/expo/guides/using-revenuecat
272
+ - Debugging: https://superwall.com/docs/expo/guides/debugging
@@ -0,0 +1,285 @@
1
+ # Integrate Superwall - Flutter
2
+
3
+ You are integrating Superwall into a Flutter app using the
4
+ **`superwallkit_flutter`** package. Get it installed and configured. **Do not add
5
+ paywall triggers (`registerPlacement`)** - that is the separate
6
+ **superwall-placements** skill.
7
+
8
+ **Requirements:** iOS deployment target **14.0+**; Android **minSdkVersion 26**,
9
+ **compileSdk 34**, Gradle **8.6+**, Android Gradle Plugin **8.4+**.
10
+
11
+ ## Checklist
12
+
13
+ - [ ] **0. Decide the purchase-handling path** (default / RevenueCat / custom).
14
+ - [ ] **1. Install** `superwallkit_flutter`; set iOS/Android native minimums + Android activities.
15
+ - [ ] **2. Configure** once at launch with the platform's `pk_` key.
16
+ - [ ] **3. API keys** branched on `Platform.isIOS` (public keys, never secrets).
17
+ - [ ] **4. Purchase handling** for the chosen path.
18
+ - [ ] **5. Build** - `flutter run` on iOS sim + Android emulator; pods/gradle resolve.
19
+ - [ ] **6. Run** - console shows Superwall startup; StoreKit test config if testing purchases.
20
+ - [ ] **7. Post-integration** (identity, attributes, subscription state, deep links, analytics), then → **superwall-placements**.
21
+
22
+ ## Docs access - read the current page when baked steps aren't enough
23
+
24
+ ```bash
25
+ curl -sL https://superwall.com/docs/flutter/llms.txt # index: every Flutter doc path
26
+ curl -sL https://superwall.com/docs/llms-full.txt # broad context across all SDKs
27
+ curl -sL https://superwall.com/docs/flutter/quickstart/install.md # any page + ".md"
28
+ ```
29
+
30
+ Pattern: fetch `flutter/llms.txt` for the slug, then
31
+ `https://superwall.com/docs/flutter/{path}.md`. Every `curl` here is verified
32
+ working. **Never invent an API** - if a symbol isn't in this reference or a page you
33
+ fetched, fetch and confirm.
34
+
35
+ ## Quickstart walk
36
+
37
+ | Order | Slug | Covered by |
38
+ | ----- | ------------------------------------------------ | ------------------------------ |
39
+ | 1 | `flutter/quickstart/install` | Step 1 here |
40
+ | 2 | `flutter/quickstart/configure` | Step 2 here |
41
+ | 3 | `flutter/quickstart/feature-gating` | **superwall-placements** skill |
42
+ | 4 | `flutter/quickstart/in-app-paywall-previews` | placements / QA |
43
+ | 5 | `flutter/quickstart/setting-user-properties` | Step 7 here |
44
+ | 6 | `flutter/quickstart/tracking-subscription-state` | Step 7 here |
45
+ | 7 | `flutter/quickstart/user-management` | Step 7 here |
46
+
47
+ ## Step 0 - Purchase-handling path (decide first)
48
+
49
+ > **Important:** Paths (b)/(c) require you to keep `subscriptionStatus` in sync;
50
+ > path (a) does not.
51
+
52
+ - **(a) Default - Superwall handles StoreKit/Billing.** Recommended, zero purchase code.
53
+ - **(b) RevenueCat stays the source of truth.** Keep RC purchasing; sync entitlements in.
54
+ `curl -sL https://superwall.com/docs/flutter/guides/using-revenuecat.md`
55
+ - **(c) Custom `PurchaseController`.** Supply one, drive status.
56
+
57
+ Full migration off another SDK → **superwall-migrate** skill.
58
+
59
+ ## Step 1 - Install
60
+
61
+ Add the package (match the project's existing Flutter tooling):
62
+
63
+ ```bash
64
+ curl -sL https://superwall.com/docs/flutter/quickstart/install.md
65
+ flutter pub add superwallkit_flutter
66
+ ```
67
+
68
+ Or add `superwallkit_flutter` to `pubspec.yaml` under `dependencies:` (use the
69
+ latest version on pub.dev) then `flutter pub get`.
70
+
71
+ ### iOS native config
72
+
73
+ `ios/Podfile`:
74
+
75
+ ```ruby
76
+ platform :ios, '14.0'
77
+ ```
78
+
79
+ Then `cd ios && pod install` (or let the next `flutter run` install pods).
80
+
81
+ ### Android native config
82
+
83
+ `android/app/build.gradle`:
84
+
85
+ ```groovy
86
+ android {
87
+ compileSdkVersion 34
88
+ defaultConfig {
89
+ minSdkVersion 26
90
+ targetSdkVersion 34
91
+ }
92
+ }
93
+ ```
94
+
95
+ `android/build.gradle` - AGP 8.4+:
96
+
97
+ ```groovy
98
+ plugins { id 'com.android.application' version '8.4.1' apply false }
99
+ ```
100
+
101
+ `android/gradle/wrapper/gradle-wrapper.properties` - Gradle 8.6+:
102
+
103
+ ```properties
104
+ distributionUrl=https\://services.gradle.org/distributions/gradle-8.6-bin.zip
105
+ ```
106
+
107
+ > **Important:** Register Superwall's activities in the `<application>` tag of
108
+ > `android/app/src/main/AndroidManifest.xml`, or Android builds/paywalls fail:
109
+
110
+ ```xml
111
+ <activity
112
+ android:name="com.superwall.sdk.paywall.view.SuperwallPaywallActivity"
113
+ android:theme="@style/Theme.MaterialComponents.DayNight.NoActionBar"
114
+ android:configChanges="orientation|screenSize|keyboardHidden">
115
+ </activity>
116
+ <activity android:name="com.superwall.sdk.debug.DebugViewActivity" />
117
+ <activity android:name="com.superwall.sdk.debug.localizations.SWLocalizationActivity" />
118
+ <activity android:name="com.superwall.sdk.debug.SWConsoleActivity" />
119
+ ```
120
+
121
+ ## Step 2 - Configure
122
+
123
+ ```bash
124
+ curl -sL https://superwall.com/docs/flutter/quickstart/configure.md
125
+ ```
126
+
127
+ ```dart
128
+ import 'package:superwallkit_flutter/superwallkit_flutter.dart';
129
+ ```
130
+
131
+ Call `Superwall.configure` **once, at launch**, with the platform's public key.
132
+
133
+ **In `main()`** (call `WidgetsFlutterBinding.ensureInitialized()` first if you
134
+ configure before `runApp`):
135
+
136
+ ```dart
137
+ import 'dart:io' show Platform;
138
+ import 'package:flutter/material.dart';
139
+ import 'package:superwallkit_flutter/superwallkit_flutter.dart';
140
+
141
+ void main() {
142
+ WidgetsFlutterBinding.ensureInitialized();
143
+ final apiKey = Platform.isIOS ? "pk_YOUR_IOS_PUBLIC_KEY" : "pk_YOUR_ANDROID_PUBLIC_KEY";
144
+ Superwall.configure(apiKey);
145
+ runApp(const MyApp());
146
+ }
147
+ ```
148
+
149
+ **Or in a root widget's `initState()`:**
150
+
151
+ ```dart
152
+ @override
153
+ void initState() {
154
+ super.initState();
155
+ final apiKey = Platform.isIOS ? "pk_YOUR_IOS_PUBLIC_KEY" : "pk_YOUR_ANDROID_PUBLIC_KEY";
156
+ Superwall.configure(apiKey);
157
+ }
158
+ ```
159
+
160
+ Optional behavior goes through `SuperwallOptions` via the named `options:` argument:
161
+ `Superwall.configure("pk_...", options: options)`.
162
+
163
+ ## Step 3 - API key handling
164
+
165
+ Use the **Public API Key(s)** (`pk_…`) from Dashboard ▸ Settings ▸ Keys - iOS and
166
+ Android apps have separate keys, so branch on `Platform.isIOS`. Public keys aren't
167
+ secrets; inline them, or read from existing config (`--dart-define` /
168
+ `String.fromEnvironment`). **Never** use a secret key.
169
+
170
+ ## Step 4 - Purchase handling (implements Step 0's choice)
171
+
172
+ ### (a) Default
173
+
174
+ Just `Superwall.configure(apiKey)`. Superwall handles purchases, restores, and
175
+ subscription status.
176
+
177
+ ### (b) RevenueCat / (c) custom
178
+
179
+ Implement a `PurchaseController` and pass it in. Read the page first:
180
+
181
+ ```bash
182
+ curl -sL https://superwall.com/docs/flutter/guides/advanced-configuration.md
183
+ ```
184
+
185
+ ```dart
186
+ class MyPurchaseController extends PurchaseController {
187
+ @override
188
+ Future<PurchaseResult> purchaseFromAppStore(String productId) async {
189
+ // Purchase via StoreKit / RevenueCat / your billing system, then return:
190
+ return PurchaseResult.purchased;
191
+ }
192
+
193
+ @override
194
+ Future<PurchaseResult> purchaseFromGooglePlay(
195
+ String productId, String? basePlanId, String? offerId) async {
196
+ return PurchaseResult.purchased;
197
+ }
198
+
199
+ @override
200
+ Future<RestorationResult> restorePurchases() async {
201
+ return RestorationResult.restored;
202
+ }
203
+ }
204
+ ```
205
+
206
+ Pass it at configure time (**positional** second argument):
207
+
208
+ ```dart
209
+ Superwall.configure(apiKey, MyPurchaseController());
210
+ ```
211
+
212
+ > **Important (paths b & c):** keep subscription status synced whenever entitlements
213
+ > change:
214
+ >
215
+ > ```dart
216
+ > Superwall.shared.setSubscriptionStatus(
217
+ > SubscriptionStatusActive(entitlements: {Entitlement(id: "pro")}),
218
+ > );
219
+ > // or
220
+ > Superwall.shared.setSubscriptionStatus(SubscriptionStatusInactive());
221
+ > ```
222
+ >
223
+ > For (b), map RevenueCat's active entitlements into that call. Confirm the exact
224
+ > `configure` argument shape against the advanced-configuration page - some SDK
225
+ > versions differ.
226
+
227
+ ## Step 5 & 6 - Verify
228
+
229
+ 1. **Build & run:** `flutter run` on an iOS simulator and an Android emulator. Must
230
+ compile with pods/gradle resolved.
231
+ 2. Watch the console on launch for Superwall SDK startup. Raise verbosity via
232
+ `SuperwallOptions` logging if needed.
233
+ 3. For iOS purchase testing, read the StoreKit testing guide:
234
+ `curl -sL https://superwall.com/docs/flutter/guides/testing-purchases.md`
235
+
236
+ ## Step 7 - Post-integration (wire what the app needs, then → placements)
237
+
238
+ - **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). `Superwall.shared.identify(user.id)` on login,
239
+ `Superwall.shared.reset()` on logout. `userId` should be a **UUID** (StoreKit
240
+ compat), never an email/device id/guessable value.
241
+ `curl -sL https://superwall.com/docs/flutter/quickstart/user-management.md`
242
+ ```dart
243
+ Superwall.shared.identify(user.id);
244
+ Superwall.shared.reset(); // on sign-out
245
+ ```
246
+ > **Use when** you need the unhashed `appUserId` to reach Google Play: set
247
+ > `SuperwallOptions()..passIdentifiersToPlayStore = true` and pass it via
248
+ > `identify(user.id, options: options)` (Android only).
249
+ - **User attributes** - `Superwall.shared.setUserAttributes(attributes)` (a
250
+ `Map<String, dynamic>`; merges, overwriting matching keys). The Flutter SDK does
251
+ **not** support deleting an attribute via `null`.
252
+ `curl -sL https://superwall.com/docs/flutter/quickstart/setting-user-properties.md`
253
+ - **Tracking subscription state** - read `Superwall.shared.subscriptionStatus`
254
+ (`.unknown` / `.active(entitlements)` / `.inactive`).
255
+ `curl -sL https://superwall.com/docs/flutter/quickstart/tracking-subscription-state.md`
256
+ - **Deep links** - pass incoming URLs to `Superwall.shared.handleDeepLink(url)`; it
257
+ fires the `deepLink_open` placement so routing is dashboard-driven.
258
+ `curl -sL https://superwall.com/docs/flutter/guides/handling-deep-links.md`
259
+ ```dart
260
+ Future<void> handleUrl(Uri url) async => Superwall.shared.handleDeepLink(url);
261
+ ```
262
+ - **3rd-party analytics** - forward Superwall events via the delegate.
263
+ `curl -sL https://superwall.com/docs/flutter/guides/3rd-party-analytics.md`
264
+
265
+ ## Pitfalls
266
+
267
+ - **Android build fails** → check minSdk 26 / compileSdk 34 / Gradle 8.6 / AGP 8.4,
268
+ and that the four Superwall activities are declared in `AndroidManifest.xml`.
269
+ - **iOS pod errors** → set `platform :ios, '14.0'` in the `Podfile`, then
270
+ `cd ios && pod install`.
271
+ - **Configuring before bindings ready** → call
272
+ `WidgetsFlutterBinding.ensureInitialized()` before `Superwall.configure` in `main()`.
273
+ - **Configured but paywalls never show** → with a `PurchaseController` you must set
274
+ `subscriptionStatus`; and no placement yet (that's the placements skill).
275
+ - **Secret key** → the key must start with `pk_` (public).
276
+
277
+ ## Deeper docs
278
+
279
+ - Index: `curl -sL https://superwall.com/docs/flutter/llms.txt`
280
+ - Install: https://superwall.com/docs/flutter/quickstart/install
281
+ - Configure: https://superwall.com/docs/flutter/quickstart/configure
282
+ - Advanced purchasing / PurchaseController: https://superwall.com/docs/flutter/guides/advanced-configuration
283
+ - Using RevenueCat: https://superwall.com/docs/flutter/guides/using-revenuecat
284
+ - Configuring (options): https://superwall.com/docs/flutter/guides/configuring
285
+ - StoreKit testing: https://superwall.com/docs/flutter/guides/testing-purchases