@superwall/cli 1.4.0 → 1.6.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/README.md +21 -5
- package/dist/{actions-EfP8phmb.js → actions-Dt35nIi8.js} +3 -2
- package/dist/{api-CEwXCCoC.js → api-BOR-uXZe.js} +9 -9
- package/dist/{app-D8mEVlQo.js → app-BU27SLPX.js} +9 -9
- package/dist/{asa-BFWehnTA.js → asa-2ykGnjaV.js} +11 -11
- package/dist/{asc-DJqQmtmR.js → asc-r3xmFT0L.js} +14 -14
- package/dist/{auth-CT2DWX8r.js → auth-BWZfguI8.js} +9 -9
- package/dist/auth.js +2 -2
- package/dist/{billing-BzEnVPD2.js → billing-BsQgXXYh.js} +1 -1
- package/dist/{bind-BZxVyt9P.js → bind-BSTAinn6.js} +5 -4
- package/dist/{command-DP96_gmP.js → command-DMoMn7uc.js} +39 -16
- package/dist/{create-Q8TqqjZt.js → create-CSo6XjSm.js} +118 -91
- package/dist/dev-B0MF6z3L.js +21 -0
- package/dist/{dev-DlCcwFu5.js → dev-CuXa3J4Z.js} +29 -24
- package/dist/{doctor-CJsjHpCZ.js → doctor-DXJaDqsx.js} +10 -10
- package/dist/{drivers-UT36AnOw.js → drivers-Cr252DOJ.js} +3 -3
- package/dist/entry.js +84 -50
- package/dist/{existing-Cak1WxWB.js → existing-Ckx_g7Be.js} +6 -3
- package/dist/{feedback-DDRzoqPx.js → feedback-Dt5yebMS.js} +6 -6
- package/dist/{hosted-CEH78QVn.js → hosted-Cjekn8oJ.js} +2 -2
- package/dist/{integrate-D8jyhDzk.js → integrate-DVqhvPVq.js} +25 -66
- package/dist/{login-kneYhhk0.js → login-Bjj8QvIN.js} +6 -6
- package/dist/migrate-qmvOtp3l.js +283 -0
- package/dist/open-studio-CpHqjovS.js +1299 -0
- package/dist/{org-Cg25bcsj.js → org-CV8c849b.js} +3 -3
- package/dist/{output-csAtR6kJ.js → output-CiELrN8w.js} +15 -2
- package/dist/{pipeline-DAeI9tHs.js → pipeline-DSCHL9KA.js} +482 -9
- package/dist/{print-skill-BHVPP9cX.js → print-skill-CaHRJ8xW.js} +7 -7
- package/dist/{promote-Boek5K2d.js → promote-UMTh8Q33.js} +17 -18
- package/dist/publish-DWX8S9yZ.js +34 -0
- package/dist/push-Dox4_5Dq.js +34 -0
- package/dist/{query-B8G6T8Ba.js → query-CnSsDZ7Q.js} +10 -10
- package/dist/reports-C0xHCLnt.js +27 -0
- package/dist/{resource-DjsWVka-.js → resource-5bgyyL9B.js} +15 -15
- package/dist/{resources-s64mBHaC.js → resources-Bf9O1JNM.js} +28 -2
- package/dist/{run-BtcQJCP8.js → run-BVeZWbXx.js} +39 -22
- package/dist/{scan-DJixvuHn.js → scan-CAObNRgc.js} +44 -4
- package/dist/skills/superwall/SKILL.md +146 -0
- package/dist/skills/superwall/references/api.md +275 -0
- package/dist/skills/superwall/references/asa.md +160 -0
- package/dist/skills/superwall/references/asc.md +96 -0
- package/dist/skills/superwall/references/dashboard-links.md +57 -0
- package/dist/skills/superwall/references/data-analytics.md +893 -0
- package/dist/skills/superwall/references/docs.md +51 -0
- package/dist/skills/superwall/references/sdk-integration.md +105 -0
- package/dist/skills/superwall/references/sdk-source.md +18 -0
- package/{skills/superwall-dashboard/SKILL.md → dist/skills/superwall/workflows/dashboard/playbook.md} +3 -9
- package/{skills/superwall-dashboard/references → dist/skills/superwall/workflows/dashboard}/setup.md +1 -3
- package/dist/skills/superwall/workflows/integrate/android.md +292 -0
- package/{skills/superwall-integrate/SKILL.md → dist/skills/superwall/workflows/integrate/playbook.md} +16 -11
- package/{skills/superwall-migrate/references → dist/skills/superwall/workflows/migrate}/adapty.md +4 -4
- package/{skills/superwall-migrate/SKILL.md → dist/skills/superwall/workflows/migrate/playbook.md} +4 -10
- package/{skills/superwall-migrate/references → dist/skills/superwall/workflows/migrate}/qonversion.md +4 -4
- package/{skills/superwall-migrate/references → dist/skills/superwall/workflows/migrate}/revenuecat.md +4 -4
- package/dist/skills/superwall/workflows/placements/android.md +175 -0
- package/{skills/superwall-placements/references → dist/skills/superwall/workflows/placements}/expo.md +1 -1
- package/{skills/superwall-placements/references → dist/skills/superwall/workflows/placements}/flutter.md +1 -1
- package/{skills/superwall-placements/references → dist/skills/superwall/workflows/placements}/ios.md +1 -1
- package/{skills/superwall-placements/SKILL.md → dist/skills/superwall/workflows/placements/playbook.md} +6 -10
- package/{skills/superwall-placements/references → dist/skills/superwall/workflows/placements}/react-native.md +2 -2
- package/{skills/superwall-placements/references → dist/skills/superwall/workflows/placements}/strategy.md +4 -3
- package/dist/skills/superwall/workflows/review/android.md +120 -0
- package/{skills/superwall-review/references → dist/skills/superwall/workflows/review}/expo.md +1 -1
- package/{skills/superwall-review/references → dist/skills/superwall/workflows/review}/flutter.md +1 -1
- package/{skills/superwall-review/references → dist/skills/superwall/workflows/review}/ios.md +1 -1
- package/{skills/superwall-review/SKILL.md → dist/skills/superwall/workflows/review/playbook.md} +2 -7
- package/{skills/superwall-review/references → dist/skills/superwall/workflows/review}/react-native.md +1 -1
- package/dist/skills/superwall-framework/SKILL.md +253 -0
- package/dist/skills/superwall-framework/references/cli.md +340 -0
- package/dist/skills/superwall-framework/references/examples.md +123 -0
- package/dist/skills/superwall-framework/references/layout.md +295 -0
- package/dist/skills/superwall-framework/references/migrate-from-editor.md +208 -0
- package/dist/skills/superwall-framework/references/migrate-from-native.md +193 -0
- package/dist/skills/superwall-framework/references/mobile-design.md +371 -0
- package/dist/skills/superwall-framework/references/native/android.md +83 -0
- package/dist/skills/superwall-framework/references/native/flutter.md +65 -0
- package/dist/skills/superwall-framework/references/native/ios.md +77 -0
- package/dist/skills/superwall-framework/references/native/react-native.md +67 -0
- package/dist/skills/superwall-framework/references/responsive.md +162 -0
- package/dist/{skills-CRG1xk0G.js → skills-Cu41i-Az.js} +12 -12
- package/dist/{skills-CODut1Hn.js → skills-grTDuHlc.js} +134 -36
- package/dist/{spinner-B9dT3DBY.js → spinner-DFctF_Jw.js} +1 -1
- package/dist/{telemetry-BtkMdT-5.js → telemetry-BuCbmoux.js} +3 -3
- package/dist/{token-hM7V1KMG.js → token-mju3Q-vc.js} +3 -3
- package/dist/{ui-Lqt_zFOr.js → ui-4gLyfrgl.js} +76 -46
- package/dist/{update-CeylIjx5.js → update-DnGfpCD7.js} +2 -2
- package/dist/{upgrade-DRqUfCBT.js → upgrade-PMoj3yqJ.js} +6 -6
- package/package.json +8 -7
- package/prompts/actions/paywall-migrate.xml +24 -0
- package/prompts/actions/screen-migrate.xml +26 -0
- package/dist/git-ZwA3Mx8m.js +0 -433
- package/dist/migrate-D_x1oyTk.js +0 -114
- package/dist/publish-C-zEUnO9.js +0 -35
- package/dist/push-DUDQG-EO.js +0 -35
- package/skills/README.md +0 -118
- /package/dist/{api-output-D9ggXQIr.js → api-output-CEhN-U_N.js} +0 -0
- /package/dist/{asc-products-C6MvSy8H.js → asc-products-1e1DoGeL.js} +0 -0
- /package/dist/{params-B1zeElGa.js → params-BxgTuCzr.js} +0 -0
- /package/{skills/superwall-integrate/references → dist/skills/superwall/workflows/integrate}/expo.md +0 -0
- /package/{skills/superwall-integrate/references → dist/skills/superwall/workflows/integrate}/flutter.md +0 -0
- /package/{skills/superwall-integrate/references → dist/skills/superwall/workflows/integrate}/ios.md +0 -0
- /package/{skills/superwall-integrate/references → dist/skills/superwall/workflows/integrate}/react-native.md +0 -0
- /package/dist/{storekit-DPonXSwe.js → storekit-Dlpbq5Wv.js} +0 -0
|
@@ -3,7 +3,7 @@
|
|
|
3
3
|
Definitive playbook. Read fully before editing. Superwall has no Qonversion-specific
|
|
4
4
|
"using-qonversion" guide, so PAYWALLS-ONLY mode uses the **generic** `PurchaseController`
|
|
5
5
|
(`/docs/ios/guides/advanced-configuration`) - mirror the RevenueCat controller shape in
|
|
6
|
-
`
|
|
6
|
+
`revenuecat.md` (beside this file), swapping RC calls for Qonversion calls.
|
|
7
7
|
|
|
8
8
|
## Scope & checklist
|
|
9
9
|
|
|
@@ -15,11 +15,11 @@ This migrates the **SDK integration**, not the whole product. Checklist:
|
|
|
15
15
|
- [ ] Swap SDK calls (init→configure, entitlement reads, present → placement, identify) (§5)
|
|
16
16
|
- [ ] Build + verify each placement; Restore Purchases as an existing subscriber (§7)
|
|
17
17
|
- [ ] FULL only: remove Qonversion dependency once verified
|
|
18
|
-
- [ ] Hand back to user: **rebuild paywalls** (
|
|
18
|
+
- [ ] Hand back to user: **rebuild paywalls** (dashboard editor), attach products, connect ASC/Play
|
|
19
19
|
|
|
20
20
|
> **Important - what does NOT migrate:**
|
|
21
21
|
>
|
|
22
|
-
> - **Qonversion paywall UI** cannot be imported - paywalls are **rebuilt**
|
|
22
|
+
> - **Qonversion paywall UI** cannot be imported - paywalls are **rebuilt** in the dashboard editor.
|
|
23
23
|
> - **Historical analytics / attribution** stays in Qonversion.
|
|
24
24
|
> - **Subscriber base:** there is currently no server-side subscriber migration from Qonversion.
|
|
25
25
|
> Existing subscribers keep access because their purchases live with the store (StoreKit /
|
|
@@ -189,7 +189,7 @@ regardless) vs gated (only when entitled). Peek: `Superwall.shared.getPresentati
|
|
|
189
189
|
## 7. Order of operations + safety
|
|
190
190
|
|
|
191
191
|
1. Re-create entitlements/products/campaign+placements (CLI); import products from ASC/Play so ids match.
|
|
192
|
-
2. **Rebuild** paywalls (
|
|
192
|
+
2. **Rebuild** paywalls (dashboard editor), attach products (hand-back to user - designs do not import).
|
|
193
193
|
3. Add Superwall SDK alongside Qonversion; configure it.
|
|
194
194
|
4. Replace offering-fetch/present call sites with `register(placement:)`; replace `checkEntitlements` reads with `subscriptionStatus`.
|
|
195
195
|
5. Build, present each placement, Restore Purchases as an existing subscriber, confirm `subscriptionStatus.isActive`.
|
|
@@ -26,11 +26,11 @@ This migrates the **SDK integration**, not the whole product. Checklist:
|
|
|
26
26
|
`pk_` key / bundle id BEFORE any create; wrong account → stop dashboard work loudly (§4)
|
|
27
27
|
- [ ] Build + verify each placement; Restore Purchases as an existing subscriber (§7)
|
|
28
28
|
- [ ] FULL only: remove RC dependency once verified
|
|
29
|
-
- [ ] Hand back to user: **rebuild paywalls** (
|
|
29
|
+
- [ ] Hand back to user: **rebuild paywalls** (dashboard editor), attach products, connect ASC/Play
|
|
30
30
|
|
|
31
31
|
> **Important - what does and does NOT migrate:**
|
|
32
32
|
>
|
|
33
|
-
> - **RC paywall designs** cannot be imported - they are **rebuilt**
|
|
33
|
+
> - **RC paywall designs** cannot be imported - they are **rebuilt** in the dashboard editor.
|
|
34
34
|
> - **Historical analytics / attribution** stays in RevenueCat.
|
|
35
35
|
> - **Subscriber base:** Superwall provides server-side RevenueCat migration tooling that ports
|
|
36
36
|
> subscription history and entitlement state - fetch the migration guide (Docs access below)
|
|
@@ -53,7 +53,7 @@ curl -sL https://www.revenuecat.com/docs/llms.txt
|
|
|
53
53
|
| RevenueCat | Superwall | Notes |
|
|
54
54
|
| ------------------------------------------------ | ---------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------- |
|
|
55
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
|
|
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 the editor). |
|
|
57
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
58
|
| Entitlement (e.g. `pro`) | **Entitlement** (re-created) | 1:1. Recreate each RC entitlement id as a Superwall entitlement. |
|
|
59
59
|
| `customerInfo.entitlements.active` | `Superwall.shared.subscriptionStatus` (`.active(Set<Entitlement>)` / `.inactive` / `.unknown`) | Status is device-derived in FULL mode. |
|
|
@@ -358,7 +358,7 @@ Set per placement in the paywall editor (**General → Feature Gating**):
|
|
|
358
358
|
## 7. Order of operations + safety
|
|
359
359
|
|
|
360
360
|
1. Re-create entitlements, products, campaign + placements in the dashboard (CLI). Import products from ASC/Play so ids match.
|
|
361
|
-
2. **Rebuild** paywalls (
|
|
361
|
+
2. **Rebuild** paywalls (dashboard editor) and attach products (hand-back to user - designs do not import).
|
|
362
362
|
3. Add Superwall SDK alongside RC (don't rip RC yet). Configure it.
|
|
363
363
|
4. Replace presentation call sites with `register(placement:)`; replace entitlement reads with `subscriptionStatus`.
|
|
364
364
|
5. Build, run, present each placement; **Restore Purchases** as an existing subscriber and confirm `subscriptionStatus.isActive`.
|
|
@@ -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
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
# Superwall placements - Expo
|
|
2
2
|
|
|
3
|
-
> Read `
|
|
3
|
+
> Read `strategy.md` (beside this file) first for _where_ placements go and _why_ (the
|
|
4
4
|
> core set, app-type playbook, audit method, gate depth). This file is the Expo API.
|
|
5
5
|
|
|
6
6
|
Expo uses the `expo-superwall` package. Placements are registered through the
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
# Superwall placements - Flutter
|
|
2
2
|
|
|
3
|
-
> Read `
|
|
3
|
+
> Read `strategy.md` (beside this file) first for _where_ placements go and _why_ (the core
|
|
4
4
|
> set, app-type playbook, audit method, gate depth). This file is the Flutter API.
|
|
5
5
|
|
|
6
6
|
## API
|
package/{skills/superwall-placements/references → dist/skills/superwall/workflows/placements}/ios.md
RENAMED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
# Superwall placements - iOS / Swift
|
|
2
2
|
|
|
3
|
-
> Read `
|
|
3
|
+
> Read `strategy.md` (beside this file) first for _where_ placements go and _why_ (the
|
|
4
4
|
> core set, app-type playbook, audit method, gate depth). This file is the iOS API.
|
|
5
5
|
|
|
6
6
|
## API
|
|
@@ -1,8 +1,3 @@
|
|
|
1
|
-
---
|
|
2
|
-
name: superwall-placements
|
|
3
|
-
description: Add or audit Superwall placements at meaningful feature gates and route them to campaigns. Use when adding, reviewing, or debugging where paywalls fire in iOS, Expo, React Native, or Flutter apps. Not for first-time SDK setup (superwall-integrate) or creating campaigns and products (superwall-dashboard).
|
|
4
|
-
---
|
|
5
|
-
|
|
6
1
|
# Superwall placements
|
|
7
2
|
|
|
8
3
|
A **placement** is a named event you fire at a meaningful moment. You register it,
|
|
@@ -17,7 +12,7 @@ reference for the exact call.
|
|
|
17
12
|
|
|
18
13
|
## Read the strategy playbook FIRST
|
|
19
14
|
|
|
20
|
-
`
|
|
15
|
+
`strategy.md` (beside this file) - the definitive, framework-agnostic guide to where
|
|
21
16
|
placements go and why. Read it before adding or auditing any placement. It covers:
|
|
22
17
|
|
|
23
18
|
- **The mental model** - register generously; let campaigns decide what presents.
|
|
@@ -40,10 +35,11 @@ Exact API, gating semantics, placement examples, audit checklist, and pitfalls:
|
|
|
40
35
|
|
|
41
36
|
| Framework | Reference |
|
|
42
37
|
| ------------ | ---------------------------- |
|
|
43
|
-
| iOS / Swift | `
|
|
44
|
-
| Expo | `
|
|
45
|
-
| React Native | `
|
|
46
|
-
| Flutter | `
|
|
38
|
+
| iOS / Swift | `ios.md` (beside this file) |
|
|
39
|
+
| Expo | `expo.md` (beside this file) |
|
|
40
|
+
| React Native | `react-native.md` (beside this file) |
|
|
41
|
+
| Flutter | `flutter.md` (beside this file) |
|
|
42
|
+
| Android | `android.md` (beside this file) |
|
|
47
43
|
|
|
48
44
|
## Placements need campaigns (`superwall` CLI, authenticated)
|
|
49
45
|
|
|
@@ -1,11 +1,11 @@
|
|
|
1
1
|
# Superwall placements - React Native
|
|
2
2
|
|
|
3
|
-
> Read `
|
|
3
|
+
> Read `strategy.md` (beside this file) first for _where_ placements go and _why_ (the core
|
|
4
4
|
> set, app-type playbook, audit method, gate depth). This file is the RN API.
|
|
5
5
|
|
|
6
6
|
The RN SDK (`@superwall/react-native-superwall`) registers placements via a single
|
|
7
7
|
options-object `register` call on the shared instance. (This is distinct from Expo,
|
|
8
|
-
which uses the `usePlacement` hook - see `
|
|
8
|
+
which uses the `usePlacement` hook - see `expo.md` (beside this file) if the app uses
|
|
9
9
|
`expo-superwall`.)
|
|
10
10
|
|
|
11
11
|
## API
|
|
@@ -1,8 +1,7 @@
|
|
|
1
1
|
# Superwall placement strategy - the playbook
|
|
2
2
|
|
|
3
3
|
This is the framework-agnostic strategy guide: **where** to put placements and
|
|
4
|
-
**why**. Read this first, then read your framework's reference (`ios.md`,
|
|
5
|
-
`expo.md`, `react-native.md`, `flutter.md`) for the exact API. The API is the
|
|
4
|
+
**why**. Read this first, then read your framework's reference (`ios.md`, `android.md`, `expo.md`, `react-native.md`, `flutter.md`) for the exact API. The API is the
|
|
6
5
|
easy part. Deciding what to instrument and which actions should remain remotely
|
|
7
6
|
gateable is the craft that makes an app's monetization flexible.
|
|
8
7
|
|
|
@@ -87,8 +86,10 @@ product and monetization model, named for the moment rather than the button.
|
|
|
87
86
|
| `upgrade_tapped` | User taps an explicit "Go Pro" / upgrade entry in settings or a banner | Self-selected high intent. Route to your fullest paywall. |
|
|
88
87
|
| `app_launch` / `session_start` | Cold launch / new session (both are auto-registered standard placements) | Broad-reach surface for win-back or a hard gate on relaunch. Usually left **campaign-off** until you deliberately want it - powerful but blunt. |
|
|
89
88
|
| a win-back / discount surface | User declines, churns, or hits a re-engagement point | Where you route a discounted offer. Often driven by standard placements like `paywall_decline` or `transaction_abandon`. |
|
|
89
|
+
| a non-purchase screen | Version check fails, rating or notification ask, announcement (`update_required`, `rate_app`, `whats_new`) | Placements are not only for paywalls. Any screen the team wants to change without a release is a surface behind a placement; the campaign decides whether it shows at all. |
|
|
90
90
|
|
|
91
|
-
The
|
|
91
|
+
The `app_launch`/`session_start` and win-back rows may remain unrouted until
|
|
92
|
+
there is a deliberate reason to present.
|
|
92
93
|
That is valid: instrumentation can exist before campaign strategy.
|
|
93
94
|
|
|
94
95
|
Superwall also **auto-registers** standard placements you can route without any
|
|
@@ -0,0 +1,120 @@
|
|
|
1
|
+
# Review Superwall - Android / Kotlin
|
|
2
|
+
|
|
3
|
+
You are reviewing an existing Android integration using
|
|
4
|
+
`com.superwall.sdk:superwall-android`. Complete the whole checklist;
|
|
5
|
+
placements are one part of it.
|
|
6
|
+
|
|
7
|
+
## Checklist
|
|
8
|
+
|
|
9
|
+
- [ ] SDK dependency in the app module and `minSdk` (23+ on SDK 2.8.0+)
|
|
10
|
+
- [ ] one early `configure` call in `Application.onCreate()` and the intended public key/options
|
|
11
|
+
- [ ] purchase controller, restore flow, and subscription-status ownership
|
|
12
|
+
- [ ] identity, reset, and user attributes
|
|
13
|
+
- [ ] intent filters / App Links and `handleDeepLink`
|
|
14
|
+
- [ ] conditional Web Checkout redemption readiness
|
|
15
|
+
- [ ] placements, feature lambdas, campaign coverage, and standard placements
|
|
16
|
+
- [ ] products, entitlements, paywalls, campaigns, and Play Console product IDs
|
|
17
|
+
- [ ] delegate/analytics and a build or test verification path
|
|
18
|
+
|
|
19
|
+
## Docs access
|
|
20
|
+
|
|
21
|
+
```bash
|
|
22
|
+
curl -sL https://superwall.com/docs/android/llms.txt
|
|
23
|
+
curl -sL https://superwall.com/docs/android/quickstart/configure.md
|
|
24
|
+
curl -sL https://superwall.com/docs/android/guides/advanced-configuration.md
|
|
25
|
+
curl -sL https://superwall.com/docs/android/quickstart/tracking-subscription-state.md
|
|
26
|
+
curl -sL https://superwall.com/docs/android/quickstart/user-management.md
|
|
27
|
+
curl -sL https://superwall.com/docs/android/guides/handling-deep-links.md
|
|
28
|
+
curl -sL https://superwall.com/docs/android/guides/web-checkout.md
|
|
29
|
+
curl -sL https://superwall.com/docs/android/quickstart/feature-gating.md
|
|
30
|
+
```
|
|
31
|
+
|
|
32
|
+
## 1. SDK and configuration
|
|
33
|
+
|
|
34
|
+
Inspect the app module's `build.gradle(.kts)` and `gradle/libs.versions.toml`
|
|
35
|
+
for `com.superwall.sdk:superwall-android` and its version. Confirm
|
|
36
|
+
`Superwall.configure(...)` (or `configureSuperwall { }`) runs once in
|
|
37
|
+
`Application.onCreate()`, declared via `android:name` in the manifest, not in an
|
|
38
|
+
Activity or a composable. A `pk_` key is public and may be inlined; verify it
|
|
39
|
+
belongs to the current app rather than treating its presence as a secret leak.
|
|
40
|
+
Read any `SuperwallOptions` and judge intentional behavior, not mere
|
|
41
|
+
customization.
|
|
42
|
+
|
|
43
|
+
## 2. Purchases, restores, and subscription state
|
|
44
|
+
|
|
45
|
+
Infer exactly which path the app uses:
|
|
46
|
+
|
|
47
|
+
- **Default:** no `PurchaseController` is correct; Superwall owns purchases,
|
|
48
|
+
restores, and subscription status through Play Billing.
|
|
49
|
+
- **RevenueCat/custom:** the controller must implement `purchase(activity,
|
|
50
|
+
product, basePlanId, offerId)` and `restorePurchases()`, return accurate
|
|
51
|
+
`PurchaseResult` / `RestorationResult` cases, and keep
|
|
52
|
+
`Superwall.instance.setSubscriptionStatus(...)` synchronized as entitlements
|
|
53
|
+
change. RevenueCat in observer mode is the documented alternative; do not
|
|
54
|
+
flag it as missing a controller.
|
|
55
|
+
|
|
56
|
+
Reading `subscriptionStatus` (a `StateFlow`), `.value`, customer info, or
|
|
57
|
+
entitlements is a documented way to drive app state and UI. Report a problem
|
|
58
|
+
only when two sources contradict each other, status remains `Unknown`, restore
|
|
59
|
+
is missing, or access logic demonstrably bypasses the intended purchase
|
|
60
|
+
architecture.
|
|
61
|
+
|
|
62
|
+
Compare dashboard products/entitlements with Play Console product IDs and base
|
|
63
|
+
plans when CLI access exists. Do not label an auth or network failure as broken
|
|
64
|
+
subscriptions; put it under **Not verified**.
|
|
65
|
+
|
|
66
|
+
## 3. Identity and attributes
|
|
67
|
+
|
|
68
|
+
If the app has accounts, trace the real login and logout paths. Expect
|
|
69
|
+
`Superwall.instance.identify(userId)` after identity is known and
|
|
70
|
+
`Superwall.instance.reset()` on logout. The id is hashed before it reaches Play
|
|
71
|
+
unless `passIdentifiersToPlayStore` is set; either way it must not be an email
|
|
72
|
+
or a device id. Review `setUserAttributes` for useful targeting data and
|
|
73
|
+
accidental sensitive values.
|
|
74
|
+
|
|
75
|
+
## 4. Deep links and Web Checkout
|
|
76
|
+
|
|
77
|
+
Trace every URI entry point: the launcher Activity's `intent.data` in
|
|
78
|
+
`onCreate`, `onNewIntent`, navigation deep links, and any routing service.
|
|
79
|
+
Incoming URIs intended for Superwall should reach
|
|
80
|
+
`Superwall.instance.handleDeepLink(intent.data.toString())` (a `String`), which produces the standard
|
|
81
|
+
`deepLink_open` placement with URL parameters. A hardcoded URI-to-placement
|
|
82
|
+
`when` is worth improving when dashboard campaign rules can replace it. Confirm
|
|
83
|
+
the manifest has the intent filter (custom scheme or verified App Link).
|
|
84
|
+
|
|
85
|
+
Web Checkout is conditional. If the app/dashboard uses it, verify return URLs
|
|
86
|
+
and post-checkout handling. Default Superwall purchasing needs no custom
|
|
87
|
+
redemption sync. A custom controller must merge redeemed web entitlements with
|
|
88
|
+
device entitlements and update status; RevenueCat must follow its documented
|
|
89
|
+
path. If there is no Web Checkout intent, list readiness only as an optional
|
|
90
|
+
opportunity.
|
|
91
|
+
|
|
92
|
+
## 5. Placements and lifecycle
|
|
93
|
+
|
|
94
|
+
Find `register(`, wrappers, analytics bridges, and placement constants.
|
|
95
|
+
Analytics bridges and calls without a feature lambda are valid. Require a
|
|
96
|
+
feature lambda only when the action itself is meant to be remotely gated. Check
|
|
97
|
+
valuable surfaces, placement parameters, accidental calls during composition
|
|
98
|
+
(inside a composable body rather than an `onClick` or `LaunchedEffect`), and
|
|
99
|
+
exact name agreement with active campaigns. Unrouted analytics/future
|
|
100
|
+
placements are fine.
|
|
101
|
+
|
|
102
|
+
Prefer standard `app_launch`, `session_start`, and `deepLink_open` placements
|
|
103
|
+
over custom duplicates when the semantics truly match. Do not suggest cosmetic
|
|
104
|
+
renames of stable keys. Review delegate forwarding for duplicated analytics or
|
|
105
|
+
missing subscription/redemption callbacks only when the app relies on them.
|
|
106
|
+
|
|
107
|
+
## 6. Dashboard and verification
|
|
108
|
+
|
|
109
|
+
Run the read-only CLI cross-checks from `playbook.md` (Authenticated cross-checks). A presenting chain needs a
|
|
110
|
+
matching Android app, product attached to the intended entitlement/paywall, and
|
|
111
|
+
an active campaign audience for placements expected to show now. Cite dashboard
|
|
112
|
+
IDs where available. Finally identify the project's existing Gradle build/test
|
|
113
|
+
command (`./gradlew :app:assembleDebug`, `./gradlew test`); in fix mode, run it
|
|
114
|
+
after minimal changes.
|
|
115
|
+
|
|
116
|
+
## Fix-mode boundaries
|
|
117
|
+
|
|
118
|
+
Fix clear wiring bugs and code/doc mismatches. Do not switch purchase providers,
|
|
119
|
+
enable Web Checkout, rename stable placements, change prices, or invent campaign
|
|
120
|
+
strategy without an explicit user decision.
|
package/{skills/superwall-review/references → dist/skills/superwall/workflows/review}/expo.md
RENAMED
|
@@ -88,7 +88,7 @@ Review `useSuperwallEvents` only when the app intends to forward analytics.
|
|
|
88
88
|
|
|
89
89
|
## 6. Dashboard and verification
|
|
90
90
|
|
|
91
|
-
Run the read-only CLI cross-checks from `
|
|
91
|
+
Run the read-only CLI cross-checks from `playbook.md` (Authenticated cross-checks). Verify the app/platform keys,
|
|
92
92
|
products, entitlements, paywall products, campaigns, and current presentation
|
|
93
93
|
placements form a usable chain. Cite IDs where available. In fix mode, run the
|
|
94
94
|
project's native Expo build/typecheck path - not only hot reload.
|
package/{skills/superwall-review/references → dist/skills/superwall/workflows/review}/flutter.md
RENAMED
|
@@ -87,7 +87,7 @@ keys. Delegate forwarding is optional unless app behavior relies on it.
|
|
|
87
87
|
|
|
88
88
|
## 6. Dashboard and verification
|
|
89
89
|
|
|
90
|
-
Run the read-only CLI checks from `
|
|
90
|
+
Run the read-only CLI checks from `playbook.md` (Authenticated cross-checks). Verify platform keys, products,
|
|
91
91
|
entitlements, paywall products, campaigns, and placements expected to present
|
|
92
92
|
now form a usable chain. Cite IDs where available. In fix mode, run existing
|
|
93
93
|
`flutter analyze`, tests, and an appropriate platform build where practical.
|
package/{skills/superwall-review/references → dist/skills/superwall/workflows/review}/ios.md
RENAMED
|
@@ -95,7 +95,7 @@ missing subscription/redemption callbacks only when the app relies on them.
|
|
|
95
95
|
|
|
96
96
|
## 6. Dashboard and verification
|
|
97
97
|
|
|
98
|
-
Run the read-only CLI cross-checks from `
|
|
98
|
+
Run the read-only CLI cross-checks from `playbook.md` (Authenticated cross-checks). A presenting chain needs a
|
|
99
99
|
matching app, product attached to the intended entitlement/paywall, and an active
|
|
100
100
|
campaign audience for placements expected to show now. Cite dashboard IDs where
|
|
101
101
|
available. Finally identify the project's existing Xcode build/test command; in
|
package/{skills/superwall-review/SKILL.md → dist/skills/superwall/workflows/review/playbook.md}
RENAMED
|
@@ -1,8 +1,3 @@
|
|
|
1
|
-
---
|
|
2
|
-
name: superwall-review
|
|
3
|
-
description: Audit an existing Superwall SDK setup across configuration, purchasing, subscription state, identity, deep links, Web Checkout readiness, placements, campaigns, products, entitlements, paywalls, and analytics. Use to review or safely fix an existing iOS, Expo, React Native, or Flutter integration. Do not use for first-time setup or provider migration.
|
|
4
|
-
---
|
|
5
|
-
|
|
6
1
|
# Review an existing Superwall setup
|
|
7
2
|
|
|
8
3
|
Review the integration as a system, not as a placement inventory. Inspect code,
|
|
@@ -59,8 +54,8 @@ use `superwall asc subscriptions <bundle-id> --json` to compare store identifier
|
|
|
59
54
|
|
|
60
55
|
## Framework reference
|
|
61
56
|
|
|
62
|
-
Read exactly one: `
|
|
63
|
-
`
|
|
57
|
+
Read exactly one: `ios.md` (beside this file), `expo.md` (beside this file),
|
|
58
|
+
`react-native.md` (beside this file), `flutter.md` (beside this file), or `android.md` (beside this file).
|
|
64
59
|
|
|
65
60
|
## Docs access
|
|
66
61
|
|
|
@@ -88,7 +88,7 @@ stable keys. Analytics delegate/hooks are optional unless the app relies on them
|
|
|
88
88
|
|
|
89
89
|
## 6. Dashboard and verification
|
|
90
90
|
|
|
91
|
-
Run the read-only CLI checks from `
|
|
91
|
+
Run the read-only CLI checks from `playbook.md` (Authenticated cross-checks). Verify app/platform keys, products,
|
|
92
92
|
entitlements, paywall products, campaigns, and placements expected to present
|
|
93
93
|
now form a usable chain. Cite IDs where available. In fix mode, run the existing
|
|
94
94
|
TypeScript and native build/test paths.
|