Skip to content

AppSetup.mdx

Latest commit

 

History

History
322 lines (268 loc) · 10.5 KB

AppSetup.mdx

File metadata and controls

322 lines (268 loc) · 10.5 KB
Raw
title App Setup
icon mobile
description Set up the Omi Flutter app for development. Build automatically with our dev backend, or manually with your own.

Overview

There are two ways to set up the Omi app for development:

**Recommended for most developers** 
One command setup using Omi's development backend
**For custom backends** 
Full control over configuration and backend
Don't want to build from source? Download the official app from the [App Store](https://apps.apple.com/us/app/friend-ai-wearable/id6502156163) or [Google Play](https://play.google.com/store/apps/details?id=com.friend.ios).

Prerequisites

Before starting, make sure you have the following installed:

Includes Dart - the core framework Required for iOS development Required for Android development iOS dependency manager You'll also need [NDK](https://developer.android.com/ndk/downloads) to build Opus for ARM devices.

Build the App Automatically

This is the recommended way to get started. It sets up your environment to use Omi's development backend with just one command.

Video Walkthrough

<iframe width="560" height="315" src="https://www.youtube.com/embed/U6L8S1SaUls?si=etmPgly-7dhyXmG_" title="Omi App Setup Video Guide" frameBorder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture" allowFullScreen ></iframe>

Setup Steps

```bash cd app ``` ```bash bash setup.sh ios ``` ```bash bash setup.sh android ``` Open the app in your IDE and hit run: - **Xcode**: Open `app/ios` folder - **Android Studio**: Open `app/android` folder 
Or run from terminal:
```bash
flutter run --flavor dev
```
The automatic setup uses Omi's development backend, making it the fastest way to start building apps and making changes.

Build the App Manually

Manual setup gives you full control, allowing you to use your own backend.

Ensure Flutter is installed by following the official [Flutter Installation Guide](https://docs.flutter.dev/get-started/install). 
Verify your setup:
```bash
flutter doctor -v
```

<AccordionGroup>
  <Accordion title="Example output" icon="terminal">
    ```
    [✓] Flutter (Channel stable, 3.41.9, on macOS 15.4.1)
    [✓] Android toolchain - develop for Android devices (Android SDK version 36.0.0)
    [✓] Xcode - develop for iOS and macOS (Xcode 16.4)
    [✓] Chrome - develop for the web
    [✓] Android Studio (version 2025.1)
    [✓] VS Code (version 1.101.0)
    [✓] Connected device (4 available)
    [✓] Network resources
    ```
  </Accordion>
  <Accordion title="Recommended versions" icon="info-circle">
    This project is tested with specific tool versions. See [`app/setup.sh`](https://github.com/BasedHardware/omi/blob/main/app/setup.sh) for recommended versions:
    - Flutter 3.41.9
    - Xcode 16.4
    - Android SDK Platform 35
    - NDK 28.2.13676358
    - JDK 21

    To set a specific JDK on macOS:
    ```bash
    flutter config --jdk-dir /Library/Java/JavaVirtualMachines/jdk-21.jdk/Contents/Home
    ```
  </Accordion>
</AccordionGroup>
From the `app` directory, install packages: ```bash cd app flutter pub get ``` Navigate to iOS directory and install CocoaPods dependencies: ```bash cd ios pod install pod repo update ``` Create your environment file from the template: ```bash cd .. cat .env.template > .dev.env ``` Edit `.dev.env` and add your API keys: 
| Key | Description |
|-----|-------------|
| `API_BASE_URL` | Your backend URL (use `https://api.omiapi.com/` for dev, or [set up your own](/doc/developer/backend/Backend_Setup)) |
| `OPENAI_API_KEY` | Optional - for AI features |
| `GOOGLE_MAPS_API_KEY` | Optional - for location features |

<Warning>
Be sure to include the trailing `/` in `API_BASE_URL` or you'll get malformed URLs. If you change this later, delete the builds folder and recreate the runner.
</Warning>
Generate necessary files: ```bash dart pub run build_runner clean dart pub run build_runner build ``` Firebase is **mandatory** for the app to run. 
<Warning>
The repo ships **prebuilt Firebase configs** for both dev and prod. If you're using Omi's development backend (the common case), they're already in place after `setup.sh` — skip to the next step.

**Never run `flutterfire configure`** against Omi's bundle IDs — it overwrites the prebuilt prod credentials in `app/ios/Config/Prod/`, `app/lib/firebase_options_prod.dart`, and `app/android/app/src/prod/`.
</Warning>

If you need your **own** Firebase project (custom backend):

1. Follow the official [Firebase Flutter Setup](https://firebase.google.com/docs/flutter/setup) through Step 1
2. For Apple login, [create an identifier](https://developer.apple.com/account/resources/identifiers/list) first
3. Configure `flutterfire config` using **your own** bundle IDs and **your own** project — not Omi's
4. Generate SHA1/SHA256 keys for your keystore and add them to Firebase ([StackOverflow guide](https://stackoverflow.com/a/56091158) | [Official Docs](https://support.google.com/firebase/answer/9137403?hl=en))

<Tip>
If you're facing auth issues, enable Google/Apple sign-in in the Firebase Console under **Authentication → Sign-in method**.
</Tip>
Select your target device and run: ```bash flutter run -v --flavor dev ``` 
To build an APK:
```bash
flutter build apk --flavor dev
```

Code Formatting

We use dart format with a line length of 120 characters.

To automatically format code on commit, install the pre-commit hook:

# From the root of the repository
ln -s -f ../../scripts/pre-commit .git/hooks/pre-commit

Troubleshooting

- Run `flutter doctor -v` for detailed output - Follow the suggestions to fix each issue - Make sure all required SDKs are installed - Ensure CocoaPods is installed: `sudo gem install cocoapods` - Run `pod install` in the `ios` directory - Try `pod repo update` if dependencies fail - Check NDK is installed via Android Studio SDK Manager - Verify JDK version matches requirements (JDK 21) - Accept all Android licenses: `flutter doctor --android-licenses` - Enable Google/Apple sign-in in Firebase Console - Verify SHA1/SHA256 keys are added to Firebase - Check bundle IDs match your Firebase configuration **Error Message:** ``` error: Unable to flip between RX and RW memory protection on pages ``` 
**Cause:**
This error occurs because iOS security restrictions prevent the Dart VM from changing memory protection during JIT compilation in Debug mode on physical devices.

**Solutions:**

1. **Use iOS Simulator (Recommended for Development):**
   - In Xcode, select an iOS Simulator (e.g., "iPhone 16 Pro") instead of your physical device
   - The simulator doesn't have this restriction, so Debug mode works normally
   - Or run: `flutter run --flavor dev` (it will use a simulator if available)

2. **Use Release/Profile Mode for Physical Devices:**
   - If you need to test on a physical device, build in Release or Profile mode:
     ```bash
     flutter run --release --flavor dev
     ```
   - Or in Xcode, select "Release" or "Profile" scheme instead of "Debug"

**Note:** This is a known Flutter/iOS limitation. Debug mode with JIT compilation requires memory protection changes that iOS blocks on physical devices for security reasons.

Need Help?

Search the help channel or ask questions Report bugs or browse existing issues

Related Documentation

Set up your own Omi backend Create Omi apps and integrations Flash and update device firmware How to contribute to Omi