<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 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 Androida za pomocą liczby całkowitej poziomu interfejsu API. Poziom interfejsu API aplikacji jest porównywany z poziomem interfejsu API danego systemu Android, który może się różnić w zależności od urządzenia z Androidem.

Pomimo nazwy ten element służy do określania poziomu interfejsu API, a nie numeru wersji pakietu SDK ani platformy Androida. Poziom interfejsu API jest zawsze pojedynczą liczbą całkowitą. Nie można określić poziomu interfejsu API na podstawie 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ć, że aplikacja jest kierowana na wersję podrzędną pakietu SDK lub 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.

Uwaga: 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 jest i nie zadeklarowano odpowiedniego elementu minSdkVersion, aplikacja zainstalowana w systemie z niezgodnym poziomem interfejsu API ulegnie awarii 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 kierowana jest aplikacja. Jeśli nie zostanie ustawiony, wartością domyślną jest wartość podana w minSdkVersion.

Ten atrybut informuje system, że aplikacja została przetestowana pod kątem wersji docelowej, a system nie włącza żadnych zachowań zgodności, aby zachować zgodność aplikacji z wersją docelową. Aplikacja nadal może działać na starszych wersjach (do minSdkVersion).

W miarę rozwoju Androida i pojawiania się nowych wersji niektóre zachowania, a nawet wygląd mogą się zmieniać. Jeśli jednak poziom interfejsu API platformy jest wyższy niż wersja zadeklarowana przez targetSdkVersion aplikacji, system może włączyć zachowania zgodności, aby aplikacja działała zgodnie z oczekiwaniami. Możesz wyłączyć te zachowania zgodności, określając targetSdkVersion, aby dopasować poziom interfejsu API platformy, na której działa aplikacja.

Jeśli na przykład ustawisz tę wartość na „11” lub wyższą, system będzie mógł zastosować domyślny motyw Holo w aplikacji, gdy będzie ona działać na Androidzie 3.0 lub nowszym. Wyłączy też tryb zgodności z ekranem na większych ekranach, ponieważ obsługa interfejsu API na poziomie 11 domyślnie obejmuje większe ekrany.

W zależności od wartości ustawionej dla tego atrybutu system może włączyć wiele zachowań związanych ze zgodnością. Kilka z tych zachowań jest opisanych w odpowiednich wersjach platformy w dokumentacji Build.VERSION_CODES.

Aby zachować zgodność aplikacji z każdą kolejną 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: poziom 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 ponownego sprawdzania jej po aktualizacji systemu. W obu przypadkach, jeśli atrybut maxSdkVersion aplikacji jest niższy niż poziom interfejsu API używany przez system, system nie zezwala na instalację aplikacji. W przypadku ponownej weryfikacji po aktualizacji systemu spowoduje to usunięcie aplikacji z urządzenia.

Aby zilustrować, jak ten atrybut może wpłynąć na aplikację po aktualizacjach systemu, rozważ 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 bezprzewodową aktualizację systemu do Androida 2.0 (poziom interfejsu API 5). Po zainstalowaniu aktualizacji system sprawdza maxSdkVersion aplikacji i pomyślnie przeprowadza ponowną weryfikację.

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 już ponownie zweryfikować aplikacji, ponieważ jego własny poziom interfejsu API (6) jest teraz wyższy niż maksymalny obsługiwany przez aplikację (5). System uniemożliwia użytkownikowi wyświetlanie aplikacji, co w praktyce oznacza usunięcie jej z urządzenia.

Ostrzeżenie: nie zalecamy deklarowania tego atrybutu. Po pierwsze nie ma potrzeby ustawiania tego atrybutu jako sposobu blokowania wdrażania aplikacji na nowych wersjach platformy Androida, gdy są one udostępniane. Nowe wersje platformy są w pełni zgodne wstecznie. Twoja aplikacja działa prawidłowo w nowych wersjach, pod warunkiem że używa tylko standardowych interfejsów API i jest zgodna ze sprawdzonymi metodami programistycznymi. Po drugie, w niektórych przypadkach zadeklarowanie 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 weź pod uwagę ich wpływ na aplikację.

Wprowadzono: poziom API 4

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

wprowadzono w:

Poziom API 1

Czym jest poziom interfejsu API?

Poziom interfejsu API to liczba całkowita, która jednoznacznie identyfikuje wersję interfejsu API platformy oferowaną przez wersję platformy Androida.

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

• 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 Androida może zawierać aktualizacje interfejsu API platformy aplikacji na Androida, który udostępnia.

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

W bardzo nielicznych przypadkach części interfejsu API są modyfikowane lub usuwane, chociaż zwykle takie zmiany są 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, który dostarcza platforma Androida, jest określany za pomocą identyfikatora w postaci liczby całkowitej, który nazywa się poziomem interfejsu API. Każda wersja platformy Androida 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 Androida miała poziom interfejsu API 1, a kolejne wersje miały wyższe poziomy. Interfejsy API wprowadzone lub wycofane w przedpremierowych pakietach SDK w wersji testowej, które nie osiągnęły stabilności platformy, są oznaczone jako „Interfejs API w trakcie tworzenia” zamiast numeru poziomu interfejsu API.

W tabeli poniżej znajdziesz poziom interfejsu API obsługiwany przez poszczególne wersje platformy Androida. Informacje o względnej liczbie urządzeń z poszczególnymi wersjami znajdziesz w panelu dystrybucji.

Interfejsy API w trakcie opracowywania

W dokumentacji API Androida interfejsy API dodane lub wycofane w wersji przedpremierowej pakietu SDK są oznaczone jako „API w trakcie tworzenia” zamiast numeru poziomu API. Ta etykieta dotyczy zarówno powiadomień „Dodano w”, jak i „Wycofano w”, dopóki pakiet SDK nie osiągnie stabilności platformy i nie otrzyma ostatecznego głównego lub podrzędnego poziomu interfejsu API. Interfejsy API w trakcie opracowywania mają te cechy:

• Stan wersji przedpremierowej: dodanie lub wycofanie interfejsu API jest częścią aktywnej wersji testowej pakietu SDK w wersji beta lub Canary przed sfinalizowaniem poziomu interfejsu API.
• Brak gwarancji stabilności: w przeciwieństwie do opublikowanych interfejsów API (które mają stały poziom i są zgodne wstecznie z przyszłymi wersjami) interfejsy API w trakcie tworzenia mogą zmieniać sygnatury, nazwy lub zostać całkowicie usunięte między wersjami testowymi pakietu SDK.

Sprawdzanie interfejsów API w trakcie tworzenia w czasie działania (PREVIEW_SDK_INT)

Interfejsy API w trakcie opracowywania mogą się zmieniać lub znikać między wersjami testowymi, dlatego nigdy nie używaj sprawdzania większości lub równości (>=) do ochrony wywołań nieopublikowanych interfejsów API. Interfejs API dostępny w wersji testowej 1 może zostać zmodyfikowany lub usunięty w wersji testowej 2.

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

• W przypadku ostatecznych kompilacji i wersji produkcyjnych Build.VERSION.PREVIEW_SDK_INT to zawsze 0.
• W przypadku wersji testowych PREVIEW_SDK_INT jest unikalny dla każdej wersji.

Zastosowania poziomu interfejsu API na Androidzie

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

• Umożliwia platformie Androida opisanie maksymalnej obsługiwanej wersji interfejsu API platformy.
• Umożliwia aplikacjom opisanie wymaganej wersji interfejsu API platformy.
• Umożliwia 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, na którym mogą działać, oraz preferowanego poziomu interfejsu API, który mają obsługiwać. Element ma 3 główne atrybuty:

• android:minSdkVersion: minimalny poziom interfejsu API, na którym aplikacja może działać. Wartość domyślna to „1”.
• android:targetSdkVersion: poziom interfejsu API, na którym aplikacja ma działać. W niektórych przypadkach pozwala to aplikacji na używanie elementów lub zachowań pliku manifestu zdefiniowanych na docelowym poziomie interfejsu API, a nie 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 użyjesz tego atrybutu, zapoznaj się z informacjami na jego temat na tej stronie.

Na przykład, aby 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 Androida, na której aplikacja może działać.

Gdy użytkownik próbuje zainstalować aplikację lub gdy aplikacja jest ponownie sprawdzana po aktualizacji systemu, system Android 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 atrybut android:minSdkVersion jest zadeklarowany, 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 interfejsu API na poziomie 1.
• Jeśli atrybut android:maxSdkVersion jest zadeklarowany, jego wartość jest równa liczbie całkowitej poziomu interfejsu API systemu lub od niej większa. Jeśli nie zostanie zadeklarowany, system zakłada, że aplikacja nie ma maksymalnego poziomu interfejsu API. Aby dowiedzieć się więcej o tym, jak system obsługuje ten atrybut, przeczytaj jego opis.

Element <uses-sdk> 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 pliku android:minSdkVersion, jest poinformowanie systemu Android, że używa interfejsów API, które zostały wprowadzone na określonym poziomie interfejsu API.

Jeśli aplikacja zostanie w jakiś sposób zainstalowana na platformie z niższym poziomem interfejsu API, ulegnie awarii w czasie działania, gdy spróbuje uzyskać dostęp do nieistniejących interfejsów API. System zapobiega temu, nie zezwalając na instalację aplikacji, jeśli najniższy wymagany przez nią poziom interfejsu API jest wyższy niż poziom wersji 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.

Zgodność aplikacji w przyszłości

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

Ponieważ prawie wszystkie zmiany w interfejsie API platformy mają charakter addytywny, aplikacja na Androida opracowana przy użyciu danej wersji interfejsu API, określonej przez jej poziom, jest zgodna z późniejszymi wersjami platformy Androida i wyższymi poziomami interfejsu API. Aplikacja może działać na wszystkich nowszych wersjach platformy Androida, z wyjątkiem odosobnionych przypadków, gdy aplikacja używa części interfejsu API, która została później z jakiegoś powodu usunięta.

Zgodność w przód jest ważna, ponieważ wiele urządzeń z Androidem otrzymuje bezprzewodowe aktualizacje systemu (OTA). Użytkownik może zainstalować aplikację i korzystać z niej, a później otrzymać aktualizację OTA do nowej wersji platformy Androida. Po zainstalowaniu aktualizacji aplikacja działa w nowej wersji środowiska wykonawczego, która nadal ma interfejs API i funkcje systemowe, od których zależy aplikacja.

Zmiany poniżej interfejsu API, np. w samym systemie, mogą mieć wpływ na aplikację, gdy jest ona uruchamiana w nowym środowisku. Jako deweloper aplikacji musisz wiedzieć, jak aplikacja wygląda i zachowuje się 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żna pobrać. Każda platforma zawiera zgodny obraz systemu, który można uruchomić w AVD, aby przetestować aplikację.

Zgodność wsteczna aplikacji

Aplikacje na Androida niekoniecznie są zgodne wstecznie z wersjami platformy Androida starszymi niż wersja, na którą zostały skompilowane.

Każda nowa wersja platformy Androida może zawierać nowe interfejsy API platformy, np. takie, które dają aplikacjom dostęp do nowych funkcji platformy lub zastępują istniejące części interfejsu API. Nowe interfejsy API są dostępne dla aplikacji, gdy są one uruchamiane na nowej platformie, a także gdy są uruchamiane na nowszych wersjach platformy, zgodnie z poziomem interfejsu API. Ponieważ jednak wcześniejsze wersje platformy nie zawierają nowych interfejsów API, aplikacje, które ich używają, nie mogą działać na tych platformach.

Chociaż jest mało prawdopodobne, aby urządzenie z Androidem zostało przywrócone do poprzedniej wersji platformy, warto pamiętać, że wiele urządzeń może działać na starszych wersjach platformy. Nawet wśród 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, na której chcesz ją skompilować. Zasadniczo 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ę pod kątem kolejnych niższych wersji docelowych. Po określeniu najniższej wersji utwórz AVD z odpowiednią wersją platformy i poziomem interfejsu API, a następnie dokładnie przetestuj aplikację. Pamiętaj, aby w pliku manifestu aplikacji zadeklarować atrybut android:minSdkVersion i ustawić jego wartość na poziom interfejsu API wersji platformy.

Deklarowanie minimalnego poziomu interfejsu API

Jeśli tworzysz aplikację, która korzysta z interfejsów API lub funkcji systemowych 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 działa zgodna wersja platformy Androida. Dzięki temu Twoja aplikacja będzie działać prawidłowo na ich urządzeniach.

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

Testowanie pod kątem wyższych poziomów interfejsu API

Po skompilowaniu aplikacji przetestuj ją na platformie określonej w atrybucie android:minSdkVersion aplikacji. W tym celu utwórz urządzenie AVD, które korzysta z wersji platformy wymaganej przez aplikację. Dodatkowo, aby sprawdzić zgodność z przyszłymi wersjami, uruchom i przetestuj aplikację na wszystkich platformach, które używają wyższego poziomu interfejsu API niż Twoja aplikacja.

Android SDK zawiera wiele wersji platformy, których możesz używać, w tym najnowszą wersję, oraz narzędzie do aktualizacji, za pomocą którego możesz w razie potrzeby pobrać inne wersje platformy.

Aby uzyskać dostęp do aktualizatora, użyj narzędzia wiersza poleceń android, które znajduje się w katalogu <sdk>/tools. Możesz uruchomić aktualizator pakietu SDK, wykonując 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 Androida, na której działa. Tabela w tym dokumencie zawiera listę wersji platformy i ich poziomów interfejsu API.

Filtrowanie dokumentacji według poziomu interfejsu API

Strony dokumentacji platformy Androida zawierają w lewym górnym rogu każdej strony opcję „Poziom interfejsu API”. Możesz użyć tego elementu sterującego, aby wyświetlić 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 w pliku manifestu.

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

Filtrowanie według poziomu interfejsu API w dokumentacji nie pokazuje, co jest nowe lub wprowadzone na każdym poziomie interfejsu API. Umożliwia wyświetlenie całego interfejsu API powiązanego z danym poziomem interfejsu API, z wyłączeniem elementów interfejsu API wprowadzonych na późniejszych poziomach.

Aby wrócić do wyświetlania pełnej dokumentacji, wybierz REL u góry menu poziomu interfejsu API. Domyślnie filtrowanie według poziomu interfejsu API jest wyłączone, dzięki czemu możesz wyświetlić 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 dany element został wprowadzony lub wycofany. Poziom interfejsu API dla pakietów i klas jest określony jako „Dodano na poziomie interfejsu API” i (w stosownych przypadkach) „Wycofano na poziomie interfejsu API” w prawym górnym rogu obszaru zawartości na każdej stronie dokumentacji. Poziom interfejsu API dla elementów klasy jest określony w nagłówkach szczegółowych opisów, na prawym marginesie. W przypadku dodatków lub wycofań interfejsów API w wersji przedpremierowej, które nie osiągnęły stabilności platformy, w tych lokalizacjach zamiast numeru poziomu interfejsu API wyświetla się komunikat „Interfejs API w trakcie opracowywania”.