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

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

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

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

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

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

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

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

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

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

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

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

• Изменения, которые влияют на все приложения, работающие в этой версии 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.

Каждое сообщение 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}

Изменения, которые контролируются targetSDKVersion могут быть включены или отключены по умолчанию, поэтому список пакетов может включать экземпляры как true , так и false , в зависимости от targetSDKVersion каждого из этих приложений. Например:

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, вы можете включать и тестировать каждое закрытое изменение одно за другим, вместо того, чтобы изменять манифест приложения и соглашаться на каждое изменение сразу. Этот дополнительный элемент управления может помочь вам тестировать изменения изолированно и избежать отладки и обновления нескольких частей вашего приложения одновременно.

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

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

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

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

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

Тип сборки	Неотлаживаемое приложение	Отлаживаемое приложение
	Все изменения	Изменения, контролируемые targetSDKVersion	Все остальные изменения
Предварительная версия для разработчиков или бета-версия	Не могу переключить	Можно переключать	Можно переключать
Публичная пользовательская сборка	Не могу переключить	Можно переключать	Не могу переключить