@superwall/cli 2.0.0 → 2.1.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +3 -2
- package/dist/{apple-CkKlHBZ9.js → apple-BHbX0jbn.js} +13 -13
- package/dist/auth.d.ts +1 -1
- package/dist/auth.js +3 -3
- package/dist/{billing-XCZU_T46.js → billing-4zhIBFRQ.js} +3 -3
- package/dist/{bind-drne__Ys.js → bind-CHLHmxgA.js} +4 -4
- package/dist/{build-Gpdq5QXP.js → build-5PQeSnNN.js} +6 -6
- package/dist/{client-DP6Rc0t_.js → client-BIvOmWPC.js} +7 -3
- package/dist/{create-BBrtgUgS.js → create-BSNIFsnN.js} +6 -6
- package/dist/{create-Cwc3SRWJ.js → create-VK-pNfN7.js} +23 -23
- package/dist/create-oj3zXvHZ.js +19 -0
- package/dist/{doctor-C9ldpPFC.js → doctor-9JS96QkX.js} +6 -6
- package/dist/{drivers-DNrx4LWA.js → drivers-BamBJ10Y.js} +3 -3
- package/dist/entry.js +20 -21
- package/dist/{environment-DF1qKlny.js → environment-eV7LEnSN.js} +15 -2
- package/dist/{existing-78LWSsqS.js → existing-C8dSYHGk.js} +2 -2
- package/dist/{held-Cy8Wl4D1.js → held-BMisHn8F.js} +6 -6
- package/dist/held-DeJW2gUk.js +16 -0
- package/dist/{integrate-DcJhpXy8.js → integrate-VWtTNPCr.js} +22 -22
- package/dist/login-2JHCG6c1.js +16 -0
- package/dist/{login-D0lh3_JI.js → login-BimbukE5.js} +5 -5
- package/dist/{login-B2TsCE2H.js → login-BmwG14LC.js} +1 -1
- package/dist/{lookup-D-nmmAbw.js → lookup-k9EeOiZr.js} +2 -2
- package/dist/{migrate-Cfec564E.js → migrate-C86h6jeF.js} +22 -22
- package/dist/{notification-url-YDbq6FMA.js → notification-url-BVaTgWZ5.js} +2 -2
- package/dist/{open-Ba2vBl1_.js → open-0tDCQOXC.js} +10 -10
- package/dist/{org-D0g_q3mv.js → org-DUwdrKPV.js} +2 -2
- package/dist/{paths-DxSLdpOI.js → paths-BCbjCLP5.js} +1 -1
- package/dist/{playbook-DIeb7hne.js → playbook-oov9yV0q.js} +10 -10
- package/dist/{promote-COD4fYdz.js → promote-DPGPamkE.js} +16 -16
- package/dist/push-Chp21y3a.js +22 -0
- package/dist/{push-CncywhkQ.js → push-Cz4lJ8Qd.js} +27 -14
- package/dist/{registry-DSrosOYs.js → registry-CTczUigi.js} +525 -179
- package/dist/{resources-Dqr01Dep.js → resources-B1qKDVXd.js} +18 -6
- package/dist/{run-C9qg_QlC.js → run-DTPsVmFw.js} +2 -2
- package/dist/scan-B1SkkUi7.js +4 -0
- package/dist/{scan-DLrsrFS9.js → scan-Bb48xZqB.js} +1 -1
- package/dist/{scope-V336uz8j.js → scope-B6UYGuwn.js} +4 -4
- package/dist/{selection-Rdw-ZUoG.js → selection-BbNk9r1q.js} +10 -4
- package/dist/server-CwrZ-I1r.js +22 -0
- package/dist/{server-D0tGG8C4.js → server-EYBMKAG1.js} +10 -8
- package/dist/{session-D_nEWKXT.js → session-Crg9X-FI.js} +41 -13
- package/dist/session-DItGa4z0.js +6 -0
- package/dist/{session-CFAmMhem.js → session-xG9E8J2N.js} +1 -1
- package/dist/skills/superwall-framework/SKILL.md +43 -7
- package/dist/skills/superwall-framework/references/cli.md +1 -0
- package/dist/skills/superwall-framework/references/examples.md +1 -0
- package/dist/skills/superwall-framework/references/layout.md +34 -1
- package/dist/skills/superwall-framework/references/migrate-from-editor.md +16 -3
- package/dist/{skills-BvFOa4y6.js → skills-BdMKE2uO.js} +5 -4
- package/dist/{skills-DMG4bpKk.js → skills-Dg3k6TRC.js} +8 -8
- package/dist/{spinner-CneRK5rk.js → spinner-Ba3XhlMb.js} +3 -3
- package/dist/{storage-s2Dnz-yl.js → storage-DIkYajce.js} +1 -1
- package/dist/{storekit-yY_kS2iR.js → storekit-C2UzIIMs.js} +3 -3
- package/dist/storekit-DHNxDDpA.js +16 -0
- package/dist/{telemetry-DtG92m5O.js → telemetry-CVP8O6Y3.js} +1 -1
- package/dist/{token-DzRh7dI1.js → token-IWv2httm.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 +4 -2
- package/dist/tools.js +561 -161
- package/dist/{upgrade-Bt4Ouw1y.js → upgrade-1t3aQUxh.js} +1 -1
- package/dist/{upgrade-Cqy5orjb.js → upgrade-DLf0LJDh.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,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
|
+
```
|
|
@@ -0,0 +1,175 @@
|
|
|
1
|
+
# Superwall placements - Android / Kotlin
|
|
2
|
+
|
|
3
|
+
> Read `strategy.md` (beside this file) first for _where_ placements go and _why_ (the
|
|
4
|
+
> core set, app-type playbook, audit method, gate depth). This file is the Android API.
|
|
5
|
+
|
|
6
|
+
## API
|
|
7
|
+
|
|
8
|
+
```kotlin
|
|
9
|
+
import com.superwall.sdk.Superwall
|
|
10
|
+
|
|
11
|
+
// With gated feature (the common form)
|
|
12
|
+
fun Superwall.register(
|
|
13
|
+
placement: String,
|
|
14
|
+
params: Map<String, Any>? = null,
|
|
15
|
+
handler: PaywallPresentationHandler? = null,
|
|
16
|
+
feature: () -> Unit,
|
|
17
|
+
)
|
|
18
|
+
|
|
19
|
+
// Fire-and-forget (no feature to gate)
|
|
20
|
+
fun Superwall.register(
|
|
21
|
+
placement: String,
|
|
22
|
+
params: Map<String, Any>? = null,
|
|
23
|
+
handler: PaywallPresentationHandler? = null,
|
|
24
|
+
)
|
|
25
|
+
```
|
|
26
|
+
|
|
27
|
+
Called on the shared instance: `Superwall.instance.register(...)`. Not a
|
|
28
|
+
suspend function - no coroutine needed. `params` values are available in
|
|
29
|
+
campaign audience rules; keys starting with `$` are reserved and dropped, and
|
|
30
|
+
arrays or nested maps are ignored.
|
|
31
|
+
|
|
32
|
+
### Gated feature
|
|
33
|
+
|
|
34
|
+
```kotlin
|
|
35
|
+
Superwall.instance.register("unlock_export") {
|
|
36
|
+
// Runs only when access is granted (see semantics below).
|
|
37
|
+
exportDocument()
|
|
38
|
+
}
|
|
39
|
+
```
|
|
40
|
+
|
|
41
|
+
### Fire-and-forget (e.g. onboarding end, an upsell surface)
|
|
42
|
+
|
|
43
|
+
```kotlin
|
|
44
|
+
Superwall.instance.register("onboarding_complete")
|
|
45
|
+
```
|
|
46
|
+
|
|
47
|
+
### Passing params for audience targeting
|
|
48
|
+
|
|
49
|
+
```kotlin
|
|
50
|
+
Superwall.instance.register(
|
|
51
|
+
placement = "unlock_export",
|
|
52
|
+
params = mapOf("source" to "editor_toolbar", "doc_count" to documents.size),
|
|
53
|
+
) {
|
|
54
|
+
exportDocument()
|
|
55
|
+
}
|
|
56
|
+
```
|
|
57
|
+
|
|
58
|
+
## Feature-gating semantics
|
|
59
|
+
|
|
60
|
+
The `feature` lambda is your gate. When it runs depends on the paywall's
|
|
61
|
+
**Feature Gating** setting (paywall editor → General → Feature Gating):
|
|
62
|
+
|
|
63
|
+
| Situation | Does `feature` run? |
|
|
64
|
+
| ---------------------------------------------------- | ------------------------------------------------------ |
|
|
65
|
+
| No campaign matches the placement | Yes, immediately (no network, no paywall) |
|
|
66
|
+
| User already subscribed / entitled | Yes, immediately, no paywall |
|
|
67
|
+
| Holdout group or no audience match | Yes, immediately (runs per current subscription state) |
|
|
68
|
+
| Paywall shown, **Non-Gated**, dismissed | Yes - access granted whether or not they paid |
|
|
69
|
+
| Paywall shown, **Gated**, dismissed without purchase | No - feature blocked |
|
|
70
|
+
| Paywall shown, user purchases | Yes, after the transaction completes |
|
|
71
|
+
|
|
72
|
+
So: **Gated** = paid-only feature; **Non-Gated** = show the paywall but let them
|
|
73
|
+
through either way (soft paywall / upsell). This is toggled in the dashboard, not
|
|
74
|
+
in code - the same `register` call works for both.
|
|
75
|
+
|
|
76
|
+
## Presentation handler (optional lifecycle observation)
|
|
77
|
+
|
|
78
|
+
```kotlin
|
|
79
|
+
val handler = PaywallPresentationHandler()
|
|
80
|
+
handler.onPresent { paywallInfo -> Log.d("SW", "presented ${paywallInfo.name}") }
|
|
81
|
+
handler.onDismiss { paywallInfo, result -> Log.d("SW", "dismissed $result") }
|
|
82
|
+
handler.onError { error -> Log.e("SW", "error", error) }
|
|
83
|
+
handler.onSkip { reason -> Log.d("SW", "skipped $reason") } // holdout, no audience match, placement not found
|
|
84
|
+
|
|
85
|
+
Superwall.instance.register("unlock_export", handler = handler) {
|
|
86
|
+
exportDocument()
|
|
87
|
+
}
|
|
88
|
+
```
|
|
89
|
+
|
|
90
|
+
Use the handler for analytics/UI reactions only. Do **not** move the gated work
|
|
91
|
+
into `onDismiss` - the `feature` lambda already handles gating correctly. Fetch
|
|
92
|
+
the page for the exact `onSkip` reason types:
|
|
93
|
+
`curl -sL https://superwall.com/docs/android/guides/advanced/using-the-presentation-handler.md`
|
|
94
|
+
|
|
95
|
+
## Where to place - one realistic gate
|
|
96
|
+
|
|
97
|
+
Compose button:
|
|
98
|
+
|
|
99
|
+
```kotlin
|
|
100
|
+
Button(onClick = {
|
|
101
|
+
Superwall.instance.register("unlock_export") {
|
|
102
|
+
exporter.exportPdf(document)
|
|
103
|
+
}
|
|
104
|
+
}) { Text("Export as PDF") }
|
|
105
|
+
```
|
|
106
|
+
|
|
107
|
+
Views:
|
|
108
|
+
|
|
109
|
+
```kotlin
|
|
110
|
+
binding.exportButton.setOnClickListener {
|
|
111
|
+
Superwall.instance.register("unlock_export") {
|
|
112
|
+
exporter.exportPdf(document)
|
|
113
|
+
}
|
|
114
|
+
}
|
|
115
|
+
```
|
|
116
|
+
|
|
117
|
+
Limit-reached gate:
|
|
118
|
+
|
|
119
|
+
```kotlin
|
|
120
|
+
fun addProject() {
|
|
121
|
+
if (projects.size < freeLimit) return createProject()
|
|
122
|
+
Superwall.instance.register("project_limit_reached") {
|
|
123
|
+
createProject()
|
|
124
|
+
}
|
|
125
|
+
}
|
|
126
|
+
```
|
|
127
|
+
|
|
128
|
+
## Audit checklist
|
|
129
|
+
|
|
130
|
+
- Find every call: `grep -rn "register(" app/src/main` (also any wrapper the
|
|
131
|
+
app's analytics layer exposes).
|
|
132
|
+
- When a placement intentionally controls access, the paywalled work is **inside**
|
|
133
|
+
the `feature` lambda rather than after the call.
|
|
134
|
+
- No outer subscription branch should prevent an intentionally remote gate from
|
|
135
|
+
using its feature lambda. Subscription reads elsewhere are valid and require
|
|
136
|
+
context.
|
|
137
|
+
- Names are stable and match presenting campaigns exactly; preserve intentional
|
|
138
|
+
analytics taxonomies and never rename for style alone.
|
|
139
|
+
- Cross-check placements expected to present now with `superwall campaigns list
|
|
140
|
+
--project <id> --app <id> --json`; analytics-only, future, and paused placements may be unrouted.
|
|
141
|
+
- Obvious premium entry points (upgrade buttons, gated exports, quota limits,
|
|
142
|
+
onboarding end) that have **no** placement.
|
|
143
|
+
|
|
144
|
+
## Dashboard routing
|
|
145
|
+
|
|
146
|
+
A placement is inert without a campaign:
|
|
147
|
+
|
|
148
|
+
```bash
|
|
149
|
+
superwall campaigns list --project <id> --app <id> --json
|
|
150
|
+
superwall campaigns create "Editor upgrade paywall" unlock_export --project <id> --app <id> --json
|
|
151
|
+
superwall campaigns placement <campaignId> another_placement --project <id> --app <id> --json
|
|
152
|
+
```
|
|
153
|
+
|
|
154
|
+
## Pitfalls
|
|
155
|
+
|
|
156
|
+
- **Registering during composition.** Never call `register` in a composable's
|
|
157
|
+
body - it re-fires on every recomposition. Register from `onClick`, a
|
|
158
|
+
`LaunchedEffect(Unit)` for screen-entry placements, or a ViewModel event.
|
|
159
|
+
- **Registering before `configure`.** Calls before `Superwall.configure(...)` in
|
|
160
|
+
`Application.onCreate()` are dropped. Configure first.
|
|
161
|
+
- **No Activity in the foreground.** A paywall is an Activity; registering from
|
|
162
|
+
a background service or during process start, before any Activity is resumed,
|
|
163
|
+
cannot present. Register from UI code.
|
|
164
|
+
- **Conflicting gates.** An outer entitlement check is a problem only when the same
|
|
165
|
+
action is intentionally controlled by the placement's feature lambda.
|
|
166
|
+
- **Waiting on the lambda to fire.** The `feature` lambda may run later (after a
|
|
167
|
+
purchase). Don't assume it runs synchronously before the next line.
|
|
168
|
+
|
|
169
|
+
## Deeper docs
|
|
170
|
+
|
|
171
|
+
- Index: https://superwall.com/docs/android/llms.txt
|
|
172
|
+
- register: https://superwall.com/docs/android/sdk-reference/register
|
|
173
|
+
- Feature gating: https://superwall.com/docs/android/quickstart/feature-gating
|
|
174
|
+
- Presentation handler: https://superwall.com/docs/android/guides/advanced/using-the-presentation-handler
|
|
175
|
+
- Deep links: https://superwall.com/docs/android/guides/handling-deep-links
|