Narzędzia platformy zgodności

Android 11 wprowadził nowe narzędzia dla programistów do testowania i debugowania aplikacji pod kątem zmian zachowania w nowszych wersjach platformy Android. Narzędzia te są częścią ramowego rozwiązania dotyczącego zgodności, które pozwala deweloperom włączać i wyłączać zmiany powodujące przerwanie działania aplikacji za pomocą opcji dla deweloperów lub ADB. Korzystaj z tej elastyczności, gdy przygotowujesz się do kierowania aplikacji na najnowszą stabilną wersję API i gdy testujesz aplikację z wersją podglądową następnej wersji Androida.

Gdy używasz narzędzi z ramy kompatybilności, platforma Androida automatycznie dostosowuje swoją wewnętrzną logikę, więc nie musisz zmieniać targetSDKVersion ani ponownie kompilować aplikacji, aby przeprowadzić podstawowe testy. Zmiany można włączać i wyłączać pojedynczo, dzięki czemu możesz wyodrębnić, przetestować i rozwiązać problemy związane z jedną zmianą zachowania naraz lub wyłączyć pojedynczą zmianę, która powoduje problemy, jeśli chcesz najpierw przetestować coś innego.

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

Włączenie zmiany zachowania może wpływać na sposób uzyskiwania przez aplikację dostępu do interfejsów API platformy, których dotyczy ta zmiana. Aby sprawdzić, które zmiany zachowania są włączone, użyj opcji dla deweloperów, narzędzia logcat lub poleceń ADB.

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

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

W opcjach programisty 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 dla programistów nie są jeszcze włączone, włącz je.
2. Otwórz aplikację Ustawienia na urządzeniu i kliknij System > Zaawansowane > Opcje programisty > Zmiany dotyczące 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 w tej wersji Androida, niezależnie od ich targetSdkVersion;

  Te zmiany są domyślnie włączone w ramach platformy zgodności i 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; Ponieważ te zmiany dotyczą tylko aplikacji kierowanych na określoną wersję Androida, nazywamy je też zmianami ograniczonymi przez targetSDKVersion.

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

Na rysunku 1 zobaczysz też sekcję Domyślnie wyłączone zmiany. Zmiany, które mieszczą się w tej sekcji, mogą służyć różnym celom. Przed wdrożeniem tych zmian przeczytaj opis zmian na liście zgodności na platformie dla danej wersji Androida.

Wykrywanie włączonych zmian za pomocą logcat

W przypadku każdej zmiany zachowania, gdy aplikacja po raz pierwszy wywoła interfejs API, którego dotyczy zmiana, system wyświetli 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, która zmiana dotyczy aplikacji. Ta wartość odpowiada jednej ze zmian zachowania wymienionych na ekranie Zmiany zgodności aplikacji (patrz rys. 1). W tym przykładzie 194833441 jest mapowane na NOTIFICATION_PERM_CHANGE_ID.

UID

Wskazuje aplikację, której dotyczy zmiana.

Województwo

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

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

Województwo	Znaczenie
ENABLED	Zmiana zostanie włączona i będzie miała wpływ na działanie aplikacji, jeśli aplikacja korzysta z zmienionych interfejsów API.
DISABLED	Zmiana jest wyłączona i nie będzie miała wpływu 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 aplikacja zwiększy wartość targetSDKVersion, aby kierować na wyższą wersję.
LOGGED	Zmiana jest rejestrowana w ramach platformy zgodności, ale nie można jej włączyć ani wyłączyć. Mimo to może ona mieć wpływ na działanie aplikacji. Aby dowiedzieć się więcej, zapoznaj się z opisem zmiany na liście ramek zgodności dla tej wersji Androida. W wielu przypadkach te typy zmian są eksperymentalne i można je zignorować.

Wykrywanie włączonych zmian za pomocą ADB

Aby wyświetlić 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

Dane wyjściowe zawierają te informacje o każdej zmianie:

Zmień identyfikator

Unikalny identyfikator tego zachowania. Na przykład: 194833441.

Nazwa

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

kryteria targetSDKVersion,

Który targetSDKVersion jest związany ze zmianą (jeśli dotyczy).

Jeśli na przykład ta zmiana jest włączona tylko w przypadku aplikacji kierowanych na wersję pakietu SDK 33 lub nowszą, zostanie zwrócona wartość enableAfterTargetSdk=32. Jeśli zmiana nie jest uwzględniana przez targetSDKVersion, dane wyjściowe to enableAfterTargetSdk=0.

Zastąpienia pakietów

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

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

packageOverrides={com.my.package=false}

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

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

Więcej informacji o konkretnych zmianach

Pełna lista zmian zachowania w ramach kompatybilności jest zawarta w dokumentacji dotyczącej każdej wersji Androida. Aby uzyskać więcej informacji, kliknij linki poniżej (w zależności od wersji Androida, dla której testujesz aplikację):

• Android 16 (poziom API 36)
• Android 15 (poziom 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 włączać i wyłączać zmiany

Głównym celem ram kompatybilności jest zapewnienie Ci kontroli i elastyczności podczas testowania aplikacji w nowszych wersjach Androida. W tej sekcji opisujemy kilka strategii, które możesz stosować podczas testowania i debugowania aplikacji, aby włączać lub wyłączać zmiany.

Kiedy wyłączyć zmiany

Decyzja o wyłączeniu zmian zwykle zależy od tego, czy zmiana jest uwzględniana przez targetSDKVersion.

Zmiany włączone dla wszystkich aplikacji

Zmiany, które wpływają na wszystkie aplikacje, są domyślnie włączone w przypadku konkretnej wersji platformy niezależnie od targetSDKVersion Twojej aplikacji, dzięki czemu możesz sprawdzić, czy uruchomienie aplikacji na tej wersji platformy ma na nią wpływ.

Jeśli na przykład przygotowujesz się do ukierunkowania na Androida 16 (poziom interfejsu API 36), możesz zacząć od zainstalowania aplikacji na urządzeniu z Androidem 16 i przetestowania jej w ramach typowych procesów testowania. Jeśli aplikacja napotka problemy, możesz wyłączyć zmianę, która je powoduje, aby kontynuować testowanie pod kątem innych problemów.

Zmiany te mogą mieć wpływ na wszystkie aplikacje niezależnie od targetSDKVersion, dlatego przed wprowadzeniem zmian ograniczonych przez targetSDKVersion należy przetestować i zaktualizować aplikację. Dzięki temu użytkownicy nie będą mieć problemów z aplikacją po zaktualizowaniu urządzenia do nowej wersji platformy.

Należy też priorytetowo traktować testowanie tych zmian, ponieważ w przypadku wersji publicznej Androida nie można ich wyłączyć. Najlepiej przetestować te zmiany w przypadku każdej wersji Androida w trakcie jej wersji w podglądzie.

Zmiany ograniczone przez targetSDKVersion

Jeśli Twoja aplikacja jest kierowana na konkretną wersję targetSDKVersion, wszystkie zmiany, które są ograniczone do tej wersji, są domyślnie włączone. Gdy przełączysz targetSDKVersion aplikacji na nową wersję, zacznie ona być modyfikowana naraz pod wieloma względami.

Ponieważ na aplikację może mieć wpływ więcej niż 1 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. Gdy przygotowujesz się do kierowania na nowy targetSdkVersion, zwykle masz listę zmian zachowania, które musisz przetestować i załatwiać w aplikacji.

Możesz na przykład przetestować aplikację pod kątem serii zmian platformy w ciągu najbliższych targetSdkVersion. Korzystając z opcji dla deweloperów lub poleceń ADB, możesz włączyć i przetestować każdą zmianę pojedynczo, zamiast zmieniać plik manifestu aplikacji i włączać wszystkie zmiany naraz. Dzięki temu dodatkowemu ustawieniu możesz testować zmiany oddzielnie i unikać debugowania oraz aktualizowania wielu części aplikacji naraz.

Po włączeniu zmiany możesz przetestować i debugować aplikację, korzystając z typowych procesów testowania. Jeśli napotkasz problemy, sprawdź dzienniki, aby określić ich przyczynę. Jeśli nie masz pewności, czy problem jest spowodowany włączoną zmianą na platformie, spróbuj ją wyłączyć, a potem ponownie przetestuj tę część aplikacji.

Włączanie i wyłączanie zmian

Platforma zgodności umożliwia włączanie i wyłączanie poszczególnych zmian za pomocą opcji dla deweloperów lub poleceń ADB. Włączanie i wyłączanie zmian może spowodować awarię aplikacji lub wyłączenie ważnych zmian dotyczących zabezpieczeń, dlatego obowiązują pewne ograniczenia dotyczące tego, kiedy możesz włączać i wyłączać zmiany.

Przełączanie zmian za pomocą opcji dla programistów

Aby włączyć lub wyłączyć zmiany, użyj opcji dla programistów. Aby je znaleźć:

1. Jeśli opcje dla programistów nie są jeszcze włączone, włącz je.
2. Otwórz aplikację Ustawienia na urządzeniu i kliknij kolejno System > Zaawansowane > Opcje programisty > Zmiany dotyczące 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 (na przykład 194833441) lub CHANGE_NAME (na przykład NOTIFICATION_PERM_CHANGE_ID) oraz PACKAGE_NAME aplikacji.

Możesz też użyć tego polecenia, aby przywrócić zmianę do stanu domyślnego, usuwając wszelkie zastąpienia ustawione za pomocą ADB lub opcji dla deweloperów:

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 zgodna z odpowiednią wersją pakietu SDK lub nowszą, oraz domyślnie wyłączone, gdy aplikacja jest zgodna z wersją pakietu SDK niższą niż wersja ograniczona. Gdy włączysz lub wyłączysz zmianę, zastąpisz jej stan domyślny.

Aby zapobiec złośliwemu wykorzystaniu platformy zgodności, obowiązują pewne ograniczenia dotyczące tego, kiedy można przełączać zmiany. To, czy możesz włączyć lub wyłączyć zmianę, zależy od jej typu, możliwości debugowania aplikacji i typu wersji uruchomionej na urządzeniu. W tabeli poniżej wyjaśniono, kiedy możesz włączać różne typy zmian: