Understanding Mobile App Versioning

Dealing with app versioning is an essential aspect of the mobile app development and release lifecycle. Both Android and iOS have distinct approaches to app versioning, which can often be confusing.

In this blog post, we will explore the nuances of app versioning for both platforms, helping you better understand their differences and similarities.

On Android, versioning comprises two components: the version code and version name.

• Version code: a non-user-facing integer value that represents the app's version, used internally. When uploading a build, you must increment the version code, ensuring the new version code is higher than the previous one. This allows the Android operating system and app stores to recognize app updates.
• Version name: a user-friendly string value that displays your app's version. Users can see this information in the Google Play Store and their device settings. Although you can follow any convention for version names, common practices include using three integers in the major, minor, and patch format (e.g., 2.0.1) called Semantic Versioning or the date format YYYY.MM.DD (e.g., 2023.04.26) called Calendar Versioning.

To manage versionCode and versionName in a typical Android app, update the app's build.gradle file:

android {
    defaultConfig {
        versionCode 42
        versionName "2.0.1"
    }
}

Depending on the app's configuration or frameworks used, you may need to update the versionCode and versionName in a different file. For instance, if you're using Flutter, you'll need to update the version in pubspec.yaml or if you are using Expo, you'll need to update the version in app.json.

On iOS, versioning also consists of two components: the build number and version name.

• Build number: a non-user-facing string value that represents the internal build version of your app. It technically follows the same major, minor, and patch format but only the major is required so in practice it can be a single integer (eg: 42). It should be incremented for each build uploaded to the App Store or TestFlight. The build number is set in the Info.plist file under the key CFBundleVersion. It can reset to 0 for each new version name.
• Version name: a user-facing string value that follows the same major, minor, and patch format (e.g., 2.0.1). It's similar to Android's version name and is visible to users in the app store and device settings. Historically, the version name is set in the Info.plist file under the key CFBundleShortVersionString. Using the date format YYYY.MM.DD (eg: 2023.04.26) is another common convention for version names.

To manage CFBundleShortVersionString and CFBundleVersion in a typical iOS app, update the app's Info.plist file:

<key>CFBundleShortVersionString</key>
<string>2.0.1</string>
<key>CFBundleVersion</key>
<string>42</string>

Depending on the app configuration or frameworks used, you may need to update the CFBundleShortVersionString and CFBundleVersion in a different file. For example, apps after Xcode 13 no longer have an Info.plist by default and require either re-creating this file or using the Xcode UI to change the version in project.pbxproj.

While both Android and iOS versioning systems have two components, there are some differences to be aware of:

• Value types: Android's version code is an integer, while its version name is a string. In contrast, both the version name and build number in iOS are strings.
• Version code/Build number: Both Android's version code and iOS's build number must be incremented for each new build uploaded. However, Android's version code must increment forever, while iOS's build number can reset to 0 for each new version name. This means that the build number can be reused for each new version name, but the version code cannot.
  • Note: The greatest value Google Play allows for versionCode is 2100000000.
• Version names: In both Android and iOS, the version name is user-facing and follows the same major, minor, and patch format. However, in Android, the version name can follow any format, whereas in iOS, the version name must follow the major, minor, and patch format (which the date format technically follows).

In Wolfia, we use the following terms and definitions to generally refer to versioning on both Android and iOS.

• App version: major, minor, and patch format (e.g., 2.0.1). While Android doesn't have to follow this format, adhering to it on both platforms makes it predictable and easy to compare.
• App build: unique build identifier (e.g., 42). While iOS can reuse the same build identifier for each new version, conceptually they serve the same purpose.

Keep in mind the differences above still apply, but having a shared vocabulary for versioning can be useful when releasing multi-platform projects.

Let's assume that you are about to release an update to your app on both platforms. The current app version is 2.0.1, with app build of 42.

For Android, you would increment both the versionCode and versionName in your build.gradle file:

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

Here, we incremented the versionCode from 42 to 43 and updated the versionName from 2.0.1 to 2.1.0. Note that the versionCode must be incremented forever, so you cannot reuse the same versionCode for each new versionName.

For iOS, you would increment both the CFBundleVersion and CFBundleShortVersionString in your Info.plist file:

<key>CFBundleShortVersionString</key>
<string>2.1.0</string>
<key>CFBundleVersion</key>
<string>0</string>

Here, we updated the CFBundleVersion from 42 to 0 and the CFBundleShortVersionString from 2.0.0 to 2.1.0. Note that the CFBundleVersion can also be incremented for each new CFBundleShortVersionString instead of resetting to 0.

By following these steps, you can ensure that your app is properly incremented on both platforms, allowing for accurate version tracking and streamlined updates.

Understanding the differences between Android and iOS versioning systems can be useful for mobile engineers, particularly for those working on cross-platform projects.

Wolfia manages version bumping for both Android and iOS, so you don't have to worry about it!