Optimize flow & paywall fetching in React Native SDK

A reliable flow or paywall fetch on React Native 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 React Native SDK.

Rules and pitfalls

Do this	Don’t do this	Why
Fetch the placement you’re about to show.	Prefetch all placements concurrently on launch.	Bulk prefetch blocks the JS thread and produces a black screen during the burst.
Fetch `getFlow` after attribution has had a chance to resolve — for example, 1–2 seconds after `activate` or after `onLatestProfileLoad` fires.	Call `getFlow` at the root component mount.	Attribution hasn’t landed yet. The flow resolves against the default audience and silently bypasses segments and ASA personalization.
Set a `loadTimeoutMs` 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 paywalls and products for the fetchPolicy and loadTimeoutMs parameter reference, and Placements for picking the right placement.

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.

In the Flow & Paywall Builder, set a custom media ID on the image or video. The file you upload there stays as the fallback.
Add the file to the native projects: the iOS app bundle and the Android assets folder.
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
const bundledAssets: Record<string, AdaptyCustomAsset> = {
  'welcome_video': {
    type: 'video',
    fileLocation: {
      ios: { fileName: 'welcome.mp4' },
      android: { relativeAssetPath: 'videos/welcome.mp4' },
    },
  },
};

const view = await createFlowView(flow, { customAssets: bundledAssets });

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: 'return_cache_data_else_load' on every fetch except the very first.
Configure a fallback paywall for every placement in the Adapty dashboard.
Set loadTimeoutMs 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.