Narzędzia platformy zgodności

W Androidzie 11 wprowadziliśmy nowe narzędzia dla programistów, które umożliwiają testowanie i debugowanie aplikacji pod kątem zmian w działaniu w nowszych wersjach platformy Android. Te narzędzia są częścią systemu sprawdzania zgodności, który pozwala programistom aplikacji włączać i wyłączać poszczególne zmiany powodujące niezgodność za pomocą Opcji programisty lub ADB. Skorzystaj z tej elastyczności, przygotowując się do kierowania na najnowszą stabilną wersję interfejsu API i testując aplikację w wersji przedpremierowej następnej wersji Androida.

Gdy używasz narzędzi systemu sprawdzania zgodności, platforma Android automatycznie dostosowuje swoją logikę wewnętrzną, więc nie musisz zmieniać targetSDKVersion ani ponownie kompilować aplikacji, aby przeprowadzić podstawowe testy. Ponieważ zmiany można włączać i wyłączać pojedynczo, możesz izolować, testować i debugować jedną zmianę w działaniu naraz lub wyłączyć pojedynczą zmianę, która powoduje problemy, jeśli musisz najpierw przetestować coś innego.

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

Gdy zmiana w działaniu jest włączona, może 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 w działaniu są włączone, za pomocą opcji programisty, logcat lub poleceń ADB.

Sprawdzanie włączonych zmian za pomocą opcji programisty

Rysunek 1. Ekran Zmiany zgodności aplikacji w opcjach programisty.

W opcjach programisty na urządzeniu możesz sprawdzić, które zmiany są włączone, i włączać lub wyłączać te zmiany w tym 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 w działaniu zwykle należy do jednej z tych 2 kategorii:

• Zmiany, które wpływają na wszystkie aplikacje działające w danej 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 wpływają tylko na aplikacje kierowane na określone wersje Androida. Ponieważ te zmiany wpływają tylko na aplikacje kierowane na określoną wersję Androida, są one też nazywane zmianami ograniczonymi przez targetSDKVersion.

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

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

Sprawdzanie włączonych zmian za pomocą logcat

Przy każdej zmianie w działaniu, gdy aplikacja po raz pierwszy w swoim procesie wywoła interfejs API, którego dotyczy ta zmiana, 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 w działaniu wymienionych na ekranie Zmiany zgodności aplikacji (patrz rysunek 1). W tym przykładzie 194833441 odpowiada NOTIFICATION_PERM_CHANGE_ID.

Użytkownik (UID)

Wskazuje, która aplikacja jest objęta zmianą.

Stan

Wskazuje, czy zmiana wpływa na aplikację.

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

Stan	Znaczenie
ENABLED	Zmiana jest włączona i będzie wpływać na działanie aplikacji, jeśli aplikacja używa zmienionych interfejsów API.
DISABLED	Zmiana jest wyłączona i nie będzie wpływać na aplikację. Uwaga: jeśli ta zmiana jest wyłączona, ponieważ targetSDKVersion aplikacji jest poniżej wymaganego progu, zmiana zostanie domyślnie włączona, gdy aplikacja zwiększy targetSDKVersion, aby kierować na wyższą wersję.
LOGGED	Zmiana jest rejestrowana przez system sprawdzania zgodności, ale nie można jej włączyć ani wyłączyć. Chociaż tej zmiany nie można włączyć ani wyłą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 te typy zmian są eksperymentalne i można je zignorować.

Sprawdzanie włączonych zmian za pomocą ADB

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

adb shell dumpsys platform_compat

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

Identyfikator zmiany

Unikalny identyfikator tej zmiany w działaniu. Na przykład 194833441.

Nazwa

Nazwa tej zmiany w działaniu. Na przykład NOTIFICATION_PERM_CHANGE_ID.

Kryteria targetSDKVersion

Który targetSDKVersion 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świetli się enableAfterTargetSdk=32. Jeśli zmiana nie jest ograniczona przez targetSDKVersion, wyświetli się enableAfterTargetSdk=0.

Zastąpienia na poziomie pakietu

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

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

packageOverrides={com.my.package=false}

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

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

Więcej informacji o konkretnych zmianach

Pełna lista zmian w działaniu w systemie sprawdzania zgodności jest częścią dokumentacji każdej wersji Androida. Więcej informacji znajdziesz w tych linkach w zależności od wersji Androida, w której testujesz aplikację:

• Android 16 (poziom API 36)
• Android 15 (poziom API 35)
• Android 14 (poziom API 34)
• 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 Ci kontroli i elastyczności podczas testowania aplikacji w nowszych wersjach Androida. W tej sekcji opisujemy kilka strategii, których możesz użyć, aby określić, kiedy włączać lub wyłączać zmiany podczas testowania i debugowania aplikacji.

Kiedy wyłączać zmiany

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

Zmiany włączone dla wszystkich aplikacji

Zmiany, które wpływają na wszystkie aplikacje, są domyślnie włączone w przypadku określonej wersji platformy, niezależnie od targetSDKVersion aplikacji. Dzięki temu możesz sprawdzić, czy aplikacja jest objęta zmianą, uruchamiając ją w tej wersji platformy.

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

Ponieważ te zmiany mogą wpływać na wszystkie aplikacje niezależnie od targetSDKVersion, zwykle należy przetestować i zaktualizować aplikację pod kątem tych zmian przed zmianami ograniczonymi przez targetSDKVersion. Pomaga to zapewnić, że użytkownicy nie będą mieli gorszych wrażeń z korzystania z aplikacji, gdy zaktualizują urządzenie do nowej wersji platformy.

Powinieneś też priorytetowo przetestować te zmiany, ponieważ nie możesz wyłączyć tych zmian gdy używasz publicznej kompilacji do publikacji Androida. Najlepiej jest testować te zmiany w każdej wersji Androida podczas jej wersji przedpremierowej.

Zmiany ograniczone przez targetSDKVersion

Jeśli aplikacja jest kierowana na określony targetSDKVersion, wszystkie zmiany ograniczone przez tę wersję są domyślnie włączone. Gdy zmienisz targetSDKVersion aplikacji na nową wersję, aplikacja zacznie być objęta wieloma nowymi zmianami naraz.

Ponieważ aplikacja może być objęta więcej niż jedną z tych zmian, podczas testowania i debugowania aplikacji może być konieczne wyłączenie niektórych z tych zmian.

Kiedy włączać zmiany

Zmiany ograniczone przez określony targetSDKVersion są domyślnie wyłączone, gdy aplikacja jest kierowana na wersję pakietu SDK niższą niż wersja ograniczona. Zwykle, gdy przygotowujesz się do kierowania na nowy targetSdkVersion, masz listę zmian w działaniu, które musisz przetestować i debugować w aplikacji.

Możesz na przykład testować aplikację pod kątem serii zmian platformy w następnym targetSdkVersion. Za pomocą opcji programisty lub poleceń ADB możesz włączać i testować każdą ograniczoną zmianę pojedynczo, zamiast zmieniać plik manifestu aplikacji i włączać wszystkie zmiany naraz. Ta dodatkowa kontrola może pomóc w testowaniu zmian w izolacji oraz uniknięciu debugowania i aktualizowania wielu części aplikacji naraz.

Po włączeniu zmiany możesz testować i debugować aplikację za pomocą typowych procesów testowania. Jeśli napotkasz problemy, sprawdź logi, aby ustalić przyczynę problemu. Jeśli nie jest jasne, czy problem jest spowodowany włączoną zmianą platformy, spróbuj wyłączyć tę zmianę, a następnie ponownie przetestować ten obszar aplikacji.

Włączanie i wyłączanie zmian

System sprawdzania zgodności umożliwia włączanie i wyłączanie każdej zmiany 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łączać i wyłączać 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 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łą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

Podaj 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ć 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 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ą, a domyślnie wyłączone, gdy aplikacja jest kierowana na wersję pakietu SDK niższą niż wersja ograniczona. Gdy włączasz lub wyłączasz zmianę, zastępujesz jej stan domyślny.

Aby zapobiec złośliwemu wykorzystaniu systemu sprawdzania zgodności, obowiązują pewne ograniczenia dotyczące tego, kiedy można przełączać zmiany. To, czy możesz przełączyć zmianę, zależy od jej typu, tego, czy aplikację można debugować, oraz typu kompilacji działającej na urządzeniu. W tej tabeli opisujemy, kiedy można przełączać różne typy zmian: