<использует-SDK>

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

android:maxSdkVersion

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

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

Хотя устройство на базе Android вряд ли будет откатиться до предыдущей версии платформы, важно понимать, что на рынке, вероятно, будет много устройств с более ранними версиями платформы. Даже среди устройств, получающих обновления по воздуху (OTA), некоторые могут работать с задержками и не получать обновления в течение значительного времени.

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

Чтобы вернуться к просмотру полной документации, выберите REL в верхней части меню «Уровень API». По умолчанию фильтрация по уровню API отключена, поэтому вы можете просматривать полный API фреймворка независимо от уровня API.

В справочной документации по отдельным элементам API указан уровень API, на котором представлен каждый элемент. Уровень API для пакетов и классов указан как «Добавлено на уровне API» в правом верхнем углу области содержимого на каждой странице документации. Уровень API для членов классов указан в заголовках их подробного описания, в правом поле.