The Android Developer Challenge is back! Submit your idea before December 2.

<uses-sdk>

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 端末ごとに異なる場合がある)と比較されます。

名前に反して、この要素は、SDK(ソフトウェア開発キット)や Android プラットフォームのバージョン番号ではなく、API レベルを指定するために使用されます。API レベルには必ず、1 つの整数を指定します。関連付けられた 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 は新しいバージョンのリリースに伴って進化しているため、一部の動作や、ときには外観まで変更されることがあります。しかし、アプリの targetSdkVersion で宣言したバージョンよりもプラットフォームの API レベルが高い場合、システムは互換動作を有効にして、アプリが引き続き想定どおりに動作できるようにします。実行するプラットフォームの API レベルと一致するように targetSdkVersion を指定することで、このような互換動作を無効にすることができます。たとえば、この値を「11」以上に設定すると、Android 3.0 以上でアプリを実行したときに新しいデフォルトのテーマ(Holo)がアプリに適用され、さらに、大きい画面で実行したときに画面互換性モードが無効になります(API レベル 11 をサポートするということは、暗黙的に大きい画面のサポートを意味するため)。

この属性に設定した値に基づいてシステムが有効にする互換動作は、多数存在します。いくつかの互換動作については、Build.VERSION_CODES リファレンスで、対応するプラットフォーム バージョンごとに説明されています。

Android の各リリースに応じてアプリをメンテナンスするには、最新の API レベルに合わせてこの属性の値を増加させ、対応するプラットフォーム バージョンでアプリを十分にテストします。

導入レベル:API レベル 4

android:maxSdkVersion
アプリの実行を想定した最大 API レベルを指定する整数。

Android 1.5、1.6、2.0、2.0.1 では、システムは、アプリのインストール時と、システムアップデート後のアプリの再検証時にこの属性の値を確認します。どちらの場合も、システム自体が使用する API レベルよりもアプリの maxSdkVersion 属性が小さい場合、アプリのインストールは許可されません。これにより、システムアップデート後の再検証で、事実上、アプリが端末から削除されます。

システムアップデート後にこの属性がアプリに与える影響について理解するため、次のような例を考えてみましょう。

マニフェストで 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)より高くなったためです。システムによってアプリがユーザーに表示されなくなり、事実上、端末から削除された状態になります。

警告:この属性の宣言は推奨されません。まず、Android プラットフォームの新しいバージョンがリリースされたときに、アプリがデプロイされないようにする手段としてこの属性を設定する必要はありません。設計上、新しいバージョンのプラットフォームは完全に下位互換性があります。アプリが標準の API のみを使用し、開発のベスト プラクティスに従っている限り、新しいバージョンでもアプリは適切に動作するはずです。また場合によっては、この属性を宣言することで、上位の API レベルへのシステムアップデート後にユーザーの端末からアプリが削除される可能性があります。アプリがインストールされる端末の多くは無線(OTA)で定期的にシステムアップデートを受信するため、この属性を設定する前にアプリへの影響を検討する必要があります。

導入レベル:API レベル 4

Android の以降のバージョン(Android 2.0.1 以上)では、インストールまたは再検証時に maxSdkVersion 属性を確認または適用することはなくなります。Google Play では引き続きこの属性をフィルタとして使用します。ただし、ダウンロードできるアプリをユーザーに提示するときです。
導入レベル:
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 レベルを示しています。各バージョンを使用している端末の相対的な数については、プラットフォーム バージョンに関するダッシュボードのページをご覧ください。

プラットフォーム バージョンAPI レベルVERSION_CODE
Android 10.0 29 Q プラットフォームの特長
Android 9 28 P プラットフォームの特長
Android 8.1 27 O_MR1 プラットフォームの特長
Android 8.0 26 O プラットフォームの特長
Android 7.1.1
Android 7.1
25 N_MR1 プラットフォームの特長
Android 7.0 24 N プラットフォームの特長
Android 6.0 23 M プラットフォームの特長
Android 5.1 22 LOLLIPOP_MR1 プラットフォームの特長
Android 5.0 21 LOLLIPOP
Android 4.4W 20 KITKAT_WATCH KitKat for Wearables のみ
Android 4.4 19 KITKAT プラットフォームの特長
Android 4.3 18 JELLY_BEAN_MR2 プラットフォームの特長
Android 4.2、4.2.2 17 JELLY_BEAN_MR1 プラットフォームの特長
Android 4.1、4.1.1 16 JELLY_BEAN プラットフォームの特長
Android 4.0.3、4.0.4 15 ICE_CREAM_SANDWICH_MR1 プラットフォームの特長
Android 4.0、4.0.1、4.0.2 14 ICE_CREAM_SANDWICH
Android 3.2 13 HONEYCOMB_MR2
Android 3.1.x 12 HONEYCOMB_MR1 プラットフォームの特長
Android 3.0.x 11 HONEYCOMB プラットフォームの特長
Android 2.3.4
Android 2.3.3
10 GINGERBREAD_MR1 プラットフォームの特長
Android 2.3.2
Android 2.3.1
Android 2.3
9 GINGERBREAD
Android 2.2.x 8 FROYO プラットフォームの特長
Android 2.1.x 7 ECLAIR_MR1 プラットフォームの特長
Android 2.0.1 6 ECLAIR_0_1
Android 2.0 5 ECLAIR
Android 1.6 4 DONUT プラットフォームの特長
Android 1.5 3 CUPCAKE プラットフォームの特長
Android 1.1 2 BASE_1_1
Android 1.0 1 BASE

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 レベルを指定します。重要:この属性を使用する前に <uses-sdk> のドキュメントをご覧ください。

たとえば、アプリを実行するために必要な最小システム API レベルを指定するには、アプリのマニフェストに android:minSdkVersion 属性を指定した <uses-sdk> 要素を記述します。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 レベルが、ターゲット端末のプラットフォーム バージョンのものよりも高い場合にはインストールを許可しないことで、このような問題が起こらないようにします。

たとえば、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 レベルを使用するすべてのプラットフォームでアプリを実行し、テストする必要があります。

Android SDK には、最新バージョンを含め、使用可能な複数のプラットフォーム バージョンが含まれています。また、必要に応じて他のプラットフォーム バージョンをダウンロードできる Updater ツールもあります。

Updater にアクセスするには、<sdk>/tools ディレクトリにある android コマンドライン ツールを使用します。android sdk を実行すると、SDK Updater が起動します。android.bat(Windows)ファイルまたは android(OS X / Linux)ファイルをダブルクリックするだけでも起動できます。

エミュレータでさまざまなプラットフォーム バージョンに対してアプリを実行するには、テストが必要なプラットフォーム バージョンごとに AVD を作成します。AVD の詳細については、仮想端末の作成と管理をご覧ください。実機でテストする場合は、端末で実行している Android プラットフォームの API レベルを確認してください。プラットフォーム バージョンと API レベルのリストについては、このドキュメントの冒頭に記載された表をご覧ください。

API レベルによるリファレンス ドキュメントのフィルタリング

Android Developers サイトのリファレンス ドキュメント ページでは、各ページの右上に [Filter by API Level] コントロールがあります。このコントロールを使用すると、アプリがマニフェスト ファイルの android:minSdkVersion 属性で指定している API レベルに基づき、アプリが実際に利用可能な API のドキュメントのみを表示することができます。

フィルタリングを使用するには、ページの検索ボックスの下にあるチェックボックスをオンにして、フィルタリングを有効にします。次に、[Filter by API Level] コントロールを、アプリで指定しているのと同じ API レベルに設定します。それ以降の API レベルで導入された API がグレー表示され、コンテンツがマスクされます。これらの API にはアプリからアクセスできないためです。

ドキュメントを API レベルでフィルタすると、新しい機能や各 API レベルで導入された機能を見ることはできません。これはあくまで、それ以降の API レベルで導入された API 要素を除外して、指定した API レベルに関連する API 全体を把握するために使用します。

API ドキュメントをフィルタしない場合は、チェックボックスを使用してこの機能を無効にします。デフォルトで API レベルのフィルタリングは無効になっているため、API レベルに関係なくフレームワーク API 全体を参照できます。

個々の API 要素のリファレンス ドキュメントには、各要素が導入された API レベルが記載されています。各ドキュメント ページのコンテンツ領域の右上に、[Since <api level>] としてパッケージおよびクラスの API レベルが記載されています。クラスメンバーの API レベルは、右端にある説明のヘッダーに記載されています。