@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.
Files changed (103) hide show
  1. package/README.md +21 -5
  2. package/dist/{actions-EfP8phmb.js → actions-Dt35nIi8.js} +3 -2
  3. package/dist/{api-CEwXCCoC.js → api-BOR-uXZe.js} +9 -9
  4. package/dist/{app-D8mEVlQo.js → app-BU27SLPX.js} +9 -9
  5. package/dist/{asa-BFWehnTA.js → asa-2ykGnjaV.js} +11 -11
  6. package/dist/{asc-DJqQmtmR.js → asc-r3xmFT0L.js} +14 -14
  7. package/dist/{auth-CT2DWX8r.js → auth-BWZfguI8.js} +9 -9
  8. package/dist/auth.js +2 -2
  9. package/dist/{billing-BzEnVPD2.js → billing-BsQgXXYh.js} +1 -1
  10. package/dist/{bind-BZxVyt9P.js → bind-BSTAinn6.js} +5 -4
  11. package/dist/{command-DP96_gmP.js → command-DMoMn7uc.js} +39 -16
  12. package/dist/{create-Q8TqqjZt.js → create-CSo6XjSm.js} +118 -91
  13. package/dist/dev-B0MF6z3L.js +21 -0
  14. package/dist/{dev-DlCcwFu5.js → dev-CuXa3J4Z.js} +29 -24
  15. package/dist/{doctor-CJsjHpCZ.js → doctor-DXJaDqsx.js} +10 -10
  16. package/dist/{drivers-UT36AnOw.js → drivers-Cr252DOJ.js} +3 -3
  17. package/dist/entry.js +84 -50
  18. package/dist/{existing-Cak1WxWB.js → existing-Ckx_g7Be.js} +6 -3
  19. package/dist/{feedback-DDRzoqPx.js → feedback-Dt5yebMS.js} +6 -6
  20. package/dist/{hosted-CEH78QVn.js → hosted-Cjekn8oJ.js} +2 -2
  21. package/dist/{integrate-D8jyhDzk.js → integrate-DVqhvPVq.js} +25 -66
  22. package/dist/{login-kneYhhk0.js → login-Bjj8QvIN.js} +6 -6
  23. package/dist/migrate-qmvOtp3l.js +283 -0
  24. package/dist/open-studio-CpHqjovS.js +1299 -0
  25. package/dist/{org-Cg25bcsj.js → org-CV8c849b.js} +3 -3
  26. package/dist/{output-csAtR6kJ.js → output-CiELrN8w.js} +15 -2
  27. package/dist/{pipeline-DAeI9tHs.js → pipeline-DSCHL9KA.js} +482 -9
  28. package/dist/{print-skill-BHVPP9cX.js → print-skill-CaHRJ8xW.js} +7 -7
  29. package/dist/{promote-Boek5K2d.js → promote-UMTh8Q33.js} +17 -18
  30. package/dist/publish-DWX8S9yZ.js +34 -0
  31. package/dist/push-Dox4_5Dq.js +34 -0
  32. package/dist/{query-B8G6T8Ba.js → query-CnSsDZ7Q.js} +10 -10
  33. package/dist/reports-C0xHCLnt.js +27 -0
  34. package/dist/{resource-DjsWVka-.js → resource-5bgyyL9B.js} +15 -15
  35. package/dist/{resources-s64mBHaC.js → resources-Bf9O1JNM.js} +28 -2
  36. package/dist/{run-BtcQJCP8.js → run-BVeZWbXx.js} +39 -22
  37. package/dist/{scan-DJixvuHn.js → scan-CAObNRgc.js} +44 -4
  38. package/dist/skills/superwall/SKILL.md +146 -0
  39. package/dist/skills/superwall/references/api.md +275 -0
  40. package/dist/skills/superwall/references/asa.md +160 -0
  41. package/dist/skills/superwall/references/asc.md +96 -0
  42. package/dist/skills/superwall/references/dashboard-links.md +57 -0
  43. package/dist/skills/superwall/references/data-analytics.md +893 -0
  44. package/dist/skills/superwall/references/docs.md +51 -0
  45. package/dist/skills/superwall/references/sdk-integration.md +105 -0
  46. package/dist/skills/superwall/references/sdk-source.md +18 -0
  47. package/{skills/superwall-dashboard/SKILL.md → dist/skills/superwall/workflows/dashboard/playbook.md} +3 -9
  48. package/{skills/superwall-dashboard/references → dist/skills/superwall/workflows/dashboard}/setup.md +1 -3
  49. package/dist/skills/superwall/workflows/integrate/android.md +292 -0
  50. package/{skills/superwall-integrate/SKILL.md → dist/skills/superwall/workflows/integrate/playbook.md} +16 -11
  51. package/{skills/superwall-migrate/references → dist/skills/superwall/workflows/migrate}/adapty.md +4 -4
  52. package/{skills/superwall-migrate/SKILL.md → dist/skills/superwall/workflows/migrate/playbook.md} +4 -10
  53. package/{skills/superwall-migrate/references → dist/skills/superwall/workflows/migrate}/qonversion.md +4 -4
  54. package/{skills/superwall-migrate/references → dist/skills/superwall/workflows/migrate}/revenuecat.md +4 -4
  55. package/dist/skills/superwall/workflows/placements/android.md +175 -0
  56. package/{skills/superwall-placements/references → dist/skills/superwall/workflows/placements}/expo.md +1 -1
  57. package/{skills/superwall-placements/references → dist/skills/superwall/workflows/placements}/flutter.md +1 -1
  58. package/{skills/superwall-placements/references → dist/skills/superwall/workflows/placements}/ios.md +1 -1
  59. package/{skills/superwall-placements/SKILL.md → dist/skills/superwall/workflows/placements/playbook.md} +6 -10
  60. package/{skills/superwall-placements/references → dist/skills/superwall/workflows/placements}/react-native.md +2 -2
  61. package/{skills/superwall-placements/references → dist/skills/superwall/workflows/placements}/strategy.md +4 -3
  62. package/dist/skills/superwall/workflows/review/android.md +120 -0
  63. package/{skills/superwall-review/references → dist/skills/superwall/workflows/review}/expo.md +1 -1
  64. package/{skills/superwall-review/references → dist/skills/superwall/workflows/review}/flutter.md +1 -1
  65. package/{skills/superwall-review/references → dist/skills/superwall/workflows/review}/ios.md +1 -1
  66. package/{skills/superwall-review/SKILL.md → dist/skills/superwall/workflows/review/playbook.md} +2 -7
  67. package/{skills/superwall-review/references → dist/skills/superwall/workflows/review}/react-native.md +1 -1
  68. package/dist/skills/superwall-framework/SKILL.md +253 -0
  69. package/dist/skills/superwall-framework/references/cli.md +340 -0
  70. package/dist/skills/superwall-framework/references/examples.md +123 -0
  71. package/dist/skills/superwall-framework/references/layout.md +295 -0
  72. package/dist/skills/superwall-framework/references/migrate-from-editor.md +208 -0
  73. package/dist/skills/superwall-framework/references/migrate-from-native.md +193 -0
  74. package/dist/skills/superwall-framework/references/mobile-design.md +371 -0
  75. package/dist/skills/superwall-framework/references/native/android.md +83 -0
  76. package/dist/skills/superwall-framework/references/native/flutter.md +65 -0
  77. package/dist/skills/superwall-framework/references/native/ios.md +77 -0
  78. package/dist/skills/superwall-framework/references/native/react-native.md +67 -0
  79. package/dist/skills/superwall-framework/references/responsive.md +162 -0
  80. package/dist/{skills-CRG1xk0G.js → skills-Cu41i-Az.js} +12 -12
  81. package/dist/{skills-CODut1Hn.js → skills-grTDuHlc.js} +134 -36
  82. package/dist/{spinner-B9dT3DBY.js → spinner-DFctF_Jw.js} +1 -1
  83. package/dist/{telemetry-BtkMdT-5.js → telemetry-BuCbmoux.js} +3 -3
  84. package/dist/{token-hM7V1KMG.js → token-mju3Q-vc.js} +3 -3
  85. package/dist/{ui-Lqt_zFOr.js → ui-4gLyfrgl.js} +76 -46
  86. package/dist/{update-CeylIjx5.js → update-DnGfpCD7.js} +2 -2
  87. package/dist/{upgrade-DRqUfCBT.js → upgrade-PMoj3yqJ.js} +6 -6
  88. package/package.json +8 -7
  89. package/prompts/actions/paywall-migrate.xml +24 -0
  90. package/prompts/actions/screen-migrate.xml +26 -0
  91. package/dist/git-ZwA3Mx8m.js +0 -433
  92. package/dist/migrate-D_x1oyTk.js +0 -114
  93. package/dist/publish-C-zEUnO9.js +0 -35
  94. package/dist/push-DUDQG-EO.js +0 -35
  95. package/skills/README.md +0 -118
  96. /package/dist/{api-output-D9ggXQIr.js → api-output-CEhN-U_N.js} +0 -0
  97. /package/dist/{asc-products-C6MvSy8H.js → asc-products-1e1DoGeL.js} +0 -0
  98. /package/dist/{params-B1zeElGa.js → params-BxgTuCzr.js} +0 -0
  99. /package/{skills/superwall-integrate/references → dist/skills/superwall/workflows/integrate}/expo.md +0 -0
  100. /package/{skills/superwall-integrate/references → dist/skills/superwall/workflows/integrate}/flutter.md +0 -0
  101. /package/{skills/superwall-integrate/references → dist/skills/superwall/workflows/integrate}/ios.md +0 -0
  102. /package/{skills/superwall-integrate/references → dist/skills/superwall/workflows/integrate}/react-native.md +0 -0
  103. /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
- `references/revenuecat.md`, swapping RC calls for Qonversion calls.
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** (superwall framework or dashboard editor), attach products, connect ASC/Play
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** - as code with the superwall framework or in the dashboard editor.
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 (superwall framework or dashboard editor), attach products (hand-back to user - designs do not import).
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** (superwall framework or dashboard editor), attach products, connect ASC/Play
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** - as code with the superwall framework or in the dashboard editor.
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 its `config.ts` with the framework, or in the editor). |
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 (superwall framework or dashboard editor) and attach products (hand-back to user - designs do not import).
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 `references/strategy.md` first for _where_ placements go and _why_ (the
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 `references/strategy.md` first for _where_ placements go and _why_ (the core
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
@@ -1,6 +1,6 @@
1
1
  # Superwall placements - iOS / Swift
2
2
 
3
- > Read `references/strategy.md` first for _where_ placements go and _why_ (the
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
- `references/strategy.md` - the definitive, framework-agnostic guide to where
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 | `references/ios.md` |
44
- | Expo | `references/expo.md` |
45
- | React Native | `references/react-native.md` |
46
- | Flutter | `references/flutter.md` |
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 `references/strategy.md` first for _where_ placements go and _why_ (the core
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 `references/expo.md` if the app uses
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 last two may remain unrouted until there is a deliberate reason to present.
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.
@@ -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 `SKILL.md`. Verify the app/platform keys,
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.
@@ -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 `SKILL.md`. Verify platform keys, products,
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.
@@ -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 `SKILL.md`. A presenting chain needs a
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
@@ -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: `references/ios.md`, `references/expo.md`,
63
- `references/react-native.md`, or `references/flutter.md`.
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 `SKILL.md`. Verify app/platform keys, products,
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.