Уровень Android API, обратная и прямая совместимость
Добрый вечер, друзья. Мы подготовили полезный перевод для будущих студентов курса «Android-разработчик. Продвинутый курс». С радостью делимся с вами данным материалом.
Если вы читаете эту статью, значит вас могут интересовать такие вещи, как:
Что означает уровень 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 в Android Studio SDK Manager.
На второй вкладке 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.
Версия API, доступная на этом уровне, соответствует версии платформы Android, на которой запущено приложение.
Например, если на фактическом устройстве установлен Android 9 (Pie), доступны все API до 28 уровня.
Если вам понятны ключевые моменты работы Android Runtime и какова роль API, то должно быть достаточно просто понять обратную и прямую совместимость, а так же использование compileSdkVersion , minSdkVersion и targetSdkVersion .
compileSdkVersion
Это значение используется только для указания Gradle, с какой версией SDK компилировать ваше приложение. Это позволяет разработчикам получить доступ ко всем API, доступным до уровня API, установленного для compileSdkVersion .
Настоятельно рекомендуется выполнить компиляцию с последней версией SDK:
высокий уровень API позволяет разработчикам использовать преимущества последнего API и возможностей, предоставляемых новыми платформами.
чтобы использовать последнюю версию SupportLibrary , compileSdkVersion должен соответствовать версии SupportLibrary .
Например, чтобы использовать SupportLibrary-28.x.x , compileSdkVersion также должен быть равен 28.
для перехода на AndroidX или его использования, compileSdkVersion должен быть установлен как минимум равным 28.
чтобы быть готовым удовлетворить требования целевого уровня API от Google Play. В Google объявили, что для более быстрого распространения новых версий Android на рынке Google каждый год будет устанавливать минимальный целевой уровень API для новых приложений и обновлений. Больше информации вы можете найти здесь и здесь.
Приложения Android совместимы с новыми версиями платформы Android, поскольку изменения в API обычно являются аддитивными, а старое 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, поэтому всегда следует иметь высокий приоритет для обновления этого значения.
Теперь соединяя все это вместе, мы видим четкое отношение
Имейте в виду, что настоятельно рекомендуется выполнить компиляцию в соответствии с последним уровнем API и стараться использовать targetSdkVersion == compileSdkVersion.
Источник
Google IMA Android SDK release history
Version
Release Date
Notes
3.25.1
11/08/2021
Adds AdsRenderingSettings.setEnableCustomTabs() and AdsRenderingSettings.getEnableCustomTabs() for in-app click-through of ads using custom tabs.
Starting from version 3.25.1, IMA SDK includes the com.google.android.gms.permission.AD_ID permission in the SDK’s manifest that is automatically merged into the app manifest by Android build tools. To learn more about the AD_ID permission declaration, including how to disable it, refer to this Play Console Help article.
Adds support for the app set ID for use cases such as reporting and fraud prevention.
Adds performance improvements when using multiple AdsLoader instances by supporting thread caching and reuse.
3.24.0
6/3/2021
Adds fixed-point precision APIs for the CuePoint and StreamManager classes used in DAI. This adds the following APIs:
Prevents a NullPointerException error related to internal calls to StreamRequest.getContentUrl() .
SDK version 3.24.0 will be deprecated on 11/08/2022. See the Deprecation Schedule for more details.
3.23.0
4/7/2021
Adds the ImaSdkSettings.setSessionId() and the ImaSdkSettings.getSessionId() methods to get and set the Session ID. This is a temporary random ID used exclusively for frequency capping.
Fixes a NullPointerException error related to companion ads.
Disables javascript within companion ads below API level 21 to fix an issue with security vulnerabilities.
SDK version 3.23.0 will be deprecated on 6/3/2022. See the Deprecation Schedule for more details.
3.22.3
3/16/2021
Fixes a NullPointerException error related to releasing the AdsLoader while an ad is being loaded.
Adds the 1206 error for an UNEXPECTED_ADS_LOADED_EVENT in cases when an ads loaded event is sent unexpected.
SDK version 3.22.3 will be deprecated on 4/7/2022. See the Deprecation Schedule for more details.
3.22.2
2/26/2021
The IMA SDK now depends on the following libraries:
com.google.android.gms:play-services-base
com.google.android.gms:play-services-basement
androidx.preference:preference
Fixes the error message when AdsLoader would receive an error without a valid session ID.
SDK version 3.22.2 will be deprecated on 3/16/2022. See the Deprecation Schedule for more details.
3.22.0
1/11/2021
Adds pod serving for DAI streams. In the pod serving workflow, Ads Manager is only responsible for serving ads. Publishers are responsible for content and creating the manifest that will then point to Ads Manager. Use ImaSdkFactory.createPodStreamRequest() to create a stream request for pod serving. If using this, you will be responsible for loading the stream on streamInit() .
Fixes a memory leak caused by the app lifecycle monitor not being properly cleaned up.
SDK version 3.22.0 will be deprecated on 2/26/2022. See the Deprecation Schedule for more details.
3.21.4
12/9/2020
Removes a harmless warning message related to calling adsLoader.release() after the webview has been destroyed.
SDK version 3.21.4 will be deprecated on 1/8/2022. See the Deprecation Schedule for more details.
3.21.2
11/20/2020
Fixes unexpected thread-safe issues caused by sending message updates from an empty queue.
Updates the documentation for AdsLoader.release() .
SDK version 3.21.2 will be deprecated on 12/9/2021. See the Deprecation Schedule for more details.
3.21.1
11/17/2020
Fixes an issue that occasionally led to app crashes when events were fired.
SDK version 3.21.1 will be deprecated on 11/20/2021. See the Deprecation Schedule for more details.
3.21.0
10/23/2020
Adds support for SIMID ads in the DAI Android SDK.
Adds the AdsLoader.release() method and deprecates BaseDisplayContainer.destroy() . This change resolves a memory leak which occurred when disposing of a BaseDisplayContainer in the middle of a VMAP ad schedule. AdsLoader.release() is the new recommended method to dispose of IMA SDK objects, instead of using BaseDisplayContainer.destroy() .
SDK version 3.21.0 will be deprecated on 11/17/2021. See the Deprecation Schedule for more details.
3.20.1
10/12/2020
Fixes an issue with HTMLResource companions on API Level 29+ of Android. The change in Android API behavior is documented here.
SDK version 3.20.1 will be deprecated on 10/23/2021. See the Deprecation Schedule for more details.
3.20.0
8/18/2020
Version 3.20.0 is the first version that will be affected by the changes to IMA pause behavior. If you use this or any future version of the SDK we recommend reading the blog post and making the changes to pause behavior in your application. Publishers can test their implementation of these changes using this ad tag.
Adds the onPause() and onResume() callbacks for the DAI VideoStreamPlayer class.
Adds the adPeriodDuration() method to the AdProgressInfo class.
Adds support for icon click fallback images on Android TV devices.
Adds the ICON_FALLBACK_IMAGE_CLOSED event to handle when the icon fallback image is closed on Android TV devices.
Removes the deprecated focusSkipButton() method from AdsManager in favor of the focus() method.
For CTV devices, ads are now auto focused when the AdEvent.AdEventType STARTED event is fired. To disable auto focus for ads, use the adsRenderingSettings.setFocusSkipButtonWhenAvailable(false) method and then use the focus() method based on the custom requirements.
Adds the getCurrentTimeMs() and getDurationMs methods to the VideoProgressUpdate() class.
Deprecates the getCurrentTime and getDuration methods in favor of the new getCurrentTimeMs and getDurationMs methods.
Fixes an issue for DASH live streams where ad events were not being reported correctly.
SDK version 3.20.0 will be deprecated on 10/12/2021. See the Deprecation Schedule for more details.
3.19.4
7/8/2020
Fixes an issue that was preventing setLoadVideoTimeout from correctly updating the timeout.
SDK version 3.19.4 will be deprecated on 8/18/2021. See the Deprecation Schedule for more details.
3.19.3
6/29/2020
Fixes an issue with the IAB TCF integration for GDPR that caused crashes for players integrated with Consent Management Platform SDKs.
SDK version 3.19.3 will be deprecated on 7/8/2021. See the Deprecation Schedule for more details.
3.19.2
6/22/2020
Fixes an issue that caused the SDK to ignore VideoAdPlayerCallback.onContentComplete() events outside of ad playback.
Adds the ability to specify different DAI subtitle sets for the same language by using the subtitle_name parameter for VideoStreamPlayer.loadUrl() .
SDK version 3.19.2 will be deprecated on 6/29/2021. See the Deprecation Schedule for more details.
3.19.0
5/12/2020
Adds the VideoAdPlayerCallback.onLoaded() callback to VideoAdPlayer .
Deprecates AdsLoader.contentComplete() in favor of VideoAdPlayerCallback.onContentComplete() and VideoStreamPlayerCallback.onContentComplete() .
SDK version 3.19.0 will be deprecated on 6/22/2021. See the Deprecation Schedule for more details.
3.18.1
3/25/2020
Adds scaling for Companion Ads on high-pixel-density devices.
Adds support for client-side SIMID ads.
SDK version 3.18.1 will be deprecated on 5/12/2021. See the Deprecation Schedule for more details.
3.18.0
3/4/2020
Adds pause() and resume() to the VideoStreamPlayer interface. These must be implemented for v3.18.0 and later.
SDK version 3.18.0 will be deprecated on 3/25/2021. See the Deprecation Schedule for more details.
3.17.0
2/7/2020
Adds the following APIs to move the validation of display containers to the time of their creation:
Adds the ImaSdkFactory.createSdkOwnedPlayer which should be used by those using IMAs built-in player (SdkOwnedPlayer). It should be manually constructed and passed into the constructor for AdDisplayContainer.
Adds not null checks to setAdContainer and setPlayer .
Updates cuepoint data to now use floating point precision.
SDK version 3.17.0 will be deprecated on 3/4/2021. See the Deprecation Schedule for more details.
3.16.5
1/22/2020
Reworks support for OMID 1.3 contentUrl with AdsRequest.setContentUrl and StreamRequest.setContentUrl .
Reworks support for OMID 1.3 friendly obstructions with FriendlyObstruction .
Deprecates the methods BaseDisplayContainer.registerVideoControlsOverlay and BaseDisplayContainer.unregisterAllVideoControlsOverlay in favor of FriendlyObstruction .
Fixes an issue with a NullPointerException occurring after calling clear() on CompanionAdSlots .
Fixes an issue that was potentially causing memory leaks when calling destroy() during ad playback.
SDK version 3.16.5 will be deprecated on 2/7/2021. See the Deprecation Schedule for more details.
3.16.2
12/5/2019
Adds support for automatic inclusion of consent parameters from IAB TCFv2 and CCPA.
Using Android preferences now requires the androidx package.
SDK version 3.16.2 will be deprecated on 1/22/2021. See the Deprecation Schedule for more details.
3.16.1
11/8/2019
Adds a new method to the ImaSdkFactory for createAudioAdDisplayContainer
SDK version 3.16.1 will be deprecated on 12/5/2020. See the Deprecation Schedule for more details.
3.16.0
10/23/2019
Adds the replaceAdTagParameters method to the StreamManager, which provides the ability to replace all ad tag parameters during a live stream.
Removes support of the following deprecated methods:
SDK version 3.16.0 will be deprecated on 11/8/2020. See the Deprecation Schedule for more details.
3.14.0
9/11/2019
Service release, no new features.
SDK version 3.14.0 will be deprecated on 10/23/2020. See the Deprecation Schedule for more details.
3.13.1
9/3/2019
Adds the ability to set the continuous play context for an ads request. See the setContinuousPlayback() for more details.
Adds the getUniversalAdIds() method to the Ad class.
Adds the setAuthToken, getAuthToken, setFormat, getFormat and the StreamFormat enum.
Fixes an error in nexus 5 devices that occurs when a container is removed before receiving an ad response.
Fixes an issue where companion ads would only render once.
Fixes an issue where unsupported ad types (nonlinears, VPAID) were not failing gracefully.
SDK version 3.13.1 will be deprecated on 9/11/2020. See the Deprecation Schedule for more details.
3.11.3
6/11/2019
Fixes bug with is_lat setting on AOSP devices.
SDK version 3.11.3 will be deprecated on 9/3/2020. See the Deprecation Schedule for more details.
3.11.2
4/16/2019
Fixes the following crash: java.lang.ClassNotFoundException: Didn’t find class «j$.util.concurrent.ConcurrentHashMap» .
SDK version 3.11.0 is officially deprecated as of 6/11/2020. See the Deprecation Schedule for more details.
3.11.0 Deprecated
3/22/2019
Introduces support for the Open Measurement SDK for third-party viewability.
Adds the registerVideoControlsOverlay() and unregisterAllVideoControlsOverlays() methods to BaseDisplayContainer .
SDK version 3.10.9 will be deprecated on 3/22/2020. See the Deprecation Schedule for more details.
3.10.9
3/13/2019
Fixed a race condition bug where ad UI sometimes doesn’t render on subsequent ads after the first ad is skipped.
Fixed a crash that occurred when calling the getCompanionAds() API.
SDK version 3.10.7 will be deprecated on 3/22/2020. See the Deprecation Schedule for more details.
3.10.7
2/19/2019
Adds the onAdPeriodStarted() and onAdPeriodEnded() ad events. These events are supported for DAI only.
SDK version 3.10.6 will be deprecated on 3/13/2020. See the Deprecation Schedule for more details.
3.10.6
1/23/2019
Adds seek() method to the stream player interface.
Adds support for AD_BUFFERING ad event callbacks.
Containers must no longer be passed in the ad request. The new workflow requires a container to be passed through an AdsLoader constructor.
Adds the BaseDisplayContainer.destroy() method.
Fixes a memory leak that occurred when video playback completes.
Deprecates requestNextAdBreak . This API will be removed in a future release. Afterwards, ads will automatically be feched 4 seconds before ad break time.
SDK version 3.10.2 will be deprecated on 2/19/2020. See the Deprecation Schedule for more details.
3.10.2
11/13/2018
Fixes a race condition that causes the second ad in a pod to throw a VAST 402 error.
Adds frequency capping and competitive exclusion to the DAI Android SDK.
Moves getAdProgressInfo() from StreamManager to BaseManager .
Adds getVastMediaHeight() , getVastMediaWidth() and getVastMediaBitrate() to Ad .
SDK version 3.9.4 will be deprecated on 1/23/2020. See the Deprecation Schedule for more details.
3.9.4
8/1/2018
Adds getCompanionAds() to Ad . This returns companion ads while using DAI only.
Adds new CompanionAd class.
Adds new SKIPPABLE_STATE_CHANGED event to AdEvent .
Fixes an issue where the default setting for focusSkipButtonWhenAvailable wasn’t being respected in some cases.
SDK version 3.9.0 will be deprecated on 8/1/2019. See the Deprecation Schedule for more details.
3.9.0
7/9/2018
Android TV is now supported.
Adds focusSkipButton() to AdsManager . This will only work on Android TV.
Adds getFocusSkipButtonWhenAvailable() to AdsRenderingSettings , defaulting to true . This will only work on Android TV.
Adds setFocusSkipButtonWhenAvailable() to AdsRenderingSettings . This will only work on Android TV.
VideoAdPlayer now extends the VolumeProvider interface. Implementing this interface is now required for custom playback.
SDK version 3.8.7 will be deprecated on 7/9/2019. See the Deprecation Schedule for more details.
3.8.7
5/23/2018
Allows animation in HTML companion ads.
SDK version 3.8.5 will be deprecated on 5/23/2019. See the Deprecation Schedule for more details.
3.8.5
4/9/2018
Fixes an issue with ImaSdkSettings being ignored.
Fixes an issue where there were build conflicts with com.android.support version files.
Adds setAdWillPlayMuted to AdsRequest .
Adds setLoadVideoTimeout to AdsRenderingSettings .
SDK version 3.8.2 will be deprecated on 4/9/2019. See the Deprecation Schedule for more details.
3.8.2
1/24/2018
Adds setLiveStreamPrefetchSeconds to AdsRequest .
Various documentation fixes.
SDK version 3.7.4 will be deprecated on 1/24/2019. See the Deprecation Schedule for more details.
3.7.4
6/29/2017
Adds setVastLoadTimeout to AdsRequest .
Adds getSkipTimeOffset to Ad .
SDK version 3.7.2 will be deprecated on 6/29/2018. See the Deprecation Schedule for more details.
3.7.2
5/25/2017
Adds setDebugMode to ImaSdkSettings .
SDK version 3.7.1 will be deprecated on 5/25/2018. See the Deprecation Schedule for more details.
3.7.1
3/24/2017
Resolves a namespace conflict when using Proguard.
Jar size reduced by around 30KB.
SDK version 3.7.0 will be deprecated on 3/24/2018. See the Deprecation Schedule for more details.
3.7.0
3/13/2017
Fixes an issue where some IMA classes were inadvertently merged into ProGuard’s a.a.a.a package.
SDK version 3.6.0 will be deprecated on 3/13/2018. See the Deprecation Schedule for more details.
3.6.0
2/16/2017
Adds the following to Ad :
getAdWrapperCreativeIds()
getAdvertiserName()
getCreativeAdId()
getCreativeId()
getDealId()
getSurveyUrl()
getUniversalAdIdRegistry()
getUniversalAdIdValue()
Adds AdsManager.requestNextAdBreak().
Adds the following to AdsRenderingSettings :
setEnablePreloading()
getEnablePreloading()
Adds the following to AdsRequest :
setContentDuration()
setContentKeywords()
setContentTitle()
SDK version 3.5.2 will be deprecated on 2/16/2018. See the Deprecation Schedule for more details.
3.5.2
11/14/2016
Adds an SDK-owned video player that optionally handles ad playback.
Adds CompanionAdSlot.ClickListener and methods to add and remove a listener.
Fixes an issue with invalid getViewability() error logs.
Fixes an issue with icons’ clickthrough behavior and not rendering correctly.
SDK version 3.4.0 will be deprecated on 11/14/2017. See the Deprecation Schedule for more details.
3.4.0
9/12/2016
Fixes a duplicate files error when using Google Play Services version 9.0.0 and up.
3.3.2
7/11/2016
Adds AD_BREAK_STARTED and AD_BREAK_ENDED events to AdEventListener.onAdEvent callback.
3.3.0
5/31/2016
Adds AdsRenderingSetting.setPlayAdsAfterTime.
3.2.1
4/7/2016
Service release, no new features.
3.1.3
12/16/2015
Out of beta.
Adds AdsManager.discardAdBreak to the API.
3.b13.3 (beta)
9/10/2015
Service release, no new features.
3.b12.1 (beta)
7/20/2015
Allows the user to customize ad UI elements via AdsRenderingSettings.setUiElements.
Adds ability to play ad breaks manually instead of automatically. See Manual Ad Break Playback.
Adds the restriction that ContentProgressProvider.getContentProgress should never return null.
Adds AdEvent.TAPPED which will fire when the user taps on any non-clickable region of a video ad.
3.b11.4 (beta)
5/21/2015
Adds the following to the API:
AdError.AdErrorCode.VAST_EMPTY_RESPONSE
AdError.getErrorNumber()
AdsRequest.setAdWillAutoPlay(Boolean)
CompanionAdSlot.isFilled()
ImaSdkSettings.setPlayerType(String)
ImaSdkSettings.setPlayerVersion(String)
3.b10.3 (beta)
3/24/2015
Added ImaSdkSettings.getMaxRedirects and ImaSdkSettings.setMaxRedirects .
IMA API classes are now final .
SDK version numbers are now in the format 3.bX.Y with b to indicate the SDK’s beta status.
The following AdError.AdErrorCode values have been removed:
API_ERROR — instead use UNKNOWN_AD_RESPONSE .
PLAYLIST_MALFORMED_RESPONSE — instead use UNKNOWN_AD_RESPONSE .
REQUIRED_LISTENERS_NOT_ADDED — was not being raised by the SDK.
VAST_INVALID_URL — instead use VAST_LOAD_TIMEOUT .
Beta v9
10/17/2014
Adds the Ad APIs getTitle , getDescription , and getContentType .
Adds information about ad pod position to the ad UI, for example, «Ad 1 of 4: (0:13)».
You should no longer directly control the pause/play/resume of ads via your video player. Instead, use AdsManager.pause() and AdsManager.resume() .
Beta v8
6/12/2014
Fixes an issue with the ad UI not clearing for skippable ads.
Documents the error code for media file load timeouts.
Beta v7
5/27/2014
Fixes an issue with Google Play Services. The SDK now requires that Google Play Services be built into your app. For more information, see Set Up Google Play Services SDK.
Beta v6
4/14/2014
Adds VAST 3 support.
Adds partial VMAP support (parity with current Ad Manager ad rules).
Adds the following to the API:
AdError.AdErrorCode.ADS_REQUEST_NETWORK_ERROR
AdEvent.AdEventType.LOG
AdEvent.getAdData()
AdPodInfo.getMaximumDuration()
AdPodInfo.getPodIndex()
AdPodInfo.getTimeOffset()
Fixes a bug where mid-rolls with an optimized pod with a wrapper caused all other ads in the pod to be skipped.
AdsRenderingSettings passsed to the AdsManager will no longer be ignored.
Fixed multiple bugs to add stability.
Beta v5
12/12/2013
Fixes issue with skippable ads in playlists.
Beta v4
10/15/2013
Added ability to reset correlator values by calling contentComplete on the AdsLoader.
Beta v3
9/5/2013
Service release, no new features.
Beta v2
7/7/2013
Public release of Beta version of SDK.
Closed Beta v2
6/24/2013
Added API to set UI language on ImaSdkSettings object. Note that this is used to set the UI language, not the ad language.
Fixed conflict that was being encountered when an app included both IMA SDK and AdMob SDK libraries.
Added logging for various internal performance metrics.
Closed Beta v1
4/2/2013
Initial Beta release. The following are known issues with the Beta release:
The following AdEvents available within the HTML5 IMA SDK are not currently supported within the Android v3 IMA SDK: IMPRESSION , LOG , SKIPPABLE_STATE_CHANGED , STOPPED , VOLUME_CHANGED , VOLUME_MUTED
There is an intermittent issue where the ad player does not properly resume after the user has clicked through on an ad. For example, occasionally, when you return to the app after clicking through on an ad, resuming play of that ad causes it to skip to the end and complete, rather than resuming where it left off prior to click through.
The ads returned by the «Instream 2» ad tag are not compatible with the v3 IMA Android SDK.
The sample player does not automatically disable seeking (scrubbing) while ads are playing. Be sure to disable seeking in your video player while ads are being played.
Except as otherwise noted, the content of this page is licensed under the Creative Commons Attribution 4.0 License, and code samples are licensed under the Apache 2.0 License. For details, see the Google Developers Site Policies. Java is a registered trademark of Oracle and/or its affiliates.
