Trang này được dịch bởi Cloud Translation API.

Công cụ khung tương thích

Android 11 giới thiệu một số công cụ mới cho nhà phát triển để kiểm thử và gỡ lỗi ứng dụng dựa trên các thay đổi về hành vi trong các phiên bản mới của nền tảng Android. Các công cụ này nằm trong một khung tương thích (compatibility framework) cho phép nhà phát triển ứng dụng bật và tắt các thay đổi có thể gây lỗi một cách riêng lẻ qua tuỳ chọn cho nhà phát triển hoặc ADB. Hãy sử dụng tính linh hoạt này khi bạn chuẩn bị nhắm đến phiên bản API ổn định mới nhất, cũng như khi bạn kiểm thử ứng dụng qua bản phát hành xem trước của phiên bản Android tiếp theo.

Khi bạn dùng các công cụ trong khung tương thích, nền tảng Android sẽ tự động điều chỉnh logic nội bộ, vì vậy, bạn không cần thay đổi targetSDKVersion hoặc biên dịch lại ứng dụng để thực hiện kiểm thử cơ bản. Vì các thay đổi có thể bật/tắt riêng lẻ, nên bạn có thể tách biệt, kiểm thử và gỡ lỗi từng thay đổi về hành vi hoặc tắt một thay đổi duy nhất gây ra vấn đề nếu trước tiên bạn cần kiểm thử một thay đổi khác.

Cách xác định xem thay đổi nào được bật

Khi bạn bật thay đổi về hành vi, thay đổi đó có thể ảnh hưởng đến cách ứng dụng của bạn truy cập nào các API nền tảng chịu ảnh hưởng của thay đổi đó. Bạn có thể kiểm tra xem thay đổi nào về hành vi đã được bật bằng cách sử dụng tuỳ chọn cho nhà phát triển, logcat hoặc lệnh ADB.

Sử dụng tuỳ chọn cho nhà phát triển để xác định các thay đổi được bật

Hình 1. Màn hình các thay đổi về khả năng tương thích của ứng dụng trong tuỳ chọn cho nhà phát triển.

Bạn có thể xem thay đổi nào được bật và bật hoặc tắt các thay đổi đó trong tuỳ chọn cho nhà phát triển trên thiết bị. Để truy cập những tuỳ chọn này, hãy làm theo các bước sau:

Nếu tuỳ chọn cho nhà phát triển chưa được bật, hãy bật các tuỳ chọn đó.
Mở ứng dụng Cài đặt trên thiết bị và chuyển đến System (Hệ thống) > Advanced (Nâng cao) > Developer options (Tuỳ chọn cho nhà phát triển) > App Compatibility Changes (Thay đổi về khả năng tương thích của ứng dụng).
Chọn ứng dụng của bạn trong danh sách.

Lưu ý: Bạn phải sử dụng biến thể bản dựng có thể gỡ lỗi của ứng dụng để bật và tắt các thay đổi.

Thay đổi về hành vi thường thuộc một trong hai danh mục sau:

Thay đổi ảnh hưởng đến tất cả ứng dụng chạy trên một phiên bản Android cụ thể, bất kể targetSdkVersion của ứng dụng là gì.

Những thay đổi này được bật theo mặc định trong khung tương thích và có trong giao diện người dùng ở phần Các thay đổi được bật theo mặc định.
Thay đổi chỉ ảnh hưởng đến những ứng dụng đang nhắm đến một số phiên bản Android cụ thể. Do các thay đổi này chỉ ảnh hưởng đến những ứng dụng nhắm đến một phiên bản Android cụ thể, nên chúng cũng được gọi là thay đổi do targetSDKVersion kiểm soát.

Theo mặc định, các thay đổi này sẽ được bật trong khung tương thích nếu ứng dụng đang nhắm đến phiên bản cao hơn phiên bản API đã liệt kê. Ví dụ: thay đổi về hành vi do targetSDKVersion kiểm soát trong Android 13 (API cấp 33) sẽ được liệt kê trong giao diện người dùng, một phần có tiêu đề là Enabled for targetSdkVersion >=33 (Bật cho targetSdkVersion >=33). Trên một số phiên bản Android thấp hơn, phần này có tiêu đề "Enabled after SDK API_LEVEL" (Bật sau SDK).

Lưu ý: Trong bản dùng thử Android 15 cho đến khi hoàn tất cấp độ API, một số thay đổi chỉ được bật khi nhắm mục tiêu Android 15 sử dụng giá trị 10000 cho cấp độ API thay vì cấp độ API cuối cùng được giả định là 35.

Bạn cũng sẽ thấy một phần trong hình 1 tên là Thay đổi được tắt theo mặc định. Các thay đổi thuộc phần này có thể phục vụ nhiều mục đích. Trước khi bật các thay đổi này, hãy đọc nội dung mô tả về thay đổi trong danh sách khung tương thích cho phiên bản Android đó.

Sử dụng logcat để xác định các thay đổi được bật

Đối với mỗi thay đổi về hành vi, trong lần đầu tiên trong quy trình của ứng dụng khi ứng dụng gọi API bị ảnh hưởng, hệ thống sẽ cho thấy một thông báo logcat như sau:

D CompatibilityChangeReporter: Compat change id reported: 194833441; UID 10265; state: ENABLED

Mỗi thông báo logcat bao gồm cả những thông tin sau:

Mã thay đổi

Cho biết thay đổi nào đang ảnh hưởng đến ứng dụng. Giá trị này tương ứng với một trong số thay đổi về hành vi nêu trên màn hình App Compatibility Changes (Thay đổi về khả năng tương thích của ứng dụng) (xem hình 1). Trong ví dụ này, 194833441 liên kết tới NOTIFICATION_PERM_CHANGE_ID.

UID

Cho biết ứng dụng nào chịu ảnh hưởng của thay đổi này.

Trạng thái

Cho biết liệu thay đổi này có ảnh hưởng đến ứng dụng hay không.

Trạng thái có thể là một trong những giá trị sau:

Trạng thái Ý nghĩa

ENABLED Thay đổi này sẽ được bật và sẽ ảnh hưởng đến hành vi của ứng dụng nếu ứng dụng dùng các API đã thay đổi.

Trạng thái	Ý nghĩa
`ENABLED`	Thay đổi này sẽ được bật và sẽ ảnh hưởng đến hành vi của ứng dụng nếu ứng dụng dùng các API đã thay đổi.
`DISABLED`	Thay đổi này sẽ bị tắt và không ảnh hưởng đến ứng dụng. Lưu ý: Nếu bạn tắt thay đổi này vì `targetSDKVersion` của ứng dụng thấp hơn ngưỡng bắt buộc, thì thay đổi này sẽ được bật theo mặc định khi ứng dụng tăng `targetSDKVersion` để nhắm đến một phiên bản cao hơn.
`LOGGED`	Thay đổi này đang được ghi lại qua khung tương thích nhưng bạn không thể bật hoặc tắt thay đổi này. Tuy bạn không thể bật hoặc tắt thay đổi này, nhưng thay đổi này vẫn có thể ảnh hưởng đến hành vi của ứng dụng. Hãy xem phần mô tả về thay đổi trong danh sách khung tương thích của phiên bản Android để biết thêm thông tin. Trong nhiều trường hợp, các loại thay đổi này là thử nghiệm và có thể bị bỏ qua.

DISABLED

Thay đổi này sẽ bị tắt và không ảnh hưởng đến ứng dụng.

Lưu ý: Nếu bạn tắt thay đổi này vì targetSDKVersion của ứng dụng thấp hơn ngưỡng bắt buộc, thì thay đổi này sẽ được bật theo mặc định khi ứng dụng tăng targetSDKVersion để nhắm đến một phiên bản cao hơn.

LOGGED Thay đổi này đang được ghi lại qua khung tương thích nhưng bạn không thể bật hoặc tắt thay đổi này. Tuy bạn không thể bật hoặc tắt thay đổi này, nhưng thay đổi này vẫn có thể ảnh hưởng đến hành vi của ứng dụng. Hãy xem phần mô tả về thay đổi trong danh sách khung tương thích của phiên bản Android để biết thêm thông tin. Trong nhiều trường hợp, các loại thay đổi này là thử nghiệm và có thể bị bỏ qua.

Sử dụng ADB để xác định các thay đổi được bật

Chạy lệnh ADB sau đây để xem toàn bộ thay đổi (cả đang bật và tắt) trên toàn bộ thiết bị:

adb shell dumpsys platform_compat

Kết quả cho thấy thông tin sau đây cho mỗi thay đổi:

Mã thay đổi

Giá trị nhận dạng riêng biệt cho thay đổi về hành vi này. Ví dụ: 194833441.

Tên

Tên của thay đổi về hành vi này. Ví dụ: NOTIFICATION_PERM_CHANGE_ID.

Tiêu chí targetSDKVersion

Loại targetSDKVersion kiểm soát thay đổi này (nếu có).

Ví dụ: nếu thay đổi này chỉ được bật cho các ứng dụng nhắm đến SDK phiên bản 33 trở lên, thì kết quả là enableAfterTargetSdk=32. Nếu targetSDKVersion không kiểm soát thay đổi này, thì kết quả là enableAfterTargetSdk=0.

Ghi đè gói

Tên của từng gói đã bị ghi đè trạng thái mặc định của thay đổi (bật hoặc tắt).

Ví dụ: nếu đây là thay đổi được bật theo mặc định, thì tên gói của ứng dụng sẽ được liệt kê nếu bạn tắt thay đổi bằng tuỳ chọn cho nhà phát triển hoặc ADB. Trong trường hợp này, kết quả sẽ là:

packageOverrides={com.my.package=false}

Các thay đổi do targetSDKVersion kiểm soát có thể được bật hoặc tắt theo mặc định, vì vậy, danh sách gói có thể bao gồm các thực thể của cả true hoặc false, tuỳ thuộc vào từng targetSDKVersion của ứng dụng đó. Ví dụ:

packageOverrides={com.my.package=true, com.another.package=false}

Tìm hiểu thêm về một số thay đổi cụ thể

Danh sách đầy đủ các thay đổi về hành vi trong khung tương thích được đưa vào tài liệu cho từng phiên bản Android. Hãy xem các đường liên kết sau để biết thêm thông tin, tuỳ thuộc vào phiên bản Android mà bạn đang kiểm thử ứng dụng:

Thời điểm bật/tắt các thay đổi

Mục đích chính của khung tương thích là giúp bạn có quyền kiểm soát và khả năng linh hoạt khi kiểm thử ứng dụng cho các phiên bản Android mới. Phần này mô tả một số chiến lược mà bạn có thể sử dụng để xác định thời điểm bật hoặc tắt các thay đổi khi kiểm thử và gỡ lỗi ứng dụng.

Thời điểm tắt các thay đổi

Việc quyết định thời điểm tắt thay đổi thường phụ thuộc vào việc thay đổi có được targetSDKVersion kiểm soát hay không.

Bật thay đổi cho tất cả ứng dụng

Theo mặc định, các thay đổi ảnh hưởng đến tất cả ứng dụng sẽ được bật cho một phiên bản nền tảng cụ thể, bất kể targetSDKVersion của ứng dụng là gì. Nhờ đó, bạn có thể biết liệu ứng dụng của mình có bị ảnh hưởng hay không bằng cách chạy ứng dụng trên phiên bản nền tảng đó.

Ví dụ: nếu đang chuẩn bị nhắm đến Android 14 (API cấp 34), thì bạn có thể bắt đầu bằng cách cài đặt ứng dụng trên một thiết bị chạy Android 14 và kiểm thử ứng dụng bằng quy trình kiểm thử thông thường. Nếu ứng dụng gặp vấn đề, thì bạn có thể tắt sự thay đổi đang gây ra vấn đề để có thể tiếp tục kiểm thử các vấn đề khác.

Vì các thay đổi này có thể ảnh hưởng đến tất cả ứng dụng bất kể targetSDKVersion là gì, bạn nên thường xuyên kiểm thử và cập nhật ứng dụng theo các thay đổi này trước các thay đổi do targetSDKVersion kiểm soát. Điều này giúp đảm bảo rằng người dùng của bạn sẽ không có trải nghiệm không tốt trong ứng dụng khi cập nhật thiết bị lên một phiên bản nền tảng mới.

Bạn cũng nên ưu tiên kiểm thử các thay đổi này vì bạn không thể tắt các thay đổi này khi sử dụng bản phát hành Android công khai. Tốt nhất là bạn nên kiểm thử các thay đổi này cho từng phiên bản Android trong khi phiên bản đang ở chế độ dùng thử.

Các thay đổi do targetSDKVersion kiểm soát

Nếu ứng dụng của bạn đang nhắm đến một targetSDKVersion cụ thể, thì mọi thay đổi do phiên bản đó kiểm soát sẽ được bật theo mặc định. Vì vậy, khi bạn chuyển targetSDKVersion của ứng dụng sang một phiên bản mới, ứng dụng đó sẽ bắt đầu chịu ảnh hưởng của nhiều thay đổi mới cùng một lúc.

Do ứng dụng của bạn có thể bị ảnh hưởng vì nhiều thay đổi trong số này, nên có thể bạn phải tắt từng thay đổi một khi kiểm thử và gỡ lỗi ứng dụng.

Thời điểm bật các thay đổi

Các thay đổi do một targetSDKVersion cụ thể kiểm soát sẽ được tắt theo mặc định bất cứ khi nào ứng dụng nhắm đến phiên bản SDK thấp hơn phiên bản được kiểm soát. Thường thì khi chuẩn bị nhắm đến một targetSdkVersion mới, bạn sẽ có danh sách thay đổi về hành vi mà bạn cần kiểm thử và gỡ lỗi cho ứng dụng.

Ví dụ: có thể bạn đang kiểm thử ứng dụng trên một loạt thay đổi về nền tảng trong targetSdkVersion tiếp theo. Bằng cách sử dụng tuỳ chọn cho nhà phát triển hoặc lệnh ADB, bạn có thể bật và kiểm thử từng thay đổi bị kiểm soát, thay vì thay đổi tệp kê khai ứng dụng và chọn sử dụng mọi thay đổi cùng lúc. Tuỳ chọn kiểm soát bổ sung này có thể giúp bạn kiểm thử các thay đổi riêng biệt và tránh phải gỡ lỗi cũng như cập nhật nhiều phần của ứng dụng cùng lúc.

Sau khi bật thay đổi, bạn có thể kiểm thử và gỡ lỗi ứng dụng bằng quy trình kiểm thử thông thường. Nếu bạn gặp sự cố, hãy kiểm tra nhật ký để giúp xác định nguyên nhân của sự cố. Nếu không rõ liệu vấn đề có phải do một thay đổi đã bật trên nền tảng gây ra hay không, hãy thử tắt thay đổi đó rồi kiểm thử lại khu vực đó của ứng dụng.

Bật hoặc tắt các thay đổi

Khung tương thích cho phép bạn bật hoặc tắt từng thay đổi bằng cách sử dụng tuỳ chọn cho nhà phát triển hoặc lệnh ADB. Do tình trạng bật hoặc tắt các thay đổi có thể khiến ứng dụng của bạn gặp lỗi hoặc tắt các thay đổi quan trọng về bảo mật, có một số quy định hạn chế về thời điểm bạn có thể bật hoặc tắt thay đổi.

Sử dụng tuỳ chọn cho nhà phát triển để bật hoặc tắt các thay đổi

Sử dụng tuỳ chọn cho nhà phát triển để bật hoặc tắt thay đổi. Để tìm tuỳ chọn cho nhà phát triển, hãy làm theo các bước sau:

Nếu tuỳ chọn cho nhà phát triển chưa được bật, hãy bật các tuỳ chọn đó.
Mở ứng dụng Settings (Cài đặt) trên thiết bị rồi chuyển đến System (Hệ thống) > Advanced (Nâng cao) > Developer options (Tuỳ chọn cho nhà phát triển) > App Compatibility Changes (Thay đổi về khả năng tương thích của ứng dụng).
Chọn ứng dụng của bạn trong danh sách.
Trong danh sách thay đổi, hãy tìm thay đổi mà bạn muốn bật hoặc tắt rồi nhấn nút chuyển.

Sử dụng ADB để bật hoặc tắt các thay đổi

Để bật hoặc tắt thay đổi bằng cách sử dụng ADB, hãy chạy một trong các lệnh sau:

adb shell am compat enable (CHANGE_ID|CHANGE_NAME) PACKAGE_NAME
adb shell am compat disable (CHANGE_ID|CHANGE_NAME) PACKAGE_NAME

Truyền CHANGE_ID (ví dụ: 194833441) hoặc CHANGE_NAME (ví dụ: NOTIFICATION_PERM_CHANGE_ID) và PACKAGE_NAME của ứng dụng.

Bạn cũng có thể sử dụng lệnh sau đây để đặt lại thay đổi về trạng thái mặc định, xoá mọi nội dung ghi đè bạn đã đặt bằng ADB hoặc tuỳ chọn cho nhà phát triển:

adb shell am compat reset (CHANGE_ID|CHANGE_NAME) PACKAGE_NAME

Quy định hạn chế trong việc bật/tắt các thay đổi

Theo mặc định, mỗi thay đổi về hành vi sẽ được bật hoặc tắt. Các thay đổi ảnh hưởng đến tất cả ứng dụng sẽ được bật theo mặc định. Các thay đổi khác sẽ do targetSdkVersion kiểm soát. Các thay đổi này được bật theo mặc định khi một ứng dụng nhắm đến phiên bản SDK tương ứng trở lên và được tắt theo mặc định khi một ứng dụng nhắm đến phiên bản SDK thấp hơn phiên bản được kiểm soát. Khi bật hoặc tắt một thay đổi, bạn sẽ ghi đè trạng thái mặc định của thay đổi đó.

Để khung tương thích không bị sử dụng sai cách, có một số quy định hạn chế về thời điểm bạn có thể bật hoặc tắt các thay đổi. Việc bạn có thể bật/tắt một thay đổi hay không tuỳ thuộc vào loại thay đổi, liệu ứng dụng của bạn có có thể gỡ lỗi hay không và loại bản dựng đang chạy trên thiết bị. Bảng sau đây mô tả các trường hợp bạn được phép bật hoặc tắt nhiều loại thay đổi:

Loại phiên bản	Ứng dụng không thể gỡ lỗi	Ứng dụng có thể gỡ lỗi
Loại phiên bản	Tất cả thay đổi	Thay đổi do targetSDKVersion kiểm soát	Mọi thay đổi khác
Bản dùng thử cho nhà phát triển hoặc bản dựng beta	Không thể bật/tắt	Có thể bật/tắt	Có thể bật/tắt
Bản dựng công khai cho người dùng	Không thể bật/tắt	Có thể bật/tắt	Không thể bật/tắt