Admin at 21:53, 20 October 2017

2017-10-20T21:53:24Z

← Older revision		Revision as of 21:53, 20 October 2017
Line 10:		Line 10:
	\|SDKVersion=5.1.1.4		\|SDKVersion=5.1.1.4
	\|supportedAdFrameworks=Google IMA		\|supportedAdFrameworks=Google IMA
			\|downloadLink=https://engineeringportal.nielsen.com/w/downloads/digital/plugins/native/exoplayer/Nielsen-ExoPlayer-Plugin-Android-1.0.1.zip
	}}		}}

Admin at 21:06, 31 August 2017

2017-08-31T21:06:51Z

← Older revision		Revision as of 21:06, 31 August 2017
Line 3:		Line 3:

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

			{{PluginInfobox
			\|pluginImage=AndroidLogoIcon
			\|osImage=AndroidIcon
			\|playerVersion=1.5.8
			\|SDKVersion=5.1.1.4
			\|supportedAdFrameworks=Google IMA
			}}

	== Component Diagram ==		== Component Diagram ==

Admin at 07:47, 25 May 2017

2017-05-25T07:47:50Z

← Older revision		Revision as of 07:47, 25 May 2017
Line 1:		Line 1:
	{{Breadcrumb\|}} {{Breadcrumb\|Digital}} {{CurrentBreadcrumb}}		{{Breadcrumb\|}} {{Breadcrumb\|Digital}} {{Breadcrumb\|DCR & DTVR}} {{CurrentBreadcrumb}}
	[[Category:Digital]]		[[Category:Digital]]

Admin at 08:01, 23 May 2017

2017-05-23T08:01:15Z

← Older revision		Revision as of 08:01, 23 May 2017
Line 55:		Line 55:
	** The sample application source code.		** The sample application source code.
	*'''Nielsen App SDK'''		*'''Nielsen App SDK'''
	** Download the Nielsen App SDK jar file from [[Downloads]]		** Download the Nielsen App SDK jar file from [[Digital Downloads]]

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

Admin: Created page with "{{Breadcrumb|}} {{Breadcrumb|Digital}} {{CurrentBreadcrumb}} Category:Digital '''Nielsen App SDK Plugin for ExoPlayer''' interacts with Nielsen App SDK to provide with ne..."

2017-05-22T21:49:53Z

Created page with "{{Breadcrumb|}} {{Breadcrumb|Digital}} {{CurrentBreadcrumb}} Category:Digital '''Nielsen App SDK Plugin for ExoPlayer''' interacts with Nielsen App SDK to provide with ne..."

New page

{{Breadcrumb|}} {{Breadcrumb|Digital}} {{CurrentBreadcrumb}}
[[Category:Digital]]

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

== Component Diagram ==
[[File:Exo-component.png|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
* 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 [https://developer.android.com/guide/topics/media/exoplayer.html|ExoPlayer 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 ===
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'''
** Download the Nielsen App SDK jar file from [[Downloads]]

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<syntaxhighlight lang="java">compile project(':NielsenExoPlayerPlugin')</syntaxhighlight>
* 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:<syntaxhighlight lang="java">PluginManager.initialiseInstance(this);</syntaxhighlight>Or this line if you want to enable log output from PluginManager and Plugin instances:<syntaxhighlight lang="java">PluginManager.initialiseInstance(this, enableLogging);</syntaxhighlight>

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.
<syntaxhighlight lang="java">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);</syntaxhighlight>

=== 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<syntaxhighlight lang="java">PluginManager.getInstance().destroyPlugin(nielsenPluginTag);</syntaxhighlight>

*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.<syntaxhighlight lang="java">PluginManager.getInstance()
.attachPluginToExoPlayer(nielsenPluginTag, exoPlayer, contentDataProvider, pluginDataProvider, pluginEventListener);</syntaxhighlight>

=== 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.
<syntaxhighlight lang="java">JSONObject onPlayDataRequest(JSONObject playDataObject, String pluginTag);
JSONObject onContentMetaDataRequest(JSONObject metadataObject, String pluginTag);</syntaxhighlight>

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.
<syntaxhighlight lang="java">boolean isContentPlaying();
boolean isContentAboutToPlay();
boolean isAdAboutToPlay();</syntaxhighlight>

==== Nielsen ExoPlayer Ads Data Provider ====
ExoPlayerAdsDataProvider has two methods and it requests data regarding advertisement player.
<syntaxhighlight lang="java">JSONObject onAdMetadataRequest(JSONObject metadataObject, String pluginTag); long onAdPositionRequest();</syntaxhighlight>

=== Advertisement Adapter ===
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 creation ====
Advertisement Adapter is created via Plugin Manager. To create Advertisement Adapter, use createAdvertisementAdapterForPlugin() method, example:
<syntaxhighlight lang="java">advertisementAdapter = PluginManager.getInstance()
.createAdvertisementAdapterForPlugin(nielsenPluginTag, adsDataProvider);</syntaxhighlight>

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:
* <code>void onAdStart()</code>
* <code>void onAdPause()</code>
* <code>void onAdResume()</code>
* <code>void onAdEnd()</code>
By delegating those ad events to the Advertisement adapter, Plugin instance can properly handle advertisement monitoring.
<blockquote>'''Note:''' A new advertisement adapter must be created when the new ExoPlayer is created and attached to the Nielsen Plugin instance.</blockquote>

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

=== Opt Out Interface ===
Use PluginManager to obtain Nielsen user Opt Out Url
<syntaxhighlight lang="java">PluginManager.getInstance().getOptOutUrl();</syntaxhighlight>
User selected Opt Out result must be passed to PluginManager instance.
<syntaxhighlight lang="java">PluginManager.getInstance().sendOptInOutEvent(optOutresult);</syntaxhighlight>
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<syntaxhighlight lang="java"><activity android:name=".OptOutActivity"/></syntaxhighlight>
* Show OptOutActiivty<syntaxhighlight lang="java"><PluginManager.getInstance().showOptOutActivity(activity);</syntaxhighlight>

=== 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<syntaxhighlight lang="java"><fragment
android:id="@+id/NielsenOptOutFragment"
android:name=".OptOutFragment"
android:layout_width="wrap_content"
android:layout_height="wrap_content"/></syntaxhighlight>
* Add Nielsen OptOutFragment with FragmentManager<syntaxhighlight lang="java">final OptOutFragment optOutFragment = OptOutFragment.newInstance();
final FragmentManager fragmentManager = getSupportFragmentManager();
fragmentManager.beginTransaction().add(R.id.fragment_container, optOutFragment, OptOutFragment.TAG).commit();</syntaxhighlight>

== PluginManager Methods ==

The following API's are provided by the PluginManager for the application to interact with Plugin instances.
{| class="wikitable"
|-
! Function !! Name
|-
| AppDisable || <syntaxhighlight lang="java">boolean disableNielsenAppSdk(boolean disable)
boolean isNielsenAppSdkDisabled()</syntaxhighlight>
|-
| Logging || <syntaxhighlight lang="java">void setLogging(boolean enableLogging) boolean isLoggingEnabled()</syntaxhighlight>
|-
| Plugin Existence || <syntaxhighlight lang="java">boolean hasPluginWithTag(String pluginTag)</syntaxhighlight>
|-
| Static Content || <syntaxhighlight lang="java">boolean sendStaticContent(JSONObject staticContent, String pluginTag)</syntaxhighlight>
|-
| ID3 Metadata || <syntaxhighlight lang="java">boolean sendId3Metadata(String metadataMap, String pluginTag)</syntaxhighlight>
|}

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

Static content usage:
<syntaxhighlight lang="java">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);</syntaxhighlight>

=== 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
<syntaxhighlight lang="java">void onMetadata(Object metadata);</syntaxhighlight>

Example:
<syntaxhighlight lang="java">@Override
public void onMetadata(Object metadata) {
PluginManager.getInstance().sendId3Metadata(metadata, nielsenPluginTag);
}</syntaxhighlight>

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

ExoPlayer Plugin Android - Revision history

Admin at 21:53, 20 October 2017

Admin at 21:06, 31 August 2017

Admin at 07:47, 25 May 2017

Admin at 08:01, 23 May 2017

Admin: Created page with "{{Breadcrumb|}} {{Breadcrumb|Digital}} {{CurrentBreadcrumb}} Category:Digital '''Nielsen App SDK Plugin for ExoPlayer''' interacts with Nielsen App SDK to provide with ne..."