Google Play verwendet die in deinem App-Manifest deklarierten <uses-sdk>-Attribute, um deine App nach Geräten zu filtern, die nicht die Anforderungen an die Plattformversion 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>- description:
Ermöglicht es dir, die Kompatibilität einer App mit einer oder mehreren Versionen der Android-Plattform anhand einer Ganzzahl auf API-Ebene auszudrü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. Die API-Ebene lässt sich nicht aus der verknüpften Android-Versionsnummer ableiten. Sie ist beispielsweise nicht mit der Hauptversion oder der Summe der Haupt- und Nebenversionen identisch.
Lesen Sie auch das Dokument über die Versionsverwaltung Ihrer Anwendungen.
- Attribute:
-
android:minSdkVersion- Eine Ganzzahl, die das minimale API-Level angibt, das zum Ausführen der Anwendung erforderlich ist. Das Android-System hindert den Nutzer daran, die App zu installieren, wenn die API-Ebene des Systems unter dem in diesem Attribut angegebenen Wert liegt. Deklarieren Sie dieses Attribut immer.
Achtung:Wenn du dieses Attribut nicht angibst, nimmt das System einen Standardwert von „1“ an. Das bedeutet, dass deine App mit allen Android-Versionen kompatibel ist. Ist dies nicht und Sie haben nicht die richtige
minSdkVersiondeklariert, 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. Aus diesem Grund musst du im AttributminSdkVersiondie entsprechende API-Ebene angeben. android:targetSdkVersion- Eine Ganzzahl, die die API-Ebene angibt, auf die die Anwendung abzielt. Wenn nichts festgelegt ist, entspricht der Standardwert dem für
minSdkVersionangegebenen Wert.Dieses Attribut informiert das System darüber, dass Sie anhand der Zielversion getestet haben. Das System aktiviert keine Kompatibilitätsverhalten, um die Aufwärtskompatibilität Ihrer App mit der Zielversion aufrechtzuerhalten. Die Anwendung kann noch 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. Ist das API-Level der Plattform jedoch höher als die Version, die im
targetSdkVersiondeiner App deklariert ist, kann das System Kompatibilitätsverhalten aktivieren, damit deine App weiterhin wie erwartet funktioniert. Sie können dieses Kompatibilitätsverhalten deaktivieren, indem SietargetSdkVersionangeben, damit es der API-Ebene der Plattform entspricht, auf der sie ausgeführt wird.Wenn du diesen Wert beispielsweise auf „11“ oder höher setzt, kann das System das Holo-Standarddesign auf deine App unter Android 3.0 oder höher anwenden. Außerdem wird der Bildschirmkompatibilitätsmodus deaktiviert, wenn es auf größeren Bildschirmen ausgeführt wird, da die Unterstützung für API-Ebene 11 implizit größere Bildschirme unterstützt.
Basierend auf dem Wert, den Sie für dieses Attribut festlegen, kann das System viele Kompatibilitätsverhalten aktivieren. Einige dieser Verhaltensweisen werden in den entsprechenden Plattformversionen in der
Build.VERSION_CODES-Referenz beschrieben.Um Ihre App zusammen mit jedem Android-Release zu verwalten, erhöhen Sie den Wert dieses Attributs, damit er dem neuesten API-Level entspricht. Testen Sie Ihre App dann gründlich auf der entsprechenden Plattformversion.
Eingeführt in: API-Level 4
- Eine Ganzzahl, die die maximale API-Ebene angibt, auf der 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 beim Installieren einer Anwendung und wenn sie nach einem Systemupdate neu validiert wird. In beiden Fällen lässt das System die Installation der Anwendung nicht zu, wenn das Attribut
maxSdkVersionder Anwendung niedriger ist als die API-Ebene, die vom System selbst verwendet wird. Im Falle einer erneuten Validierung nach dem Systemupdate wird Ihre Anwendung dadurch effektiv vom Gerät entfernt.Das folgende Beispiel veranschaulicht, wie sich dieses Attribut nach Systemupdates auf Ihre Anwendung auswirken kann:
Eine App, die in ihrem Manifest
maxSdkVersion="5"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 diemaxSdkVersionder 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 unterstützte Maximum (5). Das System verhindert, dass die Anwendung für den Nutzer sichtbar ist, und entfernt sie vom Gerät.
Warnung:Wir raten davon ab, dieses Attribut zu deklarieren. Erstens muss das Attribut nicht festgelegt werden, um die Bereitstellung Ihrer Anwendung auf neuen Versionen der Android-Plattform zu blockieren, sobald diese veröffentlicht werden. Neue Versionen der Plattform sind standardmäßig abwärtskompatibel. Ihre Anwendung funktioniert in neuen Versionen ordnungsgemäß, sofern sie nur Standard-APIs verwendet und die Best Practices für die Entwicklung eingehalten werden. Zweitens kann die Deklaration des Attributs in einigen Fällen dazu führen, dass Ihre Anwendung nach einem Systemupdate auf eine höhere API-Ebene von den Geräten der Nutzer entfernt wird. Die meisten Geräte, auf denen Ihre App wahrscheinlich installiert wird, erhalten regelmäßig Systemupdates over-the-air. Prüfen Sie daher, wie sich diese auf Ihre App auswirken, bevor Sie dieses Attribut festlegen.
Eingeführt in: API-Level 4
Bei einigen Versionen von Android (ab Android 2.0.1) wird das AttributmaxSdkVersionwährend der Installation oder erneuten Validierung nicht geprüft oder erzwungen. Google Play verwendet das Attribut 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 von einer Version der Android-Plattform angebotene Framework-API-Überarbeitung 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 Anwendungen anfordern können, sowie im System enthaltene Berechtigungserzwingungen
Jede nachfolgende Version der Android-Plattform kann Updates für die von ihr bereitgestellte Android Application Framework API enthalten.
Aktualisierungen der Framework API sind so konzipiert, dass die neue API weiterhin mit früheren Versionen der API kompatibel bleibt. Das heißt, die meisten Änderungen in der API sind additiv und führen neue Funktionen oder Ersatzfunktionen ein. Wenn Teile der API aktualisiert werden, werden die älteren ersetzten Teile verworfen, aber nicht entfernt, sodass vorhandene Anwendungen sie weiterhin verwenden 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 API-Robustheit 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 mit einer ganzzahligen Kennung namens API-Level angegeben. Jede Android-Plattformversion unterstützt genau eine API-Ebene, wobei dies implizit alle früheren API-Levels (bis API-Level 1) betrifft. Der erste Release der Android-Plattform bot API-Level 1. Durch nachfolgende 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 Vertriebs-Dashboard.
Verwendung des API-Levels unter Android
Die API-Level-ID spielt eine wichtige Rolle dabei, Nutzern und Anwendungsentwicklern die bestmögliche Erfahrung zu bieten:
- Damit kann die Android-Plattform die maximale Framework-API-Version beschreiben, 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, sodass keine versionsinkompatiblen Anwendungen 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-Levels zu beschreiben, unter denen sie ausgeführt werden können, sowie das bevorzugte API-Level, das unterstützt werden soll. Das Element bietet drei wichtige Attribute:
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 kann die Anwendung dann Manifestelemente oder Verhaltensweisen verwenden, die auf der Ziel-API-Ebene definiert sind, anstatt nur die für das Mindest-API-Level definierten Elemente zu verwenden.android:maxSdkVersion: die maximale API-Ebene, auf der 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 Mindestsystem-API-Level angeben möchten, das eine Anwendung zum Ausführen benötigt, nimmt sie in ihrem Manifest ein <uses-sdk>-Element mit einem android:minSdkVersion-Attribut auf. Der Wert von android:minSdkVersion ist die Ganzzahl, die der API-Ebene 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 neu validiert wird, prüft das Android-System zuerst die <uses-sdk>-Attribute im Manifest der App und vergleicht die Werte mit der eigenen internen API-Ebene. Das System lässt die Installation nur beginnen, wenn die folgenden Bedingungen erfüllt sind:
- Wenn ein
android:minSdkVersion-Attribut deklariert ist, ist sein Wert kleiner oder gleich der Ganzzahl der API-Ebene des Systems. Wenn keine Angabe 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 keine Angabe erfolgt, geht das System davon aus, dass die Anwendung kein maximales API-Level hat. Weitere Informationen dazu, wie das System damit umgeht, finden Sie in der Beschreibung dieses Attributs.
Ein <uses-sdk>-Element, das im Manifest einer Anwendung deklariert ist, könnte so aussehen:
<manifest> <uses-sdk android:minSdkVersion="5" /> ... </manifest>
Wenn eine Anwendung eine API-Ebene in android:minSdkVersion deklariert, muss das Android-System vor allem darüber informiert werden, dass sie APIs verwendet, die mit der angegebenen API-Ebene eingeführt wurden.
Wird die Anwendung auf einer Plattform mit einer niedrigeren API-Ebene installiert, stürzt sie zur Laufzeit ab, wenn versucht wird, auf nicht vorhandene APIs zuzugreifen. Das System verhindert dies, indem es die Installation der Anwendung nicht zulässt, wenn die niedrigste API-Ebene, die erforderlich ist, höher als die Plattformversion auf dem Zielgerät ist.
Überlegungen zur Entwicklung
Die folgenden Abschnitte enthalten Informationen zum API-Level, das Sie bei der Entwicklung Ihrer Anwendung berücksichtigen müssen.
Kompatibilität der Weiterleitung 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-Anwendung, die mit einer bestimmten API-Version entwickelt wurde, wie durch ihre API-Ebene angegeben, mit neueren Versionen der Android-Plattform und höheren API-Levels kompatibel. Die App kann auf allen neueren Versionen der Android-Plattform ausgeführt werden, außer in vereinzelten Fällen, in denen die App 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 kann deine Anwendung installieren und erfolgreich verwenden und später ein OTA-Update auf eine neue Version der Android-Plattform erhalten. Nach der Installation des Updates wird Ihre Anwendung in einer neuen Laufzeitversion der Umgebung ausgeführt, die jedoch noch über die API und die Systemfunktionen verfügt, von denen Ihre Anwendung abhängig ist.
Änderungen unter der API, beispielsweise im zugrunde liegenden System selbst, können sich auf Ihre Anwendung auswirken, wenn sie in der neuen Umgebung ausgeführt wird. Für Sie als Anwendungsentwickler ist es wichtig zu verstehen, wie die Anwendung in den einzelnen Systemumgebungen aussieht und sich verhält.
Das Android SDK umfasst mehrere Plattformen, die du herunterladen kannst, damit du deine App auf verschiedenen Versionen der Android-Plattform testen kannst. Jede Plattform enthält ein kompatibles System-Image, das Sie in einem AVD zum Testen Ihrer Anwendung ausführen können.
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 geben oder bestehende API-Teile ersetzen. Auf die neuen APIs können Anwendungen sowohl auf der neuen Plattform als auch auf späteren Versionen der Plattform zugreifen, je nach API-Ebene. Da frühere Versionen der Plattform jedoch nicht die neuen APIs enthalten, können Anwendungen, die die neuen APIs verwenden, nicht auf diesen Plattformen ausgeführt werden.
Obwohl ein Android-Gerät wahrscheinlich nicht auf eine frühere Version der Plattform herabgestuft wird, ist es wichtig zu wissen, dass es wahrscheinlich viele Geräte gibt, auf denen frühere Versionen der Plattform ausgeführt werden. Auch bei Geräten, die OTA-Updates erhalten, kann es etwas dauern, bis sie aktualisiert werden.
Plattformversion und API-Level auswählen
Bei der Entwicklung Ihrer Anwendung wählen Sie die Plattformversion aus, mit der Sie die Anwendung kompilieren. Im Allgemeinen sollten Sie Ihre Anwendung mit der niedrigsten möglichen Version der Plattform kompilieren, die von Ihrer Anwendung unterstützt wird.
Sie können die niedrigste mögliche Plattformversion ermitteln, indem Sie die Anwendung mit nacheinander 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. Deklarieren Sie ein android:minSdkVersion-Attribut im Manifest der Anwendung 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 Attribut android:minSdkVersion auf die API-Ebene 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. Dies wiederum trägt dazu bei, dass Ihre Anwendung auf ihren Geräten ordnungsgemäß funktionieren kann.
Wenn Ihre Anwendung APIs verwendet, die mit der neuesten Plattformversion eingeführt wurden, aber kein Attribut android:minSdkVersion deklariert, wird sie auf Geräten mit der neuesten Plattformversion korrekt ausgeführt, nicht jedoch auf Geräten, auf denen frühere Versionen der Plattform ausgeführt werden. Im letzteren Fall stürzt die Anwendung zur Laufzeit ab, wenn versucht wird, APIs zu verwenden, die in den früheren Versionen nicht vorhanden sind.
Mit höheren API-Levels testen
Nachdem Sie die Anwendung kompiliert haben, testen Sie sie auf der Plattform, die im Attribut android:minSdkVersion der Anwendung angegeben ist. Erstellen Sie dazu ein AVD, das die für Ihre Anwendung erforderliche Plattformversion verwendet. Um die Aufwärtskompatibilität zu prüfen, müssen Sie die Anwendung außerdem auf allen Plattformen ausführen und testen, die eine höhere API-Ebene als die Ihrer Anwendung verwenden.
Das Android SDK enthält 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 auf die Datei android.bat (Windows) oder android (OS X/Linux) doppelklicken.
Wenn Sie Ihre Anwendung auf verschiedenen 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 die API-Ebene der Android-Plattform kennen, auf der es läuft. Die Tabelle in diesem Dokument enthält eine Liste der Plattformversionen und ihrer API-Ebenen.
Referenzdokumentation nach API-Ebene filtern
Die Referenzdokumentationsseiten für die Android-Plattform bieten oben links auf jeder Seite ein Steuerelement für die API-Ebene. Sie können die Einstellung verwenden, um die Dokumentation nur für die Teile der API anzuzeigen, die tatsächlich für Ihre Anwendung zugänglich sind, basierend auf der API-Ebene, die im Attribut android:minSdkVersion der Manifestdatei festgelegt ist.
Wählen Sie zum Verwenden der Filter die von Ihrer Anwendung angegebene API-Ebene aus dem Menü aus. APIs, die auf einer späteren API-Ebene eingeführt werden, werden dann ausgegraut und ihr Inhalt wird maskiert, da sie für die Anwendung nicht zugänglich sind.
Das Filtern nach API-Ebene in der Dokumentation bietet keine Übersicht darüber, was auf den einzelnen API-Ebenen neu ist oder eingeführt wurde. Damit lässt sich die gesamte API aufrufen, die einer bestimmten API-Ebene zugeordnet ist. Dabei werden API-Elemente ausgeschlossen, die auf späteren API-Ebenen eingeführt werden.
Wenn Sie zur vollständigen Dokumentation zurückkehren möchten, wählen Sie oben im Menü der API-Ebene REL aus. Standardmäßig ist die Filterung auf API-Ebene deaktiviert, sodass Sie unabhängig vom API-Level die gesamte Framework-API anzeigen können.
Die Referenzdokumentation für einzelne API-Elemente gibt die API-Ebene an, 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 „Auf API-Ebene hinzugefügt“ angegeben. Die API-Ebene für Klassenmitglieder wird in den detaillierten Beschreibungsüberschriften am rechten Rand angegeben.