Marketing Version: nó là gì, khác biệt với Build Number và cách cấu hình

Marketing Version là gì

Marketing Version là một chuỗi ngữ nghĩa đại diện cho phiên bản ứng dụng dành cho người dùng cuối. Trên iOS, nó được đặt qua khóa CFBundleShortVersionString, trên Android qua versionName.

Thuật ngữ “Marketing Version” được sử dụng chính thức trong Xcode: trong giao diện cài đặt target, trường được gọi là “Marketing Version” và trong Info.plist, nó tương ứng với CFBundleShortVersionString. Trên Android, tương đương là versionName, mặc dù thuật ngữ này ít được sử dụng hơn.

Theo Tài liệu Apple Developer (2025), Marketing Version phải bao gồm tối đa ba số được phân cách bằng dấu chấm, không có khoảng trắng hoặc ký tự đặc biệt. Mỗi số không được vượt quá 255.

Chọn Marketing Version của bạn để phản ánh mức độ quan trọng của các thay đổi: bản cập nhật chính cho các thay đổi cơ bản, bản cập nhật phụ cho các chức năng mới.

Khác biệt với Build Number nội bộ

Marketing Version khác cơ bản với Build Number về mục đích: cái đầu tiên thông báo cho người dùng, cái thứ hai xác định bản dựng cho cửa hàng. Build Number có thể tăng mà không cần thay đổi Marketing Version.

Ví dụ, khi sửa một lỗi nghiêm trọng trong bản phát hành đã công bố, nhóm có thể xây dựng lại ứng dụng với cùng Marketing Version (1.2.0) nhưng với Build Number cao hơn (từ 15 lên 16). Người dùng sẽ thấy cùng một phiên bản, nhưng cửa hàng sẽ biết bản dựng mới hơn.

Sự linh hoạt này cho phép các nhà phát triển phát hành bản sửa lỗi mà không cần thông báo cho người dùng về việc thay đổi phiên bản.

Marketing Version được hiển thị ở đâu

Marketing Version xuất hiện tại một số điểm tương tác chính giữa người dùng và ứng dụng. Trong cửa hàng ứng dụng, nó hiển thị trên thẻ ứng dụng, trong mô tả cập nhật và lịch sử phiên bản.

Trên thiết bị, Marketing Version được hiển thị trong cài đặt hệ thống (phần “Giới thiệu” hoặc “Ứng dụng”), trong hộp thoại cập nhật qua App Store hoặc Google Play, và bên trong ứng dụng trên màn hình “Giới thiệu”.

Một Marketing Version rõ ràng giúp người dùng đánh giá mức độ mới của phiên bản đã cài đặt và đưa ra quyết định cập nhật.

Marketing Version trên iOS

Trên iOS, Marketing Version được đặt trong Xcode qua trường “Marketing Version” trên tab General của cài đặt target. Giá trị được lưu trong Info.plist dưới dạng CFBundleShortVersionString.

Định dạng phiên bản được Apple quy định chặt chẽ: chuỗi phải chứa từ một đến ba số được phân cách bằng dấu chấm (ví dụ: 1, 1.2 hoặc 1.2.3). Độ dài tối đa là 18 ký tự. Mỗi số không được vượt quá 255.

Theo Nguyên tắc đánh giá App Store của Apple (2025), App Store Connect không cho phép tải lên bản dựng nếu Marketing Version khác với phiên bản đã phát hành trước đó hơn một giá trị chính hoặc phụ — điều này bảo vệ người dùng khỏi việc bỏ lỡ các bản cập nhật.

Sử dụng agvtool để quản lý Marketing Version từ dòng lệnh — nó đơn giản hóa việc tích hợp CI/CD và đảm bảo đồng bộ hóa với Build Number.

Marketing Version trên Android

Trên Android, Marketing Version được đặt qua tham số versionName trong tệp build.gradle. Không giống như iOS, Android không áp đặt các hạn chế nghiêm ngặt về định dạng chuỗi phiên bản.

versionName có thể chứa bất kỳ ký tự nào: chữ cái, chữ số, dấu gạch ngang và dấu chấm. Google Play hiển thị chuỗi này trong thẻ ứng dụng và trong danh sách cập nhật, nhưng không xác thực nó theo bất kỳ mẫu nào.

Tuy nhiên, Google Play khuyến nghị tuân theo định dạng ngữ nghĩa Major.Minor.Patch để đảm bảo nhất quán. Điều này giúp người dùng dễ hiểu phiên bản hơn và cho phép phân tích cập nhật tự động.

Đặt versionName phản ánh rõ ràng loại bản phát hành — chính, phụ hoặc vá lỗi. Điều này giúp người dùng nhanh chóng đánh giá mức độ quan trọng của các thay đổi.

Tạo versionName động

versionName trên Android có thể được tạo động dựa trên thẻ Git hoặc biến CI/CD. Điều này đơn giản hóa quy trình đánh phiên bản và loại bỏ sự khác biệt giữa kho lưu trữ và bản dựng.

Một cách tiếp cận điển hình là đọc thẻ Git (ví dụ: v2.1.0) và sử dụng giá trị của nó làm versionName. Nếu không có thẻ, có thể tạo phiên bản dựa trên ngày tháng và số commit.

Cách tiếp cận này đảm bảo rằng versionName luôn khớp với trạng thái mã nguồn và không yêu cầu cập nhật thủ công.

Marketing Version so với Build Number

Marketing Version và Build Number là hai tham số độc lập phục vụ các mục đích khác nhau. Marketing Version thông báo cho người dùng, trong khi Build Number xác định kỹ thuật bản dựng.

Sự khác biệt chính là tính duy nhất. Build Number phải là duy nhất cho mỗi bản dựng. Marketing Version có thể lặp lại: nhiều bản dựng của cùng một phiên bản có cùng Marketing Version nhưng Build Number khác nhau.

Theo Chính sách Google Play (2025), nếu bạn tải lên hai APK có cùng Marketing Version nhưng Build Number khác nhau, Google Play sẽ chấp nhận cả hai là các bản dựng khác nhau của cùng một phiên bản. Quy tắc tương tự cũng áp dụng cho App Store.

Hãy nhớ: Build Number dành cho máy móc, Marketing Version dành cho con người. Tự động hóa cái đầu tiên và lập kế hoạch cẩn thận cho cái thứ hai.

Chiến lược đánh phiên bản

Việc chọn chiến lược phụ thuộc vào loại ứng dụng, đối tượng người dùng và quy trình phát hành. Ba sơ đồ chính — ngữ nghĩa, lịch và kết hợp — bao phủ hầu hết các tình huống.

Đánh phiên bản ngữ nghĩa (SemVer) sử dụng định dạng Major.Minor.Patch và xác định chặt chẽ thời điểm tăng từng thành phần. Nó lý tưởng cho các ứng dụng có API công khai và tích hợp phức tạp.

Theo semver.org (2023), phiên bản 2.0.0 của đặc tả SemVer được sử dụng trong 89% dự án di động mã nguồn mở và được hỗ trợ bởi tất cả các trình quản lý gói.

Đánh phiên bản theo lịch

Đánh phiên bản theo lịch (CalVer) sử dụng ngày phát hành làm phiên bản — ví dụ: 25.06 cho tháng 6 năm 2025. Cách tiếp cận này phổ biến trong các ứng dụng có bản cập nhật thường xuyên.

CalVer không truyền tải thông tin về mức độ quan trọng của các thay đổi, nhưng hiển thị rõ ràng độ mới của phiên bản. Người dùng hiểu ngay rằng phiên bản 25.06 mới hơn 25.03.

Chọn đánh phiên bản theo lịch nếu ứng dụng của bạn được cập nhật thường xuyên và người dùng quan tâm đến độ mới của dữ liệu hơn là phạm vi thay đổi.

Khuyến nghị lựa chọn

Đối với MVP và startup, phiên bản ngữ nghĩa đơn giản không có vá lỗi (Major.Minor) là phù hợp. Đối với sản phẩm trưởng thành với hỗ trợ dài hạn — SemVer đầy đủ. Đối với ứng dụng có bản phát hành liên tục — CalVer.

Không bao giờ sử dụng ngày tháng làm Build Number — điều này có thể dẫn đến xung đột với nhiều bản dựng trong một ngày. Build Number phải tuần tự hoặc tổng hợp, nhưng luôn tăng đơn điệu.

Các lỗi thường gặp với Marketing Version

Một lỗi điển hình là bỏ qua thành phần phiên bản khi chuyển sang dòng chính mới. Ví dụ, sau phiên bản 1.9.9, phiên bản tiếp theo phải là 2.0.0, không phải 1.10.0. Điều này phá vỡ ngữ nghĩa và gây nhầm lẫn cho người dùng.

Một vấn đề phổ biến khác là sự không khớp giữa Marketing Version trong mã nguồn và trong cửa hàng ứng dụng. Luôn kiểm tra rằng versionName trong build.gradle khớp với phiên bản được chỉ định trong Google Play Console hoặc App Store Connect trước khi gửi bản dựng để xem xét.

Ví dụ thiết lập Marketing Version

Các ví dụ mã cho thấy cách đặt Marketing Version trên cả hai nền tảng và tự động hóa việc cập nhật.

Thiết lập versionName trong Android Gradle

Trên Android, versionName được đặt trong build.gradle. Giá trị có thể tĩnh hoặc được đọc từ biến môi trường.

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

// Đọc phiên bản từ thẻ Git
def getVersionNameFromGit = {
    def tag = "git describe --tags".execute().
        text.trim()
    return tag.startsWith("v") ? tag.substring(1) : tag
}

versionName được trích xuất từ thẻ Git, đảm bảo sự khớp giữa phiên bản trong kho lưu trữ và ứng dụng đã được xây dựng.

Quản lý Marketing Version trong Xcode

Trên iOS, Marketing Version được đặt qua Xcode hoặc agvtool. Lệnh dưới đây đặt một phiên bản tiếp thị mới.

# Thiết lập Marketing Version
xcrun agvtool new-marketing-version 2.1.0

# Tăng tự động
xcrun agvtool next-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 target của dự án Xcode.

Fastlane cho cả hai nền tảng

Fastlane cho phép quản lý Marketing Version trên cả hai nền tảng từ một tập lệnh duy nhất, đơn giản hóa việc bảo trì dự án đa nền tảng.

# Thiết lập phiên bản tiếp thị
increment_version_number(
    version_number: "2.1.0"
)

# Tăng tự động phiên bản phụ
increment_version_number(
    bump_type: "minor"
)

Fastlane hoạt động trên cả hai nền tảng và được hỗ trợ bởi hầu hết các dịch vụ CI/CD.