Optimize flow & paywall fetching in Flutter SDK

A reliable flow or paywall fetch on Flutter does three things: renders fast, returns the audience-targeted variation, and falls back gracefully when the network is slow. The rules below cover the timing, caching, and fallback patterns to get there.

Tip

The rules assume Adapty().activate() and Adapty().identify() have already resolved. See Call order in Flutter SDK.

Rules and pitfalls

Do thisDon’t do thisWhy
Fetch the placement you’re about to show, or warm the cache with preloadFlows (SDK 4.3.0+).Fan out your own concurrent getFlow calls on launch.A hand-rolled prefetch burst blocks the main thread and produces a black screen. preloadFlows is built for this and sends the batch to the native SDK in one call.
Fetch getFlow after attribution has had a chance to resolve — for example, 1–2 seconds after activate or after didUpdateProfileStream fires.Call getFlow in main() before runApp.Attribution hasn’t landed yet. The flow resolves against the default audience and silently bypasses segments and ASA personalization.
Set a loadTimeout and configure a fallback paywall for every placement.Wait on getFlow indefinitely.Without a timeout, users on poor connectivity see a blank screen until the network resolves — or close the app.

See Fetch custom paywalls and products for the fetchPolicy and loadTimeout parameter reference, and Placements for picking the right placement.

Preload placements

Info

preloadFlows and preloadFlowsForDefaultAudience are available starting from SDK version 4.3.0.

preloadFlows caches the flow JSON ahead of time. You then use it as usual: getFlow for the flow, createFlowView for its view.

fetchPolicy decides which layer a later getFlow reads first, not whether it can reach the cache at all:

  • AdaptyFlowFetchPolicy.returnCacheDataElseLoad reads the preloaded copy first and goes to the network only when nothing is cached. AdaptyFlowFetchPolicy.returnCacheDataIfNotExpiredElseLoad(maxAge) does the same while the copy is younger than maxAge.
  • The default, AdaptyFlowFetchPolicy.reloadRevalidatingCacheData, goes to the network first and falls back to the preloaded copy when the request fails or times out.

A preload pays off either way, but differently: a cache-first policy removes the request, while the default keeps it and gains a warm copy to fall back on. On a test device, getFlow skips the cache with every policy and uses the preloaded copy only if the network request fails.

Use it when you know which placements the session will need but don’t want to show them yet — for example, right after activate and identify complete, for the flow behind a button the user hasn’t tapped.

try {
  await Adapty().preloadFlows(
    placementIds: ['onboarding', 'main_paywall'],
    loadTimeout: const Duration(seconds: 5),
  );
} on AdaptyError catch (adaptyError) {
  // at least one placement failed to preload
}

// Later, when the user reaches the paywall:
final flow = await Adapty().getFlow(
  placementId: 'main_paywall',
  fetchPolicy: AdaptyFlowFetchPolicy.returnCacheDataElseLoad,
);

Parameters:

  • placementIds (required): the placements to preload.
  • loadTimeout (optional): how long the preload waits for the audience-targeted flows. Defaults to 5 seconds, and values below 1 second are raised to 1 second. When the timeout is reached, the SDK can load the default-audience flows instead.

Behavior worth knowing:

  • The call fails only after every placement has been attempted, with one AdaptyError that covers all failed placements. A failure for one placement doesn’t stop the others, and the placements that loaded stay in the cache.
  • Preloading always goes to the network: it has no fetchPolicy of its own.
  • Preloading only warms the cache. It doesn’t return content — you still call getFlow to display it.

What a preload covers

A flow reaches the screen in layers. A preload covers the first, exactly as getFlow does:

LayerFetched byWarmed by a preload
Flow JSON — the chosen variation, its product IDs, and the remote configgetFlowYes
UI layout — the screen’s structure, styling, and textcreateFlowViewNo
Images, including the still frame that stands in for a video elementcreateFlowView, in the backgroundNo
ProductscreateFlowView or getPaywallProductsNo
Video filesThe system player, as the screen rendersNot cached by the SDK

So the first createFlowView for a given layout still costs a round trip after a preload. The native SDK then keeps that layout in its disk cache, which survives app restarts, so the cost falls on the first request rather than on every one.

Skip audience segmentation

To warm the cache without waiting for audience segmentation at all, use the default-audience variant. It takes no timeout:

await Adapty().preloadFlowsForDefaultAudience(placementIds: ['main_paywall']);

A later getFlowForDefaultAudience reads the copy the same way getFlow reads a preloadFlows copy.

Show first-screen media from the app bundle

A flow downloads its images and videos from Adapty. To show the first screen’s media instantly, serve it from the app bundle instead. This is a good way to reuse media you already ship, such as the visuals of an existing native onboarding.

  1. In the Flow & Paywall Builder, set a custom media ID on the image or video. The file you upload there stays as the fallback.
  2. Add the file to your Flutter assets and list it under assets in pubspec.yaml.
  3. When you create the flow view, pass the bundled file for that ID in customAssets:
// "welcome_video" is the custom media ID set in the Flow & Paywall Builder
final bundledAssets = {
  'welcome_video': AdaptyCustomAsset.localVideoAsset(
    assetId: 'assets/videos/welcome.mp4',
  ),
};

try {
  final view = await AdaptyUI().createFlowView(
    flow: flow,
    customAssets: bundledAssets,
  );
} on AdaptyError catch (e) {
  // handle the error
}

Bundled files add to your app’s download size, so bundle only the media users see first.

Media you don’t bundle still appears right away: the flow’s layout includes a small low-resolution copy of each image, including a video’s still frame, and shows it until the full file loads.

For the full customAssets reference, see Customize assets.

Tune for poor connectivity

For markets with consistently poor connectivity (rural areas, transit, regions affected by routing):

  • Set fetchPolicy: AdaptyFlowFetchPolicy.returnCacheDataElseLoad on every fetch except the very first.
  • Configure a fallback paywall for every placement in the Adapty dashboard.
  • Set loadTimeout to 3–5 seconds and accept the fallback when the timeout fires.
  • Don’t gate flow display on getProfile(). Call getFlow independently so a slow profile doesn’t block the UI.