@superwall/cli 2.6.0-beta.2 → 2.6.1
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 +47 -16
- package/dist/{apple-Dc5pOPms.js → apple-BE1GBJFP.js} +17 -19
- package/dist/{approve-BSbdmOez.js → approve-yRZmvkCj.js} +9 -11
- package/dist/{assets-C_RjojkK.js → assets-DTAgbWw0.js} +3 -3
- package/dist/auth.d.ts +11 -4
- package/dist/auth.js +4 -5
- package/dist/base-zc1wl_9b.js +82 -0
- package/dist/{billing-B6HK-F_a.js → billing-C1LV4-BN.js} +3 -3
- package/dist/{build-DK88pTMW.js → build-CQd-pf7O.js} +35 -16
- package/dist/{client-x08fpvay.js → config-DCqRQTJ4.js} +162 -15
- package/dist/create-CSHGZDfB.js +18 -0
- package/dist/{create-kpqEhqkk.js → create-Costu6UT.js} +9 -9
- package/dist/{create-B6-Dr3GZ.js → create-wlCp83IH.js} +41 -41
- package/dist/{doctor-DYbm8IKQ.js → doctor-Bd9ffg51.js} +50 -10
- package/dist/entry.js +45 -40
- package/dist/{environment-BFNzLLPN.js → environment-Dn7irhZr.js} +1 -1
- package/dist/{drivers-Dyi-y9Jn.js → existing-BQMB_2AG.js} +305 -8
- package/dist/framework-DW5fqjh4.js +65 -0
- package/dist/{source-BccdO4aL.js → git-Hf9Wc7Hp.js} +34 -92
- package/dist/{held-sKq3xrsT.js → held-D5wSX2Mf.js} +9 -9
- package/dist/held-Dmf5SR3p.js +15 -0
- package/dist/{install-DsIsif39.js → install-CxyqfKFe.js} +15 -17
- package/dist/{integrate-B8eA676b.js → integrate-MkyDDzI5.js} +33 -38
- package/dist/{login-BlpfYapG.js → login-B7IqDafm.js} +3 -3
- package/dist/{login-Blhxi20A.js → login-BMHDhxAx.js} +8 -9
- package/dist/login-Cp0-BgDZ.js +13 -0
- package/dist/{lookup-Dg55W9S7.js → lookup-DkcT4E-5.js} +28 -4
- package/dist/{migrate-DoRb9jmA.js → migrate-CdFoZipj.js} +66 -45
- package/dist/{notification-url-D82msWF5.js → notification-url-D6KKeXnk.js} +4 -4
- package/dist/{open-BAqLpTSI.js → open-COJE6ryI.js} +2 -2
- package/dist/{org-C4G7WjTV.js → org-BV8wwxwc.js} +4 -4
- package/dist/{organization-CmuQwcKN.js → organization-9R_1PJKk.js} +4 -4
- package/dist/{orgs-1OzwUtpT.js → orgs-ltP8H0Nl.js} +1 -2
- package/dist/{paths-gBbqgkS7.js → paths-Cb1RfjaX.js} +1 -1
- package/dist/{playbook-BKqlv77S.js → playbook-CVGolez9.js} +10 -14
- package/dist/{products-Cqq59DBQ.js → products-CJq_iXv5.js} +1 -1
- package/dist/{promote-D0i8A0CO.js → promote-B_HnFEbX.js} +27 -28
- package/dist/{pull-DgQ_UmGv.js → pull-DF4KYVcP.js} +72 -26
- package/dist/pull-JxiMyRwY.js +30 -0
- package/dist/{pull-CiIrJ5ik.js → pull-lYRULo4v.js} +33 -39
- package/dist/push-B5py7h5y.js +29 -0
- package/dist/{push-7N4XIVtg.js → push-BZN1Qpkq.js} +23 -12
- package/dist/{push-BWsXO7FN.js → push-BnllH2Rd.js} +8 -7
- package/dist/push-DHlUMkbf.js +21 -0
- package/dist/registry-BGEYCWyD.js +22 -0
- package/dist/{registry-aAR_8VOw.js → registry-CqePfigB.js} +1287 -902
- package/dist/{resolve-CcOpO_5s.js → resolve-B4bd3Qjl.js} +4 -4
- package/dist/{resources-DNwvf8rg.js → resources-BaURbSpY.js} +15 -2
- package/dist/{run-tVYJ3V5j.js → run-Bme4Egyl.js} +15 -17
- package/dist/{scan-dv0rrY4C.js → scan-DugxddUU.js} +1 -1
- package/dist/scan-J2DILUNE.js +4 -0
- package/dist/{scope-ehZ7L1nj.js → scope-Cg1AdAfO.js} +33 -3
- package/dist/{scope-BXoQo30_.js → scope-DDYLQeZw.js} +24 -18
- package/dist/screenshot-file-Dix2Qynm.js +127 -0
- package/dist/{sdk-DEfQttek.js → sdk-BFunw4Hc.js} +1 -1
- package/dist/{framework-JFLjmD5Y.js → selection-C439nEhn.js} +4 -54
- package/dist/{series-D2ZpZ8cx.js → series-B8NJK4yS.js} +1 -1
- package/dist/{server-CcZGdYjE.js → server-C_aMxzvS.js} +40 -18
- package/dist/server-Cif9w5lM.js +33 -0
- package/dist/{session-dHBtgSN0.js → session-B7frlXXQ.js} +1 -1
- package/dist/{base-83ZTv6up.js → session-CfG3gzko.js} +8 -83
- package/dist/session-DvaPyOuH.js +5 -0
- package/dist/{migration-BUedsREQ.js → setup-DQEasPhx.js} +290 -28
- package/dist/skills/index.json +5 -0
- package/dist/skills/superwall/SKILL.md +37 -10
- package/dist/skills/superwall/references/api.md +66 -21
- package/dist/skills/superwall/references/asa.md +109 -64
- package/dist/skills/superwall/references/dashboard-links.md +65 -28
- package/dist/skills/superwall/references/data-analytics.md +1 -1
- package/dist/skills/superwall/workflows/dashboard/setup.md +15 -5
- package/dist/skills/superwall/workflows/integrate/flutter.md +9 -7
- package/dist/skills/superwall-framework/SKILL.md +248 -36
- package/dist/skills/superwall-framework/references/cli.md +98 -7
- package/dist/skills/superwall-framework/references/examples.md +2 -2
- package/dist/skills/superwall-framework/references/layout.md +30 -2
- package/dist/skills/superwall-framework/references/migrate-from-editor.md +5 -0
- package/dist/skills/superwall-framework/references/migrate-from-native.md +5 -0
- package/dist/skills/teleport/SKILL.md +154 -0
- package/dist/skills/teleport/references/experiments.md +328 -0
- package/dist/skills/teleport/references/setup.md +157 -0
- package/dist/{skills-Q7xB784d.js → skills-DnegE1A6.js} +139 -9
- package/dist/{skills-Bqz2l_bx.js → skills-MmF7IyTg.js} +8 -12
- package/dist/source-DQs6iLtC.js +82 -0
- package/dist/{source-push-CG948HrX.js → source-push-MbJjh4Ki.js} +38 -14
- package/dist/{spinner-IA6hV8nI.js → spinner-Dcr-Dqdi.js} +7 -5
- package/dist/{starter-BtUUQWhd.js → starter-BlJ_InZJ.js} +2 -2
- package/dist/{status-CB_MrFu5.js → status-DHRxg1ZA.js} +9 -11
- package/dist/{output-Ggzq5_-t.js → storage-DdIAHolY.js} +40 -1
- package/dist/storekit-De998QOt.js +203 -0
- package/dist/storekit-iBCWmeKn.js +15 -0
- package/dist/{bind-DcWIIPgk.js → theme-BrUrye-c.js} +29 -6
- package/dist/token-CKCBQ4I8.js +100 -0
- package/dist/tools-skills/animate-onboarding/SKILL.md +1 -1
- package/dist/tools-skills/mobile-design/SKILL.md +1 -1
- package/dist/tools-skills/onboarding-questions/SKILL.md +1 -1
- package/dist/tools-skills/superwall/SKILL.md +43 -17
- package/dist/tools-skills/superwall/references/api.md +74 -24
- package/dist/tools-skills/superwall/references/asa.md +109 -64
- package/dist/tools-skills/superwall/references/dashboard-links.md +65 -28
- package/dist/tools-skills/superwall/references/data-analytics.md +1 -1
- package/dist/tools-skills/superwall/workflows/dashboard/playbook.md +4 -3
- package/dist/tools-skills/superwall/workflows/dashboard/setup.md +21 -8
- package/dist/tools-skills/superwall/workflows/integrate/flutter.md +9 -7
- package/dist/tools-skills/superwall/workflows/migrate/adapty.md +4 -3
- package/dist/tools-skills/superwall/workflows/migrate/playbook.md +2 -2
- package/dist/tools-skills/superwall/workflows/migrate/qonversion.md +4 -3
- package/dist/tools-skills/superwall/workflows/migrate/revenuecat.md +4 -3
- package/dist/tools-skills/superwall-editor/SKILL.md +2 -3
- package/dist/tools-skills/teleport/SKILL.md +154 -0
- package/dist/tools-skills/teleport/references/experiments.md +328 -0
- package/dist/tools-skills/teleport/references/setup.md +157 -0
- package/dist/tools.d.ts +1 -1
- package/dist/tools.js +1232 -746
- package/dist/{try-CS3jLyoP.js → try-C8QQbG0b.js} +17 -19
- package/dist/{lock-DgSx-p8Y.js → types-Dc9U_4kp.js} +86 -80
- package/dist/upgrade-CYFdpVpi.js +27 -0
- package/dist/upgrade-D0thxCA4.js +348 -0
- package/package.json +11 -3
- package/dist/config-CGcG7GOt.js +0 -113
- package/dist/create-Du8Fx7W5.js +0 -20
- package/dist/existing-WQ3pz94o.js +0 -97
- package/dist/held-DmOhszHR.js +0 -17
- package/dist/log-C0MDCfA2.js +0 -62
- package/dist/login-D9jfRO8w.js +0 -17
- package/dist/pull-CO5HlqBe.js +0 -36
- package/dist/push-BIhGDNpL.js +0 -30
- package/dist/push-BgqTddLA.js +0 -22
- package/dist/run-B-YoyB-a.js +0 -100
- package/dist/scan-BU41gcQY.js +0 -4
- package/dist/screenshot-file-XAS0Xy0e.js +0 -16
- package/dist/server-BemmM1FV.js +0 -29
- package/dist/session-4aITGsF1.js +0 -6
- package/dist/setup-m94dpT3t.js +0 -217
- package/dist/spawn-DmmmHIP-.js +0 -71
- package/dist/storage-pR0Wb0d9.js +0 -41
- package/dist/storekit-BMxyYAHj.js +0 -17
- package/dist/storekit-CQnwlpKV.js +0 -47
- package/dist/telemetry-DU56L7Cy.js +0 -56
- package/dist/theme-DUsCh-Vd.js +0 -25
- package/dist/token-BbUeExGJ.js +0 -70
- package/dist/upgrade-CKn88PZD.js +0 -206
- package/dist/upgrade-DfD3-ClG.js +0 -7
- /package/dist/{browser-Bp3yRKlU.js → browser-BVjaf98V.js} +0 -0
- /package/dist/{client-BJQXl62Q.js → client-BwYhzITp.js} +0 -0
- /package/dist/{design-lint-CiFc78aM.js → design-lint-mgO-2SGS.js} +0 -0
- /package/dist/{devtools-ByZ6XYnn.js → devtools-B6Vp6HMy.js} +0 -0
- /package/dist/{input-MDd67UIp.js → input-DOT_2Zvb.js} +0 -0
- /package/dist/{project-NoMtbMyl.js → project-BomArwSj.js} +0 -0
- /package/dist/{reports-HYVp169R.js → reports-hbxsd3Zo.js} +0 -0
- /package/dist/{storage-Bdz5AmqS.d.ts → storage-Bh3wT1Rn.d.ts} +0 -0
- /package/dist/{timing-Ca0TXY-A.js → timing-BKEEIBij.js} +0 -0
- /package/dist/{ui-D_qf3Gvw.js → ui-hFgji1e8.js} +0 -0
|
@@ -44,9 +44,32 @@ Entry points: `superwall` (SuperwallProvider — mounted for you),
|
|
|
44
44
|
`superwall/assets`.
|
|
45
45
|
|
|
46
46
|
The framework is in public beta. The CLI has `create`/`dev`/`push`/`promote`/`publish`
|
|
47
|
-
and the rebuild forms of `migrate` by default. `Unknown command
|
|
48
|
-
|
|
49
|
-
`superwall
|
|
47
|
+
and the rebuild forms of `migrate` by default. An `Unknown command` (such as
|
|
48
|
+
`Unknown command: create`, or `Unknown command: pull` before 2.3.0) means the
|
|
49
|
+
CLI that ran is older than that command; `superwall --version` shows which one
|
|
50
|
+
ran. Inside a project, the project's own `superwall` dependency is the CLI that
|
|
51
|
+
runs, whichever copy was started, and a newer CLI prints the command that
|
|
52
|
+
updates it on stderr, e.g. `cd superwall && npm i superwall@latest`. A missing
|
|
53
|
+
`pull` is never a reason to use `--overwrite-source`.
|
|
54
|
+
|
|
55
|
+
When a newer release is out, every command (`dev` at start, the rest at the
|
|
56
|
+
end) also prints an upgrade prompt on stderr, even under `--json`:
|
|
57
|
+
|
|
58
|
+
- `Update available 2.5.2 → 2.6.0 · run cd superwall && pnpm add superwall@latest`
|
|
59
|
+
is a patch or minor: tell the user in one line, run that command, then
|
|
60
|
+
carry on (or retry the command that failed).
|
|
61
|
+
- `Major update available 2.5.2 → 3.0.0`, followed by a release-notes link and
|
|
62
|
+
`Update: <command>`, is a major: tell the user, link the notes and ask
|
|
63
|
+
before running it, since a major can break paywalls. If they decline, keep
|
|
64
|
+
working on the pinned version.
|
|
65
|
+
|
|
66
|
+
Run the command exactly as printed: the project bump when the project pins
|
|
67
|
+
`superwall`, `superwall upgrade` when it doesn't. A beta pin follows npm's
|
|
68
|
+
`next` tag, so its command says `superwall@next`; never change it to
|
|
69
|
+
`@latest`. The older-pin notice above follows the same rule: run it when
|
|
70
|
+
only the minor or patch differs, ask first when the major does. The dev
|
|
71
|
+
studio shows the same update as a banner whose Copy prompt hands you these
|
|
72
|
+
steps.
|
|
50
73
|
|
|
51
74
|
## Local references — the agent playbooks
|
|
52
75
|
|
|
@@ -88,9 +111,10 @@ curl -sL https://superwall.com/docs/framework/{page}.md # one page
|
|
|
88
111
|
| Declaring products, reading variables, the three price rules | `products` |
|
|
89
112
|
| `purchase()` outcomes, restore, the two channels | `purchases` |
|
|
90
113
|
| Introductory-offer eligibility forking (`useIntroductoryOffer`), reminder notifications | `trials` |
|
|
91
|
-
| Selling on the web — modes, prefetch, the Stripe sheet, hosted checkout, promotion codes (`useDiscount`), the shopper's email, after the purchase (`postPurchase`, `useCheckoutRedemption`), `stripeMetadata`, managed payments, blocking prepaid cards (`prepaidCards`),
|
|
92
|
-
| Custom store products (external purchase controller, custom-store Stripe products) — declared by identifier, pushed with the dashboard's store | `products` |
|
|
93
|
-
| Continuing a flow on the web (teleport: `teleport: true` or `{ route, fallbacks, completion, … }`, `router.push(route, { teleport: true })
|
|
114
|
+
| Selling on the web — modes, prefetch, the Stripe sheet, hosted checkout, promotion codes (`useDiscount`), the shopper's email, after the purchase (`postPurchase`, `useCheckoutRedemption`), `stripeMetadata`, managed payments, blocking prepaid cards (`prepaidCards`), Apple Pay availability on every host (`useApplePay`, `checkApplePay`, `examples/apple-pay`); a Stripe product inside an iOS app (app to web: always hosted checkout, priced from the dashboard at push) | `web-checkout`, `products` |
|
|
115
|
+
| Custom store products (external purchase controller, custom-store Stripe products) — declared by identifier, pushed with the dashboard's store; on a hosted web paywall `purchase()` opens the store's checkout itself | `products`, `web-checkout` |
|
|
116
|
+
| Continuing a flow on the web (teleport: `teleport: true` or `{ route, fallbacks, completion, … }`, `router.push(route, { teleport: true })` and `{ teleport: false }` to stay in the app, the Apple Pay gate (`useApplePay().available`), prefetch, the teleport screen, `useTeleport`'s typed status, returning to the app with `returnToApp({ data })` and its `"opened" \| "cancelled" \| "no_app"` result, the page's `failure` and `data` back in the app, `onReturnData`) | `teleport` |
|
|
117
|
+
| Setting up an app-to-web flow or experiment end to end (start in the iOS app, pay on the web with Apple Pay): the recommended setup, the Apple Pay gate, fallbacks, A/B tests by paywall | the `teleport` skill, then `teleport` |
|
|
94
118
|
| Web funnels — answers in the URL (`useQueryState`), resume after a browser hand-off, `shift` | `web-funnels` |
|
|
95
119
|
| Multi-page flows, router, cross-page state, shared chrome | `navigation` |
|
|
96
120
|
| Built-in + custom transitions, bottom sheets | `transitions` |
|
|
@@ -121,11 +145,23 @@ Docs beyond the framework (dashboard, SDKs, web checkout setup):
|
|
|
121
145
|
2. **`purchase()` never throws for flow outcomes** — it resolves
|
|
122
146
|
`completed | abandoned | failed`. React to the awaited result; treat
|
|
123
147
|
abandoned as an outcome. Never put the buy button in a loading state.
|
|
124
|
-
|
|
125
|
-
|
|
148
|
+
A store purchase through the SDK resolves `failed` with
|
|
149
|
+
`reason: "unknown"` (or `"superseded"` when a newer purchase replaced it)
|
|
150
|
+
on iOS only: Android reports no purchase failures, so there a failed purchase stays pending until the user
|
|
126
151
|
abandons or completes. The paywall runs no timer of its own; design the
|
|
127
152
|
pending state to be survivable and never gate irreversible UI on
|
|
128
|
-
`failed` on Android.
|
|
153
|
+
`failed` on Android. On a hosted web paywall (`*.superwall.app`),
|
|
154
|
+
`purchase()` of a custom store product (`custom|…`) opens the store's
|
|
155
|
+
checkout itself in the same tab; never POST
|
|
156
|
+
`/v1/checkout/custom-store/session` yourself. It resolves `abandoned`
|
|
157
|
+
once the tab navigates (a second tap while the first is in flight also
|
|
158
|
+
resolves `abandoned` and opens nothing), and `failed` only when the
|
|
159
|
+
backend refuses the buyer's id (a placeholder such as `null`), no web
|
|
160
|
+
checkout is configured, or the network fails. A buyer without
|
|
161
|
+
`app_user_id` still gets the checkout as an anonymous buyer and a
|
|
162
|
+
redemption code after paying. Under the Web SDK custom store products
|
|
163
|
+
resolve `failed` as unsupported; inside an app they go to the SDK's
|
|
164
|
+
purchase. What happens *after* a completed purchase is
|
|
129
165
|
`postPurchase` in config (or per call): `"dismiss"` (default), `"stay"`
|
|
130
166
|
to keep the paywall up, and on the web `"redeem"` / `{ redirect }`;
|
|
131
167
|
`"stay"` on the web is finished with `useCheckoutRedemption()`. Pass
|
|
@@ -146,6 +182,64 @@ Docs beyond the framework (dashboard, SDKs, web checkout setup):
|
|
|
146
182
|
// abandoned: the user closed the store sheet — nothing changes, nothing is said
|
|
147
183
|
```
|
|
148
184
|
|
|
185
|
+
**Why a payment failed.** A failed Stripe purchase resolves
|
|
186
|
+
`{ status: "failed", product, failure }`, and `usePurchase().failure`
|
|
187
|
+
holds the last failed purchase until the next one starts. `failure` is a
|
|
188
|
+
`CheckoutFailure`: `reason` in superwall's own words, `store: "stripe"`,
|
|
189
|
+
and Stripe's raw `code`, `declineCode` and `message` when Stripe gave
|
|
190
|
+
them. Branch on `reason`, never on Stripe's codes: the reasons stay the
|
|
191
|
+
same whichever store or payment method took the payment. `reason`
|
|
192
|
+
(`CheckoutFailureReason`) is one of:
|
|
193
|
+
|
|
194
|
+
| `reason` | Meaning |
|
|
195
|
+
| --- | --- |
|
|
196
|
+
| `card_declined` | the issuer declined and gave no more specific reason |
|
|
197
|
+
| `insufficient_funds` | not enough money or credit on the card |
|
|
198
|
+
| `expired_card` | the card has expired |
|
|
199
|
+
| `incorrect_card_details` | a wrong number, CVC, expiry, postal code or PIN |
|
|
200
|
+
| `authentication_failed` | 3D Secure or another bank check failed or was cancelled |
|
|
201
|
+
| `card_not_supported` | the card can't pay for this kind of purchase or in this currency |
|
|
202
|
+
| `limit_exceeded` | a spending, frequency or PIN-attempt limit was hit |
|
|
203
|
+
| `fraud_suspected` | the issuer or Stripe flagged it, or the card is lost or stolen |
|
|
204
|
+
| `processing_error` | the issuer or the network failed; trying again may work |
|
|
205
|
+
| `unknown` | nobody reported why, or the reason is one superwall doesn't know |
|
|
206
|
+
|
|
207
|
+
`unknown` means "no reason known": the purchase still failed, so never
|
|
208
|
+
read it as success and never guess a reason behind it. Give it the
|
|
209
|
+
generic copy. What each purchase path reports:
|
|
210
|
+
|
|
211
|
+
| Purchase | `failure.reason` |
|
|
212
|
+
| --- | --- |
|
|
213
|
+
| Stripe, direct Apple Pay on the web | the exact reason |
|
|
214
|
+
| Stripe, embedded sheet (`checkout: "sheet"`) | `unknown` until the subscriptions backend reports it; subscriptions may stay `unknown` |
|
|
215
|
+
| Stripe, hosted (redirect) checkout, every Stripe purchase in an iOS app | `unknown`; reasons aren't supported there |
|
|
216
|
+
| Stripe, teleport seen from the app | the page's exact reason when the page returned it, else as for its checkout |
|
|
217
|
+
| App Store or Play Store through the SDK | `reason: "unknown"` or `"superseded"` on the failure itself, no `failure` object; iOS only |
|
|
218
|
+
| Custom store (`custom|…`) | no reason, and no callbacks |
|
|
219
|
+
|
|
220
|
+
**Purchase callbacks.** Use superwall's callbacks, never Stripe's own
|
|
221
|
+
events: `usePurchase({ onStart, onSubmit, onComplete, onAbandon,
|
|
222
|
+
onFailure })` fires for every purchase on the paywall, whichever
|
|
223
|
+
component started it; `purchase(product, { onFailure, … })` takes the
|
|
224
|
+
same callbacks for that call only, beside the hook's. They fire on every
|
|
225
|
+
platform (native store purchases, the sheet, Apple Pay, hosted checkout,
|
|
226
|
+
teleport) except for custom store products. `onSubmit` is web checkout
|
|
227
|
+
only: the shopper submitted the sheet or authorized Apple Pay. The others
|
|
228
|
+
receive the product; `onFailure` receives the failed purchase, with
|
|
229
|
+
`reason` on it (and `store`, `code`, `declineCode`, `message` for a web
|
|
230
|
+
failure). In the embedded sheet `onFailure` fires on each decline while
|
|
231
|
+
the sheet stays open for another card, and `purchase()` resolves only
|
|
232
|
+
when the sheet is paid or closed:
|
|
233
|
+
|
|
234
|
+
```tsx
|
|
235
|
+
const { purchase, failure } = usePurchase({
|
|
236
|
+
onFailure: (failed) => track("payment_failed", { reason: failed.reason }),
|
|
237
|
+
});
|
|
238
|
+
const result = await purchase("annual");
|
|
239
|
+
if (result.status === "failed" && "failure" in result && result.failure)
|
|
240
|
+
setNotice(t(`failure.${result.failure.reason}`)); // one string per reason, unknown included
|
|
241
|
+
```
|
|
242
|
+
|
|
149
243
|
The embedded Stripe sheet waits 10 s after a tap for Stripe's checkout
|
|
150
244
|
to be ready. The wait only hides the spinner and resolves `failed`: Stripe
|
|
151
245
|
keeps loading, the buyer stays on the paywall, and the next tap opens the
|
|
@@ -158,24 +252,42 @@ Docs beyond the framework (dashboard, SDKs, web checkout setup):
|
|
|
158
252
|
on `stripe_error`; read them in Safari Web Inspector or Chrome DevTools to
|
|
159
253
|
debug a slow checkout before changing the paywall.
|
|
160
254
|
|
|
161
|
-
`useApplePay()` says whether
|
|
162
|
-
|
|
163
|
-
|
|
164
|
-
|
|
165
|
-
|
|
166
|
-
and
|
|
167
|
-
|
|
168
|
-
|
|
169
|
-
|
|
170
|
-
|
|
171
|
-
`
|
|
172
|
-
|
|
173
|
-
`
|
|
174
|
-
|
|
175
|
-
|
|
176
|
-
|
|
177
|
-
|
|
178
|
-
|
|
255
|
+
`useApplePay()` says whether Apple Pay is set up with a card on this
|
|
256
|
+
device, the same way on every host: the iOS SDK, the Web SDK, a hosted
|
|
257
|
+
web paywall, a teleport page and a plain browser. It is Apple's
|
|
258
|
+
`ApplePaySession.canMakePaymentsWithActiveCard` for the page's own Stripe
|
|
259
|
+
merchant; the answer follows the cards in Wallet, not the domain's Stripe
|
|
260
|
+
registration, and any usable card counts (Apple Cash with no balance
|
|
261
|
+
too), so it means Apple Pay is set up, not that a payment will succeed.
|
|
262
|
+
It is always defined: `{ available: true }` or
|
|
263
|
+
`{ available: false, reason, message, error? }`, never `undefined`, so
|
|
264
|
+
read `applePay.available` without `?.`. `reason`
|
|
265
|
+
(`ApplePayUnavailableReason`) is `checking` until Apple answers (usually
|
|
266
|
+
right after the first render, at most 1.5 s), `no_active_card`,
|
|
267
|
+
`unsupported_browser` (no Apple Pay JS: the Android SDK, desktop Chrome,
|
|
268
|
+
whose card sheet may still offer Apple Pay by QR code), `insecure_context`
|
|
269
|
+
(not HTTPS, `http://localhost` included), `cross_origin_frame`,
|
|
270
|
+
`check_failed` (with the browser's `error`) or `timed_out` after 1.5 s,
|
|
271
|
+
which Apple's late answer still replaces. `checking` is not available:
|
|
272
|
+
a decision made on the first render keeps the shopper in the app. Apple
|
|
273
|
+
is asked once per page and every `useApplePay()` shares the answer; a
|
|
274
|
+
check that threw or timed out is asked again, and a paywall with
|
|
275
|
+
`teleport` in its config asks as it opens. `checkApplePay()` from
|
|
276
|
+
`superwall/hooks` is the same answer as a promise for code outside
|
|
277
|
+
React, never `checking`. `useVariables().device.isApplePayAvailable` is
|
|
278
|
+
`@deprecated` (the native SDK always reports `true`); never read it.
|
|
279
|
+
|
|
280
|
+
With a product, `useApplePay(product)` adds `product: { status:
|
|
281
|
+
"preparing" | "ready" | "unavailable", reason?, message?, error? }`,
|
|
282
|
+
whether the wallet is ready to open for that product. Only Stripe's
|
|
283
|
+
check, made when it prepares the product, sees the domain's registration.
|
|
284
|
+
Its `reason` (`ApplePayProductReason`) is `unsupported_host` inside the
|
|
285
|
+
iOS and Android SDKs and Studio (a purchase never opens the wallet
|
|
286
|
+
there), the device's reason when Apple Pay is not available, else an
|
|
287
|
+
`ApplePayWalletReason`: `not_prepared` means nothing has prepared that
|
|
288
|
+
product's wallet yet, not that the device can't pay; `stripe_declined`
|
|
289
|
+
means no card in Wallet, an unregistered domain or Safari's Apple Pay
|
|
290
|
+
check setting off; the rest (`stripe_check_failed`,
|
|
179
291
|
`stripe_load_failed`, `missing_public_api_key`, `session_failed`,
|
|
180
292
|
`session_unsupported`, `show_failed`) name the step that failed. The
|
|
181
293
|
wallet opens only for a product prepared before the tap: config
|
|
@@ -189,9 +301,9 @@ Docs beyond the framework (dashboard, SDKs, web checkout setup):
|
|
|
189
301
|
const { purchase, prefetch } = usePurchase();
|
|
190
302
|
const applePay = useApplePay(reference);
|
|
191
303
|
useEffect(() => {
|
|
192
|
-
if (applePay
|
|
193
|
-
}, [applePay
|
|
194
|
-
return applePay
|
|
304
|
+
if (applePay.available) prefetch(reference, { checkout: "applePay" });
|
|
305
|
+
}, [applePay.available, prefetch, reference]);
|
|
306
|
+
return applePay.product.status === "ready" ? (
|
|
195
307
|
<button onClick={() => purchase(reference, { checkout: "applePay" })}>Apple Pay</button>
|
|
196
308
|
) : (
|
|
197
309
|
<button onClick={() => purchase(reference, { checkout: "sheet" })}>Pay with card</button>
|
|
@@ -328,7 +440,11 @@ Docs beyond the framework (dashboard, SDKs, web checkout setup):
|
|
|
328
440
|
merchant's site vs Superwall's hosted web paywall page, the teleport
|
|
329
441
|
page, the studio) branches on `useDevice().host` — `"ios-sdk" |
|
|
330
442
|
"android-sdk" | "web-sdk" | "web-paywall" | "web-teleport" | "studio" |
|
|
331
|
-
"browser"`, never `undefined` — never on the URL or `window`.
|
|
443
|
+
"browser"`, never `undefined` — never on the URL or `window`. It is
|
|
444
|
+
reliable on web pages that carry a WebKit message handler: a hosted web
|
|
445
|
+
paywall reads `"web-paywall"` and the Web SDK `"web-sdk"`; only a real
|
|
446
|
+
iOS app reads `"ios-sdk"`. Never detect a hosted page yourself through
|
|
447
|
+
`window.webPaywallCtrl`, `client_surface` or `window.webkit`. UI that
|
|
332
448
|
depends on which browser shows the page (an "open in Safari" hint for a
|
|
333
449
|
funnel opened from an Instagram ad) branches on `useDevice().browser` —
|
|
334
450
|
`SuperwallBrowser | undefined`, known from the first render — never on
|
|
@@ -356,16 +472,95 @@ Docs beyond the framework (dashboard, SDKs, web checkout setup):
|
|
|
356
472
|
true })`, or `teleport: { route }` so a push to it and a Stripe purchase
|
|
357
473
|
teleport on their own and it is prepared when the paywall opens (call
|
|
358
474
|
`useTeleport().prefetch(route)` for a route only the router teleports).
|
|
475
|
+
A Stripe `purchase()` in the app teleports to `teleport.route` with the
|
|
476
|
+
tapped product preselected there (`useTeleport().productReference`);
|
|
477
|
+
without `teleport.route` it teleports the route it was tapped on, cold.
|
|
478
|
+
Teleport pays off only when the shopper can pay with Apple Pay on the
|
|
479
|
+
web page, so check `useApplePay().available` first and keep them in the
|
|
480
|
+
app when it is `false`: `router.push(route, { teleport: false })`
|
|
481
|
+
pushes even `teleport.route` in the app, or sell the store product. A
|
|
482
|
+
paywall with `teleport` asks Apple as it opens, so the answer is
|
|
483
|
+
usually there before the first tap. To set up an app-to-web flow or
|
|
484
|
+
experiment end to end, use the `teleport` skill.
|
|
359
485
|
The route opens on the web with every `useQueryState` value carried
|
|
360
486
|
along, and the app is credited when the shopper pays. Keep answers the
|
|
361
|
-
web half needs in `useQueryState`, not component state.
|
|
362
|
-
|
|
363
|
-
|
|
487
|
+
web half needs in `useQueryState`, not component state. The
|
|
488
|
+
`teleport.route` page is pre-rendered at `superwall push` per locale,
|
|
489
|
+
Stripe product (plus none) and trial, and the browser paints it before
|
|
490
|
+
any JS runs, so its first render draws only from the locale, the
|
|
491
|
+
products and prices, the trial and `useTeleport().productReference`.
|
|
492
|
+
Read `window`, dates, random values, dark mode and `useQueryState`
|
|
493
|
+
answers in an effect or below the first frame, never in that first
|
|
494
|
+
render, or the page redraws when it takes over. A pre-render warning in
|
|
495
|
+
`push` output means those pages render in the browser instead; fix what
|
|
496
|
+
it names. A custom teleport screen renders while
|
|
497
|
+
`useTeleport().status === "waiting"` and not `returned`, reopens with
|
|
498
|
+
`open()`, and buys the fallback with plain
|
|
364
499
|
`purchase()`; count cancels and returns with `useTeleport({ onCancel,
|
|
365
500
|
onReturn })`, never with your own timers (`onCancel` is the Cancel
|
|
366
501
|
button only; an unpaid return shows as `purchase()` resolving
|
|
367
|
-
`abandoned`).
|
|
368
|
-
`
|
|
502
|
+
`abandoned`). On the web half, go back to the app only with
|
|
503
|
+
`useTeleport().returnToApp()` (or `close()` / `router.back()` on the
|
|
504
|
+
first web route) — never `openDeepLink`, `openUrl` or a hand-built scheme
|
|
505
|
+
or universal link. The framework picks the link: the universal link
|
|
506
|
+
first, the URL scheme when iOS won't follow it, which is every return
|
|
507
|
+
nobody tapped, such as one after Apple Pay is closed. While iOS asks
|
|
508
|
+
"Open in…?" it dims the page and points at Open itself; draw nothing for
|
|
509
|
+
it. `returnToApp()` resolves `"opened" | "cancelled" | "no_app"`
|
|
510
|
+
(`"cancelled"`: the shopper tapped Cancel; `"no_app"`: nothing could open
|
|
511
|
+
the app), and `useTeleport().returning` is true meanwhile. On anything
|
|
512
|
+
but `"opened"` the shopper is still on the page: leave it as it is, ready
|
|
513
|
+
to buy again.
|
|
514
|
+
|
|
515
|
+
```tsx
|
|
516
|
+
const { returnToApp } = useTeleport();
|
|
517
|
+
const result = await purchase("web");
|
|
518
|
+
if (result.status === "completed") haptics.success();
|
|
519
|
+
else if (result.status === "failed") setNotice(t("purchase.failed")); // say so, keep the button
|
|
520
|
+
else {
|
|
521
|
+
// abandoned: the shopper closed the sheet without paying
|
|
522
|
+
const back = await returnToApp(); // "opened" | "cancelled" | "no_app"
|
|
523
|
+
if (back === "opened") return;
|
|
524
|
+
// "cancelled" or "no_app": still on this page — change nothing, the buy button stays
|
|
525
|
+
}
|
|
526
|
+
```
|
|
527
|
+
|
|
528
|
+
**Sending a failed payment back to the app.** After a decline on the
|
|
529
|
+
teleport page, `returnToApp()` leaves the app the page's `failure`
|
|
530
|
+
without being asked (its return link carries `reason=failed`), and
|
|
531
|
+
`returnToApp({ data })` adds your own plain JSON, at most 16 KB: over
|
|
532
|
+
that the page logs a warning and leaves only the failure. Put new
|
|
533
|
+
fields inside `data`; never encode them in the link. In the app,
|
|
534
|
+
`useTeleport()` shows them as `failure` and `data` while `status ===
|
|
535
|
+
"waiting"`, `onFailure` fires and `usePurchase().failure` is set;
|
|
536
|
+
`useTeleport({ onReturnData })` fires once the data is read. You never
|
|
537
|
+
pass the reason yourself. Nothing is left after a paid purchase (the
|
|
538
|
+
teleport is closed), and no SDK change is needed: the app reads them
|
|
539
|
+
from the teleport's session. Until the backend reports the sheet's
|
|
540
|
+
reason, a sheet decline reaches the app as `unknown`; Apple Pay's is
|
|
541
|
+
exact. Branch on `failure.reason` in the app as anywhere else:
|
|
542
|
+
|
|
543
|
+
```tsx
|
|
544
|
+
// teleport page: send a shopper short on funds back to the App Store plan
|
|
545
|
+
const teleport = useTeleport();
|
|
546
|
+
const { purchase } = usePurchase({
|
|
547
|
+
onFailure: (failure) => {
|
|
548
|
+
if (teleport.status !== "arrived") return;
|
|
549
|
+
const offer = failure.reason === "insufficient_funds" ? "app_store" : "retry";
|
|
550
|
+
void teleport.returnToApp({ data: { offer } });
|
|
551
|
+
},
|
|
552
|
+
});
|
|
553
|
+
|
|
554
|
+
// app route: offer another way to pay
|
|
555
|
+
const back = useTeleport({ onReturnData: (data) => console.info("back from the page", data) });
|
|
556
|
+
const failure = back.status === "waiting" ? back.failure : undefined;
|
|
557
|
+
if (failure?.reason === "insufficient_funds" || failure?.reason === "card_declined") {
|
|
558
|
+
// show a store product (purchase("annual")) or Apple Pay; `unknown` says only that it failed
|
|
559
|
+
}
|
|
560
|
+
```
|
|
561
|
+
|
|
562
|
+
Fetch `teleport`; the `teleport` example is the complete flow to start
|
|
563
|
+
from.
|
|
369
564
|
13. **Shipping includes the dashboard.** A push that fails on missing
|
|
370
565
|
products is not a blocker to report — create them with
|
|
371
566
|
`superwall products create` ([references/cli.md](references/cli.md)).
|
|
@@ -447,6 +642,13 @@ superwall push # sealed version, production untouched; diagnostics har
|
|
|
447
642
|
superwall promote # ship (or: superwall publish -m "why")
|
|
448
643
|
```
|
|
449
644
|
|
|
645
|
+
After a push, promote or publish, give the user the paywall's studio link:
|
|
646
|
+
`https://app.superwall.com/{orgId}/{applicationId}/paywalls/{paywallId}/studio`.
|
|
647
|
+
The app and paywall ids are in `superwall.lock`; `orgId` is
|
|
648
|
+
`organization_id` in `GET /v2/projects`. Never link a code-first paywall to
|
|
649
|
+
the legacy `superwall.com/editor` — it cannot open one. Every other
|
|
650
|
+
dashboard page is in the `superwall` skill's `references/dashboard-links.md`.
|
|
651
|
+
|
|
450
652
|
Before calling a paywall done, run the audit at the end of the
|
|
451
653
|
`mobile-design` skill (and the framework items in
|
|
452
654
|
[references/mobile-design.md](references/mobile-design.md)) and the matrix
|
|
@@ -465,6 +667,16 @@ it, so pass it only when the user says to. In an empty folder,
|
|
|
465
667
|
`superwall pull --app <id>` gets every paywall of an app without GitHub
|
|
466
668
|
([references/cli.md](references/cli.md)).
|
|
467
669
|
|
|
670
|
+
In a pnpm monorepo whose `pnpm-workspace.yaml` does not list `superwall`,
|
|
671
|
+
a bare `pnpm install` in `superwall/` installs the parent workspace, exits
|
|
672
|
+
0 and leaves `superwall/` empty; `superwall dev` then fails with
|
|
673
|
+
`No superwall framework found`. Install and re-install there with
|
|
674
|
+
`pnpm install --ignore-workspace` and commit `superwall/pnpm-lock.yaml`, or
|
|
675
|
+
add `superwall` to the workspace patterns to share the root lockfile.
|
|
676
|
+
Never take a clean `pnpm install` exit as proof: check that
|
|
677
|
+
`superwall/node_modules/superwall` exists. bun and npm are not affected
|
|
678
|
+
([references/cli.md](references/cli.md#installing-in-a-pnpm-monorepo)).
|
|
679
|
+
|
|
468
680
|
## Report what's broken
|
|
469
681
|
|
|
470
682
|
When you confirm the framework, the CLI or these docs don't behave as they
|
|
@@ -20,6 +20,15 @@ The scaffolded package scripts mirror these (`dev`, `push`, `promote`,
|
|
|
20
20
|
`SUPERWALL_API_KEY`, which is only ever the organization's secret key
|
|
21
21
|
(`sk_…`), never an app's public `pk_…` key. `dev` needs no login.
|
|
22
22
|
|
|
23
|
+
When a newer release is out, every command prints an upgrade prompt on
|
|
24
|
+
stderr, even under `--json`: at the end, or right after the intro for `dev`,
|
|
25
|
+
which never ends. A patch or minor reads `Update available 2.5.2 → 2.6.0 ·
|
|
26
|
+
run cd superwall && pnpm add superwall@latest`; a major is a
|
|
27
|
+
`Major update available 2.5.2 → 3.0.0` block with a release-notes link.
|
|
28
|
+
Run the printed command for a patch or minor; for a major, tell the user,
|
|
29
|
+
link the release notes and ask first. A beta project's command says
|
|
30
|
+
`superwall@next`; keep it. The full rule is near the top of SKILL.md.
|
|
31
|
+
|
|
23
32
|
## `superwall create`
|
|
24
33
|
|
|
25
34
|
Inside an app that already has a `superwall/` project (or inside the
|
|
@@ -33,7 +42,10 @@ Superwall app instead of detecting one from the SDK key or asking — the
|
|
|
33
42
|
dashboard's **Copy Prompt** button hands you this form, so use the id it
|
|
34
43
|
gives rather than picking; it fails if the id isn't in the account, and it
|
|
35
44
|
cannot be combined with `--no-connect`. `--yes` accepts the defaults,
|
|
36
|
-
`--no-install` skips dependencies
|
|
45
|
+
`--no-install` skips dependencies, and `--no-git` skips the git step:
|
|
46
|
+
outside a git repository `create` otherwise runs `git init` and commits
|
|
47
|
+
the scaffold along with everything else in the folder. Pass `--no-git`
|
|
48
|
+
whenever the user or the repository's rules forbid committing on your own.
|
|
37
49
|
|
|
38
50
|
`--from <paywall-id>` rebuilds a dashboard (visual editor) paywall as
|
|
39
51
|
code: it scaffolds `paywalls/<slug>/config.ts` from the paywall's
|
|
@@ -47,10 +59,49 @@ The rebuild itself is
|
|
|
47
59
|
[migrate-from-editor.md](migrate-from-editor.md). After the scaffold the
|
|
48
60
|
CLI asks whether to run the rebuild headless with the user's agent, copy
|
|
49
61
|
the prompt, or stop; `superwall migrate <paywall-id>` asks the same later
|
|
50
|
-
(and scaffolds first if needed), `--skill` prints the prompt.
|
|
62
|
+
(and scaffolds first if needed), `--skill` prints the prompt.
|
|
63
|
+
`superwall migrate <paywall-id> --dry-run` reads the paywall and its
|
|
64
|
+
served document, runs the same refusals, prints the `paywalls/<slug>` it
|
|
65
|
+
would create and the paywall and app ids it would save in `superwall.lock`,
|
|
66
|
+
and ends with "Dry run - no changes made." It writes no files and skips
|
|
67
|
+
the agent / copy / stop choice and the studio; it still needs a login, and
|
|
68
|
+
fails like the real run when the paywall has no served document. When *you*
|
|
51
69
|
are the agent driving it, read the playbook and do the inventory step with
|
|
52
70
|
the user rather than running the headless path.
|
|
53
71
|
|
|
72
|
+
### Installing in a pnpm monorepo
|
|
73
|
+
|
|
74
|
+
`superwall/` owns its own `package.json`, lockfile and `node_modules`. In a
|
|
75
|
+
pnpm monorepo whose `pnpm-workspace.yaml` patterns don't list `superwall`
|
|
76
|
+
(say `apps/*` and `packages/*`), a bare `pnpm install` inside `superwall/`
|
|
77
|
+
installs the parent workspace instead, exits 0, and leaves `superwall/`
|
|
78
|
+
without `node_modules`; `superwall dev` then fails with `No superwall
|
|
79
|
+
framework found`. bun and npm are not affected.
|
|
80
|
+
|
|
81
|
+
`create` checks that `superwall` resolves from `superwall/` after the
|
|
82
|
+
install instead of trusting the exit code. For pnpm it retries once with
|
|
83
|
+
`pnpm install --ignore-workspace` and says so:
|
|
84
|
+
``Dependencies installed with `pnpm install --ignore-workspace` — superwall/ is outside the pnpm workspace``.
|
|
85
|
+
If the framework still doesn't resolve, with any manager, it says
|
|
86
|
+
``` `<command>` finished, but superwall is still not installed for superwall/ — install it there before `superwall dev` ```
|
|
87
|
+
and keeps that command in the next steps. With `--no-install` under a
|
|
88
|
+
pnpm workspace, the next steps add
|
|
89
|
+
``Not listed in the pnpm workspace? Use `pnpm install --ignore-workspace` instead``.
|
|
90
|
+
|
|
91
|
+
Pick one setup and keep to it:
|
|
92
|
+
|
|
93
|
+
- **Standalone (what the CLI does):** install and re-install with
|
|
94
|
+
`pnpm install --ignore-workspace` inside `superwall/`, every time: a
|
|
95
|
+
later bare `pnpm install` there is again a silent no-op. It writes
|
|
96
|
+
`superwall/pnpm-lock.yaml`; commit it.
|
|
97
|
+
- **Workspace member:** add `superwall` to the patterns in
|
|
98
|
+
`pnpm-workspace.yaml`. A bare `pnpm install` then works and the project
|
|
99
|
+
shares the root lockfile. Don't run `--ignore-workspace` there: it
|
|
100
|
+
would give a member its own lockfile.
|
|
101
|
+
|
|
102
|
+
Never treat a clean `pnpm install` exit as proof: check that
|
|
103
|
+
`superwall/node_modules/superwall` exists before running `superwall dev`.
|
|
104
|
+
|
|
54
105
|
## `superwall migrate --screen <path>`
|
|
55
106
|
|
|
56
107
|
Rebuilds a native screen — SwiftUI or UIKit (`.swift`), Jetpack Compose or
|
|
@@ -61,7 +112,12 @@ hooks, the placement to register) and an `origins` entry in
|
|
|
61
112
|
`superwall.lock`, then offers the same agent / copy / stop choice. No
|
|
62
113
|
path: it lists likely screens in the app and asks. `--screenshot <file>`
|
|
63
114
|
saves the original for **Compare › Original**; with a booted iOS simulator
|
|
64
|
-
it offers to capture one. `--skill` prints the prompt.
|
|
115
|
+
it offers to capture one. `--skill` prints the prompt. `--dry-run` reads
|
|
116
|
+
the screen, runs the same refusals, prints the `paywalls/<slug>` it would
|
|
117
|
+
create and ends with "Dry run - no changes made." It writes no files and
|
|
118
|
+
skips the screenshot prompt, the agent / copy / stop choice and the
|
|
119
|
+
studio. When the screen is already scaffolded, either dry run says so and
|
|
120
|
+
stops. The rebuild and the
|
|
65
121
|
wiring are [migrate-from-native.md](migrate-from-native.md).
|
|
66
122
|
|
|
67
123
|
## `superwall dev`
|
|
@@ -90,7 +146,8 @@ Three consequences for you, not the user:
|
|
|
90
146
|
1290 x 2796 render, the App Store size Apple takes for a product page and
|
|
91
147
|
for subscription review attachments, so it uploads without resizing.
|
|
92
148
|
- **It previews; only chat edits.** The dashboard hosts the same studio for a
|
|
93
|
-
code-first paywall (its live snapshot plus every pushed version)
|
|
149
|
+
code-first paywall (its live snapshot plus every pushed version), at
|
|
150
|
+
`https://app.superwall.com/{orgId}/{applicationId}/paywalls/{paywallId}/studio`. Nothing
|
|
94
151
|
there is point-and-click editable, so never tell the user to drag a headless
|
|
95
152
|
paywall into shape — changes ship through `push`/`promote`/`publish`. Its
|
|
96
153
|
**Chat** panel is the one exception: it edits the source in a sandbox and
|
|
@@ -100,7 +157,9 @@ Three consequences for you, not the user:
|
|
|
100
157
|
preview is a `superwall build` snapshot taken when a turn ends, not a live
|
|
101
158
|
server. So edits may have arrived that a local checkout has never seen —
|
|
102
159
|
`main` carries the source commit of the last published version; run
|
|
103
|
-
`superwall pull` to bring them into the local project.
|
|
160
|
+
`superwall pull` to bring them into the local project. A chat's edits that
|
|
161
|
+
were never published stay on `studio/<paywallId>`, and `pull` doesn't bring
|
|
162
|
+
them in.
|
|
104
163
|
|
|
105
164
|
The mechanism behind both (the envelope, the `ping` reply, hosting a paywall
|
|
106
165
|
yourself) is `curl -sL superwall.com/docs/framework/host-protocol.md`.
|
|
@@ -394,6 +453,23 @@ Promote never rebuilds — it only moves the live pointer.
|
|
|
394
453
|
Push + promote in one step. Also warns about other paywalls that are
|
|
395
454
|
pushed-but-not-live, so nothing ships half-forgotten.
|
|
396
455
|
|
|
456
|
+
## The studio link after shipping
|
|
457
|
+
|
|
458
|
+
None of `push`, `promote` or `publish` prints a dashboard link, so end each
|
|
459
|
+
with the paywall's studio link yourself:
|
|
460
|
+
|
|
461
|
+
```
|
|
462
|
+
https://app.superwall.com/{orgId}/{applicationId}/paywalls/{paywallId}/studio
|
|
463
|
+
```
|
|
464
|
+
|
|
465
|
+
`applicationId` and `paywallId` are in `superwall.lock`
|
|
466
|
+
(`apps.<platform>`, `paywalls.<name>.<platform>.paywallId`); `orgId` is
|
|
467
|
+
`organization_id` of the project holding the app in `GET /v2/projects`.
|
|
468
|
+
On several platforms, give one link per platform. A paywall never pushed
|
|
469
|
+
has no studio page yet; the builder for a new one is
|
|
470
|
+
`…/paywalls/new/studio`. Never give a code-first paywall the legacy
|
|
471
|
+
`superwall.com/editor/#/…` link.
|
|
472
|
+
|
|
397
473
|
## `superwall pull`
|
|
398
474
|
|
|
399
475
|
Merges the app's source repo into this project: teammates' paywalls and
|
|
@@ -401,6 +477,16 @@ shared files, their `superwall.lock` bindings, and the sync point the next
|
|
|
401
477
|
push merges from. Run it inside a project; it pulls the repo of every app
|
|
402
478
|
`superwall.lock` binds (`--platform <p>` limits it to those platforms).
|
|
403
479
|
|
|
480
|
+
`pull` needs superwall 2.3.0 or later. Inside a project, the project's own
|
|
481
|
+
`superwall` dependency is the CLI that runs, whichever copy was started
|
|
482
|
+
(global, `npx superwall@…`), and `superwall --version` prints its version.
|
|
483
|
+
When that copy is older than the one started, the CLI says so on stderr
|
|
484
|
+
(`Running superwall 2.0.0 pinned by superwall/package.json, not 2.6.0.
|
|
485
|
+
Update it: cd superwall && npm i superwall@latest`). So `Unknown command:
|
|
486
|
+
pull` means the project pins a version older than 2.3.0: run the update
|
|
487
|
+
command it printed, then pull again. Never fall back to `--overwrite-source`
|
|
488
|
+
because `pull` is missing.
|
|
489
|
+
|
|
404
490
|
- **Local edits stay.** Uncommitted changes in the project are merged with
|
|
405
491
|
the repo's, and only the files that changed are written.
|
|
406
492
|
- **A conflict changes nothing.** If both sides changed a file (with no
|
|
@@ -423,7 +509,10 @@ clones the app's source into an empty `<dir>/superwall/` (default: the
|
|
|
423
509
|
current directory), with its `superwall.lock` bindings, `superwall.d.ts`
|
|
424
510
|
and sync point — the way to work on an app's paywalls without its codebase
|
|
425
511
|
or GitHub. It installs nothing; it prints the next step, `cd superwall &&
|
|
426
|
-
<manager> install && <dev
|
|
512
|
+
<manager> install && <dev>`; under a pnpm workspace it adds the
|
|
513
|
+
`Not listed in the pnpm workspace?` line, and when the workspace doesn't
|
|
514
|
+
list `superwall` that install must be `pnpm install --ignore-workspace`
|
|
515
|
+
([above](#installing-in-a-pnpm-monorepo)). It refuses a directory that is already a
|
|
427
516
|
superwall project (run `superwall pull` there instead) or one that already
|
|
428
517
|
has files, and an app with no code paywall or an empty source repo (start
|
|
429
518
|
one with `superwall create --app <id>`).
|
|
@@ -460,7 +549,8 @@ than listing none.
|
|
|
460
549
|
| --- | --- |
|
|
461
550
|
| `Not a superwall project` | Run inside the app (or `superwall/`); the project's `package.json` must depend on `superwall` |
|
|
462
551
|
| `…package.json is named "superwall"` | Rename the package — that name shadows the framework |
|
|
463
|
-
| `No superwall framework found` | `bun add superwall` (or npm) inside the project |
|
|
552
|
+
| `No superwall framework found` | `bun add superwall` (or npm) inside the project. In a pnpm monorepo the message adds `A pnpm workspace above … skips a project it does not list`: run `pnpm install --ignore-workspace` in `superwall/`, or add `superwall` to `pnpm-workspace.yaml` ([above](#installing-in-a-pnpm-monorepo)) |
|
|
553
|
+
| ``… finished, but superwall is still not installed for superwall/`` | The install exited 0 without installing the framework. Run the named command in `superwall/` and check `superwall/node_modules/superwall` exists ([above](#installing-in-a-pnpm-monorepo)) |
|
|
464
554
|
| `These N products do not exist on Superwall` | Create them with `superwall products create` (above) — don't just report it — or fix the identifiers in `config.ts` |
|
|
465
555
|
| `Superwall for Agents is in private beta and isn't enabled for this app yet` | Enabled per app on Superwall's side; contact support@superwall.com. Nothing in the CLI can set it |
|
|
466
556
|
| `You can open N projects - pass --app <id\|dashboard link> or --project <id>` | Add `--app <id\|dashboard link>` to the resource command |
|
|
@@ -473,6 +563,7 @@ than listing none.
|
|
|
473
563
|
| `paywall x has never been pushed` (promote) | Push first |
|
|
474
564
|
| `superwall publish requires git` | Install git — the source snapshot is part of every publish |
|
|
475
565
|
| `… version N has no source yet` (promote) | Run `superwall push` to finish that version's source, then promote |
|
|
566
|
+
| `Unknown command: pull` | The project's own `superwall` is older than 2.3.0 and is the CLI that runs (`superwall --version`). Run the update command it prints on stderr, e.g. `cd superwall && npm i superwall@latest`, then pull again ([above](#superwall-pull)) |
|
|
476
567
|
| `Someone else published changes to …` | Run `superwall pull`, then publish again; `--overwrite-source` (this paywall only) only on the user's say-so |
|
|
477
568
|
| `The source repo differs from this project in …` | Run `superwall pull`, then publish again; `--overwrite-source` (this paywall only) only on the user's say-so |
|
|
478
569
|
| `Your project and the source repo both changed …, so nothing was pulled` | Ask the user which copy wins; to take the repo's, copy their edits aside if wanted, then `superwall pull --theirs` |
|
|
@@ -55,12 +55,12 @@ number.
|
|
|
55
55
|
|
|
56
56
|
| Example | The one idea |
|
|
57
57
|
| --- | --- |
|
|
58
|
-
| `purchase-states` | The two channels: what your `purchase()` call resolves vs what the SDK reports on its own (restore arrives as `transaction_complete` with no purchase in sight) |
|
|
58
|
+
| `purchase-states` | The two channels: what your `purchase()` call resolves vs what the SDK reports on its own (restore arrives as `transaction_complete` with no purchase in sight); a failed purchase shows one string per `result.failure.reason` and `usePurchase({ onFailure })` logs each failure. Its `annual` is a store product, so in the studio it shows the generic notice; `apple-pay` sells Stripe test prices and logs `onFailure`, `onComplete` and `usePurchase().failure` for a real reason |
|
|
59
59
|
| `trial-eligibility` | Two paywalls in one, chosen by the store — every string forks and both states read as intentional |
|
|
60
60
|
| `abandonment-offer` | `purchase()` resolving `abandoned` is a signal only this paywall can act on — push a last-chance offer (a second product, not a second design) with a custom `sheet` transition |
|
|
61
61
|
| `trial-reminders` | A local notification declared in config, scheduled by the SDK when the trial starts — the paywall needn't be open when it fires |
|
|
62
62
|
| `web-funnel` | Selling on the web: steps as routes on `shift`, the answer kept in the URL with `useQueryState` (the rule for every web-funnel answer), then `checkout: "sheet"` — `purchase()` unchanged; `prefetch(reference)` on selection so the sheet opens instantly |
|
|
63
|
-
| `teleport` | Finishing an app flow on the web: `teleport: { route: "plan" }` makes `router.push("plan")` open the plan in the browser with the app's `useQueryState` answer carried along; `fallbacks: { monthly: "annual" }` offers the App Store plan on the teleport screen; the plan page reads `useTeleport().status === "arrived"` |
|
|
63
|
+
| `teleport` | Finishing an app flow on the web: `teleport: { route: "plan" }` makes `router.push("plan")` open the plan in the browser with the app's `useQueryState` answer carried along; `fallbacks: { monthly: "annual" }` offers the App Store plan on the teleport screen; the plan page reads `useTeleport().status === "arrived"`; its `onFailure` calls `returnToApp({ data: { offer, plan } })`, and back in the app the goal route reads `useTeleport().failure` and `.data` (with `onReturnData`) to offer the App Store plan to a shopper short on funds |
|
|
64
64
|
|
|
65
65
|
`purchase-states` is the only example showing the full haptic vocabulary
|
|
66
66
|
(`success()` / `error()` keyed to outcomes). `abandonment-offer` contains
|
|
@@ -171,7 +171,7 @@ the attributes the framework stamps on `<html>`:
|
|
|
171
171
|
| android · fullscreen | 24 (drawn under the status bar) | 0 (the SDK margins the webview above the nav bar) | 0 |
|
|
172
172
|
| android · modal or drawer | 0 (sheet starts below the bar) | 0 (SDK pads it) | 0 |
|
|
173
173
|
| any · popup | 0 | 0 | 0 (the SDK insets it) |
|
|
174
|
-
| web | 0 | 0 | 0 (the browser owns its chrome) |
|
|
174
|
+
| web, including a page an app teleported to (`host` `"web-teleport"`) | 0 | 0 | 0 (the browser owns its chrome) |
|
|
175
175
|
|
|
176
176
|
A **simulator** reports its host architecture (`arm64`) as `deviceModel`,
|
|
177
177
|
not an `iPhone17,1`. SDKs that know it also report the simulated phone as
|
|
@@ -198,7 +198,35 @@ the insets can't make.
|
|
|
198
198
|
`device.safeAreaInsets` (`{ top, right, bottom, left }`); the framework
|
|
199
199
|
writes those as the `--sw-safe-area-floor-*`, so they stand in where
|
|
200
200
|
`env()` reads 0. The studio's iPhone Duo (Closed) and (Open) presets do
|
|
201
|
-
this with the insets measured in Apple's Duo simulator.
|
|
201
|
+
this with the insets measured in Apple's Duo simulator. Not on a page an
|
|
202
|
+
app teleported to: it runs in the shopper's browser, below the browser's
|
|
203
|
+
own bar, so the framework describes the browser there rather than the
|
|
204
|
+
app's phone. `<html>` gets `data-sw-platform="web"`, no `data-sw-idiom` or
|
|
205
|
+
`data-sw-cutout`, and `device.safeAreaInsets` is not written as floors, so
|
|
206
|
+
only the browser's `env()` applies, as on the pre-rendered first paint.
|
|
207
|
+
|
|
208
|
+
**Branch logic on `useDevice()`, not on `data-sw-platform`.** On a
|
|
209
|
+
teleported page `useDevice().hostPlatform` still reports the app's platform
|
|
210
|
+
(`"ios"`) and `useDevice().host` is `"web-teleport"`; only the attributes the
|
|
211
|
+
CSS reads say `web`. Key styles on `data-sw-platform`; key behaviour (copy,
|
|
212
|
+
which store, whether to show a step) on `hostPlatform` and `host`.
|
|
213
|
+
|
|
214
|
+
**No padding in the browser at all.** Zero the insets for every web host,
|
|
215
|
+
a teleported page included, and leave the in-app safe area as it is:
|
|
216
|
+
|
|
217
|
+
```css
|
|
218
|
+
:root[data-sw-platform="web"] {
|
|
219
|
+
--sw-inset-top: 0px;
|
|
220
|
+
--sw-inset-right: 0px;
|
|
221
|
+
--sw-inset-bottom: 0px;
|
|
222
|
+
--sw-inset-left: 0px;
|
|
223
|
+
}
|
|
224
|
+
```
|
|
225
|
+
|
|
226
|
+
It applies once the page takes over: the pre-rendered first paint has no
|
|
227
|
+
`data-sw-platform` yet and keeps the browser's own `env()` (0 at the top in
|
|
228
|
+
Safari), so a page with a bottom `env()` can still move by that much. An
|
|
229
|
+
edge `insets` sets in `config.ts` is written inline and wins over this rule.
|
|
202
230
|
|
|
203
231
|
`push` and `noAnimation` are fullscreen. The attributes come from the
|
|
204
232
|
device the host reports and are absent, never guessed, until the host's
|
|
@@ -19,6 +19,11 @@ screenshot, product table and an inventory, records the source in
|
|
|
19
19
|
`superwall.lock` under `origins`, and connects the project to the same
|
|
20
20
|
app. Read the brief first; every step below refers to it.
|
|
21
21
|
|
|
22
|
+
To preview first, run `superwall migrate <paywall-id> --dry-run`: it
|
|
23
|
+
needs a login, reads the paywall and its served document, prints the
|
|
24
|
+
`paywalls/<slug>` and `superwall.lock` entries it would write, and ends
|
|
25
|
+
with "Dry run - no changes made." without writing a file.
|
|
26
|
+
|
|
22
27
|
## What you are migrating from
|
|
23
28
|
|
|
24
29
|
The served document (the brief's "Served document" URL) is a rendered
|