<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, upewnij się, że rozumiesz filtry w Google Play.

składnia:

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

zawarte 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ć w zależności od urządzenia.

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 interfejsu 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 pomocniczą wersję SDK, czy jej wymaga.

Przeczytaj też dokument o zarządzaniu wersjami aplikacji.

atrybuty:

android:minSdkVersion

Liczba całkowita określająca minimalny poziom interfejsu 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, domyślna wartość jest równa wartości podanej 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 wartość targetSdkVersion, która będzie zgodna z poziomem interfejsu API platformy, na której działa aplikacja.

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

W zależności od wartości ustawionej w tym atrybucie system może włączyć wiele zachowań związanych ze zgodnością. 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 interfejsie API na poziomie 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 swoim manifeście jest opublikowana w Google Play. Użytkownik, którego urządzenie działa na Androidzie 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 usunięcie jej 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 interfejsie API na poziomie 4

Niektóre wersje Androida (starsze 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 prezentowania 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 struktury, 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, a także 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 poszczególnych 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 rzadkich przypadkach części interfejsu API są modyfikowane lub usuwane, ale zwykle takie zmiany są konieczne tylko w celu zapewnienia niezawodności interfejsu API oraz bezpieczeństwa aplikacji lub systemu. Wszystkie pozostałe części interfejsu API z poprzednich wersji są przenoszone bez zmian.

Interfejs API platformy, który udostępnia platforma Android, jest określany za pomocą identyfikatora liczbowego zwanego poziomem interfejsu API. Każda wersja platformy Android obsługuje dokładnie 1 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.

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.

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 platformie Android opisanie maksymalnej wersji interfejsu API platformy, którą obsługuje.
• Umożliwia aplikacjom opisanie wymaganej wersji interfejsu API platformy.
• 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 ma 3 kluczowe atrybuty:

• android:minSdkVersion: minimalny poziom interfejsu API, na którym aplikacja może działać. Wartością domyślną jest „1”.
• android:targetSdkVersion: poziom interfejsu API, na którym ma działać aplikacja. W niektórych przypadkach umożliwia to aplikacji korzystanie z elementów manifestu lub zachowań zdefiniowanych na docelowym poziomie interfejsu API, zamiast ograniczać się do używania tylko tych, które są zdefiniowane 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 na jego temat na tej stronie.

Aby na przykład określić minimalny poziom interfejsu API systemu, którego aplikacja wymaga do działania, aplikacja zawiera w swoim manifeście 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 pliku manifestu aplikacji 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 założy, że aplikacja wymaga poziomu interfejsu API 1.
• Jeśli zadeklarowany jest atrybut android:maxSdkVersion, jego wartość jest równa lub większa od liczby całkowitej 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.

Gdy element <uses-sdk> jest 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 API, jest zgodna z późniejszymi wersjami platformy Android i wyższymi poziomami 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ć interfejs API i funkcje systemowe, od których zależy.

Zmiany pod interfejsem API, np. 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ć 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, takie jak te, 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, aby urządzenie z Androidem zostało 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.

Wybieranie wersji platformy i poziomu 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 interfejsu API, a następnie dokładnie 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 używają 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. Listę wersji platformy i odpowiadających im poziomów interfejsu API znajdziesz w tabeli w tym dokumencie.

Filtrowanie dokumentacji 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ą 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 wyświetlania pełnej dokumentacji, u góry 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 interfejsu API dla pakietów i klas jest określony jako „Dodano w interfejsie API na poziomie” w prawym górnym rogu obszaru treści na każdej stronie dokumentacji. Poziom API dla elementów klasy jest określony w nagłówkach szczegółowych opisów, przy prawym marginesie.