@superwall/cli 2.0.0 → 2.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.
- package/dist/{apple-CkKlHBZ9.js → apple-CSzNTGHM.js} +13 -13
- package/dist/auth.d.ts +1 -1
- package/dist/auth.js +3 -3
- package/dist/{billing-XCZU_T46.js → billing-C3Q8DBU2.js} +3 -3
- package/dist/{bind-drne__Ys.js → bind-BumHTi9O.js} +4 -4
- package/dist/{build-Gpdq5QXP.js → build-Bpviiclc.js} +6 -6
- package/dist/{client-DP6Rc0t_.js → client-BL0f_yGf.js} +2 -2
- package/dist/create-BSfvpWoD.js +19 -0
- package/dist/{create-Cwc3SRWJ.js → create-BUcVG4Ab.js} +23 -23
- package/dist/{create-BBrtgUgS.js → create-CfK3PeKA.js} +6 -6
- package/dist/{doctor-C9ldpPFC.js → doctor-BWqIYcMn.js} +6 -6
- package/dist/{drivers-DNrx4LWA.js → drivers-CPhdPkW5.js} +3 -3
- package/dist/entry.js +20 -21
- package/dist/{environment-DF1qKlny.js → environment-eBXjELoN.js} +1 -1
- package/dist/{existing-78LWSsqS.js → existing-BltvQiX5.js} +2 -2
- package/dist/held-CPve03KJ.js +16 -0
- package/dist/{held-Cy8Wl4D1.js → held-DgnTFMl3.js} +6 -6
- package/dist/{integrate-DcJhpXy8.js → integrate-BRsqoe01.js} +22 -22
- package/dist/{login-B2TsCE2H.js → login-BCEH5q0U.js} +1 -1
- package/dist/login-BPOONe7n.js +16 -0
- package/dist/{login-D0lh3_JI.js → login-BbTIrCFT.js} +5 -5
- package/dist/{lookup-D-nmmAbw.js → lookup-rr1AkCJA.js} +2 -2
- package/dist/{migrate-Cfec564E.js → migrate-C9X2Vz81.js} +22 -22
- package/dist/{notification-url-YDbq6FMA.js → notification-url-CV86qiKP.js} +2 -2
- package/dist/{open-Ba2vBl1_.js → open-CcpXotHG.js} +10 -10
- package/dist/{org-D0g_q3mv.js → org-BQQDo7wm.js} +2 -2
- package/dist/{paths-DxSLdpOI.js → paths-CRlU72cq.js} +1 -1
- package/dist/{playbook-DIeb7hne.js → playbook-DVMXN7fh.js} +10 -10
- package/dist/{promote-COD4fYdz.js → promote-Da8xctzy.js} +16 -16
- package/dist/push-BV-grvQg.js +22 -0
- package/dist/{push-CncywhkQ.js → push-D6R9icWN.js} +27 -14
- package/dist/{registry-DSrosOYs.js → registry-BYVD-_h6.js} +206 -49
- package/dist/{resources-Dqr01Dep.js → resources-DLON3-61.js} +18 -6
- package/dist/{run-C9qg_QlC.js → run-Co-BwhOg.js} +2 -2
- package/dist/scan-B88OlWOt.js +4 -0
- package/dist/{scan-DLrsrFS9.js → scan-CKuk-_6W.js} +1 -1
- package/dist/{scope-V336uz8j.js → scope-DV22_Ufm.js} +4 -4
- package/dist/{selection-Rdw-ZUoG.js → selection-C2_KbLuo.js} +10 -4
- package/dist/server-C4f6ccUr.js +22 -0
- package/dist/{server-D0tGG8C4.js → server-D0d2oP-5.js} +10 -8
- package/dist/{session-CFAmMhem.js → session-B-Uz0cQ7.js} +1 -1
- package/dist/session-BuvArt1j.js +6 -0
- package/dist/{session-D_nEWKXT.js → session-C4rbE3VS.js} +41 -13
- package/dist/skills/superwall-framework/SKILL.md +7 -3
- package/dist/skills/superwall-framework/references/cli.md +1 -0
- package/dist/skills/superwall-framework/references/layout.md +34 -1
- package/dist/{skills-DMG4bpKk.js → skills-CLGJuMnF.js} +8 -8
- package/dist/{skills-BvFOa4y6.js → skills-CZcpnEnG.js} +5 -4
- package/dist/{spinner-CneRK5rk.js → spinner-C2U6QBJ9.js} +3 -3
- package/dist/{storage-s2Dnz-yl.js → storage-6h9vyiAz.js} +1 -1
- package/dist/storekit-CK9JmM2D.js +16 -0
- package/dist/{storekit-yY_kS2iR.js → storekit-CinJra3V.js} +3 -3
- package/dist/{telemetry-DtG92m5O.js → telemetry-DKyDhURo.js} +1 -1
- package/dist/{token-DzRh7dI1.js → token-DaxQgQkv.js} +1 -1
- package/dist/tools-skills/animate-onboarding/SKILL.md +467 -0
- package/dist/tools-skills/animate-onboarding/references/engine.md +494 -0
- package/dist/tools-skills/animate-onboarding/references/framework/Question.tsx +71 -0
- package/dist/tools-skills/animate-onboarding/references/framework/README.md +40 -0
- package/dist/tools-skills/animate-onboarding/references/framework/answers.ts +19 -0
- package/dist/tools-skills/animate-onboarding/references/framework/flow.ts +80 -0
- package/dist/tools-skills/animate-onboarding/references/framework/handoffs.ts +869 -0
- package/dist/tools-skills/animate-onboarding/references/framework/layout.tsx +113 -0
- package/dist/tools-skills/animate-onboarding/references/framework/motion.css +559 -0
- package/dist/tools-skills/animate-onboarding/references/framework/useStoryRouter.ts +48 -0
- package/dist/tools-skills/animate-onboarding/references/handoffs.md +375 -0
- package/dist/tools-skills/animate-onboarding/references/imageReady.ts +92 -0
- package/dist/tools-skills/animate-onboarding/references/morphFrame.ts +356 -0
- package/dist/tools-skills/animate-onboarding/references/performance.md +41 -0
- package/dist/tools-skills/animate-onboarding/references/web-runtime/README.md +17 -0
- package/dist/tools-skills/animate-onboarding/references/web-runtime/handoffs.ts +858 -0
- package/dist/tools-skills/animate-onboarding/references/web-runtime/story-motion.css +301 -0
- package/dist/tools-skills/mobile-design/SKILL.md +447 -0
- package/dist/tools-skills/mobile-design/references/responsive.md +162 -0
- package/dist/tools-skills/onboarding-questions/SKILL.md +231 -0
- package/dist/tools-skills/onboarding-questions/references/arpu-questions.md +139 -0
- package/dist/tools-skills/onboarding-questions/references/craft.md +142 -0
- package/dist/tools-skills/onboarding-questions/references/example-reflective.md +117 -0
- package/dist/tools-skills/superwall/SKILL.md +263 -0
- package/dist/tools-skills/superwall/references/api.md +303 -0
- package/dist/tools-skills/superwall/references/asa.md +166 -0
- package/dist/tools-skills/superwall/references/asc.md +95 -0
- package/dist/tools-skills/superwall/references/dashboard-links.md +57 -0
- package/dist/tools-skills/superwall/references/data-analytics.md +896 -0
- package/dist/tools-skills/superwall/references/docs.md +51 -0
- package/dist/tools-skills/superwall/references/sdk-integration.md +104 -0
- package/dist/tools-skills/superwall/references/sdk-source.md +18 -0
- package/dist/tools-skills/superwall/workflows/dashboard/playbook.md +76 -0
- package/dist/tools-skills/superwall/workflows/dashboard/setup.md +100 -0
- package/dist/tools-skills/superwall/workflows/integrate/android.md +292 -0
- package/dist/tools-skills/superwall/workflows/integrate/expo.md +272 -0
- package/dist/tools-skills/superwall/workflows/integrate/flutter.md +285 -0
- package/dist/tools-skills/superwall/workflows/integrate/ios.md +314 -0
- package/dist/tools-skills/superwall/workflows/integrate/playbook.md +83 -0
- package/dist/tools-skills/superwall/workflows/integrate/react-native.md +246 -0
- package/dist/tools-skills/superwall/workflows/migrate/adapty.md +229 -0
- package/dist/tools-skills/superwall/workflows/migrate/playbook.md +78 -0
- package/dist/tools-skills/superwall/workflows/migrate/qonversion.md +227 -0
- package/dist/tools-skills/superwall/workflows/migrate/revenuecat.md +414 -0
- package/dist/tools-skills/superwall/workflows/placements/android.md +175 -0
- package/dist/tools-skills/superwall/workflows/placements/expo.md +161 -0
- package/dist/tools-skills/superwall/workflows/placements/flutter.md +139 -0
- package/dist/tools-skills/superwall/workflows/placements/ios.md +165 -0
- package/dist/tools-skills/superwall/workflows/placements/playbook.md +69 -0
- package/dist/tools-skills/superwall/workflows/placements/react-native.md +145 -0
- package/dist/tools-skills/superwall/workflows/placements/strategy.md +222 -0
- package/dist/tools-skills/superwall/workflows/review/android.md +120 -0
- package/dist/tools-skills/superwall/workflows/review/expo.md +100 -0
- package/dist/tools-skills/superwall/workflows/review/flutter.md +99 -0
- package/dist/tools-skills/superwall/workflows/review/ios.md +108 -0
- package/dist/tools-skills/superwall/workflows/review/playbook.md +70 -0
- package/dist/tools-skills/superwall/workflows/review/react-native.md +100 -0
- package/dist/tools-skills/superwall-editor/SKILL.md +113 -0
- package/dist/tools-skills/superwall-editor/references/cli.md +135 -0
- package/dist/tools-skills/superwall-editor/references/design.md +51 -0
- package/dist/tools-skills/superwall-editor/references/native-elements.md +171 -0
- package/dist/tools-skills/superwall-editor/references/workflow.md +65 -0
- package/dist/tools-skills/superwall-editor/scripts/sw-editor.sh +662 -0
- package/dist/tools-skills/wwdc/SKILL.md +22 -0
- package/dist/tools-skills/wwdc/references/docs.md +52 -0
- package/dist/tools-skills/wwdc/scripts/wwdc.sh +266 -0
- package/dist/tools.d.ts +1 -1
- package/dist/tools.js +200 -18
- package/dist/{upgrade-Bt4Ouw1y.js → upgrade-DPo0a4Es.js} +1 -1
- package/dist/{upgrade-Cqy5orjb.js → upgrade-ffseQDMx.js} +2 -2
- package/package.json +2 -2
- package/dist/create-Yvf2gStM.js +0 -19
- package/dist/held-Ddw1XSsr.js +0 -16
- package/dist/kinds-GFXB3sYu.js +0 -11
- package/dist/login-BoBe8Psl.js +0 -16
- package/dist/push-CtD4FZQV.js +0 -22
- package/dist/scan-Cv5uOwVY.js +0 -4
- package/dist/send-BxD9yf6F.js +0 -150
- package/dist/server-z1LH94R_.js +0 -22
- package/dist/session-1AV_Bs_d.js +0 -6
- package/dist/storekit-DafAnGkM.js +0 -16
- /package/dist/{devtools-ByZ6XYnn.js → devtools-pBl_vt03.js} +0 -0
- /package/dist/{reports-DdPq4blM.js → reports-D_qbl7_u.js} +0 -0
- /package/dist/{screenshot-file-0UETadF8.js → screenshot-file-tVBfUEIi.js} +0 -0
- /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
|