Android API レベルの理解
Xamarin.Android には、複数のバージョンの Android とのアプリの互換性を決定する Android API レベルの設定がいくつかあります。 このガイドでは、これらの設定の意味、それらを構成する方法、実行時にアプリに及ぼす影響について説明します。
クイック スタート
Xamarin.Android では、次の 3 つの Android API レベルのプロジェクト設定が公開されています。
ターゲット フレームワーク – アプリケーションのビルドに使用するフレームワークを指定します。 この API レベルは、Xamarin.Android によって コンパイル 時に使用されます。
[最小 Android バージョン] – アプリでサポートする最も古い Android バージョンを指定します。 この API レベルは、Android によって 実行時 に使用されます。
ターゲット Android バージョン – アプリの実行を目的とした Android のバージョンを指定します。 この API レベルは、Android によって 実行時 に使用されます。
プロジェクトの API レベルを構成する前に、その API レベルの SDK プラットフォーム コンポーネントをインストールする必要があります。 Android SDK コンポーネントのダウンロードとインストールの詳細については、「 Android SDK のセットアップ」を参照してください。
注意
2021 年 8 月以降、Google Play コンソールでは、新しいアプリで API レベル 30 (Android 11.0) 以降をターゲットにする必要があります。 既存のアプリは、2021 年 11 月以降に API レベル 30 以上をターゲットにする必要があります。 詳細については、Play コンソールのドキュメントの「アプリの作成と設定」の「 Play コンソールのターゲット API レベルの要件 」を参照してください。
通常、3 つの Xamarin.Android API レベルはすべて同じ値に設定されます。 [ アプリケーション ] ページで、[ Android バージョン (ターゲット フレームワーク) を使用してコンパイルする] を最新の安定した API バージョン (または、必要なすべての機能を備えた Android バージョン) に設定します。 次のスクリーンショットでは、ターゲット フレームワークが Android 7.1 (API レベル 25 - Nougat) に設定されています。
[ Android マニフェスト ] ページで、[Android の最小バージョン] を [SDK バージョンを使用してコンパイルを使用 する] に設定し、[ターゲット Android バージョン] をターゲット フレームワークのバージョンと同じ値に設定します (次のスクリーンショットでは、Target Android Framework は Android 7.1 (Nougat) に設定されています)。
以前のバージョンの Android との下位互換性を維持する場合は、アプリでサポートする Android の最も古いバージョンをターゲットに [ Android の最小バージョン ] を設定します。 (API レベル 14 は 、Google Play サービスと Firebase サポートに必要な最小 API レベルであることに注意してください)。次の構成例では、API レベル 14 から API レベル 25 までの Android バージョンがサポートされています。
![最小バージョンとターゲット バージョンが [自動] に設定されている - ターゲット フレームワークのバージョンを使用する](android-api-levels-images/xs-minimum.png#lightbox)
アプリで複数の Android バージョンがサポートされている場合は、アプリが [Android の最小バージョン] 設定で動作することを確認するためのランタイム チェックをコードに含める必要があります (詳細については、以下 の「Android バージョンのランタイム チェック 」を参照してください)。 ライブラリを使用または作成する場合は、ライブラリの API レベル 設定を構成する際のベスト プラクティスについては、以下の「API レベルとライブラリ」を参照してください。
Android のバージョンと API レベル
Android プラットフォームが進化し、新しい Android バージョンがリリースされると、各 Android バージョンには API レベルと呼ばれる一意の整数識別子が割り当てられます。 そのため、各 Android バージョンは 1 つの Android API レベルに対応します。 ユーザーは古いバージョンと最新バージョンの Android にアプリをインストールするため、実際の Android アプリは複数の Android API レベルで動作するように設計されている必要があります。
Android バージョン
Android の各リリースには、複数の名前が付きます。
- Android 9.0 などの Android バージョン
- コード (またはデザート) 名 (Pie など)
- 対応する API レベル (API レベル 28 など)
Android コード名は複数のバージョンと API レベルに対応している場合がありますが (下の表を参照)、各 Android バージョンは 1 つの API レベルに完全に対応しています。
さらに、Xamarin.Android では、現在既知の Android API レベルにマップされる ビルド バージョン コード が定義されています。 次の表は、API レベル、Android バージョン、コード名、Xamarin.Android ビルド バージョン コード間の変換に役立ちます (ビルド バージョン コードは名前空間で Android.OS 定義されています)。
| 名前 | Version | API レベル | リリース済み | ビルド バージョン コード |
|---|---|---|---|---|
| Q | 10.0 | 29 | 2020 年 8 月 | BuildVersionCodes.Q |
| Pie | 9.0 | 28 | 2018 年 8 月 | BuildVersionCodes.P |
| Oreo | 8.1 | 27 | 2017 年 12 月 | BuildVersionCodes.OMr1 |
| Oreo | 8.0 | 26 | 2017 年 8 月 | BuildVersionCodes.O |
| Nougat | 7.1 | 25 | 2016 年 12 月 | BuildVersionCodes.NMr1 |
| Nougat | 7.0 | 24 | 2016 年 8 月 | BuildVersionCodes.N |
| Marshmallow | 6.0 | 23 | 2015 年 8 月 | BuildVersionCodes.M |
| Lollipop | 5.1 | 22 | 2015 年 3 月 | BuildVersionCodes.LollipopMr1 |
| Lollipop | 5.0 | 21 | 2014 年 11 月 | BuildVersionCodes.Lollipop |
| キットカット ウォッチ | 4.4W | 20 | 2014 年 6 月 | BuildVersionCodes.KitKatWatch |
| キットカット | 4.4. | 19 | 2013 年 10 月 | BuildVersionCodes.KitKat |
| ジェリービーン | 4.3 | 18 | 2013 年 7 月 | BuildVersionCodes.JellyBeanMr2 |
| ジェリービーン | 4.2-4.2.2 | 17 | 2012 年 11 月 | BuildVersionCodes.JellyBeanMr1 |
| ジェリービーン | 4.1-4.1.1 | 16 | 2012 年 6 月 | BuildVersionCodes.JellyBean |
| アイスクリームサンドイッチ | 4.0.3-4.0.4 | 15 | 2011 年 12 月 | BuildVersionCodes.IceCreamSandwichMr1 |
| アイスクリームサンドイッチ | 4.0-4.0.2 | 14 | 2011 年 10 月 | BuildVersionCodes.IceCreamSandwich |
| ハニカム | 3.2 | 13 | 2011 年 6 月 | BuildVersionCodes.HoneyCombMr2 |
| ハニカム | 3.1.x | 12 | 2011 年 5 月 | BuildVersionCodes.HoneyCombMr1 |
| ハニカム | 3.0.x | 11 | 2011 年 2 月 | BuildVersionCodes.HoneyComb |
| ジンジャーブレッド | 2.3.3-2.3.4 | 10 | 2011 年 2 月 | BuildVersionCodes.GingerBreadMr1 |
| ジンジャーブレッド | 2.3-2.3.2 | 9 | 2010 年 11 月 | BuildVersionCodes.GingerBread |
| フローズン ヨーグルト | 2.2.x | 8 | 2010 年 6 月 | BuildVersionCodes.Froyo |
| Eclair | 2.1.x | 7 | 2010 年 1 月 | BuildVersionCodes.EclairMr1 |
| Eclair | 2.0.1 | 6 | 2009 年 12 月 | BuildVersionCodes.Eclair01 |
| Eclair | 2.0 | 5 | 2009 年 11 月 | BuildVersionCodes.Eclair |
| ドーナツ | 1.6 | 4 | 2009 年 9 月 | BuildVersionCodes.Donut |
| カップケーキ | 1.5 | 3 | 2009 年 5 月 | BuildVersionCodes.Cupcake |
| ベース | 1.1 | 2 | 2009 年 2 月 | BuildVersionCodes.Base11 |
| ベース | 1.0 | 1 | 2008 年 10 月 | BuildVersionCodes.Base |
次の表に示すように、新しい Android バージョンは頻繁にリリースされます。場合によっては、1 年に 1 つ以上のリリースがあります。 その結果、アプリを実行する可能性がある Android デバイスのユニバースには、さまざまな古い Android バージョンと新しい Android バージョンが含まれます。 さまざまなバージョンの Android でアプリが一貫して確実に実行されることを保証するにはどうすればよいですか? Android の API レベルは、この問題の管理に役立ちます。
Android API レベル
各 Android デバイスは、 1 つの API レベルで実行されます。この API レベルは、Android プラットフォームのバージョンごとに一意であることが保証されます。 API レベルは、アプリが呼び出すことができる API セットのバージョンを正確に識別します。マニフェスト要素、アクセス許可などの組み合わせを識別します。開発者としてコーディングする。 Android の API レベルのシステムは、デバイスにアプリケーションをインストールする前に、アプリケーションが Android システム イメージと互換性があるかどうかを Android が判断するのに役立ちます。
アプリケーションがビルドされると、次の API レベルの情報が含まれます。
アプリを実行するためにビルドされる Android の ターゲット API レベル。
Android デバイスでアプリを実行するために必要な 最小 Android API レベル。
これらの設定は、インストール時にアプリを正しく実行するために必要な機能を Android デバイスで使用できるようにするために使用されます。 そうでない場合、アプリはそのデバイスでの実行をブロックされます。 たとえば、Android デバイスの API レベルが、アプリに指定した最小 API レベルよりも低い場合、Android デバイスではユーザーがアプリをインストールできなくなります。
Project API レベルの設定
次のセクションでは、SDK マネージャーを使用して、ターゲットにする API レベルの開発環境を準備する方法と、Xamarin.Android で Target Framework、 Minimum Android バージョン、Target Android バージョン 設定を構成する方法の詳細な説明について説明します。
Android SDK プラットフォーム
Xamarin.Android で [ターゲット] または [最小 API] レベルを選択する前に、その API レベルに対応する Android SDK プラットフォーム バージョンをインストールする必要があります。 Target Framework、Minimum Android バージョン、および Target Android バージョンで使用可能な選択肢の範囲は、インストールした Android SDK のバージョンの範囲に制限されます。 SDK Manager を使用して、必要な Android SDK バージョンがインストールされていることを確認し、それを使用して、アプリに必要な新しい API レベルを追加できます。 API レベルをインストールする方法に慣れていない場合は、「 Android SDK のセットアップ」を参照してください。
[対象とする Framework]
ターゲット フレームワーク (とも呼ばれますcompileSdkVersion) は、アプリがビルド時にコンパイルされる特定の Android フレームワーク バージョン (API レベル) です。 この設定では 、アプリの 実行時に使用する API を指定しますが、インストール時にアプリで実際に使用できる API には影響しません。 その結果、ターゲット フレームワークの設定を変更しても、ランタイムの動作は変更されません。
ターゲット フレームワークは、アプリケーションがリンクされているライブラリ のバージョンを識別します。この設定によって、アプリで使用できる API が決まります。 たとえば、Android 5.0 Lollipop で導入された NotificationBuilder.SetCategory メソッドを使用する場合は、ターゲット フレームワークを API レベル 21 (ロリポップ) 以降に設定する必要があります。 プロジェクトの Target Framework を API レベル 19 (KitKat) などの API レベル に設定し、コードで メソッドを SetCategory 呼び出そうとすると、コンパイル エラーが発生します。
常に、使用可能な最新のターゲット フレームワーク バージョンを使用してコンパイルすることをお勧めします。 これにより、コードによって呼び出される可能性がある非推奨の API に対して役立つ警告メッセージが表示されます。 最新のサポート ライブラリ リリースを使用する場合は、最新の Target Framework バージョンの使用が特に重要です。各ライブラリでは、そのサポート ライブラリの最小 API レベル以上でアプリがコンパイルされることを想定しています。
Visual Studio の [ターゲット フレームワーク] 設定にアクセスするには、ソリューション エクスプローラーでプロジェクトのプロパティを開き、[アプリケーション] ページを選択します。
![プロジェクトの [プロパティ] の [アプリケーション] ページ](android-api-levels-images/vs-target-framework.png#lightbox)
上記のように、[ Android バージョンを使用してコンパイル する] のドロップダウン メニューで API レベルを選択して、ターゲット フレームワークを設定します。
![[プロジェクト オプション] ページの [ビルド全般] セクション](android-api-levels-images/xs-target-framework.png#lightbox)
Android の最小バージョン
最小 Android バージョン (とも呼ばれますminSdkVersion) は、アプリケーションをインストールして実行できる Android OS の最も古いバージョン (つまり、最も低い API レベル) です。 既定では、アプリはターゲット フレームワーク設定以上に一致するデバイスにのみインストールできます。[Android の最小バージョン] 設定が [ターゲット フレームワーク] 設定よりも 低い 場合は、アプリを以前のバージョンの Android でも実行できます。 たとえば、ターゲット フレームワークを Android 7.1 (Nougat) に設定し、Android の最小バージョンを Android 4.0.3 (Ice Cream Sandwich) に設定すると、API レベル 15 から API レベル 25 までの任意のプラットフォームにアプリをインストールできます。
アプリは、この範囲のプラットフォームで正常にビルドおよびインストールできますが、これらのプラットフォームすべてで正常に 実行 されるとは限りません。 たとえば、アプリが Android 5.0 (Lollipop) にインストールされていて、コードが Android 7.1 (Nougat) 以降でのみ使用できる API を呼び出すと、アプリにランタイム エラーが発生し、クラッシュする可能性があります。 そのため、コードは実行時に、実行されている Android デバイスでサポートされている API のみを呼び出す必要があります。 言い換えると、コードには明示的なランタイム チェックを含める必要があります。これにより、アプリで新しい API をサポートできる最新のデバイスでのみ使用されるようにする必要があります。 このガイドで後述する Android バージョンのランタイム チェックでは、これらのランタイム チェックをコードに追加する方法について説明します。
Visual Studio で [Android の最小バージョン] 設定にアクセスするには、ソリューション エクスプローラーでプロジェクトのプロパティを開き、[Android マニフェスト] ページを選択します。 [ Android の最小バージョン ] のドロップダウン メニューで、アプリケーションの [Android の最小バージョン] を選択できます。
![[SDK バージョンを使用してコンパイルする] に設定されたターゲットにする Android の最小オプション](android-api-levels-images/vs-minimum-version.png#lightbox)
[ SDK バージョンを使用してコンパイルを使用する] を選択した場合、Android の最小バージョンは [ターゲット フレームワーク] 設定と同じになります。
![Android の最小バージョンが [自動] に設定されている - ターゲット フレームワークのバージョンを使用する](android-api-levels-images/xs-minimum-version.png#lightbox)
ターゲット Android バージョン
ターゲット Android バージョン (別名targetSdkVersion) は、アプリの実行を想定している Android デバイスの API レベルです。 Android では、この設定を使用して、互換性の動作を有効にするかどうかを決定します。これにより、アプリが期待どおり動作し続けます。 Android では、アプリの [ターゲット Android バージョン] 設定を使用して、アプリに適用できる動作の変更を、中断せずに確認します (これは Android が前方互換性を提供する方法です)。
Target Framework と Target Android のバージョンは、非常に似た名前を持ちながら、同じものではありません。 [ターゲット フレームワーク] 設定では 、コンパイル時に使用するためにターゲット API レベルの情報が Xamarin.Android に伝達され、ターゲット Android バージョンは 実行時 に使用するためにターゲット API レベルの情報を Android に伝えます (アプリがインストールされ、デバイスで実行されている場合)。
Visual Studio でこの設定にアクセスするには、ソリューション エクスプローラーでプロジェクトのプロパティを開き、[Android マニフェスト] ページを選択します。 [ ターゲット Android バージョン ] のドロップダウン メニューで、アプリケーションの [ターゲット Android バージョン] を選択できます。
![[SDK バージョンを使用してコンパイルする] に設定されたターゲット Android バージョン](android-api-levels-images/vs-target-version.png#lightbox)
ターゲット Android のバージョンを、アプリのテストに使用する最新バージョンの Android に明示的に設定することをお勧めします。 理想的には、最新の Android SDK バージョンに設定する必要があります。これにより、動作の変更を処理する前に新しい API を使用できます。 ほとんどの開発者には、ターゲット Android バージョンを SDK バージョンを使用してコンパイルを使用するように設定することはお勧めしません。
![ターゲット Android のバージョンが [自動] に設定されている - ターゲット フレームワークのバージョンを使用する](android-api-levels-images/xs-target-version.png#lightbox)
一般に、ターゲット Android バージョンは、Android の最小バージョンとターゲット フレームワークによって制限される必要があります。 つまり、
Android の最小バージョン <= ターゲット Android バージョン <= ターゲット フレームワーク
SDK レベルの詳細については、Android Developer uses-sdk のドキュメントを参照してください。
Android バージョンのランタイム チェック
Android の新しいバージョンがリリースされるたびに、フレームワーク API が更新され、新しい機能または置換機能が提供されます。 いくつかの例外を除き、以前の Android バージョンの API 機能は、変更なしで新しい Android バージョンに移行されます。 その結果、アプリが特定の Android API レベルで実行されている場合、通常は変更なしで後の Android API レベルで実行できます。 しかし、以前のバージョンの Android でアプリを実行する場合はどうなりますか?
ターゲット フレームワーク設定よりも 低い Android の最小バージョンを選択した場合、実行時に一部の API をアプリで使用できない場合があります。 ただし、アプリは引き続き以前のデバイスで実行できますが、機能は低下します。 Android の最小バージョン設定に対応する Android プラットフォームで使用できない API ごとに、アプリが実行されているプラットフォームの API レベルを決定するには、 プロパティのAndroid.OS.Build.VERSION.SdkInt値を明示的にチェックする必要があります。 API レベルが、呼び出す API をサポートする Android の最小バージョンより 低い 場合、コードは、この API 呼び出しを行わずに適切に機能する方法を見つける必要があります。
たとえば、 NotificationBuilder.SetCategory メソッドを使用して 、Android 5.0 Lollipop (以降) で実行中に通知を分類するが、Android 4.1 Jelly Bean (使用できない) SetCategory などの以前のバージョンの Android でアプリを実行したいとします。 このガイドの冒頭にある Android バージョンの表を参照すると、 Android 5.0 Lollipop のビルド バージョン コードが である Android.OS.BuildVersionCodes.Lollipopことがわかります。 使用できない古いバージョンの Android SetCategory をサポートするために、コードは実行時に API レベルを検出し、API レベルが Lollipop ビルド バージョン コード以上の場合にのみ条件付きで呼び出 SetCategory すことができます。
if (Android.OS.Build.VERSION.SdkInt >= Android.OS.BuildVersionCodes.Lollipop)
{
builder.SetCategory(Notification.CategoryEmail);
}
この例では、アプリの Target Framework が Android 5.0 (API レベル 21) に設定され、その最小 Android バージョンが Android 4.1 (API レベル 16) に設定されています。 は API レベルAndroid.OS.BuildVersionCodes.Lollipop以降で使用できるためSetCategory、このコード例は実際に使用可能な場合にのみ を呼び出SetCategoryします。API レベルが 16、17、18、19、または 20 の場合は呼び出SetCategoryしを試行しません。 これらの以前の Android バージョンでは、通知が適切に並べ替えられていない (種類別に分類されていないため) 限り、機能が低下しますが、通知は引き続き発行されてユーザーに警告されます。 アプリは引き続き機能しますが、その機能は若干低下しています。
一般に、ビルド バージョン チェックは、コードが実行時に、新しい方法と古い方法のどちらを行うのかを決定するのに役立ちます。 次に例を示します。
if (Android.OS.Build.VERSION.SdkInt >= Android.OS.BuildVersionCodes.Lollipop)
{
// Do things the Lollipop way
}
else
{
// Do things the pre-Lollipop way
}
1 つ以上の API がない古い Android バージョンでアプリを実行するときに、アプリの機能を減らすか変更する方法を説明する高速で簡単なルールはありません。 場合によっては (上記の SetCategory 例のように)、API 呼び出しが使用できない場合は省略するだけで十分です。 ただし、他の場合は、アプリが最適なエクスペリエンスを提供するために必要な API レベルよりも小さいと検出された場合 Android.OS.Build.VERSION.SdkInt に、代替機能を実装する必要がある場合があります。
API レベルとライブラリ
Xamarin.Android ライブラリ プロジェクト (クラス ライブラリやバインド ライブラリなど) を作成する場合、ターゲット フレームワークの設定 (Android の最小バージョンとターゲット Android のバージョン設定は使用できません) のみを構成できます。 これは、 Android マニフェスト ページがないためです。
![[Android バージョンを使用してコンパイルする] オプションのみを使用できます](android-api-levels-images/vs-library-options.png#lightbox)
![[最小バージョン] オプションと [ターゲット バージョン] オプションのない [ビルド全般] ページ](android-api-levels-images/xs-library-options.png#lightbox)
結果のライブラリはスタンドアロン アプリではないので、Android の最小バージョンとターゲット Android バージョンの設定は使用できません。ライブラリは、パッケージ化されているアプリに応じて、任意の Android バージョンで実行できます。 ライブラリの コンパイル方法を指定できますが、ライブラリを実行するプラットフォーム API レベルを予測することはできません。 これを念頭に置いて、ライブラリを使用または作成する場合は、次のベスト プラクティスを確認する必要があります。
Android ライブラリを使用する 場合 – アプリケーションで Android ライブラリを使用する場合は、アプリの Target Framework 設定を、ライブラリのターゲット フレームワーク設定と同 じ高さの API レベルに設定してください。
Android ライブラリを作成する 場合 – 他のアプリケーションで使用する Android ライブラリを作成する場合は、そのターゲット フレームワーク設定をコンパイルするために必要な最小 API レベルに設定してください。
これらのベスト プラクティスは、ライブラリが実行時に使用できない API を呼び出そうとする (アプリがクラッシュする可能性がある) 状況を防ぐのに役立ちます。 ライブラリ開発者の場合は、API 呼び出しの使用を、API のサーフェス領域全体の小規模で確立されたサブセットに制限するように努める必要があります。 これにより、ライブラリをさまざまな Android バージョンで安全に使用できるようになります。
まとめ
このガイドでは、Android API レベルを使用して、さまざまなバージョンの Android でアプリの互換性を管理する方法について説明しました。 Xamarin.Android Target Framework、 Minimum Android バージョン、Target Android バージョン のプロジェクト設定を構成するための詳細な手順が提供されました。 Android SDK Manager を使用して SDK パッケージをインストールする手順、実行時にさまざまな API レベルを処理するコードを記述する方法の例、Android ライブラリを作成または使用するときに API レベルを管理する方法について説明しました。 また、API レベルを Android のバージョン番号 (Android 4.4 など)、Android バージョン名 (Kitkat など)、Xamarin.Android ビルド バージョン コードに関連付ける包括的な一覧も提供しました。