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

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), будет указано в пользовательском интерфейсе в разделе под названием Enabled for targetSdkVersion >=33 . В некоторых более ранних версиях Android этот раздел называется "Enabled After SDK API_LEVEL ".

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

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

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

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

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

Изменить идентификатор
Указывает, какое изменение влияет на приложение. Это значение сопоставляется с одним из изменений поведения, перечисленных на экране App Compatibility Changes (см. рисунок 1). В этом примере 194833441 сопоставляется с NOTIFICATION_PERM_CHANGE_ID .
УИД
Указывает, какое приложение затронуто изменением.
Состояние

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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), будет указано в пользовательском интерфейсе в разделе под названием Enabled for targetSdkVersion >=33 . В некоторых более ранних версиях Android этот раздел называется "Enabled After SDK API_LEVEL ".

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

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

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

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

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

Изменить идентификатор
Указывает, какое изменение влияет на приложение. Это значение сопоставляется с одним из изменений поведения, перечисленных на экране App Compatibility Changes (см. рисунок 1). В этом примере 194833441 сопоставляется с NOTIFICATION_PERM_CHANGE_ID .
УИД
Указывает, какое приложение затронуто изменением.
Состояние

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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