Quick Start

Get Appilots running in your React Native app in 5 minutes.

Building for the web?

This page covers the React Native SDK. For web apps (React, Vue, Svelte, or vanilla), see the Web SDK.

Prerequisites

• React Native >= 0.72

• Node.js >= 18

• React Navigation (@react-navigation/native) — the agent navigates through it, so it is required, not optional. It is declared as a peer dependency, so your package manager warns at install time if it is missing.

  Using Expo Router? npx create-expo-app generates it by default, and the analyzer cannot read file-based routes — a clean sync would produce an application map with zero screens. The CLI now fails instead of uploading one. Declare your screens with manifest mode and track the active route with setCurrentScreen().

• An Appilots account at app.appilots.com

Step 1: Install the SDK

npm install @appilots/sdk

Step 2: Wrap your app

Three pieces, and all three are required for the agent to do anything:

import { SafeAreaProvider } from 'react-native-safe-area-context';
import { AppilotsProvider, AppilotsNavigationContainer, AppilotsChat } from '@appilots/sdk';

function App() {
  return (
    <SafeAreaProvider>
      <AppilotsProvider
        config={{
          projectId: 'your-project-id',
          apiKey: 'ak_xxxxxxxxxxxx...',
        }}
      >
        <AppilotsNavigationContainer>
          <NavigationContainer>
            <Stack.Navigator>
              <Stack.Screen name="Home" component={HomeScreen} />
            </Stack.Navigator>
          </NavigationContainer>
        </AppilotsNavigationContainer>
        <AppilotsChat />
      </AppilotsProvider>
    </SafeAreaProvider>
  );
}

SafeAreaProvider has to be above AppilotsChat, not nested somewhere inside your navigator. The chat is a floating overlay and reads useSafeAreaInsets() to keep itself clear of the notch and the home indicator; with no provider above it, react-native-safe-area-context throws No safe area value available and takes the whole app down with it. If your app already renders SafeAreaProvider deeper in the tree, hoist it to the root rather than adding a second one.

AppilotsNavigationContainer wraps your NavigationContainer from the outside and injects the ref and onStateChange the SDK needs. Without it the agent cannot navigate at all — it can still answer questions about the current screen, which makes the failure look like a model problem rather than a wiring problem.

projectId is the minimum required field, but apiKey is what authenticates the SDK against the Appilots API (https://api.appilots.com) — without it, requests from this app instance will be rejected. Get both from your project on the dashboard. Send the key as a bearer token: Authorization: Bearer <API_KEY>.

Step 3: Let the SDK see your controls

Point the agent at your buttons, inputs and lists. Pick one of these:

// Option A — runtime, one call before your app renders.
import { enableAppilotsAutoTracking } from '@appilots/sdk';

enableAppilotsAutoTracking();

// Option B — build time. Two pieces, both required.
// 1. metro.config.js
const { withAppilots } = require('@appilots/sdk/metro');

module.exports = withAppilots(mergeConfig(getDefaultConfig(__dirname), config));

// 2. index.js — the plugin generates a module, but nothing imports it for you.
import '@appilots/auto-init'; // must be the first import

Option B is the bigger of the two: on top of auto-tracking it loads your .appilotsrc, so AppilotsProvider needs no props at all. Forgetting the index.js import is the common failure — the build succeeds, and the app then throws AppilotsProvider: No config found at runtime as if the config were missing. See SDK Overview for why.

Without one of them the component and list registries stay empty: the agent sees the text on screen but has no addressable control to press, and scroll_list does nothing.

What still needs a hook

Auto-tracking covers buttons with visible text, TextInputs with a placeholder, FlatList/SectionList/VirtualizedList/FlashList, and plain ScrollView screens (the agent can page a long form or detail screen with scroll_list, using direction — it has no rows, so no toIndex). Custom controls — a design-system dropdown, a gesture-driven toggle, a date picker — are invisible to it and need explicit registration.

A screen that scrolls but is not auto-tracked stays cut off at the fold: the agent has no way to reach what is below it.

Um Alert.alert que o app levantar passa a aparecer na observação e a bloquear o agente, como bloqueia o dedo do usuário. Isso troca um global do seu app (Alert.alert), então dá para desligar com trackNativeDialogs: false — ao custo de o agente agir às cegas enquanto um diálogo estiver na tela.

Diálogo de permissão do sistema, share sheet e compra in-app continuam invisíveis: eles não passam por nenhum código seu.

A form with no submit button still submits, as long as a field declares onSubmitEditing — on a search box or a one-field login the return key is the submit, and submitAfterFill uses it when no button is found.

Step 4: Sync MCP documents

npm install -g @appilots/cli

appilots sync

The sync command will analyze your app and upload the MCP documents to your Appilots project.

Check the screen count it reports. If it says 0 screens, the analyzer did not recognize your navigation setup and the agent will have no destination names — see CLI configuration for screenPatterns, or the manifest escape hatch if you do not use React Navigation.

Step 5: Test it!

Open your app, tap the chat, and ask the AI to navigate or fill a form.

If nothing happens

The three failures below all look the same from the chat — the agent answers, then does not act — so check them in this order.

What you see	Likely cause	Fix
Every navigate fails; console shows Navigation is not wired	AppilotsNavigationContainer missing	Step 2
The agent says it cannot find a button that is clearly on screen	Registries empty	Step 3
The agent has no idea your screen exists	MCP doc missing or stale	Step 4, re-run appilots sync
Requests rejected	Wrong or missing apiKey, or the key belongs to another project	Step 2

Two red screens instead of a silent failure:

What you see	Likely cause	Fix
AppilotsProvider: No config found	Using the Metro plugin, but index.js never imports @appilots/auto-init	Step 3
No safe area value available from inside AppilotsChat	SafeAreaProvider is missing, or nested below AppilotsChat instead of above it	Step 2

Next steps

• Installation details
• SDK configuration
• Customize MCP generation