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 działaniu nowszych wersji platformy Androida. Narzędzia te wchodzą w skład platformy zgodności, która umożliwia programistom włączanie i wyłączanie zmian powodujących niezgodność za pomocą opcji programisty lub ADB. Wykorzystaj tę elastyczność, gdy przygotowujesz się do kierowania na najnowszą stabilną wersję interfejsu API oraz testujesz aplikację w wersji testowej kolejnej wersji Androida.

Gdy korzystasz z narzędzi platformy zgodności, platforma Androida automatycznie dostosowuje swoją wewnętrzną logikę, dzięki czemu nie musisz modyfikować targetSDKVersion ani ponownie kompilować aplikacji, aby przeprowadzić podstawowe testy. Zmiany można przełączać pojedynczo, możesz więc wyodrębniać, testować i debugować tylko jedną zmianę działania naraz lub wyłączyć jedną zmianę, która powoduje problemy, jeśli chcesz najpierw przetestować coś innego.

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

Włączenie zmiany w działaniu może wpłynąć na sposób, w jaki aplikacja uzyskuje dostęp do interfejsów API platformy, na które ta zmiana ma wpływ. Aby sprawdzić, które zmiany działania są włączone, użyj opcji programisty, poleceń logcat lub ADB.

Identyfikowanie włączonych zmian za pomocą opcji dla programistów

Możesz sprawdzić, które zmiany są włączone, oraz włączyć lub wyłączyć je w opcjach programisty na urządzeniu. 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 kliknij System > Zaawansowane > Opcje programisty > Zmiany zgodności aplikacji.

3. Wybierz aplikację z listy.

Każda zmiana działania należy zwykle do jednej z tych 2 kategorii:

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

  Te zmiany są domyślnie włączone w ramach platformy zgodności i są widoczne w interfejsie w sekcji Zmiany włączone domyślnie.

• Zmiany, które mają wpływ tylko na aplikacje kierowane na określone wersje Androida. Te zmiany dotyczą tylko aplikacji kierowanych na konkretną wersję Androida, więc są one również określane jako zmiany objęte ograniczeniami przez targetSDKVersion.

  Jeśli Twoja aplikacja jest kierowana na wersję wyższą niż wymieniona wersja interfejsu API, te zmiany są domyślnie włączone w ramach platformy zgodności. Na przykład zmiana działania objęta zasadą targetSDKVersion w Androidzie 13 (poziom interfejsu API 33) będzie widoczna w interfejsie w sekcji zatytułowanej Włączone dla wersji targetSdkVersion >=33. Na niektórych starszych wersjach Androida ta sekcja ma nazwę „Włączono po SDK API_LEVEL”.

Na grafice 1 znajdziesz też sekcję Domyślnie wyłączone zmiany. Zmiany zawarte w tej sekcji mogą służyć różnym celom. Zanim włączysz te zmiany, przeczytaj opis zmiany na liście platform zgodności w danej wersji Androida.

Identyfikowanie włączonych zmian za pomocą narzędzia Logcat

Przy każdej zmianie działania, gdy pierwszy raz w procesie aplikacji wywoła ona odpowiedni interfejs API, system wyśle komunikat logcat podobny do tego:

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

Każda wiadomość logcat zawiera te informacje:

Zmień identyfikator

Wskazuje zmianę, która ma wpływ na aplikację. Ta wartość odpowiada jednej ze zmian w działaniu wymienionych na ekranie Zmiany zgodności aplikacji (patrz: rys. 1). W tym przykładzie 194833441 mapuje się na NOTIFICATION_PERM_CHANGE_ID.

Identyfikator UID

Wskazuje aplikację, której dotyczy zmiana.

Region

Wskazuje, czy zmiana dotyczy aplikacji.

Może on mieć jedną z tych wartości:

Region	Znaczenie
ENABLED	Zmiana jest włączona i będzie miała wpływ na zachowanie aplikacji, jeśli będzie ona korzystać ze zmienionych interfejsów API.
DISABLED	Ta zmiana jest wyłączona i nie ma wpływu na aplikację. Uwaga: jeśli ta zmiana zostanie wyłączona, ponieważ wartość targetSDKVersion aplikacji nie przekracza wymaganego progu, zmiana zostanie domyślnie włączona, gdy aplikacja zwiększy wartość targetSDKVersion, aby kierować ją na wyższą wersję.
LOGGED	Zmiana jest logowana za pomocą platformy zgodności, ale nie można jej włączyć ani wyłączyć. Chociaż nie można tego zrobić, może ona nadal wpływać na działanie aplikacji. Więcej informacji znajdziesz w opisie zmiany na liście platform zgodności w danej wersji Androida. W wielu przypadkach tego typu zmiany mają charakter eksperymentalny i można je zignorować.

Zidentyfikuj włączone zmiany za pomocą ADB

Uruchom to polecenie ADB, aby wyświetlić pełny zestaw zmian (włączonych i wyłączonych) na całym urządzeniu:

adb shell dumpsys platform_compat

W przypadku każdej zmiany wyniki będą zawierać te informacje:

Zmień identyfikator

Unikalny identyfikator tej zmiany zachowania. Przykład: 194833441.

Nazwa

Nazwa tego zachowania się zmienia. Przykład: NOTIFICATION_PERM_CHANGE_ID.

Kryteria wersji targetSDKVersion

targetSDKVersion, przez które zmiana jest ograniczana (jeśli występuje).

Jeśli na przykład ta zmiana jest włączona tylko w przypadku aplikacji kierowanych na pakiet SDK w wersji 33 lub nowszej, w danych wyjściowych występuje enableAfterTargetSdk=32. Jeśli zmiana nie jest ograniczona przez zasadę targetSDKVersion, parametr enableAfterTargetSdk=0 zawiera dane wyjściowe.

Zastąpienia pakietów

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

Jeśli na przykład ta zmiana jest domyślnie włączona, nazwa pakietu aplikacji będzie widoczna po wyłączeniu tej zmiany za pomocą opcji programisty lub ADB. W takim przypadku dane wyjściowe będą wyglądały tak:

packageOverrides={com.my.package=false}

Zmiany blokowane przez zasadę 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 właściwości targetSDKVersion każdej z nich. Przykład:

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

Więcej informacji o konkretnych zmianach

Pełną listę zmian w działaniu platformy zgodności znajdziesz w dokumentacji poszczególnych wersji Androida. W zależności od wersji Androida, na którą testujesz aplikację, kliknij te linki:

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

Kiedy włączać zmiany

Głównym celem platformy zgodności jest zapewnienie Ci kontroli i elastyczności podczas testowania aplikacji na nowszych wersjach Androida. W tej sekcji opisujemy niektóre strategie, za pomocą których możesz określić, kiedy włączać i wyłączać zmiany podczas testowania i debugowania aplikacji.

Kiedy wyłączyć zmiany

Decyzja o tym, kiedy włączyć zmiany, zwykle zależy od tego, czy zmiana jest objęta zasadą targetSDKVersion.

Zmiany zostały włączone we wszystkich aplikacjach

Zmiany, które mają wpływ na wszystkie aplikacje, są domyślnie włączone dla konkretnej wersji platformy, niezależnie od wersji targetSDKVersion Twojej aplikacji. Dzięki temu możesz sprawdzić, czy uruchomienie aplikacji na danej wersji wpływa na Twoją aplikację.

Jeśli na przykład przygotowujesz się do kierowania aplikacji na Androida 14 (poziom interfejsu API 34), możesz zacząć od zainstalowania aplikacji na urządzeniu z Androidem 14 i przetestować ją przy użyciu typowych procesów testowych. Jeśli występują problemy, możesz wyłączyć zmianę, która powoduje problem, aby kontynuować testowanie pod kątem innych problemów.

Te zmiany mogą mieć wpływ na wszystkie aplikacje niezależnie od targetSDKVersion, dlatego zwykle należy przetestować i zaktualizować aplikację pod kątem tych zmian przed zmianami, które są objęte ograniczeniami przez targetSDKVersion. Dzięki temu użytkownicy, którzy zaktualizują urządzenie do nowej wersji platformy, nie będą korzystać z aplikacji gorszej.

Warto też przetestować te zmiany w pierwszej kolejności, ponieważ nie można ich wyłączyć jeśli używasz publicznej kompilacji Androida. Najlepiej przetestuj te zmiany w przypadku każdej wersji Androida, gdy dana wersja jest w wersji testowej.

Zmiany objęte zasadą targetSDKVersion

Jeśli kierujesz aplikację na określony typ targetSDKVersion, wszystkie zmiany objęte tą wersją są domyślnie włączone. Gdy zmieniasz targetSDKVersion aplikacji na nową wersję, na Twoją aplikację zacznie wpływać wiele zmian naraz.

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

Kiedy włączyć zmiany

Zmiany zablokowane przez konkretny typ targetSDKVersion są domyślnie wyłączone, gdy aplikacja jest kierowana na wersję pakietu SDK starszą niż wersja ograniczona. Zwykle przygotowując się do kierowania na nowy obiekt targetSdkVersion, przygotujesz listę zmian w działaniu, które musisz przetestować i debugować.

Może to być na przykład testowana aplikacja pod kątem serii zmian platformy w ciągu najbliższych targetSdkVersion. Za pomocą opcji programisty lub poleceń ADB możesz pojedynczo włączać i testować każdą zmianę ograniczaną. Nie musisz już zmieniać pliku manifestu aplikacji i akceptować każdej zmiany jednocześnie. Ta dodatkowa opcja kontroli pomoże Ci testować zmiany niezależnie od siebie oraz uniknąć debugowania i aktualizowania wielu części aplikacji jednocześnie.

Po włączeniu zmiany możesz testować i debugować aplikację za pomocą typowych przepływów pracy podczas testowania. Jeśli napotkasz problemy, sprawdź logi, aby określić ich przyczynę. Jeśli nie masz pewności, czy problem jest spowodowany zmianą platformy, która jest włączona, wyłącz tę zmianę, a następnie ponownie przetestuj dany obszar aplikacji.

Włącz lub wyłącz zmiany

Platforma zgodności umożliwia włączanie i wyłączanie każdej zmiany za pomocą opcji programisty lub poleceń ADB. Włączanie i wyłączanie zmian może spowodować awarię aplikacji lub wyłączenie ważnych zmian w zabezpieczeniach, dlatego obowiązują pewne ograniczenia dotyczące przełączania zmian.

Przełączaj zmiany za pomocą opcji programisty

Zmiany możesz włączać i wyłączać w opcjach programisty. 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 kliknij System > Zaawansowane > Opcje programisty > Zmiany zgodności aplikacji.
3. Wybierz aplikację z listy.

4. Na liście zmian znajdź zmianę, którą chcesz włączyć lub wyłączyć, i kliknij przełącznik.

   

Przełącz zmiany za pomocą narzędzia ADB

Aby włączyć lub wyłączyć zmianę za pomocą narzędzia 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) i PACKAGE_NAME.

Możesz też użyć poniższego polecenia, aby przywrócić zmianę do stanu domyślnego, usuwając 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 działania jest włączona lub wyłączona. Zmiany, które mają wpływ na wszystkie aplikacje, są domyślnie włączone. Inne zmiany są regulowane przez zasadę targetSdkVersion. Te zmiany są domyślnie włączone, gdy aplikacja jest kierowana na odpowiednią wersję pakietu SDK lub nowszą, oraz domyślnie wyłączone, gdy aplikacja jest kierowana na wersję objętą ograniczeniami. Włączając lub wyłączając zmianę, zastąpisz jej stan domyślny.

Aby zapobiec złośliwemu użyciu platformy zgodności, obowiązują pewne ograniczenia dotyczące przełączania zmian. To, czy możesz przełączyć zmianę, zależy od typu zmiany, tego, czy aplikację można debugować, i od typu kompilacji uruchomionej na urządzeniu. W tabeli poniżej opisujemy, kiedy można przełączać różne typy zmian:

Typ kompilacji	Aplikacja bez możliwości debugowania	Aplikacja do debugowania
	Wszystkie zmiany	Zmiany objęte przez targetSDKVersion	Wszystkie inne zmiany
Przedpremierowa wersja przedpremierowa lub kompilacja beta	Nie można przełączyć	Może przełączać	Może przełączać
Kompilacja publiczna	Nie można przełączyć	Może przełączać	Nie można przełączyć