@superwall/cli 1.4.0 → 1.6.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (103) hide show
  1. package/README.md +21 -5
  2. package/dist/{actions-EfP8phmb.js → actions-Dt35nIi8.js} +3 -2
  3. package/dist/{api-CEwXCCoC.js → api-BOR-uXZe.js} +9 -9
  4. package/dist/{app-D8mEVlQo.js → app-BU27SLPX.js} +9 -9
  5. package/dist/{asa-BFWehnTA.js → asa-2ykGnjaV.js} +11 -11
  6. package/dist/{asc-DJqQmtmR.js → asc-r3xmFT0L.js} +14 -14
  7. package/dist/{auth-CT2DWX8r.js → auth-BWZfguI8.js} +9 -9
  8. package/dist/auth.js +2 -2
  9. package/dist/{billing-BzEnVPD2.js → billing-BsQgXXYh.js} +1 -1
  10. package/dist/{bind-BZxVyt9P.js → bind-BSTAinn6.js} +5 -4
  11. package/dist/{command-DP96_gmP.js → command-DMoMn7uc.js} +39 -16
  12. package/dist/{create-Q8TqqjZt.js → create-CSo6XjSm.js} +118 -91
  13. package/dist/dev-B0MF6z3L.js +21 -0
  14. package/dist/{dev-DlCcwFu5.js → dev-CuXa3J4Z.js} +29 -24
  15. package/dist/{doctor-CJsjHpCZ.js → doctor-DXJaDqsx.js} +10 -10
  16. package/dist/{drivers-UT36AnOw.js → drivers-Cr252DOJ.js} +3 -3
  17. package/dist/entry.js +84 -50
  18. package/dist/{existing-Cak1WxWB.js → existing-Ckx_g7Be.js} +6 -3
  19. package/dist/{feedback-DDRzoqPx.js → feedback-Dt5yebMS.js} +6 -6
  20. package/dist/{hosted-CEH78QVn.js → hosted-Cjekn8oJ.js} +2 -2
  21. package/dist/{integrate-D8jyhDzk.js → integrate-DVqhvPVq.js} +25 -66
  22. package/dist/{login-kneYhhk0.js → login-Bjj8QvIN.js} +6 -6
  23. package/dist/migrate-qmvOtp3l.js +283 -0
  24. package/dist/open-studio-CpHqjovS.js +1299 -0
  25. package/dist/{org-Cg25bcsj.js → org-CV8c849b.js} +3 -3
  26. package/dist/{output-csAtR6kJ.js → output-CiELrN8w.js} +15 -2
  27. package/dist/{pipeline-DAeI9tHs.js → pipeline-DSCHL9KA.js} +482 -9
  28. package/dist/{print-skill-BHVPP9cX.js → print-skill-CaHRJ8xW.js} +7 -7
  29. package/dist/{promote-Boek5K2d.js → promote-UMTh8Q33.js} +17 -18
  30. package/dist/publish-DWX8S9yZ.js +34 -0
  31. package/dist/push-Dox4_5Dq.js +34 -0
  32. package/dist/{query-B8G6T8Ba.js → query-CnSsDZ7Q.js} +10 -10
  33. package/dist/reports-C0xHCLnt.js +27 -0
  34. package/dist/{resource-DjsWVka-.js → resource-5bgyyL9B.js} +15 -15
  35. package/dist/{resources-s64mBHaC.js → resources-Bf9O1JNM.js} +28 -2
  36. package/dist/{run-BtcQJCP8.js → run-BVeZWbXx.js} +39 -22
  37. package/dist/{scan-DJixvuHn.js → scan-CAObNRgc.js} +44 -4
  38. package/dist/skills/superwall/SKILL.md +146 -0
  39. package/dist/skills/superwall/references/api.md +275 -0
  40. package/dist/skills/superwall/references/asa.md +160 -0
  41. package/dist/skills/superwall/references/asc.md +96 -0
  42. package/dist/skills/superwall/references/dashboard-links.md +57 -0
  43. package/dist/skills/superwall/references/data-analytics.md +893 -0
  44. package/dist/skills/superwall/references/docs.md +51 -0
  45. package/dist/skills/superwall/references/sdk-integration.md +105 -0
  46. package/dist/skills/superwall/references/sdk-source.md +18 -0
  47. package/{skills/superwall-dashboard/SKILL.md → dist/skills/superwall/workflows/dashboard/playbook.md} +3 -9
  48. package/{skills/superwall-dashboard/references → dist/skills/superwall/workflows/dashboard}/setup.md +1 -3
  49. package/dist/skills/superwall/workflows/integrate/android.md +292 -0
  50. package/{skills/superwall-integrate/SKILL.md → dist/skills/superwall/workflows/integrate/playbook.md} +16 -11
  51. package/{skills/superwall-migrate/references → dist/skills/superwall/workflows/migrate}/adapty.md +4 -4
  52. package/{skills/superwall-migrate/SKILL.md → dist/skills/superwall/workflows/migrate/playbook.md} +4 -10
  53. package/{skills/superwall-migrate/references → dist/skills/superwall/workflows/migrate}/qonversion.md +4 -4
  54. package/{skills/superwall-migrate/references → dist/skills/superwall/workflows/migrate}/revenuecat.md +4 -4
  55. package/dist/skills/superwall/workflows/placements/android.md +175 -0
  56. package/{skills/superwall-placements/references → dist/skills/superwall/workflows/placements}/expo.md +1 -1
  57. package/{skills/superwall-placements/references → dist/skills/superwall/workflows/placements}/flutter.md +1 -1
  58. package/{skills/superwall-placements/references → dist/skills/superwall/workflows/placements}/ios.md +1 -1
  59. package/{skills/superwall-placements/SKILL.md → dist/skills/superwall/workflows/placements/playbook.md} +6 -10
  60. package/{skills/superwall-placements/references → dist/skills/superwall/workflows/placements}/react-native.md +2 -2
  61. package/{skills/superwall-placements/references → dist/skills/superwall/workflows/placements}/strategy.md +4 -3
  62. package/dist/skills/superwall/workflows/review/android.md +120 -0
  63. package/{skills/superwall-review/references → dist/skills/superwall/workflows/review}/expo.md +1 -1
  64. package/{skills/superwall-review/references → dist/skills/superwall/workflows/review}/flutter.md +1 -1
  65. package/{skills/superwall-review/references → dist/skills/superwall/workflows/review}/ios.md +1 -1
  66. package/{skills/superwall-review/SKILL.md → dist/skills/superwall/workflows/review/playbook.md} +2 -7
  67. package/{skills/superwall-review/references → dist/skills/superwall/workflows/review}/react-native.md +1 -1
  68. package/dist/skills/superwall-framework/SKILL.md +253 -0
  69. package/dist/skills/superwall-framework/references/cli.md +340 -0
  70. package/dist/skills/superwall-framework/references/examples.md +123 -0
  71. package/dist/skills/superwall-framework/references/layout.md +295 -0
  72. package/dist/skills/superwall-framework/references/migrate-from-editor.md +208 -0
  73. package/dist/skills/superwall-framework/references/migrate-from-native.md +193 -0
  74. package/dist/skills/superwall-framework/references/mobile-design.md +371 -0
  75. package/dist/skills/superwall-framework/references/native/android.md +83 -0
  76. package/dist/skills/superwall-framework/references/native/flutter.md +65 -0
  77. package/dist/skills/superwall-framework/references/native/ios.md +77 -0
  78. package/dist/skills/superwall-framework/references/native/react-native.md +67 -0
  79. package/dist/skills/superwall-framework/references/responsive.md +162 -0
  80. package/dist/{skills-CRG1xk0G.js → skills-Cu41i-Az.js} +12 -12
  81. package/dist/{skills-CODut1Hn.js → skills-grTDuHlc.js} +134 -36
  82. package/dist/{spinner-B9dT3DBY.js → spinner-DFctF_Jw.js} +1 -1
  83. package/dist/{telemetry-BtkMdT-5.js → telemetry-BuCbmoux.js} +3 -3
  84. package/dist/{token-hM7V1KMG.js → token-mju3Q-vc.js} +3 -3
  85. package/dist/{ui-Lqt_zFOr.js → ui-4gLyfrgl.js} +76 -46
  86. package/dist/{update-CeylIjx5.js → update-DnGfpCD7.js} +2 -2
  87. package/dist/{upgrade-DRqUfCBT.js → upgrade-PMoj3yqJ.js} +6 -6
  88. package/package.json +8 -7
  89. package/prompts/actions/paywall-migrate.xml +24 -0
  90. package/prompts/actions/screen-migrate.xml +26 -0
  91. package/dist/git-ZwA3Mx8m.js +0 -433
  92. package/dist/migrate-D_x1oyTk.js +0 -114
  93. package/dist/publish-C-zEUnO9.js +0 -35
  94. package/dist/push-DUDQG-EO.js +0 -35
  95. package/skills/README.md +0 -118
  96. /package/dist/{api-output-D9ggXQIr.js → api-output-CEhN-U_N.js} +0 -0
  97. /package/dist/{asc-products-C6MvSy8H.js → asc-products-1e1DoGeL.js} +0 -0
  98. /package/dist/{params-B1zeElGa.js → params-BxgTuCzr.js} +0 -0
  99. /package/{skills/superwall-integrate/references → dist/skills/superwall/workflows/integrate}/expo.md +0 -0
  100. /package/{skills/superwall-integrate/references → dist/skills/superwall/workflows/integrate}/flutter.md +0 -0
  101. /package/{skills/superwall-integrate/references → dist/skills/superwall/workflows/integrate}/ios.md +0 -0
  102. /package/{skills/superwall-integrate/references → dist/skills/superwall/workflows/integrate}/react-native.md +0 -0
  103. /package/dist/{storekit-DPonXSwe.js → storekit-Dlpbq5Wv.js} +0 -0
@@ -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 [references/dashboard-links.md](references/dashboard-links.md).
29
+
30
+ ---
31
+
32
+ ## SDK Source (for debugging)
33
+
34
+ Clone SDK repos locally to trace internal behavior. See [references/sdk-source.md](references/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,105 @@
1
+ # SDK Integration
2
+
3
+ **Fastest path:** agents run `superwall integrate --skill` and follow the printed
4
+ framework-specific playbook directly. Humans can run `superwall integrate`, which
5
+ orchestrates a headless agent and dashboard setup. The steps below are the manual
6
+ doc-walking path for when neither fits.
7
+
8
+ ## Integration checklist
9
+
10
+ Copy this checklist to track progress:
11
+
12
+ ```
13
+ - [ ] Detect platform ({sdk})
14
+ - [ ] Determine purchase controller path (default / RevenueCat / custom)
15
+ - [ ] Install SDK dependency
16
+ - [ ] Configure Superwall at app launch
17
+ - [ ] User management (identify / reset)
18
+ - [ ] Feature gating (register placements)
19
+ - [ ] Track subscription state
20
+ - [ ] Set user properties
21
+ - [ ] In-app paywall previews (deep links)
22
+ - [ ] Post-integration: deep links, analytics, feature gating audit
23
+ ```
24
+
25
+ ## Step 1: Detect the platform
26
+
27
+ Examine the user's project to determine the SDK. Use the first match:
28
+
29
+ | Signal | SDK value |
30
+ |--------|-----------|
31
+ | `pubspec.yaml` present, Dart code | `flutter` |
32
+ | `app.json` or `app.config.js` with `expo` field | `expo` |
33
+ | `*.xcodeproj` or `Package.swift`, Swift/ObjC code | `ios` |
34
+ | `build.gradle` or `build.gradle.kts`, Kotlin/Java code | `android` |
35
+ | `react-native` in `package.json` without Expo | `expo` - the standalone RN SDK is deprecated; bare RN uses `expo-superwall` via `npx install-expo-modules` (RN 0.79+) |
36
+
37
+ Store the result as `{sdk}` - it is used in every doc URL below.
38
+
39
+ ## Step 2: Determine the purchase controller path
40
+
41
+ Ask the user (or infer from their codebase) which applies:
42
+
43
+ 1. **No existing purchase system** - New to IAP or wants Superwall to handle everything.
44
+ → **Default (no PurchaseController)**. Superwall manages purchases, restoration, and subscription tracking automatically.
45
+
46
+ 2. **Using RevenueCat** - RevenueCat SDK is present in the project.
47
+ → **RevenueCat integration**. Follow the RevenueCat guide instead of the default configure step.
48
+ `curl -sL https://superwall.com/docs/{sdk}/guides/using-revenuecat.md`
49
+
50
+ 3. **Using another billing SDK or custom purchase logic** - Qonversion, Adapty, proprietary server-side billing, etc.
51
+ → **Custom PurchaseController**. User must implement `PurchaseController` and manually set `subscriptionStatus`.
52
+ `curl -sL https://superwall.com/docs/{sdk}/guides/advanced-configuration.md`
53
+ `curl -sL https://superwall.com/docs/{sdk}/sdk-reference/PurchaseController.md`
54
+
55
+ > **Critical**: When a PurchaseController is used (paths 2 or 3), the user **must** also manually set `subscriptionStatus` on the Superwall instance.
56
+
57
+ ## Step 3: Execute the quickstart steps in order
58
+
59
+ Fetch each doc page with `curl -sL`, implement, verify, then move to the next.
60
+
61
+ **Doc URL pattern:**
62
+ ```
63
+ https://superwall.com/docs/{sdk}/quickstart/{slug}.md
64
+ ```
65
+
66
+ | # | Slug | What it covers |
67
+ |---|------|----------------|
68
+ | 1 | `install` | Add the SDK dependency to the project |
69
+ | 2 | `configure` | Initialize Superwall at app launch (apply purchase controller path from Step 2) |
70
+ | 3 | `user-management` | Identify users on sign-in, reset on logout |
71
+ | 4 | `feature-gating` | Register placements and present paywalls (page title: "Presenting Paywalls") |
72
+ | 5 | `tracking-subscription-state` | Observe subscription status changes in app code |
73
+ | 6 | `setting-user-properties` | Set custom user attributes for audience targeting |
74
+ | 7 | `in-app-paywall-previews` | Set up deep link handling for on-device paywall previews |
75
+
76
+ > Docs use `:::ios`, `:::android`, `:::flutter`, `:::expo` fences - use only the `{sdk}`-relevant code.
77
+
78
+ ## Step 4: Complete the integration
79
+
80
+ After the quickstart, walk through these remaining concerns:
81
+
82
+ - **Deep links**: Set up deep link handling for paywall previews and web checkout redemption.
83
+ `curl -sL https://superwall.com/docs/{sdk}/guides/handling-deep-links.md`
84
+
85
+ - **User identity**: Ensure `identify(userId:)` is called on sign-in with a stable, non-guessable user ID (UUID recommended). Call `reset()` on logout.
86
+
87
+ - **Feature gating audit**: Review which features should be paywalled. Register a placement for each, then configure gating rules in the Superwall dashboard.
88
+
89
+ - **User attributes**: Set custom attributes (name, plan type, cohort, etc.) for audience targeting and paywall personalization via `setUserAttributes()`.
90
+
91
+ - **3rd-party analytics** (offer if an analytics SDK is detected in the project): Forward Superwall events to their analytics tool via the SuperwallDelegate.
92
+ - Overview: `curl -sL https://superwall.com/docs/{sdk}/guides/3rd-party-analytics.md`
93
+ - Event list & forwarding: `curl -sL https://superwall.com/docs/{sdk}/guides/3rd-party-analytics/tracking-analytics.md`
94
+ - 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`
95
+ - `confirmAllAssignments()` - get all experiment/variant assignments on startup: `curl -sL https://superwall.com/docs/{sdk}/sdk-reference/confirmAllAssignments.md`
96
+
97
+ ## Advanced configuration docs
98
+
99
+ | Topic | URL |
100
+ |-------|-----|
101
+ | Purchases & subscription status | `https://superwall.com/docs/{sdk}/guides/advanced-configuration.md` |
102
+ | RevenueCat integration | `https://superwall.com/docs/{sdk}/guides/using-revenuecat.md` |
103
+ | PurchaseController reference | `https://superwall.com/docs/{sdk}/sdk-reference/PurchaseController.md` |
104
+ | SuperwallDelegate reference | `https://superwall.com/docs/{sdk}/sdk-reference/SuperwallDelegate.md` |
105
+ | 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
+ ```
@@ -1,8 +1,3 @@
1
- ---
2
- name: superwall-dashboard
3
- description: Set up the Superwall dashboard state required for placements to present paywalls. Creates entitlements, products with real pricing, and campaigns that carry each placement. Use after the SDK is integrated and placements are registered, or when a placement has no presenting campaign.
4
- ---
5
-
6
1
  # Set up the Superwall dashboard
7
2
 
8
3
  Turn an app whose code registers placements into a working dashboard: entitlement(s),
@@ -41,7 +36,7 @@ placement (in code) → campaign (routes it) → audience (who) → paywal
41
36
  `superwall entitlements create pro --project <id> --json`. Default to a single `pro` entitlement unless the
42
37
  app clearly has tiers.
43
38
  4. **Ensure products.** `superwall products list --project <id> --json` first. If none:
44
- - App Store Connect connected (`superwall asc keys list --json`) → import (see references/setup.md).
39
+ - App Store Connect connected (`superwall asc keys list --json`) → import (see `setup.md` beside this file).
45
40
  - Otherwise create with real pricing:
46
41
  `superwall products create pro_yearly --price 39.99 --period year --trial-days 7 --entitlement pro --project <id> --json`
47
42
  5. **Carry each placement.** `superwall campaigns list --project <id> --app <id> --json`. For each placement not already on
@@ -67,11 +62,10 @@ placement (in code) → campaign (routes it) → audience (who) → paywal
67
62
 
68
63
  - What already existed (ids).
69
64
  - What you created: entitlement, product ids, campaign ids, placements attached.
70
- - **Left manual:** paywall design - as code with the superwall framework (`superwall create` →
71
- `superwall publish`) or in the dashboard editor - attaching products to the paywall, and - if
65
+ - **Left manual:** paywall design in the dashboard editor, attaching products to the paywall, and - if
72
66
  products were created by hand - reconciling identifiers with App Store Connect / Google Play.
73
67
 
74
- See `references/setup.md` for the App Store Connect import path, `.storekit` generation, and pricing-flag reference.
68
+ See `setup.md` (beside this file) for the App Store Connect import path, `.storekit` generation, and pricing-flag reference.
75
69
 
76
70
  ## Docs access
77
71
 
@@ -92,9 +92,7 @@ superwall campaigns placement <campaignId> another_placement --project <id> --ap
92
92
 
93
93
  ## What the CLI cannot do (leave manual)
94
94
 
95
- - **Design the paywall** - either as code with the superwall framework (`superwall create` scaffolds
96
- a `superwall/` directory in the app; products are declared in the paywall's `config.ts`;
97
- `superwall publish` ships it) or in the dashboard's paywall editor.
95
+ - **Design the paywall** - in the dashboard's paywall editor.
98
96
  `superwall paywalls list --project <id> --app <id> --json` shows what exists.
99
97
  - **Configure audiences / experiment splits** beyond the default - done in the dashboard.
100
98
 
@@ -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
@@ -1,8 +1,3 @@
1
- ---
2
- name: superwall-integrate
3
- description: Install and configure the Superwall SDK in a mobile app for the first time. Supports iOS with SwiftUI or UIKit, Expo, bare React Native, and Flutter. Covers package installation, one configure call at launch, public API key handling, and purchase setup. Use superwall-placements to add paywall triggers.
4
- ---
5
-
6
1
  # Integrate the Superwall SDK
7
2
 
8
3
  Get Superwall installed and configured with the smallest, cleanest set of edits.
@@ -21,7 +16,7 @@ curl -sL https://superwall.com/docs/llms-full.txt # broad context across al
21
16
  curl -sL https://superwall.com/docs/{path}.md # any page as markdown (append .md)
22
17
  ```
23
18
 
24
- Each SDK also has its own index - `curl -sL https://superwall.com/docs/{ios|expo|react-native|flutter}/llms.txt`.
19
+ Each SDK also has its own index - `curl -sL https://superwall.com/docs/{ios|android|expo|react-native|flutter}/llms.txt`.
25
20
  Fetch the index to find the slug, then fetch `{path}.md`. Every reference file
26
21
  below embeds the exact `curl` at each step so you can pull current detail when the
27
22
  baked-in steps aren't enough. **Never invent an API** - if a symbol isn't in a
@@ -49,14 +44,15 @@ reference or a page you fetched, fetch and confirm.
49
44
 
50
45
  | Signal in the project | Framework | Read this reference |
51
46
  | ------------------------------------------------------------- | ------------------- | ---------------------------- |
52
- | `*.xcodeproj` / `Package.swift` / `*.swift`, no JS | iOS / Swift | `references/ios.md` |
53
- | `app.json`/`app.config.js` with an `expo` key, `expo` in deps | Expo | `references/expo.md` |
54
- | `package.json` with `react-native`, no `expo` config | React Native (bare) | `references/react-native.md` |
55
- | `pubspec.yaml` | Flutter | `references/flutter.md` |
47
+ | `*.xcodeproj` / `Package.swift` / `*.swift`, no JS | iOS / Swift | `ios.md` (beside this file) |
48
+ | `app.json`/`app.config.js` with an `expo` key, `expo` in deps | Expo | `expo.md` (beside this file) |
49
+ | `package.json` with `react-native`, no `expo` config | React Native (bare) | `react-native.md` (beside this file) |
50
+ | `pubspec.yaml` | Flutter | `flutter.md` (beside this file) |
51
+ | `build.gradle(.kts)` applying `com.android.application` | Android (Kotlin) | `android.md` (beside this file) |
56
52
 
57
53
  If both Expo and bare RN signals exist, treat it as **Expo**. If unsure, ask.
58
54
 
59
- 2. **Read `references/<framework>.md` and follow it exactly.** Each reference is a
55
+ 2. **Read `<framework>.md` beside this file and follow it exactly.** Each reference is a
60
56
  complete, verified playbook: install, configure, API key handling, verify,
61
57
  pitfalls, and doc links.
62
58
 
@@ -68,6 +64,15 @@ reference or a page you fetched, fetch and confirm.
68
64
  your source of truth. (For a full migration off another SDK, use the
69
65
  **superwall-migrate** skill.)
70
66
 
67
+ ## What else belongs in Superwall
68
+
69
+ While reading the app, note any screen the user would rather change
70
+ without a release: a paywall or offer, onboarding, an update-required or
71
+ force-upgrade screen, a rate-us or notifications prompt, an announcement,
72
+ a consent change. Mention them in your closing note as candidates for a
73
+ Superwall paywall or onboarding (built in the dashboard editor) behind a
74
+ placement. Don't build them here; the placements step wires the triggers.
75
+
71
76
  ## Definition of done
72
77
 
73
78
  1. SDK installed and resolving (pods/SPM/gradle/pub resolved).
@@ -3,7 +3,7 @@
3
3
  Definitive playbook. Read fully before editing. Superwall has no Adapty-specific
4
4
  "using-adapty" guide, so PAYWALLS-ONLY mode uses the **generic** `PurchaseController`
5
5
  (`/docs/ios/guides/advanced-configuration`) - mirror the RevenueCat controller shape in
6
- `references/revenuecat.md`, swapping RC calls for Adapty calls.
6
+ `revenuecat.md` (beside this file), swapping RC calls for Adapty calls.
7
7
 
8
8
  ## Scope & checklist
9
9
 
@@ -15,12 +15,12 @@ This migrates the **SDK integration**, not the whole product. Checklist:
15
15
  - [ ] Swap SDK calls (activate→configure, access-level reads, present → placement, identify) (§5)
16
16
  - [ ] Build + verify each placement; Restore Purchases as an existing subscriber (§7)
17
17
  - [ ] FULL only: remove Adapty dependency once verified
18
- - [ ] Hand back to user: **rebuild paywalls** (superwall framework or dashboard editor), attach products, connect ASC/Play
18
+ - [ ] Hand back to user: **rebuild paywalls** (dashboard editor), attach products, connect ASC/Play
19
19
 
20
20
  > **Important - what does NOT migrate:**
21
21
  >
22
22
  > - **Adapty paywall designs** (Paywall Builder / remote config) cannot be imported - they are
23
- > **rebuilt** - as code with the superwall framework or in the dashboard editor.
23
+ > **rebuilt** in the dashboard editor.
24
24
  > - **Historical analytics / attribution** stays in Adapty.
25
25
  > - **Subscriber base:** there is currently no server-side subscriber migration from Adapty.
26
26
  > Existing subscribers keep access because their purchases live with the store (StoreKit /
@@ -191,7 +191,7 @@ regardless) vs gated (only when entitled). Peek: `Superwall.shared.getPresentati
191
191
  ## 7. Order of operations + safety
192
192
 
193
193
  1. Re-create entitlements/products/campaign+placements (CLI); import products from ASC/Play so ids match.
194
- 2. **Rebuild** paywalls (superwall framework or dashboard editor), attach products (hand-back to user - designs do not import).
194
+ 2. **Rebuild** paywalls (dashboard editor), attach products (hand-back to user - designs do not import).
195
195
  3. Add Superwall SDK alongside Adapty; configure it.
196
196
  4. Replace `getPaywall`/present call sites with `register(placement:)`; replace access-level reads with `subscriptionStatus`.
197
197
  5. Build, present each placement, Restore Purchases as an existing subscriber, confirm `subscriptionStatus.isActive`.
@@ -1,14 +1,8 @@
1
- ---
2
- name: superwall-migrate
3
- description: Migrate a mobile app from RevenueCat, Adapty, or Qonversion to Superwall. Replaces provider SDK calls and recreates products, entitlements, campaigns, and placements. Subscriber access carries over via the stores (RevenueCat state can also be ported server-side), and paywall designs must be rebuilt. Use when replacing another paywall or billing SDK with Superwall. Not for first-time SDK setup in an app with no provider (superwall-integrate).
4
- ---
5
-
6
1
  # Migrate to Superwall
7
2
 
8
3
  > **Important - what does and does not migrate:**
9
4
  >
10
- > - Paywall designs are rebuilt from scratch - as code with the superwall framework
11
- > (`superwall create`) or in the dashboard editor.
5
+ > - Paywall designs are rebuilt from scratch in the dashboard editor.
12
6
  > - Historical analytics and attribution stay in the old provider.
13
7
  > - Adapty/Qonversion subscribers do not currently move server-side; existing
14
8
  > purchases are recovered from the store through Restore Purchases.
@@ -31,9 +25,9 @@ identity, register, and feature-gating pages before changing APIs.
31
25
 
32
26
  | Detect | Read fully |
33
27
  | ------------------------------------------------------------- | -------------------------- |
34
- | `RevenueCat`, `react-native-purchases`, `purchases_flutter` | `references/revenuecat.md` |
35
- | `Adapty`, `react-native-adapty`, `adapty_flutter` | `references/adapty.md` |
36
- | `Qonversion`, `react-native-qonversion`, `qonversion_flutter` | `references/qonversion.md` |
28
+ | `RevenueCat`, `react-native-purchases`, `purchases_flutter` | `revenuecat.md` (beside this file) |
29
+ | `Adapty`, `react-native-adapty`, `adapty_flutter` | `adapty.md` (beside this file) |
30
+ | `Qonversion`, `react-native-qonversion`, `qonversion_flutter` | `qonversion.md` (beside this file) |
37
31
 
38
32
  If several exist, identify which one owns purchases before proceeding.
39
33