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 のセットアップに関する記事を参照してください。

Note

2021 年 8 月以降、Google Play Console は、新しいアプリについて、API レベル 30 (Android 11.0) 以上をターゲットにすることを要求します。 既存のアプリは、2021 年 11 月から API レベル 30 以上をターゲットにする必要があります。 詳細については、Play Console のドキュメントの「アプリを作成して設定する」に掲載の Play Console の対象 API レベル要件を参照してください。

通常、3 つの Xamarin.Android API レベルはすべて同じ値に設定されています。 [アプリケーション] ページで、[Android バージョンを使用したコンパイル: (ターゲット フレームワーク)] を最新の安定した API バージョン (または少なくとも必要なすべての機能がある Android バージョン) に設定します。 次のスクリーン ショットでは、ターゲット フレームワークは Android 7.1 (API Level 25 - Nougat) に設定されています。

Target Framework version defaults to Compile using Android version

[Android マニフェスト] ページで、[最小 Android バージョン] を [SDK バージョンを使用したコンパイルの使用] に設定し、[ターゲット Android のバージョン] を [ターゲット フレームワーク] バージョンと同じ値に設定します (次のスクリーンショットでは、ターゲット Android のフレームワークが Android 7.1 (Nougat) に設定されています)。

Minimum and Target Android versions set to Target Framework version

前のバージョンの Android との下位互換性を維持する場合は、ターゲットにする [最小 Android バージョン] をアプリでサポートする対象の最も古い Android バージョンに設定します。 (API レベル 14 は、Google Play サービスと Firebase サポートに必要な最小 API レベルであることに注意してください)。次の構成例では、API レベル 14 から API レベル 25 までの Android バージョンがサポートされます。

Compile using API level 25 Nougat, Minimum Android version set to API level 14

アプリで複数の Android バージョンをサポートする場合は、アプリが [最小 Android バージョン] 設定で動作するように、コードに実行時チェックを含める必要があります (詳細については、以下の「Android バージョンの実行時チェック」を参照してください)。 ライブラリを使用または作成する場合は、ライブラリの API レベル設定の構成のベスト プラクティスについて、以下の「API レベルとライブラリ」を参照してください。

Android のバージョンと API レベル

Android プラットフォームが進化し、新しい Android バージョンがリリースされると、各 Android バージョンに "API レベル" と呼ばれる一意の整数識別子が割り当てられます。 そのため、各 Android バージョンは 1 つの Android API レベルに対応します。 ユーザーは Android の古いバージョンにも最新バージョンにもアプリをインストールするため、実際の Android アプリは複数の Android API レベルで動作するように設計する必要があります。

Android のバージョン

Android の各リリースには、複数の名前が付けられています。

  • Android バージョン (Android 9.0 など)
  • コード (またはデザート) 名 (Pie など)
  • 対応する API レベル (API レベル 28 など)

Android コード名は複数のバージョンと API レベルに対応する場合がありますが (以下の表を参照)、各 Android バージョンは厳密に 1 つの API レベルに対応します。

さらに、Xamarin.Android は、現在既知の Android API レベルにマップされる "ビルド バージョン コード" を定義しています。 次の表は、API レベル、Android バージョン、コード名、Xamarin.Android のビルド バージョン コード間の変換に役立ちます (ビルド バージョン コードは Android.OS 名前空間に定義されています)。

名前 バージョン API レベル リリース済み ビルド バージョン コード
Q 10.0 29 2020 年 8 月 BuildVersionCodes.Q
Pie 9.0 28 Aug 2018 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 Nov 2014 BuildVersionCodes.Lollipop
Kitkat Watch 4.4W 20 2014 年 6 月 BuildVersionCodes.KitKatWatch
Kitkat 4.4. 19 2013 年 10 月 BuildVersionCodes.KitKat
Jelly Bean 4.3 18 Jul 2013 BuildVersionCodes.JellyBeanMr2
Jelly Bean 4.2-4.2.2 17 2012 年 11 月 BuildVersionCodes.JellyBeanMr1
Jelly Bean 4.1-4.1.1 16 2012 年 6 月 BuildVersionCodes.JellyBean
Ice Cream Sandwich 4.0.3-4.0.4 15 2011 年 12 月 BuildVersionCodes.IceCreamSandwichMr1
Ice Cream Sandwich 4.0-4.0.2 14 Oct 2011 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
Gingerbread 2.3.3-2.3.4 10 2011 年 2 月 BuildVersionCodes.GingerBreadMr1
Gingerbread 2.3-2.3.2 9 2010 年 11 月 BuildVersionCodes.GingerBread
Froyo 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
Cupcake 1.5 3 2009 年 5 月 BuildVersionCodes.Cupcake
基準 1.1 2 2009 年 2 月 BuildVersionCodes.Base11
基準 1.0 1 2008 年 10 月 BuildVersionCodes.Base

この表に示すように、新しい Android バージョンは頻繁にリリースされます。場合によっては、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 デバイスはユーザーがアプリをインストールするのを阻止します。

プロジェクト API レベルの設定

以降のセクションでは、SDK マネージャーを使用して、ターゲット API レベルの開発環境を準備する方法を説明し、その後に Xamarin.Android で [ターゲット フレームワーク]、[最小 Android バージョン]、および [ターゲット Android のバージョン] の設定を構成する方法の詳細な説明を続けます。

Android SDK プラットフォーム

Xamarin.Android でターゲットまたは最小 API レベルを選択するには、その API レベルに対応する Android SDK プラットフォーム バージョンをインストールする必要があります。 [ターゲット フレームワーク]、[最小 Android バージョン]、および [ターゲット Android のバージョン] に対して使用可能な選択肢の範囲は、インストールした Android SDK バージョンの範囲に制限されます。 SDK マネージャーを使用して、必要な Android SDK バージョンがインストールされていることを確認し、そのバージョンを使用して、アプリに必要な新しい API レベルを追加できます。 API レベルのインストール方法に慣れていない場合は、Android SDK のセットアップに関するページを参照してください。

[対象とする Framework]

[ターゲット フレームワーク] (別名 compileSdkVersion) は、ビルド時にアプリがコンパイル対象にする特定の Android フレームワーク バージョン (API レベル) です。 この設定は、アプリの実行時に使用を "想定する" API を指定しますが、インストール時にアプリが実際に使用できる API には影響しません。 その結果、ターゲット フレームワークの設定を変更しても、実行時の動作は変更されません。

[ターゲット フレームワーク] は、アプリケーションのリンク対象ライブラリ バージョンを識別します。この設定により、アプリで使用できる API が決まります。 たとえば、Android 5.0 Lollipop で導入された NotificationBuilder.SetCategory メソッドを使用する場合は、[ターゲット フレームワーク] を API レベル 21 (Lollipop) 以降に設定する必要があります。 プロジェクトの [ターゲット フレームワーク] を API レベル 19 (KitKat) などの API レベルに設定し、コードで SetCategory メソッドを呼び出そうとすると、コンパイル エラーが発生します。

常に "最新の" 使用可能なターゲット フレームワーク バージョンでコンパイルすることをお勧めします。 これにより、コードによって呼び出される可能性がある非推奨の API に対して有用な警告メッセージが表示されます。 最新のサポート ライブラリ リリースを使用するときは、最新のターゲット フレームワーク バージョンを使用することが特に重要です。各ライブラリは、そのサポート ライブラリの最小 API レベル以上でアプリがコンパイルされることを想定しています。

Visual Studio で [ターゲット フレームワーク] 設定にアクセスするには、ソリューション エクスプローラーでプロジェクトのプロパティを開き、[アプリケーション] ページを選択します。

Application page of project Properties

上記のように、[Android バージョンを使用したコンパイル] のドロップダウン メニューで API レベルを選択して、ターゲット フレームワークを設定します。

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 バージョンを選択できます。

Minimum Android to target option set to Compile using SDK version

[SDK バージョンを使用したコンパイルの使用] を選択した場合、[最小 Android バージョン] は [ターゲット フレームワーク] 設定と同じになります。

ターゲット Android のバージョン

[ターゲット Android のバージョン] (別名 targetSdkVersion) は、アプリの実行が想定される Android デバイスの API レベルです。 Android は、この設定を使用して、互換性動作を有効にするかどうかを決定します。これにより、アプリが引き続き想定どおりに稼働するようになります。 Android は、アプリの [ターゲット Android のバージョン] 設定を使用して、アプリを中断せずに、それに適用できる動作変更を判断します (これが Android が前方互換性を提供する方法です)。

[ターゲット フレームワーク] と [ターゲット Android のバージョン] は、名前は非常に似ていますが、同じものではありません。 [ターゲット フレームワーク] 設定は "コンパイル時" に使用するターゲット API レベル情報を Xamarin.Android に伝達しますが、[ターゲット Android のバージョン] は "実行時" に使用するターゲット API レベル情報を Android に伝達します (アプリがデバイスにインストールされて稼働している場合)。

Visual Studio でこの設定にアクセスするには、ソリューション エクスプローラーでプロジェクトのプロパティを開き、[Android マニフェスト] ページを選択します。 [ターゲット Android のバージョン] のドロップダウン メニューで、アプリケーションのターゲット Android のバージョンを選択できます。

Target Android version set to Compile using SDK version

[ターゲット Android のバージョン] を、アプリのテストに使用する最新バージョンの Android に明示的に設定することをお勧めします。 理想的には、最新の Android SDK バージョンに設定する必要があります。これにより、動作変更に取り組む前に新しい API を使用できます。 ほとんどの開発者には、[ターゲット Android のバージョン] を [SDK バージョンを使用したコンパイルの使用] に設定することはお勧め "しません"。

一般に、[ターゲット 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 ごとに、コードで Android.OS.Build.VERSION.SdkInt プロパティの値を明示的に検査して、アプリが実行されているプラットフォームの API レベルを判断する必要があります。 API レベルが、呼び出す API をサポートする最小 Android バージョン "より低い" 場合、コードは、この API 呼び出しを行わずに適切に機能する方法を見つける必要があります。

たとえば、NotificationBuilder.SetCategory メソッドを使用して、Android 5.0 Lollipop (およびそれ以降) での実行時に通知を分類するが、Android 4.1 Jelly Bean などの前のバージョンの Android (SetCategory を使用できません) でもアプリを実行するとします。 このガイドの冒頭にある Android バージョン表を参照すると、Android 5.0 Lollipop のビルド バージョン コードは Android.OS.BuildVersionCodes.Lollipop です。 SetCategory を使用できない古いバージョンの Android をサポートするために、コードが実行時に API レベルを検出し、API レベルが Lollipop ビルド バージョン コード以上のときのみ、という条件付きで SetCategory を呼び出すことができます。

if (Android.OS.Build.VERSION.SdkInt >= Android.OS.BuildVersionCodes.Lollipop)
{
    builder.SetCategory(Notification.CategoryEmail);
}

この例では、アプリの [ターゲット フレームワーク] は Android 5.0 (API レベル 21) に設定され、[最小 Android バージョン] は Android 4.1 (API レベル 16) に設定されます。 SetCategory が使用できるのは API レベル Android.OS.BuildVersionCodes.Lollipop 以降であるため、このコード例は、実際に使用可能なときにのみ 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 マニフェスト] ページがないためです。

Only the Compile using Android version option is available

結果のライブラリはスタンドアロン アプリではないため、[最小 Android バージョン] と [ターゲット Android のバージョン] 設定は使用できません。ライブラリは、ともにパッケージ化されているアプリに応じて、任意の Android バージョンで実行できます。 ライブラリの "コンパイル" 方法は指定できますが、ライブラリを実行するプラットフォーム API レベルを予測することはできません。 これを念頭に置いて、ライブラリを使用または作成するときは、次のベスト プラクティスに従う必要があります。

  • Android ライブラリの使用時 – アプリケーションで Android ライブラリを使用する場合は、アプリの [ターゲット フレームワーク] 設定を、ライブラリの [ターゲット フレームワーク] 設定 "以上の" API レベルに設定してください。

  • Android ライブラリの作成時 – 他のアプリケーションで使用するために Android ライブラリを作成する場合は、その [ターゲット フレームワーク] 設定をコンパイルに必要な最小 API レベルに設定してください。

ライブラリが実行時に使用できない API を呼び出そうとする状況 (アプリがクラッシュする可能性がある) を防ぐために、これらのベスト プラクティスをお勧めします。 ライブラリ開発者の場合は、API 呼び出しの使用を、API サーフェス領域全体のうちで、小規模の適切に確立されたサブセットに限定するようにつとめる必要があります。 そうすることで、ライブラリをさまざまな Android バージョンで安全に使用できるようになります。

まとめ

このガイドでは、Android API レベルを使用して、さまざまなバージョンの Android にまたがるアプリの互換性を管理する方法について説明しました。 Xamarin.Android の [ターゲット フレームワーク]、[最小 Android バージョン]、[ターゲット Android のバージョン] の各プロジェクト設定を構成するための詳細な手順を示しました。 Android SDK マネージャーを使用して SDK パッケージをインストールする手順 (実行時にさまざまな API レベルを処理するコードを記述する方法の例を含む) を示し、Android ライブラリを作成または使用するときに API レベルを管理する方法について説明しました。 API レベルを Android のバージョン番号 (Android 4.4 など)、Android バージョン名 (Kitkat など)、Xamarin.Android ビルド バージョン コードに関連付ける包括的な一覧も示しました。