Android package version code

Android NDK: Version code scheme for publishing APKs per architecture

Distributing native libraries with your APK adds complexity to your build process and can bloat the size of your APK. You have to include a specific build of native libraries for every architecture you want to target, or to be more technically correct every ABI (Application Binary Interface) you are targeting. Different Android devices use different CPU’s architecture, which have support for different instruction sets. An ABI is different for each combination of CPU and the instruction set supported.

The recommended distribution method for your APK is to distribute one APK that contains all the static native libraries for all the ABIs being targeted. This article does not follow that path and discusses how to build, upload and manage separate APKs for your app. Each APK will include only the native libraries for a specific ABI. The following assumptions are made:

• You are using Android Studio 1.2+ and using the Android gradle plugin build system
• You are distributing your app through the Google Play store
• You already have static native libraries (.so) built with the Android NDK
• You are concerned about APK bloat caused by these native libraries

Universal APK or Multiple APKs

You need to make an educated and considered decision about if you distribute one APK that includes all native libraries or multiple APKs. The advantage of one universal APK is that it is simple to deploy and maintain your app, the disadvantage is that you potentially could have a substantial increase in APK size. I have previously described how to use SQLCipher in an Android app which discussed this tradeoff. Figure 1, below, shows the impact on size when shipping SQLCipher native libraries in a basic APK.

Figure 1: Size increase when including SQLCipher

Play Store requirement for unique versionCode per ABI

The only way for a developer to distribute an app, with different APKs, to users on different devices is to have a unique versionCode and to ensure each APK is targeting different devices. The versionCode needs to be unique as it is possible that a users device is compatible with more than one APK, when this happens they will receive the version with the highest versionCode.

When I mention the version I am not referring to the version that is visible to the user, which is specified as the versionName, I am talking about the internal version which is a numerical versionCode that indicates an ascending order of releases. The snippet from a build.grade script below shows the default versionCode and versionName that Android Studio will apply to a new project.

It is possible that you are maintaining existing apps which only specify the version in the AndroidManifest.xml. While this works well for static version information we need to use the new Android Gradle build system to be able to dynamically generate version information. Here is an example of version information added directly into the AndroidManifest.xml.

Format for individual versionCodes per ABI

Each ABI needs to have an unique versionCode before it can be uploaded to the play store. We are going alter the build.gradle file to automatically generate a unique version number for each ABI. Assuming we want to build our app with versionCode 101, Our aim is to produce the following results:

Figure 2: Example versionCode values for each ABI

The order of the ABI numbers are important as is the length of the 8 digit versionCode.

The order is based on way the Play store works with multiple APKs. Remember, if a users device is compatible with more than one APK for an application the device will receive the version with the highest version code. This is why an armeabi build will be given a prefix of 1 as this build will also be able to run a armeabi-v7a device (2) and in some cases a x86 device (8) due to a proprietary ARM translation layer called libhoudini.

The versionCode we are going to generate is 8 digits long to cater for multiple APKs that differ not only by target ABI, but also different Android SDK versions and screen sizes. An example of how to incorporate all these details into the 8 digit versionCode is shown in Figure 3 below. This is an extension of a numbering scheme suggested in the Android developer documentation where we prefix the number with the ABI id value that was listed in Figure 2.

Figure 3: Android versionCode suggested format reference

You should be aware that this is only a suggested method for generating version information. It is not mandatory and it can be tailored to me your needs. For example, if you know that you are not going to distribute different APKs based on Android SDK API level then you could drop those two digits from the version.

Automating unique versionCode generation

Before continuing and changing your versionCode naming convention you need to understand the following:

If you are distributing one APK containing all flavors of native libraries then you do not need to worry about implementing the following version scheme.

To automate the version process we need to customize the build process. The build.gradle script for your app is where you can configure the build to produce a separate APK for each ABI type and also set the versionCode to conform with the desired 8 digit format discussed earlier.

Here is an example of a complete build.gradle that will achieve this:

Building separate APK files

The splits mechanism for the Android Gradle Plugin allows you to generate multiple files as shown by the example below. You can include only the ABI types you want to build and it is also possible to build an APK that includes all possible native libraries through the command universalApk true.

Generate versionCode per APK

The section of the build script that sets the versionCode of each APK to a unique number is shown in the code snippet below. Note the project.ext.versionCodes which sets the first digit of the versionCode when multiplied by 10000000 we generate the 8 digit number we require. Finally the initial versionCode of the app, accessed with android.defaultConfig.versionCode, is added to complete the full numerical version for each APK.

Verify the versionCode included in each APK

The Android Asset Packaging Tool (aapt) is part of the Android build tools and is required to build APK files. You can also use it to verify the contents of the APK files you have generated.

You will find the aapt executable in your latest version of the build tools, for example ..\sdk\build-tools\22.0.1

Execute the following command on each of the APKs you have produced:

You will find a wealth of information about the APK but the following items in the output will be of most interest:

Below is a more detailed, but still trimmed sample output from the aapt badging request:

This same dump can be also used to verify other attributes of your APK, such as the build SDK version, locales and supported screen densities.

You will also be able to verify the targeted ABI and versionCode once you upload to the Play Store via the developer console.

Distribution of multiple APKs via alternative app stores

This article has assumed that you are distributing your app through the Google Play Store. It may be possible that you are using multiple distribution methods, such as promoting your app on the Amazon Appstore. According to the documentation the same version methodology will work for the multiple APK support within the Amazon Appstore. There are also a number of smaller app marketplaces that may automatically add your app. Each of these app store may or may not handle multiple APKs correctly which may result in some users downloading an APK that is incompatible with their device.

References

Multiple APK support in Android

Android apk-splits user-guide

Источник

Android package version code

В статье приведен перевод статей [1, 2], посвященных управлению версиями приложения Android, и работе приложения на разных версиях операционной системы Android. Все непонятные термины и сокращения ищите в Словарике [3].

Управление версией приложения является критически важным аспектом для обновления приложения и для стратегии его поддержки в будущем. Это важно потому что:

• Пользователям нужна соответствующая информация о версии приложения, которая установлена на их устройствах, и о доступности обновлений версии приложения для существующей инсталляции.
• Другие приложения — включая другие приложения, которые Вы публикуете в как комплект приложений — нуждаются в опросе системы для версии Вашего приложения, чтобы определить совместимость и идентифицировать зависимости (от API и библиотек).
• Сервисы, через которые Вы публикуете приложение (или приложения) могут также нуждаться в опросе Вашего приложения на его версию, чтобы можно было отобразить эту версию для пользователей. Сервис публикации может также нуждаться в проверки версии приложения, чтобы определить совместимость и установить взаимосвязи для апгрейда или довнгрейда.

Система Android не использует информацию об версии приложения для принудительного ограничения на апгрейд, довнгрейд, или на ограничение совместимости приложений сторонних производителей. Вместо этого Вы (как разработчик) отвечаете за ограничения, связанные с версиями приложения, или за информирование об этом пользователей. Однако система Android обеспечивает совместимость приложения с системой в соответствии с атрибутом minSdkVersion, который указан в манифесте. Этот атрибут позволяет приложению указать минимальный уровень системного API, с которым совместимо приложение. Дополнительную информацию см. ниже android:minSdkVersion в разделе «Как указать требования приложения к уровню (версии) API Android».

[Установка версии приложения (Application Version)]

Чтобы задать информацию о версии для Вашего приложения, нужно установить атрибуты в файле манифеста приложения (AndroidManifest.xml, секция manifest). Доступно 2 атрибута, для которых обязательно нужно назначить значения:

• android:versionCode — целое число, которое представляет версию кода приложения относительно других версий. Значение целого числа установлено так, чтобы другие приложения могли программно вычислить его, например для проверки взаимосвязи апгрейда или довнгрейда. Вы можете установить значение в любое целое число, какое захотите, однако нужно помнить, что обновленное приложение должно иметь последовательно увеличенный номер версии. Система не принуждает к такому поведению, однако увеличение номера версии с новым релизом является нормой.

Обычно Вы должны сделать первый релиз приложения с versionCode установленным в 1, и затем монотонно увеличивать это значение с каждым новым релизом, независимо от статуса, который имеет релиз: major или minor. Это не означает, что значение атрибута android:versionCode должно быть строго подобно версии релиза, которую видит пользователь (см. далее атрибут android:versionName). Приложения и сервисы публикации приложений не должны отображать значение атрибута android:versionCode для пользователей.

• android:versionName — строковое значение, которое представляет версию релиза кода приложения, которая должна быть показана пользователям.

Значение является строкой, в которой Вы можете описать версию приложения как . . , или любым другим способом, выражая текстовым идентификатором абсолютную или относительную версию приложения.

Как и атрибут android:versionCode, система Android не использует android:versionName для внутреннего использования, кроме того как отобразить это значение для пользователей. Сервисы публикации приложений могут также прочитать значение android:versionName для того, чтобы отобразить её для пользователей.

Оба этих элемента нужно задать в секции файла манифеста приложения. Пример:

Обратите внимание, что в этом примере android:versionCode показывает, что текущий файл .apk содержит второй релиз кода приложения, который соответствует минорной последующей версии релиза 1, как показано в строке android:versionName.

Рабочее окружение Android предоставляет API, позволяющее приложениям опросить систему для получения информации версии приложения. Чтобы получить информацию версии, приложения используют метод getPackageInfo(java.lang.String, int) объекта PackageManager.

[Как указать требования приложения к уровню (версии) API Android]

Если Ваше приложение требует определенную минимальную версию платформы Android, где приложение должно работать, или если приложение разработано для поддержки определенного диапазона версий платформ Android, то Вы можете указать эти требования к версиям в виде идентификаторов API Level в файле манифеста приложения. Если сделать так, то это обеспечит то, что Ваше приложение может быть установлено только на устройствах, на которых работает совместимая версия системы Android.

Чтобы указать требования к API Level, добавьте тег в файл манифеста приложения, и укажите в нем один или несколько этих атрибутов:

• android:minSdkVersion — минимальное значение версии платформы Android, на которой приложение будет работать. Значение версии указано в виде цифрового идентификатора API Level.
• android:targetSdkVersion — указывает число API Level, для которого приложение разработано. В некоторых случаях это позволит приложению использовать элементы манифеста и определять поведение по заданному уровню целевого API Level, вместо того, чтобы ограничиваться использованием только определенного минимального уровня API Level.
• android:maxSdkVersion — максимальное значение версии платформы Android, на котором приложение может работать. Внимательно прочтите документацию по секции (см. далее) перед использованием этого атрибута.

При подготовке к установке приложения система проверяет эти атрибуты и сравнивает их с версией системы. Если значение android:minSdkVersion больше версии системы, то установка приложения будет прервана. Точно также система установить Ваше приложение только в том случае, если android:maxSdkVersion совместим с версией платформы.

Если Вы не укажете эти атрибуты в манифесте, то система предположит, что Ваше приложение совместимо со всеми версиями платформы, и также нет ограничения на максимальный API Level.

Чтобы указать минимальную требуемую версию платформы для Вашего приложения, добавьте секцию дочерней к секции , и затем добавьте атрибут android:minSdkVersion и его значение.

[Подробнее о секции манифеста ]

Секция uses-sdk появилась начиная с API Level 1 (т. е. сразу, начиная с самых старых версий Android). Синтаксис секции следующий:

Секция uses-sdk позволяет Вам выражать совместимость приложения Android с одной или большим количеством версий платформ (операционных систем) Android. Эта совместимость определяется посредством чисел API Level, которая указывается в атрибутах секции minSdkVersion, targetSdkVersion, maxSdkVersion. Версия платформы может (которая соответствует определенному числу API Level) может различаться на разных устройствах Android. Указанные API Level, представленные приложением в этой секции, сравниваются с API Level системы, на которой работает (или устанавливается) приложение, и на основе этого сравнения принимаются определенные решения по инсталляции программы или её работе.

Несмотря на имя секции uses-sdk, эта секция на самом деле используется для определения API Level, но не номер версии SDK платформы Android. API Level всегда задается одиночным целым числом. Вы не можете получить из связанной с ним текстовой версии Android, кроме как получить такое соответствие из таблицы API Level (см. [4]). К примеру, API level 16 относится к версиям Android 4.1, Android 4.1.1, Android 4.1.2. Теперь рассмотрим назначение атрибутов minSdkVersion, targetSdkVersion, maxSdkVersion.

android:minSdkVersion число, обозначающее минимальный API Level, который требуется для установки, запуска и работы приложения. Система Android не позволит пользователю установить приложение, если API Level системы меньше значения, указанного в этом атрибуте. Вы всегда должны указывать этот атрибут в секции uses-sdk файла AndroidManifest.xml.

Предостережение: если Вы не укажете этот атрибут, то система предположит его значение по умолчанию «1», что означает совместимость Вашего приложения со всеми без исключения версиями операционной системы Android. Если Ваше приложение несовместимо со всеми версиями (например, оно использует API, представленное впервые на API Level 3), и Вы не укажете правильно minSdkVersion, то при установке на систему с уровнем API Level меньше 3 приложение будет завершаться с ошибкой при попытке доступа к недоступному API. По этой причине обязательно объявляйте подходящий API Level в атрибуте minSdkVersion.

android:targetSdkVersion этот атрибут представлен начиная с API Level 4. Это целое число, обозначающее API Level, для которого приложение предназначено (target, что означает цель). Если этот атрибут не установлен, то его значение по умолчанию равно minSdkVersion.

Этот атрибут информирует систему, что Вы тестировали приложение с этим API Level, и система не должна позволять любое поведение совместимости (compatibility behaviors, т. е. эмуляцию вызовов API, обеспечивающих специальную дополнительную программную обработку некоторых вызовов API), чтобы поддержать прямую совместимость приложения с целевой версией системы. Приложение все еще может работать на более старых версиях (до версий, не меньших minSdkVersion).

Поскольку Android развивается с каждой новой версией, то некоторые поведения и даже внешний вид приложения может измениться. Однако, если API level платформы выше, чем версия, указанная в targetSdkVersion приложения, система может включить обработки совместимости (compatibility behaviors), чтобы обеспечить работоспособность Вашего приложения так, как Вы этого ожидали. Вы можете запретить такие обработки совместимости, если укажете targetSdkVersion равным API level платформы Android, на которой приложение работает. Например, установка этого значения в «11» или более высокое значение позволит системе установить новую тему оформления по умолчанию (Holo) для Вашего приложения при работе на Android 3.0 или более новой, и также запретит режим совместимости экрана, когда программа будет работать на больших экранах (потому что поддержка API level 11 неявно подразумевает поддержку больших экранов).

Имеется много разновидностей обеспечения совместимости (compatibility behaviors), которые система может разрешить, базируясь на значении этого атрибута. Некоторые из этих обработок (поведений, behaviors) описаны в соответствующей документации версии платформы, см. Build.VERSION_CODES.

Чтобы обеспечить соответствие Вашего приложения каждому новому релизу Android, Вы должны увеличивать значение этого атрибута, чтобы оно соответствовало последнему API level, и затем необходимо полностью протестировать поведение приложения на этой новой версии платформы.

android:maxSdkVersion этот атрибут представлен начиная с API Level 4. Это целое число, обозначающее максимальный API Level, на котором приложение может работать.

На версиях Android 1.5, 1.6, 2.0 и 2.0.1 система проверяет значение этого атрибута, когда инсталлируется приложение, и когда приложение проверяется на совместимость после обновления системы. В любом случае, если атрибут приложения maxSdkVersion меньше API Level системы, то установка приложения будет запрещена. При проверке приложения на совместимость после обновления системы такой случай соответствует полному удалению приложения с устройства. Для иллюстрации того, как этот атрибут может повлиять на приложение после обновления системы, рассмотрим пример.

Приложение декларировало maxSdkVersion=»5″ в своем манифесте, и было опубликовано на Google Play. Пользователь устройства Android 1.6 (API Level 4) загрузил и установил это приложение. После нескольких недель пользователь принял сообщение от системы over-the-air с предложением обновить систему до уровня Android 2.0 (API Level 5). После установки этого обновления система проверила атрибут приложения maxSdkVersion, и разрешила дальнейшее использование этого приложения. Приложение после этого работало нормально. Однако через некоторое время устройство приняло другое обновление системы Android 2.0.1 (API Level 6). После обновления система не разрешает работу приложения, так как API Level системы (6) теперь выше, чем максимальный уровень, который может поддержать приложение (5). Система делает приложение невидимым для пользователя, и удаляет его из устройства.

Предупреждение: использование этого атрибута не рекомендуется. Во-первых, нет никакой потребности установить этот атрибут как средство блокирования развертывания Вашего приложения на новые версии платформы Android по мере их появления. Для Android декларируется полная обратная совместимость старых приложений для новых версий Android. Ваше приложение должно работать должным образом на всех новых версиях, если оно использует только стандартное API и следует лучшим правилам и практикам разработки. Во-вторых нужно помнить, что применение этого атрибута приведет к автоматическому удалению Вашего приложения с устройств пользователя, которые обновят свою систему на более высокий API Level, чем указано в атрибуте. Большинство устройств, на которых вероятно будет установлено Ваше приложение, получают периодические обновления системы на лету, по воздуху (over the air), так что Вы должны учитывать этот эффект перед тем, как установить этот атрибут для своего приложения.

Будущие версии Android (вне Android 2.0.1) больше не будут проверять maxSdkVersion и принудительно применять его значение при установке или проверке совместимости приложения. Однако Google Play продолжит использовать этот атрибут как фильтр при предоставлении приложений, доступных для закачки пользователям.

[Пример установки версии приложения при создании проекта в Eclipse]

В Eclipse при создании проекта запускается мастер, который на первом экране позволяет настроить параметры, касающиеся версии приложения.

Поле Minimum Required SDK определяет значение атрибута android:minSdkVersion будущего приложения. Здесь желательно указать версию достаточно популярной платформы, которая возможно уже несколько устарела.

Поле Target SDK задает атрибут android:targetSdkVersion. Укажите здесь версию системы, с которой Вы тестировали Ваше приложение. К примеру, Вы отлаживаете программу на версии Android 4.1.2, тогда в выпадающем списке Target SDK нужно выбрать API 16: Android 4.1 (Jelly Bean).

Поле Compile With задает версию SDK, на котором Ваше приложение будет скомпилировано. Задайте здесь максимальную (самую свежую) на текущий момент версию системы Android.

Источник