Framework Teleport
Continue a flow on the web from a route on: an iOS app hands the shopper to their browser, they pay with Stripe there, and come back to the app with access.
Teleport moves the rest of a flow to the web. When the flow reaches a teleporting route inside an iOS app, the shopper's browser opens on that route, on your project's web paywall domain, with the flow's answers carried along. They pay with Stripe there and come back to the app, which is credited automatically.
Turn it on in config.ts, with every default:
export default definePaywall({
products: { card: "live:price_1ABC…:14days-free", annual: "com.acme.pro.annual" },
teleport: true,
});Then teleport a push from the router:
router.push("checkout", { teleport: true });Or name the route in the config, so a push to it and a Stripe purchase teleport without asking, and the teleport is prepared when the paywall opens:
teleport: { route: "checkout", fallbacks: { card: "annual" } },purchase("card") is the same call as everywhere else.
The teleport example is a complete flow: one question in the app, then the plan in the browser.
Check for Apple Pay before teleporting
Teleport pays off when the shopper can pay with Apple Pay on the web page. Without it, most teleported shoppers don't finish, and they do better buying in the app. So check useApplePay().available first, and keep the shopper in the app unless it is true:
import { useApplePay } from "superwall/hooks";
import { useRouter } from "superwall/navigation";
const applePay = useApplePay();
const router = useRouter();
const onContinue = () =>
applePay.available
? router.push("checkout") // teleport.route: pay with Apple Pay on the web
: router.push("checkout", { teleport: false }); // the same route, in the approuter.push(route, { teleport: false }) pushes even teleport.route in the app, so the in-app route can sell the store product. Keep teleport.route in config.ts rather than deciding with { teleport: true } per push: with the route there, the paywall asks Apple as soon as it opens, prepares the teleport and pre-renders the web page, so the answer is usually there before the first tap and the browser opens at once. To A/B test where to teleport, make separate paywalls rather than branching in one.
available comes from Apple's card check, the same inside the iOS SDK as on the web, and false means stay in the app: Apple hasn't answered yet ("checking"), Wallet has no card, there is no Apple Pay (as on Android), or the check timed out. Gating web checkout on this kind of check has been measured to cut the share of paywall sessions where Apple Pay was unavailable on Stripe web checkout from about 7% to about 0.1%, with conversion flat.
Any usable card counts, Apple Cash with no balance too, so true means Apple Pay is set up, not that the payment will go through. Don't use device.isApplePayAvailable for this: it is deprecated, and the SDK always reports true.
What happens
In the app. Three things teleport:
- A push asked to.
router.push(route, { teleport: true })(orreplace) opens the route in the browser instead of pushing it, and the paywall stays where it is. - A push to
teleport.route. The same, without the option.{ teleport: false }pushes it in the app instead, see Check for Apple Pay before teleporting. - A Stripe purchase.
purchase("card")opensteleport.routein the browser, or the route it was tapped on when there is none, withcardas the product the shopper tapped. It resolves once the teleport settles:completedwhen they paid,abandonedwhen they cancelled or the checkout expired.
While the shopper is in the browser, the app shows Superwall's teleport screen over the paywall: "Finish in your browser", with Complete in Browser (opens it again), Continue In-App Instead (only with a fallback), and Cancel. The app keeps checking the purchase, in the background too. Once it is paid, the SDK redeems it and the paywall dismisses (or stays, with postPurchase: "stay").
A second tap while the browser is open reopens the same tab, switched to the product tapped this time, so the shopper never ends up with two checkouts. When they come back to the app, the screen goes and the purchase is checked once more behind a loader; if it is still unpaid after a few seconds it counts as abandoned. Cancel, closing the paywall, or paying in the app keeps the checkout watched for a few minutes, so a payment the shopper finishes anyway is still credited, and the next tap reopens the same tab.
On the web. The same paywall opens in the browser on the teleported route. Every useQueryState value the flow had in the app is already set, so the web page picks up where the app left off, and useTeleport().productReference is the product the shopper tapped. From there, navigation is ordinary:
router.pushmoves forward on the web;router.back()andclose()on the teleported route return to the app;router.canGoBack()istrueon the teleported route, so a back button stays on screen.
A Stripe purchase on the web page pays in the page, with Apple Pay or the card sheet (whatever checkout says, Apple Pay by default), never on the hosted page, and only Stripe products are sold there. Once it completes, the page says "You're all set" with Return to App, or opens the app at once and shows "You're all set" if the app didn't open, see completion. The app opens through its universal link, falling back to its URL scheme when the link doesn't open it, see Returning to the app.
The page sells one purchase per presentation. Opened again once paid, it shows "You're all set" instead of selling again; and when the app opened another checkout for the same presentation and that one got paid, the page switches to say so.
How the web page loads
With teleport.route set, superwall push pre-renders that route when it builds the paywall, and so does superwall build with a platform. It renders one page per locale, per Stripe product plus one with no product tapped, and per trial on and off: at most 200 pages, each at most 256 KB. When the shopper opens the link, the browser paints the matching page straight from the HTML, before any JavaScript runs, and React takes it over without drawing it again. The page boots with the shopper's locale and device variables, so its first render already has them.
Anything without a matching page renders in the browser, as before:
- a page made for another state, or none at all;
- a route teleported with
{ teleport: true }that isn'tteleport.route; - product references that are
__none__or only dots (.,..), and locales past the 200-page limit, which get no page.
A pre-render that fails never fails the push: it prints a warning, and that page renders in the browser.
What the first frame may read. The pre-render knows the locale, the products and their prices, whether the trial is on, and the tapped product (useTeleport().productReference). A first frame built from those is exactly the page the shopper gets.
What it can't know. The pages are rendered at build time, with no shopper. Anything drawn from these changes once the page takes over:
- user attributes from
useUser(); - the flow's
useQueryStateanswers; - markup that branches on
useColorScheme()(colours from CSS variables are right from the first paint); - the time, and random values.
Keep them off the first frame: put them below the fold, or behind a state that starts the same at build time and in the browser.
The layout keeps the pre-rendered page's insets after the page takes over: a teleported page uses only the browser's safe area, never the in-app one for the app's device. See the safe area.
Returning to the app
On the web page, three calls send the shopper back to the app: useTeleport().returnToApp(), close() from useActions(), and router.back() on the teleported route. Each opens the app through its universal link first, and through its URL scheme when the link doesn't open it.
Return only through these. Never send the shopper back with openDeepLink, openUrl, an <a href> or a link you build yourself from the app's scheme or universal link. Those skip the fallback, the prompt screen below and the result.
iOS follows a universal link only from a tap. A return that starts on its own, such as right after the shopper closes Apple Pay, or in an app with no universal link set up, goes through the URL scheme, and Safari asks "Open this page in "Your App"?" first. While that prompt is on screen, the page dims and an arrow points at Open, with a caption: "Tap to go back to the app", or "You're all set." above it after a purchase, in the device's language. The dim goes as soon as the shopper answers. It only shows once the prompt is up, so a universal link that opens the app, or a browser that shows no prompt, never dims the page. The arrow and caption are drawn on portrait iPhones; on an iPad or in landscape the page dims without them.
returnToApp() and close() resolve how the return went:
| Result | What happened |
|---|---|
"opened" | The app came up, through the universal link or after the shopper tapped Open. |
"cancelled" | The shopper tapped Cancel on the prompt and is still on the page. |
"no_app" | Nothing opened it: the app has no return link, the app isn't installed, or the browser showed no prompt for its scheme. |
React to "cancelled" by keeping the shopper where they are, with a way to try again:
import { usePurchase, useTeleport } from "superwall/hooks";
const teleport = useTeleport();
const { purchase } = usePurchase();
const [stayed, setStayed] = React.useState(false);
const buy = async () => {
const { status } = await purchase("card");
if (status !== "abandoned") return;
const result = await teleport.returnToApp();
if (result !== "opened") setStayed(true);
};
return (
<>
<Button onPress={buy} disabled={teleport.returning}>Start free trial</Button>
{stayed ? <Button onPress={teleport.returnToApp}>Back to the app</Button> : null}
</>
);The second button returns from a tap, so the universal link opens the app with no prompt.
useTeleport().returning is true from the moment the page hands the shopper over until the result is in, for a button to disable or a screen of your own. router.back() returns the same way and resolves nothing. In the app, returnToApp() resolves "opened" at once, returning is always false, and close() closes the paywall and returns undefined.
An app that takes more than three seconds to come up after Open reads as "cancelled", so treat "cancelled" as "still here", not as a refusal.
Return to the app after a failed payment
A page can send the shopper back to the app when a payment fails, and the app learns why. Call returnToApp() from onFailure: after a failed payment the return link carries reason=failed, and the page leaves the app its failure, so you can test, for example, whether shoppers whose card is short on funds buy more often in the app:
import { usePurchase, useTeleport } from "superwall/hooks";
const teleport = useTeleport();
usePurchase({
onFailure: (failure) => {
if (teleport.status !== "arrived" || failure.reason !== "insufficient_funds") return;
void teleport.returnToApp({ data: { offer: "app_store" } });
},
});returnToApp() takes one optional object. data is plain JSON for the app, up to 16 KB: strings, numbers, booleans, null, and arrays and objects of them. Data over 16 KB is dropped with a console warning and the app still gets the failure. The page leaves nothing after a paid purchase, because the teleport has closed by then.
In the app, once the shopper is back, a "waiting" useTeleport() carries:
failure: why the page's payment failed, from the page's return, or from the teleport's status once the backend reports one. The page's own Apple Pay decline has its exact reason today; an embedded-sheet decline reads"unknown"until the backend reports why, see where reasons come from.data: what the page passed toreturnToApp({ data }).
onFailure on usePurchase fires in the app too, and usePurchase().failure holds the same failure. onReturnData fires once the app has read the data. Use them to offer another way to pay:
import { usePurchase, useTeleport } from "superwall/hooks";
const { purchase } = usePurchase();
const teleport = useTeleport({
onReturnData: (data) => console.log("data from the page", data),
});
if (teleport.status !== "waiting" || !teleport.failure) return null;
return (
<Sheet>
<p>
{teleport.failure.reason === "card_declined"
? "Your card was declined. Try Apple Pay instead."
: "The payment in the browser didn't go through."}
</p>
{teleport.data?.offer === "app_store" ? (
<Button onPress={() => purchase("annual")}>Buy in the App Store</Button>
) : null}
</Sheet>
);Each trip to the browser starts clean: the app ignores a failure or data left before the browser last opened. The failure and data reach the app through the teleport's own session on the backend, so this needs no newer iOS SDK than teleport itself.
Instant opening
Creating a teleport takes a round-trip, so it is done ahead of the tap. A paywall with teleport.route prepares that teleport when it opens: when the SDK presents it, never while it preloads in the background. Any paywall with teleport also asks Apple whether Apple Pay is available as it opens. The tap then opens the browser at once, carrying any answer that changed since. For a route you reach with router.push(route, { teleport: true }), prepare it yourself, as you would prefetch a checkout:
const { prefetch } = useTeleport();
React.useEffect(() => {
prefetch("plans");
}, [prefetch]);A prepared teleport stays usable for ten minutes, only for the route it was prepared for, and is made again when the trial offer changed since. A trial offer that changes while the browser is open moves the open checkout to it, in the same tab.
Options
teleport: true takes every default. The object form changes what you name:
| Key | Default | What it does |
|---|---|---|
route | none | The route that teleports by default: a push to it (unless the push says { teleport: false }), a Stripe purchase, and the teleport prepared when the paywall opens. It is also the route pre-rendered for a fast first paint. Without it, a Stripe purchase teleports the route it was tapped on, and only { teleport: true } teleports a push. |
overlay | true | Show the teleport screen in the app. false keeps the paywall as it is, for a flow that leaves midway (an onboarding that continues on the web), or for your own screen built with useTeleport(). The purchase is watched either way. |
fallbacks | none | A store product the teleport screen offers in place of a Stripe one, keyed by the Stripe product: { card: "annual" }. Both sides are typed against your products. Continue In-App Instead buys it through the App Store, and the Stripe purchase() resolves with that purchase. Shown only once the store has priced it. |
completion | "confirmation" | After a web purchase: "confirmation" shows "You're all set" with Return to App, "direct" opens the app at once, and shows "You're all set" when the shopper cancels or the app doesn't open. |
introductoryOfferEligibility | "automatic" | Whether the web checkout offers the trial: "automatic" when the App Store says the shopper is eligible, "eligible" always, "ineligible" never. The App Store's trial history doesn't bind a Stripe purchase, so this is separate from the paywall's own introductoryOfferEligibility. |
Your own teleport screen
The teleport screen and the "You're all set" screen are TeleportScreen, which the build mounts for any paywall with teleport. Set overlay: false and draw your own from useTeleport(). Its status turns "waiting" exactly when the built-in screen would go up (once the app is in the background, after a moment if it never is, or when the SDK asks just before it opens the browser), and stays "waiting" until the purchase settles, so your screen behaves like Superwall's. Once the shopper is back in the app, returned turns true while the purchase is checked one last time:
import { usePurchase, useTeleport } from "superwall/hooks";
const teleport = useTeleport();
const { purchase } = usePurchase();
if (teleport.status !== "waiting" || teleport.returned) return null;
const fallback = teleport.fallbackReference;
return (
<Sheet>
<p>Finish your purchase in Safari.</p>
<Button onPress={teleport.open}>Open Safari</Button>
{fallback ? <Button onPress={() => purchase(fallback)}>Pay with Apple instead</Button> : null}
<Button onPress={teleport.cancel}>Cancel</Button>
</Sheet>
);status is one of:
status | Where | Carries |
|---|---|---|
"idle" | anywhere | nothing |
"waiting" | in the app, while the shopper is in the browser | productReference, fallbackReference, returned, and once back, failure and data from the page, see Return to the app after a failed payment |
"arrived" | on the web page, before the purchase | productReference |
"completed" | on the web page, once paid | productReference, paidElsewhere (another checkout of the presentation was paid) |
Buying the fallback (or any store product) while the teleport is in flight hands it over: the Stripe purchase() resolves with the in-app purchase. On the web page, returnToApp() goes back and resolves how that went, see Returning to the app. To tell the teleport page from any other web page, read useDevice().host, which is "web-teleport" there.
To follow what happens, for example to count how often shoppers cancel, pass callbacks:
const [cancels, setCancels] = React.useState(0);
useTeleport({
onOpen: () => {}, // the browser opened, the first time or again
onReturn: () => {}, // the shopper came back to the app mid-purchase
onCancel: () => setCancels((n) => n + 1), // the shopper tapped Cancel
onComplete: () => {}, // paid on the web, being redeemed
onReturnData: (data) => {}, // the app read the data the page passed to returnToApp()
});onCancel is the Cancel button only. A teleport that ends unpaid any other way, the shopper back without paying or the checkout expired, resolves its purchase() as abandoned without calling onCancel.
Requirements and fallbacks
- SuperwallKit 4.18.0 or later. On an older SDK, and on Android, nothing teleports: the route is pushed in the app as usual, and a Stripe purchase opens Superwall's hosted checkout instead, see Web checkout.
- A web paywall domain on the project's Stripe app. Teleport is refused without one; the purchase resolves
failed. - The app's URL scheme (and its team and bundle id, for the universal link) on the dashboard, so the web page can open the app again. Without them the "You're all set" screen tells the shopper to go back on their own.
superwall devdoesn't teleport: a preview has no API key. Push and open the paywall from the app to try it.
Events from the web page
The web page reports what only it can see. Everything else in a teleport is reported by the app, so nothing is counted twice.
| Event | Sent by the web page when |
|---|---|
stripeCheckout_submit | The shopper submits a payment, with Apple Pay or the card sheet. |
stripeCheckout_fail | The payment fails, a declined card for example. |
stripeCheckout_abandon | The shopper closes the payment sheet without paying. Once for every close. |
| The placement's name | The page calls customPlacement(name, params). The params are the event's properties. |
These are recorded for the user who started the teleport, in the app it came from. In that user's events they sit between the app's teleport_open and teleport_return.
The app reports the rest:
paywall_openand the placement that presented the paywall;stripeCheckout_startandtransaction_start, when the shopper taps a Stripe product in the app;teleport_openandteleport_return;transaction_abandon, once, when the teleport ends unpaid: Cancel, back without paying, or the checkout expired. Closing the payment sheet on the web page is not atransaction_abandon, the shopper can still open it again and pay;stripeCheckout_completeandtransaction_complete, once it is paid.
Page views, attribute changes and close() on the web page are not recorded.
Custom placements on the web page
In the app, customPlacement fires a placement, which can present another paywall. On the web page it is only recorded: the page doesn't navigate and no other paywall opens, so the shopper stays in the checkout. That makes it the way to count anything the page shows.
To measure how many shoppers a last-chance drawer saves, record it when it opens:
import { useState } from "react";
import { useActions, usePurchase } from "superwall/hooks";
const { customPlacement } = useActions();
const { purchase } = usePurchase();
const [drawerOpen, setDrawerOpen] = useState(false);
const buy = async () => {
const result = await purchase("annual");
if (result.status === "abandoned") {
customPlacement("drawer_shown", { offer: "annual_discount" });
setDrawerOpen(true);
}
};A shopper who closes the sheet gets a stripeCheckout_abandon, then a drawer_shown with offer as a property. Those followed by a stripeCheckout_complete are the ones the drawer saved.
The same code runs in the app, where abandoned means the teleport was given up and customPlacement is a real placement. Use a name no campaign presents a paywall for, or fire it only when useTeleport().status is "arrived".
Attribution
A teleported purchase is attributed to the paywall the app showed, exactly as with the editor's checkout page: the presentation the SDK reported, its placement and experiment, and the shopper's identity and device, all recorded when the teleport is created. Checkouts opened on the web page inherit them from the teleport.
How is this guide?
Web Funnels
Quizzes and checkout funnels on the web: one paywall whose steps are pages, every answer kept in the URL so the flow survives any browser hand-off, and payment at the end.
Variables & Personalization
React to user attributes, device state, and placement parameters, and write paywalls the dashboard can experiment on without a rebuild.