Version Name: bản chất, ý nghĩa tham số và thiết lập

Version Name là gì

Version Name là một chuỗi ngữ nghĩa xác định bản phát hành ứng dụng cho người dùng. Không giống như các định danh kỹ thuật của bản build, tham số này mang thông tin có ý nghĩa: người dùng có thể đánh giá mức độ khác biệt của bản cập nhật mới so với bản trước đó.

Version Name được hiển thị trong thẻ ứng dụng trên Google Play và App Store, trong phần “Giới thiệu về ứng dụng” trên thiết bị, cũng như trong hộp thoại cập nhật hệ thống. Các nhà phát triển chỉ định nó trong tệp cấu hình dự án trước khi xây dựng phiên bản phát hành.

Theo Semantic Versioning 2.0 (2023), định dạng Major.Minor.Patch được sử dụng trong 78% ứng dụng di động. Phiên bản chính thay đổi khi có thay đổi API không tương thích, phiên bản phụ khi thêm chức năng mới và bản vá khi sửa lỗi.

Sử dụng Version Name để giao tiếp với người dùng: họ nên hiểu ngay lập tức bản cập nhật được cung cấp có tầm quan trọng như thế nào — chính, phụ hay sửa chữa.

Cấu trúc phiên bản ngữ nghĩa

Phiên bản ngữ nghĩa bao gồm ba số được phân tách bằng dấu chấm: Major.Minor.Patch. Mỗi thành phần này chịu trách nhiệm cho một mức độ thay đổi cụ thể trong ứng dụng.

Phiên bản chính (Major) tăng khi có những thay đổi căn bản làm phá vỡ tính tương thích ngược. Phiên bản phụ (Minor) thêm chức năng mới mà không phá vỡ chức năng hiện có. Bản vá (Patch) chỉ chứa các sửa lỗi.

Ví dụ: phiên bản 3.2.1 có nghĩa là: phiên bản chính thứ ba, bản cập nhật phụ thứ hai, bản vá đầu tiên. Hệ thống này dễ hiểu cho cả nhà phát triển và người dùng.

Nơi Version Name được hiển thị

Version Name hiển thị cho người dùng ở một số vị trí chính. Trong cửa hàng ứng dụng, nó xuất hiện trong tiêu đề thẻ ứng dụng và trong danh sách cập nhật. Trên thiết bị, nó xuất hiện trong cài đặt hệ thống trong phần “Giới thiệu về ứng dụng”.

Trên Google Play, Version Name được hiển thị bên dưới tên ứng dụng và ảnh hưởng đến quyết định cập nhật của người dùng. Trong App Store, chuỗi phiên bản được hiển thị ở cùng vị trí khi xem trang ứng dụng.

Theo nghiên cứu của Apptentive (2024), 67% người dùng kiểm tra phiên bản ứng dụng trước khi cập nhật và ngữ nghĩa rõ ràng làm tăng tỷ lệ chuyển đổi cài đặt lên 23%.

Version Name trên Android

Trên Android, Version Name được thiết lập bằng tham số versionName trong tệp build.gradle (cấp mô-đun). Tham số này là một chuỗi và có thể chứa bất kỳ ký tự nào, bao gồm dấu chấm, dấu gạch ngang và chữ cái.

Tham số được khai báo bên trong khối android.defaultConfig cùng với tham số bắt buộc versionCode. Android không áp đặt hạn chế về định dạng chuỗi, nhưng Google Play khuyến nghị sử dụng định dạng ngữ nghĩa.

Theo Android Developers (2025), Google Play sử dụng versionName để hiển thị trong giao diện cửa hàng nhưng không phân tích nội dung của nó theo chương trình — chỉ versionCode ảnh hưởng đến logic cập nhật.

Chỉ định Version Name ở định dạng Major.Minor.Patch và đồng bộ hóa nó với thẻ trong hệ thống kiểm soát phiên bản để nhận dạng bản phát hành rõ ràng.

Đặc điểm của versionName trong Gradle

Gradle cho phép thiết lập versionName tĩnh trong build.gradle hoặc động thông qua các tập lệnh xây dựng. Tạo động hữu ích cho các bản build tự động qua đêm và đường ống CI/CD.

Trong build.gradle, bạn có thể sử dụng biến môi trường, tham số dòng lệnh hoặc lời gọi tập lệnh shell để hình thành versionName. Một cách tiếp cận điển hình là đọc phiên bản từ tệp version.properties.

Sự linh hoạt này cho phép các nhóm tự động hóa quy trình quản lý phiên bản và loại bỏ lỗi do con người trong quá trình chuẩn bị phát hành.

Version Name trên iOS

Trên iOS, Version Name được thiết lập bằng khóa CFBundleShortVersionString trong tệp Info.plist. Đây là tham số bắt buộc để xuất bản ứng dụng trên App Store và nó được định kiểu chặt chẽ như một chuỗi.

Không giống như Android, App Store Connect kiểm tra định dạng Version Name và yêu cầu nó khớp với mẫu số được phân tách bằng dấu chấm. Độ dài chuỗi tối đa là 18 ký tự và mỗi thành phần phiên bản không được vượt quá 255.

Theo Tài liệu dành cho nhà phát triển Apple (2025), CFBundleShortVersionString được App Store sử dụng để hiển thị phiên bản trong giao diện cửa hàng và trong hộp thoại hệ thống trên thiết bị của người dùng.

Khi tải bản build lên App Store Connect, hãy đảm bảo Version Name khớp với phiên bản được chỉ định trong tài liệu tiếp thị — điều này đơn giản hóa việc giao tiếp với người dùng.

Tích hợp với Xcode

Xcode cung cấp giao diện đồ họa để thay đổi Version Name trong cài đặt mục tiêu. Trường “Marketing Version” nằm trên tab General trong phần Identity. Các thay đổi được tự động lưu vào Info.plist.

Để tự động hóa, bạn có thể sử dụng tập lệnh xây dựng trong Xcode Build Phases hoặc tiện ích agvtool (Apple Generic Version Tool). agvtool cho phép quản lý phiên bản từ dòng lệnh và tích hợp vào CI/CD.

Cách tiếp cận này đặc biệt thuận tiện khi sử dụng fastlane hoặc Jenkins để xây dựng và phân phối ứng dụng tự động.

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

Version Name và Build Number thực hiện các nhiệm vụ khác nhau trong quy trình phát triển. Version Name là chuỗi hướng đến người dùng, trong khi Build Number là định danh số nội bộ xác định duy nhất mỗi bản build.

Build Number (versionCode trên Android, CFBundleVersion trên iOS) phải tăng với mỗi bản build mới và được các cửa hàng ứng dụng sử dụng để xác định phiên bản nào mới hơn. Version Name có thể không thay đổi qua nhiều bản build của cùng một phiên bản.

Theo Chính sách Google Play (2025), hai ứng dụng có cùng versionCode được coi là cùng một phiên bản — versionCode phải là duy nhất cho mỗi APK. Version Name không tham gia vào việc kiểm tra này.

Luôn tăng Build Number với mỗi bản build và chỉ thay đổi Version Name khi chức năng thay đổi — điều này ngăn ngừa xung đột khi xuất bản.

Cách chọn Version Name

Việc chọn Version Name phụ thuộc vào chiến lược quản lý phiên bản của nhóm. Cách tiếp cận phổ biến nhất là quản lý phiên bản ngữ nghĩa (SemVer), nhưng cũng tồn tại các sơ đồ thay thế như quản lý phiên bản theo lịch hoặc theo ngày phát hành.

Semantic Versioning 2.0 khuyến nghị định dạng Major.Minor.Patch với các hậu tố tiền phát hành tùy chọn. Đối với ứng dụng di động, sơ đồ Major.Minor cũng phổ biến, nơi phiên bản vá được bỏ qua để đơn giản hóa nhận thức.

Quản lý phiên bản theo lịch (CalVer) sử dụng ngày phát hành làm số phiên bản — ví dụ: 25.06 (năm và tháng). Cách tiếp cận này thuận tiện cho các ứng dụng có bản phát hành thường xuyên nơi ngữ nghĩa không có ý nghĩa.

Khuyến nghị chọn sơ đồ

Quản lý phiên bản ngữ nghĩa phù hợp cho các ứng dụng có API công khai nơi tính tương thích ngược quan trọng. Người dùng và người tích hợp hiểu những thay đổi nào cần mong đợi khi cập nhật.

Quản lý phiên bản theo lịch được chọn cho các ứng dụng nơi tính mới của bản phát hành quan trọng hơn phạm vi thay đổi. Ví dụ: trình tổng hợp tin tức hoặc ứng dụng thời tiết.

Sơ đồ lai kết hợp cả hai cách tiếp cận: Major.Minor.RC, trong đó RC là số bản build cho một ứng viên phát hành cụ thể. Sơ đồ này thuận tiện trong quá trình thử nghiệm beta tích cực.

Ví dụ cấu hình Version Name

Các ví dụ mã dưới đây cho thấy cách thiết lập Version Name trên Android và iOS. Đối với Android, sử dụng Gradle; đối với iOS, sử dụng Xcode Build Settings với agvtool.

Thiết lập versionName trong Android

Trong Android, phiên bản được thiết lập trong tệp app/build.gradle bên trong khối defaultConfig. Tham số versionName chấp nhận giá trị chuỗi.

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

versionName cũng có thể được đọc từ tệp bên ngoài hoặc được tạo động bằng Gradle Script.

Tạo động versionName

Phiên bản động được hình thành từ các biến môi trường của hệ thống CI/CD. Điều này đảm bảo mỗi bản build nhận được số phiên bản chính xác.

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

android {
    defaultConfig {
        versionName getVersionName()
    }
}

Cách tiếp cận này tự động hóa việc quản lý phiên bản và loại bỏ rủi ro không khớp giữa bản build và thẻ trong kho lưu trữ.

Thiết lập CFBundleShortVersionString trong iOS

Trong iOS, phiên bản có thể được thiết lập thông qua Xcode hoặc thông qua dòng lệnh bằng agvtool.

# Thiết lập phiên bản tiếp thị
xcrun agvtool new-marketing-version 2.1.0

# Đọc phiên bản hiện tại
xcrun agvtool what-marketing-version

agvtool tự động cập nhật Info.plist và đồng bộ hóa phiên bản trên tất cả các mục tiêu trong dự án Xcode.