Narzędzia platformy zgodności

W Androidzie 11 wprowadzono 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ę interfejsu API, oraz podczas testowania aplikacji z wersją podglądową następnej wersji Androida.

Gdy używasz narzędzi ramowych zgodności, platforma Android automatycznie dostosowuje swoją logikę wewnętrzną, 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 naprawić pojedynczą zmianę zachowania lub wyłączyć pojedynczą zmianę, która powoduje problemy, jeśli najpierw musisz 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, zrób to.
  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 ma tytuł „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 włączeniem 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 wiadomość logcat, np. taką:

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ę, na którą ma wpływ dana zmiana.
Region

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

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

Region Znaczenie
ENABLED Zmiana zostanie włączona i będzie miała wpływ na działanie aplikacji, jeśli aplikacja korzysta z zmienionego interfejsu 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, zmiana zostanie 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 wpływać na działanie aplikacji. Więcej informacji znajdziesz w opisie zmiany na liście ram 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ędniona 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 Twojej aplikacji będzie widoczna, jeśli wyłączysz ją 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, zapoznaj się z linkami poniżej (w zależności od wersji Androida, dla której testujesz aplikację):

Kiedy włączać i wyłączać zmiany

Głównym celem platformy zgodnoś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 wartości 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 aplikację na Androida 15 (poziom API 35), możesz zacząć od zainstalowania jej na urządzeniu z Androidem 15 i przetestować ją za pomocą 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 publicznych Androida nie można ich wyłączyć. Najlepiej przetestować te zmiany w przypadku każdej wersji Androida w trakcie jej wersji beta.

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 przez wiele nowych zmian naraz.

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 następnym targetSdkVersion. Korzystając z opcji dla deweloperów lub poleceń ADB, możesz włączyć i przetestować każdą zmianę pojedynczo zamiast zmieniać manifest 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, zrób to.
  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.

    Lista zmian, które można włączać i wyłączać

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.

Aby przywrócić zmianę do stanu domyślnego, możesz też użyć tego polecenia, które usunie wszystkie 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 wpływają 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:

Typ kompilacji Aplikacja, której nie można debugować Aplikacja do debugowania
Wszystkie zmiany Zmiany ograniczone przez wartość targetSDKVersion Pozostałe zmiany
Wersja dla programistów lub wersja 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ć