Each APK for the same application must have a unique version code, specified by the android:versionCode attribute. You must be careful about assigning version codes when publishing multiple APKs, because they must each be different, but in some cases, must or should be defined in a specific order, based on the configurations that each APK supports.
Ordering version codes
An APK that requires a higher API level must usually have a higher version code. For example, if you create two APKs to support different API levels, the APK for the higher API levels must have the higher version code. This ensures that if a device receives a system update that then qualifies it to install the APK for higher API levels, the user receives a notification to update the app. For more information about how this requirement applies, see the section above about Rules for multiple APKs.
You should also consider how the order of version codes might affect which APK your users receive either due to overlap between coverage of different APKs or future changes you might make to your APKs.
For example, if you have different APKs based on screen size, such as one for small – normal and one for large – xlarge, but foresee a time when you will change the APKs to be one for small and one for normal – xlarge, then you should make the version code for the large – xlarge APK be higher. That way, a normal size device will receive the appropriate update when you make the change, because the version code increases from the existing APK to the new APK that now supports the device.
Also, when creating multiple APKs that differ based on support for different OpenGL texture compression formats, be aware that many devices support multiple formats. Because a device receives the APK with the highest version code when there is an overlap in coverage between two APKs, you should order the version codes among your APKs so that the APK with the preferred compression format has the highest version code. For example, you might want to perform separate builds for your app using PVRTC, ATITC, and ETC1 compression formats. If you prefer these formats in this exact order, then the APK that uses PVRTC should have the highest version code, the APK that uses ATITC has a lower version code, and the version with ETC1 has the lowest. Thus, if a device supports both PVRTC and ETC1, it receives the APK with PVRTC, because it has the highest version code.
In case Google Play Store is unable to identify the correct APK to install for a target device, you may want to also create a universal APK that includes resources for all the different device variations you want to support. If you do provide a universal APK, you should assign it the lowest versionCode. Because Google Play Store installs the version of your app that is both compatible with the target device and has the highest versionCode, assigning a lower versionCode to the universal APK ensures that Google Play Store tries to install one of your other APKs before falling back to the larger universal APK.
Using a version code scheme
In order to allow different APKs to update their version codes independent of others (for example, when you fix a bug in only one APK, so don’t need to update all APKs), you should use a scheme for your version codes that provides sufficient room between each APK so that you can increase the code in one without requiring an increase in others. You should also include your actual version name in the code (that is, the user visible version assigned to android:versionName), so that it’s easy for you to associate the version code and version name.
Note: When you increase the version code for an APK, Google Play will prompt users of the previous version to update the application. Thus, to avoid unnecessary updates, you should not increase the version code for APKs that do not actually include changes.
We suggest using a version code with at least 7 digits: integers that represent the supported configurations are in the higher order bits, and the version name (from android:versionName) is in the lower order bits. For example, when the application version name is 3.1.0, version codes for an API level 4 APK and an API level 11 APK would be something like 0400310 and 1100310, respectively. The first two digits are reserved for the API Level (4 and 11, respectively), the middle two digits are for either screen sizes or GL texture formats (not used in these examples), and the last three digits are for the application’s version name (3.1.0). Figure 1 shows two examples that split based on both the platform version (API Level) and screen size.
Figure 1. A suggested scheme for your version codes, using the first two digits for the API Level, the second and third digits for the minimum and maximum screen size (1 – 4 indicating each of the four sizes) or to denote the texture formats and the last three digits for the app version.
This scheme for version codes is just a suggestion for how you should establish a pattern that is scalable as your application evolves. In particular, this scheme doesn’t demonstrate a solution for identifying different texture compression formats. One option might be to define your own table that specifies a different integer to each of the different compression formats your application supports (for example, 1 might correspond to ETC1 and 2 is ATITC, and so on).
You can use any scheme you want, but you should carefully consider how future versions of your application will need to increase their version codes and how devices can receive updates when either the device configuration changes (for example, due to a system update) or when you modify the configuration support for one or several of the APKs.