Quickstart

Not on Expo? This page is for the Expo managed workflow. If you're building with bare React Native, see SDK → React Native for the bare-RN setup (pod install, react-native-config env, Apple/Google sign-in via the platform-native libraries). The runtime API is identical — only install + native config differs.

1. Install the SDK

npx create-expo-app@latest my-app --template default
cd my-app
npx -y @layers/amba init

@layers/amba init walks you through:

• Creating an Amba account (or logging in — auto-detected when invoked from a coding agent's bash tool, in which case it provisions a sandbox account headlessly).
• Creating a project.
• Generating API keys (one client, one server).
• Writing .env.local, AMBA.md, and the /amba skill bundle into your project.
• Wiring mcpServers.amba into every detected MCP-client config (Claude Code, Cursor, Windsurf).

Then install the Expo SDK:

npx expo install @layers/amba-expo @react-native-async-storage/async-storage \
  expo-notifications expo-device expo-apple-authentication \
  expo-auth-session expo-crypto expo-linking

If you already have an account:

npx @layers/amba login

Rename env vars for Expo

Expo only exposes env vars prefixed with EXPO_PUBLIC_ to client code. Copy the CLI output into your app's .env.local with the prefix:

EXPO_PUBLIC_AMBA_PROJECT_ID=<your project id>
EXPO_PUBLIC_AMBA_CLIENT_KEY=<your client key>
EXPO_PUBLIC_AMBA_API_URL=https://api.amba.dev

2. Initialize the client

@layers/amba-expo provides an Amba singleton that handles storage, push tokens, and social sign-in for you. Call init() once in your root layout:

// app/_layout.tsx
import { useEffect } from 'react';
import { Slot } from 'expo-router';
import { Amba } from '@layers/amba-expo';
 
export default function RootLayout() {
  useEffect(() => {
    Amba.configure({
      projectId: process.env.EXPO_PUBLIC_AMBA_PROJECT_ID!,
      clientKey: process.env.EXPO_PUBLIC_AMBA_CLIENT_KEY!,
    }).catch((err) => console.warn('Amba.configure failed', err));
  }, []);
 
  return <Slot />;
}

configure() restores any persisted session from storage and creates an anonymous id. It does not create a server session by itself — the first authenticated call (tracking an event, reading XP, etc.) lazily signs in anonymously, so you don't need to call signInAnonymously() to get started. Call it explicitly only if you want to control when the anonymous user is created.

3. Register the Expo config plugin

In app.json, add @layers/amba-expo to the plugins array. The plugin wires up iOS aps-environment, Apple Sign In capability, URL schemes, and Android intent filters — no hand-editing Info.plist / AndroidManifest.xml.

{
  "expo": {
    "plugins": [
      "expo-router",
      [
        "@layers/amba-expo",
        { "projectId": "proj_...", "clientKey": "amba_ck_...", "scheme": "myapp" }
      ]
    ]
  }
}

Push on iOS requires a development build (not Expo Go) because custom entitlements aren't supported in Expo Go.

4. Track your first event

import { Amba } from '@layers/amba-expo';
 
function HomeScreen() {
  return (
    <Button
      title="Complete Workout"
      onPress={() =>
        Amba.events.track('workout_completed', {
          duration_minutes: 30,
          type: 'strength',
        })
      }
    />
  );
}

Events are sent to POST /client/events and automatically:

• Update the user's last_seen_at.
• Qualify any matching streaks.
• Trigger XP rules.
• Generate activity feed items (if configured).

5. Create a push campaign via MCP

If you're using an AI agent (Cursor, Claude Code, Windsurf), amba init in Step 1 already wired the MCP server into your client's config. The entry it wrote looks like:

{
  "mcpServers": {
    "amba": {
      "type": "http",
      "url": "https://mcp.amba.dev/mcp",
      "headers": { "Authorization": "Bearer <your-pat>" }
    }
  }
}

This activates the next time you launch your MCP client. (Cursor picks it up on the next message.) Then ask your AI agent:

"Create a push notification campaign called 'Welcome Back' that targets users who haven't opened the app in 7 days"

The agent will use amba_segments_create and amba_push_campaigns_create to set it up.

6. Check project status

npx @layers/amba status

This shows your project health: active users, push token count, segment count, and integration status.

Alternative: manual signup via the API

If you'd rather script signup (CI tasks, internal dashboards), the API exposes the same flow:

Sign up

POST /auth/developer/signup
Content-Type: application/json
 
{
  "email": "you@example.com",
  "password": "at-least-8-chars",
  "name": "Jane Dev"
}

Returns 201 with data.access_token, data.refresh_token, and data.developer. Passwords below 8 characters return WEAK_PASSWORD; duplicate emails return 409 EMAIL_EXISTS.

Log in

POST /auth/developer/login
 
{ "email": "you@example.com", "password": "..." }

Same response shape. Invalid creds return 401 INVALID_CREDENTIALS.

Rotate tokens

Refresh tokens live 30 days. Every refresh rotates both the access token and the refresh token — the old session is revoked atomically, so a replayed refresh is detected.

POST /auth/developer/refresh
 
{ "refresh_token": "<jwt>" }

Fetch the current developer

GET /auth/developer/me
Authorization: Bearer <access_token>

Log out

POST /auth/developer/logout
 
{ "refresh_token": "<jwt>" }

Logout is idempotent — an invalid token still returns { data: { success: true } }.

Create a project

POST /admin/projects
Authorization: Bearer <access_token>
 
{ "name": "My App", "environment": "development" }

Provisioning runs in the background. Poll the response until project status flips to active.

Mint an API key

Client SDKs authenticate with X-Api-Key. Keys are per-project and scoped to either development or production.

POST /admin/projects/:projectId/api-keys
Authorization: Bearer <access_token>
 
{ "name": "Expo dev key", "environment": "development" }

The response includes the plaintext key once — store it immediately. Rotating a key creates a new row and leaves the old key valid until you explicitly revoke it.

Rate limits

Developer auth is rate-limited per IP to catch credential stuffing:

Exceeding any window returns 429.

What's next?

• Walk through the kitchen-sink Expo tutorial — a full to-do app exercising every SDK module.
• Set up push notifications with APNs/FCM.
• Create user segments for targeting.
• Add streaks to drive daily engagement.
• Configure remote config for feature flags.
• Build an XP and levels system.