このページは Cloud Translation API によって翻訳されました。

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

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

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

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

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

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

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

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

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

注: アプリのデバッグ可能なビルドバリアントを使用して、変更のオンとオフを切り替える必要があります。

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

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

この種の変更は、互換性フレームワークでデフォルトで有効になり、UI の [デフォルトで有効な変更] 欄に表示されます。
特定の Android バージョンをターゲットとするアプリにのみ影響する変更。この種の変更は、特定のバージョンの Android をターゲットとするアプリにのみ影響するため、targetSDKVersion によって制限される変更とも呼ばれます。

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

注: Android 15 プレビュー期間中の API レベルが確定するまでは、Android 15 をターゲットとする場合にのみ有効になる一部の変更では、最終的に想定される API レベル 35 ではなく、10000 を API レベルとして使用します。

図 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 をアプリで使用する場合、アプリの動作に影響します。

状態	意味
`ENABLED`	変更が有効になり、変更された API をアプリで使用する場合、アプリの動作に影響します。
`DISABLED`	この変更は無効であり、アプリには影響しません。注: アプリの `targetSDKVersion` が必須のしきい値より小さいために変更が無効の場合、アプリがより上位のバージョンをターゲットとするように `targetSDKVersion` の値を増やすと、変更がデフォルトで有効になります。
`LOGGED`	変更は、互換性フレームワークを通じてログに記録されますが、オンまたはオフに切り替えることはできません。この変更を切り替えられなくても、アプリの動作が影響を受けることがあります。詳細については、その Android バージョンの互換性フレームワークリストで変更の説明をご覧ください。多くの場合、この種の変更は試験的なものであり、無視できます。

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 の新しいバージョンでアプリのテストを管理しながら柔軟に行うことです。このセクションでは、アプリをテストしてデバッグする際に変更をオンまたはオフにするタイミングを判断するための方法をいくつか紹介します。

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

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

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

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

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

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

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

targetSDKVersion により制限される変更

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

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

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

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

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

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

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

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

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

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

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

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 を条件とする変更	その他すべての変更
デベロッパープレビュービルド、ベータ版ビルド	切り替えられない	切り替えられる	切り替えられる
ユーザー向け公開ビルド	切り替えられない	切り替えられる	切り替えられない