Эта страница переведена с помощью Cloud Translation API.

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

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

При использовании инструментов совместимости платформа Android автоматически адаптирует свою внутреннюю логику, поэтому вам не нужно менять targetSDKVersion или перекомпилировать приложение для проведения базового тестирования. Поскольку изменения можно включать и выключать по отдельности, вы можете изолировать, тестировать и отлаживать по одному изменению поведения за раз или отключить отдельное изменение, вызывающее проблемы, если вам нужно сначала протестировать что-то другое.

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

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

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

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

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

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

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

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

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

Выявляйте включенные изменения с помощью logcat.

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

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

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

Изменить ID

Указывает, какое изменение затрагивает приложение. Это значение соответствует одному из изменений в поведении, перечисленных на экране «Изменения совместимости приложения» (см. рисунок 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 могут быть либо включены, либо отключены по умолчанию, поэтому список пакетов может содержать экземпляры как со значением true , так и false , в зависимости от targetSDKVersion каждого из этих приложений. Например:

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

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

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

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

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

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

Решение о том, когда следует отключать изменения, обычно зависит от того, ограничено ли изменение значением targetSDKVersion или нет.

Изменения включены для всех приложений

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

Например, если вы готовитесь к работе с Android 16 (уровень API 36), вы можете начать с установки своего приложения на устройство под управлением Android 16 и протестировать его, используя стандартные методы тестирования. Если в приложении возникнут проблемы, вы можете отключить изменение, вызывающее проблему, чтобы продолжить тестирование на наличие других неполадок.

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

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

Изменения зависят от targetSDKVersion

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

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

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

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

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

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

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

Система совместимости позволяет включать и выключать каждое изменение с помощью параметров разработчика или команд 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.	Все остальные изменения
Предварительная версия для разработчиков или бета-версия	Невозможно переключить	Можно переключить	Можно переключить
Публичная пользовательская сборка	Невозможно переключить	Можно переключить	Невозможно переключить