互換性フレームワーク ツール

Android 11 では、新しいバージョンの Android プラットフォームの動作変更に対してアプリをテスト、デバッグするための新しいデベロッパー ツールが導入されました。これらのツールは、開発者向けオプションまたは ADB を使用して、アプリ デベロッパーが互換性を破る変更を個々にオンまたはオフにできる互換性フレームワークの一部です。この柔軟性を利用して、最新の安定版 API をターゲットとする準備や、次の Android バージョンのプレビュー リリースでアプリをテストすることができます。

互換性フレームワーク ツールを使用する場合、Android プラットフォームは自動的に内部ロジックを調整するため、基本的なテストを行うために targetSDKVersion の変更やアプリの再コンパイルは必要ありません。変更は個別に切り替え可能であるため、動作変更を一度に 1 つずつ分離、テスト、デバッグできます。また、最初に別の変更をテストする必要がある場合は、問題の原因となっている変更を個別に無効にすることもできます。

有効になっている変更を特定する方法

動作変更を有効にすると、動作変更の影響を受けるプラットフォーム API へのアプリのアクセス方法に影響を与える可能性があります。有効になっている動作変更を確認するには、開発者向けオプション、logcat、ADB コマンドを使用します。

有効になっている変更を開発者向けオプションを使用して特定する

図 1. 開発者向けオプションでの [アプリの互換性の変更] 画面

デバイスの開発者向けオプションで、有効になっている変更を確認し、変更のオンとオフを切り替えることができます。これらのオプションにアクセスする手順は次のとおりです。

  1. 開発者向けオプションがまだ有効になっていない場合は、有効にします
  2. デバイスの設定アプリを開き、[システム] > [詳細設定] > [開発者向けオプション] > [アプリの互換性の変更] に移動します。
  3. リストからアプリを選択します。

各動作変更は通常、次の 2 つのカテゴリのどちらかに属します。

  • アプリの targetSdkVersion に関係なく、そのバージョンの Android で実行されるすべてのアプリに影響する変更。

    この種の変更は、互換性フレームワークでデフォルトで有効になり、UI の [デフォルトで有効な変更] 欄に表示されます。

  • 特定の Android バージョンをターゲットとするアプリにのみ影響する変更。この種の変更は、特定のバージョンの Android をターゲットとするアプリにのみ影響するため、targetSDKVersion によって制限される変更とも呼ばれます。

    このような変更は、記載された API バージョンよりも高いバージョンをアプリがターゲットとする場合、互換性フレームワークではデフォルトで有効になります。たとえば、Android 13(API レベル 33)で targetSDKVersion によって制限される動作変更は、UI の [Enabled for targetSdkVersion >=33] というタイトルのセクションに表示されます。以前のバージョンの Android では、このセクションに「SDK API_LEVEL の後に有効」というタイトルが付けられています。

図 1 に示すように [デフォルトで無効な変更] という欄もあります。 このセクションに含まれる変更は、さまざまな目的に活用できます。これらの変更を有効にする前に、その Android バージョンの互換性フレームワークのリストで変更の説明をお読みください。

有効になっている変更を logcat を使用して特定する

各動作変更について、影響受けた API をアプリのプロセスで初めて呼び出すとき、システムは次のような logcat メッセージを出力します。

D CompatibilityChangeReporter: Compat change id reported: 194833441; UID 10265; state: ENABLED

各 logcat メッセージには以下の情報が含まれます。

変更 ID
アプリに影響を与える変更点を示します。この値は、[アプリの互換性の変更] 画面(図 1)のリストに表示される動作変更のいずれか 1 つに対応しています。上記の例では、194833441NOTIFICATION_PERM_CHANGE_ID に対応しています。
UID
変更の影響を受けるアプリを示します。
状態

変更がアプリに影響しているかどうかを示します。

状態は次のいずれかの値です。

状態 意味
ENABLED この変更が有効になり、変更された API をアプリが使用する場合、アプリの動作に影響します。
DISABLED

この変更は無効になっており、アプリには影響しません。

注: アプリの targetSDKVersion が必須のしきい値より小さいために変更が無効の場合、アプリがより上位のバージョンをターゲットとするように targetSDKVersion の値を増やすと、変更がデフォルトで有効になります。

LOGGED 変更は、互換性フレームワークを通じてログに記録されますが、オンまたはオフに切り替えることはできません。この変更を切り替えられなくても、アプリの動作が影響を受けることがあります。詳細については、その Android バージョンの互換性フレームワーク リストで変更の説明をご覧ください。多くの場合、この種の変更は試験的なものであり、無視できます。

有効になっている変更を ADB を使用して特定する

次の ADB コマンドを実行して、そのデバイス全体での変更の一覧(有効と無効の両方)をすべて表示します。

adb shell dumpsys platform_compat

出力には、各変更の以下の情報が表示されます。

変更 ID
この動作変更の一意の識別子(例: 194833441)。
名前
この動作変更の名前たとえば、NOTIFICATION_PERM_CHANGE_ID のように指定できました。
targetSDKVersion の条件

どの targetSDKVersion が変更の条件となるか(該当する場合)。

たとえば、この変更が SDK バージョン 33 以降をターゲットとするアプリでのみ有効になっている場合は、enableAfterTargetSdk=32 が出力されます。変更が targetSDKVersion によって制限されない場合、enableAfterTargetSdk=0 が出力されます。

パッケージのオーバーライド

変更のデフォルトの状態(有効または無効)がオーバーライドされた各パッケージの名前。

たとえば、デフォルトで有効になる変更の場合、開発者向けオプションまたは ADB を使用して変更をオフに切り替えると、アプリのパッケージ名が表示されます。この場合、出力は次のようになります。

packageOverrides={com.my.package=false}

targetSDKVersion を条件とする変更は、デフォルトで有効または無効にできます。そのため、アプリの各 targetSDKVersion に応じて、パッケージのリストに truefalse の両方のインスタンスを含めることができます。たとえば、以下の場合です。

packageOverrides={com.my.package=true, com.another.package=false}

特定の変更に関する詳細

互換性フレームワークの動作変更の完全なリストは、各 Android バージョンのドキュメントに含まれています。詳細については、テスト対象の Android のバージョンに応じて以下のリンクをご覧ください。

変更を切り替えるとき

互換性フレームワークの主な目的は、Android の新しいバージョンでアプリのテストを管理しながら柔軟に行うことです。このセクションでは、アプリをテストしてデバッグする際に変更をオンまたはオフにするタイミングを判断するための方法をいくつか紹介します。

変更をオフに切り替えるとき

通常、変更をオフにするタイミングは、変更が targetSDKVersion により制限されるかどうかによって決まります。

すべてのアプリに適用される変更

すべてのアプリに影響する変更は、アプリの targetSDKVersion に関係なく、特定のプラットフォーム バージョンでデフォルトで有効になっているため、そのプラットフォーム バージョンでアプリを実行して、アプリが影響を受けるかどうかを確認できます。

たとえば、Android 14(API レベル 34)を対象にする場合は、Android 14 を搭載したデバイスにアプリをインストールしてから、一般的なテスト ワークフローを使用してアプリをテストできます。アプリで問題が発生した場合は、問題の原因となっている変更を無効にして、他の問題がないかテストを続行できます。

これらの変更は targetSDKVersion に関係なくすべてのアプリに影響する可能性があるため、通常、targetSDKVersion によって制限される変更に対処する前に、これらの変更に対するテストとアプリの更新を行ってください。これにより、ユーザーがデバイスを新しいプラットフォーム バージョンに更新しても、アプリのエクスペリエンスが低下することはありません。

また、Android の公開リリースビルドを使用する場合、このような変更はオフに切り替えられないため、この変更を優先的にテストする必要があります。理想的には、Android バージョンがプレビュー中の各バージョンで変更をテストすることをおすすめします。

targetSDKVersion により制限される変更

アプリが特定の targetSDKVersion をターゲットにしている場合、そのバージョンを条件とする変更はデフォルトで有効になります。したがって、アプリの targetSDKVersion を新しいバージョンに切り替えると、アプリは多数の新しい変更の影響を受け始めます。

アプリがこのような複数の変更の影響を受ける可能性があるため、アプリのテストとデバッグの際には、一部の変更を個別に無効にする必要があります。

変更をオンに切り替えるとき

特定の targetSDKVersion を条件とする変更は、条件となるバージョンよりも低い SDK バージョンをアプリがターゲットとする場合は、デフォルトで無効になります。 一般に、新しい targetSdkVersion をターゲットにする場合、アプリのテストとデバッグに必要な動作変更の一覧が作成されます。

たとえば、次の targetSdkVersion で行われるプラットフォームでの一連の変更に対してアプリをテストすることが考えられます。開発者向けオプションまたは ADB コマンドを使用すると、アプリ マニフェストを変更してすべての変更を一度に有効にするのではなく、条件付きの各変更を 1 つずつ有効にしてテストできます。これにより、変更を別々にテストし、アプリの複数の部分を一度にデバッグや更新することは避けて、コントロールできるようになります。

変更を有効にすると、通常のテスト ワークフローを使用してアプリのテストとデバッグを行うことができます。問題が発生した場合は、ログを確認して問題の原因を特定します。有効になっているプラットフォームの変更が問題の原因かどうか不明な場合は、その変更を無効にしてから、アプリのその領域を再度テストしてください。

変更をオンまたはオフに切り替える

互換性フレームワークでは、開発者向けオプションまたは ADB コマンドを使用して各変更をオンまたはオフに切り替えられます。変更をオンまたはオフに切り替えるとアプリがクラッシュしたり、重要なセキュリティ上の変更が無効になったりするおそれがあるため、変更を切り替えるタイミングにはある程度制限があります。

開発者向けオプションを使用して変更を切り替える

開発者向けオプションを使用して変更をオンまたはオフに切り替えます。開発者向けオプションを確認する手順は次のとおりです。

  1. 開発者向けオプションがまだ有効になっていない場合は、有効にします
  2. デバイスの設定アプリを開き、[システム] > [詳細設定] > [開発者向けオプション] > [アプリの互換性の変更] に移動します。
  3. リストからアプリを選択します。
  4. 変更点のリストから、オンまたはオフに切り替える変更を探し、そのスイッチをタップします。

    オンまたはオフに切り替えられる変更のリスト

ADB を使用して変更を切り替える

ADB を使用して変更をオンまたはオフに切り替えるには、次のどちらかのコマンドを実行します。

adb shell am compat enable (CHANGE_ID|CHANGE_NAME) PACKAGE_NAME
adb shell am compat disable (CHANGE_ID|CHANGE_NAME) PACKAGE_NAME

CHANGE_ID(例: 194833441)か CHANGE_NAME(例: NOTIFICATION_PERM_CHANGE_ID)のどちらかと、アプリの PACKAGE_NAME を渡します。

次のコマンドを使用して、変更をデフォルトの状態に戻し、ADB または開発者向けオプションを使用して設定したオーバーライドを削除することもできます。

adb shell am compat reset (CHANGE_ID|CHANGE_NAME) PACKAGE_NAME

変更の切り替えに関する制限

デフォルトでは、動作変更はそれぞれ有効または無効になっています。すべてのアプリに影響する変更は、デフォルトで有効です。その他の変更は、targetSdkVersion を条件とします。このような変更は、アプリのターゲットがその変更に対応する SDK バージョンと同じかそれより高い場合、デフォルトで有効になり、アプリのターゲットとする SDK バージョンが条件のバージョンより低い場合、デフォルトで無効になります。デベロッパーが変更をオンまたはオフに切り替えると、デフォルトの状態がオーバーライドされます。

互換性フレームワークが不正使用されるのを防ぐため、変更を切り替えるタイミングにはある程度制限があります。変更を切り替えることができるかどうかは、変更の種類、アプリがデバッグ可能かどうか、デバイスで実行されているビルドの種類によって異なります。次の表に、どの種類の変更をいつ切り替えられるかを示します。

ビルドの種類 デバッグできないアプリ デバッグ可能なアプリ
すべての変更 targetSDKVersion を条件とする変更 その他すべての変更
デベロッパー プレビュー ビルド、ベータ版ビルド 切り替えられない 切り替えられる 切り替えられる
ユーザー向け公開ビルド 切り替えられない 切り替えられる 切り替えられない