App version not updating on device after Blueprint re-converge: increment versionCode in APK

Android

If an app isn't updating on your devices after you upload a new APK version to Esper Apps or apply Blueprint again a Blueprint, the issue is likely that the APK's versionCode hasn't been incremented. Android uses versionCode to determine whether an APK is newer than what's installed. Learn how to fix this.

Why your app won't update

Android's package manager uses versionCode — an integer value in the APK manifest — to decide whether an incoming APK is newer than the installed version. Changing the display name alone (the versionName string) is not enough. If your new APK has the same versionCode as the installed version, Android silently rejects the install even though the Esper Console may show the installation as successful.

Before you begin

Find the versionCode of the APK currently installed on your device. You can check this in two ways:

• In the Esper Console: go to Devices & Groups → [Device Name] → Apps and look for the version information.
• Using the command line: run aapt dump badging <apk_file> | grep versionCode on your APK file.

How to fix this

1. In your app's build configuration, increment the versionCode integer to a value strictly greater than the currently installed version. For example, if the installed version has versionCode 10, set the new build to versionCode 11.
2. You can also update the versionName display string (for example, from 1.0 to 1.1) for clarity, but this step is optional.
3. Build your APK with the incremented versionCode.
4. Upload the new APK to Esper Apps in the Esper Console.
5. Navigate to your Blueprint: Blueprints → [Blueprint Name] → Apps.
6. Confirm the new APK version is selected.
7. apply Blueprint again the Blueprint by going to Blueprints → [Blueprint Name] → Converge and applying it to your device group.
8. Verify the update on your device: go to Devices & Groups → [Device Name] → Apps in the Esper Console, or check on the device itself at Settings → Apps → [App Name] → Version.

The app still won't update

If you've incremented versionCode and the app still doesn't update, check the following:

• Device storage: Verify that the device has enough free storage to accept the new APK.
• Device status: Confirm the device is online and the Esper agent is active by checking Devices & Groups → [Device Name] → Device Info → Agent Status.
• Conflicting policies: Check whether overlapping Blueprints or group-level overrides are pinning an older version of the app.
• Collect logs: If the Esper Console shows a successful install but the device version hasn't changed, collect Esper Agent logs using the command adb shell logcat -d -s EsperDevicePolicy and contact Esper Support with your device serial number, APK details, and log output.

Important notes

• versionCode must be a strictly increasing integer. It cannot be equal to or lower than the installed version, or Android will silently reject the install.
• This behavior is built into Android itself and applies to all devices and Esper Agent versions.
• versionName is just a human-readable display string and does not affect whether Android upgrades your app.
• This applies only to APKs uploaded directly to Esper Apps. Apps distributed through the Google Play Store handle versioning on the server side and are not affected.
• To prevent this issue in the future, use auto-incrementing build numbers (such as CI build numbers) as your versionCode in your build pipeline.

Still need help?

If the steps above don't resolve your issue, contact Esper Support and include your device serial number, APK details, and any relevant logs.