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 sự linh hoạt này khi bạn chuẩn bị nhắm đến những sản phẩm mới nhất phiên bản API ổn định 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ác công cụ trong khung tương thích, nền tảng Android tự động điều chỉnh logic nội bộ, do đó bạn không cần phải thay đổi targetSDKVersion hoặc biên dịch lại ứng dụng của bạn để thực hiện kiểm thử cơ bản. Bởi vì các thay đổi có thể bật/tắt từng thay đổi, bạn có thể tách riêng, kiểm tra và gỡ lỗi thay đổi hành vi cùng một lúc hoặc tắt một thay đổi gây ra sự cố nếu trước tiên, bạn cần thử nghiệm một nội dung 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ể kiểm tra xem hành vi nào các thay đổi được bật bằng tuỳ chọn cho nhà phát triển, logcat hoặc lệnh ADB.

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 những thay đổi nào được bật và bật hoặc tắt những thay đổi đó trong tuỳ chọn cho nhà phát triển của thiết bị. Để truy cập vào 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ụ: 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 đề Đã 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 đề là "Bật sau SDK API_LEVEL" thay thế.

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 bật các thay đổi này, hãy đọc mô tả thay đổi trong mục khả năng tương thích danh sách khung cho 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 được bật và sẽ ảnh hưởng đến hành vi của ứng dụng nếu ứng dụng dùng những API đã thay đổi.
DISABLED

Thay đổi này bị vô hiệu hoá 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 phiên bản SDK 33 trở lên, giá trị đầu ra là enableAfterTargetSdk=32. Nếu thay đổi không do targetSDKVersion kiểm soát, thì đầu ra là enableAfterTargetSdk=0.

Ghi đè gói

Tên của mỗi gói có trạng thái mặc định của thay đổi (được bật hoặc vô hiệu) đã bị ghi đè.

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 các gói có thể bao gồm các phiên bản của cả hai true hoặc false, tuỳ thuộc vào targetSDKVersion của từng ứ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 dưới dạng của tài liệu hướng dẫn cho từng phiên bản Android. Xem các đường liên kết sau đây cho thêm thông tin, tùy thuộc vào phiên bản Android mà bạn đang thử nghiệm ứng dụng của mình cho:

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

Các thay đổi ảnh hưởng đến tất cả ứng dụng được bật bởi mặc định cho một phiên bản nền tảng cụ thể, bất kể phiên bản targetSDKVersion, vì vậy, 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 bạn đang chuẩn bị nhắm đến Android 15 (API cấp 35), bạn có thể bắt đầu bằng cách cài đặt ứng dụng trên một thiết bị đang chạy Android 15 và kiểm thử ứng dụng bằng quy trình kiểm thử thông thường quy trình công việc. Nếu ứng dụng gặp vấn đề, bạn có thể tắt thay đổi đó đang gây ra sự cố, nhờ đó bạn có thể tiếp tục kiểm tra các sự cố 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. Điều này giúp đảm bảo rằng người dùng sẽ không có trải nghiệm ứng dụng kém chất lượng khi cập nhật thiết bị lên một phiên bản mới phiên bản nền tảng.

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 đối tượng cụ thể targetSDKVersion, 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 , ứng dụng của bạn 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 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õ liệu sự cố có phải do đã bật thay đổi nền tảng, hãy thử tắt thay đổi đó rồi kiểm tra lại 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 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.

    Danh sách thay đổi có thể bật hoặc tắt

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. Bạn có thể bật/tắt hay không thay đổi phụ thuộc vào loại thay đổi, ứ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ị của bạn. 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
Tất cả thay đổi Thay đổi do targetSDKVersion kiểm soát Mọ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