Increment Rules for iOS App Version and Build Numbers on App Store Release

Core Concepts of iOS App Version and Build Numbers

In iOS app development, version management involves two key fields: CFBundleShortVersionString (commonly referred to as the version number) and CFBundleVersion (the build number). The version number identifies the release version of the app, typically following a major.minor.patch format (e.g., 1.2.3), and is displayed to users in the App Store. The build number distinguishes different build iterations under the same version, primarily used for internal tracking and update mechanisms.

According to Apple's official Technical Note TN2420, these fields must adhere to strict increment rules. The version number must increase with each new release and cannot be reused. The build number must increase with each new build submission but can be reused across different release trains (except for macOS apps). For example, a valid sequence could be (1.0.0, 1) → (1.0.0, 2) → (1.0.1, 1), where the build number restarts from 1 in version 1.0.1.

Specific Requirements for Increment Rules

The combination of version and build numbers must remain unique. This means that even if the build number is the same, as long as the version number differs, the entire combination is valid. For instance, (1.0.1, 12) → (1.0.1, 13) → (1.0.2, 13) is a legal sequence because the version number increases from 1.0.1 to 1.0.2, while the build number remains unchanged in version 1.0.2.

In practice, developers need to ensure:

1. With each new release, the version number must increment and cannot duplicate any previous version number.
2. With each new build submission, the build number must increment (for the same version number).
3. For non-macOS apps, build numbers can be reused across different version sequences but must strictly increase within the same version sequence.

Violating these rules may lead to automatic rejection by the App Store. Common errors include attempting to upload an app with the same version or build number as a previous submission, triggering prompts like "Invalid Version Number" or "Build number must be greater than previous build."

Comparison with Android Platform

Unlike iOS's strict rules, Android's version management is more flexible. In the Google Play Store, android:versionName (equivalent to iOS's version number) can be any string, without requiring increments or a specific format. Meanwhile, android:versionCode (equivalent to the build number) must be an incrementing integer. This difference reflects the distinct philosophies of the two ecosystems: iOS emphasizes strict norms and user-visible version tracking, while Android prioritizes developer flexibility.

Technical Implementation and Best Practices

In Xcode projects, version and build numbers are typically set in the Info.plist file. Developers should use automation tools (such as Fastlane or custom scripts) to manage the increment of these fields, avoiding human errors. For example, build numbers can be auto-incremented with each build, while version numbers are manually updated upon release.

Here is a simple code example demonstrating how to read these values in Swift:

if let version = Bundle.main.infoDictionary?["CFBundleShortVersionString"] as? String,
   let build = Bundle.main.infoDictionary?["CFBundleVersion"] as? String {
    print("Version: " + version + "", Build: " + build + """)
}

Additionally, build numbers play a role in network requests. When an app uses NSURLConnection for HTTP queries, the User-Agent header includes the app name and build number, e.g., MyApp/2.21 CFNetwork/... Darwin/.... This helps servers track user behavior across different build versions.

Common Issues and Solutions

Developers often encounter issues such as:

• Incorrect version number format: Must use three dot-separated integers, e.g., 1.2.3. Avoid non-numeric characters or malformed strings.
• Duplicate build numbers: Ensure build numbers strictly increase within the same version sequence. If resubmitting a build for testing, always increment the build number.
• Cross-platform consistency: For apps supporting both iOS and macOS, note that macOS does not allow build number reuse in any release train, requiring separate management.

Adhering to Apple's version management rules not only prevents submission errors but also enhances app maintainability and user trust. It is recommended that development teams establish clear version control processes early in the project and regularly review related settings.