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. Например, это не то же самое, что основная версия или сумма основной и дополнительной версий.
Также прочитайте документ об управлении версиями ваших приложений .
- атрибуты:
-
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 из более ранних версий перенесены без изменений.
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
При разработке приложения вы выбираете версию платформы, для которой компилируете приложение. В общем, скомпилируйте свое приложение с минимально возможной версией платформы, которую может поддерживать ваше приложение.
Вы можете определить самую низкую возможную версию платформы, скомпилировав приложение с последовательно более низкими целевыми объектами сборки. Определив самую низкую версию, создайте 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, представленные на более поздних уровнях API.
Чтобы вернуться к просмотру полной документации, выберите REL в верхней части меню уровня API. По умолчанию фильтрация уровня API отключена, поэтому вы можете просматривать весь API платформы независимо от уровня API.
В справочной документации для отдельных элементов API указан уровень API, на котором представлен каждый элемент. Уровень API для пакетов и классов указывается как «Добавлено на уровне API» в правом верхнем углу области содержимого на каждой странице документации. Уровень API для членов класса указан в заголовках их подробного описания справа.