SDK-Erweiterungen

SDK-Erweiterungen nutzen modulare Systemkomponenten, um dem öffentlichen SDK APIs für bestimmte zuvor veröffentlichte API-Ebenen hinzuzufügen. Diese APIs werden an Geräte gesendet, wenn Endnutzer über Google Play-Systemupdates Modulupdates erhalten. App-Entwickler können diese APIs in ihren Apps verwenden, um zusätzliche Funktionen bereitzustellen, die ursprünglich nicht im SDK für diese älteren Android-Versionen 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 einer API-Ebene enthalten, können aber auch in einer SDK-Erweiterung einer bestimmten Version enthalten sein. Beispielsweise wurde die ACTION_PICK_IMAGES API für die Bildauswahl in Android 13 (API-Level 33) in das öffentliche SDK aufgenommen, ist aber auch über SDK-Erweiterungen ab R Extensions Version 2 verfügbar. SDK-Erweiterungsnamen entsprechen einer Ganzzahlkonstanten – entweder einer Konstante aus Build.VERSION_CODES oder einer in der Klasse SdkExtensions definierten Konstanten (z. B. SdkExtensions.AD_SERVICES).

SDK-Erweiterungen auswählen

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

Auf den API-Referenzseiten für SDK-Erweiterungs-APIs wird die früheste SDK-Erweiterungsversion angegeben, mit der Ihre App auf eine API zugreifen kann. Wenn in der Dokumentation auch eine Android-Plattformversion angegeben ist (auf die über das API-Level verwiesen wird), ist diese API auch für alle Geräte verfügbar, auf denen diese Android-Version oder eine höhere Version 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), sofern das Gerät mindestens R Extensions Version 2 hat:

Wenn Sie diese API verwenden möchten, müssen Sie sie mit einem SDK kompilieren, das mindestens API-Level 33 oder Erweiterungslevel 2 hat.

So verwenden Sie ein Erweiterungs-SDK:

1. Die Mindestversion der Erweiterungen finden Sie in der Funktionsdokumentation und API-Referenz der APIs, die Sie verwenden möchten.
2. Nachdem Sie die erforderliche Erweiterungsversion für Ihre Funktionen ermittelt 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, da die APIs additiv sind) aus. Beispiel: Android SDK-Plattform 33, Erweiterungsebene 4.

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

   Groovy

   android {
       compileSdk 33
       compileSdkExtension 4
       ...
   }
   

   Kotlin

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

Prüfen, ob SDK-Erweiterungen verfügbar sind

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

Bei der Laufzeit prüfen

Ihre App kann mithilfe der Methode getExtensionVersion() prüfen, ob SDK-Erweiterungen für eine bestimmte Plattformversion 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:

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.
}

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

Das entspricht einer Prüfung basierend auf Build.VERSION.SDK_INT:

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

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 „falsch“ zurückgeben, obwohl die Erweiterungs-API verfügbar ist. Daher ist die Prüfung mit SDK_INT nicht optimal. Die Prüfung der Erweiterungsversion ist eine bessere Möglichkeit, die API-Verfügbarkeit zu prüfen. Alle Geräte mit einer SDK_INT von mindestens 33 (Android 13 oder höher) haben die APIs der Bildauswahl im öffentlichen SDK. Es gibt jedoch auch Geräte mit einer SDK_INT von unter 33 (z. B. Android 11, 12 und 12L), die ebenfalls auf die APIs zugreifen können, wenn sie R-Erweiterungsversionen von mindestens 2 haben.

In diesem Fall kann die Verwendung einer Erweiterungsversionsüberprüfung 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 Werbedienste

Ä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 Werbedienste“ ist. Im Gegensatz zu den allgemeinen SDK-Erweiterungen wird bei Anzeigendienst-Erweiterungen die Konstante SdkExtensions.AD_SERVICES verwendet, um zu ermitteln, welche Version auf einem Gerät installiert ist:

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

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

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

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 Fotoauswahl zu prüfen. Dabei werden die bedingten Versionsprüfungen abstrahiert.

Support für Tools

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 richtigen Versionsprüfungen für APIs automatisch generieren, die mit SDK-Erweiterungen gestartet werden.

Namen und Konstanten der SDK-Erweiterung

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

Mit adb prüfen

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

adb shell getprop | grep build.version.extensions

Nach der Ausführung des Befehls sehen Sie eine Ausgabe, 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 enthält eine SDK-Erweiterung, die auf dem Gerät vorhanden ist, sowie die entsprechende Erweiterungsversion (in diesem Fall 3).