Что такое версия api в android

Что такое версия api в android

API Level это просто целое число, которое однозначно идентифицирует ревизию рабочего окружения программных библиотек (framework API revision), которая предоставляется версией платформы (операционной системой) Android.

Платформа Android предоставляет framework API, которое могут использовать приложения для взаимодействия с нижележащей системой Android. Framework API состоит из:

• Базового набора пакетов и классов.
• Набора элементов XML и атрибутов для декларирования в файле манифеста (manifest file).
• Набора элементов XML и атрибутов для декларирования и доступа к ресурсам.
• Набора намерений (Intents).
• Набора разрешений доступа к ресурсам устройства и системы, которые приложение может запросить, а также защита ограничения доступа, встроенная в систему.

Каждая последующая версия платформы Android может включать в себя обновления предоставляемого framework API приложения Android.

Обновления framework API разработаны так, чтобы новый API оставался совместимым со всеми более старыми версиями API. Т. е. большинство изменений в API добавочные, и представляют новый функционал, или функционал, заменяющий старый. Поскольку части API были обновлены, то старые заменяемые части объявляются устаревшими и нежелательными для использования (deprecated), но эти старые части все же не удаляются, чтобы существующие приложения могли продолжать их использовать. В очень редких случаях части API могут быть модифицированы или удалены, но только в том случае, если это необходимо для обеспечения устойчивости API и безопасности приложения или системы. Все другие части API от старых ревизий переносятся в новые ревизии платформы без модификации.

Framework API, который поставляет платформа Android, указывается в виде целого числа, и этот идентификатор в виде целого числа называется «API Level». Каждая версия платформы Android поддерживает точно один API Level, несмотря на неявную поддержку всех более старых версий API Level (вплоть до API Level 1). Первоначальный релиз платформы Android предоставлял API Level 1 и с каждым новым релизом номер API Level последовательно увеличивался на единицу.

В таблице ниже указаны поддерживаемые API Level для каждой платформы Android. Для информации по относительным количествам устройств, которые работают на каждой версии, см. страничку [2].

[Как используется API Level в Android]

Идентификатор API Level играет ключевую роль в предоставлении информации пользователям и разработчикам.

• API Level позволяет платформе (операционной системе) Android описать максимальную ревизию framework API, которую платформа поддерживает.
• API Level позволяет приложениям описать требуемую для них ревизию framework API.
• API Level позволяет системе обрабатывать инсталляции приложений на устройстве пользователя и определять, какие их них являются несовместимыми с текущей версией системы.

Подробнее про использовании API Level в приложении и системе Android см. [3].

[Совместимость приложений с новыми версиями операционной системы Android]

Поскольку большинство изменений framework API в операционной системе являются добавочными, то приложения Android, разработанные с указанной версией API (как указано по API Level) будут совместимы в будущем (forward-compatible) с последующими версиями платформ Android и более высокими уровнями API level. Приложения должны иметь возможность работать на всех последующих версиях платформы Android, за исключением изолированных случаев, когда приложение использует часть API, которая по некоторым причинам было удалена в поздней ревизии API.

Forward-совместимость важна, потому что множество устройств, работающих на Android, получают обновления системы на лету, по каналу Wi-Fi (over-the-air, OTA). Пользователь может установить Ваше приложение и успешно его использовать, и позднее получить OTA-обновление на новую версию платформы Android. Как только обновление установлено, Ваше приложение будет работать уже в новой версии рабочего окружения, на новом API (run-time version environment), и от этого нового API и возможностей системы будет зависеть работа Вашего приложения.

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

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

[Выбор версии платформы и API Level]

Вы можете задать минимально возможную версию платформы, компилируя приложения на низкую целевую версию платформы. После того, как определите самую низкую версию, Вам нужно создать AVD с соответствующей версией платформы (и API Level) и полностью протестировать Ваше приложение на этой платформе. Убедитесь, что установлен декларированный атрибут android:minSdkVersion в файле манифеста приложения, и его установленное значение соответствует API Level версии платформы.

[Декларирование минимальной версии API Level]

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

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

[Тестирование на верхних уровнях API Level]

После того, как скомпилировали приложение, Вы должны убедиться, что протестировали его на платформе, указанной в атрибуте android:minSdkVersion приложения. Чтобы сделать это, создайте AVD, которая использует версию платформы, требуемую приложением. Дополнительно, чтобы убедиться в forward-совместимости, Вы должны запустить и протестировать приложение на всех платформах, которые используют более высокий уровень API Level, чем использует Ваше приложение.

Чтобы запустить приложение на другой версии платформы в эмуляторе, создайте отдельное виртуальное устройство AVD для каждой версии платформы, которую Вы хотели бы протестировать. Подробнее про AVD см. [5]. Если для тестирования Вы используете физическое устройство, убедитесь, что знаете API Level платформы, на которой запускаете приложение.

[Использование Provisional API Level]

В некоторых случаях может быть доступен «Ранний просмотр (Early Look)» платформы Android SDK. Это означает разработку для платформы, которая пока официально не появилась на рынке. Чтобы начать разработку на платформе, API которой еще не получила финальную версию, то не указывается API Level платформы. Вместо этого Вы должны использовать предварительный (provisional) API Level в манифесте приложения, когда делаете сборку приложения на указанной платформе. Provisional API Level не является числом, это строка, соответствующая кодовому имени еще не выпущенной версии платформы. Provisional API Level будет указан в примечаниях к релизу для ранних релизов SDK (Early Look SDK release), и эта строка чувствительна к регистру символов.

Использование provisional API Level разработано для того, чтобы защитить разработчиков и пользователей устройств от нежелательной публикации или инсталляции приложений, основанных на Early Look framework API, потому что на финальном образе системы приложение может работать не так, как ожидалось.

Provisional API Level будет допустим только при использовании Early Look SDK, и его можно использовать для запуска приложений только в эмуляторе. Приложения, использующие provisional API Level, никогда не могут быть установлены на устройство Android. После финального релиза платформы Вы должны заменить любые экземпляры provisional API Level в Вашем файле манифеста приложения на действительный идентификатор API Level в виде целого числа.

[Фильтрация документации на основе API Level]

Страницы документации на сайте разработчиков Android предоставляют фильтр «Filter by API Level» в правом верхнем углу на каждой страничке. Вы можете использовать этот контрол для того, чтобы просмотреть документацию только для частей API, которые действительно доступны для Вашего приложения, основываясь на API Level, который указан в android:minSdkVersion файла манифеста.

Чтобы использовать фильтрацию, поставьте галочку в чекбоксе для разрешения фильтрации, сразу ниже бокса поиска на странице. Затем установите контрол «Filter by API Level» в тот же API Level, который используется в Вашем приложении. Обратите внимание, что API, представленный в последующих версиях API Level нарисованы серым, и это содержимое будет замаскировано, потому что не будет доступно в Вашем приложении.

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

Если Вы решили, что не хотите фильтровать документацию API, то просто отключите опцию, используя флажок. По умолчанию запрещена фильтрация по API Level, так что Вы можете увидеть полный full framework API, не обращая внимания на API Level.

Также имейте в виду, что документация по отдельным элементам API указывает API Level для каждого представленного элемента. API Level для пакетов и классов указывается как «Since » в правом верхнем углу содержимого каждой страницы документации. API Level для членов класса указан в соответствующем заголовочном файле.

Источник

Что такое версия api в android

В статье приведен перевод статей [1, 2], посвященных управлению версиями приложения Android, и работе приложения на разных версиях операционной системы Android. Все непонятные термины и сокращения ищите в Словарике [3].

Управление версией приложения является критически важным аспектом для обновления приложения и для стратегии его поддержки в будущем. Это важно потому что:

Система Android не использует информацию об версии приложения для принудительного ограничения на апгрейд, довнгрейд, или на ограничение совместимости приложений сторонних производителей. Вместо этого Вы (как разработчик) отвечаете за ограничения, связанные с версиями приложения, или за информирование об этом пользователей. Однако система Android обеспечивает совместимость приложения с системой в соответствии с атрибутом minSdkVersion, который указан в манифесте. Этот атрибут позволяет приложению указать минимальный уровень системного API, с которым совместимо приложение. Дополнительную информацию см. ниже android:minSdkVersion в разделе «Как указать требования приложения к уровню (версии) API Android».

[Установка версии приложения (Application Version)]

Чтобы задать информацию о версии для Вашего приложения, нужно установить атрибуты в файле манифеста приложения (AndroidManifest.xml, секция manifest). Доступно 2 атрибута, для которых обязательно нужно назначить значения:

Обычно Вы должны сделать первый релиз приложения с versionCode установленным в 1, и затем монотонно увеличивать это значение с каждым новым релизом, независимо от статуса, который имеет релиз: major или minor. Это не означает, что значение атрибута android:versionCode должно быть строго подобно версии релиза, которую видит пользователь (см. далее атрибут android:versionName). Приложения и сервисы публикации приложений не должны отображать значение атрибута android:versionCode для пользователей.

Как и атрибут android:versionCode, система Android не использует android:versionName для внутреннего использования, кроме того как отобразить это значение для пользователей. Сервисы публикации приложений могут также прочитать значение android:versionName для того, чтобы отобразить её для пользователей.

Оба этих элемента нужно задать в секции файла манифеста приложения. Пример:

Рабочее окружение Android предоставляет API, позволяющее приложениям опросить систему для получения информации версии приложения. Чтобы получить информацию версии, приложения используют метод getPackageInfo(java.lang.String, int) объекта PackageManager.

[Как указать требования приложения к уровню (версии) API Android]

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

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

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

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

[Подробнее о секции манифеста ]

Секция uses-sdk появилась начиная с API Level 1 (т. е. сразу, начиная с самых старых версий Android). Синтаксис секции следующий:

Секция uses-sdk позволяет Вам выражать совместимость приложения Android с одной или большим количеством версий платформ (операционных систем) Android. Эта совместимость определяется посредством чисел API Level, которая указывается в атрибутах секции minSdkVersion, targetSdkVersion, maxSdkVersion. Версия платформы может (которая соответствует определенному числу API Level) может различаться на разных устройствах Android. Указанные API Level, представленные приложением в этой секции, сравниваются с API Level системы, на которой работает (или устанавливается) приложение, и на основе этого сравнения принимаются определенные решения по инсталляции программы или её работе.

Несмотря на имя секции uses-sdk, эта секция на самом деле используется для определения API Level, но не номер версии SDK платформы Android. API Level всегда задается одиночным целым числом. Вы не можете получить из связанной с ним текстовой версии Android, кроме как получить такое соответствие из таблицы API Level (см. [4]). К примеру, API level 16 относится к версиям Android 4.1, Android 4.1.1, Android 4.1.2. Теперь рассмотрим назначение атрибутов minSdkVersion, targetSdkVersion, maxSdkVersion.

android:minSdkVersion число, обозначающее минимальный API Level, который требуется для установки, запуска и работы приложения. Система Android не позволит пользователю установить приложение, если API Level системы меньше значения, указанного в этом атрибуте. Вы всегда должны указывать этот атрибут в секции uses-sdk файла AndroidManifest.xml.

Предостережение: если Вы не укажете этот атрибут, то система предположит его значение по умолчанию «1», что означает совместимость Вашего приложения со всеми без исключения версиями операционной системы Android. Если Ваше приложение несовместимо со всеми версиями (например, оно использует API, представленное впервые на API Level 3), и Вы не укажете правильно minSdkVersion, то при установке на систему с уровнем API Level меньше 3 приложение будет завершаться с ошибкой при попытке доступа к недоступному API. По этой причине обязательно объявляйте подходящий API Level в атрибуте minSdkVersion.

android:targetSdkVersion этот атрибут представлен начиная с API Level 4. Это целое число, обозначающее API Level, для которого приложение предназначено (target, что означает цель). Если этот атрибут не установлен, то его значение по умолчанию равно minSdkVersion.

Этот атрибут информирует систему, что Вы тестировали приложение с этим API Level, и система не должна позволять любое поведение совместимости (compatibility behaviors, т. е. эмуляцию вызовов API, обеспечивающих специальную дополнительную программную обработку некоторых вызовов API), чтобы поддержать прямую совместимость приложения с целевой версией системы. Приложение все еще может работать на более старых версиях (до версий, не меньших minSdkVersion).

Поскольку Android развивается с каждой новой версией, то некоторые поведения и даже внешний вид приложения может измениться. Однако, если API level платформы выше, чем версия, указанная в targetSdkVersion приложения, система может включить обработки совместимости (compatibility behaviors), чтобы обеспечить работоспособность Вашего приложения так, как Вы этого ожидали. Вы можете запретить такие обработки совместимости, если укажете targetSdkVersion равным API level платформы Android, на которой приложение работает. Например, установка этого значения в «11» или более высокое значение позволит системе установить новую тему оформления по умолчанию (Holo) для Вашего приложения при работе на Android 3.0 или более новой, и также запретит режим совместимости экрана, когда программа будет работать на больших экранах (потому что поддержка API level 11 неявно подразумевает поддержку больших экранов).

Имеется много разновидностей обеспечения совместимости (compatibility behaviors), которые система может разрешить, базируясь на значении этого атрибута. Некоторые из этих обработок (поведений, behaviors) описаны в соответствующей документации версии платформы, см. Build.VERSION_CODES.

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

android:maxSdkVersion этот атрибут представлен начиная с API Level 4. Это целое число, обозначающее максимальный API Level, на котором приложение может работать.

На версиях Android 1.5, 1.6, 2.0 и 2.0.1 система проверяет значение этого атрибута, когда инсталлируется приложение, и когда приложение проверяется на совместимость после обновления системы. В любом случае, если атрибут приложения maxSdkVersion меньше API Level системы, то установка приложения будет запрещена. При проверке приложения на совместимость после обновления системы такой случай соответствует полному удалению приложения с устройства. Для иллюстрации того, как этот атрибут может повлиять на приложение после обновления системы, рассмотрим пример.

Приложение декларировало maxSdkVersion=»5″ в своем манифесте, и было опубликовано на Google Play. Пользователь устройства Android 1.6 (API Level 4) загрузил и установил это приложение. После нескольких недель пользователь принял сообщение от системы over-the-air с предложением обновить систему до уровня Android 2.0 (API Level 5). После установки этого обновления система проверила атрибут приложения maxSdkVersion, и разрешила дальнейшее использование этого приложения. Приложение после этого работало нормально. Однако через некоторое время устройство приняло другое обновление системы Android 2.0.1 (API Level 6). После обновления система не разрешает работу приложения, так как API Level системы (6) теперь выше, чем максимальный уровень, который может поддержать приложение (5). Система делает приложение невидимым для пользователя, и удаляет его из устройства.

Предупреждение: использование этого атрибута не рекомендуется. Во-первых, нет никакой потребности установить этот атрибут как средство блокирования развертывания Вашего приложения на новые версии платформы Android по мере их появления. Для Android декларируется полная обратная совместимость старых приложений для новых версий Android. Ваше приложение должно работать должным образом на всех новых версиях, если оно использует только стандартное API и следует лучшим правилам и практикам разработки. Во-вторых нужно помнить, что применение этого атрибута приведет к автоматическому удалению Вашего приложения с устройств пользователя, которые обновят свою систему на более высокий API Level, чем указано в атрибуте. Большинство устройств, на которых вероятно будет установлено Ваше приложение, получают периодические обновления системы на лету, по воздуху (over the air), так что Вы должны учитывать этот эффект перед тем, как установить этот атрибут для своего приложения.

Будущие версии Android (вне Android 2.0.1) больше не будут проверять maxSdkVersion и принудительно применять его значение при установке или проверке совместимости приложения. Однако Google Play продолжит использовать этот атрибут как фильтр при предоставлении приложений, доступных для закачки пользователям.

[Пример установки версии приложения при создании проекта в Eclipse]

В Eclipse при создании проекта запускается мастер, который на первом экране позволяет настроить параметры, касающиеся версии приложения.

Поле Minimum Required SDK определяет значение атрибута android:minSdkVersion будущего приложения. Здесь желательно указать версию достаточно популярной платформы, которая возможно уже несколько устарела.

Поле Target SDK задает атрибут android:targetSdkVersion. Укажите здесь версию системы, с которой Вы тестировали Ваше приложение. К примеру, Вы отлаживаете программу на версии Android 4.1.2, тогда в выпадающем списке Target SDK нужно выбрать API 16: Android 4.1 (Jelly Bean).

Поле Compile With задает версию SDK, на котором Ваше приложение будет скомпилировано. Задайте здесь максимальную (самую свежую) на текущий момент версию системы Android.

Источник