DCR & DTVR Xamarin Integration

From Engineering Client Portal

Revision as of 03:32, 19 November 2020 by ColinBrown (talk | contribs)

Engineering Portal breadcrumbArrow.png Digital breadcrumbArrow.png US DCR & DTVR breadcrumbArrow.png DCR & DTVR Xamarin Integration

Related Topics :
Integrate Nielsen SDK Simplified Api in Xamarin App

Integrate Nielsen SDK Legacy Api in Xamarin App

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), and Digital Ad Ratings (DAR). 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.

This guide will show how to use the Nielsen SDK in Xamarin applications on Android and iOS devices. We will not go into detail about what Xamarin is or how to create Apps with this Framework. If you are looking for information on this, please read the Xamarin documentation.

Note : Support for Xamarin in Nielsen SDK is available from version 8.0.0.0

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.

For more detail on the native SDKs please refer to the App integration guides available on this portal.

Implementation

This guide covers implementation covers

  • the details of integration of Nielsen SDK library into Xamarin app for iOS and Android platforms
  • the usage of the Nielsen SDK legacy API

What we will not cover is the general setup of Xamarin applications. If you are new to Xamarin please refer to Xamarin for documentation.

For simplicity we have focused on implementing a single instance of the Nielsen SDK. Should there be the need for multiple instances developers have to add some logic for that.

Setting up your Environment


Nielsen SDK is distributed is the form of .dll library for Xamarin. The first step is to copy NielsenIOSSDK.dll [or] NielsenAndroidSDK.dll into some folder inside of the respective platform (iOS/Android) Xamarin app folder on a filesystem a make a reference to this .dll in the iOS/Android target:


   iOS


Link

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


   Android


Link

Nielsen's App SDK is compatible with Android SDK version 4.0 and above.


Nielsen Xamarin library APIs

Nielsen SDK is initially a native framework for iOS and Android platforms. For Xamarin it is distributed as the .dll library that exports all the APIs from the native framework. Please refer to the integration guides for Nielsens native SDKs to get a deeper understanding of the technical detail.

   iOS

Nielsen iOS Xamarin library has bindings to the native Objective C Nielsen iOS dynamic framework. All the details about the Nielsen iOS SDK API could be found on engineering portal page for iOS app developers. It is fully applicable for Xamarin applications. Legacy API for the native Objective C library contains one main class NielsenAppApi and a protocol NielsenAppApiDelegate that is used to get updates about events and errors occurred in the Nielsen SDK library.

The table below describes the binding from the native library Objective C calls to C#.

   NielsenAppApi
Objective C API C# API Description
- (instancetype)initWithAppInfo:(id)appInfo 
delegate:(id<NielsenAppApiDelegate>)delegate;
[Export ("initWithAppInfo:delegate:")]public NielsenAppApi (NSObject appInfo, 
NielsenAppApiDelegate @delegate): base (NSObjectFlag.Empty);
Used to create a new instance of the SDK object
- (void)play:(id)channelInfo;
[Export ("play:")]public virtual void Play (NSObject channelInfo);
Used when there is an ID3 fed product such as DTVR and the client does not want to send in all the CMS metadata that is sent in loadMetadata. 
- (void)loadMetadata:(id)metadata;
[Export ("loadMetadata:")]public virtual void LoadMetadata (NSObject metadata);
Used to send ad or content metadata to the SDK
- (void)sendID3:(NSString *)data;
[Export ("sendID3:")]public virtual void SendID3 (string data);
Used to send the ID3 metadata.
- (void)playheadPosition:(long long)playheadPos;
[Export ("playheadPosition:")]public virtual void PlayheadPosition (long playheadPos);
Used to send the playhead position.
- (void)stop;
[Export ("stop")]public virtual void Stop ();
Used when playback is paused
- (void)end;
[Export ("end")]public virtual void End ();
Used when content playback is complete
- (void)updateOTT:(id)ottInfo;
[Export ("updateOTT:")]public virtual void UpdateOTT (NSObject ottInfo);
Used to notify App SDK that the remote OTT device (like Google ChromeCast, Roku, Amazon FireTV, etc.) is connected / disconnected (change of OTT status).
@property (readonly) NSString *optOutURL;
public virtual string OptOutURL
{
    [Export ("optOutURL")]get;}
Used to fetch the Nielsen opt-out web page URL.
- (BOOL)userOptOut:(NSString *)optOut;
[Export ("userOptOut:")]public virtual bool UserOptOut (string optOut);
Used to supply the response message from opt-out webpage to the SDK.
@property (readonly) BOOL optOutStatus;
public virtual bool OptOutStatus
{
    [Export ("optOutStatus")]
    get;}
Used to retrieve the Opt-Out or Opt-In state.
@property (assign) BOOL appDisableApi;
public virtual bool AppDisableApi
{    [Export ("appDisableApi")]get;    [Export ("setAppDisableApi:")]set;}
Used to disable the SDK.
@property (readonly) NSDictionary *lastErrorDict;
public virtual NSDictionary LastErrorDict
{    [Export ("lastErrorDict")]get;}
Returns SDK error in the form of dictionary if any error has occurred.
@property (readonly) NSDictionary *lastEventDict;
public virtual NSDictionary LastEventDict
{    [Export ("lastEventDict")]get;}
Returns SDK event in the form of dictionary if any event has occurred.
@property (readonly) NSString *meterVersion;
public virtual string MeterVersion
{    [Export ("meterVersion")]get;}
Returns the current SDK version.
@property (readonly) NSString *nielsenId;
public virtual string NielsenId
{    [Export ("nielsenId")]get;}
Used to get a string defining the Nielsen ID (NUID) number for the device.
@property (readonly) NSString *demographicId;
public virtual string DemographicId
{    [Export ("demographicId")]get;}
Used to retrieve Demographic ID (Device ID) of the current device.
@property (readonly) NSString *vendorId;
public virtual string VendorId
{    [Export ("vendorId")]get;}
Used to retrieve Vendor ID.
@property (readonly) NSString *firstPartyId;
public virtual string FirstPartyId
{    [Export ("firstPartyId")]get;}
Used to retrieve First Party ID.
@property (assign) BOOL debug;
public virtual bool Debug
{    [Export ("debug")]get;    [Export ("setDebug:")]set;}
Used to enable/disable debug flags
   NielsenAppApiDelegate
Objective C API C# API Description
- (void)nielsenAppApi:(NielsenAppApi *)appApi
errorOccurred:(NSDictionary *)error;
[Export ("nielsenAppApi:errorOccurred:")]public virtual void ErrorOccurred
(NielsenAppApi appApi, NSDictionary error);
Notifies about the last error that occurred
- (void)nielsenAppApi:(NielsenAppApi *)appApi
eventOccurred:(NSDictionary *)event;
 [Export ("nielsenAppApi:eventOccurred:")]public virtual void EventOccurred
(NielsenAppApi appApi, NSDictionary @event);
Notifies about the last event that occurred


   Android

Nielsen Android Xamarin library has bindings to the native Java Nielsen Android Jar. All the details about the Nielsen Android SDK API could be found on engineering portal page for Android app developers. It is fully applicable for Xamarin applications. Legacy API for the native Java library contains one main class AppSdk and an interface IAppNotifier that is used to get updates about events and errors occurred in the Nielsen SDK library.

The table below describes the binding from the native library Java calls to C#.

   AppSdk
Java API C# API Description
public AppSdk(Context context, JSONObject appInfo, 
IAppNotifier notifier);
public unsafe AppSdk (Context context, JSONObject appInfo, 
IAppNotifier notifier) : base (IntPtr.Zero, 
JniHandleOwnership.DoNotTransfer);
Used to create a new instance of the SDK object
public void play(JSONObject channelInfo);
public unsafe virtual void Play (JSONObject channelInfo);
Used when there is an ID3 fed product such as DTVR and the client does not want to send in all the CMS metadata that is sent in loadMetadata. 
public void loadMetadata(JSONObject jsonMetadata);
public unsafe virtual void LoadMetadata (JSONObject jsonMetadata);
Used to send ad or content metadata to the SDK
public void sendID3(String payload);
public unsafe virtual void SendID3 (string payload);
Used to send the ID3 metadata.
public void setPlayheadPosition(long position);
public unsafe virtual void SetPlayheadPosition (long position);
Used to send the playhead position.
public void stop();
public virtual void Stop ();
Used when playback is paused
public void end();
public virtual void End ();
Used when content playback is complete
public void updateOTT(JSONObject ottInfo);
public unsafe virtual void UpdateOTT (JSONObject ottInfo);
Used to notify App SDK that the remote OTT device (like Google ChromeCast, Roku, Amazon FireTV, etc.) is connected / disconnected (change of OTT status).
public String userOptOutURLString();
public virtual string UserOptOutURLString ();
Used to fetch the Nielsen opt-out web page URL.
public boolean userOptOut(String optOut);
public unsafe virtual bool UserOptOut (string optOut);
Used to supply the response message from opt-out webpage to the SDK.
public boolean getOptOutStatus();
public virtual bool OptOutStatus
{
    [Register ("getOptOutStatus", "()Z", 
    "GetGetOptOutStatusHandler")]
    get;}
Used to retrieve the Opt-Out or Opt-In state. Note: This method must not be called from main/ui thread as it will turn up to be a blocking call.
public void appDisableApi(boolean disabled);
public unsafe virtual void AppDisableApi (bool disabled);
Used to disable the SDK.
public String getLastError();
public virtual string LastError
{    [Register ("getLastError", "()Ljava/lang/String;", 
    "GetGetLastErrorHandler")]
    get;}
Returns SDK error in the form of string if any error has occurred.
public String getLastEvent();
public virtual string LastEvent
{    [Register ("getLastEvent", "()Ljava/lang/String;", 
    "GetGetLastEventHandler")]
    get;}
Returns SDK event in the form of string if any event has occurred.
public static String getMeterVersion();
public static string MeterVersion
{    [Register ("getMeterVersion", "()Ljava/lang/String;", "")]
    get;}
Returns the current SDK version.
public String getNielsenId();
public virtual string NielsenId
{    [Register ("getNielsenId", "()Ljava/lang/String;", 
    "GetGetNielsenIdHandler")]
    get;}
Used to get a string defining the Nielsen ID (NUID) number for the device. Note: Please make sure that you call this method on worker thread but not on main/ui thread.
public String getDemographicId();
public virtual string DemographicId
{    [Register ("getDemographicId", "()Ljava/lang/String;", 
    "GetGetDemographicIdHandler")]
    get;}
Used to retrieve Demographic ID (Device ID) of the current device. Note: Please make sure that you call this method on worker thread but not on main/ui thread.
public String getFirstPartyId();
public virtual string FirstPartyId
{    [Register ("getFirstPartyId", "()Ljava/lang/String;", 
    "GetGetFirstPartyIdHandler")]
    get;}
Returns First Party Id for this instance if available otherwise blank
public String getVendorId();
public virtual string VendorId
{    [Register ("getVendorId", "()Ljava/lang/String;", 
    "GetGetVendorIdHandler")]
    get;}
Returns Vendor Id if available otherwise blank
public static void setDebug(char debugState);
public unsafe static void SetDebug (char debugState);
Used to enable/disable debug flags
   IAppNotifier
Java API C# API Description
public void onAppSdkEvent(long timestamp, int code, String description);
void OnAppSdkEvent (long p0, int p1, string p2);
Method called whenever an event is to be reported from the App SDK


Library common interface

Nielsen SDK APIs are similar for both platforms iOS and Android. For cross platforms Xamarin applications it could be convenient to create a single interface than will be used in the common code of the Xamarin app. Please use our Xamarin sample application code as a reference.

public interface INielsenAnalytics
{
    // construct SDK
    void CreateNativeSDK();

    // static reporting
    void StaticForSection(string sectionName);

    // video reporting
    void PlayWithChannelName(string channelName, string mediaURL);
    void ContentMetadataWithChannelName(string channelName);
    void PlayheadPosition(long pos);
    void SendID3(string id3Data);
    void Stop();
    void End();

    // optout
    bool Optout(string command);

    // additional properties
    string Version { get; }
    string DemoId { get; }
    string VendorId { get; }
    string FirstPartyId { get; }
    string OptoutURL { get; }
    bool OptoutStatus { get; }
    bool MeterOn { get; set; }
}


While creating a Xamarin app instance the proper platform based implementation is provided as part of App constructor parameter:

App.xaml.cs
public partial class App : Application
{
    public static INielsenAnalytics NielsenAnalytics { get; private set; }

    public App(INielsenAnalytics nielsenAnalyticsImpl)
    {
        InitializeComponent();

        App.NielsenAnalytics = nielsenAnalyticsImpl;
        MainPage = new NavigationPage(new HomePage());
    }
}


Instance of platform specific interface implementation to be created before creating an App

   iOS
AppDelegate.cs
public partial class AppDelegate : global::Xamarin.Forms.Platform.iOS.FormsApplicationDelegate
{
    // This method is invoked when the application has loaded and is ready to run. In this 
    // method you should instantiate the window, load the UI into it and then make the window
    // visible.

    public override bool FinishedLaunching(UIApplication app, NSDictionary options)
    {
        global::Xamarin.Forms.Forms.Init();
        LoadApplication(new App(new iOSNielsenAnalytics()));

        return base.FinishedLaunching(app, options);
    }
}


   Android
MainActivity.cs
public class MainActivity : global::Xamarin.Forms.Platform.Android.FormsAppCompatActivity
{
    protected override void OnCreate(Bundle bundle)
    {
        base.OnCreate(bundle);

        TabLayoutResource = Resource.Layout.Tabbar;
        ToolbarResource = Resource.Layout.Toolbar;

        global::Xamarin.Forms.Forms.Init(this, bundle);

        LoadApplication(new App(new AndroidNielsenAnalytics(base.ApplicationContext)));
    }
}




Platform-based implementation of this interface can be done in the platform specific code.

   iOS
public class iOSNielsenAnalytics : INielsenAnalytics
{
    public iOSNielsenAnalytics()
    {
    }

    public void CreateNativeSDK()
    {
        
    }

    
}


   Android
public class AndroidNielsenAnalytics : INielsenAnalytics
{
    
    public AndroidNielsenAnalytics(Context context)
    {
        ...
    }

    public void CreateNativeSDK()
    {
        ...
    }

    ...
}




Please note that this common interface is created just as a reference. Please extend the methods to provide more parameters into the API calls (like parameter “length” in metadata) or use a different approach if such interface does follow your application design and architecture.

SDK Initialization

Xamarin sample application creates and uses one single instance of Nielsen App SDK. This instance is created immediately on application launch and accessed using a reference to the main App object. This approach is used in order to simplify the referenced code. The latest version of the Nielsen App SDK allows instantiating multiple instances of the SDK object, which can be used simultaneously without any issue. In the real applications please create as many instances as needed according to the application architecture. It could be required to use different instances for different products like DCR Static and DCR Video. For more information on this please read the relevant App SDK Guide.

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 While not live "DEBUG"

Sample SDK Initialization Code

NielsenAppApi library supports multiple SDK instance creation and operations.

   iOS

Xamarin sample application uses Newtonsoft.Json.Linq module to create NSString objects with JSON.

This method implements CreateNativeSDK defined in INielsenAnalytics above.

public class iOSNielsenAnalytics : INielsenAnalytics
{
    private NielsenAppApi appApiLegacy;
    private AppApiDelegate appApiDelegate;

    public void CreateNativeSDK()
    {
        JObject appInfo = new JObject {
            { "appid", "PXXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX"},
            { "nol_devDebug", "DEBUG" }
        };

        NSObject appInfoObj = NSObject.FromObject(appInfo.ToString());
        appApiDelegate = new AppApiDelegate();
        appApiLegacy = new NielsenAppApi(appInfoObj, appApiDelegate);
    }
}


Nielsen App SDK initialiser needs an instance of a delegate class to be provided as a second parameter. This additional class needs to be inherited from NielsenAppApiDelegate and implement ErrorOccurred and EventOccurred API methods.

private class AppApiDelegate : NielsenAppApiDelegate
{
    public AppApiDelegate()
    {
    }

    public override void ErrorOccurred(NielsenAppApi appApi, NSDictionary error)
    {
        Console.WriteLine(error.ToString());
    }

    public override void EventOccurred(NielsenAppApi appApi, NSDictionary @event)
    {
        Console.WriteLine(@event.ToString());
    }
}


   Android

This class implements CreateNativeSDK defined in INielsenAnalytics above.

public class AndroidNielsenAnalytics : INielsenAnalytics
{   
    private AppSdk appSDK;

    private IAppNotifier iAppNotifierImpl;

    public void CreateNativeSDK()
    {
        JSONObject appInfo = new JSONObject()
                .Put("appid", "PXXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX")
                .Put("nol_devDebug", "DEBUG");

        iAppNotifierImpl = new AppNotifierImpl();        

        appSDK = new AppSdk(context, appInfo, iAppNotifierImpl);
    }
}


Nielsen App SDK initialiser needs an instance of a delegate class to be provided as a second parameter. This additional class needs to be implemented from IAppNotifier interface thereby implementing OnAppSdkEvent API method.

private class AppNotifierImpl : IAppNotifier
{
        public void OnAppSdkEvent(long timestamp, int code, string description)
        {
            Console.WriteLine("OnAppSdkEvent => " + description);
        }
}


SDK Instance Removal

It is allowed to create and use multiple instances of the Nielsen App SDK. But sometimes it's also important to remove the SDK instance once we are done with it.

   iOS

Xamarin.iOS has a garbage collector that will take care of releasing resources for you when they are no longer in use. In addition to the garbage collector, all objects that derive from NSObject implement the System.IDisposable interface. You can call Dispose() to immediately release NielsenAppApi object, instead of waiting for Mono to perform a garbage collection cycle. When a managed object is disposed, it is no longer useful. You might still have a reference to the objects, but the object is for all intents and purposes invalid at this point.

If you do not keep a reference in your static or instance variables to your objects, Mono will happily call the Dispose() method on them, and they will release the reference to the object. Since this might be the only outstanding reference, the Objective-C runtime will destroy the object for you.

   Android
In Android AppSDK, we have a method -
 public virtual void Close ();
which disposes and frees all resources taken by the corresponding AppSdk object.

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.

Interaction with APP SDK

Configure Payload

For iOS all metadata is passed to the SDK as string objects with data in JSON format. In the sample app Newtonsoft.Json.Linq module is used to create NSString objects with JSON using JObjects. Android sample code uses JObjects directly.

   iOS
JObject contentMetadataJObj = new JObject {
    { "title", channelName },
    { "adloadtype", "2" },
    { "type", "content" },
    { "assetid", channelName },
    { "length", "1600" }
};

NSObject contentMetadata = NSObject.FromObject(contentMetadataJObj.ToString());
appApiLegacy.LoadMetadata(contentMetadata);


   Android
JSONObject contentMetadata = new JSONObject()
    .Put("title", channelName)
    .Put("adloadtype", "2")
    .Put("assetid", channelName)
    .Put("type", "content")
    .Put("length", "1600");

if (null != appSDK)
{
    appSDK.LoadMetadata(contentMetadata);
}

The following section will explain the different values.

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 custom
(no Special Characters)
Yes
program name of program (25 character limit) custom Yes
title name of program (40 character limit) custom Yes
length length of content in seconds seconds (0 for live stream) Yes
airdate the airdate in the linear TV; if not known set it to eg. "19700101 00:00:00" 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

Static Measurement

The Nielsen SDK is able to monitor Application launch events and how long your app has been running. Once the Nielsen module has been Initialized, pass a metadata object to loadMeta data that follows these rules:

Key Description Data Type Value Required?
type asset type fixed 'static' 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

You only need to do this once upon app start.

Configure API Calls

Sample API Sequence

A Sample API sequence could follow this flow:

Type Sample code Description
On Appearing appApi.LoadMetadata(contentMetadata); contentMetadata - Object contains the JSON metadata for the impression.
Start of stream appApi.Play(metadata); metadata contains JSON metadata of channel/video name being played
appApi.LoadMetadata(contentMetadata); contentMetadataObject contains the JSON metadata for the content being played
Content appApi.PlayheadPosition(pos); PlayheadPosition is position of the playhead while the content is being played
End of Stream appApi.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.

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 the play function to pass the channel descriptor information through channelName parameter when the user taps the Play button on the player.

iOS

JObject playInfoJObj = new JObject {
    { "channelName", channelName },
    { "mediaURL", mediaURL }
};

NSObject playInfo = NSObject.FromObject(playInfoJObj.ToString());
appApiLegacy.Play(playInfo);
}


Android

JSONObject playInfo = new JSONObject()
                .Put("channelName", channelName)
                .Put("mediaURL", mediaURL);

appSDK.Play(playInfo);


loadMetadata

The loadMetadata function is used to inform the SDK about new content. The contentMetadata object passed in should contain the values as described above.

iOS

JObject contentMetadataJObj = new JObject {
    { "title", channelName },
    { "adloadtype", "2" },
    { "type", "content" },
    { "assetid", channelName },
    { "length", length }
};


Android

JSONObject contentMetadata = new JSONObject()
                .Put("title", channelName)
                .Put("adloadtype", "2")
                .Put("assetid", channelName)
                .Put("type", "content")
                .Put("length", length);


playheadPosition

Use playheadPosition to tell the SDK about the current position in the video. For live content this should be the Unix timestamp (seconds since Jan-1-1970 UTC). For on-demand content, simply the playhead position in seconds.

iOS

 appApiLegacy.PlayheadPosition(pos);


Android

 appSDK.SetPlayheadPosition(pos);


stop

Tell the SDK that content playback has stopped.

iOS

 appApiLegacy.Stop();


Android

 appSDK.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).

iOS

appApiLegacy.End();


Android

appSDK.End();


sendId3

Send Nielsen-specific ID3 tags received from the HLS stream being played.

iOS

appApiLegacy.SendID3(id3Data);


Android

appSDK.SendID3(id3Data);


Privacy and Opt-Out

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 via the OptOutURL() [OR] UserOptOutURLString() method of the NielseniOS [or] NielsenAndroid SDK(s) and opened in 'WebView' / External browser.
  • If the returned value is null or empty, handle the exception 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

  • 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


In Android too users can opt out or opt back into Nielsen Measurement. SDK Opt-Out has to be done via Google Settings → Ads → Opt out of Ads Personalization.

User is opted out of Nielsen online measurement research when the "Opt out of Ads Personalization" setting is enabled.

andr-ads.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.

Nuget Packages


To start using the Android App SDK in Xamarin application, the following nuget packages are required:

  • Xamarin.AndroidX.Lifecycle.Common
  • Xamarin.AndroidX.Lifecycle.Process
  • Xamarin.AndroidX.Lifecycle.LiveData
  • Xamarin.AndroidX.Browser
  • Xamarin.AndroidX.Legacy.Support.V4
  • Xamarin.Google.Android.Material
  • Xamarin.GooglePlayServices.Identity
  • Xamarin.GooglePlayServices.Ads


In AndroidManifest.xml under <application> node add the following metadata (needed for Xamarin.GooglePlayServices.Ads) -


<meta-data android:name="com.google.android.gms.ads.AD_MANAGER_APP" android:value="true" />

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_devDebug: 'DEBUG'} from initialization call.
    • Example Production Initialization Call - Refer to the production initialization call below:

Example:

   iOS
JObject appInfo = new JObject {
    { "appid", "PXXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX"},
    { "sfcode", "dcr" },
    { "nol_devDebug", "DEBUG" }
};

NSObject appInfoObj = NSObject.FromObject(appInfo.ToString());
appApiDelegate = new AppApiDelegate();
appApiLegacy = new NielsenAppApi(appInfoObj, appApiDelegate);


   Android
JSONObject appInfo = new JSONObject()
                .Put("appid", "PXXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX")
                .Put("sfcode", "dcr"),
                .Put("nol_devDebug", "DEBUG");

AppNotifierImpl iAppNotifierImpl = new AppNotifierImpl();        

AppSdk appSDK = new AppSdk(context, appInfo, iAppNotifierImpl);