Marketing Version: 정의, Build Number와의 차이점 및 설정

Marketing Version이란

Marketing Version은 최종 사용자를 위한 애플리케이션 버전을 나타내는 의미론적 문자열입니다. iOS에서는 CFBundleShortVersionString 키를 통해, Android에서는 versionName을 통해 설정됩니다.

“Marketing Version”이라는 용어는 Xcode에서 공식적으로 사용됩니다. 타겟 설정 인터페이스에서 필드 이름이 “Marketing Version”이고, Info.plist에서는 CFBundleShortVersionString에 해당합니다. Android에서는 이에 해당하는 것이 versionName이지만, 이 용어는 덜 자주 사용됩니다.

Apple Developer 문서(2025)에 따르면, Marketing Version은 점으로 구분된 최대 3개의 숫자로 구성되어야 하며, 공백이나 특수 문자가 없어야 합니다. 각 숫자는 255를 초과할 수 없습니다.

변경 사항의 중요성을 반영하도록 Marketing Version을 선택하세요. 근본적인 변경에는 메이저 업데이트, 새로운 기능에는 마이너 업데이트를 사용합니다.

내부 Build Number와의 차이점

Marketing Version은 목적 면에서 Build Number와 근본적으로 다릅니다. 전자는 사용자에게 정보를 제공하고, 후자는 스토어용 빌드를 식별합니다. Build Number는 Marketing Version을 변경하지 않고도 증가할 수 있습니다.

예를 들어, 출시된 릴리스에서 심각한 버그를 수정할 때 팀은 동일한 Marketing Version(1.2.0)을 유지하면서 Build Number만 증가시켜(15에서 16으로) 애플리케이션을 다시 빌드할 수 있습니다. 사용자는 동일한 버전을 보지만, 스토어는 빌드가 더 새롭다는 것을 알게 됩니다.

이러한 유연성을 통해 개발자는 버전 변경을 사용자에게 알리지 않고 수정 사항을 릴리스할 수 있습니다.

Marketing Version 표시 위치

Marketing Version은 사용자와 애플리케이션 간 상호작용의 여러 주요 지점에 표시됩니다. 앱 스토어에서는 앱 카드, 업데이트 설명 및 버전 기록에 표시됩니다.

기기에서는 Marketing Version이 시스템 설정(“정보” 또는 “앱” 섹션), App Store 또는 Google Play를 통한 업데이트 대화상자, 그리고 앱 내부의 “정보” 화면에 표시됩니다.

명확한 Marketing Version은 사용자가 설치된 버전의 최신성을 평가하고 업데이트 결정을 내리는 데 도움이 됩니다.

iOS의 Marketing Version

iOS에서 Marketing Version은 Xcode의 타겟 설정 General 탭에 있는 “Marketing Version” 필드를 통해 설정됩니다. 값은 Info.plist에 CFBundleShortVersionString으로 저장됩니다.

버전 형식은 Apple에 의해 엄격하게 규제됩니다. 문자열은 점으로 구분된 1~3개의 숫자를 포함해야 합니다(예: 1, 1.2, 1.2.3). 최대 길이는 18자입니다. 각 숫자는 255를 초과할 수 없습니다.

Apple App Store Review Guidelines(2025)에 따르면, App Store Connect는 Marketing Version이 이전에 게시된 버전과 메이저 또는 마이너 값이 1개 이상 차이나는 빌드의 업로드를 허용하지 않습니다. 이는 사용자가 업데이트를 놓치는 것을 방지합니다.

명령줄에서 Marketing Version을 관리하려면 agvtool을 사용하세요. CI/CD 통합을 간소화하고 Build Number와의 동기화를 보장합니다.

Android의 Marketing Version

Android에서 Marketing Version은 build.gradle 파일의 versionName 매개변수를 통해 설정됩니다. iOS와 달리, Android는 버전 문자열 형식에 엄격한 제한을 두지 않습니다.

versionName에는 문자, 숫자, 하이픈, 점 등 모든 문자를 포함할 수 있습니다. Google Play는 이 문자열을 앱 카드와 업데이트 목록에 표시하지만, 특정 패턴에 대한 유효성 검사는 수행하지 않습니다.

그러나 Google Play는 일관성을 위해 의미론적 Major.Minor.Patch 형식을 따를 것을 권장합니다. 이는 사용자가 버전을 이해하기 쉽게 만들고 자동화된 업데이트 분석을 가능하게 합니다.

릴리스 유형(메이저, 마이너, 패치)을 명확히 반영하는 versionName을 설정하세요. 이는 사용자가 변경 사항의 중요성을 신속하게 평가하는 데 도움이 됩니다.

동적 versionName 생성

Android의 versionName은 Git 태그 또는 CI/CD 변수를 기반으로 동적으로 생성될 수 있습니다. 이는 버전 관리 프로세스를 간소화하고 리포지토리와 빌드 간의 불일치를 제거합니다.

일반적인 접근 방식은 Git 태그(예: v2.1.0)를 읽고 해당 값을 versionName으로 사용하는 것입니다. 태그가 없는 경우 날짜와 커밋 번호를 기반으로 버전을 생성할 수 있습니다.

이 접근 방식은 versionName이 항상 소스 코드 상태와 일치하고 수동 업데이트가 필요하지 않도록 보장합니다.

Marketing Version과 Build Number 비교

Marketing Version과 Build Number는 서로 다른 목적을 수행하는 두 개의 독립적인 매개변수입니다. Marketing Version은 사용자에게 정보를 제공하고, Build Number는 기술적으로 빌드를 식별합니다.

주요 차이점은 고유성입니다. Build Number는 각 빌드에서 고유해야 합니다. Marketing Version은 반복될 수 있습니다. 동일한 버전의 여러 빌드는 동일한 Marketing Version을 공유하지만 Build Number는 다릅니다.

Google Play 정책(2025)에 따르면, 동일한 Marketing Version이지만 다른 Build Number를 가진 두 개의 APK를 업로드하면 Google Play는 둘 다 동일한 버전의 서로 다른 빌드로 수락합니다. App Store에도 동일한 규칙이 적용됩니다.

기억하세요: Build Number는 기계용, Marketing Version은 사람용입니다. 전자는 자동화하고 후자는 신중하게 계획하세요.

버전 관리 전략

전략 선택은 애플리케이션 유형, 대상 사용자 및 릴리스 프로세스에 따라 달라집니다. 의미론적, 달력, 하이브리드의 세 가지 주요 체계가 대부분의 시나리오를 다룹니다.

의미론적 버전 관리(SemVer)는 Major.Minor.Patch 형식을 사용하며 각 구성 요소를 언제 증가시켜야 하는지 엄격하게 정의합니다. 공개 API와 복잡한 통합이 있는 애플리케이션에 이상적입니다.

semver.org(2023)에 따르면, SemVer 사양 버전 2.0.0은 오픈 소스 모바일 프로젝트의 89%에서 사용되며 모든 패키지 관리자에서 지원됩니다.

달력 버전 관리

달력 버전 관리(CalVer)는 릴리스 날짜를 버전으로 사용합니다(예: 2025년 6월의 경우 25.06). 이 접근 방식은 자주 업데이트되는 애플리케이션에서 인기가 있습니다.

CalVer는 변경 사항의 중요성에 대한 정보를 전달하지 않지만 버전의 최신성을 명확하게 보여줍니다. 사용자는 버전 25.06이 25.03보다 최신임을 즉시 이해합니다.

앱이 자주 업데이트되고 사용자가 변경 범위보다 데이터의 최신성을 더 중요시하는 경우 달력 버전 관리를 선택하세요.

선택 권장 사항

MVP 및 스타트업의 경우 패치가 없는 간단한 의미론적 버전(Major.Minor)이 적합합니다. 장기 지원이 필요한 성숙한 제품의 경우 전체 SemVer, 지속적 릴리스 앱의 경우 CalVer를 선택하세요.

절대 날짜를 Build Number로 사용하지 마세요. 하루에 여러 빌드가 있는 경우 충돌이 발생할 수 있습니다. Build Number는 순차적이거나 복합적이어야 하지만 항상 단조 증가해야 합니다.

Marketing Version의 일반적인 실수

일반적인 실수는 새로운 메이저 라인으로 이동할 때 버전 구성 요소를 건너뛰는 것입니다. 예를 들어, 버전 1.9.9 다음은 2.0.0이어야 하며 1.10.0이 아닙니다. 이는 의미 체계를 깨뜨리고 사용자를 혼란스럽게 합니다.

또 다른 일반적인 문제는 코드와 앱 스토어 간의 Marketing Version 불일치입니다. 검토를 위해 빌드를 제출하기 전에 build.gradle의 versionName이 Google Play Console 또는 App Store Connect에 지정된 버전과 일치하는지 항상 확인하세요.

Marketing Version 설정 예시

코드 예시는 두 플랫폼 모두에서 Marketing Version을 설정하고 업데이트를 자동화하는 방법을 보여줍니다.

Android Gradle에서 versionName 설정

Android에서 versionName은 build.gradle에서 설정됩니다. 값은 정적이거나 환경 변수에서 읽을 수 있습니다.

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

// Git 태그에서 버전 읽기
def getVersionNameFromGit = {
    def tag = "git describe --tags".execute().
        text.trim()
    return tag.startsWith("v") ? tag.substring(1) : tag
}

versionName은 Git 태그에서 추출되어 리포지토리 버전과 빌드된 애플리케이션 간의 일치를 보장합니다.

Xcode에서 Marketing Version 관리

iOS에서 Marketing Version은 Xcode 또는 agvtool을 통해 설정됩니다. 아래 명령은 새 마케팅 버전을 설정합니다.

# Marketing Version 설정
xcrun agvtool new-marketing-version 2.1.0

# 자동 증가
xcrun agvtool next-marketing-version

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

두 플랫폼을 위한 Fastlane

Fastlane을 사용하면 단일 스크립트로 두 플랫폼 모두에서 Marketing Version을 관리할 수 있어 크로스 플랫폼 프로젝트 유지 관리가 간소화됩니다.

# 마케팅 버전 설정
increment_version_number(
    version_number: "2.1.0"
)

# 마이너 버전 자동 증가
increment_version_number(
    bump_type: "minor"
)

Fastlane은 두 플랫폼 모두에서 작동하며 대부분의 CI/CD 서비스에서 지원됩니다.