<uses-sdk>

Google Play verwendet die in deinem App-Manifest deklarierten <uses-sdk>-Attribute, um deine App nach Geräten zu filtern, die die Anforderungen an die 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 mithilfe einer Ganzzahl auf API-Ebene ausdrücken. Das von einer App ausgedrückte 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 die API-Ebene anzugeben, nicht die Versionsnummer des Software Development Kits (SDK) oder der Android-Plattform. Die API-Ebene ist immer eine einzelne Ganzzahl. Sie können das API-Level nicht von der zugehörigen Android-Versionsnummer ableiten. Sie entspricht beispielsweise nicht der Hauptversion oder der Summe der Haupt- und Nebenversionen.

Lesen Sie auch das Dokument zur Versionsverwaltung für Ihre Anwendungen.

Attribute:

android:minSdkVersion

Eine Ganzzahl, die das Mindest-API-Level angibt, das zum Ausführen der Anwendung erforderlich ist. Das Android-System verhindert, dass der Nutzer die App installiert, wenn das API-Level des Systems unter dem in diesem Attribut angegebenen Wert liegt. Dieses Attribut muss immer deklariert werden.

Achtung:Wenn Sie dieses Attribut nicht angeben, geht das System von einem Standardwert von 1 aus. Das bedeutet, dass Ihre App mit allen Android-Versionen kompatibel ist. Falls dies nicht der Fall ist und Sie nicht die richtige minSdkVersion deklariert haben, stürzt die Anwendung bei der Installation auf einem System mit einem inkompatiblen API-Level ab, wenn sie versucht, auf die nicht verfügbaren APIs zuzugreifen. Aus diesem Grund musst du die entsprechende API-Ebene im Attribut minSdkVersion angeben.

android:targetSdkVersion

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

Dieses Attribut informiert das System, das Sie mit der Zielversion getestet haben. Das System aktiviert kein Kompatibilitätsverhalten, um die Aufwärtskompatibilität Ihrer Anwendung mit der Zielversion aufrechtzuerhalten. Die Anwendung kann weiterhin mit niedrigeren Versionen ausgeführt werden (bis hin zu 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 als die Version ist, die im targetSdkVersion der App angegeben ist, kann das System Kompatibilitätsverhalten aktivieren, damit deine App weiterhin wie erwartet funktioniert. Sie können dieses Kompatibilitätsverhalten deaktivieren, indem Sie targetSdkVersion entsprechend der API-Ebene der Plattform angeben, auf der es ausgeführt wird.

Wenn du diesen Wert beispielsweise auf „11“ oder höher festlegst, kann das System bei Android 3.0 oder höher das Holo-Standarddesign auf deine App anwenden. Außerdem wird bei der Ausführung auf größeren Bildschirmen der Bildschirmkompatibilitätsmodus deaktiviert, da API-Level 11 implizit auch größere Bildschirme unterstützt.

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

Wenn Sie Ihre App zusammen mit jedem Android-Release verwalten möchten, erhöhen Sie den Wert dieses Attributs, damit es dem neuesten API-Level entspricht. Testen Sie Ihre App dann gründlich auf der entsprechenden Plattformversion.

Vorgestellt in: API-Level 4

android:maxSdkVersion

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

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. Wenn das Attribut maxSdkVersion der Anwendung niedriger als das vom System selbst verwendete API-Level ist, lässt das System in beiden Fällen die Installation der Anwendung nicht zu. Bei einer erneuten Validierung nach einem Systemupdate wird Ihre Anwendung dadurch effektiv vom Gerät entfernt.

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

Eine App, die in ihrem Manifest maxSdkVersion="5" deklariert, wurde 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.

Die Anwendung funktioniert wie gewohnt. Etwas 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 eigene API-Level (6) des Systems jetzt höher als das von der Anwendung unterstützte Maximum (5) ist. Das System verhindert, dass die Anwendung für den Nutzer sichtbar ist, und entfernt sie somit vom Gerät.

Warnung: Wir raten davon ab, dieses Attribut zu deklarieren. Erstens musst du das Attribut nicht festlegen, um die Bereitstellung deiner App auf neuen Versionen der Android-Plattform zu blockieren, sobald diese veröffentlicht werden. Neue Versionen der Plattform sind standardmäßig vollständig abwärtskompatibel. Ihre Anwendung funktioniert auf neuen Versionen ordnungsgemäß, sofern sie nur Standard-APIs verwendet und Best Practices für die Entwicklung befolgt. Zweitens kann die Deklaration des Attributs in einigen Fällen dazu führen, dass deine App nach einem Systemupdate auf eine höhere API-Ebene von den Geräten der Nutzer entfernt wird. Die meisten Geräte, auf denen Ihre Anwendung wahrscheinlich installiert wird, erhalten regelmäßige Systemupdates over-the-air. Prüfen Sie daher deren Auswirkungen auf Ihre Anwendung, bevor Sie dieses Attribut festlegen.

Vorgestellt in: API-Level 4

Bei einigen Android-Versionen (außer Android 2.0.1) wird das Attribut maxSdkVersion während der Installation oder Neuvalidierung nicht überprüft oder erzwungen. Google Play verwendet das Attribut jedoch weiterhin als Filter, wenn Nutzern Apps zum Download zur Verfügung gestellt werden.

eingeführt in:

API-Level 1

Was ist ein API-Level?

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

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

• Eine Hauptgruppe 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 Anwendungen anfordern können, sowie Berechtigungserzwingungen, die im System enthalten sind

Jede nachfolgende Version der Android-Plattform kann Aktualisierungen der von ihr bereitgestellten Android Application Framework API enthalten.

Die Updates der Framework API sind so konzipiert, dass die neue API mit früheren Versionen der API kompatibel bleibt. Das heißt, die meisten Änderungen an der API sind additiv und führen neue oder Ersatzfunktionen ein. Beim Upgrade von Teilen der API werden die älteren ersetzten Teile verworfen, aber nicht entfernt, sodass sie in vorhandenen Anwendungen weiterhin verwendet werden können.

In sehr wenigen Fällen werden Teile der API geändert oder entfernt. In der Regel sind solche Änderungen jedoch nur erforderlich, um die Stabilität der API und die Anwendungs- oder Systemsicherheit zu unterstützen. Alle anderen API-Teile aus früheren Überarbeitungen werden unverändert übernommen.

Die von einer Android-Plattform bereitgestellte Framework API wird mithilfe einer Ganzzahl-ID namens API-Level angegeben. Jede Android-Plattformversion unterstützt genau ein API-Level, wobei dies jedoch implizit für alle früheren API-Levels (bis API-Level 1) gilt. In der ersten Version der Android-Plattform war API-Level 1 enthalten. In nachfolgenden Releases wurde das API-Level erhöht.

In der folgenden Tabelle ist das API-Level angegeben, 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 Vertriebsdashboard.

Verwendung des API-Levels in Android

Die API-Level-ID spielt eine wichtige Rolle bei der optimalen Nutzung für Nutzer und Anwendungsentwickler:

• Damit kann die Android-Plattform die maximal unterstützte Framework-API-Version beschreiben.
• Anwendungen können damit die erforderliche Framework-API-Version beschreiben.
• Damit kann das System die Installation von Apps auf dem Gerät des Nutzers aushandeln, sodass keine versionsinkompatiblen Apps installiert werden.

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

Anwendungen können ein von der Framework-API bereitgestelltes Manifestelement <uses-sdk> verwenden, um die minimalen und maximalen API-Ebenen zu beschreiben, unter denen sie ausgeführt werden können, sowie das bevorzugte API-Level, das sie unterstützen sollen. Das -Element bietet drei Hauptattribute:

• android:minSdkVersion: das minimale API-Level, auf dem 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 ermöglicht dies der Anwendung, Manifestelemente oder Verhaltensweisen zu verwenden, die auf der Ziel-API-Ebene definiert sind, anstatt nur die Elemente zu verwenden, die für das minimale API-Level definiert sind.
• 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.

Um beispielsweise die minimale System-API-Ebene anzugeben, die eine Anwendung zum Ausführen einer Anwendung benötigt, nimmt die Anwendung in ihrem Manifest ein <uses-sdk>-Element mit einem android:minSdkVersion-Attribut auf. Der Wert von android:minSdkVersion ist die Ganzzahl, die dem API-Level der frühesten Version der Android-Plattform entspricht, unter der die App ausgeführt werden kann.

Wenn der Nutzer versucht, eine App zu installieren, oder wenn eine App nach einem Systemupdate noch einmal validiert wird, prüft das Android-System zuerst die <uses-sdk>-Attribute im Manifest der App und vergleicht die Werte mit dem eigenen internen API-Level. Die Installation beginnt nur, 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 nicht angegeben, geht das System davon aus, dass die Anwendung API-Level 1 benötigt.
• Wenn ein android:maxSdkVersion-Attribut deklariert ist, ist sein Wert gleich oder größer als die Ganzzahl auf der API-Ebene des Systems. Wenn nicht angegeben, geht das System davon aus, dass die Anwendung kein maximales API-Level hat. In der Beschreibung dieses Attributs finden Sie weitere Informationen dazu, wie das System mit diesem Attribut umgeht.

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

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

Eine App deklariert in android:minSdkVersion hauptsächlich eine API-Ebene, um dem Android-System mitzuteilen, dass sie APIs verwendet, die auf das angegebene API-Level eingeführt wurden.

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

Überlegungen zur Entwicklung

Die folgenden Abschnitte enthalten Informationen zum API-Level, die Sie bei der Entwicklung Ihrer Anwendung berücksichtigen müssen.

Anwendungsweiterleitungskompatibilität

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

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 neueren Versionen der Android-Plattform und höheren API-Ebenen aufwärtskompatibel. Die App kann auf allen neueren Versionen der Android-Plattform ausgeführt werden, es sei denn, die App verwendet einen Teil der API, 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 Ihre Anwendung möglicherweise und verwendet sie erfolgreich. Später erhält er ein OTA-Update auf eine neue Version der Android-Plattform. Sobald das Update installiert wurde, wird Ihre Anwendung in einer neuen Laufzeitversion der Umgebung ausgeführt, die jedoch noch über die API- und Systemfunktionen verfügt, von denen Ihre Anwendung abhängt.

Änderungen unter der API, z. B. im zugrunde liegenden System, können sich auf die Anwendung auswirken, wenn sie in der neuen Umgebung ausgeführt wird. Als Anwendungsentwickler ist es wichtig zu verstehen, wie die Anwendung in jeder Systemumgebung aussieht und sich verhält.

Damit Sie Ihre App in verschiedenen Versionen der Android-Plattform testen können, enthält das Android SDK mehrere Plattformen, die Sie herunterladen können. Jede Plattform umfasst 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 Versionen der Android-Plattform, die älter sind als die Version, 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 ermöglichen oder vorhandene API-Teile ersetzen. Die neuen APIs sind für Anwendungen zugänglich, die auf der neuen Plattform oder in neueren Versionen der Plattform ausgeführt werden. Dies wird durch das API-Level angegeben. Da die neuen APIs jedoch in früheren Versionen der Plattform nicht enthalten sind, können Anwendungen, die diese verwenden, auf diesen Plattformen nicht ausgeführt werden.

Obwohl ein Android-Gerät wahrscheinlich nicht auf eine frühere Version der Plattform heruntergestuft wird, ist es wichtig zu bedenken, dass es wahrscheinlich viele Geräte in diesem Bereich gibt, auf denen frühere Versionen der Plattform ausgeführt werden. Selbst bei Geräten, die OTA-Updates erhalten, kann es zu Verzögerungen kommen, sodass das Update längere Zeit gar nicht erfolgt.

Plattformversion und API-Level auswählen

Beim Entwickeln Ihrer Anwendung wählen Sie die Plattformversion aus, mit der Sie die Anwendung kompilieren möchten. Im Allgemeinen sollten Sie Ihre Anwendung mit der niedrigsten Version der Plattform kompilieren, die von Ihrer Anwendung unterstützt wird.

Sie können die niedrigste mögliche Plattformversion ermitteln, indem Sie die Anwendung anhand von immer niedrigeren Build-Zielen kompilieren. Nachdem Sie die niedrigste Version ermittelt haben, erstellen Sie mit der entsprechenden Plattformversion und dem entsprechenden API-Level ein AVD und testen Sie Ihre Anwendung vollständig. Deklarieren Sie ein android:minSdkVersion-Attribut im Manifest der Anwendung und legen Sie als Wert das API-Level der Plattformversion fest.

Mindest-API-Level angeben

Wenn Sie eine Anwendung erstellen, die APIs oder Systemfunktionen der neuesten Plattformversion verwendet, setzen Sie das Attribut android:minSdkVersion auf das API-Level der neuesten Plattformversion. Nutzer können deine App dann nur installieren, wenn auf ihren Geräten eine kompatible Version der Android-Plattform ausgeführt wird. Dies wiederum trägt dazu bei, dass Ihre App auf den Geräten ordnungsgemäß funktioniert.

Wenn Ihre Anwendung APIs der neuesten Plattformversion verwendet, aber kein android:minSdkVersion-Attribut deklariert, wird sie ordnungsgemäß auf Geräten mit der neuesten Version der Plattform ausgeführt, jedoch nicht auf Geräten mit früheren Versionen der Plattform. In letzterem Fall stürzt die Anwendung während der Laufzeit ab, wenn sie versucht, APIs zu verwenden, die in den früheren Versionen nicht vorhanden sind.

Mit höheren API-Levels testen

Nachdem du deine Anwendung kompiliert hast, solltest du sie auf der Plattform testen, die im Attribut android:minSdkVersion der Anwendung angegeben ist. Erstellen Sie dazu ein AVD, das die für Ihre Anwendung erforderliche Plattformversion verwendet. Zum Prüfen der Aufwärtskompatibilität führen und testen Sie die Anwendung außerdem auf allen Plattformen, die ein höheres API-Level als das Ihrer Anwendung verwenden.

Das Android SDK umfasst mehrere Plattformversionen, die Sie verwenden können, einschließlich der neuesten Version, und bietet ein Updater-Tool, 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 doppelt auf die Datei android.bat (Windows) oder android (OS X/Linux) klicken.

Wenn Sie Ihre Anwendung für verschiedene Plattformversionen im Emulator ausführen möchten, erstellen Sie ein AVD für jede Plattformversion, die Sie testen möchten. Weitere Informationen zu AVDs finden Sie unter Virtuelle Geräte erstellen und verwalten. Wenn du ein physisches Gerät zum Testen verwendest, solltest du darauf achten, dass du das API-Level der Android-Plattform kennst, auf der es ausgeführt wird. In der Tabelle in diesem Dokument finden Sie eine Liste der Plattformversionen und ihrer API-Level.

Referenzdokumentation nach API-Level filtern

Die Referenzdokumentationsseiten der Android-Plattform bieten ein Steuerelement für die API-Ebene im oberen linken Bereich jeder Seite. Mit dem Steuerelement können Sie basierend auf dem API-Level, das im Attribut android:minSdkVersion der Manifestdatei der App angegeben ist, nur die Dokumentation für die Teile der API anzeigen lassen, auf die Ihre Anwendung tatsächlich zugreifen kann.

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

Das Filtern nach API-Ebene in der Dokumentation bietet keine Übersicht darüber, was in den einzelnen API-Ebenen neu ist oder eingeführt wird. So können Sie die gesamte mit einem bestimmten API-Level verknüpfte API anzeigen und API-Elemente ausschließen, die in späteren API-Ebenen eingeführt werden.

Wenn Sie zur vollständigen Dokumentation zurückkehren möchten, wählen Sie oben im API-Level-Menü REL aus. Die Filterung auf API-Ebene ist standardmäßig deaktiviert, sodass Sie unabhängig vom API-Level die gesamte Framework-API sehen können.

In der Referenzdokumentation für einzelne API-Elemente wird die API-Ebene angegeben, auf der jedes Element eingeführt wird. Die API-Ebene für Pakete und Klassen wird auf jeder Dokumentationsseite rechts oben im Inhaltsbereich als „In API-Ebene hinzugefügt“ angegeben. Die API-Ebene für Klassenmitglieder wird in den detaillierten Beschreibungsüberschriften am rechten Rand angegeben.