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

# Artifact Requirements

> What your .app or .apk must look like before it can run on Revyl

Revyl runs tests on cloud **simulators (iOS)** and **emulators (Android)**, not physical devices. That single fact drives every requirement below.

## iOS

| Required                                                                                            | Recommended          |
| --------------------------------------------------------------------------------------------------- | -------------------- |
| Simulator-slice `.app` (or zipped `.app`). Built against the `iphonesimulator` SDK, not `iphoneos`. | Debug configuration. |

### Why

Cloud simulators run a different CPU slice than physical iPhones. An `.ipa` produced for device distribution will not install on a simulator — `simctl install` rejects it with an arch mismatch. You need the `.app` bundle that Xcode/EAS produces when targeting the simulator.

### How to satisfy it

| Framework           | Knob                                                      |
| ------------------- | --------------------------------------------------------- |
| Xcode / Swift       | `xcodebuild -sdk iphonesimulator -configuration Debug`    |
| Expo (EAS)          | `ios.simulator: true` on your build profile in `eas.json` |
| React Native (bare) | `xcodebuild -sdk iphonesimulator` (Pods + workspace)      |
| Flutter             | `flutter build ios --simulator --debug`                   |

<Note>
  `.ipa` archives are not supported. If your CI produces an `.ipa`, you'll need
  a parallel simulator-slice job to upload to Revyl.
</Note>

## Android

Two requirements:

1. **Upload one installable `.apk` artifact.** `.aab`, `.apks`, APK Set archives, and split APK archives are not supported.
2. **APK must include `x86_64` in its ABI set.** Revyl's cloud emulators are `x86_64`; `arm64-v8a`-only APKs won't install.
3. **APK must be debuggable** (`android:debuggable="true"` in the merged manifest).

### Why x86\_64

Cloud emulators run a Google Play `x86_64` system image. Install fails immediately if the APK has no `x86_64` native libs. Default debug builds from every framework include all ABIs in one fat APK, so this only bites if you've narrowed `abiFilters` or `android.ndkAbiFilters`.

### Why debuggable

Debuggable builds (`android:debuggable="true"` in the merged manifest) are what allow Revyl to walk the app sandbox via `run-as <pkg>` — the platform only permits that against debuggable apps on non-rooted (Play-image) emulators. That sandbox access powers the **State tab**: SharedPreferences, Jetpack DataStore, and your app's SQLite databases. It also keeps a number of test-execution paths fast and reliable.

The runtime *will* install a non-debuggable release APK — tests still execute, video records, logs flow. You lose the State tab, and a class of debugging-dependent features. Don't ship a release APK to Revyl by default; produce a debuggable variant for testing alongside whatever you ship to users.

### How to satisfy it

| Framework              | Knob                                                                                                               |
| ---------------------- | ------------------------------------------------------------------------------------------------------------------ |
| Gradle / Kotlin / Java | `./gradlew assembleDebug` — debuggable + all ABIs by default                                                       |
| React Native (bare)    | `cd android && ./gradlew assembleDebug`                                                                            |
| Flutter                | `flutter build apk --debug`                                                                                        |
| Expo (EAS)             | The `development` profile (`developmentClient: true`, `android.buildType: "apk"`) is debuggable and ships all ABIs |

<Note>
  Custom `abiFilters` is the most common reason a build fails to install on Revyl.
  If you've narrowed the ABI set for size reasons, keep `x86_64` in it or produce
  a separate Revyl-targeted APK variant. The full ABI set is only \~10–20 MB
  larger. Do not upload `.apks` files or ZIPs containing multiple split APKs;
  Revyl does not install APK sets.
</Note>

## FAQ

<AccordionGroup>
  <Accordion title="Can I use a physical-device archive (.ipa / non-debuggable release APK)?">
    No. `.ipa` won't install on simulators. Release APKs install but lose the
    State tab and other debugging-dependent paths. Use a debug build for Revyl.
  </Accordion>

  <Accordion title="Why does Revyl insist on the simulator slice / x86_64?">
    Cloud test infra runs on shared hosts. Simulators (iOS) and emulators
    (Android) give us isolation and snapshot-restore. Physical-device farms
    exist but aren't what Revyl is.
  </Accordion>

  <Accordion title="What about Apple Silicon arm64 simulators?">
    Xcode produces a fat simulator `.app` (`x86_64` + `arm64`) by default.
    Both slices are accepted; Revyl picks the right one at install time.
  </Accordion>

  <Accordion title="My CI only produces release/production builds. What now?">
    Add a parallel debug job for Revyl. Most Gradle / Xcode / EAS projects
    need only a single extra task or profile.
  </Accordion>

  <Accordion title="My build uses abiFilters for size reasons.">
    Add `x86_64` to the filter set, or produce a separate Revyl-targeted
    variant that includes it. The full ABI set is only \~10–20 MB larger.
  </Accordion>
</AccordionGroup>

## Related

<CardGroup cols={2}>
  <Card title="Framework Build Guides" href="/builds/xcode">
    Platform-specific build commands for Xcode, Gradle, RN, Flutter, Expo.
  </Card>

  <Card title="Apps & Builds" href="/builds/index">
    Upload, activate, and manage builds in your Revyl app.
  </Card>
</CardGroup>