View source for Android SDK Initialization

== SDK Initialization ==
The latest version of the Nielsen App SDK allows instantiating multiple instances of the SDK object, which can be used simultaneously without any issue. The sharedInstance API that creates a singleton object was deprecated prior to version 5.1.1. (Version 4.0 for Android)

The following table contains the list of arguments that can be passed via the AppInfo JSON schema.
{| class="wikitable"
|-
! Parameter / Argument !! Description !! Source !! Required? !! Example
|-
| appid || Unique Nielsen ID for the application. The ID is a GUID data type. If you did not receive your App ID, let us know and we will provide you. || Nielsen-specified || Yes || PXXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX
|-
| nol_devDebug || Enables Nielsen console logging. Only required for testing
|| Nielsen-specified || Optional || "DEBUG"
|}
== Debug flag for development environment ==
Player application developers / integrators can use Debug flag to check whether an App SDK API call made is successful. To activate the Debug flag,
Pass the argument <code>@"nol_devDebug":@"INFO"</code>, in the JSON string . The permitted values are:

* '''INFO''': Displays the API calls and the input data from the application (validate player name, app ID, etc.). It can be used as certification Aid.
* '''WARN''': Indicates potential integration / configuration errors or SDK issues.
* '''ERROR''': Indicates important integration errors or non-recoverable SDK issues.
* '''DEBUG''': Debug logs, used by the developers to debug more complex issues.

Once the flag is active, it logs each API call made and the data passed. The log created by this flag is minimal.
<blockquote>'''Note''': DO NOT activate the Debug flag in a production environment.</blockquote>

==== Sample SDK Initialization Code ====
[[AppSDK()]] is no longer a singleton object and should be initialized as below.

'''Initialization of App SDK object through a JSON object'''
<syntaxhighlight lang="java">try
{
  // Prepare AppSdk configuration object (JSONObject)
  JSONObject appSdkConfig = new JSONObject()
          .put("appid", "PDA7D5EE6-B1B8-XXXX-XXXX-2A788BCXXXCA")
          .put("nol_devDebug", "DEBUG"); // only for debug builds

// Pass appSdkConfig to the AppSdk constructor
mAppSdk = new AppSdk(appContext, appSdkConfig, appSdkListener);
}
catch (JSONException e)
{
  Log.e(TAG, "Couldn’t prepare JSONObject for appSdkConfig", e);
}
</syntaxhighlight>
Here, <code>appContext</code> is the App context object and <code>appSdkConfig</code> is JSON object for holding the parameters (<code>appid</code>) the App passes to the Nielsen App SDK via a JSON string. The appid is obtained from Nielsen operational support and is unique to the app.


The integration of Nielsen App SDK will depend on type of client app.<br />
* Ensure that SDK files (AppSdk.jar and libAppSdk.so [App SDK 1.2 Only]) are included under the App’s project and the App SDK is linked to the App (the setting to link App SDK to the App can be found on property page of the App’s project).

== Initializing Viewability and Audibility Measurement ==
If your Nielsen integration will be enabled for viewability/audibility measurement, your app should call trackViewability after initializing the SDK (previous paragraphs). 

Viewability metrics allow AppSDK to track the visibility of the player and collect information about how much of the player container is visible to the end user during playback. Audibility metrics report on the device volume level.

The viewability pings will be fired following the same rules as measurement pings. Viewability pings will be POST requests, not GET requests like other data pings. POST body for viewability requests will contain the key-value pairs in JSON format. The key parameters in the URL schemes are '''invs, inau, inss, invp''' and '''ines''' which will contain the collected viewability data. This data will be formatted according to the specific rules so that downstream it will be possible to match measurement and viewability data for a session.

Audibility metrics will capture the volume level as well as mute/unmute state of the device during playback.

== Calling trackViewability for player view ==

== Input Parameters ==
{| class="wikitable"
|-
! Parameter !! Description
|-
| data || JSONObject object with the following objects and keys:
{| class="wikitable"
|-
| viewTag (mandatory) || value of String type, tag identifier for the target player view object. This tag can be assigned for the player view either programmatically or in the layout xml, as explained in above section. 
|-
| viewContainer (mandatory) || Reference to the activity object. It is needed to identify and search the target player view in current visible screen. This parameter can not be nil. This should be the current activity object where target view is loaded. If the player view is rendered in a fragment, please provide the parent activity reference of the fragment.
|-
| friendlyObstructions (optional) || an array of tags of the views which should be ignored during the intersection ratio calculation. Those are views like loading activity indicator, player controls, view with a watermark, etc. which are displayed in front of the target view, but should not reduce the viewability intersection ratio. The tags of such should be wrapped into the String objects before adding into the array. This parameter is nullable, empty array is also accepted.
|}
|}


== Syntax ==
<br/>
<syntaxhighlight lang="java">
void  trackViewability(JSONObject);
</syntaxhighlight>

== Usage Example ==
<syntaxhighlight lang="objective-c">
String targetViewTag = targetView.getTag().toString();
String activityObj = MainActivity.this;
JSONArray friendlyTags = new JSONArray();
friendlyTags.put("friendlyViewTag1");
friendlyTags.put("friendlyViewTag2");

JSONObject json = new JSONObject();
json.put("viewContainer", activityObj);
json.put("viewTag", targetViewTag);
json.put("friendlyObstructions", friendlyTags);
sdkInstance.trackViewability(json);
</syntaxhighlight>
<br>
[[File:PlayerScreen_ViewContainer-ViewTag-FriendlyViews.png|300px]]<br>

== Setting tag for a player view in layout xml ==
<br>
<syntaxhighlight lang="objective-c">
<SurfaceView
   android:id="@+id/playerView"
   android:tag="playerViewTag"           
   android:layout_width="match_parent"
   android:layout_height="match_parent"
/>
</syntaxhighlight>

== Setting tag for a player view in Activity/Fragment ==
<br>
<syntaxhighlight lang="objective-c">
mPlayerView = (SurfaceView) findViewById(R.id.playerView);
mPlayerView.setTag("playerViewTag");
</syntaxhighlight>


=== Data Collected ===
{| class="wikitable"
|-
! Parameter !! Description
|-
| Measured Value || Value is different for different request parameters:
{| class="wikitable"
|-
| '''invs''' ||  Intersection ratio for the target view in percent (from 0 to 100). Default threshold for this value is 5. Example: ['''50''',1,1528457356,10]
|-
| '''inau''' || Volume level on the device in percent (from 0 to 100), where 0 - mute, 100 - max volume level. Default threshold for this value is 1. Example: ['''30''',1,1528457356,10]
|-
| '''inss''' || Device screen size as "WxH", where W - is width in pixels, H - is height in pixels. Example: ['''"1024x768"''',1,1528457356,10]
|-
| '''invp''' || Current window size. This is different than the device screen size in a multiple scene mode or on a desktop. Format is "WxH", where W - is width in pixels, H - is height in pixels. Example: ['''"800x600"''',1,1528457356,10]
|-
| '''ines''' || Player view size as "WxH", where W - is width in pixels, H - is height in pixels. Example: ['''"300x200"''',1,1528457356,10]
|}
|-
| Start offset || Value contains the first playhead or the first id3 offset with non-null CID after start, flush or resume. Example playhead: [50,'''1''',1528457356,10]. Example id3 offset: [50,'''70100''',1528457356,10]
|-
| Start timestamp || Timestamp value when the time period related to this time series item was started. Example: [50,1,'''1528457356''',10]
|-
| Duration || Duration value is calculated as a difference between the last playhead and the first playhead for the current time series item. Example: [50,1,1528457356,'''10''']
|}