@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,221 @@
|
|
|
1
|
+
# Superwall placement strategy - the playbook
|
|
2
|
+
|
|
3
|
+
This is the framework-agnostic strategy guide: **where** to put placements and
|
|
4
|
+
**why**. Read this first, then read your framework's reference (`ios.md`,
|
|
5
|
+
`expo.md`, `react-native.md`, `flutter.md`) for the exact API. The API is the
|
|
6
|
+
easy part. Deciding what to instrument and which actions should remain remotely
|
|
7
|
+
gateable is the craft that makes an app's monetization flexible.
|
|
8
|
+
|
|
9
|
+
Most of section 1 (register everything, gate remotely) is stated in the Superwall
|
|
10
|
+
docs. Sections 2-4 and 6 are **recommended practice** - craft distilled from how
|
|
11
|
+
well-instrumented apps are built, not verbatim doc rules. They're written as
|
|
12
|
+
imperatives because they're what you should do, not because a doc mandates them.
|
|
13
|
+
|
|
14
|
+
## 1. The mental model
|
|
15
|
+
|
|
16
|
+
**Register every potentially-monetizable moment. The campaign decides what
|
|
17
|
+
happens.** A placement is a named event you fire at a boundary; whether it shows a
|
|
18
|
+
paywall, gates a feature, enters a holdout, or does nothing is decided remotely in
|
|
19
|
+
the dashboard - evaluated on-device, no network delay. The docs are explicit:
|
|
20
|
+
_"we strongly recommend registering all core functionality in order to remotely
|
|
21
|
+
configure which features you want to gate - without an app update."_ And more
|
|
22
|
+
broadly: _"Register. Everything."_ - even analytics events with no feature block,
|
|
23
|
+
so you can retroactively attach a paywall almost anywhere.
|
|
24
|
+
|
|
25
|
+
Why this matters:
|
|
26
|
+
|
|
27
|
+
- **Placements are free experimentation surface.** An unassigned placement does
|
|
28
|
+
nothing until you route it in a campaign. Registering it costs ~nothing at
|
|
29
|
+
runtime. So instrument generously now; decide monetization later, remotely.
|
|
30
|
+
- **Everything you don't register is frozen.** To monetize a moment you never
|
|
31
|
+
instrumented, you must ship an app update and wait for adoption. Every
|
|
32
|
+
un-registered premium moment is a monetization lever you can't pull.
|
|
33
|
+
- **The dashboard is where decisions live and change.** Show/hide a paywall,
|
|
34
|
+
gate/un-gate a feature, target an audience, pause for a free weekend, run an
|
|
35
|
+
A/B test - all without a release. That only works if the placement already
|
|
36
|
+
exists in the binary.
|
|
37
|
+
|
|
38
|
+
### Keep intentionally remote gates inside the registration callback
|
|
39
|
+
|
|
40
|
+
When a placement is intentionally responsible for deciding access, do not wrap it
|
|
41
|
+
in a hand-rolled `if subscribed { … } else { showPaywall() }`.
|
|
42
|
+
|
|
43
|
+
```
|
|
44
|
+
// WRONG - freezes your monetization logic into this app release
|
|
45
|
+
if (user.hasActiveSubscription) {
|
|
46
|
+
startWorkout();
|
|
47
|
+
} else {
|
|
48
|
+
presentPaywall();
|
|
49
|
+
}
|
|
50
|
+
|
|
51
|
+
// RIGHT - the campaign decides; subscribed users are filtered automatically
|
|
52
|
+
register(placement: "start_workout") {
|
|
53
|
+
startWorkout();
|
|
54
|
+
}
|
|
55
|
+
```
|
|
56
|
+
|
|
57
|
+
Why that split gate is a trap:
|
|
58
|
+
|
|
59
|
+
- **Subscribed/entitled users are filtered automatically.** When you register a
|
|
60
|
+
placement, Superwall evaluates subscription state itself: an entitled user's
|
|
61
|
+
`feature` closure runs immediately with no paywall. You do not need - and must
|
|
62
|
+
not add - your own check for this.
|
|
63
|
+
- **A code check hard-codes the decision.** "Gated vs non-gated," "who sees it,"
|
|
64
|
+
"show it at all" become properties of a shipped binary instead of dashboard
|
|
65
|
+
settings. You lose remote configuration, A/B testing, holdouts, and the free
|
|
66
|
+
weekend - the entire reason to use Superwall.
|
|
67
|
+
- **It double-gates.** Your `if` plus the paywall's own gating means even a
|
|
68
|
+
Non-Gated experiment can't let users through. It silently breaks experiments.
|
|
69
|
+
|
|
70
|
+
**Do not turn this into a ban on subscription-state reads.** Superwall documents
|
|
71
|
+
subscription status and entitlements for app state and UI, and an app may have
|
|
72
|
+
deliberate access rules outside a placement. Flag a code-side check only when the
|
|
73
|
+
same action is meant to be remotely gated and the check demonstrably prevents the
|
|
74
|
+
campaign or feature callback from controlling it. For paywall-specific UI, use
|
|
75
|
+
`getPresentationResult` to see what would happen without presenting.
|
|
76
|
+
|
|
77
|
+
## 2. Common placement candidates
|
|
78
|
+
|
|
79
|
+
Use these as prompts, not requirements. Select the moments that fit the app's real
|
|
80
|
+
product and monetization model, named for the moment rather than the button.
|
|
81
|
+
|
|
82
|
+
| Placement | Fires when | Why it's core |
|
|
83
|
+
| ------------------------------ | ------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
84
|
+
| `onboarding_complete` | User finishes onboarding | A common high-intent moment when the app has a meaningful onboarding flow. |
|
|
85
|
+
| one per premium feature gate | User taps a paid feature (`unlock_export`, `start_workout`, `remove_watermark`) | The direct "I want this paid thing" signal. `verb_noun`. One per distinct feature, not one per button that reaches it. |
|
|
86
|
+
| a limit/quota-reached moment | Free allowance exhausted (`hit_export_limit`, `scan_limit_reached`) | Catches users at peak demonstrated need. Distinct from the feature gate - the user already used it free and wants more. |
|
|
87
|
+
| `upgrade_tapped` | User taps an explicit "Go Pro" / upgrade entry in settings or a banner | Self-selected high intent. Route to your fullest paywall. |
|
|
88
|
+
| `app_launch` / `session_start` | Cold launch / new session (both are auto-registered standard placements) | Broad-reach surface for win-back or a hard gate on relaunch. Usually left **campaign-off** until you deliberately want it - powerful but blunt. |
|
|
89
|
+
| a win-back / discount surface | User declines, churns, or hits a re-engagement point | Where you route a discounted offer. Often driven by standard placements like `paywall_decline` or `transaction_abandon`. |
|
|
90
|
+
|
|
91
|
+
The last two may remain unrouted until there is a deliberate reason to present.
|
|
92
|
+
That is valid: instrumentation can exist before campaign strategy.
|
|
93
|
+
|
|
94
|
+
Superwall also **auto-registers** standard placements you can route without any
|
|
95
|
+
code: `app_install`, `app_launch`, `session_start`, `deepLink_open`,
|
|
96
|
+
`survey_response`, `paywall_decline`, `transaction_abandon`, and more. Prefer
|
|
97
|
+
these for lifecycle moments instead of inventing your own.
|
|
98
|
+
|
|
99
|
+
## 3. App-type playbook
|
|
100
|
+
|
|
101
|
+
Map the app to its type, then instrument that type's premium surface. Names below
|
|
102
|
+
are examples - keep your app's real feature vocabulary.
|
|
103
|
+
|
|
104
|
+
| App type | The paid surface | Placements (moment that fires them) |
|
|
105
|
+
| -------------------- | ------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
|
|
106
|
+
| Photo/video editor | Export, save, watermark removal, premium filters/tools | `unlock_export` (tap export/save), `remove_watermark` (tap watermark toggle), `unlock_premium_filter` (select locked filter), `hit_export_limit` (free export quota hit) |
|
|
107
|
+
| Fitness | Workout start, plan unlock, history/stats | `start_workout` (tap a locked workout), `unlock_plan` (choose a premium plan), `view_workout_history` (open stats/history), `onboarding_complete` |
|
|
108
|
+
| Productivity/utility | Nth document/scan/task, advanced features, cross-device sync | `hit_document_limit` (create Nth doc), `unlock_advanced_feature` (tap a pro tool), `enable_sync` (toggle cross-device sync), `scan_limit_reached` |
|
|
109
|
+
| Content/media | Premium article/episode, offline download | `unlock_premium_content` (tap a locked article/episode), `download_offline` (tap download), `session_start` (metered-paywall relaunch) |
|
|
110
|
+
| Dating/social | Likes limit, see-who-liked, boosts | `likes_limit_reached` (out of free likes), `see_who_liked` (tap the blurred list), `unlock_boost` (tap boost), `unlock_super_like` |
|
|
111
|
+
| AI apps | Generation quota, premium models | `generation_limit_reached` (free generations used up), `unlock_premium_model` (select a locked model), `unlock_faster_generation`, `onboarding_complete` |
|
|
112
|
+
|
|
113
|
+
For each: pick the 3-6 moments that actually correspond to money, name them for
|
|
114
|
+
the moment, and register at the point of intent (the tap/attempt), not on a
|
|
115
|
+
timer or a screen you happen to have.
|
|
116
|
+
|
|
117
|
+
## 4. The audit method (for reviews)
|
|
118
|
+
|
|
119
|
+
When reviewing an existing app's placements, work in this order. Don't start from
|
|
120
|
+
the placements that exist - start from the money.
|
|
121
|
+
|
|
122
|
+
1. **Enumerate the premium surface first.** List what is actually paid or
|
|
123
|
+
intended to be paid: every gated feature, every quota, every "Pro" affordance,
|
|
124
|
+
the upgrade entries, the end of onboarding. This is the ground truth to
|
|
125
|
+
measure against - build it before looking at code.
|
|
126
|
+
2. **Map each paid surface → placement.** For every item in step 1, find the
|
|
127
|
+
`register`/`registerPlacement` call that covers it (use the grep in your
|
|
128
|
+
framework reference).
|
|
129
|
+
3. **Then flag the four failure modes:**
|
|
130
|
+
- **Surface with no placement** → missed revenue. A paid feature you can never
|
|
131
|
+
attach a paywall to without an app update. The highest-value finding.
|
|
132
|
+
- **Expected presenter with no campaign** → presentation gap. Cross-check the
|
|
133
|
+
registered names that are supposed to show or gate now against `superwall
|
|
134
|
+
campaigns list --project <id> --app <id> --json`. Analytics-only, future, and intentionally paused
|
|
135
|
+
placements may be unrouted without being noise.
|
|
136
|
+
- **Conflicting code-side entitlement check** → grep for
|
|
137
|
+
subscription/entitlement reads at call sites (`subscriptionStatus`,
|
|
138
|
+
`hasActiveSubscription`, `getEntitlements`, `CustomerInfo`, `isPro`). Any that
|
|
139
|
+
gate the same action that Superwall is intended to control may belong inside
|
|
140
|
+
`feature`. Reads that drive UI/app state or deliberate non-placement access
|
|
141
|
+
rules are valid and must not be reported from grep alone.
|
|
142
|
+
- **Naming drift / typos** → `Start_Workout` vs `start_workout`, `unlockExport`
|
|
143
|
+
vs `unlock_export`, singular/plural drift. A typo means the campaign silently
|
|
144
|
+
never matches. Also flag campaign placements that nothing in code registers.
|
|
145
|
+
|
|
146
|
+
Report findings as: surface → expected placement → status (present / missing /
|
|
147
|
+
unrouted-but-expected / conflicting gate / misnamed). Keep analytics/future
|
|
148
|
+
instrumentation out of the issue list.
|
|
149
|
+
|
|
150
|
+
## 5. Gate depth: hard gate vs soft gate
|
|
151
|
+
|
|
152
|
+
Every placement is either a **hard gate** or a **soft/non-gated** surface. This is
|
|
153
|
+
set per-paywall in the dashboard (editor → General → Feature Gating), _not_ in
|
|
154
|
+
code - the same `register` call serves both. But you decide the _intent_ when you
|
|
155
|
+
place it, so know which you mean.
|
|
156
|
+
|
|
157
|
+
- **Hard gate (paid-only feature).** The work lives inside the `feature` closure,
|
|
158
|
+
and the paywall is set to **Gated**. Per the docs, a Gated paywall runs the
|
|
159
|
+
`feature` closure _"only if the user is already paying or if they begin
|
|
160
|
+
paying."_ Dismiss without buying → feature blocked. Use for genuinely
|
|
161
|
+
paid-only capability: the export, the premium generation, the unlimited scan.
|
|
162
|
+
|
|
163
|
+
- **Soft gate (show paywall, let them through).** Same code, paywall set to
|
|
164
|
+
**Non-Gated**: the `feature` closure runs _"when the paywall is dismissed
|
|
165
|
+
(whether they paid or not)."_ Use for upsell moments where you want to surface
|
|
166
|
+
the offer but not block the user - a nudge at `session_start`, a value reminder
|
|
167
|
+
after `onboarding_complete`.
|
|
168
|
+
|
|
169
|
+
In both cases, when no campaign matches or the user is already entitled, the
|
|
170
|
+
feature runs immediately with no paywall and no network call. The important
|
|
171
|
+
consequence: **put the paywalled work in the `feature` closure either way.** That
|
|
172
|
+
keeps the gated/non-gated choice remote. If you run the work _after_ the register
|
|
173
|
+
call unconditionally, you've made it non-gated in code and can never harden it.
|
|
174
|
+
|
|
175
|
+
## 6. How many placements?
|
|
176
|
+
|
|
177
|
+
There is no healthy universal count. A broad analytics bridge may intentionally
|
|
178
|
+
produce many placement names, while a focused app may have only a few dedicated
|
|
179
|
+
monetization placements. Judge clarity and usefulness, not totals.
|
|
180
|
+
|
|
181
|
+
For dedicated monetization keys, each should express a distinct moment. Use
|
|
182
|
+
`params` to distinguish variants (`{ source: "toolbar" }` vs `{ source: "menu" }`)
|
|
183
|
+
when they share campaign intent. Do not collapse an intentional analytics taxonomy
|
|
184
|
+
just to make the placement list shorter.
|
|
185
|
+
|
|
186
|
+
## 7. Naming rules
|
|
187
|
+
|
|
188
|
+
- **Preserve the app's established taxonomy.** The SDK does not enforce casing,
|
|
189
|
+
and the docs use multiple styles. `snake_case` is a reasonable choice for new
|
|
190
|
+
dedicated keys, but analytics bridges should retain their existing event names.
|
|
191
|
+
- **Name the user moment, not the UI widget.** `unlock_export`, not
|
|
192
|
+
`export_button_tapped`; `hit_export_limit`, not `alert_shown`. The widget can
|
|
193
|
+
change; the intent is stable.
|
|
194
|
+
- **`verb_noun` for feature gates.** `start_workout`, `unlock_export`,
|
|
195
|
+
`remove_watermark`, `download_offline`. It reads as what the user is trying to
|
|
196
|
+
do.
|
|
197
|
+
- **Stable forever.** A placement name is a routing key shared with the dashboard
|
|
198
|
+
campaign. Renaming it silently breaks routing - the campaign keeps looking for
|
|
199
|
+
the old name and the new one fires nothing. Treat renames as breaking changes:
|
|
200
|
+
add the new campaign mapping before shipping the rename, or don't rename.
|
|
201
|
+
- **Never rename for style alone.** Consistency is not worth breaking campaign
|
|
202
|
+
routing or historical analytics.
|
|
203
|
+
- **Reuse, never duplicate.** Before adding a name, check existing placements
|
|
204
|
+
(`superwall campaigns list --project <id> --app <id> --json`) and existing `register` calls. Two names for
|
|
205
|
+
one intent split your data and double your campaign work.
|
|
206
|
+
|
|
207
|
+
## Dashboard routing (required for presentation, not instrumentation)
|
|
208
|
+
|
|
209
|
+
A registered placement does not present a paywall until a campaign routes it.
|
|
210
|
+
Campaigns hold one or more placements and use audience filters to decide what each
|
|
211
|
+
user sees. Analytics-only or future placements can remain unrouted intentionally.
|
|
212
|
+
|
|
213
|
+
```bash
|
|
214
|
+
superwall campaigns list --project <id> --app <id> --json
|
|
215
|
+
superwall campaigns create "Editor upgrade paywall" unlock_export --project <id> --app <id> --json
|
|
216
|
+
superwall campaigns placement <campaignId> another_placement --project <id> --app <id> --json
|
|
217
|
+
```
|
|
218
|
+
|
|
219
|
+
Rule of thumb: one campaign per distinct paywall surface/decision (onboarding,
|
|
220
|
+
settings upgrade, win-back), routing the placements that belong to it - not one
|
|
221
|
+
campaign per trigger, and no duplicates.
|
|
@@ -0,0 +1,75 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: superwall-review
|
|
3
|
+
description: Audit an existing Superwall SDK setup across configuration, purchasing, subscription state, identity, deep links, Web Checkout readiness, placements, campaigns, products, entitlements, paywalls, and analytics. Use to review or safely fix an existing iOS, Expo, React Native, or Flutter integration. Do not use for first-time setup or provider migration.
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# Review an existing Superwall setup
|
|
7
|
+
|
|
8
|
+
Review the integration as a system, not as a placement inventory. Inspect code,
|
|
9
|
+
project configuration, and authenticated dashboard state where available. A good
|
|
10
|
+
review explains what is correct, identifies only evidence-backed defects, and
|
|
11
|
+
separates optional opportunities from required fixes.
|
|
12
|
+
|
|
13
|
+
## Review contract
|
|
14
|
+
|
|
15
|
+
1. Read the app's architecture and detect its purchase path before judging it.
|
|
16
|
+
2. Fetch the current platform docs at each relevant step; APIs and guidance move.
|
|
17
|
+
3. Audit code and native project configuration without editing in review mode.
|
|
18
|
+
4. Cross-check the dashboard and store through read-only CLI commands when auth
|
|
19
|
+
is available. A failed check is **Not verified**, never an issue by itself.
|
|
20
|
+
5. Cite file and line evidence for every code finding. Never infer a defect from
|
|
21
|
+
a symbol name alone; read the surrounding flow.
|
|
22
|
+
|
|
23
|
+
## Audit every area
|
|
24
|
+
|
|
25
|
+
| Area | What good looks like |
|
|
26
|
+
| ------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
27
|
+
| SDK & configuration | Supported package, configured once and early with the correct platform public key and intentional options. |
|
|
28
|
+
| Purchases & subscriptions | Exactly one deliberate purchase path: Superwall default, RevenueCat, or a custom controller; restores and status sync match that path. |
|
|
29
|
+
| Identity & attributes | Authenticated apps identify after login, reset/sign out on logout, and set useful targeting attributes without sensitive data. |
|
|
30
|
+
| Deep links | App URL entry points forward URLs to `handleDeepLink`, enabling the standard `deepLink_open` placement and preview links. |
|
|
31
|
+
| Web Checkout | If used or intended, redirects and redemption match the purchase path. If absent, describe readiness as optional - not broken setup. |
|
|
32
|
+
| Placements | Valuable moments are registered intentionally; real gates put controllable work in the feature callback; code and campaign names agree where presentation is expected. |
|
|
33
|
+
| Dashboard & store | Products, entitlements, paywalls, campaigns, placements, and store identifiers form a usable chain. |
|
|
34
|
+
| Analytics & lifecycle | Delegate/event forwarding is coherent and custom lifecycle events do not accidentally duplicate standard placements. |
|
|
35
|
+
|
|
36
|
+
## Correctness rules that prevent false positives
|
|
37
|
+
|
|
38
|
+
- **Analytics events becoming placements is recommended.** The docs explicitly
|
|
39
|
+
recommend registering analytics events for future flexibility.
|
|
40
|
+
- **Fire-and-forget placements are valid.** A feature callback is needed only
|
|
41
|
+
when that specific action must be remotely gateable.
|
|
42
|
+
- **Subscription-state reads are valid.** The SDK documents them for app state and
|
|
43
|
+
UI. Flag only contradictory sources of truth or broken controller/status sync.
|
|
44
|
+
- **An unrouted placement is not automatically dead.** It is a problem only when
|
|
45
|
+
the app expects that placement to present or gate now; analytics-only and future
|
|
46
|
+
placements may intentionally have no campaign.
|
|
47
|
+
- Do not require optional features (Web Checkout, delegate analytics, custom
|
|
48
|
+
attributes) without evidence that the app intends to use them.
|
|
49
|
+
- Do not recommend renaming stable placement keys for style alone.
|
|
50
|
+
|
|
51
|
+
## Authenticated cross-checks
|
|
52
|
+
|
|
53
|
+
Use `superwall whoami --json`, then `superwall bootstrap --json`. Derive the exact
|
|
54
|
+
project/app ids and pass them to `superwall products list --project <id> --json`,
|
|
55
|
+
`superwall entitlements list --project <id> --json`, `superwall campaigns list
|
|
56
|
+
--project <id> --app <id> --json`, and `superwall paywalls list --project <id>
|
|
57
|
+
--app <id> --json`. When App Store Connect is linked,
|
|
58
|
+
use `superwall asc subscriptions <bundle-id> --json` to compare store identifiers.
|
|
59
|
+
|
|
60
|
+
## Framework reference
|
|
61
|
+
|
|
62
|
+
Read exactly one: `references/ios.md`, `references/expo.md`,
|
|
63
|
+
`references/react-native.md`, or `references/flutter.md`.
|
|
64
|
+
|
|
65
|
+
## Docs access
|
|
66
|
+
|
|
67
|
+
```bash
|
|
68
|
+
curl -sL https://superwall.com/docs/llms.txt
|
|
69
|
+
curl -sL https://superwall.com/docs/{platform}/llms.txt
|
|
70
|
+
curl -sL https://superwall.com/docs/{path}.md
|
|
71
|
+
```
|
|
72
|
+
|
|
73
|
+
Use the platform pages for configure, advanced purchasing, subscription state,
|
|
74
|
+
user management, deep links, feature gating, and Web Checkout. Use dashboard
|
|
75
|
+
pages for placements, standard placements, products, and subscription management.
|
|
@@ -0,0 +1,100 @@
|
|
|
1
|
+
# Review Superwall - Expo
|
|
2
|
+
|
|
3
|
+
You are reviewing an existing Expo integration using `expo-superwall`. Complete
|
|
4
|
+
the whole checklist; placements are one part of it.
|
|
5
|
+
|
|
6
|
+
## Checklist
|
|
7
|
+
|
|
8
|
+
- [ ] package/plugin/native build configuration
|
|
9
|
+
- [ ] one root `SuperwallProvider` with correct platform keys/options
|
|
10
|
+
- [ ] purchase controller, restore flow, and subscription-status ownership
|
|
11
|
+
- [ ] identity, sign-out, and user attributes
|
|
12
|
+
- [ ] Expo linking and `handleDeepLink`
|
|
13
|
+
- [ ] conditional Web Checkout redemption readiness
|
|
14
|
+
- [ ] placements, callbacks, campaign coverage, and standard placements
|
|
15
|
+
- [ ] dashboard products, entitlements, paywalls, campaigns, and store IDs
|
|
16
|
+
- [ ] event forwarding and a native build verification path
|
|
17
|
+
|
|
18
|
+
## Docs access
|
|
19
|
+
|
|
20
|
+
```bash
|
|
21
|
+
curl -sL https://superwall.com/docs/expo/llms.txt
|
|
22
|
+
curl -sL https://superwall.com/docs/expo/quickstart/configure.md
|
|
23
|
+
curl -sL https://superwall.com/docs/expo/guides/advanced-configuration.md
|
|
24
|
+
curl -sL https://superwall.com/docs/expo/quickstart/tracking-subscription-state.md
|
|
25
|
+
curl -sL https://superwall.com/docs/expo/quickstart/user-management.md
|
|
26
|
+
curl -sL https://superwall.com/docs/expo/guides/handling-deep-links.md
|
|
27
|
+
curl -sL https://superwall.com/docs/expo/guides/web-checkout.md
|
|
28
|
+
curl -sL https://superwall.com/docs/expo/quickstart/feature-gating.md
|
|
29
|
+
```
|
|
30
|
+
|
|
31
|
+
## 1. SDK and configuration
|
|
32
|
+
|
|
33
|
+
Inspect `package.json`, the lockfile, app config, `expo-build-properties`, and the
|
|
34
|
+
native projects when present. Confirm one root `SuperwallProvider` with `apiKeys`
|
|
35
|
+
for the platforms actually shipped. `EXPO_PUBLIC_*` values are public, but should
|
|
36
|
+
follow the app's existing config pattern. Do not also require a separate
|
|
37
|
+
`configure()` when the provider already configures the SDK. Read options and
|
|
38
|
+
plugin settings in context.
|
|
39
|
+
|
|
40
|
+
## 2. Purchases, restores, and subscription state
|
|
41
|
+
|
|
42
|
+
Infer the path before judging it:
|
|
43
|
+
|
|
44
|
+
- **Default:** `SuperwallProvider` without a custom controller is correct;
|
|
45
|
+
Superwall owns purchases, restores, and status.
|
|
46
|
+
- **RevenueCat/custom:** `CustomPurchaseControllerProvider`/`PurchaseController`
|
|
47
|
+
must handle the current iOS and Android purchase signatures, restoration, and
|
|
48
|
+
synchronize status/entitlements whenever the source of truth changes.
|
|
49
|
+
|
|
50
|
+
`useUser().subscriptionStatus` is documented app state, so its use is not an
|
|
51
|
+
issue by itself. Flag only contradictory state, permanently unknown status,
|
|
52
|
+
missing restore/controller branches, or access behavior that conflicts with the
|
|
53
|
+
chosen architecture. Cross-check product and entitlement identifiers through the
|
|
54
|
+
CLI when available; failed auth/network/store checks belong in **Not verified**.
|
|
55
|
+
|
|
56
|
+
## 3. Identity and attributes
|
|
57
|
+
|
|
58
|
+
Trace actual auth transitions. Account-based apps should call `identify(userId)`
|
|
59
|
+
when login resolves and `signOut()` on logout. Review user attributes for useful
|
|
60
|
+
audience/paywall personalization and accidental sensitive data. Do not demand
|
|
61
|
+
identity in a deliberately anonymous app.
|
|
62
|
+
|
|
63
|
+
## 4. Deep links and Web Checkout
|
|
64
|
+
|
|
65
|
+
Inspect Expo Router/React Navigation linking config, `Linking` subscriptions,
|
|
66
|
+
initial URL handling, app schemes, and universal/app links. Superwall URLs should
|
|
67
|
+
reach the current docs' `SuperwallExpoModule.handleDeepLink(url)` path so the
|
|
68
|
+
standard `deepLink_open` placement carries URL parameters into campaign rules.
|
|
69
|
+
Check cold-start and already-running paths.
|
|
70
|
+
|
|
71
|
+
Web Checkout is conditional. If present, verify return URL configuration and
|
|
72
|
+
post-checkout handling. Default purchasing needs no custom redemption sync. A
|
|
73
|
+
custom controller must merge web and device entitlements; RevenueCat follows its
|
|
74
|
+
dedicated docs. Otherwise describe Web Checkout readiness only as optional.
|
|
75
|
+
|
|
76
|
+
## 5. Placements and lifecycle
|
|
77
|
+
|
|
78
|
+
Find `usePlacement`, `registerPlacement`, wrappers, constants, and analytics
|
|
79
|
+
bridges. Analytics-backed and fire-and-forget placements are valid. A `feature`
|
|
80
|
+
callback is necessary only for an action intended to be remotely gateable. Check
|
|
81
|
+
calls occur in event/effect flows rather than render, await async registrations,
|
|
82
|
+
and compare exact names only for active campaigns expected to present now.
|
|
83
|
+
Unrouted analytics/future placements are fine.
|
|
84
|
+
|
|
85
|
+
Prefer standard `app_launch`, `session_start`, and `deepLink_open` over custom
|
|
86
|
+
duplicates when semantics match. Do not recommend style-only placement renames.
|
|
87
|
+
Review `useSuperwallEvents` only when the app intends to forward analytics.
|
|
88
|
+
|
|
89
|
+
## 6. Dashboard and verification
|
|
90
|
+
|
|
91
|
+
Run the read-only CLI cross-checks from `SKILL.md`. Verify the app/platform keys,
|
|
92
|
+
products, entitlements, paywall products, campaigns, and current presentation
|
|
93
|
+
placements form a usable chain. Cite IDs where available. In fix mode, run the
|
|
94
|
+
project's native Expo build/typecheck path - not only hot reload.
|
|
95
|
+
|
|
96
|
+
## Fix-mode boundaries
|
|
97
|
+
|
|
98
|
+
Fix clear wiring bugs and code/doc mismatches. Do not change purchase providers,
|
|
99
|
+
enable Web Checkout, rename stable placements, alter prices, or invent campaign
|
|
100
|
+
strategy without an explicit user decision.
|
|
@@ -0,0 +1,99 @@
|
|
|
1
|
+
# Review Superwall - Flutter
|
|
2
|
+
|
|
3
|
+
You are reviewing an existing Flutter integration using `superwallkit_flutter`.
|
|
4
|
+
Complete the whole checklist; placements are one part of it.
|
|
5
|
+
|
|
6
|
+
## Checklist
|
|
7
|
+
|
|
8
|
+
- [ ] package and iOS/Android native configuration
|
|
9
|
+
- [ ] one early `configure` call with the correct platform key/options
|
|
10
|
+
- [ ] purchase controller, restore flow, and subscription-status ownership
|
|
11
|
+
- [ ] identity/reset and user attributes
|
|
12
|
+
- [ ] platform links/router and `handleDeepLink`
|
|
13
|
+
- [ ] conditional Web Checkout redemption readiness
|
|
14
|
+
- [ ] placements, callbacks, campaigns, and standard placements
|
|
15
|
+
- [ ] dashboard/store products, entitlements, paywalls, and campaigns
|
|
16
|
+
- [ ] delegate/analytics and build verification
|
|
17
|
+
|
|
18
|
+
## Docs access
|
|
19
|
+
|
|
20
|
+
```bash
|
|
21
|
+
curl -sL https://superwall.com/docs/flutter/llms.txt
|
|
22
|
+
curl -sL https://superwall.com/docs/flutter/quickstart/configure.md
|
|
23
|
+
curl -sL https://superwall.com/docs/flutter/guides/advanced-configuration.md
|
|
24
|
+
curl -sL https://superwall.com/docs/flutter/quickstart/tracking-subscription-state.md
|
|
25
|
+
curl -sL https://superwall.com/docs/flutter/quickstart/user-management.md
|
|
26
|
+
curl -sL https://superwall.com/docs/flutter/guides/handling-deep-links.md
|
|
27
|
+
curl -sL https://superwall.com/docs/flutter/guides/web-checkout.md
|
|
28
|
+
curl -sL https://superwall.com/docs/flutter/quickstart/feature-gating.md
|
|
29
|
+
```
|
|
30
|
+
|
|
31
|
+
## 1. SDK and configuration
|
|
32
|
+
|
|
33
|
+
Inspect `pubspec.yaml`/lock, iOS pods and deployment target, Android Gradle/SDK,
|
|
34
|
+
and `main()`. Confirm initialization happens before use, with one
|
|
35
|
+
`Superwall.configure` call and the correct key for each platform. Check
|
|
36
|
+
`WidgetsFlutterBinding.ensureInitialized()` where initialization needs it. Read
|
|
37
|
+
`SuperwallOptions` in context rather than treating custom options as suspicious.
|
|
38
|
+
|
|
39
|
+
## 2. Purchases, restores, and subscription state
|
|
40
|
+
|
|
41
|
+
Infer the path first:
|
|
42
|
+
|
|
43
|
+
- **Default:** no `PurchaseController` is correct; Superwall owns purchases,
|
|
44
|
+
restores, and subscription status.
|
|
45
|
+
- **RevenueCat/custom:** the controller must implement the current App Store and
|
|
46
|
+
Google Play purchase methods plus restore, and synchronize Superwall status as
|
|
47
|
+
entitlements change.
|
|
48
|
+
|
|
49
|
+
Reading `Superwall.shared.subscriptionStatus`, customer info, or entitlements is
|
|
50
|
+
documented and valid. Flag only conflicting sources, permanently unknown status,
|
|
51
|
+
missing controller branches, or access behavior inconsistent with the selected
|
|
52
|
+
architecture. Compare product/entitlement IDs with authenticated CLI/store data;
|
|
53
|
+
blocked checks belong in **Not verified**.
|
|
54
|
+
|
|
55
|
+
## 3. Identity and attributes
|
|
56
|
+
|
|
57
|
+
Trace login/logout. Account-based apps should call
|
|
58
|
+
`Superwall.shared.identify(...)` after authentication and `reset()` on logout.
|
|
59
|
+
For Android, check whether Play Store identifiers are intentionally passed when
|
|
60
|
+
needed. Inspect attributes for audience/paywall value and sensitive data. Do not
|
|
61
|
+
demand identity in a deliberately anonymous app.
|
|
62
|
+
|
|
63
|
+
## 4. Deep links and Web Checkout
|
|
64
|
+
|
|
65
|
+
Inspect `app_links`/`uni_links`, router handling, iOS URL schemes/universal links,
|
|
66
|
+
Android intent filters/app links, cold start, and foreground delivery. Superwall
|
|
67
|
+
URLs should reach `await Superwall.shared.handleDeepLink(uri)` so the standard
|
|
68
|
+
`deepLink_open` placement receives URL parameters for dashboard rules.
|
|
69
|
+
|
|
70
|
+
Web Checkout is conditional. If present, verify return URLs and post-checkout
|
|
71
|
+
handling. Default purchasing needs no custom redemption sync. A custom controller
|
|
72
|
+
must merge web and device entitlements and update status; RevenueCat follows its
|
|
73
|
+
dedicated docs. Otherwise list readiness only as an optional opportunity.
|
|
74
|
+
|
|
75
|
+
## 5. Placements and lifecycle
|
|
76
|
+
|
|
77
|
+
Find `registerPlacement`, wrappers, constants, and analytics bridges. Analytics
|
|
78
|
+
and fire-and-forget calls are valid. A `feature` callback is needed only when the
|
|
79
|
+
specific action should be remotely gateable. Check calls occur outside widget
|
|
80
|
+
`build`, futures are awaited where sequencing matters, active presenting campaign
|
|
81
|
+
names match, and parameters are useful. Unrouted analytics/future placements are
|
|
82
|
+
fine.
|
|
83
|
+
|
|
84
|
+
Prefer standard `app_launch`, `session_start`, and `deepLink_open` over truly
|
|
85
|
+
duplicative lifecycle placements. Do not recommend cosmetic renames of stable
|
|
86
|
+
keys. Delegate forwarding is optional unless app behavior relies on it.
|
|
87
|
+
|
|
88
|
+
## 6. Dashboard and verification
|
|
89
|
+
|
|
90
|
+
Run the read-only CLI checks from `SKILL.md`. Verify platform keys, products,
|
|
91
|
+
entitlements, paywall products, campaigns, and placements expected to present
|
|
92
|
+
now form a usable chain. Cite IDs where available. In fix mode, run existing
|
|
93
|
+
`flutter analyze`, tests, and an appropriate platform build where practical.
|
|
94
|
+
|
|
95
|
+
## Fix-mode boundaries
|
|
96
|
+
|
|
97
|
+
Fix clear wiring bugs and code/doc mismatches. Do not switch purchase providers,
|
|
98
|
+
enable Web Checkout, rename stable placements, change prices, or invent campaign
|
|
99
|
+
strategy without an explicit user decision.
|
|
@@ -0,0 +1,108 @@
|
|
|
1
|
+
# Review Superwall - iOS / Swift
|
|
2
|
+
|
|
3
|
+
You are reviewing an existing iOS integration using `SuperwallKit`. Complete the
|
|
4
|
+
whole checklist; placements are one part of it.
|
|
5
|
+
|
|
6
|
+
## Checklist
|
|
7
|
+
|
|
8
|
+
- [ ] SDK dependency and deployment target
|
|
9
|
+
- [ ] one early `configure` call and the intended public key/options
|
|
10
|
+
- [ ] purchase controller, restore flow, and subscription-status ownership
|
|
11
|
+
- [ ] identity, reset, and user attributes
|
|
12
|
+
- [ ] URL schemes/universal links and `handleDeepLink`
|
|
13
|
+
- [ ] conditional Web Checkout redemption readiness
|
|
14
|
+
- [ ] placements, feature callbacks, campaign coverage, and standard placements
|
|
15
|
+
- [ ] products, entitlements, paywalls, campaigns, and App Store identifiers
|
|
16
|
+
- [ ] delegate/analytics and a build or test verification path
|
|
17
|
+
|
|
18
|
+
## Docs access
|
|
19
|
+
|
|
20
|
+
```bash
|
|
21
|
+
curl -sL https://superwall.com/docs/ios/llms.txt
|
|
22
|
+
curl -sL https://superwall.com/docs/ios/quickstart/configure.md
|
|
23
|
+
curl -sL https://superwall.com/docs/ios/guides/advanced-configuration.md
|
|
24
|
+
curl -sL https://superwall.com/docs/ios/quickstart/tracking-subscription-state.md
|
|
25
|
+
curl -sL https://superwall.com/docs/ios/quickstart/user-management.md
|
|
26
|
+
curl -sL https://superwall.com/docs/ios/guides/handling-deep-links.md
|
|
27
|
+
curl -sL https://superwall.com/docs/ios/guides/web-checkout.md
|
|
28
|
+
curl -sL https://superwall.com/docs/ios/quickstart/feature-gating.md
|
|
29
|
+
```
|
|
30
|
+
|
|
31
|
+
## 1. SDK and configuration
|
|
32
|
+
|
|
33
|
+
Inspect `Package.resolved`, `project.pbxproj`, `Package.swift`, or the Podfile and
|
|
34
|
+
lockfile. Confirm `Superwall.configure(apiKey:)` is called once, as early as
|
|
35
|
+
practical at launch. A `pk_` key is public and may be inlined on iOS; verify it
|
|
36
|
+
belongs to the current app rather than treating its presence as a secret leak.
|
|
37
|
+
Read any `SuperwallOptions` and judge intentional behavior, not mere customization.
|
|
38
|
+
|
|
39
|
+
## 2. Purchases, restores, and subscription state
|
|
40
|
+
|
|
41
|
+
Infer exactly which path the app uses:
|
|
42
|
+
|
|
43
|
+
- **Default:** no `PurchaseController` is correct; Superwall owns purchases,
|
|
44
|
+
restores, and subscription status.
|
|
45
|
+
- **RevenueCat/custom:** the controller must implement purchase and restore,
|
|
46
|
+
return accurate result cases, and keep `Superwall.shared.subscriptionStatus`
|
|
47
|
+
synchronized as entitlements change. Custom/web products need the current doc's
|
|
48
|
+
handling; do not assume StoreKit-backed and custom products are interchangeable.
|
|
49
|
+
|
|
50
|
+
Reading `subscriptionStatus`, `.isActive`, customer info, or entitlements is a
|
|
51
|
+
documented way to drive app state and UI. Report a problem only when two sources
|
|
52
|
+
contradict each other, status remains `.unknown`, restore is missing, or access
|
|
53
|
+
logic demonstrably bypasses the intended purchase architecture.
|
|
54
|
+
|
|
55
|
+
Compare dashboard products/entitlements with App Store subscription identifiers
|
|
56
|
+
when CLI access exists. Do not label an auth, network, or ASC failure as broken
|
|
57
|
+
subscriptions; put it under **Not verified**.
|
|
58
|
+
|
|
59
|
+
## 3. Identity and attributes
|
|
60
|
+
|
|
61
|
+
If the app has accounts, trace the real login and logout paths. Expect
|
|
62
|
+
`Superwall.shared.identify(userId:)` after identity is known and
|
|
63
|
+
`Superwall.shared.reset()` on logout. On iOS, a UUID user ID is needed for
|
|
64
|
+
StoreKit `appAccountToken`; non-UUID IDs fall back to the anonymous alias for
|
|
65
|
+
store events. Review `setUserAttributes` for useful targeting data and accidental
|
|
66
|
+
sensitive values.
|
|
67
|
+
|
|
68
|
+
## 4. Deep links and Web Checkout
|
|
69
|
+
|
|
70
|
+
Trace every URL entry point: SwiftUI `.onOpenURL`, app/scene delegate methods,
|
|
71
|
+
universal links, and any routing service. Incoming URLs intended for Superwall
|
|
72
|
+
should reach `Superwall.handleDeepLink(url)`, which produces the standard
|
|
73
|
+
`deepLink_open` placement with URL parameters. A hardcoded URL-to-placement
|
|
74
|
+
switch is worth improving when dashboard campaign rules can replace it.
|
|
75
|
+
|
|
76
|
+
Web Checkout is conditional. If the app/dashboard uses it, verify return URLs and
|
|
77
|
+
post-checkout handling. Default Superwall purchasing needs no custom redemption
|
|
78
|
+
sync. A custom controller must merge redeemed web entitlements with device
|
|
79
|
+
entitlements and update status; RevenueCat must follow its documented path. If
|
|
80
|
+
there is no Web Checkout intent, list readiness only as an optional opportunity.
|
|
81
|
+
|
|
82
|
+
## 5. Placements and lifecycle
|
|
83
|
+
|
|
84
|
+
Find `register(placement:)`, wrappers, analytics bridges, and placement constants.
|
|
85
|
+
Analytics bridges and calls without a feature closure are valid. Require a
|
|
86
|
+
feature closure only when the action itself is meant to be remotely gated. Check
|
|
87
|
+
valuable surfaces, placement parameters, accidental calls during SwiftUI `body`,
|
|
88
|
+
and exact name agreement with active campaigns. Unrouted analytics/future
|
|
89
|
+
placements are fine.
|
|
90
|
+
|
|
91
|
+
Prefer standard `app_launch`, `session_start`, and `deepLink_open` placements over
|
|
92
|
+
custom duplicates when the semantics truly match. Do not suggest cosmetic
|
|
93
|
+
renames of stable keys. Review delegate forwarding for duplicated analytics or
|
|
94
|
+
missing subscription/redemption callbacks only when the app relies on them.
|
|
95
|
+
|
|
96
|
+
## 6. Dashboard and verification
|
|
97
|
+
|
|
98
|
+
Run the read-only CLI cross-checks from `SKILL.md`. A presenting chain needs a
|
|
99
|
+
matching app, product attached to the intended entitlement/paywall, and an active
|
|
100
|
+
campaign audience for placements expected to show now. Cite dashboard IDs where
|
|
101
|
+
available. Finally identify the project's existing Xcode build/test command; in
|
|
102
|
+
fix mode, run it after minimal changes.
|
|
103
|
+
|
|
104
|
+
## Fix-mode boundaries
|
|
105
|
+
|
|
106
|
+
Fix clear wiring bugs and code/doc mismatches. Do not switch purchase providers,
|
|
107
|
+
enable Web Checkout, rename stable placements, change prices, or invent campaign
|
|
108
|
+
strategy without an explicit user decision.
|