@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,227 @@
|
|
|
1
|
+
# Qonversion → Superwall
|
|
2
|
+
|
|
3
|
+
Definitive playbook. Read fully before editing. Superwall has no Qonversion-specific
|
|
4
|
+
"using-qonversion" 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 Qonversion calls.
|
|
7
|
+
|
|
8
|
+
## Scope & checklist
|
|
9
|
+
|
|
10
|
+
This migrates the **SDK integration**, not the whole product. Checklist:
|
|
11
|
+
|
|
12
|
+
- [ ] Inventory Qonversion SDK usage (grep §3)
|
|
13
|
+
- [ ] Map products / entitlements / offering-fetch call sites (§1)
|
|
14
|
+
- [ ] Re-create products, entitlements, campaign + placements in Superwall via CLI (§4)
|
|
15
|
+
- [ ] Swap SDK calls (init→configure, entitlement reads, present → placement, identify) (§5)
|
|
16
|
+
- [ ] Build + verify each placement; Restore Purchases as an existing subscriber (§7)
|
|
17
|
+
- [ ] FULL only: remove Qonversion 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
|
+
> - **Qonversion paywall UI** cannot be imported - paywalls are **rebuilt** - as code with the superwall framework or in the dashboard editor.
|
|
23
|
+
> - **Historical analytics / attribution** stays in Qonversion.
|
|
24
|
+
> - **Subscriber base:** there is currently no server-side subscriber migration from Qonversion.
|
|
25
|
+
> Existing subscribers keep access because their purchases live with the store (StoreKit /
|
|
26
|
+
> Play Billing); the app reads them device-side via **Restore Purchases** and maps them to
|
|
27
|
+
> Superwall entitlements. No subscriber data currently moves between backends.
|
|
28
|
+
|
|
29
|
+
## Docs access - fetch live, don't trust baked text
|
|
30
|
+
|
|
31
|
+
```bash
|
|
32
|
+
curl -sL https://superwall.com/docs/llms.txt # index
|
|
33
|
+
curl -sL https://superwall.com/docs/ios/guides/advanced-configuration.md # PurchaseController protocol (swap ios→expo/flutter/android)
|
|
34
|
+
curl -sL https://superwall.com/docs/support/faq/how-to-migrate-from-another-provider-to-superwall.md
|
|
35
|
+
```
|
|
36
|
+
|
|
37
|
+
## 1. Concept mapping
|
|
38
|
+
|
|
39
|
+
| Qonversion | Superwall | Notes |
|
|
40
|
+
| ------------------------------------------ | ---------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------- |
|
|
41
|
+
| Product (store SKU, Qonversion dashboard) | **Product** (re-created) | Keep the SAME App Store / Play product id. |
|
|
42
|
+
| Offering (remote product collection) | **Paywall** + **Campaign** | Qonversion swaps products remotely via offerings; Superwall swaps the whole paywall remotely via campaign rules. |
|
|
43
|
+
| Entitlement / Permission (e.g. `premium`) | **Entitlement** (re-created) | 1:1. Recreate each entitlement id as a Superwall entitlement. |
|
|
44
|
+
| `entitlements["premium"].isActive` | `Superwall.shared.subscriptionStatus.isActive` (FULL) | Device-derived in FULL mode. |
|
|
45
|
+
| User (Qonversion) + `identify` | Superwall user (`identify`) | |
|
|
46
|
+
| `setUserProperty` | `Superwall.shared.setUserAttributes` | |
|
|
47
|
+
| Where you fetch an offering and present UI | **Placement** at the call site (paywall rebuilt in editor) | |
|
|
48
|
+
|
|
49
|
+
**Mental-model shift.** With Qonversion you `checkEntitlements()`, then fetch an `offering` and
|
|
50
|
+
present your own paywall UI. In Superwall you `register(placement:)` at the call site and the
|
|
51
|
+
**campaign** decides whether/which paywall shows. Move the decision from app code to the dashboard.
|
|
52
|
+
|
|
53
|
+
## 2. Three modes - decide who owns purchases first
|
|
54
|
+
|
|
55
|
+
Once Qonversion is gone, something still has to purchase, restore, and **tell Superwall who is
|
|
56
|
+
subscribed** - Superwall only auto-detects state when its own SDK made the purchase.
|
|
57
|
+
|
|
58
|
+
### Mode A - FULL, Superwall owns purchases (default)
|
|
59
|
+
|
|
60
|
+
Remove Qonversion. Superwall handles purchase/restore and computes entitlements from device records. No `PurchaseController`, no manual status setting.
|
|
61
|
+
|
|
62
|
+
### Mode B - FULL, app keeps its own purchase flow (custom UI / direct StoreKit or Play Billing)
|
|
63
|
+
|
|
64
|
+
Qonversion is gone, but the app still buys through its own code and uses Superwall only for paywalls.
|
|
65
|
+
Superwall does NOT observe purchases it didn't make.
|
|
66
|
+
|
|
67
|
+
> **Important:** From advanced-configuration, verbatim: "You **must** set
|
|
68
|
+
> `Superwall.shared.subscriptionStatus` every time the user's subscription status changes, otherwise
|
|
69
|
+
> the SDK won't know who to show a paywall to." Do exactly ONE of: (1) implement a `PurchaseController`
|
|
70
|
+
> that sets `subscriptionStatus`; (2) enable observer mode - `SuperwallOptions().shouldObservePurchases = true`
|
|
71
|
+
> (then you can't call `Superwall.shared.purchase(...)`); or (3) push status manually after every
|
|
72
|
+
> purchase/restore/expiry (iOS: from a `Transaction.currentEntitlements` read +
|
|
73
|
+
> `Transaction.updates` listener; Expo/RN/Flutter: `Superwall.shared.setSubscriptionStatus(...)`).
|
|
74
|
+
> Skip this and Superwall shows paywalls to paying users.
|
|
75
|
+
|
|
76
|
+
```bash
|
|
77
|
+
curl -sL https://superwall.com/docs/ios/quickstart/tracking-subscription-state.md # + expo/ · flutter/ variants
|
|
78
|
+
curl -sL https://superwall.com/docs/ios/guides/advanced/observer-mode.md
|
|
79
|
+
```
|
|
80
|
+
|
|
81
|
+
### Mode C - PAYWALLS-ONLY, Qonversion stays the purchase controller
|
|
82
|
+
|
|
83
|
+
Keep Qonversion for purchases/receipts/webhooks; Superwall only shows paywalls. Implement a
|
|
84
|
+
Superwall `PurchaseController` whose `purchase`/`restore` call Qonversion, and mirror Qonversion
|
|
85
|
+
entitlements into `Superwall.shared.subscriptionStatus` / `setSubscriptionStatus`. Confirm exact
|
|
86
|
+
`PurchaseController` signatures live (no Qonversion-specific sample exists):
|
|
87
|
+
|
|
88
|
+
```bash
|
|
89
|
+
curl -sL https://superwall.com/docs/ios/guides/advanced-configuration.md
|
|
90
|
+
```
|
|
91
|
+
|
|
92
|
+
_Pure observer_ (analytics-only, Qonversion owns purchases AND paywalls): `SuperwallOptions.shouldObservePurchases = true`. `curl -sL https://superwall.com/docs/ios/guides/advanced/observer-mode.md`
|
|
93
|
+
|
|
94
|
+
## 3. Codebase inventory - grep these symbols
|
|
95
|
+
|
|
96
|
+
**iOS (Swift, `Qonversion`):**
|
|
97
|
+
|
|
98
|
+
- Config: `Qonversion.initWithConfig(` , `Qonversion.shared(`, `Qonversion.Configuration`
|
|
99
|
+
- Offerings/products (→ future placements): `Qonversion.shared().offerings(` , `.products(`, `offering.products`
|
|
100
|
+
- Purchase/restore: `.purchase(` , `.purchaseProduct(`, `.restore(`
|
|
101
|
+
- Entitlement checks (→ future gates): `.checkEntitlements(` , `.entitlements(`, `entitlements["premium"]`, `.isActive`
|
|
102
|
+
- Identity/attributes: `.identify(` , `.logout(`, `.setUserProperty(`, `.setCustomUserProperty(`
|
|
103
|
+
|
|
104
|
+
**React Native (`react-native-qonversion`):**
|
|
105
|
+
`Qonversion.initialize(config)`, `Qonversion.getSharedInstance()`, `.offerings()`, `.products()`,
|
|
106
|
+
`.purchaseProduct()` / `.purchase()`, `.restore()`, `.checkEntitlements()`, `entitlements['premium'].isActive`,
|
|
107
|
+
`.identify(userId)`, `.logout()`, `.setUserProperty()` / `.setCustomUserProperty()`.
|
|
108
|
+
|
|
109
|
+
**Flutter (`qonversion_flutter`):**
|
|
110
|
+
`Qonversion.initialize(config)`, `Qonversion.getSharedInstance()`, `.offerings()`, `.products()`,
|
|
111
|
+
`.purchase(id)` / `.purchaseProduct(product)`, `.restore()`, `.checkEntitlements()`,
|
|
112
|
+
`entitlements['premium']?.isActive`, `.identify(userId)`, `.logout()`, `.setUserProperty()` / `.setCustomUserProperty()`.
|
|
113
|
+
|
|
114
|
+
Produce: product ids, entitlement/permission ids (→ entitlements), and one row per offering-fetch/present call site → placement (`snake_case`).
|
|
115
|
+
|
|
116
|
+
## 4. Dashboard-side re-creation (CLI)
|
|
117
|
+
|
|
118
|
+
```bash
|
|
119
|
+
superwall entitlements create premium --project <projectId> --json
|
|
120
|
+
superwall products create com.app.premium_monthly --name "Premium Monthly" --project <projectId> --json
|
|
121
|
+
superwall products create com.app.premium_yearly --name "Premium Yearly" --project <projectId> --json
|
|
122
|
+
superwall campaigns create "Main paywall" paywall_main --project <projectId> --app <appId> --json
|
|
123
|
+
```
|
|
124
|
+
|
|
125
|
+
Product ids MUST equal existing App Store / Play SKUs (import from ASC via `superwall asc keys set --help`).
|
|
126
|
+
Verify with the same explicit ids: `superwall entitlements list --project <projectId> --json`,
|
|
127
|
+
`superwall products list --project <projectId> --json`, and `superwall campaigns list --project <projectId> --app <appId> --json`.
|
|
128
|
+
|
|
129
|
+
## 5. Code replacement
|
|
130
|
+
|
|
131
|
+
### FULL mode
|
|
132
|
+
|
|
133
|
+
- **Configure.** Replace `Qonversion.initWithConfig(...)` with `Superwall.configure(apiKey: "…")`. No purchase controller.
|
|
134
|
+
- **Entitlement checks → subscriptionStatus.**
|
|
135
|
+
```swift
|
|
136
|
+
// Before
|
|
137
|
+
Qonversion.shared().checkEntitlements { entitlements, error in
|
|
138
|
+
let active = entitlements["premium"]?.isActive ?? false
|
|
139
|
+
}
|
|
140
|
+
// After
|
|
141
|
+
if Superwall.shared.subscriptionStatus.isActive { /* entitled */ }
|
|
142
|
+
// per-entitlement: switch Superwall.shared.subscriptionStatus { case .active(let e): … ; case .inactive: … ; case .unknown: … }
|
|
143
|
+
```
|
|
144
|
+
- **Presentation → placement.** Replace offering fetch + present with:
|
|
145
|
+
```swift
|
|
146
|
+
Superwall.shared.register(placement: "paywall_main") { unlockFeature() }
|
|
147
|
+
```
|
|
148
|
+
RN: `Superwall.shared.register({ placement: "paywall_main" }, () => {...})`.
|
|
149
|
+
Flutter: `Superwall.shared.registerPlacement("paywall_main", feature: () {...})`.
|
|
150
|
+
- **Identity.** `Qonversion.shared().identify(id)` → `Superwall.shared.identify(userId: id)`; `.logout()` → `Superwall.shared.reset()`.
|
|
151
|
+
- **Attributes.** `.setUserProperty(...)` / `.setCustomUserProperty(...)` → `Superwall.shared.setUserAttributes([...])`. Call `identify` BEFORE `setUserAttributes`.
|
|
152
|
+
- Remove the Qonversion dependency only after build + verification.
|
|
153
|
+
|
|
154
|
+
### PAYWALLS-ONLY mode - bridge to Qonversion
|
|
155
|
+
|
|
156
|
+
Build a Superwall `PurchaseController` (confirm signatures at advanced-configuration). Skeleton,
|
|
157
|
+
mirroring the RC pattern with Qonversion calls:
|
|
158
|
+
|
|
159
|
+
```swift
|
|
160
|
+
final class QonversionPurchaseController: PurchaseController {
|
|
161
|
+
func syncSubscriptionStatus() {
|
|
162
|
+
// Qonversion is the source of truth. On launch and after purchase/restore, call
|
|
163
|
+
// Qonversion.shared().checkEntitlements and map active entitlements → Superwall entitlements:
|
|
164
|
+
// let ents = entitlements.values.filter { $0.isActive }.map { Entitlement(id: $0.id) }
|
|
165
|
+
// Superwall.shared.subscriptionStatus = ents.isEmpty ? .inactive : .active(Set(ents))
|
|
166
|
+
// (Qonversion has no continuous stream - re-check after each purchase/restore and on foreground.)
|
|
167
|
+
}
|
|
168
|
+
func purchase(product: SuperwallKit.StoreProduct) async -> PurchaseResult {
|
|
169
|
+
// Resolve the Qonversion product by id, call Qonversion.shared().purchaseProduct(...),
|
|
170
|
+
// map result → .purchased / .cancelled / .pending / .failed(error)
|
|
171
|
+
}
|
|
172
|
+
func restorePurchases() async -> RestorationResult {
|
|
173
|
+
// Qonversion.shared().restore(...); on success return .restored (catch → .failed(error))
|
|
174
|
+
}
|
|
175
|
+
}
|
|
176
|
+
```
|
|
177
|
+
|
|
178
|
+
Wire: `Superwall.configure(apiKey: "…", purchaseController: QonversionPurchaseController())` then start the sync.
|
|
179
|
+
RN/Flutter: drive `Superwall.shared.setSubscriptionStatus(...)` from `checkEntitlements()` results after
|
|
180
|
+
each purchase/restore/foreground. Confirm exact `PurchaseController` signatures and
|
|
181
|
+
`PurchaseResult`/`RestorationResult` cases at the advanced-configuration doc before finalizing.
|
|
182
|
+
|
|
183
|
+
## 6. Feature gating
|
|
184
|
+
|
|
185
|
+
Set per placement in the editor (**General → Feature Gating**): non-gated (closure runs on dismiss
|
|
186
|
+
regardless) vs gated (only when entitled). Peek: `Superwall.shared.getPresentationResult(forPlacement:)`.
|
|
187
|
+
`curl -sL https://superwall.com/docs/ios/quickstart/feature-gating.md`
|
|
188
|
+
|
|
189
|
+
## 7. Order of operations + safety
|
|
190
|
+
|
|
191
|
+
1. Re-create entitlements/products/campaign+placements (CLI); import products from ASC/Play so ids match.
|
|
192
|
+
2. **Rebuild** paywalls (superwall framework or dashboard editor), attach products (hand-back to user - designs do not import).
|
|
193
|
+
3. Add Superwall SDK alongside Qonversion; configure it.
|
|
194
|
+
4. Replace offering-fetch/present call sites with `register(placement:)`; replace `checkEntitlements` reads with `subscriptionStatus`.
|
|
195
|
+
5. Build, present each placement, Restore Purchases as an existing subscriber, confirm `subscriptionStatus.isActive`.
|
|
196
|
+
6. FULL: remove controller + Qonversion dependency. PAYWALLS-ONLY: keep Qonversion + controller.
|
|
197
|
+
7. Never delete Qonversion 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.
|
|
198
|
+
|
|
199
|
+
## 8. Pitfalls
|
|
200
|
+
|
|
201
|
+
- **Double-finish / double-charge.** Exactly one SDK finishes transactions. PAYWALLS-ONLY: Qonversion owns purchasing via the controller; never also call `Superwall.shared.purchase`. FULL: remove Qonversion purchase paths.
|
|
202
|
+
- **StoreKit listener conflicts.** Two SDKs observing StoreKit → duplicate grants/races. One owner only.
|
|
203
|
+
- **Silent "everyone sees a paywall" bug (Mode B).** Removed Qonversion but kept the app's own purchase
|
|
204
|
+
flow (custom UI / direct StoreKit / Play Billing) without syncing state → Superwall treats every user
|
|
205
|
+
as unsubscribed and shows paywalls to payers. Grep for `purchase(` / `Transaction.updates` /
|
|
206
|
+
`BillingClient` outside Superwall; if purchases happen outside Superwall, sync via controller,
|
|
207
|
+
observer mode, or a manual `subscriptionStatus` set (§2 Mode B).
|
|
208
|
+
- **Observer flag.** `shouldObservePurchases = true` disables `Superwall.shared.purchase`; observer mode only.
|
|
209
|
+
- **Entitlement id mismatch.** Superwall entitlement ids must equal Qonversion entitlement/permission ids exactly (`premium` ≠ `Premium`).
|
|
210
|
+
- **No continuous stream.** Unlike RC's `customerInfoStream`, Qonversion has no push stream - re-run `checkEntitlements` after each purchase/restore and on app foreground so `subscriptionStatus` stays fresh.
|
|
211
|
+
- **Cache during switchover.** Status may read `.unknown`/`.inactive` until the first `checkEntitlements` / StoreKit sync - prompt Restore Purchases if a known subscriber looks free.
|
|
212
|
+
- **identify order.** `identify` before `setUserAttributes`.
|
|
213
|
+
- **Unverified controller signatures.** The Qonversion controller above is a skeleton - verify `PurchaseController` protocol + result enums at the advanced-configuration doc, since there's no official Qonversion sample.
|
|
214
|
+
|
|
215
|
+
## 9. Deeper docs (fetch live)
|
|
216
|
+
|
|
217
|
+
```bash
|
|
218
|
+
curl -sL https://superwall.com/docs/support/faq/how-to-migrate-from-another-provider-to-superwall.md
|
|
219
|
+
curl -sL https://superwall.com/docs/ios/guides/advanced-configuration.md # PurchaseController (+ expo/flutter/android)
|
|
220
|
+
curl -sL https://superwall.com/docs/ios/guides/advanced/observer-mode.md
|
|
221
|
+
curl -sL https://superwall.com/docs/ios/quickstart/tracking-subscription-state.md
|
|
222
|
+
curl -sL https://superwall.com/docs/llms.txt # index
|
|
223
|
+
```
|
|
224
|
+
|
|
225
|
+
- PurchaseController reference: https://superwall.com/docs/ios/sdk-reference/PurchaseController
|
|
226
|
+
- register/identify/setUserAttributes: https://superwall.com/docs/ios/sdk-reference/register · .../identify · .../setUserAttributes
|
|
227
|
+
- Qonversion side: https://documentation.qonversion.io/docs/making-purchases · https://documentation.qonversion.io/docs/flutter-sdk · RN https://github.com/qonversion/react-native-sdk
|
|
@@ -0,0 +1,414 @@
|
|
|
1
|
+
# RevenueCat → Superwall
|
|
2
|
+
|
|
3
|
+
Definitive playbook. Read fully before editing.
|
|
4
|
+
|
|
5
|
+
## Scope & checklist
|
|
6
|
+
|
|
7
|
+
This migrates the **SDK integration**, not the whole product. Checklist:
|
|
8
|
+
|
|
9
|
+
- [ ] Inventory RevenueCat SDK usage (grep §3)
|
|
10
|
+
- [ ] Map products / entitlements / presentation call sites (§1)
|
|
11
|
+
- [ ] Re-create products, entitlements, campaign + placements in Superwall via CLI (§4)
|
|
12
|
+
- [ ] Swap SDK calls (configure, entitlement reads, presentation → placement, identify) (§5)
|
|
13
|
+
- [ ] **Confirm subscription state reaches Superwall** - grep for `purchase(`, `Transaction.updates`,
|
|
14
|
+
`Transaction.currentEntitlements`, `BillingClient`, or any purchase call site _outside_ Superwall.
|
|
15
|
+
If ANY purchase can happen without Superwall making it (Mode B / Mode C), verify state is synced
|
|
16
|
+
via a `PurchaseController`, observer mode, or a manual `subscriptionStatus` set - otherwise
|
|
17
|
+
Superwall shows paywalls to paying users (§2)
|
|
18
|
+
- [ ] **Inventory side-effects in RC purchase/restore callbacks before deleting** - backend sync
|
|
19
|
+
POSTs, analytics (Singular/PostHog/TikTok/…), attribution, post-purchase navigation - and reroute
|
|
20
|
+
each into a `SuperwallDelegate` (§5 "Side-effects")
|
|
21
|
+
- [ ] **Identity lifecycle**: `identify` at login/session-restore; `reset()` on EVERY sign-out path
|
|
22
|
+
(logout, account deletion, forced 401) (§5)
|
|
23
|
+
- [ ] **Inventory ALL other purchase stacks** (SwiftyStoreKit, `SKPaymentQueue`, IAPManager-style
|
|
24
|
+
singletons) - remove or explicitly retire; one transaction finisher only (§3)
|
|
25
|
+
- [ ] **Dashboard account gate**: `superwall apps list --json` must show the app matching the code's
|
|
26
|
+
`pk_` key / bundle id BEFORE any create; wrong account → stop dashboard work loudly (§4)
|
|
27
|
+
- [ ] Build + verify each placement; Restore Purchases as an existing subscriber (§7)
|
|
28
|
+
- [ ] FULL only: remove RC dependency once verified
|
|
29
|
+
- [ ] Hand back to user: **rebuild paywalls** (superwall framework or dashboard editor), attach products, connect ASC/Play
|
|
30
|
+
|
|
31
|
+
> **Important - what does and does NOT migrate:**
|
|
32
|
+
>
|
|
33
|
+
> - **RC paywall designs** cannot be imported - they are **rebuilt** - as code with the superwall framework or in the dashboard editor.
|
|
34
|
+
> - **Historical analytics / attribution** stays in RevenueCat.
|
|
35
|
+
> - **Subscriber base:** Superwall provides server-side RevenueCat migration tooling that ports
|
|
36
|
+
> subscription history and entitlement state - fetch the migration guide (Docs access below)
|
|
37
|
+
> for the current process before promising specifics. Independently of any data move, existing
|
|
38
|
+
> subscribers keep access via device-side **Restore Purchases** because their purchases live
|
|
39
|
+
> with the store.
|
|
40
|
+
|
|
41
|
+
## Docs access - fetch live, don't trust baked text
|
|
42
|
+
|
|
43
|
+
```bash
|
|
44
|
+
curl -sL https://superwall.com/docs/llms.txt # index
|
|
45
|
+
curl -sL https://superwall.com/docs/dashboard/guides/migrating-from-revenuecat-to-superwall.md # migration guide (verified)
|
|
46
|
+
curl -sL https://superwall.com/docs/ios/guides/using-revenuecat.md # PAYWALLS-ONLY controller (swap ios→expo/flutter/android)
|
|
47
|
+
curl -sL https://superwall.com/docs/ios/guides/advanced-configuration.md # PurchaseController protocol
|
|
48
|
+
curl -sL https://www.revenuecat.com/docs/llms.txt # RevenueCat's own docs index - append .md to any RC docs page to study the existing integration
|
|
49
|
+
```
|
|
50
|
+
|
|
51
|
+
## 1. Concept mapping
|
|
52
|
+
|
|
53
|
+
| RevenueCat | Superwall | Notes |
|
|
54
|
+
| ------------------------------------------------ | ---------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------- |
|
|
55
|
+
| Product (store SKU wrapped in RC dashboard) | **Product** (re-created) | Keep the SAME App Store / Play product identifier. Only the management layer moves. |
|
|
56
|
+
| Package (`$rc_monthly`, inside an Offering) | (no direct equal) | A package is just "product + duration slot." In Superwall you attach the raw products to a paywall (in its `config.ts` with the framework, or in the editor). |
|
|
57
|
+
| Offering (remote set of packages) | **Paywall** + **Campaign** | RC picks products remotely via Offering; Superwall picks the whole paywall (products included) remotely via Campaign rules. |
|
|
58
|
+
| Entitlement (e.g. `pro`) | **Entitlement** (re-created) | 1:1. Recreate each RC entitlement id as a Superwall entitlement. |
|
|
59
|
+
| `customerInfo.entitlements.active` | `Superwall.shared.subscriptionStatus` (`.active(Set<Entitlement>)` / `.inactive` / `.unknown`) | Status is device-derived in FULL mode. |
|
|
60
|
+
| RC Paywalls (RC's paywall UI) | **Paywall** (rebuilt), shown by **placement** | Design does NOT import - see below. |
|
|
61
|
+
| Manual "should I show a paywall?" gating in code | **register(placement:)** - campaign decides | |
|
|
62
|
+
|
|
63
|
+
**Mental-model shift.** With RC you check entitlement status, then decide in code whether to
|
|
64
|
+
fetch an offering and present a paywall. With Superwall you **register a placement at the call
|
|
65
|
+
site** (`register(placement: "start_workout") { … }`) and the **campaign** decides whether a
|
|
66
|
+
paywall shows, which one, and A/B variant. Move the _decision_ out of the app and into the
|
|
67
|
+
dashboard. The trailing feature closure runs when the user is entitled (gated) or always
|
|
68
|
+
(non-gated) - see §6.
|
|
69
|
+
|
|
70
|
+
## 2. Three modes - decide who owns purchases first
|
|
71
|
+
|
|
72
|
+
Removing RevenueCat is not the whole decision. Once RC is gone, _something_ still has to
|
|
73
|
+
purchase, restore, and **tell Superwall who is subscribed**. Superwall only auto-detects
|
|
74
|
+
subscription state when its own SDK made the purchase. Pick the mode that matches the app you
|
|
75
|
+
actually have - the middle one is the easiest to get wrong.
|
|
76
|
+
|
|
77
|
+
### Mode A - FULL, Superwall owns purchases (default, simplest)
|
|
78
|
+
|
|
79
|
+
Remove RevenueCat entirely. Superwall's SDK handles purchase, restore, and entitlement
|
|
80
|
+
computation from the device's App Store / Play records. No `PurchaseController`, no manual status
|
|
81
|
+
setting. Use this unless the app has its own checkout UI or billing code you're keeping.
|
|
82
|
+
|
|
83
|
+
### Mode B - FULL, app keeps its own purchase flow (custom UI / direct StoreKit or Play Billing)
|
|
84
|
+
|
|
85
|
+
RevenueCat is gone, but the app still buys through **its own code** - a custom purchase screen,
|
|
86
|
+
direct StoreKit 2 / Play Billing, or a home-grown billing layer - and uses Superwall _only_ to
|
|
87
|
+
show paywalls and register placements. This is the mode that silently breaks: Superwall does NOT
|
|
88
|
+
observe purchases it didn't make, so unless you sync state it thinks **every** user is unsubscribed
|
|
89
|
+
and shows paywalls to people who already pay.
|
|
90
|
+
|
|
91
|
+
> **Important:** From the advanced-configuration doc, verbatim: "You **must** set
|
|
92
|
+
> `Superwall.shared.subscriptionStatus` every time the user's subscription status changes,
|
|
93
|
+
> otherwise the SDK won't know who to show a paywall to." In this mode you MUST do exactly ONE of:
|
|
94
|
+
>
|
|
95
|
+
> 1. **Implement a `PurchaseController`** - route your purchase/restore through it and set
|
|
96
|
+
> `subscriptionStatus` from it (same controller shape as §5, but calling your own billing code
|
|
97
|
+
> instead of RC).
|
|
98
|
+
> 2. **Enable observer mode** - `SuperwallOptions().shouldObservePurchases = true`. Per the doc,
|
|
99
|
+
> observer mode "solely reports transaction completions" (revenue tracking) - entitlement/
|
|
100
|
+
> subscriptionStatus is kept current by Superwall's server-side pipeline (App Store Server
|
|
101
|
+
> Notifications + the dashboard product → entitlement mapping - confirm against the
|
|
102
|
+
> observer-mode doc below), so that mapping MUST exist for gating to work. You then CANNOT call `Superwall.shared.purchase(...)`.
|
|
103
|
+
> (`curl -sL https://superwall.com/docs/ios/guides/advanced/observer-mode.md`)
|
|
104
|
+
> 3. **Push status manually** - after every purchase / restore / expiry, set
|
|
105
|
+
> `Superwall.shared.subscriptionStatus` yourself (e.g. from a `Transaction.currentEntitlements`
|
|
106
|
+
> read plus a `Transaction.updates` listener on iOS).
|
|
107
|
+
|
|
108
|
+
iOS manual-push sketch (verified against advanced-configuration.md → "Step 3: Keeping
|
|
109
|
+
`subscriptionStatus` Up-To-Date"):
|
|
110
|
+
|
|
111
|
+
```swift
|
|
112
|
+
import SuperwallKit
|
|
113
|
+
import StoreKit
|
|
114
|
+
|
|
115
|
+
// Call once on launch, AND keep a `Transaction.updates` listener running so later
|
|
116
|
+
// renewals/expiries/refunds re-run this - status must be pushed on EVERY change.
|
|
117
|
+
func syncSubscriptionStatus() async {
|
|
118
|
+
var purchasedProductIds: Set<String> = []
|
|
119
|
+
for await verificationResult in Transaction.currentEntitlements {
|
|
120
|
+
if case .verified(let transaction) = verificationResult {
|
|
121
|
+
purchasedProductIds.insert(transaction.productID)
|
|
122
|
+
}
|
|
123
|
+
}
|
|
124
|
+
let entitlements = Superwall.shared.entitlements.byProductIds(purchasedProductIds)
|
|
125
|
+
await MainActor.run {
|
|
126
|
+
Superwall.shared.subscriptionStatus = entitlements.isEmpty ? .inactive : .active(entitlements)
|
|
127
|
+
}
|
|
128
|
+
}
|
|
129
|
+
```
|
|
130
|
+
|
|
131
|
+
Expo / React Native and Flutter don't assign `subscriptionStatus` directly - they call
|
|
132
|
+
`Superwall.shared.setSubscriptionStatus(...)` (RN uses `SubscriptionStatus.Active(entitlementIds)` /
|
|
133
|
+
`.Inactive()`). Confirm the exact shape per framework:
|
|
134
|
+
|
|
135
|
+
```bash
|
|
136
|
+
curl -sL https://superwall.com/docs/ios/quickstart/tracking-subscription-state.md
|
|
137
|
+
curl -sL https://superwall.com/docs/expo/quickstart/tracking-subscription-state.md
|
|
138
|
+
curl -sL https://superwall.com/docs/flutter/quickstart/tracking-subscription-state.md
|
|
139
|
+
```
|
|
140
|
+
|
|
141
|
+
### Mode C - PAYWALLS-ONLY, RevenueCat stays the purchase controller
|
|
142
|
+
|
|
143
|
+
Keep RevenueCat for purchases/receipts/webhooks; Superwall only shows paywalls. Implement a
|
|
144
|
+
`PurchaseController` that forwards buys to RC and mirror RC's `customerInfo` into
|
|
145
|
+
`Superwall.shared.subscriptionStatus` (§5). Use when RC's server-side entitlements, integrations, or
|
|
146
|
+
cross-platform/web receipts must stay authoritative.
|
|
147
|
+
|
|
148
|
+
```bash
|
|
149
|
+
curl -sL https://superwall.com/docs/ios/guides/using-revenuecat.md # swap ios → expo / flutter / android
|
|
150
|
+
```
|
|
151
|
+
|
|
152
|
+
Web-checkout variants: `.../guides/web-checkout/using-revenuecat` per framework.
|
|
153
|
+
|
|
154
|
+
_Pure observer_ (analytics-only, RC owns purchases AND paywalls): set
|
|
155
|
+
`options.shouldObservePurchases = true` on `SuperwallOptions`. Superwall records revenue but you
|
|
156
|
+
CANNOT call `Superwall.shared.purchase(...)`. `curl -sL https://superwall.com/docs/ios/guides/advanced/observer-mode.md`
|
|
157
|
+
|
|
158
|
+
## 3. Codebase inventory - grep these symbols
|
|
159
|
+
|
|
160
|
+
**iOS (Swift, `RevenueCat`):**
|
|
161
|
+
|
|
162
|
+
- Config: `Purchases.configure(withAPIKey:` , `Purchases.logLevel`, `Purchases.shared.delegate`, `PurchasesDelegate`
|
|
163
|
+
- Products/offerings: `Purchases.shared.offerings(`, `.getOfferings(`, `offering.availablePackages`, `package.storeProduct`
|
|
164
|
+
- Purchase/restore: `Purchases.shared.purchase(package:` , `.purchase(product:`, `.restorePurchases(`
|
|
165
|
+
- Entitlement checks (→ future gates): `customerInfo(`, `customerInfoStream`, `.entitlements.active[`, `.entitlements.activeInCurrentEnvironment`, `entitlement.isActive`
|
|
166
|
+
- Identity/attributes: `Purchases.shared.logIn(`, `.logOut(`, `.attribution`, `.setAttributes(`, `Purchases.shared.appUserID`
|
|
167
|
+
- **Presentation call sites** (RC paywalls / your own): `PaywallView`, `.presentPaywallIfNeeded`, `presentPaywall`, any place an offering is fetched then a sheet shown → each becomes a **placement**.
|
|
168
|
+
|
|
169
|
+
**React Native / Expo (`react-native-purchases`, `react-native-purchases-ui`):**
|
|
170
|
+
`Purchases.configure({apiKey})`, `Purchases.getOfferings()`, `Purchases.getProducts()`,
|
|
171
|
+
`Purchases.purchasePackage()`, `Purchases.purchaseStoreProduct()`, `Purchases.purchaseSubscriptionOption()`,
|
|
172
|
+
`Purchases.restorePurchases()`, `Purchases.getCustomerInfo()`, `Purchases.addCustomerInfoUpdateListener()`,
|
|
173
|
+
`customerInfo.entitlements.active`, `Purchases.logIn()/logOut()`, `RevenueCatUI.presentPaywall()`.
|
|
174
|
+
|
|
175
|
+
**Flutter (`purchases_flutter`, `purchases_ui_flutter`):**
|
|
176
|
+
`Purchases.configure(PurchasesConfiguration(...))`, `Purchases.getOfferings()`, `Purchases.getProducts()`,
|
|
177
|
+
`Purchases.purchasePackage()`, `Purchases.purchaseStoreProduct()`, `Purchases.purchase(PurchaseParams...)`,
|
|
178
|
+
`Purchases.restorePurchases()`, `Purchases.getCustomerInfo()`, `Purchases.addCustomerInfoUpdateListener()`,
|
|
179
|
+
`customerInfo.entitlements.active`, `Purchases.logIn()/logOut()`, `RevenueCatUI.presentPaywall()`.
|
|
180
|
+
|
|
181
|
+
Produce: list of product ids, entitlement ids, and one row per presentation call site → proposed `snake_case` placement.
|
|
182
|
+
|
|
183
|
+
**Beyond RC - sweep the whole billing surface (real apps carry layers):**
|
|
184
|
+
|
|
185
|
+
- Other purchase stacks: `SwiftyStoreKit`, `SKPaymentQueue`, `Transaction.updates`, `IAPManager`,
|
|
186
|
+
`StoreObserver`, Play `BillingClient` - each is a competing transaction finisher; plan removal or
|
|
187
|
+
explicit retirement for every one.
|
|
188
|
+
- Existing Superwall wrappers: grep `Superwall.configure`, `SWPaywallManager`/`*PaywallManager`
|
|
189
|
+
singletons - hybrid apps often already configure Superwall once; never add a second configure.
|
|
190
|
+
- ALL sign-out paths: logout screens, account-deletion flows, 401/session-expiry handlers - each
|
|
191
|
+
needs `Superwall.shared.reset()`.
|
|
192
|
+
- Purchase-callback side-effects: backend POSTs, analytics, attribution, navigation (see §5
|
|
193
|
+
"Side-effects").
|
|
194
|
+
|
|
195
|
+
## 4. Dashboard-side re-creation (CLI)
|
|
196
|
+
|
|
197
|
+
**Account gate first:** `superwall apps list --json` and confirm one app's `public_api_key` equals
|
|
198
|
+
the `pk_` in the code (or the bundle id matches). No match = the CLI session is on the WRONG
|
|
199
|
+
account: stop dashboard work, say so loudly in the summary/handback file, and have the user
|
|
200
|
+
`superwall login` with the owning account. Never create resources in an unrelated project; never
|
|
201
|
+
call the migration complete with dashboard work silently skipped.
|
|
202
|
+
|
|
203
|
+
For each entitlement and product found, use the project/app ids from the account gate:
|
|
204
|
+
|
|
205
|
+
```bash
|
|
206
|
+
superwall entitlements create pro --project <projectId> --json
|
|
207
|
+
superwall products create com.app.pro_monthly --name "Pro Monthly" --project <projectId> --json
|
|
208
|
+
superwall products create com.app.pro_yearly --name "Pro Yearly" --project <projectId> --json
|
|
209
|
+
```
|
|
210
|
+
|
|
211
|
+
Product ids MUST equal the existing App Store / Play SKUs (import via ASC connection instead of
|
|
212
|
+
manual create when possible - `superwall asc keys set --help`). Then one campaign with
|
|
213
|
+
a placement per call site:
|
|
214
|
+
|
|
215
|
+
```bash
|
|
216
|
+
superwall campaigns create "Main paywall" start_workout --project <projectId> --app <appId> --json
|
|
217
|
+
superwall campaigns placement <campaignId> unlock_export --project <projectId> --app <appId> --json
|
|
218
|
+
```
|
|
219
|
+
|
|
220
|
+
Verify with the same explicit ids: `superwall entitlements list --project <projectId> --json`,
|
|
221
|
+
`superwall products list --project <projectId> --json`, and `superwall campaigns list --project <projectId> --app <appId> --json`.
|
|
222
|
+
|
|
223
|
+
## 5. Code replacement
|
|
224
|
+
|
|
225
|
+
### FULL mode
|
|
226
|
+
|
|
227
|
+
- **Configure.** Replace `Purchases.configure(...)` with `Superwall.configure(apiKey: "…")`. No purchase controller.
|
|
228
|
+
- **Entitlement checks.** Replace RC reads:
|
|
229
|
+
```swift
|
|
230
|
+
// Before
|
|
231
|
+
let info = try? await Purchases.shared.customerInfo()
|
|
232
|
+
return info?.entitlements.active["pro"]?.isActive ?? false
|
|
233
|
+
// After
|
|
234
|
+
if Superwall.shared.subscriptionStatus.isActive { /* entitled */ }
|
|
235
|
+
// or, per-entitlement:
|
|
236
|
+
switch Superwall.shared.subscriptionStatus {
|
|
237
|
+
case .active(let entitlements): handler(true) // entitlements: Set<Entitlement>
|
|
238
|
+
case .inactive: handler(false)
|
|
239
|
+
case .unknown: handler(false)
|
|
240
|
+
}
|
|
241
|
+
```
|
|
242
|
+
- **Presentation → placement.** Replace "fetch offering + present paywall" with:
|
|
243
|
+
```swift
|
|
244
|
+
Superwall.shared.register(placement: "start_workout") {
|
|
245
|
+
navigation.startWorkout() // runs when entitled (gated) - see §6
|
|
246
|
+
}
|
|
247
|
+
```
|
|
248
|
+
RN: `Superwall.shared.register({ placement: "start_workout" }, () => {...})`.
|
|
249
|
+
Flutter: `Superwall.shared.registerPlacement("start_workout", feature: () {...})`.
|
|
250
|
+
- **Remove `PurchaseController`** if one existed:
|
|
251
|
+
```swift
|
|
252
|
+
// Before: Superwall.configure(apiKey:"…", purchaseController: RCPurchaseController())
|
|
253
|
+
// After: Superwall.configure(apiKey: "…")
|
|
254
|
+
```
|
|
255
|
+
- **Identity.** `Purchases.shared.logIn(id)` → `Superwall.shared.identify(userId: id)`; `logOut()` → `Superwall.shared.reset()`.
|
|
256
|
+
Then grep for sign-out paths logIn/logOut DIDN'T cover: account deletion, forced auth-failure
|
|
257
|
+
(401) logout, session expiry. Every one needs `reset()` - a missed path leaks the previous user's
|
|
258
|
+
identity and paywall assignments to the next login. `identify` must run at login AND app-launch
|
|
259
|
+
session-restore, BEFORE any placement can fire.
|
|
260
|
+
- **Attributes.** `Purchases.shared.setAttributes([...])` → `Superwall.shared.setUserAttributes([...])`. Call `identify` BEFORE `setUserAttributes`; `identify` is idempotent.
|
|
261
|
+
- Remove the RevenueCat dependency only after everything builds and is verified.
|
|
262
|
+
|
|
263
|
+
### Side-effects - reroute what lived inside RC callbacks (FULL mode, CRITICAL)
|
|
264
|
+
|
|
265
|
+
Real apps bury critical work inside `PurchaseController.purchase()` / RC delegate callbacks. A
|
|
266
|
+
mechanical swap deletes it and everything still compiles - then production breaks. Typical
|
|
267
|
+
casualties: a purchase callback that is the ONLY caller of a backend subscription-sync request
|
|
268
|
+
(the server route gating every premium feature), or the only place an attribution/analytics
|
|
269
|
+
trial-started event is tracked.
|
|
270
|
+
|
|
271
|
+
Before deleting the controller/delegates, list every statement inside purchase & restore success
|
|
272
|
+
paths and reroute each into a `SuperwallDelegate`:
|
|
273
|
+
|
|
274
|
+
```swift
|
|
275
|
+
class AppSuperwallDelegate: SuperwallDelegate {
|
|
276
|
+
func handleSuperwallEvent(withInfo info: SuperwallEventInfo) {
|
|
277
|
+
switch info.event {
|
|
278
|
+
case .transactionComplete(_, let product, _, _):
|
|
279
|
+
syncSubscriptionWithBackend() // backend gate stays alive
|
|
280
|
+
Analytics.trackPurchase(product.productIdentifier) // Singular/PostHog/TikTok/…
|
|
281
|
+
case .transactionRestore:
|
|
282
|
+
syncSubscriptionWithBackend()
|
|
283
|
+
default: break
|
|
284
|
+
}
|
|
285
|
+
}
|
|
286
|
+
}
|
|
287
|
+
// Superwall.shared.delegate = AppSuperwallDelegate() - retain it; set right after configure.
|
|
288
|
+
```
|
|
289
|
+
|
|
290
|
+
- **Backend-gated apps:** if the server checks its own subscription record before unlocking
|
|
291
|
+
features, a device-side purchase that never notifies the server = paying users locked out.
|
|
292
|
+
Keep the sync (delegate POST above) or move gating to Superwall entitlements - and VERIFY the
|
|
293
|
+
backend route accepts the new payload (legacy routes often expect provider-specific ids like an
|
|
294
|
+
RC app-user-id).
|
|
295
|
+
- **Analytics/attribution parity:** every event the old callbacks emitted (trial started, purchase,
|
|
296
|
+
restore) must fire from the delegate, or configure the equivalent dashboard integration
|
|
297
|
+
(Settings → Integrations) and verify events arrive before removing the client-side calls.
|
|
298
|
+
|
|
299
|
+
### PAYWALLS-ONLY mode - iOS `PurchaseController` (verbatim from docs)
|
|
300
|
+
|
|
301
|
+
```swift
|
|
302
|
+
import SuperwallKit
|
|
303
|
+
import RevenueCat
|
|
304
|
+
import StoreKit
|
|
305
|
+
|
|
306
|
+
final class RCPurchaseController: PurchaseController {
|
|
307
|
+
func syncSubscriptionStatus() {
|
|
308
|
+
assert(Purchases.isConfigured, "You must configure RevenueCat before calling this method.")
|
|
309
|
+
Task {
|
|
310
|
+
for await customerInfo in Purchases.shared.customerInfoStream {
|
|
311
|
+
let superwallEntitlements = customerInfo.entitlements.activeInCurrentEnvironment.keys.map {
|
|
312
|
+
Entitlement(id: $0)
|
|
313
|
+
}
|
|
314
|
+
await MainActor.run { [superwallEntitlements] in
|
|
315
|
+
Superwall.shared.subscriptionStatus = .active(Set(superwallEntitlements))
|
|
316
|
+
}
|
|
317
|
+
}
|
|
318
|
+
}
|
|
319
|
+
}
|
|
320
|
+
|
|
321
|
+
func purchase(product: SuperwallKit.StoreProduct) async -> PurchaseResult {
|
|
322
|
+
do {
|
|
323
|
+
guard let sk2Product = product.sk2Product else { throw PurchasingError.sk2ProductNotFound }
|
|
324
|
+
let storeProduct = RevenueCat.StoreProduct(sk2Product: sk2Product)
|
|
325
|
+
let result = try await Purchases.shared.purchase(product: storeProduct)
|
|
326
|
+
return result.userCancelled ? .cancelled : .purchased
|
|
327
|
+
} catch let error as ErrorCode {
|
|
328
|
+
return error == .paymentPendingError ? .pending : .failed(error)
|
|
329
|
+
} catch { return .failed(error) }
|
|
330
|
+
}
|
|
331
|
+
|
|
332
|
+
func restorePurchases() async -> RestorationResult {
|
|
333
|
+
do { _ = try await Purchases.shared.restorePurchases(); return .restored }
|
|
334
|
+
catch { return .failed(error) }
|
|
335
|
+
}
|
|
336
|
+
}
|
|
337
|
+
```
|
|
338
|
+
|
|
339
|
+
Wire it:
|
|
340
|
+
|
|
341
|
+
```swift
|
|
342
|
+
let purchaseController = RCPurchaseController()
|
|
343
|
+
Superwall.configure(apiKey: "pk_YOUR_PUBLIC_KEY", purchaseController: purchaseController)
|
|
344
|
+
purchaseController.syncSubscriptionStatus()
|
|
345
|
+
```
|
|
346
|
+
|
|
347
|
+
RN/Flutter: same shape via `addCustomerInfoUpdateListener` → `Superwall.shared.setSubscriptionStatus(SubscriptionStatus.Active(entitlementIds))` / `.Inactive()`; purchase via `Purchases.purchaseStoreProduct` / `Purchases.purchaseSubscriptionOption` (RN) or `Purchases.purchase(PurchaseParams.storeProduct(...))` (Flutter). Newer RN uses `CustomPurchaseControllerProvider` with `onPurchase`/`onPurchaseRestore` callbacks instead of passing a controller to `configure`.
|
|
348
|
+
|
|
349
|
+
## 6. Feature gating
|
|
350
|
+
|
|
351
|
+
Set per placement in the paywall editor (**General → Feature Gating**):
|
|
352
|
+
|
|
353
|
+
- **Non-gated**: feature closure runs on dismiss whether or not they paid.
|
|
354
|
+
- **Gated**: feature closure runs only if the user is (or becomes) entitled.
|
|
355
|
+
Peek without presenting: `Superwall.shared.getPresentationResult(forPlacement:)`.
|
|
356
|
+
`curl -sL https://superwall.com/docs/ios/quickstart/feature-gating.md`
|
|
357
|
+
|
|
358
|
+
## 7. Order of operations + safety
|
|
359
|
+
|
|
360
|
+
1. Re-create entitlements, products, campaign + placements in the dashboard (CLI). Import products from ASC/Play so ids match.
|
|
361
|
+
2. **Rebuild** paywalls (superwall framework or dashboard editor) and attach products (hand-back to user - designs do not import).
|
|
362
|
+
3. Add Superwall SDK alongside RC (don't rip RC yet). Configure it.
|
|
363
|
+
4. Replace presentation call sites with `register(placement:)`; replace entitlement reads with `subscriptionStatus`.
|
|
364
|
+
5. Build, run, present each placement; **Restore Purchases** as an existing subscriber and confirm `subscriptionStatus.isActive`.
|
|
365
|
+
6. FULL: remove `PurchaseController` + the RevenueCat dependency. PAYWALLS-ONLY: keep RC + controller.
|
|
366
|
+
7. Never delete RC dashboard/webhook config until verified in production.
|
|
367
|
+
|
|
368
|
+
Existing subscribers keep access even without a server-side data move - Superwall reads status from
|
|
369
|
+
the device's App Store / Play records after **Restore Purchases**. To port subscription history and
|
|
370
|
+
entitlement state server-side, follow the RevenueCat migration guide (§9) for the current process.
|
|
371
|
+
|
|
372
|
+
## 8. Pitfalls
|
|
373
|
+
|
|
374
|
+
- **Silent "everyone sees a paywall" bug (Mode B).** If you removed RC and kept the app's own
|
|
375
|
+
purchase flow (custom UI / direct StoreKit / Play Billing) but never told Superwall about
|
|
376
|
+
subscription state, Superwall treats every user as `.unknown`/`.inactive` and shows paywalls to
|
|
377
|
+
paying users. Any purchase happening outside Superwall REQUIRES a `PurchaseController`, observer
|
|
378
|
+
mode, or a manual `subscriptionStatus` set (§2 Mode B).
|
|
379
|
+
- **Double-charge / dueling finishers.** In PAYWALLS-ONLY, only ONE SDK may finish transactions. Let RC own purchasing via the controller; do NOT also call `Superwall.shared.purchase`. In FULL, remove RC's purchase paths entirely so two SDKs don't both react to StoreKit.
|
|
380
|
+
- **StoreKit listener conflicts.** Two SDKs observing StoreKit transactions cause duplicate grants/races. Pick one owner.
|
|
381
|
+
- **Observer-mode flag.** `shouldObservePurchases = true` disables `Superwall.shared.purchase`. Only set it in observer (analytics-only) mode, never in FULL.
|
|
382
|
+
- **Entitlement id mismatch.** Superwall entitlement ids must exactly match the RC entitlement keys you mirror (`pro` ≠ `Pro`).
|
|
383
|
+
- **Cache during switchover.** Right after swapping SDKs, status may read `.unknown`/`.inactive` until the first `customerInfoStream`/StoreKit sync - prompt Restore Purchases if a known subscriber looks free.
|
|
384
|
+
- **SK1 vs SK2.** The iOS controller expects a SK2 product (`product.sk2Product`); don't force Superwall to StoreKit 1 via `SuperwallOption`, or `purchase(product:)` gets no SK2 product.
|
|
385
|
+
- **identify order.** Call `identify` before `setUserAttributes`, or attributes attach to an anonymous user.
|
|
386
|
+
- **Deleted side-effects.** Removing a `PurchaseController` deletes everything inside it - backend
|
|
387
|
+
subscription sync, analytics, attribution. Builds stay green; production breaks. Reroute via
|
|
388
|
+
`SuperwallDelegate` FIRST (§5 "Side-effects").
|
|
389
|
+
- **Identity leakage.** No `reset()` on logout/account-deletion/401 paths → next user inherits the
|
|
390
|
+
previous user's identity and sticky paywall assignments.
|
|
391
|
+
- **Stranded navigation.** `register` without a feature closure on a gating placement → holdout /
|
|
392
|
+
skipped users tap the button and nothing happens. Gate navigation IN the closure.
|
|
393
|
+
- **Duplicate configure.** Hybrid apps often already call `configure` in a wrapper manager; adding
|
|
394
|
+
another in AppDelegate double-configures.
|
|
395
|
+
|
|
396
|
+
## 9. Deeper docs (fetch live)
|
|
397
|
+
|
|
398
|
+
```bash
|
|
399
|
+
curl -sL https://superwall.com/docs/dashboard/guides/migrating-from-revenuecat-to-superwall.md # migration guide
|
|
400
|
+
curl -sL https://superwall.com/docs/ios/guides/using-revenuecat.md # + expo/flutter/android
|
|
401
|
+
curl -sL https://superwall.com/docs/ios/guides/advanced/observer-mode.md
|
|
402
|
+
curl -sL https://superwall.com/docs/ios/quickstart/tracking-subscription-state.md
|
|
403
|
+
curl -sL https://superwall.com/docs/support/faq/how-to-migrate-from-another-provider-to-superwall.md
|
|
404
|
+
curl -sL https://superwall.com/docs/llms.txt # index (per-framework: /ios /expo /react-native /flutter llms.txt)
|
|
405
|
+
```
|
|
406
|
+
|
|
407
|
+
- register(): https://superwall.com/docs/ios/sdk-reference/register · identify(): .../identify · setUserAttributes(): .../setUserAttributes
|
|
408
|
+
|
|
409
|
+
`PurchasingError` enum (referenced by the iOS controller) - define alongside it:
|
|
410
|
+
|
|
411
|
+
```swift
|
|
412
|
+
enum PurchasingError: LocalizedError { case sk2ProductNotFound
|
|
413
|
+
var errorDescription: String? { "Superwall didn't pass a StoreKit 2 product to purchase." } }
|
|
414
|
+
```
|