Quickstart - FlowPilot

This guide takes you from nothing to a flow rendering in your app. It touches every part of FlowPilot: the dashboard, the Flow Editor, a placement, and a FlowPilot SDK. The dashboard steps are the same for everyone; the SDK steps have tabs for iOS (Swift) and Expo (React Native), so follow the tab that matches your app. 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 app you can run and access to the FlowPilot dashboard:

iOS: an Apple app you can run (a fresh Xcode project is fine).
Expo: a React Native app created with Expo (npx create-expo-app is fine), run on a simulator or device.

Steps

Create a workspace and app

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

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.

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.

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 platform your app runs on: select iOS for an iOS app, and add Android too if your Expo app ships there. The device’s platform must be in this list for the placement to resolve a flow.See Creating placements.

Add the SDK to your app

iOS
Expo

Add the FlowPilot Swift package to your Xcode project with Swift Package Manager.See iOS installation.

Install the package and its Expo peer dependencies, then add the Reanimated Babel plugin.

npm install @flowpilotjs/react-native-sdk

See Expo installation for the full peer-dependency list and Babel setup.

Configure the SDK at launch

Configure the SDK once at app launch with your API key and App ID.

iOS
Expo

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 iOS configuration.

import { FlowPilot } from '@flowpilotjs/react-native-sdk';

// At module load, or in your root component before any flow is presented.
FlowPilot.configure({
  apiKey: 'fp_live_xxxxxxxxxxxxxxxx',
  appId: 'your-app-id',
});

The environment defaults to 'production'. Unlike iOS, configure throws if the API key does not start with fp_ or the App ID is empty, so let that surface during development. See Expo configuration.

Present the placement

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

iOS (UIKit)
iOS (SwiftUI)
Expo

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 iOS: Presenting placements.

import FlowPilotSDK
import SwiftUI

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

    var body: some View {
        Color.clear
            .flowPresenter(session: $session) { result in
                print("Flow finished: \(result.outcome)")
            }
            .task {
                session = try? await FlowPilot.shared?.createSession(
                    placementKey: "onboarding"
                )
            }
    }
}

See iOS: SwiftUI.

On Expo you present declaratively: resolve a session, then render it with <FlowPilotPresenter />. resolveSession returns null (instead of throwing) when nothing is presentable.

import { useEffect, useState } from 'react';
import { useSafeAreaInsets } from 'react-native-safe-area-context';
import {
  FlowPilot,
  FlowPilotPresenter,
  type FlowSession,
} from '@flowpilotjs/react-native-sdk';

export function OnboardingGate() {
  const [session, setSession] = useState<FlowSession | null>(null);
  const insets = useSafeAreaInsets();

  useEffect(() => {
    FlowPilot.resolveSession('onboarding').then(setSession);
  }, []);

  return (
    <FlowPilotPresenter
      session={session}
      safeAreaInsets={insets}
      onComplete={({ outcome }) => {
        console.log('Flow finished:', outcome);
        setSession(null);
      }}
    />
  );
}

FlowPilot.presentPlacement() is deprecated on Expo and renders nothing; always use the presenter. See Expo: Presenting placements.

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 you pass when configuring the SDK 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:

Is the API key valid and an SDK key (it starts with fp_)?
Is the App ID the one that owns the placement?
Is the placement active (not paused) and targeting your app’s platform (iOS, or Android for an Expo app there)?
Is a published flow version attached to the placement?
Is the placement key in your code an exact match?
Is the device online? If it may be offline, configure a cache or bundled fallback.

Still stuck? See iOS troubleshooting or Expo troubleshooting.

​Before you start

​Steps

​Common mistakes

​Troubleshooting

​Related pages

Before you start

Steps

Common mistakes

Troubleshooting

Related pages