@superwall/cli 1.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 (85) hide show
  1. package/LICENSE +21 -0
  2. package/README.md +201 -0
  3. package/dist/actions-MB-eBY64.js +140 -0
  4. package/dist/api-BF7-toqM.js +151 -0
  5. package/dist/api-output-B5hh0q4V.js +20 -0
  6. package/dist/app-K6j9Es7h.js +189 -0
  7. package/dist/asc-CArSwo5D.js +539 -0
  8. package/dist/asc-products-YQ6Oc6YO.js +93 -0
  9. package/dist/auth-CY2cO_NF.js +139 -0
  10. package/dist/auth.d.ts +30 -0
  11. package/dist/auth.js +4 -0
  12. package/dist/billing-DWyfEQ6l.js +80 -0
  13. package/dist/bind-hslFhcTR.js +213 -0
  14. package/dist/chunk-DQxbwPpZ.js +30 -0
  15. package/dist/command-Kwx4ekbo.js +283 -0
  16. package/dist/create-Bbi8BOO1.js +410 -0
  17. package/dist/dev-D0lQDCQI.js +397 -0
  18. package/dist/devtools-8EgLo86w.js +3638 -0
  19. package/dist/doctor-ByeRdMcl.js +88 -0
  20. package/dist/drivers-DVAZgone.js +413 -0
  21. package/dist/entry.d.ts +9 -0
  22. package/dist/entry.js +495 -0
  23. package/dist/existing-CcJrIIAU.js +88 -0
  24. package/dist/feedback-Z0Wk7VC5.js +73 -0
  25. package/dist/git-3OX9u3xE.js +433 -0
  26. package/dist/hosted-CHwaUqLd.js +32 -0
  27. package/dist/integrate-DqOAqK7J.js +863 -0
  28. package/dist/json-C3hPIMkI.js +7 -0
  29. package/dist/login-Dr8UN_Gx.js +290 -0
  30. package/dist/migrate-D92bJTg6.js +114 -0
  31. package/dist/org-B2gy9Pmu.js +40 -0
  32. package/dist/params-Bvq0iqQK.js +52 -0
  33. package/dist/pipeline-CHHIg6BU.js +1056 -0
  34. package/dist/print-skill-BnZAk7dV.js +74 -0
  35. package/dist/promote-CRe9170G.js +88 -0
  36. package/dist/publish-DsODvrOD.js +35 -0
  37. package/dist/push-BDkZUC0v.js +35 -0
  38. package/dist/query-DIllrSnk.js +53 -0
  39. package/dist/resource-CdP1MDla.js +483 -0
  40. package/dist/resources-CVrWwA1K.js +233 -0
  41. package/dist/run-cGGBUMs5.js +89 -0
  42. package/dist/scan-BQexuUPO.js +236 -0
  43. package/dist/skills-DhuUs28u.js +64 -0
  44. package/dist/skills-xrfXt9u0.js +205 -0
  45. package/dist/spawn-DSoTXy_j.js +69 -0
  46. package/dist/spinner-gOxIMz-V.js +18 -0
  47. package/dist/storekit-Ddvs4Ynw.js +29 -0
  48. package/dist/telemetry-CcfrtXdf.js +204 -0
  49. package/dist/token-DHRH8cxi.js +102 -0
  50. package/dist/ui-C4ncRJqd.js +27703 -0
  51. package/dist/update-BiVeR024.js +137 -0
  52. package/dist/upgrade-DYWspApv.js +72 -0
  53. package/package.json +87 -0
  54. package/prompts/actions/dashboard-setup.xml +10 -0
  55. package/prompts/actions/integrate.xml +5 -0
  56. package/prompts/actions/migrate.xml +11 -0
  57. package/prompts/actions/placements-implement.xml +20 -0
  58. package/prompts/actions/placements-review.xml +18 -0
  59. package/prompts/actions/review-fix.xml +18 -0
  60. package/prompts/actions/review.xml +18 -0
  61. package/prompts/commandments.xml +17 -0
  62. package/prompts/context.xml +9 -0
  63. package/skills/README.md +118 -0
  64. package/skills/superwall-dashboard/SKILL.md +81 -0
  65. package/skills/superwall-dashboard/references/setup.md +101 -0
  66. package/skills/superwall-integrate/SKILL.md +76 -0
  67. package/skills/superwall-integrate/references/expo.md +269 -0
  68. package/skills/superwall-integrate/references/flutter.md +285 -0
  69. package/skills/superwall-integrate/references/ios.md +314 -0
  70. package/skills/superwall-integrate/references/react-native.md +245 -0
  71. package/skills/superwall-migrate/SKILL.md +83 -0
  72. package/skills/superwall-migrate/references/adapty.md +229 -0
  73. package/skills/superwall-migrate/references/qonversion.md +227 -0
  74. package/skills/superwall-migrate/references/revenuecat.md +414 -0
  75. package/skills/superwall-placements/SKILL.md +73 -0
  76. package/skills/superwall-placements/references/expo.md +161 -0
  77. package/skills/superwall-placements/references/flutter.md +139 -0
  78. package/skills/superwall-placements/references/ios.md +165 -0
  79. package/skills/superwall-placements/references/react-native.md +145 -0
  80. package/skills/superwall-placements/references/strategy.md +221 -0
  81. package/skills/superwall-review/SKILL.md +75 -0
  82. package/skills/superwall-review/references/expo.md +100 -0
  83. package/skills/superwall-review/references/flutter.md +99 -0
  84. package/skills/superwall-review/references/ios.md +108 -0
  85. package/skills/superwall-review/references/react-native.md +100 -0
@@ -0,0 +1,285 @@
1
+ # Integrate Superwall - Flutter
2
+
3
+ You are integrating Superwall into a Flutter app using the
4
+ **`superwallkit_flutter`** package. Get it installed and configured. **Do not add
5
+ paywall triggers (`registerPlacement`)** - that is the separate
6
+ **superwall-placements** skill.
7
+
8
+ **Requirements:** iOS deployment target **14.0+**; Android **minSdkVersion 26**,
9
+ **compileSdk 34**, Gradle **8.6+**, Android Gradle Plugin **8.4+**.
10
+
11
+ ## Checklist
12
+
13
+ - [ ] **0. Decide the purchase-handling path** (default / RevenueCat / custom).
14
+ - [ ] **1. Install** `superwallkit_flutter`; set iOS/Android native minimums + Android activities.
15
+ - [ ] **2. Configure** once at launch with the platform's `pk_` key.
16
+ - [ ] **3. API keys** branched on `Platform.isIOS` (public keys, never secrets).
17
+ - [ ] **4. Purchase handling** for the chosen path.
18
+ - [ ] **5. Build** - `flutter run` on iOS sim + Android emulator; pods/gradle resolve.
19
+ - [ ] **6. Run** - console shows Superwall startup; StoreKit test config if testing purchases.
20
+ - [ ] **7. Post-integration** (identity, attributes, subscription state, deep links, analytics), then → **superwall-placements**.
21
+
22
+ ## Docs access - read the current page when baked steps aren't enough
23
+
24
+ ```bash
25
+ curl -sL https://superwall.com/docs/flutter/llms.txt # index: every Flutter doc path
26
+ curl -sL https://superwall.com/docs/llms-full.txt # broad context across all SDKs
27
+ curl -sL https://superwall.com/docs/flutter/quickstart/install.md # any page + ".md"
28
+ ```
29
+
30
+ Pattern: fetch `flutter/llms.txt` for the slug, then
31
+ `https://superwall.com/docs/flutter/{path}.md`. Every `curl` here is verified
32
+ working. **Never invent an API** - if a symbol isn't in this reference or a page you
33
+ fetched, fetch and confirm.
34
+
35
+ ## Quickstart walk
36
+
37
+ | Order | Slug | Covered by |
38
+ | ----- | ------------------------------------------------ | ------------------------------ |
39
+ | 1 | `flutter/quickstart/install` | Step 1 here |
40
+ | 2 | `flutter/quickstart/configure` | Step 2 here |
41
+ | 3 | `flutter/quickstart/feature-gating` | **superwall-placements** skill |
42
+ | 4 | `flutter/quickstart/in-app-paywall-previews` | placements / QA |
43
+ | 5 | `flutter/quickstart/setting-user-properties` | Step 7 here |
44
+ | 6 | `flutter/quickstart/tracking-subscription-state` | Step 7 here |
45
+ | 7 | `flutter/quickstart/user-management` | Step 7 here |
46
+
47
+ ## Step 0 - Purchase-handling path (decide first)
48
+
49
+ > **Important:** Paths (b)/(c) require you to keep `subscriptionStatus` in sync;
50
+ > path (a) does not.
51
+
52
+ - **(a) Default - Superwall handles StoreKit/Billing.** Recommended, zero purchase code.
53
+ - **(b) RevenueCat stays the source of truth.** Keep RC purchasing; sync entitlements in.
54
+ `curl -sL https://superwall.com/docs/flutter/guides/using-revenuecat.md`
55
+ - **(c) Custom `PurchaseController`.** Supply one, drive status.
56
+
57
+ Full migration off another SDK → **superwall-migrate** skill.
58
+
59
+ ## Step 1 - Install
60
+
61
+ Add the package (match the project's existing Flutter tooling):
62
+
63
+ ```bash
64
+ curl -sL https://superwall.com/docs/flutter/quickstart/install.md
65
+ flutter pub add superwallkit_flutter
66
+ ```
67
+
68
+ Or add `superwallkit_flutter` to `pubspec.yaml` under `dependencies:` (use the
69
+ latest version on pub.dev) then `flutter pub get`.
70
+
71
+ ### iOS native config
72
+
73
+ `ios/Podfile`:
74
+
75
+ ```ruby
76
+ platform :ios, '14.0'
77
+ ```
78
+
79
+ Then `cd ios && pod install` (or let the next `flutter run` install pods).
80
+
81
+ ### Android native config
82
+
83
+ `android/app/build.gradle`:
84
+
85
+ ```groovy
86
+ android {
87
+ compileSdkVersion 34
88
+ defaultConfig {
89
+ minSdkVersion 26
90
+ targetSdkVersion 34
91
+ }
92
+ }
93
+ ```
94
+
95
+ `android/build.gradle` - AGP 8.4+:
96
+
97
+ ```groovy
98
+ plugins { id 'com.android.application' version '8.4.1' apply false }
99
+ ```
100
+
101
+ `android/gradle/wrapper/gradle-wrapper.properties` - Gradle 8.6+:
102
+
103
+ ```properties
104
+ distributionUrl=https\://services.gradle.org/distributions/gradle-8.6-bin.zip
105
+ ```
106
+
107
+ > **Important:** Register Superwall's activities in the `<application>` tag of
108
+ > `android/app/src/main/AndroidManifest.xml`, or Android builds/paywalls fail:
109
+
110
+ ```xml
111
+ <activity
112
+ android:name="com.superwall.sdk.paywall.view.SuperwallPaywallActivity"
113
+ android:theme="@style/Theme.MaterialComponents.DayNight.NoActionBar"
114
+ android:configChanges="orientation|screenSize|keyboardHidden">
115
+ </activity>
116
+ <activity android:name="com.superwall.sdk.debug.DebugViewActivity" />
117
+ <activity android:name="com.superwall.sdk.debug.localizations.SWLocalizationActivity" />
118
+ <activity android:name="com.superwall.sdk.debug.SWConsoleActivity" />
119
+ ```
120
+
121
+ ## Step 2 - Configure
122
+
123
+ ```bash
124
+ curl -sL https://superwall.com/docs/flutter/quickstart/configure.md
125
+ ```
126
+
127
+ ```dart
128
+ import 'package:superwallkit_flutter/superwallkit_flutter.dart';
129
+ ```
130
+
131
+ Call `Superwall.configure` **once, at launch**, with the platform's public key.
132
+
133
+ **In `main()`** (call `WidgetsFlutterBinding.ensureInitialized()` first if you
134
+ configure before `runApp`):
135
+
136
+ ```dart
137
+ import 'dart:io' show Platform;
138
+ import 'package:flutter/material.dart';
139
+ import 'package:superwallkit_flutter/superwallkit_flutter.dart';
140
+
141
+ void main() {
142
+ WidgetsFlutterBinding.ensureInitialized();
143
+ final apiKey = Platform.isIOS ? "pk_YOUR_IOS_PUBLIC_KEY" : "pk_YOUR_ANDROID_PUBLIC_KEY";
144
+ Superwall.configure(apiKey);
145
+ runApp(const MyApp());
146
+ }
147
+ ```
148
+
149
+ **Or in a root widget's `initState()`:**
150
+
151
+ ```dart
152
+ @override
153
+ void initState() {
154
+ super.initState();
155
+ final apiKey = Platform.isIOS ? "pk_YOUR_IOS_PUBLIC_KEY" : "pk_YOUR_ANDROID_PUBLIC_KEY";
156
+ Superwall.configure(apiKey);
157
+ }
158
+ ```
159
+
160
+ Optional behavior goes through `SuperwallOptions` via the named `options:` argument:
161
+ `Superwall.configure("pk_...", options: options)`.
162
+
163
+ ## Step 3 - API key handling
164
+
165
+ Use the **Public API Key(s)** (`pk_…`) from Dashboard ▸ Settings ▸ Keys - iOS and
166
+ Android apps have separate keys, so branch on `Platform.isIOS`. Public keys aren't
167
+ secrets; inline them, or read from existing config (`--dart-define` /
168
+ `String.fromEnvironment`). **Never** use a secret key.
169
+
170
+ ## Step 4 - Purchase handling (implements Step 0's choice)
171
+
172
+ ### (a) Default
173
+
174
+ Just `Superwall.configure(apiKey)`. Superwall handles purchases, restores, and
175
+ subscription status.
176
+
177
+ ### (b) RevenueCat / (c) custom
178
+
179
+ Implement a `PurchaseController` and pass it in. Read the page first:
180
+
181
+ ```bash
182
+ curl -sL https://superwall.com/docs/flutter/guides/advanced-configuration.md
183
+ ```
184
+
185
+ ```dart
186
+ class MyPurchaseController extends PurchaseController {
187
+ @override
188
+ Future<PurchaseResult> purchaseFromAppStore(String productId) async {
189
+ // Purchase via StoreKit / RevenueCat / your billing system, then return:
190
+ return PurchaseResult.purchased;
191
+ }
192
+
193
+ @override
194
+ Future<PurchaseResult> purchaseFromGooglePlay(
195
+ String productId, String? basePlanId, String? offerId) async {
196
+ return PurchaseResult.purchased;
197
+ }
198
+
199
+ @override
200
+ Future<RestorationResult> restorePurchases() async {
201
+ return RestorationResult.restored;
202
+ }
203
+ }
204
+ ```
205
+
206
+ Pass it at configure time (**positional** second argument):
207
+
208
+ ```dart
209
+ Superwall.configure(apiKey, MyPurchaseController());
210
+ ```
211
+
212
+ > **Important (paths b & c):** keep subscription status synced whenever entitlements
213
+ > change:
214
+ >
215
+ > ```dart
216
+ > Superwall.shared.setSubscriptionStatus(
217
+ > SubscriptionStatusActive(entitlements: {Entitlement(id: "pro")}),
218
+ > );
219
+ > // or
220
+ > Superwall.shared.setSubscriptionStatus(SubscriptionStatusInactive());
221
+ > ```
222
+ >
223
+ > For (b), map RevenueCat's active entitlements into that call. Confirm the exact
224
+ > `configure` argument shape against the advanced-configuration page - some SDK
225
+ > versions differ.
226
+
227
+ ## Step 5 & 6 - Verify
228
+
229
+ 1. **Build & run:** `flutter run` on an iOS simulator and an Android emulator. Must
230
+ compile with pods/gradle resolved.
231
+ 2. Watch the console on launch for Superwall SDK startup. Raise verbosity via
232
+ `SuperwallOptions` logging if needed.
233
+ 3. For iOS purchase testing, read the StoreKit testing guide:
234
+ `curl -sL https://superwall.com/docs/flutter/guides/testing-purchases.md`
235
+
236
+ ## Step 7 - Post-integration (wire what the app needs, then → placements)
237
+
238
+ - **User identity - REQUIRED if the app has ANY auth/login system.** Not optional: without it every logged-in user is anonymous to Superwall, breaking user-scoped audiences, attribution, and cross-device status. Wire it the moment you see a login/logout flow (grep for signIn/login/logout/signOut/auth). `Superwall.shared.identify(user.id)` on login,
239
+ `Superwall.shared.reset()` on logout. `userId` should be a **UUID** (StoreKit
240
+ compat), never an email/device id/guessable value.
241
+ `curl -sL https://superwall.com/docs/flutter/quickstart/user-management.md`
242
+ ```dart
243
+ Superwall.shared.identify(user.id);
244
+ Superwall.shared.reset(); // on sign-out
245
+ ```
246
+ > **Use when** you need the unhashed `appUserId` to reach Google Play: set
247
+ > `SuperwallOptions()..passIdentifiersToPlayStore = true` and pass it via
248
+ > `identify(user.id, options: options)` (Android only).
249
+ - **User attributes** - `Superwall.shared.setUserAttributes(attributes)` (a
250
+ `Map<String, dynamic>`; merges, overwriting matching keys). The Flutter SDK does
251
+ **not** support deleting an attribute via `null`.
252
+ `curl -sL https://superwall.com/docs/flutter/quickstart/setting-user-properties.md`
253
+ - **Tracking subscription state** - read `Superwall.shared.subscriptionStatus`
254
+ (`.unknown` / `.active(entitlements)` / `.inactive`).
255
+ `curl -sL https://superwall.com/docs/flutter/quickstart/tracking-subscription-state.md`
256
+ - **Deep links** - pass incoming URLs to `Superwall.shared.handleDeepLink(url)`; it
257
+ fires the `deepLink_open` placement so routing is dashboard-driven.
258
+ `curl -sL https://superwall.com/docs/flutter/guides/handling-deep-links.md`
259
+ ```dart
260
+ Future<void> handleUrl(Uri url) async => Superwall.shared.handleDeepLink(url);
261
+ ```
262
+ - **3rd-party analytics** - forward Superwall events via the delegate.
263
+ `curl -sL https://superwall.com/docs/flutter/guides/3rd-party-analytics.md`
264
+
265
+ ## Pitfalls
266
+
267
+ - **Android build fails** → check minSdk 26 / compileSdk 34 / Gradle 8.6 / AGP 8.4,
268
+ and that the four Superwall activities are declared in `AndroidManifest.xml`.
269
+ - **iOS pod errors** → set `platform :ios, '14.0'` in the `Podfile`, then
270
+ `cd ios && pod install`.
271
+ - **Configuring before bindings ready** → call
272
+ `WidgetsFlutterBinding.ensureInitialized()` before `Superwall.configure` in `main()`.
273
+ - **Configured but paywalls never show** → with a `PurchaseController` you must set
274
+ `subscriptionStatus`; and no placement yet (that's the placements skill).
275
+ - **Secret key** → the key must start with `pk_` (public).
276
+
277
+ ## Deeper docs
278
+
279
+ - Index: `curl -sL https://superwall.com/docs/flutter/llms.txt`
280
+ - Install: https://superwall.com/docs/flutter/quickstart/install
281
+ - Configure: https://superwall.com/docs/flutter/quickstart/configure
282
+ - Advanced purchasing / PurchaseController: https://superwall.com/docs/flutter/guides/advanced-configuration
283
+ - Using RevenueCat: https://superwall.com/docs/flutter/guides/using-revenuecat
284
+ - Configuring (options): https://superwall.com/docs/flutter/guides/configuring
285
+ - StoreKit testing: https://superwall.com/docs/flutter/guides/testing-purchases
@@ -0,0 +1,314 @@
1
+ # Integrate Superwall - iOS / Swift
2
+
3
+ You are integrating Superwall into a native iOS app (SwiftUI or UIKit). Get the
4
+ SDK installed and configured cleanly. **Do not add paywall triggers (`register`)**;
5
+ 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** `SuperwallKit` via the manager the project already uses (SPM or CocoaPods).
13
+ - [ ] **2. Configure** once at launch 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** - compiles with `SuperwallKit` resolved.
17
+ - [ ] **6. Run** - console shows Superwall SDK startup; StoreKit test config 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/ios/llms.txt # index: every iOS doc path
27
+ curl -sL https://superwall.com/docs/llms-full.txt # broad context across all SDKs
28
+ curl -sL https://superwall.com/docs/ios/quickstart/install.md # any page + ".md"
29
+ ```
30
+
31
+ Pattern: fetch `ios/llms.txt` to find the slug, then fetch
32
+ `https://superwall.com/docs/ios/{path}.md`. Every `curl` in this file is verified
33
+ working. **Never invent an API** - if a symbol isn't in this reference or a page
34
+ you fetched, fetch the page and confirm.
35
+
36
+ ## Quickstart walk
37
+
38
+ The iOS quickstart is a sequence of pages. This reference mirrors it. Fetch any
39
+ page with the `curl` shown at that step.
40
+
41
+ | Order | Slug | Covered by |
42
+ | ----- | -------------------------------------------- | ----------------------------------------- |
43
+ | 1 | `ios/quickstart/install` | Step 1 here |
44
+ | 2 | `ios/quickstart/configure` | Step 2 here |
45
+ | 3 | `ios/quickstart/feature-gating` | **superwall-placements** skill (not here) |
46
+ | 4 | `ios/quickstart/in-app-paywall-previews` | placements / QA |
47
+ | 5 | `ios/quickstart/setting-user-properties` | Step 7 here |
48
+ | 6 | `ios/quickstart/tracking-subscription-state` | Step 7 here |
49
+ | 7 | `ios/quickstart/user-management` | Step 7 here |
50
+
51
+ ## Step 0 - Purchase-handling path (decide first)
52
+
53
+ > **Important:** This choice determines whether you pass a `PurchaseController`
54
+ > and whether _you_ must keep `subscriptionStatus` in sync. Paths (b) and (c)
55
+ > require manual subscription-status management; path (a) does not.
56
+
57
+ - **(a) Default - Superwall handles StoreKit.** No existing IAP code. Recommended,
58
+ zero purchase code. Superwall manages purchases, restores, and subscription
59
+ status. Use this unless the app already has a billing SDK.
60
+ - **(b) RevenueCat stays the source of truth.** The app already uses RevenueCat.
61
+ Keep RC as the purchase controller and sync its `CustomerInfo` into Superwall.
62
+ Follow `curl -sL https://superwall.com/docs/ios/guides/using-revenuecat.md`.
63
+ - **(c) Custom `PurchaseController`.** The app has its own StoreKit/billing stack.
64
+ Implement `PurchaseController` and drive `subscriptionStatus` yourself.
65
+
66
+ For a full migration off another SDK, use the **superwall-migrate** skill.
67
+
68
+ ## Step 1 - Install
69
+
70
+ The SDK product is **`SuperwallKit`** from `github.com/superwall/Superwall-iOS`.
71
+ Use the dependency manager the project already uses.
72
+
73
+ ```bash
74
+ curl -sL https://superwall.com/docs/ios/quickstart/install.md
75
+ ```
76
+
77
+ ### Swift Package Manager (preferred; detect `Package.swift` or existing SPM setup)
78
+
79
+ **Via Xcode UI:**
80
+
81
+ 1. File ▸ Add Package Dependencies…
82
+ 2. Paste `https://github.com/superwall/Superwall-iOS`.
83
+ 3. Dependency Rule: **Up to Next Major Version**, lower bound **`4.0.0`**.
84
+ 4. Add Package; confirm the **SuperwallKit** product is added to your app target.
85
+
86
+ **Via `Package.swift`** (SPM projects, and the safe route for an agent with Xcode closed):
87
+
88
+ ```swift
89
+ dependencies: [
90
+ .package(url: "https://github.com/superwall/Superwall-iOS", from: "4.0.0"),
91
+ ],
92
+ targets: [
93
+ .target(
94
+ name: "YourApp",
95
+ dependencies: [
96
+ .product(name: "SuperwallKit", package: "Superwall-iOS"),
97
+ ]
98
+ ),
99
+ ]
100
+ ```
101
+
102
+ **Editing `.pbxproj` directly** (agent, no Xcode): only if the project already has
103
+ SPM references to copy the exact `XCRemoteSwiftPackageReference` /
104
+ `XCSwiftPackageProductDependency` structure from; then
105
+ `xcodebuild -resolvePackageDependencies`. Otherwise instruct the user to add it via
106
+ the Xcode UI - safer than hand-editing.
107
+
108
+ ### CocoaPods (detect a `Podfile`)
109
+
110
+ Add to the app target:
111
+
112
+ ```ruby
113
+ pod 'SuperwallKit', '< 5.0.0'
114
+ ```
115
+
116
+ Then:
117
+
118
+ ```bash
119
+ pod repo update
120
+ pod install
121
+ ```
122
+
123
+ > **Important:** With CocoaPods, set **User Script Sandboxing = No** in the
124
+ > target's Build Settings, or the build fails on the SDK's build phase.
125
+
126
+ ## Step 2 - Configure
127
+
128
+ Call `Superwall.configure(apiKey:)` **once, at launch, as early as possible**.
129
+
130
+ ```bash
131
+ curl -sL https://superwall.com/docs/ios/quickstart/configure.md
132
+ ```
133
+
134
+ ```swift
135
+ import SuperwallKit
136
+ ```
137
+
138
+ ### SwiftUI - in the `App` struct's `init()`
139
+
140
+ ```swift
141
+ import SwiftUI
142
+ import SuperwallKit
143
+
144
+ @main
145
+ struct MyApp: App {
146
+ init() {
147
+ Superwall.configure(apiKey: "pk_YOUR_PUBLIC_KEY")
148
+ }
149
+
150
+ var body: some Scene {
151
+ WindowGroup { ContentView() }
152
+ }
153
+ }
154
+ ```
155
+
156
+ ### UIKit - in `AppDelegate`
157
+
158
+ ```swift
159
+ import UIKit
160
+ import SuperwallKit
161
+
162
+ @main
163
+ class AppDelegate: UIResponder, UIApplicationDelegate {
164
+ func application(
165
+ _ application: UIApplication,
166
+ didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?
167
+ ) -> Bool {
168
+ Superwall.configure(apiKey: "pk_YOUR_PUBLIC_KEY")
169
+ return true
170
+ }
171
+ }
172
+ ```
173
+
174
+ With a `SceneDelegate`, still configure in `AppDelegate`'s
175
+ `didFinishLaunchingWithOptions` - it runs first and only once.
176
+
177
+ ### Objective-C
178
+
179
+ ```objectivec
180
+ @import SuperwallKit;
181
+ [Superwall configureWithApiKey:@"pk_YOUR_PUBLIC_KEY"];
182
+ ```
183
+
184
+ ## Step 3 - API key handling
185
+
186
+ Use the **Public API Key** (starts with `pk_`) from Dashboard ▸ Settings ▸ Keys.
187
+ On iOS it is conventional to inline the public key in the `configure` call - it is
188
+ not a secret. **Never** use a secret/server key here and never commit one. If the
189
+ project centralizes config (an `.xcconfig`, a `Secrets` enum), follow that pattern.
190
+
191
+ ## Step 4 - Purchase handling (implements Step 0's choice)
192
+
193
+ ### (a) Default
194
+
195
+ Nothing extra. `Superwall.configure(apiKey:)` with no `purchaseController` means
196
+ Superwall manages purchases, restores, and subscription status automatically.
197
+
198
+ ### (b) RevenueCat
199
+
200
+ Create an `RCPurchaseController: PurchaseController` that forwards `purchase` to
201
+ `Purchases.shared.purchase()` and `restorePurchases` to
202
+ `Purchases.shared.restorePurchases()`, then sync entitlements via RevenueCat's
203
+ `customerInfoStream` into `Superwall.shared.subscriptionStatus`:
204
+
205
+ ```swift
206
+ let purchaseController = RCPurchaseController()
207
+ Superwall.configure(apiKey: "pk_YOUR_PUBLIC_KEY", purchaseController: purchaseController)
208
+ purchaseController.syncSubscriptionStatus()
209
+ ```
210
+
211
+ > **Important:** Copy the full `RCPurchaseController` from the doc - do not hand-roll it.
212
+ > `curl -sL https://superwall.com/docs/ios/guides/using-revenuecat.md`
213
+
214
+ ### (c) Custom `PurchaseController`
215
+
216
+ ```bash
217
+ curl -sL https://superwall.com/docs/ios/guides/advanced-configuration.md
218
+ ```
219
+
220
+ ```swift
221
+ import SuperwallKit
222
+ import StoreKit
223
+
224
+ final class MyPurchaseController: PurchaseController {
225
+ static let shared = MyPurchaseController()
226
+
227
+ func purchase(product: StoreProduct) async -> PurchaseResult {
228
+ // Purchase via StoreKit / your billing system, then return one of:
229
+ return .purchased // .cancelled, .pending, .failed(Error)
230
+ }
231
+
232
+ func restorePurchases() async -> RestorationResult {
233
+ return .restored // .failed(error)
234
+ }
235
+ }
236
+
237
+ Superwall.configure(
238
+ apiKey: "pk_YOUR_PUBLIC_KEY",
239
+ purchaseController: MyPurchaseController.shared
240
+ )
241
+ ```
242
+
243
+ > **Important (paths b & c):** With a `PurchaseController` you **must** set
244
+ > `Superwall.shared.subscriptionStatus` whenever entitlements change. Cases:
245
+ > `.unknown` (default - paywalls wait), `.active(let entitlements)` (a
246
+ > `Set<Entitlement>`), `.inactive`. Leaving it `.unknown` means paywalls never present.
247
+
248
+ ```swift
249
+ Superwall.shared.subscriptionStatus = .active(entitlements) // Set<Entitlement>
250
+ Superwall.shared.subscriptionStatus = .inactive
251
+ ```
252
+
253
+ ## Step 5 & 6 - Verify
254
+
255
+ 1. **Build:** `xcodebuild -scheme <YourScheme> -destination 'generic/platform=iOS' build`
256
+ (or ⌘B). Must compile with `SuperwallKit` resolved.
257
+ 2. **Run** on a simulator; the Xcode console logs Superwall SDK startup. To confirm
258
+ the key, temporarily set `SuperwallOptions.logging.level = .debug` and look for a
259
+ successful config fetch.
260
+ 3. **StoreKit testing** (test purchases without App Store Connect): File ▸ New ▸
261
+ File… ▸ StoreKit Configuration File, name it `Products`, save at project root
262
+ (don't add to target). Scheme ▸ Run ▸ Options ▸ StoreKit Configuration ▸ select
263
+ `Products.storekit`. Product IDs must match the products on your paywall. Reset via
264
+ Debug ▸ StoreKit ▸ Manage Transactions.
265
+ `curl -sL https://superwall.com/docs/ios/guides/testing-purchases.md`
266
+
267
+ ## Step 7 - Post-integration (wire what the app needs, then → placements)
268
+
269
+ Do the ones the app requires. Each has a fetchable page.
270
+
271
+ - **User identity - REQUIRED if the app has ANY auth/login system.** Not optional: without it every logged-in user is anonymous to Superwall, breaking user-scoped audiences, attribution, and cross-device status. Wire it the moment you see a login/logout flow (grep for signIn/login/logout/signOut/auth). call `Superwall.shared.identify(userId:)` on login,
272
+ `Superwall.shared.reset()` on logout. `userId` **must be a valid UUID** (StoreKit
273
+ compat) and must not be an email, device id, or guessable value.
274
+ `curl -sL https://superwall.com/docs/ios/quickstart/user-management.md`
275
+ ```swift
276
+ Superwall.shared.identify(userId: user.id)
277
+ Superwall.shared.reset() // on sign-out
278
+ ```
279
+ - **User attributes** - target audiences / fill paywall variables.
280
+ `curl -sL https://superwall.com/docs/ios/quickstart/setting-user-properties.md`
281
+ ```swift
282
+ Superwall.shared.setUserAttributes(["email": user.email, "plan": "trial"])
283
+ // pass nil to unset a key (Swift only)
284
+ ```
285
+ - **Tracking subscription state** - read `Superwall.shared.subscriptionStatus`
286
+ (or `.isActive`); observe changes via the delegate's
287
+ `subscriptionStatusDidChange(from:to:)`.
288
+ `curl -sL https://superwall.com/docs/ios/quickstart/tracking-subscription-state.md`
289
+ - **Deep links** - pass incoming URLs to `Superwall.handleDeepLink(url)`; it fires
290
+ the `deepLink_open` placement so routing is dashboard-driven.
291
+ `curl -sL https://superwall.com/docs/ios/guides/handling-deep-links.md`
292
+ - **3rd-party analytics** - forward Superwall events to your analytics via the
293
+ delegate. `curl -sL https://superwall.com/docs/ios/guides/3rd-party-analytics.md`
294
+
295
+ ## Pitfalls
296
+
297
+ - **CocoaPods build failure** → **User Script Sandboxing = No** in Build Settings.
298
+ - **`.pbxproj` hand-edits with Xcode open** → Xcode overwrites them; close Xcode or use the UI.
299
+ - **Configured but paywalls never show** → `subscriptionStatus` stuck at `.unknown`
300
+ (only when you use a `PurchaseController` - you must set it), or no placement yet
301
+ (that's the placements skill).
302
+ - **Configuring more than once / not at launch** → configure exactly once in
303
+ `App.init()` or `didFinishLaunchingWithOptions`, not in a view body.
304
+ - **Secret key** → the key must start with `pk_`; a secret key fails config.
305
+
306
+ ## Deeper docs
307
+
308
+ - Index: `curl -sL https://superwall.com/docs/ios/llms.txt`
309
+ - Install: https://superwall.com/docs/ios/quickstart/install
310
+ - Configure: https://superwall.com/docs/ios/quickstart/configure
311
+ - Advanced purchasing / PurchaseController: https://superwall.com/docs/ios/guides/advanced-configuration
312
+ - Using RevenueCat: https://superwall.com/docs/ios/guides/using-revenuecat
313
+ - StoreKit testing: https://superwall.com/docs/ios/guides/testing-purchases
314
+ - SDK reference: https://superwall.com/docs/ios/sdk-reference/Superwall