Version Code: 개념, 숫자 식별자 및 업데이트

Android에서 Version Code란

Version Code는 Integer 유형의 정수로, Android 애플리케이션의 각 빌드에 할당됩니다. Version Name과 달리 Version Code는 사용자에게 표시되지 않으며 운영 체제와 Google Play가 업데이트 설치 시 버전을 비교하는 데만 사용됩니다.

Version Code 형식

Version Code는 1에서 2100000000 사이의 양의 정수여야 합니다. 각 후속 빌드는 이전 빌드보다 엄격히 큰 Version Code를 가져야 합니다. 개발자가 Version Code 5로 빌드를 출시한 경우, 다음 게시는 6, 7 또는 5보다 큰 숫자를 사용할 수 있지만 4나 다시 5는 사용할 수 없습니다.

기원 역사

Google은 2007년 Android SDK 출시와 함께 Version Code와 Version Name의 분리를 도입했습니다. Version Code는 자동 버전 비교를 위한 기계 식별자로 설계되었고, Version Name은 사람이 읽을 수 있는 레이블로 설계되었습니다. 이 분리를 통해 개발자는 버전 이름을 원하는 대로 지정하면서 숫자 코드를 통해 엄격한 업데이트 순서를 유지할 수 있습니다.

Version Code를 통한 버전 관리 작동 방식

Version Code의 비교 메커니즘은 Android 운영 체제와 Google Play 스토어에 내장되어 있습니다. 게시할 때마다 Google Play는 새 빌드의 Version Code가 설치된 버전의 코드보다 큰지 확인합니다. 조건이 충족되지 않으면 게시가 오류와 함께 거부됩니다.

업데이트 확인 프로세스

기기가 업데이트를 확인하기 위해 Google Play에 연결하면 서버는 설치된 애플리케이션의 Version Code를 스토어에서 사용 가능한 최대값과 비교합니다. 서버의 코드가 더 크면 업데이트 다운로드 및 설치가 시작됩니다. 사용자는 개발자가 지정한 Version Name을 보지만, 업데이트 결정은 Version Code를 기반으로 이루어집니다.

Version Code 증가

개발자들은 Version Code를 증가시키기 위해 다양한 전략을 적용합니다. 가장 간단한 것은 빌드마다 1씩 증가시키는 것입니다. CI/CD 파이프라인의 경우 타임스탬프나 빌드 번호가 자주 사용됩니다: 2026070301(년-월-일-번호). 코드가 단조롭게 증가하고 서로 다른 빌드와 Google Play 트랙 간에 중복되지 않는 것이 중요합니다.

• 단조 증가 — 릴리스 브랜치에 커밋할 때마다 1씩 증가
• 타임스탬프 형식 — 일일 빌드의 경우 20260703, 하루에 여러 빌드의 경우 2026070301
• 숫자로 표현한 SemVer — 버전 1.1.0의 경우 100010000 (major 1, minor 1, patch 0)
• 빌드 번호 — CI 시스템(Jenkins, GitHub Actions)의 BUILD_NUMBER 사용

Version Code와 Version Name의 차이점

Version Code와 Version Name은 build.gradle에서 서로 다른 기능을 수행하는 두 개의 독립적인 필드입니다. Version Code는 시스템용 내부 식별자이고, Version Name은 사용자용 마케팅 레이블입니다. 이들은 서로 독립적으로 변경될 수 있습니다.

사용자용 Version Name

Version Name은 애플리케이션 설정, Google Play 및 업데이트 대화상자에 표시되는 문자열입니다. 개발자는 1.0.0, 2.3.1-beta, 3.0-rc1과 같은任何 형식을 지정할 수 있습니다. Version Name은 문자열 버전 비교에 사용되지 않습니다 — Google Play는 항상 Version Code에 의존합니다.

차이 시나리오

Version Code가 증가하는 동안 Version Name이 동일하게 유지되는 상황이 가능합니다. 예를 들어, 개발자가 기능을 변경하지 않고 핫픽스 빌드에서 중요한 버그를 수정하는 경우입니다. Version Name은 2.0.0으로 유지되고 Version Code는 5에서 6으로 변경됩니다. Google Play는 이러한 업데이트를 올바르게 처리합니다.

// 예: version name은 변경되지 않고 코드가 증가함
android {
    defaultConfig {
        versionCode 6  // 5였음 — 새 기능 없는 핫픽스
        versionName "2.0.0"  // 변경되지 않음
    }
}

// 런타임에서 버전 확인
val code = BuildConfig.VERSION_CODE
val name = BuildConfig.VERSION_NAME
println("Code: $code, Name: $name")

build.gradle에서 Version Code 설정

Version Code 설정은 애플리케이션 모듈의 build.gradle 파일에서 수행됩니다. versionCode 필드는 정수를 허용하며 defaultConfig 블록의 일부입니다. 다양한 flavor 빌드의 경우 제품 구성에서 versionCode 필드를 통해 사용자 정의 값을 설정할 수 있습니다.

기본 설정

// build.gradle.kts — Kotlin DSL
android {
    defaultConfig {
        applicationId "com.example.app"
        versionCode 15
        versionName "2.1.0"
    }

    flavorDimensions +"version"
    productFlavors {
        create("demo") {
            versionCode 1015
        }
        create("full") {
            versionCode 2015
        }
    }
}

Product flavors를 사용하면 다양한 구성(데모 버전, 태블릿용 별도 버전)에 대해 다른 Version Code를 사용할 수 있습니다. 프로젝트에서 flavor를 사용하는 경우 최종 Version Code는 기본 번호와 flavor별 증가분으로 구성됩니다. Google Play는 각 조합을 독립적으로 추적합니다.

CI를 통한 증가 자동화

CI/CD 파이프라인(GitHub Actions, GitLab CI, Jenkins)에서 Version Code는 빌드 번호나 날짜를 기준으로 자동 생성되는 경우가 많습니다. 이렇게 하면 수동 업데이트 시 인적 오류가 제거됩니다. 스크립트는 build.gradle에서 현재 Version Code를 읽고, 증가시킨 후 빌드를 시작하기 전에 다시 씁니다.

// Version Code 자동 증가
import java.util.Properties
import java.io.FileInputStream

val versionProps = Properties()
versionProps.load(FileInputStream("version.properties"))

val versionCode = versionProps.getProperty("VERSION_CODE").toInt() + 1
versionProps.setProperty("VERSION_CODE", versionCode.toString())

android {
    defaultConfig {
        versionCode = versionCode
    }
}

Google Play 게시를 위한 Version Code 특성

Google Play에는 앱 게시 및 업데이트 시 Version Code에 대한 엄격한 규칙이 있습니다. 이러한 규칙을 위반하면 빌드가 거부되거나 업데이트를 출시할 수 없게 됩니다. 개발자는 라이프사이클의 모든 단계에서 제한 사항과 코드 관리 전략을 이해해야 합니다.

단조 증가 규칙

Google Play는 Version Code가 현재 게시된 버전보다 작거나 같은 APK 또는 AAB의 업로드를 허용하지 않습니다. 이 규칙은 각 트랙(production, beta, alpha)에 독립적으로 적용됩니다. production에 Version Code 10인 빌드가 업로드되고 alpha에 코드 5인 빌드가 있는 경우, alpha 트랙은 6, 7, 8, 9로 업데이트할 수 있지만 production은 10으로 유지됩니다.

트랙 간 마이그레이션

빌드를 alpha에서 beta로, 그다음 production으로 승격할 때 Version Code는 각 단계에서 증가해야 합니다. alpha 버전의 코드가 10이면 beta는 11, production은 12를 사용할 수 있습니다. alpha가 이미 10을 사용 중인 경우, production이 아직 보지 못했더라도 코드 10인 빌드를 production에 출시할 수 없습니다.

• 단조 증가 — 트랙 내 각 빌드는 동일 트랙의 이전 빌드보다 큰 Version Code를 가짐
• 트랙 간 인식 — 트랙 간 승격 시 Version Code가 순차적으로 증가함
• 내부 테스트 — 내부 테스트 트랙도 동일한 단조성 규칙을 사용함
• 여러 APK — 이전 게시 형식은 각 APK에 고유한 Version Code가 필요했음

Version Code 지정 오류

가장 흔한 오류는 동일한 트랙에 업로드된 다른 빌드에서 Version Code가 일치하는 것입니다. Google Play는 APK_VERSION_CODE_ALREADY_EXISTS 오류를 반환합니다. 또 다른 오류는 최대값 2100000000을 초과하여 컴파일 실패가 발생하는 것입니다. 충돌을 피하려면 빌드 번호나 빌드 날짜에 연결된 CI 시스템의 자동 코드 생성을 사용하세요.

개발자들은 또한 대체 트랙용 핫픽스 릴리스를 빌드할 때 Version Code를 증가시키지 않는 실수를 자주 합니다. production의 코드가 15이고 alpha 트랙이 14로 남아 있는 경우, alpha를 production으로 승격할 때 Google Play는 해당 코드가 현재 production 코드보다 작기 때문에 빌드를 거부합니다. 모든 트랙에서 코드의 단조성을 동시에 모니터링하세요 — 이를 위해 모든 트랙이 현재 값을 읽는 단일 version.properties 파일을 사용하는 것이 편리합니다.