Brightcove Plugin Android

Engineering Portal / Digital / DCR & DTVR / Brightcove Plugin Android

Nielsen App SDK Plugin for Brightcove interacts with Nielsen App SDK to provide with necessary data for streaming measurement based on the SDK events received from the Brightcove Player SDK.

	OS	Player Version	SDK Version	Supported Ad Frameworks	Download
		5.3.1.732	5.1.1.17	FreeWheel, OnceUX, Google IMA and VMAP	Download

Component Diagram

The component diagram above shows the interaction of the Plugin with various components.

App

The App is the Android application implemented by the client. The application

• Creates the Plugin and extends the Brightcove Player.
• Instantiates BrightcoveExoPlayerVideoView. A reference of the VideoView is passed to the Plugin during creation.
• Interacts with the Plugin to provide metadata for the content and / or Ad to the Nielsen App SDK for measurement.

BRCPlayerVideoView

This is the Brightcove’s ExoPlayer video view and is a part of the Brightcove Player SDK. The VideoView is

• Instantiated by the Android application from the layout XML set with setContentView().
• Designed to replace Android’s native VideoView.
• Used to provide public methods to mirror those of the native VideoView
• A Java collection-like API for managing the internal playlist.

The VideoView uses Event workflow and emits different events during the video playback.

Nielsen App SDK

This is the Nielsen App SDK which handles the content and ad measurement based on the information received from the Plugin.

Plugin

The Nielsen App SDK Plugin for Brightcove is registered with the Brightcove SDK when it is instantiated by the application.

• It integrates with the Brightcove Player SDK which in turn listens to the player events and emits the events.
• It listens to events that can initiate an action like PLAY, PAUSE, STOP etc. or events that signal the completion of an action like DID_PLAY, PROGRESS, COMPLETED etc. and calls the appropriate Nielsen App SDK APIs.
• The Nielsen App SDK Plugin is also a wrapper for the Nielsen App SDK.

BRC EventEmitter

This is a part of the Brightcove Player SDK. Events in the Brightcove Player SDK for Android represent a state or action that can be passed down through a chain of listeners. All events have a type and a map of properties associated with them.

• The EventEmitter is the public facing API for classes to emit and listen to events. It can be obtained from BrightcoveVideoView

Plugin Implementation

Pre-requisites

• Nielsen SDK Configuration Form: Complete this form to receive the appid(s). The information on this form is required to set up the Content Management System (CMS) mapping for the app.
• Nielsen App ID (appid): A unique ID that Nielsen assigns to the site / player.
• Nielsen App SDK Plugin for Brightcove: The download link for the Plugin Packages are provided with the Nielsen appid(s).
• Brightcove Player SDK for Android
• VideoView: Before moving the app into production, Nielsen must validate the Plugin’s integration in a test environment.

Initial Configuration

Before integrating the Plugin, make sure to download the following:

• Brightcove Player SDK for Android
  • Update the build.gradle file to use the latest version of the Brightcove SDK from their Maven repository.
  • If the Brightcove SDK aar files are downloaded already, copy them to the libs/ directory and make appropriate changes in the build.gradle file to include them in the build.

Note: In order to enable the FreeWheel ad Plugin, obtain separately and install the non-free file AdManager.jar into the libs/ specified in the build.gradle file. Contact FreeWheel directly for more information on how to obtain their products.

• Nielsen App SDK Plugin for Brightcove Package, which includes:
  • The Nielsen App SDK Plugin for Brightcove source code and
  • The sample application source code which supports Brightcove’s FreeWheel, OnceUX, Google IMA and VMAP ad Plugins.

• Nielsen App SDK
  • Download the Nielsen App SDK jar file from https://engineeringforum.nielsen.com/sdk/developers/downloads.php.

Follow the steps below, to include the Nielsen Plugin and sample app into the player application project

• • Unzip the NielsenAppSDKPluginBrc.zip file.
  • Build the Plugin’s aar file as follows.
  • Import the module NielsenBrcPlugin into the project.
  • Add “anpVersion” parameter to the gradle.properties file and assign the appropriate Brightcove SDK build version number (e.g.: anpversion=4.6.6). Refer to Plugin’s build.gradle for more information.
  • Create a /libs directory in NielsenBrcPlugin.
  • Copy the Nielsen AppSDK jar file into this /libs directory.
  • Build the NielsenBrcPlugin module and this should produce the NielsenBrcPlugin.aar file.
• Build the SampleApp with the Plugin

• FreeWheel SampleApp
  • Import the module NielsenSampleAppForBrcFreeWheel into the project.
  • Add AdManager.jar file path in the dependencies in the build.gradle.

project.ext
{
    libraryDirectory = "${System.getProperty("user.home")}/libs/"
}
dependencies
{
   compile files(libraryDirectory + "AdManager.jar")
}

OR

• If AdManager is copied to /libs then set libraryDirectory="libs/".

project.ext
{
    libraryDirectory = "libs/"
}
dependencies
{
   compile files(libraryDirectory + "AdManager.jar")
}

• Replace ':brcplugin' with ':NielsenBrcPlugin' in sample app build.gradle

compile project(':NielsenBrcPlugin')

• Refer to Sample App's build.gradle
• Build the NielsenSampleAppForBrcVMAP to produce the NielsenSampleAppForBrcVMAP’s apk file (Sample App with Plugin).

Note: If you get the com.google.android.gms:play-service-ads: 10,2,0 error, download and install the latest Google-Play-Services in Android Studio from SDK Manager.

Initialization with Global Parameters

To create the Plugin that initializes the AppSDK, pass the global parameters in a JSON string format. Some of the global parameters are

• Nielsen App ID (appid)
• app version
• app name
• sfcode
• dma
• ccode
• CMS Metadata

For more details refer to the Nielsen Android SDK API Reference.

Setup

The steps for setting up the Nielsen App SDK Plugin for Brightcove Player are as follows

Nielsen App SDK Plugin Creation

The Nielsen App SDK Plugin for Brightcove integrates with the Brightcove SDK by listening for events from the player, other plugins and emits events for the player. It is also a wrapper for the Nielsen App SDK. It is registered with the Brightcove SDK when it is instantiated by the application.

The App creates the Plugin as mentioned below.

plugin = new Plugin(eventEmitter, context, videoView, config);

where

• eventEmitter is the Brightcove event emitter obtained from the BrightcoveVideoView,
• context is the application context,
• videoView is the BrightcoveVideoView, and
• config contains the parameters to initialize the App SDK in the JSON format.

For more details refer to the Nielsen Android SDK API Reference.

Passing Metadata

The Plugin contains two interface methods – getMetaData and getPlayData that the client needs to implement to provide the necessary metadata for content and ad and also the metadata required for play.

This data is returned in a map container.

Map<String, String> getMetaData(Event event);
Map<String, String> getPlayData(Event event);

The data returned by the getMetaData() for content contains

• Assetid : unique id assigned to asset
• Program : program name
• Title : episode title – only applicable to video content
• Length – length of content in seconds
• segA – segment A will be episode title for video content
• segB – Segment B
• segC – Segment C

The data returned by the getPlayData() contains the “channelName”. For more details refer to the Nielsen Android SDK API Reference.

Calling the methods

The application can communicate with the Plugin for functions such as appDisable, app configuration settings change, OptIn / OptOut, static content and network availability via the events customized for Brightcove. The method emit() emits an event passing along the properties map. The key and value pair for each of the event is given in the table

Function	Event	Properties(String, Object)
AppDisable	APP_DISABLE	("APP_DISABLE", TRUE/FALSE)
Config Settings Change	SETTINGS_REQUEST	("SETTINGS_REQUEST", { "appName": appName, "clientid": appClientId , "vcid": videoCensusId, "appVersion": appVerBuilt , "prod": appProd , "nol_nlsApiDbg": nol_nlsApiDbg , "sfcode": sfCode , "appid": appid , "category": appCategory , "pd": appPD , "tfid" : appTfId , "sid": appSId })
OptIn / OptOut	OPT_IN	("OPT_IN", "nielsenappsdk://0") OR ("OPT_IN", "nielsenappsdk://1")
Static Content	STATIC_CONTENT	(“STATIC_CONTENT”, { "type": "static", "section": "siteSection", "segA": "SegmentA", "segB": "SegmentB", "segC": "SegmentC", "crossId1": "Reference11" })
Network Availability change	NETWORK_AVAILABLE_CHANGE	("NETWORK_AVAILABLE_CHANGE", TRUE/FALSE)

Below is a sample snippet of the code to emit the "APP_DISBALE" event from the application to Plugin.

Map<String, Object> properties = new HashMap<String, Object>();
properties.put("APP_DISABLE", appDisabled == true?"TRUE":"FALSE");
eventEmitter.emit("APP_DISABLE", properties);

Build files

Plugin's build.gradle

This is an example of the Plugin's build.gradle file. Modify the file as specified in above section

apply plugin: 'com.android.library'
repositories
{
  mavenCentral()
  maven
  {
     url "http://repo.brightcove.com/releases"
  }
  mavenLocal()
}
android
{
  compileSdkVersion 23
  buildToolsVersion “23.0.1”
  defaultConfig
    {
      minSdkVersion 16
      targetSdkVersion 23
      versionCode 2
      versionName “1.0”
    }
  buildTypes
  {
    debug
    {
      debuggable true
    }
    release
    {
      minifyEnabled false
      proguardFiles getDefaultProguardFile('proguard-android.txt'), 'proguard-rules.pro'
    }
  }
  productFlavors
  {
  }
}
dependencies
{
  compile fileTree(dir: 'libs', include: ['*.jar'])
  compile 'com.android.support:appcompat-v7:23.0.0'
  compile 'com.google.android.gms:play-services-maps:7.8.0'
  compile 'com.google.exoplayer:library:1.5.3.1'
  compile 'com.brightcove.player:android-sdk:4.7.2'
  compile 'com.brightcove.player:exoplayer:4.7.2'
}

Application's build.gradle

This is an example of the Application’s build.gradle file. Please make the necessary changes as specified in above section

FreeWheel SampleApp

apply plugin: 'com.android.application'
repositories
{
  mavenCentral()
  maven
  {
    url "http://repo.brightcove.com/releases"
  }
  mavenLocal()
}
println "Using Android Native Player version: $anpVersion"
project.ext
{
  // The directory that will be used to reference dependent libraries.
  // Modify as needed. Defaulted to users home directory.
  libraryDirectory = "${System.getProperty("user.home")}/libs/"
}
dependencies
{
  compile "com.brightcove.player:android-freewheel-plugin:${anpVersion}"
  compile files(libraryDirectory + "FWAdManager.jar")
}
android
{
  compileSdkVersion 23
  BuildToolsVersion "23.0.1"
  defaultConfig
  {
      applicationId "com.nielsen.appsdk.brcsampleappforfreewheel"
      minSdkVersion 16
      targetSdkVersion 23
      versionCode 1
      versionName "1.0"
  }
  buildTypes
  {
      debug
      {
         debuggable true
      }
      release
      {
          minifyEnabled false
          proguardFiles getDefaultProguardFile('proguard-android.txt'), 'proguard-rules.pro'
      }
  }
}
dependencies
{
  compile 'com.android.support:appcompat-v7:23.0.0'
  compile 'com.brightcove.player:android-sdk:4.6.6'
  compile 'com.brightcove.player:exoplayer:4.6.6'
  compile 'com.brightcove.player:android-hls-player:4.6.6'
  compile 'com.brightcove.player:android-freewheel-plugin:4.6.6'
  compile project(':NielsenBrcPlugin')
}

OnceUX SampleApp

apply plugin: 'com.android.application'
repositories
{
  mavenCentral()
  maven
  {
    url "http://repo.brightcove.com/releases"
  }
  mavenLocal()
}
println "Using Android Native Player version: $anpVersion"
project.ext
{
  libraryDirectory = "${System.getProperty("user.home")}/libs/"
}
dependencies
{
  compile "com.brightcove.player:android-onceux-plugin:${anpVersion}"
}
android
{
  compileSdkVersion 23
  BuildToolsVersion "23.0.1"
  defaultConfig
  {
      applicationId "com.nielsen.appsdk.brcsampleappforonceux"
      minSdkVersion 16
      targetSdkVersion 23
      versionCode 1
      versionName "1.0"
  }
  buildTypes
  {
      release
      {
          minifyEnabled false
          proguardFiles getDefaultProguardFile('proguard-android.txt'), 'proguard-rules.pro'
      }
  }
}
dependencies
{
  compile 'com.android.support:appcompat-v7:23.0.0'
  compile 'com.brightcove.player:android-sdk:4.7.2'
  compile 'com.brightcove.player:exoplayer:4.7.2'
  compile 'com.brightcove.player:onceux-android-library:2.1.+'
  compile project(':NielsenBrcPlugin')
}

Google IMA SampleApp

apply plugin: 'com.android.application'
repositories
{
  mavenCentral()
  maven
  {
    url "http://repo.brightcove.com/releases"
  }
  mavenLocal()
}
println "Using Android Native Player version: $anpVersion"
project.ext
{
  libraryDirectory = "${System.getProperty("user.home")}/libs/"
  imaAndroidSdkJarFileName = "ima-android-sdk-beta9.jar"
}
def downloadIMA()
{
  def libsdk = libraryDirectory + imaAndroidSdkJarFileName
  File dep = file(libsdk)
  if (!dep.exists())
    {
      apply plugin: 'download-task'
      println "Downloading the Google IMA SDK…"
    }
  download
    {
      src 'https://dl.google.com/in-stream/google_sdk/android/v3/' + imaAndroidSdkJarFileName
      dest file(libraryDirectory + imaAndroidSdkJarFileName)
    }
}
}
downloadIMA()
dependencies
{
  compile "com.brightcove.player:android-ima-plugin:${anpVersion}"
  compile files(libraryDirectory + imaAndroidSdkJarFileName)
}
android
{
  compileSdkVersion 23
  BuildToolsVersion "23.0.1"
  defaultConfig
  {
      applicationId "com.nielsen.appsdk.brcsampleappforgoogleima"
      minSdkVersion 16
      targetSdkVersion 23
      versionCode 1
      versionName "1.0"
  }
  buildTypes
  {
      release
      {
          minifyEnabled false
          proguardFiles getDefaultProguardFile('proguard-android.txt'), 'proguard-rules.pro'
      }
  }
}
dependencies
{
  compile 'com.google.exoplayer:library:1.5.3.1'
  compile 'com.android.support:appcompat-v7:23.0.0'
  compile 'com.brightcove.player:exoplayer:4.7.2'
  compile 'com.brightcove.player:android-ima-plugin:${anpVersion}'
  compile 'com.google.android.gms:play-services-ads:7.+'
  compile project(':NielsenBrcPlugin')
}

VMAP SampleApp

apply plugin: 'com.android.application'
repositories
{
  mavenCentral()
  maven
  {
    url "http://repo.brightcove.com/releases"
  }
  mavenLocal()
}
println "Using Android Native Player version: $anpVersion"
project.ext
{
// The directory that will be used to reference dependent libraries.  

// Modify as needed. Defaulted to users home directory.  

  libraryDirectory = "${System.getProperty("user.home")}/libs/"
}
android
{
  compileSdkVersion 23
  BuildToolsVersion "23.0.1"
  defaultConfig
  {
      applicationId "com.nielsen.appsdk.brcsampleappforvmap"
      minSdkVersion 16
      targetSdkVersion 23
      versionCode 3
      versionName "1.3.0"
  }
  buildTypes
  {
      release
      {
          minifyEnabled false
          proguardFiles getDefaultProguardFile('proguard-android.txt'), 'proguard-rules.pro'
      }
  }
}
dependencies
{
  compile "com.brightcove.player:android-vmap-plugin:${anpVersion}"
  compile 'com.google.android.gms:play-services-ads:10.2.0'
  compile 'com.android.support:appcompat-v7:23.0.0'
  compile 'com.brightcove.player:android-sdk:4.13.1'
  compile 'com.brightcove.player:exoplayer:4.13.1'
  compile project(':NielsenBrcPlugin')
}

Known Issues

For FreeWheel ad support if the application is brought to the background while an ad is playing and then moved to the foreground, the ad resumes playing but no events are sent to indicate resuming of the ad. This causes a loss in the ad crediting and has been reported to Brightcove (ticket number for reference is 411614).

Releases

Name	Version #	Date	Comments
Nielsen AppSDK Plugin for Brightcove (FreeWheel)	1.0.0	01/11/2016	Initial version of the Nielsen App SDK Plugin for Brightcove (Android) with support for FreeWheel ads. Plugin with FreeWheel ad support was tested with AppSdk build 4.0.0.8.
Nielsen AppSDK Plugin for Brightcove (OnceUX & Google IMA)	1.0.1	03/15/2016	Nielsen App SDK Plugin for Brightcove (Android) with support for OnceUX and Google IMA ads. Plugin with Google IMA ad support was tested with AppSDK build 5.0.0.4 & Plugin with OnceUX ad support was tested with AppSDK build 4.0.0.8
Nielsen AppSDK Plugin for Brightcove(FreeWheel) with changes for DCR & International (Germany) combined AppSdk build	1.2.0	04/29/2016	Version of the Nielsen App SDK Plugin for Brightcove (Android) with support for FreeWheel ads and compatible with DCR & International (Germany) combined AppSdk build. Plugin with FreeWheel ad support was tested with AppSdk build 5.1.0.4
Nielsen AppSDK Plugin for Brightcove(VMAP, FreeWheel & Google IMA)	1.3.1	03/24/2017	Version of the Nielsen App SDK Plugin for Brightcove (Android) with support for VMAP, FreeWheel & Google IMA ads. Plugin was tested with Brightcove player SDK version 4.13.0 and Nielsen AppSdk build 5.1.1.18