Уровень Android API, обратная и прямая совместимость
Если вы читаете эту статью, значит вас могут интересовать такие вещи, как:
- Что означает уровень API?
- Как использовать compileSdkVersion , minSdkVersion или targetSdkVersion ?
- Как можно гарантировать, что приложение будет работать правильно на устройствах с разными версиями ОС?
Все эти понятия связаны друг с другом, и я постараюсь объяснить их вам в этой статье простым, но эффективным способом.
Для этого необходимо понимать разницу между SDK и API и знать что такое уровень API в экосистеме Android.
Это правда, что в Android между SDK и API существует отношение 1:1, и часто эти два термина используются как синонимы, но важно понимать, что это не одно и то же.
Правильнее говорить, что для каждой версии Android есть SDK и эквивалентный API, а также уровень этого API.
Расшифровывается как Software Development Kit (комплект для разработки программного обеспечения). Обратите внимание на слово «kit» (комплект)… он как раз представляет из себя набор различных инструментов, библиотек, документации, примеров, помогающих разработчикам создавать, отлаживать и запускать приложения для Android. API предоставляется вместе с SDK.
Если открыть SDK Manager в Android Studio, можно будет яснее увидеть, из чего состоит Android SDK.
На первой вкладке SDK Platform перечислены SDK каждой версии Android.
Как показано на рисунке ниже, Android 9.0 SDK (также известный как Pie) содержит:
- Android SDK Platform 28 (это API фреймворка).
- Исходный код для Android 28 (это реализация API, как вы видите, она не является обязательной… запомните это).
- и еще куча других вещей… например, различные системные образы для эмулятора Android.
На второй вкладке SDK Tools показаны другие инструменты, которые также являются частью SDK, но не зависят от версии платформы. Это означает, что они могут быть выпущены или обновлены отдельно.
Расшифровывается как Application Programming Interface (программный интерфейс приложения). Это просто интерфейс, уровень абстракции, который обеспечивает связь между двумя разными «частями» программного обеспечения. Он работает как договор между поставщиком (например, библиотекой) и потребителем (например, приложением).
Это набор формальных определений, таких как классы, методы, функции, модули, константы, которые могут использоваться другими разработчиками для написания своего кода. При этом API не включает в себя реализацию.
Уровень API
Уровень API — это целочисленное значение, однозначно идентифицирующее версию API фреймворка, предлагаемую платформой Android.
Обычно обновления API фреймворка платформы разрабатываются таким образом, чтобы новая версия API оставалась совместимой с более ранними версиями, поэтому большинство изменений в новом API являются аддитивными, а старые части API становятся устаревшими, но не удаляются.
И теперь кто-то может задаться вопросом…
если API Android не предоставляет реализацию, а SDK Manager предлагает необязательный загружаемый исходный код API в составе SDK, то где находится соответствующая реализация?
Ответ прост. На устройстве.
Давайте разберемся с этим…
От исходного кода к APK-файлу
Как правило, проект под Android состоит из кода, написанного разработчиками с использованием Android API (модуль приложения), а также некоторых других библиотек/зависимостей (.jar-файлов, AAR, модулей и т.д.) и ресурсов.
Процесс компиляции преобразует код, написанный на Java или Kotlin, включая зависимости (одна из причин уменьшить ваш код!), в байт-код DEX, а затем сжимает все в файл APK вместе с ресурсами. На данном этапе реализация API не включена в итоговый APK!
Процесс сборки — Android Developers
DEX файлы и Android Runtime
Архитектура Android — Android Developers
Android Runtime — это место, где делается вся грязная работа и где выполняются DEX-файлы. Оно состоит из двух основных компонентов:
- Виртуальная машина, чтобы воспользоваться преимуществами переносимости кода и независимости от платформы. Начиная с Android 5.0 (Lollipop), старая среда выполнения, Dalvik Virtual Machine, была полностью заменена новой средой Android RunTime (ART). Dalvik использовал JIT-компилятор, тогда как ART использует AOT (Ahead of time) компиляцию плюс JIT для профилирования кода во время выполнения.
- Базовые библиотеки — это стандартные библиотеки Java и Android. Проще говоря, именно здесь находится реализация API.
Например, если на фактическом устройстве установлен Android 9 (Pie), доступны все API до 28 уровня.
Если вам понятны ключевые моменты работы Android Runtime и какова роль API, то должно быть достаточно просто понять обратную и прямую совместимость, а так же использование compileSdkVersion , minSdkVersion и targetSdkVersion .
compileSdkVersion
Это значение используется только для указания Gradle, с какой версией SDK компилировать ваше приложение. Это позволяет разработчикам получить доступ ко всем API, доступным до уровня API, установленного для compileSdkVersion .
Настоятельно рекомендуется выполнить компиляцию с последней версией SDK:
- высокий уровень API позволяет разработчикам использовать преимущества последнего API и возможностей, предоставляемых новыми платформами.
- чтобы использовать последнюю версию SupportLibrary , compileSdkVersion должен соответствовать версии SupportLibrary .
- для перехода на AndroidX или его использования, compileSdkVersion должен быть установлен как минимум равным 28.
- чтобы быть готовым удовлетворить требования целевого уровня API от Google Play. В Google объявили, что для более быстрого распространения новых версий Android на рынке Google каждый год будет устанавливать минимальный целевой уровень API для новых приложений и обновлений. Больше информации вы можете найти здесь и здесь.
Это означает, что прямая совместимость в основном гарантируется платформой, и при запуске приложения на устройстве с более высоким уровнем API, чем тот, который указан в compileSdkVersion , не возникает никаких проблем во время выполнения, приложение будет работать так же, как и ожидалось, на более новых версиях платформы.
Приложение + compileSdkVersion = 26 и метод API xyz() , представленный в API 26 уровня, могут работать на устройстве с Android 8 Oreo (API 26 уровня).
Это же приложение может работать на устройстве с Android 9 Pie (API 28 уровня), поскольку метод API xyz() все еще доступен на API 28 уровня.
minSdkVersion
Это значение обозначает минимальный уровень API, на котором приложение может работать. Это минимальное требование. Если не указан, значением по умолчанию является 1.
Разработчики обязаны установить корректное значение и обеспечить правильную работу приложения до этого уровня API. Это называется обратной совместимостью.
Во время разработки Lint также предупредит разработчиков при попытке использовать любой API ниже указанного в minSdkVersion . Очень важно не игнорировать предупреждения и исправить их!
Чтобы обеспечить обратную совместимость, разработчики могут во время выполнения проверять версию платформы и использовать новый API в более новых версиях платформы и старый API в более старых версиях или, в зависимости от случая, использовать некоторые статические библиотеки, которые обеспечивают обратную совместимость.
Также важно упомянуть, что Google Play Store использует это значение, чтобы определить, можно ли установить приложение на определенное устройство, сопоставив версию платформы устройства с minSdkVersion приложения.
Разработчики должны быть очень осторожны при выборе этого значения, поскольку обратная совместимость не гарантируется платформой.
Выбор «правильного» значения для проекта также является бизнес-решением, поскольку оно влияет на то, насколько большой будет аудитория приложения. Посмотрите на распределение платформ.
Приложение + compileSdkVersion = 26 + minSdkVersion = 22 и метод API xyz() , представленный в API 26 уровня, могут работать на устройстве с Android 8 Oreo (API 26 уровня).
Это же приложение можно установить и запустить на более старом устройстве с Android 5.1 Lollipop (API 22 уровня), где метода API xyz() не существует. Если разработчики не обеспечили обратную совместимость ни с помощью проверок времени выполнения, ни с помощью каких-либо библиотек, то приложение будет аварийно завершать работу, как только оно попытается получить доступ к методу API xyz() .
targetSdkVersion
Это значение указывает уровень API, на котором приложение было разработано.
Не путайте его с compileSdkVersion . Последний используется только во время компиляции и делает новые API доступными для разработчиков. Первый, напротив, является частью APK (также как и minSdkVersion ) и изменяет поведение среды выполнения. Это способ, которым разработчики могут контролировать прямую совместимость.
Иногда могут быть некоторые изменения API в базовой системе, которые могут повлиять на поведение приложения при работе в новой среде выполнения.
Целевой уровень приложения включает поведение среды выполнения, которое зависит от конкретной версии платформы. Если приложение не готово к поддержке этих изменений поведения среды выполнения, оно, вероятно, завершится сбоем.
Простым примером является Runtime Permission, которое было представлено в Android 6 Marshmallow (API 23 уровня).
Приложение может быть скомпилировано с использованием API 23 уровня, но иметь целевым API 22 уровня, если оно еще не готово поддержать новую модель разрешений времени выполнения.
Таким образом, приложение может по-прежнему быть совместимым без включения нового поведения среды выполнения.
В любом случае, как уже упоминалось, Google требует, чтобы приложения удовлетворяли новым требованиям целевого уровня API, поэтому всегда следует иметь высокий приоритет для обновления этого значения.
Теперь соединяя все это вместе, мы видим четкое отношение
minSdkVersion ≤ targetSdkVersion ≤ compileSdkVersion
Имейте в виду, что настоятельно рекомендуется выполнить компиляцию в соответствии с последним уровнем API и стараться использовать targetSdkVersion == compileSdkVersion.
Общие сведения об уровнях API Android
В Xamarin.Android есть несколько параметров уровня API Android, определяющих совместимость приложения с несколькими версиями Android. В этом руководстве объясняется, что означают эти параметры, как их настроить и как они влияют на приложение во время выполнения.
Быстрый запуск
Xamarin.Android предоставляет три параметра проекта уровня API Android:
Целевая платформа — указывает, какую платформу следует использовать при создании приложения. Этот уровень API используется во время компиляции Xamarin.Android.
Минимальная версия Android — указывает старую версию Android, которую вы хотите поддерживать в приложении. Этот уровень API используется во время выполнения Android.
Целевая версия Android — указывает версию Android, в которую приложение предназначено для запуска. Этот уровень API используется во время выполнения Android.
Перед настройкой уровня API для проекта необходимо установить компоненты платформы SDK для этого уровня API. Дополнительные сведения о скачивании и установке компонентов пакета SDK для Android см. в разделе «Установка пакета SDK для Android».
Начиная с августа 2021 г. консоль Google Play требует, чтобы новые приложения предназначены для API уровня 30 (Android 11.0) или более поздней версии. Существующие приложения необходимы для целевого уровня API 30 или выше, начиная с ноября 2021 г. Дополнительные сведения см. в разделе «Требования к целевому уровню API для консоли воспроизведения » статьи «Создание и настройка приложения» в документации по консоли воспроизведения.
- Visual Studio
- Visual Studio для Mac
Как правило, все три уровня API Xamarin.Android имеют одинаковое значение. На странице приложения задайте для версии Android (target Framework) последнюю стабильную версию API (или, как минимум, версию Android, которая содержит все необходимые функции). На следующем снимке экрана целевая платформа имеет значение Android 7.1 (УРОВЕНЬ API 25 — Nougat):
На странице манифеста Android задайте минимальную версию Android для использования компиляции с помощью пакета SDK и установите целевую версию Android таким же значением, что и версия Target Framework (на следующем снимке экрана целевая платформа Android имеет значение Android 7.1 (Nougat)):
Если вы хотите поддерживать обратную совместимость с более ранней версией Android, установите минимальную версию Android, чтобы она была настроена на старую версию Android, которую вы хотите поддерживать в приложении. (Обратите внимание, что уровень API 14 является минимальным уровнем API, необходимым для служб Google Play и поддержки Firebase.) В следующем примере конфигурации поддерживаются версии Android с уровня API 14 до уровня API 25:
Как правило, все три уровня API Xamarin.Android имеют одинаковое значение. Задайте для целевой платформы последнюю стабильную версию API (или, как минимум, версию Android с всеми нужными функциями). Чтобы задать целевую платформу, перейдите к разделу «Общие сборки>» в разделе «Параметры Project«. На следующем снимке экрана целевая платформа имеет значение Use the latest installed platform (8.0):
Параметры минимальной и целевой версии Android можно найти в разделе «Сборка > приложения Android» в разделе «Параметры Project«. Установите для минимальной версии Android значение «Автоматически» — используйте версию целевой платформы и задайте целевую версию Android таким же значением, как и версия Target Framework. На следующем снимке экрана целевая платформа Android framework имеет значение Android 8.0 (уровень API 26), чтобы он соответствовал приведенному выше параметру целевой платформы:
Если вы хотите сохранить обратную совместимость с более ранней версией Android, измените минимальную версию Android на старую версию Android, которую вы хотите поддерживать в приложении. Обратите внимание, что уровень API 14 является минимальным уровнем API, необходимым для служб Google Play и поддержки Firebase. Например, следующая конфигурация поддерживает версии Android до уровня 14 API:
Если приложение поддерживает несколько версий Android, код должен включать проверки среды выполнения, чтобы убедиться, что приложение работает с параметром минимальной версии Android (дополнительные сведения см. в разделе «Проверки среды выполнения для версий Android «). Если вы используете или создаете библиотеку , ознакомьтесь со следующими рекомендациями по настройке параметров уровня API для библиотек.
Версии Android и уровни API
По мере развития платформы Android и выпуска новых версий Android каждая версия Android назначается уникальный целочисленный идентификатор, называемый уровнем API. Таким образом, каждая версия Android соответствует одному уровню API Android. Так как пользователи устанавливают приложения на более старых и последних версиях Android, реальные приложения Android должны быть разработаны для работы с несколькими уровнями API Android.
Версии Android
Каждый выпуск Android проходит по нескольким именам:
- Версия Android, например Android 9.0
- Имя кода (или десерта), например Pie
- Соответствующий уровень API, например УРОВЕНЬ API 28
Имя кода Android может соответствовать нескольким версиям и уровням API (как показано в таблице ниже), но каждая версия Android соответствует ровно одному уровню API.
Кроме того, Xamarin.Android определяет коды версий сборки , которые сопоставляют с известными уровнями API Android. Следующая таблица поможет вам выполнить преобразование между уровнем API, версией Android, именем кода и кодом версии сборки Xamarin.Android (коды версий сборки определяются в Android.OS пространстве имен):
| Имя | Версия | Уровень API | Выпущено | Код версии сборки |
|---|---|---|---|---|
| Q | 10.0 | 29 | Август 2020 г. | BuildVersionCodes.Q |
| Pie | 9.0 | 28 | Август 2018 г. | BuildVersionCodes.P |
| Oreo | 8.1 | 27 | Декабрь 2017 г. | BuildVersionCodes.OMr1 |
| Oreo | 8.0 | 26 | Авг 2017 | BuildVersionCodes.O |
| Nougat | 7.1 | 25 | Декабрь 2016 г. | BuildVersionCodes.NMr1 |
| Nougat | 7,0 | 24 | Август 2016 г. | BuildVersionCodes.N |
| Marshmallow | 6.0 | 23 | Авг 2015 | BuildVersionCodes.M |
| Lollipop | 5.1 | 22 | Мар 2015 | BuildVersionCodes.LollipopMr1 |
| Lollipop | 5.0 | 21 | Ноя 2014 | BuildVersionCodes.Lollipop |
| Kitkat Watch | 4.4W | 20 | Июнь 2014 г. | BuildVersionCodes.KitKatWatch |
| Kitkat | 4.4. | 19 | Окт 2013 | BuildVersionCodes.KitKat |
| Желе Боб | 4.3 | 18 | Июль 2013 г. | BuildVersionCodes.JellyBeanMr2 |
| Желе Боб | 4.2-4.2.2 | 17 | Ноябрь 2012 г. | BuildVersionCodes.JellyBeanMr1 |
| Желе Боб | 4.1-4.1.1 | 16 | Июнь 2012 г. | BuildVersionCodes.JellyBean |
| Мороженое сэндвич | 4.0.3-4.0.4 | 15 | Декабрь 2011 г. | BuildVersionCodes.IceCreamSandwichMr1 |
| Мороженое сэндвич | 4.0-4.0.2 | 14 | Октябрь 2011 | BuildVersionCodes.IceCreamSandwich |
| Соты | 3.2 | 13 | Июнь 2011 г. | BuildVersionCodes.HoneyCombMr2 |
| Соты | 3.1.x | 12 | Май 2011 г. | BuildVersionCodes.HoneyCombMr1 |
| Соты | 3.0.x | 11 | Февраль 2011 г. | BuildVersionCodes.HoneyComb |
| Пряник | 2.3.3-2.3.4 | 10 | Февраль 2011 г. | BuildVersionCodes.GingerBreadMr1 |
| Пряник | 2.3-2.3.2 | 9 | Ноябрь 2010 г. | BuildVersionCodes.GingerBread |
| Froyo | 2.2.x | 8 | Июнь 2010 г. | BuildVersionCodes.Froyo |
| Eclair | 2.1.x | 7 | янв 2010 | BuildVersionCodes.EclairMr1 |
| Eclair | 2.0.1 | 6 | Декабрь 2009 г. | BuildVersionCodes.Eclair01 |
| Eclair | 2,0 | 5 | Ноябрь 2009 г. | BuildVersionCodes.Eclair |
| кольцевой график; | 1.6 | 4 | Сентябрь 2009 г. | BuildVersionCodes.Donut |
| Кекс | 1.5 | 3 | Май 2009 г. | BuildVersionCodes.Cupcake |
| Основной | 1,1 | 2 | Февраль 2009 г. | BuildVersionCodes.Base11 |
| Основной | 1,0 | 1 | Октябрь 2008 г. | BuildVersionCodes.Base |
Как показано в этой таблице, новые версии Android выпускаются часто — иногда более одного выпуска в год. В результате вселенная устройств Android, которые могут запускать ваше приложение, включает широкий спектр старых и новых версий Android. Как вы можете гарантировать, что ваше приложение будет работать согласованно и надежно в столь разных версиях Android? Уровни API Android помогут вам управлять этой проблемой.
Уровни API Android
Каждое устройство Android работает на одном уровне API. Этот уровень API гарантированно будет уникальным для каждой версии платформы Android. Уровень API точно определяет версию набора API, к которому может обращаться ваше приложение; он определяет сочетание элементов манифеста, разрешений и т. д., которые вы кодируете в качестве разработчика. Система уровней API Android помогает Android определить, совместимо ли приложение с системным образом Android перед установкой приложения на устройстве.
При построении приложения он содержит следующие сведения об уровне API:
Целевой уровень API Android, на который будет создано приложение.
Минимальный уровень API Android, необходимый устройству Android для запуска приложения.
Эти параметры используются для обеспечения того, чтобы функциональность, необходимая для правильного запуска приложения, была доступна на устройстве Android во время установки. В противном случае приложение заблокировано на этом устройстве. Например, если уровень API устройства Android ниже минимального уровня API, указанного для приложения, устройство Android не позволит пользователю устанавливать приложение.
параметры уровня API Project
В следующих разделах объясняется, как с помощью диспетчера пакетов SDK подготовить среду разработки для целевых уровней API, а затем подробно описано, как настроить целевую платформу, минимальную версию Android и параметры целевой версии Android в Xamarin.Android.
Платформы пакета SDK для Android
Прежде чем выбрать целевой или минимальный уровень API в Xamarin.Android, необходимо установить версию платформы пакета SDK для Android, соответствующую уровню API. Диапазон доступных вариантов для целевой платформы, минимальной версии Android и целевой версии Android ограничен диапазоном установленных версий пакета SDK для Android. Диспетчер пакетов SDK можно использовать для проверки того, установлены ли необходимые версии пакета SDK для Android, и его можно использовать для добавления новых уровней API, необходимых для вашего приложения. Если вы не знакомы с установкой уровней API, см. статью «Настройка пакета SDK для Android».
Требуемая версия .NET Framework
Целевая платформа (также известная как compileSdkVersion ) — это конкретная версия платформы Android (уровень API), для которую приложение компилируется во время сборки. Этот параметр указывает, какие API приложение ожидает использовать при его запуске, но не влияет на то, какие API фактически доступны вашему приложению при его установке. В результате изменение параметра Целевой платформы не изменяет поведение среды выполнения.
Целевая платформа определяет, какие версии библиотеки связаны с приложением. Этот параметр определяет, какие API можно использовать в приложении. Например, если вы хотите использовать метод NotificationBuilder.SetCategory , представленный в Android 5.0 Lollipop, необходимо задать для целевой платформы значение API уровня 21 (Lollipop) или более поздней версии. Если вы настроите целевую платформу проекта на уровень API, например API уровня 19 (KitKat) и попытаетесь вызвать SetCategory метод в коде, вы получите ошибку компиляции.
Рекомендуется всегда скомпилировать последнюю доступную версию Target Framework. Это обеспечивает полезные предупреждающие сообщения для любых устаревших API, которые могут вызываться кодом. Использование последней версии Target Framework особенно важно при использовании последних выпусков библиотеки поддержки. Каждая библиотека ожидает компиляцию приложения на минимальном уровне API библиотеки или выше.
- Visual Studio
- Visual Studio для Mac
Чтобы получить доступ к параметру целевой платформы в Visual Studio, откройте свойства проекта в Обозреватель решений и выберите страницу приложения:
Задайте целевую платформу, выбрав уровень API в раскрывающемся меню в разделе «Компиляция с помощью версии Android «, как показано выше.
Чтобы получить доступ к параметру целевой платформы в Visual Studio для Mac, щелкните правой кнопкой мыши имя проекта и выберите «Параметры«. Откроется диалоговое окно «Параметры Project«. В этом диалоговом окне перейдите к разделу «Общие сборки>«, как показано ниже:
Задайте целевую платформу, выбрав уровень API в раскрывающемся меню справа от целевой платформы , как показано выше.
Минимальная версия Android
Минимальная версия Android (также известная как minSdkVersion ) — это самая старая версия ОС Android (т. е. самый низкий уровень API), которая может установить и запустить приложение. По умолчанию приложение можно установить только на устройствах, соответствующих параметру целевой платформы или выше; Если минимальная версия Android меньше целевой платформы, приложение также может работать в более ранних версиях Android. Например, если установить целевую платформу на Android 7.1 (Nougat) и установить минимальную версию Android на Android 4.0.3 (Ice Cream Sandwich), приложение можно установить на любой платформе с уровня API 15 до уровня API 25 включительно.
Несмотря на то, что приложение может успешно выполнять сборку и установку на этих платформах, это не гарантирует успешное выполнение на всех этих платформах. Например, если приложение установлено на Android 5.0 (Lollipop) и код вызывает API, доступный только в Android 7.1 (Nougat) и более новых версиях, ваше приложение получит ошибку среды выполнения и, возможно, завершится сбоем. Поэтому код должен гарантировать, что во время выполнения он вызывает только те API, которые поддерживаются устройством Android, на котором он работает. Другими словами, код должен включать явные проверки среды выполнения, чтобы убедиться, что приложение использует новые API только на устройствах, которые достаточно недавно для их поддержки. В этом руководстве описано, как добавить эти проверки среды выполнения в код.
- Visual Studio
- Visual Studio для Mac
Чтобы получить доступ к параметру минимальной версии Android в Visual Studio, откройте свойства проекта в Обозреватель решений и выберите страницу манифеста Android. В раскрывающемся меню в разделе «Минимальная версия Android » можно выбрать минимальную версию Android для приложения:
Если выбрать «Использовать компиляцию с помощью версии пакета SDK«, минимальная версия Android будет совпадать с параметром целевой платформы.
Чтобы получить доступ к минимальной версии Android в Visual Studio для Mac, щелкните правой кнопкой мыши имя проекта и выберите пункт «Параметры«. Откроется диалоговое окно «Параметры Project«. Перейдите к разделу «Сборка > приложения Android«. В раскрывающемся меню справа от минимальной версии Android можно задать минимальную версию Android для приложения:
Если выбрать «Автоматический» — используйте версию целевой платформы, минимальная версия Android будет совпадать с параметром целевой платформы.
Целевая версия Android
Целевая версия Android (также известная как targetSdkVersion ) — это уровень API устройства Android, на котором приложение ожидает запуска. Android использует этот параметр, чтобы определить, следует ли включать какие-либо режимы совместимости. Это гарантирует, что ваше приложение будет работать так, как вы ожидаете. Android использует целевой параметр версии Android вашего приложения, чтобы выяснить, какие изменения поведения можно применить к приложению, не нарушая его (это то, как Android обеспечивает прямую совместимость).
Целевая платформа и целевая версия Android, имеющие очень похожие имена, не совпадают. Параметр Target Framework передает сведения о целевом уровне API в Xamarin.Android для использования во время компиляции, а целевая версия Android передает сведения о целевом уровне API Android для использования во время выполнения (когда приложение установлено и запущено на устройстве).
- Visual Studio
- Visual Studio для Mac
Чтобы получить доступ к этому параметру в Visual Studio, откройте свойства проекта в Обозреватель решений и выберите страницу манифеста Android. В раскрывающемся меню в разделе » Целевая версия Android » можно выбрать целевую версию Android для приложения:
Мы рекомендуем явно установить целевую версию Android на последнюю версию Android, которая используется для тестирования приложения. В идеале необходимо задать последнюю версию пакета SDK для Android. Это позволяет использовать новые API перед изменением поведения. Для большинства разработчиков не рекомендуется устанавливать целевую версию Android для использования компиляции с помощью версии пакета SDK.
Чтобы получить доступ к этому параметру в Visual Studio для Mac, щелкните правой кнопкой мыши имя проекта и выберите пункт «Параметры«. Откроется диалоговое окно «Параметры Project«. Перейдите к разделу «Сборка > приложения Android«. В раскрывающемся меню справа от целевой версии Android можно задать целевую версию Android для приложения:
Мы рекомендуем явно установить целевую версию Android на последнюю версию Android, которая используется для тестирования приложения. В идеале его следует установить в последнюю доступную версию пакета SDK для Android. Это позволяет использовать новые API перед выполнением изменений в поведении. Для большинства разработчиков не рекомендуется устанавливать для целевой версии Android значение «Автоматически». Используйте версию целевой платформы.
Как правило, целевая версия Android должна быть ограничена минимальной версией Android и целевой платформой. Это означает следующее:
Минимальная версия Android = целевая версия <Android = целевая платформа <
Дополнительные сведения об уровнях пакета SDK см. в документации разработчика android , использующего пакет SDK .
Проверка среды выполнения для версий Android
По мере выпуска каждой новой версии Android API платформы обновляется для предоставления новых или заменяющих функций. За некоторыми исключениями функции API из более ранних версий Android переносятся в более новые версии Android без изменений. В результате, если приложение выполняется на определенном уровне API Android, обычно оно сможет работать на более позднем уровне API Android без изменений. Но что делать, если вы также хотите запустить приложение в более ранних версиях Android?
Если выбрать минимальную версию Android, которая ниже параметра целевой платформы, некоторые API могут быть недоступны для приложения во время выполнения. Однако приложение по-прежнему может работать на более раннем устройстве, но с ограниченной функциональностью. Для каждого API, недоступного на платформах Android, соответствующих параметру минимальной версии Android, код должен явно проверить значение Android.OS.Build.VERSION.SdkInt свойства, чтобы определить уровень API платформы, на котором выполняется приложение. Если уровень API ниже минимальной версии Android, поддерживающей API, который требуется вызвать, код должен найти способ правильной работы, не выполняя этот вызов API.
Например, предположим, что мы хотим использовать метод NotificationBuilder.SetCategory для классификации уведомлений при запуске в Android 5.0 Lollipop (и более поздних версий), но мы по-прежнему хотим, чтобы наше приложение работало на более ранних версиях Android, таких как Android 4.1 Jelly Bean (где SetCategory недоступно). Ссылаясь на таблицу версий Android в начале этого руководства, мы видим, что код версии сборки для Android 5.0 Lollipop имеет значение Android.OS.BuildVersionCodes.Lollipop . Для поддержки старых версий Android, где SetCategory она недоступна, наш код может обнаруживать уровень API во время выполнения и условно вызывать SetCategory только в том случае, если уровень API больше или равен коду версии сборки Lollipop:
В этом примере целевая платформа приложения имеет значение Android 5.0 (уровень API 21), а минимальная версия Android — Android 4.1 (уровень API 16). Так как SetCategory он доступен на уровне Android.OS.BuildVersionCodes.Lollipop API и более поздних версий, этот пример кода будет вызываться SetCategory только в том случае, если уровень SetCategory API равен 16, 17, 18, 19 или 20. Эти более ранние версии Android сокращаются только в той степени, в которой уведомления отсортированы неправильно (так как они не классифицируются по типу), но уведомления по-прежнему публикуются для оповещения пользователя. Наше приложение по-прежнему работает, но его функциональность немного уменьшается.
Как правило, проверка версии сборки помогает коду решать во время выполнения между новым способом и старым способом. Пример:
Нет быстрого и простого правила, объясняющего, как уменьшить или изменить функциональные возможности приложения при запуске в более старых версиях Android, которые не имеют одного или нескольких API. В некоторых случаях (например, в SetCategory приведенном выше примере) достаточно пропустить вызов API, если он недоступен. Однако в других случаях может потребоваться реализовать альтернативные функции, чтобы при Android.OS.Build.VERSION.SdkInt обнаружении было меньше уровня API, необходимого приложению для оптимального взаимодействия.
Уровни и библиотеки API
- Visual Studio
- Visual Studio для Mac
При создании проекта библиотеки Xamarin.Android (например, библиотеки классов или библиотеки привязок) можно настроить только параметр целевой платформы— минимальная версия Android и параметры целевой версии Android недоступны. Это связано с отсутствием страницы манифеста Android :
При создании проекта библиотеки Xamarin.Android отсутствует страница приложения Android , на которой можно настроить минимальную версию Android и целевую версию Android— минимальная версия Android и параметры целевой версии Android недоступны. Это связано с отсутствием страницы «Сборка > приложения Android «:
Минимальная версия Android и параметры целевой версии Android недоступны, так как результирующая библиотека не является автономным приложением. Библиотека может выполняться в любой версии Android в зависимости от приложения, с которым оно упаковано. Вы можете указать способ компиляции библиотеки, но нельзя предсказать, на каком уровне API платформы будет выполняться библиотека. Учитывая это, при использовании или создании библиотек следует соблюдать следующие рекомендации.
При использовании библиотеки Android — если вы используете библиотеку Android в приложении, обязательно задайте для параметра целевой платформы приложения уровень API, который не ниже , чем параметр целевой платформы библиотеки.
При создании библиотеки Android — если вы создаете библиотеку Android для использования другими приложениями, обязательно задайте для параметра Target Framework минимальный уровень API, необходимый для компиляции.
Эти рекомендации рекомендуется, чтобы предотвратить ситуацию, когда библиотека пытается вызвать API, который недоступен во время выполнения (что может привести к сбою приложения). Если вы являетесь разработчиком библиотеки, следует стремиться ограничить использование вызовов API небольшим и хорошо установленным подмножеством общей контактной зоны API. Это помогает обеспечить безопасное использование библиотеки в более широком диапазоне версий Android.
Android API Levels
This is an overview of all Android versions and their corresponding identifiers for Android developers. Anyone is welcome to open an issue or pull request. Happy developing!
- targetSdk must be 31+ for new apps.
- targetSdk will need to be 31+ for app updates by Nov 2022 and all existing apps by Nov 2023. 3
- targetSdk must be 30+ for app updates, and new WearOS apps.
- targetSdk will need to be 30+ for all existing apps by November 2022. 3
- targetSdk must be 28+ for Wear OS app updates.
-
requires a minSdk of 21 or higher.
- Google Play services do not support Android versions below API level 19.
-
/AndroidX libraries require a minSdk of 14 or higher.
Definitions
Gradle files
| Kotlin variable | Groovy variable | Definition |
|---|---|---|
| minSdk | minSdkVersion | The minimum SDK version your app will support, defined in build.gradle . For example, if your minSdk is 26, this SDK version corresponse to API Level 26 and Android 8, so your app will only run on devices with Android 8 or higher. |
| targetSdk | targetSdkVersion | The SDK version that your app targets, defined in build.gradle . This should always be the same as compileSdk . |
| compileSdk | compileSdkVersion | The SDK version that your app compiles against, defined in build.gradle . Android Studio uses this SDK version to build your AABs and APKs. This should always be the same as targetSdk . |
Code files
| Variable | Definition |
|---|---|
| Build.VERSION.SDK_INT | The SDK version of the Android OS currently running on the user’s device. For example, on a device running Android 11, this value will be 30 (aka Build.VERSION_CODES.R ), even if the target and compile SDK of the app is different. |
Footnotes
Cumulative usage distribution figures were last updated on August 9, 2022 using data from Statcounter GlobalStats. These figures may have changed significantly since the last update. You may update the figures yourself with a pull request. ↩
The codenames for Android 10 and above in the table are the internal codenames. Beginning with Android 10, Google dropped the usage of codenames publicly. ↩
In 2022, Google began imposing minimum targetSdk requirements for existing apps, in addition new apps and app updates. Existing apps that are not updated to meet targetSdk requirements by their deadlines will be subject to restrictions. This requirement excludes Wear OS apps. ↩
SDK Platform release notes
This page provides release information about the SDK packages available for download from the SDK Manager, in the SDK Platforms tab.
Each SDK Platform version includes the following packages:
- The Android SDK Platform package. This is required to compile your app for that version.
- Several System Image packages. At least one of these is required to run that version on the Android Emulator.
Each platform version includes a system image for each supported form factor (handsets, Android TV, and Android Wear). Each form factor may offer variations to match your computer’s processor architecture (such as Intel x86 and ARM EABI). System images labeled Google APIs include access to Google Play services and those labeled Google Play also include Google Play Store.
The revision numbers listed below are for the Android SDK Platform package only. The system images may receive separate updates, usually to resolve bugs with the emulator. There are no release notes for the system images, but you should always keep them up to date.
Important: To see the most recent Android system components in the Android SDK Manager, you must first install the most recent Android SDK Command-Line tools package.
Android 13 (API level 33)
For details about the platform changes, see the Android 13 documentation.
Android 12 (API levels 31, 32)
This Automated Test Device (ATD) image is an Android system image that is optimized for headless automated tests. Early data indicates that tests that use this image should experience reduction in emulator process CPU and memory usage, and reduction in test wall time.
It achieves these performance gains through:
- Removing most user-facing applications (for example Dialer, Settings, and SystemUI).
- Disabling hardware renderer drawing.
The image comes with two versions: Google APIs ATD which provides Google APIs, and AOSP ATD which provides pure AOSP experience.
To learn more about running tests using ATDs, see Run tests using Automated Test Devices.
Android 11 (API level 30)
For details about the platform changes, see the Android 11 documentation.
Android 10 (API level 29)
For details about the platform changes, see Android 10 for Developers.
Revision 5 (July 2020)
This revision adds Android Automotive OS stubs.
Android 9 (API level 28)
For details about the platform changes, see Android 9 for developers.
Revision 1 (August 2018)
Released to stable channel (no longer in preview).
Android 8.1 (API level 27)
For details about the platform changes, see Android 8.1 for developers.
Revision 1 (December 2017)
Released to stable channel (no longer in preview).
Android 8.0 (API level 26)
For details about the platform changes, see Android 8.0 for developers.
Revision 2 (August 2017)
Released to stable channel (no longer in preview).
Android 7.1 (API level 25)
For details about the platform changes, see Android 7.1 for developers.
Revision 3 (December 2016)
Incremental update. Released as the final Android 7.1.1 (no longer in preview).
- Android SDK Platform-Tools 25.0.1 or higher is required.
- Android SDK Build-Tools 25.0.1 or higher is required.
Revision 2 (November 2016)
Incremental update. Released as Android 7.1.1 Developer Preview 2. For more information, see the Android 7.1 API Overview.
- Android SDK Platform-Tools 25.0.1 or higher is required.
- Android SDK Build-Tools 25.0.1 or higher is required.
Revision 1 (October 2016)
Initial release for Android 7.1 (API level 25). Released as Android 7.1 Developer Preview 1. For more information, see the Android 7.1 API Overview.
- Android SDK Platform-Tools 25.0.0 or higher is required.
- Android SDK Build-Tools 25.0.0 or higher is required.
Android 7.0 (API level 24)
For details about the platform changes, see Android 7.0 for developers.
Revision 1 (August 2016)
Initial release for Android 7.0 (API level 24). For more information, see the Android 7.0 API Overview.
- Android SDK Platform-tools r24 or higher is required.
- Android SDK Tools 24.0.0 or higher is required.
Android 6.0 (API level 23)
For details about the platform changes, see the Android 6.0 changes and Android 6.0 APIs.
Revision 2 (November 2015)
Fixed bugs in the layout rendering library used by Android Studio.
- Android SDK Platform-tools r23 or higher is required.
- Android SDK Tools 24.3.4 or higher is required.
Revision 1 (August 2015)
Initial release for Android 6.0 (API level 23). For more information, see the Android 6.0 API Overview.
- Android SDK Platform-tools r23 or higher is required.
- Android SDK Tools 24.3.4 or higher is required.
Android 5.1 (API level 22)
For details about the platform changes, see the Lollipop overview and Android 5.1 API changes.
Revision 1 (March 2015)
Initial release for Android 5.1 (API level 22). For more information, see the Android 5.1 API Overview.
- Android SDK Platform-tools r22 or higher is required.
- Android SDK Tools 23.0.5 or higher is required.
Android 5.0 (API level 21)
For details about the platform changes, see the Lollipop overview and Android 5.0 API changes.
Revision 2 (December 2014)
Updated layouts in the Support Library and fixed various issues.
- Android SDK Platform-tools r21 or higher is required.
- Android SDK Tools 23.0.5 or higher is required.
Revision 1 (October 2014)
Initial release for Android 5.0 (API level 21). For more information, see the Android 5.0 API Overview.
- Android SDK Platform-tools r21 or higher is required.
- Android SDK Tools 23.0.5 or higher is required.
Android 4.4W (API level 20)
This version makes KitKat available for Android Wear.
Revision 2 (October 2014)
Updated the rendering library.
- Android SDK Platform-tools r20 or higher is required.
- Android SDK Tools 23.0 or higher is required.
Revision 1 (June 2014)
Initial release for Android Wear.
- Android SDK Platform-tools r20 or higher is required.
- Android SDK Tools 23.0 or higher is required.
Android 4.4 (API level 19)
For details about the platform changes, see the KitKat overview and Android 4.4 API changes.
Revision 2 (December 2013)
Maintenance release. The system version is 4.4.2. For more information, see the Android 4.4 API Overview.
Dependencies: Android SDK Platform-tools r19 or higher is required. Android SDK Tools 22.3 or higher is recommended.
Revision 1 (October 2013)
Initial release. The system version is 4.4. For more information, see the Android 4.4 API Overview.
Dependencies: Android SDK Platform-tools r19 or higher is required. Android SDK Tools 22.3 or higher is recommended.
Android 4.3 (API level 18)
For details about the platform changes, see the Jelly Bean overview and Android 4.3 API changes.
Revision 2 (August 2013)
Maintenance update. The system version is 4.3.
Dependencies: Android SDK Platform-tools r18 or higher is required. Android SDK Tools 22.0.4 or higher is recommended.
Revision 1 (July 2013)
Initial release. The system version is 4.3.
Dependencies: Android SDK Platform-tools r18 or higher is required. Android SDK Tools 22.0.4 or higher is recommended.
Android 4.2 (API level 17)
For details about the platform changes, see the Jelly Bean overview and Android 4.2 API changes.
Revision 2 (February 2013)
Maintenance update. The system version is 4.2.2.
Dependencies: SDK Tools r21 or higher is required.
Revision 1 (November 2012)
Initial release. The system version is 4.2.
Dependencies: SDK Tools r20 or higher is required.
Android 4.1 (API level 16)
For details about the platform changes, see the Jelly Bean overview and Android 4.1 API changes.
Revision 3 (October 2012)
Maintenance update. The system version is 4.1.2.
Dependencies: SDK Tools r20 or higher is required.
Revision 2 (July 2012)
Maintenance update. The system version is 4.1.1.
Dependencies: SDK Tools r20 or higher is required.
Revision 1 (June 2012)
Initial release. The system version is 4.1.0.
Dependencies: SDK Tools r20 or higher is required.
Android 4.0.3 (API level 15)
Revision 3 (March 2012)
Maintenance update. The system version is 4.0.4.
Note: This system image includes support for emulator hardware graphics acceleration when used with SDK Tools r17 or higher. (more info)
Dependencies: SDK Tools r17 or higher is required.
Revision 2 (January 2012)
Maintenance update. The system version is 4.0.3.
Dependencies: SDK Tools r14 or higher is required.
Revision 1 (December 2011)
Initial release. The system version is 4.0.3.
Dependencies: SDK Tools r14 or higher is required.
Android 4.0 (API level 14)
Android 4.0, Revision 2 (December 2011)
Maintenance update. The system version is 4.0.2.
Dependencies: SDK Tools r14 or higher is required.
Android 4.0, Revision 1 (October 2011)
Initial release. The system version is 4.0.1.
Dependencies: SDK Tools r14 or higher is required.
Android 3.2 (API level 13)
Android 3.2, Revision 1 (July 2011)
Android 3.1 (API level 12)
Android 3.1, Revision 3 (July 2011)
Requires SDK Tools r12 or higher.
Improvements to the platform’s rendering library to support the visual layout editor in the ADT Eclipse plugin. This revision allows for more drawing features in ADT and fixes several bugs in the previous rendering library. It also unlocks several editor features that were added in ADT 12.
Android 3.1, Revision 2 (May 2011)
Requires SDK Tools r11 or higher.
Fixes an issue with the visual layout editor rendering library that prevented Android 3.1 from running in ADT.
Android 3.1, Revision 1 (May 2011)
Requires SDK Tools r11 or higher.
Android 3.0 (API level 11)
Android 3.0, Revision 2 (July 2011)
Requires SDK Tools r12 or higher.
Improvements to the platform’s rendering library to support the visual layout editor in the ADT Eclipse plugin. This revision allows for more drawing features in ADT and fixes several bugs in the previous rendering library. It also unlocks several editor features that were added in ADT 12.
Android 3.0, Revision 1 (February 2011)
Requires SDK Tools r10 or higher.
Android 2.3.3 (API level 10)
Android 2.3.3, Revision 2 (July 2011)
Requires SDK Tools r12 or higher.
Improvements to the platform’s rendering library to support the visual layout editor in the ADT Eclipse plugin. This revision allows for more drawing features in ADT and fixes several bugs in the previous rendering library. It also unlocks several editor features that were added in ADT 12.