Brightcove Plugin Android
From Engineering Client Portal
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