Template:Android SDK Initialization
From Engineering Client Portal
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.
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 @"nol_devDebug":@"INFO"
, 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.
Note: DO NOT activate the Debug flag in a production environment.
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
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);
}
Here, appContext
is the App context object and appSdkConfig
is JSON object for holding the parameters (appid
) 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.
- 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
Parameter | Description | ||||||
---|---|---|---|---|---|---|---|
data | JSONObject object with the following objects and keys:
|
Syntax
void trackViewability(JSONObject);
Usage Example
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);
Setting tag for a player view in layout xml
<SurfaceView
android:id="@+id/playerView"
android:tag="playerViewTag"
android:layout_width="match_parent"
android:layout_height="match_parent"
/>
Setting tag for a player view in Activity/Fragment
mPlayerView = (SurfaceView) findViewById(R.id.playerView);
mPlayerView.setTag("playerViewTag");
Data Collected
Parameter | Description | ||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|
Measured Value | Value is different for different request parameters:
| ||||||||||
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] |