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

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

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

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

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

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

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

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

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

3. リストからアプリを選択します。

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

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

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

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

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

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

有効になっている変更を 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 によって制限される変更は、有効化または デフォルトで無効になっているため、パッケージのリストには両方のインスタンスを含めることができる true または false（アプリの各 targetSDKVersion による）。次に例を示します。

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

特定の変更に関する詳細

互換性フレームワークの動作変更の完全なリストは、 をご覧ください。詳しくは、 より詳しい情報（アプリをテストしている 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 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 バージョンが条件のバージョンより低い場合、デフォルトで無効になります。デベロッパーが変更をオンまたはオフに切り替えると、デフォルトの状態がオーバーライドされます。

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