<uses-sdk>

Google Play verwendet die <uses-sdk>-Attribute, die in Ihrem App-Manifest deklariert sind, um Ihre App von Geräten zu filtern, die die Anforderungen der Plattformversion nicht erfüllen. Bevor Sie diese Attribute festlegen, sollten Sie sich mit den Google Play-Filtern vertraut machen.

syntax:

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

enthalten in:

<manifest>

description:

Hiermit können Sie die Kompatibilität einer Anwendung mit einer oder mehreren Versionen der Android-Plattform anhand einer Ganzzahl für die API-Ebene angeben. 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 seines Namens wird dieses Element verwendet, um das API-Level anzugeben, nicht die Versionsnummer des Software Development Kits (SDK) oder der Android-Plattform. 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 mit der Hauptversion oder der Summe der Haupt- und Nebenversion identisch.

Lesen Sie auch das Dokument zur Versionsverwaltung Ihrer Anwendungen.

attributes:

android:minSdkVersion

Eine Ganzzahl, die das Mindest-API-Level angibt, das für die Ausführung der Anwendung erforderlich ist. Das Android-System verhindert, dass der Nutzer die Anwendung installiert, wenn das API-Level des Systems unter dem in diesem Attribut angegebenen Wert liegt. Deklarieren Sie dieses Attribut immer.

Achtung:Wenn Sie dieses Attribut nicht angeben, verwendet das System den Standardwert „1“, was bedeutet, dass Ihre App mit allen Android-Versionen kompatibel ist. Wenn das nicht der Fall ist und Sie die richtige minSdkVersion nicht deklariert haben, stürzt die Anwendung bei der Installation auf einem System mit einer inkompatiblen API-Ebene während der Laufzeit ab, wenn versucht wird, auf die nicht verfügbaren APIs zuzugreifen. Deklarieren Sie daher unbedingt die richtige API-Ebene im Attribut minSdkVersion.

android:targetSdkVersion

Eine Ganzzahl, die das API-Level angibt, auf das die Anwendung ausgerichtet ist. Wenn nicht festgelegt, entspricht der Standardwert dem für minSdkVersion festgelegten Wert.

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

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 Version, die in der targetSdkVersion Ihrer App angegeben ist, kann das System Kompatibilitätsverhalten aktivieren, damit Ihre App weiterhin wie erwartet funktioniert. Sie können diese Kompatibilitätsfunktionen deaktivieren, indem Sie targetSdkVersion angeben, um die API-Ebene der Plattform anzupassen, auf der die Funktion 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 auf 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 größere Bildschirme implizit von der Unterstützung der API-Ebene 11 abgedeckt sind.

Je nach dem für dieses Attribut festgelegten Wert kann das System viele Kompatibilitätsoptionen aktivieren. Einige dieser Verhaltensweisen werden in der Build.VERSION_CODES-Referenz für die entsprechenden Plattformversionen beschrieben.

Wenn Sie Ihre App mit jedem Android-Release aktualisieren möchten, erhöhen Sie den Wert dieses Attributs auf das neueste API-Level und testen Sie Ihre App dann gründlich auf der entsprechenden Plattformversion.

Eingeführt in: API-Level 4

android:maxSdkVersion

Eine Ganzzahl, die die maximale API-Ebene angibt, auf der die Anwendung ausgeführt werden soll.

Unter 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 wird die Installation der Anwendung vom System verhindert, wenn das maxSdkVersion-Attribut der Anwendung niedriger ist als die API-Ebene, die vom System selbst verwendet wird. Bei einer erneuten Validierung nach einem Systemupdate wird Ihre App effektiv vom Gerät entfernt.

Im folgenden Beispiel wird veranschaulicht, wie sich dieses Attribut nach Systemupdates auf Ihre Anwendung auswirken kann:

Eine Anwendung, die maxSdkVersion="5" in ihrem Manifest deklariert, 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). Nach der Installation des Updates prüft das System die maxSdkVersion der Anwendung und validiert sie noch einmal erfolgreich.

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 noch einmal validieren, da das API-Level des Systems (6) jetzt höher ist als das von der Anwendung maximal unterstützte (5). Das System verhindert, dass die Anwendung für den Nutzer sichtbar ist, und entfernt sie so effektiv vom Gerät.

Warnung:Wir empfehlen, dieses Attribut nicht zu deklarieren. Erstens: Sie müssen das Attribut nicht festlegen, um die Bereitstellung Ihrer Anwendung auf neuen Versionen der Android-Plattform zu blockieren, sobald diese veröffentlicht werden. Neue Versionen der Plattform sind von Haus aus vollständig abwärtskompatibel. Ihre Anwendung funktioniert in neuen Versionen ordnungsgemäß, sofern nur Standard-APIs verwendet und die Best Practices für die Entwicklung befolgt werden. Zweitens kann die Deklaration des Attributs in einigen Fällen dazu führen, dass Ihre App nach einem Systemupdate auf ein höheres API-Level von den Geräten der Nutzer entfernt wird. Die meisten Geräte, auf denen Ihre App wahrscheinlich installiert ist, erhalten regelmäßig drahtlose Systemupdates. Berücksichtigen Sie deren Auswirkungen auf Ihre App, bevor Sie dieses Attribut festlegen.

Eingeführt in: API-Level 4

Bei einigen Android-Versionen (ab Android 2.0.1) wird das Attribut maxSdkVersion bei der Installation oder erneuten Validierung nicht geprüft oder erzwungen. Google Play verwendet das Attribut jedoch weiterhin als Filter, wenn Nutzern zum Download verfügbare Apps angezeigt werden.

eingeführt in:

API-Level 1

Was ist die API-Ebene?

Das API-Level ist ein Ganzzahlwert, der die Framework-API-Revision eindeutig identifiziert, die von einer Version der Android-Plattform angeboten wird.

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

• Eine Reihe 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 Abrufen von Ressourcen
• Eine Reihe von Intents
• Eine Reihe von Berechtigungen, die von Anwendungen angefordert werden können, sowie Berechtigungserzwungen im System

Jede nachfolgende Version der Android-Plattform kann Updates für die API des Android Application Frameworks 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 also additive und führen zu neuen oder Ersatzfunktionen. Wenn Teile der API aktualisiert werden, werden die älteren ersetzten Teile eingestellt, aber nicht entfernt, damit sie von vorhandenen Anwendungen weiterhin verwendet werden können.

In sehr wenigen Fällen werden Teile der API geändert oder entfernt. Normalerweise sind solche Änderungen jedoch nur erforderlich, um die Robustheit der API sowie die Anwendungs- oder Systemsicherheit zu unterstützen. Alle anderen API-Teile aus früheren Versionen 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 ist jedoch implizit für alle früheren API-Levels (bis API-Level 1) vorhanden. Die erste Version der Android-Plattform bot API-Level 1. Bei nachfolgenden Releases wurde die API-Ebene 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 der Geräte, auf denen die einzelnen Versionen ausgeführt werden, finden Sie im Dashboard zur Verteilung.

Verwendung des API-Levels unter Android

Die Kennung der API-Ebene spielt eine wichtige Rolle bei der Gewährleistung einer optimalen Nutzung für Nutzer und Anwendungsentwickler:

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

Jede Android-Plattformversion speichert die Kennung der API-Ebene intern im Android-System selbst.

Anwendungen können ein Manifestelement verwenden, das von der Framework-API <uses-sdk> bereitgestellt wird, um die Mindest- und Höchst-API-Ebenen zu beschreiben, unter denen sie ausgeführt werden können, sowie die bevorzugte API-Ebene, die sie unterstützen sollen. Das Element bietet drei wichtige Attribute:

• android:minSdkVersion: die Mindest-API-Ebene, auf der die Anwendung ausgeführt werden kann. Der Standardwert ist „1“.
• android:targetSdkVersion: die API-Ebene, auf der die Anwendung ausgeführt werden soll. In einigen Fällen kann die Anwendung so Manifestelemente oder -verhalten verwenden, die auf der Ziel-API-Ebene definiert sind, anstatt nur die für die Mindest-API-Ebene definierten verwenden zu müssen.
• android:maxSdkVersion: die maximale API-Ebene, auf der die Anwendung ausgeführt werden kann. Wichtig:Lesen Sie sich die Informationen zu diesem Attribut auf dieser Seite durch, 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 dem Attribut android:minSdkVersion. 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 eine Anwendung nach einem Systemupdate noch einmal zu validieren, prüft das Android-System zuerst die <uses-sdk>-Attribute im Manifest der Anwendung und vergleicht die Werte mit seiner eigenen internen API-Ebene. Die Installation wird vom System nur gestartet, wenn folgende Bedingungen erfüllt sind:

• Wenn ein android:minSdkVersion-Attribut deklariert ist, ist sein Wert kleiner oder gleich der Ganzzahl für die API-Ebene des Systems. Wenn keine Deklaration erfolgt, geht das System davon aus, dass für die Anwendung API-Level 1 erforderlich ist.
• Wenn ein android:maxSdkVersion-Attribut deklariert ist, ist sein Wert gleich oder größer als die Ganzzahl der API-Ebene des Systems. Wenn dies nicht deklariert ist, geht das System davon aus, dass die Anwendung kein maximales API-Level hat. Weitere Informationen zur Verarbeitung dieses Attributs finden Sie in der Beschreibung dieses Attributs.

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

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

Der Hauptgrund, warum eine Anwendung in android:minSdkVersion ein API-Level angibt, besteht darin, dem Android-System mitzuteilen, dass sie APIs verwendet, die in der angegebenen API-Ebene eingeführt wurden.

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

Überlegungen zur Entwicklung

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

Anwendungskompatibilität

Android-Anwendungen sind in der Regel mit neuen Versionen der Android-Plattform kompatibel.

Da fast alle Änderungen an der Framework-API additiv sind, ist eine Android-Anwendung, die mit einer bestimmten Version der API entwickelt wurde, wie durch die API-Ebene angegeben, mit neueren Versionen der Android-Plattform und höheren API-Ebenen kompatibel. Die Anwendung kann auf allen neueren Versionen der Android-Plattform ausgeführt werden, mit Ausnahme von Einzelfällen, in denen die Anwendung einen Teil der API verwendet, der später aus irgendeinem Grund entfernt wird.

Die Zukunftssicherheit ist wichtig, da viele Android-Geräte Systemupdates per Funk (Over-the-air, OTA) erhalten. Der Nutzer installiert Ihre App und verwendet sie erfolgreich. Später erhält er ein Over-the-Air-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 aber weiterhin die API und Systemfunktionen enthält, von denen Ihre Anwendung abhängt.

Änderungen unter der API, z. B. am zugrunde liegenden System selbst, können sich auf Ihre Anwendung auswirken, wenn sie in der neuen Umgebung ausgeführt wird. Als Entwickler der Anwendung ist es wichtig, dass Sie wissen, wie die Anwendung in jeder Systemumgebung aussieht und sich verhält.

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

Abwärtskompatibilität von Anwendungen

Android-Anwendungen sind nicht unbedingt abwärtskompatibel mit Versionen der Android-Plattform, die älter als die Version sind, mit der sie kompiliert wurden.

Jede neue Version der Android-Plattform kann neue Framework-APIs enthalten, z. B. solche, die Anwendungen Zugriff auf neue Plattformfunktionen gewähren oder vorhandene API-Teile ersetzen. Die neuen APIs sind für Anwendungen zugänglich, wenn sie auf der neuen Plattform oder auf neueren Versionen der Plattform ausgeführt werden, wie von der API-Ebene angegeben. Da frühere Versionen der Plattform die neuen APIs jedoch nicht enthalten, können Anwendungen, die die neuen APIs verwenden, auf diesen Plattformen nicht 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 im Einsatz 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 einige Zeit dauern, bis ein Update verfügbar ist.

Plattformversion und API-Level auswählen

Bei der Entwicklung Ihrer Anwendung wählen Sie die Plattformversion aus, mit der Sie die Anwendung kompilieren. Kompilieren Sie Ihre Anwendung im Allgemeinen mit der niedrigsten Version der Plattform, die Ihre Anwendung unterstützen kann.

Sie können die niedrigste mögliche Plattformversion ermitteln, indem Sie die Anwendung mit nacheinander niedrigeren Buildzielen kompilieren. Nachdem Sie die niedrigste Version ermittelt haben, erstellen Sie eine AVD mit der entsprechenden Plattformversion und API-Ebene und testen Sie Ihre Anwendung vollständig. Deklarieren Sie im Manifest der Anwendung ein android:minSdkVersion-Attribut und legen Sie als Wert die API-Ebene der Plattformversion fest.

Mindest-API-Level angeben

Wenn Sie eine Anwendung erstellen, die APIs oder Systemfunktionen verwendet, die in der neuesten Plattformversion eingeführt wurden, setzen Sie das android:minSdkVersion-Attribut auf die API-Ebene der neuesten Plattformversion. So können Nutzer Ihre App nur installieren, wenn auf ihren Geräten eine kompatible Version der Android-Plattform ausgeführt wird. So lässt sich dafür sorgen, dass Ihre Anwendung auf den Geräten der Nutzer ordnungsgemäß funktioniert.

Wenn Ihre Anwendung APIs verwendet, die in der neuesten Plattformversion eingeführt wurden, aber kein android:minSdkVersion-Attribut deklariert, wird sie auf Geräten mit der neuesten Plattformversion ordnungsgemäß ausgeführt, nicht aber auf Geräten mit älteren Plattformversionen. Im letzteren Fall stürzt die Anwendung bei der Laufzeit ab, wenn versucht wird, APIs zu verwenden, die in den älteren Versionen nicht vorhanden sind.

Tests mit höheren API-Ebenen

Testen Sie Ihre Anwendung nach dem Kompilieren auf der Plattform, die im android:minSdkVersion-Attribut der Anwendung angegeben ist. Erstellen Sie dazu eine AVD, die die für Ihre Anwendung erforderliche Plattformversion verwendet. Um die Zukunftssicherheit zu prüfen, sollten Sie die Anwendung außerdem auf allen Plattformen ausführen und testen, die eine höhere API-Ebene als Ihre Anwendung verwenden.

Das Android SDK enthält mehrere Plattformversionen, die Sie verwenden können, einschließlich der neuesten Version. Außerdem gibt es ein Updatetool, mit dem Sie bei Bedarf andere Plattformversionen herunterladen können.

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

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

Referenzdokumentation nach API-Ebene filtern

Auf den Seiten der Android-Plattform-Referenzdokumentation finden Sie links oben auf jeder Seite die Option „API-Ebene“. Sie können mit dem Steuerelement die Dokumentation nur für Teile der API anzeigen lassen, auf die Ihre Anwendung tatsächlich zugreifen kann. Dabei wird die API-Ebene berücksichtigt, die im android:minSdkVersion-Attribut der Manifestdatei 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 einer späteren API-Ebene eingeführt wurden, sind dann ausgegraut und ihr Inhalt wird ausgeblendet, da sie für Ihre Anwendung nicht zugänglich sind.

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

Wenn Sie die vollständige Dokumentation aufrufen möchten, wählen Sie oben im Menü auf API-Ebene REL aus. Standardmäßig ist das Filtern auf API-Ebene deaktiviert, sodass Sie die vollständige Framework-API unabhängig von der API-Ebene aufrufen 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 „In API-Ebene hinzugefügt“ angegeben. Die API-Ebene für Klassenmitglieder wird in den Überschriften der detaillierten Beschreibungen am rechten Rand angegeben.