> ## Documentation Index
> Fetch the complete documentation index at: /docs/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

> [!NOTE]
>
> **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.

> [!TIP]
>
> Add our [MCP Server](/docs/mcp-setup.md) to help you build your app for our cloud.

## Build Requirements

BugRadar runs your mobile apps on both our **virtual device cloud** (iOS Simulators and Android Emulators) and **[real devices in the cloud](/docs/real-device-testing.md)**. 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` | 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](/docs/real-device-testing.md).

> [!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.

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

#### App Clips

* A simulator build of your full app already contains its App Clip, in `YourApp.app/AppClips/`. Upload the full app as usual.
* You can also upload an App Clip on its own: an `.app` whose `Info.plist` contains `NSAppClip`, built for the simulator and zipped like any other `.app`. This is a valid upload.

See [Testing App Clips](/docs/guides-app-clips.md) to open the App Clip in a test.

### Android Builds

* **Format**: `.apk` (Android App Bundles, `.aab`, are not supported)
* **Architecture**: a **universal** APK (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.

***

Select your framework to see build instructions:

> [tab] React Native
>
> > [!WARNING]
> >
> > **Important:** For test runs, build React Native apps in Release mode. A debug build loads its JavaScript from Metro on your computer, which a test run can't reach. In a [sandbox](/docs/sandboxes.md#local-development), debug builds work with `BugRadar sandbox forward 8081`.
>
> ## 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
>
> 3. Go to Finder, compress `YourApp` to a `.zip` and upload/drag it into the BugRadar 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": {
>     "BugRadar-simulator": {
>       "distribution": "internal",
>       "ios": {
>         "simulator": true
>       }
>     }
>   }
> }
> ```
>
> 2. Run the build command:
>
> ```bash theme={null}
> eas build --platform ios --profile BugRadar-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 BugRadar
>
> > [!WARNING]
> >
> > This profile only creates a Simulator artifact; it does not enable APNs. If
> > the app uses `expo-notifications`, add its config plugin. During Expo Prebuild
> > or Continuous Native Generation, that plugin adds
> > `aps-environment=development` to the iOS app. If the app does not use
> > `expo-notifications`, declare the entitlement under `ios.entitlements` or
> > configure it in the native Xcode project. Follow [Testing Push Notifications:
> > Configure an Expo EAS
> > build](/docs/guides-push-notifications.md#configure-an-expo-eas-build).
>
> ## 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 BugRadar
>
> ### 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 BugRadar

> [tab] Flutter
>
> ## 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).
>
> 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 BugRadar 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 BugRadar app upload dialog

> [tab] Native iOS
>
> ## 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 BugRadar app upload dialog
>
> > [!TIP]
> >
> > **Finding the build folder in Finder:**
> >
> > * Open Finder
> > * Press **Command + Shift + G**
> > * Paste the path and press Enter
>
> ### Option 2A: Ordinary unsigned Simulator build
>
> 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 BugRadar app upload dialog
>
> > [!WARNING]
> >
> > This recipe explicitly disables signing. It cannot be used for APNs push
> > notification testing or any feature that requires a signed entitlement.
>
> ### Option 2B: Push-capable signed Simulator build
>
> First enable **Push Notifications** for the app target under **Signing & Capabilities** in Xcode. Then build without the settings that disable signing:
>
> ```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 \
>   build
> ```
>
> The signed `.app` is located at:
>
> ```bash theme={null}
> ./build/Build/Products/Release-iphonesimulator/YourAppName.app
> ```
>
> Before compressing it, confirm that the signed entitlements contain the APNs development environment:
>
> ```bash theme={null}
> codesign -d --entitlements :- \
>   ./build/Build/Products/Release-iphonesimulator/YourAppName.app
> ```
>
> The output must contain `aps-environment` with the value `development`. Then run the complete architecture, entitlement, and bundle-ID preflight in [Testing Push Notifications](/docs/guides-push-notifications.md#verify-the-simulator-artifact), compress the `.app`, and upload the resulting `.zip`.
>
> > [!NOTE]
> >
> > **Why Release configuration?** Release builds provide production parity with
> > optimizations enabled, matching what your users experience. Debug builds work,
> > but they are not recommended because they do not reflect the production
> > environment.

> [tab] Native 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 BugRadar
>
> **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.
>
> **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

***

## Real device builds (`.ipa`)

To run on [real iPhones](/docs/real-device-testing.md) 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. Private devices are the exception: they install your build as signed, so its provisioning profile must include each private phone's UDID. Copy the UDIDs from the **Devices** page, register them in your Apple Developer account, then regenerate the provisioning profile and rebuild. 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.

> [!NOTE]
>
> 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.

> [!NOTE]
>
> Android needs no separate build — a universal `.apk` already runs on both emulators and real devices.

> [tab] React Native (Expo)
>
> 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 BugRadar.

> [tab] Flutter
>
> ```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 BugRadar.

> [tab] Native iOS / bare React Native
>
> **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 BugRadar
>
> **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 BugRadar.

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


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.