@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,51 @@
1
+ ## Documentation
2
+
3
+ All Superwall documentation is available in machine-readable formats. **Do not hardcode doc content** - always fetch live.
4
+
5
+ | Resource | URL | Use when |
6
+ | ----------- | ----------------------------------------------- | --------------------------------------------- |
7
+ | Doc index | `https://superwall.com/docs/llms.txt` | Finding the right doc page for a topic |
8
+ | Full docs | `https://superwall.com/docs/llms-full.txt` | Need comprehensive context across many topics |
9
+ | Single page | `curl -sL https://superwall.com/docs/{path}.md` | Reading a specific doc page |
10
+
11
+ ### Platform doc prefixes
12
+
13
+ - iOS: `/docs/ios/`
14
+ - Android: `/docs/android/`
15
+ - Flutter: `/docs/flutter/`
16
+ - Expo: `/docs/expo/`
17
+ - React Native: `/docs/react-native/`
18
+ - Dashboard: `/docs/dashboard/`
19
+ - Web Checkout: `/docs/web-checkout/`
20
+ - Integrations: `/docs/integrations/`
21
+
22
+ **Tip**: Fetch `llms.txt` first to find the exact path, then fetch that page with `curl -sL`.
23
+
24
+ ---
25
+
26
+ ## Dashboard Links
27
+
28
+ URL patterns for linking users to Superwall dashboard pages. See [dashboard-links.md](dashboard-links.md).
29
+
30
+ ---
31
+
32
+ ## SDK Source (for debugging)
33
+
34
+ Clone SDK repos locally to trace internal behavior. See [sdk-source.md](sdk-source.md).
35
+
36
+ ---
37
+
38
+ ## Webhooks & Integrations
39
+
40
+ **Live integration catalog** (same source the Superwall dashboard pulls from):
41
+
42
+ ```bash
43
+ curl -s https://webhooks.superwall.me/integrations
44
+ ```
45
+
46
+ Always fetch live - do not cache.
47
+
48
+ For general webhook and event documentation, fetch from the docs:
49
+
50
+ - **Webhook setup**: `curl -sL https://superwall.com/docs/integrations/webhooks.md`
51
+ - **Event catalog**: Fetch `https://superwall.com/docs/llms.txt` and search for "events" or "analytics" to find the full event type reference
@@ -0,0 +1,104 @@
1
+ # SDK Integration
2
+
3
+ **Fastest path:** agents run `superwall integrate --skill` and follow the printed
4
+ framework-specific playbook directly using the installed CLI. Without the CLI,
5
+ read the bundled playbooks or follow the manual doc-walking path below.
6
+
7
+ ## Integration checklist
8
+
9
+ Copy this checklist to track progress:
10
+
11
+ ```
12
+ - [ ] Detect platform ({sdk})
13
+ - [ ] Determine purchase controller path (default / RevenueCat / custom)
14
+ - [ ] Install SDK dependency
15
+ - [ ] Configure Superwall at app launch
16
+ - [ ] User management (identify / reset)
17
+ - [ ] Feature gating (register placements)
18
+ - [ ] Track subscription state
19
+ - [ ] Set user properties
20
+ - [ ] In-app paywall previews (deep links)
21
+ - [ ] Post-integration: deep links, analytics, feature gating audit
22
+ ```
23
+
24
+ ## Step 1: Detect the platform
25
+
26
+ Examine the user's project to determine the SDK. Use the first match:
27
+
28
+ | Signal | SDK value |
29
+ |--------|-----------|
30
+ | `pubspec.yaml` present, Dart code | `flutter` |
31
+ | `app.json` or `app.config.js` with `expo` field | `expo` |
32
+ | `*.xcodeproj` or `Package.swift`, Swift/ObjC code | `ios` |
33
+ | `build.gradle` or `build.gradle.kts`, Kotlin/Java code | `android` |
34
+ | `react-native` in `package.json` without Expo | `expo` - the standalone RN SDK is deprecated; bare RN uses `expo-superwall` via the pinned Expo modules installer in the [React Native playbook](../workflows/integrate/react-native.md) (RN 0.79+) |
35
+
36
+ Store the result as `{sdk}` - it is used in every doc URL below.
37
+
38
+ ## Step 2: Determine the purchase controller path
39
+
40
+ Ask the user (or infer from their codebase) which applies:
41
+
42
+ 1. **No existing purchase system** - New to IAP or wants Superwall to handle everything.
43
+ → **Default (no PurchaseController)**. Superwall manages purchases, restoration, and subscription tracking automatically.
44
+
45
+ 2. **Using RevenueCat** - RevenueCat SDK is present in the project.
46
+ → **RevenueCat integration**. Follow the RevenueCat guide instead of the default configure step.
47
+ `curl -sL https://superwall.com/docs/{sdk}/guides/using-revenuecat.md`
48
+
49
+ 3. **Using another billing SDK or custom purchase logic** - Qonversion, Adapty, proprietary server-side billing, etc.
50
+ → **Custom PurchaseController**. User must implement `PurchaseController` and manually set `subscriptionStatus`.
51
+ `curl -sL https://superwall.com/docs/{sdk}/guides/advanced-configuration.md`
52
+ `curl -sL https://superwall.com/docs/{sdk}/sdk-reference/PurchaseController.md`
53
+
54
+ > **Critical**: When a PurchaseController is used (paths 2 or 3), the user **must** also manually set `subscriptionStatus` on the Superwall instance.
55
+
56
+ ## Step 3: Execute the quickstart steps in order
57
+
58
+ Fetch each doc page with `curl -sL`, implement, verify, then move to the next.
59
+
60
+ **Doc URL pattern:**
61
+ ```
62
+ https://superwall.com/docs/{sdk}/quickstart/{slug}.md
63
+ ```
64
+
65
+ | # | Slug | What it covers |
66
+ |---|------|----------------|
67
+ | 1 | `install` | Add the SDK dependency to the project |
68
+ | 2 | `configure` | Initialize Superwall at app launch (apply purchase controller path from Step 2) |
69
+ | 3 | `user-management` | Identify users on sign-in, reset on logout |
70
+ | 4 | `feature-gating` | Register placements and present paywalls (page title: "Presenting Paywalls") |
71
+ | 5 | `tracking-subscription-state` | Observe subscription status changes in app code |
72
+ | 6 | `setting-user-properties` | Set custom user attributes for audience targeting |
73
+ | 7 | `in-app-paywall-previews` | Set up deep link handling for on-device paywall previews |
74
+
75
+ > Docs use `:::ios`, `:::android`, `:::flutter`, `:::expo` fences - use only the `{sdk}`-relevant code.
76
+
77
+ ## Step 4: Complete the integration
78
+
79
+ After the quickstart, walk through these remaining concerns:
80
+
81
+ - **Deep links**: Set up deep link handling for paywall previews and web checkout redemption.
82
+ `curl -sL https://superwall.com/docs/{sdk}/guides/handling-deep-links.md`
83
+
84
+ - **User identity**: Ensure `identify(userId:)` is called on sign-in with a stable, non-guessable user ID (UUID recommended). Call `reset()` on logout.
85
+
86
+ - **Feature gating audit**: Review which features should be paywalled. Register a placement for each, then configure gating rules in the Superwall dashboard.
87
+
88
+ - **User attributes**: Set custom attributes (name, plan type, cohort, etc.) for audience targeting and paywall personalization via `setUserAttributes()`.
89
+
90
+ - **3rd-party analytics** (offer if an analytics SDK is detected in the project): Forward Superwall events to their analytics tool via the SuperwallDelegate.
91
+ - Overview: `curl -sL https://superwall.com/docs/{sdk}/guides/3rd-party-analytics.md`
92
+ - Event list & forwarding: `curl -sL https://superwall.com/docs/{sdk}/guides/3rd-party-analytics/tracking-analytics.md`
93
+ - Cohorting (experiment/variant IDs in Amplitude, Mixpanel, etc.): `curl -sL https://superwall.com/docs/{sdk}/guides/3rd-party-analytics/cohorting-in-3rd-party-tools.md`
94
+ - `confirmAllAssignments()` - get all experiment/variant assignments on startup: `curl -sL https://superwall.com/docs/{sdk}/sdk-reference/confirmAllAssignments.md`
95
+
96
+ ## Advanced configuration docs
97
+
98
+ | Topic | URL |
99
+ |-------|-----|
100
+ | Purchases & subscription status | `https://superwall.com/docs/{sdk}/guides/advanced-configuration.md` |
101
+ | RevenueCat integration | `https://superwall.com/docs/{sdk}/guides/using-revenuecat.md` |
102
+ | PurchaseController reference | `https://superwall.com/docs/{sdk}/sdk-reference/PurchaseController.md` |
103
+ | SuperwallDelegate reference | `https://superwall.com/docs/{sdk}/sdk-reference/SuperwallDelegate.md` |
104
+ | SuperwallOptions reference | `https://superwall.com/docs/{sdk}/sdk-reference/SuperwallOptions.md` |
@@ -0,0 +1,18 @@
1
+ # SDK Source
2
+
3
+ Clone into `tmp/superwall-sdks/`. If the directory already exists, `git pull` instead of re-cloning.
4
+
5
+ | SDK | Repo | Branch |
6
+ |-----|------|--------|
7
+ | iOS | `https://github.com/superwall/Superwall-iOS.git` | `develop` |
8
+ | Android | `https://github.com/superwall/Superwall-Android.git` | `develop` |
9
+ | Flutter | `https://github.com/superwall/Superwall-Flutter.git` | `main` |
10
+ | React Native | `https://github.com/superwall/react-native-superwall.git` | `main` |
11
+
12
+ ```bash
13
+ # Clone
14
+ git clone -b {branch} {repo} tmp/superwall-sdks/{sdk}
15
+
16
+ # Update existing
17
+ git -C tmp/superwall-sdks/{sdk} pull
18
+ ```
@@ -0,0 +1,76 @@
1
+ # Set up the Superwall dashboard
2
+
3
+ Turn an app whose code registers placements into a working dashboard: entitlement(s),
4
+ products, and campaigns that route each placement to a paywall. Use the globally
5
+ installed, already-authenticated `superwall` CLI for every change. Pass `--json` on
6
+ every command. Run `superwall whoami --json` first; if not logged in, tell the user to run
7
+ `superwall login`.
8
+
9
+ ## The model (teach this, then act)
10
+
11
+ ```
12
+ placement (in code) → campaign (routes it) → audience (who) → paywall (what shows)
13
+ ↑
14
+ products + entitlements (what's sold / unlocked)
15
+ ```
16
+
17
+ - A **placement** is a `register("event")` call in the app. It does **nothing** until a
18
+ campaign carries it.
19
+ - A **campaign** is the container that routes placements. It holds **audiences** (top-to-bottom
20
+ filter rules; first match wins, sticky assignment) and each audience runs an **experiment**
21
+ that splits traffic across **paywalls**.
22
+ - A **paywall** sells **products**; buying grants an **entitlement** (e.g. `pro`) which is the
23
+ boolean the app gates features on.
24
+ - So: register a placement in code → add it to a campaign → the campaign shows a paywall. Without
25
+ the campaign step, the placement fires and silently does nothing.
26
+
27
+ ## Do it in order
28
+
29
+ 1. **Find the app.** `superwall apps list --json`. Match the app by its `public_api_key`
30
+ (the `pk_…` in the app's `configure()` call). Note its `id` → pass `--app <id>` to
31
+ campaign/paywall commands, `--project <id>` to product/entitlement commands. Always pass
32
+ these ids; JSON mode never guesses when multiple scopes exist.
33
+ 2. **Find registered placements.** Grep the app for `register(`, `registerPlacement(`,
34
+ `usePlacement(`, `Superwall.shared.register` - collect the exact event-name strings.
35
+ 3. **Ensure an entitlement.** `superwall entitlements list --project <id> --json`; reuse an existing one, else
36
+ `superwall entitlements create pro --project <id> --json`. Default to a single `pro` entitlement unless the
37
+ app clearly has tiers.
38
+ 4. **Ensure products.** `superwall products list --project <id> --json` first. If none:
39
+ - App Store Connect connected (`superwall asc keys list --json`) → import (see `setup.md` beside this file).
40
+ - Otherwise create with real pricing:
41
+ `superwall products create pro_yearly --price 39.99 --period year --trial-days 7 --entitlement pro --project <id> --json`
42
+ 5. **Carry each placement.** `superwall campaigns list --project <id> --app <id> --json`. For each placement not already on
43
+ a campaign: `superwall campaigns create "<description>" <placement> --project <id> --app <id> --json` (campaigns require an initial placement; it seeds a 100% holdout audience), or add more with `superwall campaigns placement <campaignId> <placement> --project <id> --app <id> --json`.
44
+
45
+ ## Guardrails
46
+
47
+ - **List before you create.** Never create a duplicate entitlement/product/campaign.
48
+ - **Never delete or destructively modify** existing campaigns, paywalls, products, or audiences.
49
+ - Reuse existing entitlements and products; only add what's missing.
50
+ - Idempotent by design - re-running should be a no-op when everything already exists.
51
+
52
+ ## Best practices
53
+
54
+ - **One campaign per surface** (e.g. an "Onboarding" campaign carrying the onboarding placement,
55
+ a "Feature gates" campaign carrying in-app gate placements) reads better than one campaign per
56
+ placement - a campaign can carry several related placements. When unsure, one campaign per
57
+ distinct user context.
58
+ - Name campaigns for the surface/intent, not the placement string.
59
+ - Keep entitlements coarse (`pro`); don't mint one per product.
60
+
61
+ ## Report back (short-line markdown)
62
+
63
+ - What already existed (ids).
64
+ - What you created: entitlement, product ids, campaign ids, placements attached.
65
+ - **Left manual:** paywall design - as code with the superwall framework (`superwall create` →
66
+ `superwall publish`) or in the dashboard editor - attaching products to the paywall, and - if
67
+ products were created by hand - reconciling identifiers with App Store Connect / Google Play.
68
+
69
+ See `setup.md` (beside this file) for the App Store Connect import path, `.storekit` generation, and pricing-flag reference.
70
+
71
+ ## Docs access
72
+
73
+ Any Superwall doc page is fetchable as markdown: `curl -sL https://superwall.com/docs/llms.txt`
74
+ to find the path (dashboard concepts live under `/docs/dashboard/`), then
75
+ `curl -sL https://superwall.com/docs/{path}.md` for the page. Use this for campaign/audience
76
+ details beyond this skill.
@@ -0,0 +1,100 @@
1
+ # Dashboard setup - reference
2
+
3
+ Detailed recipes for the `superwall-dashboard` skill. Every command takes `--json`.
4
+
5
+ ## Scoping
6
+
7
+ | Resource | Scope | Flag |
8
+ | ---------------------- | ----------- | ---------------- |
9
+ | products, entitlements | project | `--project <id>` |
10
+ | campaigns, paywalls | application | `--app <id>` |
11
+
12
+ `superwall apps list --json` returns projects with nested `applications` (each has `id`,
13
+ `platform`, `bundle_id`, `public_api_key`). One project holds one app per platform, so with a
14
+ single app the CLI auto-scopes; agents always pass the flags explicitly.
15
+
16
+ ## Products
17
+
18
+ ### Create by hand (real pricing)
19
+
20
+ ```bash
21
+ superwall products create <identifier> \
22
+ --price 39.99 \ # major units; converted to cents for you
23
+ --currency USD \ # default USD
24
+ --period year \ # day | week | month | year
25
+ --period-count 1 \ # periods per cycle, default 1
26
+ --trial-days 7 \ # optional free-trial length
27
+ --entitlement pro \ # entitlement(s) to grant; repeat --entitlement for more
28
+ --name "Pro Yearly" \ # optional display name
29
+ --project <id> --json
30
+ ```
31
+
32
+ Use the **real store product identifiers** (the ones in App Store Connect / Google Play), e.g.
33
+ `com.app.pro.yearly`. The dashboard product identifier must match the store's or the SDK can't
34
+ resolve it on device.
35
+
36
+ ### Import from App Store Connect
37
+
38
+ There is **no** `products import` subcommand. `superwall integrate --skill`
39
+ prints the full setup instructions without spawning another agent. To import
40
+ products yourself, use credentials the user has already connected privately,
41
+ enumerate via the signed ASC proxy, then create products in the approved scope.
42
+ If credentials are missing, have the user consult `superwall asc keys set --help`
43
+ at their own terminal and complete setup themselves. Do not request, inspect,
44
+ or upload their private key.
45
+
46
+ ```bash
47
+ superwall asc keys list --json # confirm connected; note the team id
48
+
49
+ # enumerate real products for the app (by bundle id or ASC app id)
50
+ superwall asc subscriptions com.app.bundle --json # renewing subs
51
+ superwall asc iaps com.app.bundle --json # one-time / non-renewing
52
+ superwall asc products com.app.bundle --json # everything
53
+ superwall asc apps --json # list ASC apps if unsure of the id
54
+
55
+ # create each returned productId, granting your entitlement
56
+ superwall products create com.app.pro.yearly --entitlement pro --project <id> --json
57
+ ```
58
+
59
+ Products imported this way carry only the identifier (and reference name); Xcode/StoreKit and
60
+ the stores remain the source of truth for pricing.
61
+
62
+ ### Generate a local `.storekit` file (for Xcode testing without sandbox)
63
+
64
+ ```bash
65
+ superwall products storekit --project <id> --out Superwall.storekit --json
66
+ ```
67
+
68
+ Seeds product identifiers into a StoreKit configuration file; Xcode refines pricing/types on import.
69
+
70
+ ## Entitlements
71
+
72
+ ```bash
73
+ superwall entitlements list --project <id> --json
74
+ superwall entitlements create pro --project <id> --json
75
+ ```
76
+
77
+ Default to a single coarse `pro` entitlement. Add more only for genuine tiers (e.g. `pro`,
78
+ `team`). Products grant entitlements via `--entitlement` at create time.
79
+
80
+ ## Campaigns + placements
81
+
82
+ ```bash
83
+ superwall campaigns list --project <id> --app <id> --json
84
+ superwall campaigns create "Onboarding" onboarding_complete --project <id> --app <id> --json
85
+ superwall campaigns placement <campaignId> another_placement --project <id> --app <id> --json
86
+ ```
87
+
88
+ - `create` takes a **description**, not an identifier - name it for the surface.
89
+ - A campaign can carry several related placements; call `campaigns placement` once per placement.
90
+ - Adding a placement that's already on the campaign is safe to skip - list first.
91
+
92
+ ## What the CLI cannot do (leave manual)
93
+
94
+ - **Design the paywall** - either as code with the superwall framework (`superwall create` scaffolds
95
+ a `superwall/` directory in the app; products are declared in the paywall's `config.ts`;
96
+ `superwall publish` ships it) or in the dashboard's paywall editor.
97
+ `superwall paywalls list --project <id> --app <id> --json` shows what exists.
98
+ - **Configure audiences / experiment splits** beyond the default - done in the dashboard.
99
+
100
+ Report these as the remaining manual steps.
@@ -0,0 +1,292 @@
1
+ # Integrate Superwall - Android / Kotlin
2
+
3
+ You are integrating Superwall into a native Android app (Jetpack Compose or
4
+ Views). Get the SDK installed and configured cleanly. **Do not add paywall
5
+ triggers (`register`)**; that is the separate **superwall-placements** skill.
6
+
7
+ ## Checklist
8
+
9
+ Work top to bottom. Steps 1-4 are this skill; 5-6 verify; 7 is the hand-off list.
10
+
11
+ - [ ] **0. Decide the purchase-handling path** (default / RevenueCat / custom) - it changes what you write in steps 2 & 4.
12
+ - [ ] **1. Install** `com.superwall.sdk:superwall-android` via Gradle in the app module.
13
+ - [ ] **2. Configure** once in `Application.onCreate()` with the public `pk_` key.
14
+ - [ ] **3. API key** handled correctly (public key, not a secret; follow existing config pattern).
15
+ - [ ] **4. Purchase handling** wired for the chosen path.
16
+ - [ ] **5. Build** - `./gradlew :app:assembleDebug` compiles with the SDK resolved.
17
+ - [ ] **6. Run** - Logcat shows Superwall SDK startup; a license-tested account or test mode in place if testing purchases.
18
+ - [ ] **7. Post-integration** (identity, attributes, subscription state, deep links, analytics) - see the final section; wire what the app needs, then move to **superwall-placements**.
19
+
20
+ ## Docs access - read the current page when baked steps aren't enough
21
+
22
+ Superwall's docs are fetchable **as markdown**. When a step below is ambiguous or
23
+ you need current detail, fetch the page rather than guessing:
24
+
25
+ ```bash
26
+ curl -sL https://superwall.com/docs/android/llms.txt # index: every Android doc path
27
+ curl -sL https://superwall.com/docs/llms-full.txt # broad context across all SDKs
28
+ curl -sL https://superwall.com/docs/android/quickstart/install.md # any page + ".md"
29
+ ```
30
+
31
+ Pattern: fetch `android/llms.txt` to find the slug, then fetch
32
+ `https://superwall.com/docs/android/{path}.md`. Every `curl` in this file is
33
+ verified working. **Never invent an API** - if a symbol isn't in this reference
34
+ or a page you fetched, fetch the page and confirm.
35
+
36
+ ## Quickstart walk
37
+
38
+ | Order | Slug | Covered by |
39
+ | ----- | ------------------------------------------------ | ----------------------------------------- |
40
+ | 1 | `android/quickstart/install` | Step 1 here |
41
+ | 2 | `android/quickstart/configure` | Step 2 here |
42
+ | 3 | `android/quickstart/feature-gating` | **superwall-placements** skill (not here) |
43
+ | 4 | `android/quickstart/in-app-paywall-previews` | placements / QA (deep link setup) |
44
+ | 5 | `android/quickstart/setting-user-properties` | Step 7 here |
45
+ | 6 | `android/quickstart/tracking-subscription-state` | Step 7 here |
46
+ | 7 | `android/quickstart/user-management` | Step 7 here |
47
+
48
+ ## Step 0 - Purchase-handling path (decide first)
49
+
50
+ > **Important:** This choice determines whether you pass a `PurchaseController`
51
+ > and whether _you_ must keep `subscriptionStatus` in sync. Paths (b) and (c)
52
+ > require manual subscription-status management; path (a) does not.
53
+
54
+ - **(a) Default - Superwall handles Google Play Billing.** No existing IAP code.
55
+ Recommended, zero purchase code. Superwall manages purchases, restores, and
56
+ subscription status. Use this unless the app already has a billing SDK.
57
+ - **(b) RevenueCat stays the source of truth.** The app already uses RevenueCat
58
+ (`com.revenuecat.purchases`). Keep RC as the purchase controller and sync its
59
+ `CustomerInfo` into Superwall, or put RevenueCat in observer mode. Follow
60
+ `curl -sL https://superwall.com/docs/android/guides/using-revenuecat.md`.
61
+ - **(c) Custom `PurchaseController`.** The app has its own Play Billing stack.
62
+ Implement `PurchaseController` and drive `subscriptionStatus` yourself.
63
+
64
+ For a full migration off another SDK, use the **superwall-migrate** skill.
65
+
66
+ ## Step 1 - Install
67
+
68
+ The artifact is **`com.superwall.sdk:superwall-android`**. Take the version from
69
+ the releases page rather than this file (it moves):
70
+ `https://github.com/superwall/Superwall-Android/releases`.
71
+
72
+ ```bash
73
+ curl -sL https://superwall.com/docs/android/quickstart/install.md
74
+ ```
75
+
76
+ Add it to the **app module** (the one whose `build.gradle(.kts)` applies
77
+ `com.android.application`), using the form the project already uses:
78
+
79
+ ```kotlin
80
+ // app/build.gradle.kts
81
+ dependencies {
82
+ implementation("com.superwall.sdk:superwall-android:<latest>")
83
+ }
84
+ ```
85
+
86
+ ```groovy
87
+ // app/build.gradle
88
+ implementation "com.superwall.sdk:superwall-android:<latest>"
89
+ ```
90
+
91
+ ```toml
92
+ # gradle/libs.versions.toml, when the project uses a version catalog
93
+ [libraries]
94
+ superwall-android = { group = "com.superwall.sdk", name = "superwall-android", version = "<latest>" }
95
+ ```
96
+
97
+ Then sync. `minSdk` must be 23 or higher on SDK 2.8.0+ (21 on older releases;
98
+ the install page and changelog say which); the SDK also brings Play Billing 9,
99
+ so any other billing library in the app must support it. Keep `INTERNET` in the manifest (it is there for
100
+ virtually every app already).
101
+
102
+ ## Step 2 - Configure
103
+
104
+ Configure once, in the `Application` subclass's `onCreate()`, before any
105
+ Activity needs a paywall. If the app has no `Application` subclass, add one and
106
+ declare it with `android:name` in `AndroidManifest.xml`.
107
+
108
+ ```bash
109
+ curl -sL https://superwall.com/docs/android/quickstart/configure.md
110
+ ```
111
+
112
+ ```kotlin
113
+ // MainApplication.kt
114
+ import android.app.Application
115
+ import com.superwall.sdk.Superwall
116
+
117
+ class MainApplication : Application() {
118
+ override fun onCreate() {
119
+ super.onCreate()
120
+ Superwall.configure(this, "pk_YOUR_PUBLIC_KEY")
121
+ }
122
+ }
123
+ ```
124
+
125
+ ```xml
126
+ <!-- AndroidManifest.xml -->
127
+ <application android:name=".MainApplication" ...>
128
+ ```
129
+
130
+ The DSL form takes options and a purchase controller:
131
+
132
+ ```kotlin
133
+ configureSuperwall("pk_YOUR_PUBLIC_KEY") {
134
+ purchaseController = MyPurchaseController(this@MainApplication)
135
+ options = SuperwallOptions().apply { /* paywalls, logging, … */ }
136
+ }
137
+ ```
138
+
139
+ Compose apps configure in the same place: `Application.onCreate()`, never inside
140
+ a composable or an Activity's `setContent`.
141
+
142
+ ## Step 3 - API key handling
143
+
144
+ Use the **Public API Key** (starts with `pk_`) from Dashboard ▸ Settings ▸ Keys.
145
+ It is not a secret; inlining it in `configure` is conventional. If the project
146
+ centralizes keys (`BuildConfig` fields from `local.properties`, a `Secrets`
147
+ object, product flavors), follow that pattern. **Never** use a secret/server key
148
+ here and never commit one.
149
+
150
+ ## Step 4 - Purchase handling (implements Step 0's choice)
151
+
152
+ ### (a) Default
153
+
154
+ Nothing extra. `Superwall.configure(context, apiKey)` with no
155
+ `purchaseController` means Superwall manages purchases, restores, and
156
+ subscription status through Google Play Billing.
157
+
158
+ ### (b) RevenueCat
159
+
160
+ Create an `RCPurchaseController : PurchaseController` that forwards `purchase` to
161
+ RevenueCat and `restorePurchases` to `Purchases.sharedInstance.restorePurchases`,
162
+ then sync entitlements from RevenueCat's customer info into
163
+ `Superwall.instance.setSubscriptionStatus(...)`:
164
+
165
+ ```kotlin
166
+ val purchaseController = RCPurchaseController(this)
167
+ Superwall.configure(this, "pk_YOUR_PUBLIC_KEY", purchaseController)
168
+ purchaseController.syncSubscriptionStatus()
169
+ ```
170
+
171
+ > **Important:** Copy the full `RCPurchaseController` from the doc - do not hand-roll it.
172
+ > `curl -sL https://superwall.com/docs/android/guides/using-revenuecat.md`
173
+ > The same page describes observer mode (`PurchasesAreCompletedBy`) as the
174
+ > recommended alternative when the app does not need to own purchasing.
175
+
176
+ ### (c) Custom `PurchaseController`
177
+
178
+ ```bash
179
+ curl -sL https://superwall.com/docs/android/guides/advanced-configuration.md
180
+ ```
181
+
182
+ ```kotlin
183
+ import android.app.Activity
184
+ import android.content.Context
185
+ import com.superwall.sdk.delegate.PurchaseResult
186
+ import com.superwall.sdk.delegate.RestorationResult
187
+ import com.superwall.sdk.delegate.subscription_controller.PurchaseController
188
+ import com.superwall.sdk.store.abstractions.product.StoreProduct
189
+
190
+ class MyPurchaseController(val context: Context) : PurchaseController {
191
+ override suspend fun purchase(
192
+ activity: Activity,
193
+ product: StoreProduct,
194
+ basePlanId: String?,
195
+ offerId: String?,
196
+ ): PurchaseResult {
197
+ // Purchase via Play Billing / your billing system, then return one of:
198
+ return PurchaseResult.Purchased() // Cancelled(), Pending(), Failed(message)
199
+ }
200
+
201
+ override suspend fun restorePurchases(): RestorationResult {
202
+ return RestorationResult.Restored() // Failed(error)
203
+ }
204
+ }
205
+
206
+ Superwall.configure(this, "pk_YOUR_PUBLIC_KEY", MyPurchaseController(this))
207
+ ```
208
+
209
+ > **Important (paths b & c):** With a `PurchaseController` you **must** call
210
+ > `Superwall.instance.setSubscriptionStatus(...)` whenever entitlements change.
211
+ > Cases: `SubscriptionStatus.Unknown` (default - paywalls wait),
212
+ > `SubscriptionStatus.Active(entitlements)` (a `Set<Entitlement>`),
213
+ > `SubscriptionStatus.Inactive`. Leaving it `Unknown` means paywalls never present.
214
+
215
+ ```kotlin
216
+ Superwall.instance.setSubscriptionStatus(SubscriptionStatus.Active(entitlements))
217
+ Superwall.instance.setSubscriptionStatus(SubscriptionStatus.Inactive)
218
+ ```
219
+
220
+ ## Step 5 & 6 - Verify
221
+
222
+ 1. **Build:** `./gradlew :app:assembleDebug` (use the module name the project has).
223
+ Must compile with the SDK resolved; a version catalog typo shows up here.
224
+ 2. **Run** on an emulator or device; Logcat (filter `Superwall`) logs SDK startup.
225
+ To confirm the key, temporarily set `SuperwallOptions().logging.level` to
226
+ debug and look for a successful config fetch.
227
+ 3. **Purchases without Play Console products** - test mode simulates purchases
228
+ end to end: `curl -sL https://superwall.com/docs/android/guides/test-mode.md`.
229
+ Real Play Billing needs the app in a Play track with a license-tester account
230
+ and product IDs that match the paywall's products.
231
+
232
+ ## Step 7 - Post-integration (wire what the app needs, then → placements)
233
+
234
+ Do the ones the app requires. Each has a fetchable page.
235
+
236
+ - **User identity - REQUIRED if the app has ANY auth/login system.** Not optional:
237
+ without it every logged-in user is anonymous to Superwall, breaking user-scoped
238
+ audiences, attribution, and cross-device status. Wire it the moment you see a
239
+ login/logout flow (grep for signIn/login/logout/signOut/auth). Call
240
+ `Superwall.instance.identify(userId)` on login, `Superwall.instance.reset()` on
241
+ logout. The `userId` must not be an email, a device id, or guessable. Superwall
242
+ SHA-256 hashes it before passing it to Play as the obfuscated account id;
243
+ `SuperwallOptions().passIdentifiersToPlayStore = true` sends it raw.
244
+ `curl -sL https://superwall.com/docs/android/quickstart/user-management.md`
245
+ ```kotlin
246
+ Superwall.instance.identify(user.id)
247
+ Superwall.instance.reset() // on sign-out
248
+ ```
249
+ - **User attributes** - target audiences / fill paywall variables.
250
+ `curl -sL https://superwall.com/docs/android/quickstart/setting-user-properties.md`
251
+ ```kotlin
252
+ Superwall.instance.setUserAttributes(mapOf("email" to user.email, "plan" to "trial"))
253
+ Superwall.instance.setUserAttributes(mapOf("plan" to null)) // unset a key
254
+ ```
255
+ - **Tracking subscription state** - `Superwall.instance.subscriptionStatus` is a
256
+ `StateFlow<SubscriptionStatus>`; read `.value` or `collect` it in a
257
+ `lifecycleScope`. Cases: `Active(entitlements)`, `Inactive`, `Unknown`.
258
+ `curl -sL https://superwall.com/docs/android/quickstart/tracking-subscription-state.md`
259
+ - **Deep links** - pass incoming URIs (from `intent.data` in `onCreate` /
260
+ `onNewIntent`) to `Superwall.instance.handleDeepLink(intent.data.toString())` —
261
+ the Android signature takes the URL as a `String`; it fires the
262
+ `deepLink_open` placement so routing is dashboard-driven. Needs an intent
263
+ filter for the scheme / App Link first.
264
+ `curl -sL https://superwall.com/docs/android/guides/handling-deep-links.md`
265
+ `curl -sL https://superwall.com/docs/android/quickstart/in-app-paywall-previews.md`
266
+ - **Delegate and 3rd-party analytics** - `Superwall.instance.delegate = …`
267
+ implementing `SuperwallDelegate`; `handleSuperwallEvent` forwards events,
268
+ `subscriptionStatusDidChange`, `handleCustomPaywallAction`.
269
+ `curl -sL https://superwall.com/docs/android/guides/using-superwall-delegate.md`
270
+
271
+ ## Pitfalls
272
+
273
+ - **Configured in an Activity instead of `Application.onCreate()`** → paywalls
274
+ configured late or more than once; the first `register` calls are dropped.
275
+ - **Wrong module** → the dependency added to a library module or the root
276
+ `build.gradle`; it belongs to the app module (or the catalog plus the app module).
277
+ - **Configured but paywalls never show** → `subscriptionStatus` stuck at `Unknown`
278
+ (only when you use a `PurchaseController` - you must set it), or no placement yet
279
+ (that's the placements skill).
280
+ - **ProGuard / R8 stripping** → the SDK ships consumer rules (per the changelog); if minified builds
281
+ fail, confirm nothing strips `com.superwall.sdk` before adding rules.
282
+ - **Secret key** → the key must start with `pk_`; a secret key fails config.
283
+
284
+ ## Deeper docs
285
+
286
+ - Index: `curl -sL https://superwall.com/docs/android/llms.txt`
287
+ - Install: https://superwall.com/docs/android/quickstart/install
288
+ - Configure: https://superwall.com/docs/android/quickstart/configure
289
+ - Advanced purchasing / PurchaseController: https://superwall.com/docs/android/guides/advanced-configuration
290
+ - Using RevenueCat: https://superwall.com/docs/android/guides/using-revenuecat
291
+ - Test mode: https://superwall.com/docs/android/guides/test-mode
292
+ - SDK reference: https://superwall.com/docs/android/sdk-reference/Superwall