Tiện ích SDK

Tiện ích SDK tận dụng các thành phần hệ thống mô-đun để thêm API vào SDK công khai cho một số cấp độ API đã phát hành trước đó. Các API này được phân phối đến thiết bị khi người dùng cuối nhận được bản cập nhật mô-đun thông qua bản cập nhật hệ thống Google Play. Nhà phát triển ứng dụng có thể sử dụng các API này trong ứng dụng của mình để cung cấp thêm chức năng vốn không có sẵn trong SDK đối với các phiên bản Android trước.

Tạo phiên bản API

Kể từ Android 11 (API cấp 30), các thiết bị Android sẽ bao gồm một bộ Tiện ích SDK. Khi được thêm vào, các API này sẽ thuộc một cấp độ API nhưng cũng có thể nằm trong một tiện ích SDK của một phiên bản cụ thể. Ví dụ: ACTION_PICK_IMAGES API cho Công cụ chọn ảnh được thêm vào SDK công khai trong Android 13 (API cấp 33), nhưng cũng có trong các tiện ích SDK kể từ các tiện ích R Phiên bản 2. Tên tiện ích SDK tương ứng với một hằng số nguyên. Hằng số đó có thể nằm trong Build.VERSION_CODES hoặc được xác định trong lớp SdkExtensions (chẳng hạn như SdkExtensions.AD_SERVICES).

Xác định Tiện ích SDK cần dùng

Để có thể sử dụng API Tiện ích SDK (SDK Extension API), trước tiên, bạn cần xác định SDK nào chứa API hỗ trợ các trường hợp sử dụng cho ứng dụng của mình.

Các trang tài liệu tham khảo API cho API Tiện ích SDK cho biết phiên bản tiện ích SDK cũ nhất mà ứng dụng của bạn có thể dùng để truy cập API. Nếu tài liệu cũng chỉ định một phiên bản nền tảng Android (được tham chiếu theo cấp độ API), thì API đó cũng có trong tất cả thiết bị chạy phiên bản Android đó trở lên.

Ví dụ: ACTION_PICK_IMAGES thường có trong SDK công khai từ Android 13 (API cấp 33), nhưng cũng có trong các thiết bị từ Android 11 (API cấp 30) với điều kiện tối thiểu là thiết bị có Tiện ích R Phiên bản 2:

Để sử dụng API này, bạn cần biên dịch dựa trên một SDK có cấp độ API tối thiểu là 33, hoặc Cấp độ tiện ích tối thiểu là 2.

Để sử dụng SDK tiện ích, hãy làm theo các bước sau:

1. Tìm phiên bản tiện ích tối thiểu mà bạn cần bằng cách kiểm tra tài liệu về tính năng và tài liệu tham khảo API đối với các API mà bạn muốn sử dụng.
2. Sau khi xác định được phiên bản tiện ích cần thiết cho bộ tính năng của mình, hãy mở Trình quản lý SDK trong Android Studio.
3. Chọn mục Nền tảng SDK Android có phiên bản tiện ích tương ứng (hoặc phiên bản cao hơn, vì API có tính bổ sung). Ví dụ: Nền tảng SDK Android 33, Cấp độ tiện ích 4.

4. Khai báo các giá trị này cho tệp build.gradle.kts hoặc build.gradle trong ứng dụng của bạn:

   Groovy

   android {
       compileSdk 33
       compileSdkExtension 4
       ...
   }
   

   Kotlin

   android {
       compileSdk = 33
       compileSdkExtension = 4
       ...
   }
   

Kiểm tra xem có Tiện ích SDK hay không

Ứng dụng của bạn có thể kiểm tra xem có những phiên bản Tiện ích SDK nào trong thời gian chạy. Đồng thời, trong quá trình phát triển, bạn có thể tìm các phiên bản tiện ích bằng lệnh Cầu gỡ lỗi Android (adb), như mô tả trong các phần sau.

Kiểm tra trong thời gian chạy

Trong thời gian chạy, ứng dụng của bạn có thể kiểm tra xem có Tiện ích SDK trong một phiên bản nền tảng cụ thể hay không bằng phương thức getExtensionVersion(). Ví dụ: Mã sau đây sẽ kiểm tra xem có phiên bản tiện ích 2 trở lên cho Tiện ích SDK Android 11 (API cấp 30) hay không:

fun isPhotoPickerAvailable(): Boolean {
    return SdkExtensions.getExtensionVersion(Build.VERSION_CODES.R) >= 2
    // Safely use extension APIs that are available with Android 11 (API level 30) Extensions Version 2, such as Photo Picker.
}

public static final boolean isPhotoPickerAvailable() {
    return SdkExtensions.getExtensionVersion(Build.VERSION_CODES.R) >= 2;
}

Điều này tương tự như việc kiểm tra dựa trên Build.VERSION.SDK_INT:

fun isPhotoPickerAvailable(): Boolean {
    return Build.VERSION.SDK_INT >= 33
}

public static final boolean isPhotoPickerAvailable() {
    return Build.VERSION.SDK_INT >= 33;
}

Hoạt động kiểm tra SDK_INT này vẫn an toàn và hợp lệ, nhưng isPhotoPickerAvailable sẽ trả về giá trị false (sai) trên một số thiết bị mặc dù có API tiện ích. Do đó, hoạt động kiểm tra SDK_INT không tối ưu. Thay vào đó, bạn nên kiểm tra phiên bản tiện ích để kiểm tra tính sẵn có của API. Tất cả thiết bị có SDK_INT từ 33 trở lên (Android 13 trở lên) đều có API Công cụ chọn ảnh (Photo Picker API) trong SDK công khai, nhưng một số thiết bị có SDK_INT dưới 33 (chẳng hạn như Android 11, 12 và 12L) cũng có thể truy cập API nếu những thiết bị đó có phiên bản tiện ích R tối thiểu là 2.

Trong trường hợp này, việc kiểm tra phiên bản tiện ích có thể giúp ứng dụng của bạn cung cấp chức năng bổ sung cho nhiều người dùng hơn. Xem Tên và hằng số Tiện ích SDK để biết danh sách tất cả hằng số mà bạn có thể dùng để kiểm tra một số Tiện ích SDK nhất định trên thiết bị.

Tiện ích Dịch vụ quảng cáo

Tương tự như tập hợp chung của Tiện ích SDK, tài liệu tham khảo API AdServices đôi khi cho biết API là một phần của phiên bản "Tiện ích Dịch vụ quảng cáo". Không giống như Tiện ích SDK chung, Tiện ích Dịch vụ quảng cáo sử dụng hằng số SdkExtensions.AD_SERVICES để xác định phiên bản có trên thiết bị:

fun isAdServicesAvailable(): Boolean {
    return SdkExtensions.getExtensionVersion(SdkExtensions.AD_SERVICES) >= 4
}

public static final boolean isAdServicesAvailable() {
    return SdkExtensions.getExtensionVersion(SdkExtensions.AD_SERVICES) >= 4;
}

Để tìm hiểu thêm về các tính năng trong Tiện ích Dịch vụ quảng cáo và cách bắt đầu, hãy xem Tài liệu về Tiện ích Dịch vụ quảng cáo.

Phương thức tiện ích

Trong một số trường hợp, Tiện ích SDK có các phương thức tiện ích Jetpack để kiểm tra tính sẵn có của API Tiện ích SDK. Ví dụ: bạn có thể sử dụng hàm thư viện Jetpack để kiểm tra tính sẵn có của PhotoPicker, phương thức này sẽ loại bỏ các hoạt động kiểm tra có điều kiện đối với phiên bản.

Hỗ trợ về công cụ

Trong Android Studio Flamingo | 2022.2.1 trở lên, công cụ tìm lỗi mã nguồn có thể quét tìm vấn đề trong các phiên bản Tiện ích SDK khi kiểm tra NewAPI. Ngoài ra, Android Studio có thể tự động tạo chính xác hoạt động kiểm tra phiên bản cho các API được khởi chạy bằng Tiện ích SDK.

Tên và hằng số của Tiện ích SDK

Bảng sau đây mô tả cách các bộ Tiện ích SDK được liệt kê trong tài liệu tham khảo API ánh xạ đến các hằng số mà ứng dụng của bạn có thể dùng để kiểm tra tính sẵn có của API trong thời gian chạy. Bộ tiện ích SDK chung cho mỗi SDK công khai ánh xạ tới các giá trị của Build.VERSION_CODES.

Kiểm tra bằng adb

Để kiểm tra Tiện ích SDK nào có sẵn trên thiết bị bằng adb, hãy chạy lệnh sau:

adb shell getprop | grep build.version.extensions

Sau khi chạy lệnh, bạn sẽ thấy kết quả có dạng sau:

[build.version.extensions.r]: [3] # Android 11 (API level 30) and higher
[build.version.extensions.s]: [3] # Android 12 (API level 31) and higher
[build.version.extensions.t]: [3] # Android 13 (API level 33) and higher

Mỗi dòng hiển thị một Tiện ích SDK có trên thiết bị cùng với phiên bản tiện ích tương ứng (phiên bản 3 trong trường hợp này).