Narzędzia platformy zgodności

Android 11 wprowadził nowe narzędzia dla programistów do testowania i debugowania aplikacji pod kątem zmian w działaniu w nowszych wersjach platformy Android. Te narzędzia są częścią platformy zgodności, która umożliwia programistom aplikacji włączanie i wyłączanie poszczególnych zmian powodujących niezgodność za pomocą opcji programisty lub ADB. Skorzystaj z tej elastyczności, przygotowując się do kierowania aplikacji na najnowszą stabilną wersję interfejsu API i testowania jej z wersją zapoznawczą kolejnej wersji Androida.

Gdy używasz narzędzi platformy 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ć po jednej zmianie zachowania naraz lub wyłączyć jedną zmianę, która powoduje problemy, jeśli musisz najpierw przetestować coś innego.

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

Gdy zmiana w zachowaniu jest włączona, może to wpłynąć 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, korzystając z opcji programisty, logcat lub poleceń ADB.

Sprawdzanie włączonych zmian za pomocą opcji programisty

Rysunek 1. 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ć je. 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 przejdź do sekcji System > Zaawansowane > Opcje programisty > Zmiany w kompatybilności aplikacji.

3. Wybierz aplikację z listy.

Każda zmiana zachowania zwykle należy do jednej z tych 2 kategorii:

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

  Te zmiany są domyślnie włączone w strukturze zgodności i są 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. Te zmiany dotyczą tylko aplikacji kierowanych na konkretną wersję Androida, dlatego określa się je też jako zmiany ograniczone przez targetSDKVersion.

  Te zmiany są domyślnie włączone w ramach zgodności, jeśli aplikacja jest kierowana na wersję wyższą niż wymieniona wersja interfejsu API. Na przykład zmiana zachowania, 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”.

Na rysunku 1 zobaczysz też sekcję Zmiany domyślnie wyłączone. Zmiany w tej sekcji mogą służyć różnym celom. Przed włączeniem tych zmian zapoznaj się z opisem zmian na liście platformy zgodności dla danej wersji Androida.

Określanie włączonych zmian za pomocą logcat

Przy każdej zmianie zachowania, gdy aplikacja po raz pierwszy w swoim procesie wywoła dany interfejs API, 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 wpływa na aplikację. Ta wartość jest powiązana z jedną ze zmian w zachowaniu wymienionych na ekranie Zmiany dotyczące zgodności aplikacji (patrz rysunek 1). W tym przykładzie 194833441 jest mapowany na NOTIFICATION_PERM_CHANGE_ID.

UID

Wskazuje, której aplikacji 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 jest włączona i wpłynie na działanie aplikacji, jeśli korzysta ona ze 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ż targetSDKVersion aplikacji jest poniżej wymaganego progu, zostanie ona domyślnie włączona, gdy aplikacja zwiększy targetSDKVersion, aby kierować reklamy na wyższą wersję.
LOGGED	Zmiana jest rejestrowana w ramach platformy zgodności, ale nie można jej włączyć ani wyłączyć. Mimo że nie można jej włączyć ani wyłączyć, może ona mieć wpływ na działanie aplikacji. Więcej informacji znajdziesz w opisie zmiany na liście platform zgodności dla danej wersji Androida. W wielu przypadkach te rodzaje zmian mają charakter eksperymentalny i można je zignorować.

Określanie włączonych zmian za pomocą ADB

Aby zobaczyć pełny zestaw zmian (włączonych 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 tej zmiany zachowania. Na przykład: 194833441.

Nazwa

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

Kryteria targetSDKVersion

targetSDKVersion, od którego zależy zmiana (jeśli dotyczy).

Jeśli na przykład ta zmiana jest włączona tylko w przypadku aplikacji kierowanych na wersję SDK 33 lub nowszą, zwracana jest wartość enableAfterTargetSdk=32. Jeśli zmiana nie jest ograniczona przez targetSDKVersion, zwracana jest wartość enableAfterTargetSdk=0.

Zastąpienia 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 zmiana jest domyślnie włączona, nazwa pakietu aplikacji będzie widoczna, gdy wyłączysz zmianę za pomocą opcji programisty 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 tych aplikacji. Przykład:

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

Więcej informacji o konkretnych zmianach

Pełna lista zmian w zachowaniu w ramach zgodności jest dostępna w dokumentacji każdej wersji Androida. Więcej informacji znajdziesz w linkach poniżej (w zależności od wersji Androida, na której testujesz aplikację):

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

Kiedy przełą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 zastosować, aby określić, kiedy włączać lub wyłączać zmiany podczas testowania i debugowania aplikacji.

Kiedy wyłączyć zmiany

Decyzja o wyłączeniu zmian zależy zwykle od tego, czy są one ograniczone przez targetSDKVersion.

Zmiany włączone dla wszystkich aplikacji

Zmiany, które mają wpływ na wszystkie aplikacje, są domyślnie włączone w przypadku określonej wersji platformy, niezależnie od targetSDKVersionaplikacji, więc możesz sprawdzić, czy zmiana ma wpływ na Twoją aplikację, uruchamiając ją w tej wersji platformy.

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

Ponieważ te zmiany mogą mieć wpływ na wszystkie aplikacje niezależnie od targetSDKVersion, zwykle należy przetestować i zaktualizować aplikację pod kątem tych zmian przed wprowadzeniem zmian, które są ograniczone przez targetSDKVersion. Dzięki temu użytkownicy nie będą mieli gorszych wrażeń z korzystania z aplikacji po zaktualizowaniu urządzenia do nowej wersji platformy.

Warto też przetestować te zmiany, ponieważ nie można ich wyłączyć w publicznej wersji Androida. Najlepiej byłoby przetestować te zmiany w przypadku każdej wersji Androida w okresie jej podglądu.

Zmiany zależne od targetSDKVersion

Jeśli Twoja aplikacja jest kierowana na konkretną wersję targetSDKVersion, wszelkie zmiany, które są ograniczone przez tę wersję, są domyślnie włączone. Gdy zmienisz targetSDKVersion aplikacji na nową wersję, na Twoją aplikację zacznie wpływać wiele nowych zmian jednocześnie.

Na 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.

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. Zwykle podczas przygotowywania się do kierowania reklam na nowy targetSdkVersion masz listę zmian w zachowaniu, które musisz przetestować i w których musisz usunąć błędy w aplikacji.

Możesz na przykład testować aplikację pod kątem serii zmian na platformie, które zostaną wprowadzone w ciągu najbliższych targetSdkVersion. Korzystając z opcji programisty lub poleceń ADB, możesz włączać i testować poszczególne zmiany po kolei, zamiast zmieniać plik manifestu aplikacji i włączać wszystkie zmiany naraz. Ta dodatkowa kontrola może pomóc Ci testować zmiany w izolacji i uniknąć debugowania oraz aktualizowania wielu części aplikacji jednocześnie.

Po włączeniu zmiany możesz przetestować i debugować aplikację, korzystając ze zwykłych przepływów pracy związanych z testowaniem. Jeśli napotkasz problemy, sprawdź dzienniki, aby określić przyczynę problemu. Jeśli nie masz pewności, czy problem jest spowodowany włączoną zmianą na platformie, spróbuj ją wyłączyć, a następnie ponownie przetestować ten obszar aplikacji.

Włączanie i wyłączanie zmian

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

Przełączanie zmian za pomocą opcji programisty

Użyj opcji programisty, aby włączyć lub wyłączyć 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 przejdź do sekcji System > Zaawansowane > Opcje programisty > Zmiany w zakresie 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

Przekaż 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 i usunąć 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 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ą, a domyślnie wyłączone, gdy aplikacja jest zgodna z wersją pakietu SDK starszą niż wersja objęta ograniczeniami. Gdy włączysz lub wyłączysz zmianę, zastąpisz jej stan domyślny.

Aby zapobiec złośliwemu wykorzystaniu platformy zgodności, istnieją pewne ograniczenia dotyczące tego, kiedy można przełączać zmiany. Możliwość przełączania zmian zależy od typu zmiany, tego, czy aplikacja jest możliwa do debugowania, oraz typu kompilacji uruchomionej na urządzeniu. W tabeli poniżej opisano, kiedy można włączać i wyłączać różne typy zmian: