<uses-sdk>

Google Play verwendet die im App-Manifest deklarierten <uses-sdk>-Attribute, um Ihre App auf Geräten herauszufiltern, die die Anforderungen an die Plattformversion nicht erfüllen. Bevor Sie diese Attribute festlegen, sollten Sie sich mit Google Play-Filtern vertraut machen.

Syntax:

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

Enthalten in:

<manifest>

description:

Ermöglicht es Ihnen, die Kompatibilität einer Anwendung mit einer oder mehreren Versionen der Android-Plattform mithilfe einer API-Level-Ganzzahl anzugeben. Das von einer Anwendung angegebene API-Level wird mit dem API-Level eines bestimmten Android-Systems verglichen, das je nach Android-Gerät variieren kann.

Trotz des Namens wird mit diesem Element das API-Level und nicht die Versionsnummer des Software Development Kit (SDK) oder der Android-Plattform angegeben. Die API-Ebene ist immer eine einzelne Ganzzahl. Das API-Level kann nicht aus der zugehörigen Android-Versionsnummer abgeleitet werden. Sie ist beispielsweise nicht dasselbe wie die Hauptversion oder die Summe der Haupt- und Nebenversionen.

Es ist nicht möglich, anzugeben, dass eine App entweder auf eine Neben-SDK-Version ausgerichtet ist oder diese erfordert.

Lesen Sie auch das Dokument zur Versionsverwaltung Ihrer Anwendungen.

Attribute:

android:minSdkVersion

Eine Ganzzahl, die das Mindest-API-Level angibt, das für die Ausführung der Anwendung erforderlich ist. Das Android-System verhindert die Installation der Anwendung, wenn das API-Level des Systems niedriger ist als der in diesem Attribut angegebene Wert. Dieses Attribut muss immer deklariert werden.

Achtung:Wenn Sie dieses Attribut nicht deklarieren, geht das System von einem Standardwert von „1“ aus. Das bedeutet, dass Ihre Anwendung mit allen Android-Versionen kompatibel ist. Wenn dies nicht der Fall ist und Sie die richtige minSdkVersion nicht deklariert haben, stürzt die Anwendung bei der Installation auf einem System mit einem inkompatiblen API-Level während der Laufzeit ab, wenn versucht wird, auf die nicht verfügbaren APIs zuzugreifen. Geben Sie daher unbedingt das entsprechende API-Level im Attribut minSdkVersion an.

android:targetSdkVersion

Eine Ganzzahl, die das API-Level angibt, auf das die Anwendung ausgerichtet ist. Wenn nichts anderes festgelegt wird, entspricht der Standardwert dem Wert, der für minSdkVersion angegeben wurde.

Dieses Attribut informiert das System darüber, dass Sie die App mit der Zielversion getestet haben. Das System aktiviert keine Kompatibilitätsfunktionen, um die Vorwärtskompatibilität Ihrer App mit der Zielversion aufrechtzuerhalten. Die Anwendung kann weiterhin auf niedrigeren Versionen (bis zu minSdkVersion) ausgeführt werden.

Da sich Android mit jeder Version weiterentwickelt, ändern sich eventuell auch die Funktionsweise und das Aussehen. Wenn das API-Level der Plattform jedoch höher ist als die von Ihrer App deklarierte Version von targetSdkVersion, kann das System Kompatibilitätsverhalten aktivieren, damit Ihre App weiterhin wie erwartet funktioniert. Sie können solche Kompatibilitätsverhalten deaktivieren, indem Sie targetSdkVersion so angeben, dass es dem API-Level der Plattform entspricht, auf der die App ausgeführt wird.

Wenn Sie diesen Wert beispielsweise auf „11“ oder höher festlegen, wendet das System das Holo-Standarddesign auf Ihre App an, wenn sie unter Android 3.0 oder höher ausgeführt wird. Außerdem wird der Bildschirmkompatibilitätsmodus deaktiviert, wenn die App auf größeren Bildschirmen ausgeführt wird, da die Unterstützung für API-Level 11 implizit auch die Unterstützung für größere Bildschirme umfasst.

Je nach dem Wert, den Sie für dieses Attribut festlegen, kann das System viele verschiedene Kompatibilitätsverhalten aktivieren. Einige dieser Verhaltensweisen werden in der Build.VERSION_CODES-Referenz durch die entsprechenden Plattformversionen beschrieben.

Um Ihre Anwendung mit jeder Android-Version auf dem neuesten Stand zu halten, erhöhen Sie den Wert dieses Attributs entsprechend dem neuesten API-Level und testen Sie Ihre Anwendung dann gründlich auf der entsprechenden Plattformversion.

Eingeführt in: API-Level 4

android:maxSdkVersion

Eine Ganzzahl, die das maximale API-Level angibt, für das die Anwendung entwickelt wurde.

In Android 1.5, 1.6, 2.0 und 2.0.1 prüft das System den Wert dieses Attributs bei der Installation einer Anwendung und bei der erneuten Validierung der Anwendung nach einem Systemupdate. In beiden Fällen lässt das System die Installation der Anwendung nicht zu, wenn das Attribut maxSdkVersion der Anwendung niedriger ist als die vom System selbst verwendete API-Ebene. Im Falle einer erneuten Validierung nach einem Systemupdate wird Ihre Anwendung effektiv vom Gerät entfernt.

Das folgende Beispiel veranschaulicht, wie sich dieses Attribut nach Systemupdates auf Ihre Anwendung auswirken kann:

Eine Anwendung, in deren Manifest maxSdkVersion="5" deklariert ist, wird bei Google Play veröffentlicht. Ein Nutzer, auf dessen Gerät Android 1.6 (API-Level 4) ausgeführt wird, lädt die App herunter und installiert sie. Nach einigen Wochen erhält der Nutzer ein Over-the-Air-Systemupdate auf Android 2.0 (API-Level 5). Nachdem das Update installiert wurde, prüft das System die maxSdkVersion der Anwendung und validiert sie noch einmal.

Die Anwendung funktioniert wie gewohnt. Einige Zeit später erhält das Gerät jedoch ein weiteres Systemupdate, diesmal auf Android 2.0.1 (API-Level 6). Nach dem Update kann das System die Anwendung nicht mehr neu validieren, da das API‑Level des Systems (6) jetzt höher ist als das von der Anwendung maximal unterstützte API‑Level (5). Das System verhindert, dass die Anwendung für den Nutzer sichtbar ist, und entfernt sie damit vom Gerät.

Warnung:Wir raten davon ab, dieses Attribut zu deklarieren. Zunächst einmal ist es nicht erforderlich, das Attribut festzulegen, um die Bereitstellung Ihrer Anwendung auf neuen Versionen der Android-Plattform zu blockieren, wenn diese veröffentlicht werden. Neue Versionen der Plattform sind standardmäßig vollständig abwärtskompatibel. Ihre Anwendung funktioniert auch mit neuen Versionen einwandfrei, sofern sie nur Standard-APIs verwendet und die Best Practices für die Entwicklung beachtet. Zweitens kann die Deklaration des Attributs in einigen Fällen dazu führen, dass Ihre Anwendung nach einem Systemupdate auf ein höheres API-Level von den Geräten der Nutzer entfernt wird. Die meisten Geräte, auf denen Ihre Anwendung wahrscheinlich installiert wird, erhalten regelmäßig Systemupdates über das Mobilfunknetz. Berücksichtigen Sie daher die Auswirkungen auf Ihre Anwendung, bevor Sie dieses Attribut festlegen.

Eingeführt in: API-Level 4

Bei einigen Versionen von Android (über Android 2.0.1 hinaus) wird das Attribut maxSdkVersion während der Installation oder erneuten Validierung nicht geprüft oder erzwungen. Google Play verwendet das Attribut weiterhin als Filter, wenn Nutzern zum Download verfügbare Anwendungen präsentiert werden.

Eingeführt in:

API‑Level 1

Was ist das API-Level?

Das API-Level ist ein ganzzahliger Wert, der die von einer Version der Android-Plattform angebotene Framework-API-Revision eindeutig identifiziert.

Die Android-Plattform bietet eine Framework-API, mit der Anwendungen mit dem zugrunde liegenden Android-System interagieren können. Die Framework-API besteht aus:

• Ein Kernsatz von Paketen und Klassen
• Eine Reihe von XML-Elementen und ‑Attributen zum Deklarieren einer Manifestdatei
• Eine Reihe von XML-Elementen und ‑Attributen zum Deklarieren und Zugreifen auf Ressourcen
• Eine Reihe von Intents
• Eine Reihe von Berechtigungen, die von Anwendungen angefordert werden können, sowie Berechtigungsdurchsetzungen, die im System enthalten sind

Jede nachfolgende Version der Android-Plattform kann Aktualisierungen der API des Android-Anwendungsframeworks enthalten.

Updates der Framework-API sind so konzipiert, dass die neue API mit früheren Versionen der API kompatibel bleibt. Die meisten Änderungen an der API sind additiv und führen neue oder Ersatzfunktionen ein. Wenn Teile der API aktualisiert werden, werden die älteren, ersetzten Teile eingestellt, aber nicht entfernt, damit bestehende Anwendungen sie weiterhin verwenden können.

In sehr wenigen Fällen werden Teile der API geändert oder entfernt. Solche Änderungen sind in der Regel jedoch nur erforderlich, um die Robustheit der API und die Sicherheit von Anwendungen oder Systemen zu gewährleisten. Alle anderen API-Teile aus früheren Revisionen werden unverändert übernommen.

Die Framework-API, die von einer Android-Plattform bereitgestellt wird, wird mit einer Ganzzahl-ID namens API-Ebene angegeben. Jede Android-Plattformversion unterstützt genau ein API-Level. Die Unterstützung für alle früheren API-Levels (bis API-Level 1) ist jedoch implizit. Die erste Version der Android-Plattform hatte API-Level 1. Bei nachfolgenden Versionen wurde das API-Level erhöht.

In der folgenden Tabelle ist die API-Ebene angegeben, die von den einzelnen Versionen der Android-Plattform unterstützt wird. Informationen zur relativen Anzahl von Geräten, auf denen die einzelnen Versionen ausgeführt werden, finden Sie im Verteilungs-Dashboard.

Verwendung des API‑Levels in Android

Die API-Level-Kennung spielt eine wichtige Rolle, um Nutzern und Anwendungsentwicklern die bestmögliche Erfahrung zu bieten:

• Damit kann die Android-Plattform die maximale Framework-API-Revision beschreiben, die sie unterstützt.
• Damit können Anwendungen die erforderliche Framework-API-Version angeben.
• Das System kann so die Installation von Anwendungen auf dem Gerät des Nutzers aushandeln, damit keine versionsinkompatiblen Anwendungen installiert werden.

Jede Android-Plattformversion speichert ihre API-Level-Kennung intern im Android-System.

Anwendungen können ein vom Framework bereitgestelltes Manifestelement – <uses-sdk> – verwenden, um die minimalen und maximalen API-Levels zu beschreiben, unter denen sie ausgeführt werden können, sowie den bevorzugten API-Level, für den sie entwickelt wurden. Das Element bietet drei wichtige Attribute:

• android:minSdkVersion: Das Mindest-API-Level, auf dem die Anwendung ausgeführt werden kann. Der Standardwert ist „1“.
• android:targetSdkVersion: Die API-Ebene, für die die Anwendung entwickelt wurde. In einigen Fällen kann die Anwendung dadurch Manifestelemente oder Verhaltensweisen verwenden, die in der Ziel-API-Ebene definiert sind, anstatt nur auf die für die Mindest-API-Ebene definierten Elemente beschränkt zu sein.
• android:maxSdkVersion: Das maximale API-Level, auf dem die Anwendung ausgeführt werden kann. Wichtig:Lesen Sie die Informationen zu diesem Attribut auf dieser Seite, bevor Sie es verwenden.

Wenn Sie beispielsweise die Mindestsystem-API-Ebene angeben möchten, die eine Anwendung zum Ausführen benötigt, enthält die Anwendung in ihrem Manifest ein <uses-sdk>-Element mit einem android:minSdkVersion-Attribut. Der Wert von android:minSdkVersion ist die Ganzzahl, die dem API-Level der frühesten Version der Android-Plattform entspricht, unter der die Anwendung ausgeführt werden kann.

Wenn der Nutzer versucht, eine Anwendung zu installieren, oder wenn eine Anwendung nach einem Systemupdate neu validiert wird, prüft das Android-System zuerst die <uses-sdk>-Attribute im Manifest der Anwendung und vergleicht die Werte mit dem eigenen internen API-Level. Das System lässt die Installation nur beginnen, wenn diese Bedingungen erfüllt sind:

• Wenn ein android:minSdkVersion-Attribut deklariert wird, ist sein Wert kleiner als oder gleich der Ganzzahl des API‑Levels des Systems. Wenn nicht deklariert, geht das System davon aus, dass die Anwendung API‑Level 1 erfordert.
• Wenn ein android:maxSdkVersion-Attribut deklariert wird, ist sein Wert gleich oder größer als die Ganzzahl des API-Levels des Systems. Wenn nicht deklariert, geht das System davon aus, dass die Anwendung kein maximales API-Level hat. Weitere Informationen zur Verarbeitung dieses Attributs durch das System finden Sie in der Beschreibung des Attributs.

Wenn ein <uses-sdk>-Element im Manifest einer Anwendung deklariert wird, kann es so aussehen:

<manifest>
  <uses-sdk android:minSdkVersion="5" />
  ...
</manifest>

Der Hauptgrund dafür, dass eine Anwendung ein API-Level in android:minSdkVersion deklariert, besteht darin, dem Android-System mitzuteilen, dass sie APIs verwendet, die im angegebenen API-Level eingeführt wurden.

Wenn die Anwendung auf einer Plattform mit einem niedrigeren API-Level installiert wird, stürzt sie zur Laufzeit ab, wenn sie versucht, auf nicht vorhandene APIs zuzugreifen. Das System verhindert dies, indem es die Installation der Anwendung verhindert, wenn der niedrigste erforderliche API-Level höher ist als der der Plattformversion auf dem Zielgerät.

Überlegungen zur Entwicklung

In den folgenden Abschnitten finden Sie Informationen zum API-Level, die Sie bei der Entwicklung Ihrer Anwendung berücksichtigen müssen.

Vorwärtskompatibilität von Anwendungen

Android-Anwendungen sind in der Regel mit neuen Versionen der Android-Plattform abwärtskompatibel.

Da fast alle Änderungen an der Framework-API additiv sind, ist eine Android-Anwendung, die mit einer bestimmten Version der API entwickelt wurde (angegeben durch den API-Level), mit späteren Versionen der Android-Plattform und höheren API-Levels vorwärtskompatibel. Die Anwendung kann auf allen späteren Versionen der Android-Plattform ausgeführt werden, außer in Einzelfällen, in denen die Anwendung einen Teil der API verwendet, der später aus irgendeinem Grund entfernt wird.

Die Vorwärtskompatibilität ist wichtig, da viele Android-Geräte OTA-Systemupdates (Over-the-Air) erhalten. Der Nutzer installiert Ihre Anwendung und verwendet sie erfolgreich. Später erhält er ein OTA-Update auf eine neue Version der Android-Plattform. Nach der Installation des Updates wird Ihre Anwendung in einer neuen Laufzeitversion der Umgebung ausgeführt, die jedoch weiterhin die API- und Systemfunktionen bietet, von denen Ihre Anwendung abhängt.

Änderungen unterhalb der API, z. B. im zugrunde liegenden System selbst, können sich auf Ihre Anwendung auswirken, wenn sie in der neuen Umgebung ausgeführt wird. Als Anwendungsentwickler ist es wichtig, dass Sie wissen, wie die Anwendung in den einzelnen Systemumgebungen aussieht und sich verhält.

Das Android SDK enthält mehrere Plattformen, die Sie herunterladen können, um Ihre Anwendung auf verschiedenen Versionen der Android-Plattform zu testen. Jede Plattform enthält ein kompatibles System-Image, das Sie in einem AVD ausführen können, um Ihre Anwendung zu testen.

Abwärtskompatibilität von Anwendungen

Android-Anwendungen sind nicht unbedingt abwärtskompatibel mit Android-Plattformversionen, die älter sind als die Version, für die sie kompiliert wurden.

Jede neue Version der Android-Plattform kann neue Framework-APIs enthalten, z. B. solche, die Anwendungen Zugriff auf neue Plattformfunktionen ermöglichen oder vorhandene API-Teile ersetzen. Die neuen APIs sind für Anwendungen verfügbar, wenn sie auf der neuen Plattform und auch auf späteren Versionen der Plattform ausgeführt werden, wie durch das API-Level angegeben. Da frühere Versionen der Plattform die neuen APIs jedoch nicht enthalten, können Anwendungen, die die neuen APIs verwenden, nicht auf diesen Plattformen ausgeführt werden.

Es ist zwar unwahrscheinlich, dass ein Android-Gerät auf eine frühere Version der Plattform zurückgesetzt wird, aber es ist wichtig zu wissen, dass es wahrscheinlich viele Geräte gibt, auf denen ältere Versionen der Plattform ausgeführt werden. Auch bei Geräten, die OTA-Updates erhalten, kann es zu Verzögerungen kommen und es kann eine Weile dauern, bis ein Update verfügbar ist.

Plattformversion und API-Level auswählen

Bei der Entwicklung Ihrer Anwendung wählen Sie die Plattformversion aus, für die die Anwendung kompiliert wird. Kompilieren Sie Ihre Anwendung im Allgemeinen für die niedrigstmögliche Version der Plattform, die Ihre Anwendung unterstützen kann.

Sie können die niedrigste mögliche Plattformversion ermitteln, indem Sie die Anwendung mit immer niedrigeren Build-Zielen kompilieren. Nachdem Sie die niedrigste Version ermittelt haben, erstellen Sie ein AVD mit der entsprechenden Plattformversion und dem entsprechenden API-Level und testen Sie Ihre Anwendung vollständig. Achten Sie darauf, dass Sie im Manifest der Anwendung ein android:minSdkVersion-Attribut deklarieren und dessen Wert auf das API-Level der Plattformversion festlegen.

Mindest-API-Level deklarieren

Wenn Sie eine Anwendung entwickeln, die APIs oder Systemfunktionen der neuesten Plattformversion verwendet, legen Sie das Attribut android:minSdkVersion auf das API-Level der neuesten Plattformversion fest. So können Nutzer Ihre App nur installieren, wenn auf ihren Geräten eine kompatible Version der Android-Plattform ausgeführt wird. So können Sie sicherstellen, dass Ihre Anwendung auf ihren Geräten ordnungsgemäß funktioniert.

Wenn in Ihrer Anwendung APIs verwendet werden, die in der neuesten Plattformversion eingeführt wurden, aber kein android:minSdkVersion-Attribut deklariert wird, funktioniert sie auf Geräten mit der neuesten Version der Plattform ordnungsgemäß, nicht jedoch auf Geräten mit älteren Versionen der Plattform. Im letzteren Fall stürzt die Anwendung zur Laufzeit ab, wenn sie versucht, APIs zu verwenden, die in den früheren Versionen nicht vorhanden sind.

Mit höheren API-Levels testen

Nachdem Sie Ihre Anwendung kompiliert haben, müssen Sie sie auf der Plattform testen, die im Attribut android:minSdkVersion der Anwendung angegeben ist. Erstellen Sie dazu ein AVD, das die von Ihrer Anwendung benötigte Plattformversion verwendet. Um die Vorwärtskompatibilität zu prüfen, sollten Sie die Anwendung außerdem auf allen Plattformen ausführen und testen, die ein höheres API-Level als das von Ihrer Anwendung verwendete API-Level verwenden.

Das Android SDK enthält mehrere Plattformversionen, die Sie verwenden können, einschließlich der neuesten Version. Außerdem ist ein Updater-Tool enthalten, mit dem Sie bei Bedarf andere Plattformversionen herunterladen können.

Verwenden Sie das android-Befehlszeilentool im Verzeichnis <sdk>/tools, um auf das Updater zuzugreifen. Sie können das SDK-Aktualisierungsprogramm mit dem Befehl android sdk starten. Sie können auch doppelt auf die Datei android.bat (Windows) oder android (OS X/Linux) klicken.

Wenn Sie Ihre Anwendung im Emulator mit verschiedenen Plattformversionen ausführen möchten, erstellen Sie für jede Plattformversion, die Sie testen möchten, ein AVD. Weitere Informationen zu AVDs finden Sie unter Virtuelle Geräte erstellen und verwalten. Wenn Sie ein physisches Gerät zum Testen verwenden, müssen Sie das API-Level der Android-Plattform kennen, auf der es ausgeführt wird. Eine Liste der Plattformversionen und ihrer API-Levels finden Sie in der Tabelle in diesem Dokument.

Referenzdokumentation nach API-Level filtern

Auf den Referenzdokumentationsseiten der Android-Plattform finden Sie oben links auf jeder Seite ein Steuerelement für die API-Ebene. Mit diesem Steuerelement können Sie die Dokumentation nur für Teile der API anzeigen, auf die Ihre Anwendung tatsächlich zugreifen kann. Dies basiert auf der API-Ebene, die in der Manifestdatei im Attribut android:minSdkVersion angegeben ist.

Wenn Sie die Filterung verwenden möchten, wählen Sie im Menü die von Ihrer Anwendung angegebene API-Ebene aus. APIs, die in einem späteren API-Level eingeführt wurden, werden dann ausgegraut und ihr Inhalt wird maskiert, da sie für Ihre Anwendung nicht zugänglich sind.

Wenn Sie die Dokumentation nach API-Level filtern, sehen Sie nicht, was in den einzelnen API-Levels neu ist oder eingeführt wurde. So können Sie die gesamte API ansehen, die mit einer bestimmten API-Ebene verknüpft ist, und gleichzeitig API-Elemente ausschließen, die in späteren API-Ebenen eingeführt wurden.

Wenn Sie die vollständige Dokumentation wieder aufrufen möchten, wählen Sie oben im Menü für die API-Ebene REL aus. Standardmäßig ist die Filterung auf API-Ebene deaktiviert, sodass Sie die vollständige Framework-API unabhängig von der API-Ebene sehen können.

In der Referenzdokumentation für einzelne API-Elemente wird die API-Ebene angegeben, auf der die einzelnen Elemente eingeführt werden. Die API-Ebene für Pakete und Klassen wird auf jeder Dokumentationsseite oben rechts im Inhaltsbereich als „Added in API level“ (Hinzugefügt in API-Ebene) angegeben. Der API-Level für Klassenmember wird in den Überschriften der detaillierten Beschreibungen am rechten Rand angegeben.