Configuration

Basic setup

Call FlwKit.configure() once at app startup. Place it in your @main App init() or AppDelegate.application(_:didFinishLaunchingWithOptions:) — before any view appears.

import SwiftUI
import FlwKit_ios
 
@main
struct MyApp: App {
    init() {
        FlwKit.configure(apiKey: "your-api-key")
    }
 
    var body: some Scene {
        WindowGroup {
            ContentView()
        }
    }
}

configure() triggers a background prefetch of the active flow immediately. By the time a user reaches FlwKitFlowView, the flow is typically already cached and renders with no loading state.

FlwKit.configure()

public static func configure(
    apiKey: String,
    userId: String? = nil,
    baseURL: String? = nil
)

Parameter	Type	Required	Default	Description
`apiKey`	`String`	Yes	—	Your app's API key from the dashboard.
`userId`	`String?`	No	`nil`	Stable identifier for the current user. Used to tie analytics events and A/B test assignments to a specific user. Pass `nil` to use an anonymous session.
`baseURL`	`String?`	No	`https://api.flwkit.com`	Override the API base URL. Only needed when self-hosting the FlwKit backend.

FlwKitFlowView

Add FlwKitFlowView to any SwiftUI view. The active flow is fetched automatically.

// Minimal
FlwKitFlowView()
 
// With completion handler
FlwKitFlowView { result in
    // navigate away
}
 
// Full control
FlwKitFlowView(
    attributes: ["plan": "pro"],
    onComplete: { result in },
    onExit: { }
)

Parameter	Type	Required	Default	Description
`attributes`	`[String: Any]`	No	`[:]`	Key-value data passed into the flow. Accessible in conditional transitions via `attributes.{key}`.
`onComplete`	`((FlwKitCompletionResult) -> Void)?`	No	`nil`	Called when the flow reaches a terminal `complete` action.
`onExit`	`(() -> Void)?`	No	`nil`	Called when the user exits mid-flow.

FlwKitCompletionResult

Property	Type	Description
`flowId`	`String`	The flow key identifier.
`variantId`	`String?`	A/B test variant ID, or `nil` if the user was not in a test.
`completedAt`	`Date`	Timestamp of completion.
`answers`	`[String: Any]`	All answers keyed by block `key`. Choice answers are mapped to option labels, not raw values.

FlwKit.present() — UIKit

Use FlwKit.present() to get the flow view programmatically and embed it in a UIHostingController.

FlwKit.present(
    attributes: [:],
    onComplete: { result in
        DispatchQueue.main.async { self.dismiss(animated: true) }
    },
    completion: { result in
        switch result {
        case .success(let flowView):
            let host = UIHostingController(rootView: flowView)
            host.modalPresentationStyle = .fullScreen
            self.present(host, animated: true)
        case .failure(let error):
            print(error.localizedDescription)
        }
    }
)

Parameter	Type	Required	Default	Description
`attributes`	`[String: Any]`	No	`[:]`	Same as `FlwKitFlowView.attributes`.
`onComplete`	`(FlwKitCompletionResult) -> Void`	No	no-op	Same as `FlwKitFlowView.onComplete`.
`onExit`	`(() -> Void)?`	No	`nil`	Same as `FlwKitFlowView.onExit`.
`completion`	`(Result<AnyView, Error>) -> Void`	Yes	—	Receives the flow view or an error.

Error handling

All errors conform to LocalizedError. Check error.localizedDescription for a human-readable message.

When flowNotFound or a network error occurs, the SDK automatically falls back to the most recently cached flow. The error is only surfaced if no cache exists.

Caching

The SDK caches the active flow in UserDefaults after the first successful fetch.

Situation	Behavior
Cache exists on launch	Flow renders immediately; cache refreshes in the background.
No cache, network available	Flow fetches with a loading indicator.
No cache, network unavailable	`FlwKitFlowView` shows an error state with a retry button.

User progress (current screen and answers) is also persisted and restored automatically if the user closes the app mid-flow.

Permission blocks setup (iOS)

Permission blocks trigger native Apple permission prompts from the host app.
If required app configuration is missing, iOS will not show the prompt.

Required setup by block type

Block type	Required Info.plist key(s)	Additional project setup
`notification_permission`	None required by Apple for the prompt call	None
`health_permission`	`NSHealthShareUsageDescription`	Enable HealthKit capability on your app target
`tracking_permission`	`NSUserTrackingUsageDescription`	iOS 14+ only. Prompt appears once per app install
`camera_permission`	`NSCameraUsageDescription`	None
`location_permission`	`NSLocationWhenInUseUsageDescription`	None (for when-in-use flow)
`microphone_permission`	`NSMicrophoneUsageDescription`	None
`photo_library_permission`	`NSPhotoLibraryUsageDescription`	None

Example Info.plist entries

<key>NSHealthShareUsageDescription</key>
<string>We use Health data to personalize your onboarding experience.</string>
<key>NSUserTrackingUsageDescription</key>
<string>We use anonymous data to improve content relevance.</string>
<key>NSCameraUsageDescription</key>
<string>We use your camera for profile photos and scan flows.</string>
<key>NSLocationWhenInUseUsageDescription</key>
<string>We use your location to personalize recommendations.</string>
<key>NSMicrophoneUsageDescription</key>
<string>We use your microphone for voice input blocks.</string>
<key>NSPhotoLibraryUsageDescription</key>
<string>We use your photo library so you can select images.</string>

Important behavior

Apple shows each permission prompt at most once unless the app is reinstalled.
If a user already denied permission, guide them to Settings → Your App to enable it manually.
For tracking_permission, iOS returns current status immediately when already decided (no second popup).
For health_permission, missing HealthKit capability prevents the system prompt from appearing.

Configuration

Basic setup

FlwKit.configure()

FlwKitFlowView

FlwKitCompletionResult

FlwKit.present() — UIKit

Error handling

Caching

Permission blocks setup (iOS)

Required setup by block type

Example Info.plist entries

Important behavior

Next steps

Blocks

Quickstart

On this page

Configuration

FlwKitError cases

Blocks

Quickstart

On this page