Skip to main content

Your First Integration

This guide takes you from an empty Appilots project to a working in-app AI assistant that can navigate your React Native app and fill a form. It stitches together the pieces covered individually in the SDK, CLI, and Dashboard sections.

We'll use a small fleet-management app as the running example: it has a Home screen, a Vehicles list, and a VehicleCreate form.

Prerequisites​

  • React Native >= 0.72, React >= 18, Node.js >= 18
  • An account at app.appilots.com

Step 1 — Create a project and get an API key​

  1. In the dashboard, click New Project and give it a name (for example, "Fleet App").
  2. Note the Project ID.
  3. Create an API key for the project. The full key is shown once — copy it now. It looks like ak_xxxxxxxxxxxx....

See Projects & API keys for key management details (rotation, revocation, per-environment keys).

Step 2 — Install the SDK​

npm install @appilots/sdk

Make sure the peer dependencies are present: react-native-safe-area-context (>= 4) and react-native-svg (>= 13). See Installation.

Step 3 — Wrap your app​

import { NavigationContainer } from '@react-navigation/native';
import {
  AppilotsProvider,
  AppilotsNavigationContainer,
  AppilotsChat,
} from '@appilots/sdk';

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

Three things happened here:

Step 4 — Describe a screen to the agent​

Register the form screen so the agent knows what it's for and what's on it:

// VehicleCreateScreen.tsx
import { registerScreen } from '@appilots/sdk';

registerScreen({
  name: 'VehicleCreate',
  title: 'New Vehicle',
  description: 'Form to register a new vehicle for the account.',
  fields: [
    { id: 'plate', label: 'License Plate', type: 'text', required: true },
    { id: 'model', label: 'Model', type: 'text', required: true },
  ],
  actions: [
    {
      id: 'submitVehicle',
      label: 'Save Vehicle',
      type: 'submit',
      effect: 'write',
      riskLevel: 'low',
    },
  ],
  suggestedPrompts: ['Add a vehicle'],
});

Step 5 — Make the fields operable​

Registering the screen describes it; registering the elements makes them something the agent can actually type into and press. The quickest precise way is the hooks:

import { useRef, useState } from 'react';
import { TextInput, Button } from 'react-native';
import { useAppilotsField, useAppilotsTarget } from '@appilots/sdk';

function VehicleCreateScreen() {
  const [plate, setPlate] = useState('');
  const plateRef = useRef<TextInput>(null);

  useAppilotsField('plate', {
    value: plate,
    onChangeText: setPlate,
    ref: plateRef,
    label: 'License Plate',
    screen: 'VehicleCreate',
  });

  const handleSubmit = () => {
    /* save the vehicle */
  };
  useAppilotsTarget('submitVehicle', {
    onPress: handleSubmit,
    label: 'Save Vehicle',
    screen: 'VehicleCreate',
  });

  return (
    <>
      <TextInput ref={plateRef} value={plate} onChangeText={setPlate} />
      <Button title="Save Vehicle" onPress={handleSubmit} />
    </>
  );
}

For app-wide coverage with less code, look at auto-tracking and the HOC factories — adding a testID to existing components is often all it takes.

Step 6 — Generate and upload the MCP document​

The agent also needs the static map of your app — screens, navigation graph, forms — which the CLI generates from your source code:

npm install -g @appilots/cli

appilots init --api-key ak_xxxxxxxxxxxx... --server https://api.appilots.com
appilots sync

init writes a .appilotsrc (and adds it to .gitignore — it contains your key). sync analyzes the project and uploads the MCP document. Re-run sync whenever screens, navigation, or forms change — or run appilots watch during development, and wire sync into CI for production.

Step 7 — Try it​

Launch the app, tap the chat bubble, and ask:

"Add a vehicle with plate ABC-1234, model Onix"

You should see the agent navigate to VehicleCreate, fill both fields, and press Save Vehicle — with progress shown as an action breadcrumb in the chat. If it doesn't, Troubleshooting covers the common causes (unregistered elements, stale MCP document, missing config).

Where to go next​

Last updated on