Инструменты платформы совместимости

В Android 11 появились новые инструменты разработчика для тестирования и отладки приложений с учётом изменений в поведении в новых версиях платформы Android. Эти инструменты являются частью фреймворка совместимости , который позволяет разработчикам приложений индивидуально включать и отключать критические изменения с помощью параметров разработчика или ADB . Используйте эту гибкость при подготовке к использованию последней стабильной версии API и при тестировании своего приложения с предварительной версией следующей версии Android .

When you use the compatibility framework tools, the Android platform automatically adapts its internal logic, so you don't need to change your targetSDKVersion or recompile your app to perform basic testing. Because changes are individually toggleable, you can isolate, test, and debug one behavior change at a time or disable a single change that's causing issues if you need to test something else first.

Как определить, какие изменения включены

Когда изменение поведения включено, оно может повлиять на то, как ваше приложение обращается к API платформы, затронутым этим изменением. Вы можете проверить, какие изменения поведения включены, используя параметры разработчика, logcat или команды ADB.

Определите включенные изменения с помощью параметров разработчика

Рисунок 1. Экран изменений совместимости приложений в параметрах разработчика.

Вы можете увидеть, какие изменения включены, и включить или отключить их в параметрах разработчика устройства. Чтобы получить доступ к этим параметрам, выполните следующие действия:

1. Если параметры разработчика еще не включены, включите их .
2. Откройте приложение «Настройки» вашего устройства и перейдите в раздел «Система» > «Дополнительно» > «Параметры разработчика» > «Изменения совместимости приложений» .

3. Выберите приложение из списка.

Каждое изменение поведения обычно относится к одной из следующих двух категорий:

• Изменения, которые влияют на все приложения, работающие в этой версии Android, независимо от targetSdkVersion приложения.

  Эти изменения включены по умолчанию в фреймворке совместимости и перечислены в пользовательском интерфейсе в разделе «Изменения, включенные по умолчанию» .

• Изменения, затрагивающие только приложения, предназначенные для определённых версий Android. Поскольку эти изменения затрагивают только приложения, предназначенные для определённой версии Android, их также называют изменениями, контролируемыми по targetSDKVersion .

  Эти изменения включены по умолчанию в фреймворке совместимости, если ваше приложение ориентировано на версию API выше указанной. Например, изменение поведения, которое активируется targetSDKVersion в Android 13 (уровень API 33), будет указано в пользовательском интерфейсе в разделе « Включено для targetSdkVersion >=33» . В некоторых более ранних версиях Android этот раздел называется «Включено после SDK API_LEVEL ».

На рисунке 1 вы также увидите раздел « Изменения, отключенные по умолчанию» . Изменения, попадающие в этот раздел, могут иметь множество целей. Перед включением этих изменений ознакомьтесь с описанием изменений в списке совместимых фреймворков для данной версии Android .

Определите включенные изменения с помощью logcat

Для каждого изменения поведения, в первый раз в процессе работы вашего приложения, когда оно вызывает затронутый API, система выводит сообщение logcat, подобное следующему:

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

Каждое сообщение LogCat содержит следующую информацию:

Изменить идентификатор

Указывает, какое изменение влияет на приложение. Это значение соответствует одному из изменений поведения, перечисленных на экране «Изменения совместимости приложений» (см. рисунок 1). В этом примере 194833441 соответствует NOTIFICATION_PERM_CHANGE_ID .

UID

Указывает, какое приложение затронуто изменением.

Состояние

Указывает, влияет ли изменение на приложение.

Состояние может иметь одно из следующих значений:

Состояние	Значение
ENABLED	Изменение включено и повлияет на поведение приложения, если приложение использует измененные API.
DISABLED	Изменение отключено и не повлияет на приложение. Примечание: если это изменение отключено из-за того, что targetSDKVersion приложения ниже требуемого порогового значения, изменение будет включено по умолчанию, когда приложение увеличит targetSDKVersion для перехода на более высокую версию.
LOGGED	Изменение регистрируется фреймворком совместимости, но его нельзя включить или отключить. Хотя это изменение невозможно включить или отключить, оно всё равно может повлиять на поведение вашего приложения. Подробнее см. описание изменения в списке фреймворков совместимости для этой версии Android . Во многих случаях подобные изменения являются экспериментальными и их можно игнорировать.

Определите включенные изменения с помощью ADB

Выполните следующую команду ADB, чтобы увидеть полный набор изменений (как включенных, так и отключенных) на всем устройстве:

adb shell dumpsys platform_compat

В выходных данных для каждого изменения отображается следующая информация:

Изменить идентификатор

Уникальный идентификатор этого изменения поведения. Например, 194833441 .

Имя

Имя этого изменения поведения. Например, NOTIFICATION_PERM_CHANGE_ID .

критерии targetSDKVersion

Какая targetSDKVersion используется для изменения (если таковая имеется).

Например, если это изменение включено только для приложений, использующих SDK версии 33 или выше, выводится enableAfterTargetSdk=32 . Если изменение не ограничено targetSDKVersion , выводится enableAfterTargetSdk=0 .

Переопределения пакетов

Имя каждого пакета, в котором было переопределено состояние изменения по умолчанию (включено или отключено).

Например, если это изменение включено по умолчанию, имя пакета вашего приложения будет указано, если вы отключите это изменение в настройках разработчика или через ADB. В этом случае вывод будет следующим:

packageOverrides={com.my.package=false}

Changes that are gated by targetSDKVersion can be either enabled or disabled by default, so the list of packages can include instances of both true or false , depending on each of those app's targetSDKVersion . For example:

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

Узнайте больше о конкретных изменениях

Полный список изменений в поведении фреймворка совместимости включен в документацию для каждой версии Android. Дополнительную информацию можно найти по следующим ссылкам (в зависимости от версии Android, для которой вы тестируете приложение):

• Android 16 (уровень API 36)
• 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 16 (API уровня 36), вы можете начать с установки приложения на устройство под управлением Android 16 и протестировать его, используя стандартные рабочие процессы тестирования. Если в приложении возникнут проблемы, вы можете отключить вызывающее их изменение, чтобы продолжить тестирование на наличие других проблем.

Because these changes can affect all apps regardless of targetSDKVersion , you should usually test and update your app for these changes before changes that are gated by targetSDKVersion . This helps ensure that your users won't have a degraded app experience when they update their device to a new platform version.

Вам также следует уделить первоочередное внимание тестированию этих изменений, поскольку вы не можете отключить их при использовании публичной версии Android . В идеале следует проводить тестирование этих изменений для каждой версии Android , пока она находится в стадии предварительной версии .

Изменения, контролируемые targetSDKVersion

Если ваше приложение ориентировано на определённую версию targetSDKVersion , все изменения, контролируемые этой версией, будут включены по умолчанию. Таким образом, при изменении версии targetSDKVersion ваше приложение сразу же подвергнется влиянию множества новых изменений.

Поскольку на ваше приложение может повлиять более одного из этих изменений, вам может потребоваться отключать некоторые из этих изменений по отдельности во время тестирования и отладки приложения.

Когда следует включать изменения

Изменения, контролируемые определённой версией targetSDKVersion , по умолчанию отключены, если приложение использует версию SDK ниже целевой. Как правило, при подготовке к использованию новой версии targetSdkVersion у вас есть список изменений поведения, которые необходимо протестировать и отладить в приложении.

Например, вы можете тестировать приложение на соответствие серии изменений платформы в следующей targetSdkVersion . Используя параметры разработчика или команды ADB, вы можете включать и тестировать каждое контролируемое изменение по отдельности, вместо того, чтобы изменять манифест приложения и одновременно соглашаться на каждое изменение. Этот дополнительный контроль поможет вам тестировать изменения изолированно и избежать отладки и обновления нескольких частей приложения одновременно.

После включения изменения вы можете протестировать и отладить приложение, используя стандартные рабочие процессы тестирования. При возникновении проблем проверьте журналы, чтобы определить их причину. Если неясно, вызвана ли проблема включенным изменением платформы, попробуйте отключить это изменение и повторно протестировать соответствующую часть приложения.

Включить или выключить изменения

Фреймворк совместимости позволяет включать и отключать каждое изменение с помощью параметров разработчика или команд ADB. Поскольку включение и отключение изменений может привести к сбою приложения или отключению важных изменений безопасности, существуют некоторые ограничения на возможность включения и выключения изменений .

Включайте и отключайте изменения с помощью параметров разработчика

Используйте параметры разработчика для включения и выключения изменений. Чтобы открыть параметры разработчика, выполните следующие действия:

1. Если параметры разработчика еще не включены, включите их .
2. Open your device's Settings app and navigate to System > Advanced > Developer options > App Compatibility Changes .
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 ниже контролируемой. Включение или выключение изменения переопределяет его состояние по умолчанию.

Чтобы предотвратить злонамеренное использование фреймворка совместимости, существуют некоторые ограничения на возможность переключения изменений. Возможность переключения изменений зависит от типа изменения, отладочной версии приложения и типа сборки, запущенной на вашем устройстве. В следующей таблице описано, когда разрешено переключать различные типы изменений: