iOS SDK API Reference

Engineering Portal / Digital / iOS SDK API Reference

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

Prerequisites

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

	Item	Description	Source
☑	App ID (appid)	Unique ID assigned to the player/site and configured by product.	Contact Nielsen
☑	sfcode	Environment that the SDK must point to	Contact Nielsen
☑	Nielsen SDK	Includes SDK frameworks and sample implementation; See iOS SDK Release Notes	Download

If you do not have any of these pre-requisites 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.

SDK Implementation

Information on how to obtain, how to configure your development environment, and how to Initialize the Nielsen SDK is located in either the DCR Implementation Guide, or the DTVR Implementation Guide depending on your requirements.

_

Nielsen iOS App SDK Application Life Cycle

Life cycle of SDK instance includes four general states:

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 Idle state.
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 an event to occur.
Processing state – The SDK instance is processing playing information. The 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 is active. If a LIVE event, use the current UNIX timestamp (seconds since Jan-1-1970 UTC).
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.
Disabled state – The SDK instance is disabled and is not processing playing information.
1. appDisableApi is set to true

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.

As soon as the playback resumes, call play, loadMetadata and playheadPosition

icon

Finite-state machine table

This table provides the possible changes of state for the SDK instance, when it is in a specific state and receives an API call.

API call received	Initial State	Idle State	Processing State	Disabled State
`initWithAppInfo:delegate:`	IDLE STATE (OR) DISABLED STATE	IDLE STATE	-	-
`play` & `loadMetadata`	-	PROCESSING STATE	-	-
`playheadPosition`	-	-	PROCESSING STATE	-
`sendID3`	-	-	PROCESSING STATE	-
`stop`	-	-	IDLE STATE	-
`end`	-	-	IDLE STATE	-
`appDisableApi`: YES	-	DISABLED STATE	-	-
`appDisableApi`: NO	-	-	-	IDLE STATE (OR) DISABLED STATE
`userOptOut`: YES	-	-	IDLE STATE	-
`userOptOut`: NO	-	PROCESSING STATE	-	-
'-' indicates that no API call is expected.

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.

The below is a sample - detailed information on the metadata requirements are located in either the DCR Implementation Guide, or the DTVR Implementation Guide

Swift

let contentMetadata = [
    "type": "content",
    "assetid": "C77664",
    "title": "Program S2, E3",
    "isfullepisode": "Yes",
    "program": "Program Name",
    "length": "3600",
    "airdate": "20171020 10:05:00",
    "adloadtype": "2",
    "segB": "CustomSegmentValueB", //optional
    "segC": "CustomSegmentValueC", //optional
];

Objective C

 
NSDictionary * contentMetadata = @ {
    @ "type": @ "content",
        @ "assetid": @ "C77664",
        @ "title": @ "S2,E3",
        @ "isfullepisode": @ "y",  
        @ "program": @ "Program Name",
        @ "length": @ "3600",
        @ "airdate": @ "20180120 10:00:00",
        @ "adloadtype": @ "2",
        @ "segB": @ "CustomSegmentValueB", //optional
        @ "segC": @ "CustomSegmentValueC", //optional
}

Retrieving ID3 Tags

Only required for DTVR clients
Not applicable for German Clients

ID3 tags have a payload of about 249 characters and start with "www.nielsen.com".

ID3 tags are extracted by observing a property called timedMetadata on the iOS player item. Now this is done via a concept called KVO (Key Value Observing), where you register interest in a property, and the runtime will let you know when it has changed.

Both the iOS native players have the ability to extract ID3 tags, If any other player apart from iOS native players (AVPlayer, MPMoviePlayer) is used, check and ensure that the player has the capability to extract ID3 tags.

Examples of extracting ID3 tags from the iOS Native Player

Swift

 
      //Setting observer to track timedMetadata
            player.addObserver(self, forKeyPath: timedMetadataKey, options: NSKeyValueObservingOptions.new, context: &TimedMetadataObserverContext)

 
   override func observeValue(forKeyPath keyPath: String?, of object: Any?, change: [NSKeyValueChangeKey : Any]?, context: UnsafeMutableRawPointer?) {
        
        if keyPath == timedMetadataKey {
            if(context == &TimedMetadataObserverContext){
                if change != nil {
                    let timedMetadataArray = change![.newKey]
                    if timedMetadataArray != nil && (timedMetadataArray! as AnyObject) is Array<Any> {
                        for item in timedMetadataArray as! [AVMetadataItem]  {
                            //Handling TimedMetadata
                            self.handleTimedMetadata(metadataItem: item)
                        }
                    }
                }
            }
        }

 
 func handleTimedMetadata(metadataItem: AVMetadataItem) {
        guard let extraAttributeType = metadataItem.extraAttributes else {
            return
        }
        let info : AVMetadataExtraAttributeKey = AVMetadataExtraAttributeKey(rawValue: "info")
        let extraString = extraAttributeType[info] as AnyObject
        let key = metadataItem.key as! String
        
        //If tag starts with "www.nielsen.com", then only sending to SDK
        if key == "PRIV" && extraString.range(of: "www.nielsen.com").length > 0 {
            
            DispatchQueue.global(qos: .default).async { () -> Void in
                self.nielsenApi?.sendID3(extraString as! String)
            }
        }
    }

Objective C

    //Adding observer to player to track play,pause and reverse
    [player addObserver:self
             forKeyPath:@"rate"
                options:(NSKeyValueObservingOptionNew)
                context:nil];

       
        //Setting observer to track timedMetadata
        [player addObserver:self
                 forKeyPath: timedMetadataKey
                    options: (NSKeyValueObservingOptionNew)
                    context: &TimedMetadataObserverContext];

     
- (void)observeValueForKeyPath:(NSString *)keyPath
                      ofObject:(id)object
                        change:(NSDictionary *)change
                       context:(void *)context
{
    if(keyPath == timedMetadataKey){
        if(context == &TimedMetadataObserverContext){
            
            id newMetadataArray = [change objectForKey:NSKeyValueChangeNewKey];
            if (newMetadataArray != [NSNull null])
            {
                array = newMetadataArray;
                for (AVMetadataItem *metadataItem in array)
                {
                    //Handling TimedMetadata
                    [self handleTimedMetadata: metadataItem];
                }
            }
            
        }
    }

     
- (void)handleTimedMetadata:(AVMetadataItem *)timedMetadata
{
    // We expect the content to contain plists encoded as timed metadata
    // AVPlayer turns these into NSDictionaries
    
    id extraAttributeType = [timedMetadata extraAttributes];
    NSString *extraString = nil;
    if ([extraAttributeType isKindOfClass:[NSDictionary class]])
    {
        extraString = [extraAttributeType valueForKey:@"info"];
    }
    else if ([extraAttributeType isKindOfClass:[NSString class]])
    {
        extraString = extraAttributeType;
    }
    
    NSString *key = [NSString stringWithFormat:@"%@", [timedMetadata key]];
    
    //If tag starts with "www.nielsen.com", then only sending to SDK
    if ([key isEqualToString:@"PRIV"] && [extraString rangeOfString:@"www.nielsen.com"].length > 0)
    {
        
        dispatch_async(dispatch_get_global_queue(DISPATCH_QUEUE_PRIORITY_DEFAULT, 0), ^{
            [nielsenApi sendID3:extraString];
        });
    }
}

Note: ID3 tags are not applicable for International (Germany)

IOS SDK API Methods & Properties

Scenario	Method / Property	DTVR	DAR	DCR	International (Germany)	Description
Initialize	initWithAppInfo:delegate:	✔	✔	✔	✔	Used to create a new instance of the SDK object
Measurement	play	✔	✔	✔	✔	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. This allows the client to send in at least the required “channel name” value associated to the ID3 feed. If this is not called then the “channel name” value populated will be the default value of “defaultChannelName”.
Measurement	loadMetadata	✔	✔	✔	✔	Used to send ad or content metadata to the SDK in the form of JSON string. Application constructs a JSON hashmap and calls this API.
Measurement	sendID3	✔				Used to send the ID3 metadata.
Measurement	playheadPosition			✔	✔	Used to send the playhead position.
Measurement	stop	✔		✔	✔	Used when playback is paused and when switching between ad and content or content and ad.
Measurement	end	✔	✔	✔	✔	Used when content playback is complete. This is triggered 1) at the end of the content stream, 2) if the user switches to another piece of content
Measurement	staticEnd			✔	✔	Used with DCR Static duration in between loadMetadata calls for static content when section name is the same but a new static view event and duration measurement restart is desired
Measurement	updateOTT				✔	Used to notify App SDK that the remote OTT device (like Google ChromeCast, Roku, Amazon FireTV, etc.) is connected / disconnected (change of OTT status).
Opt-out	optOutURL	✔	✔	✔	✔	Used to fetch the Nielsen opt-out web page URL.
Opt-out	userOptOut	✔	✔	✔	✔	Used to supply the response message from opt-out webpage to the SDK.
Opt-out	optOutStatus	✔	✔	✔	✔	Call this API to retrieve the Opt-Out or Opt-In state.
Opt-out	appDisableApi (kill switch)	✔	✔	✔	✔	Used to disable the SDK.
Viewability Audibility	trackViewability	✔		✔	✔	Used to start the viewability measurement.
Log	lastErrorDict	✔	✔	✔	✔	Returns SDK error in the form of dictionary if any error has occurred.
Log	lastEventDict	✔	✔	✔	✔	Returns SDK event in the form of dictionary if any event has occurred.
Log	meterVersion	✔	✔	✔	✔	Returns the current SDK version.
Log	nielsenId	✔	✔	✔	✔	Used to get a string defining the Nielsen ID (NUID) number for the device.
Log	demographicId	✔	✔	✔	✔	Used to retrieve Demographic ID (Device ID) of the current device.
Log	debug	✔	✔	✔	✔	Used to enable/disable debug flags. Newly introduced in SDK version 5.0.0 for International (Germany)

NielsenAppApi Class Description

The NielsenAppApi class is the primary application interface to the Nielsen App SDK. For example, after an instance object of the NielsenAppApi class is created and initialized, it can be used by the calling application to collect HLS timed metadata using the SDK’s sendID3: method. These are the public methods and properties exposed by the NielsenAppApi class:

@interface NielsenAppApi: NSObject

  @property (readonly) BOOL optOutStatus;
  @property (assign) BOOL appDisableApi;
  @property (assign) BOOL debug;
  @property (readonly, nonnull) NSString *nielsenId;
  @property (readonly, nonnull) NSString *demographicId;
  @property (readonly, nonnull) NSString *firstPartyId;
  @property (readonly, nonnull) NSString *vendorId;
  @property (readonly, nonnull) NSString *optOutURL;
  @property (readonly, nullable) NSString *meterVersion;
  @property (readonly, nullable) NSDictionary *lastEventDict;
  @property (readonly, nullable) NSDictionary *lastErrorDict;

  - (nullable instancetype)initWithAppInfo:(nonnull id)appInfo delegate:(nullable id<NielsenAppApiDelegate>)delegate

  - (void)play:(nullable id)channelInfo;
  - (void)loadMetadata:(nullable id)metadata;
  – (void)stop;
  – (void)end;
  - (void)playheadPosition:(long long)playheadPos;
  - (void)sendID3:(nonnull NSString *)data;
  - (void)updateOTT:(nonnull id)ottInfo;
  - (BOOL)userOptOut:(nonnull NSString *)optOut;
  - (void)trackViewability:(nonnull NSDictionary *)data;

  - (nonnull NSString *)getNielsenId __attribute((deprecated(("nielsenId is not used by the SDK anymore"))));
  - (nonnull NSString *)optOutURLString __attribute((deprecated(("Please use optOutURL property instead."))));
  - (nullable NSString *)getMeterVersion __attribute((deprecated(("Please use meterVersion property instead."))));
  - (nullable NSDictionary *)getLastEventDict __attribute((deprecated(("Please use lastEventDict property instead."))));
  - (nullable NSDictionary *)getLastErrorDict __attribute((deprecated(("Please use lastErrorDict property instead.")))); 

  @protocol NielsenAppApiDelegate <NSObject>

  @optional
  - (void)nielsenAppApi:(nonnull NielsenAppApi *)appApi eventOccurred:(nonnull NSDictionary *)event;
  - (void)nielsenAppApi:(nonnull NielsenAppApi *)appApi errorOccurred:(nonnull NSDictionary *)error;

@end

AppApiEventCode

An enumeration with predefined App SDK event state transition codes.

typedef NS_ENUM(unsigned int, AppApiEventCode)
{
     AppApiStartup = 2001,
     AppApiShutdown = 2002,
}AppApiEventCode;

App SDK Event Codes

Event Code	Event Name	Event Description
2001	AppApiStartup	App SDK has initialized successfully. It will happen only after App SDK has received a valid config file
2002	AppApiShutdown	App SDK is shutting down. It will happen just before App SDK is destroyed

AppApiErrorCode

iOS contains two types of error codes, 1-15 and 1001-1009.

For, 1-15, an enumeration with predefined error codes which the App SDK object can generate.

typedef NS_ENUM(unsigned int, LogCode) {
    LogCodeFailedParseStartInfo, // 1.
    LogCodeFailedParseMetadata, // 2.
    LogCodeFailedProcessID3, // 3.
    LogCodeFailedReceiveConfig, // 4.
    LogCodeFailedParseConfig, // 5.
    LogCodeFailedStartProcessor, // 6.
    LogCodeFailedCreateUrl, // 7.
    LogCodeFailedCreateRequest, // 8.
    LogCodeFailedSendHttpRequest, // 9.
    LogCodeFailedSendPing, // 10.
    LogCodeFailedSendTSV, // 11.
    LogCodeFailedSendStationRequest, // 12.
    LogCodeFailedAccessDatabase, // 13.
    LogCodeException, // 14.
    LogCodeInvalidPlayheadPosition, // 15.
    LogCodeLongAd, // 16.
    LogCodeIncorrectSfcode, // 17.
    LogCodeHemUidExceedLimit, // 18.
    LogCodeViewabilityUnableFindView // 19.
};

For, 1001-1009, an enumeration with predefined error codes which the App SDK object can generate.

typedef NS_ENUM(unsigned int, AppApiErrorCode)
{
   AppApiNetworkConnectionFailure = 1001,
   AppApiFileWriteFailure = 1002,
   AppApiFileReadFailure = 1003,
   AppApiEmptyValue = 1004,
   AppApiEmptyAppName = 1005,
   AppApiEmptyAppVersion = 1006,
   AppApiEmptyAppId = 1007,
   AppApiAnExceptionOccured = 1008,
   AppApiUnknownExceptionOccured = 1009
};

App SDK Error Codes

Error Code	Error Name	Error Description
1	LogCodeFailedParseStartInfo	Failed to parse the play() JSON string
2	LogCodeFailedParseMetadata	Failed to parse the loadMetadata() JSON string
3	LogCodeFailedProcessID3	Failed to process ID3 data on a data processor
4	LogCodeFailedReceiveConfig	Failed to receive configuration file from Census
5	LogCodeFailedParseConfig	Failed to parse the config file JSON string
6	LogCodeFailedStartProcessor	Failed to create SDK processor
7	LogCodeFailedCreateUrl	Failed to generate URL due to missing mandatory parameter
8	LogCodeFailedCreateRequest	Failed to create request in HTTP client
9	LogCodeFailedSendHttpRequest	Failed sending HTTP or HTTPS request
10	LogCodeFailedSendPing	Failed to send ping
11	LogCodeFailedSendTSV	Failed to send TSV request
12	LogCodeFailedSendStationRequest	Failed to send StationId request
13	LogCodeFailedAccessDatabase	Failed to read/write from/to database table
14	LogCodeException	Any exception handled by SDK code
15	LogCodeInvalidPlayheadPosition	Invalid playhead position
16	LogCodeLongAd	Long ad
17	LogCodeIncorrectSfcode	Incorrect client supplied sfcode
18	LogCodeHemUidExceedLimit	Exceeded limit of chars for hem uid
19	LogCodeViewabilityUnableFindView	Viewability unable to find a view with the specificed tag

Error Code	Error Name	Error Description
1001	AppApiNetworkConnectionFailure	App SDK Could not connect to server
1002	AppApiFileWriteFailure	App SDK Could not write to file
1003	AppApiFileReadFailure	App SDK Could not read data from file
1004	AppApiEmptyValue	Empty value Found.
1005	AppApiEmptyAppName	Cannot initialize SDK Object without an AppName(Player Name)
1006	AppApiEmptyAppVersion	Cannot initialize API Object without an AppVersion
1007	AppApiEmptyAppId	Cannot initialize API Object without an AppId
1008	AppApiAnExceptionOccured	Exception occurred
1009	AppApiUnknownExceptionOccured	Unknown exception occurred

Nielsen Sample Applications

Nielsen SDK client package contains iOS sample player applications based on native Players integrated with SDK framework. The players demonstrate all the supported functions of the SDK and show the integration details for both legacy and trackEvent API. There are players developed on Objective C and Swift. Implementation of the sample apps is based on native iOS AVPlayer.

The UI components of the iOS App SDK sample applications are common to both as shown below.

From the Channel Selection buttons ⬇️ & ⬆️ , the user will be able select the channels to stream.
The Info button ℹ️ displays information of the SDK version, current Nielsen ID used for the device, and the option for opt-out/opt-in.
The Play ▶️ and Pause ⏸️ buttons will control the streaming of the selected channel.
The area at the bottom of the window displays the current stream status.
The Clear button 🔃 clears out the status window.
The Email button 📧 can be used to email the tags and status in a text file to Nielsen.

If target device supports Picture-in-Picture playing, it could be activated by PIP button in the Video player window.

Channel URLs and metadata are obtained from the JSON file named appConfig.json and stored in the application bundle.

Viewability testing

The sample applications shipped with the client package has support for viewability metrics verification. The player view can be moved using a finger-dragging gesture in the application window. This allows the tester to reduce the visible area of the player view and check the resulting data. There are additional UI buttons:

Cover View button opens a popup with multiple UI controls which allow changing a player-view alpha and/or visibility as well to show a cover view in front of the player view.
Alert button to open a native UI alert in the application.

Nielsen Privacy Requirements

There are three primary methods for implementing user Opt-out preferences:

OS-level Opt-out - managed by Limit Ad Tracking setting on device (preferred approach).
Legacy Opt-out - Direct call to SDK; used only for older versions of Nielsen iOS SDK (< 5.1.1.18)
App Level Opt-Out - Where Ad Framework cannot be leveraged

Privacy Protections

Privacy protections that Nielsen ensures to have with each App SDK integration are as follows.

Disclosure of viewership data collection in app store description
Disclosure of viewership data collection in EULA / Privacy Policy
A link in the EULA/Privacy policy, or in another conspicuous location within the App, to a Nielsen-hosted web page outlining what Nielsen is collecting and how it is being used
Method for users to opt-out of Nielsen measurement, any time while using the application

Ratings Data Flow

Every view of creditable and watermarked content is measured by Nielsen.

Information NOT Shared

With Nielsen
- User's Identity
With Data Provider
- Content information
- Whether user is viewing an ad or video content
- Player used to play the streaming (audio / video, etc.)
- Values being de-duped / aggregating for

Nielsen collects only what it needs for audience measurement. Every view of creditable, watermarked content will be measured by Nielsen.

Data Collected

Type of Information	Parameter	Transmitted to Nielsen?	Sent to Provider?
Nielsen ID3 Watermark
	FinalDistributor Timestamp	Yes	No
	Program Content Timestamp	Yes	No
	Mobile Breakout Code	Yes	No
	Commercial Credit Code – Linear or Dynamic	Yes	No
	Time ShiftedViewing Code	Yes	No
	Segment Number	Yes	No
	Segment View Pattern	Yes	No
Device/App Info
	Device OSVersion	Yes	Yes
	Device Model	Yes	No
	Device Advertiser ID (Apple IDFA or Google AdID/Android ID)	Yes	Yes
	Cache Buster	Yes	Yes
	App Version	Yes	No
	App Name	Yes	No
	SDKDisabled Flag	Yes	No
	ServerCode	Yes	No
	Channel or URL	Yes	No
Nielsen Identifiers
	Client ID	Yes	No
	Campaign ID	Yes	Yes
	Nielsen Unique Device ID	Yes	No
	Application ID	Yes	No
	DeviceGroup (ex. Tablet, Smartphone, Desktop)	Yes	Yes
	OS Group (ex. Android, iOS, Windows)	Yes	Yes
	SDKVersion	Yes	No
	IP Address for DMA, Country Code	Yes	Yes

Note: Data is hashed, and encrypted using AES 128 before transmission to data provider.

Example ping sent to provider

https://provider.com/cgi-bin/brandlift.php?campaign_id=ff12725d724fac7934cf6003f096b4cd&placement_id=a4164b8fba9ee7c873a9c72c7091bb58&creative_id=25280139b61a947e127a52f56c8a2fdd&segment1=9000&segment2=41&segment3=iOS&OSVer=iOS6.1&c9=&devgrp=tablet&h=f5f243fe6d&rnd=1376971827360

This ping passes the following parameters to the provider:

Campaign ID – (campaign, placement, creative)
Country Code
DMA
OS Group (ex. iOS, Android)
DeviceOS Version
Device Advertiser ID
DeviceGroup (ex. Tablet, Smartphone, Desktop)
Cache Buster

TVOS Opt-out

To Opt-Out, users must have access to “About Nielsen Measurement” page.

TVOS does not support creating instances of UIWebView and display web pages. Instead it makes use of a TVML page (built on TVML template) which displays information in a specific order.

Opt-Out page is built on descriptiveAlertTemplate and appears as follows:

TVOs OptOut LimitAdTracking1.png

TVOs OptOut LimitAdTracking2.png

Opt-out wording

About Nielsen Measurement
YOUR CHOICES
Television and the way we watch it have come a long way since Nielsen began measuring TV audiences in 1950. Today, the ability to watch programs at any time and on multiple devices amplifies the need for exceptionally adept and flexible audience measurement capabilities. Consumers are changing with the times, and the same goes for Nielsen. As technology continues to evolve and media companies try new ways to attract viewers, understanding what consumers are watching — and what they're watching on — is more important than ever. Today, viewing video is a personal and mobile experience —anytime and anywhere. Our capabilities provide relevant metrics that are necessary to inform successful marketing and programming and drive continued growth. As a global information and measurement leader, we are committed to protecting the privacy and security of the data we collect, process and use. While our digital measurement products are not used to identify you in any way, they help us and our clients measure and analyze how consumers engage with media across online, mobile and emerging technologies, and offer insights into consumer behavior. Nielsen believes that you should have a choice about whether to contribute to our research and insights. To opt out of Nielsen measurement on this device, you need only to activate the “Limit Ad Tracking” option in your device's settings. If you have this app on more than one mobile device, you will need to change the settings on each device. If, after you have opted out, you change your mind and would like to opt back in, please deactivate the “Limit Ad Tracking” option in your device's settings.
To learn more about our digital measurement products and your choices in regard to them, please visit https://www.nielsen.com/digitaIprivacy.

Users need to toggle the “Limit Ad Tracking” option in order to Opt-In / Opt-Out of Nielsen Measurement.

To retrieve the current Opt-Out status of a device, use the optOutStatus method.

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.

Viewability and Audibility Implementation

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.

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.

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]

Viewability support requires additional parameters to be provided from player applications to the SDK. In order to provide these parameters and to start the viewability measurement, the following method has been added to the public SDK API (please refer to the trackViewability public API reference for details and usage examples):

Objective C

- (void)trackViewability:(nonnull NSDictionary *)data;

Swift

func trackViewability(_ data: [String : Any])

For Audibility measurement SDK uses iOS system API in order to get the volume level for the device:

AVAudioSession.sharedInstance().outputVolume

iOS SDK API Reference

From Engineering Client Portal

Revision as of 21:09, 30 March 2023 by NickParrucci (talk | contribs) (→‎IOS SDK API Methods & Properties)
(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)

Overview

Prerequisites

SDK Implementation

Contents

Nielsen iOS App SDK Application Life Cycle

Finite-state machine table

Handling JSON Metadata

Retrieving ID3 Tags

Examples of extracting ID3 tags from the iOS Native Player

IOS SDK API Methods & Properties

NielsenAppApi Class Description

AppApiEventCode

App SDK Event Codes

AppApiErrorCode

App SDK Error Codes

Nielsen Sample Applications

Viewability testing

Nielsen Privacy Requirements

Privacy Protections

Ratings Data Flow

Data Collected

Example ping sent to provider

TVOS Opt-out

Opt-out wording

Viewability and Audibility Implementation

Data Collected

iOS SDK API Reference

From Engineering Client Portal

Revision as of 21:09, 30 March 2023 by NickParrucci (talk | contribs) (→‎IOS SDK API Methods & Properties)(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)

Overview

Prerequisites

SDK Implementation

Nielsen iOS App SDK Application Life Cycle

Finite-state machine table

Handling JSON Metadata

Retrieving ID3 Tags

Examples of extracting ID3 tags from the iOS Native Player

IOS SDK API Methods & Properties

NielsenAppApi Class Description

AppApiEventCode

App SDK Event Codes

AppApiErrorCode

App SDK Error Codes

Nielsen Sample Applications

Viewability testing

Nielsen Privacy Requirements

Privacy Protections

Ratings Data Flow

Data Collected

Example ping sent to provider

TVOS Opt-out

Opt-out wording

Viewability and Audibility Implementation

Data Collected

Revision as of 21:09, 30 March 2023 by NickParrucci (talk | contribs) (→‎IOS SDK API Methods & Properties)
(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)