> ## Documentation Index
> Fetch the complete documentation index at: https://docs.autosana.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Building Your Mobile App for Our Cloud

> Step-by-step guide to building your mobile app for our virtual device cloud

<Info>
  **Testing a website?** You don't need to build anything - just enter your URL when creating an app. This guide is for mobile apps (iOS and Android) only.
</Info>

<Tip>
  Add our [MCP Server](/mcp-setup) to help you build your app for our cloud.
</Tip>

## Build Requirements

Autosana runs your mobile apps on both our **virtual device cloud** (iOS Simulators and Android Emulators) and **[real devices in the cloud](/real-device-testing)**. The build you upload decides where it can run:

| Platform | Build                         | Runs on                        |
| -------- | ----------------------------- | ------------------------------ |
| iOS      | `.app` (compressed as `.zip`) | Simulator only                 |
| iOS      | `.ipa`                        | Real devices only              |
| Android  | `.apk` / `.aab`               | Emulators **and** real devices |

### iOS Builds

* **Simulator** — a `.app` bundle compressed as `.zip`, built for the simulator SDK (`arm64`). Cheapest and fastest; covers most testing.
* **Real device** — a `.ipa` built for physical hardware (`iphoneos`). Required for [real-device testing](/real-device-testing).

<Tip>
  Building on an M1+ Mac will use `arm64` by default. Intel Macs will produce `x86_64` builds, which won't work on our simulators.
</Tip>

The simulator (`.app`) build steps are below; jump to [Real device builds](#real-device-builds-ipa) for `.ipa`.

### Android Builds

* **Format**: `.apk` or `.aab`
* **Architecture**: a **universal** APK/AAB (recommended) runs on both emulators and real devices. An `x86_64`-only APK runs on emulators but not real devices.

<Tip>
  Most build commands create universal APKs that include all architectures by default, so the same Android build works on both emulators and real devices — no separate build needed.
</Tip>

***

Select your framework to see build instructions:

<Tabs>
  <Tab title="React Native" icon="react">
    <Warning>
      **Important:** React Native apps must be built in Release mode. Debug builds will attempt to connect to Metro bundler and fail to run on the device. Release builds bundle the JavaScript code directly into the app, making them standalone.
    </Warning>

    ## React Native (iOS)

    1. Build it with:

    ```bash theme={null}
    npx react-native run-ios --mode Release
    ```

    2. App file should be here:

    ```bash theme={null}
    ios/build/Build/Products/Release-iphonesimulator/[YourApp].app
    ```

    <Note>
      In macOS, it should just be `YourApp` because macOS hides `.app` extensions
    </Note>

    3. Go to Finder, compress `YourApp` to a `.zip` and upload/drag it into the Autosana app upload dialog

    ### React Native with Expo (iOS)

    For Expo projects, use EAS Build to create simulator builds:

    1. Add this profile to your `eas.json`:

    ```json theme={null}
    {
      "build": {
        "preview-simulator": {
          "distribution": "internal",
          "ios": {
            "simulator": true
          }
        }
      }
    }
    ```

    2. Run the build command:

    ```bash theme={null}
    eas build --platform ios --profile preview-simulator
    ```

    3. Once the build completes, EAS will provide a download URL for the build
    4. Download and extract it to get the `.app` file
    5. Compress the `.app` to a `.zip` and upload it to Autosana

    ## React Native (Android)

    1. Navigate to your Android directory and build the release APK:

    ```bash theme={null}
    cd android && ./gradlew assembleRelease
    ```

    2. The APK will be located at:

    ```bash theme={null}
    android/app/build/outputs/apk/release/app-release.apk
    ```

    3. Upload the `.apk` file to Autosana

    ### React Native with Expo (Android)

    For Expo projects, use EAS Build to create APK builds:

    1. Add this profile to your `eas.json`:

    ```json theme={null}
    {
      "build": {
        "preview": {
          "distribution": "internal",
          "channel": "preview",
          "android": {
            "buildType": "apk"
          }
        }
      }
    }
    ```

    2. Run the build command:

    ```bash theme={null}
    eas build --platform android --profile preview
    ```

    3. Once the build completes, EAS will provide a download URL for the `.apk` file
    4. Download the APK and upload it to Autosana
  </Tab>

  <Tab title="Flutter" icon="mobile">
    ## Flutter (iOS)

    <Note>
      This builds a `.app` for the **simulator**. To test on real iPhones, build a `.ipa` instead — see [Real device builds](#real-device-builds-ipa).
    </Note>

    1. Build the app for simulator:

    ```bash theme={null}
    flutter build ios --simulator
    ```

    If your app uses flavors, add the `--flavor` flag:

    ```bash theme={null}
    flutter build ios --simulator --flavor [flavorName]
    ```

    2. The `.app` file will be located at:

    ```bash theme={null}
    build/ios/iphonesimulator/Runner.app
    ```

    3. Compress the `.app` to a `.zip` file
    4. Drag or upload the `.zip` file into the Autosana app upload dialog

    ## Flutter (Android)

    1. Build apk in debug mode:

    ```bash theme={null}
    flutter build apk --debug
    ```

    If your app uses flavors, add the `--flavor` flag:

    ```bash theme={null}
    flutter build apk --debug --flavor [flavorName]
    ```

    2. File is located at:

    ```bash theme={null}
    build/app/outputs/flutter-apk/app-debug.apk
    ```

    3. Drag or upload the `.apk` file into the Autosana app upload dialog
  </Tab>

  <Tab title="Native iOS" icon="apple">
    ## Native iOS (Xcode/SwiftUI)

    ### Option 1: Using Xcode (Graphical Interface)

    1. Open your project in Xcode
    2. At the top of Xcode, set:
       * The scheme to your app target (e.g., "MyApp")
       * The device to a simulator (e.g., "iPhone 16 Pro")
    3. In Xcode menu, select **Product > Scheme > Edit Scheme**
    4. Under **Run**, change **Build Configuration** to **Release**
    5. Press **Command + B** to build the project
    6. After the build finishes, the `.app` file will be located at:

    ```bash theme={null}
    ~/Library/Developer/Xcode/DerivedData/<ProjectName>/Build/Products/Release-iphonesimulator/<AppName>.app
    ```

    7. Right click and open in Finder
    8. Right click and compress it to make a `.zip` file
    9. Drag or upload the `.zip` file into the Autosana app upload dialog

    <Tip>
      **Finding the build folder in Finder:**

      * Open Finder
      * Press **Command + Shift + G**
      * Paste the path and press Enter
    </Tip>

    ### Option 2: Using Terminal (Command Line)

    1. Open Terminal and navigate to the root of your Xcode project:

    ```bash theme={null}
    cd /path/to/your/project
    ```

    2. Run this command to build the Release version for simulator:

    ```bash theme={null}
    xcodebuild -scheme YourAppScheme \
      -sdk iphonesimulator \
      -configuration Release \
      -destination 'platform=iOS Simulator,OS=latest,name=iPhone 16 Pro' \
      -derivedDataPath ./build \
      ARCHS=arm64 \
      ONLY_ACTIVE_ARCH=NO \
      CODE_SIGN_IDENTITY="" \
      CODE_SIGNING_REQUIRED=NO \
      CODE_SIGNING_ALLOWED=NO \
      build
    ```

    3. After the build completes, your `.app` file will be located:

    ```bash theme={null}
    ./build/Build/Products/Release-iphonesimulator/YourAppName.app
    ```

    4. Right click and open in Finder
    5. Right click and compress it to make a `.zip` file
    6. Drag or upload the `.zip` file into the Autosana app upload dialog

    <Warning>
      If your Simulator build uses signed entitlements such as Push Notifications, use the Xcode build steps above or adapt the command to keep code signing enabled. The command-line example disables signing and is only suitable for apps that do not need signed entitlements.
    </Warning>

    <Note>
      **Why Release configuration?** Release builds provide production parity with optimizations enabled, matching what your users experience. Most Simulator builds can use the unsigned command above, but apps that rely on signed entitlements are an exception. While Debug builds will work, they're not recommended for testing as they don't reflect the production environment.
    </Note>
  </Tab>

  <Tab title="Native Android" icon="android">
    ## Native Android (Kotlin/Java)

    ### Option 1: Debug Build (Recommended for Quick Testing)

    Debug builds work immediately without any signing configuration.

    **Using Android Studio:**

    1. Open your project in Android Studio
    2. From the menu bar, select **Build > Build Bundle(s) / APK(s) > Build APK(s)**
    3. Wait for the build to complete
    4. Click on **locate** in the notification that appears, or navigate to:

    ```bash theme={null}
    app/build/outputs/apk/debug/app-debug.apk
    ```

    5. Upload the `.apk` file to Autosana

    **Using Terminal:**

    ```bash theme={null}
    cd /path/to/your/android/project
    ./gradlew assembleDebug
    ```

    APK location: `app/build/outputs/apk/debug/app-debug.apk`

    ### Option 2: Release Build (Production Parity)

    Release builds provide better production parity but require signing configuration.

    **Step 1: Configure Signing (if not already set up)**

    Add this to your `app/build.gradle`:

    ```gradle theme={null}
    android {
        buildTypes {
            release {
                // Use debug keystore for testing (not for Play Store)
                signingConfig signingConfigs.debug
                minifyEnabled false
            }
        }
    }
    ```

    <Note>
      This uses the debug keystore for convenience. For Play Store releases, you'll need a proper release keystore.
    </Note>

    **Step 2: Build the Release APK**

    **Using Terminal:**

    ```bash theme={null}
    cd /path/to/your/android/project
    ./gradlew assembleRelease
    ```

    APK location: `app/build/outputs/apk/release/app-release.apk`

    **Using Android Studio:**

    1. Open your project in Android Studio
    2. From the menu bar, select **Build > Select Build Variant**
    3. Change from "debug" to "release"
    4. Select **Build > Build Bundle(s) / APK(s) > Build APK(s)**

    <Tip>
      **Which should I use?**

      * **Debug**: Faster builds, works immediately, easier debugging
      * **Release**: Production-like optimizations, catches minification issues
    </Tip>
  </Tab>
</Tabs>

***

## Real device builds (`.ipa`)

To run on [real iPhones](/real-device-testing) instead of the simulator, upload an **`.ipa`** built for physical hardware (`iphoneos`) — not a zipped `.app`. The file extension is how we route the build: `.ipa` → real device, `.app` / `.zip` → simulator.

<Warning>
  **Signing matters.** Use a **Development** or **Ad Hoc** signed `.ipa`. You do **not** need to register our device UDIDs — builds are automatically re-signed for the test device. Enterprise-signed builds fail to launch on our devices, and App Store builds aren't supported. Re-signing strips some entitlements (e.g. Push Notifications, Apple Pay, App Groups), so features depending on them won't work during tests.
</Warning>

<Info>
  If re-signing breaks Team-ID-prefixed Keychain access groups, expand **Advanced** during IPA upload and enable **Fix Keychain access after re-signing**. Most apps do not need this option.
</Info>

<Info>
  Android needs no separate build — a universal `.apk` / `.aab` already runs on both emulators and real devices.
</Info>

<Tabs>
  <Tab title="React Native (Expo)" icon="react">
    Use an EAS profile with internal distribution — note there is **no** `simulator: true`:

    ```json theme={null}
    {
      "build": {
        "device": {
          "distribution": "internal"
        }
      }
    }
    ```

    ```bash theme={null}
    eas build --platform ios --profile device
    ```

    EAS provides a download URL for the `.ipa`. Upload that file to Autosana.
  </Tab>

  <Tab title="Flutter" icon="mobile">
    ```bash theme={null}
    flutter build ipa --export-method development
    ```

    (The default export method is `app-store`, which won't launch on our devices.)

    The `.ipa` is written to:

    ```bash theme={null}
    build/ios/ipa/[YourApp].ipa
    ```

    Upload that `.ipa` to Autosana.
  </Tab>

  <Tab title="Native iOS / bare React Native" icon="apple">
    **Using Xcode:**

    1. Set the run destination to **Any iOS Device** (not a simulator)
    2. **Product > Archive**
    3. In the Organizer, click **Distribute App** and choose **Debugging** (development) or **Release Testing** (ad hoc) — not Enterprise or App Store Connect
    4. Upload the exported `.ipa` to Autosana

    **Using Terminal:**

    ```bash theme={null}
    xcodebuild -scheme YourAppScheme \
      -sdk iphoneos \
      -configuration Release \
      -archivePath ./build/YourApp.xcarchive \
      archive

    xcodebuild -exportArchive \
      -archivePath ./build/YourApp.xcarchive \
      -exportPath ./build/ipa \
      -exportOptionsPlist ExportOptions.plist
    ```

    With `ExportOptions.plist` setting the signing method to `debugging` (or `release-testing`):

    ```xml theme={null}
    <?xml version="1.0" encoding="UTF-8"?>
    <!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
    <plist version="1.0">
    <dict>
        <key>method</key>
        <string>debugging</string>
    </dict>
    </plist>
    ```

    The `.ipa` lands in `./build/ipa/`. Upload it to Autosana.
  </Tab>
</Tabs>

<Note>
  After uploading your `.ipa`, start a run with **Target: Real device** (or `physical_device: true` via the API). See [Real Device Testing](/real-device-testing) for how to run and pick a device.
</Note>