App update via API fails silently: use `versionCode` in INSTALL command instead of separate UNINSTALL + INSTALL sequence

Android

When you upgrade an enterprise application on Android devices using the Esper API, you may encounter silent failures where the app disappears from the device entirely. This typically happens when you issue separate UNINSTALL and INSTALL commands, or when the versionCode field is missing from your installation payload. This article explains why this occurs and how to fix it.

Why app upgrades fail silently

The Esper Command API processes UNINSTALL and INSTALL operations independently and asynchronously. When you submit both commands in sequence without waiting for the first to complete, they can execute out of order—the INSTALL may finish before the UNINSTALL starts, and then the UNINSTALL removes the newly installed app.

Additionally, the Android package manager will not install an APK if the versionCode in your API request is missing or lower than the already-installed version. If the versionCode field is omitted from your INSTALL command payload, the device silently skips the installation with no error message.

How to upgrade apps correctly

Follow these steps to upgrade an enterprise app without encountering silent failures:

1. Ensure the new APK is accessible at a publicly reachable URL (for example, an FTP server, S3 bucket, or CDN).
2. Generate the SHA-256 Base64URL hash of the APK:

   openssl dgst -sha256 -binary "/path/to/app.apk" | openssl base64 | tr '+/' '-_' | tr -d '='

3. Verify that the versionCode in your APK manifest (AndroidManifest.xml) is higher than the currently installed version.
4. Submit a single INSTALL command via the Esper API with the following payload fields:
   • package_name — the app's package identifier
   • apk_path — the publicly accessible URL to the APK
   • version_code — must be higher than the currently installed build
   • apk_checksum — the SHA-256 Base64URL hash from step 2
5. In the Esper Console, navigate to Devices & Groups → [Device Name] → Apps and confirm the application now displays the new version number.

If you must use separate UNINSTALL and INSTALL commands

If your workflow requires uninstalling an app before installing it (for example, when changing package signatures or downgrading), use the following approach:

1. Issue the UNINSTALL command.
2. Poll the command status endpoint or monitor the Activity Feed in the Esper Console to confirm the UNINSTALL command status is Success.
3. Only after receiving success confirmation, issue the INSTALL command with the correct versionCode in the payload.

You can check the Activity Feed by navigating to Devices & Groups → [Device Name] → Activity Feed.

Troubleshooting

The INSTALL command shows Success, but the app version has not changed:

• Verify that the versionCode in your API payload exactly matches the versionCode declared in the APK manifest. A mismatch causes silent failure.

Commands continue to execute out of order:

• Check network latency between your API client and the Esper cloud endpoint. High latency may cause the command queue to batch and dispatch unpredictably.
• Implement a client-side polling loop that monitors the command status endpoint before issuing subsequent commands.

The app cannot be installed even after uninstalling:

• Confirm that the APK is accessible at the URL specified in your apk_path field.
• Verify that the apk_checksum value is a valid SHA-256 Base64URL hash.

Still need help?

If you continue to experience app upgrade failures after following these steps, contact Esper Support and include the Activity Feed entries for the failed commands.