Marketing Version: What It Is, Difference from Build Number, and Configuration

What Is Marketing Version

Marketing Version is a semantic string that represents the application version for the end user. On iOS it is set via the CFBundleShortVersionString key, on Android via versionName.

The term “Marketing Version” is officially used in Xcode: in the target settings interface the field is called “Marketing Version”, and in Info.plist it corresponds to CFBundleShortVersionString. On Android the equivalent is versionName, although the term is used less frequently.

According to Apple Developer Documentation (2025), Marketing Version must consist of at most three numbers separated by dots, without spaces or special characters. Each number must not exceed 255.

Choose your Marketing Version to reflect the significance of changes: major updates for fundamental changes, minor ones for new functionality.

Difference from Internal Build Number

Marketing Version fundamentally differs from Build Number in purpose: the former informs the user, the latter identifies the build for the store. Build Number can increase without changing the Marketing Version.

For example, when fixing a critical bug in a released build, the team can rebuild the application with the same Marketing Version (1.2.0) but an increased Build Number (from 15 to 16). The user will see the same version, but the store will know the build is newer.

This flexibility allows developers to release fixes without notifying users about a version change.

Where Marketing Version Is Displayed

Marketing Version appears in several key touchpoints of user interaction with the application. In the app store, it is visible in the app card, update description, and version history.

On the device, Marketing Version is shown in system settings (the “About” or “Apps” section), in update dialogs via App Store or Google Play, and inside the app itself on the “About” screen.

A clear Marketing Version helps users evaluate the relevance of their installed version and make an update decision.

Marketing Version on iOS

On iOS, Marketing Version is set in Xcode via the “Marketing Version” field on the General tab of target settings. The value is saved in Info.plist as CFBundleShortVersionString.

The version format is strictly regulated by Apple: the string must contain between one and three numbers separated by dots (e.g., 1, 1.2, or 1.2.3). The maximum length is 18 characters. Each number must not exceed 255.

According to Apple App Store Review Guidelines (2025), App Store Connect does not allow uploading a build if the Marketing Version differs from the previous published version by more than one major or minor value — this protects users from missed updates.

Use agvtool to manage Marketing Version from the command line — it simplifies CI/CD integration and guarantees synchronization with Build Number.

Marketing Version on Android

On Android, Marketing Version is set via the versionName parameter in the build.gradle file. Unlike iOS, Android does not impose strict restrictions on the version string format.

versionName can contain any characters: letters, digits, hyphens, and dots. Google Play displays this string in the app card and in the update list, but does not validate it against any pattern.

However, Google Play recommends sticking to the semantic Major.Minor.Patch format for consistency. This makes it easier for users to understand the version and enables automated update analysis.

Set a versionName that clearly reflects the release type — major, minor, or patch. This helps users quickly assess the significance of changes.

Dynamic versionName Generation

versionName on Android can be generated dynamically based on Git tags or CI/CD variables. This simplifies the versioning process and eliminates discrepancies between the repository and the build.

A typical approach is reading a Git tag (e.g., v2.1.0) and using its value as versionName. If the tag is absent, a version can be generated based on the date and commit number.

This approach guarantees that versionName always matches the source code state and does not require manual updates.

Marketing Version vs Build Number

Marketing Version and Build Number are two independent parameters that serve different purposes. Marketing Version informs the user, while Build Number technically identifies the build.

The key difference is uniqueness. Build Number must be unique for each build. Marketing Version can repeat: multiple builds of the same version share the same Marketing Version but have different Build Numbers.

According to Google Play Policy (2025), if you upload two APKs with the same Marketing Version but different Build Numbers, Google Play accepts both as different builds of the same version. The same rule applies to the App Store.

Remember: Build Number is for machines, Marketing Version is for people. Automate the former and carefully plan the latter.

Versioning Strategies

Choosing a strategy depends on the application type, audience, and release process. Three main schemes — semantic, calendar, and hybrid — cover most scenarios.

Semantic Versioning (SemVer) uses the Major.Minor.Patch format and strictly defines when each component should be incremented. It is ideal for applications with a public API and complex integration.

According to semver.org (2023), version 2.0.0 of the SemVer specification is used in 89% of open-source mobile projects and is supported by all package managers.

Calendar Versioning

Calendar Versioning (CalVer) uses the release date as the version — for example, 25.06 for June 2025. This approach is popular in applications with frequent updates.

CalVer does not convey information about the significance of changes but clearly shows the freshness of the version. Users immediately understand that version 25.06 is newer than 25.03.

Choose calendar versioning if your app updates frequently and users care more about data freshness than the scope of changes.

Selection Recommendations

For MVPs and startups, a simple semantic version without patch (Major.Minor) works well. For mature products with long-term support — full SemVer. For apps with continuous releases — CalVer.

Never use the date as the Build Number — this can lead to conflicts with multiple builds per day. Build Number should be sequential or composite but always monotonically increasing.

Common Marketing Version Mistakes

A typical mistake is skipping a version component when moving to a new major line. For example, after version 1.9.9, the next should be 2.0.0, not 1.10.0. This breaks semantics and confuses users.

Another common issue is a mismatch between the Marketing Version in code and in the app store. Always verify that versionName in build.gradle matches the version specified in Google Play Console or App Store Connect before submitting a build for review.

Marketing Version Setup Examples

Code examples show how to set Marketing Version on both platforms and automate its updates.

Setting versionName in Android Gradle

In Android, versionName is set in build.gradle. The value can be static or read from an environment variable.

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

// Reading version from Git tag
def getVersionNameFromGit = {
    def tag = "git describe --tags".execute().
        text.trim()
    return tag.startsWith("v") ? tag.substring(1) : tag
}

versionName is extracted from a Git tag, ensuring alignment between the repository version and the built application.

Managing Marketing Version in Xcode

On iOS, Marketing Version is set via Xcode or agvtool. The command below sets a new marketing version.

# Setting Marketing Version
xcrun agvtool new-marketing-version 2.1.0

# Auto increment
xcrun agvtool next-marketing-version

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

Fastlane for Both Platforms

Fastlane allows managing Marketing Version on both platforms from a single script, simplifying cross-platform project maintenance.

# Setting marketing version
increment_version_number(
    version_number: "2.1.0"
)

# Auto increment of minor version
increment_version_number(
    bump_type: "minor"
)

Fastlane works on both platforms and is supported by most CI/CD services.