<uses-sdk>

Google Play używa atrybutów <uses-sdk> zadeklarowanych w pliku manifestu, aby filtrować aplikację i urządzeń, które nie spełniają wymagań dotyczących wersji platformy. Zanim ustawisz te atrybuty, upewnij się, że znasz filtry Google Play.

składnia:

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

zawarte w:

<manifest>

description:

Pozwala wyrazić zgodność aplikacji z co najmniej jedną wersją platformy Androida za pomocą liczby całkowitej na poziomie interfejsu API. Poziom interfejsu API wyrażony 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 swojej nazwie element ten służy do określenia poziomu interfejsu API, a nie numeru wersji pakietu SDK lub platformy Android. Poziom interfejsu API musi być zawsze jedną 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 lub suma wersji dur i moll.

Przeczytaj też dokument o obsłudze wersji 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 wartość domyślną „1”, co oznacza, że Twoja aplikacja jest zgodna ze wszystkimi wersjami Androida. Jeśli nie jest i nie zadeklarowano prawidłowego interfejsu minSdkVersion, aplikacja zainstalowana w systemie o niezgodnym poziomie interfejsu API ulega awarii w czasie działania, gdy próbuje uzyskać dostęp do niedostępnych interfejsów API. Dlatego w atrybucie minSdkVersion musisz zadeklarować odpowiedni poziom interfejsu API.

android:targetSdkVersion

Liczba całkowita określająca poziom interfejsu API, na który kierowana jest aplikacja. Jeśli zasada nie jest skonfigurowana, domyślną wartością jest minSdkVersion.

Ten atrybut informuje system, że został on przetestowany w porównaniu z wersją docelową. System nie włącza żadnych działań związanych ze zgodnością, aby zapewnić zgodność aplikacji z wersją docelową. Aplikacja nadal działa w starszych wersjach (do minSdkVersion).

W miarę rozwoju Androida z każdą nową wersją niektóre zachowania, a nawet wygląd mogą ulec zmianie. Jeśli jednak poziom interfejsu API platformy jest wyższy niż wersja zadeklarowana przez zasadę targetSdkVersion aplikacji, system może włączyć zachowania zgodności, aby aplikacja nadal działała zgodnie z oczekiwaniami. Aby wyłączyć takie zachowania zgodności, możesz określić właściwość targetSdkVersion, aby pasowała do poziomu interfejsu API platformy, na której działa.

Na przykład ustawienie tej wartości na „11” lub wyższej spowoduje, że system zastosuje domyślny motyw Holo do Twojej aplikacji na urządzeniach z Androidem 3.0 lub nowszym. Wyłączy też tryb zgodności ekranu działający na większych ekranach, ponieważ obsługa interfejsu API poziomu 11 domyślnie obsługuje większe ekrany.

System może włączyć wiele działań związanych ze zgodnością w zależności od wartości, jaką ustawisz dla tego atrybutu. Niektóre z tych zachowań są opisane w odpowiednich wersjach platformy w dokumentacji Build.VERSION_CODES.

Aby utrzymywać aplikację wraz z każdą wersją Androida, zwiększ wartość tego atrybutu, aby pasowała do najnowszego poziomu 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 ma działać aplikacja.

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

Aby pokazać, jak ten atrybut może wpłynąć na aplikację po aktualizacji systemu, przyjrzyjmy się temu przykładowi:

Aplikacja z deklaracją maxSdkVersion="5" w pliku manifestu została opublikowana w Google Play. Użytkownik, który korzysta z urządzenia z Androidem 1.6 (poziom interfejsu API 4) pobiera i instaluje aplikację. Po kilku tygodniach bezprzewodowa aktualizacja systemu do Androida 2.0 (poziom interfejsu API 5). Po zainstalowaniu aktualizacji system sprawdza maxSdkVersion aplikacji i pomyślnie weryfikuje ją ponownie.

Aplikacja działa normalnie. Po jakimś czasie urządzenie otrzyma 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ż poziom interfejsu API systemu (6) jest teraz wyższy niż maksymalny obsługiwany przez aplikację (5). System uniemożliwia wyświetlanie aplikacji użytkownikowi, co skutkuje usunięciem jej z urządzenia.

Ostrzeżenie: nie zalecamy zadeklarowania tego atrybutu. Po pierwsze, nie trzeba ustawiać tego atrybutu jako sposobu blokowania wdrożenia aplikacji na nowych wersjach platformy Androida w miarę ich udostępniania. Nowe wersje platformy z założenia są w pełni zgodne wstecznie. Twoja aplikacja działa prawidłowo w nowych wersjach, o ile używa tylko 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 na wyższy poziom interfejsu API. Większość urządzeń, na których prawdopodobnie zostanie zainstalowana Twoja aplikacja, będzie otrzymywać okresowe aktualizacje systemu bezprzewodowo. Zanim ustawisz ten atrybut, zastanów się nad ich wpływem na aplikację.

Wprowadzono: poziom API 4

Niektóre wersje Androida (oprócz Androida 2.0.1) nie sprawdzają ani nie wymuszają atrybutu maxSdkVersion podczas instalacji lub ponownej weryfikacji. Google Play nadal używa tego atrybutu jako filtra, jednak wyświetlając użytkownikom aplikacje dostępne do pobrania.

wprowadzone w:

Poziom interfejsu API 1

Co to jest poziom API?

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

Platforma Android udostępnia interfejs API platformy, za pomocą którego aplikacje mogą współdziałać z bazowym systemem Android. Składniki interfejsu API platformy:

• Podstawowy zestaw pakietów i klas
• Zestaw elementów i atrybutów XML do deklarowania pliku manifestu
• Zbiór elementów i atrybutów XML do deklarowania zasobów i uzyskiwania do nich dostępu
• Zbiór intencji.
• Zbiór uprawnień, których mogą żądać aplikacje, oraz instrukcje egzekwowania uprawnień obejmowane w systemie

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

Aktualizacje interfejsu Framework API mają zapewniać zgodność nowego interfejsu API z jego wcześniejszymi wersjami. Oznacza to, że większość zmian w interfejsie API się dodaje i wprowadza nowe lub zastępujące funkcje. W trakcie uaktualniania części interfejsu API starsze, zastąpione elementy są wycofywane, ale nie są usuwane, tak aby istniejące aplikacje mogły nadal z nich korzystać.

W bardzo nielicznych przypadkach fragmenty interfejsu API są modyfikowane lub usuwane. Zwykle jednak takie zmiany są potrzebne tylko do zapewnienia solidności interfejsu API oraz bezpieczeństwa aplikacji lub systemu. Pozostałe części interfejsu API z wcześniejszych wersji są przenoszone bez modyfikacji.

Interfejs API platformy Android dostarczany przez platformę Androida jest określany przy użyciu identyfikatora całkowitej o nazwie Poziom interfejsu API. Każda wersja platformy Androida obsługuje dokładnie 1 poziom interfejsu API, chociaż obsługa ta jest niejawna na wszystkich wcześniejszych poziomach (aż do poziomu 1). Pierwotna wersja platformy Android zapewniała interfejs API na poziomie 1. Kolejne wersje zwiększały ten poziom.

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

Zastosowania poziomu interfejsu API na Androidzie

Identyfikator poziomu interfejsu API odgrywa kluczową rolę w zapewnianiu najlepszej obsługi użytkownikom i deweloperom aplikacji:

• Pozwala platformie Androida opisywać maksymalną wersję interfejsu API platformy, którą obsługuje.
• Pozwala aplikacjom opisać wymaganą wersję interfejsu API platformy.
• Pozwala systemowi negocjować instalację aplikacji na urządzeniu użytkownika, tak aby nie były instalowane aplikacje niezgodne z wersją.

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

Aplikacje mogą korzystać z elementu manifestu udostępnianego przez interfejs API platformy <uses-sdk> do opisania minimalnego i maksymalnego poziomu interfejsu API, na którym mogą działać, a także preferowanego poziomu interfejsu API, który są obsługiwane przez te aplikacje. Ten element wyróżnia 3 główne atrybuty:

• android:minSdkVersion: minimalny poziom interfejsu API, na którym może działać aplikacja. Wartością domyślną jest „1”.
• android:targetSdkVersion: poziom interfejsu API, na którym ma działać aplikacja. W niektórych przypadkach pozwala to aplikacji używać elementów manifestu lub zachowań zdefiniowanych na docelowym poziomie interfejsu API, zamiast ograniczać się tylko do tych zdefiniowanych na 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, przeczytaj informacje o tym atrybucie na tej stronie.

Aby na przykład określić minimalny poziom interfejsu API systemu wymagany do uruchomienia aplikacji, zawiera ona 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 może działać aplikacja.

Gdy użytkownik próbuje zainstalować aplikację lub podczas ponownej weryfikacji aplikacji 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 umożliwia rozpoczęcie instalacji tylko wtedy, gdy są spełnione te warunki:

• Jeśli atrybut android:minSdkVersion został zadeklarowany, jego wartość jest mniejsza od liczby całkowitej systemu interfejsu API lub jej równa. Jeśli nie zostaną one zadeklarowane, system zakłada, że aplikacja wymaga interfejsu API na poziomie 1.
• Jeśli atrybut android:maxSdkVersion został zadeklarowany, jego wartość jest równa liczbie całkowitej systemu interfejsu API lub od niej większa. Jeśli nie zostanie zadeklarowana, system zakłada, że aplikacja nie ma maksymalnego poziomu interfejsu API. Przeczytaj opis tego atrybutu, aby dowiedzieć się, jak system go obsługuje.

Po zadeklarowaniu w pliku manifestu aplikacji element <uses-sdk> 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 wprowadzonych na określonym poziomie interfejsu API.

Jeśli aplikacja instaluje się na platformie o niższym poziomie interfejsu API, ulega awarii w czasie działania, gdy próbuje uzyskać dostęp do nieistniejących interfejsów API. System zapobiega takiemu wynikowi, nie zezwalając na instalację aplikacji, jeśli najniższy wymagany poziom interfejsu API jest wyższy niż wersja platformy na urządzeniu docelowym.

Kwestie związane z programowaniem

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

Zgodność z przekierowywaniem aplikacji

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

Prawie wszystkie zmiany w interfejsie API platformy są sumowane, dlatego aplikacja na Androida utworzona przy użyciu dowolnej wersji interfejsu API określona przez jej poziom API jest zgodna z przyszłymi wersjami platformy Androida i wyższymi poziomami API. Aplikacja może działać na wszystkich nowszych wersjach platformy Android z wyjątkiem od czasu do czasu, gdy korzysta ona z części interfejsu API, która z jakiegoś powodu została później usunięta.

Zgodność w przyszłości jest ważna, ponieważ wiele urządzeń z Androidem otrzymuje aktualizacje systemu bezprzewodowo (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 będzie działać w nowej wersji środowiska wykonawczego, ale która nadal ma interfejs API i funkcje systemowe, od których zależy Twoja aplikacja.

Zmiany poniżej interfejsu API, np. w samym systemie bazowym, mogą mieć wpływ na aplikację, gdy jest ona uruchomiona w nowym środowisku. Jako deweloper aplikacji musisz wiedzieć, jak aplikacja wygląda i działa w poszczególnych środowiskach systemowych.

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

Wsteczna zgodność aplikacji

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

Każda nowa wersja platformy Androida może zawierać nowe interfejsy API platformy, na przykład te, które dają aplikacjom dostęp do nowych funkcji platformy lub zastępują dotychczasowe części interfejsów API. Nowe interfejsy API są dostępne dla aplikacji działających na nowej platformie, a także podczas działania na nowszych wersjach platformy, zgodnie z poziomem interfejsu API. Ponieważ jednak wcześniejsze wersje platformy nie zawierają nowych interfejsów API, aplikacje korzystające z nich nie mogą działać na tych platformach.

Chociaż najprawdopodobniej nie przywrócimy wcześniejszej wersji platformy w przypadku urządzenia z Androidem, trzeba pamiętać, że na rynku prawdopodobnie będzie wiele urządzeń, na których działają wcześniejsze wersje platformy. Nawet urządzenia, które otrzymują aktualizacje OTA, mogą się opóźniać i nie otrzymać ich przez dłuższy czas.

Wybierz wersję platformy i poziom interfejsu API

Tworząc aplikację, wybierasz wersję platformy, na której kompilujesz ją. Ogólnie rzecz biorąc, należy skompilować aplikację z najniższą możliwą wersją platformy, jaką może ona obsługiwać.

Możesz określić najniższą możliwą wersję platformy, skompilując aplikację pod kątem kolejnych niższych wartości docelowych kompilacji. Po określeniu najniższej wersji utwórz AVD, używając odpowiedniej wersji platformy i poziomu interfejsu API, a potem w pełni przetestuj aplikację. Pamiętaj, aby zadeklarować atrybut android:minSdkVersion w pliku manifestu aplikacji i ustawić jego wartość na poziom interfejsu API wersji platformy.

Zadeklarowanie 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 API najnowszej wersji platformy. Dzięki temu użytkownicy będą mogli instalować Twoją aplikację tylko wtedy, gdy na ich urządzeniach jest zainstalowana zgodną wersję platformy Androida. Dzięki temu możesz 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 zadeklaruje 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órych nie ma w poprzednich wersjach.

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

Po skompilowaniu aplikacji przetestuj ją na platformie określonej w atrybucie android:minSdkVersion w jej atrybucie. W tym celu utwórz AVD korzystający z wersji platformy wymaganej przez aplikację. Dodatkowo, aby sprawdzić zgodność z przyszłością, uruchom i przetestuj aplikację na wszystkich platformach, które korzystają z wyższego poziomu interfejsu API niż ten używany przez aplikację.

Pakiet Android SDK zawiera wiele wersji platform, z których możesz korzystać, w tym najnowszą wersję, oraz narzędzie aktualizatora, którego możesz użyć do pobierania innych wersji platformy w razie potrzeby.

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

Aby uruchomić aplikację w emulatorze na różnych wersjach platformy, utwórz osobny plik AVD dla każdej wersji platformy, którą chcesz przetestować. Więcej informacji na temat AVD 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 Androida, na której działa. W tabeli w tym dokumencie znajdziesz listę wersji platformy i ich poziomów API.

Filtrowanie dokumentacji referencyjnej według poziomu interfejsu API

Strony z dokumentacją platformy Androida zawierają w lewym górnym rogu każdej strony element sterujący „Poziom interfejsu API”. Możesz użyć tego elementu sterującego, aby wyświetlić dokumentację tylko tych części interfejsu API, które są rzeczywiście dostępne dla Twojej aplikacji, na podstawie poziomu 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ą następnie wyszarzone, a ich zawartość jest maskowana, ponieważ nie są one dostępne dla aplikacji.

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

Aby wrócić do pełnej dokumentacji, wybierz REL u góry menu poziomu interfejsu API. Domyślnie filtrowanie na poziomie interfejsu API jest wyłączone, więc możesz wyświetlać pełny interfejs API platformy niezależnie od jego poziomu.

Dokumentacja poszczególnych elementów interfejsu API określa poziom API, na którym jest wprowadzany każdy element. Poziom interfejsu API pakietów i klas określa się jako „Dodano na poziomie interfejsu API” w prawym górnym rogu obszaru treści na każdej stronie dokumentacji. Poziom interfejsu API dla uczestników zajęć jest określony w szczegółowych nagłówkach opisu na prawym marginesie.