> ## Documentation Index
> Fetch the complete documentation index at: https://docs.getflowpilot.io/llms.txt
> Use this file to discover all available pages before exploring further.

# API reference

> The public exports of the FlowPilot Expo SDK, grouped by area, with links to the guide pages that show usage.

This is the lookup reference for `@flowpilotjs/react-native-sdk`. Every symbol here is exported from the package's entry point. The guide pages (Getting started through Offline and performance) teach how to use them in context; this page is the index.

<Note>
  This reference targets the current published **FlowPilot Expo SDK** (1.0.x) on npm. Public exports can change between versions, so check the installed package version (and `FlowPilot.sdkVersion`) if a signature here does not match.
</Note>

## Setup

`FlowPilot` is a singleton instance. Configure it once, then call methods on the same import.

```ts theme={null}
import { FlowPilot } from '@flowpilotjs/react-native-sdk';

// Validate and apply configuration. Throws on an invalid API key or empty App ID.
FlowPilot.configure(config: FlowPilotConfiguration): void

FlowPilot.isConfigured: boolean   // getter: true after a successful configure
FlowPilot.sdkVersion: string      // getter: the SDK version string

// Identity. See Variables and context.
FlowPilot.identify(userId: string): void   // tie events to your account id (mirrors iOS)
FlowPilot.reset(): Promise<void>           // clear identity on logout; fresh anonymous id
```

### `FlowPilotConfiguration`

Only `apiKey` and `appId` are required; everything else has a default.

| Field                      | Type                                               | Default         | Notes                                                                                                                                                         |
| -------------------------- | -------------------------------------------------- | --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `apiKey`                   | `string`                                           | required        | Workspace SDK key. Must start with `fp_`.                                                                                                                     |
| `appId`                    | `string`                                           | required        | The app's FlowPilot App ID.                                                                                                                                   |
| `environment`              | `EnvironmentConfig`                                | `'production'`  | Backend + default cache TTL.                                                                                                                                  |
| `context`                  | `Record<string, unknown>`                          | `undefined`     | Initial SDK context for variable resolution and targeting.                                                                                                    |
| `cachingEnabled`           | `boolean`                                          | `true`          | In-memory + on-disk flow cache.                                                                                                                               |
| `mediaPreloadingEnabled`   | `boolean`                                          | `true`          | Preload images in screen order on session create.                                                                                                             |
| `resolveTimeout`           | `number` (seconds)                                 | `4`             | Hard deadline for a live resolve. Floored at `0.5`.                                                                                                           |
| `prefetchOnLaunch`         | `string[]`                                         | `[]`            | Placement keys to warm in the background after `configure`.                                                                                                   |
| `prefetchMediaStrategy`    | `PrefetchMediaStrategy`                            | `'firstScreen'` | How aggressively launch prefetch warms images.                                                                                                                |
| `resolveNoFallbackTimeout` | `number` (seconds)                                 | `12`            | Extended resolve deadline used only when fresh + stale cache miss **and** no bundled default exists. Floored at `resolveTimeout`; set at/below it to disable. |
| `bundledFlows`             | `Record<string, object \| (() => object \| null)>` | `{}`            | Offline default flows by placement key.                                                                                                                       |
| `bundledFlowAssets`        | `Record<string, BundledFlowAssets>`                | `{}`            | Offline image/icon/font bundles by placement key.                                                                                                             |
| `logLevel`                 | `LogLevel`                                         | `'info'`        | Console log verbosity.                                                                                                                                        |
| `disableErrorReporting`    | `boolean`                                          | `false`         | Opt out of FlowPilot's scoped internal error reporting.                                                                                                       |

```ts theme={null}
type EnvironmentConfig = 'development' | 'staging' | 'production' | { baseUrl: string };
type PrefetchMediaStrategy = 'none' | 'firstScreen' | 'allScreens';
type LogLevel = 'none' | 'error' | 'warn' | 'info' | 'debug' | 'verbose';
```

See [Configuration](/expo-sdk/configuration).

## Presenting

Methods on `FlowPilot`. See [Presenting placements](/expo-sdk/presenting-placements) and [Prefetching](/expo-sdk/prefetching).

```ts theme={null}
// Non-throwing resolver. Returns null when nothing is presentable. Recommended.
resolveSession(placementId: string): Promise<FlowSession | null>

// Resolve and return an unstarted session. Rejects when nothing is presentable.
createSession(placementId: string): Promise<FlowSession>

// DEPRECATED on Expo: renders NO UI (no global host). Returns an error result
// immediately. Use resolveSession/createSession + <FlowPilotPresenter>.
presentPlacement(placementId: string): Promise<FlowPresentationResult>

// Build a session from raw flow JSON (preview/testing). No SDK config / network.
createSessionFromSchema(
  schema: FlowDefinition,
  options?: { suppressAnalytics?: boolean; mediaBaseUrl?: string; iconBaseUrl?: string },
): FlowSession

// True if a presentable flow is available now (warms the cache as a side effect).
isPlacementReady(placementKey: string): Promise<boolean>

// Warm one or more placements. Best-effort, concurrent, never rejects.
prefetch(
  placementIds: string[],
  options?: { warmMedia?: boolean },
): Promise<Record<string, PrefetchOutcome>>
```

### `PrefetchOutcome`

```ts theme={null}
type PrefetchState =
  | { type: 'warmed' }
  | { type: 'noFlow' }
  | { type: 'failed'; error: Error };

interface PrefetchOutcome {
  placementKey: string;
  state: PrefetchState;
  mediaWarmed: boolean;
  isWarmed: boolean;
}
```

## Components

How a session becomes on-screen UI. See [Presenting placements](/expo-sdk/presenting-placements).

```tsx theme={null}
// Full-screen modal presenter (FlowPresenter wrapped in a Modal).
function FlowPilotPresenter(props: FlowPilotPresenterProps): JSX.Element

interface FlowPilotPresenterProps {
  session: FlowSession | null;
  onComplete?: (result: FlowPresentationResult) => void;
  safeAreaInsets?: { top: number; bottom: number; left: number; right: number };
  animationType?: 'none' | 'slide' | 'fade';                                   // default 'slide'
  presentationStyle?: 'fullScreen' | 'pageSheet' | 'formSheet' | 'overFullScreen'; // default 'fullScreen'
  statusBarStyle?: 'default' | 'light-content' | 'dark-content';
  fallback?: React.ReactNode | (() => React.ReactNode);
  onError?: (error: Error) => void;
}

// Lower-level renderer (no Modal wrapper), for custom embedding.
function FlowPresenter(props: FlowPresenterProps): JSX.Element
```

## Session

`FlowSession` is the live handle to a presented flow. See [Results and outcomes](/expo-sdk/results-and-outcomes).

```ts theme={null}
class FlowSession {
  // Read-only state
  readonly placementId: string;
  readonly resolveResponse: ResolveResponse;
  readonly variableStore: VariableStore;
  readonly actionExecutor: ActionExecutor;
  readonly analyticsBatcher: AnalyticsBatcher;
  readonly mediaBaseUrl: string;
  readonly iconBaseUrl: string;
  suppressAnalytics: boolean;

  get flow(): FlowDefinition;
  get navigationController(): NavigationController;
  get state(): FlowSessionState;            // 'idle'|'loading'|'active'|'completed'|'error'
  get currentScreen(): ScreenNode | null;
  get isFlowClosed(): boolean;

  // Lifecycle
  setDelegate(delegate: FlowSessionDelegate): void;
  start(): void;
  dismiss(): void;
  failPresentation(): void;
  reset(): void;
  replaceFlow(newDefinition: FlowDefinition, fonts?: FontFile[]): Promise<void>;

  // Conversions
  trackConversion(amount: number, currency: string, productId?: string, metadata?: Record<string, unknown>): void;
}
```

### Results and lifecycle types

```ts theme={null}
interface FlowPresentationResult {
  outcome: 'completed' | 'dismissed' | 'error';
  error?: Error;
}

type FlowOutcome = 'completed' | 'dismissed' | 'error';
type FlowSessionState = 'idle' | 'loading' | 'active' | 'completed' | 'error';

type FlowSessionDelegate = {
  onScreenChange(screen: ScreenNode, transition: TransitionConfig, direction: 'forward' | 'back'): void;
  onFlowComplete(outcome: FlowOutcome): void;
  onStateChange(state: FlowSessionState): void;
};
```

## Variables

See [Variables and context](/expo-sdk/variables-and-context).

```ts theme={null}
type VariableValue = string | number | boolean | string[] | number[] | boolean[];
type VariableTypeName = 'string' | 'number' | 'boolean' | 'list';

interface FlowVariable {
  key: string;
  label?: string;
  type: VariableTypeName;
  listItemType?: 'string' | 'number' | 'boolean';
  scope: 'global';
  lifecycle: 'static' | 'session';
  source: { kind: 'constant'; value: VariableValue } | { kind: 'sdk'; path: string };
  writable: boolean;
  defaultValue?: VariableValue;
}

// Reactive store on each session (advanced).
class VariableStore {
  get(key: string): VariableValue | undefined;
  getByLabelOrKey(labelOrKey: string): VariableValue | undefined;
  getAll(): Record<string, VariableValue>;
  set(key: string, value: VariableValue): boolean;     // false if unknown or read-only
  contains(key: string): boolean;
  interpolate(template: string): string;
  subscribe(listener: () => void): () => void;
  // ...plus batch/reset helpers
}

// Expression / property helpers (advanced)
function evaluateCondition(condition: Condition, store: VariableStore): boolean;
function resolveProperty<T>(value: PropertyValue<T>, store: VariableStore): T | undefined;
function resolveStringProperty(value: PropertyValue<string>, store: VariableStore): string | undefined;
```

## Custom components, screens, and actions

Methods on `FlowPilot`, plus the definition types. See [Custom components and actions](/expo-sdk/custom-components) and [Custom screens](/expo-sdk/custom-screens).

```ts theme={null}
// Custom components (rendered).
registerCustomComponent(key: string, definition: {
  version?: number;
  inputs?: Record<string, VariableTypeName>;
  outputs?: Record<string, { description?: string; payload?: Record<string, VariableTypeName> }>;
  component: React.ComponentType<CustomComponentRenderProps>;
}): void
unregisterCustomComponent(key: string, version?: number): void
getCustomComponent(key: string, version: number): CustomComponentDefinition | undefined

// Custom screens (registered but NOT rendered in this build).
registerCustomScreen(screenId: string, definition: {
  inputs?: Record<string, VariableTypeName>;
  outputs?: Record<string, { description?: string; payload?: Record<string, VariableTypeName> }>;
  component: React.ComponentType<CustomScreenRenderProps>;
}): void

// Custom actions.
registerCustomAction(key: string, handler: CustomActionHandler): void
unregisterCustomAction(key: string): void
```

```ts theme={null}
interface CustomComponentRenderProps {
  props: { inputs: Record<string, VariableValue> };
  context: CustomComponentContext;
}
interface CustomComponentContext {
  containerSize: { width: number; height: number };
  containerConstraints: {
    minWidth?: number; maxWidth?: number; minHeight?: number; maxHeight?: number;
    supportsIntrinsicSize: boolean;
  };
  emit(eventName: string, payload?: Record<string, unknown>): void;
}

interface CustomScreenRenderProps {
  props: { inputs: Record<string, VariableValue> };
  context: CustomScreenContext;
}
interface CustomScreenContext extends CustomComponentContext {
  screenId: string;
  setZonesVisible(visible: boolean): void;
}

type CustomActionHandler = (
  params: Record<string, unknown> | undefined,
  context: ActionContext,
) => Promise<void>;

interface ActionContext {
  variableStore: VariableStore;
  navigationController: NavigationController;
  analyticsTracker?: { track(eventKey: string, properties?: Record<string, unknown>): void; /* ... */ };
  flowId: string;
  screenId?: string;
  elementId?: string;
  elementType?: string;
  isFlowClosed: boolean;
}
```

<Warning>
  Custom **components** render today. Custom **screens** do not: `registerCustomScreen` stores the definition but the renderer never invokes it in this build. See [Custom screens](/expo-sdk/custom-screens).
</Warning>

## Analytics

See [Analytics integration](/expo-sdk/analytics).

```ts theme={null}
// Additive callback for every analytics event the SDK emits.
setAnalyticsCallback(callback: AnalyticsCallback): void
type AnalyticsCallback = (event: { eventName: string; properties: Record<string, unknown> }) => void

// Conversion attributed to the most-recently-started session.
trackConversion(amount: number, currency: string, productId?: string, metadata?: Record<string, unknown>): void
```

The full on-wire event shape is exported as the `AnalyticsEvent` type. Automatic event names: `flow_start`, `screen_view`, `screen_exit`, `element_interaction`, `flow_complete`, `flow_exit`, `experiment_exposure`, plus `conversion` from `trackConversion`. See the [Event taxonomy](/reference/event-taxonomy).

## Errors

See [Error handling](/expo-sdk/error-handling).

```ts theme={null}
class FlowPilotError extends Error {
  readonly code: ErrorCode;
  readonly underlyingError?: Error;
  readonly context?: Record<string, string>;
}

type ErrorCode =
  | 'INVALID_API_KEY' | 'SDK_NOT_INITIALIZED' | 'NETWORK_ERROR' | 'API_ERROR'
  | 'TIMEOUT' | 'RATE_LIMITED' | 'PLACEMENT_NOT_FOUND' | 'FLOW_NOT_FOUND'
  | 'UNSUPPORTED_SCHEMA_VERSION' | 'INVALID_FLOW_SCHEMA' | 'COMPONENT_RENDER_ERROR'
  | 'CUSTOM_COMPONENT_NOT_FOUND' | 'NAVIGATION_ERROR' | 'VARIABLE_ERROR'
  | 'ACTION_ERROR' | 'ACTION_CHAIN_TIMEOUT' | 'INTERNAL_ERROR';
```

## Caching and offline

See [Caching](/expo-sdk/caching) and [Offline and bundled flows](/expo-sdk/offline-bundled-flows).

```ts theme={null}
clearCache(): Promise<void>   // async (disk delete); await before the next resolve
clearImageCache(): void
registerBundledFlow(placementKey: string, json: object, assets?: BundledFlowAssets): void
registerBundledFlowAssets(placementKey: string, assets: BundledFlowAssets): void

// Which fail-safe tier produced a presented flow (surfaced as delivery_source).
type FlowDeliverySource = 'network' | 'cache' | 'stale_cache' | 'bundled_default';

interface BundledFlowAssets {
  manifest: {
    images: { url?: string; src?: string; resource: string }[];
    icons: { url?: string; name?: string; resource: string }[];
    fonts: { family: string; weight: number; style?: string; resource: string }[];
  };
  resources: Record<string, number | string>; // resource path -> require()'d module or uri
}
```

## Media and fonts

See [Media preloading](/expo-sdk/media-preloading).

```ts theme={null}
class MediaPreloader {
  preload(
    flow: FlowDefinition, mediaBaseUrl: string, iconBaseUrl: string,
    onProgress?: PreloadProgressCallback, options?: { firstScreenOnly?: boolean },
  ): Promise<PreloadProgress>;
  abort(): void;
}
const mediaPreloader: MediaPreloader; // the SDK's shared instance

interface PreloadProgress {
  totalItems: number; completedItems: number; failedItems: number;
  currentScreenIndex: number; progress: number; isComplete: boolean;
}
type PreloadProgressCallback = (progress: PreloadProgress) => void;

// Fonts
class FontManager { /* loadFonts, registerLocalFont, resolveFont, isLoaded, clear, ... */ }
const fontManager: FontManager;
function fontWeightToRN(weight: number | string): string;
```

## Accessibility

```ts theme={null}
function initAccessibility(): void;            // start reduce-motion monitoring (called by configure)
function isReduceMotionEnabled(): boolean;
function useReduceMotion(): boolean;           // React hook
function getAccessibilityRole(componentType: string): string | undefined;
function buildAccessibilityProps(/* ... */): object;
function buildProgressAccessibility(/* ... */): object;
```

All built-in animations respect the reduce-motion setting automatically.

## Advanced rendering exports

The package also exports the renderer internals so preview tooling and advanced hosts can drive rendering directly. Most apps never import these; use `FlowPilotPresenter` instead. They include:

* **Renderers:** `ScreenRenderer`, `ComponentRenderer`, `FlowPresenter`, `FlowRenderProvider` (+ `FlowRenderContextValue`).
* **Backgrounds:** `BackgroundRenderer`, `resolveScreenBackground`.
* **Animation hooks:** `useComponentAnimation`, `useAttentionEffect`, `usePressFeedback`, `useStaggerDelay`, `useStaggerContext`, `triggerHaptic`, `MotionBackgroundLayer`, `resolveLegacyFlatAnimation`.
* **Text effects:** `TypewriterEffect`, `CountUpEffect`, `ScrambleEffect`, `FadePerLineEffect`, `TextRotationEffect`.
* **Particles:** `ParticleOverlay` (+ `ParticleOverlayHandle`, `ParticleOverlayProps`), `PARTICLE_PRESETS`.

These mirror the model and config types also exported for typing flow JSON: `FlowDefinition`, `FlowNode`, `ComponentNode`, `ComponentType`, `PropertyValue`, `Condition`, `ComponentAction`, `TransitionConfig`, `ScreenBackground`, `AnimationTimeline`, `PersistentUI`, and more. See the [Flow schema](/reference/flow-schema) and [Component reference](/reference/component-reference).

## Related pages

* [Installation](/expo-sdk/installation)
* [Configuration](/expo-sdk/configuration)
* [Quickstart](/expo-sdk/quickstart)
* [Presenting placements](/expo-sdk/presenting-placements)
* [Results and outcomes](/expo-sdk/results-and-outcomes)
* [Prefetching](/expo-sdk/prefetching)
* [Variables and context](/expo-sdk/variables-and-context)
* [Conversions and revenue](/expo-sdk/conversions)
* [Custom components and actions](/expo-sdk/custom-components)
* [Custom screens](/expo-sdk/custom-screens)
* [Analytics integration](/expo-sdk/analytics)
* [Error handling](/expo-sdk/error-handling)
* [Caching](/expo-sdk/caching)
* [Offline and bundled flows](/expo-sdk/offline-bundled-flows)
* [Media preloading](/expo-sdk/media-preloading)
* [Troubleshooting](/expo-sdk/troubleshooting)