App version not updating on devices after Blueprint publish: version code must be incremented alongside version name

Android

When you upload a new app version to a Blueprint and publish it, your devices may continue running the old version. This typically happens when the app's version code hasn't been incremented. This article explains why this occurs and how to fix it.

Understanding the issue

Android's system uses two version identifiers for apps:

• Version name — the human-readable version (for example, "1.0" or "1.1")
• Version code — an integer that Android uses to determine if an update is available

Android's package manager only recognizes an app as updated when the version code is higher than the currently installed version. If you increment only the version name but leave the version code the same or lower, Android silently rejects the installation as an upgrade.

How to check version codes

1. In the Esper Console, go to Devices & Groups → [Device Name] → Apps and locate your app to see its installed version code.
2. Alternatively, use ADB to retrieve the installed version code:

   adb shell dumpsys package <package.name> | grep versionCode

3. Check the uploaded APK's version code in the Esper Console at Apps → [App Name] → Versions.
4. Compare the two values. The new APK's version code must be strictly greater than the installed version code.

How to fix the version code

1. If the version codes match or the new APK has a lower code, ask your development team to rebuild the APK with an incremented version code.
2. In the app's AndroidManifest.xml or build.gradle, increment the versionCode to a value higher than the currently installed version. For example:

   <!-- AndroidManifest.xml example -->
   android:versionCode="2"
   android:versionName="1.1"

3. Ensure both versionName and versionCode are higher than the previous release.
4. Upload the corrected APK to the Esper Console via Apps → Add App → Upload APK.
5. Update your Blueprint to reference the new APK version: navigate to Blueprints → [Blueprint Name] → Apps, select the updated version, and save.
6. Publish the Blueprint to your devices: Blueprints → [Blueprint Name] → Publish → Select Group/Devices → Confirm.
7. Verify the update by going to Devices & Groups → [Device Name] → Apps. The app should show the new version name and code within a few minutes.

Troubleshooting if the update still doesn't appear

• Confirm the device is online. Updates cannot be delivered to offline devices.
• Verify the device is assigned to the correct Blueprint and that the Blueprint publish completed successfully in Blueprints → [Blueprint Name] → Publish History.
• Check whether the app is marked as Required or Optional in the Blueprint. Optional apps may not force an installation.
• If the app installs correctly after manual uninstall and reinstall but not through the Blueprint, collect device logs to help diagnose the issue:

  adb shell logcat -d | grep -i "esper\|Esper Agent\|install\|package"

Best practices

• Always increment both versionName and versionCode together for each new release. While only versionCode is enforced by Android, incrementing both prevents confusion and follows Android best practices.
• versionCode must be a positive integer and strictly greater than the installed version's code. You don't need to increment by exactly 1.

Still need help?

If you've confirmed the version code is higher, the device is online, the Blueprint is correctly published, and the app still isn't updating, contact Esper Support. Provide the device serial number, app package name, old and new version code values, and any relevant device logs.