@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.
- package/LICENSE +21 -0
- package/README.md +201 -0
- package/dist/actions-MB-eBY64.js +140 -0
- package/dist/api-BF7-toqM.js +151 -0
- package/dist/api-output-B5hh0q4V.js +20 -0
- package/dist/app-K6j9Es7h.js +189 -0
- package/dist/asc-CArSwo5D.js +539 -0
- package/dist/asc-products-YQ6Oc6YO.js +93 -0
- package/dist/auth-CY2cO_NF.js +139 -0
- package/dist/auth.d.ts +30 -0
- package/dist/auth.js +4 -0
- package/dist/billing-DWyfEQ6l.js +80 -0
- package/dist/bind-hslFhcTR.js +213 -0
- package/dist/chunk-DQxbwPpZ.js +30 -0
- package/dist/command-Kwx4ekbo.js +283 -0
- package/dist/create-Bbi8BOO1.js +410 -0
- package/dist/dev-D0lQDCQI.js +397 -0
- package/dist/devtools-8EgLo86w.js +3638 -0
- package/dist/doctor-ByeRdMcl.js +88 -0
- package/dist/drivers-DVAZgone.js +413 -0
- package/dist/entry.d.ts +9 -0
- package/dist/entry.js +495 -0
- package/dist/existing-CcJrIIAU.js +88 -0
- package/dist/feedback-Z0Wk7VC5.js +73 -0
- package/dist/git-3OX9u3xE.js +433 -0
- package/dist/hosted-CHwaUqLd.js +32 -0
- package/dist/integrate-DqOAqK7J.js +863 -0
- package/dist/json-C3hPIMkI.js +7 -0
- package/dist/login-Dr8UN_Gx.js +290 -0
- package/dist/migrate-D92bJTg6.js +114 -0
- package/dist/org-B2gy9Pmu.js +40 -0
- package/dist/params-Bvq0iqQK.js +52 -0
- package/dist/pipeline-CHHIg6BU.js +1056 -0
- package/dist/print-skill-BnZAk7dV.js +74 -0
- package/dist/promote-CRe9170G.js +88 -0
- package/dist/publish-DsODvrOD.js +35 -0
- package/dist/push-BDkZUC0v.js +35 -0
- package/dist/query-DIllrSnk.js +53 -0
- package/dist/resource-CdP1MDla.js +483 -0
- package/dist/resources-CVrWwA1K.js +233 -0
- package/dist/run-cGGBUMs5.js +89 -0
- package/dist/scan-BQexuUPO.js +236 -0
- package/dist/skills-DhuUs28u.js +64 -0
- package/dist/skills-xrfXt9u0.js +205 -0
- package/dist/spawn-DSoTXy_j.js +69 -0
- package/dist/spinner-gOxIMz-V.js +18 -0
- package/dist/storekit-Ddvs4Ynw.js +29 -0
- package/dist/telemetry-CcfrtXdf.js +204 -0
- package/dist/token-DHRH8cxi.js +102 -0
- package/dist/ui-C4ncRJqd.js +27703 -0
- package/dist/update-BiVeR024.js +137 -0
- package/dist/upgrade-DYWspApv.js +72 -0
- package/package.json +87 -0
- package/prompts/actions/dashboard-setup.xml +10 -0
- package/prompts/actions/integrate.xml +5 -0
- package/prompts/actions/migrate.xml +11 -0
- package/prompts/actions/placements-implement.xml +20 -0
- package/prompts/actions/placements-review.xml +18 -0
- package/prompts/actions/review-fix.xml +18 -0
- package/prompts/actions/review.xml +18 -0
- package/prompts/commandments.xml +17 -0
- package/prompts/context.xml +9 -0
- package/skills/README.md +118 -0
- package/skills/superwall-dashboard/SKILL.md +81 -0
- package/skills/superwall-dashboard/references/setup.md +101 -0
- package/skills/superwall-integrate/SKILL.md +76 -0
- package/skills/superwall-integrate/references/expo.md +269 -0
- package/skills/superwall-integrate/references/flutter.md +285 -0
- package/skills/superwall-integrate/references/ios.md +314 -0
- package/skills/superwall-integrate/references/react-native.md +245 -0
- package/skills/superwall-migrate/SKILL.md +83 -0
- package/skills/superwall-migrate/references/adapty.md +229 -0
- package/skills/superwall-migrate/references/qonversion.md +227 -0
- package/skills/superwall-migrate/references/revenuecat.md +414 -0
- package/skills/superwall-placements/SKILL.md +73 -0
- package/skills/superwall-placements/references/expo.md +161 -0
- package/skills/superwall-placements/references/flutter.md +139 -0
- package/skills/superwall-placements/references/ios.md +165 -0
- package/skills/superwall-placements/references/react-native.md +145 -0
- package/skills/superwall-placements/references/strategy.md +221 -0
- package/skills/superwall-review/SKILL.md +75 -0
- package/skills/superwall-review/references/expo.md +100 -0
- package/skills/superwall-review/references/flutter.md +99 -0
- package/skills/superwall-review/references/ios.md +108 -0
- package/skills/superwall-review/references/react-native.md +100 -0
|
@@ -0,0 +1,245 @@
|
|
|
1
|
+
# Integrate Superwall - React Native (bare, non-Expo)
|
|
2
|
+
|
|
3
|
+
You are integrating Superwall into a **bare** React Native app (no Expo config).
|
|
4
|
+
Get the SDK installed and configured. **Do not add paywall triggers** - that is the
|
|
5
|
+
separate **superwall-placements** skill.
|
|
6
|
+
|
|
7
|
+
> **Important - which SDK:** Superwall's recommended SDK for React Native is now
|
|
8
|
+
> **`expo-superwall`**, installed into bare RN via Expo modules (**Path A**). The
|
|
9
|
+
> standalone **`@superwall/react-native-superwall`** is **deprecated** (**Path B**,
|
|
10
|
+
> kept only for existing setups). Default to Path A. Use Path B only if the project
|
|
11
|
+
> cannot add Expo modules or is already on the legacy SDK.
|
|
12
|
+
|
|
13
|
+
**Requirements (Path A):** React Native **0.79+**, Node **18+**, iOS deployment
|
|
14
|
+
target **15.1+**, Android **minSdkVersion 21+**.
|
|
15
|
+
|
|
16
|
+
## Checklist
|
|
17
|
+
|
|
18
|
+
- [ ] **0. Decide the purchase-handling path** (default / RevenueCat / custom).
|
|
19
|
+
- [ ] **0b. Pick the SDK** - Path A (`expo-superwall`, default) or Path B (legacy).
|
|
20
|
+
- [ ] **1. Install** the SDK + native deps (pods / gradle).
|
|
21
|
+
- [ ] **2. Configure** at launch with per-platform `pk_` keys.
|
|
22
|
+
- [ ] **3. API keys** branched on platform (public keys, never secrets).
|
|
23
|
+
- [ ] **4. Purchase handling** for the chosen path.
|
|
24
|
+
- [ ] **5. Native rebuild** (not just a Metro reload) - module links.
|
|
25
|
+
- [ ] **6. Run** - native logs show Superwall startup.
|
|
26
|
+
- [ ] **7. Post-integration** (identity, attributes, subscription state, deep links, analytics), then → **superwall-placements**.
|
|
27
|
+
|
|
28
|
+
## Docs access - read the current page when baked steps aren't enough
|
|
29
|
+
|
|
30
|
+
```bash
|
|
31
|
+
curl -sL https://superwall.com/docs/expo/llms.txt # Path A docs (expo-superwall) live here
|
|
32
|
+
curl -sL https://superwall.com/docs/react-native/llms.txt # Path B legacy SDK reference
|
|
33
|
+
curl -sL https://superwall.com/docs/llms-full.txt # broad context
|
|
34
|
+
curl -sL https://superwall.com/docs/expo/guides/using-expo-sdk-in-bare-react-native.md
|
|
35
|
+
```
|
|
36
|
+
|
|
37
|
+
Pattern: fetch the index, then `https://superwall.com/docs/{sdk}/{path}.md`. Every
|
|
38
|
+
`curl` here is verified working. **Path A uses the Expo docs** - the hooks/provider
|
|
39
|
+
API (`SuperwallProvider`, `useUser`) is documented under `/docs/expo/…`. **Never
|
|
40
|
+
invent an API**; fetch and confirm.
|
|
41
|
+
|
|
42
|
+
## Quickstart walk
|
|
43
|
+
|
|
44
|
+
Path A follows the **Expo** quickstart. Path B uses the (deprecated) react-native
|
|
45
|
+
SDK reference.
|
|
46
|
+
|
|
47
|
+
| Order | Path A slug (Expo docs) | Covered by |
|
|
48
|
+
| ----- | ------------------------------------------------- | --------------- |
|
|
49
|
+
| 1 | `expo/guides/using-expo-sdk-in-bare-react-native` | Step 1 (Path A) |
|
|
50
|
+
| 2 | `expo/quickstart/configure` | Step 2 |
|
|
51
|
+
| 3 | `expo/quickstart/setting-user-properties` | Step 7 |
|
|
52
|
+
| 4 | `expo/quickstart/tracking-subscription-state` | Step 7 |
|
|
53
|
+
| 5 | `expo/quickstart/user-management` | Step 7 |
|
|
54
|
+
|
|
55
|
+
Path B reference: `curl -sL https://superwall.com/docs/react-native/llms.txt`
|
|
56
|
+
|
|
57
|
+
## Step 0 - Purchase-handling path (decide first)
|
|
58
|
+
|
|
59
|
+
> **Important:** Paths (b)/(c) require manual subscription-status management; (a) doesn't.
|
|
60
|
+
|
|
61
|
+
- **(a) Default - Superwall handles StoreKit/Billing.** Recommended, zero purchase code.
|
|
62
|
+
- **(b) RevenueCat stays the source of truth.** Keep RC purchasing; sync entitlements in.
|
|
63
|
+
- **(c) Custom purchase controller.** Supply a `PurchaseController`, drive status.
|
|
64
|
+
|
|
65
|
+
Full migration off another SDK → **superwall-migrate** skill.
|
|
66
|
+
|
|
67
|
+
---
|
|
68
|
+
|
|
69
|
+
## Path A - `expo-superwall` in bare React Native (recommended)
|
|
70
|
+
|
|
71
|
+
### 1. Install
|
|
72
|
+
|
|
73
|
+
Add Expo modules support to the bare project (the Superwall-documented way to
|
|
74
|
+
consume `expo-superwall` without full Expo):
|
|
75
|
+
|
|
76
|
+
```bash
|
|
77
|
+
curl -sL https://superwall.com/docs/expo/guides/using-expo-sdk-in-bare-react-native.md
|
|
78
|
+
npx install-expo-modules@latest
|
|
79
|
+
```
|
|
80
|
+
|
|
81
|
+
Install the SDK with the project's package manager (detect from lockfile):
|
|
82
|
+
|
|
83
|
+
```bash
|
|
84
|
+
npm install expo-superwall
|
|
85
|
+
# or: yarn add expo-superwall / pnpm add expo-superwall / bun add expo-superwall
|
|
86
|
+
```
|
|
87
|
+
|
|
88
|
+
Install iOS pods, ensure Android mins:
|
|
89
|
+
|
|
90
|
+
```bash
|
|
91
|
+
cd ios && pod install
|
|
92
|
+
```
|
|
93
|
+
|
|
94
|
+
`android/app/build.gradle`: `minSdkVersion 21`+ (with `compileSdkVersion` /
|
|
95
|
+
`targetSdkVersion` 34).
|
|
96
|
+
|
|
97
|
+
### 2. Configure
|
|
98
|
+
|
|
99
|
+
Wrap the app root in `SuperwallProvider` with per-platform public keys:
|
|
100
|
+
|
|
101
|
+
```tsx
|
|
102
|
+
import { SuperwallProvider } from "expo-superwall";
|
|
103
|
+
|
|
104
|
+
export default function App() {
|
|
105
|
+
return (
|
|
106
|
+
<SuperwallProvider
|
|
107
|
+
apiKeys={{ ios: "pk_YOUR_IOS_PUBLIC_KEY", android: "pk_YOUR_ANDROID_PUBLIC_KEY" }}
|
|
108
|
+
>
|
|
109
|
+
{/* your existing app tree */}
|
|
110
|
+
</SuperwallProvider>
|
|
111
|
+
);
|
|
112
|
+
}
|
|
113
|
+
```
|
|
114
|
+
|
|
115
|
+
`SuperwallProvider` configures the SDK on mount - **do not** also call a separate
|
|
116
|
+
`configure()`. Optional behavior goes through the `options` prop.
|
|
117
|
+
|
|
118
|
+
Path A shares the Expo API. Skip to **API key handling**, **Purchase handling**,
|
|
119
|
+
**Post-integration** - they apply to both paths (Path A uses the hooks form).
|
|
120
|
+
|
|
121
|
+
---
|
|
122
|
+
|
|
123
|
+
## Path B - legacy `@superwall/react-native-superwall`
|
|
124
|
+
|
|
125
|
+
Use only if you cannot add Expo modules, or the project already uses this SDK.
|
|
126
|
+
|
|
127
|
+
### 1. Install
|
|
128
|
+
|
|
129
|
+
```bash
|
|
130
|
+
npm install @superwall/react-native-superwall
|
|
131
|
+
# or: yarn add @superwall/react-native-superwall
|
|
132
|
+
cd ios && pod install
|
|
133
|
+
```
|
|
134
|
+
|
|
135
|
+
Android autolinks - no extra native step beyond a normal build.
|
|
136
|
+
|
|
137
|
+
### 2. Configure
|
|
138
|
+
|
|
139
|
+
Import the default export and call `Superwall.configure` once at launch (root
|
|
140
|
+
component's `useEffect` with empty deps). The public key is per-platform:
|
|
141
|
+
|
|
142
|
+
```tsx
|
|
143
|
+
import { useEffect } from "react";
|
|
144
|
+
import { Platform } from "react-native";
|
|
145
|
+
import Superwall from "@superwall/react-native-superwall";
|
|
146
|
+
|
|
147
|
+
export default function App() {
|
|
148
|
+
useEffect(() => {
|
|
149
|
+
const apiKey = Platform.OS === "ios" ? "pk_YOUR_IOS_PUBLIC_KEY" : "pk_YOUR_ANDROID_PUBLIC_KEY";
|
|
150
|
+
Superwall.configure({ apiKey });
|
|
151
|
+
}, []);
|
|
152
|
+
|
|
153
|
+
return (/* your app */);
|
|
154
|
+
}
|
|
155
|
+
```
|
|
156
|
+
|
|
157
|
+
Full signature: `Superwall.configure({ apiKey, options?, purchaseController?, completion? })`
|
|
158
|
+
(returns a Promise resolving to the configured instance, also at `Superwall.shared`).
|
|
159
|
+
`curl -sL https://superwall.com/docs/react-native/sdk-reference/configure.md`
|
|
160
|
+
|
|
161
|
+
---
|
|
162
|
+
|
|
163
|
+
## API key handling (both paths)
|
|
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. Public keys aren't secrets;
|
|
167
|
+
inline them, or read from existing config (`react-native-config`). **Never** use a
|
|
168
|
+
secret/server key.
|
|
169
|
+
|
|
170
|
+
## Purchase handling (both paths - implements Step 0)
|
|
171
|
+
|
|
172
|
+
### (a) Default
|
|
173
|
+
|
|
174
|
+
Nothing extra - Superwall manages purchases, restores, and subscription status.
|
|
175
|
+
|
|
176
|
+
### (b) RevenueCat / (c) custom
|
|
177
|
+
|
|
178
|
+
Subclass `PurchaseController` and implement `purchaseFromAppStore(productId)`,
|
|
179
|
+
`purchaseFromGooglePlay(productId, basePlanId?, offerId?)`, `restorePurchases()`;
|
|
180
|
+
pass it at configure time. Read the page first - **do not invent method names**:
|
|
181
|
+
|
|
182
|
+
```bash
|
|
183
|
+
curl -sL https://superwall.com/docs/expo/guides/advanced-configuration.md
|
|
184
|
+
```
|
|
185
|
+
|
|
186
|
+
```tsx
|
|
187
|
+
export class MyPurchaseController extends PurchaseController {
|
|
188
|
+
async purchaseFromAppStore(productId: string): Promise<PurchaseResult> { /* ... */ }
|
|
189
|
+
async purchaseFromGooglePlay(
|
|
190
|
+
productId: string, basePlanId?: string, offerId?: string
|
|
191
|
+
): Promise<PurchaseResult> { /* ... */ }
|
|
192
|
+
async restorePurchases(): Promise<RestorationResult> { /* ... */ }
|
|
193
|
+
}
|
|
194
|
+
```
|
|
195
|
+
|
|
196
|
+
> **Important (paths b & c):** keep subscription status synced whenever entitlements
|
|
197
|
+
> change. Path A (hooks): `const { setSubscriptionStatus } = useUser();
|
|
198
|
+
setSubscriptionStatus({ status: "ACTIVE", entitlements: [{ id: "pro" }] })`.
|
|
199
|
+
> Shared instance:
|
|
200
|
+
> `Superwall.shared.setSubscriptionStatus(SubscriptionStatus.Active([new Entitlement("pro")]))`
|
|
201
|
+
> / `SubscriptionStatus.Inactive()`. For (b), map RevenueCat's active entitlements in.
|
|
202
|
+
|
|
203
|
+
## Verify (both paths)
|
|
204
|
+
|
|
205
|
+
1. **Native rebuild** & run: `npx react-native run-ios` / `run-android`. Path A must
|
|
206
|
+
relink the native module - rebuild, don't just reload JS.
|
|
207
|
+
2. Watch native logs on launch for Superwall SDK startup.
|
|
208
|
+
3. iOS purchase testing: StoreKit testing in Xcode.
|
|
209
|
+
|
|
210
|
+
## Post-integration (wire what the app needs, then → placements)
|
|
211
|
+
|
|
212
|
+
Path A uses the `useUser` hook; Path B uses static `Superwall` methods.
|
|
213
|
+
|
|
214
|
+
- **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). Path A: `const { identify, signOut } = useUser()`. Path B:
|
|
215
|
+
`Superwall.shared.identify(userId)` / `Superwall.shared.reset()`. `userId` should
|
|
216
|
+
be a **UUID** (StoreKit compat), never an email/device id/guessable value.
|
|
217
|
+
`curl -sL https://superwall.com/docs/expo/quickstart/user-management.md`
|
|
218
|
+
- **User attributes** - `setUserAttributes(...)`.
|
|
219
|
+
`curl -sL https://superwall.com/docs/expo/quickstart/setting-user-properties.md`
|
|
220
|
+
- **Tracking subscription state** - Path A: `subscriptionStatus` from `useUser`
|
|
221
|
+
(`status` = `"ACTIVE" | "INACTIVE" | "UNKNOWN"`).
|
|
222
|
+
`curl -sL https://superwall.com/docs/expo/quickstart/tracking-subscription-state.md`
|
|
223
|
+
- **Deep links** - pass URLs to `handleDeepLink`; fires the `deepLink_open` placement.
|
|
224
|
+
`curl -sL https://superwall.com/docs/expo/guides/handling-deep-links.md`
|
|
225
|
+
- **3rd-party analytics** - forward events (Path A: `useSuperwallEvents`).
|
|
226
|
+
`curl -sL https://superwall.com/docs/expo/guides/3rd-party-analytics.md`
|
|
227
|
+
|
|
228
|
+
## Pitfalls
|
|
229
|
+
|
|
230
|
+
- **iOS module not found / link errors** → `cd ios && pod install`, then a full
|
|
231
|
+
native rebuild (not just Metro reload).
|
|
232
|
+
- **Reached for the wrong SDK** → prefer Path A (`expo-superwall`); the standalone
|
|
233
|
+
`@superwall/react-native-superwall` is deprecated.
|
|
234
|
+
- **Path A native module missing** → `npx install-expo-modules@latest` must succeed
|
|
235
|
+
before `pod install`; rebuild afterward.
|
|
236
|
+
- **Configuring on every render** → Path B: wrap `configure` in `useEffect(..., [])`.
|
|
237
|
+
- **Secret key** → key must start with `pk_`.
|
|
238
|
+
|
|
239
|
+
## Deeper docs
|
|
240
|
+
|
|
241
|
+
- Bare RN install guide (Path A): https://superwall.com/docs/expo/guides/using-expo-sdk-in-bare-react-native
|
|
242
|
+
- Migrating from the legacy SDK: https://superwall.com/docs/expo/guides/migrating-react-native
|
|
243
|
+
- Legacy `configure()` (Path B): https://superwall.com/docs/react-native/sdk-reference/configure
|
|
244
|
+
- React Native SDK reference index: `curl -sL https://superwall.com/docs/react-native/llms.txt`
|
|
245
|
+
- Expo docs index (applies to Path A): `curl -sL https://superwall.com/docs/expo/llms.txt`
|
|
@@ -0,0 +1,83 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: superwall-migrate
|
|
3
|
+
description: Migrate a mobile app from RevenueCat, Adapty, or Qonversion to Superwall. Replaces provider SDK calls and recreates products, entitlements, campaigns, and placements. Subscriber access carries over via the stores (RevenueCat state can also be ported server-side), and paywall designs must be rebuilt. Use when replacing another paywall or billing SDK with Superwall. Not for first-time SDK setup in an app with no provider (superwall-integrate).
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# Migrate to Superwall
|
|
7
|
+
|
|
8
|
+
> **Important - what does and does not migrate:**
|
|
9
|
+
>
|
|
10
|
+
> - Paywall designs are rebuilt from scratch - as code with the superwall framework
|
|
11
|
+
> (`superwall create`) or in the dashboard editor.
|
|
12
|
+
> - Historical analytics and attribution stay in the old provider.
|
|
13
|
+
> - Adapty/Qonversion subscribers do not currently move server-side; existing
|
|
14
|
+
> purchases are recovered from the store through Restore Purchases.
|
|
15
|
+
> - RevenueCat: Superwall provides server-side migration tooling that ports
|
|
16
|
+
> subscription history and entitlement state - fetch the live migration guide
|
|
17
|
+
> for the current process before promising specifics. Restore Purchases works
|
|
18
|
+
> regardless.
|
|
19
|
+
|
|
20
|
+
## Docs access
|
|
21
|
+
|
|
22
|
+
```bash
|
|
23
|
+
curl -sL https://superwall.com/docs/llms.txt
|
|
24
|
+
curl -sL https://superwall.com/docs/{path}.md
|
|
25
|
+
```
|
|
26
|
+
|
|
27
|
+
Fetch the framework's configure, purchase-controller, subscription-state,
|
|
28
|
+
identity, register, and feature-gating pages before changing APIs.
|
|
29
|
+
|
|
30
|
+
## Route to exactly one provider playbook
|
|
31
|
+
|
|
32
|
+
| Detect | Read fully |
|
|
33
|
+
| ------------------------------------------------------------- | -------------------------- |
|
|
34
|
+
| `RevenueCat`, `react-native-purchases`, `purchases_flutter` | `references/revenuecat.md` |
|
|
35
|
+
| `Adapty`, `react-native-adapty`, `adapty_flutter` | `references/adapty.md` |
|
|
36
|
+
| `Qonversion`, `react-native-qonversion`, `qonversion_flutter` | `references/qonversion.md` |
|
|
37
|
+
|
|
38
|
+
If several exist, identify which one owns purchases before proceeding.
|
|
39
|
+
|
|
40
|
+
## Flow
|
|
41
|
+
|
|
42
|
+
1. Inventory configure, purchase, restore, entitlement, identity, attributes,
|
|
43
|
+
presentation calls, and all callback side effects.
|
|
44
|
+
2. Choose billing ownership: Superwall, retained custom/store billing, or the
|
|
45
|
+
existing provider as a purchase controller. Follow the chosen playbook.
|
|
46
|
+
3. Map store product ids unchanged, provider entitlements/access levels to
|
|
47
|
+
Superwall entitlements, and each presentation call site to a placement.
|
|
48
|
+
4. Run `superwall apps list --json`; match the code's public key or bundle id and
|
|
49
|
+
record explicit project/app ids. Stop on an account mismatch.
|
|
50
|
+
5. Recreate only missing dashboard resources with scoped JSON commands.
|
|
51
|
+
6. Add Superwall alongside the provider, replace presentation with placements,
|
|
52
|
+
preserve purchase/restore side effects and identity lifecycle, then build.
|
|
53
|
+
7. Verify every placement and Restore Purchases as an existing subscriber.
|
|
54
|
+
8. Remove the old SDK only in full-migration mode and only after verification.
|
|
55
|
+
9. Hand back migrated code, created ids, evidence, and every remaining manual step.
|
|
56
|
+
|
|
57
|
+
## Non-negotiable seams
|
|
58
|
+
|
|
59
|
+
- Exactly one purchase owner and transaction finisher.
|
|
60
|
+
- Purchases outside Superwall must continuously sync subscription state through
|
|
61
|
+
a purchase controller, observer mode, or explicit status updates.
|
|
62
|
+
- Preserve backend sync, analytics, attribution, cache refresh, and navigation
|
|
63
|
+
from old purchase/restore callbacks.
|
|
64
|
+
- Identify before placements can fire; reset on logout, deletion, and forced
|
|
65
|
+
session expiry.
|
|
66
|
+
- Put remotely gated work inside the placement feature callback.
|
|
67
|
+
- Never create dashboard resources until the logged-in app match is verified.
|
|
68
|
+
|
|
69
|
+
## CLI contract
|
|
70
|
+
|
|
71
|
+
Agents always use `--json` and explicit scope:
|
|
72
|
+
|
|
73
|
+
```bash
|
|
74
|
+
superwall whoami --json
|
|
75
|
+
superwall apps list --json
|
|
76
|
+
superwall entitlements list --project <projectId> --json
|
|
77
|
+
superwall entitlements create <id> --project <projectId> --json
|
|
78
|
+
superwall products list --project <projectId> --json
|
|
79
|
+
superwall products create <storeId> --project <projectId> --json
|
|
80
|
+
superwall campaigns list --project <projectId> --app <appId> --json
|
|
81
|
+
superwall campaigns create "<description>" <placement> --project <projectId> --app <appId> --json
|
|
82
|
+
superwall campaigns placement <campaignId> <placement> --project <projectId> --app <appId> --json
|
|
83
|
+
```
|
|
@@ -0,0 +1,229 @@
|
|
|
1
|
+
# Adapty → Superwall
|
|
2
|
+
|
|
3
|
+
Definitive playbook. Read fully before editing. Superwall has no Adapty-specific
|
|
4
|
+
"using-adapty" guide, so PAYWALLS-ONLY mode uses the **generic** `PurchaseController`
|
|
5
|
+
(`/docs/ios/guides/advanced-configuration`) - mirror the RevenueCat controller shape in
|
|
6
|
+
`references/revenuecat.md`, swapping RC calls for Adapty calls.
|
|
7
|
+
|
|
8
|
+
## Scope & checklist
|
|
9
|
+
|
|
10
|
+
This migrates the **SDK integration**, not the whole product. Checklist:
|
|
11
|
+
|
|
12
|
+
- [ ] Inventory Adapty SDK usage (grep §3)
|
|
13
|
+
- [ ] Map products / access levels / `getPaywall` call sites (§1)
|
|
14
|
+
- [ ] Re-create products, entitlements, campaign + placements in Superwall via CLI (§4)
|
|
15
|
+
- [ ] Swap SDK calls (activate→configure, access-level reads, present → placement, identify) (§5)
|
|
16
|
+
- [ ] Build + verify each placement; Restore Purchases as an existing subscriber (§7)
|
|
17
|
+
- [ ] FULL only: remove Adapty dependency once verified
|
|
18
|
+
- [ ] Hand back to user: **rebuild paywalls** (superwall framework or dashboard editor), attach products, connect ASC/Play
|
|
19
|
+
|
|
20
|
+
> **Important - what does NOT migrate:**
|
|
21
|
+
>
|
|
22
|
+
> - **Adapty paywall designs** (Paywall Builder / remote config) cannot be imported - they are
|
|
23
|
+
> **rebuilt** - as code with the superwall framework or in the dashboard editor.
|
|
24
|
+
> - **Historical analytics / attribution** stays in Adapty.
|
|
25
|
+
> - **Subscriber base:** there is currently no server-side subscriber migration from Adapty.
|
|
26
|
+
> Existing subscribers keep access because their purchases live with the store (StoreKit /
|
|
27
|
+
> Play Billing); the app reads them device-side via **Restore Purchases** and maps them to
|
|
28
|
+
> Superwall entitlements. No subscriber data currently moves between backends.
|
|
29
|
+
|
|
30
|
+
## Docs access - fetch live, don't trust baked text
|
|
31
|
+
|
|
32
|
+
```bash
|
|
33
|
+
curl -sL https://superwall.com/docs/llms.txt # index
|
|
34
|
+
curl -sL https://superwall.com/docs/ios/guides/advanced-configuration.md # PurchaseController protocol (swap ios→expo/flutter/android)
|
|
35
|
+
curl -sL https://superwall.com/docs/support/faq/how-to-migrate-from-another-provider-to-superwall.md
|
|
36
|
+
```
|
|
37
|
+
|
|
38
|
+
## 1. Concept mapping
|
|
39
|
+
|
|
40
|
+
| Adapty | Superwall | Notes |
|
|
41
|
+
| ------------------------------------------------ | ----------------------------------------------------- | ------------------------------------------------------------------------------------------------------ |
|
|
42
|
+
| Product (store SKU) | **Product** (re-created) | Keep the SAME App Store / Play product id. |
|
|
43
|
+
| Paywall (Adapty Paywall Builder / remote config) | **Paywall** (rebuilt) | Design does NOT import - rebuild from scratch. |
|
|
44
|
+
| Placement (`main`, `onboarding`, …) | **Placement** (inside a **Campaign**) | Closest 1:1 - Adapty already hardcodes placement ids at call sites; reuse the names (as `snake_case`). |
|
|
45
|
+
| Access Level (e.g. `premium`) | **Entitlement** (re-created) | 1:1. Recreate each access-level id as a Superwall entitlement. |
|
|
46
|
+
| `profile.accessLevels["premium"].isActive` | `Superwall.shared.subscriptionStatus.isActive` (FULL) | Device-derived in FULL mode. |
|
|
47
|
+
| Profile (Adapty user) | Superwall user (`identify`) | |
|
|
48
|
+
| `Adapty.updateProfile` custom attributes | `Superwall.shared.setUserAttributes` | |
|
|
49
|
+
|
|
50
|
+
**Mental-model shift.** Adapty already uses placements - but you call `Adapty.getPaywall(placementId:)`,
|
|
51
|
+
fetch products, and present. In Superwall you just `register(placement:)` at the call site and the
|
|
52
|
+
**campaign** decides whether/which paywall shows. The decision moves from app code to the dashboard.
|
|
53
|
+
|
|
54
|
+
## 2. Three modes - decide who owns purchases first
|
|
55
|
+
|
|
56
|
+
Once Adapty is gone, something still has to purchase, restore, and **tell Superwall who is
|
|
57
|
+
subscribed** - Superwall only auto-detects state when its own SDK made the purchase.
|
|
58
|
+
|
|
59
|
+
### Mode A - FULL, Superwall owns purchases (default)
|
|
60
|
+
|
|
61
|
+
Remove Adapty. Superwall handles purchase/restore and computes entitlements from device records. No `PurchaseController`, no manual status setting.
|
|
62
|
+
|
|
63
|
+
### Mode B - FULL, app keeps its own purchase flow (custom UI / direct StoreKit or Play Billing)
|
|
64
|
+
|
|
65
|
+
Adapty is gone, but the app still buys through its own code and uses Superwall only for paywalls.
|
|
66
|
+
Superwall does NOT observe purchases it didn't make.
|
|
67
|
+
|
|
68
|
+
> **Important:** From advanced-configuration, verbatim: "You **must** set
|
|
69
|
+
> `Superwall.shared.subscriptionStatus` every time the user's subscription status changes, otherwise
|
|
70
|
+
> the SDK won't know who to show a paywall to." Do exactly ONE of: (1) implement a `PurchaseController`
|
|
71
|
+
> that sets `subscriptionStatus`; (2) enable observer mode - `SuperwallOptions().shouldObservePurchases = true`
|
|
72
|
+
> (then you can't call `Superwall.shared.purchase(...)`); or (3) push status manually after every
|
|
73
|
+
> purchase/restore/expiry (iOS: from a `Transaction.currentEntitlements` read +
|
|
74
|
+
> `Transaction.updates` listener; Expo/RN/Flutter: `Superwall.shared.setSubscriptionStatus(...)`).
|
|
75
|
+
> Skip this and Superwall shows paywalls to paying users.
|
|
76
|
+
|
|
77
|
+
```bash
|
|
78
|
+
curl -sL https://superwall.com/docs/ios/quickstart/tracking-subscription-state.md # + expo/ · flutter/ variants
|
|
79
|
+
curl -sL https://superwall.com/docs/ios/guides/advanced/observer-mode.md
|
|
80
|
+
```
|
|
81
|
+
|
|
82
|
+
### Mode C - PAYWALLS-ONLY, Adapty stays the purchase controller
|
|
83
|
+
|
|
84
|
+
Keep Adapty for purchases/receipts/webhooks; Superwall only shows paywalls. Implement a Superwall
|
|
85
|
+
`PurchaseController` whose `purchase`/`restore` call Adapty, and mirror Adapty access levels into
|
|
86
|
+
`Superwall.shared.subscriptionStatus` / `setSubscriptionStatus`. Confirm the exact
|
|
87
|
+
`PurchaseController` protocol signatures live (there is no Adapty-specific sample):
|
|
88
|
+
|
|
89
|
+
```bash
|
|
90
|
+
curl -sL https://superwall.com/docs/ios/guides/advanced-configuration.md
|
|
91
|
+
```
|
|
92
|
+
|
|
93
|
+
_Pure observer_ (analytics-only, Adapty owns purchases AND paywalls): `SuperwallOptions.shouldObservePurchases = true`. `curl -sL https://superwall.com/docs/ios/guides/advanced/observer-mode.md`
|
|
94
|
+
|
|
95
|
+
## 3. Codebase inventory - grep these symbols
|
|
96
|
+
|
|
97
|
+
**iOS (Swift, `Adapty`):**
|
|
98
|
+
|
|
99
|
+
- Config: `Adapty.activate(` , `AdaptyConfiguration`, `Adapty.delegate`, `AdaptyDelegate`
|
|
100
|
+
- Paywall/products (→ future placements): `Adapty.getPaywall(placementId:` , `Adapty.getPaywallProducts(paywall:` , `AdaptyUI.getPaywallConfiguration`, `AdaptyPaywallController`, `paywall.remoteConfig`
|
|
101
|
+
- Purchase/restore: `Adapty.makePurchase(product:` , `Adapty.restorePurchases(`
|
|
102
|
+
- Access-level checks (→ future gates): `Adapty.getProfile(` , `profile.accessLevels[` , `.isActive`, `AdaptyDelegate.didLoadLatestProfile`
|
|
103
|
+
- Identity/attributes: `Adapty.identify(` , `Adapty.logout(` , `Adapty.updateProfile(` (`AdaptyProfileParameters` / `.customAttributes`)
|
|
104
|
+
|
|
105
|
+
**React Native (`react-native-adapty`):**
|
|
106
|
+
`adapty.activate('APP_KEY')`, `adapty.getPaywall(placementId)`, `adapty.getPaywallProducts(paywall)`,
|
|
107
|
+
`adapty.makePurchase(product)`, `adapty.restorePurchases()`, `adapty.getProfile()`,
|
|
108
|
+
`profile.accessLevels['premium'].isActive`, `adapty.identify(id)`, `adapty.logout()`,
|
|
109
|
+
`adapty.updateProfile({...})`, `adapty.addEventListener('onLatestProfileLoad', …)`.
|
|
110
|
+
|
|
111
|
+
**Flutter (`adapty_flutter`):**
|
|
112
|
+
`Adapty().activate(...)`, `Adapty().getPaywall(placementId: ...)`, `Adapty().getPaywallProducts(paywall: ...)`,
|
|
113
|
+
`Adapty().makePurchase(product: ...)`, `Adapty().restorePurchases()`, `Adapty().getProfile()`,
|
|
114
|
+
`profile.accessLevels['premium']?.isActive`, `Adapty().identify(...)`, `Adapty().logout()`,
|
|
115
|
+
`Adapty().updateProfile(...)`, `adaptyDelegate.didLoadLatestProfile`.
|
|
116
|
+
|
|
117
|
+
Produce: product ids, access-level ids (→ entitlements), and one row per `getPaywall`/present call site → placement (reuse Adapty's placement id, `snake_case`).
|
|
118
|
+
|
|
119
|
+
## 4. Dashboard-side re-creation (CLI)
|
|
120
|
+
|
|
121
|
+
```bash
|
|
122
|
+
superwall entitlements create premium --project <projectId> --json
|
|
123
|
+
superwall products create com.app.premium_monthly --name "Premium Monthly" --project <projectId> --json
|
|
124
|
+
superwall products create com.app.premium_yearly --name "Premium Yearly" --project <projectId> --json
|
|
125
|
+
superwall campaigns create "Main paywall" main --project <projectId> --app <appId> --json
|
|
126
|
+
superwall campaigns placement <campaignId> onboarding --project <projectId> --app <appId> --json
|
|
127
|
+
```
|
|
128
|
+
|
|
129
|
+
Product ids MUST equal existing App Store / Play SKUs (import from ASC via `superwall asc keys set --help`).
|
|
130
|
+
Verify with the same explicit ids: `superwall entitlements list --project <projectId> --json`,
|
|
131
|
+
`superwall products list --project <projectId> --json`, and `superwall campaigns list --project <projectId> --app <appId> --json`.
|
|
132
|
+
|
|
133
|
+
## 5. Code replacement
|
|
134
|
+
|
|
135
|
+
### FULL mode
|
|
136
|
+
|
|
137
|
+
- **Configure.** Replace `Adapty.activate(...)` with `Superwall.configure(apiKey: "…")`. No purchase controller.
|
|
138
|
+
- **Access-level checks → subscriptionStatus.**
|
|
139
|
+
```swift
|
|
140
|
+
// Before
|
|
141
|
+
let profile = try? await Adapty.getProfile()
|
|
142
|
+
return profile?.accessLevels["premium"]?.isActive ?? false
|
|
143
|
+
// After
|
|
144
|
+
if Superwall.shared.subscriptionStatus.isActive { /* entitled */ }
|
|
145
|
+
// per-entitlement: switch Superwall.shared.subscriptionStatus { case .active(let e): … ; case .inactive: … ; case .unknown: … }
|
|
146
|
+
```
|
|
147
|
+
- **Presentation → placement.** Replace `getPaywall` + `getPaywallProducts` + present with:
|
|
148
|
+
```swift
|
|
149
|
+
Superwall.shared.register(placement: "main") { unlockFeature() }
|
|
150
|
+
```
|
|
151
|
+
RN: `Superwall.shared.register({ placement: "main" }, () => {...})`.
|
|
152
|
+
Flutter: `Superwall.shared.registerPlacement("main", feature: () {...})`.
|
|
153
|
+
- **Identity.** `Adapty.identify(id)` → `Superwall.shared.identify(userId: id)`; `Adapty.logout()` → `Superwall.shared.reset()`.
|
|
154
|
+
- **Attributes.** `Adapty.updateProfile(params)` (customAttributes) → `Superwall.shared.setUserAttributes([...])`. Call `identify` BEFORE `setUserAttributes`.
|
|
155
|
+
- Remove the Adapty dependency only after build + verification.
|
|
156
|
+
|
|
157
|
+
### PAYWALLS-ONLY mode - bridge to Adapty
|
|
158
|
+
|
|
159
|
+
Build a Superwall `PurchaseController` (confirm signatures at advanced-configuration). Skeleton,
|
|
160
|
+
mirroring the RC pattern with Adapty calls:
|
|
161
|
+
|
|
162
|
+
```swift
|
|
163
|
+
final class AdaptyPurchaseController: PurchaseController {
|
|
164
|
+
func syncSubscriptionStatus() {
|
|
165
|
+
// Adapty is the source of truth. On every profile update (AdaptyDelegate.didLoadLatestProfile
|
|
166
|
+
// or an initial getProfile), map active access levels → Superwall entitlements:
|
|
167
|
+
// let ents = profile.accessLevels.filter { $0.value.isActive }.keys.map { Entitlement(id: $0) }
|
|
168
|
+
// Superwall.shared.subscriptionStatus = ents.isEmpty ? .inactive : .active(Set(ents))
|
|
169
|
+
}
|
|
170
|
+
func purchase(product: SuperwallKit.StoreProduct) async -> PurchaseResult {
|
|
171
|
+
// Resolve the matching AdaptyPaywallProduct (or make an Adapty purchase by product id),
|
|
172
|
+
// call Adapty.makePurchase(product:), map its result → .purchased / .cancelled / .pending / .failed(error)
|
|
173
|
+
}
|
|
174
|
+
func restorePurchases() async -> RestorationResult {
|
|
175
|
+
// try await Adapty.restorePurchases(); return .restored (catch → .failed(error))
|
|
176
|
+
}
|
|
177
|
+
}
|
|
178
|
+
```
|
|
179
|
+
|
|
180
|
+
Wire: `Superwall.configure(apiKey: "…", purchaseController: AdaptyPurchaseController())` then start the sync.
|
|
181
|
+
Set `AdaptyDelegate` so `didLoadLatestProfile` drives `Superwall.shared.subscriptionStatus` (iOS) /
|
|
182
|
+
`setSubscriptionStatus(...)` (RN/Flutter). Confirm the exact `PurchaseController` method signatures and
|
|
183
|
+
`PurchaseResult`/`RestorationResult` cases at the advanced-configuration doc before finalizing.
|
|
184
|
+
|
|
185
|
+
## 6. Feature gating
|
|
186
|
+
|
|
187
|
+
Set per placement in the editor (**General → Feature Gating**): non-gated (closure runs on dismiss
|
|
188
|
+
regardless) vs gated (only when entitled). Peek: `Superwall.shared.getPresentationResult(forPlacement:)`.
|
|
189
|
+
`curl -sL https://superwall.com/docs/ios/quickstart/feature-gating.md`
|
|
190
|
+
|
|
191
|
+
## 7. Order of operations + safety
|
|
192
|
+
|
|
193
|
+
1. Re-create entitlements/products/campaign+placements (CLI); import products from ASC/Play so ids match.
|
|
194
|
+
2. **Rebuild** paywalls (superwall framework or dashboard editor), attach products (hand-back to user - designs do not import).
|
|
195
|
+
3. Add Superwall SDK alongside Adapty; configure it.
|
|
196
|
+
4. Replace `getPaywall`/present call sites with `register(placement:)`; replace access-level reads with `subscriptionStatus`.
|
|
197
|
+
5. Build, present each placement, Restore Purchases as an existing subscriber, confirm `subscriptionStatus.isActive`.
|
|
198
|
+
6. FULL: remove controller + Adapty dependency. PAYWALLS-ONLY: keep Adapty + controller.
|
|
199
|
+
7. Never delete Adapty dashboard/webhook config until verified in production. Existing subscribers keep access via device-side Restore Purchases (Superwall reads store records) - no server-side subscriber migration currently exists.
|
|
200
|
+
|
|
201
|
+
## 8. Pitfalls
|
|
202
|
+
|
|
203
|
+
- **Double-finish / double-charge.** Exactly one SDK finishes transactions. PAYWALLS-ONLY: Adapty owns purchasing via the controller; never also call `Superwall.shared.purchase`. FULL: remove Adapty purchase paths.
|
|
204
|
+
- **StoreKit listener conflicts.** Two SDKs observing StoreKit → duplicate grants/races. One owner only.
|
|
205
|
+
- **Silent "everyone sees a paywall" bug (Mode B).** Removed Adapty but kept the app's own purchase
|
|
206
|
+
flow (custom UI / direct StoreKit / Play Billing) without syncing state → Superwall treats every user
|
|
207
|
+
as unsubscribed and shows paywalls to payers. Grep for `purchase(` / `Transaction.updates` /
|
|
208
|
+
`BillingClient` outside Superwall; if purchases happen outside Superwall, sync via controller,
|
|
209
|
+
observer mode, or a manual `subscriptionStatus` set (§2 Mode B).
|
|
210
|
+
- **Observer flag.** `shouldObservePurchases = true` disables `Superwall.shared.purchase`; observer mode only.
|
|
211
|
+
- **Entitlement id mismatch.** Superwall entitlement ids must equal Adapty access-level ids exactly (`premium` ≠ `Premium`).
|
|
212
|
+
- **Access-level nuances.** Adapty access levels also carry grace-period / lifetime / billing-issue states; when mirroring, treat `isActive` (incl. grace period per your policy) as entitled - don't silently drop grace-period users.
|
|
213
|
+
- **Cache during switchover.** Status may read `.unknown`/`.inactive` until the first profile load / StoreKit sync - prompt Restore Purchases if a known subscriber looks free.
|
|
214
|
+
- **identify order.** `identify` before `setUserAttributes`.
|
|
215
|
+
- **Unverified controller signatures.** The Adapty controller above is a skeleton - verify `PurchaseController` protocol + result enums at the advanced-configuration doc, since there's no official Adapty sample.
|
|
216
|
+
|
|
217
|
+
## 9. Deeper docs (fetch live)
|
|
218
|
+
|
|
219
|
+
```bash
|
|
220
|
+
curl -sL https://superwall.com/docs/support/faq/how-to-migrate-from-another-provider-to-superwall.md
|
|
221
|
+
curl -sL https://superwall.com/docs/ios/guides/advanced-configuration.md # PurchaseController (+ expo/flutter/android)
|
|
222
|
+
curl -sL https://superwall.com/docs/ios/guides/advanced/observer-mode.md
|
|
223
|
+
curl -sL https://superwall.com/docs/ios/quickstart/tracking-subscription-state.md
|
|
224
|
+
curl -sL https://superwall.com/docs/llms.txt # index
|
|
225
|
+
```
|
|
226
|
+
|
|
227
|
+
- PurchaseController reference: https://superwall.com/docs/ios/sdk-reference/PurchaseController
|
|
228
|
+
- register/identify/setUserAttributes: https://superwall.com/docs/ios/sdk-reference/register · .../identify · .../setUserAttributes
|
|
229
|
+
- Adapty side: https://adapty.io/docs/ios-sdk-overview · https://adapty.io/docs/making-purchases · RN https://adapty.io/docs/react-native-making-purchases · Flutter https://adapty.io/docs/flutter-sdk-making-purchases
|