Versioning is a critical component of your app upgrade and maintenance strategy. Versioning is important because:
The Android system does not use app version information to enforce
restrictions on upgrades, downgrades, or compatibility of third-party apps.
Instead, you are responsible for enforcing version
restrictions within your app or by informing users of the version
restrictions and limitations. The Android system does, however, enforce
system version compatibility as expressed by the minSdkVersion
setting in the build files. This setting allows an app to
specify the minimum system API with which it is compatible. For more
information see Specifying Minimum System API
Version.
To define the version information for your app, set values for the version settings in the Gradle build files. These values are then merged into your app's manifest file during the build process.
Note: If your app defines the app version directly in the
<manifest>
element, the version values in the Gradle build
file will override the settings in the manifest. Additionally, defining these
settings in the Gradle build files allows you to specify different values for
different versions of your app. For greater flexibility and to avoid
potential overwriting when the manifest is merged, you should remove these
attributes from the <manifest>
element and define your
version settings in the Gradle build files instead.
Two settings are available, and you should always define values for both of them:
versionCode
— An integer used as an internal version number.
This number is used only to determine whether one version is more recent
than another, with higher numbers indicating more recent versions. This is
not the version number shown to users; that number is set by the
versionName
setting, below.
The value is an integer so that other apps can programmatically evaluate it, for example to check an upgrade or downgrade relationship. You can set the value to any integer you want, however you should make sure that each successive release of your app uses a greater value. The system does not enforce this behavior, but increasing the value with successive releases is normative.
Typically, you would release the first version of your app with
versionCode
set to 1, then monotonically increase the value
with each release, regardless whether the release constitutes a major or
minor release. This means that the versionCode
value does
not necessarily have a strong resemblance to the app release version that
is visible to the user (see versionName
, below). Apps and
publishing services should not display this version value to users.
Warning: The greatest value Google Play allows for
versionCode
is 2100000000.
versionName
— A string used as the version number shown to
users. This setting can be specified as a raw string or as a reference to a
string resource.
The value is a string so that you can describe the app version as a
<major>.<minor>.<point> string, or as any other type of
absolute or relative version identifier. The versionName
has
no purpose other than to be displayed to users.
You can define default values for these settings by including them in the
defaultConfig {}
block, nested inside the android {}
block of your module's build.gradle
file. You can then override
these default values for different versions of your app by defining separate
values for individual build types or product flavors. The following
build.gradle
file shows the versionCode
and versionName
settings in the defaultConfig {}
block, as well as the productFlavors {}
block.
android { ... defaultConfig { ... versionCode 2 versionName "1.1" } productFlavors { demo { ... versionName "1.1-demo" } full { ... } } }
In the defaultConfig {}
block of this example, the
versionCode
value indicates that the current APK contains the
second release of the app, and the versionName
string specifies
that it will appear to users as version 1.1. This build.gradle
file also defines two product flavors, "demo" and "full." Since the "demo"
product flavor defines versionName
as "1.1-demo", the "demo"
build uses this versionName
instead of the default value. The
"full" product flavor block does not define versionName
, so it
uses the default value of "1.1".
The Android framework provides an API to let you query the system
for version information about your app. To obtain version information,
use the
getPackageInfo(java.lang.String, int)
method of PackageManager
.
Note: When you use
Instant Run, Android Studio
automatically sets the versionCode
to MAXINT
and the
versionName
to "INSTANTRUN"
.
If your app requires a specific minimum version of the Android
platform, you can specify that version requirement as API level settings
in the app's build.gradle
file. During the build process, these
settings are merged into your app's manifest file. Specifying API level
requirements ensures that your app can only be installed on devices that are
running a compatible version of the Android platform.
Note: If you specify API level requirements directly in your
app's manifest file, the corresponding settings in the build files will
override the settings in the manifest file. Additionally, defining these
settings in the Gradle build files allows you to specify different values for
different versions of your app. For greater flexibility and to avoid
potential overwriting when the manifest is merged, you should remove these
attributes from the <uses-sdk>
element and define your API
level settings in the Gradle build files instead.
There are two API level settings available:
minSdkVersion
— The minimum version
of the Android platform on which the app will run, specified
by the platform's API level identifier. targetSdkVersion
— Specifies the API level
on which the app is designed to run. In some cases, this allows the
app to use manifest elements or behaviors defined in the target
API level, rather than being restricted to using only those defined
for the minimum API level.
To specify default API level requirements in a build.gradle
file, add one or more of the settings above to the defaultConfig
{}
block, nested inside the android {}
block. You can
also override these default values for different
versions of your app by adding the settings to build types or product flavors.
The following build.gradle
file specifies default
minSdkVersion
and targetSdkVersion
settings in the
defaultConfig {}
block and overrides minSdkVersion
for one product flavor.
android { ... defaultConfig { ... minSdkVersion 14 targetSdkVersion 24 } productFlavors { main { ... } afterLollipop { ... minSdkVersion 21 } } }
When preparing to install your app, the system checks the value of
these settings and compares them to the system version. If the
minSdkVersion
value is greater than the system version, the
system prevents the installation of the app.
If you do not specify these settings, the system assumes that your app is compatible with all platform versions.
For more information, see the <uses-sdk>
manifest element documentation and the API Levels
document. For Gradle build settings, see Configure Build Variants.