Version Name: 본질, 파라미터 의미 및 설정

Version Name이란

Version Name은 사용자에게 애플리케이션 릴리스를 식별하는 의미론적 문자열입니다. 기술적 빌드 식별자와 달리 이 파라미터는 의미 있는 정보를 전달합니다. 사용자는 새 업데이트가 이전 업데이트와 얼마나 다른지 평가할 수 있습니다.

Version Name은 Google Play 및 App Store의 애플리케이션 카드, 기기의 "앱 정보" 섹션, 시스템 업데이트 대화상자에 표시됩니다. 개발자는 릴리스 버전을 빌드하기 전에 프로젝트 구성 파일에서 이를 지정합니다.

Semantic Versioning 2.0(2023)에 따르면 Major.Minor.Patch 형식은 모바일 애플리케이션의 78%에서 사용됩니다. 메이저 버전은 호환되지 않는 API 변경 시 변경되고, 마이너 버전은 기능 추가 시, 패치는 버그 수정 시 변경됩니다.

Version Name을 사용하여 사용자와 소통하세요. 사용자는 제공된 업데이트가 메이저, 마이너 또는 수정 중 어떤 것인지 즉시 이해할 수 있어야 합니다.

의미론적 버전 구조

의미론적 버전은 점으로 구분된 세 개의 숫자로 구성됩니다: Major.Minor.Patch. 각 구성 요소는 애플리케이션의 특정 수준 변경을 담당합니다.

메이저 버전(Major)은 하위 호환성을 깨는 근본적인 변경 사항이 도입될 때 증가합니다. 마이너 버전(Minor)은 기존 기능을 깨지 않고 새 기능을 추가합니다. 패치(Patch)는 버그 수정만 포함합니다.

예를 들어 버전 3.2.1은 세 번째 메이저 버전, 두 번째 마이너 업데이트, 첫 번째 패치를 의미합니다. 이 시스템은 개발자와 사용자 모두에게 이해하기 쉽습니다.

Version Name 표시 위치

Version Name은 여러 주요 위치에서 사용자에게 표시됩니다. 앱 스토어에서는 애플리케이션 카드 헤더와 업데이트 목록에 표시됩니다. 기기에서는 "앱 정보" 섹션의 시스템 설정에 표시됩니다.

Google Play에서 Version Name은 애플리케이션 이름 아래에 표시되며 사용자의 업데이트 결정에 영향을 줍니다. App Store에서도 버전 문자열은 애플리케이션 페이지를 볼 때 같은 위치에 표시됩니다.

Apptentive(2024) 연구에 따르면 사용자의 67%가 업데이트 전에 앱 버전을 확인하며, 명확한 의미론은 설치 전환율을 23%까지 높입니다.

Android에서의 Version Name

Android에서 Version Name은 build.gradle 파일(모듈 수준)의 versionName 파라미터로 설정합니다. 이 파라미터는 문자열이며 점, 하이픈, 문자를 포함한 모든 문자를 포함할 수 있습니다.

파라미터는 필수 versionCode 파라미터와 함께 android.defaultConfig 블록 내에서 선언됩니다. Android는 문자열 형식에 제한을 두지 않지만 Google Play는 의미론적 형식 사용을 권장합니다.

Android Developers(2025)에 따르면 Google Play는 스토어 인터페이스 표시를 위해 versionName을 사용하지만 프로그래밍 방식으로 내용을 분석하지는 않습니다. 업데이트 로직에 영향을 주는 것은 versionCode뿐입니다.

Version Name을 Major.Minor.Patch 형식으로 지정하고 버전 관리 시스템의 태그와 동기화하여 릴리스를 명확하게 식별할 수 있도록 하세요.

Gradle에서 versionName의 특징

Gradle은 build.gradle에서 정적으로 또는 빌드 스크립트를 통해 동적으로 versionName을 설정할 수 있게 합니다. 동적 생성은 자동 야간 빌드 및 CI/CD 파이프라인에 유용합니다.

build.gradle에서는 환경 변수, 명령줄 파라미터 또는 셸 스크립트 호출을 사용하여 versionName을 구성할 수 있습니다. 일반적인 접근 방식은 version.properties 파일에서 버전을 읽는 것입니다.

이러한 유연성을 통해 팀은 버전 관리 프로세스를 자동화하고 릴리스 준비 중 인적 오류를 제거할 수 있습니다.

iOS에서의 Version Name

iOS에서 Version Name은 Info.plist 파일의 CFBundleShortVersionString 키로 설정합니다. 이는 App Store에 애플리케이션을 게시하기 위한 필수 파라미터이며 문자열로 엄격하게 타입이 지정됩니다.

Android와 달리 App Store Connect는 Version Name 형식을 확인하고 점으로 구분된 숫자 패턴과 일치하도록 요구합니다. 최대 문자열 길이는 18자이며 각 버전 구성 요소는 255를 초과할 수 없습니다.

Apple Developer Documentation(2025)에 따르면 CFBundleShortVersionString은 App Store가 스토어 인터페이스와 사용자 기기의 시스템 대화상자에 버전을 표시하는 데 사용합니다.

App Store Connect에 빌드를 업로드할 때 Version Name이 마케팅 자료에 지정된 버전과 일치하는지 확인하세요. 이렇게 하면 사용자와의 커뮤니케이션이 간소화됩니다.

Xcode와의 통합

Xcode는 대상 설정에서 Version Name을 변경할 수 있는 그래픽 인터페이스를 제공합니다. "Marketing Version" 필드는 Identity 섹션의 General 탭에 있습니다. 변경 사항은 Info.plist에 자동으로 저장됩니다.

자동화를 위해 Xcode Build Phases의 빌드 스크립트나 agvtool(Apple Generic Version Tool) 유틸리티를 사용할 수 있습니다. agvtool은 명령줄에서 버전을 관리할 수 있게 하며 CI/CD에 통합됩니다.

이러한 접근 방식은 fastlane 또는 Jenkins를 사용한 애플리케이션의 자동 빌드 및 전달에 특히 편리합니다.

Version Name과 Build Number의 차이점

Version Name과 Build Number는 개발 프로세스에서 서로 다른 역할을 수행합니다. Version Name은 사용자 대상 문자열인 반면, Build Number는 각 빌드를 고유하게 식별하는 내부 숫자 식별자입니다.

Build Number(Android의 versionCode, iOS의 CFBundleVersion)는 새 빌드마다 증가해야 하며 앱 스토어에서 어떤 버전이 최신인지 결정하는 데 사용됩니다. Version Name은 동일한 버전의 여러 빌드에서 변경되지 않을 수 있습니다.

Google Play Policy(2025)에 따르면 동일한 versionCode를 가진 두 앱은 동일한 버전으로 간주됩니다. versionCode는 각 APK에 대해 고유해야 합니다. Version Name은 이 검사에 참여하지 않습니다.

빌드할 때마다 항상 Build Number를 증가시키고 기능이 변경될 때만 Version Name을 변경하세요. 이렇게 하면 게시 시 충돌을 방지할 수 있습니다.

Version Name 선택 방법

Version Name 선택은 팀의 버전 관리 전략에 따라 달라집니다. 가장 일반적인 접근 방식은 의미론적 버전 관리(SemVer)이지만, 달력 버전 관리나 릴리스 날짜 기반 버전 관리와 같은 대안 체계도 존재합니다.

Semantic Versioning 2.0은 선택적 사전 릴리스 접미사가 있는 Major.Minor.Patch 형식을 권장합니다. 모바일 애플리케이션의 경우 인식을 단순화하기 위해 패치 버전을 생략한 Major.Minor 체계도 인기가 있습니다.

달력 버전 관리(CalVer)는 릴리스 날짜를 버전 번호로 사용합니다(예: 25.06(년, 월)). 이 접근 방식은 의미론이 의미가 없는 빈번한 릴리스가 있는 애플리케이션에 편리합니다.

체계 선택을 위한 권장 사항

의미론적 버전 관리는 하위 호환성이 중요한 공개 API가 있는 애플리케이션에 적합합니다. 사용자와 통합자는 업데이트 시 어떤 변경이 예상되는지 이해할 수 있습니다.

달력 버전 관리는 변경 범위보다 릴리스의 새로움이 더 중요한 애플리케이션에 선택됩니다. 예를 들어 뉴스 수집기나 날씨 앱이 있습니다.

하이브리드 체계는 두 접근 방식을 결합합니다: Major.Minor.RC. 여기서 RC는 특정 릴리스 후보의 빌드 번호입니다. 이 체계는 활성 베타 테스트 중에 편리합니다.

Version Name 설정 예제

아래 코드 예제는 Android와 iOS에서 Version Name을 설정하는 방법을 보여줍니다. Android는 Gradle을 사용하고 iOS는 agvtool을 사용한 Xcode Build Settings를 사용합니다.

Android에서 versionName 설정

Android에서 버전은 app/build.gradle 파일의 defaultConfig 블록 내에서 설정됩니다. versionName 파라미터는 문자열 값을 받습니다.

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

versionName은 외부 파일에서 읽거나 Gradle Script를 사용하여 동적으로 생성할 수도 있습니다.

동적 versionName 생성

동적 버전은 CI/CD 시스템의 환경 변수로 생성됩니다. 이렇게 하면 각 빌드가 올바른 버전 번호를 받을 수 있습니다.

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

android {
    defaultConfig {
        versionName getVersionName()
    }
}

이 접근 방식은 버전 관리를 자동화하고 빌드와 리포지토리 태그 간의 불일치 위험을 제거합니다.

iOS에서 CFBundleShortVersionString 설정

iOS에서 버전은 Xcode를 통해 또는 agvtool을 사용하여 명령줄에서 설정할 수 있습니다.

# 마케팅 버전 설정
xcrun agvtool new-marketing-version 2.1.0

# 현재 버전 읽기
xcrun agvtool what-marketing-version

agvtool은 Info.plist를 자동으로 업데이트하고 Xcode 프로젝트의 모든 대상 간에 버전을 동기화합니다.