<uses-sdk>

Google Play używa atrybutów <uses-sdk> zadeklarowanych w pliku manifestu aplikacji, aby odfiltrować aplikację z urządzeń, które nie spełniają wymagań dotyczących wersji platformy. Zanim ustawisz te atrybuty, zapoznaj się z filtrami w Google Play.

składnia:

<uses-sdk android:minSdkVersion="integer"
          android:targetSdkVersion="integer"
          android:maxSdkVersion="integer" />

zawiera się w:

<manifest>

description:

Umożliwia określenie zgodności aplikacji z co najmniej jedną wersją platformy Android za pomocą liczby całkowitej reprezentującej poziom interfejsu API. Poziom interfejsu API określony przez aplikację jest porównywany z poziomem interfejsu API danego systemu Android, który może się różnić na różnych urządzeniach z Androidem.

Wbrew nazwie ten element służy do określania poziomu interfejsu API, a nie numeru wersji pakietu SDK ani platformy Android. Poziom API jest zawsze pojedynczą liczbą całkowitą. Poziomu API nie można wywnioskować z powiązanego z nim numeru wersji Androida. Nie jest to na przykład to samo co wersja główna ani suma wersji głównej i podrzędnej.

Nie można określić, czy aplikacja jest kierowana na wersję podrzędną pakietu SDK, czy jej wymaga.

Przeczytaj też dokument o zarządzaniu wersjami aplikacji.

atrybuty:

android:minSdkVersion

Liczba całkowita określająca minimalny poziom API wymagany do uruchomienia aplikacji. System Android uniemożliwia użytkownikowi zainstalowanie aplikacji, jeśli poziom interfejsu API systemu jest niższy niż wartość określona w tym atrybucie. Zawsze deklaruj ten atrybut.

Ostrzeżenie: jeśli nie zadeklarujesz tego atrybutu, system przyjmie domyślną wartość „1”, co oznacza, że aplikacja jest zgodna ze wszystkimi wersjami Androida. Jeśli nie, a nie zadeklarujesz odpowiedniego minSdkVersion, aplikacja po zainstalowaniu w systemie z niezgodnym poziomem interfejsu API ulegnie awarii w czasie działania podczas próby uzyskania dostępu do niedostępnych interfejsów API. Z tego powodu pamiętaj, aby zadeklarować odpowiedni poziom interfejsu API w atrybucie minSdkVersion.

android:targetSdkVersion

Liczba całkowita określająca poziom interfejsu API, na który jest kierowana aplikacja. Jeśli nie zostanie ustawiona, wartością domyślną jest wartość podana w przypadku parametru minSdkVersion.

Ten atrybut informuje system, że testy zostały przeprowadzone na docelowej wersji, a system nie włącza żadnych zachowań związanych ze zgodnością, aby zachować zgodność aplikacji z docelową wersją. Aplikacja nadal może działać w starszych wersjach (aż do minSdkVersion).

Wraz z każdą nową wersją Androida zmienia się jego działanie, a nawet wygląd. Jeśli jednak poziom interfejsu API platformy jest wyższy niż wersja zadeklarowana przez targetSdkVersion aplikacji, system może włączyć zachowania związane ze zgodnością, aby aplikacja nadal działała zgodnie z oczekiwaniami. Takie zachowania związane z kompatybilnością możesz wyłączyć, określając targetSdkVersion, aby dopasować poziom interfejsu API do platformy, na której działa.

Jeśli na przykład ustawisz tę wartość na „11” lub wyższą, system zastosuje domyślny motyw Holo do Twojej aplikacji, gdy będzie ona działać na Androidzie 3.0 lub nowszym, a także wyłączy tryb zgodności ekranu, gdy będzie ona działać na większych ekranach, ponieważ obsługa API na poziomie 11 oznacza obsługę większych ekranów.

System może włączyć wiele zachowań związanych ze zgodnością na podstawie wartości ustawionej w tym atrybucie. Niektóre z tych zachowań są opisane w odpowiednich wersjach platformy w Build.VERSION_CODES.

Aby utrzymać aplikację w zgodności z każdą wersją Androida, zwiększ wartość tego atrybutu, aby odpowiadała najnowszemu poziomowi interfejsu API, a następnie dokładnie przetestuj aplikację na odpowiedniej wersji platformy.

Wprowadzono w poziomie API 4

android:maxSdkVersion

Liczba całkowita określająca maksymalny poziom interfejsu API, na którym aplikacja ma działać.

W Androidzie 1.5, 1.6, 2.0 i 2.0.1 system sprawdza wartość tego atrybutu podczas instalowania aplikacji i ponownej weryfikacji aplikacji po aktualizacji systemu. W obu przypadkach, jeśli atrybut maxSdkVersion aplikacji jest niższy niż poziom interfejsu API używany przez sam system, system nie zezwoli na zainstalowanie aplikacji. W przypadku ponownej weryfikacji po aktualizacji systemu spowoduje to usunięcie aplikacji z urządzenia.

Aby zilustrować, jak ten atrybut może wpływać na aplikację po aktualizacjach systemu, rozważmy ten przykład:

Aplikacja deklarująca maxSdkVersion="5" w pliku manifestu jest publikowana w Google Play. Użytkownik, którego urządzenie ma Androida 1.6 (poziom interfejsu API 4), pobiera i instaluje aplikację. Po kilku tygodniach otrzymuje aktualizację systemu przez sieć do Androida 2.0 (poziom interfejsu API 5). Po zainstalowaniu aktualizacji system sprawdza maxSdkVersion aplikacji i ponownie ją weryfikuje.

Aplikacja działa normalnie. Jednak po pewnym czasie urządzenie otrzymuje kolejną aktualizację systemu, tym razem do Androida 2.0.1 (poziom interfejsu API 6). Po aktualizacji system nie może ponownie zweryfikować aplikacji, ponieważ jego własny poziom API (6) jest teraz wyższy niż maksymalny poziom obsługiwany przez aplikację (5). System uniemożliwia wyświetlanie aplikacji użytkownikowi, co w efekcie powoduje jej usunięcie z urządzenia.

Ostrzeżenie: nie zalecamy deklarowania tego atrybutu. Po pierwsze, nie musisz ustawiać atrybutu jako sposobu blokowania wdrażania aplikacji w nowych wersjach platformy Android, gdy są one udostępniane. Nowe wersje platformy są w pełni zgodne wstecznie. Aplikacja działa prawidłowo w nowych wersjach, o ile korzysta tylko ze standardowych interfejsów API i jest zgodna ze sprawdzonymi metodami programowania. Po drugie, w niektórych przypadkach zadeklarowanie tego atrybutu może spowodować usunięcie aplikacji z urządzeń użytkowników po aktualizacji systemu do wyższego poziomu interfejsu API. Większość urządzeń, na których prawdopodobnie zostanie zainstalowana Twoja aplikacja, otrzymuje okresowe aktualizacje systemu bezprzewodowo, więc przed ustawieniem tego atrybutu rozważ ich wpływ na aplikację.

Wprowadzono w poziomie API 4

Niektóre wersje Androida (nowsze niż 2.0.1) nie sprawdzają ani nie wymuszają atrybutu maxSdkVersion podczas instalacji lub ponownej weryfikacji. Google Play nadal używa tego atrybutu jako filtra podczas wyświetlania użytkownikom aplikacji dostępnych do pobrania.

wprowadzony w:

Poziom API 1

Co to jest poziom interfejsu API?

Poziom interfejsu API to wartość całkowita, która jednoznacznie identyfikuje wersję interfejsu API platformy oferowaną przez wersję platformy Android.

Platforma Android udostępnia interfejs API, którego aplikacje mogą używać do interakcji z systemem Android. Interfejs API platformy składa się z:

• podstawowy zestaw pakietów i klas,
• Zestaw elementów i atrybutów XML do deklarowania pliku manifestu
• Zestaw elementów i atrybutów XML do deklarowania zasobów i uzyskiwania do nich dostępu
• Zestaw intencji
• Zestaw uprawnień, o które mogą prosić aplikacje, oraz egzekwowanie uprawnień w systemie.

Każda kolejna wersja platformy Android może zawierać aktualizacje interfejsu API platformy aplikacji na Androida.

Aktualizacje interfejsu API platformy są projektowane tak, aby nowy interfejs API był zgodny ze starszymi wersjami. Oznacza to, że większość zmian w interfejsie API ma charakter dodatkowy i wprowadza nowe lub zastępcze funkcje. W miarę uaktualniania części interfejsu API starsze, zastąpione części są wycofywane, ale nie usuwane, aby istniejące aplikacje mogły nadal z nich korzystać.

W bardzo niewielu przypadkach części interfejsu API są modyfikowane lub usuwane, chociaż takie zmiany są zwykle potrzebne tylko do zapewnienia niezawodności interfejsu API oraz bezpieczeństwa aplikacji lub systemu. Wszystkie pozostałe części interfejsu API z wcześniejszych wersji są przenoszone bez zmian.

Interfejs API platformy Androida jest określany za pomocą identyfikatora liczbowego zwanego poziomem interfejsu API. Każda wersja platformy Android obsługuje dokładnie jeden poziom interfejsu API, chociaż obsługiwane są też wszystkie wcześniejsze poziomy interfejsu API (aż do poziomu 1). Pierwsza wersja platformy Android miała poziom interfejsu API 1, a kolejne wersje zwiększały ten poziom. Interfejsy API wprowadzone w wersjach przedpremierowych pakietów SDK, które nie osiągnęły jeszcze stabilności platformy, są oznaczone jako „Interfejs API w trakcie opracowywania” zamiast liczbowego poziomu interfejsu API.

W tabeli poniżej znajdziesz poziom interfejsu API obsługiwany przez poszczególne wersje platformy Android. Informacje o względnej liczbie urządzeń, na których działa każda wersja, znajdziesz w panelu dystrybucji.

Interfejsy API w trakcie opracowywania

W dokumentacji API Androida niektóre interfejsy API są oznaczone jako „API under development” (Interfejs API w trakcie opracowywania) zamiast liczbą całkowitą określającą poziom interfejsu API. Interfejsy API w trakcie opracowywania mają te cechy:

• Stan wersji przedpremierowej: te interfejsy API są obecnie częścią aktywnej wersji pakietu SDK w wersji beta lub canary i nie osiągnęły jeszcze stabilności platformy.
• Brak gwarancji stabilności: w przeciwieństwie do opublikowanych interfejsów API (które mają stały poziom API i są wstecznie kompatybilne w przypadku przyszłych wersji) interfejsy API w trakcie opracowywania mogą zmieniać sygnatury, nazwy lub zostać całkowicie usunięte między wersjami pakietu SDK w wersji podglądowej.

Sprawdzanie interfejsów API w trakcie opracowywania (PREVIEW_SDK_INT)

Interfejsy API w trakcie opracowywania mogą się zmieniać lub znikać między wersjami podglądowymi, dlatego nigdy nie używaj sprawdzania „większe lub równe” (>=), aby chronić wywołania nieopublikowanych interfejsów API. Interfejs API dostępny w wersji przedpremierowej 1 może zostać zmodyfikowany lub usunięty w wersji przedpremierowej 2.

Zamiast tego aplikacje eksperymentujące z funkcjami w wersji podglądowej muszą sprawdzać wartość Build.VERSION.PREVIEW_SDK_INT pod kątem ścisłej równości (==) z dokładną wersją podglądową, na podstawie której została skompilowana:

• W przypadku ostatecznych wersji produkcyjnych i publikacji wartość Build.VERSION.PREVIEW_SDK_INT jest zawsze równa 0.
• W wersjach przedpremierowych PREVIEW_SDK_INT jest unikalny dla każdej wersji.

Zastosowania poziomu interfejsu API w Androidzie

Identyfikator poziomu interfejsu API odgrywa kluczową rolę w zapewnianiu jak najlepszych wrażeń użytkownikom i deweloperom aplikacji:

• Umożliwia on platformie Android opisanie maksymalnej wersji interfejsu API platformy, którą obsługuje.
• Umożliwia aplikacjom opisanie wersji interfejsu API platformy, której wymagają.
• Umożliwia to systemowi negocjowanie instalacji aplikacji na urządzeniu użytkownika, dzięki czemu nie są instalowane aplikacje niezgodne z wersją.

Każda wersja platformy Androida przechowuje identyfikator poziomu interfejsu API wewnętrznie, w samym systemie Android.

Aplikacje mogą używać elementu manifestu udostępnianego przez interfejs API platformy – <uses-sdk> – do opisywania minimalnego i maksymalnego poziomu interfejsu API, w którym mogą działać, a także preferowanego poziomu interfejsu API, który obsługują. Element ten ma 3 kluczowe atrybuty:

• android:minSdkVersion: minimalny poziom interfejsu API, na którym może działać aplikacja. Wartość domyślna to „1”.
• android:targetSdkVersion: poziom interfejsu API, na którym ma działać aplikacja. W niektórych przypadkach umożliwia to aplikacji używanie elementów manifestu lub zachowań zdefiniowanych na docelowym poziomie interfejsu API, zamiast ograniczać się do używania tylko tych zdefiniowanych na minimalnym poziomie interfejsu API.
• android:maxSdkVersion: maksymalny poziom interfejsu API, na którym aplikacja może działać. Ważne: zanim zaczniesz używać tego atrybutu, przeczytaj informacje o nim na tej stronie.

Aby na przykład określić minimalny poziom interfejsu API systemu, którego aplikacja wymaga do działania, aplikacja zawiera w pliku manifestu element <uses-sdk> z atrybutem android:minSdkVersion. Wartość android:minSdkVersion to liczba całkowita odpowiadająca poziomowi interfejsu API najwcześniejszej wersji platformy Android, na której może działać aplikacja.

Gdy użytkownik próbuje zainstalować aplikację lub gdy system Android ponownie weryfikuje aplikację po aktualizacji systemu, najpierw sprawdza atrybuty <uses-sdk> w jej pliku manifestu i porównuje wartości z własnym wewnętrznym poziomem interfejsu API. System zezwala na rozpoczęcie instalacji tylko wtedy, gdy spełnione są te warunki:

• Jeśli zadeklarowany jest atrybut android:minSdkVersion, jego wartość jest mniejsza lub równa liczbie całkowitej poziomu interfejsu API systemu. Jeśli nie zostanie zadeklarowany, system zakłada, że aplikacja wymaga poziomu API 1.
• Jeśli zadeklarowany jest atrybut android:maxSdkVersion, jego wartość jest równa lub większa niż liczba całkowita poziomu interfejsu API systemu. Jeśli nie zostanie zadeklarowany, system zakłada, że aplikacja nie ma maksymalnego poziomu API. Więcej informacji o tym, jak system obsługuje ten atrybut, znajdziesz w jego opisie.

Jeśli element <uses-sdk> zostanie zadeklarowany w manifeście aplikacji, może wyglądać tak:

<manifest>
  <uses-sdk android:minSdkVersion="5" />
  ...
</manifest>

Głównym powodem, dla którego aplikacja deklaruje poziom interfejsu API w android:minSdkVersion, jest poinformowanie systemu Android, że korzysta z interfejsów API, które zostały wprowadzone na określonym poziomie interfejsu API.

Jeśli aplikacja zostanie zainstalowana na platformie z niższym poziomem interfejsu API, ulegnie awarii w czasie działania, gdy spróbuje uzyskać dostęp do interfejsów API, które nie istnieją. System zapobiega takiej sytuacji, uniemożliwiając instalację aplikacji, jeśli najniższy wymagany przez nią poziom API jest wyższy niż poziom API platformy na urządzeniu docelowym.

Uwagi dotyczące programowania

W sekcjach poniżej znajdziesz informacje o poziomie interfejsu API, które musisz wziąć pod uwagę podczas tworzenia aplikacji.

Dalsza zgodność aplikacji

Aplikacje na Androida są zwykle zgodne z nowymi wersjami platformy Android.

Prawie wszystkie zmiany w interfejsie API platformy są dodatkowe, więc aplikacja na Androida opracowana przy użyciu dowolnej wersji interfejsu API określonej przez poziom interfejsu API jest zgodna z późniejszymi wersjami platformy Android i wyższymi poziomami interfejsu API. Aplikacja może działać na wszystkich późniejszych wersjach platformy Android, z wyjątkiem odosobnionych przypadków, w których aplikacja korzysta z części interfejsu API, która została później z jakiegoś powodu usunięta.

Zgodność z przyszłymi wersjami jest ważna, ponieważ wiele urządzeń z Androidem otrzymuje bezprzewodowe (OTA) aktualizacje systemu. Użytkownik może zainstalować aplikację i z niej korzystać, a potem otrzymać aktualizację OTA do nowej wersji platformy Android. Po zainstalowaniu aktualizacji aplikacja będzie działać w nowej wersji środowiska wykonawczego, ale nadal będzie mieć dostęp do interfejsu API i funkcji systemowych, od których zależy.

Zmiany pod interfejsem API, takie jak zmiany w samym systemie bazowym, mogą mieć wpływ na działanie aplikacji w nowym środowisku. Jako deweloper aplikacji musisz wiedzieć, jak aplikacja wygląda i działa w każdym środowisku systemowym.

Aby ułatwić Ci testowanie aplikacji na różnych wersjach platformy Android, pakiet Android SDK zawiera wiele platform, które możesz pobrać. Każda platforma zawiera zgodny obraz systemu, który możesz uruchomić na AVD, aby przetestować aplikację.

Zgodność wsteczna aplikacji

Aplikacje na Androida nie muszą być wstecznie zgodne z wersjami platformy Android starszymi niż wersja, w której zostały skompilowane.

Każda nowa wersja platformy Android może zawierać nowe interfejsy API platformy, np. takie, które zapewniają aplikacjom dostęp do nowych funkcji platformy lub zastępują istniejące części interfejsu API. Nowe interfejsy API są dostępne dla aplikacji działających na nowej platformie, a także na jej nowszych wersjach, zgodnie z poziomem interfejsu API. Jednak starsze wersje platformy nie zawierają nowych interfejsów API, więc aplikacje, które z nich korzystają, nie mogą na nich działać.

Chociaż mało prawdopodobne jest, że urządzenie z Androidem zostanie przywrócone do wcześniejszej wersji platformy, warto pamiętać, że wiele urządzeń może działać na starszych wersjach platformy. Nawet w przypadku urządzeń, które otrzymują aktualizacje OTA, niektóre mogą mieć opóźnienia i nie otrzymywać aktualizacji przez dłuższy czas.

Wybierz wersję platformy i poziom interfejsu API

Podczas tworzenia aplikacji wybierasz wersję platformy, pod kątem której ją kompilujesz. Ogólnie rzecz biorąc, kompiluj aplikację pod kątem najniższej możliwej wersji platformy, którą może obsługiwać.

Najniższą możliwą wersję platformy możesz określić, kompilując aplikację z kolejnymi niższymi wersjami docelowymi. Po określeniu najniższej wersji utwórz AVD, używając odpowiedniej wersji platformy i poziomu API, a następnie w pełni przetestuj aplikację. Pamiętaj, aby zadeklarować atrybut android:minSdkVersion w manifeście aplikacji i ustawić jego wartość na poziom API wersji platformy.

Deklarowanie minimalnego poziomu interfejsu API

Jeśli tworzysz aplikację, która korzysta z interfejsów API lub funkcji systemu wprowadzonych w najnowszej wersji platformy, ustaw atrybut android:minSdkVersion na poziom interfejsu API najnowszej wersji platformy. Dzięki temu użytkownicy będą mogli zainstalować Twoją aplikację tylko wtedy, gdy na ich urządzeniach będzie działać zgodna wersja platformy Android. Dzięki temu aplikacja będzie działać prawidłowo na ich urządzeniach.

Jeśli aplikacja korzysta z interfejsów API wprowadzonych w najnowszej wersji platformy, ale nie deklaruje atrybutu android:minSdkVersion, działa prawidłowo na urządzeniach z najnowszą wersją platformy, ale nie na urządzeniach z wcześniejszymi wersjami platformy. W tym drugim przypadku aplikacja ulega awarii w czasie działania, gdy próbuje użyć interfejsów API, które nie istnieją w starszych wersjach.

Testowanie na wyższych poziomach interfejsu API

Po skompilowaniu aplikacji przetestuj ją na platformie określonej w atrybucie android:minSdkVersion aplikacji. Aby to zrobić, utwórz AVD, który korzysta z wersji platformy wymaganej przez Twoją aplikację. Aby sprawdzić zgodność z przyszłymi wersjami, uruchom i przetestuj aplikację na wszystkich platformach, które korzystają z wyższego poziomu interfejsu API niż ten, którego używa Twoja aplikacja.

Pakiet Android SDK zawiera wiele wersji platformy, z których możesz korzystać, w tym najnowszą. Udostępnia też narzędzie do aktualizacji, za pomocą którego możesz w razie potrzeby pobierać inne wersje platformy.

Aby uzyskać dostęp do narzędzia do aktualizacji, użyj narzędzia wiersza poleceń android, które znajduje się w katalogu <sdk>/tools. Aby uruchomić narzędzie do aktualizacji pakietu SDK, wykonaj polecenie android sdk. Możesz też kliknąć dwukrotnie plik android.bat (Windows) lub android (OS X/Linux).

Aby uruchomić aplikację na różnych wersjach platformy w emulatorze, utwórz AVD dla każdej wersji platformy, którą chcesz przetestować. Więcej informacji o AVD znajdziesz w artykule Tworzenie urządzeń wirtualnych i zarządzanie nimi. Jeśli do testowania używasz urządzenia fizycznego, sprawdź, jaki jest poziom interfejsu API platformy Android, na której działa. W tabeli w tym dokumencie znajdziesz listę wersji platformy i odpowiadających im poziomów interfejsu API.

Filtrowanie dokumentacji referencyjnej według poziomu interfejsu API

Na stronach dokumentacji referencyjnej platformy Android w lewym górnym rogu każdej strony znajduje się element sterujący „Poziom API”. Za pomocą tego elementu możesz wyświetlać dokumentację tylko tych części interfejsu API, które są faktycznie dostępne dla Twojej aplikacji, na podstawie poziomu interfejsu API określonego w atrybucie android:minSdkVersion pliku manifestu.

Aby użyć filtrowania, wybierz z menu poziom interfejsu API określony przez aplikację. Interfejsy API wprowadzone na późniejszym poziomie API są wyszarzone, a ich zawartość jest zamaskowana, ponieważ nie są dostępne dla Twojej aplikacji.

Filtrowanie według poziomu interfejsu API w dokumentacji nie zapewnia widoku nowości ani funkcji wprowadzonych na poszczególnych poziomach interfejsu API. Umożliwia wyświetlenie całego interfejsu API powiązanego z danym poziomem API, z wyłączeniem elementów interfejsu API wprowadzonych na późniejszych poziomach API.

Aby wrócić do pełnej dokumentacji, w menu poziomu interfejsu API wybierz REL. Domyślnie filtrowanie według poziomu interfejsu API jest wyłączone, dzięki czemu możesz wyświetlać pełny interfejs API platformy niezależnie od poziomu interfejsu API.

Dokumentacja referencyjna poszczególnych elementów interfejsu API określa poziom interfejsu API, na którym wprowadzono każdy element. Poziom API pakietów i klas jest określony jako „Dodano na poziomie API” w prawym górnym rogu obszaru treści na każdej stronie dokumentacji. Poziom API dla elementów klasy jest podany w nagłówkach szczegółowych opisów, po prawej stronie. W przypadku interfejsów API w wersji przedpremierowej, które nie osiągnęły jeszcze stabilności platformy, w tym miejscu wyświetla się komunikat „Interfejs API w trakcie opracowywania” zamiast liczby całkowitej poziomu interfejsu API.