JW Player Plugin Android - Revision history

Admin at 21:52, 20 October 2017

2017-10-20T21:52:20Z

← Older revision		Revision as of 21:52, 20 October 2017
Line 10:		Line 10:
	\|SDKVersion=5.1.0.4		\|SDKVersion=5.1.0.4
	\|supportedAdFrameworks=VMAP and VAST		\|supportedAdFrameworks=VMAP and VAST
			\|downloadLink=https://engineeringportal.nielsen.com/w/downloads/digital/plugins/jwplayer/android/Nielsen-App-SDK-JW-Player-Plugin-Android-1.1.0.zip
	}}		}}

Admin at 20:36, 31 August 2017

2017-08-31T20:36:32Z

← Older revision		Revision as of 20:36, 31 August 2017
Line 2:		Line 2:
	[[Category:Digital]]		[[Category:Digital]]

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

			{{PluginInfobox
			\|pluginImage=JWPlayerIcon
			\|osImage=AndroidIcon
			\|playerVersion=2.0.141
			\|SDKVersion=5.1.0.4
			\|supportedAdFrameworks=VMAP and VAST
			}}

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

Admin at 07:48, 25 May 2017

2017-05-25T07:48:46Z

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

	'''Supported Ad Frameworks'''		'''Supported Ad Frameworks'''
	* VMAP		* VMAP

Admin: /* Plugin lifecycle */

2017-05-22T21:08:06Z

Plugin lifecycle

← Older revision		Revision as of 21:08, 22 May 2017
Line 128:		Line 128:
	===Plugin lifecycle===		===Plugin lifecycle===
	* Scope		* 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.		** 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.		** Destroy the Plugin instance manually, when it is not required.
	* Destroying Plugin instance		* Destroying Plugin instance
	* * Use the PluginManager to destroy a 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.<syntaxhighlight lang="java">PluginManager.getInstance().destroyPlugin(nielsenPluginTag);</syntaxhighlight>		** Provide the Tag of the Plugin instance to specify which Plugin instance is to be destroyed.<syntaxhighlight lang="java">PluginManager.getInstance().destroyPlugin(nielsenPluginTag);</syntaxhighlight>
	* Re-attaching Plugin to new JwPlayerView		* 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.		** 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.<syntaxhighlight lang="java">PluginManager.getInstance().reattachPluginToJwPlayerView(nielsenPluginTag, jwPlayerView, nielsenPluginDataProvider, pluginEventListener);</syntaxhighlight>		** Ensure to re-attach the NielsenPluginDataProvider and PluginEventListener.<syntaxhighlight lang="java">PluginManager.getInstance().reattachPluginToJwPlayerView(nielsenPluginTag, jwPlayerView, nielsenPluginDataProvider, pluginEventListener);</syntaxhighlight>

	=== Nielsen Plugin Data Provider ===		=== Nielsen Plugin Data Provider ===

Admin: /* Initial Configuration */

2017-05-22T20:56:33Z

Initial Configuration

← Older revision		Revision as of 20:56, 22 May 2017
Line 43:		Line 43:

	=== Initial Configuration ===		=== Initial Configuration ===
	Before integrating the Plugin, make sure to download the following		Before integrating the Plugin, make sure to download the following:

	*'''JW Player ADK for Android'''		*'''JW Player ADK for Android'''

Admin: /* Initial Configuration */

2017-05-22T20:47:40Z

Initial Configuration

← Older revision		Revision as of 20:47, 22 May 2017
Line 54:		Line 54:

	*'''Nielsen App SDK'''		*'''Nielsen App SDK'''
	**Download the Nielsen App SDK jar file from [[~~Digital~~ Downloads]]		**Download the Nielsen App SDK jar file from [[Downloads]]

	== Building the Plugin and Sample App ==		== Building the Plugin and Sample App ==

Admin: Created page with "{{Breadcrumb|}} {{Breadcrumb|Digital}} {{CurrentBreadcrumb}} Category:Digital '''Supported Ad Frameworks''' * VMAP * VAST '''Nielsen App SDK Plugin for JW Player''' intera..."

2017-05-22T19:58:51Z

Created page with "{{Breadcrumb|}} {{Breadcrumb|Digital}} {{CurrentBreadcrumb}} Category:Digital '''Supported Ad Frameworks''' * VMAP * VAST '''Nielsen App SDK Plugin for JW Player''' intera..."

New page

{{Breadcrumb|}} {{Breadcrumb|Digital}} {{CurrentBreadcrumb}}
[[Category:Digital]]
'''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 ==
[[File:JwPlayer-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
* 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 [[https://www.jwplayer.com/products/mobile-sdk/android/|JW 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 [[Digital 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<syntaxhighlight lang="java">compile project(‘:NielsenJWPlayerPlugin’)</syntaxhighlight>
** 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:<syntaxhighlight lang="java">PluginManager.initialiseInstance(this);</syntaxhighlight>To enable log output from PluginManager and Plugin instances, use<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. 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.
<syntaxhighlight lang="java">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);
}</syntaxhighlight>

===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.<syntaxhighlight lang="java">PluginManager.getInstance().destroyPlugin(nielsenPluginTag);</syntaxhighlight>
* 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.<syntaxhighlight lang="java">PluginManager.getInstance().reattachPluginToJwPlayerView(nielsenPluginTag, jwPlayerView, nielsenPluginDataProvider, pluginEventListener);</syntaxhighlight>

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

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.
<blockquote>'''Note''': The PluginManager must have at least one Plugin instance for the 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 [[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<syntaxhighlight lang="java"><activity android:name=”jwplugin.appsdk.nielsen.com.jwplugin.OptOutActivity” /></syntaxhighlight>
* Show OptOutActivity<syntaxhighlight lang="java>PluginManager.getInstance().showOptOutActivity(activity);</syntaxhighlight>

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

Implementation:
* Add OptOutFragment in the activity layout<syntaxhighlight lang="java"><fragment
android:id=”@+id/NielsenOptOutFragment”
android:name=”jwplugin.appsdk.nielsen.com.jwplugin.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 Plugin Manager provides the application with these functions.

{| 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(StaticContent staticContent, String pluginTag)</syntaxhighlight>
|}

== Releases ==
{| class="wikitable"
|-
! Name !! Version # !! Date !! Comments
|-
| Nielsen App SDK Plugin for JW Player (VMAP) || 1.0.0 || 2/28/2016 || Initial version of the Nielsen App SDK Plugin for JW Player (Android) with support for VAST and VMAP ads.
|-
| Nielsen App SDK Plugin for JW Player || 1.1.0 || 6/17/2016 || Plugin with changes due to changes in App sdk API’s in the DCR and International (Germany) combined build was tested with App SDK version 5.1.0.4 and JWPlayer SDK version 2.1.0.141
|}