Overview: Brightcove Native SDK for Android

Documentation structure

At Brightcove, we strive to keep the documentation structured, clean and intuitive. As such, we leverage github READMEs for details on all our plugins and integrations. For your convenience, we've listed and linked to these plugins below.

Android support

The Native SDK for Android offers support for the following versions of Android:

Active support

Brightcove provides active support for the latest Android SDK on the following Android versions:

14.0
13.0
12.0
11.0
10.0
9.0
8.0, 8.1

Passive support

Brightcove provides passive support for the following Android versions:

7.0, 7.1
6.0
5.0, 5.1

Understanding support levels

Support is defined in terms of the [major version].[minor version] of an OS (for example: Android 8.1). In order to take advantage of the latest technology improvements from Google, we offer two levels of support:

Active: Brightcove actively tests these versions, prioritizing newer OS levels, and addresses issues found with these OS versions.
Passive: Brightcove no longer tests on these OS versions. Issues found will be handled on a case by case basis.

Generally, Brightcove provides active support for the versions of the OS that are used by 80% of the user base, and passive support for other versions used by at least 5% of the user base.

Android variant support

The Brightcove Native SDK for Android is developed for and tested with mainline Android OS releases. Brightcove does not officially support after-market distributions of Android, such as LineageOS.

Users of devices running variant Android releases may experience issues with applications developed using the Native SDK for Android.

Connected TV / Set top boxes

The Native SDK for Android offers support for the following Android-based set top boxes:

Android TV
Fire TV (FireOS 5.0+ devices)

The set top box devices we tested with include:

Nexus Player
Nvidia Shield

The Brightcove Native SDK for Android sample apps will work on Android TV and Fire TV. This means your TV-based apps can include advertising, content protection (DRM), live playback, custom UI controls, Brightcove Analytics and QoE metrics.

Check out the Styled Controls sample app for details on styling the UI controls in your TV app.

Getting started

Before beginning development with the Android SDK there are a few concepts you should learn about:

Media
The current version of the Native SDK supports playing content from your Video Cloud account through the Playback API, or as remote assets with internet accessible URLs.
Analytics
With the Native SDK, Video Cloud customers automatically get robust analytics data reported in Video Cloud.
Gradle
Gradle is the foundation of the Android SDK build system, and is integrated with Android Studio.
Maven repo
The Brightcove Native SDK for Android Maven artifacts (jar files) are available in the Brightcove Maven Repo - https://repo.brightcove.com/releases

For details about adding the Maven repo to your Android project, see the Build an app using the Native SDK for Android document.
Android SDK overview
To aid in your understanding of the SDK, learn how critical components interact to handle the complexities of controlling the native video player.
Build an app using the Native SDK for Android
Create your first app with the Brightcove Native SDK for Android, which plays a video from your own backend system. Video Cloud customers will additionally retrieve and play a video from the Brightcove Catalog service.

Please note that with the Native SDK for Android version 7.0.1, MediaPlayer is no longer supported for content playback.
Video-on-Demand training
View a series of training videos that walk you through the steps of building an app in Android Studio that plays a video and a playlist from your Video Cloud library.
Mailing list
Join the Brightcove Native SDKs mailing list to stay informed of release announcements for the Native SDKs.

The posts in the channel are for historical purposes. Signing up will add you to the email list for SDK releases.

Download the SDK

Get the latest version of the Brightcove Native SDK for Android:

	Package (Github Repo)	Reference Documentation	Notes	Supported Framework	Samples
SDK	Native SDK for Android v10.0.0	SDK Reference	Release Notes	Media3 1.4.1	Sample Applications

or select this button:

Previous releases

Notes

The following notes refer to the latest version of the Native SDK:

Starting with version 10.0.0, Brightcove's Native SDK for Android uses Media3.

Starting with version 6.10.0, Brightcove's Native SDK for Android uses the Jetpack (androidx.*) libraries instead of the original support libraries. This change is required for Exoplayer version 2.10.0 and above. To use Jetpack, your apps must meet the following requirements:

Migrate to Jetpack (AndroidX) dependencies
Android Gradle Tools 3.2.0
Gradle version 4.6

For more information on how to migrate to JetPack refer to the official Android migration guide.

The Android Minimum SDK Version supported by the Brightcove Native SDK for Android is now 21.

For ExoPlayer v2.19.1, you need to enable Java 11 support. To do this, add the following to the android section of your app's build.gradle file. For details, see Android's ExoPlayer document.

android {
    compileOptions {
      targetCompatibility JavaVersion.VERSION_11
    }
  }

This overrides the default Java version based on the project's compileSdkVersion value.

Core SDK installation

Installation of the Brightcove core SDK is very straightforward. There are two ways to do this:

Using the gradle build system
Manually downloading the SDK

Using the gradle build system

The easiest way to add the Brightcove SDK and its dependencies is to use the gradle build system in Android Studio.

Using a dynamic dependency version with the '+' character is discouraged in the Gradle community. Using dynamic versioning brings a significant risk to your build process, as newer APIs may become unexpectedly incompatible with your app's source code.

For more information about using gradle, see Android's Add Build Dependencies documentation.

Manually downloading the SDK

You can also manually download the Brightcove SDK as follows:

Simply download the SDK and unzip it. You will find a number of folders.
Inside the sdk folder, you will find the core SDK with the name android-sdk-x.x.x.aar, where x.x.x is the latest SDK version number.
Add the android-sdk-x.x.x.aar file to your library, along with any plugin files that you may need.

Integrations

The following table contains links to get plugins integrated with your SDK implementation. The plugins can be downloaded from their respective Github Repos, and each repo contains a detailed README with instructions on how to setup the plugin.

It is recommended that you use the BrightcoveExoPlayerVideoView class whenever possible. Widevine Modular is supported when using this class.

The sample applications demonstrate the basic functionality of each plugin integrated with the SDK. These sample apps are a good way to learn about each plugin, and serve as a reference point when debugging.

Previous integration versions

Category	Brightcove Plugin	Reference Documentation	Sample Apps	Supported Partner/Vendor Plugin
Advertising	FreeWheel plugin 10.0.0 ^[1]	FreeWheel Reference	Basic FreeWheel Sample	FreeWheel AdManager library 6.28.0
			FreeWheel with Widevine Modular Sample
	IMA plugin 10.0.0 ^[2]	IMA Reference	Ad Rules with IMA Sample	Google IMA 3.36.0
			Ad Rules with IMA and Widevine Sample
			Basic IMA VAST Sample
	Pulse plugin 10.0.0	Pulse Reference	Pulse Sample	Pulse SDK 2.5.20.3.0
	SSAI plugin 10.0.0	SSAI Reference	Basic SSAI Sample	None
Analytics	Omniture plugin 10.0.0 ^[3]	Omniture Reference		AdobeVideoLibrary 4.11.0 VideoHeartbeat 2.0.0
Chromecast	Cast plugin 10.0.0	Cast Reference	Brightcove Receiver Sample Google Receiver Sample	Media3 1.4.1

The following notes refer to the integrations in the table above.

You cannot pick and choose individual Brightcove plugin versions with partner plugin versions. You must use the partner plugin versions that are specified, as this is what has been tested.
To avoid problems with conflicting java libraries, make sure that you remove old versions from the path before adding the new libraries to your path. For the sample apps, include plugin libraries into the libs/ top-level directory.

^[1] The Native SDK for Android v4.11.0 supports the functionality for the skipCurrentAd and skipCurrentAdBreak methods, but it does require the FreeWheel AdManager library v6.10.0. If you do not upgrade the FreeWheel library when using these methods, your application may crash.

The Native SDK for Android v5.2.0 has been updated to support FreeWheel AdManager v6.17.0. The SDK will not work with previous versions of the FreeWheel AdManager.

^[2] The Brightcove Native SDKs support VMAP XML templates that contain the VAST protocol, including VAST 3.0, and limited support for VAST 4.0. For more details about VAST version compatibility, see Google's Support and Compatibility document for the IMA SDK for Android. The Native SDKs also support the IAB Open Measurement SDK.

^[3] You must independently obtain and install the adobeMobileLibrary.jar file into the top-level directory. The adobeMobileLibrary.jar file version 4.11.0 is provided along with the VideoHeartbeat.jar file version 2.0.

Combining plugins

With the Native SDK for Android, most plugins can be combined. This sample app shows you how to use the Brightcove ExoPlayer with Google IMA 3.36.0 ads and content protection with Widevine Modular.

Samples

Brightcove recommends using the BrightcoveExoPlayerVideoView implementation when possible. For samples and code snippets, see the following:

All samples for the Brightcove Native SDK for Android
- brightcove-exoplayer folder – Samples use the ExoPlayer implementation.
- brightcove-player-controls folder – Concepts can be used with the ExoPlayer implementation.
Code snippets to help with specific tasks

The following table contains links to code samples that are in addition to the samples associated with the integrations in the previous section.

Sample Application	Description
Basic Sample	Create a basic app that plays videos from your Video Cloud library.
Chromecast	Cast your videos to a Chromecast-connected TV. For an overview, see the The Cast plugin for the Native SDK for Android document.
Custom Controls	Customize the player controls.
DRM with Widevine	Protect your content with Widevine. The Android framework supports Widevine Modular when using the ExoPlayer Video View. For details, see the Widevine reference.
Live Stream	Create an app that runs an HLS live stream.
Offline playback	Download and play DASH videos, including those protected with Widevine encryption. For an overview, see the Offline Playback with the Native SDKs document.
Remote Video	Load a video from a remote server.
Video list	Use a `RecyclerView` to handle a set of videos.
360° Video	Plays a 360° video, as long as the projection property is set. When the Video 360 button in the control bar is tapped, the video is displayed in VR Goggles mode with side-by-side images. For details, see the Using 360° Videos with the Mobile SDKs document.

Solution guides

The following table contains links to developer docs which will help you get started with your own app using the Brightcove Native SDK, and guide you through some of the features and functionality available.

Guide	Description
Brightcove Native SDK for Android Setup	Learn the basics of working with the Brightcove Native SDK for Android by walking you through the development of a simple video playback app using content from your own backend system. Video Cloud customers will additionally retrieve and play a video from the Brightcove Catalog service.
Creating Plugins	Learn how to create a plugin for the Brightcove Native SDK for Android.
Managing View Layout	Learn how to manage the layout of a View added to the `BrightcoveVideoView` .
Handling Orientation Changes	Learn how to manage unwanted default behavior when the orientation changes.
IAB Open Measurement	Learn how to use the Open Measurement SDK with the IMA plugin for support of third-party tools for ad measurement and verifcation.
Source Selection	Learn about the default rendition selection process when playing a video.
Using Brightcove Analytics	Learn how to set properties in Brightcove Analytics from your mobile app using the Brightcove SDK for Android.
Working with Player Controls	Learn how to customize and hide player controls.

Best practices

Here is additional information that you may find helpful when working with the Brightcove Native SDK.

Advertising with IMA

The placement of VAST ads is typically specified by a VMAP document. VAST describes an ad while VMAP describes the placement of ads in a video. For code details, see the following:

When working with IMA ads, it is best practice to check that your ads work outside of the SDK before implementing them. The following links will be helpful for this:

Companion ads

Companion ads and click-through ads are not supported on Android TV. Because there is no web browser support on Android TV, there is no destination for a click-through URL.

Working with ProGuard

Using ProGuard allows you to create more secure apps, making them harder to reverse engineer. ProGuard is integrated into the Android build system, so you can choose to enable it or build without it.

If you receive an error when ProGuard is enabled in Gradle, try adding the following exclusion rules:

  -dontwarn com.google.**
  -dontwarn android.media.**
  -keep class android.media.** { *; }
  -keep class com.google.** { *; }
  -keep interface com.google.** { *; }
  -keep class com.google.ads.interactivemedia.** { *; }
  -keep interface com.google.ads.interactivemedia.** { *; }

For a complete list of ProGuard rules used by the Brightcove Native SDK, download and unzip the current Native SDK for Android. Open the sdk folder and view the proguard.txt file.

Playback behavior

You may notice some of the following playback behaviors on certain Android devices:

Video pause

Android's Smart Pause feature on Samsung devices will pause a video when the user looks away from the device screen. You can disable this feature if you do not want videos to pause on Smart Pause-enabled devices.