Android deployment

Use Deploy to install a recorded Android package on a saved emulator, run it and inspect the result. This page describes the current Windows x64 emulator workflow, not Play Store submission or a promise of managed USB-phone deployment.

Before you begin

Open the intended project in cApp on a Windows x64 computer with its local service connected. Either have a recorded Android package from Build, or select a verified compiler release in Build for Build & run. A .capp-showcase demo or compiler reference by itself is not an Android package.

You need disk space for tools, the Android system image and persistent device data. Native compilation additionally needs Build's Rust and Android NDK prerequisites. Installing emulator tools alone does not satisfy the native build toolchain.

First setup

Open Deploy → Android tools and inspect the detected tools. An existing Android Studio setup is normally discovered. Under Tool locations, enter an existing Android SDK folder, Java executable or bundletool.jar when automatic discovery did not select the intended installation; choose Save tool locations, then refresh.

For missing prerequisites, expand Install missing tools, review the licences and choose Install missing Android tools. This can acquire the command-line tools, emulator, ADB and APK inspection tools; Java and bundletool are acquired when missing. The licence checkbox is deliberate consent to installing those dependencies.

If acceleration is unavailable, follow the reported CPU-virtualization and Windows Hypervisor Platform guidance, then restart Windows as required. cApp reports the problem rather than silently changing Windows features.

Create or reuse a device

1. Under Choose a device, check Saved emulator. Reuse an existing device when you need its app data to survive between tests.
2. For a new device, expand Create another device and choose Load available images & profiles.
3. Select the hardware profile and Android system image, name the device, and review Memory and Storage for your computer.
4. Accept the selected image's licence and choose Download & create device. Inspect the operation result before attempting another creation with the same name.
5. Select the saved emulator, choose Start emulator when needed, and wait for the device state to become usable. Refresh devices updates the observed state.

A device's name is not its Android package identity. cApp distinguishes devices it opened from an emulator already started in Android Studio. It can reuse the latter; close externally started emulator windows yourself. Stop emulator controls a device opened by cApp and does not mean “delete its data.”

Choose and install a build

Choose Recorded Android package for the active project. Opening Install & run on an emulator from Build's Android result takes you to Deploy with that output selected.

Choose Verify package before installation. New packages have a native package identity linking the compiler release, settings, toolchain and actual file hashes. Old outputs remain visible in Build history, but need a fresh package before this verified deployment flow can use them. Do not work around failed verification by relabelling an arbitrary APK as a recorded build.

For Build & run, expand Build a fresh emulator version and inspect the release shown there. The flow includes x86_64 native code for the emulator. Also include ARM64 and ARMv7 phones in this package expands the package architectures; it does not itself deploy or qualify a phone. A package compiled only for a phone architecture cannot be assumed to work in the selected x86_64 emulator.

After verification, choose Install & run. The workflow checks the device, application identity, architecture, Android version and signing certificate before reporting installation and launch.

Keep app data through updates

Normal deployment uses an update path rather than uninstalling the application or clearing its data. Retain the same application ID and signing key, and use an acceptable newer version when updating. A different ID installs a different app; it does not automatically inherit the old app's storage.

A signing mismatch or older version stops with an explanation. Use the original signing key or produce an appropriate newer package rather than treating an uninstall/data wipe as the normal repair. Back up valuable application data using that app's supported process before risky testing. Retaining storage does not certify your application's own data migration logic.

For AAB emulator testing, cApp uses the persistent Android debug key to produce a test APK. It does not change the original AAB or turn it into a production-signed release. Test and production signing identities must not be treated as interchangeable.

Inspect the result

Run & inspect shows the stage, status and message. Expand Operation details & app logs for the recorded details. Export report retains the exact package and launch evidence; review it for local identifiers and application log content before sharing it.

App logs reads logs for the app deployed to the selected emulator. Recent deployments lets you reopen a recorded operation. A running process ID proves that startup was observed, not that a wallet flow, Guide task, backend request or Local AI model worked.

In the running application, check its first screen, navigation, permissions, backend, selected Sidecars and one representative workflow. Close and reopen it, then test an update against the same saved emulator to check data retention. Use application-surface tests for repeatable in-app checks.

Interrupted or cancelled operations

Cancel operation is not a rollback of an installation that already happened. Stop emulator is a separate device action. After a service interruption or uncertain installation result, inspect Recent deployments, the recorded stage and the actual installed app before making another request. The workflow does not automatically retry an uncertain installation.

If Build selection changed during Build & run, review the recorded package rather than assuming the new visible selection is what was installed. Keep the selected release, package and device together when comparing runs.

Troubleshooting

What success looks like

The expected package is verified, installed and observed running on the intended emulator, with a report linking those facts. Your representative workflows and data-retention checks also pass. Return to Build for the broader release checklist; publication remains a separate operation.