<uses-sdk>

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

zawarte w:

<manifest>

description:

Umożliwia określenie zgodności aplikacji z jedną lub wieloma wersjami platformy Android 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.

Pomimo swojej nazwy ten element służy do określania poziomu interfejsu API, a nie numeru wersji pakietu SDK czy platformy Androida. Poziom interfejsu API jest zawsze jedną liczbą całkowitą. Nie można uzyskać poziomu interfejsu API na podstawie powiązanego numeru wersji Androida. Na przykład to nie to samo co wersja główna czy suma wersji głównej i podrzędnej.

Przeczytaj też dokument na temat obsługi 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 aplikacja jest zgodna ze wszystkimi wersjami Androida. Jeśli nie jest i nie zostanie zadeklarowana prawidłowa minSdkVersion, to po zainstalowaniu w systemie o niezgodnym poziomie interfejsu API aplikacja ulega awarii w czasie działania przy próbie uzyskania dostępu do niedostępnych interfejsów API. Dlatego pamiętaj, aby zadeklarować w atrybucie minSdkVersion 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, wartość domyślna jest równa wartości podanej w zasadzie minSdkVersion.

Ten atrybut informuje system, który został przez Ciebie przetestowany pod kątem wersji docelowej, i nie umożliwia żadnych działań związanych ze zgodnością, aby zachować zgodność aplikacji z wersją docelową w przyszłości. Aplikacja może nadal działać w starszych wersjach (do minSdkVersion).

Wraz z każdą nową wersją Androida niektóre zachowania, a nawet wygląd mogą ulec zmianie. 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 nadal działała zgodnie z oczekiwaniami. Możesz wyłączyć takie zachowania zgodności, określając właściwość targetSdkVersion tak, aby pasowała do poziomu interfejsu API platformy, na której działa.

Na przykład ustawienie tej wartości na „11” lub wyższą umożliwia systemowi zastosowanie domyślnego motywu Holo w przypadku Androida w wersji 3.0 lub nowszej oraz wyłączenie trybu zgodności ekranu na większych ekranach, ponieważ obsługa poziomu 11 interfejsu API domyślnie obsługuje większe ekrany.

System może włączyć wiele działań dotyczących zgodności na podstawie wartości ustawionej dla danego atrybutu. Kilka z tych zachowań zostało opisanych przez odpowiednie wersje platformy w dokumentacji Build.VERSION_CODES.

Aby utrzymywać aplikację wraz z każdą wersją Androida, zwiększ wartość tego atrybutu, tak aby pasowała do najnowszego poziomu interfejsu API, a następnie dokładnie przetestuj aplikację na odpowiedniej wersji platformy.

Wprowadzono w: API poziomu 4

android:maxSdkVersion

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

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

Aby pokazać, jak ten atrybut może wpływać na aplikację po aktualizacjach systemu, zapoznaj się z tym przykładem:

Aplikacja z deklaracją maxSdkVersion="5" w pliku manifestu została opublikowana w Google Play. Użytkownik, którego urządzenie korzysta z Androida 1.6 (poziom interfejsu API 4), pobiera i instaluje aplikację. Po kilku tygodniach system otrzymuje bezprzewodową aktualizację do Androida 2.0 (poziom interfejsu API 5). Po zainstalowaniu aktualizacji system sprawdzi maxSdkVersion aplikacji i ponownie ją sprawdzi.

Aplikacja działa jak zwykle. Jednak jakiś czas później 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 weryfikować aplikacji, ponieważ poziom interfejsu API systemu (6) jest teraz wyższy niż maksymalny obsługiwany przez aplikację (5). System zapobiega wyświetlaniu aplikacji dla użytkownika, co powoduje usunięcie jej z urządzenia.

Ostrzeżenie: nie zalecamy deklarowania tego atrybutu. Po pierwsze, nie musisz ustawiać tego atrybutu jako sposobu na zablokowanie wdrażania aplikacji w nowych wersjach platformy Androida, gdy tylko zostaną udostępnione. Z założenia 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 dla programistów. Po drugie, w niektórych przypadkach zadeklarowanie tego atrybutu może spowodować usunięcie aplikacji z urządzeń użytkowników po zaktualizowaniu systemu do wyższego poziomu interfejsu API. Większość urządzeń, na których Twoja aplikacja będzie prawdopodobnie instalowana, otrzymuje okresowe aktualizacje systemu bezprzewodowo, dlatego zanim ustawisz ten atrybut, weź pod uwagę ich wpływ na aplikację.

Wprowadzono w: API poziomu 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 korzysta z tego atrybutu jako filtra, ale gdy przedstawia użytkownikom aplikacje dostępne do pobrania.

wprowadzone w:

Poziom API 1

Co to jest poziom API?

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

Platforma Android udostępnia platformę API, za pomocą której aplikacje mogą komunikować się z bazowym systemem Android. Interfejs API platformy składa się z tych elementów:

• Podstawowy zestaw pakietów i klas
• Zestaw elementów XML i atrybutów do zadeklarowania pliku manifestu
• Zestaw elementów XML i atrybutów do deklarowania zasobów i uzyskiwania do nich dostępu
• zbiór intencji,
• Zestaw uprawnień, o które mogą prosić aplikacje, a także elementów wymuszających uprawnienia w systemie

Każda kolejna wersja platformy Androida może zawierać aktualizacje udostępnianego przez nią interfejsu API platformy aplikacji na Androida.

Aktualizacje interfejsu Framework API mają na celu zapewnienie jego zgodności z wcześniejszymi wersjami tego interfejsu. Oznacza to, że większość zmian w interfejsie API ma sumę 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, aby istniejące aplikacje nadal mogły z nich korzystać.

W bardzo niewielu przypadkach części interfejsu API są modyfikowane lub usuwane, ale zwykle takie zmiany są zwykle potrzebne tylko do zapewnienia stabilności interfejsu API oraz bezpieczeństwa aplikacji lub systemu. Wszystkie inne części interfejsu API z wcześniejszych wersji zostaną przeniesione bez wprowadzania zmian.

Interfejs API platformy Androida jest określany za pomocą identyfikatora całkowitego o nazwie poziom interfejsu API. Każda wersja platformy Androida obsługuje dokładnie jeden poziom interfejsu API, ale jest to obsługiwane na wszystkich wcześniejszych poziomach API (do poziomu 1). Pierwsza wersja platformy Androida zapewniała poziom API 1. W kolejnych wersjach ten poziom wzrósł.

W tabeli poniżej znajdziesz 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 użytkownikom i deweloperom aplikacji najlepszych możliwych rozwiązań:

• Umożliwia platformie Androida opisywanie maksymalnej wersji interfejsu API, jaką obsługuje.
• Umożliwia aplikacjom opisywanie wymaganej wersji interfejsu Framework API.
• Dzięki temu system negocjuje instalację aplikacji na urządzeniu użytkownika, dzięki czemu nie będą instalowane aplikacje niezgodne z wersjami.

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

Aplikacje mogą używać elementu manifestu udostępnionego przez interfejs API platformy <uses-sdk>, aby opisać minimalny i maksymalny poziom interfejsu API, na którym mogą działać, a także preferowany poziom API, który jest dla nich obsługiwany. Ten element ma 3 kluczowe atrybuty:

• android:minSdkVersion: minimalny poziom interfejsu API, na którym można uruchomić aplikację. Wartość domyślna to „1”.
• android:targetSdkVersion: poziom interfejsu API, na którym została zaprojektowana aplikacja. W niektórych przypadkach pozwala to aplikacji używać elementów lub zachowań zdefiniowanych na docelowym poziomie interfejsu API, a nie tylko tych określonych dla minimalnego poziomu interfejsu API.
• android:maxSdkVersion: maksymalny poziom interfejsu API, na którym można uruchomić aplikację. Ważne: zanim użyjesz tego atrybutu, przeczytaj informacje o nim na tej stronie.

Aby na przykład określić minimalny systemowy poziom interfejsu API wymagany przez aplikację do uruchomienia, aplikacja powinna umieścić 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żna uruchomić aplikację.

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

• Jeśli atrybut android:minSdkVersion jest zadeklarowany, jego wartość jest mniejsza od liczby całkowitej na poziomie interfejsu API systemu lub jej równa. Jeśli nie zostanie zadeklarowany, system przyjmie, że aplikacja wymaga interfejsu API poziomu 1.
• Jeśli atrybut android:maxSdkVersion jest zadeklarowany, jego wartość jest równa lub większa od liczby całkowitej na poziomie interfejsu API systemu. Jeśli nie zostanie zadeklarowany, system zakłada, że aplikacja nie ma maksymalnego poziomu interfejsu API. Przeczytaj opis tego atrybutu, aby dowiedzieć się więcej o tym, 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 deklarowania poziomu interfejsu API w aplikacji 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 w jakiś sposób instaluje się na platformie o niższym poziomie interfejsu API, podczas próby uzyskania dostępu do nieistniejących interfejsów API ulega awarii w czasie działania. System zapobiega temu efektowi, nie zezwalając na instalację aplikacji, jeśli wymagany najniższy poziom interfejsu API jest wyższy niż w wersji platformy na urządzeniu docelowym.

Uwagi dotyczące programowania

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

Zgodność z przekazywaną aplikacją

Aplikacje na Androida są zazwyczaj kompatybilne z nowymi wersjami platformy Androida.

Ponieważ niemal wszystkie zmiany w interfejsie API platformy się sumują, aplikacja na Androida opracowana przy użyciu dowolnej wersji interfejsu API określonej przez jej poziom jest zgodna z nowszymi wersjami platformy Android i wyższymi poziomami interfejsu API. Aplikacja może działać we wszystkich nowszych wersjach platformy Androida, z wyjątkiem rzadkich przypadków, gdy aplikacja używa części interfejsu API, która z jakiegoś powodu zostaje później usunięta.

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

Zmiany pod interfejsem API, takie jak zmiany w systemie bazowym, mogą mieć wpływ na aplikację uruchamianą w nowym środowisku. 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ć w AVD, aby przetestować aplikację.

Zgodność wsteczna aplikacji

Aplikacje na Androida nie muszą być zgodne wstecznie z wersjami platformy Androida starszymi od wersji, na 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ą istniejące części API. Nowe interfejsy API są dostępne dla aplikacji, gdy działają na nowej platformie, a także w przypadku działania w późniejszych wersjach platformy, zgodnie z poziomem interfejsu API. Jednak wcześniejsze wersje platformy nie zawierają nowych interfejsów API, dlatego aplikacje korzystające z tych interfejsów nie mogą na nich działać.

Choć urządzenia z Androidem nie zostaną prawdopodobnie przekształcone do poprzedniej wersji platformy, trzeba pamiętać, że prawdopodobnie w tej dziedzinie jest wiele urządzeń, które obsługują wcześniejsze wersje platformy. Nawet w przypadku urządzeń otrzymujących aktualizacje OTA niektóre z nich mogą działać z opóźnieniem, przez co mogą nie otrzymać aktualizacji przez dłuższy czas.

Wybierz wersję platformy i poziom interfejsu API

Tworząc aplikację, wybierasz wersję platformy, na podstawie której ją kompilujesz. Ogólnie rzecz biorąc, skompiluj aplikację na najniższej możliwej wersji platformy, którą obsługuje Twoja aplikacja.

Aby określić najniższą możliwą wersję platformy, skompiluj aplikację na podstawie stopniowo niższego poziomu celów kompilacji. Po określeniu najniższej wersji utwórz AVD za pomocą odpowiedniej wersji platformy i poziomu interfejsu API, a następnie w pełni przetestuj aplikację. Pamiętaj, aby w pliku manifestu aplikacji zadeklarować atrybut android:minSdkVersion i ustawić jego wartość na poziomie interfejsu API danej 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 API najnowszej wersji platformy. Dzięki temu użytkownicy będą mogli zainstalować Twoją aplikację tylko wtedy, gdy ich urządzenia mają kompatybilną wersję platformy Androida. Dzięki temu możesz zapewnić prawidłowe działanie aplikacji na swoich urządzeniach.

Jeśli Twoja 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 drugim przypadku, gdy próbuje ona użyć interfejsów API, których we wcześniejszych wersjach występuje, aplikacja ulega awarii.

Testowanie z wykorzystaniem wyższych poziomów interfejsu API

Gdy skompilujesz aplikację, przetestuj ją na platformie podanej w atrybucie android:minSdkVersion aplikacji. Aby to zrobić, utwórz narzędzie AVD korzystające z wersji platformy wymaganej przez Twoją aplikację. Dodatkowo, aby sprawdzić zgodność do przodu, uruchom i przetestuj aplikację na wszystkich platformach korzystających z wyższego poziomu interfejsu API niż Twoja aplikacja.

Pakiet Android SDK zawiera wiele dostępnych wersji platformy, w tym najnowszą wersję. Zawiera też narzędzie aktualizatora, za pomocą którego można w razie potrzeby pobrać inne wersje platformy.

Aby uzyskać dostęp do aktualizatora, użyj narzędzia wiersza poleceń android znajdującego się w katalogu <sdk>/tools. Aktualizator pakietu SDK możesz uruchomić, wykonując android sdk. Możesz też dwukrotnie kliknąć 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 fizycznego urządzenia, upewnij się, że znasz poziom API platformy Androida, na której działa. Listę wersji platform i ich poziomów API znajdziesz w tabeli w tym dokumencie.

Filtrowanie dokumentacji referencyjnej według poziomu interfejsu API

Strony z dokumentacją platformy Androida oferują opcję „Poziom interfejsu API” w lewym górnym rogu każdej strony. Za pomocą tej opcji możesz wyświetlać dokumentację tylko tych części interfejsu API, które są rzeczywiście dostępne dla Twojej aplikacji, na podstawie poziomu interfejsu API podanego w atrybucie android:minSdkVersion w pliku manifestu.

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

Filtrowanie w dokumentacji według poziomu interfejsu API nie daje wglądu w nowe ani wprowadzone elementy na poszczególnych poziomach. Pozwala wyświetlić cały interfejs API powiązany z danym poziomem API i jednocześnie wykluczyć elementy interfejsu API wprowadzone 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, dzięki czemu można wyświetlić pełną treść interfejsu API platformy niezależnie od jego poziomu.

Dokumentacja referencyjna dotycząca poszczególnych elementów interfejsu API określa poziom interfejsu API, na którym wprowadzany jest każdy element. Poziom interfejsu API pakietów i klas jest oznaczony jako „Dodany na poziomie interfejsu API” w prawym górnym rogu obszaru treści na każdej stronie dokumentacji. Poziom interfejsu API członków klas jest określony w szczegółowych nagłówkach opisu na prawym marginesie.