In Adapty, a flow combines an onboarding and a paywall into a single entity behind one placement. A flow replaces the separate onboarding and paywall that you build and serve on their own today.

This guide explains what changes when you move to flows and how to roll the change out without disrupting users on older app versions.

Flows vs. onboardings and paywalls

With separate onboardings and paywalls, you maintain two builders and two placements. You also hand users off from the onboarding to the paywall in your own code.

A flow replaces both with one experience — intro screens, a quiz, and the purchase screen — built in one editor and served from one placement.

The table below compares what each option gives you:

	Flow	Paywall Builder paywall	Onboarding
Multiple screens	Yes	No — single screen	Yes
Rendering	Native	Native	WebView
Products and placement	One placement; you add products directly to the flow	One placement; you add products directly to the paywall	One placement, but no products of its own — to sell, you create a separate paywall and serve it from its own placement

Should you migrate?

Your existing onboardings and paywalls keep working, and Adapty continues to support them. New features, however, now ship to flows rather than to the standalone onboarding and paywall builders.

If you’re building for the long term, flows are the better foundation — migrate to them when it fits your release schedule.

How to migrate

The migration has four steps. Most of the effort is a one-time SDK upgrade — building and previewing the flow is no-code.

1. Build your flow: Create a flow in the no-code editor; no developer needed.
2. Preview on device: Check the flow on a real device through the Adapty mobile app; no app build needed.
3. Create a new placement for your flow: Create a new flow placement with its own unique ID, and decide how it coexists with your existing placements.
4. Update the SDK: Upgrade to iOS SDK v4, fetch the flow from its placement, and verify a sandbox purchase. This is the main developer task.

Build your flow

On the Flows page, click Create flow to start building, recreating your onboarding and paywall as one experience. To learn more about the builder:

• Flows documentation: Walks you through the builder and what you can create.
• Common flow recipes: Step-by-step guides for the most common screens.
• Ask AI: Use the chat on any docs page when you get stuck.

Preview on device

You can preview the flow on a real device without touching the app. Download the Adapty app from the App Store. Then, in the flow builder, click Test on device, choose a locale, and scan the QR code with your device. This shows the real screens, branching, copy, and design.

Create a new placement for your flow

A placement serves one type of content only — a flow, a paywall, or an onboarding. You cannot convert an existing onboarding or paywall placement into a flow placement (see placement types). A flow needs its own new placement.

Give the new flow placement a completely new, unique placement ID. It can’t match or reuse the ID of an existing paywall or onboarding placement.

You don’t have to move every location to flows at once. In iOS SDK v4, the getFlow method fetches from both flow placements and paywall placements, so your app calls the same method everywhere. Keep Paywall Builder paywalls in the placements where you want them, and use flows in the rest.

During the transition, each placement type tracks its own metrics. While both old and new app versions are live, your data splits across two sets of placements. The old onboarding and paywall placements cover older versions; the new flow placement covers SDK v4+. Compare these as separate cohorts, and expect the flow placement’s share to grow as users update.

You can keep A/B testing with flows: run a Regular A/B test across flow variants on a flow placement. Crossplacement A/B tests are currently available only for paywalls, so you can’t run one across flow placements yet. Comparing a new flow against your old paywall is a cohort comparison, not a single test — they live on different placement types.

Update the SDK

With your flow placement ready, point the app at it. Flows render only on the Adapty SDK v4 and later. Upgrade the SDK and fetch the flow from your new placement with getFlow(placementId:). See the iOS SDK v4 migration guide for specific upgrade steps.

Once the flow is wired in, verify it like any other purchase flow: run it on a device or simulator and make a sandbox purchase to confirm that products, the purchase, and the access level all work.