SDK Extensions

SDK 拡張機能は、モジュラー システム コンポーネントを利用して、以前リリースされた特定の API レベルの API を公開 SDK に追加します。これらの API は、エンドユーザーが Google Play システム アップデートを通じてモジュール アップデートを受信したときに、デバイスに配信されます。アプリ デベロッパーは、アプリでこれらの API を利用することで、以前のバージョンの Android の SDK では使用できなかった追加機能を提供できます。

API のバージョン管理

Android 11（API レベル 30）以降では、Android デバイスに SDK 拡張機能のセットが含まれています。新しい API が追加されると特定の API レベルに追加されますが、特定のバージョンの SDK 拡張機能にも追加される場合があります。たとえば、写真選択ツール用の ACTION_PICK_IMAGES API は、Android 13（API レベル 33）で公開 SDK に追加されましたが、R 拡張機能バージョン 2 以降の SDK 拡張機能でも使用可能です。SDK 拡張機能名は整数定数に対応しています。これは、Build.VERSION_CODES の定数または SdkExtensions で定義された定数（SdkExtensions.AD_SERVICES など）のいずれかです。

使用する SDK 拡張機能を決定する

SDK Extension API を使用するには、アプリのユースケースをサポートする API をどの SDK に含めるかを決定する必要があります。

SDK Extension API の API リファレンス ページには、アプリが API へのアクセスに使用できる SDK 拡張機能の最小バージョンが規定されています。（API レベルによって参照される）Android プラットフォームのバージョンもドキュメントで規定されている場合、その API は、そのバージョン以降の Android を搭載したすべてのデバイスでも使用可能です。

たとえば、ACTION_PICK_IMAGES は一般的に Android 13（API レベル 33）以降の公開 SDK で使用可能ですが、R 拡張機能バージョン 2 以上が搭載されていれば、Android 11（API レベル 30）以上のデバイスでも使用可能です。

API リファレンス ドキュメントには、SDK 拡張機能に含まれる API の拡張機能バージョンが示されています

この API を使用するには、API レベル 33 以上、または拡張機能レベル 2 以上の SDK でコンパイルする必要があります。

拡張機能 SDK を使用する手順は次のとおりです。

  1. 機能のドキュメントと、使用する API の API リファレンスを確認して、必要な拡張機能の最小バージョンを見つけます。
  2. 使用する機能セットに必要な拡張機能バージョンを決定したら、Android Studio で SDK Manager を開きます。
  3. 対応する拡張機能バージョン（または、API の追加であるため、それより上位のバージョン）の Android SDK Platform エントリを選択します。たとえば、Android SDK Platform 33、拡張機能レベル 4 を選択します。

  4. アプリの build.gradle.kts または build.gradle ファイルで次の値を宣言します。

    Groovy

    android {
    compileSdk 33
    compileSdkExtension 4
    ...
}

    Kotlin

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

SDK 拡張機能が使用可能かどうかを確認する

アプリでは、使用可能な SDK 拡張機能バージョンを実行時に確認できます。開発中は、後半のセクションで説明するように、Android Debug Bridge（adb）コマンドを使用して拡張機能バージョンを検索できます。

実行時に確認する

アプリでは、getExtensionVersion() メソッドを使用して、特定のプラットフォーム バージョンで SDK 拡張機能が使用可能かどうかを実行時に確認できます。たとえば、次のコードは、Android 11（API レベル 30）の SDK 拡張機能で拡張機能バージョン 2 以上が使用可能かどうかを確認します。

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

これは、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;
}

この SDK_INT チェックは安全かつ有効ですが、一部のデバイスでは、拡張機能 API が使用可能であっても isPhotoPickerAvailable は false を返します。したがって、SDK_INT チェックは最善の方法ではなく、API の可用性を確認する方法としては拡張機能バージョン チェックの方が適切です。SDK_INT が 33 以上（Android 13 以降）のすべてのデバイスでは公開 SDK に写真選択ツール API が含まれていますが、SDK_INT が 33 未満（Android 11、12、12L など）のデバイスでも、R 拡張機能バージョンが 2 以上であれば写真選択ツール API にアクセスできます。

この場合、拡張機能バージョン チェックを使用すると、アプリはより多くのユーザーに追加機能を提供できます。デバイス上の特定の SDK 拡張機能を確認するために使用できるすべての定数のリストについては、SDK 拡張機能名と定数をご覧ください。

広告サービス拡張機能

SDK 拡張機能の一般的なセットと同様に、AdServices API リファレンスでは、API が「広告サービス拡張機能」バージョンの一部であると示されていることがあります。一般的な SDK 拡張機能とは異なり、広告サービス拡張機能は、SdkExtensions.AD_SERVICES 定数を使用してデバイス上に存在するバージョンを確認します。

Kotlin

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

Java

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

広告サービス拡張機能に含まれる機能と利用方法について詳しくは、広告サービス拡張機能のドキュメントをご覧ください。

ユーティリティ メソッド

SDK 拡張機能には、SDK Extension API の可用性を確認するための Jetpack ユーティリティ メソッドが含まれている場合があります。たとえば、Jetpack ライブラリ関数を使用して PhotoPicker の可用性を確認できます。これにより、条件付きバージョン チェックが抽象化されます。

ツールサポート

Android Studio Flamingo | 2022.2.1 以降では、lint ツールの NewAPI チェックの一環として、SDK 拡張機能バージョンに関する問題をスキャンできます。さらに、Android Studio では、SDK 拡張機能で起動される API の適正バージョン チェックを自動生成できます。

lint ツールは、API の呼び出しに必要な SDK 拡張機能の最小バージョン要件を満たしていないインスタンスにフラグを設定します。

SDK 拡張機能名と定数

API リファレンス ドキュメントに記載されている SDK 拡張機能のセットと、アプリが実行時に API の可用性を確認するために使用できる定数とのマッピングを次の表に示します。個々の公開 SDK の SDK 拡張機能の一般的なセットは、Build.VERSION_CODES の値にマッピングされます。

SDK 拡張機能名 定数 対象のデバイス
R 拡張機能 VERSION_CODES.R Android 11（API レベル 30）以降
S 拡張機能 VERSION_CODES.S Android 12（API レベル 31）以降
T 拡張機能 VERSION_CODES.TIRAMISU Android 13（API レベル 33）以降
広告サービス拡張機能 SdkExtensions.AD_SERVICES Android 13（API レベル 33）以降

adb で確認する

デバイスで使用可能な SDK 拡張機能を adb で確認するには、次のコマンドを実行します。

adb shell getprop | grep build.version.extensions

コマンドを実行すると、次のような出力が表示されます。

[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

各行には、デバイス上に存在する SDK 拡張機能と、それに対応する拡張機能バージョン（この場合は 3）が表示されます。