API reference

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.

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.

Setup

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

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.

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

See Configuration.

Presenting

Methods on FlowPilot. See Presenting placements and Prefetching.

// 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`

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.

// 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.

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

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.

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 and Custom screens.

// 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

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;
}

Custom components render today. Custom screens do not: registerCustomScreen stores the definition but the renderer never invokes it in this build. See Custom screens.

Analytics

See Analytics integration.

// 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.

Errors

See Error handling.

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 and Offline and bundled flows.

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.

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

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 exports

Flows are drawn by the FlowPilot runtime in a WebView, so there are no renderer internals to import any more (2.0 removed ScreenRenderer, ComponentRenderer, the background/animation/text-effect/particle exports and the component-level model types along with the React Native renderer). What remains for advanced hosts:

Presentation: FlowPresenter (+ FlowPresenterProps) for custom embedding, and FlowWebRuntimeView if you compose the WebView yourself.
Runtime identity: isRuntimeAvailable, runtimeMetadata, EXPECTED_FLOW_SCHEMA_VERSION, BRIDGE_PROTOCOL_VERSION — enough to report which runtime build your app shipped.
Types for the envelope: FlowDefinition, FlowNode, ScreenNode, FlowOutcome, ComponentAction, FlowVariable, VariableValue. These describe what the host reads, not the flow’s component tree — for that, read the flow JSON. See the Flow schema and Component reference.

Getting started

Presenting flows

Data & context

Customization

Offline & performance

Reference

Setup

`FlowPilotConfiguration`

Presenting

`PrefetchOutcome`

Components

Session

Results and lifecycle types

Variables

Custom components, screens, and actions

Analytics

Errors

Caching and offline

Media and fonts

Accessibility

Advanced exports

​Setup

​FlowPilotConfiguration

​Presenting

​PrefetchOutcome

​Components

​Session

​Results and lifecycle types

​Variables

​Custom components, screens, and actions

​Analytics

​Errors

​Caching and offline

​Media and fonts

​Accessibility

​Advanced exports

​Related pages

Setup

`FlowPilotConfiguration`

Presenting

`PrefetchOutcome`

Components

Session

Results and lifecycle types

Variables

Custom components, screens, and actions

Analytics

Errors

Caching and offline

Media and fonts

Accessibility

Advanced exports

Related pages