@superwall/cli 2.6.1 → 2.7.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/dist/{apple-BE1GBJFP.js → apple-DfYTDEJy.js} +16 -16
- package/dist/{approve-yRZmvkCj.js → approve-CoQJhii4.js} +7 -7
- package/dist/{assets-DTAgbWw0.js → assets-BN0tFoj7.js} +3 -3
- package/dist/auth.d.ts +1 -1
- package/dist/auth.js +3 -3
- package/dist/{base-zc1wl_9b.js → base-DAnzMjI8.js} +2 -2
- package/dist/{billing-C1LV4-BN.js → billing-CFGrG-WZ.js} +3 -3
- package/dist/{build-CQd-pf7O.js → build-CTBvzIG8.js} +10 -10
- package/dist/{config-DCqRQTJ4.js → config-CJRNScT0.js} +4 -4
- package/dist/{create-wlCp83IH.js → create-BLs-0ETi.js} +29 -29
- package/dist/create-C_kjQp0N.js +18 -0
- package/dist/{create-Costu6UT.js → create-aWzdpjJU.js} +8 -8
- package/dist/{doctor-Bd9ffg51.js → doctor-ChI2Kfru.js} +21 -21
- package/dist/entry.js +28 -29
- package/dist/{environment-Dn7irhZr.js → environment-BQiaGqjB.js} +1 -1
- package/dist/{existing-BQMB_2AG.js → existing-Cxg_gSN1.js} +8 -8
- package/dist/{git-Hf9Wc7Hp.js → git-D9ooAMt7.js} +1 -1
- package/dist/held-CQMCqJMa.js +15 -0
- package/dist/{held-D5wSX2Mf.js → held-CmvNRCRD.js} +327 -22
- package/dist/{scope-DDYLQeZw.js → input-ApyzIzVy.js} +48 -7
- package/dist/{install-CxyqfKFe.js → install-DM0JBdpE.js} +12 -12
- package/dist/{integrate-MkyDDzI5.js → integrate-ZQUaScQ0.js} +21 -22
- package/dist/login-Cnt3UZKV.js +13 -0
- package/dist/{login-B7IqDafm.js → login-CvzBt9eM.js} +2 -2
- package/dist/{login-BMHDhxAx.js → login-Oo2NWLlX.js} +7 -7
- package/dist/{lookup-DkcT4E-5.js → lookup-CHLrO7v7.js} +3 -3
- package/dist/{migrate-CdFoZipj.js → migrate-mFKBset8.js} +30 -30
- package/dist/{notification-url-D6KKeXnk.js → notification-url-Dpx0pbYs.js} +3 -3
- package/dist/{open-COJE6ryI.js → open-CxgE8kLT.js} +2 -2
- package/dist/{org-BV8wwxwc.js → org-0KDPRSlc.js} +4 -4
- package/dist/{organization-9R_1PJKk.js → organization-Cg--QQtz.js} +4 -4
- package/dist/{orgs-ltP8H0Nl.js → orgs-Df8DzIav.js} +1 -1
- package/dist/{paths-Cb1RfjaX.js → paths-B4FNcaHO.js} +1 -1
- package/dist/{playbook-CVGolez9.js → playbook-pFhIg_0e.js} +10 -10
- package/dist/{promote-B_HnFEbX.js → promote-Crwz1xI0.js} +23 -23
- package/dist/{pull-DF4KYVcP.js → pull-BixwETu1.js} +10 -10
- package/dist/pull-C0gY7HGj.js +30 -0
- package/dist/{pull-lYRULo4v.js → pull-D8GfsKha.js} +30 -30
- package/dist/{push-BZN1Qpkq.js → push-BKoav_FU.js} +10 -10
- package/dist/{push-BnllH2Rd.js → push-BNFvZHUM.js} +8 -8
- package/dist/push-DOaBj8hr.js +29 -0
- package/dist/push-uWv5P0LA.js +21 -0
- package/dist/{registry-CqePfigB.js → registry-BPqRG08G.js} +268 -433
- package/dist/registry-DGHTk7l-.js +21 -0
- package/dist/{resolve-B4bd3Qjl.js → resolve-CarLrF4b.js} +3 -3
- package/dist/{resources-BaURbSpY.js → resources-BeXleviK.js} +15 -34
- package/dist/{run-Bme4Egyl.js → run-naBCXCfn.js} +14 -14
- package/dist/{scan-DugxddUU.js → scan-CtYVCqDS.js} +1 -1
- package/dist/scan-KWnscsk-.js +4 -0
- package/dist/{sdk-BFunw4Hc.js → sdk-BKVRAv23.js} +2 -2
- package/dist/{selection-C439nEhn.js → selection-CpEfqw2b.js} +1 -1
- package/dist/{series-B8NJK4yS.js → series-C9OU5kd7.js} +1 -1
- package/dist/server-DjBnyiwD.js +33 -0
- package/dist/{server-C_aMxzvS.js → server-Dp5Imq3v.js} +11 -11
- package/dist/{session-CfG3gzko.js → session-6HA1OwHe.js} +6 -6
- package/dist/session-BatiAUPQ.js +5 -0
- package/dist/{session-B7frlXXQ.js → session-BpLOLurZ.js} +1 -1
- package/dist/{setup-DQEasPhx.js → setup-RL-5c6SV.js} +10 -10
- package/dist/skills/superwall/SKILL.md +8 -1
- package/dist/skills/superwall/references/api.md +34 -3
- package/dist/skills/superwall/references/asc.md +5 -1
- package/dist/skills/superwall/workflows/dashboard/playbook.md +1 -1
- package/dist/skills/superwall/workflows/dashboard/setup.md +6 -2
- package/dist/skills/superwall/workflows/migrate/adapty.md +1 -1
- package/dist/skills/superwall/workflows/migrate/playbook.md +6 -1
- package/dist/skills/superwall/workflows/migrate/qonversion.md +1 -1
- package/dist/skills/superwall/workflows/migrate/revenuecat.md +1 -1
- package/dist/skills/superwall/workflows/placements/android.md +4 -1
- package/dist/skills/superwall/workflows/placements/expo.md +4 -1
- package/dist/skills/superwall/workflows/placements/flutter.md +4 -1
- package/dist/skills/superwall/workflows/placements/ios.md +4 -1
- package/dist/skills/superwall/workflows/placements/playbook.md +6 -1
- package/dist/skills/superwall/workflows/placements/react-native.md +4 -1
- package/dist/skills/superwall/workflows/placements/strategy.md +4 -1
- package/dist/skills/superwall-framework/SKILL.md +54 -4
- package/dist/skills/superwall-framework/references/cli.md +6 -0
- package/dist/skills/superwall-framework/references/elements-checkout.md +457 -0
- package/dist/skills/superwall-framework/references/examples.md +1 -0
- package/dist/skills/superwall-framework/references/layout.md +10 -0
- package/dist/skills/teleport/SKILL.md +1 -1
- package/dist/{skills-DnegE1A6.js → skills-C1ku2pgy.js} +5 -5
- package/dist/{skills-MmF7IyTg.js → skills-CkAWJveA.js} +8 -8
- package/dist/{source-push-MbJjh4Ki.js → source-push-D59hV02W.js} +6 -6
- package/dist/{spinner-Dcr-Dqdi.js → spinner-hTCJZAoJ.js} +42 -7
- package/dist/{starter-BlJ_InZJ.js → starter-jYb2nmlb.js} +3 -3
- package/dist/{status-DHRxg1ZA.js → status-DrD9CHtK.js} +7 -7
- package/dist/{storage-DdIAHolY.js → storage-D0Q4xBi-.js} +1 -1
- package/dist/storekit-CAOpa6_f.js +14 -0
- package/dist/{storekit-De998QOt.js → storekit-TLBxGIrN.js} +5 -5
- package/dist/{theme-BrUrye-c.js → theme-Bvv0yrk_.js} +5 -5
- package/dist/{token-CKCBQ4I8.js → token-SEWilQo9.js} +1 -1
- package/dist/tools-skills/superwall/SKILL.md +8 -1
- package/dist/tools-skills/superwall/references/api.md +34 -3
- package/dist/tools-skills/superwall/references/asc.md +5 -1
- package/dist/tools-skills/superwall/workflows/dashboard/playbook.md +1 -1
- package/dist/tools-skills/superwall/workflows/dashboard/setup.md +6 -2
- package/dist/tools-skills/superwall/workflows/migrate/adapty.md +1 -1
- package/dist/tools-skills/superwall/workflows/migrate/playbook.md +6 -1
- package/dist/tools-skills/superwall/workflows/migrate/qonversion.md +1 -1
- package/dist/tools-skills/superwall/workflows/migrate/revenuecat.md +1 -1
- package/dist/tools-skills/superwall/workflows/placements/android.md +4 -1
- package/dist/tools-skills/superwall/workflows/placements/expo.md +4 -1
- package/dist/tools-skills/superwall/workflows/placements/flutter.md +4 -1
- package/dist/tools-skills/superwall/workflows/placements/ios.md +4 -1
- package/dist/tools-skills/superwall/workflows/placements/playbook.md +6 -1
- package/dist/tools-skills/superwall/workflows/placements/react-native.md +4 -1
- package/dist/tools-skills/superwall/workflows/placements/strategy.md +4 -1
- package/dist/tools-skills/teleport/SKILL.md +1 -1
- package/dist/tools.d.ts +4 -2
- package/dist/tools.js +1352 -1187
- package/dist/{try-C8QQbG0b.js → try-BpMpLGCs.js} +15 -15
- package/dist/{ui-hFgji1e8.js → ui-Dye-QvEj.js} +26 -1
- package/dist/{upgrade-D0thxCA4.js → upgrade-BLFWdbGR.js} +7 -7
- package/dist/upgrade-BzN7PjKg.js +27 -0
- package/package.json +2 -2
- package/dist/create-CSHGZDfB.js +0 -18
- package/dist/held-Dmf5SR3p.js +0 -15
- package/dist/input-DOT_2Zvb.js +0 -42
- package/dist/login-Cp0-BgDZ.js +0 -13
- package/dist/pull-JxiMyRwY.js +0 -30
- package/dist/push-B5py7h5y.js +0 -29
- package/dist/push-DHlUMkbf.js +0 -21
- package/dist/registry-BGEYCWyD.js +0 -22
- package/dist/scan-J2DILUNE.js +0 -4
- package/dist/server-Cif9w5lM.js +0 -33
- package/dist/session-DvaPyOuH.js +0 -5
- package/dist/storekit-iBCWmeKn.js +0 -15
- package/dist/upgrade-CYFdpVpi.js +0 -27
- /package/dist/{design-lint-mgO-2SGS.js → design-lint-CeG3_ZWN.js} +0 -0
- /package/dist/{devtools-B6Vp6HMy.js → devtools-B3tCQFD-.js} +0 -0
- /package/dist/{download-DhGd4hOB.js → download-DVFHIwia.js} +0 -0
- /package/dist/{project-BomArwSj.js → project-Dml4t7jO.js} +0 -0
- /package/dist/{reports-hbxsd3Zo.js → reports-CJQ-8sj4.js} +0 -0
- /package/dist/{screenshot-file-Dix2Qynm.js → screenshot-file-CcqMLpL5.js} +0 -0
- /package/dist/{source-DQs6iLtC.js → source-Ct9kOCAb.js} +0 -0
- /package/dist/{storage-Bh3wT1Rn.d.ts → storage-BaK-MUM8.d.ts} +0 -0
- /package/dist/{timing-BKEEIBij.js → timing-m0ZUzYiP.js} +0 -0
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
---
|
|
2
2
|
name: superwall-framework
|
|
3
|
-
description: Author any screen an app should be able to change without a release — paywalls, offers, onboarding funnels, update-required and force-upgrade screens, lifecycle prompts, announcements, web checkout flows — as React mini-apps with the superwall framework (the `superwall` npm package). Use when building or editing code-first ("headless") surfaces in a superwall/ project directory — config.ts, app/ routes, hooks (useProducts, usePurchase, useDiscount, useActions…), navigation, localization, assets, insets and mobile layout — when running `superwall create/dev/push/promote/publish/pull` (including pulling a teammate's paywalls or an app's source into an empty folder with `superwall pull --app`), when rebuilding a dashboard (visual editor) paywall as code (`superwall migrate <id>`), or when a native SwiftUI / Kotlin / React Native / Flutter screen of that kind is being built and should become a Superwall surface instead. The default for any screen an agent builds that the user would rather change after shipping than release for (paywalls, onboarding, update-required, lifecycle prompts, announcements, offers, web flows); the browser visual editor (superwall-editor) is legacy and only for explicit edits inside it. NOT for general CLI/resource management (superwall).
|
|
3
|
+
description: Author any screen an app should be able to change without a release — paywalls, offers, onboarding funnels, update-required and force-upgrade screens, lifecycle prompts, announcements, web checkout flows — as React mini-apps with the superwall framework (the `superwall` npm package). Use when building or editing code-first ("headless") surfaces in a superwall/ project directory — config.ts, app/ routes, hooks (useProducts, usePurchase, useDiscount, useActions…), custom checkout forms built from Stripe Elements (the elements checkout mode, `superwall/checkout`, `superwall/checkout/stripe`), navigation, localization, assets, insets and mobile layout — when running `superwall create/dev/push/promote/publish/pull` (including pulling a teammate's paywalls or an app's source into an empty folder with `superwall pull --app`), when rebuilding a dashboard (visual editor) paywall as code (`superwall migrate <id>`), or when a native SwiftUI / Kotlin / React Native / Flutter screen of that kind is being built and should become a Superwall surface instead. The default for any screen an agent builds that the user would rather change after shipping than release for (paywalls, onboarding, update-required, lifecycle prompts, announcements, offers, web flows); the browser visual editor (superwall-editor) is legacy and only for explicit edits inside it. NOT for general CLI/resource management (superwall).
|
|
4
4
|
---
|
|
5
5
|
|
|
6
6
|
# The superwall framework
|
|
@@ -89,6 +89,7 @@ web page inside an app.
|
|
|
89
89
|
| Migrating a dashboard (visual editor) paywall to code — `superwall create --from <id>`, reading the editor's document store, the element / action / state mapping, Compare › Original, the review gate, the campaign switch, and the rebuild playbook the CLI hands its agent | [references/migrate-from-editor.md](references/migrate-from-editor.md) |
|
|
90
90
|
| Migrating a native screen to a surface — `superwall migrate --screen <path>`, what the scan reads, the screenshot original, the rebuild playbook, wiring `register()` afterwards | [references/migrate-from-native.md](references/migrate-from-native.md) |
|
|
91
91
|
| What each native construct becomes, per source framework, and the `register()` wiring in that SDK | [references/native/ios.md](references/native/ios.md) (SwiftUI, UIKit) · [android.md](references/native/android.md) (Compose, Views) · [react-native.md](references/native/react-native.md) · [flutter.md](references/native/flutter.md) |
|
|
92
|
+
| **A checkout form of the paywall's own — must-follow.** `checkout: "elements"`: `<StripeCheckout>`, `useCheckout()`, `<PurchaseButton>`, which Stripe elements work, the email rule, styling from the design tokens, layout recipes (Apple Pay + Link + card), the callbacks per payment path, moving an existing Stripe checkout onto superwall | [references/elements-checkout.md](references/elements-checkout.md) |
|
|
92
93
|
| Examples — using them, browsing them, what each teaches | [references/examples.md](references/examples.md) |
|
|
93
94
|
|
|
94
95
|
## Everything else — fetch the docs live
|
|
@@ -111,7 +112,7 @@ curl -sL https://superwall.com/docs/framework/{page}.md # one page
|
|
|
111
112
|
| Declaring products, reading variables, the three price rules | `products` |
|
|
112
113
|
| `purchase()` outcomes, restore, the two channels | `purchases` |
|
|
113
114
|
| Introductory-offer eligibility forking (`useIntroductoryOffer`), reminder notifications | `trials` |
|
|
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
|
+
| Selling on the web — modes (a custom form in `elements` mode is [references/elements-checkout.md](references/elements-checkout.md)), 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
116
|
| 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
117
|
| 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
118
|
| 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` |
|
|
@@ -145,6 +146,10 @@ Docs beyond the framework (dashboard, SDKs, web checkout setup):
|
|
|
145
146
|
2. **`purchase()` never throws for flow outcomes** — it resolves
|
|
146
147
|
`completed | abandoned | failed`. React to the awaited result; treat
|
|
147
148
|
abandoned as an outcome. Never put the buy button in a loading state.
|
|
149
|
+
The one exception is the `<PurchaseButton>` of an `elements` checkout
|
|
150
|
+
form (rule 22): a card payment opens no store sheet, so the button
|
|
151
|
+
disables itself while paying and its label says so
|
|
152
|
+
(`useCheckout().status === "paying"`).
|
|
148
153
|
A store purchase through the SDK resolves `failed` with
|
|
149
154
|
`reason: "unknown"` (or `"superseded"` when a newer purchase replaced it)
|
|
150
155
|
on iOS only: Android reports no purchase failures, so there a failed purchase stays pending until the user
|
|
@@ -293,8 +298,10 @@ Docs beyond the framework (dashboard, SDKs, web checkout setup):
|
|
|
293
298
|
wallet opens only for a product prepared before the tap: config
|
|
294
299
|
`checkout: "applePay"` prepares it on its own, a `"sheet"` paywall calls
|
|
295
300
|
`prefetch(ref, { checkout: "applePay" })`, and an unprepared tap opens
|
|
296
|
-
the sheet.
|
|
297
|
-
|
|
301
|
+
the sheet. Config `checkout: "elements"` prepares it too, from the
|
|
302
|
+
form's price, so a button of the paywall's own can open superwall's
|
|
303
|
+
Apple Pay beside the card form. Any other config `checkout` sends a
|
|
304
|
+
Stripe purchase to the hosted page. Types come from `superwall/hooks`; `examples/apple-pay`
|
|
298
305
|
renders the hook.
|
|
299
306
|
|
|
300
307
|
```tsx
|
|
@@ -482,6 +489,10 @@ Docs beyond the framework (dashboard, SDKs, web checkout setup):
|
|
|
482
489
|
paywall with `teleport` asks Apple as it opens, so the answer is
|
|
483
490
|
usually there before the first tap. To set up an app-to-web flow or
|
|
484
491
|
experiment end to end, use the `teleport` skill.
|
|
492
|
+
In `superwall dev`, a push the studio teleports turns the preview into
|
|
493
|
+
the browser page (`web`, no in-app floors, ending above Safari's
|
|
494
|
+
toolbar on a portrait iPhone): check the web half's styling there, as in
|
|
495
|
+
[references/layout.md](references/layout.md).
|
|
485
496
|
The route opens on the web with every `useQueryState` value carried
|
|
486
497
|
along, and the app is credited when the shopper pays. Keep answers the
|
|
487
498
|
web half needs in `useQueryState`, not component state. The
|
|
@@ -633,6 +644,45 @@ Docs beyond the framework (dashboard, SDKs, web checkout setup):
|
|
|
633
644
|
attribute (`useUserAttribute`), which the host persists. Use storage only for something optional, inside a
|
|
634
645
|
`try`/`catch` that treats a failure as unset (docs: `troubleshooting`).
|
|
635
646
|
|
|
647
|
+
22. **A checkout form of the paywall's own is `checkout: "elements"`,
|
|
648
|
+
built only from superwall's imports.** Read
|
|
649
|
+
[references/elements-checkout.md](references/elements-checkout.md)
|
|
650
|
+
before writing one. The CTA, the "due today" line and the failure
|
|
651
|
+
notice come from `useCheckout()` and `<PurchaseButton>` in
|
|
652
|
+
`superwall/checkout`, which work in any store's form. `<StripeCheckout>`
|
|
653
|
+
and Stripe's elements come from `superwall/checkout/stripe`, used only
|
|
654
|
+
inside the Stripe form. Never install or import `@stripe/*`: a project's
|
|
655
|
+
own copy has its own React context, and its elements throw "Could not
|
|
656
|
+
find Elements context". Every purchase needs an email (from
|
|
657
|
+
`LinkAuthenticationElement`, a wallet, the `email` prop or the user's
|
|
658
|
+
`email` attribute); without one `submit()` returns `incomplete` with
|
|
659
|
+
`email_required` and charges nothing. `options` must be stable: build it
|
|
660
|
+
with `useMemo`, or Stripe redraws every field. Inside the iOS app, in
|
|
661
|
+
Studio and on SDKs below 4.10.8 the form reports `unavailable` and draws
|
|
662
|
+
nothing, so the paywall still offers `usePurchase().purchase()` there.
|
|
663
|
+
`examples/elements-checkout` is the reference.
|
|
664
|
+
|
|
665
|
+
```tsx
|
|
666
|
+
const Pay = ({ product }: { product: Plan }) => {
|
|
667
|
+
const { status, amounts } = useCheckout();
|
|
668
|
+
const { purchase } = usePurchase();
|
|
669
|
+
if (status === "unavailable")
|
|
670
|
+
return <button onClick={() => void purchase(product)}>{t("cta.subscribe")}</button>;
|
|
671
|
+
return (
|
|
672
|
+
<PurchaseButton>
|
|
673
|
+
{status === "paying" ? t("cta.paying") : amounts?.trialDays ? t("cta.trial") : t("cta.subscribe")}
|
|
674
|
+
</PurchaseButton>
|
|
675
|
+
);
|
|
676
|
+
};
|
|
677
|
+
|
|
678
|
+
const options = useMemo<StripeCheckoutOptions>(() => ({ appearance }), [appearance]);
|
|
679
|
+
<StripeCheckout product={product} options={options}>
|
|
680
|
+
<LinkAuthenticationElement />
|
|
681
|
+
<PaymentElement />
|
|
682
|
+
<Pay product={product} />
|
|
683
|
+
</StripeCheckout>;
|
|
684
|
+
```
|
|
685
|
+
|
|
636
686
|
## Working loop
|
|
637
687
|
|
|
638
688
|
```bash
|
|
@@ -231,6 +231,12 @@ superwall products create --identifier <identifier> \
|
|
|
231
231
|
lists them.
|
|
232
232
|
- `--price` is major units (39.99); `--period` is `day|week|month|year`;
|
|
233
233
|
`--trial-days` sets the intro offer. `--dry-run` confirms the target first.
|
|
234
|
+
- Change a trial or period later with
|
|
235
|
+
`superwall products update <id> --trial-days <n> --yes` (also `--period`,
|
|
236
|
+
`--period-count`; a one-time product needs `--period` with
|
|
237
|
+
`--trial-days`), never a raw `superwall patch`. It needs a CLI newer than
|
|
238
|
+
2.6.1; the `superwall` skill's API reference has the details and the
|
|
239
|
+
fallback for older CLIs.
|
|
234
240
|
|
|
235
241
|
Derive identifiers and prices from the design. Where the design shows a
|
|
236
242
|
placeholder (`US$XX.xx`), pick an explicit stand-in and say so — never
|
|
@@ -0,0 +1,457 @@
|
|
|
1
|
+
# Build your own checkout form from Stripe's elements
|
|
2
|
+
|
|
3
|
+
`checkout: "elements"` lets a paywall build its own checkout form from
|
|
4
|
+
Stripe's own elements (wallet buttons, a card form, an email field, an
|
|
5
|
+
address) while superwall prices the form, takes the payment, runs 3D Secure
|
|
6
|
+
and the free trial, and completes the purchase with entitlements and
|
|
7
|
+
redemption, exactly as Apple Pay and the sheet do. The project installs
|
|
8
|
+
nothing from Stripe and runs no backend. The `elements-checkout` example is
|
|
9
|
+
the reference implementation; its chips switch between ten layouts of the
|
|
10
|
+
same purchase.
|
|
11
|
+
|
|
12
|
+
## Which mode
|
|
13
|
+
|
|
14
|
+
| The paywall wants | `checkout` |
|
|
15
|
+
| ------------------------------------------------------------------- | ------------------------ |
|
|
16
|
+
| To leave for Superwall's hosted checkout page and come back | `"external"` (default) |
|
|
17
|
+
| Stripe's ready-made payment sheet, no design work | `"sheet"` |
|
|
18
|
+
| One key straight to Apple Pay, the sheet where it isn't available | `"applePay"` |
|
|
19
|
+
| Its own form: card fields, wallets, Link, in the paywall's design | `"elements"` |
|
|
20
|
+
|
|
21
|
+
Pick `elements` when the card form sits on the paywall itself, styled like
|
|
22
|
+
it, or when an existing custom Stripe checkout is being moved onto
|
|
23
|
+
superwall. Pick `sheet` when nobody wants to design a form, and `applePay`
|
|
24
|
+
when Apple Pay is the only button. In `elements` mode a plain
|
|
25
|
+
`purchase(product)` still opens the sheet, and superwall's Apple Pay sheet is
|
|
26
|
+
prepared too (see [Recipes](#recipes)).
|
|
27
|
+
|
|
28
|
+
```ts
|
|
29
|
+
// config.ts
|
|
30
|
+
checkout: { mode: "elements", prefetch: "trial" },
|
|
31
|
+
products: {
|
|
32
|
+
trial: "test:price_1R7OiTBmoUO4I4NSACz7JoAy:3days-free",
|
|
33
|
+
monthly: "test:price_1RJpYPBmoUO4I4NSX0AUMLee:no-trial",
|
|
34
|
+
},
|
|
35
|
+
```
|
|
36
|
+
|
|
37
|
+
`prefetch` names the product whose price loads as the paywall opens
|
|
38
|
+
(default: the first Stripe product; `false` turns it off), so the form
|
|
39
|
+
renders without a wait. Any other product loads when `<StripeCheckout>`
|
|
40
|
+
first asks for it. `prepaidCards: "block"` can't filter an `elements`
|
|
41
|
+
payment; only the sheet fallback refuses prepaid cards.
|
|
42
|
+
|
|
43
|
+
## The imports
|
|
44
|
+
|
|
45
|
+
```tsx
|
|
46
|
+
import { PurchaseButton, useCheckout } from "superwall/checkout";
|
|
47
|
+
import {
|
|
48
|
+
ExpressCheckoutElement,
|
|
49
|
+
LinkAuthenticationElement,
|
|
50
|
+
PaymentElement,
|
|
51
|
+
StripeCheckout,
|
|
52
|
+
} from "superwall/checkout/stripe";
|
|
53
|
+
```
|
|
54
|
+
|
|
55
|
+
- **`superwall/checkout`** holds what every store's form shares:
|
|
56
|
+
`useCheckout()`, `<PurchaseButton>` and their types (`UseCheckoutResult`,
|
|
57
|
+
`CheckoutAmounts`, `CheckoutSubmitResult`, `CheckoutUnavailableReason`,
|
|
58
|
+
`CheckoutFailure`, `PurchaseButtonProps`). Build the CTA, the "due today"
|
|
59
|
+
line and the failure notice on these, so they work unchanged in another
|
|
60
|
+
store's form.
|
|
61
|
+
- **`superwall/checkout/stripe`** holds what is Stripe's: `<StripeCheckout>`,
|
|
62
|
+
`StripeCheckoutOptions`, `StripeCheckoutProps`, and Stripe's elements.
|
|
63
|
+
Import from it only inside the Stripe form. A paywall that never imports it
|
|
64
|
+
never ships Stripe's React bindings.
|
|
65
|
+
- **Never import from `@stripe/react-stripe-js` or `@stripe/stripe-js`, and
|
|
66
|
+
never install them.** A project's own copy of Stripe's React package has
|
|
67
|
+
its own context: its elements can't see `<StripeCheckout>` and throw
|
|
68
|
+
"Could not find Elements context".
|
|
69
|
+
|
|
70
|
+
## A form
|
|
71
|
+
|
|
72
|
+
```tsx
|
|
73
|
+
import { useMemo } from "react";
|
|
74
|
+
import { PurchaseButton, useCheckout } from "superwall/checkout";
|
|
75
|
+
import {
|
|
76
|
+
ExpressCheckoutElement,
|
|
77
|
+
LinkAuthenticationElement,
|
|
78
|
+
PaymentElement,
|
|
79
|
+
StripeCheckout,
|
|
80
|
+
type StripeCheckoutOptions,
|
|
81
|
+
} from "superwall/checkout/stripe";
|
|
82
|
+
import { usePurchase } from "superwall/hooks";
|
|
83
|
+
import { useRouter } from "superwall/navigation";
|
|
84
|
+
|
|
85
|
+
const Summary = ({ product }: { product: Plan }) => {
|
|
86
|
+
const { status, amounts, failure } = useCheckout();
|
|
87
|
+
const label = amounts?.trialDays ? "Start free trial" : "Subscribe";
|
|
88
|
+
if (status === "unavailable") return <PlainPurchase product={product} />;
|
|
89
|
+
return (
|
|
90
|
+
<>
|
|
91
|
+
{failure ? <p role="status">{failure.message ?? "Your payment was declined."}</p> : null}
|
|
92
|
+
<PurchaseButton className="button">
|
|
93
|
+
{status === "paying" ? "Paying…" : label}
|
|
94
|
+
</PurchaseButton>
|
|
95
|
+
</>
|
|
96
|
+
);
|
|
97
|
+
};
|
|
98
|
+
|
|
99
|
+
// Where the form can't take payment (inside the iOS app, Studio, an SDK
|
|
100
|
+
// below 4.10.8), the paywall still sells: purchase() opens hosted checkout.
|
|
101
|
+
const PlainPurchase = ({ product }: { product: Plan }) => {
|
|
102
|
+
const { purchase } = usePurchase();
|
|
103
|
+
return (
|
|
104
|
+
<button className="button" onClick={() => void purchase(product)}>
|
|
105
|
+
Subscribe
|
|
106
|
+
</button>
|
|
107
|
+
);
|
|
108
|
+
};
|
|
109
|
+
|
|
110
|
+
type Plan = "annual" | "monthly";
|
|
111
|
+
|
|
112
|
+
export function Checkout({ product }: { product: Plan }) {
|
|
113
|
+
const router = useRouter();
|
|
114
|
+
const options = useMemo<StripeCheckoutOptions>(
|
|
115
|
+
() => ({ appearance: { theme: "flat" } }),
|
|
116
|
+
[],
|
|
117
|
+
);
|
|
118
|
+
return (
|
|
119
|
+
<StripeCheckout product={product} options={options} onComplete={() => router.push("welcome")}>
|
|
120
|
+
<ExpressCheckoutElement />
|
|
121
|
+
<LinkAuthenticationElement />
|
|
122
|
+
<PaymentElement options={{ layout: "tabs" }} />
|
|
123
|
+
<Summary product={product} />
|
|
124
|
+
</StripeCheckout>
|
|
125
|
+
);
|
|
126
|
+
}
|
|
127
|
+
```
|
|
128
|
+
|
|
129
|
+
The rules this follows, each one broken in real builds:
|
|
130
|
+
|
|
131
|
+
1. **Every purchase needs an email.** It is the subscription customer's
|
|
132
|
+
email: the receipt, the redemption link and the billing portal hang on
|
|
133
|
+
it. See [The email](#the-email).
|
|
134
|
+
2. **`options` is stable.** Build it with `useMemo` (or a module constant). A
|
|
135
|
+
new object on every render makes Stripe redraw every field.
|
|
136
|
+
3. **`unavailable` is a state to design for, not an error.** Inside the iOS
|
|
137
|
+
app, in Studio and on SDKs below 4.10.8 the form reports `unavailable`
|
|
138
|
+
and Stripe's elements render nothing; offer `usePurchase().purchase()`
|
|
139
|
+
there, which opens hosted checkout.
|
|
140
|
+
4. **The trial label reads `amounts.trialDays`**, not `dueNow === 0`: a 100%
|
|
141
|
+
discount makes `dueNow` `0` with no trial.
|
|
142
|
+
5. **`<PurchaseButton>` says it is paying.** It disables itself while a
|
|
143
|
+
payment runs and its label reads "Paying…" from `status === "paying"`. This
|
|
144
|
+
is the one exception to "never put a purchase button in a loading state":
|
|
145
|
+
a card payment opens no store sheet, so the paywall is the only feedback,
|
|
146
|
+
and without it the shopper sees nothing for a few seconds and taps again.
|
|
147
|
+
|
|
148
|
+
## `<StripeCheckout>`
|
|
149
|
+
|
|
150
|
+
A form for one Stripe product. It renders at once from the product's price;
|
|
151
|
+
nothing is created in Stripe until the shopper pays. Switching `product`
|
|
152
|
+
re-prices the form and Stripe's fields keep what was typed.
|
|
153
|
+
|
|
154
|
+
| Prop | What it takes |
|
|
155
|
+
| ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
|
|
156
|
+
| `product` | The Stripe product, by reference (`"annual"`) or as a product. Required. |
|
|
157
|
+
| `options` | `StripeCheckoutOptions`: Stripe's Elements options (`appearance`, `fonts`, `locale`, `loader`, `paymentMethodTypes`…), minus `mode`, `amount`, `currency`, `paymentMethodCreation` and `setupFutureUsage`, which come from the product. Default: Stripe's own. |
|
|
158
|
+
| `email` | The shopper's email from the paywall's own field. Pass `""` while it is empty. Default: see [The email](#the-email). |
|
|
159
|
+
| `stripeMetadata` | Metadata set on the Stripe subscription. Default: none. |
|
|
160
|
+
| `postPurchase` | What happens after the purchase, as for `purchase()`. Default: the paywall's config. |
|
|
161
|
+
| `onStart`, `onSubmit`, `onComplete`, `onAbandon`, `onFailure` | `usePurchase`'s callbacks, fired for this form's purchases only. See [Events](#events). |
|
|
162
|
+
| `children` | The form: Stripe's elements from `superwall/checkout/stripe`, a `<PurchaseButton>`, any UI of the paywall's. |
|
|
163
|
+
|
|
164
|
+
`locale` defaults to the paywall's locale, so Stripe's labels and errors
|
|
165
|
+
match the paywall's language. `paymentMethodTypes` defaults to
|
|
166
|
+
`["card", "link"]`, which covers cards, Apple Pay, Google Pay and Link; any
|
|
167
|
+
other type is dropped with a console warning (see [Limits](#limits)).
|
|
168
|
+
|
|
169
|
+
## `useCheckout()`
|
|
170
|
+
|
|
171
|
+
Read it from any component inside `<StripeCheckout>`; outside one it throws.
|
|
172
|
+
|
|
173
|
+
| Field | What it holds |
|
|
174
|
+
| ----------- | ------------------------------------------------------------------------------------------------------------------------------------- |
|
|
175
|
+
| `status` | `"preparing"` (Stripe.js and the price are loading), `"ready"`, `"paying"`, `"unavailable"` |
|
|
176
|
+
| `reason` | Why it is `unavailable` (below). Set only then. |
|
|
177
|
+
| `message` | The reason in an English sentence, for logs and a notice. |
|
|
178
|
+
| `error` | What the browser or Stripe threw, when a step threw (`{ name, message }`). |
|
|
179
|
+
| `product` | The product the form sells. Absent when the paywall has no such product. |
|
|
180
|
+
| `amounts` | `CheckoutAmounts`, absent until the price loads: `currency` (lowercase ISO), `dueNow`, `recurring` (after any discount), `interval`, `intervalCount`, `trialDays?`, `discount?` |
|
|
181
|
+
| `canSubmit` | `status === "ready"` |
|
|
182
|
+
| `submit()` | Pays with what the shopper entered. Resolves a `CheckoutSubmitResult`. |
|
|
183
|
+
| `failure` | `CheckoutFailure` of the last payment, cleared when the next starts. |
|
|
184
|
+
|
|
185
|
+
Amounts are in the currency's minor units, and not every currency has two
|
|
186
|
+
decimals (yen has none). Format them with the currency's own digits:
|
|
187
|
+
|
|
188
|
+
```ts
|
|
189
|
+
const formatAmount = (amount: number, currency: string) => {
|
|
190
|
+
const format = new Intl.NumberFormat(undefined, { style: "currency", currency });
|
|
191
|
+
return format.format(amount / 10 ** (format.resolvedOptions().maximumFractionDigits ?? 2));
|
|
192
|
+
};
|
|
193
|
+
```
|
|
194
|
+
|
|
195
|
+
**`submit()` results.** `completed`, `abandoned` and `failed` are a purchase
|
|
196
|
+
and reach every callback. `incomplete` means no purchase started: the
|
|
197
|
+
fields are not filled in (they already show the shopper what is missing), the
|
|
198
|
+
form has no email (`error.name === "email_required"`), or Stripe refused to
|
|
199
|
+
read the form, such as when no `PaymentElement` is mounted. `unavailable`
|
|
200
|
+
carries a `reason`, which is also `"preparing"` or `"paying"` when the form
|
|
201
|
+
wasn't ready or is already paying.
|
|
202
|
+
|
|
203
|
+
**Unavailable reasons** (`CheckoutUnavailableReason`):
|
|
204
|
+
|
|
205
|
+
| `reason` | When | What the paywall does |
|
|
206
|
+
| ------------------------ | -------------------------------------------------------------------------------------------- | ----------------------------------------- |
|
|
207
|
+
| `unsupported_host` | Inside the iOS app, in Studio, or an SDK below 4.10.8 | Offer `usePurchase().purchase()` |
|
|
208
|
+
| `external_checkout` | The config's `checkout` isn't `"elements"` | Fix `config.ts` |
|
|
209
|
+
| `missing_public_api_key` | The host supplied no public API key | A host or setup problem; log it |
|
|
210
|
+
| `unknown_product` | The paywall has no product with this reference | Point the identifier at a dashboard product |
|
|
211
|
+
| `unsupported_product` | Not a Stripe product, such as an App Store product | Buy it with `usePurchase().purchase()` |
|
|
212
|
+
| `session_failed` | Fetching the price failed; `error` holds why | Show the notice; offer `purchase()` |
|
|
213
|
+
| `session_unsupported` | The backend can't take this product in a form, such as a one-time price | Use `purchase()` |
|
|
214
|
+
| `store_load_failed` | Stripe.js didn't load | Show the notice; offer `purchase()` |
|
|
215
|
+
|
|
216
|
+
**Failure reasons** are the same `CheckoutFailureReason`s as every web
|
|
217
|
+
purchase (`card_declined`, `insufficient_funds`, `expired_card`,
|
|
218
|
+
`incorrect_card_details`, `authentication_failed`, `card_not_supported`,
|
|
219
|
+
`limit_exceeded`, `fraud_suspected`, `processing_error`, `unknown`), with
|
|
220
|
+
Stripe's `code`, `declineCode` and `message`. A decline keeps the form open
|
|
221
|
+
for another card; show `failure.message` and let the shopper pay again. If
|
|
222
|
+
a promotion code or a sign-in replaces the price while the shopper is
|
|
223
|
+
paying, the payment is refused before any charge with `reason: "unknown"`,
|
|
224
|
+
`code: "quote_changed"`.
|
|
225
|
+
|
|
226
|
+
## `<PurchaseButton>`
|
|
227
|
+
|
|
228
|
+
`useCheckout().submit` on a `<button>`: disabled until the form can pay and
|
|
229
|
+
while it pays, with `data-status` set to `status` and `aria-busy` while
|
|
230
|
+
paying, so CSS can style each state. Every other prop goes to the button;
|
|
231
|
+
`onClick` runs first and `event.preventDefault()` stops the payment. It
|
|
232
|
+
shows nothing for an `incomplete` result. A paywall with its own email box
|
|
233
|
+
pays from its own button instead and shows the result's `error.message`:
|
|
234
|
+
|
|
235
|
+
```tsx
|
|
236
|
+
import { useState } from "react";
|
|
237
|
+
import { useCheckout } from "superwall/checkout";
|
|
238
|
+
|
|
239
|
+
const PayButton = ({ label }: { label: string }) => {
|
|
240
|
+
const { canSubmit, submit, status } = useCheckout();
|
|
241
|
+
const [problem, setProblem] = useState<string>();
|
|
242
|
+
return (
|
|
243
|
+
<>
|
|
244
|
+
{problem ? <p role="status">{problem}</p> : null}
|
|
245
|
+
<button
|
|
246
|
+
disabled={!canSubmit}
|
|
247
|
+
onClick={async () => {
|
|
248
|
+
setProblem(undefined);
|
|
249
|
+
const result = await submit();
|
|
250
|
+
if (result.status === "incomplete") setProblem(result.error.message);
|
|
251
|
+
}}
|
|
252
|
+
>
|
|
253
|
+
{status === "paying" ? "Paying…" : label}
|
|
254
|
+
</button>
|
|
255
|
+
</>
|
|
256
|
+
);
|
|
257
|
+
};
|
|
258
|
+
```
|
|
259
|
+
|
|
260
|
+
## The email
|
|
261
|
+
|
|
262
|
+
Every purchase needs one. The form takes the first of:
|
|
263
|
+
|
|
264
|
+
1. the `email` prop, for a paywall that collects it in its own `<input>`
|
|
265
|
+
(pass `""` while empty);
|
|
266
|
+
2. the email typed into `LinkAuthenticationElement`, which also signs a Link
|
|
267
|
+
shopper in;
|
|
268
|
+
3. the email on the card's or wallet's billing details (a wallet in
|
|
269
|
+
`ExpressCheckoutElement` is always asked for one);
|
|
270
|
+
4. the user's `email` attribute, which also pre-fills
|
|
271
|
+
`LinkAuthenticationElement`.
|
|
272
|
+
|
|
273
|
+
With none of these, the form logs a warning once it is ready, and a card
|
|
274
|
+
payment returns `incomplete` with `email_required` and charges nothing. So
|
|
275
|
+
render `LinkAuthenticationElement` above the card form, pass your own
|
|
276
|
+
field's value as `email`, or set the `email` attribute before the paywall
|
|
277
|
+
shows; a wallets-only form needs nothing more.
|
|
278
|
+
|
|
279
|
+
## Which Stripe elements work
|
|
280
|
+
|
|
281
|
+
`superwall/checkout/stripe` re-exports Stripe's components unchanged, with
|
|
282
|
+
every option Stripe documents (`PaymentElement`'s `layout: "tabs"` or
|
|
283
|
+
`"accordion"`, `fields`, `wallets`, `terms`, `defaultValues`…). Two are
|
|
284
|
+
wrapped because superwall needs their events; their props are Stripe's,
|
|
285
|
+
minus the handlers superwall owns.
|
|
286
|
+
|
|
287
|
+
| Element | Supported | Notes |
|
|
288
|
+
| ------------------------------------------------------------------------- | --------- | ----------------------------------------------------------------------------------------- |
|
|
289
|
+
| `PaymentElement` | Yes | Cards and Link |
|
|
290
|
+
| `ExpressCheckoutElement` | Wrapped | Apple Pay, Google Pay, Link. superwall owns `onClick`, `onConfirm` and `onCancel`; `onReady` and the rest are yours |
|
|
291
|
+
| `LinkAuthenticationElement` | Wrapped | Hands the email to the purchase; pre-filled from the user's `email` attribute |
|
|
292
|
+
| `AddressElement` | Yes | `mode: "billing"`: the address goes onto the payment method |
|
|
293
|
+
| `CardElement`, `CardNumberElement`, `CardExpiryElement`, `CardCvcElement` | Yes | The classic card fields; styled with `options.style`, not `appearance` |
|
|
294
|
+
| `useStripe()`, `useElements()` | Yes | For reading the form; never confirm with them, call `useCheckout().submit()` |
|
|
295
|
+
| `ShippingAddressElement`, `AddressElement` with `mode: "shipping"` | No | A subscription ships nothing, and the purchase has nowhere to send it |
|
|
296
|
+
| `TaxIdElement` | No | The purchase has nowhere to send a tax ID |
|
|
297
|
+
| `IbanElement`, SEPA, ACH, iDEAL, Klarna, Afterpay, Cash App Pay | No | They redirect or need a bank mandate: a return-and-resume flow superwall doesn't have |
|
|
298
|
+
| `PaymentMethodMessagingElement` | No | It advertises the buy-now-pay-later methods above |
|
|
299
|
+
| `EmbeddedCheckout`, `CheckoutProvider` | No | Stripe's own hosted checkout: use `checkout: "sheet"` instead |
|
|
300
|
+
|
|
301
|
+
Saved cards and a customer's earlier payment methods aren't offered: the
|
|
302
|
+
form pays as a new customer each time. A promotion code box is not a Stripe
|
|
303
|
+
element: it is a plain input on `useDiscount()`, superwall's own codes, and
|
|
304
|
+
a redeemed code re-prices the form and the charge.
|
|
305
|
+
|
|
306
|
+
## Matching the paywall's design
|
|
307
|
+
|
|
308
|
+
Stripe draws its fields in its own frame, so they can't read the paywall's
|
|
309
|
+
CSS variables. The example's `components/appearance.ts` is the pattern:
|
|
310
|
+
|
|
311
|
+
- **Resolve the tokens to plain colours.** Read each CSS variable from the
|
|
312
|
+
surface's `theme.css` (`--surface`, `--fg`, `--fg-muted`, `--border`,
|
|
313
|
+
`--accent`…) through `getComputedStyle`, turn it into `rgb()`, and read
|
|
314
|
+
them again when the root's `light`/`dark` class changes.
|
|
315
|
+
- **`appearance.variables`**: `colorBackground` is the plan rows' surface,
|
|
316
|
+
not the page background; text, placeholder, accent, `colorDanger`, font,
|
|
317
|
+
`fontSizeBase: "16px"` and the corner radius come from the tokens.
|
|
318
|
+
- **`appearance.rules`**: a hairline border and `boxShadow: "none"` on
|
|
319
|
+
`.Input`, `.Tab`, `.AccordionItem` and `.Block` (Link's "save my
|
|
320
|
+
information" box), and the accent border on `.Input:focus` and
|
|
321
|
+
`.Tab--selected`, so every field matches the paywall's own inputs.
|
|
322
|
+
- **`fonts`**: the font file itself, `{ family, src: "url(…woff2)", weight }`,
|
|
323
|
+
never a `cssSrc` stylesheet. Stripe fetches `cssSrc` from the paywall's
|
|
324
|
+
page, where the hosted page's Content Security Policy blocks Google Fonts;
|
|
325
|
+
a font file loads inside Stripe's frame.
|
|
326
|
+
- **The classic card fields** take `options.style` (`base`, `invalid`,
|
|
327
|
+
`::placeholder`) instead of `appearance`; wrap each in the paywall's own
|
|
328
|
+
input class for the surface, border and focus edge.
|
|
329
|
+
- **Wallet buttons** take `buttonHeight` and `buttonType` in
|
|
330
|
+
`ExpressCheckoutElement`'s options; `buttonType: { applePay: "plain" }`
|
|
331
|
+
shows the bare Apple Pay logo, the same size as Link's button.
|
|
332
|
+
- **Memoize the result.** Return the options from `useMemo` keyed on the
|
|
333
|
+
palette; a new object on every render redraws every field.
|
|
334
|
+
|
|
335
|
+
## Recipes
|
|
336
|
+
|
|
337
|
+
Elements are plain components: put them in any order, around any UI.
|
|
338
|
+
|
|
339
|
+
- **Apple Pay, Link and a card (recommended).** superwall's own Apple Pay
|
|
340
|
+
sheet on a button of the paywall's own, because it is the most fully
|
|
341
|
+
instrumented path; Link alone in the express row; the card form with its
|
|
342
|
+
wallets off so no wallet shows twice. In `elements` mode the paywall
|
|
343
|
+
prepares the Apple Pay sheet from the form's price, so the button opens it
|
|
344
|
+
at once:
|
|
345
|
+
|
|
346
|
+
```tsx
|
|
347
|
+
const ApplePayButton = ({ product }: { product: "annual" }) => {
|
|
348
|
+
const { product: wallet } = useApplePay(product);
|
|
349
|
+
const { purchase } = usePurchase();
|
|
350
|
+
return wallet.status === "ready" ? (
|
|
351
|
+
<button className="apple-pay" onClick={() => void purchase(product, { checkout: "applePay" })} />
|
|
352
|
+
) : null;
|
|
353
|
+
};
|
|
354
|
+
|
|
355
|
+
<StripeCheckout product="annual" options={options}>
|
|
356
|
+
<ApplePayButton product="annual" />
|
|
357
|
+
<ExpressCheckoutElement
|
|
358
|
+
options={{ paymentMethods: { applePay: "never", googlePay: "never", link: "auto" } }}
|
|
359
|
+
/>
|
|
360
|
+
<LinkAuthenticationElement />
|
|
361
|
+
<PaymentElement options={{ layout: "tabs", wallets: { applePay: "never", googlePay: "never" } }} />
|
|
362
|
+
<PurchaseButton>Subscribe</PurchaseButton>
|
|
363
|
+
</StripeCheckout>
|
|
364
|
+
```
|
|
365
|
+
|
|
366
|
+
Use the full `ExpressCheckoutElement` only when the paywall wants every
|
|
367
|
+
express method together in Stripe's row.
|
|
368
|
+
- **Only one wallet in the row.** `paymentMethods` turns the others off:
|
|
369
|
+
`{ applePay: "auto", googlePay: "never", link: "never" }`.
|
|
370
|
+
- **A divider beside the wallets.** The express row renders nothing on a
|
|
371
|
+
device with no wallet, so show "or pay with card" only after
|
|
372
|
+
`ExpressCheckoutElement`'s `onReady` reports one:
|
|
373
|
+
`onReady={({ availablePaymentMethods }) => setShown(Object.values(availablePaymentMethods ?? {}).some(Boolean))}`.
|
|
374
|
+
- **Wallets only.** Just `ExpressCheckoutElement`, no CTA: the wallet pays
|
|
375
|
+
and asks for the email itself.
|
|
376
|
+
- **Split card fields.** `CardNumberElement`, `CardExpiryElement`,
|
|
377
|
+
`CardCvcElement` (or the one-line `CardElement`), the paywall's own email
|
|
378
|
+
`<input>` passed as `email`, and its own button on `submit()` that shows
|
|
379
|
+
an `incomplete` message.
|
|
380
|
+
- **Billing address.** `AddressElement` with `mode: "billing"`; put the
|
|
381
|
+
paywall's own tags on the subscription with `stripeMetadata`.
|
|
382
|
+
- **Promotion code.** A plain input calling `useDiscount().redeem(code)`; the
|
|
383
|
+
form re-prices and `amounts.discount` is set.
|
|
384
|
+
|
|
385
|
+
## Events
|
|
386
|
+
|
|
387
|
+
`usePurchase` callbacks hear every purchase on the paywall, superwall's
|
|
388
|
+
Apple Pay sheet included; `<StripeCheckout>`'s hear only that form's. The
|
|
389
|
+
native SDK gets the matching `stripe_checkout_*` messages, so a
|
|
390
|
+
`transaction_abandon` reaches its analytics.
|
|
391
|
+
|
|
392
|
+
| What the shopper does | Callbacks, in order |
|
|
393
|
+
| ------------------------------------------ | ------------------------------------------- |
|
|
394
|
+
| Pays with a card | `onStart`, `onSubmit`, `onComplete` |
|
|
395
|
+
| Pays with an incomplete form or no email | nothing: `submit()` returns `incomplete` |
|
|
396
|
+
| Card declined | `onStart`, `onSubmit`, `onFailure` (reason) |
|
|
397
|
+
| Pays again after a decline | a new `onStart`, then as above |
|
|
398
|
+
| Fails 3D Secure | `onStart`, `onSubmit`, `onFailure` |
|
|
399
|
+
| Opens Link or a wallet in the express row | `onStart` |
|
|
400
|
+
| … and pays | `onSubmit`, `onComplete` |
|
|
401
|
+
| … and closes it | `onAbandon` |
|
|
402
|
+
| Taps superwall's Apple Pay button and pays | `onStart`, `onSubmit`, `onComplete` |
|
|
403
|
+
| … and closes the sheet | `onAbandon` (from `usePurchase` only) |
|
|
404
|
+
|
|
405
|
+
A card form never fires `onAbandon`. The callbacks don't say which method
|
|
406
|
+
paid; a paywall that needs it knows which of its buttons the shopper used.
|
|
407
|
+
|
|
408
|
+
## Migrating an existing Stripe checkout
|
|
409
|
+
|
|
410
|
+
A custom Stripe checkout usually has an `<Elements>` provider with a client
|
|
411
|
+
secret, a server endpoint that creates the PaymentIntent or subscription, a
|
|
412
|
+
`stripe.confirmPayment()` call on submit and a webhook that grants access.
|
|
413
|
+
|
|
414
|
+
1. **Set the mode.** `checkout: { mode: "elements" }` in `config.ts`, and
|
|
415
|
+
the Stripe products in `products`.
|
|
416
|
+
2. **Swap the provider.** Replace `<Elements stripe={…} options={{ clientSecret }}>`
|
|
417
|
+
with `<StripeCheckout product="annual">`. Move `appearance`, `fonts`,
|
|
418
|
+
`locale` and `paymentMethodTypes` into its `options`; drop
|
|
419
|
+
`clientSecret`, `mode`, `amount` and `currency`, which come from the
|
|
420
|
+
product.
|
|
421
|
+
3. **Keep the elements.** Same props, imported from
|
|
422
|
+
`superwall/checkout/stripe` instead of `@stripe/react-stripe-js`; remove
|
|
423
|
+
the `@stripe/*` dependencies.
|
|
424
|
+
4. **Swap the submit.** Where you called `elements.submit()` and
|
|
425
|
+
`stripe.confirmPayment()`, call `useCheckout().submit()`, or render
|
|
426
|
+
`<PurchaseButton>`. 3D Secure, trials and failures are handled.
|
|
427
|
+
5. **Collect the email.** Keep `LinkAuthenticationElement`, or pass your own
|
|
428
|
+
field's value as `email`.
|
|
429
|
+
6. **Move the metadata.** What you put on the subscription goes in
|
|
430
|
+
`stripeMetadata`.
|
|
431
|
+
7. **Delete the backend.** The PaymentIntent endpoint and the
|
|
432
|
+
access-granting webhook go: superwall creates the subscription, grants
|
|
433
|
+
the entitlement and redeems it in the app.
|
|
434
|
+
8. **Move the reactions.** Success and error handling moves to
|
|
435
|
+
`onComplete`, `onFailure` and `onAbandon` on `<StripeCheckout>`, or to
|
|
436
|
+
`usePurchase()`'s callbacks.
|
|
437
|
+
|
|
438
|
+
Any element from the unsupported list has no place in the port; drop it
|
|
439
|
+
or keep that product on the hosted checkout.
|
|
440
|
+
|
|
441
|
+
## Limits
|
|
442
|
+
|
|
443
|
+
- **Only card and Link.** `paymentMethodTypes` beyond `card` and `link` are
|
|
444
|
+
dropped with a console warning. A payment method of any other type, say
|
|
445
|
+
from an `IbanElement` imported straight from Stripe's package, fails with
|
|
446
|
+
`card_not_supported` (code `payment_method_unsupported`) before anything
|
|
447
|
+
is charged. Redirect and bank-debit methods need a return-and-resume flow
|
|
448
|
+
that doesn't exist yet.
|
|
449
|
+
- **Not inside the iOS app.** There `status` is `unavailable`
|
|
450
|
+
(`unsupported_host`) and a purchase opens hosted checkout in the browser.
|
|
451
|
+
Studio and SDKs below 4.10.8 report the same; a teleport page and a web
|
|
452
|
+
paywall take payment.
|
|
453
|
+
- **Studio never pays.** The preview shows the form's `unavailable` state;
|
|
454
|
+
try a real payment on a published web paywall with Stripe test cards:
|
|
455
|
+
`4242 4242 4242 4242` pays, `4000 0000 0000 0002` is declined,
|
|
456
|
+
`4000 0025 0000 3155` asks for 3D Secure.
|
|
457
|
+
- **Subscriptions only.** A one-time price reports `session_unsupported`.
|
|
@@ -56,6 +56,7 @@ number.
|
|
|
56
56
|
| Example | The one idea |
|
|
57
57
|
| --- | --- |
|
|
58
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
|
+
| `elements-checkout` | A checkout form of the paywall's own in `checkout: "elements"` mode: `<StripeCheckout>` around Stripe's elements, the CTA on `useCheckout()` and `<PurchaseButton>`, an email always collected, fields styled from the design tokens (`components/appearance.ts`), ten layouts on chips (superwall's Apple Pay + Link + card is the default) and an event log showing which callbacks fire for each path ([elements-checkout.md](elements-checkout.md)) |
|
|
59
60
|
| `trial-eligibility` | Two paywalls in one, chosen by the store — every string forks and both states read as intentional |
|
|
60
61
|
| `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
62
|
| `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 |
|
|
@@ -228,6 +228,16 @@ It applies once the page takes over: the pre-rendered first paint has no
|
|
|
228
228
|
Safari), so a page with a bottom `env()` can still move by that much. An
|
|
229
229
|
edge `insets` sets in `config.ts` is written inline and wins over this rule.
|
|
230
230
|
|
|
231
|
+
**In the studio, a teleport shows the browser page.** Walk to the
|
|
232
|
+
teleported route in `superwall dev` (tap the button that runs
|
|
233
|
+
`router.push(route, { teleport: true })`) and the preview becomes the page
|
|
234
|
+
the shopper lands on: `data-sw-platform="web"`, no idiom or cutout, no
|
|
235
|
+
in-app floors, and on a portrait iPhone a viewport that ends above Safari's
|
|
236
|
+
toolbar. Check the `:root[data-sw-platform="web"]` rules, sticky footers
|
|
237
|
+
and safe-area padding there; the toolbar is browser chrome, never padding
|
|
238
|
+
the page adds. A landscape iPhone keeps the app's insets with the bar
|
|
239
|
+
drawn over the page, and going back to the app restores the in-app frame.
|
|
240
|
+
|
|
231
241
|
`push` and `noAnimation` are fullscreen. The attributes come from the
|
|
232
242
|
device the host reports and are absent, never guessed, until the host's
|
|
233
243
|
first message; the studio sets them per preset, so switching devices
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
---
|
|
2
2
|
name: teleport
|
|
3
|
-
description: Set up an app-to-web flow or experiment with the superwall framework's teleport — the shopper starts on a paywall or onboarding in the iOS app and finishes on the web, paying with Apple Pay through Stripe, and the app is credited on its own. Covers the recommended setup (`teleport.route` in config.ts, the Apple Pay gate with `useApplePay().available` and `router.push(route, { teleport:
|
|
3
|
+
description: Set up an app-to-web flow or experiment with the superwall framework's teleport — the shopper starts on a paywall or onboarding in the iOS app and finishes on the web, paying with Apple Pay through Stripe, and the app is credited on its own. Covers the recommended setup (`teleport.route` in config.ts, the Apple Pay gate with `useApplePay().available` and `router.push(route, { teleport:false })`, `teleport.fallbacks`, blocking prepaid cards), what buying a Stripe product inside the app does, direct Apple Pay checkout (not with Stripe Managed Payments), A/B testing teleport by paywall in a campaign, and a catalogue of setups and experiments (web pricing, discounts, failure rescue, abandonment offers, custom teleport screens, trial eligibility, `completion`, attribution). Use when the user asks to "set up app to web", "app-to-web experiment", "teleport", "send users to web checkout from the app", "sell on the web from iOS", "Stripe / Apple Pay from the app", or to test web checkout against the App Store. Needs the superwall-framework skill for everything else about the paywall.
|
|
4
4
|
user-invocable: true
|
|
5
5
|
---
|
|
6
6
|
|
|
@@ -1,8 +1,8 @@
|
|
|
1
|
-
import { T as isNonInteractive, c as CHANNELS, s as CHANNEL, v as TELEMETRY_HOST, x as VERSION, y as TELEMETRY_KEY } from "./environment-
|
|
2
|
-
import { _ as writeTelemetryNoticeShown, c as readSkillsSync, g as writeSkillsSync, t as readAnonymousId, u as telemetryNoticeShown } from "./config-
|
|
3
|
-
import { n as ui } from "./ui-
|
|
4
|
-
import { n as withSpinner } from "./spinner-
|
|
5
|
-
import { i as packagedDir, t as AGENT_SKILLS_DIR } from "./paths-
|
|
1
|
+
import { T as isNonInteractive, c as CHANNELS, s as CHANNEL, v as TELEMETRY_HOST, x as VERSION, y as TELEMETRY_KEY } from "./environment-BQiaGqjB.js";
|
|
2
|
+
import { _ as writeTelemetryNoticeShown, c as readSkillsSync, g as writeSkillsSync, t as readAnonymousId, u as telemetryNoticeShown } from "./config-CJRNScT0.js";
|
|
3
|
+
import { n as ui } from "./ui-Dye-QvEj.js";
|
|
4
|
+
import { n as withSpinner } from "./spinner-hTCJZAoJ.js";
|
|
5
|
+
import { i as packagedDir, t as AGENT_SKILLS_DIR } from "./paths-B4FNcaHO.js";
|
|
6
6
|
import { execFile, spawn } from "node:child_process";
|
|
7
7
|
import { appendFileSync, existsSync, mkdtempSync, readFileSync, readdirSync, rmSync, writeFileSync } from "node:fs";
|
|
8
8
|
import { tmpdir } from "node:os";
|