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 có thể gây lỗi một cách riêng lẻ qua tuỳ 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 và khi bạn kiểm thử ứng dụng bằng bản thử nghiệm phiên bản Android tiếp theo.

Khi bạn sử dụng 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ộ để bạn không cần thay đổi targetSDKVersion hoặc biên dịch lại ứng dụng nhằm triển khai kiểm thử cơ bản. Vì các thay đổi có thể bật/tắt riêng, nên bạn có thể phân tách, kiểm thử và gỡ lỗi từng thay đổi về hành vi hoặc tắt một thay đổi gây ra sự cố 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 bạ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ể dùng tuỳ chọn cho nhà phát triển, logcat hoặc lệnh ADB để kiểm tra xem thay đổi về hành vi nào được bật.

Sử dụng tuỳ 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 của ứng dụng trong tuỳ chọn cho nhà phát triển.

Bạn có thể xem thay đổi nào đang 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 các tuỳ chọn này, hãy làm theo các bước sau:

1. Nếu tuỳ chọn cho nhà phát triển chưa được bật, hãy bật các tuỳ chọn đó.
2. 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 (Tuỳ 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).

3. Chọn ứng dụng của bạn trong danh sách.

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 cụ thể, bất kể targetSdkVersion của ứng dụng là gì.

  Những thay đổi nà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 cụ thể. Do cá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, cá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ụ: một thay đổi về hành vi do targetSDKVersion kiểm soát trong Android 13 (API cấp 33) sẽ được liệt kê trên giao diện người dùng trong phần có tiêu đề Được bật từ phiên bản targetSdkVersion >=33. Trên một số phiên bản Android thấp hơn, phần này có tiêu đề là "Được bật từ sau phiên bản SDK API_LEVEL".

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 của phiên bản Android đó.

Sử dụ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 củ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 cả những thông tin sau:

Mã 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 đó sử dụng các API đã thay đổi.
DISABLED	Thay đổi này đã bị tắt và sẽ 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 củ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ử dụ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:

Mã thay đổi

Giá trị nhận dạng riêng biệt cho thay đổi về hành vi này. Ví dụ: 194833441.

Tên

Tên của thay đổi về hành vi này. Ví dụ: NOTIFICATION_PERM_CHANGE_ID.

Tiêu chí targetSDKVersion

Loại targetSDKVersion kiểm soá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 đã ghi đè trạng thái mặc định của thay đổi (dù bật hay 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 tuỳ 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 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 như một phần của tài liệu cho từng phiên bản Android. Hãy xem các đường liên kết sau đây để biết thêm thông tin, tuỳ thuộc vào phiên bản Android của ứng dụng bạn đang kiểm thử:

• Android 15 (API cấp 35)
• Android 14 (API cấp 34)
• Android 13 (API cấp 33)
• Android 12 (API cấp 31 và 32)
• Android 11 (API cấp 30)

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ể nắm được liệu ứng dụng của bạn 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 15 (API cấp 35), thì 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 15 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 đề, 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.

Vì cá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 các thay đổi này trước các thay đổi do targetSDKVersion kiểm soát. Việc này giúp đảm bảo rằng người dùng không có trải nghiệm ứng dụng bị giảm chất lượng khi họ 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ử các thay đổi này vì bạn không thể tắt cá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ử cá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 soá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 phiên bản mới, ứng dụng đó sẽ bắt đầu chịu tác độ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 vì 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

Cá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 tuỳ 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. Tuỳ 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õ vấn đề có phải do một thay đổi được bật về 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 đó trong ứ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 tuỳ chọn cho nhà phát triển hoặc lệnh ADB. Do tình trạ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, có một số quy đị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 tuỳ chọn cho nhà phát triển để bật hoặc tắt thay đổi. Để tìm tuỳ chọn cho nhà phát triển, hãy làm theo các bước sau:

1. Nếu tuỳ chọn cho nhà phát triển chưa được bật, hãy bật các tuỳ chọn đó.
2. 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 (Tuỳ 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).
3. Chọn ứng dụng của bạn trong danh sách.

4. 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ử dụ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, xoá mọi nội dung ghi đè bạn đã đặt bằng ADB hoặc tuỳ 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 các thay đổi

Theo mặc định, mỗi thay đổi về hành vi sẽ được bật hoặc tắt. Các thay đổi ảnh hưởng đến tất cả ứng dụng sẽ được bật theo mặc định. Các thay đổi khác sẽ 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 bị sử dụng sai cách, có một số quy đị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 hoặc tắt một thay đổi còn tuỳ thuộc vào loại thay đổi, ứng dụng 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: