Google Play は、アプリ マニフェストで宣言されている <uses-sdk> 属性を使用して、プラットフォームのバージョン要件を満たしていないデバイスからアプリを除外します。これらの属性を設定する前に、Google Play フィルタを十分に理解しておいてください。
- 構文:
<uses-sdk android:minSdkVersion="integer" android:targetSdkVersion="integer" android:maxSdkVersion="integer" />
- 上位の要素:
<manifest>- 説明:
API レベルを示す整数を使用して、アプリが Android プラットフォームの 1 つ以上のバージョンと互換性を持つことを明示できます。アプリによって明示された API レベルは特定の Android システムの API レベルと比較され、それは Android デバイスごとに異なる可能性があります。
この要素はその名前に反して、API レベルを指定するために使用されます。ソフトウェア開発キット（SDK）や Android プラットフォームのバージョン番号を指定するためのものではありません。API レベルは常に 1 つの整数であり、関連付けられている Android バージョン番号から API レベルを取得することはできません。具体的には、メジャー バージョンと同じではなく、メジャー バージョンとマイナー バージョンの合計でもありません。
アプリのバージョン管理に関するドキュメントもご覧ください。
- 属性:
-
android:minSdkVersion- アプリを実行するために必要な最小 API レベルを示す整数。Android システムは、システムの API レベルがこの属性で指定された値よりも低い場合、ユーザーがアプリをインストールできないようにします。この属性は常に宣言します。
注意: この属性を宣言しない場合、システムはデフォルト値を「1」であると見なします。この値は、アプリがすべての Android バージョンと互換性を持つことを示します。アプリが互換性を持たず、なおかつ適切な
minSdkVersionを宣言していなければ、互換性のない API レベルを持つシステムにインストールされた場合、アプリが使用できない API にアクセスしようとすると、実行時にクラッシュします。そのため、必ずminSdkVersion属性で適切な API レベルを宣言するようにしてください。 android:targetSdkVersion- アプリがターゲットとする API レベルを示す整数。設定しない場合、デフォルト値は
minSdkVersionに指定された値になります。この属性により、アプリがターゲット バージョンに対してテストされたこと、アプリのターゲット バージョンとの上位互換性を維持するため、互換性動作を有効にしないことがシステムに伝わります。アプリは、古いバージョン（
minSdkVersion以降）でも引き続き実行できます。Android は新しいバージョンが登場するたびに進化し、動作や外観に変更が加えられることもあります。しかし、プラットフォームの API レベルがアプリの
targetSdkVersionで宣言されたバージョンより高い場合、アプリを引き続き想定どおりに動作させるため、システムにより互換性動作が有効になることがあります。このような互換性動作は、アプリが実行されるプラットフォームの API レベルと一致するようにtargetSdkVersionを指定することで、無効にできます。たとえば、この値を「11」以上に設定すると、システムは Android 3.0 以降で実行されているアプリに対し、デフォルトのテーマとして Holo を適用できます。また、大画面でアプリが実行されているときは、画面互換性モードが無効になります。これは、API レベル 11 では暗黙的に大画面がサポートされるためです。
この属性に設定された値に基づいて、システムが有効にできる互換性動作は数多くあります。そのうちのいくつかの動作は、
Build.VERSION_CODESリファレンスの対応するプラットフォーム バージョンで説明されています。各 Android リリースに合わせてアプリを維持するには、最新の API レベルと一致するようにこの属性の値を増やしたうえで、対応するプラットフォーム バージョンでアプリを十分にテストします。
API レベル 4 で導入
- アプリが動作するように設計されている最大 API レベルを示す整数。
Android 1.5、1.6、2.0、2.0.1 では、アプリのインストール時とシステム アップデート後のアプリの再検証時に、システムがこの属性の値をチェックします。いずれの場合も、アプリの
maxSdkVersion属性がシステム自体で使用される API レベルよりも低ければ、システムはアプリのインストールを許可しません。システム アップデート後に再検証される場合、アプリは事実上デバイスから削除されます。次の例を使用して、この属性がシステム アップデート後にアプリに及ぼす影響について説明します。
マニフェスト内で
maxSdkVersion="5"を宣言しているアプリが Google Play で公開されています。Android 1.6（API レベル 4）を搭載したデバイスで、ユーザーがアプリをダウンロードしてインストールします。数週間後、ユーザーは Android 2.0（API レベル 5）への無線（OTA）システム アップデートを受信します。アップデートがインストールされると、システムはアプリのmaxSdkVersionをチェックし、再検証に成功します。アプリは通常どおり機能しています。しかし、その後しばらくして、デバイスが別のシステム アップデートを受信します。今度は、Android 2.0.1（API レベル 6）へのアップデートです。アップデート後、システム自体の API レベル（6）がアプリでサポートされる最大レベル（5）よりも高くなったため、システムはアプリを再検証できなくなります。システムはアプリがユーザーに表示されないようにして、事実上デバイスからアプリを削除します。
警告: この属性を宣言することはおすすめしません。第 1 に、Android プラットフォームの新しいバージョンがリリースされたときに、新バージョンへのアプリのデプロイをブロックする手段としてこの属性を設定する必要はありません。設計上、プラットフォームの新しいバージョンには完全な下位互換性があります。アプリケーションは、標準の API のみを使用し、開発のベスト プラクティスに準拠していれば、新しいバージョンで適切に動作します。第 2 に、この属性を宣言すると、より高い API レベルへのシステム アップデート後に、ユーザーのデバイスからアプリが削除されてしまう場合があります。アプリがインストールされるであろうデバイスの大半は定期的に無線（OTA）システム アップデートを受信するので、この属性を設定する前に、それがアプリに及ぼす影響を考えてください。
API レベル 4 で導入
Android の一部のバージョン（Android 2.0.1 以降）では、インストールや再検証時にmaxSdkVersion属性のチェックや適用が行われません。ただし、Google Play は、ダウンロード可能なアプリをユーザーに提示する際に、引き続きこの属性をフィルタとして使用します。
- 導入時の API レベル:
- API レベル 1
API レベルとは
API レベルとは、Android プラットフォームのバージョンごとに提供されるフレームワーク API のリビジョンを一意に識別する整数値です。
Android プラットフォームは、アプリが基盤となる Android システムとの通信に使用できるフレームワーク API を提供しています。フレームワーク API は次の要素で構成されます。
- パッケージとクラスのコアセット
- マニフェスト ファイルを宣言するための XML 要素と属性のセット
- リソースを宣言してアクセスするための XML 要素と属性のセット
- インテントのセット
- アプリがリクエストできる権限のセットと、システムに含まれる権限の適用
Android プラットフォームの個々の後続バージョンには、プラットフォームが提供する Android アプリ フレームワーク API のアップデートが含まれる場合があります。
フレームワーク API のアップデートは、新しい API で以前のバージョンの API との互換性が維持されるように設計されています。つまり、API のほとんどの変更は追加的なもので、新機能または代替機能の導入です。API の一部がアップグレードされると、置き換えられた古い部分は非推奨となりますが、削除されることはありません。そのため、既存のアプリはそれらを引き続き使用できます。
API の一部が変更や削除されることもごくまれにありますが、一般的に、そのような変更が行われるのは、API の堅牢性およびアプリやシステムのセキュリティをサポートするのに必要な場合に限られます。API のその他の部分は、すべて以前のリビジョンから変更されずに引き継がれます。
Android プラットフォームが提供するフレームワーク API は、API レベルと呼ばれる整数の識別子で示されます。以前の API レベルはすべて（API レベル 1 まで）暗黙的にサポートされますが、各 Android プラットフォーム バージョンで厳密にサポートされる API レベルは 1 つです。Android プラットフォームの初回リリースでは API レベル 1 が提供され、その後のリリースでは API レベルが増加しました。
次の表に、Android プラットフォームの各バージョンでサポートされている API レベルを示します。各バージョンを搭載しているデバイスの相対数については、配信ダッシュボードをご覧ください。
Android での API レベルの使用
API レベル識別子は、ユーザーとアプリ デベロッパーに対して可能な限り最適なエクスペリエンスを保証するうえで、次のような重要な役割を果たします。
- Android プラットフォームは、サポート対象であるフレームワーク API の最大リビジョンを記述できる
- アプリは、必要とするフレームワーク API のリビジョンを記述できる
- システムは、バージョン互換性のないアプリがインストールされないように、ユーザー デバイスへのアプリのインストールを判断できる
各 Android プラットフォーム バージョンでは、API レベル識別子を Android システム自体に内包しています。
アプリは、フレームワーク API から提供されるマニフェスト要素（<uses-sdk>）を使用して、アプリを実行できる最小および最大 API レベルと、サポートするよう設計されている推奨 API レベルを記述できます。この要素には、次の 3 つの主要な属性があります。
android:minSdkVersion: アプリを実行できる最小 API レベル。デフォルト値は「1」です。android:targetSdkVersion: アプリが動作するように設計されている API レベル。これにより、場合に応じて、アプリが最小 API レベルに対して定義されたものに限らず、対象 API レベルで定義されたマニフェスト要素や動作も使用できるようになります。android:maxSdkVersion: アプリを実行できる最大 API レベル。重要: この属性を使用する前に、このページのこの属性に関する情報をお読みください。
たとえば、アプリの実行に必要な最小システム API レベルを指定するには、アプリのマニフェストに android:minSdkVersion 属性を持つ <uses-sdk> 要素を含めます。android:minSdkVersion の値は、アプリを実行できる最も古いバージョンの Android プラットフォームの API レベルに対応する整数です。
ユーザーがアプリをインストールしようとするとき、またはシステム アップデート後にアプリを再検証するとき、Android システムは最初にアプリのマニフェスト内の <uses-sdk> 属性をチェックし、その値をシステム内部の API レベルと比較します。システムは、次の条件が満たされる場合にのみ、インストールの開始を許可します。
android:minSdkVersion属性が宣言されている場合、その値がシステムの API レベルの整数値以下であること。宣言されていない場合、システムはアプリに必要な API レベルを 1 と見なします。android:maxSdkVersion属性が宣言されている場合、その値がシステムの API レベルの整数値以上であること。宣言されていない場合、システムはアプリに最大 API レベルがないものと見なします。システムによる属性の処理方法については、この属性の説明をご覧ください。
アプリのマニフェスト内で宣言される場合、<uses-sdk> 要素は次のようになります。
<manifest> <uses-sdk android:minSdkVersion="5" /> ... </manifest>
アプリが android:minSdkVersion で API レベルを宣言する主な理由は、指定した API レベルで導入された API を使用していることを Android システムに伝えるためです。
API レベルが低いプラットフォームになんらかの方法でアプリがインストールされると、存在しない API にアプリがアクセスしようとした場合、実行時にクラッシュします。アプリに必要な最小 API レベルが対象 デバイスのプラットフォーム バージョンの API レベルより高い場合、システムは、アプリをインストールさせないことにより、このような事態を回避します。
開発時の考慮事項
以下のセクションでは、アプリの開発時に考慮すべき API レベルに関する情報を提供します。
アプリの上位互換性
一般的に Android アプリは、Android プラットフォームの新しいバージョンと上位互換性があります。
フレームワーク API の変更はほとんどすべて追加的なものです。そのため、その API レベルで指定されているように、特定バージョンの API を使用して開発された Android アプリは、新しいバージョンの Android プラットフォームおよび上位の API レベルと上位互換性があります。アプリは、新バージョンのあらゆる Android プラットフォームで実行できます。ただし、なんらかの理由により後で削除された API の特定部分をアプリが使用している場合を除きます。
多くの Android 搭載デバイスは無線（OTA）でシステム アップデートを受信するため、上位互換性があることは重要です。ユーザーは、正常にアプリをインストールして使用できるようになった後、Android プラットフォームの新バージョンへの無線（OTA）アップデートを受信することがあります。アップデートがインストールされると、アプリは新しいランタイム バージョンの環境で実行されますが、この環境にはアプリが依存する API とシステムの機能が残っています。
基盤となるシステム自体の変更など、API より下位に変更すると、新しい環境での実行時にアプリに影響する可能性があります。アプリ デベロッパーにとって、各システム環境でのアプリの外観と動作を把握することは重要です。
デベロッパーがさまざまなバージョンの Android プラットフォームでアプリをテストできるように、Android SDK にはダウンロード可能な複数のプラットフォームが含まれています。各プラットフォームには互換性のあるシステム イメージが含まれており、アプリをテストするために AVD で実行できます。
アプリの下位互換性
Android アプリは、コンパイル以前のバージョンの Android プラットフォームと必ずしも下位互換性があるわけではありません。
Android プラットフォームの各新バージョンには、プラットフォームの新機能へのアクセスをアプリに提供する、既存の API 部分を置き換える、などの新しいフレームワーク API が含まれていることがあります。新しい API は、新しいプラットフォームで実行するとき、また API レベルで指定したバージョン以降のプラットフォームで実行する場合にも、アプリにアクセスできます。ただし、以前のバージョンのプラットフォームには新しい API が含まれていないため、新しい API を使用するアプリをこれらのプラットフォームで実行することはできません。
Android 搭載デバイスを以前のバージョンのプラットフォームにダウングレードする可能性は高くないものの、実際には以前のバージョンのプラットフォームを実行しているであろうデバイスが多いことを認識しておくのは大切です。無線（OTA）アップデートを受信するデバイスでさえ、タイムラグがあり、長期間アップデートされていないものがあるかもしれません。
プラットフォーム バージョンと API レベルの選択
アプリの開発時に、アプリをコンパイルするプラットフォームのバージョンを選択します。一般的には、アプリがサポートできる可能な限り最小バージョンのプラットフォームでアプリをコンパイルしてください。
ビルド ターゲットのバージョンを徐々に下げてアプリをコンパイルすることで、サポート可能な最小のプラットフォーム バージョンを決定できます。最小バージョンを決定したら、対応するプラットフォーム バージョンおよび API レベルを使用して AVD を作成し、アプリを十分にテストします。必ずアプリのマニフェストで android:minSdkVersion 属性を宣言し、その値をプラットフォーム バージョンの API レベルに設定してください。
最小 API レベルを宣言する
最新のプラットフォーム バージョンで導入された API またはシステム機能を使用するアプリをビルドする場合は、android:minSdkVersion 属性を最新のプラットフォーム バージョンの API レベルに設定します。これは、ユーザーがデバイスで互換性のあるバージョンの Android プラットフォームを実行している場合にのみ、アプリをインストールできるようにするためです。これにより、アプリがデバイスで適切に機能することが保証されます。
最新のプラットフォーム バージョンで導入された API を使用するアプリでも android:minSdkVersion 属性を宣言していない場合、アプリは最新バージョンのプラットフォームを搭載したデバイスでは適切に動作しますが、以前のバージョンのプラットフォームを搭載したデバイスでは適切に動作しません。後者の場合、以前のバージョンに存在しない API をアプリが使用しようとすると、実行時にクラッシュします。
高い API レベルに対するテスト
アプリをコンパイルしたら、必ずアプリの android:minSdkVersion 属性で指定したプラットフォームでテストします。そのためには、アプリに必要なプラットフォーム バージョンを使用する AVD を作成します。また、上位互換性を確認するには、アプリが使用している API レベルより上位の API レベルを使用するすべてのプラットフォームで、アプリを実行してテストします。
Android SDK には、最新バージョンを含む使用可能な複数のプラットフォーム バージョンが用意されています。また、必要に応じて他のプラットフォーム バージョンをダウンロードするのに使用できるアップデータ ツールも提供しています。
アップデータにアクセスするには、<sdk>/tools ディレクトリにある android コマンドライン ツールを使用します。android sdk を実行することで、SDK アップデータを起動できます。android.bat（Windows）または android（OS X/Linux）ファイルをダブルクリックしてもよいでしょう。
さまざまなプラットフォーム バージョンに対するアプリをエミュレータで実行するには、テストするプラットフォーム バージョンごとに AVD を作成します。AVD について詳しくは、仮想デバイスの作成と管理をご覧ください。物理デバイスを使用してテストする場合は、そのデバイスが搭載している Android プラットフォームの API レベルを必ず認識しておいてください。プラットフォームのバージョンとその API レベルのリストについては、このドキュメントにある表をご覧ください。
API レベルによるリファレンス ドキュメントのフィルタリング
Android プラットフォームのリファレンス ドキュメントには、各ページの左上の領域に「API レベル」コントロールを提示しています。このコントロールを使用すると、マニフェスト ファイルの android:minSdkVersion 属性で指定している API レベルに基づいて、アプリが実際に利用できる API パーツに対するドキュメントのみを表示できます。
フィルタリングを使用するには、アプリで指定した API レベルをメニューから選択します。それ以降の API レベルで導入された API はグレー表示され、これらはアプリで利用できないため、その内容はマスキングされます。
API レベルでドキュメントをフィルタすることで、各 API レベルの新しい要素や導入された要素は表示されません。フィルタリングは、特定の API レベルに関連する API 全体を表示する手段を提供するものであり、それ以降の API レベルで導入された API 要素は除外されます。
戻って完全なドキュメントを表示するには、API レベルメニューの上部にある [REL] を選択します。デフォルトでは、API レベルによるフィルタリングは無効になっており、API レベルに関係なく完全なフレームワーク API を表示できます。
各 API 要素のリファレンス ドキュメントには、各要素を導入する API レベルが記載されています。パッケージおよびクラスの API レベルは、各ドキュメント ページのコンテンツ領域の右上に「API レベルで追加されました」として記載されています。クラスメンバーの API レベルは、右端の詳細説明ヘッダーに記載されています。