Migrate to flows

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.

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. That placement is a new one: a flow is its own content type, so it can’t run on the onboarding or paywall placement it replaces.

The table below compares what each option gives you:

Should you migrate?

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: Convert an existing paywall in one click, or create a flow from a template; 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 the Adapty SDK v4, fetch the flow from its placement, and verify a sandbox purchase. This is the main developer task.

Build your flow

If your paywall was built in the legacy Paywall Builder, convert it rather than rebuilding it. The Move to new builder action recreates it as a draft flow in one click — layout, copy in every locale, and products with prices as variables — and your original stays live while you edit and test. See Convert a paywall into a flow.

To build something new instead, pick the route that fits:

• Start from a template: A starter template or a blank flow in the Flow & Paywall Builder, with no code.
• Use the agent skill: Your own AI coding tool authors and edits flows from the terminal — useful for quizzes, branching, and adding locales in bulk.

Reference while you build:

• Flow & Paywall Builder 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 mobile app for iOS or Android. Then, in the Flow & Paywall 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

Flows, paywalls, and onboardings are three different content types, and each of them is measured with its own metric set — which is why a placement serves one type only. A placement’s type is fixed when you create it, so there’s no way to convert an existing onboarding or paywall placement into a flow placement (see placement types). Every flow you serve needs a new placement of its own.

You don’t have to move every location to flows at once. In 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.

Create the placements with an agent skill

With more than a handful of placements to move, the migrate-placements skill creates them from your own AI coding tool instead. It reads every placement in your app through the Adapty CLI, groups them by the paywall each one serves, asks per paywall where the flow comes from, then creates one flow placement per paywall placement in scope and hands back the old-to-new ID mapping and the getFlow call your app has to ship.

Your paywall placements are read and never edited, so they keep serving while you work, and every placement ID the skill proposes waits for your approval.

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. See the v4 migration guide for your platform — iOS, Android, React Native, Flutter, Unity, Kotlin Multiplatform, or Capacitor — 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. See the testing guide for your platform: iOS, Android, React Native, Flutter, Unity, Kotlin Multiplatform, or Capacitor.