Overview: Brightcove Player SDK for Android

Product(s)
Video Cloud
Brightcove Player
Role(s)
Device SDK Developer
Task(s)
Develop with the Native SDKs
SDK
Overview
Android

Welcome to the Android SDK developer documentation. Here you will find the information needed to develop with the Android SDK.

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.

Supported versions

The Native Player 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:

  • 9.0
  • 8.0, 8.1
  • 7.0, 7.1
  • 6.0
  • 5.0, 5.1
  • 4.4

Passive support

Brightcove provides passive support for the following Android versions:

  • Currently, there is no Android OS in passive support

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 will test and fix bugs on these OS versions.
  • Passive: Brightcove will test on these OS versions, but bug fixes 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.

Connected TV / Set top boxes

The Native Player 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:

  1. Media

    The current version of the Native Player SDK supports playing content from your Video Cloud account through the Playback API, or as remote assets with internet accessible URLs.

  2. Analytics

    With the Native Player SDK, Video Cloud customers automatically get robust analytics data reported in Video Cloud.

  3. Gradle

    Gradle is the foundation of the Android SDK build system, and is integrated with Android Studio.

  4. Maven repo

    The Brightcove Native Player for Android Maven artifacts (jar files) are now available in the Brightcove Maven Repo - http://repo.brightcove.com/releases

  5. 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.

  6. Build an app using the Native SDK for Android

    Create your first app with the Brightcove Player 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.

  7. SDK developer forum

    Join us in the SDK developer forum where SDK related questions are answered by Brightcove engineers and the community. Search for previously answered questions or post a new one. As a public group, you can gain access by providing your email address.

  8. 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.

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 v6.5.0 SDK Reference Release Notes ExoPlayer 2 v2.7.0 Sample Applications

or select this button:

To view the product updates for all of the Native SDKs and the associated plugins, see the Release Notes for the Brightcove Native SDKs document.

Core SDK installation

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

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.

For an example, review the build.gradle file in the android-player-samples project. Note that you can specify the version of the Brightcove Native SDK to use. It is recommended that you always use the latest version.

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:

  1. Simply download the SDK and unzip it. You will find a number of folders.
  2. 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.
  3. 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.

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 v6.5.0 [1] FreeWheel Reference Basic FreeWheel Sample FreeWheel AdManager library v6.23.0
    FreeWheel with Widevine Modular Sample  
IMA plugin v6.5.0 IMA Reference Ad Rules with IMA Sample Google IMA v3-3.9.0
    Ad Rules with IMA and Widevine Sample  
    Basic IMA Sample [2]  
OnceUX plugin v6.5.0 OnceUX Reference Basic OnceUx Sample onceux-android-library 2.1.17
VMAP plugin v6.5.0 [3] VMAP Reference None
Analytics Omniture plugin v6.5.0 [4] Omniture Reference Basic Omniture Sample AdobeVideoLibrary 4.11.0

VideoHeartbeat 2.0.0
Chromecast Cast plugin v6.5.0 Cast Reference Cast Sample ExoPlayer Cast Extension v2.7.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 ads and content protection with Widevine Modular.

Samples

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

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. For the latest Widevine release announcements and product updates, see the Widevine Product News.
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-Degree 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 Player SDK, and guide you through some of the features and functionality available.

Guide Description
Brightcove Player SDK for Android Setup Learn the basics of working with the Brightcove Player 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 Player 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.
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:

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.