@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.
- package/LICENSE +21 -0
- package/README.md +201 -0
- package/dist/actions-MB-eBY64.js +140 -0
- package/dist/api-BF7-toqM.js +151 -0
- package/dist/api-output-B5hh0q4V.js +20 -0
- package/dist/app-K6j9Es7h.js +189 -0
- package/dist/asc-CArSwo5D.js +539 -0
- package/dist/asc-products-YQ6Oc6YO.js +93 -0
- package/dist/auth-CY2cO_NF.js +139 -0
- package/dist/auth.d.ts +30 -0
- package/dist/auth.js +4 -0
- package/dist/billing-DWyfEQ6l.js +80 -0
- package/dist/bind-hslFhcTR.js +213 -0
- package/dist/chunk-DQxbwPpZ.js +30 -0
- package/dist/command-Kwx4ekbo.js +283 -0
- package/dist/create-Bbi8BOO1.js +410 -0
- package/dist/dev-D0lQDCQI.js +397 -0
- package/dist/devtools-8EgLo86w.js +3638 -0
- package/dist/doctor-ByeRdMcl.js +88 -0
- package/dist/drivers-DVAZgone.js +413 -0
- package/dist/entry.d.ts +9 -0
- package/dist/entry.js +495 -0
- package/dist/existing-CcJrIIAU.js +88 -0
- package/dist/feedback-Z0Wk7VC5.js +73 -0
- package/dist/git-3OX9u3xE.js +433 -0
- package/dist/hosted-CHwaUqLd.js +32 -0
- package/dist/integrate-DqOAqK7J.js +863 -0
- package/dist/json-C3hPIMkI.js +7 -0
- package/dist/login-Dr8UN_Gx.js +290 -0
- package/dist/migrate-D92bJTg6.js +114 -0
- package/dist/org-B2gy9Pmu.js +40 -0
- package/dist/params-Bvq0iqQK.js +52 -0
- package/dist/pipeline-CHHIg6BU.js +1056 -0
- package/dist/print-skill-BnZAk7dV.js +74 -0
- package/dist/promote-CRe9170G.js +88 -0
- package/dist/publish-DsODvrOD.js +35 -0
- package/dist/push-BDkZUC0v.js +35 -0
- package/dist/query-DIllrSnk.js +53 -0
- package/dist/resource-CdP1MDla.js +483 -0
- package/dist/resources-CVrWwA1K.js +233 -0
- package/dist/run-cGGBUMs5.js +89 -0
- package/dist/scan-BQexuUPO.js +236 -0
- package/dist/skills-DhuUs28u.js +64 -0
- package/dist/skills-xrfXt9u0.js +205 -0
- package/dist/spawn-DSoTXy_j.js +69 -0
- package/dist/spinner-gOxIMz-V.js +18 -0
- package/dist/storekit-Ddvs4Ynw.js +29 -0
- package/dist/telemetry-CcfrtXdf.js +204 -0
- package/dist/token-DHRH8cxi.js +102 -0
- package/dist/ui-C4ncRJqd.js +27703 -0
- package/dist/update-BiVeR024.js +137 -0
- package/dist/upgrade-DYWspApv.js +72 -0
- package/package.json +87 -0
- package/prompts/actions/dashboard-setup.xml +10 -0
- package/prompts/actions/integrate.xml +5 -0
- package/prompts/actions/migrate.xml +11 -0
- package/prompts/actions/placements-implement.xml +20 -0
- package/prompts/actions/placements-review.xml +18 -0
- package/prompts/actions/review-fix.xml +18 -0
- package/prompts/actions/review.xml +18 -0
- package/prompts/commandments.xml +17 -0
- package/prompts/context.xml +9 -0
- package/skills/README.md +118 -0
- package/skills/superwall-dashboard/SKILL.md +81 -0
- package/skills/superwall-dashboard/references/setup.md +101 -0
- package/skills/superwall-integrate/SKILL.md +76 -0
- package/skills/superwall-integrate/references/expo.md +269 -0
- package/skills/superwall-integrate/references/flutter.md +285 -0
- package/skills/superwall-integrate/references/ios.md +314 -0
- package/skills/superwall-integrate/references/react-native.md +245 -0
- package/skills/superwall-migrate/SKILL.md +83 -0
- package/skills/superwall-migrate/references/adapty.md +229 -0
- package/skills/superwall-migrate/references/qonversion.md +227 -0
- package/skills/superwall-migrate/references/revenuecat.md +414 -0
- package/skills/superwall-placements/SKILL.md +73 -0
- package/skills/superwall-placements/references/expo.md +161 -0
- package/skills/superwall-placements/references/flutter.md +139 -0
- package/skills/superwall-placements/references/ios.md +165 -0
- package/skills/superwall-placements/references/react-native.md +145 -0
- package/skills/superwall-placements/references/strategy.md +221 -0
- package/skills/superwall-review/SKILL.md +75 -0
- package/skills/superwall-review/references/expo.md +100 -0
- package/skills/superwall-review/references/flutter.md +99 -0
- package/skills/superwall-review/references/ios.md +108 -0
- 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
|