​
Prerequisites​

Before starting, make sure you have the following installed:

​
Build the app automatically​

​
Video Walkthrough​

Building the app automatically means setting up your environment to use Omi’s Development backend. That makes it much easier for you to get started - with just one command!

This is the best way to get started, make changes to the app, and build apps on Omi.

Alternatively, you can build the app manually (see below) - which allows you to use your own backend, etc.

1. Navigate to the directory:

cd app

2. Build the app for iOS:

bash setup.sh ios

Note: This works great for iOS simulators! 🎉 Want to run on your real device? Ping us on Discord - we’d love to help! (Apple limits us to 100 dev devices)

3. Build the app for Android:

bash setup.sh android

If you use windows run the following commands

.\setup\scripts\setup.ps1

4. Run app in simulator:

Now that we’ve built the app, we can run it in the simulator. Open the app in Xcode (open folder app/ios) or Android Studio (open folder app/android) - then just hit the run button!

Alternatively, run flutter run --flavor dev in terminal

​
Build the app manually:​

Manual setup is useful if you want to build the app with your own backend.

​
1. Flutter Setup

Ensure Flutter is installed via FVM. Do not use global Flutter or upgrade it.

fvm setup (tested on macos):

dart pub global activate fvm

# install flutter 3.24.1
fvm install 3.24.1

# use flutter 3.24.1
fvm use 3.24.1

# check flutter version
fvm flutter --version

Run the following to verify setup:

fvm flutter doctor -v

Example output:

[✓] Flutter (Channel stable, 3.24.1, on macOS 15.3.2 24D81 darwin-arm64, locale en-US)
    • Flutter version 3.24.1 on channel stable at /Users/bread/fvm/versions/3.24.1
    • Upstream repository https://github.com/flutter/flutter.git
    • Framework revision 5874a72aa4 (9 months ago), 2024-08-20 16:46:00 -0500
    • Engine revision c9b9d5780d
    • Dart version 3.5.1
    • DevTools version 2.37.2

[✓] Android toolchain - develop for Android devices (Android SDK version 35.0.0)
    • Android SDK at /Users/bread/Library/Android/sdk
    • Platform android-35, build-tools 35.0.0
    • ANDROID_HOME = /Users/bread/Library/Android/sdk
    • ANDROID_SDK_ROOT = /Users/bread/Library/Android/sdk
    • Java binary at: /Library/Java/JavaVirtualMachines/jdk-17.jdk/Contents/Home/bin/java
    • Java version Java(TM) SE Runtime Environment (build 17.0.7+8-LTS-224)
    • All Android licenses accepted.

[!] Xcode - develop for iOS and macOS (Xcode 16.3)
    • Xcode at /Applications/Xcode.app/Contents/Developer
    • Build 16E140
    ✗ Unable to get list of installed Simulator runtimes.
    ✗ CocoaPods not installed.
        CocoaPods is a package manager for iOS or macOS platform code.
        Without CocoaPods, plugins will not work on iOS or macOS.
        For more info, see https://flutter.dev/to/platform-plugins
      For installation instructions, see https://guides.cocoapods.org/using/getting-started.html#installation

[✓] Chrome - develop for the web
    • Chrome at /Applications/Google Chrome.app/Contents/MacOS/Google Chrome

[✓] Android Studio (version 2024.3)
    • Android Studio at /Applications/Android Studio.app/Contents
    • Flutter plugin can be installed from:
      🔨 https://plugins.jetbrains.com/plugin/9212-flutter
    • Dart plugin can be installed from:
      🔨 https://plugins.jetbrains.com/plugin/6351-dart
    • Java version OpenJDK Runtime Environment (build 21.0.6+-13355223-b631.42)

[✓] VS Code (version 1.100.2)
    • VS Code at /Applications/Visual Studio Code.app/Contents
    • Flutter extension version 3.110.0

[✓] Connected device (4 available)
    • sdk gphone64 arm64 (mobile)     • emulator-5554         • android-arm64  • Android 13 (API 33) (emulator)
    • macOS (desktop)                 • macos                 • darwin-arm64   • macOS 15.3.2 24D81 darwin-arm64
    • Mac Designed for iPad (desktop) • mac-designed-for-ipad • darwin         • macOS 15.3.2 24D81 darwin-arm64
    • Chrome (web)                    • chrome                • web-javascript • Google Chrome 136.0.7103.114

[✓] Network resources
    • All expected network resources are available.

! Doctor found issues in 1 category.

Notes:

  • Flutter version must be 3.24.1 on the stable channel, do not use global Flutter or upgrade it.

  • Android SDK platform tools must be 35.0.0

  • Ensure JDK version is 17 for Android builds. Set it explicitly:

  • (On macos you can use the following command to set the jdk version)

fvm flutter config --jdk-dir /Library/Java/JavaVirtualMachines/jdk-17.jdk/Contents/Home
  • CocoaPods must be installed to run on iOS/macOS
  • Android Studio and VS Code versions do not matter as long as fvm flutter is used for all commands

​
2. Get Flutter Dependencies​

From within app directory, install flutter packages:

cd app 
fvm flutter pub get

​
3. Install iOS Pods​

Navigate to the iOS directory and install the CocoaPods dependencies:

cd ios
pod install 
pod repo update

​
4. Environment Configuration​

Create .env using template .env.template, the env template has OPENAI_API_KEY, GOOGLE_MAPS_API_KEY which are optional.

cd ..
cat .env.template > .dev.env

​
5. API Keys​

Add your API keys to the .env file. (Sentry is not needed)

  • API_BASE_URL is your backend url. You can use our dev backend URL https://backend-dt5lrfkkoa-uc.a.run.app/ or Follow this guide to install backend
  • Be sure to include the trailing ’/’ or you’ll get malformed URL’s
  • If you want to update this later on, you will need to delete the builds folder, and recreate the runner using dart.

​
6. Run Build Runner​

Generate necessary files with Build Runner:

fvm dart pub run build_runner clean
fvm dart pub run build_runner build

​
7. Setup Firebase​

  • This step is mandatory for running the app, otherwise firebase related code needs to be removed from the app.

  • Follow official Firebase Docs till Step 1

  • If you want to use Apple login, first go and create an identifier on the apple developer website

  • Run the following command to register the prod flavor of the app. The command will prompt you to select configuration type; under it, select Target and then Runner

    • substitute your apple identifier with the IOS_BUNDLE_ID in the command below
    flutterfire config --out=lib/firebase_options_prod.dart --ios-bundle-id=IOS_BUNDLE_ID --android-app-id=com.friend.ios --android-out=android/app/src/prod/  --ios-out=ios/Config/Prod/

  • Similarly for dev environment

    flutterfire config --out=lib/firebase_options_dev.dart --ios-bundle-id=com.friend-app-with-wearable.ios12.develop --android-app-id=com.friend.ios.dev --android-out=android/app/src/dev/  --ios-out=ios/Config/Dev/

  • Generate SHA1/SHA256 Keys for your Keystore and add them to Firebase. Follow the steps mentioned in this StackOverflow answer or the Official Docs. This is required for Firebase Auth through Google OAuth to work.

If you’re facing auth issues running the app, enable Google/Apple sign-in in Firebase. Go to the Firebase console and select your project. In the left-hand menu, click on “Authentication.” On the “Sign-in method” tab, scroll down to the “Sign-in providers” section. Click on the “Google” sign-in provider. Click the “Enable” switch to enable Google Sign-In for your Firebase project.

​
8. Run the App​

  • Select your target device in Xcode or Android Studio.
  • Run the app using fvm flutter run -v --flavor dev
  • To generate a dev apk fvm flutter build apk ---flavor dev

Having troubles? Join Discord and search your issue in help channel