Lập phiên bản ứng dụng

Việc tạo phiên bản là một phần quan trọng trong chiến lược nâng cấp và bảo trì ứng dụng của bạn. Việc tạo phiên bản quan trọng vì:

• Người dùng cần có thông tin cụ thể về phiên bản ứng dụng đã được cài đặt trên thiết bị của họ và các phiên bản nâng cấp có sẵn để cài đặt.
• Các ứng dụng khác–bao gồm các ứng dụng khác mà bạn phát hành dưới dạng bộ ứng dụng–cần truy vấn hệ thống cho phiên bản của ứng dụng để xác định khả năng tương thích và xác định phần phụ thuộc.
• Dịch vụ mà qua đó bạn sẽ xuất bản (các) ứng dụng của mình cũng có thể cần thực hiện truy vấn để lấy thông tin phiên bản của ứng dụng nhằm trình bày cho người dùng thấy. Dịch vụ phát hành cũng có thể cần kiểm tra phiên bản ứng dụng để xác định khả năng tương thích và thiết lập các mối quan hệ nâng cấp/hạ cấp.

Hệ thống Android sử dụng thông tin về phiên bản của ứng dụng để ngăn việc hạ cấp. Hệ thống này không sử dụng thông tin phiên bản ứng dụng để hạn chế việc nâng cấp hoặc tương thích các ứng dụng bên thứ ba. Ứng dụng của bạn phải thực thi mọi quy tắc hạn chế về phiên bản và phải cho người dùng biết về các quy tắc đó.

Hệ thống Android thực thi khả năng tương thích của phiên bản hệ thống, như được thể hiện trong chế độ cài đặt minSdk trong tệp bản dựng. Chế độ cài đặt này cho phép ứng dụng chỉ định cấp độ API hệ thống tối thiểu tương thích với ứng dụng đó. Để biết thêm thông tin về các yêu cầu đối với API, hãy xem phần Chỉ định yêu cầu về cấp độ API.

Tuỳ theo dự án mà các yêu cầu về phiên bản sẽ khác nhau. Tuy nhiên, nhiều nhà phát triển xem Phiên bản ngữ nghĩa là một cơ sở phù hợp để lập chiến lược tạo phiên bản.

Thiết lập thông tin về phiên bản ứng dụng

Để xác định thông tin phiên bản cho ứng dụng của bạn, hãy thiết lập giá trị cho các tuỳ chọn cài đặt phiên bản trong tệp bản dựng Gradle.

    android {
      namespace 'com.example.testapp'
      compileSdk 33

      defaultConfig {
          applicationId "com.example.testapp"
          minSdk 24
          targetSdk 33
          versionCode 1
          versionName "1.0"
          ...
      }
      ...
    }
    ...
    

    android {
      namespace = "com.example.testapp"
      compileSdk = 33

      defaultConfig {
          applicationId = "com.example.testapp"
          minSdk = 24
          targetSdk = 33
          versionCode = 1
          versionName = "1.0"
          ...
      }
      ...
    }
    ...
      

Chế độ cài đặt phiên bản

Xác định các giá trị cho cả hai chế độ cài đặt phiên bản có sẵn: versionCode và versionName.

versionCode

Một số nguyên dương được dùng làm số phiên bản nội bộ. Số này giúp xác định xem liệu một phiên bản có được ra mắt gần đây hơn một phiên bản khác hay không, và số cao hơn cho biết rằng đó là phiên bản mới hơn. Đây không phải là số phiên bản mà người dùng thấy; số đó được thiết lập bởi chế độ cài đặt versionName bên dưới. Hệ thống Android sử dụng giá trị versionCode để ngăn chặn việc hạ cấp bằng cách không cho phép người dùng cài đặt một APK có versionCode thấp hơn phiên bản cài đặt trên thiết bị của họ.

Giá trị này là một số nguyên dương để các ứng dụng khác có thể dùng để đánh giá bằng phương thức có lập trình (ví dụ: để kiểm tra mối quan hệ nâng cấp hoặc hạ cấp). Bạn có thể thiết lập giá trị này thành bất cứ số nguyên dương nào. uy nhiên, hãy đảm bảo rằng ở mỗi bản phát hành kế tiếp ứng dụng của bạn đều sử dụng một giá trị lớn hơn.

Cảnh báo: Giá trị lớn nhất mà Google Play cho phép đối với versionCode là 2100000000.

Bạn không thể tải một tệp APK lên Cửa hàng Play bằng một versionCode đã sử dụng cho phiên bản trước đó.

Lưu ý: Trong một số trường hợp, bạn có thể cần tải phiên bản ứng dụng có versionCode thấp hơn phiên bản mới nhất lên. Ví dụ: nếu đang xuất bản nhiều APK, bạn có thể thiết lập trước phạm vi versionCode cho một số APK. Để biết thêm về cách chỉ định giá trị versionCode cho nhiều APK, hãy xem phần Chỉ định mã phiên bản.

Thông thường, bạn sẽ phát hành phiên bản đầu tiên của ứng dụng với versionCode được thiết lập là 1, sau đó tăng giá trị này đối với mỗi bản phát hành, bất kể bản phát hành đó sẽ trở thành bản phát hành chính hay nhỏ. Điều này có nghĩa là giá trị versionCode không giống với phiên bản phát hành ứng dụng mà người dùng thấy được. Các ứng dụng và dịch vụ phát hành không được cho người dùng thấy giá trị phiên bản này.

versionName

Một chuỗi được dùng làm số phiên bản mà người dùng sẽ thấy. Tuỳ chọn cài đặt này có thể được chỉ định làm một chuỗi thô hoặc tham chiếu đến một tài nguyên chuỗi.

Giá trị này là một chuỗi để bạn có thể mô tả phiên bản ứng dụng dưới dạng chuỗi <major>.<minor>.<point> hoặc bất cứ loại giá trị nhận dạng phiên bản tuyệt đối hay tương đối nào khác. versionName là giá trị duy nhất mà người dùng nhìn thấy.

Xác định giá trị số phiên bản

Bạn có thể xác định các giá trị mặc định cho các chế độ cài đặt này bằng cách đưa những giá trị đó vào khối defaultConfig {}, lồng trong khối android {} của tệp build.gradle hoặc build.gradle.kts trong mô-đun. Sau đó, bạn có thể ghi đè các giá trị mặc định này cho các phiên bản khác nhau của ứng dụng bằng cách xác định các giá trị riêng biệt cho các loại bản dựng hoặc phiên bản sản phẩm riêng lẻ. Tệp sau đây cho thấy chế độ cài đặt versionCode và versionName trong khối defaultConfig {}, cũng như khối productFlavors {}.

Sau đó, các giá trị này được hợp nhất vào tệp kê khai của ứng dụng trong quá trình tạo bản dựng.

    android {
        ...
        defaultConfig {
            ...
            versionCode 2
            versionName "1.1"
        }
        productFlavors {
            demo {
                ...
                versionName "1.1-demo"
            }
            full {
                ...
            }
        }
    }
    

    android {
        ...
        defaultConfig {
            ...
            versionCode = 2
            versionName = "1.1"
        }
        productFlavors {
            create("demo") {
                ...
                versionName = "1.1-demo"
            }
            create("full") {
                ...
            }
        }
    }
    

Trong khối defaultConfig {} của ví dụ này, giá trị versionCode cho biết rằng APK hiện tại chứa bản phát hành thứ hai của ứng dụng, đồng thời chuỗi versionName chỉ định rằng phiên bản này sẽ xuất hiện cho người dùng dưới dạng phiên bản 1.1. Tệp này cũng xác định hai phiên bản sản phẩm là "demo" (bản minh hoạ) và "full" (bản đầy đủ). Vì phiên bản sản phẩm "demo" này xác định versionName là "1.1-demo", nên bản dựng "demo" sẽ sử dụng versionName này thay vì giá trị mặc định. Khối phiên bản sản phẩm "full" không xác định versionName, vì vậy khối này sử dụng giá trị mặc định là "1.1".

Lưu ý: Nếu ứng dụng của bạn xác định phiên bản ứng dụng ngay trong phần tử <manifest>, thì giá trị phiên bản trong tệp bản dựng Gradle sẽ ghi đè chế độ cài đặt trong tệp kê khai. Ngoài ra, việc xác định các tuỳ chọn cài đặt này trong tệp bản dựng Gradle cho phép bạn chỉ định các giá trị khác nhau cho các phiên bản khác nhau của ứng dụng. Để linh hoạt hơn và tránh khả năng ghi đè tệp khi tệp kê khai được hợp nhất, bạn nên xoá các thuộc tính này khỏi phần tử <manifest> và xác định chế độ cài đặt phiên bản của mình trong tệp bản dựng Gradle.

Khung Android cung cấp một API cho phép bạn truy vấn hệ thống để biết thông tin về phiên bản của ứng dụng. Để có được thông tin phiên bản, hãy sử dụng phương thức PackageManager.getPackageInfo(java.lang.String, int).

Chỉ định yêu cầu đối với cấp độ API

Nếu ứng dụng của bạn yêu cầu một phiên bản tối thiểu cụ thể của nền tảng Android, bạn có thể chỉ định chế độ cài đặt yêu cầu về cấp độ API của phiên bản đó trong tệp build.gradle hoặc build.gradle.kts của ứng dụng. Trong quá trình tạo bản dựng, các tuỳ chọn cài đặt này sẽ được hợp nhất vào tệp kê khai của ứng dụng. Việc chỉ định yêu cầu về cấp độ API đảm bảo rằng ứng dụng của bạn chỉ có thể được cài đặt trên các thiết bị đang chạy phiên bản nền tảng Android tương thích.

Lưu ý: Nếu bạn chỉ định trực tiếp các yêu cầu về cấp độ API trong tệp kê khai của ứng dụng, thì các chế độ cài đặt tương ứng trong tệp bản dựng sẽ ghi đè chế độ cài đặt trong tệp kê khai. Ngoài ra, việc xác định các tuỳ chọn cài đặt này trong tệp bản dựng Gradle cho phép bạn chỉ định các giá trị khác nhau cho các phiên bản khác nhau của ứng dụng. Để linh hoạt hơn và tránh khả năng ghi đè khi tệp kê khai được hợp nhất, bạn nên xoá các thuộc tính này khỏi phần tử <uses-sdk> và xác định chế độ cài đặt cấp độ API của mình trong các tệp bản dựng Gradle.

Có hai chế độ cài đặt cấp độ API:

• minSdk – Phiên bản tối thiểu của nền tảng Android mà ứng dụng sẽ chạy, do giá trị nhận dạng cấp độ API của nền tảng chỉ định.
• targetSdk – Chỉ định cấp độ API mà bạn dùng để chạy ứng dụng. Trong một số trường hợp, việc này cho phép ứng dụng sử dụng các phần tử hoặc hành vi tệp kê khai được xác định ở cấp độ API mục tiêu, thay vì chỉ giới hạn việc sử dụng các phần tử được xác định cho cấp API tối thiểu.

Để chỉ định các yêu cầu về cấp độ API mặc định trong tệp build.gradle hoặc build.gradle.kts, hãy thêm một hoặc nhiều chế độ cài đặt cấp độ API vào khối defaultConfig{}, lồng trong khối android {}. Bạn cũng có thể ghi đè các giá trị mặc định này cho các phiên bản khác nhau của ứng dụng bằng cách thêm các tuỳ chọn cài đặt để xây dựng loại bản dựng hoặc phiên bản sản phẩm.

Tệp sau đây chỉ định các chế độ cài đặt mặc định cho minSdk và targetSdk trong khối defaultConfig {} và ghi đè minSdk cho một phiên bản sản phẩm.

android {
    ...
    defaultConfig {
        ...
        minSdk 21
        targetSdk 33
    }
    productFlavors {
        main {
            ...
        }
        afterNougat {
            ...
            minSdk 24
        }
    }
}

android {
    ...
    defaultConfig {
        ...
        minSdk = 21
        targetSdk = 33
    }
    productFlavors {
        create("main") {
            ...
        }
        create("afterNougat") {
            ...
            minSdk = 24
        }
    }
}

Khi chuẩn bị cài đặt ứng dụng của bạn, hệ thống sẽ kiểm tra giá trị của các tuỳ chọn cài đặt này và so sánh với phiên bản hệ thống. Nếu giá trị minSdk lớn hơn phiên bản hệ thống, thì hệ thống sẽ ngăn không cho cài đặt ứng dụng.

Nếu bạn không chỉ định các chế độ cài đặt này, hệ thống sẽ mặc định rằng ứng dụng của bạn tương thích với tất cả phiên bản nền tảng. Điều này tương đương với việc thiết lập minSdk thành 1.

Để biết thêm thông tin, hãy xem bài viết Cấp độ API là gì?. Đối với tuỳ chọn cài đặt bản dựng Gradle, hãy xem phần Định cấu hình biến thể bản dựng.