DCR Italy Video App SDK: Difference between revisions

From Engineering Client Portal

No edit summary
 
(22 intermediate revisions by 3 users not shown)
Line 1: Line 1:
{{Breadcrumb|}} {{Breadcrumb|Digital}} {{Breadcrumb|International}}  {{CurrentBreadcrumb}}
{{Breadcrumb|}} {{Breadcrumb|Digital}} {{Breadcrumb|International DCR}}  {{CurrentBreadcrumb}}
[[Category:Digital]]
[[Category:Digital]]


Line 42: Line 42:
* AVFoundation.framework
* AVFoundation.framework
** This framework is mandatory for the iOS SDK version 5.1.1 to work.
** This framework is mandatory for the iOS SDK version 5.1.1 to work.
* CoreLocation.framework (Not applicable for International (Germany))
* CoreLocation.framework  
* CoreMedia.framework
* CoreMedia.framework
* NielsenAppApi.framework
* NielsenAppApi.framework
Line 154: Line 154:
|| Nielsen-specified || Yes || "it"
|| Nielsen-specified || Yes || "it"
|-
|-
| nol_sdkDebug || Enables Nielsen console logging. Only required for testing
| nol_devDebug || Enables Nielsen console logging. Only required for testing
|| Nielsen-specified || Yes || "DEBUG"
|| Nielsen-specified || Optional || "DEBUG"
|}
|}
<br />
<br />
Line 301: Line 301:
NSDictionary  *channelInfo = @
NSDictionary  *channelInfo = @
{
{
   @"channelname":@"My Channel Name 1",
   @"channelName":@"My Channel Name 1",
}
}


Line 308: Line 308:
   @"assetid": [NSString stringWithFormat:@"ProgramAssetId-%d", i],
   @"assetid": [NSString stringWithFormat:@"ProgramAssetId-%d", i],
   @"length": @"3600",
   @"length": @"3600",
  @"program", "Program Name",
  @"title": @"Program S3, EP1",
  @"isfullepisode": @"y",
  @"adloadtype": "2",
  @"airdate": "20161013 20:00:00"
}
}
</syntaxhighlight>
</syntaxhighlight>
Line 313: Line 318:
JSONObject channelInfo = new JSONObject()
JSONObject channelInfo = new JSONObject()
     .put("channelname","My Channel Name 1")
     .put("channelname","My Channel Name 1")


JSONObject contentMetadata = new JSONObject()
JSONObject contentMetadata = new JSONObject()
Line 334: Line 338:
|-
|-
! Key !! Description !! Values !! Required
! Key !! Description !! Values !! Required
|-
| type || type of asset || "content" || ✓
|-
|-
| channelName || Any string representing the channel/stream || custom || ✓
| channelName || Any string representing the channel/stream || custom || ✓
Line 351: Line 353:
| type || type of asset || <code>"content"</code> || Yes
| type || type of asset || <code>"content"</code> || Yes
|-
|-
| assetid || unique ID assigned to asset || custom || Yes
| assetid || unique ID assigned to asset (32 Character limit)|| custom || Yes
|-
|-
| program ||name of program (25 character limit) || custom || Yes
| program ||name of program (100 character limit) || custom || Yes
|-
|-
| title ||name of program (40 character limit) || custom || Yes
| title ||name of program (100 character limit) || custom || Yes
|-
|-
| length || length of content in seconds || <code>seconds</code> (86400 for live stream) || Yes
| length || length of content in seconds || <code>seconds</code> (0 for live stream) || Yes
|-
|-
| airdate || the airdate in the linear TV || YYYYMMDD HH24:MI:SS || Yes
| airdate || the airdate in the linear TV || YYYYMMDD HH24:MI:SS || Yes
Line 418: Line 420:


'''Note''': In case of any interruptions during playback due to alarm, calendar, call, flight mode, Wi-Fi toggle, channel change, etc., call [[stop]] to stop the measurement.
'''Note''': In case of any interruptions during playback due to alarm, calendar, call, flight mode, Wi-Fi toggle, channel change, etc., call [[stop]] to stop the measurement.
* As soon as the playback resumes, call [[DCR_Video_APP_SDK#play|play]], [[DCR_Video_APP_SDK#loadMetadata|loadMetadata]] and  [[DCR_Video_APP_SDK#playheadPosition|playheadPosition]].</blockquote>
* As soon as the playback resumes, call [[DCR_Video_APP_SDK#loadMetadata|loadMetadata]] and  [[DCR_Video_APP_SDK#playheadPosition|playheadPosition]].</blockquote>


=== Sequence of Calls ===
=== Sequence of Calls ===
Line 478: Line 480:
When content stop is initiated and content cannot be resumed from the same position (it can only be restarted from the beginning of stream).
When content stop is initiated and content cannot be resumed from the same position (it can only be restarted from the beginning of stream).
{{ExampleCode|
{{ExampleCode|
|Objective C = <syntaxhighlight lang="objective-c">- (void) end;</syntaxhighlight>
|Objective C = <syntaxhighlight lang="objective-c">- (void) end {
|Android = <syntaxhighlight lang="java">public void stop()</syntaxhighlight>
// Nielsen End Measurement
|Swift = <syntaxhighlight lang="swift">self.nielsenAppApi?.stop</syntaxhighlight>
[self.nielsenAppApi end];
}</syntaxhighlight>
|Android = <syntaxhighlight lang="java">public void end(){
// Nielsen End Measurement
mAppSdk.end()
}
</syntaxhighlight>
|Swift = <syntaxhighlight lang="swift">
func end() {
// Nielsen End Measurement
self.nielsenAppApi?.end()
}
</syntaxhighlight>
}}
}}


Line 616: Line 630:


== Going Live ==
== Going Live ==
Once the DCR Tracking Code is added to Instant Articles, Nielsen will validate the implementation. Following Nielsen testing, users need to make one update to the initialization call to ensure that the site is being measured properly.
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.
# '''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:<syntaxhighlight lang="javascript">var nSdkInstance = NOLBUNDLE.nlsQ("PXXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX", "nlsnInstance");</syntaxhighlight>
#* '''Example Production Initialization Call''' - Refer to the production initialization call below:


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

Latest revision as of 01:40, 10 September 2020

Engineering Portal / Digital / International DCR / DCR Italy Video App SDK

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.

Prerequisites

To start using the App SDK, the following details are required:

  • App ID (appid): Unique ID assigned to the player/site and configured by product.
  • sfcode: Unique identifier for the environment that the SDK should point to.
  • Nielsen SDK: The Nielsen SDK package contains a variety of sample players for your reference.

If you do not have any of these prerequisites or if you have any questions, please contact our SDK sales support team. Refer to Digital Measurement Onboarding guide for information on how to get a Nielsen App SDK and appid.

Implementation

This guide covers implementation steps for iOS using Xcode and Android using Android Studio.

Setting up your Development Environment

xCode

Configuring Xcode Development Environment

Nielsen App SDK is compatible with Apple iOS versions 9.0 and above.

The SDK uses the NSURLSession instead of the deprecated NSURLConnection.

Note: All communications between the SDK and the Census (Collection Facility) use HTTPS.

Importing Frameworks The first step is to ensure that the following frameworks and libraries are imported into the Frameworks folder of the Xcode project before creating an instance of the Nielsen App SDK object.

  • UIKit.framework
  • Foundation.framework
  • AdSupport.framework
  • SystemConfiguration.framework
  • Security.framework
    • Nielsen Analytics framework makes use of a number of functions in this library.
  • AVFoundation.framework
    • This framework is mandatory for the iOS SDK version 5.1.1 to work.
  • CoreLocation.framework
  • CoreMedia.framework
  • NielsenAppApi.framework
  • libc++.tbd (as SDK contains Objective C++ source file)
    • Alternatively, include -lstdc++ in Build Settings → Other Linker Flag of the Xcode project

Example

  • Extract “NielsenAppApi.Framework” from the Nielsen App SDK sample app and copy it to Frameworks folder of the Xcode project.
  • Add the code -#import NielsenAppApi/NielsenAppApi.h to the View Controller’s header file.

Ensure that the following are included in the Linked Frameworks and Libraries list (located in the project’s Summary settings).

  • Nielsen App SDK
  • iOS security framework


Using Swift To import a set of Objective-C files in the same app target as your Swift code, you rely on an Objective-C bridging header to expose those files to Swift. Xcode offers to create this header file when you add a Swift file to an existing Objective-C app, or an Objective-C file to an existing Swift app.

Select File/New File/Objective-C File
Xcode will prompt you to create a bridging header.

bridgingheader 2x.png

Once this file has been created, you need to add the following:

#import <NielsenAppApi/NielsenAppApi.h>

Using Objective-C Add the code

#import <NielsenAppApi/NielsenAppApi.h>

to the View Controller’s header file.


Java

Configuring Android Development Environment'

  • The Nielsen App SDK (located in the com.nielsen.app.sdk package) class is the primary application interface to the Nielsen App SDK on Android.
  • The Nielsen App SDK class is defined as the only public class belonging to the com.nielsen.app.sdk package.

Nielsen App SDK is compatible with Android OS versions 2.3+. Clients can control / configure the protocol to be used – HTTPS or HTTP to suit their needs.

The Nielsen App SDK 1.2 library is composed of two parts:

  • The Java AppSdk.jar library that runs on the Android’s Dalvik Virtual Machine.
  • The C/C++ libAppSdk.so native library that runs directly on the device’s hardware.

Note: App SDK 4.0.0 contains AppSDK.jar component only and does not support C/C++ libAppSdk.so components.

The requirement for the Java AppSdk.jar library and the libAppSdk.so native library will depend on the type of host application that will make use of them.

  • For Video player applications
    • The Android OS hosting the App SDK should use a media player supporting HLS streaming (Android 3.0 and later will support it natively).
    • If the player application uses a 3rd party media player implementing its own HLS, then the minimum Android version will be limited to version 2.3, since the SDK depends on Google Play support to work properly.
  • For Audio player applications
    • The Android OS hosting the App SDK should be at version 2.3 and later since the SDK depends on the Google Play support to work properly.

Ensure to unzip the Nielsen App SDK sample app and copy the AppSdk.jar into the libs/ folder on the App’s Eclipse project. Copy the libAppSdk.so file under libs/armeabi/ folder into the same Eclipse project.

  • App SDK 1.2 provides support for x86, mips, and armeabi-7a architecture; the respective libAppSdk.so can be found under the libs/x86/, libs/mips/, and libs/armeabi-7a/ folders.

Add the following permissions on the project’s AndroidManifest.xml file.

<uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" android:required="false" />
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE"/>
<uses-permission android:name="android.permission.INTERNET"/>

For more details to handle runtime permissions in Android versions, please visit [1]. Download the latest google-play-services_lib and include it in the App’s project in order to use the App SDK.

  • App SDK checks to see if there is a Google service available and updated.
  • If not available or updated, App SDK will not use this service when executing its functions and will make reference to missing imports and the app will not be compiled.

To include the Google Play library in the media player project, copy the google-play-services_lib folder into the same location as the project

  • Access File > Import.
  • Select Existing Android Code into Workspace and click Next.
  • Click Browse and navigate to the google-play-services_lib to include it into the projects.
  • Select the exact Project Build Target for Eclipse to use from Android SDK.
    • Android 4.4.2, etc. OR
    • Edit project.properties file to point to Android target version e.g. target= android-19.

Once the google-play-services_lib is included into the App project, include the following code under the <application> node in the AndroidManifest.xml.

<meta-data android:name="com.google.android.gms.version" android:value="@integer/google_play_services_version"/>

Also, include the version.xml file that comes with the google-play-services_lib under the res/values directory of the media player project.

  • Once the files are in place, import com.nielsen.app.sdk to the java source code and start accessing the public interface.


Library

Nielsen App SDK uses the following packages/classes from the Google Play service.

  • google-play-services_lib

Classes/package

  • com.google.android.gms.ads.identifier.AdvertisingIdClient;
  • com.google.android.gms.ads.identifier.AdvertisingIdClient.Info;
  • com.google.android.gms.common.ConnectionResult;
  • com.google.android.gms.common.GooglePlayServicesUtil;
  • com.google.android.gms.common.GooglePlayServicesRepairableException;
  • com.google.android.gms.common.GooglePlayServicesNotAvailableException;

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)

  • 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? Example
appid Unique id for the application assigned by Nielsen. It is GUID data type. Nielsen-specified Yes 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.

Italian Clients

  • "it"
Nielsen-specified Yes "it"
nol_devDebug Enables Nielsen console logging. Only required for testing Nielsen-specified Optional "DEBUG"


Sample SDK Initialization Code

Swift

Swift 4.0 Example: NielsenInit.swift

class NielsenInit: NSObject {
    class func createNielsenAppApi(delegate: NielsenAppApiDelegate) -> NielsenAppApi?{
    let appInformation:[String: String] = [
           "appid": "PDA7D5EE6-B1B8-XXXX-XXXX-2A788BCXXXCA",
            "appversion": "1.0",
            "appname": "app name here",
            "sfcode": "it",
            "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",
                                     @"appversion": "1.0",
                                     @"appname": "app name here",
                                     @"sfcode": "it",
                                     @"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

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("appversion", "1.0")
          .put("appname", "Sample App Name")
          .put("sfcode", "it")
          .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, 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 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).

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.

Configure Payload

Handling JSON Metadata

All the SDK methods handles only two types of objects: NSString, NSDictionary. The parameters passed must be either a JSON formatted string or a NSDictionary object. The JSON passed in the SDK must be well-formed.

  • NSDictionary object
    • If an object of unexpected type is passed to the method, the error message will be logged.
    • If string has invalid JSON format, the error message will be logged.
  • JSON value must be string value.
    • This includes boolean and numeric values. For example, a value of true should be represented with "true", number value 123 should be "123".
    • All the Variable Names like appid, appname, sfcode, dataSrc, title, type etc. are case-sensitive. Use the correct variable name as specified in the documentation.
  • JSON string can be prepared using either raw NSString or serialized NSDictionary.

Swift

       let channelInfo = [
            "channelName": "My Channel Name 1",
];
        
        let contentMetadata = [
                "type": "content",
                "assetid": "88675545",
                "title": "Program S3, EP1",
                "isfullepisode":"n",
                "adloadtype":"2",
                "program":"Program Name",
                "length":"3600", 
                "airdate":"20171020 10:05:00"
];

Objective C

 
NSDictionary  *channelInfo = @
{
  @"channelName":@"My Channel Name 1",
}

NSDictionary *contentMetadata = @
  {@"type": @"content",
  @"assetid": [NSString stringWithFormat:@"ProgramAssetId-%d", i],
  @"length": @"3600",
  @"program", "Program Name",
  @"title": @"Program S3, EP1",
  @"isfullepisode": @"y",
  @"adloadtype": "2",
  @"airdate": "20161013 20:00:00"
}

Java

JSONObject channelInfo = new JSONObject()
    .put("channelname","My Channel Name 1")

JSONObject contentMetadata = new JSONObject()
//SDK Metadata
    .put("type", "content")
    .put("assetid", "vid345-67483")
    .put("program", "Program Name")
    .put("title", "Program S3, EP1")
    .put("length", "3600")
    .put("isfullepisode", "y")
    .put("adloadtype", "2")
    .put("airdate", "20161013 20:00:00")

Configure metadata

Configure metadata should remain constant throughout the completion of an episode or live stream.

Key Description Values Required
channelName Any string representing the channel/stream custom


Content metadata

Content metadata should remain constant throughout the entirety of an episode/clip including when ads play.

Keys Description Values Required
type type of asset "content" Yes
assetid unique ID assigned to asset (32 Character limit) custom Yes
program name of program (100 character limit) custom Yes
title name of program (100 character limit) custom Yes
length length of content in seconds seconds (0 for live stream) Yes
airdate the airdate in the linear TV YYYYMMDD HH24:MI:SS Yes
isfullepisode full episode flag "y"- full episode, "n"- non full episode Yes
adloadtype type of ad load:

"1" Linear – matches TV ad load

"2" Dynamic – Dynamic Ad Insertion (DAI)

"2" - DCR measures content with dynamic ads Yes


Ad Metadata

The ad metadata (if applicable) should be passed for each individual ad, if ads are available during or before the stream begins.

Keys Description Values Required
type type of ad 'preroll', 'midroll', or 'postroll'
assetid unique ID assigned to ad custom

Configure API Calls

Sample API Sequence

A Sample API sequence could follow this flow:

Type Sample code Description
On App Start [nielsenMeter loadMetadata: contentMetadata]; // contentMetadata Object contains the JSON metadata for the impression
Start of stream [nielsenMeter play: channelName]; // channelName contains JSON metadata of channel/video name being played
[nielsenMeter loadMetadata: contentMetadataObject]; // contentMetadataObject contains the JSON metadata for the content being played
Content [nielsenMeter playheadPosition: position]; // playheadPosition is position of the playhead while the content is being played
End of Stream [nielsenMeter end]; // Content playback is completed.

Life cycle of SDK instance

Life cycle of SDK instance includes four general states:

  1. Initial state – The SDK is not initialized and hence, not ready to process playing information. Once the SDK is moved out of this state, it needs instantiation of the new SDK instance in order to get the instance in the Initial state.
  2. Idle state – The SDK is initialized and is ready to process playing information. Once Initialized, the SDK instance is not processing any data, but is listening for the play event to occur.
  3. Processing state – The SDK instance is processing playing information. play and loadMetadata calls move the SDK instance into this state. In this state, the SDK instance will be able to process the following calls.
    1. playheadPosition – Call this API every one second when playhead position timer is fired.
    2. stop – Call this API when the playback is paused, switches between content and ad (within the same content playback) or encounters interruptions.
    3. end – SDK instance exits from Processing state when this API is called.
  4. Disabled state – The SDK instance is disabled and is not processing playing information. SDK instance moves into this state in one of the following scenarios.
    1. Initialization fails
    2. appDisableApi is called
@property (assign) BOOL appDisableApi;

Note: For API Version 5.1 and above, App SDK will fire data pings and continue measurement even after the user has opted out from Nielsen measurement on a device. The data ping will be marked as opted-out ping.

Note: In case of any interruptions during playback due to alarm, calendar, call, flight mode, Wi-Fi toggle, channel change, etc., call stop to stop the measurement.

Sequence of Calls

play

Use play to pass the channel descriptor information through channelName parameter when the user taps the Play button on the player.

Swift

nielsenAppApi?.play(JSONObject channelInfo);

Objective C

   [nielsenAppApi play:(JSONObject channelInfo)];

Java

    public void play(JSONObject channelInfo);

loadMetadata

Swift

self.nielsenAppApi?.loadMetadata(contentMetadata)

Objective C

 (void)loadMetadata:(id)contentMetadata;

Java

public void loadMetadata(JSONObject contentMetadata);

playheadPosition

Swift

        //Monitor the Playhead position of the AVPlayer
        let timeInterval: CMTime = CMTimeMakeWithSeconds(1.0,10)
        self.avPlayerViewController.player?.addPeriodicTimeObserver(forInterval: timeInterval, queue: DispatchQueue.main) {(elapsedTime: CMTime) -> Void in
            if self.avPlayerViewController.player!.currentItem?.status == .readyToPlay {
                let time : Float64 = self.avPlayerViewController.player!.currentTime().seconds;
                let pos = Int64(time);
                NSLog("New Elapse Time = \(time)");
                self.nielsenAppApi?.playheadPosition(pos);
            }
        }
    }

Objective C

 (void) playheadPosition: (long long) playheadPos

Sending playheadposition for content

AVPlayer *player;
CMTime curTime=[player currentTime];
int pos = CMTimeGetSeconds(curTime);
[nAppApiObject playheadPosition:pos];

Java

public void setPlayheadPosition(long position)

stop

Swift

self.nielsenAppApi?.stop

Objective C

 (void) stop

Java

public void stop()

end

When content stop is initiated and content cannot be resumed from the same position (it can only be restarted from the beginning of stream).

Swift

func end() {
// Nielsen End Measurement
self.nielsenAppApi?.end()
}

Objective C

- (void) end {
// Nielsen End Measurement
[self.nielsenAppApi end];
}

Java

public void end(){
 // Nielsen End Measurement
 mAppSdk.end()
}

Privacy and Opt-Out

iOS

iOS Opt-Out Implementation

To opt out, users must have access to "About Nielsen Measurement" page. User can click this page from app settings screen.

Include About Nielsen Measurement and Your Choices link in the Privacy Policy / EULA or as a button near the link to the app's Privacy Policy.

  • URL for the Nielsen Privacy web page should be retrieved from the optOutURL property of the SDK object optOutURL and opened in 'WebView' / External browser.
  • If the App SDK returns NULL in the optOutURL, handle the exception gracefully and retry later.
  • To retrieve the current Opt-Out status of a device, use the optOutStatus method.


The app must provide access to "About Nielsen Measurement" page for the users. Include "About Nielsen Measurement" and Your Choices link in the Privacy Policy / EULA or as a button near the link to the app's Privacy Policy.

Privacy policy iOS.jpg

  • URL to this web page should be called from SDK and opened in 'WebView' / External browser.
  • If the App SDK returns NULL as Opt-Out URL, handle this case and retry later.
  • To retrieve the current Opt-Out status, use the optOutStatus property from Nielsen's SDK API.
@property (readonly) BOOL optOutStatus;
  • App should provide a UI control like 'close' or 'back' button to close the 'WebView' / External browser.


Users can opt out or opt back into Nielsen Measurement. Opt-Out feature relies on iOS' system setting – "Limit Ad Tracking". The setting can be accessed in the Settings application on any iOS device: Settings → Privacy → Advertising → Limit Ad Tracking.

User is opted out of Nielsen online measurement research when the "Limit Ad Tracking" setting is enabled.

Opt-Out iOS.jpg

Note: For API Version 5.1 and above, App SDK will fire data pings and continue measurement even after the user has opted out from Nielsen measurement on a device. The data ping will be marked as opted-out ping.



Java

Android Opt-Out Implementation

To opt out, users must have access to "About Nielsen Measurement" page. User can click this page from app settings screen.

Include About Nielsen Measurement and Your Choices link in the Privacy Policy / EULA or as a button near the link to the app's Privacy Policy.

  • URL to this web page should be called from SDK by invoking userOptOutURLString() and opened in 'WebView' / External browser.
public String userOptOutURLString()
  • If the App SDK returns NULL as Opt-Out URL, handle the exception gracefully and retry later.
  • To retrieve the current Opt-Out status of a device, use the getOptOutStatus() method.
public boolean getOptOutStatus()

Displaying Opt-Out in a WebView

optOutUrl = mAppSdk.userOptOutURLString();
if(optOutUrl !=null)
{
   mWebView = (WebView) findViewById(R.id.webView);
   mWebView.getSettings().setJavaScriptEnabled(true);
   mWebView.getSettings().setBuiltInZoomControls(true);
   mWebView.getSettings().setDisplayZoomControls(false);
   mWebView.getSettings().setLoadWithOverviewMode(true);
   mWebView.getSettings().setUseWideViewPort(true);
   mWebView.setWebViewClient(new MonitorWebView());
   mWebView.setWebChromeClient(new WebChromeClient());
   mWebView.loadUrl(optOutUrl);
}
else
{
   //Handle it gracefully and Retry later
}


The app must provide access to "About Nielsen Measurement" page for the users. Include "About Nielsen Measurement" and Your Choices link in the Privacy Policy / EULA or as a button near the link to the app's Privacy Policy.

Privacy policy iOS.jpg

Note: When ‘WebView’ / External browser is closed, do not pass the status returned from ‘WebView’ / External browser to the SDK within the app, as the new Opt-Out page will not return any response.

Note: App SDK manages the user’s choice (Opt-Out / Opt-In), the app does not need to manage this status.

Starting from SDK version 5.1.1.18:

  • SDK will be sending the data pings to census even though SDK is opted out (In earlier releases all the traffic from SDK to census will be ceased). However, all the outgoing pings will have the parameter uoo=true using which backend can ignore this data.
  • Current Opt-Out page is now updated to have no hyperlinks for Opt-Out / Opt-In operations. SDK Opt-Out has to be done via

Google Settings → Ads → Opt out of Ads Personalization.

Note: For Amazon devices, see Opt-Out Implementation for Amazon Devices below.

andr-ads.jpg

Note: The App SDK will fire data pings and continue measurement even after the user has opted out from Nielsen measurement on a device. The data ping will be marked as opted-out ping.

Opt-Out Implementation for Amazon Devices

Amazon device users can opt out or opt back into Nielsen Measurement, any time using the device’s setting – 'Limit Ad Tracking' (Interest-based ads).

User is opted out of Nielsen Online Measurement when ‘Limit Ad Tracking’ is enabled.


For devices running on Fire OS 5.1 and above, retrieve the Ad tracking value.

Retrieving Ad tracking Value

ContentResolver cr = getContentResolver();
int limitAdTracking = Secure.getInt(cr, "limit_ad_tracking", 2);
  • Returns limit_ad_tracking value "0" if enabled
  • Returns limit_ad_tracking value "1" if disabled
  • Returns limit_ad_tracking value "2" if ad tracking is not supported (below Fire OS 5.1).

Note: Google Play Services are not needed to retrieve ad tracking state on Amazon devices. Limit Ad Tracking can be accessed through Settings → Apps & Games → Advertising ID.

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": "it"
            // 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", "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);
}