Template:iOS SDK Initialization

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. (Click here for an example of multiple instances)

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.

Swift Example

Sample SDK Initialization Code

NielsenInit.swift

class NielsenInit: NSObject {
    class func createNielsenAppApi(delegate: NielsenAppApiDelegate) -> NielsenAppApi?{
    let appInformation:[String: String] = [
           "appid": "PE392366B-F2C1-4BC4-AB62-A7DAFDCXXXX",
           "nol_devDebug": "DEBUG"
        ]
        return NielsenAppApi(appInfo:appInformation, delegate:delegate)}}

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

Sample SDK Initialization Code

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": "PE392366B-F2C1-4BC4-AB62-A7DAFDC51XXX",
                                     @"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
}}

The following might be in the Viewcontroller.m

@implementation ViewController

- (void)viewDidLoad {
    [super viewDidLoad];
    
    //Setting background image
    UIImage *backgroundImage = [UIImage imageNamed:@"new_ios_bg.png"];
    UIImageView *backgroundImageView=[[UIImageView alloc]initWithFrame:self.view.frame];
    backgroundImageView.image=backgroundImage;
    [self.view insertSubview:backgroundImageView atIndex:0];
    
    //Mark: In NielsenInit class we are initialising the Nielsen SDK.
    
    //Getting the instance of Nielsen SDK
    nielsenApi = [NielsenInit createNielsenAppApiWithDelegate:nil];
}

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

NSDictionary object with the following objects and keys: viewTag (mandatory) value of NSNumber type, unique identifier (tag) for the target view object. This tag can be assigned for the player view either programmatically or in the storyboard/xib. viewContainer (mandatory) pointer to the parent view object. It is needed to identify the concrete scene in the applications which support multiple scenes. This parameter can not be nil. friendlyObstructions (nullable) an array of tags of the views which should be ignored during the intersection ratio calculation. Those are views like loading activity indicator, player controls, view with a watermark, etc. which are displayed in front of the target view, but should not reduce the viewability intersection ratio. The tags of such should be wrapped into the NSNumber objects before adding into the array. This parameter is nullable, empty array is also accepted.

Objective C

NSString *targetViewTag = targetView.tag;
NSString *controlsViewTag = controlsViewTag.tag;
NSString *activityIndicatorViewTag = activityIndicatorView.tag;
NSDictionary *viewabilityData = @{@"viewTag": targetViewTag,
                                  @"viewContainer": targetView.window,
                                  @"friendlyObstructions": @[controlsViewTag, activityIndicatorViewTag]};
[sdkInstance trackViewability:viewabilityData];

Swift

let targetViewTag = targetView.tag
let controlsViewTag = controlsViewTag.tag
let activityIndicatorViewTag = activityIndicatorView.tag
let viewabilityData: [String:Any] = ["viewTag": "\(targetViewTag)",
                                     "viewContainer": targetView.window!,
                                     "friendlyObstructions": ["\(controlsViewTag)", "\(activityIndicatorViewTag)"]]
sdkInstance.trackViewability(viewabilityData)

Data Collected

Parameter	Description
Measured Value	Value is different for different request parameters: invs Intersection ratio for the target view in percent (from 0 to 100). Default threshold for this value is 5. Example: [50,1,1528457356,10] inau Volume level on the device in percent (from 0 to 100), where 0 - mute, 100 - max volume level. Default threshold for this value is 1. Example: [30,1,1528457356,10] inss Device screen size as "WxH", where W - is width in pixels, H - is height in pixels. Example: ["1024x768",1,1528457356,10] invp Current window size. This is different than the device screen size in a multiple scene mode or on a desktop. Format is "WxH", where W - is width in pixels, H - is height in pixels. Example: ["800x600",1,1528457356,10] ines Player view size as "WxH", where W - is width in pixels, H - is height in pixels. Example: ["300x200",1,1528457356,10]
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]