SDK-Erweiterungen

SDK-Erweiterungen nutzen modulare System komponenten, um dem öffentlichen SDK APIs für bestimmte zuvor veröffentlichte API-Levels hinzuzufügen. Diese APIs werden auf Geräten bereitgestellt, wenn Endnutzer Modulupdates über Google Play-Systemupdates erhalten. App-Entwickler können diese APIs in ihren Apps verwenden, um zusätzliche Funktionen bereitzustellen, die in den vorherigen Versionen von Android ursprünglich nicht im SDK verfügbar waren.

API-Versionierung

Ab Android 11 (API-Level 30) enthalten Android-Geräte eine Reihe von SDK-Erweiterungen. Wenn neue APIs hinzugefügt werden, sind sie in einem API-Level enthalten, können aber auch in einer SDK-Erweiterung einer bestimmten Version enthalten sein. Die ACTION_PICK_IMAGES API für die Bildauswahl wurde beispielsweise in Android 13 (API-Level 33) dem öffentlichen SDK hinzugefügt, ist aber auch über SDK-Erweiterungen ab Version 2 der R-Erweiterungen verfügbar. SDK-Erweiterungsnamen entsprechen einer ganzzahligen Konstanten, entweder einer Konstanten aus Build.VERSION_CODES oder einer in der SdkExtensions Klasse definierten Konstanten (wie SdkExtensions.AD_SERVICES).

Zu verwendende SDK-Erweiterungen bestimmen

Bevor Sie SDK-Erweiterungs-APIs verwenden können, müssen Sie zuerst festlegen, welche SDKs die APIs enthalten, die die Anwendungsfälle Ihrer App unterstützen.

Auf den API-Referenzseiten für SDK-Erweiterungs-APIs ist die früheste SDK-Erweiterungsversion angegeben, die Ihre App verwenden kann, um auf eine API zuzugreifen. Wenn in der Dokumentation auch eine Android-Plattformversion (referenziert durch das API-Level) angegeben ist, ist diese API auch für alle Geräte verfügbar, auf denen diese Android-Version oder höher ausgeführt wird.

ACTION_PICK_IMAGES ist beispielsweise ab Android 13 (API-Level 33) allgemein im öffentlichen SDK verfügbar, aber auch auf Geräten mit Android 11 (API-Level 30) verfügbar, sofern das Gerät mindestens Version 2 der R-Erweiterungen hat:

Bei APIs, die Teil von SDK-Erweiterungen sind, wird die Erweiterungsversion in der API-Referenzdokumentation angezeigt.

Um diese API zu verwenden, müssen Sie mit einem SDK kompilieren, das mindestens API-Level 33 oder Erweiterungslevel 2 hat.

So verwenden Sie ein Erweiterungs-SDK:

  1. Suchen Sie die erforderliche Mindestversion der Erweiterungen, indem Sie die Dokumentation zu den Funktionen und die API-Referenz für die APIs prüfen, die Sie verwenden möchten.
  2. Nachdem Sie die erforderliche Erweiterungsversion für Ihr Feature-Set festgelegt haben, öffnen Sie den SDK-Manager in Android Studio.
  3. Wählen Sie den Eintrag „Android SDK Platform“ mit der entsprechenden Erweiterungsversion oder einer höheren Version aus, da die APIs additiv sind. Beispiel: Android SDK Platform 33, Erweiterungslevel 4.

  4. Deklarieren Sie diese Werte in der build.gradle.kts oder build.gradle Datei Ihrer App:

    Groovy

    android {
    compileSdk 33
    compileSdkExtension 4
    ...
}

    Kotlin

    android {
    compileSdk = 33
    compileSdkExtension = 4
    ...
}

Verfügbarkeit von SDK-Erweiterungen prüfen

Ihre App kann zur Laufzeit prüfen, welche SDK-Erweiterungsversionen verfügbar sind. Während der Entwicklung können Sie die Erweiterungsversionen mit Android Debug Bridge-Befehlen (adb) suchen, wie in den folgenden Abschnitten beschrieben.

Zur Laufzeit prüfen

Ihre App kann zur Laufzeit prüfen, ob SDK-Erweiterungen für eine gegebene Plattformversion mit der getExtensionVersion() Methode verfügbar sind. Mit dem folgenden Code wird beispielsweise geprüft, ob die Erweiterungsversion 2 oder höher für die SDK-Erweiterung für Android 11 (API-Level 30) verfügbar ist:

Kotlin

fun isPhotoPickerAvailable(): Boolean {
    return SdkExtensions.getExtensionVersion(Build.VERSION_CODES.R) >= 2
    // Safely use extension APIs that are available with Android 11 (API level 30) Extensions Version 2, such as Photo Picker.
}

Java

public static final boolean isPhotoPickerAvailable() {
    return SdkExtensions.getExtensionVersion(Build.VERSION_CODES.R) >= 2;
}

Dies ähnelt einer Prüfung basierend auf Build.VERSION.SDK_INT:

Kotlin

fun isPhotoPickerAvailable(): Boolean {
    return Build.VERSION.SDK_INT >= 33
}

Java

public static final boolean isPhotoPickerAvailable() {
    return Build.VERSION.SDK_INT >= 33;
}

Diese SDK_INT-Prüfung ist weiterhin sicher und gültig, aber isPhotoPickerAvailable würde auf einigen Geräten „false“ zurückgeben, obwohl die Erweiterungs-API verfügbar ist. Daher ist die SDK_INT-Prüfung nicht optimal und die Prüfung der Erweiterungsversion ist eine bessere Möglichkeit, die API-Verfügbarkeit zu prüfen. Auf allen Geräten mit SDK_INT größer oder gleich 33 (Android 13 oder höher) sind die APIs der Bildauswahl im öffentlichen SDK verfügbar. Es gibt aber auch Geräte mit SDK_INT kleiner als 33 (z. B. Android 11, 12 und 12L), die ebenfalls auf die APIs zugreifen könnten, wenn sie R-Erweiterungsversionen von mindestens 2 haben.

In diesem Fall kann eine Prüfung der Erweiterungsversion dazu beitragen, dass Ihre App mehr Nutzern zusätzliche Funktionen bietet. Eine Liste aller Konstanten, mit denen Sie auf einem Gerät nach bestimmten SDK-Erweiterungen suchen können, finden Sie unter Namen und Konstanten von SDK-Erweiterungen.

Erweiterungen für Anzeigendienste

Ähnlich wie bei den allgemeinen SDK-Erweiterungen wird in der AdServices-API-Referenz manchmal angegeben, dass eine API Teil einer Version der „Erweiterungen für Anzeigendienste“ ist. Im Gegensatz zu den allgemeinen SDK-Erweiterungen verwenden die Erweiterungen für Anzeigendienste die Konstante SdkExtensions.AD_SERVICES, um zu bestimmen, welche Version auf einem Gerät vorhanden ist:

Kotlin

fun isAdServicesAvailable(): Boolean {
    return SdkExtensions.getExtensionVersion(SdkExtensions.AD_SERVICES) >= 4
}

Java

public static final boolean isAdServicesAvailable() {
    return SdkExtensions.getExtensionVersion(SdkExtensions.AD_SERVICES) >= 4;
}

Weitere Informationen zu den Funktionen in den Erweiterungen für Anzeigendienste und zu den ersten Schritten finden Sie in der Dokumentation zu den Erweiterungen für Anzeigendienste.

Dienstmethoden

In einigen Fällen haben SDK-Erweiterungen Jetpack-Dienstmethoden, mit denen die Verfügbarkeit ihrer SDK-Erweiterungs-APIs geprüft werden kann. Sie können beispielsweise eine Jetpack -Bibliotheksfunktion verwenden, um die Verfügbarkeit der Bildauswahl zu prüfen, wodurch die bedingten Versionsprüfungen abstrahiert werden.

Tool-Unterstützung

In Android Studio Flamingo | 2022.2.1 oder höher kann das Lint-Tool im Rahmen der NewAPI-Prüfung nach Problemen mit SDK-Erweiterungsversionen suchen. Außerdem kann Android Studio die korrekten Versionsprüfungen für APIs automatisch generieren, die mit SDK-Erweiterungen gestartet werden.

Das Lint-Tool kennzeichnet Fälle, in denen die erforderliche Mindestversion der SDK-Erweiterungen zum Aufrufen einer API nicht erfüllt ist.

Namen und Konstanten von SDK-Erweiterungen

In der folgenden Tabelle wird beschrieben, wie die verschiedenen Gruppen von SDK-Erweiterungen, die in der API-Referenzdokumentation aufgeführt sind, Konstanten zugeordnet werden, mit denen Ihre App zur Laufzeit die API-Verfügbarkeit prüfen kann. Die allgemeine Gruppe von SDK-Erweiterungen für jedes öffentliche SDK wird Werten von Build.VERSION_CODES zugeordnet.

Name der SDK-Erweiterung Konstante Berechtigte Geräte
R-Erweiterungen VERSION_CODES.R Android 11 (API-Level 30) und höher
S-Erweiterungen VERSION_CODES.S Android 12 (API-Level 31) und höher
T-Erweiterungen VERSION_CODES.TIRAMISU Android 13 (API-Level 33) und höher
U-Erweiterungen VERSION_CODES.UPSIDE_DOWN_CAKE Android 14 (API-Level 34) und höher
V-Erweiterungen VERSION_CODES.VANILLA_ICE_CREAM Android 15 (API-Level 35) und höher
B-Erweiterungen VERSION_CODES.BAKLAVA Android 16 (API-Level 36) und höher
C-Erweiterungen VERSION_CODES.CINNAMON_BUN Android 17 (API-Level 37) und höher
Erweiterungen für Anzeigendienste SdkExtensions.AD_SERVICES Android 13 (API-Level 33) und höher

Mit adb prüfen

Führen Sie den folgenden Befehl aus, um zu prüfen, welche SDK-Erweiterungen auf einem Gerät mit adb verfügbar sind:

adb shell getprop | grep build.version.extensions

Nach der Ausführung des Befehls wird eine Ausgabe angezeigt, die in etwa so aussieht:

[build.version.extensions.r]: [3] # Android 11 (API level 30) and higher
[build.version.extensions.s]: [3] # Android 12 (API level 31) and higher
[build.version.extensions.t]: [3] # Android 13 (API level 33) and higher

Jede Zeile zeigt eine SDK-Erweiterung, die auf dem Gerät vorhanden ist, zusammen mit der entsprechenden Erweiterungsversion (in diesem Fall 3).