Google Play использует атрибуты <uses-sdk> , указанные в манифесте вашего приложения, для фильтрации вашего приложения на устройствах, не соответствующих требованиям к версии платформы. Прежде чем устанавливать эти атрибуты, убедитесь, что вы понимаете принцип работы фильтров Google Play .
- синтаксис:
<uses-sdk android:minSdkVersion="integer" android:targetSdkVersion="integer" android:maxSdkVersion="integer" />
- содержится в:
-
<manifest> - описание:
Позволяет выразить совместимость приложения с одной или несколькими версиями платформы Android с помощью целочисленного значения уровня API. Уровень API, выраженный приложением, сравнивается с уровнем API данной системы Android, который может различаться на разных устройствах Android.
Несмотря на своё название, этот элемент используется для указания уровня API, а не номера версии комплекта разработки программного обеспечения (SDK) или платформы Android. Уровень API всегда представляет собой одно целое число. Вы не можете определить уровень API по соответствующему номеру версии Android. Например, он не совпадает с основной версией или суммой основной и дополнительной версий.
Невозможно указать, что приложение ориентировано на использование или требует минорной версии SDK.
Также ознакомьтесь с документом о версионировании ваших приложений .
- атрибуты:
-
android:minSdkVersion - Целочисленное значение, указывающее минимальный уровень API, необходимый для работы приложения. Система Android не позволит пользователю установить приложение, если уровень API системы ниже значения, указанного в этом атрибуте. Всегда объявляйте этот атрибут.
Внимание: если вы не укажете этот атрибут, система примет значение по умолчанию "1", что означает совместимость вашего приложения со всеми версиями Android. Если это не так , и вы не указали правильный
minSdkVersion, то при установке на систему с несовместимым уровнем API приложение завершится с ошибкой во время выполнения при попытке доступа к недоступным API. Поэтому обязательно укажите соответствующий уровень API в атрибутеminSdkVersion. -
android:targetSdkVersion - Целочисленное значение, указывающее на уровень API, на который ориентировано приложение. Если значение не задано, по умолчанию используется значение параметра
minSdkVersion.Этот атрибут сообщает системе, что тестирование проводилось на целевой версии, и система не включает никаких механизмов обеспечения совместимости для поддержания обратной совместимости вашего приложения с целевой версией. Приложение по-прежнему может работать на более старых версиях (вплоть до
minSdkVersion).По мере развития Android с каждой новой версией, некоторые аспекты его работы и даже внешний вид могут меняться. Однако, если уровень API платформы выше версии, указанной в параметре
targetSdkVersionвашего приложения, система может включить режимы совместимости, чтобы ваше приложение продолжало работать так, как вы ожидаете. Вы можете отключить такие режимы совместимости, указавtargetSdkVersionв соответствии с уровнем API платформы, на которой работает приложение.Например, установка этого значения на "11" или выше позволяет системе применять стандартную тему Holo к вашему приложению при работе на Android 3.0 или выше, а также отключает режим совместимости с экраном при работе на больших экранах, поскольку поддержка API уровня 11 подразумевает поддержку больших экранов.
В зависимости от значения этого атрибута система может включать множество вариантов обеспечения совместимости. Некоторые из этих вариантов описаны соответствующими версиями платформы в справочнике
Build.VERSION_CODES.Чтобы ваше приложение оставалось актуальным при каждом обновлении Android, увеличьте значение этого атрибута в соответствии с последним уровнем API, а затем тщательно протестируйте приложение на соответствующей версии платформы.
Введено в: API уровня 4
- Целое число, указывающее максимальный уровень API, на котором предназначено работать приложение.
В Android 1.5, 1.6, 2.0 и 2.0.1 система проверяет значение этого атрибута при установке приложения и при повторной проверке приложения после обновления системы. В любом случае, если значение атрибута
maxSdkVersionниже уровня API, используемого самой системой, то установка приложения невозможна. В случае повторной проверки после обновления системы это фактически удаляет ваше приложение с устройства.Чтобы проиллюстрировать, как этот атрибут может повлиять на ваше приложение после обновления системы, рассмотрим следующий пример:
Приложение, в манифесте которого указано значение
maxSdkVersion="5"публикуется в Google Play. Пользователь, устройство которого работает под управлением Android 1.6 (уровень API 4), загружает и устанавливает приложение. Через несколько недель пользователь получает обновление системы до Android 2.0 (уровень API 5) по беспроводной сети. После установки обновления система проверяетmaxSdkVersionприложения и успешно подтверждает его корректность.Приложение работает в обычном режиме. Однако некоторое время спустя устройство получает еще одно системное обновление, на этот раз до Android 2.0.1 (уровень API 6). После обновления система больше не может повторно проверить приложение, поскольку собственный уровень API системы (6) теперь выше максимального уровня, поддерживаемого приложением (5). Система блокирует отображение приложения для пользователя, фактически удаляя его с устройства.
Внимание: Мы не рекомендуем указывать этот атрибут. Во-первых, нет необходимости устанавливать этот атрибут, чтобы блокировать развертывание вашего приложения на новых версиях платформы Android по мере их выпуска. По своей конструкции новые версии платформы полностью обратно совместимы. Ваше приложение будет корректно работать на новых версиях при условии, что оно использует только стандартные API и следует передовым методам разработки. Во-вторых, в некоторых случаях указание этого атрибута может привести к удалению вашего приложения с устройств пользователей после обновления системы до более высокого уровня API. Большинство устройств, на которых, вероятно, будет установлено ваше приложение, получают периодические обновления системы по беспроводной сети, поэтому, прежде чем устанавливать этот атрибут, оцените их влияние на ваше приложение.
Введено в: API уровня 4
В некоторых версиях Android (начиная с Android 2.0.1) атрибутmaxSdkVersionне проверяется и не используется при установке или повторной проверке. Однако Google Play продолжает использовать этот атрибут в качестве фильтра при показе пользователям приложений, доступных для загрузки.
-
- введено в:
- Уровень API 1
Что такое уровень API?
Уровень API — это целочисленное значение, однозначно определяющее версию API фреймворка, предлагаемую той или иной версией платформы Android.
Платформа Android предоставляет API-интерфейс, который приложения могут использовать для взаимодействия с базовой системой Android. API-интерфейс состоит из:
- Базовый набор пакетов и классов.
- Набор XML-элементов и атрибутов для объявления файла манифеста.
- Набор XML-элементов и атрибутов для объявления и доступа к ресурсам.
- Набор намерений
- Набор разрешений, которые могут запрашивать приложения, а также механизмы обеспечения соблюдения этих разрешений, включенные в систему.
Каждая последующая версия платформы Android может включать обновления API платформы приложений Android, которые она предоставляет.
Обновления API фреймворка разработаны таким образом, чтобы новый API оставался совместимым с более ранними версиями. То есть большинство изменений в API носят аддитивный характер и вводят новую или заменяющую функциональность. По мере обновления частей API, старые, замененные части объявляются устаревшими, но не удаляются, так что существующие приложения по-прежнему могут их использовать.
В очень небольшом числе случаев части API изменяются или удаляются, хотя, как правило, такие изменения необходимы только для обеспечения надежности API и безопасности приложений или систем. Все остальные части API из более ранних версий переносятся без изменений.
API фреймворка, предоставляемый платформой Android, определяется с помощью целочисленного идентификатора, называемого уровнем API . Каждая версия платформы Android поддерживает ровно один уровень API, хотя поддержка всех более ранних уровней API (вплоть до уровня API 1) подразумевается. Первоначальный релиз платформы Android предоставлял уровень API 1, а в последующих релизах уровень API увеличивался.
В таблице ниже указан уровень API, поддерживаемый каждой версией платформы Android. Информацию об относительном количестве устройств, работающих под управлением каждой версии, см. на панели мониторинга распространения .
Использование уровней API в Android
Идентификатор уровня API играет ключевую роль в обеспечении максимально комфортного взаимодействия как для пользователей, так и для разработчиков приложений:
- Это позволяет платформе Android описывать максимально поддерживаемую ею версию API фреймворка.
- Это позволяет приложениям описывать необходимую им версию API фреймворка.
- Это позволяет системе согласовывать установку приложений на устройстве пользователя таким образом, чтобы не устанавливались приложения, несовместимые по версии.
Каждая версия платформы Android хранит свой идентификатор уровня API внутри самой системы Android.
Приложения могут использовать элемент манифеста, предоставляемый API фреймворка — <uses-sdk> — для описания минимального и максимального уровней API, в рамках которых они могут работать, а также предпочтительного уровня API, который они предназначены поддерживать. Этот элемент предлагает три ключевых атрибута:
-
android:minSdkVersion: минимальный уровень API, на котором может работать приложение. Значение по умолчанию — "1". -
android:targetSdkVersion: уровень API, на котором предназначено работать приложение. В некоторых случаях это позволяет приложению использовать элементы манифеста или поведение, определенные на целевом уровне API, вместо того, чтобы ограничиваться использованием только тех, которые определены для минимального уровня API. -
android:maxSdkVersion: максимальный уровень API, на котором может работать приложение. Важно: перед использованием ознакомьтесь с информацией об этом атрибуте на этой странице.
Например, чтобы указать минимальный уровень API системы, необходимый приложению для работы, приложение включает в свой манифест элемент <uses-sdk> с атрибутом android:minSdkVersion . Значение android:minSdkVersion — это целое число, соответствующее уровню API самой ранней версии платформы Android, под которой может работать приложение.
Когда пользователь пытается установить приложение или повторно проверяет приложение после обновления системы, система Android сначала проверяет атрибуты <uses-sdk> в манифесте приложения и сравнивает их значения со своим внутренним уровнем API. Система разрешает начать установку только при соблюдении следующих условий:
- Если атрибут
android:minSdkVersionобъявлен, его значение меньше или равно целочисленному значению уровня API системы. Если атрибут не объявлен, система предполагает, что приложению требуется уровень API 1. - Если объявлен атрибут
android:maxSdkVersion, его значение равно или больше целочисленного значения уровня API системы. Если атрибут не объявлен, система предполагает, что у приложения нет максимального уровня API. Для получения дополнительной информации о том, как система обрабатывает этот атрибут, ознакомьтесь с его описанием .
При указании в манифесте приложения элемент <uses-sdk> может выглядеть следующим образом:
<manifest> <uses-sdk android:minSdkVersion="5" /> ... </manifest>
Основная причина, по которой приложение указывает уровень API в android:minSdkVersion заключается в том, чтобы сообщить системе Android, что она использует API, которые были введены на указанном уровне API.
Если приложение каким-то образом устанавливается на платформу с более низким уровнем API, оно аварийно завершает работу во время выполнения при попытке доступа к несуществующим API. Система предотвращает это, не позволяя приложению установиться, если минимальный требуемый уровень API выше, чем версия платформы на целевом устройстве.
Вопросы развития
В следующих разделах представлена информация об уровнях API, которую необходимо учитывать при разработке приложения.
Обратная совместимость приложений
Приложения для Android, как правило, обратно совместимы с новыми версиями платформы Android.
Поскольку почти все изменения в API фреймворка являются аддитивными, Android-приложение, разработанное с использованием любой версии API, определяемой его уровнем API, является обратно совместимым с более поздними версиями платформы Android и более высокими уровнями API. Приложение может работать на всех более поздних версиях платформы Android, за исключением отдельных случаев, когда приложение использует часть API, которая впоследствии по какой-либо причине удаляется.
Обратная совместимость важна, поскольку многие устройства на базе Android получают обновления системы по беспроводной сети (OTA). Пользователь может установить ваше приложение и успешно им пользоваться, а затем получить OTA-обновление до новой версии платформы Android. После установки обновления ваше приложение будет работать в новой версии среды выполнения, но при этом сохранит API и системные возможности, от которых зависит ваше приложение.
Изменения на уровне API, например, в самой базовой системе, могут повлиять на работу вашего приложения в новой среде. Для вас, как для разработчика приложения, важно понимать, как приложение выглядит и ведет себя в каждой системной среде.
Чтобы помочь вам протестировать ваше приложение на различных версиях платформы Android, Android SDK включает в себя несколько платформ, которые вы можете загрузить. Каждая платформа включает в себя совместимый образ системы, который вы можете запустить в AVD для тестирования вашего приложения.
Обратная совместимость приложения
Приложения для Android не обязательно обратно совместимы с версиями платформы Android, более старыми, чем та версия, для которой они были скомпилированы.
Каждая новая версия платформы Android может включать новые API-интерфейсы, например, те, которые предоставляют приложениям доступ к новым возможностям платформы или заменяют существующие части API. Новые API-интерфейсы доступны приложениям как при работе на новой платформе, так и при работе на более поздних версиях платформы, в зависимости от уровня API. Но поскольку более ранние версии платформы не включают новые API-интерфейсы, приложения, использующие новые API, не могут работать на этих платформах.
Хотя устройство на базе Android вряд ли будет понижено до предыдущей версии платформы, важно понимать, что в эксплуатации, вероятно, будет много устройств, работающих на более ранних версиях платформы. Даже среди устройств, получающих обновления по воздуху (OTA), некоторые могут отставать и не получать обновления в течение значительного времени.
Выберите версию платформы и уровень API.
При разработке приложения вы выбираете версию платформы, для которой будете компилировать приложение. Как правило, компилируйте приложение для самой низкой возможной версии платформы, которую оно поддерживает.
Минимальную возможную версию платформы можно определить, скомпилировав приложение с последовательно более низкими версиями API. После определения минимальной версии создайте AVD, используя соответствующую версию платформы и уровень API, и полностью протестируйте приложение. Обязательно укажите атрибут android:minSdkVersion в манифесте приложения и установите его значение равным уровню API версии платформы.
Укажите минимальный уровень API.
Если вы разрабатываете приложение, использующее API или системные функции, появившиеся в последней версии платформы, установите атрибут android:minSdkVersion на уровень API последней версии платформы. Это позволит пользователям устанавливать ваше приложение только в том случае, если на их устройствах установлена совместимая версия платформы Android. В свою очередь, это поможет гарантировать корректную работу вашего приложения на их устройствах.
Если ваше приложение использует API, появившиеся в последней версии платформы, но не указывает атрибут android:minSdkVersion , то оно корректно работает на устройствах, работающих под управлением последней версии платформы, но не на устройствах, работающих под управлением более ранних версий. В последнем случае приложение аварийно завершает работу во время выполнения, когда пытается использовать API, которых нет в более ранних версиях.
Проведите тестирование при более высоких уровнях API.
После компиляции приложения обязательно протестируйте его на платформе, указанной в атрибуте android:minSdkVersion приложения. Для этого создайте AVD, использующий версию платформы, необходимую для вашего приложения. Кроме того, для проверки обратной совместимости запустите и протестируйте приложение на всех платформах, использующих более высокий уровень API, чем тот, который используется вашим приложением.
В состав Android SDK входят несколько версий для разных платформ, включая последнюю, а также инструмент обновления, с помощью которого можно загрузить необходимые версии для других платформ.
Для доступа к программе обновления используйте инструмент командной строки android , расположенный в каталоге <sdk>/tools. Запустить программу обновления SDK можно, выполнив команду android sdk . Также можно дважды щелкнуть файл android.bat (Windows) или android (OS X/Linux).
Чтобы запустить приложение на разных версиях платформы в эмуляторе, создайте AVD для каждой версии платформы, которую вы хотите протестировать. Дополнительную информацию об AVD см. в разделе «Создание и управление виртуальными устройствами» . Если вы используете физическое устройство для тестирования, убедитесь, что вам известен уровень API платформы Android, на которой оно работает. Список версий платформ и их уровней API приведен в таблице в этом документе.
Отфильтруйте справочную документацию по уровню API.
На страницах справочной документации платформы Android в верхнем левом углу каждой страницы есть элемент управления «Уровень API». С помощью этого элемента управления можно отображать документацию только для тех частей API, которые фактически доступны вашему приложению, в зависимости от уровня API, указанного в атрибуте android:minSdkVersion файла манифеста.
Для использования фильтрации выберите из меню уровень API, указанный вашим приложением. API, появившиеся на более позднем уровне, будут выделены серым цветом, а их содержимое будет скрыто, поскольку они недоступны для вашего приложения.
Фильтрация по уровню API в документации не позволяет увидеть, что нового или введено на каждом уровне API. Она предоставляет способ просмотреть весь API, связанный с данным уровнем API, исключая при этом элементы API, введенные на более поздних уровнях.
Чтобы вернуться к просмотру полной документации, выберите REL в верхней части меню уровней API. По умолчанию фильтрация по уровням API отключена, поэтому вы можете просмотреть полный API фреймворка независимо от уровня API.
В справочной документации для отдельных элементов API указывается уровень API, на котором представлен каждый элемент. Уровень API для пакетов и классов указывается как «Добавлено на уровне API» в правом верхнем углу области содержимого на каждой странице документации. Уровень API для членов класса указывается в заголовках их подробного описания, в правом поле.