JW Player Plugin Android: Difference between revisions

Revision as of 20:47, 22 May 2017

Engineering Portal / Digital / JW Player Plugin Android
Supported Ad Frameworks

VMAP
VAST

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

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

Instantiates the PluginManager and creates the JWPlayerView.
Creates Nielsen Plugin Data Provider objects to enable Nielsen monitoring.
Interacts with the PluginManager to create or destroy Nielsen Plugin instances.

JwPlayerView

This is a part of the JW Player Android SDK. The VideoView is used to play content and ads.

Refer to [Player SDK Documentation] for more information.

Nielsen Plugin Data provider

The Nielsen Plugin sends content and ad metadata to the Nielsen SDK for measurement. This component collects content and ad metadata and also provides an interface to populate additional metadata to Nielsen Plugin Instances. Plugin Data below for more details.

PluginManager

The Nielsen PluginManager manages the Nielsen Plugin instances (created by the application through the PluginManager) and handles interaction with them.

Plugin

The Nielsen App SDK Plugin for JW Player handles the JwPlayerView events and data from NielsenPluginDataProvider to make appropriate calls to the Nielsen App SDK. It is a wrapper around the Nielsen App SDK.

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 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 JW Player: The download link for the Plugin Packages are provided with the Nielsen appid(s).
JW 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

JW Player ADK for Android
- Download the JW Player SDK from https://www.jwplayer.com/products/mobile-sdk/

Nielsen App SDK Plugin for JW Player, which includes:
- Plugin Implementation Guide (this document)
- The Nielsen App SDK Plugin for JW Player source code and
- The sample application source code which supports JW Player VMAP ad Plugin.

Nielsen App SDK
- Download the Nielsen App SDK jar file from Downloads

Building the Plugin and Sample App

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

Unzip the Nielsen JW Player Plugin file.
Build the Plugin’s aar file as follows.
Import the module NielsenJWPlayerPlugin into the project.
Create a /libs directory in NielsenJWPlayerPlugin.
Copy the Nielsen App SDK jar files into this /libs directory.
Import JWPlayer.aar file and add it as a dependency to the NielsenJWPlayerPlugin build.gradle file
Build the NielsenJWPlayerPlugin module and this should produce the NielsenJWPlayerPlugin.aar file.
Build the Sample App (NielsenSampleAppForJWPlayer) with the Plugin (NielsenJWPlayerPlugin).

Nielsen SampleApp
- Import the module NielsenSampleAppForJWPlayer into the project.
- Include the following in the build.gradle to compile with the JWPlugin
```
compile project(‘:NielsenJWPlayerPlugin’)
```
- Build the NielsenSampleAppForJWPlayer module and this should produce the NielsenSampleAppForJWPlayer.apk file (Sample App with Plugin).

Nielsen JW Player Plugin

The Nielsen JW Player Plugin monitors the JW Player events and provides the required metadata to the Nielsen App SDK for measurements. The application creates JWPlayer Plugin to monitor JW player with Nielsen measuring SDK.

PluginManager and Plugin instances

Like Nielsen SDK, the Nielsen JW Player can have utmost four plugin instances running simultaneously.

Plugin Manager

The main object that manages Nielsen JWPlayer Plugins is the Nielsen PluginManager. All interaction with Nielsen JW Player Plugins is done through the Nielsen PluginManager instance. Initialize the Nielsen PluginManager instance as mentioned below.

Create an Application class that extends AppSdkApplication. It is mandatory to extend AppSdkApplication and change application android:name field in AndroidManifest file.
In this Application class, call the initialiseInstance() in the onCreate method as follows:
```
PluginManager.initialiseInstance(this);
```
To enable log output from PluginManager and Plugin instances, use
```
PluginManager.initialiseInstance(this, enableLogging);
```
After initialization PluginManager instance is ready to create the Plugin instances.

Plugin Tags

The PluginManager stores Plugin instances and each Plugin instance has its own tag. Tags can be specified in createNewPlugin() method. Else (if the tag is null), the tag is created and returned.

Plugin tags are important because every interaction with Plugin occurs via its tag through the PluginManager.

Plugin Creation

Create the plugin using createNewPlugin() method of PluginManager instance.

Important fields are JwPlayerView, PluginConfig and NielsenPluginDataProvider where PluginConfig object has all properties mandatory for Nielsen SDK. For more details refer to the Android SDK API Reference.

As stated in #Plugin_Tags section, createNewPlugin() method returns the Plugin tag that is either generated by the PluginManager itself (null is passed in pluginTag field) or tag provided to the instance.

PluginEventListener is an optional field that can be used to forward the Nielsen App SDK events to that object.

PluginEventListener must not be anonymous as it will result in collection of garbage data.

Following is an example of the code for creating the Plugin.

private void initialisePlugin(JWPlayerView jwPlayerView) {
this.pluginEventListener = new NielsenPluginEventListener();
JSONObject config = null;
try {
config = new JSONObject()
         .put(“appName”, getResources().getString(R.string.app_name))
         .put(“appId”, “TF2D48D99-9B58-B05C-E040-070AAB3176DB”)
         .put(“appCategory”,”AppSampleCategory”)
         .put(“appClientId”, “AppSampleClientId”)
         .put(“appPD”, “AppSamplePd”)
         .put(“appProd”, “vc,iag”)
         .put(“appSId”, “AppSampleSid”)
         .put(“appTfId”, “AppSampleTfid”)
         .put(“appVerBuilt”, BuildConfig.VERSION_NAME)
         .put(“videoCensusId”, “AppSampleVcId”)
         .put(“nol_devdebug”, “DEBUG”)
         .put(“sfcode”, PluginConfig.SF_CODE_DCRAGF);
nielsenPluginTag = PluginManager.getInstance()
.createNewPlugin(jwPlayerView, config, null, getContext(), this, pluginEventListener);
} catch (JSONException Ex) {
Log.e(TAG, “Exception during creation of JSON Object for config”);
}
// Or this next line if you want to provide your own pluginTag
PluginManager.getInstance()
.createNewPlugin(jwPlayerView, pluginConfig, nielsenPluginTag, context, nielsenPluginDataProvider, pluginEventListener);
}

Plugin lifecycle

Scope
* After creation, every Plugin is stored in the PluginManager. The Plugin Manager is a Singleton instance. This means that Plugin scope is greater than JwPlayerView which the Plugin monitors and is not destroyed when the Activity or Fragment holding JwPlayerView is destroyed. Plugin only has a WeakReference to this JwPlayerView object to prevent memory leaks. This also ensures that JwPlayerView is destroyed along with its Activity or Fragment.
* Destroy the Plugin instance manually, when it is not required.
Destroying Plugin instance
* Use the PluginManager to destroy a Plugin instance.
* Provide the Tag of the Plugin instance to specify which Plugin instance is to be destroyed.
```
PluginManager.getInstance().destroyPlugin(nielsenPluginTag);
```
Re-attaching Plugin to new JwPlayerView
* Upon device rotation and configuration change, if the activity or fragment is recreated, it is possible to attach new JwPlayerView to existing Plugin instance as the scope of Plugin instance is greater.

* Ensure to re-attach the NielsenPluginDataProvider and PluginEventListener.

PluginManager.getInstance().reattachPluginToJwPlayerView(nielsenPluginTag, jwPlayerView, nielsenPluginDataProvider, pluginEventListener);

Nielsen Plugin Data Provider

Nielsen Plugin sends content and ad metadata to the Nielsen SDK for measurement. It collects content and ad metadata and also provides an interface for the client to populate additional metadata.

NielsenPluginDataProvider uses three methods to collect metadata from app.

JSONObject onPlayDataRequest(JSONObject playData, String pluginTag);
JSONObject onContentMetaDataRequest(JSONObject metadataObject, String pluginTag);
JSONObject onAdMetadataRequest(JSONObject metadataObject, String pluginTag);

pluginTag field is passed by plugin so that it is easy to identify which Plugin instance requires data in case of any boolean Plugin instances.

For more details refer to the Android SDK API Reference

Opt-In / Opt-Out use cases

When the user wants to opt in or opt out of Nielsen measurement, a new dynamic page should be displayed. Nielsen JW Player plugin provides an interface to obtain the OptOut URL. In addition, it also provides two other Opt Out implementations.

optIn
optOut

The optIn / optOut value selected by the user is passed to the Plugin.

Note: The PluginManager must have at least one Plugin instance for the OptOut use case to work.

Opt Out Interface

Use PluginManager to obtain Nielsen user Opt Out URL

PluginManager.getInstance().getOptOutUrl();

User selected Opt Out result must be passed to PluginManager instance.

PluginManager.getInstance().sendOptInOutEvent(optOutresult);

For more information refer to the Android SDK API Reference.

Opt Out Activity

The OptOut Activity is provided along with the Plugin. Render the Nielsen OptOut web page, using the following steps.

Implementation:

Add Nielsen OptOutActivity to AndroidManifest.xml

<activity android:name=”jwplugin.appsdk.nielsen.com.jwplugin.OptOutActivity” />

Show OptOutActivity

PluginManager.getInstance().showOptOutActivity(activity);

Opt Out Fragment

An OptOutFragment is also provided with the Plugin. Render the Nielsen OptOut web page, using the following steps.