Version Name: Essence, Parameter Meaning, and Setup

What is Version Name

Version Name is a semantic string that identifies the application release for the user. Unlike technical build identifiers, this parameter carries meaningful information: users can evaluate how much a new update differs from the previous one.

Version Name is displayed in the app card on Google Play and the App Store, in the "About app" section on the device, and in system update dialogs. Developers specify it in project configuration files before building the release version.

According to Semantic Versioning 2.0 (2023), the Major.Minor.Patch format is used in 78% of mobile applications. The major version changes with incompatible API changes, the minor version with new functionality, and the patch with bug fixes.

Use Version Name to communicate with the user: they should immediately understand how significant the offered update is — major, minor, or corrective.

Semantic Version Structure

Semantic version consists of three numbers separated by dots: Major.Minor.Patch. Each component is responsible for a specific level of changes in the application.

The major version (Major) increments when breaking changes are introduced. The minor version (Minor) adds new functionality without breaking existing features. The patch (Patch) contains only bug fixes.

For example, version 3.2.1 means: third major version, second minor update, first patch. This system is understandable for both developers and users.

Where Version Name is Displayed

Version Name is visible to the user in several key places. In the app store, it appears in the app card header and in the update list. On the device, it appears in system settings under "About app".

On Google Play, Version Name is shown below the app name and influences the user's decision to update. In the App Store, the version string is displayed in the same place when viewing the app page.

According to Apptentive (2024) research, 67% of users check the app version before updating, and clear semantics increase install conversion by 23%.

Version Name on Android

On Android, Version Name is set by the versionName parameter in the build.gradle file (module level). This parameter is a string and can contain any characters, including dots, hyphens, and letters.

The parameter is declared inside the android.defaultConfig block along with the required versionCode parameter. Android does not impose restrictions on the string format, but Google Play recommends using the semantic format.

According to Android Developers (2025), Google Play uses versionName for display in the store interface but does not analyze its content programmatically — only versionCode affects the update logic.

Specify Version Name in the Major.Minor.Patch format and synchronize it with the tag in the version control system for unambiguous release identification.

versionName Features in Gradle

Gradle allows setting versionName statically in build.gradle or dynamically through build scripts. Dynamic generation is useful for automatic nightly builds and CI/CD pipelines.

In build.gradle, you can use environment variables, command-line parameters, or shell script calls to form versionName. A typical approach is reading the version from a version.properties file.

This flexibility allows teams to automate the versioning process and eliminate human error during release preparation.

Version Name on iOS

On iOS, Version Name is set by the CFBundleShortVersionString key in the Info.plist file. This is a required parameter for publishing an app on the App Store, and it is strictly typed as a string.

Unlike Android, App Store Connect checks the Version Name format and requires it to match a template of numbers separated by dots. The maximum string length is 18 characters, and each version component cannot exceed 255.

According to Apple Developer Documentation (2025), CFBundleShortVersionString is used by the App Store to display the version in the store interface and in system dialogs on the user's device.

When uploading a build to App Store Connect, ensure Version Name matches the version specified in marketing materials — this simplifies communication with users.

Integration with Xcode

Xcode provides a graphical interface for changing Version Name in the target settings. The "Marketing Version" field is located on the General tab under Identity. Changes are automatically saved to Info.plist.

For automation, you can use build scripts in Xcode Build Phases or the agvtool (Apple Generic Version Tool). agvtool allows managing versions from the command line and integrates into CI/CD.

This approach is especially convenient when using fastlane or Jenkins for automatic build and delivery of applications.

Differences Between Version Name and Build Number

Version Name and Build Number serve different purposes in the development process. Version Name is a user-facing string, while Build Number is an internal numeric identifier that uniquely identifies each build.

Build Number (versionCode in Android, CFBundleVersion in iOS) must increase with each new build and is used by app stores to determine which version is newer. Version Name can remain unchanged across multiple builds of the same version.

According to Google Play Policy (2025), two apps with the same versionCode are considered the same version — versionCode must be unique for each APK. Version Name is not involved in this check.

Always increment Build Number with every build and change Version Name only when functionality changes — this prevents conflicts during publishing.

How to Choose Version Name

Choosing Version Name depends on the team's versioning strategy. The most common approach is semantic versioning (SemVer), but alternative schemes exist, such as calendar versioning or release-date versioning.

Semantic Versioning 2.0 recommends the Major.Minor.Patch format with optional pre-release suffixes. For mobile apps, the Major.Minor scheme is also popular, where the patch version is omitted for simplicity.

Calendar versioning (CalVer) uses the release date as the version number — for example, 25.06 (year and month). This approach is convenient for apps with frequent releases where semantics are not meaningful.

Recommendations for Choosing a Scheme

Semantic versioning is suitable for apps with a public API where backward compatibility is important. Users and integrators understand what changes to expect with updates.

Calendar versioning is chosen for apps where the freshness of the release matters more than the scope of changes. For example, news aggregators or weather apps.

Hybrid scheme combines both approaches: Major.Minor.RC, where RC is the build number for a specific release candidate. This scheme is convenient during active beta testing.

Version Name Configuration Examples

Code examples below show how to set Version Name on Android and iOS. For Android, Gradle is used; for iOS, Xcode Build Settings with agvtool.

Setting versionName in Android

In Android, the version is set in the app/build.gradle file inside the defaultConfig block. The versionName parameter accepts a string value.

android {
    defaultConfig {
        versionCode 3
        versionName "2.1.0"
    }
}

versionName can also be read from an external file or generated dynamically using Gradle Script.

Dynamic versionName Generation

Dynamic version is formed from the CI/CD system environment variables. This ensures each build receives the correct version number.

def getVersionName = {
    return System.getenv("VERSION_NAME") ?:
            "2.1.0"
}

android {
    defaultConfig {
        versionName getVersionName()
    }
}

This approach automates versioning and eliminates the risk of mismatch between the build and the repository tag.

Setting CFBundleShortVersionString in iOS

In iOS, the version can be set through Xcode or via the command line using agvtool.

# Setting the marketing version
xcrun agvtool new-marketing-version 2.1.0

# Reading the current version
xcrun agvtool what-marketing-version

agvtool automatically updates Info.plist and synchronizes the version across all targets in the Xcode project.