Narzędzia platformy zgodności

W Androidzie 11 wprowadziliśmy nowe narzędzia dla programistów do testowania i debugowania aplikacji pod kątem zmian w działaniu nowszych wersji 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 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ę 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 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 zachowaniu 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ć te zmiany. 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 zakresie 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 na 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 mają wpływ tylko na aplikacje kierowane na określone wersje Androida. Ponieważ te zmiany dotyczą tylko aplikacji kierowanych na konkretną wersję Androida, są one również określane jako zmiany ograniczone 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 zachowania, która jest ograniczona przez targetSDKVersion w Androidzie 13 (API na poziomie 33), będzie wyświetlana w interfejsie w sekcji zatytułowanej Włączone w przypadku targetSdkVersion >=33. W niektórych starszych wersjach Androida ta sekcja nosi nazwę „Włączone po SDK API_LEVEL”.

Na rysunku 1 zobaczysz też sekcję Default Disabled Changes (Zmiany domyślnie wyłączone). Zmiany w tej sekcji mogą służyć różnym celom. Przed włączeniem tych zmian przeczytaj opis 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:

Identyfikator zmiany

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.

Użytkownik (UID)

Wskazuje, której aplikacji dotyczy zmiana.

Stan

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

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

Stan	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 wpłynie 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ć reklamy na wyższą wersję.
LOGGED	Zmiana jest rejestrowana w ramach systemu sprawdzania 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 wpływać na działanie aplikacji. Więcej informacji znajdziesz w opisie zmiany na liście systemów sprawdzania 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

Wynik zawiera te informacje o każdej zmianie:

Identyfikator zmiany

Unikalny identyfikator tej zmiany zachowania. Na przykład: 194833441.

Nazwa

Nazwa tej zmiany w zachowaniu. 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 pakiet SDK w wersji 33 lub nowszej, 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 true lub 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 systemie sprawdzania zgodności jest dostępna w dokumentacji każdej wersji Androida. Więcej informacji znajdziesz w tych artykułach (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 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ó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 wpływają na wszystkie aplikacje, są domyślnie włączone w przypadku określonej wersji platformy, niezależnie od targetSDKVersion aplikacji. Możesz sprawdzić, czy Twoja aplikacja jest objęta tymi zmianami, uruchamiając ją w tej wersji platformy.

Jeśli na przykład przygotowujesz się do kierowania reklam na Androida 16 (poziom interfejsu API 36), możesz zainstalować aplikację na urządzeniu z Androidem 16 i przetestować ją za pomocą typowych procesów testowania. Jeśli w aplikacji wystąpią problemy, możesz wyłączyć zmianę, która je powoduje, i kontynuować testowanie pod kątem innych problemów.

Te zmiany mogą mieć wpływ na wszystkie aplikacje, niezależnie od targetSDKVersion. Dlatego przed wprowadzeniem zmian ograniczonych przez targetSDKVersion przetestuj i zaktualizuj aplikację pod kątem tych zmian. Dzięki temu użytkownicy nie odczują pogorszenia jakości, gdy zaktualizują platformę do nowej wersji.

Warto też nadać priorytet testowaniu tych zmian, ponieważ w przypadku korzystania z publicznej kompilacji do publikacji Androida nie można ich wyłączyć. Najlepiej byłoby przetestować te zmiany w przypadku każdej wersji Androida w okresie jej podglądu.

Zmiany ograniczone przez 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ę, zacznie ona podlegać wielu nowym zmianom naraz.

Na Twoją 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 wersję pakietu SDK niższą niż wersja ograniczona. Zwykle, gdy przygotowujesz się do kierowania 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 stopniowo, 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 naraz.

Po włączeniu zmiany możesz przetestować i debugować aplikację, korzystając ze zwykłych procesów testowania. 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

System sprawdzania 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) i 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 w zachowaniu 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 systemu sprawdzania zgodności, istnieją pewne ograniczenia dotyczące tego, kiedy można przełączać zmiany. Możliwość włączenia lub wyłączenia zmiany zależy od jej typu, tego, czy aplikacja jest z możliwością debugowania, oraz typu kompilacji uruchomionej na urządzeniu. W tabeli poniżej opisano, kiedy możesz włączać i wyłączać różne typy zmian: