<uses-sdk>

Google Play używa atrybutów <uses-sdk>deklarowanych w pliku manifestu aplikacji, aby odfiltrowywać aplikacje 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" />

zawarte w:

<manifest>

description:

Umożliwia określenie zgodności aplikacji z co najmniej jedną wersją platformy Android za pomocą liczby całkowitej poziomu interfejsu API. Poziom interfejsu API wyrażony przez aplikację jest porównywany z poziomem interfejsu API danego systemu Androida, 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ślenia poziomu interfejsu API, a nie wersji pakietu SDK ani platformy Android. Poziom interfejsu API to zawsze pojedyncza liczba całkowita. Nie można określić poziomu interfejsu API na podstawie powiązanego numeru wersji Androida. Nie jest to na przykład wersja główna ani suma wersji głównej i podrzędnej.

Przeczytaj też dokument dotyczący zarządzania wersjami aplikacji.

atrybuty:

android:minSdkVersion

Całka oznaczająca minimalny poziom interfejsu API wymagany do działania aplikacji. System Android uniemożliwia użytkownikowi zainstalowanie aplikacji, jeśli poziom interfejsu API jest niższy niż wartość podana w tym atrybucie. Ten atrybut należy zawsze deklarować.

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, a nie zadeklarujesz odpowiedniej wartości minSdkVersion, aplikacja zainstalowana w systemie z niezgodnym poziomem interfejsu API ulegnie awarii podczas działania, gdy spróbuje uzyskać dostęp do niedostępnych interfejsów API. Z tego powodu pamiętaj, aby w atrybucie minSdkVersion zadeklarować odpowiedni poziom interfejsu API.

android:targetSdkVersion

Całka oznaczająca poziom interfejsu API, na który kierowana jest aplikacja. Jeśli nie zostanie ustawiony, jego domyślna wartość będzie taka sama jak wartość właściwości minSdkVersion.

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

Wraz z każdą nową wersją Androida mogą się zmieniać niektóre zachowania i nawet wygląd. Jeśli jednak poziom interfejsu API platformy jest wyższy niż wersja zadeklarowana przez targetSdkVersion Twojej aplikacji, system może włączyć zachowania zgodności, aby aplikacja nadal działała zgodnie z oczekiwaniami. Możesz wyłączyć takie zachowania zgodności, podając wartość targetSdkVersion, aby dopasować poziom interfejsu API do poziomu platformy, na której działa.

Na przykład ustawienie tej wartości na „11” lub wyższą powoduje zastosowanie przez system domyślnego motywu Holo w aplikacji podczas uruchamiania jej na Androidzie 3.0 lub nowszym. Ustawienie tej wartości na „11” lub wyższą powoduje też wyłączenie trybu zgodności ekranu podczas uruchamiania aplikacji na większych ekranach, ponieważ obsługa poziomu interfejsu API 11 oznacza domyślnie obsługę większych ekranów.

System może włączyć wiele zachowań związanych ze zgodnością na podstawie wartości ustawionej dla tego atrybutu. Niektóre z tych zachowań są opisane w opisie odpowiednich wersji platformy w dokumentacji Build.VERSION_CODES.

Aby aplikacja była zgodna z każdą nową 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.

Wprowadzone w poziomie interfejsu API 4

android:maxSdkVersion

Cała liczba oznaczają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 podczas ponownego sprawdzania jej poprawności po aktualizacji systemu. W obu przypadkach, jeśli atrybut maxSdkVersion aplikacji jest niższy niż poziom interfejsu API używany przez system, system nie pozwoli na zainstalowanie aplikacji. W przypadku ponownej weryfikacji po aktualizacji systemu aplikacja zostanie usunięta z urządzenia.

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

Aplikacja, która w swoim pliku manifestu deklaruje maxSdkVersion="5", została opublikowana w Google Play. Użytkownik, którego urządzenie ma Androida 1.6 (poziom interfejsu API 4), pobiera i instaluje aplikację. Po kilku tygodniach użytkownik otrzymuje bezprzewodową aktualizację systemu do Androida 2.0 (poziom interfejsu API 5). Po zainstalowaniu aktualizacji system sprawdza maxSdkVersion aplikacji i pomyślnie ją weryfikuje.

Aplikacja działa normalnie. Po jakimś czasie urządzenie otrzymało kolejną aktualizację systemu, tym razem do Androida 2.0.1 (poziom interfejsu API 6). Po aktualizacji system nie może ponownie sprawdzić aplikacji, ponieważ jego własny poziom API (6) jest wyższy niż maksymalny 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ć tego atrybutu, aby zablokować wdrażanie aplikacji w przypadku nowych wersji platformy Android, gdy tylko zostaną wydane. Nowe wersje platformy są w pełni zgodne z poprzednimi. Twoja aplikacja działa prawidłowo w nowych wersjach, o ile korzysta tylko ze standardowych interfejsów API i stosuje się do sprawdzonych metod programowania. Po drugie, w niektórych przypadkach zadeklarowanie tego atrybutu może spowodować, że aplikacja zostanie usunięta z urządzeń użytkowników po aktualizacji systemu do wyższego poziomu interfejsu API. Większość urządzeń, na których prawdopodobnie będzie zainstalowana Twoja aplikacja, otrzymuje okresowe aktualizacje systemowe bezprzewodowo, więc przed ustawieniem tego atrybutu zastanów się nad ich wpływem na aplikację.

Wprowadzone w poziomie interfejsu API 4

Niektóre wersje Androida (starsze niż 2.0.1) nie sprawdzają ani nie egzekwują atrybutu maxSdkVersion podczas instalacji ani ponownej weryfikacji. Google Play nadal używa tego atrybutu jako filtra, aby wyświetlać użytkownikom aplikacje dostępne do pobrania.

wprowadzona w:

Poziom API 1

Czym 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 Androida udostępnia interfejs API frameworku, którego aplikacje mogą używać do interakcji z podstawowym systemem Androida. Interfejs API frameworku 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 służących do deklarowania zasobów i uzyskiwania do nich dostępu
• zestaw intencji,
• zestaw uprawnień, o które aplikacje mogą prosić, a także zasady egzekwowania uprawnień uwzględnione w systemie.

Każda kolejna wersja platformy Android może zawierać aktualizacje interfejsu API Android Application Framework.

Aktualizacje interfejsu API framework są tak zaprojektowane, aby nowy interfejs API był zgodny z wcześniejszymi wersjami. Oznacza to, że większość zmian w interfejsie API jest uzupełniająca i wprowadza nowe funkcje lub zastępuje istniejące. W miarę uaktualniania interfejsu API starsze, zastępowane części są wycofywane, ale nie są usuwane, aby istniejące aplikacje mogły z nich nadal korzystać.

W bardzo rzadkich przypadkach niektóre części interfejsu API są modyfikowane lub usuwane, ale zwykle takie zmiany są potrzebne tylko do zapewnienia niezawodności interfejsu API oraz bezpieczeństwa aplikacji lub systemu. Wszystkie inne części interfejsu API z wcześniejszych wersji są przenoszone bez zmian.

Interfejs API frameworku dostarczany przez platformę Android jest określany za pomocą identyfikatora całkowitego o nazwie poziom interfejsu API. Każda wersja platformy Android obsługuje dokładnie jeden poziom interfejsu API, ale obsługa jest domyślna dla wszystkich wcześniejszych poziomów interfejsu API (do poziomu 1). Pierwsza wersja platformy Android miała poziom interfejsu API 1, a w kolejnych wersjach poziom interfejsu API był zwiększany.

Tabela poniżej określa poziom interfejsu API obsługiwany przez każdą wersję platformy Android. Informacje o względnej liczbie urządzeń z poszczególnymi wersjami znajdziesz w panelu Dystrybucja.

Zastosowanie poziomu interfejsu API na Androidzie

Identyfikator poziomu interfejsu API odgrywa kluczową rolę w zapewnieniu jak najlepszego działania aplikacji i zadowolenia użytkowników:

• Umożliwia platformie Android określenie maksymalnej wersji interfejsu API frameworku, którą obsługuje.
• Umożliwia aplikacjom określenie wersji interfejsu API framework, której potrzebują.
• Umożliwia systemowi negocjowanie instalacji aplikacji na urządzeniu użytkownika, aby nie instalować aplikacji niezgodnych z wersją.

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

Aplikacje mogą używać elementu manifestu udostępnianego przez interfejs API frameworku (<uses-sdk>), aby opisać minimalny i maksymalny poziom interfejsu API, w których mogą działać, a także preferowany poziom interfejsu API, który mają obsługiwać. Element 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 pozwala to aplikacji na korzystanie z elementów lub zachowań manifestu zdefiniowanych w docelowym poziomie interfejsu API, zamiast ograniczać ją do korzystania tylko z tych zdefiniowanych w minimalnym poziomie interfejsu API.
• android:maxSdkVersion: maksymalny poziom interfejsu API, na którym może działać aplikacja. Ważne: zanim użyjesz tego atrybutu, zapoznaj się z informacjami o nim na tej stronie.

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

Gdy użytkownik próbuje zainstalować aplikację lub gdy po aktualizacji systemu następuje ponowna weryfikacja aplikacji, system Android najpierw sprawdza atrybuty <uses-sdk> w pliku manifestu aplikacji i porównuje ich wartości z wartościami w swoim wewnętrznym interfejsie 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 równa lub mniejsza od liczby całkowitej na poziomie interfejsu API systemu. Jeśli nie zostanie zadeklarowany, system przyjmie, że aplikacja wymaga poziomu 1 interfejsu API.
• Jeśli atrybut android:maxSdkVersion jest zadeklarowany, jego wartość jest równa lub większa niż liczba całkowita poziomu interfejsu API systemu. Jeśli nie jest ona zadeklarowana, 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>deklarowany 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 Androida, że używa 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 nieistniejących interfejsów API. System zapobiega temu, nie pozwalając na instalację aplikacji, jeśli wymagany minimalny poziom interfejsu API jest wyższy niż wersja platformy na urządzeniu docelowym.

Uwagi dotyczące tworzenia

W następnych sekcjach znajdziesz informacje dotyczące poziomu interfejsu API, które musisz wziąć pod uwagę podczas tworzenia aplikacji.

Zgodność aplikacji wstecz

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

Ponieważ prawie wszystkie zmiany w interfejsie API frameworku są dodatkowymi, aplikacja na Androida opracowana przy użyciu dowolnej wersji interfejsu API, zgodnie z jej poziomem, jest zgodna z późniejszymi wersjami platformy Android i wyższymi poziomami interfejsu API. Aplikacja może działać we wszystkich nowszych wersjach platformy Android, z wyjątkiem pojedynczych przypadków, gdy korzysta ona z części interfejsu API, która później została z jakiegoś powodu usunięta.

Wsteczna zgodność 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 uruchomieniowego, ale nadal będzie mieć interfejs API i możliwości systemu, od których zależy aplikacja.

Zmiany poniżej interfejsu API, np. zmiany w podstawowym systemie, 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 systemu.

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

Zgodność wsteczna aplikacji

Aplikacje na Androida niekoniecznie są 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 frameworku, 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, gdy są uruchamiane na nowej platformie, a także w późniejszych wersjach tej platformy, zgodnie z poziomem interfejsu API. Wcześniejsze wersje tej platformy nie zawierają jednak nowych interfejsów API, więc aplikacje, które ich używają, nie mogą na nich działać.

Chociaż urządzenie z Androidem prawdopodobnie nie zostanie przywrócone do poprzedniej wersji platformy, należy pamiętać, że na rynku może być wiele urządzeń z wcześniejszymi wersjami tej platformy. Nawet w przypadku urządzeń, które otrzymują aktualizacje OTA, niektóre mogą się opóźniać lub nie otrzymywać aktualizacji przez długi czas.

Wybierz wersję platformy i poziom interfejsu API

Podczas tworzenia aplikacji wybierasz wersję platformy, dla której kompilujesz aplikację. Ogólnie rzecz biorąc, skompiluj aplikację na potrzeby najstarszej wersji platformy, którą może ona obsługiwać.

Aby określić najniższą możliwą wersję platformy, skompiluj aplikację z coraz niższym celem kompilacji. Po określeniu najniższej wersji utwórz urządzenie AVD, używając odpowiedniej wersji platformy i poziomu interfejsu API, a następnie przetestuj aplikację. Pamiętaj, aby w pliku manifestu aplikacji zadeklarować atrybut android:minSdkVersion i ustawić jego wartość na poziom API wersji platformy.

Zadeklaruj minimalny poziom 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 odpowiadający najnowszej wersji platformy. Dzięki temu użytkownicy będą mogli zainstalować Twoją aplikację tylko wtedy, gdy ich urządzenia będą działać na zgodnej wersji platformy Android. Dzięki temu będziesz mieć pewność, że aplikacja będzie działać prawidłowo na ich urządzeniach.

Jeśli Twoja aplikacja korzysta z 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 wcześniejszymi wersjami platformy. W tym drugim przypadku aplikacja ulega awarii w czasie wykonywania, gdy próbuje użyć interfejsów API, których nie ma w poprzednich wersjach.

Testowanie na wyższych poziomach interfejsu API

Po skompilowaniu aplikacji przetestuj ją na platformie określonej w atribute android:minSdkVersionaplikacji. Aby to zrobić, utwórz AVD, który używa wersji platformy wymaganej przez Twoją aplikację. Aby sprawdzić zgodność wsteczną, uruchom i przetestuj aplikację na wszystkich platformach, które korzystają z wyższego poziomu interfejsu API niż ten używany przez Twoją aplikację.

Pakiet SDK Androida zawiera kilka wersji platformy, w tym najnowszą, a także narzędzie do aktualizacji, za pomocą którego możesz pobrać inne wersje platformy w razie potrzeby.

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 urządzeniach wirtualnych znajdziesz w artykule Tworzenie urządzeń wirtualnych i zarządzanie nimi. Jeśli do testowania używasz urządzenia fizycznego, sprawdź, czy znasz poziom interfejsu API platformy Android, na której ono działa. Lista wersji platformy i ich poziomów interfejsu API znajduje się w tabeli w tym dokumencie.

Filtrowanie dokumentacji na podstawie poziomu interfejsu API

W lewym górnym rogu każdej strony w dokumentacji referencyjnej platformy Android znajduje się element sterujący „Poziom interfejsu API”. Za pomocą tego ustawienia możesz wyświetlać dokumentację tylko dla 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 w późniejszej wersji interfejsu API są wyszarzone, a ich zawartość jest zamaskowana, ponieważ nie są dostępne dla aplikacji.

Filtrowanie według poziomu interfejsu API w dokumentacji nie pozwala zobaczyć, co jest nowe lub zostało wprowadzone na poszczególnych poziomach interfejsu API. Umożliwia wyświetlanie całego interfejsu API powiązanego z danym poziomem interfejsu API, przy jednoczesnym wykluczeniu elementów interfejsu API wprowadzonych na późniejszych poziomach.

Aby wrócić do pełnej dokumentacji, u góry menu na poziomie interfejsu API kliknij REL. Domyślnie filtrowanie według poziomu interfejsu API jest wyłączone, dzięki czemu możesz wyświetlić pełny interfejs API frameworku niezależnie od poziomu interfejsu API.

Dokumentacja poszczególnych elementów interfejsu API określa poziom interfejsu API, na którym są one dostępne. Poziom interfejsu API pakietów i klas jest określony jako „Dodano w poziomie interfejsu API” w prawym górnym rogu obszaru treści na każdej stronie dokumentacji. Poziom interfejsu API w przypadku elementów klasy jest określony w ich szczegółowych opisach w nagłówkach po prawej stronie.