Version Code: nó là gì, định danh số và cập nhật

Version Code trong Android là gì

Version Code là một số nguyên kiểu Integer được gán cho mỗi bản build của ứng dụng Android. Không giống như Version Name, Version Code không hiển thị cho người dùng và chỉ được hệ điều hành và Google Play sử dụng để so sánh phiên bản khi cài đặt bản cập nhật.

Định dạng Version Code

Version Code phải là một số nguyên dương trong khoảng từ 1 đến 2100000000. Mỗi bản build tiếp theo phải có Version Code lớn hơn nghiêm ngặt so với bản trước. Nếu nhà phát triển đã phát hành bản build với Version Code 5, lần xuất bản tiếp theo có thể sử dụng 6, 7 hoặc bất kỳ số nào lớn hơn 5, nhưng không phải 4 và không phải 5 một lần nữa.

Lịch sử hình thành

Google đã giới thiệu sự phân chia giữa Version Code và Version Name với việc ra mắt Android SDK vào năm 2007. Version Code được thiết kế như một định danh máy để so sánh phiên bản tự động, trong khi Version Name được tạo ra như một nhãn có thể đọc được bởi con người. Sự phân chia này cho phép nhà phát triển đặt tên phiên bản theo ý muốn trong khi vẫn duy trì thứ tự cập nhật nghiêm ngặt thông qua mã số.

Cách hoạt động của quản lý phiên bản qua Version Code

Cơ chế so sánh của Version Code được tích hợp trong hệ điều hành Android và cửa hàng Google Play. Mỗi lần xuất bản, Google Play kiểm tra rằng Version Code của bản build mới lớn hơn mã của phiên bản đã cài đặt. Nếu điều kiện không được đáp ứng, việc xuất bản bị từ chối với lỗi.

Quy trình kiểm tra cập nhật

Khi một thiết bị liên hệ với Google Play để kiểm tra cập nhật, máy chủ so sánh Version Code của ứng dụng đã cài đặt với giá trị tối đa có sẵn trong cửa hàng. Nếu mã trên máy chủ lớn hơn, quá trình tải xuống và cài đặt bản cập nhật sẽ bắt đầu. Người dùng nhìn thấy Version Name do nhà phát triển chỉ định, nhưng quyết định cập nhật được đưa ra dựa trên Version Code.

Tăng Version Code

Các nhà phát triển áp dụng các chiến lược khác nhau để tăng Version Code. Đơn giản nhất là tăng thêm 1 cho mỗi bản build. Đối với các pipeline CI/CD, thường sử dụng timestamp hoặc số build: 2026070301 (năm-tháng-ngày-số). Điều quan trọng là mã phải tăng đơn điệu và không lặp lại giữa các bản build và track Google Play khác nhau.

• Tăng đơn điệu — tăng thêm 1 cho mỗi commit vào nhánh phát hành
• Định dạng timestamp — 20260703 cho các bản build hàng ngày, 2026070301 cho nhiều bản trong ngày
• SemVer dưới dạng số — 100010000 cho phiên bản 1.1.0 (major 1, minor 1, patch 0)
• Số build — sử dụng BUILD_NUMBER từ hệ thống CI (Jenkins, GitHub Actions)

Sự khác biệt giữa Version Code và Version Name

Version Code và Version Name là hai trường độc lập trong build.gradle thực hiện các chức năng khác nhau. Version Code là định danh nội bộ cho hệ thống, Version Name là nhãn tiếp thị cho người dùng. Chúng có thể thay đổi độc lập với nhau.

Version Name cho người dùng

Version Name là một chuỗi được hiển thị trong cài đặt ứng dụng, trong Google Play và trong hộp thoại cập nhật. Nhà phát triển có thể chỉ định bất kỳ định dạng nào: 1.0.0, 2.3.1-beta, 3.0-rc1. Version Name không được sử dụng để so sánh phiên bản chuỗi — Google Play luôn dựa vào Version Code.

Các kịch bản khác biệt

Có thể xảy ra tình huống Version Code tăng trong khi Version Name vẫn giữ nguyên. Ví dụ, nếu nhà phát triển sửa lỗi nghiêm trọng trong bản build hotfix mà không thay đổi chức năng. Version Name vẫn là 2.0.0, trong khi Version Code thay đổi từ 5 thành 6. Google Play sẽ xử lý bản cập nhật này một cách chính xác.

// Ví dụ: version name không thay đổi, mã tăng lên
android {
    defaultConfig {
        versionCode 6  // Trước là 5 — hotfix không có tính năng mới
        versionName "2.0.0"  // Không thay đổi
    }
}

// Kiểm tra phiên bản trong runtime
val code = BuildConfig.VERSION_CODE
val name = BuildConfig.VERSION_NAME
println("Code: $code, Name: $name")

Cấu hình Version Code trong build.gradle

Cấu hình Version Code được thực hiện trong tệp build.gradle của mô-đun ứng dụng. Trường versionCode chấp nhận một số nguyên và là một phần của khối defaultConfig. Đối với các bản build flavor khác nhau, có thể đặt giá trị tùy chỉnh thông qua trường versionCode trong cấu hình sản phẩm.

Cấu hình cơ bản

// 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 cho phép sử dụng Version Code khác nhau cho các cấu hình khác nhau: phiên bản dùng thử, phiên bản riêng cho máy tính bảng. Nếu flavors được sử dụng trong dự án, Version Code cuối cùng được tạo thành từ số cơ bản và mức tăng cụ thể của flavor. Google Play theo dõi từng tổ hợp một cách độc lập.

Tự động hóa tăng qua CI

Trong các pipeline CI/CD (GitHub Actions, GitLab CI, Jenkins), Version Code thường được tạo tự động dựa trên số build hoặc ngày tháng. Điều này loại bỏ lỗi con người trong quá trình cập nhật thủ công. Tập lệnh đọc Version Code hiện tại từ build.gradle, tăng nó và ghi lại trước khi bắt đầu build.

// Tự động tăng 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
    }
}

Đặc điểm của Version Code khi xuất bản lên Google Play

Google Play có các quy tắc nghiêm ngặt về Version Code khi xuất bản và cập nhật ứng dụng. Vi phạm các quy tắc này dẫn đến việc từ chối bản build hoặc không thể phát hành bản cập nhật. Nhà phát triển cần hiểu các giới hạn và chiến lược quản lý mã ở tất cả các giai đoạn của vòng đời.

Quy tắc tăng đơn điệu

Google Play không cho phép tải lên APK hoặc AAB có Version Code nhỏ hơn hoặc bằng phiên bản hiện đã được xuất bản. Quy tắc này áp dụng cho từng track (production, beta, alpha) một cách độc lập. Nếu bản build với Version Code 10 được tải lên production và bản build với mã 5 ở alpha, track alpha có thể được cập nhật lên 6, 7, 8 hoặc 9, nhưng production vẫn ở 10.

Di chuyển giữa các track

Khi thăng cấp bản build từ alpha lên beta và sau đó lên production, Version Code phải tăng ở mỗi giai đoạn. Nếu phiên bản alpha có mã 10, beta có thể sử dụng 11 và production sử dụng 12. Bạn không thể phát hành bản build với mã 10 lên production nếu alpha đã sử dụng 10, ngay cả khi production chưa thấy nó.

• Tăng đơn điệu — mỗi bản build trong một track có Version Code lớn hơn bản trước trong cùng track
• Nhận thức giữa các track — khi thăng cấp giữa các track, Version Code tăng tuần tự
• Kiểm thử nội bộ — track kiểm thử nội bộ sử dụng cùng quy tắc đơn điệu
• Nhiều APK — định dạng xuất bản cũ yêu cầu Version Code duy nhất cho mỗi APK

Lỗi khi chỉ định Version Code

Lỗi phổ biến nhất là trùng Version Code trong các bản build khác nhau được tải lên cùng một track. Google Play trả về lỗi APK_VERSION_CODE_ALREADY_EXISTS. Một lỗi khác là vượt quá giá trị tối đa 2100000000, gây ra lỗi biên dịch. Để tránh xung đột, hãy sử dụng tính năng tạo mã tự động trong hệ thống CI gắn với số build hoặc ngày build.

Các nhà phát triển cũng thường mắc lỗi không tăng Version Code khi xây dựng bản phát hành hotfix cho một track thay thế. Nếu production có mã 15 và track alpha ở lại 14, khi thăng cấp alpha lên production, Google Play sẽ từ chối bản build vì mã của nó nhỏ hơn mã production hiện tại. Hãy giám sát tính đơn điệu của mã trên tất cả các track cùng lúc — để làm điều này, thuận tiện sử dụng một tệp version.properties duy nhất mà tất cả các track đọc giá trị hiện tại.