Xây dựng nhiều APK

Thận trọng: Kể từ tháng 8 năm 2021, bạn phải phát hành tất cả ứng dụng mới dưới dạng Gói ứng dụng. Nếu bạn phát hành ứng dụng lên Google Play, hãy tạo và tải một tệp Android App Bundle lên. Khi bạn làm như vậy, Google Play sẽ tự động tạo và phân phát các tệp APK được tối ưu hoá cho cấu hình thiết bị của từng người dùng. Vì vậy, họ chỉ tải mã và tài nguyên cần thiết xuống để chạy ứng dụng của bạn. Việc xuất bản nhiều tệp APK sẽ hữu ích nếu bạn đang phát hành lên một cửa hàng không hỗ trợ định dạng AAB. Trong trường hợp đó, bạn phải tự xây dựng, ký và quản lý từng tệp APK.

Mặc dù tốt hơn là bạn nên tạo một tệp APK duy nhất để hỗ trợ tất cả thiết bị mục tiêu bất cứ khi nào có thể, nhưng điều này có thể dẫn đến một tệp APK rất lớn do các tệp hỗ trợ nhiều mật độ màn hình hoặc Giao diện nhị phân của ứng dụng (ABI). Một cách để giảm kích thước tệp APK là tạo nhiều tệp APK chứa các tệp có mật độ màn hình hoặc ABI cụ thể.

Gradle có thể tạo nhiều APK riêng biệt chỉ chứa mã và tài nguyên cụ thể cho từng mật độ hoặc ABI. Trang này mô tả cách định cấu hình bản dựng để tạo nhiều APK. Nếu bạn cần tạo nhiều phiên bản ứng dụng không dựa trên mật độ màn hình hoặc ABI (Giao diện nhị phân ứng dụng), hãy sử dụng biến thể bản dựng.

Định cấu hình bản dựng cho nhiều APK

Để định cấu hình bản dựng cho nhiều APK, hãy thêm khối splits vào tệp build.gradle cấp mô-đun. Trong khối splits, hãy cung cấp một khối density chỉ định cách bạn muốn Gradle tạo các tệp APK theo mật độ hoặc một khối abi chỉ định cách bạn muốn Gradle tạo các tệp APK theo ABI. Bạn có thể cung cấp cả khối mật độ và khối ABI. Hệ thống xây dựng sẽ tạo một APK cho mỗi tổ hợp mật độ và ABI.

Lưu ý: Chức năng tạo APK theo ngôn ngữ chỉ được hỗ trợ cho các dự án Ứng dụng Android tức thì

Định cấu hình nhiều APK cho mật độ màn hình

Để tạo các APK riêng cho các mật độ màn hình khác nhau, hãy thêm một khối density bên trong khối splits. Trong khối density, hãy cung cấp danh sách các mật độ màn hình và kích thước màn hình tương thích mong muốn. Chỉ sử dụng danh sách kích thước màn hình tương thích nếu bạn cần các phần tử <compatible-screens> cụ thể trong tệp kê khai của mỗi tệp APK.

Các tùy chọn DSL Gradle sau đây được dùng để định cấu hình nhiều APK cho các mật độ màn hình:

enable đối với Groovy, isEnable đối với tập lệnh Kotlin

Nếu bạn thiết lập phần tử này thành true, Gradle sẽ tạo nhiều APK dựa trên mật độ màn hình mà bạn xác định. Giá trị mặc định là false.

exclude

Chỉ định một danh sách mật độ được phân tách bằng dấu phẩy mà bạn không muốn Gradle tạo các APK riêng biệt. Sử dụng exclude nếu bạn muốn tạo APK cho hầu hết các mật độ nhưng cần loại trừ một vài mật độ mà ứng dụng của bạn không hỗ trợ.

reset()

Xoá danh sách mật độ màn hình mặc định. Chỉ sử dụng khi kết hợp với phần tử include để chỉ định mật độ mà bạn muốn thêm.

Đoạn mã sau đây sẽ đặt danh sách mật độ thành chỉ ldpi và xxhdpi bằng cách gọi reset() để xoá danh sách, sau đó sử dụng include:

reset()                  // Clears the default list from all densities
                         // to no densities.
include "ldpi", "xxhdpi" // Specifies the two densities to generate APKs
                         // for.

include

Chỉ định một danh sách mật độ được phân tách bằng dấu phẩy mà bạn muốn Gradle tạo APK. Chỉ sử dụng kết hợp với reset() để chỉ định danh sách mật độ chính xác.

compatibleScreens

Chỉ định danh sách các kích thước màn hình tương thích được phân tách bằng dấu phẩy. Thao tác này sẽ chèn một nút <compatible-screens> phù hợp trong tệp kê khai cho từng APK.

Chế độ cài đặt này giúp bạn quản lý cả mật độ màn hình và kích thước màn hình một cách thuận tiện trong cùng một mục build.gradle. Tuy nhiên, việc sử dụng <compatible-screens> có thể giới hạn các loại thiết bị mà ứng dụng của bạn tương thích. Để biết những cách khác giúp hỗ trợ nhiều kích thước màn hình, hãy xem bài viết tổng quan về khả năng tương thích với màn hình.

Vì mỗi tệp APK dựa trên mật độ màn hình bao gồm một thẻ <compatible-screens> có các hạn chế cụ thể về những loại màn hình mà tệp APK đó hỗ trợ (ngay cả khi bạn phát hành nhiều tệp APK), nên một số thiết bị mới không khớp với nhiều bộ lọc tệp APK của bạn. Do đó, Gradle luôn tạo một tệp APK chung bổ sung chứa các thành phần cho mọi mật độ màn hình và không chứa thẻ <compatible-screens>. Phát hành tệp APK chung này cùng với tệp APK theo mật độ để cung cấp tính năng dự phòng cho các thiết bị không khớp với tệp APK có thẻ <compatible-screens>.

Ví dụ sau đây tạo ra một APK riêng cho từng mật độ màn hình, ngoại trừ ldpi, xxhdpi và xxxhdpi. Bạn có thể thực hiện việc này bằng cách sử dụng exclude để xoá 3 mật độ đó khỏi danh sách mặc định của tất cả các mật độ.

Groovy

android {
  ...
  splits {

    // Configures multiple APKs based on screen density.
    density {

      // Configures multiple APKs based on screen density.
      enable true

      // Specifies a list of screen densities you don't want Gradle to create multiple APKs for.
      exclude "ldpi", "xxhdpi", "xxxhdpi"

      // Specifies a list of compatible screen size settings for the manifest.
      compatibleScreens 'small', 'normal', 'large', 'xlarge'
    }
  }
}

Kotlin

android {
    ...
    splits {

        // Configures multiple APKs based on screen density.
        density {

            // Configures multiple APKs based on screen density.
            isEnable = true

            // Specifies a list of screen densities you don't want Gradle to create multiple APKs for.
            exclude("ldpi", "xxhdpi", "xxxhdpi")

            // Specifies a list of compatible screen size settings for the manifest.
            compatibleScreens("small", "normal", "large", "xlarge")
        }
    }
}

Để biết danh sách tên mật độ và tên kích thước màn hình, hãy xem phần Hỗ trợ nhiều kích thước màn hình. Để biết thêm thông tin chi tiết về cách tuỳ chỉnh các biến thể bản dựng khác nhau của ứng dụng theo các loại màn hình và thiết bị cụ thể, hãy xem nội dung Khai báo hỗ trợ màn hình bị hạn chế.

Định cấu hình nhiều APK cho ABI

Để tạo các APK riêng cho từng ABI, hãy thêm một khối abi bên trong khối splits của bạn. Trong khối abi, hãy cung cấp danh sách các ABI mà bạn muốn.

Các tuỳ chọn DSL Gradle sau đây được dùng để định cấu hình nhiều APK cho mỗi ABI:

enable đối với Groovy hoặc isEnable đối với tập lệnh Kotlin

Nếu bạn thiết lập phần tử này thành true, Gradle sẽ tạo nhiều APK dựa trên các ABI mà bạn xác định. Giá trị mặc định là false.

exclude

Chỉ định một danh sách ABI được phân tách bằng dấu phẩy mà bạn không muốn Gradle tạo các APK riêng. Hãy sử dụng exclude nếu bạn muốn tạo APK cho hầu hết các ABI nhưng cần loại trừ một số ABI mà ứng dụng của bạn không hỗ trợ.

reset()

Xoá danh sách ABI mặc định. Chỉ sử dụng khi kết hợp với phần tử include để chỉ định ABI mà bạn muốn thêm.

Đoạn mã sau đây sẽ thiết lập danh sách ABI thành chỉ x86 và x86_64 bằng cách gọi reset() để xoá danh sách, sau đó sử dụng include:

reset()                 // Clears the default list from all ABIs to no ABIs.
include "x86", "x86_64" // Specifies the two ABIs we want to generate APKs for.

include

Chỉ định danh sách ABI được phân tách bằng dấu phẩy mà bạn muốn Gradle tạo APK. Chỉ sử dụng kết hợp với reset() để chỉ định danh sách ABI chính xác.

universalApk đối với Groovy hoặc isUniversalApk đối với tập lệnh Kotlin

Nếu true, Gradle sẽ tạo một APK chung ngoài các APK theo ABI. Một APK chung chứa mã và tài nguyên cho tất cả ABI trong một APK duy nhất. Giá trị mặc định là false.

Xin lưu ý rằng tuỳ chọn này chỉ có trong khối splits.abi. Khi xây dựng nhiều APK dựa trên mật độ màn hình, Gradle luôn tạo một APK chung chứa mã và tài nguyên cho mọi mật độ màn hình.

Ví dụ sau đây sẽ tạo ra một APK riêng cho mỗi ABI: x86 và x86_64. Bạn có thể thực hiện việc này bằng cách sử dụng reset() để bắt đầu với danh sách ABI trống, tiếp theo là include kèm theo danh sách ABI mà mỗi ABI nhận được một APK.

Groovy

android {
  ...
  splits {

    // Configures multiple APKs based on ABI.
    abi {

      // Enables building multiple APKs per ABI.
      enable true

      // By default all ABIs are included, so use reset() and include to specify that you only
      // want APKs for x86 and x86_64.

      // Resets the list of ABIs for Gradle to create APKs for to none.
      reset()

      // Specifies a list of ABIs for Gradle to create APKs for.
      include "x86", "x86_64"

      // Specifies that you don't want to also generate a universal APK that includes all ABIs.
      universalApk false
    }
  }
}

Kotlin

android {
  ...
  splits {

    // Configures multiple APKs based on ABI.
    abi {

      // Enables building multiple APKs per ABI.
      isEnable = true

      // By default all ABIs are included, so use reset() and include to specify that you only
      // want APKs for x86 and x86_64.

      // Resets the list of ABIs for Gradle to create APKs for to none.
      reset()

      // Specifies a list of ABIs for Gradle to create APKs for.
      include("x86", "x86_64")

      // Specifies that you don't want to also generate a universal APK that includes all ABIs.
      isUniversalApk = false
    }
  }
}

Để biết danh sách các ABI được hỗ trợ, hãy xem phần Các ABI được hỗ trợ.

Dự án không có mã gốc/C++

Đối với các dự án không có mã gốc/C++, bảng điều khiển Build Variants (Biến thể bản dựng) có 2 cột: Module (Mô-đun) và Active BuildVariant (Biến thể bản dựng đang hoạt động) như trong hình 1.

Hình 1. Bảng điều khiển Build Variants (Biến thể bản dựng) có 2 cột cho các dự án không có mã gốc/C++.

Giá trị Active Build Variant (Biến thể bản dựng đang hoạt động) của mô-đun xác định biến thể bản dựng được triển khai và xuất hiện trong trình chỉnh sửa. Để chuyển đổi giữa các biến thể, hãy nhấp vào ô Active Build Variant (Biến thể bản dựng đang hoạt động) của một mô-đun và chọn biến thể mong muốn trong trường danh sách.

Dự án có mã gốc/C++

Đối với các dự án có mã gốc/C++, bảng điều khiển Build Variants (Biến thể bản dựng) có 3 cột: Module (Mô-đun), Active BuildVariant (Biến thể bản dựng đang hoạt động) và Active ABI (ABI đang hoạt động), như minh hoạ trong hình 2.

Hình 2. Bảng điều khiển Build Variants (Biến thể bản dựng) sẽ thêm cột Active ABI (ABI đang hoạt động) cho dự án có mã gốc/C++.

Giá trị Active Build Variant (Biến thể bản dựng đang hoạt động) của mô-đun giúp xác định biến thể bản dựng được triển khai và xuất hiện trong trình chỉnh sửa. Đối với các mô-đun gốc, giá trị Active ABI (ABI đang hoạt động) xác định ABI mà trình chỉnh sửa sử dụng, nhưng không ảnh hưởng đến nội dung được triển khai.

Cách thay đổi loại bản dựng hoặc ABI:

1. Nhấp vào ô của cột Active Build Variant (Biến thể bản dựng đang hoạt động) hoặc Active ABI (ABI đang hoạt động).
2. Chọn biến thể hoặc ABI mong muốn trong trường danh sách. Quá trình đồng bộ mới sẽ tự động chạy.

Khi một ứng dụng hoặc mô-đun thư viện có thay đổi thì thay đổi đó sẽ áp dụng cho tất cả các hàng phụ thuộc.

Định cấu hình phiên bản

Theo mặc định, khi Gradle tạo nhiều APK, mỗi APK sẽ có cùng một thông tin phiên bản, như được chỉ định trong tệp build.gradle hoặc build.gradle.kts ở cấp mô-đun. Vì Cửa hàng Google Play không cho phép nhiều APK cho cùng một ứng dụng mà tất cả đều có cùng thông tin phiên bản, nên bạn cần đảm bảo rằng mỗi APK có một versionCode duy nhất trước khi tải lên Cửa hàng Play.

Bạn có thể định cấu hình tệp build.gradle cấp mô-đun để ghi đè versionCode cho từng APK. Bằng cách tạo một mục ánh xạ chỉ định một giá trị số duy nhất cho mỗi ABI và mật độ mà bạn định cấu hình nhiều APK, bạn có thể ghi đè mã phiên bản đầu ra bằng một giá trị kết hợp mã phiên bản được xác định trong khối defaultConfig hoặc productFlavors với giá trị số được chỉ định cho mật độ hoặc ABI.

Trong ví dụ sau, APK cho ABI x86 nhận được versionCode là 2004 và ABI x86_64 nhận được versionCode là 3004.

Việc chỉ định mã phiên bản theo từng mức tăng lớn, chẳng hạn như 1000, cho phép bạn chỉ định mã phiên bản duy nhất sau này nếu cần cập nhật ứng dụng. Ví dụ: nếu defaultConfig.versionCode lặp lại thành 5 trong lần cập nhật tiếp theo, thì Gradle sẽ gán versionCode là 2005 cho APK x86 và 3005 cho APK x86_64.

Mẹo: Nếu bản dựng của bạn có chứa một tệp APK chung, hãy chỉ định cho tệp đó một versionCode thấp hơn so với bất kỳ tệp APK nào khác của bạn. Do Cửa hàng Google Play cài đặt phiên bản ứng dụng vừa tương thích với thiết bị mục tiêu vừa có versionCode cao nhất, nên việc chỉ định versionCode thấp hơn cho APK chung sẽ đảm bảo Cửa hàng Google Play có thể cài đặt một trong các APK của bạn trước khi quay lại APK chung. Mã mẫu sau đây xử lý vấn đề này bằng cách không ghi đè versionCode mặc định của APK chung.

Groovy

android {
  ...
  defaultConfig {
    ...
    versionCode 4
  }
  splits {
    ...
  }
}

// Map for the version code that gives each ABI a value.
ext.abiCodes = ['armeabi-v7a':1, x86:2, x86_64:3]

// For per-density APKs, create a similar map:
// ext.densityCodes = ['mdpi': 1, 'hdpi': 2, 'xhdpi': 3]

import com.android.build.OutputFile

// For each APK output variant, override versionCode with a combination of
// ext.abiCodes * 1000 + variant.versionCode. In this example, variant.versionCode
// is equal to defaultConfig.versionCode. If you configure product flavors that
// define their own versionCode, variant.versionCode uses that value instead.
android.applicationVariants.all { variant ->

  // Assigns a different version code for each output APK
  // other than the universal APK.
  variant.outputs.each { output ->

    // Stores the value of ext.abiCodes that is associated with the ABI for this variant.
    def baseAbiVersionCode =
            // Determines the ABI for this variant and returns the mapped value.
            project.ext.abiCodes.get(output.getFilter(OutputFile.ABI))

    // Because abiCodes.get() returns null for ABIs that are not mapped by ext.abiCodes,
    // the following code doesn't override the version code for universal APKs.
    // However, because you want universal APKs to have the lowest version code,
    // this outcome is desirable.
    if (baseAbiVersionCode != null) {

      // Assigns the new version code to versionCodeOverride, which changes the
      // version code for only the output APK, not for the variant itself. Skipping
      // this step causes Gradle to use the value of variant.versionCode for the APK.
      output.versionCodeOverride =
              baseAbiVersionCode * 1000 + variant.versionCode
    }
  }
}

Kotlin

android {
  ...
  defaultConfig {
    ...
    versionCode = 4
  }
  splits {
    ...
  }
}

// Map for the version code that gives each ABI a value.
val abiCodes = mapOf("armeabi-v7a" to 1, "x86" to 2, "x86_64" to 3)

// For per-density APKs, create a similar map:
// val densityCodes = mapOf("mdpi" to 1, "hdpi" to 2, "xhdpi" to 3)

import com.android.build.api.variant.FilterConfiguration.FilterType.*

// For each APK output variant, override versionCode with a combination of
// abiCodes * 1000 + variant.versionCode. In this example, variant.versionCode
// is equal to defaultConfig.versionCode. If you configure product flavors that
// define their own versionCode, variant.versionCode uses that value instead.
androidComponents {
    onVariants { variant ->

        // Assigns a different version code for each output APK
        // other than the universal APK.
        variant.outputs.forEach { output ->
            val name = output.filters.find { it.filterType == ABI }?.identifier

            // Stores the value of abiCodes that is associated with the ABI for this variant.
            val baseAbiCode = abiCodes[name]
            // Because abiCodes.get() returns null for ABIs that are not mapped by ext.abiCodes,
            // the following code doesn't override the version code for universal APKs.
            // However, because you want universal APKs to have the lowest version code,
            // this outcome is desirable.
            if (baseAbiCode != null) {
                // Assigns the new version code to output.versionCode, which changes the version code
                // for only the output APK, not for the variant itself.
                output.versionCode.set(baseAbiCode * 1000 + (output.versionCode.get() ?: 0))
            }
        }
    }
}

Để biết thêm ví dụ về các lược đồ mã phiên bản thay thế, hãy xem phần Chỉ định mã phiên bản.

Xây dựng nhiều APK

Sau khi bạn định cấu hình tệp build.gradle hoặc build.gradle.kts ở cấp mô-đun để xây dựng nhiều APK, hãy nhấp vào Build > Build APK (Tạo > Tạo APK) để tạo tất cả APK cho mô-đun hiện được chọn trong ngăn Project (Dự án). Gradle sẽ tạo các APK cho mỗi mật độ hoặc ABI trong thư mục build/outputs/apk/ của dự án.

Gradle sẽ xây dựng một APK cho mỗi mật độ hoặc ABI mà bạn định cấu hình nhiều APK. Nếu bạn cho phép nhiều APK cho cả mật độ và ABI, Gradle sẽ tạo một APK cho mỗi tổ hợp mật độ và ABI.

Ví dụ: đoạn mã build.gradle sau đây cho phép tạo nhiều APK cho mật độ mdpi và hdpi, cũng như các ABI x86 và x86_64:

Groovy

...
  splits {
    density {
      enable true
      reset()
      include "mdpi", "hdpi"
    }
    abi {
      enable true
      reset()
      include "x86", "x86_64"
    }
  }

Kotlin

...
  splits {
    density {
      isEnable = true
      reset()
      include("mdpi", "hdpi")
    }
    abi {
      isEnable = true
      reset()
      include("x86", "x86_64")
    }
  }

Kết quả từ cấu hình mẫu bao gồm 4 APK sau:

• app-hdpiX86-release.apk: Chứa mã và tài nguyên cho mật độ hdpi và ABI x86.
• app-hdpiX86_64-release.apk: Chứa mã và tài nguyên cho mật độ hdpi và ABI x86_64.
• app-mdpiX86-release.apk: Chứa mã và tài nguyên cho mật độ mdpi và ABI x86.
• app-mdpiX86_64-release.apk: Chứa mã và tài nguyên cho mật độ mdpi và ABI x86_64.

Khi xây dựng nhiều APK dựa trên mật độ màn hình, Gradle luôn tạo một APK chung, bao gồm mã và tài nguyên cho tất cả các mật độ, ngoài các APK theo mật độ.

Khi xây dựng nhiều APK dựa trên ABI, Gradle chỉ tạo một APK chứa mã và tài nguyên cho tất cả ABI nếu bạn chỉ định universalApk true trong khối splits.abi trong tệp build.gradle (đối với Groovy) hoặc isUniversalApk = true trong khối splits.abi trong tệp build.gradle.kts (đối với tập lệnh Kotlin).

Định dạng tên tệp APK

Khi xây dựng nhiều APK, Gradle sẽ tạo tên tệp APK bằng giao thức sau:

modulename-screendensityABI-buildvariant.apk

Thành phần của lược đồ này bao gồm:

modulename

Chỉ định tên mô-đun đang được xây dựng.

screendensity

Nếu bạn bật nhiều tệp APK cho mật độ màn hình, hãy chỉ định mật độ màn hình cho tệp APK, chẳng hạn như mdpi.

ABI

Nếu bạn bật nhiều APK cho ABI, hãy chỉ định ABI cho APK, chẳng hạn như x86.

Nếu bạn bật nhiều APK cho cả mật độ màn hình và ABI, Gradle sẽ liên kết tên mật độ với tên ABI, ví dụ như mdpiX86. Nếu bạn bật universalApk cho các APK theo ABI, Gradle sẽ sử dụng universal làm phần ABI của tên tệp APK chung.

buildvariant

Chỉ định biến thể bản dựng đang được tạo, chẳng hạn như debug.

Ví dụ: khi tạo tệp APK mật độ màn hình mdpi cho phiên bản gỡ lỗi của myApp, tên tệp APK là myApp-mdpi-debug.apk. Phiên bản phát hành của myApp được định cấu hình để xây dựng nhiều APK cho cả mật độ màn hình mdpi và ABI x86 có tên tệp APK là myApp-mdpiX86-release.apk.