Google Play は、アプリ マニフェストで宣言された <uses-sdk> 属性を使用して、プラットフォーム バージョン要件を満たしていないデバイスからアプリを除外します。これらの属性を設定する前に、Google Play フィルタを十分に理解してください。
- 構文:
<uses-sdk android:minSdkVersion="integer" android:targetSdkVersion="integer" android:maxSdkVersion="integer" />
- 上位の要素:
<manifest>- 説明:
API レベルを示す整数を使用して、アプリが Android プラットフォームの 1 つ以上のバージョンと互換性を持つことを明示できます。アプリによって明示された API レベルは、さまざまな Android デバイスで異なる特定の Android システムの API レベルと比較されます。
この要素は、その名前に反して、SDK（ソフトウェア開発キット）または Android プラットフォームのバージョン番号ではなく、API レベルを示すために使用されます。API レベルは常に単一の整数であり、関連する Android バージョン番号から導き出すことはできません（具体的には、メジャー バージョンと同じではなく、メジャー バージョンとマイナー バージョンの合計でもありません）。
アプリのバージョン管理に関するドキュメントもご覧ください。
- 属性:
-
android:minSdkVersion- アプリを実行するために必要な最小 API レベルを示す整数。Android システムは、システムの API レベルがこの属性で指定された値よりも低い場合、ユーザーがアプリをインストールできないようにします。この属性は必ず宣言する必要があります。
注意: この属性を宣言しなかった場合、システムはデフォルト値の「1」であると見なします。この値は、アプリがすべての Android バージョンと互換性を持つことを示します。アプリがすべてのバージョンと互換性を持つわけでない場合（たとえば、API レベル 3 で導入された API を使用している場合）、適切な
minSdkVersionを宣言していないと、API レベルが 3 未満のシステムにアプリをインストールしたときに、アプリは使用できない 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 レベル: API レベル 4
android:maxSdkVersion- アプリが動作するように設計されている最大 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 レベル: API レベル 4
将来のバージョン（Android 2.0.1 より後）の Android では、インストールまたは再検証時に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 レベル」と呼ばれる整数の識別子で示されます。個々の Android プラットフォーム バージョンによってサポートされる API レベルは 1 つだけですが、以前のすべての API レベル（API レベル 1 以上）も暗黙的にサポートされます。Android プラットフォームの初回リリースは API レベル 1 として提供され、その後のリリースでは API レベルが上がります。
以下の表は、Android プラットフォームの各バージョンでサポートされる API レベルを示しています。各バージョンを搭載しているデバイスの相対数については、プラットフォーム バージョンのダッシュボードに関するページをご覧ください。
Android での API レベルの使用
API レベル識別子は、ユーザーとアプリ デベロッパーに対して可能な限り最適なエクスペリエンスを保証するうえで、次のような重要な役割を果たします。
- Android プラットフォームは、サポート対象であるフレームワーク API の最大リビジョンを指定できる
- アプリは、必要とするフレームワーク API のリビジョンを指定できる
- システムは、ユーザーのデバイスへのアプリのインストールをネゴシエートして、バージョン互換性のないアプリのインストールを回避することができる
個々の Android プラットフォーム バージョンでは、API レベル識別子を Android システム自体に内部的に格納しています。
アプリは、フレームワーク API によって提供されるマニフェスト要素（<uses-sdk>）を使用して、アプリを実行できる最小 API レベルおよび最大 API レベルと、アプリがサポートするように設計されている優先 API レベルを指定できます。この要素には、次の 3 つの主要な属性があります。
android:minSdkVersion- アプリを実行できる最小 API レベルを指定します。デフォルト値は「1」です。android:targetSdkVersion- アプリが動作するように設計されている API レベルを指定します。これにより、場合によっては、最小 API レベルで定義されたマニフェスト要素（動作）だけでなく、ターゲット API レベルで定義されたマニフェスト要素（動作）をアプリで使用することが可能になります。android:maxSdkVersion- アプリを実行できる最大 API レベルを指定します。重要: この属性を使用する前に、<uses-sdk>のドキュメントをお読みください。
たとえば、アプリの実行に必要な最小システム API レベルを指定するには、アプリのマニフェストに <uses-sdk> 要素を含めて android:minSdkVersion 属性を指定します。android:minSdkVersion の値は、アプリを実行できる最も古いバージョンの Android プラットフォームの API レベルに対応する整数になります。
ユーザーがアプリをインストールしようとしたとき、またはシステム アップデート後にアプリを再検証するとき、Android システムは最初にアプリのマニフェスト内の <uses-sdk> 属性をチェックし、その値をシステム内部の API レベルと比較します。システムは、次の条件が満たされる場合にのみ、インストールの開始を許可します。
android:minSdkVersion属性が宣言されている場合、その値がシステムの API レベルの整数値以下であること。宣言されていない場合、システムはアプリに必要な API レベルを 1 と見なします。android:maxSdkVersion属性が宣言されている場合、その値がシステムの API レベルの整数値以上であること。宣言されていない場合、システムはアプリに最大 API レベルがないと見なします。システムがこの属性を処理する仕組みについて詳しくは、<uses-sdk>のドキュメントをご覧ください。
<uses-sdk> 要素は、アプリのマニフェスト内で次のように宣言されます。
<manifest> <uses-sdk android:minSdkVersion="5" /> ... </manifest>
アプリが android:minSdkVersion で API レベルを宣言する主な理由は、指定した API レベルで導入された API を使用していることを Android システムに伝えるためです。指定した値より API レベルが低いプラットフォームになんらかの方法でアプリがインストールされた場合、アプリは存在しない API にアクセスしようとして実行時にクラッシュします。システムは、アプリに必要な最小 API レベルがターゲット デバイスのプラットフォーム バージョンの API レベルより高い場合にアプリのインストールを許可しないことで、このような問題の発生を防ぎます。
たとえば、android.appwidget パッケージは API レベル 3 で導入されました。アプリがこの API を使用する場合は、android:minSdkVersion 属性で「3」の値を宣言する必要があります。この場合、アプリは Android 1.5（API レベル 3）や Android 1.6（API レベル 4）などのプラットフォームにはインストールできますが、Android 1.1（API レベル 2）や Android 1.0（API レベル 1）などのプラットフォームにはインストールできません。
アプリの API レベル要件を指定する方法について詳しくは、マニフェスト ファイルのドキュメントの <uses-sdk> セクションをご覧ください。
開発時の考慮事項
以降のセクションでは、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 コマンドライン ツールを使用します。SDK アップデータを起動するには、android sdk を実行します。または、android.bat ファイル（Windows）と android ファイル（OS X / Linux）のいずれかをダブルクリックするだけで起動できます。
エミュレータを使用してさまざまなプラットフォーム バージョンでアプリを実行するには、テストするプラットフォーム バージョンごとに AVD を作成します。AVD について詳しくは、仮想デバイスの作成と管理をご覧ください。実機を使用してテストする場合は、デバイスが搭載している Android プラットフォームの API レベルを確認してください。プラットフォーム バージョンとそれに対応する API レベルのリストについては、このドキュメントの前半にある表をご覧ください。
API レベルによるリファレンス ドキュメントのフィルタリング
Android プラットフォームのリファレンス ドキュメントには、各ページの左上の領域に API レベルをフィルタするためのコントロールがあります。このコントロールを使用すると、アプリのマニフェスト ファイルの android:minSdkVersion 属性で指定している API レベルに基づいて、アプリが実際に利用できる API に対応するドキュメントのみを表示できます。
フィルタリングを有効にするには、ページの検索ボックスのすぐ下にあるチェックボックスをオンにします。次に、[Filter by API Level] コントロールを、アプリで指定している API レベルに設定します。なお、それ以降の API レベルで導入された API はグレー表示され、その内容はマスキングされます。これらの API はアプリで利用できないからです。
API レベルでドキュメントをフィルタすると、新しい要素または各 API レベルで導入された要素は表示されなくなります。フィルタリングは、あくまでも指定した API レベルに関連する API 全体を表示するための手段であり、それ以降の API レベルで導入された API 要素は除外されます。
API ドキュメントをフィルタしない場合は、チェックボックスを使用してフィルタリングを無効にします。デフォルトでは、API レベルによるフィルタリングは無効になっており、API レベルに関係なくフレームワーク API 全体を参照できます。
また、個々の API 要素のリファレンス ドキュメントには、各要素が導入されたときの API レベルが記載されています。パッケージおよびクラスの API レベルは、各ドキュメント ページのコンテンツ領域の右上隅に [Since <api level>] として記載されています。クラスメンバーの API レベルは、右端の詳細説明ヘッダーに記載されています。