Skip to main content
This guide takes you from nothing to a flow rendering in your iOS app. It touches every part of FlowPilot: the dashboard, the Flow Editor, a placement, and the iOS SDK. Plan for about 15 minutes.
New to FlowPilot? Read Core concepts first to learn the terms used throughout these docs.

​
Before you start

You need an Apple app you can run (a fresh Xcode project is fine) and access to the FlowPilot dashboard.

​
Steps

1

Create a workspace and app

Sign in to the dashboard and create a workspace (your organization), then create an app for your iOS target inside it. Note the App ID. The SDK needs it at launch.See Workspaces and apps.
2

Create an SDK API key

In the app’s settings, create an SDK API key. Copy it now, because it is shown only once. This key is different from your dashboard login. The SDK sends it as Authorization: Bearer <key> to the /v1 API.See API keys.
3

Build a flow and publish it

Open the Flow Editor, add a screen, and drop in a text component and a button. Give the button a closeFlow action so tapping it ends the flow. Then publish the flow to create a servable version. A draft is never served.See Your first screen and Publishing.
4

Create a placement and attach the flow

Create a placement with a key like onboarding. Set its default flow version to the one you just published, and make sure the placement targets the iOS platform.See Creating placements.
5

Add the SDK to your app

Add the FlowPilot Swift package to your Xcode project with Swift Package Manager.See Installation.
6

Configure the SDK at launch

Call FlowPilot.configure(_:) once at app launch with your API key and App ID.
import FlowPilotSDK

// In AppDelegate.application(_:didFinishLaunchingWithOptions:)
// or your App struct's init().
FlowPilot.configure(
    FlowPilotConfiguration(
        apiKey: "fp_live_xxxxxxxxxxxxxxxx",
        appId: "your-app-id"
    )
)
The environment defaults to .production. The SDK expects the API key to start with fp_. If it does not, configuration is skipped and an error is logged. See Configuration.
7

Present the placement

Ask the SDK to resolve and present your placement. Use the placement key from step 4.
import FlowPilotSDK
import UIKit

final class HomeViewController: UIViewController {
    func startOnboarding() {
        guard let flowPilot = FlowPilot.shared else { return }
        Task {
            do {
                let result = try await flowPilot.presentPlacement("onboarding", from: self)
                print("Flow finished: \(result.outcome)")
            } catch {
                print("FlowPilot could not present a flow: \(error)")
            }
        }
    }
}
See Presenting placements for results, options, and the never-throws fallback variant.
Run the app. The flow you published appears, and tapping the button closes it.

​
Common mistakes

  • Using a dashboard token instead of an SDK API key. The SDK authenticates against the /v1 API with Authorization: Bearer <sdk-key>. Your Clerk dashboard session will not work. Create an SDK key in the app settings.
  • App ID mismatch. The App ID passed to FlowPilotConfiguration must be the app that owns the placement. If they differ, the resolve returns no flow and nothing shows.
  • Placement key typo, paused placement, or no flow attached. The key in your code must match the placement key exactly. A paused placement, or one with no flow attached, resolves to nothing.
  • Forgetting to publish. A draft flow is not served. Publish a version and attach that version to the placement.

​
Troubleshooting

Nothing appears? Walk this checklist:
  1. Is the API key valid and an SDK key (it starts with fp_)?
  2. Is the App ID the one that owns the placement?
  3. Is the placement active (not paused) and targeting iOS?
  4. Is a published flow version attached to the placement?
  5. Is the placement key in your code an exact match?
  6. Is the device online? If it may be offline, configure a cache or bundled fallback.
Still stuck? See iOS troubleshooting.