Media preloading

​

Turning preloading on or off

// Override for a single SwiftUI session.
let session = try await FlowPilot.shared?.createSession(
    placementKey: "onboarding",
    preloadMedia: true
)

​

Observing progress

• waitForMediaPreload() is async and suspends until preloading completes. Awaiting it does not block a thread, it suspends the calling task. Use it to gate a present on a fully preloaded flow.
• cancelMediaPreload() stops an in-progress preload, for example if the user navigates away before you present.

​

Example

​

Gate the present on a fully preloaded flow

import FlowPilotSDK

func presentOnboarding(from viewController: UIViewController) {
    Task {
        guard let session = await FlowPilot.shared?.resolveSession(placementKey: "onboarding") else {
            // Nothing to present (see error handling / host fallback).
            return
        }

        // Suspend (does not block) until images are ready.
        await session.waitForMediaPreload()

        let host = FlowHostingController(session: session)
        viewController.present(host, animated: true)
    }
}

​

Show a loading bar bound to progress (SwiftUI)

import SwiftUI
import FlowPilotSDK

struct OnboardingGate: View {
    @State private var session: FlowSession?

    var body: some View {
        Group {
            if let session {
                PreloadGate(session: session)
            } else {
                ProgressView("Preparing...")
            }
        }
        .task {
            session = await FlowPilot.shared?.resolveSession(placementKey: "onboarding")
        }
    }
}

private struct PreloadGate: View {
    @ObservedObject var session: FlowSession

    var body: some View {
        if session.isMediaPreloaded {
            FlowPresenterView(session: session)
        } else {
            VStack(spacing: 12) {
                ProgressView(value: session.mediaPreloadProgress)
                Text("\(Int(session.mediaPreloadProgress * 100))%")
                    .font(.caption)
                    .foregroundStyle(.secondary)
            }
            .padding()
        }
    }
}

​

Notes

• Preloading is in screen order. Images on the first screen download first, then the second, and so on. Persistent zones (navigation bar, footer, overlay) are highest priority because they show on every screen. So even a partial preload covers what the user sees first.
• It only covers images. The preloader downloads image content. It does not preload Lottie animations or other media types.
• Gating is a trade-off. Waiting for a full preload means a short, predictable delay before the flow appears, in exchange for no spinners during the flow. Not gating means the flow appears immediately and the last screens may still be loading. Pick per placement.
• Prefetch is related but separate. A bare prefetch warms the resolved-flow cache and fonts, not images; this media preloader runs at session creation or present time. They are complementary. You can also warm images ahead of time with prefetch(_:warmMedia: true) or prefetchOnLaunch (bounded by prefetchMediaStrategy), which uses this same image cache, so a placement warmed that way shows its first screen with no pop-in.

​

Common mistakes

• Blocking the main thread to wait. Do not spin on isMediaPreloaded in a loop or run preloading synchronously on the main actor. Use await session.waitForMediaPreload() (which suspends, not blocks) or observe mediaPreloadProgress from SwiftUI.
• Gating heavy media on cellular. A flow with many large images can be slow to fully preload on a cellular connection. If you gate the present, the user waits. Consider not gating, or trimming media, for flows that run on first launch.
• Assuming isMediaPreloaded means success. It flips to true when preloading finishes, even if some images failed to download. A failed image simply loads (or retries) on demand later; it does not block the flow.
• Recreating the session to retry preloading. Preloading starts once per session at creation. To re-run it, create a new session rather than calling preload methods again.

​

Troubleshooting

​

Related pages

• Caching
• Offline and bundled flows
• Prefetching and readiness
• SwiftUI integration
• Configuration