ExoPlayer Plugin Android

From Engineering Client Portal

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

Nielsen App SDK Plugin for ExoPlayer interacts with Nielsen App SDK to provide with necessary data for streaming measurement based on Android ExoPlayer events received.

OS Player Version SDK Version Supported Ad Frameworks Download
{{{alt}}}
iOS
 1.5.8 5.1.1.4 Google IMA Download

Component Diagram

Exo-component.png

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

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

ExoPlayer

ExoPlayer is an application level media player for Android. It provides an alternative to Android's MediaPlayer API for playing audio and video both locally and over the Internet. For more details refer to the project site.

Nielsen Plugin Data provider

Plugin Data Provider component provides additional data to a Nielsen Plugin instances.

Nielsen Content Data provider

Content Data Provider component provides additional data to a Nielsen Plugin instances regarding content.

Nielsen Ads Data provider

Ads Data Provider component provides additional data to a Nielsen Plugin instances regarding advertisement.

Advertisement Adapter is created by Plugin Manager. It enables advertisement monitoring.

PluginManager

The Nielsen PluginManager manages the Nielsen Plugin instances which the application creates through the PluginManager. It handles interaction with the Plugin instances.

Plugin

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

Nielsen AppSdk

This is the Nielsen AppSDK which handles the content and ad measurement based on the information provided by 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 ExoPlayer: The download link for the Plugin Packages are provided with the Nielsen appid(s).
  • ExoPlayer SDK for Android
  • Test Environment Validation: 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:

  • Nielsen App SDK Plugin for ExoPlayer
  • The Nielsen App SDK Plugin for ExoPlayer package includes
    • Plugin Implementation Guide (this document)
    • The Nielsen App SDK Plugin for ExoPlayer source code and
    • The sample application source code.
  • Nielsen App SDK

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

  • Unzip the Nielsen-ExoPlayer-Plugin-Android-1.0.1.zip file
  • Build the Plugin's aar file as follows.
    • Import the module NielsenExoPlayerPlugin into the project.
    • Create a /libs directory in NielsenExoPlayerPlugin. Copy the Nielsen AppSDK jar file into /libs directory
    • Add ExoPlayer as a dependency to the NielsenExoPlayerPlugin build.gradle file
    • Build the NielsenExoPlayerPlugin module and this should produce the NielsenExoPlayerPlugin.aar file
  • Build the NielsenSampleAppForExoPlayer with the NielsenExoPlayerPlugin

Nielsen SampleApp

  • Import the module NielsenSampleAppForExoPlayer into the project.
  • Add ad related jar files in the /libs directory if required eg. For Google IMA add the gIMAsdk.jar file
  • Include the following in the build.gradle to compile with the NielsenExoPlayerPlugin
    compile project(':NielsenExoPlayerPlugin')
  • Build the NielsenSampleAppForExoPlayer to produce the NielsenSampleAppForExoPlayer apk file (Sample App with Plugin).

Nielsen ExoPlayer Plugin

The Nielsen ExoPlayer Plugin monitors the ExoPlayer events and provides the required metadata to the Nielsen AppSDK for measurements. The ExoPlayer Plugin is created with the PluginManager.

In order to monitor ExoPlayer with Nielsen measuring SDK, ExoPlayer Plugin has to be created.

PluginManager and Plugin instances

At any moment there can be at most 4 instances of Nielsen SDK. That rule also applies to Nielsen ExoPlayer Plugin instances.

Plugin Manager

The main object that manages Nielsen ExoPlayer Plugins is the Nielsen PluginManager. All interaction with Nielsen ExoPlayer Plugins is done through the Nielsen PluginManager instance. Nielsen PluginManager instance has to be initialized and the proper way to do this is:

  • By creating your own Application class that extends AppSdkApplication. It is mandatory to extend AppSdkApplication and change application android:name field in AndroidManifest file. Nielsen SDK will not work properly for DCR static productif you do not extend it.
  • In your own application class, call the initialiseInstance() in the onCreate method:
    PluginManager.initialiseInstance(this);
    Or this line if you want to enable log output from PluginManager and Plugin instances:
    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, or if it is null, the tag is created and returned.

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

Plugin Creation

Plugin is created with createNewPlugin method of PluginManager instance. Plugin can be created with or without ExoPlayer reference. With later option, ExoPlayer has to be attached to the Plugin instance.

Important fields is PluginConfig which 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 as pluginTag field) or tag provided to it.

PluginEventListener is an optional field. If set, the Nielsen AppSdk events are forwarded to that object. PluginEventListener must not be anonymous as it will be garbage collected.

Following is an example of the code for Plugin creation without ExoPlayer reference. 

JSONObject config = new JSONObject()
              .put("appid", "TF2D48D99-9B58-B05C-E040-070AAB3176DB")
              .put("appname", getResources().getString(R.string.app_name))
              .put("appversion", BuildConfig.VERSION_NAME)
              .put("sfcode", PluginConfig.SF_CODE_DCR)
              .put("clientid", "AppSampleClientId")
              .put("prod", "vc,iag")
              .put("category", "AppSampleCategory")
              .put("tfid", "AppSampleTfid")
              .put("vcid", "AppSampleVcId")
              .put("sid", "AppSampleSid")
              .put("pd", "AppSamplePd")
              .put("nol_devdebug", "DEBUG")
              .put("nol_url_override", sdkCfgUrl);
nielsenPluginTag = PluginManager.getInstance()
.createNewPlugin(config, null, getContext(), pluginEventListener);
// Or this next line if you want to provide your own pluginTag
PluginManager.getInstance()
.createNewPlugin(pluginConfigBuilder.build(), nielsenPluginTag, getContext(), pluginEventListener);

Plugin lifecycle

  • Scope:
    • After creation, every Plugin is stored in the PluginManager. The Plugin Manager is a Singleton. This means that Plugin scope is greater than ExoPlayer which the Plugin monitors and is not destroyed when Activity or Fragment holding ExoPlayer is destroyed. Plugin only has a WeakReference to that ExoPlayer object to prevent memory leaks. Also, this ensures that ExoPLayer is destroyed with its Activity or Fragment.
    • The Plugin instance has to be destroyed manually when it is not required any more.
  • 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 instance
      PluginManager.getInstance().destroyPlugin(nielsenPluginTag);
  • Attaching Plugin to new ExoPlayer:
    • Upon device rotation and configuration change, if the activity or fragment is recreated, since Plugin instance scope is greater, it is possible to attach new ExoPlayer to the existing Plugin instance.
    • Note that NielsenPluginDataProvider, ExoPlayerContentDataProvider and PluginEventListener have to be attached too.
      PluginManager.getInstance()
.attachPluginToExoPlayer(nielsenPluginTag, exoPlayer, contentDataProvider, pluginDataProvider, pluginEventListener);

Data Providers

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

Nielsen Plugin Data Provider

NielsenPluginDataProvider has two methods that it uses to collect metadata from app. 

JSONObject onPlayDataRequest(JSONObject playDataObject, String pluginTag);
JSONObject onContentMetaDataRequest(JSONObject metadataObject, String pluginTag);

pluginTag field is passed by plugin so that in case of mulitple Plugin instances it is easily distinguishable which Plugin instance requires data.

For more information on the Nielsen App SDK metadata refer to the Android SDK API Reference.

Nielsen ExoPlayer Content Data Provider

ExoPlayerContentDataProvider has three methods and it request data regarding ExoPlayer that is linked to the Plugin instance and plays content. 

boolean isContentPlaying();
boolean isContentAboutToPlay();
boolean isAdAboutToPlay();

Nielsen ExoPlayer Ads Data Provider

ExoPlayerAdsDataProvider has two methods and it requests data regarding advertisement player. 

JSONObject onAdMetadataRequest(JSONObject metadataObject, String pluginTag); long onAdPositionRequest();

Advertisement Adapter is a link between user Advertisement implementation and Nielsen Plugin instance that monitors that advertisement.

Advertisement Adapter is required only for advertisement monitoring, and it is not necessary for the regular content monitoring.

Advertisement Adapter is created via Plugin Manager. To create Advertisement Adapter, use createAdvertisementAdapterForPlugin() method, example: 

advertisementAdapter = PluginManager.getInstance()
.createAdvertisementAdapterForPlugin(nielsenPluginTag, adsDataProvider);

Both pluginTag and AdsDataProvider parameters are mandatory.

Usage

It is user responsibility to call appropriate advertisement adapter methods when it is required.

Advertisement adapter methods:

  • void onAdStart()
  • void onAdPause()
  • void onAdResume()
  • void onAdEnd()

By delegating those ad events to the Advertisement adapter, Plugin instance can properly handle advertisement monitoring.

Note: A new advertisement adapter must be created when the new ExoPlayer is created and attached to the Nielsen Plugin instance.

Opt-In / Opt-Out use cases

When the app user wants to opt in or opt out of Nielsen measurement, a new dynamic page should be displayed. Nielsen ExoPlayer plugin provides an interface to obtain the OptOut Url. Additionally it also provides two other Opt Out implementations. The optIn / optOut value selected by the user is passed to the Plugin.

Note: All OptOut use cases rely on a Plugin instance which means that PluginManager must have at least one Plugin instance for 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 Nielsen SDK Documentation.

Opt Out Activity

The OptOut Activity is provided with the Plugin. Using the following steps the Nielsen Opt Out web page can be rendered.

Implementation:

  • Add Nielsen OptOutctivity to your AndroidManifest.xml
    <activity android:name=".OptOutActivity"/>
  • Show OptOutActiivty
    <PluginManager.getInstance().showOptOutActivity(activity);

Opt Out Fragment

An OptOutFragment is also provided with the Plugin. Using the following steps the Nielsen OptOut web page can be rendered.

Implementation:

  • Add OptOutFragment in your activity layout
    <fragment
android:id="@+id/NielsenOptOutFragment"
android:name=".OptOutFragment"
android:layout_width="wrap_content"
android:layout_height="wrap_content"/>
  • Add Nielsen OptOutFragment with FragmentManager
    final OptOutFragment optOutFragment = OptOutFragment.newInstance();
final FragmentManager fragmentManager = getSupportFragmentManager();
fragmentManager.beginTransaction().add(R.id.fragment_container, optOutFragment, OptOutFragment.TAG).commit();

PluginManager Methods

The following API's are provided by the PluginManager for the application to interact with Plugin instances.

Function Name
AppDisable 
boolean disableNielsenAppSdk(boolean disable)
boolean isNielsenAppSdkDisabled()
Logging 
void setLogging(boolean enableLogging) boolean isLoggingEnabled()
Plugin Existence 
boolean hasPluginWithTag(String pluginTag)
Static Content 
boolean sendStaticContent(JSONObject staticContent, String pluginTag)
ID3 Metadata 
boolean sendId3Metadata(String metadataMap, String pluginTag)

Static content

StaticContent is used to provide the metadata required for measuring static content.

Static content usage: 

JSONObject staticContent = new JSONObject()
       .put("type", "static")
       .put("section", "siteSection")
       .put("crossId", "Reference11")
       .put("segA", "segA")
       .put("segB", "segB")
       .put("segC", "segC");
PluginManager.getInstance().sendStaticContent(staticContent, nielsenPluginTag);

ID3 Metadata

If your ExoPlayer implementation supports ID3 metadata, it can be passed to the Nielsen AppSdk Plugin through the PluginManager.

ID3 metadata API usage:

Forward metadata object from the MetadataTrackRenderer.MetadataRenderer <Object> callback method 

void onMetadata(Object metadata);

Example: 

@Override
public void onMetadata(Object metadata) {
PluginManager.getInstance().sendId3Metadata(metadata, nielsenPluginTag);
}

PluginTag parameter is mandatory. It specifies which Plugin instance will be used to send ID3 metadata.

ExoPlayer 1.5.8 has a known issue

https://github.com/google/ExoPlayer/issues/1074

Due to this, in case of live stream pause and resume scenario, live stream could not continue playback after ~2 mins of resume from pause. Rather it posts an error for this Exception in trace so that app developers can take preventive measures to recover from the situation. If app developers are not taking care of this, it may lead to possible app user experience issue where user has to hit play button to continue to play live stream after pause and resume scenario.

Releases

Name Version # Date Comments
Nielsen AppSDK Plugin for ExoPlayer 1.0.0 7/26/2016 Initial version of the Nielsen Android App SDK Plugin for ExoPlayer with Google IMA ad support. This Plugin has been tested with AppSdk v5.1.1.3.
Nielsen AppSDK Plugin for ExoPlayer 1.0.1 8/26/2016 Updated version of the Nielsen Android App SDK Plugin for ExoPlayer with Google IMA ad support. This Plugin has been tested with AppSdk v5.1.1.4 and ExoPlayer version 1.5.8. ExoPlayer had changed ID3 extraction listener and classes in v1.5.8, those changes are incorporated in the Nielsen Plugin as well
Retrieved from "https://engineeringportal.nielsen.com/w/index.php?title=ExoPlayer_Plugin_Android&oldid=1804"