Narzędzia platformy zgodności

W Androidzie 11 wprowadziliśmy nowe narzędzia dla programistów do testowania i debugowania aplikacji pod kątem zmian w zachowaniu w nowszych wersjach platformy Android. Te narzędzia są częścią systemu sprawdzania zgodności, który umożliwia deweloperom aplikacji włączanie i wyłączanie poszczególnych zmian powodujących niezgodność za pomocą opcji programisty lub ADB. Wykorzystaj tę elastyczność, przygotowując się do kierowania na najnowszą stabilną wersję interfejsu API i testując aplikację w wersji testowej kolejnej wersji Androida.

Gdy używasz narzędzi systemu sprawdzania zgodności, platforma Androida automatycznie dostosowuje swoją wewnętrzną logikę, więc nie musisz zmieniać targetSDKVersion ani rekompilować aplikacji, aby przeprowadzić podstawowe testy. Zmiany można przełączać pojedynczo, więc możesz wyizolować, przetestować i debugować jedną zmianę zachowania naraz lub wyłączyć pojedynczą zmianę, która powoduje problemy, jeśli najpierw musisz przetestować coś innego.

Jak sprawdzić, które zmiany są włączone

Gdy zmiana zachowania jest włączona, może ona wpływać na sposób, w jaki aplikacja uzyskuje dostęp do interfejsów API platformy, których dotyczy ta zmiana. Możesz sprawdzić, które zmiany zachowania są włączone, korzystając z opcji programisty, logcat lub poleceń ADB.

Identyfikowanie włączonych zmian za pomocą opcji programisty

Rysunek 1. Zmiany dotyczące zgodności aplikacji na ekranie opcji programisty.

W opcjach programisty na urządzeniu możesz sprawdzić, które zmiany są włączone, oraz włączać i wyłączać te zmiany. Aby uzyskać dostęp do tych opcji, wykonaj te czynności:

1. Jeśli opcje programisty nie są jeszcze włączone, włącz je.
2. Otwórz na urządzeniu aplikację Ustawienia i wybierz System > Zaawansowane > Opcje programisty > Zmiany zgodności aplikacji.

3. Wybierz aplikację z listy.

Każda zmiana zachowania zwykle należy do jednej z tych 2 kategorii:

• Zmiany, które wpływają na wszystkie aplikacje działające na tej wersji Androida, niezależnie od targetSdkVersion aplikacji.

  Te zmiany są domyślnie włączone w systemie sprawdzania zgodności i są wymienione w interfejsie w sekcji Domyślnie włączone zmiany.

• Zmiany, które mają wpływ tylko na aplikacje kierowane na określone wersje Androida. Te zmiany mają wpływ tylko na aplikacje kierowane na konkretną wersję Androida, dlatego są też nazywane zmianami ograniczonymi przez targetSDKVersion.

  Te zmiany są domyślnie włączone w systemie sprawdzania zgodności, jeśli aplikacja jest kierowana na wyższą wersję niż podana wersja interfejsu API. Na przykład zmiana zachowania, która jest ograniczona przez targetSDKVersion w Androidzie 13 (poziom API 33), będzie widoczna w interfejsie w sekcji Włączone dla targetSdkVersion >=33. W niektórych starszych wersjach Androida ta sekcja nosi nazwę „Włączone po pakiecie SDK API_LEVEL”.

Na rysunku 1 widoczna jest też sekcja Default Disabled Changes (Domyślnie wyłączone zmiany). Zmiany, które należą do tej sekcji, mogą służyć różnym celom. Zanim włączysz te zmiany, przeczytaj ich opis na liście systemu sprawdzania zgodności dla danej wersji Androida.

Identyfikowanie włączonych zmian za pomocą logcat

W przypadku każdej zmiany zachowania, gdy aplikacja po raz pierwszy wywoła dany interfejs API, system wyświetli komunikat logcat podobny do tego:

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

Każdy komunikat logcat zawiera te informacje:

Identyfikator zmiany

Wskazuje, która zmiana wpływa na aplikację. Ta wartość odpowiada jednej ze zmian zachowania wymienionych na ekranie Zmiany dotyczące zgodności aplikacji (patrz rysunek 1). W tym przykładzie 194833441 jest mapowany na NOTIFICATION_PERM_CHANGE_ID.

Użytkownik (UID)

Wskazuje, której aplikacji dotyczy zmiana.

Stan

Wskazuje, czy zmiana ma wpływ na aplikację.

Stan może mieć jedną z tych wartości:

Stan	Znaczenie
ENABLED	Zmiana jest włączona i będzie miała wpływ na działanie aplikacji, jeśli aplikacja korzysta z interfejsów API, które zostały zmienione.
DISABLED	Zmiana jest wyłączona i nie wpłynie na aplikację. Uwaga: jeśli ta zmiana jest wyłączona, ponieważ wartość targetSDKVersion aplikacji jest poniżej wymaganego progu, zostanie ona domyślnie włączona, gdy wartość targetSDKVersion aplikacji wzrośnie, aby aplikacja była kierowana na wyższą wersję.
LOGGED	Zmiana jest rejestrowana przez system sprawdzania zgodności, ale nie można jej włączyć ani wyłączyć. Chociaż nie można jej przełączyć, może ona nadal wpływać na działanie aplikacji. Więcej informacji znajdziesz w opisie zmiany na liście systemu sprawdzania zgodności dla danej wersji Androida. W wielu przypadkach tego typu zmiany są eksperymentalne i można je zignorować.

Identyfikowanie włączonych zmian za pomocą ADB

Aby zobaczyć pełny zestaw zmian (zarówno włączonych, jak i wyłączonych) na całym urządzeniu, uruchom to polecenie ADB:

adb shell dumpsys platform_compat

Wynik zawiera te informacje o każdej zmianie:

Identyfikator zmiany

Unikalny identyfikator tej zmiany zachowania. Na przykład: 194833441.

Nazwa

Nazwa tej zmiany zachowania. Na przykład: NOTIFICATION_PERM_CHANGE_ID.

Kryteria targetSDKVersion

targetSDKVersion, który ogranicza zmianę (jeśli dotyczy).

Jeśli na przykład ta zmiana jest włączona tylko w przypadku aplikacji kierowanych na pakiet SDK w wersji 33 lub nowszej, wyświetlane są dane enableAfterTargetSdk=32. Jeśli zmiana nie jest ograniczona przez targetSDKVersion, wyświetlane jest enableAfterTargetSdk=0.

Zastąpienia na poziomie pakietu

Nazwa każdego pakietu, w którym stan domyślny zmiany (włączona lub wyłączona) został zastąpiony.

Jeśli na przykład zmiana jest domyślnie włączona, nazwa pakietu aplikacji będzie widoczna, jeśli wyłączysz zmianę za pomocą opcji programisty lub ADB. W tym przypadku dane wyjściowe będą wyglądać tak:

packageOverrides={com.my.package=false}

Zmiany, które są kontrolowane przez targetSDKVersion, mogą być domyślnie włączone lub wyłączone, więc lista pakietów może zawierać wystąpienia zarówno true, jak i false, w zależności od targetSDKVersion każdej z tych aplikacji. Przykład:

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

Więcej informacji o konkretnych zmianach

Pełna lista zmian zachowania w systemie sprawdzania zgodności jest zawarta w dokumentacji każdej wersji Androida. Więcej informacji znajdziesz w linkach poniżej, w zależności od wersji Androida, na której testujesz aplikację:

• Android 16 (poziom API 36)
• Android 15 (poziom interfejsu API 35)
• Android 14 (poziom 34 interfejsu API)
• Android 13 (poziom API 33)
• Android 12 (poziomy API 31 i 32)
• Android 11 (poziom API 30)

Kiedy przełączać zmiany

Głównym celem systemu sprawdzania zgodności jest zapewnienie kontroli i elastyczności podczas testowania aplikacji na nowszych wersjach Androida. W tej sekcji opisujemy kilka strategii, których możesz użyć, aby określić, kiedy włączać i wyłączać zmiany podczas testowania i debugowania aplikacji.

Kiedy wyłączyć przełącznik

Decyzja o tym, kiedy wyłączyć zmiany, zwykle zależy od tego, czy zmiana jest ograniczona przez targetSDKVersion.

Zmiany włączone we wszystkich aplikacjach

Zmiany, które wpływają na wszystkie aplikacje, są domyślnie włączone w przypadku określonej wersji platformy, niezależnie od targetSDKVersion aplikacji. Możesz więc sprawdzić, czy zmiany mają wpływ na Twoją aplikację, uruchamiając ją na tej wersji platformy.

Jeśli na przykład przygotowujesz się do kierowania na Androida 16 (poziom interfejsu API 36), możesz zainstalować aplikację na urządzeniu z Androidem 16 i przetestować ją, korzystając z typowych procesów testowania. Jeśli w aplikacji wystąpią problemy, możesz wyłączyć zmianę, która je powoduje, i kontynuować testowanie pod kątem innych problemów.

Te zmiany mogą mieć wpływ na wszystkie aplikacje, niezależnie od targetSDKVersion, więc przetestuj i zaktualizuj aplikację pod kątem tych zmian, zanim wprowadzisz zmiany, które są ograniczone przez targetSDKVersion. Dzięki temu użytkownicy nie będą mieli problemów po aktualizacji do nowej wersji platformy.

Warto też priorytetowo przetestować te zmiany, ponieważ nie można ich wyłączyć w kompilacji do publikacji Androida. Najlepiej przetestować te zmiany w każdej wersji Androida, gdy jest ona w wersji testowej.

Zmiany ograniczone przez: targetSDKVersion

Jeśli aplikacja jest kierowana na konkretną wersję targetSDKVersion, wszystkie zmiany, które są ograniczone przez tę wersję, są domyślnie włączone. Dlatego gdy zmienisz targetSDKVersion aplikacji na nową wersję, od razu zacznie na nią wpływać wiele nowych zmian.

Ponieważ na aplikację może mieć wpływ więcej niż jedna z tych zmian, podczas testowania i debugowania aplikacji może być konieczne wyłączenie niektórych z nich.

Kiedy włączyć zmiany

Zmiany, które są ograniczone przez określony targetSDKVersion, są domyślnie wyłączone, gdy aplikacja jest kierowana na niższą wersję pakietu SDK niż wersja ograniczona. Zazwyczaj podczas przygotowywania się do kierowania na nową wersję targetSdkVersion masz listę zmian w zachowaniu, które musisz przetestować i pod kątem których musisz debugować aplikację.

Możesz na przykład testować aplikację pod kątem serii zmian na platformie w ciągu najbliższych targetSdkVersion. Za pomocą opcji programisty lub poleceń ADB możesz włączyć i przetestować każdą zmianę po kolei, zamiast zmieniać manifest aplikacji i akceptować wszystkie zmiany naraz.

Ta dodatkowa kontrola może pomóc Ci przetestować zmiany w izolacji i uniknąć debugowania oraz aktualizowania wielu części aplikacji naraz.

Po włączeniu zmiany możesz przetestować i zdebugować aplikację, korzystając z typowych procesów testowania. Jeśli napotkasz problemy, sprawdź dzienniki, aby ustalić ich przyczynę. Jeśli nie masz pewności, czy problem jest spowodowany przez włączoną zmianę platformy, spróbuj ją wyłączyć, a następnie ponownie przetestuj ten obszar aplikacji.

Włączanie i wyłączanie zmian

System sprawdzania zgodności umożliwia włączanie i wyłączanie poszczególnych zmian za pomocą opcji programisty lub poleceń ADB. Ponieważ włączanie i wyłączanie zmian może spowodować awarię aplikacji lub wyłączenie ważnych zmian zabezpieczeń, obowiązują pewne ograniczenia dotyczące tego, kiedy można przełączać zmiany.

Przełączanie zmian za pomocą opcji programisty

Użyj opcji programisty, aby włączyć lub wyłączyć zmiany. Aby znaleźć opcje programisty, wykonaj te czynności:

1. Jeśli opcje programisty nie są jeszcze włączone, włącz je.
2. Otwórz na urządzeniu aplikację Ustawienia i wybierz System > Zaawansowane > Opcje programisty > Zmiany zgodności aplikacji.
3. Wybierz aplikację z listy.
4. Na liście zmian znajdź tę, którą chcesz włączyć lub wyłączyć, i kliknij przełącznik.

Przełączanie zmian za pomocą ADB

Aby włączyć lub wyłączyć zmianę za pomocą ADB, uruchom jedno z tych poleceń:

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

Przekaż CHANGE_ID (np. 194833441) lub CHANGE_NAME (np. NOTIFICATION_PERM_CHANGE_ID) oraz PACKAGE_NAME aplikacji.

Możesz też użyć tego polecenia, aby przywrócić domyślny stan zmiany i usunąć wszelkie zastąpienia ustawione za pomocą ADB lub opcji programisty:

adb shell am compat reset (CHANGE_ID|CHANGE_NAME) PACKAGE_NAME

Ograniczenia dotyczące przełączania zmian

Domyślnie każda zmiana zachowania jest włączona lub wyłączona. Zmiany, które mają wpływ na wszystkie aplikacje, są domyślnie włączone. Inne zmiany są ograniczone przez targetSdkVersion. Te zmiany są domyślnie włączone, gdy aplikacja jest kierowana na odpowiednią wersję pakietu SDK lub nowszą, i domyślnie wyłączone, gdy aplikacja jest kierowana na wersję pakietu SDK niższą niż wersja z ograniczeniami. Gdy włączysz lub wyłączysz zmianę, zastąpisz jej stan domyślny.

Aby zapobiec wykorzystywaniu systemu sprawdzania zgodności do szkodliwych działań, wprowadziliśmy pewne ograniczenia dotyczące możliwości przełączania zmian. To, czy możesz przełączyć zmianę, zależy od jej typu, tego, czy aplikacja jest możliwa do debugowania, oraz od typu kompilacji uruchomionej na urządzeniu. W tabeli poniżej opisano, kiedy można przełączać różne typy zmian: