@superwall/cli 2.6.0 → 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.
Files changed (89) hide show
  1. package/dist/{apple-D-rfsuDA.js → apple-BE1GBJFP.js} +14 -14
  2. package/dist/{approve-aPc5RoXB.js → approve-yRZmvkCj.js} +6 -6
  3. package/dist/{assets-PyuXe45Y.js → assets-DTAgbWw0.js} +3 -3
  4. package/dist/auth.js +3 -3
  5. package/dist/{base-CAU0hWoI.js → base-zc1wl_9b.js} +2 -2
  6. package/dist/{billing-Dt6L_l9R.js → billing-C1LV4-BN.js} +3 -3
  7. package/dist/{build-CY5FnMNY.js → build-CQd-pf7O.js} +8 -8
  8. package/dist/{config-DOp5oChe.js → config-DCqRQTJ4.js} +3 -3
  9. package/dist/create-CSHGZDfB.js +18 -0
  10. package/dist/{create-D6w3UL0m.js → create-Costu6UT.js} +7 -7
  11. package/dist/{create-BZL5VH4L.js → create-wlCp83IH.js} +25 -25
  12. package/dist/{doctor-C9FR0qw3.js → doctor-Bd9ffg51.js} +19 -19
  13. package/dist/entry.js +24 -24
  14. package/dist/{environment-sE2wZYdg.js → environment-Dn7irhZr.js} +1 -1
  15. package/dist/{existing--peXpOZj.js → existing-BQMB_2AG.js} +8 -8
  16. package/dist/{held-CUBCOCGP.js → held-D5wSX2Mf.js} +8 -8
  17. package/dist/held-Dmf5SR3p.js +15 -0
  18. package/dist/{install-C5d82gZF.js → install-CxyqfKFe.js} +10 -10
  19. package/dist/{integrate-D8J_X1bj.js → integrate-MkyDDzI5.js} +19 -19
  20. package/dist/{login-DXhm9L0F.js → login-B7IqDafm.js} +1 -1
  21. package/dist/{login-C6X7JrhM.js → login-BMHDhxAx.js} +6 -6
  22. package/dist/login-Cp0-BgDZ.js +13 -0
  23. package/dist/{lookup-DqmIbUkv.js → lookup-DkcT4E-5.js} +3 -3
  24. package/dist/{migrate-BYF6hKZ2.js → migrate-CdFoZipj.js} +26 -26
  25. package/dist/{notification-url-Bo54nkXv.js → notification-url-D6KKeXnk.js} +2 -2
  26. package/dist/{open-xdgXUzaF.js → open-COJE6ryI.js} +2 -2
  27. package/dist/{org-BD8U3D1_.js → org-BV8wwxwc.js} +3 -3
  28. package/dist/{organization-D-ZlB3qU.js → organization-9R_1PJKk.js} +3 -3
  29. package/dist/{orgs-DQQJ3sw_.js → orgs-ltP8H0Nl.js} +1 -1
  30. package/dist/{paths-CIlyzF2I.js → paths-Cb1RfjaX.js} +1 -1
  31. package/dist/{playbook-ecggWGFi.js → playbook-CVGolez9.js} +9 -9
  32. package/dist/{promote-QVMLGYlU.js → promote-B_HnFEbX.js} +19 -19
  33. package/dist/{pull-CCXhb2a7.js → pull-DF4KYVcP.js} +7 -7
  34. package/dist/pull-JxiMyRwY.js +30 -0
  35. package/dist/{pull-CrdsfsAl.js → pull-lYRULo4v.js} +24 -24
  36. package/dist/push-B5py7h5y.js +29 -0
  37. package/dist/{push-DJMGG7zW.js → push-BZN1Qpkq.js} +7 -7
  38. package/dist/{push-DiMDwGfe.js → push-BnllH2Rd.js} +4 -4
  39. package/dist/{push-D6pJM_vv.js → push-DHlUMkbf.js} +11 -11
  40. package/dist/registry-BGEYCWyD.js +22 -0
  41. package/dist/{registry-BSnQXft4.js → registry-CqePfigB.js} +51 -51
  42. package/dist/{resolve-DO7bPota.js → resolve-B4bd3Qjl.js} +2 -2
  43. package/dist/{resources-XwvXA20E.js → resources-BaURbSpY.js} +2 -2
  44. package/dist/{run-B-YvxfRc.js → run-Bme4Egyl.js} +9 -9
  45. package/dist/{scan-ViBhmrB7.js → scan-DugxddUU.js} +1 -1
  46. package/dist/scan-J2DILUNE.js +4 -0
  47. package/dist/{scope-BLLUxbrA.js → scope-DDYLQeZw.js} +6 -6
  48. package/dist/{selection-C07e_GGY.js → selection-C439nEhn.js} +1 -1
  49. package/dist/{server-CBtHzl9y.js → server-C_aMxzvS.js} +9 -9
  50. package/dist/server-Cif9w5lM.js +33 -0
  51. package/dist/{session-BlrwAdGN.js → session-B7frlXXQ.js} +1 -1
  52. package/dist/{session-BfVx50iA.js → session-CfG3gzko.js} +5 -5
  53. package/dist/session-DvaPyOuH.js +5 -0
  54. package/dist/{setup-a4B72xJ8.js → setup-DQEasPhx.js} +9 -9
  55. package/dist/skills/index.json +5 -0
  56. package/dist/skills/superwall-framework/SKILL.md +52 -23
  57. package/dist/skills/superwall-framework/references/layout.md +30 -2
  58. package/dist/skills/teleport/SKILL.md +154 -0
  59. package/dist/skills/teleport/references/experiments.md +328 -0
  60. package/dist/skills/teleport/references/setup.md +157 -0
  61. package/dist/{skills-BB1uIt8t.js → skills-DnegE1A6.js} +4 -4
  62. package/dist/{skills-SnxFa2in.js → skills-MmF7IyTg.js} +7 -7
  63. package/dist/{source-push-w7miTr6m.js → source-push-MbJjh4Ki.js} +4 -4
  64. package/dist/{spinner-BQp7fQvK.js → spinner-Dcr-Dqdi.js} +4 -4
  65. package/dist/{status-DxsIw9zq.js → status-DHRxg1ZA.js} +6 -6
  66. package/dist/{storage-BR6imSqm.js → storage-DdIAHolY.js} +1 -1
  67. package/dist/{storekit-BqyujKQ_.js → storekit-De998QOt.js} +4 -4
  68. package/dist/storekit-iBCWmeKn.js +15 -0
  69. package/dist/{theme-Ed0gz6hr.js → theme-BrUrye-c.js} +4 -4
  70. package/dist/{token-CWQ6tdva.js → token-CKCBQ4I8.js} +1 -1
  71. package/dist/tools-skills/teleport/SKILL.md +154 -0
  72. package/dist/tools-skills/teleport/references/experiments.md +328 -0
  73. package/dist/tools-skills/teleport/references/setup.md +157 -0
  74. package/dist/tools.js +6 -5
  75. package/dist/{try-C3HW3hPZ.js → try-C8QQbG0b.js} +10 -10
  76. package/dist/upgrade-CYFdpVpi.js +27 -0
  77. package/dist/{upgrade-Cw9jVt-r.js → upgrade-D0thxCA4.js} +7 -7
  78. package/package.json +2 -2
  79. package/dist/create-DM5Y1Pyk.js +0 -18
  80. package/dist/held-DVxvPMSG.js +0 -15
  81. package/dist/login-et319ESO.js +0 -13
  82. package/dist/pull-h71pL3r_.js +0 -30
  83. package/dist/push-BIq6R8Ro.js +0 -29
  84. package/dist/registry-YwzTfCNc.js +0 -22
  85. package/dist/scan-B36wkZmI.js +0 -4
  86. package/dist/server-CZwSfzKe.js +0 -33
  87. package/dist/session-Cip4j99n.js +0 -5
  88. package/dist/storekit-ELVCMF0X.js +0 -15
  89. package/dist/upgrade-DVsonzDF.js +0 -27
@@ -111,9 +111,10 @@ curl -sL https://superwall.com/docs/framework/{page}.md # one page
111
111
  | Declaring products, reading variables, the three price rules | `products` |
112
112
  | `purchase()` outcomes, restore, the two channels | `purchases` |
113
113
  | 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`), direct Apple Pay availability (`useApplePay`, `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` |
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
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 })`, 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` |
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` |
117
118
  | Web funnels — answers in the URL (`useQueryState`), resume after a browser hand-off, `shift` | `web-funnels` |
118
119
  | Multi-page flows, router, cross-page state, shared chrome | `navigation` |
119
120
  | Built-in + custom transitions, bottom sheets | `transitions` |
@@ -251,24 +252,42 @@ Docs beyond the framework (dashboard, SDKs, web checkout setup):
251
252
  on `stripe_error`; read them in Safari Web Inspector or Chrome DevTools to
252
253
  debug a slow checkout before changing the paywall.
253
254
 
254
- `useApplePay()` says whether direct Apple Pay (the wallet the browser
255
- opens itself) is available, from `ApplePaySession.canMakePayments()`,
256
- known on the first render. Web hosts only (Web SDK, hosted web paywall,
257
- teleport page, plain browser): `{ available: true }` or
258
- `{ available: false, reason, message, error? }`; `undefined` in the iOS
259
- and Android SDKs and Studio. `reason` (`ApplePayUnavailableReason`) is
260
- `unsupported_browser` (no Apple Pay JS, as in desktop Chrome — its card
261
- sheet may still offer Apple Pay by QR code, which is not direct Apple
262
- Pay), `insecure_context` (not HTTPS, `http://localhost` included),
263
- `device_unsupported`, `cross_origin_frame` or `check_failed`; `error` is
264
- `{ name, message }` when the check threw. Only Stripe sees the cards in
265
- Wallet and the domain's registration: `useApplePay(product)` adds
266
- `product: { status: "preparing" | "ready" | "unavailable", reason?,
267
- message?, error? }`. Its `reason` is the browser's when the browser can't
268
- pay, else an `ApplePayWalletReason`: `not_prepared` means nothing has
269
- prepared that product's wallet yet, not that the device can't pay;
270
- `stripe_declined` means no card in Wallet, an unregistered domain or
271
- Safari's Apple Pay check setting off; the rest (`stripe_check_failed`,
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`,
272
291
  `stripe_load_failed`, `missing_public_api_key`, `session_failed`,
273
292
  `session_unsupported`, `show_failed`) name the step that failed. The
274
293
  wallet opens only for a product prepared before the tap: config
@@ -282,9 +301,9 @@ Docs beyond the framework (dashboard, SDKs, web checkout setup):
282
301
  const { purchase, prefetch } = usePurchase();
283
302
  const applePay = useApplePay(reference);
284
303
  useEffect(() => {
285
- if (applePay?.available) prefetch(reference, { checkout: "applePay" });
286
- }, [applePay?.available, prefetch, reference]);
287
- return applePay?.available && applePay.product.status === "ready" ? (
304
+ if (applePay.available) prefetch(reference, { checkout: "applePay" });
305
+ }, [applePay.available, prefetch, reference]);
306
+ return applePay.product.status === "ready" ? (
288
307
  <button onClick={() => purchase(reference, { checkout: "applePay" })}>Apple Pay</button>
289
308
  ) : (
290
309
  <button onClick={() => purchase(reference, { checkout: "sheet" })}>Pay with card</button>
@@ -453,6 +472,16 @@ Docs beyond the framework (dashboard, SDKs, web checkout setup):
453
472
  true })`, or `teleport: { route }` so a push to it and a Stripe purchase
454
473
  teleport on their own and it is prepared when the paywall opens (call
455
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.
456
485
  The route opens on the web with every `useQueryState` value carried
457
486
  along, and the app is credited when the shopper pays. Keep answers the
458
487
  web half needs in `useQueryState`, not component state. The
@@ -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
@@ -0,0 +1,154 @@
1
+ ---
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: 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
+ user-invocable: true
5
+ ---
6
+
7
+ # Teleport: app to web
8
+
9
+ App to web means the shopper starts in the iOS app and finishes on the web:
10
+ a paywall shown by SuperwallKit 4.18+ opens one of its routes in the
11
+ shopper's browser, they pay there with Apple Pay (Stripe), and the app is
12
+ credited without a restore. With the superwall framework this is one key,
13
+ `teleport`, in the paywall's `config.ts`; the same paywall runs on both
14
+ sides, so nothing is built twice. Everything about writing the paywall
15
+ itself (routes, hooks, layout, push and publish) is in the
16
+ `superwall-framework` skill; this skill is how to set up teleport well.
17
+
18
+ The framework is headless React: every screen, offer, branch and
19
+ fallback here is code the user owns, so anything they can describe they can
20
+ build. Treat the setup below as the baseline and
21
+ [references/experiments.md](references/experiments.md) as the menu of what
22
+ else is possible; offer from it.
23
+
24
+ These are **today's recommendations** (November 2026). They come from what
25
+ converts so far and may change; when the user's own results disagree, theirs
26
+ win. Say so when you hand a setup over.
27
+
28
+ ## The rules
29
+
30
+ 1. **Teleport through `teleport.route` in `config.ts`, always.** Name the
31
+ route the web half opens on: `teleport: { route: "plan" }`. A paywall
32
+ with `teleport.route` prepares that teleport and warms the web page the
33
+ moment it opens, asks Apple about Apple Pay at the same time, and
34
+ `superwall push` pre-renders the route so the browser paints it before
35
+ any script runs. A route teleported only with
36
+ `router.push(route, { teleport: true })` gets none of that and opens
37
+ cold. Never hand-build a link or call `openExternalUrl` to reach the web.
38
+ 2. **Send only shoppers with Apple Pay to the web.** App to web converts
39
+ well when the shopper pays with a double click; typing a card in a
40
+ browser does not. Read `useApplePay().available` and push the route with
41
+ `{ teleport: applePay.available }`: `true` teleports, `false` pushes the
42
+ same route in the app (`teleport: false` overrides `teleport.route`), so
43
+ the page is still warmed and checked. `false` includes `checking`, the
44
+ first moments before Apple answers; it is cached for the page, and the
45
+ paywall asked when it opened, so by the shopper's tap it has almost
46
+ always answered. Call `await checkApplePay()` instead when a tap must
47
+ wait for the real answer (at most 1.5 s, never `checking`).
48
+ 3. **In the app, sell store products; on the web, Stripe products.** The
49
+ route pushed in the app (no Apple Pay) offers the App Store product;
50
+ branch on `useDevice().host` (`"ios-sdk"` or `"android-sdk"` in an
51
+ app, `"web-teleport"` on the teleport page), never on the URL.
52
+ `purchase()` of a Stripe product inside the app teleports: to
53
+ `teleport.route` with the tapped product preselected there
54
+ (`useTeleport().productReference`), or, without `teleport.route`, to
55
+ the route it was tapped on, cold. That is fine as a deliberate path,
56
+ never as a side effect of the in-app branch.
57
+ 4. **Map every Stripe product to a store product in `teleport.fallbacks`.**
58
+ While the shopper is in the browser the app shows Superwall's teleport
59
+ screen; `fallbacks` adds "Continue In-App Instead", which buys the store
60
+ product. It is the way back for anyone who changes their mind.
61
+ 5. **Use direct Apple Pay, and block prepaid cards:** `checkout: { mode:
62
+ "applePay", prepaidCards: "block" }`. Direct Apple Pay opens Apple's own
63
+ sheet on the tap, a double click and done; it converts better than
64
+ Stripe's embedded card sheet (`"sheet"`), so never pick `"sheet"` for a
65
+ teleport paywall. It is **not available with Stripe Managed Payments**: a
66
+ Managed Payments session can't be paid with Apple Pay directly
67
+ (`useApplePay(product).product.reason` is `session_unsupported`) and the
68
+ shopper gets the card sheet instead. When the account uses Managed
69
+ Payments, tell the user, recommend direct Apple Pay, and let them decide
70
+ whether to set `managedPayments: false` in `checkout` for this paywall
71
+ (they give up Stripe acting as merchant of record on it). Prepaid cards
72
+ are how free trials are abused; `prepaidCards` holds on the card sheet,
73
+ but Apple Pay itself can't be filtered by card type, so also add a Radar
74
+ rule in the Stripe dashboard (see setup).
75
+ 6. **A/B test with separate paywalls, not branches in one.** Each variant is
76
+ its own paywall directory with its own `teleport.route`, attached as its
77
+ own variant in a campaign. A flag inside one paywall that decides which
78
+ route teleports loses the preparation, warm-up and pre-render for every
79
+ route but the configured one.
80
+
81
+ ## Worked example
82
+
83
+ The `teleport` example (`superwall create --example teleport`) is the full
84
+ flow; this is the shape with the rules above applied. `monthly` and `pro`
85
+ are Stripe products, `annual` the App Store one.
86
+
87
+ ```ts
88
+ // paywalls/web-checkout/config.ts
89
+ import { definePaywall } from "superwall/config";
90
+
91
+ export default definePaywall({
92
+ name: "Web checkout",
93
+ teleport: { route: "plan", fallbacks: { monthly: "annual", pro: "annual" } },
94
+ checkout: { mode: "applePay", prepaidCards: "block" },
95
+ products: {
96
+ monthly: "live:price_MONTHLY:7days-free",
97
+ pro: "live:price_PRO:no-trial",
98
+ annual: "pro_5999_year",
99
+ },
100
+ });
101
+ ```
102
+
103
+ ```tsx
104
+ // paywalls/web-checkout/app/goal.tsx — in the app
105
+ import { useApplePay } from "superwall/hooks";
106
+ import { useRouter } from "superwall/navigation";
107
+
108
+ export default function Goal() {
109
+ const router = useRouter();
110
+ const applePay = useApplePay();
111
+
112
+ return (
113
+ <button
114
+ type="button"
115
+ onClick={() => {
116
+ // Apple Pay set up: plan opens in the browser. Otherwise: plan, in the app.
117
+ router.push("plan", { teleport: applePay.available });
118
+ }}
119
+ >
120
+ Continue
121
+ </button>
122
+ );
123
+ }
124
+ ```
125
+
126
+ ```tsx
127
+ // paywalls/web-checkout/app/plan.tsx — on the web, or in the app without Apple Pay
128
+ import { useDevice, useProducts, usePurchase } from "superwall/hooks";
129
+
130
+ export default function Plan() {
131
+ const { host } = useDevice();
132
+ const { getProduct } = useProducts();
133
+ const { purchase } = usePurchase();
134
+ // In an app sell the store product: a Stripe purchase in the iOS app would
135
+ // teleport again, and the Android app can't teleport at all.
136
+ const inApp = host === "ios-sdk" || host === "android-sdk";
137
+ const reference = inApp ? "annual" : "monthly";
138
+ const product = getProduct(reference);
139
+
140
+ return (
141
+ <button type="button" onClick={() => void purchase(reference)}>
142
+ {product?.variables.price ? `Subscribe for ${product.variables.price}` : "Subscribe"}
143
+ </button>
144
+ );
145
+ }
146
+ ```
147
+
148
+ ## Where to go next
149
+
150
+ | The job | Read |
151
+ | --- | --- |
152
+ | Set up app to web end to end: prerequisites, the paywall, products, the campaign, verifying on a device | [references/setup.md](references/setup.md) |
153
+ | Setups and experiments: A/B tests by paywall, web prices and discounts, email before the teleport, failure and abandonment rescue, a custom teleport screen, trial eligibility, `completion`, attribution, and more | [references/experiments.md](references/experiments.md) |
154
+ | Anything else about the paywall: routes, `useQueryState`, `useTeleport`, layout, push and publish | the `superwall-framework` skill |
@@ -0,0 +1,328 @@
1
+ # Setups and experiments
2
+
3
+ What else an app-to-web flow can do, and what is worth testing. None of
4
+ this is required; [setup.md](setup.md) is the baseline. Read this file as
5
+ a menu of what the framework makes possible, and show the user that range:
6
+ a paywall is the user's own React, and teleport's primitives (the config
7
+ options, `useTeleport`, `usePurchase` callbacks, `useApplePay`,
8
+ `returnToApp({ data })`, `router.push(route, { teleport })`) compose into
9
+ almost any flow they can describe. When they ask for something not listed
10
+ here, build it from those pieces before saying it can't be done.
11
+
12
+ When the user asks for "an experiment" without saying which, start with
13
+ the first A/B test below against their current in-app paywall, and
14
+ suggest two or three others from this file as next steps.
15
+
16
+ Every snippet below is cut from a file that type-checks against the framework. `monthly` and
17
+ `webAnnual` are Stripe products, `annual` and `annualOffer` App Store ones;
18
+ use the user's own references.
19
+
20
+ ## A/B tests: one paywall per variant
21
+
22
+ Test teleport variants as separate paywalls, each a variant in the same
23
+ campaign audience, never as a flag inside one paywall. Only the configured
24
+ `teleport.route` is prepared, warmed, Apple Pay-checked and pre-rendered,
25
+ so a branch that teleports another route makes one variant slower and the
26
+ test unfair.
27
+
28
+ Copy the paywall directory, change only what the variant tests, push both,
29
+ and add each as a variant of the campaign audience. Find the endpoints with
30
+ `superwall api docs variant`, and split traffic with `superwall campaigns
31
+ variants weights <campaignId> <audienceId>` (the `superwall` skill's
32
+ `references/api.md`). Changing weights changes live traffic: confirm with
33
+ the user first.
34
+
35
+ Tests worth running, each one paywall directory per arm:
36
+
37
+ | Test | Arm A | Arm B |
38
+ | --- | --- | --- |
39
+ | App to web at all | the current in-app paywall | the same paywall with `teleport` |
40
+ | Which page teleports | `teleport.route` on the plan picker | on the last page |
41
+ | Web price | the same price as the App Store | a lower Stripe price (below) |
42
+ | Trial on the web | `introductoryOfferEligibility: "automatic"` | `"ineligible"` |
43
+ | After paying | `completion: "confirmation"` | `"direct"` |
44
+ | Who teleports | everyone with Apple Pay | only trial-eligible shoppers (below) |
45
+ | Way back | `fallbacks` on the teleport screen | a custom screen with its own offer (below) |
46
+ | Failure rescue | none | back to the app on a decline (below) |
47
+
48
+ ## Show the web price beside the App Store's
49
+
50
+ A Stripe product pays no App Store commission, so the web can be cheaper.
51
+ Both products are priced in the app before the teleport; say so on the
52
+ button that teleports:
53
+
54
+ ```tsx
55
+ const applePay = useApplePay();
56
+ const { getProduct } = useProducts();
57
+ const store = getProduct("annual")?.variables.price;
58
+ const web = getProduct("webAnnual")?.variables.price;
59
+
60
+ const label = applePay.available
61
+ ? web && store ? `${web} a year with Apple Pay (${store} in the App Store)` : "Continue"
62
+ : store ? `${store} a year` : "Continue";
63
+
64
+ return (
65
+ <button type="button" onClick={() => router.push("plan", { teleport: applePay.available })}>
66
+ {label}
67
+ </button>
68
+ );
69
+ ```
70
+
71
+ Without Apple Pay the same button stays in the app and names the App Store
72
+ price, so every shopper still has a way forward.
73
+
74
+ Never write a price into code or copy; both come from the stores.
75
+
76
+ ## Who teleports
77
+
78
+ The `teleport` option on a push is any boolean, so the gate can be more
79
+ than Apple Pay. Teleport only shoppers who can still take the trial, for
80
+ example:
81
+
82
+ ```tsx
83
+ const applePay = useApplePay();
84
+ const { eligible } = useIntroductoryOffer();
85
+ const teleport = applePay.available && eligible === true;
86
+
87
+ <button type="button" onClick={() => router.push("plan", { teleport })}>Continue</button>;
88
+ ```
89
+
90
+ The same works for a user attribute (`useUserAttribute`), a quiz answer in
91
+ `useQueryState`, or the locale. Keep Apple Pay in every gate.
92
+
93
+ ## Ask for the email in the app
94
+
95
+ A `user.email` becomes the Stripe customer's email, and the teleport page
96
+ takes the email the app sent, so asking for it before the teleport saves
97
+ the shopper typing it in the browser and lets the user follow up when a
98
+ web payment never happens:
99
+
100
+ ```tsx
101
+ const applePay = useApplePay();
102
+ const [email, setEmail] = useUserAttribute("email");
103
+
104
+ <input type="email" value={email ?? ""} onChange={(event) => void setEmail(event.target.value)} />;
105
+ <button type="button" onClick={() => router.push("plan", { teleport: applePay.available })}>
106
+ Continue
107
+ </button>;
108
+ ```
109
+
110
+ ## Promotion codes on the web
111
+
112
+ `useDiscount()` redeems a Stripe promotion code and prices every product
113
+ with it:
114
+
115
+ ```tsx
116
+ const { redeem, applied, getDiscountedProduct } = useDiscount();
117
+ const { purchase } = usePurchase();
118
+ const [code, setCode] = React.useState("");
119
+ const deal = applied ? getDiscountedProduct("webAnnual") : undefined;
120
+
121
+ <input value={code} onChange={(event) => setCode(event.target.value)} />;
122
+ <button type="button" onClick={() => void redeem(code)}>Apply</button>;
123
+ <button type="button" onClick={() => void purchase("webAnnual")}>
124
+ {deal?.applies ? `${deal.discountedPrice} (was ${deal.price})` : "Subscribe"}
125
+ </button>;
126
+ ```
127
+
128
+ `redeem(code)` resolves with the verdict; `useDiscount({ onDropped })`
129
+ fires when checkout later refuses a code.
130
+
131
+ ## Rescue a failed payment
132
+
133
+ `usePurchase({ onFailure })` says why a web payment failed
134
+ (`failure.reason`: `card_declined`, `insufficient_funds`, `expired_card`,
135
+ `incorrect_card_details`, `authentication_failed`, `card_not_supported`,
136
+ `limit_exceeded`, `fraud_suspected`, `processing_error`, `unknown`). Each
137
+ reason can get its own answer: a cheaper plan on the page, or back to the
138
+ app for the App Store:
139
+
140
+ ```tsx
141
+ // the teleport route, on the web
142
+ const teleport = useTeleport();
143
+ const [cheaper, setCheaper] = React.useState(false);
144
+ const { purchase } = usePurchase({
145
+ onFailure: (failure) => {
146
+ if (teleport.status !== "arrived") return;
147
+ if (failure.reason === "insufficient_funds") setCheaper(true);
148
+ else if (failure.reason === "card_declined") void teleport.returnToApp({ data: { offer: "app_store" } });
149
+ },
150
+ });
151
+ const reference = cheaper ? "monthly" : "webAnnual";
152
+ ```
153
+
154
+ In the app, `useTeleport()` reads what came back while `status ===
155
+ "waiting"`:
156
+
157
+ ```tsx
158
+ // the route before it, in the app
159
+ const back = useTeleport({ onReturnData: (data) => console.info("back from the page", data) });
160
+ const offer = back.status === "waiting" ? back.data?.offer : undefined;
161
+ const failure = back.status === "waiting" ? back.failure : undefined;
162
+ // offer === "app_store": show purchase("annual"); failure: say what happened
163
+ ```
164
+
165
+ `returnToApp()` resolves `"opened"`, `"cancelled"` (the shopper tapped
166
+ Cancel on "Open in App?") or `"no_app"`; on anything but `"opened"` they
167
+ are still on the page, so leave it ready to buy again. The data is plain
168
+ JSON, at most 16 KB.
169
+
170
+ ## An offer when the shopper gives up
171
+
172
+ In the app, `useTeleport({ onCancel })` fires when the shopper cancels on
173
+ the teleport screen. Answer with an in-app offer, an App Store product at
174
+ an introductory price, on a route of its own:
175
+
176
+ ```tsx
177
+ // in the app
178
+ const router = useRouter();
179
+ const { customPlacement } = useActions();
180
+ useTeleport({
181
+ onCancel: () => {
182
+ customPlacement("teleport_cancelled");
183
+ router.push("offer", { teleport: false });
184
+ },
185
+ });
186
+ ```
187
+
188
+ ```tsx
189
+ // app/offer.tsx
190
+ const price = getProduct("annualOffer")?.variables.price;
191
+
192
+ <button type="button" onClick={() => void purchase("annualOffer")}>
193
+ {price ? `Stay in the app: ${price} for the first year` : "Stay in the app"}
194
+ </button>;
195
+ ```
196
+
197
+ `customPlacement(name)` fires a placement the SDK reports like any other,
198
+ so the user can count it, and aim a campaign at it, in the dashboard.
199
+ `useTeleport({ onOpen, onReturn, onComplete })` are there for the other
200
+ moments; an unpaid return resolves the `purchase()` as `abandoned`.
201
+
202
+ ## Your own teleport screen
203
+
204
+ `teleport.overlay: false` hides Superwall's teleport screen; draw your own
205
+ from `useTeleport()` while `status === "waiting"` and not `returned`. Its
206
+ copy, its offer and its look are all yours:
207
+
208
+ ```tsx
209
+ export function WaitingScreen() {
210
+ const teleport = useTeleport();
211
+ const { getProduct } = useProducts();
212
+ const { purchase } = usePurchase();
213
+ if (teleport.status !== "waiting" || teleport.returned) return null;
214
+ const fallback = teleport.fallbackReference;
215
+ const price = fallback ? getProduct(fallback)?.variables.price : undefined;
216
+
217
+ return (
218
+ <div role="dialog">
219
+ <p>Finish in Safari. Your plan is waiting there.</p>
220
+ <button type="button" onClick={teleport.open}>Open Safari again</button>
221
+ {fallback && price ? (
222
+ <button type="button" onClick={() => void purchase(fallback)}>
223
+ Pay {price} in the app instead
224
+ </button>
225
+ ) : null}
226
+ <button type="button" onClick={teleport.cancel}>Not now</button>
227
+ </div>
228
+ );
229
+ }
230
+ ```
231
+
232
+ `fallbackReference` is the `teleport.fallbacks` product for what is being
233
+ bought. Render it from the layout so it covers every page. Keep the default
234
+ screen unless the user wants their own; it already does all of this.
235
+
236
+ ## An Apple Pay button on the web page
237
+
238
+ `useApplePay(product).product` says whether Apple's sheet will open for
239
+ that product, so the web page can promise it:
240
+
241
+ ```tsx
242
+ const applePay = useApplePay("webAnnual");
243
+
244
+ <button type="button" onClick={() => void purchase("webAnnual")}>
245
+ {applePay.product.status === "ready" ? "Pay with Apple Pay" : "Continue to payment"}
246
+ </button>;
247
+ ```
248
+
249
+ ## After the payment: `completion`
250
+
251
+ `teleport.completion` decides what the web page does once paid:
252
+ `"confirmation"` (the default) shows "You're all set" with Return to App;
253
+ `"direct"` opens the app at once and shows that screen only when the app
254
+ didn't open. Worth testing when shoppers stay on the page after paying.
255
+
256
+ ## The trial on the web: `introductoryOfferEligibility`
257
+
258
+ The App Store's trial history doesn't bind a Stripe purchase, so the web
259
+ checkout decides on its own: `teleport.introductoryOfferEligibility` is
260
+ `"automatic"` (the app's store says the shopper is eligible, the default),
261
+ `"eligible"` (always offer it) or `"ineligible"` (never). The Stripe
262
+ product's offer (`7days-free`, `no-trial`) sets which trial it is.
263
+
264
+ ## Tag the purchase for analysis
265
+
266
+ `purchase(reference, { stripeMetadata })` writes key/values onto the
267
+ Stripe subscription, visible in Stripe and its webhooks; tag the arm so
268
+ revenue joins the experiment:
269
+
270
+ ```tsx
271
+ const teleport = useTeleport();
272
+ const tapped = teleport.status === "arrived" ? teleport.productReference : undefined;
273
+ const reference = tapped ?? "webAnnual";
274
+
275
+ <button
276
+ type="button"
277
+ onClick={() => void purchase(reference, { stripeMetadata: { experiment: "teleport-early", variant: "b" } })}
278
+ >
279
+ Subscribe
280
+ </button>;
281
+ ```
282
+
283
+ `teleport.productReference` is the Stripe product tapped in the app when a
284
+ `purchase()` started the teleport; preselect it.
285
+
286
+ ## Two ways into the web
287
+
288
+ When a paywall teleports from more than one page, keep the main one as
289
+ `teleport.route` and prepare the other with `useTeleport().prefetch(route)`
290
+ as soon as it can be reached, so it opens warm too:
291
+
292
+ ```tsx
293
+ const applePay = useApplePay();
294
+ const { prefetch } = useTeleport();
295
+ React.useEffect(() => prefetch("checkout"), [prefetch]);
296
+
297
+ <button type="button" onClick={() => router.push("checkout", { teleport: applePay.available })}>
298
+ Checkout
299
+ </button>;
300
+ ```
301
+
302
+ The second page keeps the same Apple Pay gate as the first.
303
+
304
+ ## Leaving the web page without paying
305
+
306
+ On the first web route, `router.back()` and `close()` return to the app.
307
+ The teleport screen's Continue In-App Instead buys the `teleport.fallbacks`
308
+ product.
309
+
310
+ ## A Stripe purchase in the app
311
+
312
+ `purchase()` of a Stripe product inside the app teleports: to
313
+ `teleport.route` with that product preselected
314
+ (`useTeleport().productReference` on the page), or, without
315
+ `teleport.route`, to the route it was tapped on, which is not warmed.
316
+ Without `teleport` in config at all, it opens Superwall's hosted checkout
317
+ in the browser instead, the older app-to-web path. Prefer pushing
318
+ `teleport.route` behind the Apple Pay gate; use a Stripe purchase in the
319
+ app when that preselection is the point.
320
+
321
+ ## And everything else
322
+
323
+ The web page is the same paywall, so the rest of the framework applies on
324
+ both sides: transitions and motion, Rive, layouts and themes, localized
325
+ copy, haptics in the app, `useQueryState` answers carried across the
326
+ teleport, quizzes and onboarding before the paywall, trial reminders. Any
327
+ of them can be an arm of a test. Pick by what the user wants to learn, and
328
+ keep one change per arm.