Narzędzia platformy zgodności

W Androidzie 11 wprowadziliśmy nowe narzędzia dla programistów umożliwiające testowanie i debugowanie aplikacji pod kątem zmian w działaniu w nowszych wersjach platformy Androida. Narzędzia te wchodzą w skład platformy zgodności, która umożliwia deweloperom aplikacji włączanie i wyłączanie zmian powodujących niezgodność za pomocą opcji programisty lub ADB. Wykorzystaj tę elastyczność podczas przygotowań do kierowania reklam na najnowszą stabilną wersję interfejsu API oraz podczas testowania aplikacji z wersją testową nowej wersji Androida.

Gdy korzystasz z narzędzi platformy zgodności, platforma Androida automatycznie dostosowuje swoją wewnętrzną logikę, więc nie musisz zmieniać targetSDKVersion ani ponownie skompilować aplikacji, by przeprowadzić podstawowe testy. Zmiany można przełączać pojedynczo, dlatego możesz wyizolować, przetestować i debugować po jednej zmianie w zachowaniu lub wyłączyć pojedynczą zmianę powodującą problemy, jeśli najpierw musisz przetestować coś innego.

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

Włączenie zmiany działania może wpłynąć na dostęp aplikacji do interfejsów API platform, na które wpływa ta zmiana. Aby sprawdzić, które zmiany w działaniu są włączone, użyj opcji programisty, logcat lub poleceń ADB.

Identyfikuj włączone zmiany za pomocą opcji programisty

Rysunek 1. w opcjach programisty w sekcji „Zmiany zgodności aplikacji”.

Możesz sprawdzić, które zmiany są włączone, i 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 wybierz System > Zaawansowane > Opcje programisty > Zmiany zgodności aplikacji.

  3. Wybierz aplikację z listy.

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

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

    Te zmiany są domyślnie włączone w platformie zgodności i wyświetlane w interfejsie w sekcji Domyślne włączone zmiany.

  • Zmiany, które dotyczą tylko aplikacji kierowanych na określone wersje Androida. Te zmiany dotyczą tylko aplikacji kierowanych na określoną wersję Androida, dlatego są również nazywane zmianami ograniczonymi przez targetSDKVersion.

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

Na rys. 1 znajduje się sekcja Domyślnie wyłączone zmiany. Zmiany zawarte w tej sekcji mogą służyć różnym celom. Zanim włączysz te zmiany, przeczytaj ich opis na liście zestawienia zgodności dla danej wersji Androida.

Zidentyfikuj włączone zmiany za pomocą narzędzia logcat

Przy każdej zmianie działania, gdy aplikacja po raz pierwszy wywoła odpowiedni interfejs API, system zwraca komunikat logcat podobny do tego:

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

Każdy komunikat logcat zawiera te informacje:

Zmień identyfikator
Wskazuje, która zmiana dotyczy aplikacji. Ta wartość jest mapowana na jedną ze zmian w działaniu wyświetlanych na ekranie Zmiany zgodności aplikacji (zobacz ilustrację 1). W tym przykładzie 194833441 odpowiada mapie na adres NOTIFICATION_PERM_CHANGE_ID.
Identyfikator UID
Wskazuje aplikację, której dotyczy zmiana.
Region

Wskazuje, czy zmiana dotyczy aplikacji.

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

Region Znaczenie
ENABLED Zmiana zostanie włączona i wpłynie na działanie aplikacji, jeśli korzysta ona ze zmienionych interfejsów API.
DISABLED

Ta zmiana zostanie wyłączona i nie będzie miała wpływu na aplikację.

Uwaga: jeśli ta zmiana zostanie wyłączona, ponieważ targetSDKVersion aplikacji nie osiągnie 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 przez platformę zgodności, ale nie można jej włączyć ani wyłączyć. Choć tej zmiany nie można przełączyć, może ona nadal wpływać na działanie aplikacji. Więcej informacji znajdziesz na liście platform zgodności dla danej wersji Androida. W wielu przypadkach takie zmiany mają charakter eksperymentalny i można je zignorować.

Zidentyfikuj włączone zmiany za pomocą ADB

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

adb shell dumpsys platform_compat

Dane wyjściowe zawierają następujące informacje o każdej zmianie:

Zmień identyfikator
Unikalny identyfikator tej zmiany zachowania. Na przykład: 194833441.
Nazwa
Nazwa tego działania się zmienia. Na przykład: NOTIFICATION_PERM_CHANGE_ID.
Kryteria wersji targetSDKVersion

Który zasób targetSDKVersion jest objęty ograniczeniami (jeżeli takie istnieją).

Jeśli na przykład ta zmiana dotyczy tylko aplikacji kierowanych na pakiet SDK w wersji 33 lub nowszej, dane wyjściowe mają enableAfterTargetSdk=32. Jeśli zmiana nie jest zablokowana przez zasadę targetSDKVersion, zwracany jest parametr enableAfterTargetSdk=0.

Zastąpienia pakietu

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

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

packageOverrides={com.my.package=false}

Zmiany ograniczone przez tag targetSDKVersion mogą być domyślnie włączone lub wyłączone, więc lista pakietów może zawierać wystąpienia obu pakietów true lub false, w zależności od tego, jaki atrybut targetSDKVersion dotyczy 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 działania w ramach platformy zgodności jest częścią dokumentacji poszczególnych wersji Androida. W zależności od wersji Androida, na którą testujesz aplikację, skorzystaj z tych linków:

Kiedy włączać zmiany

Głównym celem platformy zgodności jest zapewnienie Ci kontroli i elastyczności podczas testowania aplikacji z nowszymi wersjami Androida. W tej sekcji opisujemy kilka strategii umożliwiających określenie, kiedy włączać i wyłączać zmiany podczas testowania i debugowania aplikacji.

Kiedy wyłączać zmiany

Decyzja o wyłączeniu zmian zwykle zależy od tego, czy jest ona zablokowana przez zasadę targetSDKVersion.

Zmiany włączone dla wszystkich aplikacji

Zmiany, które wpływają na wszystkie aplikacje, są domyślnie włączone na określonej wersji platformy niezależnie od targetSDKVersion Twojej aplikacji. Możesz więc sprawdzić, czy uruchomienie aplikacji na danej wersji platformy 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 przetestowania jej za pomocą typowych procesów testowania. Jeśli wystąpią problemy z aplikacją, możesz wyłączyć zmianę, która powoduje problem, i kontynuować testowanie pod kątem innych problemów.

Te zmiany mogą mieć wpływ na wszystkie aplikacje niezależnie od ustawienia targetSDKVersion, dlatego zwykle najpierw przetestuj i zaktualizuj aplikację pod kątem tych zmian, zanim zmiany zostaną objęte ograniczeniami targetSDKVersion. Dzięki temu po zaktualizowaniu urządzeń do nowej wersji platformy działanie aplikacji nie będzie gorsze.

Warto też przetestować te zmiany, ponieważ nie można ich wyłączyć w przypadku publicznej wersji Androida. Najlepiej przetestuj te zmiany w każdej wersji Androida, podczas gdy ta wersja jest już w wersji testowej.

Zmiany zablokowane przez: targetSDKVersion

Jeśli Twoja aplikacja jest kierowana na określony typ targetSDKVersion, wszystkie zmiany objęte tą wersją są domyślnie włączone. Dlatego gdy przełączasz się z targetSDKVersion na nową wersję, w aplikacji zacznie wprowadzać wiele nowych zmian jednocześnie.

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

Kiedy włączać zmiany

Zmiany objęte konkretnym targetSDKVersion są domyślnie wyłączone, gdy aplikacja jest kierowana na wersję pakietu SDK niższą niż wersja dla zabezpieczeń. Zwykle, przygotowując się do kierowania reklam na nowy kraj targetSdkVersion, będziesz mieć listę zmian w działaniu, które musisz przetestować i debugować pod kątem nowej wersji aplikacji.

Możesz na przykład testować aplikację pod kątem szeregu zmian na platformie, które nastąpi w najbliższym targetSdkVersion. Korzystając z opcji programisty lub poleceń ADB, możesz włączać i testować każdą zmianę oddzielnie, zamiast zmieniać plik manifestu aplikacji i wprowadzać wszystkie zmiany naraz. Ta dodatkowa opcja pozwala przetestować zmiany osobno oraz uniknąć debugowania i aktualizowania wielu części aplikacji jednocześnie.

Po włączeniu zmiany możesz przetestować i debugować aplikację za pomocą typowych przepływów pracy testowych. Jeśli napotkasz problem, sprawdź dzienniki, aby ustalić jego przyczynę. Jeśli nie masz pewności, czy przyczyną problemu jest wprowadzona zmiana na platformie, spróbuj ją wyłączyć i ponownie sprawdzić w tym obszarze aplikacji.

Włącz lub wyłącz zmiany

Platforma 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 w zabezpieczeniach, obowiązują pewne ograniczenia umożliwiające włączanie zmian.

Przełączanie zmian za pomocą opcji programisty

Zmiany możesz włączać i wyłączać, korzystając z opcji 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 wybierz 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.

    Lista zmian, które można włączyć lub wyłączyć

Przełącz zmiany za pomocą ADB

Aby włączyć lub wyłączyć zmianę przy użyciu 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

Prześlij CHANGE_ID (np. 194833441) lub CHANGE_NAME (np. NOTIFICATION_PERM_CHANGE_ID) i PACKAGE_NAME swojej aplikacji.

Możesz też użyć tego polecenia, aby zresetować 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 przełączania zmian

Domyślnie każda zmiana w działaniu 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 kierowana na odpowiednią wersję pakietu SDK lub nowszą, i domyślnie wyłączone, gdy aplikacja jest kierowana na wersję pakietu SDK starszą niż wersja zablokowana. Włączając lub wyłączając zmianę, zastępujesz jej stan domyślny.

Aby zapobiec złośliwemu wykorzystaniu platformy zgodności, wprowadziliśmy pewne ograniczenia dotyczące możliwości przełączania zmian. Możliwość włączenia zmiany zależy od jej typu, od tego, czy aplikacja umożliwia debugowanie, oraz od typu kompilacji uruchomionej na urządzeniu. W tabeli poniżej opisujemy, kiedy możesz przełączać różne typy zmian:

Typ kompilacji Aplikacja niemożliwa do debugowania Aplikacja z możliwością debugowania
Wszystkie zmiany Zmiany nadzorowane przez targetSDKVersion Wszystkie inne zmiany
Wersja przedpremierowa dla programistów lub kompilacja beta Nie można przełączyć Możliwość przełączania Możliwość przełączania
Publiczna kompilacja użytkownika Nie można przełączyć Możliwość przełączania Nie można przełączyć