<uses-sdk>

Google Play verwendet die in Ihrem App-Manifest deklarierten <uses-sdk>-Attribute, um Ihre App auf Geräten herauszufiltern, die die Anforderungen an die Plattformversion nicht erfüllen. Bevor du diese Attribute festlegst, solltest du dich mit den Google Play-Filtern vertraut machen.

Syntax:

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

enthalten in:

<manifest>

Beschreibung:

Ermöglicht es, die Kompatibilität einer App mit einer oder mehreren Versionen der Android-Plattform mithilfe einer Ganzzahl für das API-Level auszudrücken. 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 dieses Element verwendet, um das API-Level anzugeben, nicht die Versionsnummer des Software Development Kit (SDK) oder der Android-Plattform. Das API-Level ist immer eine einzelne Ganzzahl. Das API-Level lässt sich nicht von der zugehörigen Android-Versionsnummer ableiten. Sie ist beispielsweise nicht mit der Hauptversion oder der Summe der Haupt- und Nebenversionen identisch.

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

Lesen Sie auch das Dokument zur Versionsverwaltung Ihrer Anwendungen.

Attribute:

android:minSdkVersion

Eine Ganzzahl, die das für die Ausführung der Anwendung erforderliche Mindest-API-Level angibt. Das Android-System verhindert, dass der Nutzer die App installiert, wenn das API-Level des Systems niedriger ist als der in diesem Attribut angegebene Wert. Geben Sie dieses Attribut immer an.

Achtung: Wenn Sie dieses Attribut nicht deklarieren, geht das System von einem Standardwert von „1“ aus. Das bedeutet, dass Ihre App mit allen Android-Versionen kompatibel ist. Wenn dies nicht der Fall ist und du nicht die richtige minSdkVersion deklariert hast, 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. Achten Sie daher darauf, das entsprechende API-Level im Attribut minSdkVersion zu deklarieren.

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 angegebenen Wert.

Dieses Attribut informiert das System darüber, dass Sie die Zielversion getestet haben. Das System aktiviert keine Kompatibilitätsverhalten, um die Aufwä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 Version, die im targetSdkVersion Ihrer App deklariert ist, 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 es ausgeführt wird.

Wenn Sie diesen Wert beispielsweise auf „11“ oder höher festlegen, kann das System das Holo-Standarddesign auf Ihre App anwenden, 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 größere Bildschirme unterstützt.

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

Wenn du deine App mit jedem Android-Release aktualisieren möchtest, erhöhe den Wert dieses Attributs auf das neueste API-Level und teste deine App dann gründlich auf der entsprechenden Plattformversion.

Eingeführt in: API-Level 4

android:maxSdkVersion

Eine Ganzzahl, die das maximale API-Level angibt, auf dem die Anwendung ausgeführt werden kann.

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

Das folgende Beispiel veranschaulicht, wie sich dieses Attribut nach Systemupdates auf deine App 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 neu validieren, da das systemeigene API-Level (6) jetzt höher ist als das von der Anwendung maximal unterstützte Level (5). Das System verhindert, dass die Anwendung für den Nutzer sichtbar ist, und entfernt sie so vom Gerät.

Warnung: Wir raten davon ab, dieses Attribut zu deklarieren. Erstens ist es nicht erforderlich, das Attribut festzulegen, um die Bereitstellung deiner App 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 in neuen Versionen ordnungsgemäß, sofern sie 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 deine App nach einem Systemupdate auf ein höheres API-Level von den Geräten der Nutzer entfernt wird. Die meisten Geräte, auf denen deine App wahrscheinlich installiert wird, erhalten regelmäßig Systemupdates over the air. Berücksichtige daher die Auswirkungen auf deine App, bevor du dieses Attribut festlegst.

Eingeführt in: API-Level 4

Einige Android-Versionen (nach Android 2.0.1) prüfen oder erzwingen das Attribut maxSdkVersion während der Installation oder erneuten Validierung nicht. Google Play verwendet das Attribut jedoch weiterhin als Filter, wenn Nutzern Apps zum Download angeboten werden.

eingeführt in:

API-Level 1

Was ist das API-Level?

Das API-Level ist ein ganzzahliger Wert, der die Framework-API-Version einer Version der Android-Plattform 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:

• Eine Reihe von Kernpaketen und -klassen
• Eine Reihe von XML-Elementen und -Attributen zum Deklarieren einer Manifestdatei
• Eine Reihe von XML-Elementen und -Attributen zum Deklarieren von und Zugreifen auf Ressourcen
• Eine Reihe von Intents
• Eine Reihe von Berechtigungen, die Anwendungen anfordern können, sowie im System enthaltene Berechtigungsdurchsetzungen

Jede neue Version der Android-Plattform kann Aktualisierungen der von ihr bereitgestellten API des Android-Anwendungs-Frameworks enthalten.

Aktualisierungen der Framework API sind so konzipiert, dass die neue API mit früheren Versionen der API kompatibel bleibt. Das bedeutet, dass die meisten Änderungen an der API additiv sind und neue oder Ersatzfunktionen einführen. Wenn Teile der API aktualisiert werden, werden die älteren, ersetzten Teile verworfen, aber nicht entfernt, sodass sie von vorhandenen Anwendungen weiterhin verwendet werden können.

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

Die Framework-API, die eine Android-Plattform bereitstellt, wird mit einer Ganzzahl-ID angegeben, die als API-Level bezeichnet wird. Jede Android-Plattformversion unterstützt genau ein API-Level, wobei alle früheren API-Level (bis API-Level 1) implizit unterstützt werden. Die erste Version der Android-Plattform bot API-Level 1. In nachfolgenden Versionen wurde das API-Level erhöht. APIs, die in Vorabveröffentlichungen von SDKs eingeführt oder eingestellt wurden, die noch nicht die Plattformstabilität erreicht haben, werden mit „API in Entwicklung“ anstelle einer API-Levelnummer gekennzeichnet.

In der folgenden Tabelle ist das API-Level aufgeführt, das 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, findest du im Verteilungs-Dashboard.

APIs in der Entwicklung

In der Android API-Referenzdokumentation sind APIs, die in einem Vorabveröffentlichungs-SDK hinzugefügt oder eingestellt wurden, mit „API in Entwicklung“ anstelle einer API-Levelnummer gekennzeichnet. Dieses Label gilt sowohl für „Hinzugefügt in“ als auch für „Eingestellt in“, bis das SDK die Plattformstabilität erreicht und ein endgültiges Haupt- oder Neben-API-Level erhält. APIs in der Entwicklung haben die folgenden Merkmale:

• Vorabveröffentlichungsstatus: Die API-Ergänzung oder -Einstellung ist Teil einer aktiven Beta- oder Canary-SDK-Vorabversion vor der Fertigstellung des API-Levels.
• Keine Stabilitätsgarantie: Im Gegensatz zu veröffentlichten APIs, die ein permanentes API-Level haben und mit zukünftigen Releases abwärtskompatibel sind, können sich bei APIs in der Entwicklung zwischen den SDK-Vorabversionen die Signaturen ändern, sie können umbenannt oder vollständig entfernt werden.

Prüfung auf APIs, die sich zur Laufzeit in der Entwicklung befinden (PREVIEW_SDK_INT)

Da sich APIs, die sich in der Entwicklung befinden, zwischen Vorabversionen ändern oder verschwinden können, sollten Sie niemals eine „Größer als oder gleich“-Prüfung (>=) verwenden, um Aufrufe an unveröffentlichte APIs zu schützen. Eine API, die in Vorabversion 1 vorhanden ist, kann in Vorabversion 2 geändert oder entfernt werden.

Stattdessen müssen Apps, die mit Funktionen in der Vorabversion experimentieren, den Wert Build.VERSION.PREVIEW_SDK_INT auf strikte Gleichheit (==) mit der genauen Vorabversion prüfen, mit der die App kompiliert wurde:

• Bei endgültigen Produktions-Builds und ‑Releases ist Build.VERSION.PREVIEW_SDK_INT immer 0.
• In Vorabversionen ist PREVIEW_SDK_INT für jeden Release eindeutig.

Verwendung des API-Levels in Android

Die API-Level-ID spielt eine wichtige Rolle, um Nutzern und Anwendungsentwicklern die bestmögliche Nutzung zu ermöglichen:

• Damit kann die Android-Plattform die maximale Framework-API-Version beschreiben, die sie unterstützt.
• Anwendungen können damit die erforderliche Framework-API-Version beschreiben.
• Dadurch kann das System die Installation von Anwendungen auf dem Gerät des Nutzers so verhandeln, dass keine inkompatiblen Versionen installiert werden.

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

Anwendungen können ein Manifestelement verwenden, das von der Framework-API bereitgestellt wird (<uses-sdk>), um die minimalen und maximalen API-Level zu beschreiben, unter denen sie ausgeführt werden können, sowie das bevorzugte API-Level, das sie unterstützen sollen. 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: das API-Level, auf dem die Anwendung ausgeführt werden soll. In einigen Fällen kann die Anwendung dadurch Manifestelemente oder Verhaltensweisen verwenden, die in der Ziel-API-Ebene definiert sind, anstatt nur die für die Mindest-API-Ebene definierten Elemente oder Verhaltensweisen verwenden zu können.
• 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 das minimale System-API-Level angeben möchten, das eine Anwendung für die Ausführung 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 zu, wenn die folgenden Bedingungen erfüllt sind:

• Wenn ein android:minSdkVersion-Attribut deklariert ist, ist sein Wert kleiner oder gleich der Ganzzahl des API-Levels des Systems. Wenn nichts deklariert ist, geht das System davon aus, dass die Anwendung API-Level 1 erfordert.
• Wenn ein android:maxSdkVersion-Attribut deklariert ist, ist sein Wert gleich oder größer als die Ganzzahl des API-Levels des Systems. Wenn keine Angabe gemacht wird, geht das System davon aus, dass die Anwendung kein maximales API-Level hat. Weitere Informationen dazu, wie das System dieses Attribut verarbeitet, 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 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 irgendwie auf einer Plattform mit einem niedrigeren API-Level installiert wird, stürzt sie zur Laufzeit ab, wenn sie versucht, auf APIs zuzugreifen, die nicht vorhanden sind. Das System verhindert dieses Ergebnis, indem es die Installation der Anwendung nicht zulässt, wenn das niedrigste erforderliche API-Level höher ist als das 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.

Aufwärtskompatibilität von Anwendungen

Android-Apps sind im Allgemeinen mit neuen Versionen der Android-Plattform aufwärtskompatibel.

Da fast alle Änderungen an der Framework-API additiv sind, ist eine Android-App, die mit einer bestimmten Version der API (wie durch ihr API-Level angegeben) entwickelt wurde, mit späteren Versionen der Android-Plattform und höheren API-Levels kompatibel. 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 Aufwärtskompatibilität ist wichtig, da viele Android-Geräte OTA-Systemupdates (Over the Air) erhalten. Der Nutzer installiert deine 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 jedoch weiterhin die API- und Systemfunktionen enthält, 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.

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 einem AVD ausführen können, um Ihre Anwendung zu testen.

Abwärtskompatibilität von Anwendungen

Android-Apps sind nicht unbedingt abwärtskompatibel mit Versionen der Android-Plattform, 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 gewähren oder vorhandene API-Teile ersetzen. Die neuen APIs sind für Anwendungen zugänglich, 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 herabgestuft wird, aber es ist wichtig zu wissen, dass es wahrscheinlich viele Geräte gibt, auf denen frühere Versionen der Plattform ausgeführt werden. Selbst bei Geräten, die Over-the-air-Updates erhalten, kann es bei einigen zu Verzögerungen kommen und es kann sein, dass sie für längere Zeit kein Update erhalten.

Plattformversion und API-Level auswählen

Wenn Sie Ihre Anwendung entwickeln, wählen Sie die Plattformversion aus, mit der Sie die Anwendung kompilieren. Im Allgemeinen sollten Sie Ihre Anwendung für die niedrigste mögliche Version der Plattform kompilieren, die Ihre Anwendung unterstützen kann.

Sie können die niedrigste mögliche Plattformversion ermitteln, indem Sie die Anwendung für immer niedrigere Build-Ziele kompilieren. Nachdem Sie die niedrigste Version ermittelt haben, erstellen Sie ein AVD mit der entsprechenden Plattformversion und API-Ebene und testen Sie Ihre Anwendung vollständig. Achten Sie darauf, im Manifest der Anwendung ein android:minSdkVersion-Attribut zu deklarieren und seinen Wert auf das API-Level der Plattformversion festzulegen.

Mindest-API-Level deklarieren

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

Wenn deine Anwendung APIs verwendet, die in der aktuellen Plattformversion eingeführt wurden, aber kein android:minSdkVersion-Attribut deklariert, funktioniert sie auf Geräten mit der aktuellen Version der Plattform, aber nicht auf Geräten mit früheren 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, sollten 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. Führen Sie die Anwendung außerdem auf allen Plattformen aus, die ein höheres API-Level als Ihre Anwendung verwenden, und testen Sie sie, um die Aufwärtskompatibilität zu prüfen.

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

Verwenden Sie für den Zugriff auf das Updateprogramm das Befehlszeilentool android im Verzeichnis <sdk>/tools. Sie können das SDK-Updateprogramm starten, indem Sie android sdk ausführen. Sie können auch auf die Datei android.bat (Windows) oder android (OS X/Linux) doppelklicken.

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-Level finden Sie in der Tabelle in diesem Dokument.

Referenzdokumentation nach API-Level filtern

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

Wenn Sie die Filterung verwenden möchten, wählen Sie im Menü das von Ihrer Anwendung angegebene API-Level 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 du in der Dokumentation nach API-Level filterst, siehst du nicht, was in den einzelnen API-Levels neu ist oder eingeführt wurde. So können Sie die gesamte API für ein bestimmtes API-Level aufrufen und gleichzeitig API-Elemente ausschließen, die in späteren API-Levels eingeführt wurden.

Wenn Sie die vollständige Dokumentation wieder aufrufen möchten, wählen Sie oben im Menü „API-Level“ die Option REL aus. Standardmäßig ist die Filterung nach API-Level deaktiviert, sodass Sie die gesamte Framework-API unabhängig vom API-Level sehen können.

In der Referenzdokumentation für einzelne API-Elemente wird das API-Level angegeben, auf dem jedes Element eingeführt oder eingestellt wird. Das API-Level für Pakete und Klassen wird oben rechts im Inhaltsbereich jeder Dokumentationsseite als „Hinzugefügt in API-Level“ und gegebenenfalls als „Eingestellt in API-Level“ angegeben. Das API-Level für Klassenmitglieder wird in den Überschriften der detaillierten Beschreibungen am rechten Rand angegeben. Bei Vorabveröffentlichungen von API-Ergänzungen oder -Einstellungen, die noch nicht die Plattformstabilität erreicht haben, wird an diesen Stellen „API in Entwicklung“ anstelle einer API-Levelnummer angezeigt.