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 task-tracking app as the running example: it has a Home screen, a Tasks list, and a TaskCreate form. Nothing here is specific to tasks — swap in whatever your app actually does; the agent reads the names YOU register, not a vocabulary it was taught.

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="Tasks" component={TasksScreen} />
            <Stack.Screen name="TaskCreate" component={TaskCreateScreen} />
          </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:

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

registerScreen({
  name: 'TaskCreate',
  title: 'New task',
  description: 'Form to create a task with a title and a due date.',
  fields: [
    { id: 'title', label: 'Title', type: 'text', required: true },
    { id: 'dueDate', label: 'Due date', type: 'date', required: true },
  ],
  actions: [
    {
      id: 'submitTask',
      label: 'Save task',
      type: 'submit',
      effect: 'write',
      riskLevel: 'low',
    },
  ],
  suggestedPrompts: ['Add a task'],
});

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 TaskCreateScreen() {
  const [title, setTitle] = useState('');
  const titleRef = useRef<TextInput>(null);

  useAppilotsField('title', {
    value: title,
    onChangeText: setTitle,
    ref: titleRef,
    label: 'Title',
    screen: 'TaskCreate',
  });

  const handleSubmit = () => {
    /* save the task */
  };
  useAppilotsTarget('submitTask', {
    onPress: handleSubmit,
    label: 'Save task',
    screen: 'TaskCreate',
  });

  return (
    <>
      <TextInput ref={titleRef} value={title} onChangeText={setTitle} />
      <Button title="Save task" 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 task called Send the invoice, due tomorrow"

You should see the agent navigate to TaskCreate, fill both fields, and press Save task — 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