<uses-sdk>

Google Play использует атрибуты <uses-sdk>, указанные в манифесте приложения, чтобы отфильтровать устройства, которые не соответствуют требованиям к версии платформы. Прежде чем задавать эти атрибуты, ознакомьтесь с информацией о фильтрах в Google Play.

Синтаксис:

<uses-sdk android:minSdkVersion="integer"
          android:targetSdkVersion="integer"
          android:maxSdkVersion="integer" />

содержится в:

<manifest>

description:

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

Несмотря на название, этот элемент используется для указания уровня API, а не номера версии пакета средств разработки (SDK) или платформы Android. Уровень API всегда обозначается одним целым числом. Уровень API нельзя определить по номеру версии Android. Например, он не совпадает с номером основной версии или суммой номеров основной и промежуточной версий.

Указать, что приложение предназначено для промежуточной версии SDK или требует ее, нельзя.

Также ознакомьтесь с документом об управлении версиями приложений.

атрибуты:

android:minSdkVersion

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

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

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

API в разработке

В справочной документации по Android API интерфейсы, добавленные или объявленные устаревшими в предварительном выпуске SDK, помечаются как API в разработке, а не номером уровня API. Эта пометка применяется к уведомлениям "Добавлено в" и "Устарело в", пока SDK не достигнет стабильности платформы и не получит окончательный основной или дополнительный уровень API. API, находящиеся в разработке, имеют следующие характеристики:

• Статус предварительной версии. Добавление или прекращение поддержки API является частью активной бета-версии или ранней версии SDK до окончательного определения уровня API.
• Стабильность не гарантируется. В отличие от выпущенных API, которые имеют постоянный уровень и совместимы с будущими версиями, API, находящиеся в разработке, могут быть изменены, переименованы или полностью удалены в предварительных версиях SDK.

Проверять наличие API, находящихся в разработке, во время выполнения (PREVIEW_SDK_INT)

Поскольку API, находящиеся в разработке, могут изменяться или удаляться между предварительными выпусками, никогда не используйте проверку "больше или равно" (>=) для защиты вызовов невыпущенных API. API, присутствующий в предварительной версии 1, может быть изменен или удален в предварительной версии 2.

Вместо этого приложения, экспериментирующие с предварительными версиями функций, должны проверять значение Build.VERSION.PREVIEW_SDK_INT на строгое равенство (==) точной версии предварительной версии, с которой было скомпилировано приложение:

• В финальных рабочих сборках и выпусках значение Build.VERSION.PREVIEW_SDK_INT всегда равно 0.
• В предварительных сборках значение PREVIEW_SDK_INT уникально для каждого выпуска.

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

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

Изменения ниже API, например в самой базовой системе, могут повлиять на ваше приложение при его запуске в новой среде. Вам, как разработчику приложения, важно понимать, как оно выглядит и работает в каждой системной среде.

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

Обратная совместимость приложений

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

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

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

Выберите версию платформы и уровень API

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

Чтобы определить минимальную версию платформы, компилируйте приложение для все более ранних версий. Определив самую раннюю версию, создайте виртуальное устройство Android с соответствующей версией платформы и уровнем API и полностью протестируйте приложение. Убедитесь, что в манифесте приложения объявлен атрибут android:minSdkVersion и ему присвоено значение уровня API версии платформы.

Как объявить минимальный уровень API

Если вы создаете приложение, которое использует API или системные функции, представленные в последней версии платформы, задайте для атрибута android:minSdkVersion уровень API последней версии платформы. Это необходимо, чтобы пользователи могли устанавливать ваше приложение только на устройства с совместимой версией платформы Android. Это поможет обеспечить корректную работу приложения на устройствах пользователей.

Если в приложении используются API, представленные в последней версии платформы, но не объявлен атрибут android:minSdkVersion, то оно будет правильно работать на устройствах с последней версией платформы, но не на устройствах с более ранними версиями. В последнем случае приложение аварийно завершает работу при попытке использовать API, которых нет в более ранних версиях.

Тестирование на более высоких уровнях API

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

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

Чтобы запустить инструмент обновления, используйте инструмент командной строки android, который находится в каталоге <sdk>/tools. Чтобы запустить инструмент обновления SDK, выполните команду android sdk. Вы также можете нажать дважды на файл android.bat (Windows) или android (OS X/Linux).

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

Как отфильтровать справочную документацию по уровню API

На страницах справочной документации по платформе Android в левом верхнем углу есть элемент управления "Уровень API". Вы можете настроить показ документации только для тех частей API, которые доступны вашему приложению. Это зависит от уровня API, указанного в атрибуте android:minSdkVersion файла манифеста.

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

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

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

В справочной документации по отдельным элементам API указывается уровень API, на котором каждый элемент был добавлен или объявлен устаревшим. Уровень API для пакетов и классов указывается в правом верхнем углу области контента на каждой странице документации в виде "Добавлено в API уровня" и, если применимо, "Устарело в API уровня". Уровень API для элементов класса указывается в заголовках их подробных описаний у правого поля. Если дополнения или прекращение поддержки API в предварительном выпуске не достигли стабильности платформы, в этих местах вместо номера уровня API будет указано API under development (API в разработке).