Skip to content
Wire AI docs

Getting started

The kit is @wireai/activation, a drop-in React Native and Expo AI onboarding kit. One component runs a backend-orchestrated flow: themed cards, progress, a mid-flow value screen, per-step validation, and a completion recap. It sits on the open-source wireai-rn SDK and talks to the multi-tenant Wire AI backend over A2A. MIT licensed.

Wire server
A2A backend, decides each step, stores the funnel
↓ plan, schemas, progress budget
answers, client events ↑
Your app
@wireai/activation kit renders the flow
getwireai console
Register apps, set the question script, read the funnel
↔ config down (questions, context), funnel and insights up
Plan and schemas come down, answers and events go up, and the console holds the config and the funnel.
The fast path: let your coding tool wire it in
You do not have to do these steps by hand. Point your coding tool at the Wire AI MCP server, or run a Claude skill, and it installs the kit, wires Metro, and scaffolds the screen for you. The manual steps below are here when you want to see exactly what it does.
1

Install the kit and the SDK

$
npminstall @wireai/activation wireai-rn
2

Wire Metro (required)

The kit ships a Metro wrapper. Without it, the themed assets do not resolve. Wrap your existing config:

metro.config.js
1const { getDefaultConfig } = require("expo/metro-config");
2const { withWireOnboarding } = require("@wireai/activation/metro");
3
4module.exports = withWireOnboarding(getDefaultConfig(__dirname));
3

Set your two secrets

Nothing renders without both: an app apiKey (a wai_ key that resolves your tenant server-side) and the backend serverUrl. Create them in the getwireai console or with the backend register script. Read them from your environment, never hardcode them in the bundle.

.env
EXPO_PUBLIC_WIREAI_API_KEY=your-wai-key-from-the-console
EXPO_PUBLIC_WIREAI_SERVER_URL=your-backend-url
EXPO_PUBLIC_WIREAI_APP_ID=your-app-id
4

Render WireOnboarding

Pass a config built from your environment, a theme, an onComplete handler that persists the result, and, always, a fallbackFlow so a backend error degrades to your static onboarding instead of dead-ending.

OnboardingScreen.tsx
1import { WireOnboarding, wireConfigFromEnv } from "@wireai/activation";
2import { YourStaticOnboarding } from "./YourStaticOnboarding";
3
4export function OnboardingScreen() {
5  return (
6    <WireOnboarding
7      config={wireConfigFromEnv({ appId: "your-app-id" })}
8      theme={{ accent: "#3ba9ae" }}
9      onComplete={(result) => persist(result)}
10      fallbackFlow={<YourStaticOnboarding />}
11    />
12  );
13}
5

Capture the result on completion

The onComplete callback fires when the user finishes the flow. Persist what you need (the answers, the derived profile) and route the user into the app.

Always pass a fallbackFlow
A missing or invalid config, or a backend hiccup, should never leave a new user staring at a blank screen. The fallbackFlow is your static onboarding, and it is what renders if Wire AI cannot.

Environment variables

The wireConfigFromEnv helper reads three variables and returns a config, or null when they are absent, which is how you gate the AI flow off cleanly. All three carry the EXPO_PUBLIC_ prefix because the client reads them at runtime.

EXPO_PUBLIC_WIREAI_API_KEYYour wai_ app key. Resolves the tenant server-side.
EXPO_PUBLIC_WIREAI_SERVER_URLThe backend base URL.
EXPO_PUBLIC_WIREAI_APP_IDYour app id, forwarded on every request.

Keep them in your env files and your env typing, never hardcoded in the bundle. If you already track install attribution, forward it through wireConfigFromEnv({ appId, metadata: attributionMetadata(...) }).

The fallbackFlow safety net

The kit is built so it can never break onboarding. Pass your existing static onboarding as fallbackFlow, and a backend error or timeout degrades to it instead of dead-ending a new user. When the AI flow degrades this way, the kit reports a client_fallback event to POST /v1/events on its own, so your dashboard's fallback rate counts the whole-flow case. Do not also report your own fallback, or you double-count it.

What happens offline or on error

The first card is guarded by a watchdog, startTimeoutMs, which defaults to 15 seconds. If the backend errors or times out, your onError handler fires and owns recovery, which is where you route to the static flow. Without an onError handler the kit shows an inline retry rather than a dead end. Per-turn signals arrive on onEvent as error, retry, and fallback, so you keep your analytics honest even though the kit owns the loop.

Testing your integration

Two paths are worth exercising before you ship. Gate the AI flow off with isOnboardingEnabled({ remote }) and confirm you branch cleanly to the static flow when config is missing or a remote kill-switch is off. Then force a backend error and confirm the fallback renders. For local development without an account, the kit ships DemoOnboarding, a no-account QA harness you can drop in to walk the UI. Leave the change type-checking green.

Next: MCP integration·Integrate with a Claude skill