DCR Germany Static App SDK

From Engineering Client Portal

Engineering Portal breadcrumbArrow.png Digital breadcrumbArrow.png AGF Implementation Documentation breadcrumbArrow.png DCR Germany Static App SDK

Overview

The Nielsen App 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 iOS and Android Apps developers to integrate Nielsen Measurement into their App for the Static Content Measurement.

This guide will show you how to enable Static measurement in your App. The Nielsen App Static Measurement of each different page/section requires different metadata.

Prerequisites

  • To get started, an AppID is needed. The AppID is a unique ID assigned to the App. This will be provided upon starting the integration from Nielsen.
  apid: "XXXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX" // eg. PDA7D5EE6-B1B8-XXXX-XXXX-2A788BCXXXCA
  • No ID AppSDK:

    ONLY the No ID AppSDK should be downloaded for the AGF market!

Step 1: Set up your Development Environment

iOS

For setting up your iOS Development Environment, refer to DCR Germany Video App SDK#iOS

Android

For setting up your Android Development Environment, refer to DCR Germany Video App SDK#Android


Step 2: Create and Initialize SDK Instance

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)

  • A maximum of four SDK instances per appid are supported. When a fifth SDK instance is launched, the SDK will return “nil” from initWithAppInfo:delegate:
  • When four SDK instances exist, you must destroy an old instance before creating a new one.

The following table contains the list of arguments that can be passed via the AppInfo JSON schema.

  • The appid is provided by the Nielsen Technical Account Manager (TAM). The appid is a GUID data type and is specific to the application.
Parameter / Argument Description Source Required/Obligatory? Example
appid Unique id for the application assigned by Nielsen. It is GUID data type. Nielsen-specified "PXXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX"
appname Name of the application Client-defined No "Nielsen Sample App"
appversion Current version of the app used Client-defined No "1.0.2"
sfcode Nielsen collection facility to which the SDK should connect.

AGF Clients

  • "eu" (For Testing/Certification and in Pproduction)
Nielsen-specified "eu"
nol_devDebug Enables Nielsen console logging. Has to be set to "DEBUG" until certified Nielsen-specified Optional "DEBUG"


Sample SDK Initialization Code

iOS
Swift
class NielsenInit: NSObject {
    class func createNielsenAppApi(delegate: NielsenAppApiDelegate) -> NielsenAppApi?{
    let appInformation:[String: String] = [
           "appid": "PDA7D5EE6-B1B8-XXXX-XXXX-2A788BCXXXCA",
            "sfcode": "eu",
            "nol_devDebug": "DEBUG"
        ]
        return NielsenAppApi(appInfo:appInformation, delegate:delegate)
    }
}


Sample code using AVPlayer.
ViewController.swift

class ViewController: UIViewController, NielsenAppApiDelegate, AVPictureInPictureControllerDelegate, CLLocationManagerDelegate  {
    
    let avPlayerViewController = AVPlayerViewController()
    var avPlayer:AVPlayer?
    var nielsenAppApi: NielsenAppApi!

  override func viewDidLoad() {
        super.viewDidLoad()

self.nielsenAppApi = NielsenInit.createNielsenAppApi(delegate: self)
NSLog("Nielsen SDK initialized")

            }
  }
Objective-C

Initialize the Nielsen App object within the viewDidLoad view controller delegate method using initWithAppInfo:delegate:

If App SDK is initialized using init or new methods, it will ignore the API calls resulting in no measurement. The SDK will not return any errors.

    
#import "NlsAppApiFactory.h"
#import <NielsenAppApi/NielsenAppApi.h>

@implementation NlsAppApiFactory

+ (NielsenAppApi *)createNielsenAppApiWithDelegate:(id<NielsenAppApiDelegate>)delegate;
{
    NSDictionary *appInformation = @{
                                     @"appid": "PDA7D5EE6-B1B8-XXXX-XXXX-2A788BCXXXCA",
                                     @"sfcode": "eu",
                                     @"nol_devDebug": @"DEBUG"
                                     };
    return [[NielsenAppApi alloc] initWithAppInfo:appInformation delegate:delegate];
}
@end


The following would be the NlsAppApiFactory.h file:

#import <Foundation/Foundation.h>

@class NielsenAppApi;
@protocol NielsenAppApiDeligate;

@interface NlsAppApiFactory : NSObject 

+ (NielsenAppAPI *) createNielsenAppApiWithDelegate:(id<NielsenAppApiDelegate>)delegate;

@end
Android
Java

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("sfcode", "eu")
          .put("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);
}

Here, appContext is the App context object and appSdkConfig is JSON object for holding the parameters (appid, appname, sfcode) 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 file AppSdk.jar is 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).


Step 3: Review the APP SDK Error & Event Codes

To view the Error and Event codes for iOS and Android, please review the App SDK Event Code Reference page.


Step 4: Create Metadata Object for your page section

The full description of the other key/value pairs for Metadata can be found here: AGF Metadata Convention for Static Measurement

Example Web Page Metadata Object

iOS

Swift
 class SDKMethods : NSObject{ 
    func loadStaticMaster() -> [String : Any] {      
        //Loading Static Main data      
        let staticData =
            [
        "type": "static",
        "assetid": "Unique_asset_ID",
        "section": "Unique_section_ID",
        "segA": "Unique_section_segA",
        "segB": "Mandatory_section_segB",
        "segC": "Optional_section_segC",
        "subbrand": "subbrand_received_from_Nielsen"
        ]       
        return staticData    
    }
Objective-C
 
NSDictionary * staticMetadata = @ {
    @ "type": @ "static",
        @ "assetid": @ "Unique_asset_ID",
        @ "section": @ "Unique_section_ID",
        @ "segA": @ "Unique_section_segA",
        @ "segB": @ "Mandatory_section_segB",
        @ "segC": @ "Optional_section_segC",
        @ "subbrand": @ "subbrand_received_from_Nielsen"
}

Android

   staticMetadata = new JSONObject()
        .put("type", "static")
        .put("section", "Unique_section_ID")
        .put("assetid", "Unique_asset_ID")
        .put("segA", "Unique_section_segA")
        .put("segB", "Mandatory_section_segB")
        .put("segC","Optional_section_segC")
        .put("subbrand","subbrand_received_from_Nielsen");

Step 5: Start the Measurement by calling the loadMetadata AppSDK API

Use the metadata object created in the previous step in the loadMetadata AppSDK API Call.

Swift

self.nielsenAppApi?.loadMetadata(contentMetadata)

Objective C

 (void)loadMetadata:(id)contentMetadata;

Java

public void loadMetadata(JSONObject contentMetadata);

Step 6: Privacy and Opt-Out

The AppSDK measurement is working without cookies and other personal information. No user can be identified personally, therefore an opt-out functionality is not required. The Nielsen AppSDK measurement is utilizing a cookieless domain. In order to disclose Nielsen measurement privacy statement, please include the following items in your privacy policy:

Please contact your Nielsen SDK support team directly for any related questions.

Step 7: Going Live

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

  1. Debug Logging: Disable logging by deleting {nol_sdkDebug: 'DEBUG'} from initialization call.
    • Example Production Initialization Call - Refer to the production initialization call below:

iOS Example:

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

Android Example:

  
try
{
  // Prepare AppSdk configuration object (JSONObject)
  JSONObject appSdkConfig = new JSONObject()
          .put("appid", "PXXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX")
          .put("sfcode", "eu")
            // 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);
}


Note: before going live you have to inform Nielsen team - this is necessary, because Nielsen team has to adjust internal configuration parameter to enable data collection. Without that notification no data will be collected and no data will be reported.