Expo quickstart - FlowPilot

This is the shortest path from an installed SDK to a flow on screen: configure at launch, present a placement, then read the result. It assumes you already have a published flow attached to a placement (the Quickstart walks through building that end to end).

Before you startYou need:

A FlowPilot workspace.
An app inside that workspace.
An SDK API key for that app.

You also need:

The SDK installed in your Expo app, with its peer dependencies and the Reanimated Babel plugin.
A placement key (for example onboarding) with a published flow attached.

Steps

Configure at launch

Call FlowPilot.configure(...) once, as early as possible, with your API key and App ID. See Configuration for every option.

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

FlowPilot.configure({
  apiKey: 'fp_live_xxxxxxxxxxxxxxxx',
  appId: 'your-app-id',
});

Present a placement

Pick the path that fits how you present UI.

Imperative (modal)
Declarative (component)

presentPlacement opens a full-screen modal and resolves a promise with the outcome once the user finishes or dismisses. It never throws for predictable failures, it returns an error outcome instead.

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

async function startOnboarding() {
  const result = await FlowPilot.presentPlacement('onboarding');

  switch (result.outcome) {
    case 'completed':
      // The user finished the flow.
      break;
    case 'dismissed':
      // The user closed the flow early.
      break;
    case 'error':
      console.warn('Flow failed:', result.error?.message);
      break;
  }
}

Build a FlowSession with createSession, then render it with <FlowPilotPresenter />. This gives you safe-area control and lets you embed the flow in your own tree.

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(() => {
    let cancelled = false;
    FlowPilot.createSession('onboarding').then((s) => {
      if (cancelled) return;
      setSession(s);
      s.start();
    });
    return () => {
      cancelled = true;
    };
  }, []);

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

Read the result

Both paths hand you a result with an outcome of 'completed', 'dismissed', or 'error'. Switch on it to decide what to do next.

function handle(result: { outcome: string; error?: Error }) {
  switch (result.outcome) {
    case 'completed':
      // The user finished the flow.
      break;
    case 'dismissed':
      // The user closed the flow before finishing.
      break;
    case 'error':
      // FlowPilot had nothing to present, or rendering failed.
      console.warn(result.error?.message);
      break;
  }
}

See Results and outcomes for the full shape and how to read final variables and experiment assignments.

That is the full loop: configure, present, read the result. For the host fallback, prefetching, custom components, and offline support in depth, see the pages below.

Common mistakes

Using a dashboard token instead of an SDK API key. The SDK authenticates with an SDK key that starts with fp_. Your dashboard login will not work. Create an SDK key in app settings.
App ID mismatch. The appId you configure must own the placement, or the resolve returns no flow.
Placement key typo, paused placement, or no flow attached. The key in code must match the placement key exactly, the placement must be active, and a published flow must be attached.
Forgetting to publish. A draft flow is never served. Publish a version and attach it to the placement.
Calling presentPlacement before configure. It throws SDK_NOT_INITIALIZED (surfaced as an error outcome). Configure first.

Troubleshooting

Nothing appears? Walk this checklist:

Is the API key an SDK key (it starts with fp_) and valid for the environment you configured?
Is the App ID the one that owns the placement?
Is the placement active (not paused) and targeting your platform?
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 caching or a bundled fallback.

Set logLevel: 'debug' in configure to see each resolve and why a flow was rejected. Still stuck? See Troubleshooting.

​Steps

​Common mistakes

​Troubleshooting

​Related pages

Steps

Common mistakes

Troubleshooting

Related pages