View source for Brightcove Plugin Android

{{Breadcrumb|}} {{Breadcrumb|Digital}} {{Breadcrumb|DCR & DTVR}}  {{CurrentBreadcrumb}}
[[Category:Digital]]

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

{{PluginInfobox
|pluginImage=BrightcoveIcon
|osImage=AndroidIcon
|playerVersion=5.3.1.732
|SDKVersion=5.1.1.17
|supportedAdFrameworks=FreeWheel, OnceUX, Google IMA and VMAP
|downloadLink=https://engineeringportal.nielsen.com/w/downloads/digital/plugins/brightcove/android/Nielsen-App-SDK-Brightcove-Plugin-Android-1.3.1.zip
}}

== Component Diagram ==
[[File:Bright-component-diagram.jpg|link=]]

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.
<blockquote>'''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.</blockquote>

*'''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 [[BrightCove_Android_Player_Plugin_Implementation_Guide#Build_files|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.
<syntaxhighlight lang="javascript">project.ext
{
    libraryDirectory = "${System.getProperty("user.home")}/libs/"
}
dependencies
{
   compile files(libraryDirectory + "AdManager.jar")
}</syntaxhighlight>
OR
* If AdManager is copied to /libs then set libraryDirectory="libs/".
<syntaxhighlight lang="javascript">project.ext
{
    libraryDirectory = "libs/"
}
dependencies
{
   compile files(libraryDirectory + "AdManager.jar")
}</syntaxhighlight>
* Replace <code>':brcplugin'</code> with <code>':NielsenBrcPlugin'</code> in sample app ''build.gradle''
<syntaxhighlight lang="javascript">compile project(':NielsenBrcPlugin')</syntaxhighlight>
* Refer to [[BrightCove_Android_Player_Plugin_Implementation_Guide#OnceUX_SampleApp|Sample App's ''build.gradle'']]
* Build the NielsenSampleAppForBrcVMAP to produce the NielsenSampleAppForBrcVMAP’s apk file (Sample App with Plugin).
<blockquote>'''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.
<syntaxhighlight lang="java">plugin = new Plugin(eventEmitter, context, videoView, config);</syntaxhighlight>
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.
<syntaxhighlight lang="java">Map<String, String> getMetaData(Event event);
Map<String, String> getPlayData(Event event);</syntaxhighlight>

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
{| class="wikitable"
|-
! Function !! Event !! Properties(String, Object)
|-
| AppDisable || <code>APP_DISABLE</code> || <code>("APP_DISABLE", TRUE/FALSE)</code>
|-
| Config Settings Change || <code>SETTINGS_REQUEST</code> || <syntaxhighlight lang="java">("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
})</syntaxhighlight>
|-
| OptIn / OptOut || <code>OPT_IN</code> || <code>	
("OPT_IN", "nielsenappsdk://0") OR

("OPT_IN", "nielsenappsdk://1")</code>
|-
| Static Content || <code>STATIC_CONTENT</code> || <syntaxhighlight lang="java">(“STATIC_CONTENT”,
{
  "type": "static",
  "section": "siteSection",
  "segA": "SegmentA",
  "segB": "SegmentB",
  "segC": "SegmentC",
  "crossId1": "Reference11"
  })</syntaxhighlight>
|-
| Network Availability change || <code>NETWORK_AVAILABLE_CHANGE</code> || <code>("NETWORK_AVAILABLE_CHANGE", TRUE/FALSE)</code>
|}

Below is a sample snippet of the code to emit the "APP_DISBALE" event from the application to Plugin.
<syntaxhighlight lang="java">Map<String, Object> properties = new HashMap<String, Object>();
properties.put("APP_DISABLE", appDisabled == true?"TRUE":"FALSE");
eventEmitter.emit("APP_DISABLE", properties);</syntaxhighlight>

=== 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
<syntaxhighlight lang="java">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'
}</syntaxhighlight>

==== 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 ====
<syntaxhighlight lang="java">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')
}</syntaxhighlight>

==== OnceUX SampleApp ====
<syntaxhighlight lang="java">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')
}</syntaxhighlight>

==== Google IMA SampleApp ====
<syntaxhighlight lang="java">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')
}</syntaxhighlight>

==== VMAP SampleApp ====
<syntaxhighlight lang="java">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')
}</syntaxhighlight>

==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 ==
{| class="wikitable"
|-
! 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
|}