View source for DCR Italy Static App SDK

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

== Overview ==
The Nielsen SDK is one of multiple framework SDKs that Nielsen provides to enable measuring linear (live) and on-demand TV viewing using TVs, mobile devices, etc.
The App SDK is the framework for mobile application developers to integrate Nielsen Measurement into their media player applications. It supports a variety of Nielsen Measurement Products like Digital in TV Ratings, Digital Content Ratings ([[DCR & DTVR]]), [[Digital Ad Ratings]] (DAR), [[Digital Audio]]. Nielsen SDKs are also equipped to measure static content and can track key life cycle events of an application like:
*Application launch events and how long app was running
*Time of viewing a sub section / page in the application.

==  Implementation ==
This guide covers implementation steps for iOS using Xcode and Java using Android Studio to enable '''STATIC MEASUREMENT''' within you APP.

== Prerequisites == 
To start using the Nielsen App SDK, your Xcode or Android Studio environments need to have specific Frameworks or Classes included in your project/app.  This information is detailed in the [[DCR Italy Video App SDK]] documentation.

<blockquote> The remainder of this document will assume that you have followed the steps outlined in the [[DCR Italy Video App SDK]] documentation to Initialize the Nielsen SDK.</blockquote>

== Initialize the SDK == 
Specific steps are outlined in the [[DCR Italy Video App SDK]] documentation.

== Populate and Pass Metadata Object ==
The Nielsen SDK is able to monitor Application launch events and how long your app has been running.  Once the Nielsen SDK has been Initialized, pass <code>"type":'static'</code> as a JSON object via loadMetadata.

{{ExampleCode|
|Swift = <syntaxhighlight lang="swift">
        let staticMetadata = [
            "type": "static",
            "assetid": "vid345-67483",
            "section": "siteSection"
        ];
         self.nielsenAppApi?.loadMetadata(staticMetadata)
</syntaxhighlight>
|Objective C = <syntaxhighlight lang="objective-c"> 
   NSDictionary *staticMetadata = @
    {
        "type": "static",
        "assetid": "vid345-67483",
        "section": "siteSection"
    }
– (void)loadMetadata:(id)staticMetadata;
</syntaxhighlight>

|Android = <syntaxhighlight lang="java">    JSONObject staticMetadata = new JSONObject()
        .put("type", "static")
        .put("section", "siteSection")
        .put("assetid", "vid345-67483")
    }
public void loadMetadata(JSONObject staticMetadata);
</syntaxhighlight>

}}
The above code would be repeated for each change in "section" within your app.

=== Nielsen SDK Metadata ===
The following table defines the staticMetadata reserved keys:

{| class="wikitable"
|-
! Key !! Description !! Data Type !! Value !! Required?
|-
| type || asset type || fixed || <code>'static'</code> || Yes
|-
| assetid || Unique ID for each article || dynamic || custom || Yes
|-
| section || section of each site (e.g. section value should be first level in page URL: website.com/section). Limit to 25 unique values || dynamic || custom || Yes
|}

== Handling Foreground and Background states  ==
For iOS, background/foreground detection is handled by the app lifecylce APIs which are provided by [https://developer.apple.com/library/content/documentation/iPhone/Conceptual/iPhoneOSProgrammingGuide/TheAppLifeCycle/TheAppLifeCycle.html Apple]:

Foreground/Background state measurement is a requirement of Nielsen AppSDK implementation which is especially crucial for static measurement. It may be implemented in multiple ways for Android. This includes
* Enable the Nielsen SDK to measure background/foreground state by makingthe relevant update to the AndroidManifest.
* Integrate Nielsen’s SdkBgFgDetectionUtility class within your Custom Application Class.
* Custom implementation of the required methods within your application.

=== ForeGround/Background Measurement via AndroidManifest ===
The simplest way to measure the app background/foreground state is to add the following application tag to the Manifest XML. Integrating this into the Manifest XML will enable the SDK to measure app state directly. This approach is supported for Android 4.0 and up only; it requires that the application class is not in use for some other purpose.
<syntaxhighlight lang="java">
<application android:name=”com.nielsen.app.sdk.AppSdkApplication”>
</syntaxhighlight>

=== Using the Android SdkBgFbDetectionUtility Class ===
For developers who are already using the application class, it is recommended that background/foreground state is implemented using the  [[Android_Background_Foreground|SdkBgFgDetectionUtility class]].  The  [[Android_Background_Foreground|SdkBgFgDetectionUtility class]] is compatible with Android 4+ and has been made available to Nielsen clients.

=== Manual Background/ForeGround State Management ===
In cases where the developer is not able to use the AndroidManifest.xml solution nor the Nielsen provided   [[Android_Background_Foreground|SdkBgFgDetectionUtility class]]  the developer will need to manually identify the change of state through the application and call the respective API (appInForeground() or appInBackground()) to inform the SDK regarding the change of state from background to foreground or foreground to background.

The SDK is informed about app state using the below methods.
<syntaxhighlight lang="java">
AppLaunchMeasurementManager.appInForeground(getApplicationContext());
AppLaunchMeasurementManager.appInBackground(getApplicationContext());
</syntaxhighlight>
Within the lifecycle of individual activities, onResume() and onPause() are best suited to providing indication of the app state.


Correct measurement of the foreground/background state is crucial to Static App measurement within Nielsen Digital Content Ratings (DCR).

== Privacy and Opt-Out ==
Please follow the steps outlined in the [[DCR Italy Video App SDK]] documentation.

== Going Live ==
Following Nielsen testing, users need to make one update to the initialization call to ensure that the site is being measured properly.

# '''Debug Logging''': Disable logging by deleting <code>{nol_sdkDebug: 'DEBUG'}</code> from initialization call.
#* '''Example Production Initialization Call''' - Refer to the production initialization call below:

'''<big>iOS Example:</big>'''

<syntaxhighlight lang="swift">
class NielsenInit: NSObject {
    class func createNielsenAppApi(delegate: NielsenAppApiDelegate) -> NielsenAppApi?{
    let appInformation:[String: String] = [
            "appid": "PXXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX",
            "sfcode": "it"
            // Remove Flag:   "nol_devDebug": "DEBUG"
        ]
        return NielsenAppApi(appInfo:appInformation, delegate:delegate)
    }
}
</syntaxhighlight>


'''<big>Android Example:</big>''' 
<syntaxhighlight lang="java">  
try
{
  // Prepare AppSdk configuration object (JSONObject)
  JSONObject appSdkConfig = new JSONObject()
          .put("appid", "PXXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX")
          .put("sfcode", "it")
            // Remove Flag:   "nol_devDebug": "DEBUG"

// 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>