@superwall/cli 2.6.0 → 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.
Files changed (142) hide show
  1. package/dist/{apple-D-rfsuDA.js → apple-DfYTDEJy.js} +16 -16
  2. package/dist/{approve-aPc5RoXB.js → approve-CoQJhii4.js} +7 -7
  3. package/dist/{assets-PyuXe45Y.js → assets-BN0tFoj7.js} +3 -3
  4. package/dist/auth.d.ts +1 -1
  5. package/dist/auth.js +3 -3
  6. package/dist/{base-CAU0hWoI.js → base-DAnzMjI8.js} +2 -2
  7. package/dist/{billing-Dt6L_l9R.js → billing-CFGrG-WZ.js} +3 -3
  8. package/dist/{build-CY5FnMNY.js → build-CTBvzIG8.js} +10 -10
  9. package/dist/{config-DOp5oChe.js → config-CJRNScT0.js} +4 -4
  10. package/dist/{create-BZL5VH4L.js → create-BLs-0ETi.js} +29 -29
  11. package/dist/create-C_kjQp0N.js +18 -0
  12. package/dist/{create-D6w3UL0m.js → create-aWzdpjJU.js} +8 -8
  13. package/dist/{doctor-C9FR0qw3.js → doctor-ChI2Kfru.js} +21 -21
  14. package/dist/entry.js +28 -29
  15. package/dist/{environment-sE2wZYdg.js → environment-BQiaGqjB.js} +1 -1
  16. package/dist/{existing--peXpOZj.js → existing-Cxg_gSN1.js} +8 -8
  17. package/dist/{git-Hf9Wc7Hp.js → git-D9ooAMt7.js} +1 -1
  18. package/dist/held-CQMCqJMa.js +15 -0
  19. package/dist/{held-CUBCOCGP.js → held-CmvNRCRD.js} +327 -22
  20. package/dist/{scope-BLLUxbrA.js → input-ApyzIzVy.js} +48 -7
  21. package/dist/{install-C5d82gZF.js → install-DM0JBdpE.js} +12 -12
  22. package/dist/{integrate-D8J_X1bj.js → integrate-ZQUaScQ0.js} +21 -22
  23. package/dist/login-Cnt3UZKV.js +13 -0
  24. package/dist/{login-DXhm9L0F.js → login-CvzBt9eM.js} +2 -2
  25. package/dist/{login-C6X7JrhM.js → login-Oo2NWLlX.js} +7 -7
  26. package/dist/{lookup-DqmIbUkv.js → lookup-CHLrO7v7.js} +3 -3
  27. package/dist/{migrate-BYF6hKZ2.js → migrate-mFKBset8.js} +30 -30
  28. package/dist/{notification-url-Bo54nkXv.js → notification-url-Dpx0pbYs.js} +3 -3
  29. package/dist/{open-xdgXUzaF.js → open-CxgE8kLT.js} +2 -2
  30. package/dist/{org-BD8U3D1_.js → org-0KDPRSlc.js} +4 -4
  31. package/dist/{organization-D-ZlB3qU.js → organization-Cg--QQtz.js} +4 -4
  32. package/dist/{orgs-DQQJ3sw_.js → orgs-Df8DzIav.js} +1 -1
  33. package/dist/{paths-CIlyzF2I.js → paths-B4FNcaHO.js} +1 -1
  34. package/dist/{playbook-ecggWGFi.js → playbook-pFhIg_0e.js} +10 -10
  35. package/dist/{promote-QVMLGYlU.js → promote-Crwz1xI0.js} +23 -23
  36. package/dist/{pull-CCXhb2a7.js → pull-BixwETu1.js} +10 -10
  37. package/dist/pull-C0gY7HGj.js +30 -0
  38. package/dist/{pull-CrdsfsAl.js → pull-D8GfsKha.js} +30 -30
  39. package/dist/{push-DJMGG7zW.js → push-BKoav_FU.js} +10 -10
  40. package/dist/{push-DiMDwGfe.js → push-BNFvZHUM.js} +8 -8
  41. package/dist/push-DOaBj8hr.js +29 -0
  42. package/dist/push-uWv5P0LA.js +21 -0
  43. package/dist/{registry-BSnQXft4.js → registry-BPqRG08G.js} +270 -435
  44. package/dist/registry-DGHTk7l-.js +21 -0
  45. package/dist/{resolve-DO7bPota.js → resolve-CarLrF4b.js} +3 -3
  46. package/dist/{resources-XwvXA20E.js → resources-BeXleviK.js} +15 -34
  47. package/dist/{run-B-YvxfRc.js → run-naBCXCfn.js} +14 -14
  48. package/dist/{scan-ViBhmrB7.js → scan-CtYVCqDS.js} +1 -1
  49. package/dist/scan-KWnscsk-.js +4 -0
  50. package/dist/{sdk-BFunw4Hc.js → sdk-BKVRAv23.js} +2 -2
  51. package/dist/{selection-C07e_GGY.js → selection-CpEfqw2b.js} +1 -1
  52. package/dist/{series-B8NJK4yS.js → series-C9OU5kd7.js} +1 -1
  53. package/dist/server-DjBnyiwD.js +33 -0
  54. package/dist/{server-CBtHzl9y.js → server-Dp5Imq3v.js} +11 -11
  55. package/dist/{session-BfVx50iA.js → session-6HA1OwHe.js} +6 -6
  56. package/dist/session-BatiAUPQ.js +5 -0
  57. package/dist/{session-BlrwAdGN.js → session-BpLOLurZ.js} +1 -1
  58. package/dist/{setup-a4B72xJ8.js → setup-RL-5c6SV.js} +10 -10
  59. package/dist/skills/index.json +5 -0
  60. package/dist/skills/superwall/SKILL.md +8 -1
  61. package/dist/skills/superwall/references/api.md +34 -3
  62. package/dist/skills/superwall/references/asc.md +5 -1
  63. package/dist/skills/superwall/workflows/dashboard/playbook.md +1 -1
  64. package/dist/skills/superwall/workflows/dashboard/setup.md +6 -2
  65. package/dist/skills/superwall/workflows/migrate/adapty.md +1 -1
  66. package/dist/skills/superwall/workflows/migrate/playbook.md +6 -1
  67. package/dist/skills/superwall/workflows/migrate/qonversion.md +1 -1
  68. package/dist/skills/superwall/workflows/migrate/revenuecat.md +1 -1
  69. package/dist/skills/superwall/workflows/placements/android.md +4 -1
  70. package/dist/skills/superwall/workflows/placements/expo.md +4 -1
  71. package/dist/skills/superwall/workflows/placements/flutter.md +4 -1
  72. package/dist/skills/superwall/workflows/placements/ios.md +4 -1
  73. package/dist/skills/superwall/workflows/placements/playbook.md +6 -1
  74. package/dist/skills/superwall/workflows/placements/react-native.md +4 -1
  75. package/dist/skills/superwall/workflows/placements/strategy.md +4 -1
  76. package/dist/skills/superwall-framework/SKILL.md +105 -26
  77. package/dist/skills/superwall-framework/references/cli.md +6 -0
  78. package/dist/skills/superwall-framework/references/elements-checkout.md +457 -0
  79. package/dist/skills/superwall-framework/references/examples.md +1 -0
  80. package/dist/skills/superwall-framework/references/layout.md +40 -2
  81. package/dist/skills/teleport/SKILL.md +154 -0
  82. package/dist/skills/teleport/references/experiments.md +328 -0
  83. package/dist/skills/teleport/references/setup.md +157 -0
  84. package/dist/{skills-BB1uIt8t.js → skills-C1ku2pgy.js} +5 -5
  85. package/dist/{skills-SnxFa2in.js → skills-CkAWJveA.js} +8 -8
  86. package/dist/{source-push-w7miTr6m.js → source-push-D59hV02W.js} +6 -6
  87. package/dist/{spinner-BQp7fQvK.js → spinner-hTCJZAoJ.js} +42 -7
  88. package/dist/{starter-BlJ_InZJ.js → starter-jYb2nmlb.js} +3 -3
  89. package/dist/{status-DxsIw9zq.js → status-DrD9CHtK.js} +7 -7
  90. package/dist/{storage-BR6imSqm.js → storage-D0Q4xBi-.js} +1 -1
  91. package/dist/storekit-CAOpa6_f.js +14 -0
  92. package/dist/{storekit-BqyujKQ_.js → storekit-TLBxGIrN.js} +5 -5
  93. package/dist/{theme-Ed0gz6hr.js → theme-Bvv0yrk_.js} +5 -5
  94. package/dist/{token-CWQ6tdva.js → token-SEWilQo9.js} +1 -1
  95. package/dist/tools-skills/superwall/SKILL.md +8 -1
  96. package/dist/tools-skills/superwall/references/api.md +34 -3
  97. package/dist/tools-skills/superwall/references/asc.md +5 -1
  98. package/dist/tools-skills/superwall/workflows/dashboard/playbook.md +1 -1
  99. package/dist/tools-skills/superwall/workflows/dashboard/setup.md +6 -2
  100. package/dist/tools-skills/superwall/workflows/migrate/adapty.md +1 -1
  101. package/dist/tools-skills/superwall/workflows/migrate/playbook.md +6 -1
  102. package/dist/tools-skills/superwall/workflows/migrate/qonversion.md +1 -1
  103. package/dist/tools-skills/superwall/workflows/migrate/revenuecat.md +1 -1
  104. package/dist/tools-skills/superwall/workflows/placements/android.md +4 -1
  105. package/dist/tools-skills/superwall/workflows/placements/expo.md +4 -1
  106. package/dist/tools-skills/superwall/workflows/placements/flutter.md +4 -1
  107. package/dist/tools-skills/superwall/workflows/placements/ios.md +4 -1
  108. package/dist/tools-skills/superwall/workflows/placements/playbook.md +6 -1
  109. package/dist/tools-skills/superwall/workflows/placements/react-native.md +4 -1
  110. package/dist/tools-skills/superwall/workflows/placements/strategy.md +4 -1
  111. package/dist/tools-skills/teleport/SKILL.md +154 -0
  112. package/dist/tools-skills/teleport/references/experiments.md +328 -0
  113. package/dist/tools-skills/teleport/references/setup.md +157 -0
  114. package/dist/tools.d.ts +4 -2
  115. package/dist/tools.js +1357 -1191
  116. package/dist/{try-C3HW3hPZ.js → try-BpMpLGCs.js} +15 -15
  117. package/dist/{ui-hFgji1e8.js → ui-Dye-QvEj.js} +26 -1
  118. package/dist/{upgrade-Cw9jVt-r.js → upgrade-BLFWdbGR.js} +7 -7
  119. package/dist/upgrade-BzN7PjKg.js +27 -0
  120. package/package.json +2 -2
  121. package/dist/create-DM5Y1Pyk.js +0 -18
  122. package/dist/held-DVxvPMSG.js +0 -15
  123. package/dist/input-DOT_2Zvb.js +0 -42
  124. package/dist/login-et319ESO.js +0 -13
  125. package/dist/pull-h71pL3r_.js +0 -30
  126. package/dist/push-BIq6R8Ro.js +0 -29
  127. package/dist/push-D6pJM_vv.js +0 -21
  128. package/dist/registry-YwzTfCNc.js +0 -22
  129. package/dist/scan-B36wkZmI.js +0 -4
  130. package/dist/server-CZwSfzKe.js +0 -33
  131. package/dist/session-Cip4j99n.js +0 -5
  132. package/dist/storekit-ELVCMF0X.js +0 -15
  133. package/dist/upgrade-DVsonzDF.js +0 -27
  134. /package/dist/{design-lint-mgO-2SGS.js → design-lint-CeG3_ZWN.js} +0 -0
  135. /package/dist/{devtools-B6Vp6HMy.js → devtools-B3tCQFD-.js} +0 -0
  136. /package/dist/{download-DhGd4hOB.js → download-DVFHIwia.js} +0 -0
  137. /package/dist/{project-BomArwSj.js → project-Dml4t7jO.js} +0 -0
  138. /package/dist/{reports-hbxsd3Zo.js → reports-CJQ-8sj4.js} +0 -0
  139. /package/dist/{screenshot-file-Dix2Qynm.js → screenshot-file-CcqMLpL5.js} +0 -0
  140. /package/dist/{source-DQs6iLtC.js → source-Ct9kOCAb.js} +0 -0
  141. /package/dist/{storage-Bh3wT1Rn.d.ts → storage-BaK-MUM8.d.ts} +0 -0
  142. /package/dist/{timing-BKEEIBij.js → timing-m0ZUzYiP.js} +0 -0
@@ -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.
@@ -0,0 +1,157 @@
1
+ # Set up app to web
2
+
3
+ The playbook for "set up an app-to-web flow" or "an app-to-web experiment".
4
+ Do every step; each ends with how to tell it worked. The recommendations are
5
+ today's (November 2026) and may change. The `superwall-framework` skill
6
+ covers everything about writing the paywall; this file only adds what
7
+ teleport needs.
8
+
9
+ ## Checklist
10
+
11
+ - [ ] 1. Prerequisites hold (SDK, web paywall domain, Stripe, app links)
12
+ - [ ] 2. Products: Stripe products for the web, a store product for each fallback
13
+ - [ ] 3. `config.ts`: `teleport.route`, `fallbacks`, direct Apple Pay with prepaid cards blocked
14
+ - [ ] 4. The Apple Pay gate on the push that reaches `teleport.route`
15
+ - [ ] 5. The teleport route sells Stripe on the web and the store in the app
16
+ - [ ] 6. Prepaid cards blocked in Stripe Radar too
17
+ - [ ] 7. Pushed, verified on an iPhone, attached to a campaign
18
+
19
+ ## 1. Prerequisites
20
+
21
+ - **SuperwallKit 4.18.0 or later** in the iOS app. On an older SDK, and on
22
+ Android, teleport doesn't run: the route opens in the app and a Stripe
23
+ purchase goes to Superwall's hosted checkout. Read the version from the
24
+ app's package manager, never assume it.
25
+ - **A web paywall domain and Stripe connected** on the Superwall app the
26
+ paywall is pushed to: the teleport page opens on that domain, and Stripe
27
+ takes the payment. Both are dashboard settings; when either is missing,
28
+ say so and stop, the user sets them up.
29
+ - **A way back to the app:** its universal link (associated domains), its
30
+ URL scheme, or both. The framework picks the link; `no_app` from
31
+ `returnToApp()` means neither is set.
32
+
33
+ ## 2. Products
34
+
35
+ Stripe products (`{environment}:{priceId}:{offer}`, such as
36
+ `live:price_123:7days-free`) are what the web page sells. Give each one a
37
+ store product to fall back to in the app. Never hardcode a price: the stores
38
+ price them at runtime. Create what's missing with `superwall products
39
+ create` (the `superwall-framework` skill's `references/cli.md`); list first.
40
+
41
+ ## 3. `config.ts`
42
+
43
+ ```ts
44
+ import { definePaywall } from "superwall/config";
45
+
46
+ export default definePaywall({
47
+ name: "Web checkout",
48
+ teleport: {
49
+ route: "plan", // the web half opens here; prepared, warmed and pre-rendered
50
+ fallbacks: { monthly: "annual" }, // "Continue In-App Instead" on the teleport screen
51
+ },
52
+ checkout: { mode: "applePay", prepaidCards: "block" },
53
+ products: { monthly: "live:price_MONTHLY:7days-free", annual: "pro_5999_year" },
54
+ });
55
+ ```
56
+
57
+ - `route` is required by this playbook even though the type makes it
58
+ optional: it is what makes the browser open at once.
59
+ - `checkout` only applies to the web half here: inside the iOS app a
60
+ purchase never uses it. `"applePay"` is direct Apple Pay: Apple's sheet
61
+ opens on the tap, and Stripe's card sheet is only the fallback where
62
+ Apple Pay can't open. Always use it on a teleport paywall; `"sheet"`
63
+ (Stripe's embedded checkout) makes every shopper start from a card form.
64
+ A teleport page left without `checkout` uses `"applePay"` too, but write
65
+ it so `prepaidCards` has a place.
66
+ - **Stripe Managed Payments:** direct Apple Pay is not available with it.
67
+ A Managed Payments checkout session comes back as Stripe's embedded
68
+ checkout, so `useApplePay(product).product` reads `session_unsupported`
69
+ and the tap opens the card sheet. Ask the user whether their Stripe
70
+ account uses Managed Payments; when it does, recommend direct Apple Pay
71
+ and let them choose `checkout: { mode: "applePay", managedPayments:
72
+ false, prepaidCards: "block" }` for this paywall (Stripe stops acting as
73
+ merchant of record on it). Their call, not yours.
74
+ - Leave `completion` (`"confirmation"`) and `introductoryOfferEligibility`
75
+ (`"automatic"`) at their defaults unless the user is testing them
76
+ ([experiments.md](experiments.md)).
77
+
78
+ ## 4. The Apple Pay gate
79
+
80
+ The push that reaches `teleport.route` decides whether the shopper goes to
81
+ the web:
82
+
83
+ ```tsx
84
+ const applePay = useApplePay();
85
+ router.push("plan", { teleport: applePay.available });
86
+ ```
87
+
88
+ `available` is Apple's own card check
89
+ (`ApplePaySession.canMakePaymentsWithActiveCard`), the same in the iOS
90
+ app's web view as in a browser; on Android it is `false`
91
+ (`unsupported_browser`), where teleport doesn't run anyway. The answer is
92
+ asked when the paywall opens and cached for the page; an error or a timeout
93
+ is asked again. A tap that must wait for the answer uses
94
+ `const { available } = await checkApplePay()` instead.
95
+
96
+ Verify: in the studio (Chrome) `useApplePay()` reads `false,
97
+ unsupported_browser`, so the push stays in the app. That is expected; the
98
+ teleport itself only runs on an iPhone (step 7).
99
+
100
+ ## 5. The teleport route
101
+
102
+ The route runs in two places: on the web page after a teleport, and in the
103
+ app for shoppers without Apple Pay. Branch on `useDevice().host`:
104
+
105
+ - `"ios-sdk"` or `"android-sdk"`: sell the store product. A Stripe
106
+ `purchase()` in the iOS app would teleport again, and the Android app
107
+ can't teleport, so it would open hosted checkout instead.
108
+ - anything else (`"web-teleport"` on the teleport page): sell the Stripe
109
+ product, preselecting `useTeleport().productReference` when the app
110
+ passed one.
111
+
112
+ Keep the first render of the route to what the pre-render knows (locale,
113
+ products and prices, trial, `productReference`); the `superwall-framework`
114
+ skill's teleport rule lists the details.
115
+
116
+ ## 6. Prepaid cards in Stripe
117
+
118
+ `prepaidCards: "block"` refuses prepaid cards on Stripe's card sheet and
119
+ hosted checkout. An Apple Pay payment can't be filtered by card type from
120
+ the paywall, so also ask the user to add a rule in the Stripe dashboard
121
+ (Radar → Rules): `Block if :card_funding: = 'prepaid'`, and to check it
122
+ in test mode. That is a person's step; list it in the hand-over.
123
+
124
+ ## 7. Push, verify, attach
125
+
126
+ 1. `superwall push`, then fix every pre-render warning it prints for the
127
+ teleport route (the page would render in the browser instead).
128
+ 2. On an iPhone with a card in Wallet, open the paywall from the app (the
129
+ SDK's debugger, or its placement), tap through to `plan`: the browser
130
+ opens on the plan, Apple Pay pays, "You're all set", Return to App, and
131
+ the app is unlocked.
132
+ 3. On an iPhone or simulator with an empty Wallet, the same tap opens
133
+ `plan` in the app with the store product.
134
+ 4. On the web page, the pay button opens Apple's sheet straight away, not
135
+ a card form. A card form means `"sheet"` mode or Managed Payments
136
+ (step 3).
137
+ 5. In the browser, cancel the payment and use Continue In-App Instead on
138
+ the teleport screen: the store sheet opens for the fallback.
139
+ 6. `superwall promote` (or `publish`), then attach the paywall to its
140
+ campaign (the `superwall` skill's dashboard workflow). For an
141
+ experiment, each variant is its own paywall: see
142
+ [experiments.md](experiments.md#ab-tests-one-paywall-per-variant).
143
+
144
+ ## Pitfalls
145
+
146
+ - Teleporting a route other than `teleport.route` with
147
+ `router.push(route, { teleport: true })`: it opens cold. Make it the
148
+ route, or call `useTeleport().prefetch(route)` when it must stay
149
+ another one.
150
+ - Reading `useApplePay()?.available`: it is always defined; read it
151
+ without `?.`. `useVariables().device.isApplePayAvailable` is deprecated
152
+ and always `true` in the app.
153
+ - Answers kept in component state are lost on the web: keep what the web
154
+ half needs in `useQueryState`, which the teleport carries along.
155
+ - Returning to the app with `openDeepLink` or a hand-built link: use
156
+ `useTeleport().returnToApp()`, or `close()` / `router.back()` on the
157
+ first web route.
package/dist/tools.d.ts CHANGED
@@ -1,4 +1,4 @@
1
- import "./storage-Bh3wT1Rn.js";
1
+ import "./storage-BaK-MUM8.js";
2
2
 
3
3
  //#region src/core/api/client.d.ts
4
4
 
@@ -21,7 +21,9 @@ type SuperwallApi = {
21
21
  post<T>(path: string, body: unknown, options?: RequestOptions): Promise<T>;
22
22
  put<T>(path: string, body: unknown, options?: RequestOptions): Promise<T>;
23
23
  patch<T>(path: string, body: unknown, options?: RequestOptions): Promise<T>;
24
- del<T>(path: string, options?: RequestOptions): Promise<T>;
24
+ del<T>(path: string, options?: RequestOptions & {
25
+ body?: unknown;
26
+ }): Promise<T>;
25
27
  postText(path: string, body: string): Promise<string>;
26
28
  list<T>(path: string): Promise<T[]>;
27
29
  };