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

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 の [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 つに対応しています。上記の例では、194833441 は NOTIFICATION_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 に応じて、パッケージのリストには true と false の両方のインスタンスが含まれることがあります。次に例を示します。

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

特定の変更に関する詳細

互換性フレームワークの動作変更の一覧は、各 Android バージョンのドキュメントに記載されています。詳しくは、アプリをテストする Android のバージョンに応じて、以下のリンクをご覧ください。

• Android 15（API レベル 35）
• Android 14（API レベル 34）
• Android 13（API レベル 33）
• Android 12（API レベル 31 および 32）
• Android 11（API レベル 30）

変更を切り替えるとき

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

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

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

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

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

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

これらの変更は 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 バージョンが条件のバージョンより低い場合、デフォルトで無効になります。デベロッパーが変更をオンまたはオフに切り替えると、デフォルトの状態がオーバーライドされます。

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