Version your app (original) (raw)

Versioning is a critical component of your app upgrade and maintenance strategy. Versioning is important because:

The Android system uses your app's version information to protect against downgrades. The system doesn't use app version information to enforce restrictions on upgrades or compatibility of third-party apps. Your app must enforce any version restrictions and tell users about them.

The Android system enforces system version compatibility, as expressed by the minSdk setting in the build files. This setting lets an app specify the minimum system API that it is compatible with. For more information about API requirements, see Specify API level (SDK version) requirements.

Versioning requirements vary between different projects. However, many developers considerSemantic Versioning a good basis for a versioning strategy.

Set app version information

To define the version information for your app, set values for the version settings in the Gradle build files:

Groovy

android {
  namespace 'com.example.testapp'
  compileSdk 33

  defaultConfig {
      applicationId "com.example.testapp"
      minSdk 24
      targetSdk 33
      versionCode 1
      versionName "1.0"
      ...
  }
  ...
}
...

Kotlin

android {
  namespace = "com.example.testapp"
  compileSdk = 33

  defaultConfig {
      applicationId = "com.example.testapp"
      minSdk = 24
      targetSdk = 33
      versionCode = 1
      versionName = "1.0"
      ...
  }
  ...
}
...

Version settings

Define values for both of the version settings available: versionCode andversionName.

versionCode

A positive integer used as an internal version number. This number helps 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 theversionName setting. The Android system uses theversionCode value to protect against downgrades by preventing users from installing an APK with a lower versionCode than the version currently installed on their device.

The value is a positive integer so that other apps can programmatically evaluate it—to check an upgrade or downgrade relationship, for instance. You can set the value to any positive integer. However, make sure that each successive release of your app uses a greater value.

Note: The greatest value Google Play allows forversionCode is 2100000000.

You can't upload an APK to the Play Store with a versionCode you have already used for a previous version.

Note: In some situations, you might want to upload a version of your app with a lower versionCode than the most recent version. For example, if you are publishing multiple APKs, you might have pre-set versionCode ranges for specific APKs. For more about assigning versionCode values for multiple APKs, seeAssigning version codes.

Typically, you release the first version of your app withversionCode set to 1, then monotonically increase the value with each release, regardless of whether the release constitutes a major or minor release. This means that the versionCode value doesn't necessarily resemble the app release version that is visible to the user. Apps and publishing services shouldn't display this version value to users.

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 .. string or as any other type of absolute or relative version identifier. The versionName is the only value displayed to users.

Define version values

You can define default values for these settings by including them in thedefaultConfig {} block, nested inside the android {} block of your module's build.gradle or build.gradle.kts 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 file shows theversionCode and versionName settings in thedefaultConfig {} block, as well as the productFlavors {} block.

These values are then merged into your app's manifest file during the build process.

Groovy

android {
    ...
    defaultConfig {
        ...
        versionCode 2
        versionName "1.1"
    }
    productFlavors {
        demo {
            ...
            versionName "1.1-demo"
        }
        full {
            ...
        }
    }
}

Kotlin

android {
    ...
    defaultConfig {
        ...
        versionCode = 2
        versionName = "1.1"
    }
    productFlavors {
        create("demo") {
            ...
            versionName = "1.1-demo"
        }
        create("full") {
            ...
        }
    }
}

In the defaultConfig {} block of this example, theversionCode 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 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 doesn't define versionName, so it uses the default value of "1.1".

Note: If your app defines the app version directly in the<manifest> element, the version values in the Gradle build file override the settings in the manifest. Additionally, defining these settings in the Gradle build files lets you specify different values for different versions of your app. For greater flexibility and to avoid potential overwriting when the manifest is merged, remove these attributes from the <manifest> element and define your version settings in the Gradle build files instead.

The Android framework provides an API to let you query the system for version information about your app. To obtain version information, use the[ PackageManager.getPackageInfo(java.lang.String, int)](/reference/android/content/pm/PackageManager#getPackageInfo%28java.lang.String,%20android.content.pm.PackageManager.PackageInfoFlags%29) method.

Specify API level (SDK version) requirements

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 or build.gradle.kts 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 lets you specify different values for different versions of your app. For greater flexibility and to avoid potential overwriting when the manifest is merged, 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:

It is not possible to specify that an app either targets or requires a minor SDK version. To call new APIs safely that require a higher major or minor SDK version than your minSdkVersion, you can guard a code block with a check for a minor or major release using theSDK_INT_FULL constant.

if (SDK_INT_FULL >= VERSION_CODES_FULL.[MAJOR or MINOR RELEASE]) { // Use APIs introduced in a major or minor SDK version }

To specify default API level requirements in a build.gradle orbuild.gradle.kts file, add one or more of the API level settings to thedefaultConfig{} 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 file specifies defaultminSdk and targetSdk settings in thedefaultConfig {} block and overrides minSdk for one product flavor:

Groovy

android { ... defaultConfig { ... minSdk 21 targetSdk 33 } productFlavors { main { ... } afterNougat { ... minSdk 24 } } }

Kotlin

android { ... defaultConfig { ... minSdk = 21 targetSdk = 33 } productFlavors { create("main") { ... } create("afterNougat") { ... minSdk = 24 } } }

When preparing to install your app, the system checks the value of these settings and compares them to the system version. If theminSdk value is greater than the system version, the system prevents the installation of the app.

If you don't specify these settings, the system assumes that your app is compatible with all platform versions. This is equivalent to setting minSdk to 1.

For more information, see What is API Level?. For Gradle build settings, see Configure build variants.