Overview: Brightcove Native SDK for 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.

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:

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

  2. Analytics

    With the Native 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 SDK for Android Maven artifacts (jar files) are available in the Brightcove Maven Repo - https://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 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.

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

  8. Mailing list

    Join the Brightcove Native SDKs mailing list to stay informed of release announcements for the Native SDKs.

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 v8.4.1 SDK Reference Release Notes ExoPlayer 2.19.1 Sample Applications

or select this button:

Notes

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

  • 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 19.
  • 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

    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:

    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 8.4.1 [1] FreeWheel Reference Basic FreeWheel Sample FreeWheel AdManager library 6.28.0
        FreeWheel with Widevine Modular Sample  
    IMA plugin 8.4.1 [2] IMA Reference Ad Rules with IMA Sample Google IMA 3.31.0
        Ad Rules with IMA and Widevine Sample  
        Basic IMA VAST Sample  
    Pulse plugin 8.4.1 Pulse Reference Pulse Sample Pulse SDK 2.5.20.3.0
    SSAI plugin 8.4.1 SSAI Reference Basic SSAI Sample None
    Analytics Omniture plugin 8.4.1 [3] Omniture Reference AdobeVideoLibrary 4.11.0

    VideoHeartbeat 2.0.0
    Chromecast Cast plugin 8.4.1 Cast Reference Brightcove Receiver Sample
    Google Receiver Sample
    ExoPlayer Cast Extension 2.19.1

    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.31.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:

    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.