Course: Android App Development
Topic: Configuring Application ID, Version Code, and Version Name
Course Link: Android App Development Course
Demo Registration: Register for a Course Demo
Website: JustAcademy
Every Android application needs a unique identifier and a versioning strategy. The application ID identifies the installed app, while the version code and version name help distinguish one release from another.
These values are usually configured in the app module's Gradle build file. Correct configuration is important when installing an app on devices, managing debug and release builds, publishing updates, and maintaining compatibility with an existing Google Play listing.
Android developers commonly work with three important properties:
These properties are generally configured in the defaultConfig block of the app module's build.gradle.kts or build.gradle file. Android Developers: Configure the App Module
The applicationId is a unique identifier assigned to an Android application. It is typically written in reverse-domain notation, such as com.example.shoppingapp.
Android uses this identifier to distinguish one application from another. Google Play also uses it to associate published updates with an existing app listing.
| Application | Example Application ID |
|---|---|
| Shopping application | com.example.shoppingapp |
| Learning application | com.example.learningapp |
| Fitness application | com.example.fitnessapp |
| Company application | com.companyname.businessapp |
These examples are illustrative. For a real application, select an identifier controlled by your organization and ensure it does not conflict with another app you intend to publish.
Important: Changing the application ID after publishing generally causes Android and Google Play to treat the build as a different application. Existing users will not receive it as a normal update to the original listing.
Open the app module's Gradle configuration file in Android Studio. With the Kotlin DSL, the file is usually named app/build.gradle.kts.
android {
namespace = "com.example.shoppingapp"
defaultConfig {
applicationId = "com.example.shoppingapp"
minSdk = 23
targetSdk = 35
versionCode = 1
versionName = "1.0"
}
}
This example illustrates the relevant properties. The SDK values shown are examples; choose SDK versions that are appropriate for the project and its current publishing requirements.
android {
namespace "com.example.shoppingapp"
defaultConfig {
applicationId "com.example.shoppingapp"
minSdk 23
targetSdk 35
versionCode 1
versionName "1.0"
}
}
Use the syntax that matches your project's Gradle file. Do not copy Kotlin DSL syntax directly into a Groovy DSL file or vice versa.
build.gradle.kts or build.gradle.android block.defaultConfig block.applicationId.These terms are related but have different responsibilities. Understanding the distinction prevents mistakes when reorganizing source code or changing an app's identity.
| Term | Purpose | Typical Location |
|---|---|---|
applicationId |
Identifies the installed app and its Google Play listing. | App module Gradle configuration |
namespace |
Defines the namespace used for generated classes such as R. |
App module Gradle configuration |
| Kotlin or Java package | Organizes source code classes and declares their package. | Source files and directory structure |
For straightforward projects, the namespace and application ID often use the same value. They can be different, however, and they serve separate purposes.
android {
namespace = "com.company.shopping"
defaultConfig {
applicationId = "com.company.shoppingapp"
}
}
In this example, generated resource classes use the namespace com.company.shopping, while the installed application is identified as com.company.shoppingapp. Source files must import generated classes from the correct namespace where necessary.
When changing the namespace, review source package declarations and imports. When changing the application ID, carefully consider installation and publishing consequences.
The versionCode is an internal integer that indicates the relative version of an Android application. Android and publishing services use it to determine which version is newer.
Higher version codes represent newer releases. When publishing an update to Google Play, the version code must be higher than the code used by the previously published release for that app.
| Release | Version Code | Purpose |
|---|---|---|
| Initial release | 1 | First published version |
| First update | 2 | Bug fixes and improvements |
| Second update | 3 | New features |
| Major update | 4 | Expanded functionality |
These numbers are only examples. A project may use a different version-code scheme, provided it follows the applicable platform and distribution requirements.
The versionName is a human-readable string that describes the application's version. It is commonly displayed in app information screens, release notes, support documentation, and other user-facing places.
| Version Name | Possible Meaning |
|---|---|
1.0 |
Initial stable release |
1.1 |
Minor improvements |
1.2.0 |
Feature release using a three-part format |
2.0.0 |
Major release |
2.0.0-beta |
Pre-release or beta build |
The version name is a string, so the team can select a suitable naming format. A common approach is semantic versioning: MAJOR.MINOR.PATCH.
This is a versioning convention rather than a mandatory Android rule. Choose a scheme that suits the product and use it consistently.
| Feature | Version Code | Version Name |
|---|---|---|
| Data type | Integer | String |
| Main purpose | Internal version ordering | Human-readable version label |
| Typical example | 12 |
2.1.0 |
| Must increase for each Google Play update? | Yes, for each new upload to the same listing | Not necessarily, though it should reflect the release plan |
| Displayed to users as the version label? | No, not normally | Yes, when the app or store displays it |
defaultConfig {
applicationId = "com.example.shoppingapp"
versionCode = 12
versionName = "2.1.0"
}
In this configuration, the app has internal version code 12 and user-facing version name 2.1.0. The two values do not have to match numerically.
When preparing a new release, developers should review the changes being delivered and update version information according to the project's release policy.
// Initial release
defaultConfig {
versionCode = 1
versionName = "1.0.0"
}
// Later release
defaultConfig {
versionCode = 2
versionName = "1.1.0"
}
// Subsequent bug-fix release
defaultConfig {
versionCode = 3
versionName = "1.1.1"
}
Only one set of these values should be active in the actual configuration at a time unless the project deliberately uses separate flavors or build types. The snippets above illustrate successive release states, not multiple blocks to paste into the same file.
During development, it is often useful to install a debug build alongside the production application. Android does not allow two installed applications to share the same application ID on a device as separate installations.
Gradle allows developers to append an application ID suffix to a build type.
android {
namespace = "com.example.shoppingapp"
defaultConfig {
applicationId = "com.example.shoppingapp"
versionCode = 1
versionName = "1.0"
}
buildTypes {
debug {
applicationIdSuffix = ".debug"
versionNameSuffix = "-debug"
}
release {
// Uses the base application ID and version name.
}
}
}
With this configuration, the debug build uses an application ID such as com.example.shoppingapp.debug and a version name such as 1.0-debug. The release build uses the base application ID and version name.
Remember that a debug build with a different application ID is a different installed app. Its local data is not automatically shared with the production app.
Product flavors allow a project to create different versions of the same application, such as free and premium editions or development and staging builds. Flavors can customize application IDs and version names.
android {
namespace = "com.example.shoppingapp"
defaultConfig {
applicationId = "com.example.shoppingapp"
versionCode = 10
versionName = "2.0.0"
}
flavorDimensions += "edition"
productFlavors {
create("free") {
dimension = "edition"
applicationIdSuffix = ".free"
versionNameSuffix = "-free"
}
create("pro") {
dimension = "edition"
applicationIdSuffix = ".pro"
versionNameSuffix = "-pro"
}
}
}
This example creates different app identities for the free and pro variants. The resulting identifiers are illustrative:
com.example.shoppingapp.freecom.example.shoppingapp.proWhen product flavors and build types are combined, Gradle creates build variants such as freeDebug, freeRelease, proDebug, and proRelease.
Use distinct application IDs only when the variants are intended to install or publish as separate applications. If the intention is to update one existing Play listing, preserve its application ID and follow its versioning requirements.
In modern Android Gradle projects, application identity and version information should generally be configured through the module's Gradle file. During the build, the Android build tools merge the relevant values into the final application package.
For example, the configuration below is usually preferred over manually maintaining version values in the source manifest:
android {
namespace = "com.example.shoppingapp"
defaultConfig {
applicationId = "com.example.shoppingapp"
versionCode = 5
versionName = "1.4.0"
}
}
If the source manifest contains older version attributes, the Gradle configuration takes precedence for the generated app. Avoid maintaining competing definitions because this can create confusion during troubleshooting.
An application may need to display its version name in an About screen or include version details in diagnostic information. On current Android APIs, PackageManager can be used to retrieve package information.
import android.content.Context
import android.content.pm.PackageManager
import android.os.Build
fun getAppVersionName(context: Context): String {
val packageManager = context.packageManager
val packageName = context.packageName
val packageInfo = if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.TIRAMISU) {
packageManager.getPackageInfo(
packageName,
PackageManager.PackageInfoFlags.of(0)
)
} else {
@Suppress("DEPRECATION")
packageManager.getPackageInfo(packageName, 0)
}
return packageInfo.versionName.orEmpty()
}
This function retrieves the installed application's version name. Keep Android API compatibility in mind when accessing package information, and use the appropriate API for the minimum SDK and compile SDK of the project.
val versionName = getAppVersionName(context)
Text(text = "Version $versionName")
The Text example uses Jetpack Compose. In a traditional XML-based application, the version can instead be assigned to a TextView.
Some projects maintain version values directly in Gradle. Larger projects may derive them from a centralized configuration file, a release script, or a CI pipeline. Automation reduces the chance of forgetting to update a version during release preparation.
// app/build.gradle.kts
val appVersionCode = 12
val appVersionName = "2.1.0"
android {
defaultConfig {
applicationId = "com.example.shoppingapp"
versionCode = appVersionCode
versionName = appVersionName
}
}
This example centralizes the values within one Gradle script. A project can also use Gradle properties or another controlled source if the team needs to share version information across modules or automation tools.
| Problem | Possible Cause | Solution |
|---|---|---|
| App installs as a separate application after an update | The application ID changed. | Restore the original application ID if the goal is to update the existing app. |
| Google Play rejects an upload because of its version code | The version code is not higher than the previously uploaded release or has already been used. | Choose an unused, higher version code that complies with current publishing rules. |
| Debug and release builds overwrite one another | Both variants use the same application ID. | Configure a debug application ID suffix if side-by-side installation is required. |
| Version label does not change as expected | The wrong variant is installed or the version name is overridden. | Check the selected build variant, flavor, and version suffix configuration. |
| Gradle sync fails after editing configuration | Incorrect DSL syntax or invalid configuration. | Check whether the file uses Kotlin DSL or Groovy DSL and review the error message. |
| Generated resource imports fail after changing namespace | Source code imports the wrong generated R class. |
Update relevant imports and verify the namespace configuration. |
| Existing users cannot install the intended update | The app identity or signing setup does not match the original release. | Verify the application ID, signing certificate, and distribution configuration. |
| Version information differs across build variants | Flavors or build types override the default values. | Inspect variant-specific Gradle configuration and version suffixes. |
Task: Configure the application identity and version information for a sample Android shopping application.
com.example.shoppingapp.com.example.shoppingapp.1.1.0.0.The application should use the intended identifier and version values. Debug and release variants should behave according to the chosen configuration, and the release version should follow a consistent versioning policy.
Answer: The application ID uniquely identifies an installed Android app and its associated Google Play listing.
Answer: It is normally configured through the applicationId property in the app module's Gradle file, inside defaultConfig.
Answer: The application ID identifies the installed app, while the namespace controls generated class namespaces such as the location of the generated R class.
Answer: Version code is an integer used to determine the relative ordering of application releases. Higher values represent newer releases.
Answer: Version name is a human-readable string that describes the application's release, such as 1.2.0.
Answer: Yes. Version code is an integer used internally, while version name is a string intended to describe the version to people.
Answer: A changed application ID is treated as a different app identity, so it generally cannot update the existing application installation or Google Play listing.
Answer: Give the debug build a different application ID, commonly by setting applicationIdSuffix = ".debug".
Answer: A product flavor defines a variation of an application, such as free and premium editions, and can customize settings including the application ID and version name.
Answer: They are generally maintained in the app module's Gradle configuration or a controlled centralized version source, with Gradle supplying the values to the generated application package.
Configuring the application ID, version code, and version name is an essential part of Android project setup and release management. The application ID defines the app's identity, the version code helps the platform and publishing services distinguish releases, and the version name provides a readable label for users and developers.
By configuring these properties correctly in Gradle, maintaining a consistent versioning strategy, and validating build variants before publication, Android developers can avoid common installation and release errors. A stable application ID and carefully managed version numbers make ongoing updates safer and easier to maintain.
