@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,101 @@
|
|
|
1
|
+
# Dashboard setup - reference
|
|
2
|
+
|
|
3
|
+
Detailed recipes for the `superwall-dashboard` skill. Every command takes `--json`.
|
|
4
|
+
|
|
5
|
+
## Scoping
|
|
6
|
+
|
|
7
|
+
| Resource | Scope | Flag |
|
|
8
|
+
| ---------------------- | ----------- | ---------------- |
|
|
9
|
+
| products, entitlements | project | `--project <id>` |
|
|
10
|
+
| campaigns, paywalls | application | `--app <id>` |
|
|
11
|
+
|
|
12
|
+
`superwall apps list --json` returns projects with nested `applications` (each has `id`,
|
|
13
|
+
`platform`, `bundle_id`, `public_api_key`). One project holds one app per platform, so with a
|
|
14
|
+
single app the CLI auto-scopes; agents always pass the flags explicitly.
|
|
15
|
+
|
|
16
|
+
## Products
|
|
17
|
+
|
|
18
|
+
### Create by hand (real pricing)
|
|
19
|
+
|
|
20
|
+
```bash
|
|
21
|
+
superwall products create <identifier> \
|
|
22
|
+
--price 39.99 \ # major units; converted to cents for you
|
|
23
|
+
--currency USD \ # default USD
|
|
24
|
+
--period year \ # day | week | month | year
|
|
25
|
+
--period-count 1 \ # periods per cycle, default 1
|
|
26
|
+
--trial-days 7 \ # optional free-trial length
|
|
27
|
+
--entitlement pro \ # entitlement(s) to grant; repeat --entitlement for more
|
|
28
|
+
--name "Pro Yearly" \ # optional display name
|
|
29
|
+
--project <id> --json
|
|
30
|
+
```
|
|
31
|
+
|
|
32
|
+
Use the **real store product identifiers** (the ones in App Store Connect / Google Play), e.g.
|
|
33
|
+
`com.app.pro.yearly`. The dashboard product identifier must match the store's or the SDK can't
|
|
34
|
+
resolve it on device.
|
|
35
|
+
|
|
36
|
+
### Import from App Store Connect
|
|
37
|
+
|
|
38
|
+
There is **no** `products import` subcommand. Two ways to import:
|
|
39
|
+
|
|
40
|
+
1. **Orchestrated (hands-off):** run `superwall integrate` - the CLI
|
|
41
|
+
walks App Store Connect and imports products interactively.
|
|
42
|
+
2. **Agent-driven (you do it):** connect the key once, enumerate via the signed ASC proxy, then
|
|
43
|
+
create each product:
|
|
44
|
+
|
|
45
|
+
```bash
|
|
46
|
+
# one-time: upload the ASC API key to Superwall's vault (nothing stored locally)
|
|
47
|
+
superwall asc keys set --key-id <KEY_ID> --issuer <ISSUER_ID> --key-file ./AuthKey_<KEY_ID>.p8 --json
|
|
48
|
+
superwall asc keys list --json # confirm connected; note the team id
|
|
49
|
+
|
|
50
|
+
# enumerate real products for the app (by bundle id or ASC app id)
|
|
51
|
+
superwall asc subscriptions com.app.bundle --json # renewing subs
|
|
52
|
+
superwall asc iaps com.app.bundle --json # one-time / non-renewing
|
|
53
|
+
superwall asc products com.app.bundle --json # everything
|
|
54
|
+
superwall asc apps --json # list ASC apps if unsure of the id
|
|
55
|
+
|
|
56
|
+
# create each returned productId, granting your entitlement
|
|
57
|
+
superwall products create com.app.pro.yearly --entitlement pro --project <id> --json
|
|
58
|
+
```
|
|
59
|
+
|
|
60
|
+
Products imported this way carry only the identifier (and reference name); Xcode/StoreKit and
|
|
61
|
+
the stores remain the source of truth for pricing.
|
|
62
|
+
|
|
63
|
+
### Generate a local `.storekit` file (for Xcode testing without sandbox)
|
|
64
|
+
|
|
65
|
+
```bash
|
|
66
|
+
superwall products storekit --project <id> --out Superwall.storekit --json
|
|
67
|
+
```
|
|
68
|
+
|
|
69
|
+
Seeds product identifiers into a StoreKit configuration file; Xcode refines pricing/types on import.
|
|
70
|
+
|
|
71
|
+
## Entitlements
|
|
72
|
+
|
|
73
|
+
```bash
|
|
74
|
+
superwall entitlements list --project <id> --json
|
|
75
|
+
superwall entitlements create pro --project <id> --json
|
|
76
|
+
```
|
|
77
|
+
|
|
78
|
+
Default to a single coarse `pro` entitlement. Add more only for genuine tiers (e.g. `pro`,
|
|
79
|
+
`team`). Products grant entitlements via `--entitlement` at create time.
|
|
80
|
+
|
|
81
|
+
## Campaigns + placements
|
|
82
|
+
|
|
83
|
+
```bash
|
|
84
|
+
superwall campaigns list --project <id> --app <id> --json
|
|
85
|
+
superwall campaigns create "Onboarding" onboarding_complete --project <id> --app <id> --json
|
|
86
|
+
superwall campaigns placement <campaignId> another_placement --project <id> --app <id> --json
|
|
87
|
+
```
|
|
88
|
+
|
|
89
|
+
- `create` takes a **description**, not an identifier - name it for the surface.
|
|
90
|
+
- A campaign can carry several related placements; call `campaigns placement` once per placement.
|
|
91
|
+
- Adding a placement that's already on the campaign is safe to skip - list first.
|
|
92
|
+
|
|
93
|
+
## What the CLI cannot do (leave manual)
|
|
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.
|
|
98
|
+
`superwall paywalls list --project <id> --app <id> --json` shows what exists.
|
|
99
|
+
- **Configure audiences / experiment splits** beyond the default - done in the dashboard.
|
|
100
|
+
|
|
101
|
+
Report these as the remaining manual steps.
|
|
@@ -0,0 +1,76 @@
|
|
|
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
|
+
# Integrate the Superwall SDK
|
|
7
|
+
|
|
8
|
+
Get Superwall installed and configured with the smallest, cleanest set of edits.
|
|
9
|
+
Placements (paywall triggers) are a **separate step** - do not add `register()` /
|
|
10
|
+
`registerPlacement()` calls or example "Go Premium" buttons here. After this skill
|
|
11
|
+
succeeds, use the **superwall-placements** skill to add triggers.
|
|
12
|
+
|
|
13
|
+
## Docs access
|
|
14
|
+
|
|
15
|
+
Superwall's docs are fetchable **as markdown** - always prefer fetching the current
|
|
16
|
+
page over relying on memory:
|
|
17
|
+
|
|
18
|
+
```bash
|
|
19
|
+
curl -sL https://superwall.com/docs/llms.txt # index: discover any doc path
|
|
20
|
+
curl -sL https://superwall.com/docs/llms-full.txt # broad context across all SDKs
|
|
21
|
+
curl -sL https://superwall.com/docs/{path}.md # any page as markdown (append .md)
|
|
22
|
+
```
|
|
23
|
+
|
|
24
|
+
Each SDK also has its own index - `curl -sL https://superwall.com/docs/{ios|expo|react-native|flutter}/llms.txt`.
|
|
25
|
+
Fetch the index to find the slug, then fetch `{path}.md`. Every reference file
|
|
26
|
+
below embeds the exact `curl` at each step so you can pull current detail when the
|
|
27
|
+
baked-in steps aren't enough. **Never invent an API** - if a symbol isn't in a
|
|
28
|
+
reference or a page you fetched, fetch and confirm.
|
|
29
|
+
|
|
30
|
+
## Principles
|
|
31
|
+
|
|
32
|
+
- Make the smallest set of edits that yields a working, verifiable integration.
|
|
33
|
+
Don't refactor or reformat unrelated code.
|
|
34
|
+
- **Read a file before editing it**; match its existing style and conventions.
|
|
35
|
+
- **Detect the package manager / build system** from the project (lockfiles,
|
|
36
|
+
`Podfile`, `app.json`, `pubspec.yaml`, `Package.swift`) - never assume
|
|
37
|
+
npm/yarn/pnpm/bun/CocoaPods/SPM.
|
|
38
|
+
- **Never invent an API key.** Use the exact public key you were given (it starts
|
|
39
|
+
with `pk_`). Never commit a secret. The public key may be inlined where the
|
|
40
|
+
platform conventionally does so (e.g. iOS `configure()`); otherwise use the
|
|
41
|
+
platform's standard env/config mechanism.
|
|
42
|
+
- **Never invent an API.** Every symbol you write must come from the reference
|
|
43
|
+
file or the linked docs. If the docs are ambiguous, say so and link the page.
|
|
44
|
+
- Configure **once, at app launch**, as early in the launch path as possible.
|
|
45
|
+
|
|
46
|
+
## Steps
|
|
47
|
+
|
|
48
|
+
1. **Detect the framework** from the project files:
|
|
49
|
+
|
|
50
|
+
| Signal in the project | Framework | Read this reference |
|
|
51
|
+
| ------------------------------------------------------------- | ------------------- | ---------------------------- |
|
|
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` |
|
|
56
|
+
|
|
57
|
+
If both Expo and bare RN signals exist, treat it as **Expo**. If unsure, ask.
|
|
58
|
+
|
|
59
|
+
2. **Read `references/<framework>.md` and follow it exactly.** Each reference is a
|
|
60
|
+
complete, verified playbook: install, configure, API key handling, verify,
|
|
61
|
+
pitfalls, and doc links.
|
|
62
|
+
|
|
63
|
+
3. **Pick the purchase-handling path** (covered in each reference):
|
|
64
|
+
- **No existing IAP system** → default. No `PurchaseController`; Superwall
|
|
65
|
+
manages purchases, restoration, and subscription state.
|
|
66
|
+
- **RevenueCat / Adapty / Qonversion / custom StoreKit already present** →
|
|
67
|
+
implement a `PurchaseController` and keep `subscriptionStatus` in sync with
|
|
68
|
+
your source of truth. (For a full migration off another SDK, use the
|
|
69
|
+
**superwall-migrate** skill.)
|
|
70
|
+
|
|
71
|
+
## Definition of done
|
|
72
|
+
|
|
73
|
+
1. SDK installed and resolving (pods/SPM/gradle/pub resolved).
|
|
74
|
+
2. Superwall configured exactly once at launch with the provided public `pk_` key.
|
|
75
|
+
3. If a build command exists, build to verify it compiles.
|
|
76
|
+
4. No placements added - that is the placements step.
|
|
@@ -0,0 +1,269 @@
|
|
|
1
|
+
# Integrate Superwall - Expo
|
|
2
|
+
|
|
3
|
+
You are integrating Superwall into an Expo app using the **`expo-superwall`**
|
|
4
|
+
package (the modern, recommended SDK - hooks + provider API). Get it installed and
|
|
5
|
+
configured. **Do not add paywall triggers (`usePlacement` / `registerPlacement`)**;
|
|
6
|
+
that is the separate **superwall-placements** skill.
|
|
7
|
+
|
|
8
|
+
**Requirements:** Expo SDK **53+**, iOS deployment target **15.1+** (**16.4+** for
|
|
9
|
+
Expo SDK 56+), Android **minSdkVersion 21+**. **Expo Go does not work** - you must
|
|
10
|
+
use a Development Build (custom dev client). See Pitfalls.
|
|
11
|
+
|
|
12
|
+
## Checklist
|
|
13
|
+
|
|
14
|
+
- [ ] **0. Decide the purchase-handling path** (default / RevenueCat / custom).
|
|
15
|
+
- [ ] **1. Install** `expo-superwall` + `expo-build-properties`; produce a native build.
|
|
16
|
+
- [ ] **2. Configure** - wrap the root in `SuperwallProvider` with per-platform `pk_` keys.
|
|
17
|
+
- [ ] **3. API keys** via `EXPO_PUBLIC_*` env vars (public keys, never secrets).
|
|
18
|
+
- [ ] **4. Purchase handling** for the chosen path.
|
|
19
|
+
- [ ] **5. Build a dev client** (NOT Expo Go) - native module links.
|
|
20
|
+
- [ ] **6. Run** - logs show Superwall startup; StoreKit test config if testing purchases.
|
|
21
|
+
- [ ] **7. Post-integration** (identity, attributes, subscription state, deep links, analytics) - final section, then → **superwall-placements**.
|
|
22
|
+
|
|
23
|
+
## Docs access - read the current page when baked steps aren't enough
|
|
24
|
+
|
|
25
|
+
Superwall's docs are fetchable **as markdown**. Fetch instead of guessing:
|
|
26
|
+
|
|
27
|
+
```bash
|
|
28
|
+
curl -sL https://superwall.com/docs/expo/llms.txt # index: every Expo doc path
|
|
29
|
+
curl -sL https://superwall.com/docs/llms-full.txt # broad context across all SDKs
|
|
30
|
+
curl -sL https://superwall.com/docs/expo/quickstart/configure.md # any page + ".md"
|
|
31
|
+
```
|
|
32
|
+
|
|
33
|
+
Pattern: fetch `expo/llms.txt` for the slug, then
|
|
34
|
+
`https://superwall.com/docs/expo/{path}.md`. Every `curl` here is verified working.
|
|
35
|
+
The Expo SDK is hooks-based (`useUser`, `usePlacement`, `useSuperwallEvents`) and
|
|
36
|
+
its component API (`SuperwallProvider`, `SuperwallLoading`/`SuperwallLoaded`,
|
|
37
|
+
`CustomPurchaseControllerProvider`) differs from the native SDKs - **never invent a
|
|
38
|
+
hook or prop**; fetch the SDK-reference page and confirm.
|
|
39
|
+
|
|
40
|
+
## Quickstart walk
|
|
41
|
+
|
|
42
|
+
| Order | Slug | Covered by |
|
|
43
|
+
| ----- | --------------------------------------------- | ------------------------------ |
|
|
44
|
+
| 1 | `expo/quickstart/install` | Step 1 here |
|
|
45
|
+
| 2 | `expo/quickstart/configure` | Step 2 here |
|
|
46
|
+
| 3 | `expo/quickstart/present-first-paywall` | **superwall-placements** skill |
|
|
47
|
+
| 4 | `expo/quickstart/feature-gating` | **superwall-placements** skill |
|
|
48
|
+
| 5 | `expo/quickstart/in-app-paywall-previews` | placements / QA |
|
|
49
|
+
| 6 | `expo/quickstart/setting-user-properties` | Step 7 here |
|
|
50
|
+
| 7 | `expo/quickstart/tracking-subscription-state` | Step 7 here |
|
|
51
|
+
| 8 | `expo/quickstart/user-management` | Step 7 here |
|
|
52
|
+
|
|
53
|
+
SDK-reference index (components + hooks):
|
|
54
|
+
`curl -sL https://superwall.com/docs/expo/llms.txt`
|
|
55
|
+
|
|
56
|
+
## Step 0 - Purchase-handling path (decide first)
|
|
57
|
+
|
|
58
|
+
> **Important:** Paths (b) and (c) require you to keep subscription status in sync
|
|
59
|
+
> yourself via `setSubscriptionStatus`. Path (a) does not.
|
|
60
|
+
|
|
61
|
+
- **(a) Default - Superwall handles StoreKit/Billing.** No existing IAP code.
|
|
62
|
+
Recommended, zero purchase code. Just use `SuperwallProvider`.
|
|
63
|
+
- **(b) RevenueCat stays the source of truth.** Keep RC purchasing and sync its
|
|
64
|
+
entitlements into Superwall. `curl -sL https://superwall.com/docs/expo/guides/using-revenuecat.md`
|
|
65
|
+
- **(c) Custom purchase controller.** The app has its own billing. Supply a
|
|
66
|
+
`PurchaseController` via `CustomPurchaseControllerProvider` and drive status.
|
|
67
|
+
|
|
68
|
+
For a full migration off another SDK, use the **superwall-migrate** skill.
|
|
69
|
+
|
|
70
|
+
## Step 1 - Install
|
|
71
|
+
|
|
72
|
+
Detect the package manager from the lockfile. Use `expo install` so versions match
|
|
73
|
+
the Expo SDK.
|
|
74
|
+
|
|
75
|
+
```bash
|
|
76
|
+
curl -sL https://superwall.com/docs/expo/quickstart/install.md
|
|
77
|
+
```
|
|
78
|
+
|
|
79
|
+
```bash
|
|
80
|
+
npx expo install expo-superwall
|
|
81
|
+
# or: pnpm dlx expo install expo-superwall / yarn dlx expo install expo-superwall / bunx expo install expo-superwall
|
|
82
|
+
```
|
|
83
|
+
|
|
84
|
+
Also install and configure `expo-build-properties` to guarantee native minimums:
|
|
85
|
+
|
|
86
|
+
```bash
|
|
87
|
+
npx expo install expo-build-properties
|
|
88
|
+
```
|
|
89
|
+
|
|
90
|
+
Merge into the **existing** `plugins` array in `app.json` / `app.config.js` (don't
|
|
91
|
+
create a second one):
|
|
92
|
+
|
|
93
|
+
```json
|
|
94
|
+
{
|
|
95
|
+
"expo": {
|
|
96
|
+
"plugins": [
|
|
97
|
+
["expo-build-properties", {
|
|
98
|
+
"ios": { "deploymentTarget": "15.1" },
|
|
99
|
+
"android": { "minSdkVersion": 21 }
|
|
100
|
+
}]
|
|
101
|
+
]
|
|
102
|
+
}
|
|
103
|
+
}
|
|
104
|
+
```
|
|
105
|
+
|
|
106
|
+
(For Expo SDK 56+, set `"deploymentTarget": "16.4"`.)
|
|
107
|
+
|
|
108
|
+
`expo-superwall` is a native module, so produce a **native build**:
|
|
109
|
+
|
|
110
|
+
```bash
|
|
111
|
+
npx expo run:ios # or: npx expo run:android
|
|
112
|
+
```
|
|
113
|
+
|
|
114
|
+
For an **existing** project whose `ios/`/`android/` predate the install, regenerate
|
|
115
|
+
them (back up custom native code first):
|
|
116
|
+
|
|
117
|
+
```bash
|
|
118
|
+
npx expo prebuild --clean
|
|
119
|
+
```
|
|
120
|
+
|
|
121
|
+
## Step 2 - Configure
|
|
122
|
+
|
|
123
|
+
Wrap the app root in `SuperwallProvider` with per-platform public keys. Place it at
|
|
124
|
+
the very top of the tree - the root `App` component, or `app/_layout.tsx` for
|
|
125
|
+
expo-router so it mounts once above every route.
|
|
126
|
+
|
|
127
|
+
```bash
|
|
128
|
+
curl -sL https://superwall.com/docs/expo/quickstart/configure.md
|
|
129
|
+
```
|
|
130
|
+
|
|
131
|
+
```tsx
|
|
132
|
+
import { SuperwallProvider } from "expo-superwall";
|
|
133
|
+
|
|
134
|
+
export default function App() {
|
|
135
|
+
return (
|
|
136
|
+
<SuperwallProvider
|
|
137
|
+
apiKeys={{
|
|
138
|
+
ios: process.env.EXPO_PUBLIC_SUPERWALL_IOS_KEY!,
|
|
139
|
+
android: process.env.EXPO_PUBLIC_SUPERWALL_ANDROID_KEY!,
|
|
140
|
+
}}
|
|
141
|
+
>
|
|
142
|
+
{/* your existing app tree */}
|
|
143
|
+
</SuperwallProvider>
|
|
144
|
+
);
|
|
145
|
+
}
|
|
146
|
+
```
|
|
147
|
+
|
|
148
|
+
`apiKeys` takes `ios` and optionally `android`. `SuperwallProvider` configures the
|
|
149
|
+
SDK on mount - **do not** also call a separate `configure()`. Optional behavior
|
|
150
|
+
goes through the `options` prop:
|
|
151
|
+
|
|
152
|
+
```tsx
|
|
153
|
+
<SuperwallProvider apiKeys={{ ios: "...", android: "..." }} options={{ /* ... */ }}>
|
|
154
|
+
```
|
|
155
|
+
|
|
156
|
+
To gate UI on SDK readiness, `SuperwallLoading` / `SuperwallLoaded` are available
|
|
157
|
+
(see the SDK-reference components).
|
|
158
|
+
|
|
159
|
+
## Step 3 - API key handling
|
|
160
|
+
|
|
161
|
+
Use the **Public API Key(s)** (`pk_…`) from Dashboard ▸ Settings ▸ Keys - iOS and
|
|
162
|
+
Android apps each have their own key. Store as `EXPO_PUBLIC_`-prefixed env vars
|
|
163
|
+
(readable in JS at build time) in `.env` / `app.config.js`. Public keys aren't
|
|
164
|
+
secrets, but `EXPO_PUBLIC_*` keeps them out of source and lets environments differ.
|
|
165
|
+
**Never** put a secret/server key here.
|
|
166
|
+
|
|
167
|
+
## Step 4 - Purchase handling (implements Step 0's choice)
|
|
168
|
+
|
|
169
|
+
### (a) Default
|
|
170
|
+
|
|
171
|
+
Just use `SuperwallProvider` as above. Superwall manages purchases, restores, and
|
|
172
|
+
subscription status.
|
|
173
|
+
|
|
174
|
+
### (b) RevenueCat / (c) custom
|
|
175
|
+
|
|
176
|
+
Supply a `PurchaseController` through `CustomPurchaseControllerProvider`. Read the
|
|
177
|
+
page before writing - the exact wiring differs between the hooks API and the compat
|
|
178
|
+
API:
|
|
179
|
+
|
|
180
|
+
```bash
|
|
181
|
+
curl -sL https://superwall.com/docs/expo/guides/advanced-configuration.md
|
|
182
|
+
```
|
|
183
|
+
|
|
184
|
+
The controller implements `purchaseFromAppStore(productId)`,
|
|
185
|
+
`purchaseFromGooglePlay(productId, basePlanId?, offerId?)`, and `restorePurchases()`:
|
|
186
|
+
|
|
187
|
+
```tsx
|
|
188
|
+
export class MyPurchaseController extends PurchaseController {
|
|
189
|
+
async purchaseFromAppStore(productId: string): Promise<PurchaseResult> { /* ... */ }
|
|
190
|
+
async purchaseFromGooglePlay(
|
|
191
|
+
productId: string, basePlanId?: string, offerId?: string
|
|
192
|
+
): Promise<PurchaseResult> { /* ... */ }
|
|
193
|
+
async restorePurchases(): Promise<RestorationResult> { /* ... */ }
|
|
194
|
+
}
|
|
195
|
+
```
|
|
196
|
+
|
|
197
|
+
> **Important (paths b & c):** keep subscription status in sync whenever
|
|
198
|
+
> entitlements change. Via the `useUser` hook:
|
|
199
|
+
>
|
|
200
|
+
> ```tsx
|
|
201
|
+
> const { setSubscriptionStatus } = useUser();
|
|
202
|
+
> setSubscriptionStatus({ status: "ACTIVE", entitlements: [{ id: "pro" }] });
|
|
203
|
+
> // or: setSubscriptionStatus({ status: "INACTIVE" });
|
|
204
|
+
> ```
|
|
205
|
+
>
|
|
206
|
+
> Or via the shared instance:
|
|
207
|
+
> `Superwall.shared.setSubscriptionStatus(SubscriptionStatus.Active([new Entitlement("pro")]))`
|
|
208
|
+
> / `SubscriptionStatus.Inactive()`. For (b), map RevenueCat's active entitlements
|
|
209
|
+
> into that call. Confirm shapes against the advanced-configuration page.
|
|
210
|
+
|
|
211
|
+
## Step 5 & 6 - Verify
|
|
212
|
+
|
|
213
|
+
1. **Build a dev client** and run it: `npx expo run:ios` / `npx expo run:android`
|
|
214
|
+
(NOT Expo Go). Must compile with the native module linked.
|
|
215
|
+
2. Watch Metro/Xcode/Android logs on launch for Superwall SDK startup.
|
|
216
|
+
> **Important:** Superwall does **not** refetch config on hot reload - fully
|
|
217
|
+
> restart the app after changing SDK setup.
|
|
218
|
+
3. For iOS purchases in the simulator, read the StoreKit testing guide:
|
|
219
|
+
`curl -sL https://superwall.com/docs/expo/guides/testing-purchases.md`
|
|
220
|
+
|
|
221
|
+
## Step 7 - Post-integration (wire what the app needs, then → placements)
|
|
222
|
+
|
|
223
|
+
The Expo SDK exposes these through the **`useUser`** hook and event hooks.
|
|
224
|
+
|
|
225
|
+
- **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). `identify(userId)` on login, `signOut()` on logout. `userId`
|
|
226
|
+
should be a **UUID** (StoreKit compat), never an email/device id/guessable value.
|
|
227
|
+
`curl -sL https://superwall.com/docs/expo/quickstart/user-management.md`
|
|
228
|
+
```tsx
|
|
229
|
+
const { identify, signOut } = useUser();
|
|
230
|
+
await identify(user.id);
|
|
231
|
+
signOut();
|
|
232
|
+
```
|
|
233
|
+
- **User attributes** - `curl -sL https://superwall.com/docs/expo/quickstart/setting-user-properties.md`
|
|
234
|
+
- **Tracking subscription state** - read `subscriptionStatus` from `useUser`
|
|
235
|
+
(`status` is `"ACTIVE" | "INACTIVE" | "UNKNOWN"`); react to changes with
|
|
236
|
+
`useSuperwallEvents({ onSubscriptionStatusChange })`.
|
|
237
|
+
`curl -sL https://superwall.com/docs/expo/quickstart/tracking-subscription-state.md`
|
|
238
|
+
```tsx
|
|
239
|
+
const { subscriptionStatus } = useUser();
|
|
240
|
+
if (subscriptionStatus?.status === "ACTIVE") { /* entitled */ }
|
|
241
|
+
```
|
|
242
|
+
- **Deep links** - `curl -sL https://superwall.com/docs/expo/guides/handling-deep-links.md`
|
|
243
|
+
- **3rd-party analytics** - forward events via `useSuperwallEvents`.
|
|
244
|
+
`curl -sL https://superwall.com/docs/expo/guides/3rd-party-analytics.md`
|
|
245
|
+
|
|
246
|
+
## Pitfalls
|
|
247
|
+
|
|
248
|
+
- **"Cannot find native module 'SuperwallExpo'" / paywalls don't load** → you're on
|
|
249
|
+
Expo Go. Build a dev client: `npx expo run:ios` / `run:android`, or
|
|
250
|
+
`eas build --profile development --platform ios`.
|
|
251
|
+
- **Existing app, native folders out of date** → `npx expo prebuild --clean` (back
|
|
252
|
+
up custom native code first).
|
|
253
|
+
- **EAS build missing the module** → fresh dev build:
|
|
254
|
+
`eas build --profile development --platform ios`.
|
|
255
|
+
- **Stale caches after install** → `npx expo start --clear`, reinstall
|
|
256
|
+
`node_modules`, `pod install --repo-update` in `ios/`.
|
|
257
|
+
- **Wrong Expo SDK** → `npx expo-doctor`; needs Expo SDK 53+.
|
|
258
|
+
- **Changes not taking effect** → hot reload doesn't re-configure Superwall; fully
|
|
259
|
+
restart.
|
|
260
|
+
|
|
261
|
+
## Deeper docs
|
|
262
|
+
|
|
263
|
+
- Index: `curl -sL https://superwall.com/docs/expo/llms.txt`
|
|
264
|
+
- Install: https://superwall.com/docs/expo/quickstart/install
|
|
265
|
+
- Configure: https://superwall.com/docs/expo/quickstart/configure
|
|
266
|
+
- Configuring (options): https://superwall.com/docs/expo/guides/configuring
|
|
267
|
+
- Advanced purchasing / PurchaseController: https://superwall.com/docs/expo/guides/advanced-configuration
|
|
268
|
+
- Using RevenueCat: https://superwall.com/docs/expo/guides/using-revenuecat
|
|
269
|
+
- Debugging: https://superwall.com/docs/expo/guides/debugging
|