@superwall/cli 1.7.0 → 2.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (229) hide show
  1. package/README.md +192 -52
  2. package/dist/{setup-Bxj22rYi.js → apple-CSzNTGHM.js} +82 -76
  3. package/dist/auth.d.ts +4 -19
  4. package/dist/auth.js +4 -2
  5. package/dist/{actions-B7ym3oVS.js → billing-C3Q8DBU2.js} +98 -28
  6. package/dist/{bind-YrJvuRF9.js → bind-BumHTi9O.js} +38 -33
  7. package/dist/{build-DLoCW5Ri.js → build-Bpviiclc.js} +20 -26
  8. package/dist/client-BL0f_yGf.js +176 -0
  9. package/dist/{asc-Bf7zBbyS.js → client-BZ1UbpXz.js} +16 -15
  10. package/dist/config-BO1Y87kV.js +105 -0
  11. package/dist/create-BSfvpWoD.js +19 -0
  12. package/dist/{create-pkANt1Gs.js → create-BUcVG4Ab.js} +195 -169
  13. package/dist/{notification-url-DuKF2659.js → create-CfK3PeKA.js} +235 -539
  14. package/dist/doctor-BWqIYcMn.js +83 -0
  15. package/dist/{drivers-Qx9LxmRN.js → drivers-CPhdPkW5.js} +185 -172
  16. package/dist/entry.d.ts +0 -5
  17. package/dist/entry.js +28072 -1134
  18. package/dist/environment-eBXjELoN.js +58 -0
  19. package/dist/{existing-AVEfZu2A.js → existing-BltvQiX5.js} +12 -6
  20. package/dist/held-CPve03KJ.js +16 -0
  21. package/dist/held-DgnTFMl3.js +1112 -0
  22. package/dist/input-vi0bou04.js +42 -0
  23. package/dist/{integrate-brmhPG-S.js → integrate-BRsqoe01.js} +277 -254
  24. package/dist/log-NVhVe_oe.js +62 -0
  25. package/dist/login-BCEH5q0U.js +53 -0
  26. package/dist/login-BPOONe7n.js +16 -0
  27. package/dist/{login-Do4wFuLv.js → login-BbTIrCFT.js} +118 -55
  28. package/dist/lookup-rr1AkCJA.js +71 -0
  29. package/dist/migrate-C9X2Vz81.js +274 -0
  30. package/dist/notification-url-CV86qiKP.js +100 -0
  31. package/dist/{open-studio-DOw-6ydc.js → open-CcpXotHG.js} +34 -43
  32. package/dist/org-BQQDo7wm.js +35 -0
  33. package/dist/output-Ggzq5_-t.js +122 -0
  34. package/dist/paths-CRlU72cq.js +29 -0
  35. package/dist/playbook-DVMXN7fh.js +53 -0
  36. package/dist/{asc-products-9JXtDxI4.js → products-DH_fK9tY.js} +6 -6
  37. package/dist/promote-Da8xctzy.js +91 -0
  38. package/dist/push-BV-grvQg.js +22 -0
  39. package/dist/push-D6R9icWN.js +495 -0
  40. package/dist/registry-BYVD-_h6.js +10385 -0
  41. package/dist/{reports-CfJqoava.js → reports-D_qbl7_u.js} +7 -6
  42. package/dist/{resources-Bf9O1JNM.js → resources-DLON3-61.js} +162 -55
  43. package/dist/{run-DsVZ5snL.js → run-Co-BwhOg.js} +16 -22
  44. package/dist/scan-B88OlWOt.js +4 -0
  45. package/dist/{scan-zKsddO72.js → scan-CKuk-_6W.js} +48 -37
  46. package/dist/scope-DV22_Ufm.js +198 -0
  47. package/dist/screenshot-file-tVBfUEIi.js +16 -0
  48. package/dist/{selection-CxZoX4NT.js → selection-C2_KbLuo.js} +100 -51
  49. package/dist/server-C4f6ccUr.js +22 -0
  50. package/dist/{dev-DmB3XqaJ.js → server-D0d2oP-5.js} +86 -94
  51. package/dist/session-B-Uz0cQ7.js +40 -0
  52. package/dist/session-BuvArt1j.js +6 -0
  53. package/dist/session-C4rbE3VS.js +796 -0
  54. package/dist/skills/animate-onboarding/SKILL.md +467 -0
  55. package/dist/skills/animate-onboarding/references/engine.md +494 -0
  56. package/dist/skills/animate-onboarding/references/framework/Question.tsx +71 -0
  57. package/dist/skills/animate-onboarding/references/framework/README.md +40 -0
  58. package/dist/skills/animate-onboarding/references/framework/answers.ts +19 -0
  59. package/dist/skills/animate-onboarding/references/framework/flow.ts +80 -0
  60. package/dist/skills/animate-onboarding/references/framework/handoffs.ts +869 -0
  61. package/dist/skills/animate-onboarding/references/framework/layout.tsx +113 -0
  62. package/dist/skills/animate-onboarding/references/framework/motion.css +559 -0
  63. package/dist/skills/animate-onboarding/references/framework/useStoryRouter.ts +48 -0
  64. package/dist/skills/animate-onboarding/references/handoffs.md +375 -0
  65. package/dist/skills/animate-onboarding/references/imageReady.ts +92 -0
  66. package/dist/skills/animate-onboarding/references/morphFrame.ts +356 -0
  67. package/dist/skills/animate-onboarding/references/performance.md +41 -0
  68. package/dist/skills/animate-onboarding/references/web-runtime/README.md +17 -0
  69. package/dist/skills/animate-onboarding/references/web-runtime/handoffs.ts +858 -0
  70. package/dist/skills/animate-onboarding/references/web-runtime/story-motion.css +301 -0
  71. package/dist/skills/index.json +37 -0
  72. package/dist/skills/mobile-design/SKILL.md +447 -0
  73. package/dist/skills/mobile-design/references/responsive.md +162 -0
  74. package/dist/skills/onboarding-questions/SKILL.md +231 -0
  75. package/dist/skills/onboarding-questions/references/arpu-questions.md +139 -0
  76. package/dist/skills/onboarding-questions/references/craft.md +142 -0
  77. package/dist/skills/onboarding-questions/references/example-reflective.md +117 -0
  78. package/dist/skills/superwall/SKILL.md +82 -9
  79. package/dist/skills/superwall/references/api.md +153 -37
  80. package/dist/skills/superwall/references/apple-setup.md +316 -0
  81. package/dist/skills/superwall/references/asc.md +74 -38
  82. package/dist/skills/superwall/references/data-analytics.md +55 -21
  83. package/dist/skills/superwall/workflows/dashboard/playbook.md +3 -3
  84. package/dist/skills/superwall/workflows/dashboard/setup.md +8 -8
  85. package/dist/skills/superwall/workflows/migrate/adapty.md +6 -6
  86. package/dist/skills/superwall/workflows/migrate/playbook.md +4 -4
  87. package/dist/skills/superwall/workflows/migrate/qonversion.md +5 -5
  88. package/dist/skills/superwall/workflows/migrate/revenuecat.md +6 -6
  89. package/dist/skills/superwall/workflows/placements/android.md +2 -2
  90. package/dist/skills/superwall/workflows/placements/expo.md +2 -2
  91. package/dist/skills/superwall/workflows/placements/flutter.md +2 -2
  92. package/dist/skills/superwall/workflows/placements/ios.md +2 -2
  93. package/dist/skills/superwall/workflows/placements/playbook.md +2 -2
  94. package/dist/skills/superwall/workflows/placements/react-native.md +2 -2
  95. package/dist/skills/superwall/workflows/placements/strategy.md +2 -2
  96. package/dist/skills/superwall/workflows/review/playbook.md +1 -1
  97. package/dist/skills/superwall-editor/SKILL.md +61 -0
  98. package/dist/skills/superwall-editor/references/cli.md +135 -0
  99. package/dist/skills/superwall-editor/references/design.md +51 -0
  100. package/dist/skills/superwall-editor/references/native-elements.md +171 -0
  101. package/dist/skills/superwall-editor/references/workflow.md +65 -0
  102. package/dist/skills/superwall-editor/scripts/sw-editor.sh +662 -0
  103. package/dist/skills/superwall-framework/SKILL.md +85 -31
  104. package/dist/skills/superwall-framework/references/cli.md +58 -27
  105. package/dist/skills/superwall-framework/references/examples.md +4 -3
  106. package/dist/skills/superwall-framework/references/layout.md +64 -9
  107. package/dist/skills/superwall-framework/references/migrate-from-editor.md +1 -1
  108. package/dist/skills/superwall-framework/references/onboarding-state.md +245 -0
  109. package/dist/skills/wwdc/SKILL.md +22 -0
  110. package/dist/skills/wwdc/references/docs.md +52 -0
  111. package/dist/skills/wwdc/scripts/wwdc.sh +266 -0
  112. package/dist/skills-CLGJuMnF.js +14 -0
  113. package/dist/{skills-DPzlnfCK.js → skills-CZcpnEnG.js} +100 -122
  114. package/dist/{spawn-DSoTXy_j.js → spawn-DmmmHIP-.js} +14 -12
  115. package/dist/spinner-C2U6QBJ9.js +294 -0
  116. package/dist/storage-6h9vyiAz.js +31 -0
  117. package/dist/storage-CerJ5KLP.d.ts +16 -0
  118. package/dist/storekit-CK9JmM2D.js +16 -0
  119. package/dist/storekit-CinJra3V.js +47 -0
  120. package/dist/telemetry-DKyDhURo.js +56 -0
  121. package/dist/theme-DUsCh-Vd.js +25 -0
  122. package/dist/timing-BVxPrYq3.js +5 -0
  123. package/dist/{token-C0it-Xh7.js → token-DaxQgQkv.js} +6 -38
  124. package/dist/tools-skills/animate-onboarding/SKILL.md +467 -0
  125. package/dist/tools-skills/animate-onboarding/references/engine.md +494 -0
  126. package/dist/tools-skills/animate-onboarding/references/framework/Question.tsx +71 -0
  127. package/dist/tools-skills/animate-onboarding/references/framework/README.md +40 -0
  128. package/dist/tools-skills/animate-onboarding/references/framework/answers.ts +19 -0
  129. package/dist/tools-skills/animate-onboarding/references/framework/flow.ts +80 -0
  130. package/dist/tools-skills/animate-onboarding/references/framework/handoffs.ts +869 -0
  131. package/dist/tools-skills/animate-onboarding/references/framework/layout.tsx +113 -0
  132. package/dist/tools-skills/animate-onboarding/references/framework/motion.css +559 -0
  133. package/dist/tools-skills/animate-onboarding/references/framework/useStoryRouter.ts +48 -0
  134. package/dist/tools-skills/animate-onboarding/references/handoffs.md +375 -0
  135. package/dist/tools-skills/animate-onboarding/references/imageReady.ts +92 -0
  136. package/dist/tools-skills/animate-onboarding/references/morphFrame.ts +356 -0
  137. package/dist/tools-skills/animate-onboarding/references/performance.md +41 -0
  138. package/dist/tools-skills/animate-onboarding/references/web-runtime/README.md +17 -0
  139. package/dist/tools-skills/animate-onboarding/references/web-runtime/handoffs.ts +858 -0
  140. package/dist/tools-skills/animate-onboarding/references/web-runtime/story-motion.css +301 -0
  141. package/dist/tools-skills/mobile-design/SKILL.md +447 -0
  142. package/dist/tools-skills/mobile-design/references/responsive.md +162 -0
  143. package/dist/tools-skills/onboarding-questions/SKILL.md +231 -0
  144. package/dist/tools-skills/onboarding-questions/references/arpu-questions.md +139 -0
  145. package/dist/tools-skills/onboarding-questions/references/craft.md +142 -0
  146. package/dist/tools-skills/onboarding-questions/references/example-reflective.md +117 -0
  147. package/dist/tools-skills/superwall/SKILL.md +263 -0
  148. package/dist/tools-skills/superwall/references/api.md +303 -0
  149. package/dist/tools-skills/superwall/references/asa.md +166 -0
  150. package/dist/tools-skills/superwall/references/asc.md +95 -0
  151. package/dist/tools-skills/superwall/references/dashboard-links.md +57 -0
  152. package/dist/tools-skills/superwall/references/data-analytics.md +896 -0
  153. package/dist/tools-skills/superwall/references/docs.md +51 -0
  154. package/dist/tools-skills/superwall/references/sdk-integration.md +104 -0
  155. package/dist/tools-skills/superwall/references/sdk-source.md +18 -0
  156. package/dist/tools-skills/superwall/workflows/dashboard/playbook.md +76 -0
  157. package/dist/tools-skills/superwall/workflows/dashboard/setup.md +100 -0
  158. package/dist/tools-skills/superwall/workflows/integrate/android.md +292 -0
  159. package/dist/tools-skills/superwall/workflows/integrate/expo.md +272 -0
  160. package/dist/tools-skills/superwall/workflows/integrate/flutter.md +285 -0
  161. package/dist/tools-skills/superwall/workflows/integrate/ios.md +314 -0
  162. package/dist/tools-skills/superwall/workflows/integrate/playbook.md +83 -0
  163. package/dist/tools-skills/superwall/workflows/integrate/react-native.md +246 -0
  164. package/dist/tools-skills/superwall/workflows/migrate/adapty.md +229 -0
  165. package/dist/tools-skills/superwall/workflows/migrate/playbook.md +78 -0
  166. package/dist/tools-skills/superwall/workflows/migrate/qonversion.md +227 -0
  167. package/dist/tools-skills/superwall/workflows/migrate/revenuecat.md +414 -0
  168. package/dist/tools-skills/superwall/workflows/placements/android.md +175 -0
  169. package/dist/tools-skills/superwall/workflows/placements/expo.md +161 -0
  170. package/dist/tools-skills/superwall/workflows/placements/flutter.md +139 -0
  171. package/dist/tools-skills/superwall/workflows/placements/ios.md +165 -0
  172. package/dist/tools-skills/superwall/workflows/placements/playbook.md +69 -0
  173. package/dist/tools-skills/superwall/workflows/placements/react-native.md +145 -0
  174. package/dist/tools-skills/superwall/workflows/placements/strategy.md +222 -0
  175. package/dist/tools-skills/superwall/workflows/review/android.md +120 -0
  176. package/dist/tools-skills/superwall/workflows/review/expo.md +100 -0
  177. package/dist/tools-skills/superwall/workflows/review/flutter.md +99 -0
  178. package/dist/tools-skills/superwall/workflows/review/ios.md +108 -0
  179. package/dist/tools-skills/superwall/workflows/review/playbook.md +70 -0
  180. package/dist/tools-skills/superwall/workflows/review/react-native.md +100 -0
  181. package/dist/tools-skills/superwall-editor/SKILL.md +113 -0
  182. package/dist/tools-skills/superwall-editor/references/cli.md +135 -0
  183. package/dist/tools-skills/superwall-editor/references/design.md +51 -0
  184. package/dist/tools-skills/superwall-editor/references/native-elements.md +171 -0
  185. package/dist/tools-skills/superwall-editor/references/workflow.md +65 -0
  186. package/dist/tools-skills/superwall-editor/scripts/sw-editor.sh +662 -0
  187. package/dist/tools-skills/wwdc/SKILL.md +22 -0
  188. package/dist/tools-skills/wwdc/references/docs.md +52 -0
  189. package/dist/tools-skills/wwdc/scripts/wwdc.sh +266 -0
  190. package/dist/tools.d.ts +96 -0
  191. package/dist/tools.js +11360 -0
  192. package/dist/ui-D_qf3Gvw.js +53 -0
  193. package/dist/upgrade-DPo0a4Es.js +117 -0
  194. package/dist/upgrade-ffseQDMx.js +7 -0
  195. package/package.json +10 -5
  196. package/dist/api-CZzirVMj.js +0 -151
  197. package/dist/api-output-aJNw7Syy.js +0 -20
  198. package/dist/app-DH6U8yuI.js +0 -190
  199. package/dist/asa-C-sQzPPn.js +0 -1194
  200. package/dist/asc-1ZBJ6DwS.js +0 -778
  201. package/dist/auth-YRhlV3DE.js +0 -140
  202. package/dist/billing-CCYHdApx.js +0 -80
  203. package/dist/bundle-id-CKxl_026.js +0 -121
  204. package/dist/command-CMIz81Da.js +0 -301
  205. package/dist/dev-DZy6pOnB.js +0 -22
  206. package/dist/doctor-H-hf-Yww.js +0 -88
  207. package/dist/feedback-CKf-rpBW.js +0 -152
  208. package/dist/hosted-CXe9TrWx.js +0 -32
  209. package/dist/migrate-C9ERDR6y.js +0 -284
  210. package/dist/org-sj7uyvp-.js +0 -40
  211. package/dist/output-C4o2gJ1K.js +0 -146
  212. package/dist/params-l3CrvRtR.js +0 -51
  213. package/dist/pipeline-BqzqZhX1.js +0 -977
  214. package/dist/print-skill-ZojRSybs.js +0 -74
  215. package/dist/promote-BG8X4Nv_.js +0 -88
  216. package/dist/publish-sxLh-G4G.js +0 -35
  217. package/dist/push-bQ6Vxtg8.js +0 -35
  218. package/dist/query-_FbybaH-.js +0 -53
  219. package/dist/resource-CGIwSd29.js +0 -323
  220. package/dist/revenue-provider-ebsRINY8.js +0 -100
  221. package/dist/scope-BvzD-kO4.js +0 -223
  222. package/dist/skills-D_R-lEsK.js +0 -64
  223. package/dist/spinner-TWa0hia6.js +0 -18
  224. package/dist/storekit-Cj9Cpjcz.js +0 -29
  225. package/dist/telemetry-DeA1mvnT.js +0 -169
  226. package/dist/ui-Dy0b-9L8.js +0 -27738
  227. package/dist/update-B2fWIc4q.js +0 -59
  228. package/dist/upgrade-BmzkTKrh.js +0 -72
  229. /package/dist/{devtools-8EgLo86w.js → devtools-pBl_vt03.js} +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