Preparing Your App Build

VibeView runs your app on cloud iOS/tvOS simulators and Android emulators. That means the file you upload must be a simulator/emulator build — a build made for a physical device will not install. This page shows how to produce an uploadable build for each platform and framework.

Accepted formats

Uploads are limited to 500 MB per file. .ipa files are rejected — an .ipa is a device build and cannot run on a simulator (see below for what to upload instead).

iOS

Why your .ipa won’t work

An .ipa (what Xcode’s Archive flow and App Store/TestFlight distribution produce) is compiled for physical iPhone hardware. Simulators need a build compiled against the simulator SDK instead. You don’t need signing certificates or provisioning profiles for a simulator build — any project that runs in the Xcode simulator can produce one.

Getting the .app from Xcode

The easiest way: run your app once on a local simulator, then grab the build Xcode already made.

1. In Xcode, select any iOS Simulator as the run destination and press Run (⌘R).

2. Find the built .app in DerivedData:

   ~/Library/Developer/Xcode/DerivedData/<YourApp>-<random>/Build/Products/Debug-iphonesimulator/<YourApp>.app

   Or locate it from within Xcode: Product → Show Build Folder in Finder, then open Products/Debug-iphonesimulator/.

Building from the command line

xcodebuild -scheme YourApp \
  -sdk iphonesimulator \
  -configuration Debug \
  -derivedDataPath build

The bundle lands in build/Build/Products/Debug-iphonesimulator/YourApp.app. (For workspace-based projects, add -workspace YourApp.xcworkspace.)

Architecture

VibeView’s iOS simulators run on Apple silicon, so your simulator build must include an arm64 slice. Modern Xcode includes it by default — but if your project still carries the old EXCLUDED_ARCHS = arm64 workaround for simulator builds, remove it. You can check a build with:

lipo -info YourApp.app/YourApp

The output should include arm64.

Compressing the bundle

A .app is a folder, so it must be compressed before upload — and it must sit at the top level of the archive, not nested inside other folders. If the upload succeeds but the app later fails to install, a nested archive is the most common cause.

• Finder: right-click YourApp.app → Compress “YourApp”.

• Terminal:

  ditto -c -k --keepParent YourApp.app YourApp.zip

Compress the .app itself — not the folder that contains it.

tvOS

Same flow as iOS, with the tvOS simulator SDK:

xcodebuild -scheme YourApp \
  -sdk appletvsimulator \
  -configuration Debug \
  -derivedDataPath build

The bundle lands in build/Build/Products/Debug-appletvsimulator/YourApp.app. Compress and upload it the same way.

Android

Building an APK

./gradlew assembleDebug

The APK lands in app/build/outputs/apk/debug/app-debug.apk and can be uploaded as-is — debug builds are signed automatically with the debug keystore, so no release signing setup is needed.

App Bundles (.aab)

.aab files can’t be uploaded directly. Convert your bundle to a universal APK with bundletool:

bundletool build-apks --bundle=app.aab --output=app.apks --mode=universal
unzip app.apks universal.apk

Rename universal.apk as you like and upload it.

Architecture

VibeView’s Android emulators are x86_64. If your app ships native libraries, make sure the build includes x86_64 ABIs (standard debug builds include all ABIs by default — this only matters if your build filters ABIs, e.g. via abiFilters, reactNativeArchitectures in gradle.properties, or per-ABI splits). An APK without an x86_64 slice will fail to install (INSTALL_FAILED_NO_MATCHING_ABIS) or crash on launch, depending on the device. Uploads check for this and warn when a build has native code but no x86_64 — if you see that warning, rebuild with x86_64 included before starting sessions.

Android TV

Upload a regular .apk. TV apps are detected automatically from the app’s manifest, and the platform shows as Android TV in your Apps list.

Framework notes

• React Native: the iOS app is a normal Xcode project — run npx react-native run-ios once, then grab the .app from DerivedData as described above. For Android, cd android && ./gradlew assembleDebug.
• Expo: use a development or preview build with a simulator profile ("ios": { "simulator": true } in eas.json); the build output contains the simulator .app. Expo Go itself is not your app — upload your own build.
• Flutter: flutter build ios --simulator --debug produces build/ios/iphonesimulator/Runner.app. For Android, flutter build apk --debug.

Troubleshooting

• “iOS simulators require .app bundles, not .ipa files” — you uploaded a device build. Produce a simulator build as described above.
• Upload succeeds, but the app fails to install in a session — most often the .app is nested inside extra folders in the archive. Re-compress so the .app sits at the archive’s top level.
• “File too large” — uploads are capped at 500 MB. Debug simulator builds are usually far smaller than release archives; check you’re not zipping extra folders (like a whole DerivedData directory) alongside the .app.
• App installs but crashes immediately on iOS — check the build includes an arm64 simulator slice (see Architecture above).
• App fails to install, or installs but crashes immediately, on Android — the APK most likely ships native code without an x86_64 slice (common when a build is targeted at ARM devices or TV boxes); depending on the device this shows up as an install failure (INSTALL_FAILED_NO_MATCHING_ABIS) or a crash on launch. The upload warns about this; rebuild with x86_64 included (see Architecture above).

Next steps

Once you have your build file, head to Apps to upload it, or follow the Getting Started guide end-to-end.