@superwall/cli 1.4.0 → 1.6.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +21 -5
- package/dist/{actions-EfP8phmb.js → actions-Dt35nIi8.js} +3 -2
- package/dist/{api-CEwXCCoC.js → api-BOR-uXZe.js} +9 -9
- package/dist/{app-D8mEVlQo.js → app-BU27SLPX.js} +9 -9
- package/dist/{asa-BFWehnTA.js → asa-2ykGnjaV.js} +11 -11
- package/dist/{asc-DJqQmtmR.js → asc-r3xmFT0L.js} +14 -14
- package/dist/{auth-CT2DWX8r.js → auth-BWZfguI8.js} +9 -9
- package/dist/auth.js +2 -2
- package/dist/{billing-BzEnVPD2.js → billing-BsQgXXYh.js} +1 -1
- package/dist/{bind-BZxVyt9P.js → bind-BSTAinn6.js} +5 -4
- package/dist/{command-DP96_gmP.js → command-DMoMn7uc.js} +39 -16
- package/dist/{create-Q8TqqjZt.js → create-CSo6XjSm.js} +118 -91
- package/dist/dev-B0MF6z3L.js +21 -0
- package/dist/{dev-DlCcwFu5.js → dev-CuXa3J4Z.js} +29 -24
- package/dist/{doctor-CJsjHpCZ.js → doctor-DXJaDqsx.js} +10 -10
- package/dist/{drivers-UT36AnOw.js → drivers-Cr252DOJ.js} +3 -3
- package/dist/entry.js +84 -50
- package/dist/{existing-Cak1WxWB.js → existing-Ckx_g7Be.js} +6 -3
- package/dist/{feedback-DDRzoqPx.js → feedback-Dt5yebMS.js} +6 -6
- package/dist/{hosted-CEH78QVn.js → hosted-Cjekn8oJ.js} +2 -2
- package/dist/{integrate-D8jyhDzk.js → integrate-DVqhvPVq.js} +25 -66
- package/dist/{login-kneYhhk0.js → login-Bjj8QvIN.js} +6 -6
- package/dist/migrate-qmvOtp3l.js +283 -0
- package/dist/open-studio-CpHqjovS.js +1299 -0
- package/dist/{org-Cg25bcsj.js → org-CV8c849b.js} +3 -3
- package/dist/{output-csAtR6kJ.js → output-CiELrN8w.js} +15 -2
- package/dist/{pipeline-DAeI9tHs.js → pipeline-DSCHL9KA.js} +482 -9
- package/dist/{print-skill-BHVPP9cX.js → print-skill-CaHRJ8xW.js} +7 -7
- package/dist/{promote-Boek5K2d.js → promote-UMTh8Q33.js} +17 -18
- package/dist/publish-DWX8S9yZ.js +34 -0
- package/dist/push-Dox4_5Dq.js +34 -0
- package/dist/{query-B8G6T8Ba.js → query-CnSsDZ7Q.js} +10 -10
- package/dist/reports-C0xHCLnt.js +27 -0
- package/dist/{resource-DjsWVka-.js → resource-5bgyyL9B.js} +15 -15
- package/dist/{resources-s64mBHaC.js → resources-Bf9O1JNM.js} +28 -2
- package/dist/{run-BtcQJCP8.js → run-BVeZWbXx.js} +39 -22
- package/dist/{scan-DJixvuHn.js → scan-CAObNRgc.js} +44 -4
- package/dist/skills/superwall/SKILL.md +146 -0
- package/dist/skills/superwall/references/api.md +275 -0
- package/dist/skills/superwall/references/asa.md +160 -0
- package/dist/skills/superwall/references/asc.md +96 -0
- package/dist/skills/superwall/references/dashboard-links.md +57 -0
- package/dist/skills/superwall/references/data-analytics.md +893 -0
- package/dist/skills/superwall/references/docs.md +51 -0
- package/dist/skills/superwall/references/sdk-integration.md +105 -0
- package/dist/skills/superwall/references/sdk-source.md +18 -0
- package/{skills/superwall-dashboard/SKILL.md → dist/skills/superwall/workflows/dashboard/playbook.md} +3 -9
- package/{skills/superwall-dashboard/references → dist/skills/superwall/workflows/dashboard}/setup.md +1 -3
- package/dist/skills/superwall/workflows/integrate/android.md +292 -0
- package/{skills/superwall-integrate/SKILL.md → dist/skills/superwall/workflows/integrate/playbook.md} +16 -11
- package/{skills/superwall-migrate/references → dist/skills/superwall/workflows/migrate}/adapty.md +4 -4
- package/{skills/superwall-migrate/SKILL.md → dist/skills/superwall/workflows/migrate/playbook.md} +4 -10
- package/{skills/superwall-migrate/references → dist/skills/superwall/workflows/migrate}/qonversion.md +4 -4
- package/{skills/superwall-migrate/references → dist/skills/superwall/workflows/migrate}/revenuecat.md +4 -4
- package/dist/skills/superwall/workflows/placements/android.md +175 -0
- package/{skills/superwall-placements/references → dist/skills/superwall/workflows/placements}/expo.md +1 -1
- package/{skills/superwall-placements/references → dist/skills/superwall/workflows/placements}/flutter.md +1 -1
- package/{skills/superwall-placements/references → dist/skills/superwall/workflows/placements}/ios.md +1 -1
- package/{skills/superwall-placements/SKILL.md → dist/skills/superwall/workflows/placements/playbook.md} +6 -10
- package/{skills/superwall-placements/references → dist/skills/superwall/workflows/placements}/react-native.md +2 -2
- package/{skills/superwall-placements/references → dist/skills/superwall/workflows/placements}/strategy.md +4 -3
- package/dist/skills/superwall/workflows/review/android.md +120 -0
- package/{skills/superwall-review/references → dist/skills/superwall/workflows/review}/expo.md +1 -1
- package/{skills/superwall-review/references → dist/skills/superwall/workflows/review}/flutter.md +1 -1
- package/{skills/superwall-review/references → dist/skills/superwall/workflows/review}/ios.md +1 -1
- package/{skills/superwall-review/SKILL.md → dist/skills/superwall/workflows/review/playbook.md} +2 -7
- package/{skills/superwall-review/references → dist/skills/superwall/workflows/review}/react-native.md +1 -1
- package/dist/skills/superwall-framework/SKILL.md +253 -0
- package/dist/skills/superwall-framework/references/cli.md +340 -0
- package/dist/skills/superwall-framework/references/examples.md +123 -0
- package/dist/skills/superwall-framework/references/layout.md +295 -0
- package/dist/skills/superwall-framework/references/migrate-from-editor.md +208 -0
- package/dist/skills/superwall-framework/references/migrate-from-native.md +193 -0
- package/dist/skills/superwall-framework/references/mobile-design.md +371 -0
- package/dist/skills/superwall-framework/references/native/android.md +83 -0
- package/dist/skills/superwall-framework/references/native/flutter.md +65 -0
- package/dist/skills/superwall-framework/references/native/ios.md +77 -0
- package/dist/skills/superwall-framework/references/native/react-native.md +67 -0
- package/dist/skills/superwall-framework/references/responsive.md +162 -0
- package/dist/{skills-CRG1xk0G.js → skills-Cu41i-Az.js} +12 -12
- package/dist/{skills-CODut1Hn.js → skills-grTDuHlc.js} +134 -36
- package/dist/{spinner-B9dT3DBY.js → spinner-DFctF_Jw.js} +1 -1
- package/dist/{telemetry-BtkMdT-5.js → telemetry-BuCbmoux.js} +3 -3
- package/dist/{token-hM7V1KMG.js → token-mju3Q-vc.js} +3 -3
- package/dist/{ui-Lqt_zFOr.js → ui-4gLyfrgl.js} +76 -46
- package/dist/{update-CeylIjx5.js → update-DnGfpCD7.js} +2 -2
- package/dist/{upgrade-DRqUfCBT.js → upgrade-PMoj3yqJ.js} +6 -6
- package/package.json +8 -7
- package/prompts/actions/paywall-migrate.xml +24 -0
- package/prompts/actions/screen-migrate.xml +26 -0
- package/dist/git-ZwA3Mx8m.js +0 -433
- package/dist/migrate-D_x1oyTk.js +0 -114
- package/dist/publish-C-zEUnO9.js +0 -35
- package/dist/push-DUDQG-EO.js +0 -35
- package/skills/README.md +0 -118
- /package/dist/{api-output-D9ggXQIr.js → api-output-CEhN-U_N.js} +0 -0
- /package/dist/{asc-products-C6MvSy8H.js → asc-products-1e1DoGeL.js} +0 -0
- /package/dist/{params-B1zeElGa.js → params-BxgTuCzr.js} +0 -0
- /package/{skills/superwall-integrate/references → dist/skills/superwall/workflows/integrate}/expo.md +0 -0
- /package/{skills/superwall-integrate/references → dist/skills/superwall/workflows/integrate}/flutter.md +0 -0
- /package/{skills/superwall-integrate/references → dist/skills/superwall/workflows/integrate}/ios.md +0 -0
- /package/{skills/superwall-integrate/references → dist/skills/superwall/workflows/integrate}/react-native.md +0 -0
- /package/dist/{storekit-DPonXSwe.js → storekit-Dlpbq5Wv.js} +0 -0
|
@@ -0,0 +1,193 @@
|
|
|
1
|
+
# Migrating a native screen to a Superwall surface
|
|
2
|
+
|
|
3
|
+
Any screen the app would rather change without a release — update-required
|
|
4
|
+
and force-upgrade, onboarding steps, rate-us and notification prompts,
|
|
5
|
+
announcements, offers and win-backs — can become a framework surface shown
|
|
6
|
+
through a placement. The move is a **rebuild**, not a port: same copy,
|
|
7
|
+
assets and behavior, expressed as a page with the framework's hooks. The
|
|
8
|
+
CLI does the deterministic half; you rebuild the page; the user reviews it
|
|
9
|
+
next to a screenshot of the original; then the app is wired.
|
|
10
|
+
|
|
11
|
+
```bash
|
|
12
|
+
superwall migrate --screen App/UpdateRequiredView.swift # in the app's root
|
|
13
|
+
superwall migrate --screen # scan for likely screens and pick
|
|
14
|
+
```
|
|
15
|
+
|
|
16
|
+
The scan reads that one file — SwiftUI or UIKit (`.swift`), Jetpack Compose or
|
|
17
|
+
Android Views (`.kt`), React Native (`.tsx`), Flutter (`.dart`) — and writes into the project it finds (or a
|
|
18
|
+
new `superwall/`):
|
|
19
|
+
|
|
20
|
+
- `paywalls/<slug>/config.ts`: the screen's name, and a product slot per
|
|
21
|
+
store identifier the source referenced. The user confirms they exist on
|
|
22
|
+
the dashboard; a push refuses unknown products.
|
|
23
|
+
- `paywalls/<slug>/MIGRATION.md`, the brief: source path and framework,
|
|
24
|
+
every user-visible string with its dynamic values, assets and system
|
|
25
|
+
symbols, links, product ids, and each action mapped to the hook that
|
|
26
|
+
replaces it. **Read the brief first; then read the source and what it
|
|
27
|
+
imports.** Strings in string tables, view models and theme files are not
|
|
28
|
+
in the scan.
|
|
29
|
+
- `superwall.lock` → `origins["paywall/<slug>"] = { path, framework,
|
|
30
|
+
screenshot? }`, so `superwall migrate --screen <path>` picks the rebuild
|
|
31
|
+
up later and the studio knows the original.
|
|
32
|
+
|
|
33
|
+
Then the CLI offers to run the rebuild headless with the user's agent, copy
|
|
34
|
+
the prompt, or stop; `--skill` prints the prompt. When *you* are the agent
|
|
35
|
+
driving it, do the inventory with the user rather than the headless path.
|
|
36
|
+
|
|
37
|
+
## The original
|
|
38
|
+
|
|
39
|
+
The studio cannot render native UI, so **Compare › Original** shows a
|
|
40
|
+
screenshot: the CLI offers to capture a booted iOS simulator, or the user
|
|
41
|
+
passes `--screenshot <file>` (an Android emulator capture works too). It is
|
|
42
|
+
saved as `paywalls/<slug>/original.png`. Without one there is no Original
|
|
43
|
+
entry — keep the app running in the simulator beside the studio, and take
|
|
44
|
+
your own screenshots when reviewing.
|
|
45
|
+
|
|
46
|
+
## Rebuilding
|
|
47
|
+
|
|
48
|
+
Read [layout.md](layout.md) and [mobile-design.md](mobile-design.md) first,
|
|
49
|
+
and hold to the localization rule in `SKILL.md` (every string through
|
|
50
|
+
`messages/` and `t()`, even for one language). Then:
|
|
51
|
+
|
|
52
|
+
- One page per screen state that was a separate view; a single screen is
|
|
53
|
+
`app/index.tsx` alone. Tokens from the source's styles and the app's
|
|
54
|
+
theme into `:root` / `:root.dark` in `theme.css`; match the app's dark
|
|
55
|
+
appearance, not the starter's.
|
|
56
|
+
- Every string in `messages/en.ts`, read with `t()`; dynamic values as
|
|
57
|
+
`t()` parameters from `useVariables()`, `useProducts()` or placement
|
|
58
|
+
params. Every locale the app has becomes `messages/<locale>.ts`.
|
|
59
|
+
- Assets copied into `assets/`; system symbols and Material icons become
|
|
60
|
+
SVGs; fonts subset with `@font-face`.
|
|
61
|
+
- Actions, per the brief's table:
|
|
62
|
+
|
|
63
|
+
| The screen did | The surface does |
|
|
64
|
+
| --- | --- |
|
|
65
|
+
| a purchase | `usePurchase()` with the slot from `config.ts` |
|
|
66
|
+
| a restore | `useActions().restore()` |
|
|
67
|
+
| opened a URL, the App Store included | `useActions().openUrl(url)` |
|
|
68
|
+
| asked for a store review | `useActions().requestStoreReview()` |
|
|
69
|
+
| asked for notifications | `useActions().requestPermission("notification")` |
|
|
70
|
+
| dismissed itself | `useActions().close()` |
|
|
71
|
+
| navigated within its own flow | another route and `useRouter().push()` |
|
|
72
|
+
| navigated elsewhere, refreshed data, routed the app | nothing: close, and the app's placement handler continues |
|
|
73
|
+
| read app / OS version, device facts | `useDevice()`, `useVariables()` |
|
|
74
|
+
| fetched its own data | placement params or user attributes set before `register()`, read with `useVariables()` |
|
|
75
|
+
| safe-area work | nothing; the framework insets the screen |
|
|
76
|
+
|
|
77
|
+
- Only write inside `paywalls/<slug>/`. Never edit the app, never add
|
|
78
|
+
`register()` calls, never delete the native screen, never push or touch
|
|
79
|
+
campaigns. Anything with no equivalent (share sheet, camera, a settings
|
|
80
|
+
deep link the SDK cannot open) goes in the closing note as not carried
|
|
81
|
+
over.
|
|
82
|
+
|
|
83
|
+
## Wiring the app (after the user has reviewed and pushed)
|
|
84
|
+
|
|
85
|
+
The brief names the placement (the screen's name in snake_case). Where the
|
|
86
|
+
app presented the screen, register instead, with the same condition and
|
|
87
|
+
the data the screen needs as params. This is ordinary placement work:
|
|
88
|
+
the `superwall` skill's `workflows/placements/` playbook (printed by
|
|
89
|
+
`superwall integrate --skill`) is the playbook for where and how to
|
|
90
|
+
register in each SDK, and the SDK docs are the API reference —
|
|
91
|
+
fetch the page for the app's platform rather than working from memory:
|
|
92
|
+
|
|
93
|
+
```bash
|
|
94
|
+
curl -sL https://superwall.com/docs/ios/quickstart/feature-gating.md
|
|
95
|
+
curl -sL https://superwall.com/docs/android/quickstart/feature-gating.md
|
|
96
|
+
curl -sL https://superwall.com/docs/expo/quickstart/feature-gating.md
|
|
97
|
+
curl -sL https://superwall.com/docs/flutter/quickstart/feature-gating.md
|
|
98
|
+
```
|
|
99
|
+
|
|
100
|
+
```swift
|
|
101
|
+
if needsUpdate { Superwall.shared.register(placement: "update_required") }
|
|
102
|
+
```
|
|
103
|
+
|
|
104
|
+
```kotlin
|
|
105
|
+
if (needsUpdate) Superwall.instance.register("update_required")
|
|
106
|
+
```
|
|
107
|
+
|
|
108
|
+
```tsx
|
|
109
|
+
const { registerPlacement } = usePlacement();
|
|
110
|
+
if (needsUpdate) await registerPlacement({ placement: "update_required" });
|
|
111
|
+
```
|
|
112
|
+
|
|
113
|
+
```dart
|
|
114
|
+
if (needsUpdate) Superwall.shared.registerPlacement('update_required');
|
|
115
|
+
```
|
|
116
|
+
|
|
117
|
+
A screen the user must not dismiss is a **gated** surface: the campaign's
|
|
118
|
+
paywall is gated and the `feature` callback only runs when the user is
|
|
119
|
+
let through; keep the app's hard block until the surface is live. Create
|
|
120
|
+
the campaign and placement on the dashboard (`superwall integrate`, the
|
|
121
|
+
`superwall` skill's `workflows/dashboard/`), verify on a device, then delete
|
|
122
|
+
the native screen, its assets and strings. `native/<framework>.md` beside
|
|
123
|
+
this file has the full construct table for each source framework.
|
|
124
|
+
|
|
125
|
+
## Playbook: rebuilding the screen
|
|
126
|
+
|
|
127
|
+
You are inside a `superwall/` project. One surface, `paywalls/<slug>/`, was
|
|
128
|
+
scaffolded from a screen in the app: its `config.ts` carries the name and
|
|
129
|
+
any products the screen sold, its `MIGRATION.md` is your brief, and
|
|
130
|
+
everything under `app/` is a starter to replace. Rebuild the screen so it
|
|
131
|
+
looks and behaves like the source, written the way the framework is meant
|
|
132
|
+
to be used. The source file stays untouched; wiring the app is a later
|
|
133
|
+
step the user runs.
|
|
134
|
+
|
|
135
|
+
Read `layout.md` (insets, positioning, scrolling) and `mobile-design.md`
|
|
136
|
+
before writing a line, and hold to the localization rule in `SKILL.md`:
|
|
137
|
+
every string through `messages/` and `t()`, even for one language. This section fixes the order of
|
|
138
|
+
work and the boundaries; the source framework's file under `native/`
|
|
139
|
+
(`ios.md`, `android.md`, `react-native.md`, `flutter.md`) explains how the
|
|
140
|
+
source was wired and what each construct becomes.
|
|
141
|
+
|
|
142
|
+
### Docs access
|
|
143
|
+
|
|
144
|
+
```bash
|
|
145
|
+
curl -sL https://superwall.com/docs/framework/llms.txt # page index
|
|
146
|
+
curl -sL https://superwall.com/docs/framework/{page}.md # one page
|
|
147
|
+
```
|
|
148
|
+
|
|
149
|
+
### Order of work
|
|
150
|
+
|
|
151
|
+
- [ ] Read `MIGRATION.md`, then the source file it names (the path is
|
|
152
|
+
relative to this directory). Confirm the brief's inventory against
|
|
153
|
+
the code: every string, every asset, every control and what it does,
|
|
154
|
+
every conditional branch (a loading state, an error, a version
|
|
155
|
+
check). Follow imports for view models, string tables and theme
|
|
156
|
+
files that hold what the screen draws; the brief only saw one file.
|
|
157
|
+
- [ ] Design tokens: colors, type, spacing and radii from the source's
|
|
158
|
+
styles (and the app's theme if it uses one) into `:root` /
|
|
159
|
+
`:root.dark` variables in `app/theme.css`. Keep
|
|
160
|
+
`--sw-background: var(--bg)`. Match the app's dark appearance, not
|
|
161
|
+
the framework starter's.
|
|
162
|
+
- [ ] One route per screen state that was a separate view; a single
|
|
163
|
+
screen is `app/index.tsx` alone. Every control becomes the hook call
|
|
164
|
+
the brief's action table names; anything the app did after the
|
|
165
|
+
screen (routing, refreshing) is not yours — the screen closes and
|
|
166
|
+
the app's placement handler continues.
|
|
167
|
+
- [ ] Every string through messages, even for one language: the copy in
|
|
168
|
+
`messages/en.ts`, `t()` in the pages (`aria-label`s included), dynamic
|
|
169
|
+
values as `t()` parameters read from `useVariables()`, `useProducts()`
|
|
170
|
+
or placement params. Assets copied into `assets/` and referenced
|
|
171
|
+
relatively; system symbols replaced with SVGs.
|
|
172
|
+
- [ ] Layout rules from `layout.md`: the framework insets the screen; no
|
|
173
|
+
`env()`, no `position: fixed`, a pinned CTA sticky in the page, shell
|
|
174
|
+
`flex: 1 1 auto`, nothing `100dvh`.
|
|
175
|
+
- [ ] `bun run typecheck` in the project passes. Fix every diagnostic
|
|
176
|
+
`superwall dev` would print.
|
|
177
|
+
- [ ] Leave `MIGRATION.md` in place; the user deletes it after review.
|
|
178
|
+
- [ ] End your note with the placement name from the brief and the file in
|
|
179
|
+
the app that presented the screen, so the wiring step starts from it.
|
|
180
|
+
|
|
181
|
+
### Boundaries
|
|
182
|
+
|
|
183
|
+
- Only write inside `paywalls/<slug>/`. Never edit the app's source, never
|
|
184
|
+
add `register()` calls, never delete the native screen: the user wires
|
|
185
|
+
the app after reviewing the rebuild, with the framework reference below.
|
|
186
|
+
- Never run `superwall push`, `promote` or `publish`, and never touch
|
|
187
|
+
campaigns or products. The user reviews in the studio (Compare › Original
|
|
188
|
+
shows the simulator screenshot when one was captured) and ships.
|
|
189
|
+
- Never change `config.ts` except to replace a product identifier the
|
|
190
|
+
user has named. Never invent a product or a price.
|
|
191
|
+
- Anything with no framework equivalent (a native share sheet, a system
|
|
192
|
+
settings deep link the SDK cannot open, a camera view) is listed in your
|
|
193
|
+
final note as not carried over, never approximated.
|
|
@@ -0,0 +1,371 @@
|
|
|
1
|
+
# Mobile design execution
|
|
2
|
+
|
|
3
|
+
A paywall renders inside a native webview on a phone, presented by the
|
|
4
|
+
app over whatever the user was doing. It is judged against the native
|
|
5
|
+
screens around it, not against other web pages. Two things decide whether
|
|
6
|
+
it passes: reproducing the design exactly, and following the platform
|
|
7
|
+
conventions users feel but never name. These are working practices, not
|
|
8
|
+
laws — the design reference always wins over any rule here — but every
|
|
9
|
+
one of them exists because a shipped paywall got it wrong.
|
|
10
|
+
|
|
11
|
+
Read this whole file once per paywall. Skim the audit at the end before
|
|
12
|
+
every hand-off.
|
|
13
|
+
|
|
14
|
+
## The reference is the contract
|
|
15
|
+
|
|
16
|
+
- **Build 1:1.** Spacing, sizing, weights, colors, and effects come from
|
|
17
|
+
the reference, not from habit. Measure the reference at logical points
|
|
18
|
+
(a screenshot at device width) instead of eyeballing; compare your
|
|
19
|
+
build against it side by side before calling it done.
|
|
20
|
+
- **Add nothing the design doesn't show.** No extra links, badges,
|
|
21
|
+
footnotes, or affordances, however well-intentioned. If something seems
|
|
22
|
+
missing (a restore affordance, a legal link), raise it in conversation
|
|
23
|
+
— never add it to the UI unprompted.
|
|
24
|
+
- **Effects are design decisions, not defaults.** Shadows, gradients,
|
|
25
|
+
borders, blurs, and radii belong to the design system of the paywall
|
|
26
|
+
being built. If the reference is flat, build flat; if it is soft and
|
|
27
|
+
elevated, match that. Reach for an effect only when the reference shows
|
|
28
|
+
it.
|
|
29
|
+
- **A reference drawn at one size is a specification for every size.**
|
|
30
|
+
A Figma frame is 393×852 or so; the paywall ships to 320-wide phones,
|
|
31
|
+
667-tall phones, tablets and, sometimes, landscape. Where the reference
|
|
32
|
+
is silent, [responsive.md](responsive.md) says what to do; where it
|
|
33
|
+
speaks, follow it and scale the rest around it.
|
|
34
|
+
|
|
35
|
+
## The skeleton every screen shares
|
|
36
|
+
|
|
37
|
+
Native screens have a fixed anatomy, and a paywall that follows it reads
|
|
38
|
+
as native before a single color is applied:
|
|
39
|
+
|
|
40
|
+
```
|
|
41
|
+
┌──────────────────────────────┐ ← status bar / cutout — the framework's inset, not yours
|
|
42
|
+
│ [close] [skip] │ ← layout chrome, absolute inside the shell
|
|
43
|
+
│ │
|
|
44
|
+
│ scrolling content │ ← a page: ordinary padding, the page itself scrolls
|
|
45
|
+
│ (the page itself scrolls) │
|
|
46
|
+
│ │
|
|
47
|
+
│ ░░░░░░░░ fade ░░░░░░░░░░░░░░ │ ← content slides under the pinned area
|
|
48
|
+
│ [ Primary CTA (full) ] │ ← pinned bottom chrome
|
|
49
|
+
│ Restore · Terms · Privacy │
|
|
50
|
+
└──────────────────────────────┘ ← home indicator / nav bar — the framework's inset
|
|
51
|
+
```
|
|
52
|
+
|
|
53
|
+
**The framework insets the whole paywall.** Its root box fills the
|
|
54
|
+
viewport and is padded by the safe area of the device the paywall is on,
|
|
55
|
+
so everything you render already starts clear of the bars, and its
|
|
56
|
+
content box is what layout chrome positions against. Each page's scroll
|
|
57
|
+
container reaches back out to the screen edges and carries the inset as
|
|
58
|
+
its scroll padding, so content scrolls under the bars and rests clear of
|
|
59
|
+
them, like a native scroll view. You write ordinary padding. The canonical stylesheet, which every example and the
|
|
60
|
+
`superwall create` scaffold share:
|
|
61
|
+
|
|
62
|
+
```css
|
|
63
|
+
:root {
|
|
64
|
+
--sw-background: var(--bg); /* every route paints it */
|
|
65
|
+
--sw-page-inset-bottom: 0px; /* the layout's footer owns the bottom edge; drop this line if the layout has no footer below the pages */
|
|
66
|
+
}
|
|
67
|
+
```
|
|
68
|
+
|
|
69
|
+
**A background that is not white MUST also be set in `config.ts`.** This is
|
|
70
|
+
not a duplicate of `--sw-background` and it is not optional:
|
|
71
|
+
|
|
72
|
+
```ts
|
|
73
|
+
background: { light: "#fdfef6", dark: "#0c0b0a" } // config.ts
|
|
74
|
+
```
|
|
75
|
+
|
|
76
|
+
`--sw-background` paints the *routes*. `background` in config is what the
|
|
77
|
+
framework writes on `<html>`, per scheme, and `<html>` is what the shopper
|
|
78
|
+
sees when the scroll rubber-bands past the end of the content — every
|
|
79
|
+
iOS scroll does this. Set only the CSS variable and the paywall looks
|
|
80
|
+
right at rest and flashes a white band on every bounce, on a dark paywall
|
|
81
|
+
most of all. The two always carry the same colors; the audit below checks
|
|
82
|
+
it.
|
|
83
|
+
|
|
84
|
+
```css
|
|
85
|
+
.shell { /* layout.tsx — a flex child of the framework's content box */
|
|
86
|
+
display: flex;
|
|
87
|
+
flex: 1 1 auto; /* never min-height: 100dvh — that overflows the insets and scrolls */
|
|
88
|
+
flex-direction: column;
|
|
89
|
+
}
|
|
90
|
+
|
|
91
|
+
.page { /* a route — plain padding, the inset is already outside */
|
|
92
|
+
display: flex;
|
|
93
|
+
flex-direction: column;
|
|
94
|
+
min-height: 100%;
|
|
95
|
+
padding: 16px 20px 0;
|
|
96
|
+
}
|
|
97
|
+
|
|
98
|
+
.close { /* layout chrome — absolute, already below the bar */
|
|
99
|
+
position: absolute;
|
|
100
|
+
top: 4px;
|
|
101
|
+
right: 16px;
|
|
102
|
+
}
|
|
103
|
+
|
|
104
|
+
.footer { /* pinned CTA, last child of the page; sticks above the home indicator, content scrolls under the fade to the edge */
|
|
105
|
+
position: sticky;
|
|
106
|
+
bottom: 0;
|
|
107
|
+
margin-top: auto;
|
|
108
|
+
padding: 24px 0 12px;
|
|
109
|
+
background: linear-gradient(to bottom, transparent, var(--bg) 32px);
|
|
110
|
+
}
|
|
111
|
+
```
|
|
112
|
+
|
|
113
|
+
Three rules keep it honest, and [layout.md](layout.md) is the exact
|
|
114
|
+
mechanics behind them — the DOM the framework renders, what fixed,
|
|
115
|
+
absolute and sticky resolve against inside it, the inset settings and
|
|
116
|
+
their precedence, the floor table, and the debugging order:
|
|
117
|
+
|
|
118
|
+
1. **Nothing in a layout or page adds or subtracts a safe-area inset,
|
|
119
|
+
and nothing is `position: fixed`.** The root did the insets and the
|
|
120
|
+
pages already scroll under them; fixed ignores them and
|
|
121
|
+
rides along with a page during transitions. Chrome is absolute in the
|
|
122
|
+
layout or sticky in the page. The one time a control reads the safe
|
|
123
|
+
area itself is over a deliberate bleed (`insets: { top: "none" }`),
|
|
124
|
+
and then it reads `--sw-safe-area-inset-*`, never `env()`.
|
|
125
|
+
2. **Chrome sits at inset *plus* spacing, never at the inset.** The
|
|
126
|
+
floor for a class of device is a minimum (an iPhone 16 Pro's bar is
|
|
127
|
+
62px against the island floor of 59; a cutout Pixel's is taller than
|
|
128
|
+
Android's 24), so the 4–16px of ordinary spacing above the first
|
|
129
|
+
element is what absorbs the difference on the real phone.
|
|
130
|
+
3. **Sides are real.** Rotate an island phone and the cutout takes 59px of
|
|
131
|
+
one side; the framework pads the root's sides for it. Don't undo that
|
|
132
|
+
with negative margins unless the element is meant to bleed.
|
|
133
|
+
|
|
134
|
+
## Insets — when to change them
|
|
135
|
+
|
|
136
|
+
`insets` in `config.ts` is what the paywall is padded with. The default,
|
|
137
|
+
`"safe-area"`, is right for almost every paywall and needs no CSS. Change
|
|
138
|
+
it only when the design bleeds, and say so in the hand-off:
|
|
139
|
+
|
|
140
|
+
```ts
|
|
141
|
+
insets: "none" // full-bleed: the paywall draws the whole screen
|
|
142
|
+
insets: { top: "none" } // a hero under the status bar; other edges stay safe
|
|
143
|
+
insets: 24 // pixels on every edge (a web-only paywall with a fixed gutter)
|
|
144
|
+
```
|
|
145
|
+
|
|
146
|
+
Android is the platform to think about twice: its bottom inset is 0
|
|
147
|
+
because the SDK keeps the webview above the navigation bar, so a design
|
|
148
|
+
tuned to 34px of air under the CTA on iPhone needs its own 12–16px on
|
|
149
|
+
Android, and its top floor is the standard 24px status bar while cutout
|
|
150
|
+
phones can run taller.
|
|
151
|
+
|
|
152
|
+
**Tailwind**: the shell is `flex flex-1 flex-col`, chrome is
|
|
153
|
+
`absolute top-1 right-4`, a pinned CTA is `sticky bottom-0 mt-auto`, and
|
|
154
|
+
chrome over a bleed reads the safe area as an arbitrary value:
|
|
155
|
+
`top-[calc(var(--sw-safe-area-inset-top)+8px)]`. Do not reinvent the
|
|
156
|
+
variables as theme tokens.
|
|
157
|
+
|
|
158
|
+
## Scrolling and pinned chrome
|
|
159
|
+
|
|
160
|
+
- **The page scrolls; the CTA does not.** On a page with real content the
|
|
161
|
+
primary action is pinned at the bottom and the content scrolls under
|
|
162
|
+
it. A CTA that scrolls away with the copy is the single most common
|
|
163
|
+
reason a paywall underperforms a native one. Pinned means
|
|
164
|
+
`position: sticky; bottom: 0` as the page's last child, never fixed
|
|
165
|
+
([layout.md](layout.md)).
|
|
166
|
+
- The pinned area carries a **gradient from transparent to the page
|
|
167
|
+
background** so content fades out behind it instead of clipping to a
|
|
168
|
+
hard edge; set `background` in config to the same color so the native
|
|
169
|
+
loading backdrop matches.
|
|
170
|
+
- If the fade is a separate element over the content, `pointer-events:
|
|
171
|
+
none` on it so it doesn't swallow scroll gestures; a sticky footer that
|
|
172
|
+
*is* the button needs nothing.
|
|
173
|
+
- **The last content row must scroll clear of the fade**: a sticky footer
|
|
174
|
+
takes its own space at the end of the page, so give the content above it
|
|
175
|
+
a little bottom margin rather than a page padding that guesses the
|
|
176
|
+
footer's height.
|
|
177
|
+
- Let the page itself scroll. Don't invent nested scroll areas — the
|
|
178
|
+
platform (and `scrollEnabled` in config) owns scroll behavior, and a
|
|
179
|
+
nested scroller breaks the rubber-band and the SDK's scroll control.
|
|
180
|
+
The scroll container is the page's route, not the window.
|
|
181
|
+
- A short page still lays out the same way: the pinned chrome is pinned
|
|
182
|
+
whether or not there is anything to scroll, so nothing jumps when the
|
|
183
|
+
content grows by a line in another locale.
|
|
184
|
+
- Never `overflow: hidden` on `html`/`body` to "fix" scrolling. If
|
|
185
|
+
something scrolls that shouldn't, find the element that is taller than
|
|
186
|
+
the viewport.
|
|
187
|
+
|
|
188
|
+
## Platform conventions
|
|
189
|
+
|
|
190
|
+
The SDK reports the platform, and the studio's presets switch it. Design
|
|
191
|
+
for each; don't design for iOS and let Android inherit it.
|
|
192
|
+
|
|
193
|
+
### iOS
|
|
194
|
+
|
|
195
|
+
- **Close** is a small circular button (≈ 30–32px visual, 44px tap) at
|
|
196
|
+
the top-right, or top-left when the design says so; a sheet
|
|
197
|
+
(`presentation: modal`) has the system grabber and usually no close.
|
|
198
|
+
- **Back** lives in the layout as a chevron at top-left and pops the
|
|
199
|
+
stack; there is no hardware back.
|
|
200
|
+
- Buttons are rounded (12–16px) or fully pill-shaped, full width, 50–56px
|
|
201
|
+
tall; text is 17px semibold. The primary CTA is the only filled button
|
|
202
|
+
on screen.
|
|
203
|
+
- The system font (`-apple-system, BlinkMacSystemFont, "SF Pro Text"`)
|
|
204
|
+
with tight negative tracking on display sizes is what reads as native.
|
|
205
|
+
- Segmented controls, toggles and radio rows look like their UIKit
|
|
206
|
+
counterparts; if the design shows a custom one, match the design.
|
|
207
|
+
- Restore, Terms and Privacy sit under the CTA as small, muted text
|
|
208
|
+
links (13px), never as buttons.
|
|
209
|
+
|
|
210
|
+
### Android
|
|
211
|
+
|
|
212
|
+
- **Close** is an `×` or `←` at the top-left in the Material tradition,
|
|
213
|
+
or wherever the design puts it; the **hardware/gesture back** dismisses
|
|
214
|
+
the paywall through the SDK, so never rely on your own back control
|
|
215
|
+
being the only way out.
|
|
216
|
+
- The status bar on a fullscreen paywall is drawn *over* the paywall
|
|
217
|
+
(the framework's top inset handles it); the navigation bar is *not* —
|
|
218
|
+
the SDK keeps the webview above it, so the bottom inset is 0 there and
|
|
219
|
+
a pinned CTA needs its own bottom padding (12–16px) rather than
|
|
220
|
+
relying on the inset to give it air.
|
|
221
|
+
- Buttons are fully rounded (Material 3 pill) or 12px, 48–56px tall;
|
|
222
|
+
labels 16px medium; Roboto through the system stack
|
|
223
|
+
(`system-ui, Roboto, sans-serif`).
|
|
224
|
+
- Ripple is the native press feedback; a scale-down press state is an
|
|
225
|
+
acceptable web stand-in and should be subtler (0.98) than on iOS.
|
|
226
|
+
- Copy differs: "Restore purchases" is fine on both, but "Cancel anytime
|
|
227
|
+
in Settings" is iOS-specific wording; say "in Google Play" or keep it
|
|
228
|
+
store-neutral when the paywall ships to both.
|
|
229
|
+
|
|
230
|
+
### Web (a web funnel or a web-only paywall)
|
|
231
|
+
|
|
232
|
+
- No status bar, no home indicator, no SDK chrome: every inset is 0 and
|
|
233
|
+
the browser draws its own bars around the viewport. The framework's
|
|
234
|
+
wrapper is sized with `100dvh`, so a pinned CTA sits above Safari's
|
|
235
|
+
toolbar as it collapses; never size anything of your own with `100vh`.
|
|
236
|
+
- Keyboard focus is real here. Keep `:focus-visible` styles on inputs
|
|
237
|
+
and buttons; it is the one surface where you should not suppress them.
|
|
238
|
+
- Mouse exists: hover states are welcome, and the desktop layout centers
|
|
239
|
+
a phone-width column (`max-width: 28–34rem`) rather than stretching
|
|
240
|
+
cards across 1440px.
|
|
241
|
+
- Links may still go through `openUrl`, which is a plain navigation on
|
|
242
|
+
the web; keep the one call so the same page runs natively.
|
|
243
|
+
|
|
244
|
+
## Touch
|
|
245
|
+
|
|
246
|
+
- Tap targets ≥ 44×44pt on iOS, ≥ 48×48dp on Android. A visually
|
|
247
|
+
shorter control (a slim segmented control) can trade height when the
|
|
248
|
+
design demands it — width and spacing must compensate, and the hit
|
|
249
|
+
area can be extended with padding or a pseudo-element.
|
|
250
|
+
- Haptics on every meaningful tap (`useHaptics()`): `light` for
|
|
251
|
+
navigation and CTAs, `selection` for choosing between options,
|
|
252
|
+
`success` on `transaction_complete`, `error` sparingly on failures.
|
|
253
|
+
iOS fires nothing on its own inside a webview.
|
|
254
|
+
- **Suppress focus rings on tap-driven controls** in native paywalls —
|
|
255
|
+
`:focus-visible` heuristics misfire in webviews and previews, drawing
|
|
256
|
+
outlines the design never asked for. Keep keyboard focus styles only
|
|
257
|
+
where a keyboard is real (web).
|
|
258
|
+
- On controls: `-webkit-tap-highlight-color: transparent`,
|
|
259
|
+
`touch-action: manipulation`, `user-select: none`; on the page,
|
|
260
|
+
`-webkit-user-select: none` except on copy the user might want to
|
|
261
|
+
select (legal text).
|
|
262
|
+
- Never disable a control to show "loading"; the store sheet is the
|
|
263
|
+
feedback (`usePurchase().isPurchasing` exists for the rare case that
|
|
264
|
+
genuinely needs it — a buy button is not one).
|
|
265
|
+
- The whole option row is the tap target, not just its radio; the whole
|
|
266
|
+
footer link is, not just its text.
|
|
267
|
+
|
|
268
|
+
## Motion
|
|
269
|
+
|
|
270
|
+
- **Animate functional movement only** — elements that physically travel
|
|
271
|
+
between states: a segmented-control thumb sliding, a sheet presenting,
|
|
272
|
+
a progress bar filling, an accordion opening. Content that merely
|
|
273
|
+
changes (text, list rows, a price) updates in place; it does not fade,
|
|
274
|
+
slide, or stagger unless the design explicitly calls for it.
|
|
275
|
+
- **Press feedback is the baseline interaction**: a scale-down active
|
|
276
|
+
state (~0.96 iOS, ~0.98 Android; fast in ~80ms, settle out ~200ms) on
|
|
277
|
+
tappable elements, paired with a haptic. That is the whole story for
|
|
278
|
+
most controls.
|
|
279
|
+
- Entry animations are opt-in per design — and when a design has one, it
|
|
280
|
+
gates on presentation (`paywall_open`), never mount, because the SDK
|
|
281
|
+
preloads paywalls hidden (docs: `lifecycle`).
|
|
282
|
+
- Page transitions belong to the router (`push`, `slide`, `fade`,
|
|
283
|
+
`shift`, or a custom one on `[data-sw-route]`); never animate a page's
|
|
284
|
+
own root on navigation, or the two fight.
|
|
285
|
+
- Honor `prefers-reduced-motion` by collapsing durations to ~1ms; the
|
|
286
|
+
router already does for its transitions.
|
|
287
|
+
- Durations: 150–250ms for state changes, 300–500ms for spatial moves,
|
|
288
|
+
never longer than 600ms for anything the user waits on.
|
|
289
|
+
|
|
290
|
+
## Type and rendering
|
|
291
|
+
|
|
292
|
+
- Default to the system font stack unless the design specifies brand
|
|
293
|
+
type — it is what makes a webview read as native. `-apple-system,
|
|
294
|
+
BlinkMacSystemFont, system-ui, "Segoe UI", Roboto, sans-serif` covers
|
|
295
|
+
every platform in one declaration.
|
|
296
|
+
- `-webkit-text-size-adjust: 100%` on `html`; antialiased smoothing;
|
|
297
|
+
body copy 15–17px (17 matches iOS body text; 16 Android); display sizes
|
|
298
|
+
with `clamp()` so they shrink on 320px and stop growing on tablets.
|
|
299
|
+
- Line lengths: 45–65 characters on phones; on tablets and desktop web,
|
|
300
|
+
cap the column, don't stretch the measure.
|
|
301
|
+
- Custom fonts are bytes every open pays for: **subset before shipping**
|
|
302
|
+
(latin-only Manrope ≈ 24 kB vs ≈ 90 kB for the family), ship **woff2**
|
|
303
|
+
only, and treat one family plus one mono as the budget. Compress and
|
|
304
|
+
size imagery for a phone screen for the same reason (docs: `assets`).
|
|
305
|
+
- Respect the user's text size where the design allows: `rem` for type
|
|
306
|
+
and the spacing tied to it, `px` for hairlines, radii and icon boxes.
|
|
307
|
+
The host reports `fontScale`/`preferredContentSizeCategory` if a design
|
|
308
|
+
needs to clamp at the extremes.
|
|
309
|
+
|
|
310
|
+
## Color and dark mode
|
|
311
|
+
|
|
312
|
+
- Dark mode styles hang off the `:root.dark` class — never
|
|
313
|
+
`prefers-color-scheme` (docs: `lifecycle`). Design both palettes even
|
|
314
|
+
when the reference shows only one, and check both in the studio.
|
|
315
|
+
- Set `background` in config to the page background in both schemes; it
|
|
316
|
+
paints the native backdrop and the loading spinner, so the load is
|
|
317
|
+
seamless.
|
|
318
|
+
- Semantic tokens, never raw hex in components: `--bg`, `--fg`,
|
|
319
|
+
`--surface`, `--accent`, then muted/border/wash derived with
|
|
320
|
+
`color-mix()` so the dark palette needs only the base values.
|
|
321
|
+
- Contrast: body text ≥ 4.5:1, large display ≥ 3:1, on *both* schemes.
|
|
322
|
+
Muted text is the usual offender; 55% of the foreground is about the
|
|
323
|
+
floor on a light background.
|
|
324
|
+
- Never paint pure `#000` behind content in dark mode unless the design
|
|
325
|
+
is OLED-black on purpose; `#0d0f12`–`#1c1b19` is what native dark
|
|
326
|
+
screens use.
|
|
327
|
+
|
|
328
|
+
## Images and media
|
|
329
|
+
|
|
330
|
+
- Ship hero imagery at 2× the logical size it renders, compressed, and
|
|
331
|
+
in a modern format; a 1290-wide PNG for a 393-wide hero is the wrong
|
|
332
|
+
file.
|
|
333
|
+
- A hero that bleeds to the top edge sits *under* the status bar on
|
|
334
|
+
purpose — `insets: { top: "none" }` in config, the layout's absolute
|
|
335
|
+
close button positioned from `--sw-safe-area-inset-top`, and a scrim on
|
|
336
|
+
the image so the bar's text stays legible in both schemes.
|
|
337
|
+
- Video and Lottie autoplay muted, loop only when the design loops, and
|
|
338
|
+
pause when the page is covered (`useIsFocused()`).
|
|
339
|
+
|
|
340
|
+
## The pre-ship audit
|
|
341
|
+
|
|
342
|
+
Run it in the studio on every preset and both schemes; a paywall is not
|
|
343
|
+
done until every line passes.
|
|
344
|
+
|
|
345
|
+
- [ ] No `env()` and no `position: fixed` in the stylesheet; no layout or
|
|
346
|
+
page adds a safe-area inset of its own; nothing of yours is
|
|
347
|
+
`100dvh`/`100vh` tall; `insets` in config only where the design
|
|
348
|
+
bleeds, and then the chrome over the bleed reads
|
|
349
|
+
`--sw-safe-area-inset-*`.
|
|
350
|
+
- [ ] Close/back sits below the bar on iPhone SE (home button, 20px), an
|
|
351
|
+
island phone, a Pixel, an iPad; and clear of the cutout in landscape
|
|
352
|
+
where the app allows rotation.
|
|
353
|
+
- [ ] The primary CTA is pinned, full width, above the home indicator on
|
|
354
|
+
iOS and 12px+ above the bottom on Android; the last content row
|
|
355
|
+
scrolls clear of it.
|
|
356
|
+
- [ ] Nothing overflows horizontally at 320px; nothing is clipped at 667px
|
|
357
|
+
tall with the largest locale's copy.
|
|
358
|
+
- [ ] Both schemes designed and checked; `background` in `config.ts` and
|
|
359
|
+
`--sw-background` in CSS set to the same colors. Scroll past the end
|
|
360
|
+
of a page in both schemes: any white flash means `background` is
|
|
361
|
+
missing from config.
|
|
362
|
+
- [ ] Tap targets ≥ 44px; haptics on every meaningful tap; no focus rings
|
|
363
|
+
on tap controls natively; `aria-label` on icon buttons.
|
|
364
|
+
- [ ] No loading state on the buy button; unpriced state designed;
|
|
365
|
+
abandoned purchase handled.
|
|
366
|
+
- [ ] Copy is store-neutral where the paywall ships to both stores, and
|
|
367
|
+
every string, `aria-label`s included, comes from `messages/` through
|
|
368
|
+
`t()`, with prices interpolated and guarded, never in a catalog.
|
|
369
|
+
- [ ] Custom fonts subset and woff2; images sized for a phone.
|
|
370
|
+
- [ ] The configured presentation (`modal`, `drawer`, `popup`) checked as
|
|
371
|
+
a sheet, not only as fullscreen.
|
|
@@ -0,0 +1,83 @@
|
|
|
1
|
+
# Android source screens (Jetpack Compose and Views)
|
|
2
|
+
|
|
3
|
+
How the screen you are rebuilding was wired, what each construct becomes,
|
|
4
|
+
and what the user changes in the app once the rebuild is reviewed.
|
|
5
|
+
|
|
6
|
+
## Reading the source
|
|
7
|
+
|
|
8
|
+
| In the source | Becomes |
|
|
9
|
+
| --- | --- |
|
|
10
|
+
| `Text("…")`, `stringResource(R.string.x)`, `getString(R.string.x)`, `android:text="@string/x"` in a layout | a `messages/en.ts` entry read with `t()`; the text is in `res/values/strings.xml`, and every `res/values-<locale>/strings.xml` becomes `messages/<locale>.ts` |
|
|
11
|
+
| `"$value"` / `"${expr}"` in a string, `%1$s` placeholders in a resource | a `t()` parameter |
|
|
12
|
+
| `painterResource(R.drawable.x)`, `android:src="@drawable/x"`, `app:srcCompat` | the file from `res/drawable*` copied into `assets/` (take the vector XML as SVG or the highest-density PNG) |
|
|
13
|
+
| `Icons.Default.X` / `Icons.Outlined.X` | an SVG in `assets/`; Material icons are not on the web unless you add them |
|
|
14
|
+
| `FontFamily(Font(R.font.x))`, `res/font` | the font file, subset, in `assets/`; `@font-face` in `theme.css` |
|
|
15
|
+
| `MaterialTheme.colorScheme`, `colorResource(R.color.x)`, `res/values/colors.xml`, `values-night` | `:root` / `:root.dark` variables, both themes from the resources |
|
|
16
|
+
| `isSystemInDarkTheme()`, `Configuration.UI_MODE_NIGHT_MASK` | `useColorScheme()` from the framework, or `:root.dark` CSS |
|
|
17
|
+
| `BillingClient.launchBillingFlow`, RevenueCat `purchaseWith` | `usePurchase()` with the slot from `config.ts` |
|
|
18
|
+
| `queryPurchasesAsync`, `restorePurchases` | `useActions().restore()` |
|
|
19
|
+
| `Intent(Intent.ACTION_VIEW, uri)`, `CustomTabsIntent`, `LocalUriHandler.openUri` (Play Store links included) | `useActions().openUrl(url)` |
|
|
20
|
+
| `ReviewManager.requestReviewFlow` / `launchReviewFlow` | `useActions().requestStoreReview()` |
|
|
21
|
+
| `POST_NOTIFICATIONS` via `RequestPermission()` / `rememberPermissionState` | `useActions().requestPermission("notification")` |
|
|
22
|
+
| `finish()`, `onBackPressedDispatcher`, `popBackStack()`, `onDismiss` | `useActions().close()` |
|
|
23
|
+
| `navController.navigate` to a destination in the same flow | a second route under `app/` and `useRouter().push()` |
|
|
24
|
+
| `startActivity` / `navigate` to something outside the flow (settings, a web view) | close and let the app's placement handler route; note it |
|
|
25
|
+
| `ViewModel`, `StateFlow`, `remember { }` state | React state; data the ViewModel fetched becomes a placement param or a user attribute the app sets before `register()` |
|
|
26
|
+
| `BuildConfig.VERSION_NAME`, `Build.VERSION` reads | `useDevice()` and `useVariables()`; the SDK reports app and OS versions |
|
|
27
|
+
| `WindowInsets`, `systemBarsPadding()`, `fitsSystemWindows` | nothing; the framework insets the screen (`layout.md`); Android's bottom inset is 0 because the SDK keeps the paywall above the navigation bar |
|
|
28
|
+
|
|
29
|
+
A Views screen splits across an Activity or Fragment, a layout XML under
|
|
30
|
+
`res/layout`, and `strings.xml`; the scan resolved `R.string` and
|
|
31
|
+
`@string/` references into the brief, but read the layout for structure and
|
|
32
|
+
`res/values-night` for the dark theme. A Compose screen keeps its structure in
|
|
33
|
+
the composable; follow `viewModel()` and `hiltViewModel()` to the data.
|
|
34
|
+
|
|
35
|
+
## Wiring the app afterwards (the user does this, with you, after review)
|
|
36
|
+
|
|
37
|
+
This is a placement at a feature gate — the `superwall` skill's
|
|
38
|
+
`workflows/placements/` playbook (`superwall integrate --skill` includes it)
|
|
39
|
+
is the full playbook for
|
|
40
|
+
where and how to register, and the SDK docs are the reference for the
|
|
41
|
+
API; fetch them rather than working from memory:
|
|
42
|
+
|
|
43
|
+
```bash
|
|
44
|
+
curl -sL https://superwall.com/docs/android/quickstart/feature-gating.md # Superwall.instance.register(placement) { }
|
|
45
|
+
curl -sL https://superwall.com/docs/android/llms.txt # every other page
|
|
46
|
+
```
|
|
47
|
+
|
|
48
|
+
Where the app presented the screen:
|
|
49
|
+
|
|
50
|
+
```kotlin
|
|
51
|
+
// before
|
|
52
|
+
if (needsUpdate) startActivity(Intent(this, UpdateRequiredActivity::class.java))
|
|
53
|
+
|
|
54
|
+
// after
|
|
55
|
+
if (needsUpdate) Superwall.instance.register("update_required")
|
|
56
|
+
```
|
|
57
|
+
|
|
58
|
+
or in Compose:
|
|
59
|
+
|
|
60
|
+
```kotlin
|
|
61
|
+
// before
|
|
62
|
+
if (needsUpdate) navController.navigate("update_required")
|
|
63
|
+
|
|
64
|
+
// after
|
|
65
|
+
LaunchedEffect(needsUpdate) {
|
|
66
|
+
if (needsUpdate) Superwall.instance.register("update_required")
|
|
67
|
+
}
|
|
68
|
+
```
|
|
69
|
+
|
|
70
|
+
- The placement name is in the brief. Register it with the same condition
|
|
71
|
+
the app used, from UI code with an Activity in the foreground; pass what
|
|
72
|
+
the screen needs as `params` instead of reading it in the screen. Never
|
|
73
|
+
register inside a composable body.
|
|
74
|
+
- A screen the user must not dismiss (a forced update) is a **gated**
|
|
75
|
+
surface: the campaign's paywall is set to gated, and the `feature` lambda
|
|
76
|
+
passed to `register` only runs when the surface reports the user
|
|
77
|
+
through. Keep the app's own hard block until the surface is live.
|
|
78
|
+
- Create the campaign and placement on the dashboard for that placement
|
|
79
|
+
name and point it at the pushed surface; `superwall integrate` and the
|
|
80
|
+
`superwall` skill's `workflows/dashboard/` playbook cover it.
|
|
81
|
+
- Delete the native screen, its layout, drawables and strings once the
|
|
82
|
+
campaign is live and verified on a device. Keep a release with both for
|
|
83
|
+
one cycle if users on old builds still need the native one.
|