Engineering Client Portal - User contributions [en]

DCR Podcasts in Digital

2019-01-11T16:28:25Z

Admin2: UTC -> UNIX

{{Breadcrumb|}} {{Breadcrumb|Digital}} {{Breadcrumb|Digital Audio}} {{CurrentBreadcrumb}}
[[Category:Podcasts]]

__TOC__

== Steps ==
'''This document assumes you have implemented Digital Audio with Live AM/FM stream measurement''' with a "radio" content type. It outlines the new parameters you will use to implement podcast measurement.

#Contact your Nielsen Account Representative to discuss the way you would like your podcasts reported (Classified)
#Your TAM will provide new appIds for the applications that will offer podcasts
#Update the parameters you use to call the SDK play and playheadPosition. Reference the appropriate [[DCR Podcasts in Digital#Changes_for_Podcast_Measurement|Changes for Podcast Measurement]] below
#Obtain Nielsen Podcast certification once your changes are complete and tested
#Complete a Production License with your Nielsen Account Representative
=== Library ===
Use the same SDK library as Digital Audio, live AM/FM stream measurement.

== Changes for Podcast Measurement ==
=== Initializing the SDK ===
Update your appid to the new ID provided by your TAM for podcast measurement.
When you initialize the SDK, use 'dcr' in the sfcode instead of 'drm'.

=== play ===
Call [[play]] when the user taps the '''Play''' button to start the content.. The channelName parameter is not required.

'''play Example'''

<syntaxhighlight lang="json">{
"channelName": "KABC-FM Morning Show"
}</syntaxhighlight>

=== loadMetadata ===
Use [[loadMetadata]] to pass information about your podcast to the SDK. The parameters must be passed as a JSON object.
<syntaxhighlight lang="objective-c"> – (void) loadMetadata :(id)metadata;</syntaxhighlight>
Refer to [[loadMetadata]] for the list of parameters to be passed in the JSON object.
<blockquote>'''Note:''' The [[loadMetadata]] call after the first [[play]] call '''must have ‘content’ ("type": "content").''' </blockquote>

'''loadMetadata Example'''
<syntaxhighlight lang="json">{
"type": "content",
"assetid": "KABC:345-67483",
"program": "KABC Morning Show",
"title": "20171125: HR1",
"length": "3600",
"segB": "KABC-FM", // station call letters and band are optional here
"isfullepisode": "y",
"airdate": "20171125 06:00:00",
"adloadtype": "2",
"pipmode":"false"
}</syntaxhighlight>

=== playheadPosition for "content" ===
You will continue to use [[playheadPosition]] to pass the position of the playhead while the content is being played; however, you will pass the relative position from the beginning of the file. '''This is different than live stream measurement, which uses the current Unix timestamp (seconds since Jan-1-1970 UTC).'''

{| class="wikitable"
|-
! Key !! Description !! Values !! Required? (Y/N) !! Example
|-
| On-Demand Audio || Position taken from beginning of the content in seconds. || Client-defined || Yes || Current player position from beginning of the content.
|}

''' playheadPosition Syntax Example for iOS'''
<syntaxhighlight lang="objective-c"> CMTime curTime=[player currentTime];
long pos=CMTimeGetSeconds(curTime);
[nAppApiObject playheadPosition:pos];</syntaxhighlight>

'''Usage Sequence and API'''
The sample API sequence can be used as a reference to identify the specific events that need to be called during content and ad playback.

{| class="wikitable"
|-
! Action !! Sample code !! Description
|-
| rowspan="2" | Start of stream || <code>[nielsenMeter play: channelName];</code> || // channelName contains JSON metadata of program being played
|-
| <code>[nielsenMeter loadMetadata: contentMetadataObject];</code> || // contentMetadataObject contains the JSON metadata for the content being played
|-
| Listening || <code>[nielsenMeter playheadPosition: position];</code> || // playheadPosition is position of the playhead while the content is being played
|-
| End of Stream || <code>[nielsenMeter end];</code> || // Content playback is completed.
|}

- Continue to call [[playheadPosition]] every two seconds until the user pauses, stops, or loses audio.

- Call a new ''loadMetadata'' when the user selects a different program.

'''With Preroll, Midroll, Postroll Ads'''
'''Please note:''' The below examples include ad pod information. These ads are not ads served as part of the originator's programming (studio-recorded ads). These ads are hosted independently from the podcast content file.

When applicable, Playhead should be passed for the entire duration of ad pod, if the ad pod details are passed as part of [[loadMetadata]].

{| class="wikitable"
|-
! Action !! Sample code !! Description
|-
| rowspan="2" | Start of stream || <code>[nielsenMeter play: channelName];</code> || // channelName contains JSON metadata of channel/video name being played
|-
| <code>[nielsenMeter loadMetadata: contentMetadataObject];</code> || // contentMetadataObject contains the JSON metadata for the content being played
|-
| rowspan="3" | Preroll || <code>[nielsenMeter loadMetadata: prerollMetadataObject];</code> || // prerollMetadataObject contains the JSON metadata for the preroll ad
|-
| <code>[nielsenMeter playheadPosition: position];</code> || // position is position of the playhead while the preroll ad is being played
|-
| <code>[nielsenMeter stop];</code> || // Call stop after preroll occurs
|-
| rowspan="3" | Listening || <code>[nielsenMeter loadMetadata: contentMetadataObject];</code> || // contentMetadataObject contains the JSON metadata for the content being played
|-
| <code>[nielsenMeter playheadPosition: position];</code> || // position is position of the playhead while the content is being played
|-
| <code>[nielsenMeter stop];</code> || // Call stop after the content is paused (ad starts)
|-
| rowspan="3" | Midroll || <code>[nielsenMeter loadMetadata: midrollMetadataObject];</code> || // midrollMetadataObject contains the JSON metadata for the midroll ad
|-
| <code>[nielsenMeter playheadPosition: position];</code> || // position is position of the playhead while the midroll ad is being played
|-
| <code>[nielsenMeter stop];</code> || // Call stop after midroll occurs
|-
| rowspan="3" | Content (End of stream) || <code>[nielsenMeter loadMetadata: contentMetadataObject];</code> || // contentMetadataObject contains the JSON metadata for the content being played
|-
| <code>[nielsenMeter playheadPosition: position];</code> || // position is position of the playhead while the content is being played
|-
| <code>[nielsenMeter end];</code> || // Called at the end of content
|-
| rowspan="3" | Postroll || <code>[nielsenMeter loadMetadata: postrollMetadataObject];</code> || // postrollMetadataObject contains the JSON metadata for the postroll ad
|-
| <code>[nielsenMeter playheadPosition: position];</code> || // position is position of the playhead while the postroll ad is being played
|-
| <code>[nielsenMeter stop];</code> || // Call stop after postroll occurs
|}

<blockquote>'''Note:''' Each Ad playhead should reset or begin from 0 at ad start. When content has resumed following an ad break, playhead position must continue from where previous content segment was left off.</blockquote>

== Nielsen Measurement Opt-Out Implementation ==
No changes are necessary because Opt-out implementation for podcasts is the same as live AM/FM stream measurement.

== Technical Guides ==
{| class="wikitable"
! style="width: 90px;" | Type
! style="width: 45px;" |
! style="width: 45px;" | OS
! style="width: 50%;" | DCR Implementation Guide
!| SDK Documentation
|-
| rowspan="7" | {{SmallIcon|SDKIcon.png|alt=SDK}}
|-
| rowspan="3" | {{OSIcon|VideoIcon.png|alt=Video}}
| {{OSIcon|macOSIcon.png|alt=iOS}}
| '''[[DCR Video iOS SDK]]'''
| [[iOS SDK API Reference]]
|-
| {{OSIcon|AndroidIcon.png|alt=Android}}
| '''[[DCR Video Android SDK]]'''
| [[Android SDK API Reference]]
|}

{| class="wikitable"
|-
! style="width: 90px;" |
! style="width: 42%;" | Technical Guides
!
|-
| rowspan="7" | {{SmallIcon|DigitalIcon.png}}
| '''[[Digital Measurement Onboarding]]'''
| '''[[Digital Measurement Metadata]]'''
|-
| '''[[Digital Measurement Testing]]'''
| '''[[Digital Measurement Interruption Scenarios]]'''
|-
| '''[[Digital Measurement FAQ]]'''
|
|-
| '''[[Digital Pre-Certification Checklist App SDK]]'''
| '''[[Digital Pre-Certification Checklist Browser SDK]]'''
|}

Digital Measurement Metadata

2018-10-23T18:40:29Z

Admin2:

{{Breadcrumb|}} {{Breadcrumb|Digital}} {{Breadcrumb|DCR & DTVR}} {{CurrentBreadcrumb}}
[[Category:Digital]]

The metadata received for each asset is used for classification and reporting. There are reserved Nielsen keys for collecting the required metadata.

=== Reserved Keys ===
Content and Ad Metadata can be passed through key-values using the Nielsen reserved keys. The last column in the table below indicates metadata parameters that will be displayed in reporting.

==== Content Metadata ====
{| class="wikitable"
|-
! Key
! Description
! style="width: 14%;" | Values
! style="width: 12%;" | Required for Audio/Video?
! style="width: 12%;" | Required for Static (page)?
! Reported for
|-
| clientid || Brand value is automatically populated through the App ID provided. The value passed here will override the default value. (e.g. Multiple brands in App) || custom || Optional || Optional || Audio / Video and Static Measurement
|-
| subbrand || VCID value is automatically populated through the App ID provided. This value passed here will override the default value. (e.g. Multiple Sub-brands in App) || custom || Optional || Optional || Audio / Video and Static Measurement
|-
| type ||
Type of measurement:
*audio / video – "content"
*page – "static"
*ad – "preroll", "midroll" or "postroll"
|| "content", "static" || Mandatory || Mandatory ||
|-
| assetid || ID assigned to content. '''Must be unique and consistent''' across all content at the episode level, as well as across platforms (e.g. iOS and Android use the same ID). || custom (no [[Special Characters]]) || Mandatory || Not Required ||
|-
| section || Section of site || custom || Not Required || Mandatory ||
|-
| isfullepisode || Full episode flag ||
*"y" or "lf" - full episode
*"n" or "sf" - short form
|| Mandatory || Not Required ||
|-
| program || Program name || custom || Mandatory || Not Required || Audio / Video Measurement
|-
| title || Episode title || custom || Mandatory || Not Required || Audio / Video Measurement
|-
| length || Length of content in seconds for VOD. 0 may be used for Live content if the exact content length is not known. || custom || Mandatory || Not Required ||
|-
| segA || Segment A (this is not available for audio / video Measurement reporting as the episode title is reported) || custom || Not Required || Not Required || Static Measurement
|-
| segB || Segment B || custom || Not Required || Not Required || Audio / Video and Static Measurement
|-
| segC || Segment C || custom || Not Required || Not Required || Audio / Video and Static Measurement
|-
| crossId1 || Standard episode ID. Gracenote/TMS ID should be used when available. Must be unique per episode. || custom || Optional || Not Required ||
|-
| crossId2 || Content originator (required only for distributors) || custom || Optional || Not Required ||
|-
| airdate || Original (local) air date and time (Eastern Time for US) || YYYYMMDD HH24:MI:SS || Mandatory || Not Required ||
|-
| pipmode ||
Current state of picture-in-picture (PIP) mode on device.
*"true" if audio / video measurement is displayed in PIP mode
*"false" if audio / video measurement is displayed in regular mode
|| "true", "false" || Optional || Not Required || Audio / Video Measurement
|-
| adloadtype ||
Type of ad load:
#Linear - matches TV ad load
#Dynamic - Dynamic Ad Insertion (DAI)
|| "1" - Linear
"2" - Dynamic
|| Mandatory for DCR || Not Required || DCR
|-
| adModel ||
Type of ad model:
#Linear - matches TV ad load
#Dynamic - Dynamic Ad Insertion (DAI)
|| "1" - Linear
"2" - Dynamic
|| Mandatory for DTVR || Not Required || DTVR
|-
| progen || Genre (required only for non-TV originated content). See [[DCR OTT Genre List]] for acceptable values. || e.g. DD for Daytime Drama || Required for non-TV content || Not Required
|}

'''clientid & subbrand (vcid)'''
By default, clientid and subbrand are setup in Nielsen backend configuration to capture brand and sub-brand information. The fields get populated from backend for a registered client appid. But if an app contains multiple brands and sub-brands and client is willing to give credit to another brand or sub-brand then :
*Client app developer can override the clientid and subbrand (brand and sub-brand info.) in [[loadMetadata]] call to get a proper measurement for a desired brand and sub-brand.
**If no clientid and subbrand are specified in CMS of a content and an ad, default values reported in the Configuration will be reported.
**If clientid and subbrand are specified in CMS of the content or ad, the most recent clientid and subbrand will be reported in subsequent pings. To report with a different clientid and subbrand, include the new values for the keys in their subsequent [[loadMetadata]] call.
'''Picture-in-picture (PIP) mode'''
Once the app detects PIP mode, call [[loadMetadata]] with the same set of assetids, values and with one additional parameter "pipmode": "true". Once PIP mode is disabled in the device, call [[loadMetadata]] again with "pipmode":"false".

==== Custom Variables Extension ====
Contact Nielsen Technical Account Manager (TAM) to configure any custom variables, as needed for implementing the application.

See [[Custom Variables Extension]] for more information.

==== Advertisement Metadata ====
{| class="wikitable"
|-
! Key !! Description !! Values !! Required for Audio / Video? !! Required for Static (page)
|-
| type || Type of ad || "preroll"
"midroll"
"postroll"
|| Mandatory || Not Required
|-
| assetid || An ID assigned to the advertisement. Can be an internal ID, an ID provided by the ad server, or a randomly generated ID. Must be unique across all ads || custom || Mandatory || Not Required
|-
| title || Title of the advertisement || "MyAdName" || Mandatory || Not Required
|}

=== Passing Metadata ===
The required metadata can be passed as key values through the loadMetadata method. The sample code below shows a metadata objects for various assets.
'''Audio / Video Measurement Asset'''
Type should be "content"
<syntaxhighlight lang="json"> {
"type": "content",
"assetName": "myassetName",
"length": "300.0",
"title": "myTitle",
"program": "myProgram",
"censuscategory": "myCensusCategory",
"assetid": "myAssetId",
"channelName": "myChannel",
"adloadtype": "2",
"segB": "segmentB",
"segC": "segmentC",
"isfullepisode":"y",
"crossId1": "Reference11",
"crossId2": "Reference22",
"airdate": "20161013 20:00:00"
}</syntaxhighlight>

'''Static (Page) Measurement Asset'''
Type should be "static"
<syntaxhighlight lang="json"> {
"type": "static",
"assetid": "static123",
"assetName": "Page-Asset",
"section": "siteSection",
"segA": "segmentA",
"segB": "segmentB",
"segC": "segmentC"
}</syntaxhighlight>

'''For any of the ad types'''
<syntaxhighlight lang="json"> {
"type": "midroll",
"length": "30.0",
"assetid": "myMidrollAssetId",
"adloadtype": "2",
"tv": "true",
"dataSrc": "cms"
}</syntaxhighlight>
<blockquote>'''Note''': In case the individual ad details are not available, send ad pod (presence) details through the <code>loadMetadata</code> and playhead position through <code>setPlayheadPosition</code>.</blockquote>

'''loadMetadata'''
The object can then be passed when calling [[loadMetadata]].
<syntaxhighlight lang="java"> loadMetadata(jsonMetadataObject);</syntaxhighlight>

Digital Measurement Metadata

2018-10-23T18:39:18Z

Admin2:

{{Breadcrumb|}} {{Breadcrumb|Digital}} {{Breadcrumb|DCR & DTVR}} {{CurrentBreadcrumb}}
[[Category:Digital]]

The metadata received for each asset is used for classification and reporting. There are reserved Nielsen keys for collecting the required metadata.

=== Reserved Keys ===
Content and Ad Metadata can be passed through key-values using the Nielsen reserved keys. The last column in the table below indicates metadata parameters that will be displayed in reporting.

==== Content Metadata ====
{| class="wikitable"
|-
! Key
! Description
! style="width: 14%;" | Values
! style="width: 12%;" | Required for Audio/Video?
! style="width: 12%;" | Required for Static (page)?
! Reported for
|-
| clientid || Brand value is automatically populated through the App ID provided. The value passed here will override the default value. (e.g. Multiple brands in App) || custom || Optional || Optional || Audio / Video and Static Measurement
|-
| subbrand || VCID value is automatically populated through the App ID provided. This value passed here will override the default value. (e.g. Multiple Sub-brands in App) || custom || Optional || Optional || Audio / Video and Static Measurement
|-
| type ||
Type of measurement:
*audio / video – "content"
*page – "static"
*ad – "preroll", "midroll" or "postroll"
|| "content", "static" || Mandatory || Mandatory ||
|-
| assetid || ID assigned to content. '''Must be unique and consistent''' across all content at the episode level, across platforms. || custom (no [[Special Characters]]) || Mandatory || Not Required ||
|-
| section || Section of site || custom || Not Required || Mandatory ||
|-
| isfullepisode || Full episode flag ||
*"y" or "lf" - full episode
*"n" or "sf" - short form
|| Mandatory || Not Required ||
|-
| program || Program name || custom || Mandatory || Not Required || Audio / Video Measurement
|-
| title || Episode title || custom || Mandatory || Not Required || Audio / Video Measurement
|-
| length || Length of content in seconds for VOD. 0 may be used for Live content if the exact content length is not known. || custom || Mandatory || Not Required ||
|-
| segA || Segment A (this is not available for audio / video Measurement reporting as the episode title is reported) || custom || Not Required || Not Required || Static Measurement
|-
| segB || Segment B || custom || Not Required || Not Required || Audio / Video and Static Measurement
|-
| segC || Segment C || custom || Not Required || Not Required || Audio / Video and Static Measurement
|-
| crossId1 || Standard episode ID. Gracenote/TMS ID should be used when available. Must be unique per episode. || custom || Optional || Not Required ||
|-
| crossId2 || Content originator (required only for distributors) || custom || Optional || Not Required ||
|-
| airdate || Original (local) air date and time (Eastern Time for US) || YYYYMMDD HH24:MI:SS || Mandatory || Not Required ||
|-
| pipmode ||
Current state of picture-in-picture (PIP) mode on device.
*"true" if audio / video measurement is displayed in PIP mode
*"false" if audio / video measurement is displayed in regular mode
|| "true", "false" || Optional || Not Required || Audio / Video Measurement
|-
| adloadtype ||
Type of ad load:
#Linear - matches TV ad load
#Dynamic - Dynamic Ad Insertion (DAI)
|| "1" - Linear
"2" - Dynamic
|| Mandatory for DCR || Not Required || DCR
|-
| adModel ||
Type of ad model:
#Linear - matches TV ad load
#Dynamic - Dynamic Ad Insertion (DAI)
|| "1" - Linear
"2" - Dynamic
|| Mandatory for DTVR || Not Required || DTVR
|-
| progen || Genre (required only for non-TV originated content). See [[DCR OTT Genre List]] for acceptable values. || e.g. DD for Daytime Drama || Required for non-TV content || Not Required
|}

'''clientid & subbrand (vcid)'''
By default, clientid and subbrand are setup in Nielsen backend configuration to capture brand and sub-brand information. The fields get populated from backend for a registered client appid. But if an app contains multiple brands and sub-brands and client is willing to give credit to another brand or sub-brand then :
*Client app developer can override the clientid and subbrand (brand and sub-brand info.) in [[loadMetadata]] call to get a proper measurement for a desired brand and sub-brand.
**If no clientid and subbrand are specified in CMS of a content and an ad, default values reported in the Configuration will be reported.
**If clientid and subbrand are specified in CMS of the content or ad, the most recent clientid and subbrand will be reported in subsequent pings. To report with a different clientid and subbrand, include the new values for the keys in their subsequent [[loadMetadata]] call.
'''Picture-in-picture (PIP) mode'''
Once the app detects PIP mode, call [[loadMetadata]] with the same set of assetids, values and with one additional parameter "pipmode": "true". Once PIP mode is disabled in the device, call [[loadMetadata]] again with "pipmode":"false".

==== Custom Variables Extension ====
Contact Nielsen Technical Account Manager (TAM) to configure any custom variables, as needed for implementing the application.

See [[Custom Variables Extension]] for more information.

==== Advertisement Metadata ====
{| class="wikitable"
|-
! Key !! Description !! Values !! Required for Audio / Video? !! Required for Static (page)
|-
| type || Type of ad || "preroll"
"midroll"
"postroll"
|| Mandatory || Not Required
|-
| assetid || An ID assigned to the advertisement. Can be an internal ID, an ID provided by the ad server, or a randomly generated ID. Must be unique across all ads || custom || Mandatory || Not Required
|-
| title || Title of the advertisement || "MyAdName" || Mandatory || Not Required
|}

=== Passing Metadata ===
The required metadata can be passed as key values through the loadMetadata method. The sample code below shows a metadata objects for various assets.
'''Audio / Video Measurement Asset'''
Type should be "content"
<syntaxhighlight lang="json"> {
"type": "content",
"assetName": "myassetName",
"length": "300.0",
"title": "myTitle",
"program": "myProgram",
"censuscategory": "myCensusCategory",
"assetid": "myAssetId",
"channelName": "myChannel",
"adloadtype": "2",
"segB": "segmentB",
"segC": "segmentC",
"isfullepisode":"y",
"crossId1": "Reference11",
"crossId2": "Reference22",
"airdate": "20161013 20:00:00"
}</syntaxhighlight>

'''Static (Page) Measurement Asset'''
Type should be "static"
<syntaxhighlight lang="json"> {
"type": "static",
"assetid": "static123",
"assetName": "Page-Asset",
"section": "siteSection",
"segA": "segmentA",
"segB": "segmentB",
"segC": "segmentC"
}</syntaxhighlight>

'''For any of the ad types'''
<syntaxhighlight lang="json"> {
"type": "midroll",
"length": "30.0",
"assetid": "myMidrollAssetId",
"adloadtype": "2",
"tv": "true",
"dataSrc": "cms"
}</syntaxhighlight>
<blockquote>'''Note''': In case the individual ad details are not available, send ad pod (presence) details through the <code>loadMetadata</code> and playhead position through <code>setPlayheadPosition</code>.</blockquote>

'''loadMetadata'''
The object can then be passed when calling [[loadMetadata]].
<syntaxhighlight lang="java"> loadMetadata(jsonMetadataObject);</syntaxhighlight>

DCR Static Google AMP Cloud API

2018-03-20T22:45:04Z

Admin2: /* Metadata Keys */

{{Breadcrumb|}} {{Breadcrumb|Digital}} {{Breadcrumb|DCR & DTVR}} {{CurrentBreadcrumb}}
[[Category:Digital]]

This guide will show you how to enable Digital Content Ratings (DCR) Static measurement on Google AMP.

== Import AMP Analytics Javascript Library ==
If you have not already, you will need to import the AMP JS library in the <code><head></code> of your webpage in order to make an AMP page:
<syntaxhighlight lang="html"><script async src="https://cdn.ampproject.org/v0.js"></script></syntaxhighlight>

Next, please ensure that the following line is included in the <code><head></code> of the webpage:
<syntaxhighlight lang="html"><script async custom-element="amp-analytics" src="https://cdn.ampproject.org/v0/amp-analytics-0.1.js"></script></syntaxhighlight>
<blockquote>'''Note''': AMP pages require all traffic to be using HTTPS, including the webpage itself</blockquote>

== Specify the Analytics Provider ==
DCR measurement can be added to your AMP pages through the AMP-Analytics element:
<syntaxhighlight lang="html"><amp-analytics type="nielsen">

</amp-analytics></syntaxhighlight>

For more information on the Analytics type, you can refer to the [https://www.ampproject.org/docs/guides/analytics/analytics-vendors Analytics vendors] section of Google's AMP Developer Documentation.

== Configure Metadata ==
You will need to match the metadata fields on your AMP page with those of your non-AMP page.

=== Metadata Keys ===
The Nielsen reserved keys are:
{| class="wikitable"
|-
! Key !! Description !! Example Value !! Required
|-
| apid || unique ID assigned by Nielsen || <code>XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX</code> || ✓
|-
| apv || current version of the Nielsen implementation || <code>1.0</code> || ✓
|-
| apn || name of the website || <code>My AMP Website</code> ||
|-
| section || section of the site to be measured || <code>Entertainment</code> || ✓
|-
| segA || custom segment to be used to break out reporting || <code>Music</code> ||
|-
| segB || custom segment to be used to break out reporting || <code>News</code> ||
|-
| segC || Reserved custom segment for Google AMP || <code>Google AMP</code> || ✓
|}

The values passed through the Nielsen keys will determine the breakouts you will see in reporting. If you decide not to use custom segments A and B, then you do not need to pass a value in these keys. It is suggested you use the same segments used in non-AMP pages.
<blockquote>'''Note''': The value for the 'apid' you pass for AMP measurement should not include the 'P' prefix that is otherwise present on other SDK-related implementations</blockquote>

=== Metadata for Reporting ===
You can reference the table to determine how the metadata you pass is used to define your reporting structure:
{| class="wikitable"
|-
! Reporting Level !! Key !! Description
|-
| Brand/Sub-brand || apid || brand and sub-brand are determined by assigned App ID passed during initialization
|-
| Section || section || section or category for the AMP page
|-
| Custom Segment A || segA || available segment for custom reporting. Custom segments will roll into the sub-brand
|-
| Custom Segment B || segB || available segment for custom reporting. Custom segments will roll into the sub-brand
|-
| Custom Segment C || segC || Custom segment C is reserved for reporting ‘Google AMP’. The Google AMP custom segment will be available under sub-brand and will include the total metrics for all your AMP pages
|}

If you would like your AMP pages to report into the same reporting structure as your website, we recommend passing the same dynamic metadata in Section, Custom Segment A, and Custom Segment B as you are on your website. This way your AMP pageviews contribute to those aggregations.

=== Aggregation Limits ===
There are limits on the number of unique values that can be aggregated on in reporting. The specific limitations by key are:
{| class="wikitable"
|-
! Key !! Aggregation Limit
|-
| section || maximum of 25 unique values (section <= 25)
|-
| segA || total sum of segA, segB, and segC must be a maximum of 24 unique values (segA + segB + segC <= 24)
|-
| segB || total sum of segA, segB, and segC must be a maximum of 24 unique values (segA + segB + segC <= 24)
|}

== Example Implementation ==
The below is an example implementation of Nielsen measurement on an AMP page:
<syntaxhighlight lang="html"><amp-analytics type="nielsen">
<script type="application/json">
{
"vars": {
"apid": "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX",
"apv": "1.0",
"apn": "My AMP Website",
"section": "Entertainment",
"segA": "Music",
"segB": "News",
"segC": "Google AMP"
}
}
</script>
</amp-analytics></syntaxhighlight>

You can find more information about dynamic variables on [https://github.com/ampproject/amphtml/blob/master/spec/amp-var-substitutions.md#page-and-content Google's AMP documentation].

<blockquote>'''Note''': append <code>#development=1</code> at the end of your URL to see AMP debug logs in the console. This can be helpful when troubleshooting</blockquote>

== Privacy Policy ==
Nielsen uses cookies for browser measurement. In order to comply with our privacy restrictions, we ask that you make a link to our Digital Privacy Policy available on your site. You can find our privacy policy here:
http://priv-policy.imrworldwide.com/priv/browser/us/en/optout.html

DCR & DTVR

2018-01-29T14:13:15Z

Admin2: /* Plugins */

{{Breadcrumb|}} {{Breadcrumb|Digital}} {{CurrentBreadcrumb}}
[[Category:Digital]]
{{CategoryIcon|DCR.png|Digital Content Ratings (DCR) & Digital in TV Ratings (DTVR)}}

__NOTOC__

{| class="wikitable"
|-
! style="width: 90px;" |
! style="width: 42%;" | General Reference
!
|-
| rowspan="7" | {{SmallIcon|DigitalIcon.png}}
| '''[[Digital Measurement Onboarding]]'''
| '''[[Digital Measurement Metadata]]'''
|-
| '''[[Digital Measurement Testing]]'''
| '''[[Digital Measurement Interruption Scenarios]]'''
|-
| '''[[Digital Measurement FAQ]]'''
|
|-
| '''[[Digital Pre-Certification Checklist App SDK]]'''
| '''[[Digital Pre-Certification Checklist Browser SDK]]'''
|}

== SDK - Video ==
{| class="wikitable"
! style="width: 90px;" | Type
! style="width: 45px;" |
! style="width: 45px;" | OS
! style="width: 30%;" | DCR Implementation Guide
! style="width: 25%;" | DTVR Implementation Guide
!| SDK Documentation
|-
| rowspan="7" | {{SmallIcon|SDKIcon.png|alt=SDK}}
|-
| rowspan="3" | {{OSIcon|VideoIcon.png|alt=Video}}
| {{OSIcon|macOSIcon.png|alt=iOS}}
| '''[[DCR Video iOS SDK]]'''
| '''[[DTVR iOS SDK]]'''
| [[iOS SDK API Reference]]
|-
| {{OSIcon|AndroidIcon.png|alt=Android}}
| '''[[DCR Video Android SDK]]'''
| '''[[DTVR Android SDK]]'''
| [[Android SDK API Reference]]
|-
| {{OSIcon|BrowserIcon.png|alt=Browser}}
| '''[[DCR Video Browser SDK]]'''
| '''[[DTVR Browser SDK]]'''
| [[Browser SDK API Reference]]
|}

== SDK - Static ==
{| class="wikitable"
! style="width: 90px;" | Type
! style="width: 45px;" |
! style="width: 45px;" | OS
! style="width: 55%;" | DCR Implementation Guide
!| SDK Documentation
|-
| rowspan="6" | {{SmallIcon|SDKIcon.png|alt=SDK}}
| rowspan="7" | {{OSIcon|StaticIcon.png|alt=Static Content}}
| {{OSIcon|macOSIcon.png|alt=iOS}}
| '''[[DCR Static iOS SDK]]'''
| [[iOS SDK API Reference]]
|-
| {{OSIcon|AndroidIcon.png|alt=Android}}
| '''[[DCR Static Android SDK]]'''
| [[Android SDK API Reference]]
|-
| rowspan="2" | {{OSIcon|BrowserIcon.png|alt=Browser}}
| '''[[DCR Static Browser SDK]]'''
| rowspan="4" | [[Browser SDK API Reference]]
|-
| '''[[DCR Static Lite Browser SDK]]'''
|-
| {{OSIcon|GoogleTagManagerIcon.png|alt=Google Tag Manager}}
| '''[[DCR Static Google Tag Manager]]'''
|-
| {{OSIcon|FacebookIcon.png|alt=Facebook Instant Articles}}
| '''[[DCR Static Facebook Instant Articles Browser SDK]]'''
|-
|
| {{OSIcon|AMPIcon.png|alt=Google AMP}}
| '''[[DCR Static Google AMP Cloud API]]'''
| N/A
|}

== Cloud API ==
{| class="wikitable"
! style="width: 90px;" | Type
! style="width: 45px;" |
! style="width: 45px;" | OS
!| DCR Implementation Guide
|-
| rowspan="3" | {{SmallIcon|CloudAPIIcon.png|alt=Cloud API}}
| rowspan="3" |
{{OSIcon|VideoIcon.png|alt=Video}}
 
{{OSIcon|StaticIcon.png|alt=Static Content}}
| {{OSIcon|APIIcon.png|alt=Cloud API}}
| '''[[DCR Video & Static Cloud API ]]'''
|-
| {{OSIcon|APIIcon.png|alt=Cloud API}}
| '''[[DCR Video & Static Mobile Cloud API ]]'''
|-
| {{OSIcon|RokuIcon.png|alt=Roku}}
| '''[[DCR Video & Static Roku Cloud API]]'''
|}

International

2018-01-29T14:12:33Z

Admin2:

{{Breadcrumb|}} {{Breadcrumb|Digital}} {{CurrentBreadcrumb}}
[[Category:Digital]]
{{CategoryIcon|International.png|International}}

__NOTOC__

<blockquote>Please contact your Nielsen representative for documentation if the guides for your country aren't listed.</blockquote>

{| class="wikitable"
! colspan="3" | Downloads
|-
| style="width: 90px;" |{{SmallIcon|DownloadIcon.png|alt=Cloud API}}
|style="width: 90px;" | {{SmallIcon|SDKIcon.png}}
| '''[[Digital Downloads|SDK Downloads]]'''
|}

{| class="wikitable"
|-
! style="width: 90px;" | Germany
! style="width: 90px;" |
! style="width: 45px;" |
! style="width: 45px;" | OS
!| Guide
|-
| rowspan="6" | {{SmallIcon|DEFlagIcon.png}}
| rowspan="6" | {{SmallIcon|SDKIcon.png}}
| rowspan="3" | {{OSIcon|VideoIcon.png}}
| {{OSIcon|macOSIcon.png}}
 
{{OSIcon|AndroidIcon.png}}
| '''[[DCR Germany Video App SDK]]'''
|-
| {{OSIcon|BrowserIcon.png}}
| '''[[DCR Germany Video Browser SDK]]'''
|}

{| class="wikitable"
|-
! style="width: 90px;" | Italy
! style="width: 90px;" |
! style="width: 45px;" |
! style="width: 45px;" | OS
!| Guide
|-
| rowspan="7" | {{SmallIcon|ITFlagIcon.png}}
| rowspan="7" | {{SmallIcon|SDKIcon.png}}
| rowspan="3" | {{OSIcon|VideoIcon.png}}
| {{OSIcon|macOSIcon.png}}
 
{{OSIcon|AndroidIcon.png}}
| '''[[DCR Italy Video App SDK]]'''
|-
| rowspan="2" | {{OSIcon|BrowserIcon.png}}
| '''[[DCR Italy Video Browser SDK (6.0.0)]]'''
|-
| '''[[DCR Italy Video Browser SDK (6.0.1)]] Object Video only'''
|-
| rowspan="5" | {{OSIcon|StaticIcon.png}}
| {{OSIcon|macOSIcon.png}}
 
{{OSIcon|AndroidIcon.png}}
| '''[[DCR Italy Static App SDK]]'''
|-
| {{OSIcon|BrowserIcon.png}}
| '''[[DCR Italy Static Browser SDK]]'''
|-
| {{OSIcon|FacebookIcon.png|alt=Facebook Instant Articles}}
| '''[[DCR Italy Static Facebook Instant Articles Browser SDK]]'''
|-
| {{OSIcon|AMPIcon.png|alt=Google AMP}}
| '''[[DCR Italy Static Google AMP Cloud API]]'''
|}

DCR Italy Static Google AMP Cloud API

2018-01-25T17:55:34Z

Admin2: /* Metadata Keys */

{{Breadcrumb|}} {{Breadcrumb|Digital}} {{Breadcrumb|DCR & DTVR}} {{CurrentBreadcrumb}}
[[Category:Digital]]

This guide will show you how to enable Digital Content Ratings (DCR) Static measurement on Google AMP.

== Import AMP Analytics Javascript Library ==
If you have not already, you will need to import the AMP JS library in the <code><head></code> of your webpage in order to make an AMP page:
<syntaxhighlight lang="html"><script async src="https://cdn.ampproject.org/v0.js"></script></syntaxhighlight>

Next, please ensure that the following line is included in the <code><head></code> of the webpage:
<syntaxhighlight lang="html"><script async custom-element="amp-analytics" src="https://cdn.ampproject.org/v0/amp-analytics-0.1.js"></script></syntaxhighlight>
<blockquote>'''Note''': AMP pages require all traffic to be using HTTPS, including the webpage itself</blockquote>

== Specify the Analytics Provider ==
DCR measurement can be added to your AMP pages through the AMP-Analytics element:
<syntaxhighlight lang="html"><amp-analytics type="nielsen">

</amp-analytics></syntaxhighlight>

For more information on the Analytics type, you can refer to the [https://www.ampproject.org/docs/guides/analytics/analytics-vendors Analytics vendors] section of Google's AMP Developer Documentation.

== Configure Metadata ==
You will need to match the metadata fields on your AMP page with those of your non-AMP page.

=== Metadata Keys ===
The Nielsen reserved keys are:
{| class="wikitable"
|-
! Key !! Description !! Example Value !! Required
|-
| apid || unique ID assigned by Nielsen || <code>XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX</code> || ✓
|-
| prefix || URL prefix to allow EU data collection || <code>eu-</code> || ✓
|-
| apv || current version of the Nielsen implementation || <code>1.0</code> || ✓
|-
| apn || name of the website || <code>My AMP Website</code> ||
|-
| section || section of the site to be measured || <code>Entertainment</code> || ✓
|-
| segA || custom segment to be used to break out reporting || <code>Music</code> ||
|-
| segB || custom segment to be used to break out reporting || <code>News</code> ||
|-
| segC || Reserved custom segment for Google AMP || <code>Google AMP</code> || ✓
|}

The values passed through the Nielsen keys will determine the breakouts you will see in reporting. If you decide not to use custom segments A and B, then you do not need to pass a value in these keys. It is suggested you use the same segments used in non-AMP pages.

=== Metadata for Reporting ===
You can reference the table to determine how the metadata you pass is used to define your reporting structure:
{| class="wikitable"
|-
! Reporting Level !! Key !! Description
|-
| Brand/Sub-brand || apid || brand and sub-brand are determined by assigned App ID passed during initialization
|-
| Section || section || section or category for the AMP page
|-
| Custom Segment A || segA || available segment for custom reporting. Custom segments will roll into the sub-brand
|-
| Custom Segment B || segB || available segment for custom reporting. Custom segments will roll into the sub-brand
|-
| Custom Segment C || segC || Custom segment C is reserved for reporting ‘Google AMP’. The Google AMP custom segment will be available under sub-brand and will include the total metrics for all your AMP pages
|}

If you would like your AMP pages to report into the same reporting structure as your website, we recommend passing the same dynamic metadata in Section, Custom Segment A, and Custom Segment B as you are on your website. This way your AMP pageviews contribute to those aggregations.

=== Aggregation Limits ===
There are limits on the number of unique values that can be aggregated on in reporting. The specific limitations by key are:
{| class="wikitable"
|-
! Key !! Aggregation Limit
|-
| section || maximum of 25 unique values (section <= 25)
|-
| segA || total sum of segA, segB, and segC must be a maximum of 24 unique values (segA + segB + segC <= 24)
|-
| segB || total sum of segA, segB, and segC must be a maximum of 24 unique values (segA + segB + segC <= 24)
|}

== Example Implementation ==
The below is an example implementation of Nielsen measurement on an AMP page:
<syntaxhighlight lang="html"><amp-analytics type="nielsen">
<script type="application/json">
{
"vars": {
"apid": "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX",
"prefix": "eu-",
"apv": "1.0",
"apn": "My AMP Website",
"section": "Entertainment",
"segA": "Music",
"segB": "News",
"segC": "Google AMP"
}
}
</script>
</amp-analytics></syntaxhighlight>

You can find more information about dynamic variables on [https://github.com/ampproject/amphtml/blob/master/spec/amp-var-substitutions.md#page-and-content Google's AMP documentation].

<blockquote>'''Note''': append <code>#development=1</code> at the end of your URL to see AMP debug logs in the console. This can be helpful when troubleshooting</blockquote>

== Privacy Policy ==
Nielsen uses cookies for browser measurement. In order to comply with our privacy restrictions, we ask that you make a link to our Digital Privacy Policy available on your site. You can find our privacy policy here:
http://www.nielsen.com/digitalprivacy#choice

DCR Italy Static Google AMP Cloud API

2018-01-24T16:50:52Z

Admin2: Created page with "{{Breadcrumb|}} {{Breadcrumb|Digital}} {{Breadcrumb|DCR & DTVR}} {{CurrentBreadcrumb}} Category:Digital This guide will show you how to enable Digital Content Ratings (D..."

{{Breadcrumb|}} {{Breadcrumb|Digital}} {{Breadcrumb|DCR & DTVR}} {{CurrentBreadcrumb}}
[[Category:Digital]]

This guide will show you how to enable Digital Content Ratings (DCR) Static measurement on Google AMP.

== Import AMP Analytics Javascript Library ==
If you have not already, you will need to import the AMP JS library in the <code><head></code> of your webpage in order to make an AMP page:
<syntaxhighlight lang="html"><script async src="https://cdn.ampproject.org/v0.js"></script></syntaxhighlight>

Next, please ensure that the following line is included in the <code><head></code> of the webpage:
<syntaxhighlight lang="html"><script async custom-element="amp-analytics" src="https://cdn.ampproject.org/v0/amp-analytics-0.1.js"></script></syntaxhighlight>
<blockquote>'''Note''': AMP pages require all traffic to be using HTTPS, including the webpage itself</blockquote>

== Specify the Analytics Provider ==
DCR measurement can be added to your AMP pages through the AMP-Analytics element:
<syntaxhighlight lang="html"><amp-analytics type="nielsen">

</amp-analytics></syntaxhighlight>

For more information on the Analytics type, you can refer to the [https://www.ampproject.org/docs/guides/analytics/analytics-vendors Analytics vendors] section of Google's AMP Developer Documentation.

== Configure Metadata ==
You will need to match the metadata fields on your AMP page with those of your non-AMP page.

=== Metadata Keys ===
The Nielsen reserved keys are:
{| class="wikitable"
|-
! Key !! Description !! Example Value !! Required
|-
| apid || unique ID assigned by Nielsen || <code>XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX</code> || ✓
|-
| apv || current version of the Nielsen implementation || <code>1.0</code> || ✓
|-
| apn || name of the website || <code>My AMP Website</code> ||
|-
| section || section of the site to be measured || <code>Entertainment</code> || ✓
|-
| segA || custom segment to be used to break out reporting || <code>Music</code> ||
|-
| segB || custom segment to be used to break out reporting || <code>News</code> ||
|-
| segC || Reserved custom segment for Google AMP || <code>Google AMP</code> || ✓
|}

The values passed through the Nielsen keys will determine the breakouts you will see in reporting. If you decide not to use custom segments A and B, then you do not need to pass a value in these keys. It is suggested you use the same segments used in non-AMP pages.

=== Metadata for Reporting ===
You can reference the table to determine how the metadata you pass is used to define your reporting structure:
{| class="wikitable"
|-
! Reporting Level !! Key !! Description
|-
| Brand/Sub-brand || apid || brand and sub-brand are determined by assigned App ID passed during initialization
|-
| Section || section || section or category for the AMP page
|-
| Custom Segment A || segA || available segment for custom reporting. Custom segments will roll into the sub-brand
|-
| Custom Segment B || segB || available segment for custom reporting. Custom segments will roll into the sub-brand
|-
| Custom Segment C || segC || Custom segment C is reserved for reporting ‘Google AMP’. The Google AMP custom segment will be available under sub-brand and will include the total metrics for all your AMP pages
|}

If you would like your AMP pages to report into the same reporting structure as your website, we recommend passing the same dynamic metadata in Section, Custom Segment A, and Custom Segment B as you are on your website. This way your AMP pageviews contribute to those aggregations.

=== Aggregation Limits ===
There are limits on the number of unique values that can be aggregated on in reporting. The specific limitations by key are:
{| class="wikitable"
|-
! Key !! Aggregation Limit
|-
| section || maximum of 25 unique values (section <= 25)
|-
| segA || total sum of segA, segB, and segC must be a maximum of 24 unique values (segA + segB + segC <= 24)
|-
| segB || total sum of segA, segB, and segC must be a maximum of 24 unique values (segA + segB + segC <= 24)
|}

== Example Implementation ==
The below is an example implementation of Nielsen measurement on an AMP page:
<syntaxhighlight lang="html"><amp-analytics type="nielsen">
<script type="application/json">
{
"vars": {
"apid": "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX",
"prefix": "eu-",
"apv": "1.0",
"apn": "My AMP Website",
"section": "Entertainment",
"segA": "Music",
"segB": "News",
"segC": "Google AMP"
}
}
</script>
</amp-analytics></syntaxhighlight>

You can find more information about dynamic variables on [https://github.com/ampproject/amphtml/blob/master/spec/amp-var-substitutions.md#page-and-content Google's AMP documentation].

<blockquote>'''Note''': append <code>#development=1</code> at the end of your URL to see AMP debug logs in the console. This can be helpful when troubleshooting</blockquote>

== Privacy Policy ==
Nielsen uses cookies for browser measurement. In order to comply with our privacy restrictions, we ask that you make a link to our Digital Privacy Policy available on your site. You can find our privacy policy here:
http://www.nielsen.com/digitalprivacy#choice

Brightcove Plugin Browser

2017-11-02T18:27:02Z

Admin2:

{{Breadcrumb|}} {{Breadcrumb|Digital}} {{Breadcrumb|DCR & DTVR}} {{CurrentBreadcrumb}}
[[Category:Digital]]

The Nielsen Browser SDK (Software Development Kit) is the Nielsen framework for measuring media consumption in browser environments.

{{PluginInfobox
|pluginImage=BrightcoveIcon
|osImage=BrowserIcon
|playerVersion=5.18.0 - 5.22.0
|SDKVersion=5.1.1
|supportedAdFrameworks=
}}.

This SDK has the following features:
* '''Multiple product support''': built-in capabilities to support Digital Content Ratings(DCR), VideoCensus(VC), Digital Program Ratings(DPR) and IAG.

<blockquote>'''Note''': The Brightcove Plugin 5.1.0.9 is compatible with the Brightcove V5 player version 5.17 and 5.22.2. Brightcove V5 player 5.18 through 5.22.0 should not be used with the version 5.1.0.9 of the plugin.

All of the player issues that would have impacted measurement have been fixed in 5.22.2.

</blockquote>

== Getting Started ==
=== What You Will Need? ===
* '''Nielsen App ID (apid)''': a Unique ID that Nielsen assigns to the site / player. The 'apid' will be provided by your Technical Account Manager.
* '''BrightCove Plugin''': Plugin URLs are provided in the below [[#URL|section]].
* '''Test Environment Validation''': before you move into production, Nielsen must validate the SDK integration in a test environment.

=== Initial Configuration ===
Before integrating the plugin, configure the metadata, obtain Nielsen APID's, and review the Nielsen plugin URLs for Brightcove.

=== Obtain the Nielsen Application ID (apid) ===
The Nielsen apid is required to enable SDK functionality. Your Technical Account Manager will provide two apids for each player configuration
* Test apid: use this apid during development and testing
* Production apid: use this apid in your production environment after Nielsen has tested and qualified the player.

=== Brightcove Plugin URL's ===
* BC Perform Player (JS)
** http://cdn-gl.imrworldwide.com/novms/bc/3/ggng510.js
** https://cdn-gl.imrworldwide.com/novms/bc/3/ggng510.js

=== Global Parameters ===
To initialize the Nielsen Browser SDK, pass four global parameters when adding the BC Perform plugin.
{| class="wikitable"
|-
! Keys !! Description !! Values
|-
| apid || Unique ID assigned to player/site. There are two IDs provided || <code>'XXXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX'</code>
* Test: begins with 'T' and is used for testing
* Production: begins with 'P' and is used in live environment when testing and certification is completed.
|-
| sfcode || Location of collection environment. During testing, all traffic should be directed to 'dcr-cert'. || testing: <code>'dcr-cert'</code>

production: <code>'dcr'</code>
|-
| nsdkv || Nielsen SDK Version || <code>'511'</code>
|-
| apn || User-defined string value for describing the player / site. || custom
|}

The below parameter is optional but recommended when testing implementation.
{| class="wikitable"
|-
! Keys !! Description !! Values
|-
| nol_sdkDebug || Nielsen SDK console logging that should be used while testing. Make sure to disable before moving the implementation to production. || <code>'INFO'</code> – API calls

<code>'WARNING'</code> – System level logs

<code>'ERROR'</code> – Error logs

<code>'DEBUG'</code> – Full logs
|}

=== Configure Metadata ===
There are two types of metadata
* '''DCR Content Metadata''': identify content
* '''DCR Ad Metadata''': identify ad
Metadata can be passed through key-values using the Nielsen reserved keys.

The metadata received for each asset is used for classification and reporting. There are reserved Nielsen keys for collecting the required metadata.

=== Content Metadata ===
{| class="wikitable"
|-
! Keys !! Description !! Values !! Type !! Required
|-
| type || Type of asset || <code>'content'</code> || string || Yes
|-
| assetid || Unique ID assigned to asset || <code>custom</code> || string || Yes
|-
| program || Program Name || <code>custom</code> || string || Yes
|-
| title || Episode title || <code>custom</code> || string || Yes
|-
| airdate || The original airdate for linear TV || <code>'20161013 20:00:00'</code> || date || No
|-
| length || Length of content in seconds || <code>3600</code> (86400 for lives tream)|| integer || Yes
|-
| segB || Custom Reporting Segment || <code>custom</code> || string || No
|-
| segC || Custom Reporting Segment || <code>custom</code> || string || No
|-
| isfullepisode || Full Episode Flag ||
<code>'y'</code> - Full Episode

<code>'n'</code> - Non Full Episode
|| boolean || Yes
|-
| adloadtype || Distinguishes Dynamic vs Linear Ad Insertion ||
<code>'1'</code> - Linear

<code>'2'</code> - Dynamic
|| integer || Yes
|-
| crossId1 || Standard Episode ID || <code>custom</code> || string || Yes
|-
| crossId2 || Content Originator ID || <code>custom</code> || string || No
|-
| mediaURL || URL location of the content being streamed || <code>custom</code> || string || Yes
|-
| hasAds || Distinguishes when content includes Ads ||
<code>'0'</code> - No Ads

<code>'1'</code> - Includes Ads

<code>'2'</code> - Unknown
|| integer || Yes
|}

=== Ad Metadata ===
{| class="wikitable"
|-
! Keys !! Description !! Values !! Type !! Required
|-
| type || Type of ad ||
<code>'preroll'</code>

<code>'midroll'</code>

<code>'postroll'</code>
|| string || Yes
|-
| assetid || Unique ID assigned to ad || <code>custom</code> || string || Yes
|}
<blockquote>'''Note''':There is a URL character limit of 2000 characters imposed due to browser limitations. Exceeding this value can impair data delivery on particular browsers.</blockquote>

== Setup ==
In order to integrate the Nielsen plugin, follow the steps for setting up these players in the Brightcove user interface as they appear below by each player type.

=== Brightcove Player Setup ===
The new Brightcove Perform player allows two interchangeable ways to add the plugin: on the web site, so the player will come already configured, and programmatically on the client side.

These options, as well as the whole process of adding a plugin is common to the player and described here http://support.brightcove.com/en/perform/docs/configuring-player-plugins

==== For Nielsen SDK plugin, the integrator would need ====
* A list of initialization parameters (Application ID, App Name, sfcode, and nsdkv). Refer to [[#Global Parameters|Global Parameters]] section above.
* A link (URL) to SDK plugin (ggng510.js) for Brightcove
* A list of metadata fields with their names (Nielsen Key Mapping) to pass to the plugin. For more information, refer to [[#Configure Metadata|Configure Metadata]] section.
* Access to the Brightcove VideoCloud Perform Portal https://studio.brightcove.com/products/videocloud/home

==== To add Nielsen SDK plugin using UI do the following ====
Open Brightcove VideoCloud portal, open players list and open (or create) a player the plugin should be added to.
Scroll down to the 'Plugins' section in player configuration

[[File:Plugins-BC.jpg|link=]]

* Click "Edit" and enter the URL to plugin JS file. Click "+" to add the row.

[[File:js-BC.jpg|link=]]

* Then click "Name, Options (JSON)" row and enter "NielsenBC" for the plugin name and required initialization parameters provided by your Nielsen Technical Account Manager, as below:

[[File:Js-BC2.jpg|link=]]

Example Code:
<syntaxhighlight lang="json">{
"nol_sdkDebug": "DEBUG",
"sfcode": "dcr-cert",
"apn": "Test_player_name",
"nsdkv": "511",
"apid": "T4BFBFAC9-XXXX-XXXX-XXXX-22B092CBCC2B",
}</syntaxhighlight>

Adding <code>"nol_sdkDebug": "DEBUG"</code> will allow SDK events in the console.
<blockquote>'''Note''': <code>"nol_sdkDebug": "DEBUG"</code> must be removed when moving a player live to production to disable the debug logging.</blockquote>

==== Pass Content & Ad Metadata to The Brightcove Video Player ====
Pass the required content, and ad metadata to the Brightcove video player so that the Nielsen Plug-In is able to pick it up in order to populate the DCR crediting tags. The Nielsen Plug-In is preconfigured to automatically obtain metadata from Custom Fields. These can be set through the Brightcove User Interface (under ADMIN) or programmatically.

Information on creating Custom Metadatafields can be found on the [https://support.brightcove.com/en/video-cloud/docs/creating-custom-metadata-fields|Brightcove Support site].
<blockquote>'''Note:''' If you are using the Brightcove player with the PERFORM service, you will need to populate the media info. Please contact Brightcove support for details on this process.</blockquote>

[[File:Video-Fields.jpg|link=]]

For more information on how to pass the required metadata to the Brightcove [https://www.brightcove.com/en/online-video-platform VideoCloud] player, please reach out to your Brightcove Account Manager for further assistance.

==== To add Nielsen SDK programmatically ====
* Include plugin source<syntaxhighlight lang="html"><script src="//cdn-gl.imrworldwide.com/novms/bc/3/ggng510.js"></script></syntaxhighlight>
* Bind plugin to the player with inititalization parameters<syntaxhighlight lang="javascript">videojs("myPlayerID").NielsenBC(
{
"apid": "PXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX",
"apn": "Your_player_name",
"sfcode": "dcr-cert",
"nsdkv": "511"
}
}</syntaxhighlight>
* For CMS data binding, the following rules apply
* The plugin automatically captures the following video data
* * Data from video duration is automatically capture by the plugin<syntaxhighlight lang="javascript">nielsenData.length = videoInfo.duration;</syntaxhighlight>
* * Field "type" is set to <code>"content"</code>, <code>"preroll"</code>, <code>"midroll"</code> or <code>"postroll"</code>.
* If video data contains custom fields, all those fields are copied over to Nielsen data: <code>nielsenData[i] = videoInfo.custom_fields[i]</code> (with 'i' iterated over all custom field names), which may override some of the default values or standard field values
* '''The plugin does not automatically assign a value to assetid'''. To pass programmatically, use the custom fields object. (See code example below)
* Parameter videoInfo.id must be a unique string to allow the plugin detecting the content change.

=== Notes ===
* If some CMS metadata values should be set for all videos played, those values can be passed as "defaults" field on the player level (in the player configuration), like this<syntaxhighlight lang="json">{
"apid": "PXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX",
"apn": "Your_player_name",
"sfcode": "dcr",
"nsdkv": "511",
"defaults": { "customValue": "true" }
}</syntaxhighlight>
* CMS metadata values can also be set at the asset level<syntaxhighlight lang="json">{
"sources" :
[ {
"src" : "http://solutions.brightcove.com/../videos/Sea_SeaHorse.mp4",
"type" : "video/mp4"
} ],
"custom_fields":
{
"assetid": "6475587654",
"mediaURL": "http://solutions.brightcove.com/bcls/../videos/Sea_Anemone.mp4",
"dataSrc": "cms",
"hasAds": "1"
},
"name": "Sea Anemone",
"thumbnail": "http://solutions.brightcove.com/bcls/assets/images/Sea_Anemone_poster.png",
"id": "5195888503001"
}
}</syntaxhighlight>

=== Ad Support ===
The plugin will also extract information about the number and length of advertisements played with the video.

== Opt-Out Implementation ==
The site must provide a means for the user to opt out of, or opt back into Nielsen Measurement. A user can opt out if preferring to not participate in any Nielsen online measurement research. To implement the Opt-Out option, include the following in the privacy policy page:
* A notice that the player includes proprietary measurement software that allows users to contribute to market research (such as Nielsen TV Ratings)
* A link to the Nielsen Digital Measurement Privacy Policy at http://www.nielsen.com/digitalprivacy
On the Nielsen Digital Measurement Privacy Policy page, users can click choices to read more detailed information about the measurement software and their options. The users can click a link to retrieve an Opt-Out cookie if they do not want to participate in Nielsen online measurement.

Nielsen properties may feature Nielsen proprietary measurement software, which will allow the users to contribute to market research, such as Nielsen TV Ratings.

To learn more about the information that Nielsen software may collect and your choices with regard to it, please see the Nielsen Digital Measurement Privacy Policy at http://www.nielsen.com/digitalprivacy.

=== Opt-In ===
Once users have opted out, they can choose to opt back into Nielsen Measurement at anytime by selecting the Opt-In link on the Nielsen Digital Privacy Policy page. When a user selects the link, their Opt-Out cookie will be deleted and they will be measured.

== Going Live ==
After the integration is certified, there is one update to be made to the existing code to ensure that the player will be measured properly:
*'''App ID''': Change the apid to the production ID starting with the letter 'P':<syntaxhighlight lang="console">'PXXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX'</syntaxhighlight>
* '''Collection Environment''': Change the value for <code>sfcode</code> from <code>dcr-cert</code> to <code>dcr</code> to point traffic to the Nielsen production collection environment. Do not use <code>dcr-cert</code> for production traffic
<blockquote>'''Note''': Ensure that the <code>nol_sdkDebug</code> parameter is not used.</blockquote>

Brightcove Plugin Browser

2017-10-18T21:29:22Z

Admin2:

{{Breadcrumb|}} {{Breadcrumb|Digital}} {{Breadcrumb|DCR & DTVR}} {{CurrentBreadcrumb}}
[[Category:Digital]]

The Nielsen Browser SDK (Software Development Kit) is the Nielsen framework for measuring media consumption in browser environments.

{{PluginInfobox
|pluginImage=BrightcoveIcon
|osImage=BrowserIcon
|playerVersion=5.18.0 - 5.22.0
|SDKVersion=5.1.1
|supportedAdFrameworks=
}}.

This SDK has the following features:
* '''Multiple product support''': built-in capabilities to support Digital Content Ratings(DCR), VideoCensus(VC), Digital Program Ratings(DPR) and IAG.

<blockquote>'''Note''': The Brightcove Plugin 5.1.0.9 is compatible with the Brightcove V5 player version 5.17 and 5.22.2.

All of the player issues that would have impacted measurement have been fixed in 5.22.2.

Brightcove V5 player 5.18 through 5.22.0 should not be used with the plugin.</blockquote>

== Getting Started ==
=== What You Will Need? ===
* '''Nielsen App ID (apid)''': a Unique ID that Nielsen assigns to the site / player. The 'apid' will be provided by your Technical Account Manager.
* '''BrightCove Plugin''': Plugin URLs are provided in the below [[#URL|section]].
* '''Test Environment Validation''': before you move into production, Nielsen must validate the SDK integration in a test environment.

=== Initial Configuration ===
Before integrating the plugin, configure the metadata, obtain Nielsen APID's, and review the Nielsen plugin URLs for Brightcove.

=== Obtain the Nielsen Application ID (apid) ===
The Nielsen apid is required to enable SDK functionality. Your Technical Account Manager will provide two apids for each player configuration
* Test apid: use this apid during development and testing
* Production apid: use this apid in your production environment after Nielsen has tested and qualified the player.

=== Brightcove Plugin URL's ===
* BC Perform Player (JS)
** http://cdn-gl.imrworldwide.com/novms/bc/3/ggng510.js
** https://cdn-gl.imrworldwide.com/novms/bc/3/ggng510.js

=== Global Parameters ===
To initialize the Nielsen Browser SDK, pass four global parameters when adding the BC Perform plugin.
{| class="wikitable"
|-
! Keys !! Description !! Values
|-
| apid || Unique ID assigned to player/site. There are two IDs provided || <code>'XXXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX'</code>
* Test: begins with 'T' and is used for testing
* Production: begins with 'P' and is used in live environment when testing and certification is completed.
|-
| sfcode || Location of collection environment. During testing, all traffic should be directed to 'dcr-cert'. || testing: <code>'dcr-cert'</code>

production: <code>'dcr'</code>
|-
| nsdkv || Nielsen SDK Version || <code>'511'</code>
|-
| apn || User-defined string value for describing the player / site. || custom
|}

The below parameter is optional but recommended when testing implementation.
{| class="wikitable"
|-
! Keys !! Description !! Values
|-
| nol_sdkDebug || Nielsen SDK console logging that should be used while testing. Make sure to disable before moving the implementation to production. || <code>'INFO'</code> – API calls

<code>'WARNING'</code> – System level logs

<code>'ERROR'</code> – Error logs

<code>'DEBUG'</code> – Full logs
|}

=== Configure Metadata ===
There are two types of metadata
* '''DCR Content Metadata''': identify content
* '''DCR Ad Metadata''': identify ad
Metadata can be passed through key-values using the Nielsen reserved keys.

The metadata received for each asset is used for classification and reporting. There are reserved Nielsen keys for collecting the required metadata.

=== Content Metadata ===
{| class="wikitable"
|-
! Keys !! Description !! Values !! Type !! Required
|-
| type || Type of asset || <code>'content'</code> || string || Yes
|-
| assetid || Unique ID assigned to asset || <code>custom</code> || string || Yes
|-
| program || Program Name || <code>custom</code> || string || Yes
|-
| title || Episode title || <code>custom</code> || string || Yes
|-
| airdate || The original airdate for linear TV || <code>'20161013 20:00:00'</code> || date || No
|-
| length || Length of content in seconds || <code>3600</code> (86400 for lives tream)|| integer || Yes
|-
| segB || Custom Reporting Segment || <code>custom</code> || string || No
|-
| segC || Custom Reporting Segment || <code>custom</code> || string || No
|-
| isfullepisode || Full Episode Flag ||
<code>'y'</code> - Full Episode

<code>'n'</code> - Non Full Episode
|| boolean || Yes
|-
| adloadtype || Distinguishes Dynamic vs Linear Ad Insertion ||
<code>'1'</code> - Linear

<code>'2'</code> - Dynamic
|| integer || Yes
|-
| crossId1 || Standard Episode ID || <code>custom</code> || string || Yes
|-
| crossId2 || Content Originator ID || <code>custom</code> || string || No
|-
| mediaURL || URL location of the content being streamed || <code>custom</code> || string || Yes
|-
| hasAds || Distinguishes when content includes Ads ||
<code>'0'</code> - No Ads

<code>'1'</code> - Includes Ads

<code>'2'</code> - Unknown
|| integer || Yes
|}

=== Ad Metadata ===
{| class="wikitable"
|-
! Keys !! Description !! Values !! Type !! Required
|-
| type || Type of ad ||
<code>'preroll'</code>

<code>'midroll'</code>

<code>'postroll'</code>
|| string || Yes
|-
| assetid || Unique ID assigned to ad || <code>custom</code> || string || Yes
|}
<blockquote>'''Note''':There is a URL character limit of 2000 characters imposed due to browser limitations. Exceeding this value can impair data delivery on particular browsers.</blockquote>

== Setup ==
In order to integrate the Nielsen plugin, follow the steps for setting up these players in the Brightcove user interface as they appear below by each player type.

=== Brightcove Player Setup ===
The new Brightcove Perform player allows two interchangeable ways to add the plugin: on the web site, so the player will come already configured, and programmatically on the client side.

These options, as well as the whole process of adding a plugin is common to the player and described here http://support.brightcove.com/en/perform/docs/configuring-player-plugins

==== For Nielsen SDK plugin, the integrator would need ====
* A list of initialization parameters (Application ID, App Name, sfcode, and nsdkv). Refer to [[#Global Parameters|Global Parameters]] section above.
* A link (URL) to SDK plugin (ggng510.js) for Brightcove
* A list of metadata fields with their names (Nielsen Key Mapping) to pass to the plugin. For more information, refer to [[#Configure Metadata|Configure Metadata]] section.
* Access to the Brightcove VideoCloud Perform Portal https://studio.brightcove.com/products/videocloud/home

==== To add Nielsen SDK plugin using UI do the following ====
Open Brightcove VideoCloud portal, open players list and open (or create) a player the plugin should be added to.
Scroll down to the 'Plugins' section in player configuration

[[File:Plugins-BC.jpg|link=]]

* Click "Edit" and enter the URL to plugin JS file. Click "+" to add the row.

[[File:js-BC.jpg|link=]]

* Then click "Name, Options (JSON)" row and enter "NielsenBC" for the plugin name and required initialization parameters provided by your Nielsen Technical Account Manager, as below:

[[File:Js-BC2.jpg|link=]]

Example Code:
<syntaxhighlight lang="json">{
"nol_sdkDebug": "DEBUG",
"sfcode": "dcr-cert",
"apn": "Test_player_name",
"nsdkv": "511",
"apid": "T4BFBFAC9-XXXX-XXXX-XXXX-22B092CBCC2B",
}</syntaxhighlight>

Adding <code>"nol_sdkDebug": "DEBUG"</code> will allow SDK events in the console.
<blockquote>'''Note''': <code>"nol_sdkDebug": "DEBUG"</code> must be removed when moving a player live to production to disable the debug logging.</blockquote>

==== Pass Content & Ad Metadata to The Brightcove Video Player ====
Pass the required content, and ad metadata to the Brightcove video player so that the Nielsen Plug-In is able to pick it up in order to populate the DCR crediting tags. The Nielsen Plug-In is preconfigured to automatically obtain metadata from Custom Fields. These can be set through the Brightcove User Interface (under ADMIN) or programmatically.

Information on creating Custom Metadatafields can be found on the [https://support.brightcove.com/en/video-cloud/docs/creating-custom-metadata-fields|Brightcove Support site].
<blockquote>'''Note:''' If you are using the Brightcove player with the PERFORM service, you will need to populate the media info. Please contact Brightcove support for details on this process.</blockquote>

[[File:Video-Fields.jpg|link=]]

For more information on how to pass the required metadata to the Brightcove [https://www.brightcove.com/en/online-video-platform VideoCloud] player, please reach out to your Brightcove Account Manager for further assistance.

==== To add Nielsen SDK programmatically ====
* Include plugin source<syntaxhighlight lang="html"><script src="//cdn-gl.imrworldwide.com/novms/bc/3/ggng510.js"></script></syntaxhighlight>
* Bind plugin to the player with inititalization parameters<syntaxhighlight lang="javascript">videojs("myPlayerID").NielsenBC(
{
"apid": "PXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX",
"apn": "Your_player_name",
"sfcode": "dcr-cert",
"nsdkv": "511"
}
}</syntaxhighlight>
* For CMS data binding, the following rules apply
* The plugin automatically captures the following video data
* * Data from video duration is automatically capture by the plugin<syntaxhighlight lang="javascript">nielsenData.length = videoInfo.duration;</syntaxhighlight>
* * Field "type" is set to <code>"content"</code>, <code>"preroll"</code>, <code>"midroll"</code> or <code>"postroll"</code>.
* If video data contains custom fields, all those fields are copied over to Nielsen data: <code>nielsenData[i] = videoInfo.custom_fields[i]</code> (with 'i' iterated over all custom field names), which may override some of the default values or standard field values
* '''The plugin does not automatically assign a value to assetid'''. To pass programmatically, use the custom fields object. (See code example below)
* Parameter videoInfo.id must be a unique string to allow the plugin detecting the content change.

=== Notes ===
* If some CMS metadata values should be set for all videos played, those values can be passed as "defaults" field on the player level (in the player configuration), like this<syntaxhighlight lang="json">{
"apid": "PXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX",
"apn": "Your_player_name",
"sfcode": "dcr",
"nsdkv": "511",
"defaults": { "customValue": "true" }
}</syntaxhighlight>
* CMS metadata values can also be set at the asset level<syntaxhighlight lang="json">{
"sources" :
[ {
"src" : "http://solutions.brightcove.com/../videos/Sea_SeaHorse.mp4",
"type" : "video/mp4"
} ],
"custom_fields":
{
"assetid": "6475587654",
"mediaURL": "http://solutions.brightcove.com/bcls/../videos/Sea_Anemone.mp4",
"dataSrc": "cms",
"hasAds": "1"
},
"name": "Sea Anemone",
"thumbnail": "http://solutions.brightcove.com/bcls/assets/images/Sea_Anemone_poster.png",
"id": "5195888503001"
}
}</syntaxhighlight>

=== Ad Support ===
The plugin will also extract information about the number and length of advertisements played with the video.

== Opt-Out Implementation ==
The site must provide a means for the user to opt out of, or opt back into Nielsen Measurement. A user can opt out if preferring to not participate in any Nielsen online measurement research. To implement the Opt-Out option, include the following in the privacy policy page:
* A notice that the player includes proprietary measurement software that allows users to contribute to market research (such as Nielsen TV Ratings)
* A link to the Nielsen Digital Measurement Privacy Policy at http://www.nielsen.com/digitalprivacy
On the Nielsen Digital Measurement Privacy Policy page, users can click choices to read more detailed information about the measurement software and their options. The users can click a link to retrieve an Opt-Out cookie if they do not want to participate in Nielsen online measurement.

Nielsen properties may feature Nielsen proprietary measurement software, which will allow the users to contribute to market research, such as Nielsen TV Ratings.

To learn more about the information that Nielsen software may collect and your choices with regard to it, please see the Nielsen Digital Measurement Privacy Policy at http://www.nielsen.com/digitalprivacy.

=== Opt-In ===
Once users have opted out, they can choose to opt back into Nielsen Measurement at anytime by selecting the Opt-In link on the Nielsen Digital Privacy Policy page. When a user selects the link, their Opt-Out cookie will be deleted and they will be measured.

== Going Live ==
After the integration is certified, there is one update to be made to the existing code to ensure that the player will be measured properly:
*'''App ID''': Change the apid to the production ID starting with the letter 'P':<syntaxhighlight lang="console">'PXXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX'</syntaxhighlight>
* '''Collection Environment''': Change the value for <code>sfcode</code> from <code>dcr-cert</code> to <code>dcr</code> to point traffic to the Nielsen production collection environment. Do not use <code>dcr-cert</code> for production traffic
<blockquote>'''Note''': Ensure that the <code>nol_sdkDebug</code> parameter is not used.</blockquote>

DTVR Android SDK

2017-09-22T20:27:34Z

Admin2: /* Configure API calls - loadMetadata */

{{Breadcrumb|}} {{Breadcrumb|Digital}} {{Breadcrumb|DCR & DTVR}} {{CurrentBreadcrumb}}
[[Category:Digital]]

== 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''' and '''Sample Player''': A part of the downloaded package
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]] for more information on how to get a Nielsen App SDK and appid.

== Import Library ==
Refer to [[Android SDK API Reference#Setting Up Development Environment|Android SDK API Reference - Setting Up Development Environment]] for information on importing libraries.
* The latest version of App SDK allows instantiating multiple instances of App SDK object and can be used simultaneously without any issues.
<blockquote>Note: The latest version of App SDK contains only appsdk.jar file and does not feature any native shared libraries like libAppSdk.so.</blockquote>

== Initialize SDK ==
Initialize App SDK as soon as the application is launched. Refer to [[Android SDK API Reference#Initialization|Android SDK API Reference - Initialization]] for details on initializing an AppSDK object and the parameters required.

== Configure and fire API calls ==
=== Configure API calls - play ===
Call [[play()]] when starting or resuming a streaming session to pass the channel descriptor information through <code>channelName</code> parameter when the user taps the '''Play''' button on the player.
* <code>channelName</code> is a 32-character free-form text field containing the name of the program or feed being sent (such as ESPN2, Food Network, etc.)
Call [[play()]] with <code>channelName</code> JSON as below.
<syntaxhighlight lang="json"> {
"channelName": "TheMovieTitle"
}</syntaxhighlight>

=== Configure API calls - loadMetadata ===
Load the CMS metadata by calling [[loadMetadata|loadMetadata()]] on the SDK object.
<syntaxhighlight lang="swift"> loadMetadata(JSONObject jsonMetadata);</syntaxhighlight>
Refer to [[Digital Measurement Metadata]] for the list of parameters to be passed in the JSON object.
Call [[loadMetadata()]] for the content after the first [[play()]] call. Call [[loadMetadata()]] with JSON metadata for the active content as below.
<syntaxhighlight lang="json"> {
"type": "content",
"adModel": "1"
}</syntaxhighlight>

=== Configure API calls - sendID3 ===
[[sendID3()]] API is a receiver for HLS timed metadata events (ID3 tags) provided through the notification system. This API filters out Nielsen-specific ID3 tags from the system and buffers the data for transfer to Nielsen’s collection facility. Call [[sendID3()]] whenever new Nielsen ID3 metadata is available for processing during session playback.
==== Sample ID3 tags ====
* <code>www.nielsen.com/X100zdCIGeIlgZnkYj6UvQ==/X100zdCIGeIlgZnkYj6UvQ==/AAAB2Jz2_k74GXSzx4npHuI_JwJd3QSUpW30rDkGTcbHEzIMWleCzM-uvNOP9fzJcQMWQLJqzXMCAxParOb5sGijSV9dNM3QiBniJYGZ5GI-lL1fXTTN0IgZ4iWBmeRiPpS9AAAAAAAAAAAAAAAAAAAAAFJWFM5SVhTONNU=/00000/00000/00</code>
* <code>www.nielsen.com/X100zdCIGeIlgZnkYj6UvQ==/R8WHe7pEBeqBhu8jTeXydg==/AAICoyitYqlxT7n6aZ0oMCGheFi4CXFp46AMUPZz1lMr_M9tr3_cjee1SHqxrOiVerMDLeyn9xzocZSKwi746Re8vNOtpNCAZjYABs_J0R25IHpvOc1HS8QHGgD5TgOJeS6gX100zdCIGeIlgZnkYj6UvVJWFNhSVhTiPE0=/00000/46016/00</code>
<blockquote>'''Note''': ID3 tags are not applicable for International (Germany)</blockquote>

Refer to [[Android SDK API Reference#Retrieving ID3 Tags|Android SDK API Reference - Retrieving ID3 Tags]] section to know more details.

===Configure API calls - stop ===
Call [[stop()]] only when the stream playback is stopped by a user. Common events are; network loss, power / standby, incoming call, alarm, etc. Call [[stop()]] only when buffering continues for 30 seconds (not when it starts). Call [[play()]] when resuming a stream (previously stopped) or starting playback of a new stream.

===Configure API calls - end ===
Call [[end()]] only at the end of playback. Not mandatory if stream is live/does not end.

==API Call sequence==
===Use Case 1: Content has no Advertisements===
Call [[play()]] with <code>channelName</code> JSON as below:
<syntaxhighlight lang="json"> {
"channelName": "TheMovieTitle"
}</syntaxhighlight>

===Use Case 2: Content has linear (non-DAI) Advertisements===
Call [[play()]] (for the first ad) with <code>channelName</code> JSON as below:
<syntaxhighlight lang="json"> {
"channelName": "TheMovieTitle"
}</syntaxhighlight>
Call [[loadMetadata()]] with JSON metadata for the active content as below:
<syntaxhighlight lang="json"> {
"adModel": "1"
}</syntaxhighlight>
Call [[sendID3()]] with ID3 payload
<syntaxhighlight lang="java">
sendID3(payload)
</syntaxhighlight>

== Handling Foreground and Background states of App==

There are two ways of handling the foreground and background states of the client application.
*Let App SDK handle the app states information (foreground / background) and use it, as necessary.
*Capture app states through the application and trigger the corresponding API ([[appInForeground()]] or [[appInBackground()]]) upon every change of state. This allows Nielsen App SDK to know the app state.

=== New devices (Android 4.0 and later versions) ===

'''Add ''application'' tag to Manifest XML file'''
When a client’s app supports only new devices (Android 4.0 and above) and the client has not implemented a custom Application class for some other purpose,
* Add the following entry (application tag) into the Manifest XML file to use SDK’s state detection feature.
<syntaxhighlight lang="xml"> <application android:name="com.nielsen.app.sdk.AppSdkApplication"></syntaxhighlight>
This is the custom Application class where the whole background detection implementation is done. No new permissions are required to change the properties in Manifest XML file.

=== Older devices (Android 4.0 or earlier version) ===

Identify the change of state through the application and call the respective API ([[appInForeground()]] or [[appInBackground()]]) upon every change of state (foreground / background). The SDK will use this information to pass the app launch times, etc. to Collection facility.
<syntaxhighlight lang="java">
AppLaunchMeasurementManager.appInForeground(getApplicationContext());
AppLaunchMeasurementManager.appInBackground(getApplicationContext());
</syntaxhighlight>

== Interruptions during playback ==
As part of integrating Nielsen App SDK with the player application, the Audio / Video app developer needs to handle the following possible interruption scenarios:
* Pause / Play
* Network Loss (Wi-Fi / Airplane / Cellular)
* Call Interrupt (SIM or Third party Skype / Hangout call)
* Alarm Interrupt
* Content Buffering
* Device Lock / Unlock (Video players only, not for Audio players)
* App going in the Background/Foreground (Video players only, not for Audio players)
* Channel / Station Change Scenario
* Unplugging of headphone
In case of encountering one of the above interruptions, the player application needs to
* Call [[stop()]] immediately (except when content is buffering) and withhold sending playhead position.
* Start sending pings – [[loadMetadata()]] and [[sendID3()]] for the new viewing session, once the playback resumes.
Please see the [[Digital Measurement FAQ]] for more details

== Nielsen Measurement Opt-Out Implementation ==
As a global information and measurement leader, we are committed to protecting the privacy and security of the data we collect, process and use. Our digital measurement products are not used to identify the consumer in any way, but 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.
* When the app user wants to opt in or opt out of Nielsen measurement, a new dynamic page (with content string obtained from [[userOptOutURLString()]]) should be displayed.
** Use [[getOptOutStatus()]] to retrieve the device’s Opt-Out status.
* This Opt-out page should be displayed in a webview (within the app) and not in any external browser.
* Capture the user’s selection in this page and pass it to the SDK through [[userOptOut()]] for Nielsen to save the user’s preference.
* For more details, refer to [[Android SDK API Reference#Android Opt-Out Implementation|Android SDK API Reference - Android Opt-Out Implementation]] and Nielsen Digital Privacy.

== Testing an Implementation - App ==
See [[Digital Measurement Testing]].

DTVR iOS SDK

2017-09-22T20:27:05Z

Admin2: /* Configure API calls - loadMetadata */

Digital Measurement Metadata

2017-09-19T19:49:20Z

Admin2:

{{Breadcrumb|}} {{Breadcrumb|Digital}} {{Breadcrumb|DCR & DTVR}} {{CurrentBreadcrumb}}
[[Category:Digital]]

The metadata received for each asset is used for classification and reporting. There are reserved Nielsen keys for collecting the required metadata.

=== Reserved Keys ===
Content and Ad Metadata can be passed through key-values using the Nielsen reserved keys. The last column in the table below indicates metadata parameters that will be displayed in reporting.

==== Content Metadata ====
{| class="wikitable"
|-
! Key !! Description !! Values !! Required for Audio/Video? !! Required for Static (page)? !! Reported for
|-
| clientid || Brand value is automatically populated through the App ID provided. The value passed here will override the default value. (e.g. Multiple brands in App) || custom || Optional || Optional || Audio / Video and Static Measurement
|-
| vcid || VCID value is automatically populated through the App ID provided. This value passed here will override the default value. (e.g. Multiple Sub-brands in App) || custom || Optional || Optional || Audio / Video and Static Measurement
|-
| type ||
Type of measurement:
*audio / video – "content"
*page – "static"
*ad – "preroll", "midroll" or "postroll"
|| "content", "static" || Mandatory || Mandatory ||
|-
| assetid || ID assigned to content. Must be unique across all content at the episode level. || custom || Mandatory || Not Required ||
|-
| section || Section of site || custom || Not Required || Mandatory ||
|-
| isfullepisode || Full episode flag ||
*"y" or "lf" - full episode
*"n" or "sf" - short form
|| Mandatory || Not Required ||
|-
| program || Program name || custom || Mandatory || Not Required || Audio / Video Measurement
|-
| title || Episode title || custom || Mandatory || Not Required || Audio / Video Measurement
|-
| length || Length of content in seconds for VOD. The estimated content length has to be passed for live content. || custom || Mandatory || Not Required ||
|-
| segA || Segment A (this is not available for audio / video Measurement reporting as the episode title is reported) || custom || Not Required || Not Required || Static Measurement
|-
| segB || Segment B || custom || Not Required || Not Required || Audio / Video and Static Measurement
|-
| segC || Segment C || custom || Not Required || Not Required || Audio / Video and Static Measurement
|-
| crossId1 || Standard episode ID || custom || Optional || Not Required ||
|-
| crossId2 || Content originator (required only for distributors) || custom || Optional || Not Required ||
|-
| airdate || Original (local) air date and time (Eastern Time for US) || YYYYMMDD HH24:MI:SS || Mandatory || Not Required ||
|-
| pipmode ||
Current state of picture-in-picture (PIP) mode on device.
*"true" if audio / video measurement is displayed in PIP mode
*"false" if audio / video measurement is displayed in regular mode
|| "true", "false" || Mandatory || Not Required || Audio / Video Measurement
|-
| adloadtype ||
Type of ad load:
#Linear - matches TV ad load
#Dynamic - Dynamic Ad Insertion (DAI)
|| "1" - Linear
"2" - Dynamic
|| Mandatory || Not Required ||
|-
| progen || Genre (required only for OTT) || e.g. DD for Daytime Drama || Optional || Not Required
|}

'''clientid & subbrand (vcid)'''
By default, clientid and subbrand are setup in Nielsen backend configuration to capture brand and sub-brand information. The fields get populated from backend for a registered client appid. But if an app contains multiple brands and sub-brands and client is willing to give credit to another brand or sub-brand then :
*Client app developer can override the clientid and subbrand (brand and sub-brand info.) in [[loadMetadata]] call to get a proper measurement for a desired brand and sub-brand.
**If no clientid and subbrand are specified in CMS of a content and an ad, default values reported in the Configuration will be reported.
**If clientid and subbrand are specified in CMS of the content or ad, the most recent clientid and subbrand will be reported in subsequent pings. To report with a different clientid and subbrand, include the new values for the keys in their subsequent [[loadMetadata]] call.
'''Picture-in-picture (PIP) mode'''
Once the app detects PIP mode, call [[loadMetadata]] with the same set of assetids, values and with one additional parameter "pipmode": "true". Once PIP mode is disabled in the device, call [[loadMetadata]] again with "pipmode":"false".

==== Custom Variables Extension ====
Contact Nielsen Technical Account Manager (TAM) to configure any custom variables, as needed for implementing the application.

See [[Custom Variables Extension]] for more information.

==== Advertisement Metadata ====
{| class="wikitable"
|-
! Key !! Description !! Values !! Required for Audio / Video? !! Required for Static (page)
|-
| type || Type of ad || "preroll"
"midroll"
"postroll"
|| Mandatory || Not Required
|-
| assetid || An ID assigned to the advertisement. Can be an internal ID, an ID provided by the ad server, or a randomly generated ID. Must be unique across all ads || custom || Mandatory || Not Required
|-
| title || Title of the advertisement || "MyAdName" || Mandatory || Not Required
|}

=== Passing Metadata ===
The required metadata can be passed as key values through the loadMetadata method. The sample code below shows a metadata objects for various assets.
'''Audio / Video Measurement Asset'''
Type should be "content"
<syntaxhighlight lang="json"> {
"type": "content",
"assetName": "myassetName",
"length": "300",
"title": "myTitle",
"program": "myProgram",
"censuscategory": "myCensusCategory",
"assetid": "myAssetId",
"channelName": "myChannel",
"adloadtype": "2",
"segB": "segmentB",
"segC": "segmentC",
"isfullepisode":"y",
"crossId1": "Reference11",
"crossId2": "Reference22",
"airdate": "20161013 20:00:00"
}</syntaxhighlight>

'''Static (Page) Measurement Asset'''
Type should be "static"
<syntaxhighlight lang="json"> {
"type": "static",
"assetid": "static123",
"assetName": "Page-Asset",
"section": "siteSection",
"segA": "segmentA",
"segB": "segmentB",
"segC": "segmentC"
}</syntaxhighlight>

'''For any of the ad types'''
<syntaxhighlight lang="json"> {
"type": "midroll",
"length": "30",
"assetid": "myMidrollAssetId",
"adModel": "2",
"tv": "true",
"dataSrc": "cms"
}</syntaxhighlight>
<blockquote>'''Note''': In case the individual ad details are not available, send ad pod (presence) details through the <code>loadMetadata</code> and playhead position through <code>setPlayheadPosition</code>.</blockquote>

'''loadMetadata'''
The object can then be passed when calling [[loadMetadata]].
<syntaxhighlight lang="java"> loadMetadata(jsonMetadataObject);</syntaxhighlight>

Digital Pre-Certification Checklist App SDK

2017-09-12T20:38:43Z

Admin2: /* loadMetadata() - Content */

== Pre-certification Checklist - VOD with Ads ==
Before starting the certification process, please verify the following steps have been completed.
* Your Client Service representative should have already discussed a reporting hierarchy with you -- along with a Parent, Brand, and Sub-brand/Channel
* Your Technical Account Manager should have:
** provided you with an AppID
** informed you of our Opt-Out requirement for your App/Play Store description
** informed you of our Opt-Out requirement for a WebView inside your apps
* Retrieving AppSDK logs
** ‘nol_devDebug’ : ‘DEBUG’ should be present in initialization call (see below)
** Android: use adb logcat (note: requires Android Studio)
** iOS: idevicesyslog (note: requires XCode)

== Initialization ==
The first step in the Certification process is to ensure that the Nielsen SDK is initializing at app startup, and that the global metadata values are present.
{| class="wikitable"
|-
! Keys !! Value
|-
| appid || <code>PXXXXX-XXXXXX-XXXXX-XXXXX</code>
|-
| appname || <code>example app name</code>
|-
| appversion || <code>2.0</code>
|-
| nol_devDebug || <code>debug</code>
|}

'''iOS Example'''
<syntaxhighlight lang="objective-c">NSDictionary* appInformation = @
{ // AppID is Nielsen-supplied
@"appid": @"PXXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX",
@"appname": @"Sample App Name",
@"appversion": @"2.0",
@"nol_devDebug": @"DEBUG" // required for testing only
}</syntaxhighlight>

'''Android Example'''
<syntaxhighlight lang="java">JSONObject appSdkConfig = new JSONObject()
.put("appid", "PXXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX")
.put("appname", "Sample App Name")
.put("appversion","2.0")
.put("nol_devDebug”, "DEBUG"); // required for testing only
// Pass appSdkConfig to the AppSdk constructor
mAppSdk = new AppSdk(appContext, appSdkConfig, appSdkListener);</syntaxhighlight>

== Test Cases ==
The following lists the test cases along with the Expected results:
{| class="wikitable"
|-
! Test Case !! Param !! Expected Result !! Pass/Fail
|-
| SDK Initialized || <code>appid</code> || Correct app id ||
|-
| || <code>appname</code> || Player name ||
|-
| || <code>appversion</code> || Correct build ||
|-
| || <code>nol_devDebug</code> || <code>'DEBUG</code> ||
|}

=== play() ===
* The <code>play()</code> call is required only once per viewing session (until app is killed)
* Called just before playback commences for first piece of content
{| class="wikitable"
|-
! Test Case !! Param !! Expected Result !! Pass/Fail
|-
| Play || <code>channelname</code> || Name of Channel ||
|}

=== loadMetadata() - Content ===
* Called at beginning of content, or when resuming content from interruption
{| class="wikitable"
|-
! Test !! Param !! Example Value !! Accepted Values !! Pass/Fail
|-
| loadMetadata || <code>type</code> || <code>"content"</code> || <code>"content"</code> ||
|-
| || <code>assetid</code> || <code>"unique_id_500291"</code> || (unique per asset) ||
|-
| || <code>length</code> || <code>"600"</code> || length in seconds (int or float) ||
|-
| || <code>title</code> || <code>"Episode Title"</code> || (any non-empty value) ||
|-
| || <code>program</code> || <code>"Show Name"</code> || (any non-empty value) ||
|-
| || <code>segB</code> || <code>"Primetime"</code> || (any value), used for optional breakdown ||
|-
| || <code>segC</code> || <code>"Comedy"</code> || (any value), used for optional breakdown ||
|-
| || <code>crossId1</code> || <code>"EP018S9S290015"</code> || Gracenote ID ||
|-
| || <code>crossId2</code> || <code>"ABC"</code> || Network Name ||
|-
| || <code>isfullepisode</code> || <code>"y"</code> || (<code>"y"</code> or <code>"n"</code>) (<code>"Y"</code> or <code>"N"</code>) ||
|-
| || <code>airdate</code> || <code>"20160206 23:00:00</code> || <code>"YYYYMMDD[space]HH:MM:SS"</code> -- note: HH=24 hour time ||
|-
| || <code>adloadtype</code> || <code>"1"</code> || <code>"1"</code> for linear ads, <code>"2"</code> for DAI ||
|-
| || <code>hasAds</code> || <code>"1"</code> || <code>"0"</code> for no ads, <code>"1"</code> for has ads ||
|}

=== loadMetadata() - ad ===
* Called at beginning of ad, or when resuming ad from interruption
{| class="wikitable"
|-
! Test !! Param !! Example Value !! Accepted Values !! Pass/Fail
|-
| loadMetadata || <code>assetid</code> || <code>"ad_2201343201"</code> || (any non-empty value) ||
|-
| || <code>type</code> || <code>"midroll"</code> || <code>"preroll"</code>, <code>"midroll"</code>, <code>"postroll"</code> || Example
|}

=== setPlayheadPosition() - Preroll ad ===
* Track current position of playhead
* Starts at 0 at the beginning of ad
* Updated at least once per second
* Separate playhead position for ads and content, should accurately reflect current position in either ads or content
* Final playhead position for content must equal the length specified in loadMetadata(), followed by end() call
{| class="wikitable"
|-
! Test Case !! Test Condition !! Pass/Fail
|-
| <code>setPlayehadPosition</code> || Called every second ||
|-
| <code>stop()</code> || Called at the end of Ad ||
|}

=== loadMetadata() - Content ===
* Test is to validate Content metadata is the same as original metadata passed during initial loadMetadata call.
{| class="wikitable"
|-
! Test !! Param !! Example Value !! Accepted Values !! Pass/Fail
|-
| loadMetadata || <code>type</code> || <code>"content"</code> || <code>"content"</code> ||
|-
| || <code>assetid</code> || <code>"unique_id_500291"</code> || (unique per asset) ||
|-
| || <code>length</code> || <code>"600"</code> || length in seconds (int or float) ||
|-
| || <code>title</code> || <code>"Episode Title"</code> || (any non-empty value) ||
|-
| || <code>program</code> || <code>"Show Name"</code> || (any non-empty value) ||
|-
| || <code>segB</code> || <code>"Primetime"</code> || (any value), used for optional breakdown ||
|-
| || <code>segC</code> || <code>"Comedy"</code> || (any value), used for optional breakdown ||
|-
| || <code>crossId1</code> || <code>"EP018S9S290015"</code> || Gracenote ID ||
|-
| || <code>crossId2</code> || <code>"ABC"</code> || Network Name ||
|-
| || <code>isfullepisode</code> || <code>"y"</code> || (<code>"y"</code> or <code>"n"</code>) (<code>"Y"</code> or <code>"N"</code>) ||
|-
| || <code>airdate</code> || <code>"20160206 23:00:00</code> || <code>"YYYYMMDD[space]HH:MM:SS"</code> -- note: HH=24 hour time ||
|-
| || <code>adloadtype</code> || <code>"1"</code> || <code>"1"</code> for linear ads, <code>"2"</code> for DAI ||
|-
| || <code>hasAds</code> || <code>"1"</code> || <code>"0"</code> for no ads, <code>"1"</code> for has ads ||
|}

=== setPlayheadPosition() - Content ===
* Track current position of playhead
* Starts at 0 at the beginning of content
* Updated at least once per second
* Separate playhead position for ads and content, should accurately reflect current position in either ads or content
* Final playhead position for content must equal the length specified in loadMetadata(), followed by end() call
{| class="wikitable"
|-
! Test Case !! Test Condition !! Pass/Fail
|-
| <code>setPlayehadPosition</code> || Called every second ||
|-
| <code>stop()</code> || Called at the end of Content ||
|}

=== stop() ===
* Indicates one of the following:
* Playback of content or ad was interrupted
* Reached end of ad (no parameters or metadata)

=== end() ===
* Reached the end of content (no parameters or metadata)

== Interruptions ==
* All interruptions to playback of content or ads should trigger a call to stop(). Once the interruption is over, loadMetadata() with the same metadata should be called, followed by playheadPosition resuming from where it left off.

* Interruptions include:
** user-induced pause
** screen turned off
** app sent to background
** headphones removed (note, if app simply switches audio output from headphones to speaker without pausing, there is no need to call stop())
** alarm/call interruption
** internet connection lost (n.b. cached playback plays as normal until it expires)
{| class="wikitable"
|-
! Test Case !! Test Condition !! Pass/Fail
|-
| user-induced pause || <code>stop()</code>, <code>loadMetadata()</code> & <code>playheadPosition</code> ||
|-
| screen turned off || <code>stop()</code>, <code>loadMetadata()</code> & <code>playheadPosition</code> ||
|-
| app sent to background || <code>stop()</code>, <code>loadMetadata()</code> & <code>playheadPosition</code> ||
|-
| headphones removed || <code>stop()</code>, <code>loadMetadata()</code> & <code>playheadPosition</code> ||
|-
| alarm/call interruption || <code>stop()</code>, <code>loadMetadata()</code> & <code>playheadPosition</code> ||
|-
| internet connection lost || <code>stop()</code>, <code>loadMetadata()</code> & <code>playheadPosition</code> ||
|-
| content paused || <code>playheadPosition</code> is not passed ||
|-
| resume content || <code>loadMetadata()</code> is called for content ||
|-
| || <code>loadMetadataM</code> is the same as original ||
|-
| || <code>playheadPosition</code> continues from resumed position ||
|}

'''Expected SDK behavior for all interruptions:'''
# interruption triggers stop() call
# when content resumes, loadMetadata() is called with the same metadata that was playing previously (ad or content)
# playheadPosition() resumes from the same position before the interruption

'''Example session:'''
* 5 minutes of content played, call interruption, content resumes until end of 15 min video

== Scrubbing ==
{| class="wikitable"
|-
! Test Case !! Test Condition !! Pass/Fail
|-
| Scrub Backward || new playhead position is accurate ||
|-
| || new playhead continues from new position ||
|-
| Scrub Forward || new playhead position is accurate ||
|-
| || new playhead continues from new position ||
|-
| Scrub to end || final playhead position is passed ||
|-
| || end event called at completion of content playback ||
|-
| Scrub past midroll || Playhead for content stops ||
|}

== Midroll & Postroll Ads ==
{| class="wikitable"
|-
! Test Case !! Test Condition !! Pass/Fail
|-
| <code>loadMetadata()</code> || Called for each Ad ||
|-
| || Required Metadata is accurate ||
|-
| <code>playheadPosition</code> || Passed every second ||
|-
| <code>stop()</code> || called for each ad ||
|-
| <code>loadMetadata()</code>, <code>playheadPosition</code>, <code>stop()</code> || correct sequence for each ad ||
|}

== Opt-Out ==
Users must have access to "About Nielsen Measurement" page. User can click this page from app settings screen.
* URL to this web page should be called from SDK by invoking optOutURL and opened in 'WebView' / External browser.
* 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 optOutStatus method.
{| class="wikitable"
|-
! Test Case !! Test Condition !! Pass/Fail
|-
| <code>optOutView</code> || User can Opt-Out ||
|}

Digital Pre-Certification Checklist App SDK

2017-09-12T17:47:07Z

Admin2: Does not need to be fired before every playhead position update, this will cause the SDK to not credit any seconds of viewing.

== Pre-certification Checklist - VOD with Ads ==
Before starting the certification process, please verify the following steps have been completed.
* Your Client Service representative should have already discussed a reporting hierarchy with you -- along with a Parent, Brand, and Sub-brand/Channel
* Your Technical Account Manager should have:
** provided you with an AppID
** informed you of our Opt-Out requirement for your App/Play Store description
** informed you of our Opt-Out requirement for a WebView inside your apps
* Retrieving AppSDK logs
** ‘nol_devDebug’ : ‘DEBUG’ should be present in initialization call (see below)
** Android: use adb logcat (note: requires Android Studio)
** iOS: idevicesyslog (note: requires XCode)

== Initialization ==
The first step in the Certification process is to ensure that the Nielsen SDK is initializing at app startup, and that the global metadata values are present.
{| class="wikitable"
|-
! Keys !! Value
|-
| appid || <code>PXXXXX-XXXXXX-XXXXX-XXXXX</code>
|-
| appname || <code>example app name</code>
|-
| appversion || <code>2.0</code>
|-
| nol_devDebug || <code>debug</code>
|}

'''iOS Example'''
<syntaxhighlight lang="objective-c">NSDictionary* appInformation = @
{ // AppID is Nielsen-supplied
@"appid": @"PXXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX",
@"appname": @"Sample App Name",
@"appversion": @"2.0",
@"nol_devDebug": @"DEBUG" // required for testing only
}</syntaxhighlight>

'''Android Example'''
<syntaxhighlight lang="java">JSONObject appSdkConfig = new JSONObject()
.put("appid", "PXXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX")
.put("appname", "Sample App Name")
.put("appversion","2.0")
.put("nol_devDebug”, "DEBUG"); // required for testing only
// Pass appSdkConfig to the AppSdk constructor
mAppSdk = new AppSdk(appContext, appSdkConfig, appSdkListener);</syntaxhighlight>

== Test Cases ==
The following lists the test cases along with the Expected results:
{| class="wikitable"
|-
! Test Case !! Param !! Expected Result !! Pass/Fail
|-
| SDK Initialized || <code>appid</code> || Correct app id ||
|-
| || <code>appname</code> || Player name ||
|-
| || <code>appversion</code> || Correct build ||
|-
| || <code>nol_devDebug</code> || <code>'DEBUG</code> ||
|}

=== play() ===
* The <code>play()</code> call is required only once per viewing session (until app is killed)
* Called just before playback commences for first piece of content
{| class="wikitable"
|-
! Test Case !! Param !! Expected Result !! Pass/Fail
|-
| Play || <code>channelname</code> || Name of Channel ||
|}

=== loadMetadata() - Content ===
* Called at beginning of content, or when resuming content from interruption
* Fires before any playheadPosition update
{| class="wikitable"
|-
! Test !! Param !! Example Value !! Accepted Values !! Pass/Fail
|-
| loadMetadata || <code>type</code> || <code>"content"</code> || <code>"content"</code> ||
|-
| || <code>assetid</code> || <code>"unique_id_500291"</code> || (unique per asset) ||
|-
| || <code>length</code> || <code>"600"</code> || length in seconds (int or float) ||
|-
| || <code>title</code> || <code>"Episode Title"</code> || (any non-empty value) ||
|-
| || <code>program</code> || <code>"Show Name"</code> || (any non-empty value) ||
|-
| || <code>segB</code> || <code>"Primetime"</code> || (any value), used for optional breakdown ||
|-
| || <code>segC</code> || <code>"Comedy"</code> || (any value), used for optional breakdown ||
|-
| || <code>crossId1</code> || <code>"EP018S9S290015"</code> || Gracenote ID ||
|-
| || <code>crossId2</code> || <code>"ABC"</code> || Network Name ||
|-
| || <code>isfullepisode</code> || <code>"y"</code> || (<code>"y"</code> or <code>"n"</code>) (<code>"Y"</code> or <code>"N"</code>) ||
|-
| || <code>airdate</code> || <code>"20160206 23:00:00</code> || <code>"YYYYMMDD[space]HH:MM:SS"</code> -- note: HH=24 hour time ||
|-
| || <code>adloadtype</code> || <code>"1"</code> || <code>"1"</code> for linear ads, <code>"2"</code> for DAI ||
|-
| || <code>hasAds</code> || <code>"1"</code> || <code>"0"</code> for no ads, <code>"1"</code> for has ads ||
|}

=== loadMetadata() - ad ===
* Called at beginning of ad, or when resuming ad from interruption
{| class="wikitable"
|-
! Test !! Param !! Example Value !! Accepted Values !! Pass/Fail
|-
| loadMetadata || <code>assetid</code> || <code>"ad_2201343201"</code> || (any non-empty value) ||
|-
| || <code>type</code> || <code>"midroll"</code> || <code>"preroll"</code>, <code>"midroll"</code>, <code>"postroll"</code> || Example
|}

=== setPlayheadPosition() - Preroll ad ===
* Track current position of playhead
* Starts at 0 at the beginning of ad
* Updated at least once per second
* Separate playhead position for ads and content, should accurately reflect current position in either ads or content
* Final playhead position for content must equal the length specified in loadMetadata(), followed by end() call
{| class="wikitable"
|-
! Test Case !! Test Condition !! Pass/Fail
|-
| <code>setPlayehadPosition</code> || Called every second ||
|-
| <code>stop()</code> || Called at the end of Ad ||
|}

=== loadMetadata() - Content ===
* Test is to validate Content metadata is the same as original metadata passed during initial loadMetadata call.
{| class="wikitable"
|-
! Test !! Param !! Example Value !! Accepted Values !! Pass/Fail
|-
| loadMetadata || <code>type</code> || <code>"content"</code> || <code>"content"</code> ||
|-
| || <code>assetid</code> || <code>"unique_id_500291"</code> || (unique per asset) ||
|-
| || <code>length</code> || <code>"600"</code> || length in seconds (int or float) ||
|-
| || <code>title</code> || <code>"Episode Title"</code> || (any non-empty value) ||
|-
| || <code>program</code> || <code>"Show Name"</code> || (any non-empty value) ||
|-
| || <code>segB</code> || <code>"Primetime"</code> || (any value), used for optional breakdown ||
|-
| || <code>segC</code> || <code>"Comedy"</code> || (any value), used for optional breakdown ||
|-
| || <code>crossId1</code> || <code>"EP018S9S290015"</code> || Gracenote ID ||
|-
| || <code>crossId2</code> || <code>"ABC"</code> || Network Name ||
|-
| || <code>isfullepisode</code> || <code>"y"</code> || (<code>"y"</code> or <code>"n"</code>) (<code>"Y"</code> or <code>"N"</code>) ||
|-
| || <code>airdate</code> || <code>"20160206 23:00:00</code> || <code>"YYYYMMDD[space]HH:MM:SS"</code> -- note: HH=24 hour time ||
|-
| || <code>adloadtype</code> || <code>"1"</code> || <code>"1"</code> for linear ads, <code>"2"</code> for DAI ||
|-
| || <code>hasAds</code> || <code>"1"</code> || <code>"0"</code> for no ads, <code>"1"</code> for has ads ||
|}

=== setPlayheadPosition() - Content ===
* Track current position of playhead
* Starts at 0 at the beginning of content
* Updated at least once per second
* Separate playhead position for ads and content, should accurately reflect current position in either ads or content
* Final playhead position for content must equal the length specified in loadMetadata(), followed by end() call
{| class="wikitable"
|-
! Test Case !! Test Condition !! Pass/Fail
|-
| <code>setPlayehadPosition</code> || Called every second ||
|-
| <code>stop()</code> || Called at the end of Content ||
|}

=== stop() ===
* Indicates one of the following:
* Playback of content or ad was interrupted
* Reached end of ad (no parameters or metadata)

=== end() ===
* Reached the end of content (no parameters or metadata)

== Interruptions ==
* All interruptions to playback of content or ads should trigger a call to stop(). Once the interruption is over, loadMetadata() with the same metadata should be called, followed by playheadPosition resuming from where it left off.

* Interruptions include:
** user-induced pause
** screen turned off
** app sent to background
** headphones removed (note, if app simply switches audio output from headphones to speaker without pausing, there is no need to call stop())
** alarm/call interruption
** internet connection lost (n.b. cached playback plays as normal until it expires)
{| class="wikitable"
|-
! Test Case !! Test Condition !! Pass/Fail
|-
| user-induced pause || <code>stop()</code>, <code>loadMetadata()</code> & <code>playheadPosition</code> ||
|-
| screen turned off || <code>stop()</code>, <code>loadMetadata()</code> & <code>playheadPosition</code> ||
|-
| app sent to background || <code>stop()</code>, <code>loadMetadata()</code> & <code>playheadPosition</code> ||
|-
| headphones removed || <code>stop()</code>, <code>loadMetadata()</code> & <code>playheadPosition</code> ||
|-
| alarm/call interruption || <code>stop()</code>, <code>loadMetadata()</code> & <code>playheadPosition</code> ||
|-
| internet connection lost || <code>stop()</code>, <code>loadMetadata()</code> & <code>playheadPosition</code> ||
|-
| content paused || <code>playheadPosition</code> is not passed ||
|-
| resume content || <code>loadMetadata()</code> is called for content ||
|-
| || <code>loadMetadataM</code> is the same as original ||
|-
| || <code>playheadPosition</code> continues from resumed position ||
|}

'''Expected SDK behavior for all interruptions:'''
# interruption triggers stop() call
# when content resumes, loadMetadata() is called with the same metadata that was playing previously (ad or content)
# playheadPosition() resumes from the same position before the interruption

'''Example session:'''
* 5 minutes of content played, call interruption, content resumes until end of 15 min video

== Scrubbing ==
{| class="wikitable"
|-
! Test Case !! Test Condition !! Pass/Fail
|-
| Scrub Backward || new playhead position is accurate ||
|-
| || new playhead continues from new position ||
|-
| Scrub Forward || new playhead position is accurate ||
|-
| || new playhead continues from new position ||
|-
| Scrub to end || final playhead position is passed ||
|-
| || end event called at completion of content playback ||
|-
| Scrub past midroll || Playhead for content stops ||
|}

== Midroll & Postroll Ads ==
{| class="wikitable"
|-
! Test Case !! Test Condition !! Pass/Fail
|-
| <code>loadMetadata()</code> || Called for each Ad ||
|-
| || Required Metadata is accurate ||
|-
| <code>playheadPosition</code> || Passed every second ||
|-
| <code>stop()</code> || called for each ad ||
|-
| <code>loadMetadata()</code>, <code>playheadPosition</code>, <code>stop()</code> || correct sequence for each ad ||
|}

== Opt-Out ==
Users must have access to "About Nielsen Measurement" page. User can click this page from app settings screen.
* URL to this web page should be called from SDK by invoking optOutURL and opened in 'WebView' / External browser.
* 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 optOutStatus method.
{| class="wikitable"
|-
! Test Case !! Test Condition !! Pass/Fail
|-
| <code>optOutView</code> || User can Opt-Out ||
|}

DAR Android SDK

2017-08-29T19:28:19Z

Admin2: /* SDK Integration */

{{Breadcrumb|}} {{Breadcrumb|Digital}} {{Breadcrumb|Digital Ad Ratings}} {{CurrentBreadcrumb}}
[[Category:Digital]]

== 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''' and '''Sample Player''': A part of the downloaded package
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]] for more information on how to get a Nielsen App SDK and appid.

== Import Library ==
Refer to [[Android SDK API Reference#Importing Frameworks|Android SDK API Reference - Importing Frameworks]] for information on importing libraries.
* The latest version of App SDK allows instantiating multiple instances of App SDK object and can be used simultaneously without any issues.
<blockquote>'''Note:''' The latest version of App SDK contains only appsdk.jar file and does not feature any native shared libraries like libAppSdk.so.</blockquote>

== Initialize SDK ==
Initialize App SDK as soon as the application is launched. Refer to [[Android SDK API Reference#Initialization|Android SDK API Reference - Initialization]] for details on initializing an AppSDK object and the parameters required.

== Configure API calls ==

=== loadMetadata ===
DAR tags are used to track commercial delivery for campaign ratings. DAR tags are received during the streaming session from the Content Management System (CMS) identifying that the video contains ad content. This information should be passed as a JSON object via the [[loadMetadata()]] method with DAR contents.

=== DAR Tags ===
Nielsen DAR tag may come in different forms from ad service via VAST XML or ad service integrated player framework library. The CMS data must be passed as a JSON object.
<syntaxhighlight lang="java">
loadMetadata(JSONObject jsonMetadata);
</syntaxhighlight>

Refer to [[Digital Measurement Metadata]] section for the parameters to be passed in the JSON object.

The DAR tags received from your CMS system should be transformed into a JSON string and passed in via the [[loadMetadata()]] method.

{| class="wikitable"
|-
! Variable Name !! Variable Description !! Example
|-
| type || Type identifies the tag content type. For DAR, the data type should be always set to "ad". || ad
|-
| ocrtag || The complete tag/URL is supplied by your Technical Account Manager. This should include the complete URL including the http portion. The ocrtag should be properly URI encoded. || <nowiki>http://secure-uat-cert.imrworldwide.com</nowiki>/cgi-bin/m?ci= ENTXX5&am=3&ep=1&at=view&rt=banner&st= image&ca=XX1717&cr=crvXX35&pc=plc1234
|}

=== SDK Integration ===
After getting the string from an ad service, to integrate Nielsen SDK for DAR tag, the app should first identify a Nielsen beacon in the use cases below
* If the input string is CDATA string, get the value of the CDATA as a new input string.
* If the input string (or new input string) starts with http and the hostname ends with “imrworldwide.com”, the input string is a Nielsen beacon (case 1 and case 3).
* If the input string (or new input string) starts with http and the CR field exists
** Get the value of the CR field.
** If the CR value starts with http and the hostname of the CR value ends with “imrworldwide.com”, the CR value is a Nielsen beacon (case 2 and case 4).
** If the Nielsen beacon exists, remove the value of the CR field from the input string and process the updated string for the non-DAR beacon.
* If the Nielsen beacon exists
** URL decode the Nielsen beacon.
** If the c13 field exists in the Nielsen beacon, remove the c13 from the Nielsen beacon.
** Create JSON with the Nielsen beacon
<syntaxhighlight lang="json">
{
"type": "ad",
"ocrtag": "<Nielsen beacon>"
}</syntaxhighlight>
* '''EXAMPLE''': Sample JSON string with the DAR string (decoded http string without the c13)<syntaxhighlight lang="json">
{
"type": "ad",
"ocrtag": "http://secure-gl.imrworldwide.com/cgi-bin/m?ci=ent30986&am=22&ep=1&at=view&rt=banner&st=image&ca=cmp97144&cr=1186239&pc=3739659&r=2011370876"
}
</syntaxhighlight>
** Send the JSON to the Nielsen SDK using loadMetadata.

== Nielsen Measurement Opt-Out Implementation ==
As a global information and measurement leader, we are committed to protecting the privacy and security of the data we collect, process and use. Our digital measurement products are not used to identify the consumer in any way, but 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.
* When the app user wants to opt in or opt out of Nielsen measurement, a new dynamic page (with content string obtained from [[userOptOutURLString()]]) should be displayed.
** Use [[getOptOutStatus()]] to retrieve the device’s Opt-Out status.
* This Opt-out page should be displayed in a webview (within the app) and not in any external browser.
* Capture the user’s selection in this page and pass it to the SDK through [[userOptOut()]] for Nielsen to save the user’s preference.
* For more details, refer to [[Android SDK API Reference#Android Opt-Out Implementation|Android SDK API Reference - Android Opt-Out Implementation]] and Nielsen Digital Privacy.
<blockquote>'''Note:''' The SDK will continue measurement even after the user has opted out from Nielsen measurement.</blockquote>

=== Pre-Certification Checklists ===
After the application is ready to be sent for Nielsen Certification, please go through the Pre-Certification Checklist and ensure the app behaves as expected, before submitting to Nielsen.

=== Testing an Implementation - App ===
See [[Digital Measurement Testing]].

DAR Android SDK

2017-08-29T19:19:34Z

Admin2: /* SDK Integration */

{{Breadcrumb|}} {{Breadcrumb|Digital}} {{Breadcrumb|Digital Ad Ratings}} {{CurrentBreadcrumb}}
[[Category:Digital]]

== 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''' and '''Sample Player''': A part of the downloaded package
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]] for more information on how to get a Nielsen App SDK and appid.

== Import Library ==
Refer to [[Android SDK API Reference#Importing Frameworks|Android SDK API Reference - Importing Frameworks]] for information on importing libraries.
* The latest version of App SDK allows instantiating multiple instances of App SDK object and can be used simultaneously without any issues.
<blockquote>'''Note:''' The latest version of App SDK contains only appsdk.jar file and does not feature any native shared libraries like libAppSdk.so.</blockquote>

== Initialize SDK ==
Initialize App SDK as soon as the application is launched. Refer to [[Android SDK API Reference#Initialization|Android SDK API Reference - Initialization]] for details on initializing an AppSDK object and the parameters required.

== Configure API calls ==

=== loadMetadata ===
DAR tags are used to track commercial delivery for campaign ratings. DAR tags are received during the streaming session from the Content Management System (CMS) identifying that the video contains ad content. This information should be passed as a JSON object via the [[loadMetadata()]] method with DAR contents.

=== DAR Tags ===
Nielsen DAR tag may come in different forms from ad service via VAST XML or ad service integrated player framework library. The CMS data must be passed as a JSON object.
<syntaxhighlight lang="java">
loadMetadata(JSONObject jsonMetadata);
</syntaxhighlight>

Refer to [[Digital Measurement Metadata]] section for the parameters to be passed in the JSON object.

The DAR tags received from your CMS system should be transformed into a JSON string and passed in via the [[loadMetadata()]] method.

{| class="wikitable"
|-
! Variable Name !! Variable Description !! Example
|-
| type || Type identifies the tag content type. For DAR, the data type should be always set to "ad". || ad
|-
| ocrtag || The complete tag/URL is supplied by your Technical Account Manager. This should include the complete URL including the http portion. The ocrtag should be properly URI encoded. || <nowiki>http://secure-uat-cert.imrworldwide.com</nowiki>/cgi-bin/m?ci= ENTXX5&am=3&ep=1&at=view&rt=banner&st= image&ca=XX1717&cr=crvXX35&pc=plc1234
|}

=== SDK Integration ===
After getting the string from an ad service, to integrate Nielsen SDK for DAR tag, the app should first identify a Nielsen beacon in the use cases below
* If the input string is CDATA string, get the value of the CDATA as a new input string.
* If the input string (or new input string) starts with http and the hostname ends with “imrworldwide.com”, the input string is a Nielsen beacon (case 1 and case 3).
* If the input string (or new input string) starts with http and the CR field exists
** Get the value of the CR field.
** If the CR value starts with http and the hostname of the CR value ends with “imrworldwide.com”, the CR value is a Nielsen beacon (case 2 and case 4).
** If the Nielsen beacon exists, remove the value of the CR field from the input string and process the updated string for the non-DAR beacon.
* If the Nielsen beacon exists
** URL decode the Nielsen beacon.
** If the c13 field exists in the Nielsen beacon, remove the c13 from the Nielsen beacon.
** Create JSON with the Nielsen beacon
<syntaxhighlight lang="json">
{
"type": "ad",
"ocrtag": "<Nielsen beacon>"
}
</syntaxhighlight>
* '''EXAMPLE''': Sample JSON string with the DAR string (decoded http string without the c13)
<syntaxhighlight lang="json">
{
"type": "ad",
"ocrtag": "http://secure-gl.imrworldwide.com/cgi-bin/m?ci=ent30986&am=22&ep=1&at=view&rt=banner&st=image&ca=cmp97144&cr=1186239&pc=3739659&r=2011370876"
}
</syntaxhighlight>
** Send the JSON to the Nielsen SDK using loadMetadata.

== Nielsen Measurement Opt-Out Implementation ==
As a global information and measurement leader, we are committed to protecting the privacy and security of the data we collect, process and use. Our digital measurement products are not used to identify the consumer in any way, but 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.
* When the app user wants to opt in or opt out of Nielsen measurement, a new dynamic page (with content string obtained from [[userOptOutURLString()]]) should be displayed.
** Use [[getOptOutStatus()]] to retrieve the device’s Opt-Out status.
* This Opt-out page should be displayed in a webview (within the app) and not in any external browser.
* Capture the user’s selection in this page and pass it to the SDK through [[userOptOut()]] for Nielsen to save the user’s preference.
* For more details, refer to [[Android SDK API Reference#Android Opt-Out Implementation|Android SDK API Reference - Android Opt-Out Implementation]] and Nielsen Digital Privacy.
<blockquote>'''Note:''' The SDK will continue measurement even after the user has opted out from Nielsen measurement.</blockquote>

=== Pre-Certification Checklists ===
After the application is ready to be sent for Nielsen Certification, please go through the Pre-Certification Checklist and ensure the app behaves as expected, before submitting to Nielsen.

=== Testing an Implementation - App ===
See [[Digital Measurement Testing]].

DAR Android SDK

2017-08-29T19:19:22Z

Admin2: /* SDK Integration */

{{Breadcrumb|}} {{Breadcrumb|Digital}} {{Breadcrumb|Digital Ad Ratings}} {{CurrentBreadcrumb}}
[[Category:Digital]]

== 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''' and '''Sample Player''': A part of the downloaded package
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]] for more information on how to get a Nielsen App SDK and appid.

== Import Library ==
Refer to [[Android SDK API Reference#Importing Frameworks|Android SDK API Reference - Importing Frameworks]] for information on importing libraries.
* The latest version of App SDK allows instantiating multiple instances of App SDK object and can be used simultaneously without any issues.
<blockquote>'''Note:''' The latest version of App SDK contains only appsdk.jar file and does not feature any native shared libraries like libAppSdk.so.</blockquote>

== Initialize SDK ==
Initialize App SDK as soon as the application is launched. Refer to [[Android SDK API Reference#Initialization|Android SDK API Reference - Initialization]] for details on initializing an AppSDK object and the parameters required.

== Configure API calls ==

=== loadMetadata ===
DAR tags are used to track commercial delivery for campaign ratings. DAR tags are received during the streaming session from the Content Management System (CMS) identifying that the video contains ad content. This information should be passed as a JSON object via the [[loadMetadata()]] method with DAR contents.

=== DAR Tags ===
Nielsen DAR tag may come in different forms from ad service via VAST XML or ad service integrated player framework library. The CMS data must be passed as a JSON object.
<syntaxhighlight lang="java">
loadMetadata(JSONObject jsonMetadata);
</syntaxhighlight>

Refer to [[Digital Measurement Metadata]] section for the parameters to be passed in the JSON object.

The DAR tags received from your CMS system should be transformed into a JSON string and passed in via the [[loadMetadata()]] method.

{| class="wikitable"
|-
! Variable Name !! Variable Description !! Example
|-
| type || Type identifies the tag content type. For DAR, the data type should be always set to "ad". || ad
|-
| ocrtag || The complete tag/URL is supplied by your Technical Account Manager. This should include the complete URL including the http portion. The ocrtag should be properly URI encoded. || <nowiki>http://secure-uat-cert.imrworldwide.com</nowiki>/cgi-bin/m?ci= ENTXX5&am=3&ep=1&at=view&rt=banner&st= image&ca=XX1717&cr=crvXX35&pc=plc1234
|}

=== SDK Integration ===
After getting the string from an ad service, to integrate Nielsen SDK for DAR tag, the app should first identify a Nielsen beacon in the use cases below
* If the input string is CDATA string, get the value of the CDATA as a new input string.
* If the input string (or new input string) starts with http and the hostname ends with “imrworldwide.com”, the input string is a Nielsen beacon (case 1 and case 3).
* If the input string (or new input string) starts with http and the CR field exists
** Get the value of the CR field.
** If the CR value starts with http and the hostname of the CR value ends with “imrworldwide.com”, the CR value is a Nielsen beacon (case 2 and case 4).
** If the Nielsen beacon exists, remove the value of the CR field from the input string and process the updated string for the non-DAR beacon.
* If the Nielsen beacon exists
** URL decode the Nielsen beacon.
** If the c13 field exists in the Nielsen beacon, remove the c13 from the Nielsen beacon.
** Create JSON with the Nielsen beacon
<syntaxhighlight lang="json">
{
"type": "ad",
"ocrtag": "<Nielsen beacon>"
}
</syntaxhighlight>
* '''EXAMPLE''': Sample JSON string with the DAR string (decoded http string without the c13)
<syntaxhighlight lang="json">
{
"type": "ad",
"ocrtag": "http://secure-gl.imrworldwide.com/cgi-bin/m?ci=ent30986&am=22&ep=1&at=view&rt=banner&st=image&ca=cmp97144&cr=1186239&pc=3739659&r=2011370876"
}
</syntaxhighlight>
* Send the JSON to the Nielsen SDK using loadMetadata.

== Nielsen Measurement Opt-Out Implementation ==
As a global information and measurement leader, we are committed to protecting the privacy and security of the data we collect, process and use. Our digital measurement products are not used to identify the consumer in any way, but 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.
* When the app user wants to opt in or opt out of Nielsen measurement, a new dynamic page (with content string obtained from [[userOptOutURLString()]]) should be displayed.
** Use [[getOptOutStatus()]] to retrieve the device’s Opt-Out status.
* This Opt-out page should be displayed in a webview (within the app) and not in any external browser.
* Capture the user’s selection in this page and pass it to the SDK through [[userOptOut()]] for Nielsen to save the user’s preference.
* For more details, refer to [[Android SDK API Reference#Android Opt-Out Implementation|Android SDK API Reference - Android Opt-Out Implementation]] and Nielsen Digital Privacy.
<blockquote>'''Note:''' The SDK will continue measurement even after the user has opted out from Nielsen measurement.</blockquote>

=== Pre-Certification Checklists ===
After the application is ready to be sent for Nielsen Certification, please go through the Pre-Certification Checklist and ensure the app behaves as expected, before submitting to Nielsen.

=== Testing an Implementation - App ===
See [[Digital Measurement Testing]].

DAR iOS SDK

2017-08-29T19:18:57Z

Admin2: /* SDK Integration */

{{Breadcrumb|}} {{Breadcrumb|Digital}} {{Breadcrumb|Digital Ad Ratings}} {{CurrentBreadcrumb}}
[[Category:Digital]]

== 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''' and '''Sample Player''': A part of the downloaded package
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]] for more information on how to get a Nielsen App SDK and appid.

== Import Library ==
Refer to [[iOS SDK API Reference#Importing Frameworks|iOS SDK API Reference - Importing Frameworks]] for information on importing libraries.
* The latest version of App SDK allows instantiating multiple instances of App SDK object and can be used simultaneously without any issues.

== Initialize SDK ==
Initialize App SDK as soon as the application is launched. Refer to [[iOS SDK API Reference#Initialization|iOS SDK API Reference - Initialization]] for details on initializing an AppSDK object and the parameters required.

== Configure API calls ==

=== loadMetadata ===
DAR tags are used to track commercial delivery for campaign ratings. DAR tags are received during the streaming session from the Content Management System (CMS) identifying that the video contains ad content. This information should be passed as a JSON object via the [[loadMetadata]] method with DAR contents.

=== DAR Tags ===
Nielsen DAR tag may come in different forms from ad service via VAST XML or ad service integrated player framework library

The CMS data must be passed as a JSON object.

<syntaxhighlight lang="objective-c">
– (void)loadMetadata:(id)metadata;
</syntaxhighlight>

Refer to [[Digital Measurement Metadata]] section for the list of parameters to be passed in the JSON object.

[[loadMetadata]] call after the first play call must have ‘content’ details (<code>"type": "content"</code>). This call should occur before any preroll ad starts playing.

=== API Call sequence ===
Call [[loadMetadata]] with JSON metadata for content as below.

<syntaxhighlight lang="objective-c">
NSDictionary* metaDatainformation =
@{
@"type" : @"ad",
@"ocrtag" : @"URL received from Ad server"
};
NSData* jsonDARInfo = [NSJSONSerialization dataWithJSONObject:metaDatainformation options:0 error:nil];
NSString* darInfo = [[NSString alloc] initWithBytes:[jsonDARInfo bytes]
length:[jsonDARInfo length]
encoding:NSUTF8StringEncoding];
[NID3Meter loadMetadata:darInfo];
</syntaxhighlight>

The DAR tags received from your CMS system should be transformed into a JSON string and passed in via the [[loadMetadata]] method.

{| class="wikitable"
|-
! Variable Name !! Variable Description !! Example
|-
| type || Type identifies the tag content type. For DAR, the data type should be always set to "ad". || ad
|-
| ocrtag || The complete tag/URL is supplied by your Technical Account Manager. This should include the complete URL including the http portion. The ocrtag should be properly URI encoded. || <nowiki>http://secure-uat-cert.imrworldwide.com</nowiki>/cgi-bin/m?ci= ENTXX5&am=3&ep=1&at=view&rt=banner&st= image&ca=XX1717&cr=crvXX35&pc=plc1234
|}

=== SDK Integration ===
After getting the string from an ad service, to integrate Nielsen SDK for DAR tag, the app should first identify a Nielsen beacon in the use cases below
* If the input string is CDATA string, get the value of the CDATA as a new input string.
* If the input string (or new input string) starts with http and the hostname ends with “imrworldwide.com”, the input string is a Nielsen beacon (case 1 and case 3).
* If the input string (or new input string) starts with http and the CR field exists
** Get the value of the CR field.
** If the CR value starts with http and the hostname of the CR value ends with “imrworldwide.com”, the CR value is a Nielsen beacon (case 2 and case 4).
** If the Nielsen beacon exists, remove the value of the CR field from the input string and process the updated string for the non-DAR beacon.
* If the Nielsen beacon exists
** URL decode the Nielsen beacon.
** If the c13 field exists in the Nielsen beacon, remove the c13 from the Nielsen beacon.
** Create JSON with the Nielsen beacon
<syntaxhighlight lang="json">
{
"type": "ad",
"ocrtag": "<Nielsen beacon>"
}</syntaxhighlight>
* '''EXAMPLE''': Sample JSON string with the DAR string (decoded http string without the c13)<syntaxhighlight lang="json"> {
"type": "ad",
"ocrtag": "http://secure-gl.imrworldwide.com/cgi-bin/m?ci=ent30986&am=22&ep=1&at=view&rt=banner&st=image&ca=cmp97144&cr=1186239&pc=3739659&r=2011370876"
}
</syntaxhighlight>
** Send the JSON to the Nielsen SDK using loadMetadata.

== Nielsen Measurement Opt-Out Implementation ==
As a global information and measurement leader, we are committed to protecting the privacy and security of the data we collect, process and use. Our digital measurement products are not used to identify the consumer in any way, but 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.
* When the app user wants to opt in or opt out of Nielsen measurement, a new dynamic page (with content string obtained from [[optOutURL]]) should be displayed.
** Use [[optOutStatus]] to retrieve the device’s Opt-Out status.
* This Opt-out page should be displayed in a webview (within the app) and not in any external browser.
* Capture the user’s selection in this page and pass it to the SDK through [[userOptOut]] for Nielsen to save the user’s preference.
* For more details, refer to [[iOS SDK API Reference#iOS Opt-Out Implementation|iOS SDK API Reference - iOS Opt-Out Implementation]] and Nielsen Digital Privacy.
<blockquote>Note: The SDK will continue measurement even after the user has opted out from Nielsen measurement.</blockquote>

=== Pre-Certification Checklists ===
After the application is ready to be sent for Nielsen Certification, please go through the Pre-Certification Checklist and ensure the app behaves as expected, before submitting to Nielsen.

=== Testing an Implementation - App ===
See [[Digital Measurement Testing ]].

Mobile DAR Attributes Requirements

2017-08-29T19:16:26Z

Admin2: /* Appendix A: Example Implementation */

{{Breadcrumb|}} {{Breadcrumb|Digital}} {{Breadcrumb|Digital Ad Ratings}} {{CurrentBreadcrumb}}
[[Category:Digital]]

== Introduction ==
Currently, Nielsen’s DAR tags are well supported online via '''browser'''-based viewing on PCs, MACs, and tablets/smartphones. However, when ads are served to tablets/smartphones via native '''app-store applications''', additional attributes are needed in order for Nielsen clients to employ Nielsen’s mobile DAR (mDAR) measurement product.

One way Nielsen clients can accomplish this is by the use of Nielsen’s native iOS/Android App SDK. Nielsen’s App SDK automatically adds these additional mobile attributes to mDAR measurement pings that are sent to Nielsen’s collection system. However, there is a significant portion of the mobile application universe where it is either not feasible, or desirable to integrate Nielsen’s native App SDK into 3rd party applications.

This document describes additional attributes that must be added to DAR pings to create mDAR-compliant tags by way of a server-side macro replacement. This method is often referred to as Nielsen’s “non-SDK” DAR solution. Nielsen envisions that these attributes be added by ad networks when they respond to ad requests from client mobile devices.

To support the insertion of the Advertising ID, it is assumed that you have published a specification that app publishers follow to pass the appropriate Advertising ID (for example, IDFA) in the Ad request URL. Typically, your Ad server will expand a macro that grabs that ID seen in the Ad request URL and pass it via the DAR pixel outlined below. See [[#Appendix A: Example Implementation]].

Finally, once you have completed your integration, you will be required to submit to a short certification. See [[#Appendix B: Implementation, Testing & Certification]]. Certification also grants inclusion to the approved publisher and platform vendor list.
{| class="wikitable"
|-
! Additional DAR Tag Parameters for Mobile !! Description !! Mandatory?
|-
| &c7 || OS Grouping ||
|-
| &c8 || Device Grouping ||
|-
| &c9 || Advertising ID || <center>✔</center>
|-
| &c10 || Platform ||
|-
| &c12 || App Version ||
|-
| &c13 || AppID (Nielsen assigned App ID) || <center>✔</center>
|-
| &c14 || OS Version ||
|-
| &uoo || Opt-out indicator || When applicable
|}
<blockquote>'''Note''': Clients are encouragesd to make an effort to always fill-in optional parameters.

'''Note''': Do not URL encode the values.</blockquote>

== C7 - OS Grouping (Optional) ==
Valid device OS Grouping data values are the following literal values:
* osgrp,IOS
* osgrp,DROID
* osgrp,ANDROID
<blockquote>'''Note''': If one of the above values cannot be specific, then the parameter should not be included int he call.</blockquote>

== C8 - Device Grouping ==
Valid literal values for phone, tablet, portable media player (iPod) and unknown are as follows:
* devgrp,PHN
* devgrp,TAB
* devgrp,PMP
* devgrp,UNWN
* devgrp,DSK
<blockquote>'''Note''': If one of the above values cannot be specific, then the parameter should not be included in the call or should be left empty</blockquote>

== C9 - Advertising ID ==
This is the advertiser ID for the client’s mobile device. IDFA for iOS, Google Advertising ID for Android:
* devid,<IDFA>
* devid,<IFA>
* devid,<Google Advertising ID>
<blockquote>'''Note''': For Android devices, the Google Advertiser ID should be used as the default and the Android ID as the second option.

'''Note''': If C9 is <empty>, upon receiving the ping, the Nielsen collection server will attempt a 302 redirect to the data provider per the regular DAR pixel for browsers.</blockquote>

As of August 1, 2014, Google is enforcing use of the Advertising ID for advertising and user analytics (http://play.google.com/about/developer-content-policy.html).

<blockquote>'' "Beginning August 1st 2014, all updates and new apps uploaded to the Play Store must use the advertising ID (when available on a device) in lieu of any other device identifiers for any advertising purposes."</blockquote>

It is preferred that the IDFA or Google Advertising ID be sent as is from the mobile device (“cleartext”). However, if mandated, we will support SHA256 hashed values with no-salt. Passing a hashed value (and/or salting) using any other standard will result in a failed match by the data provider upon receiving the ping. In turn, this results in impressions surfacing in the DAR unmeasurable audience totals. Please contact Nielsen if you anticipate a large percentage of hashed values coming in from your publisher clients.

=== Privacy, Ad Tracking, and Ad Targeting ===
In newer iterations of the iOS and Android device operating systems, a facility exists allowing users to “opt-out” of “Ad Tracking”. It is Nielsen’s interpretation that this setting is primarily designed to allow users to specify opt-out of Ad Targeting rather than Ad Measurement. DAR
does not provide Ad Targeting data.

However, it is also Nielsen’s position that the publisher or Ad network should provide a mechanism to also allow a user to opt-out of Ad Measurement. The Nielsen SDK will honor the Nielsen Ad Measurement opt-out settings configurable @ http://www.nielsen.com/us/en/campaigns/privacy-policy-opt-out.html.

However if the integration approach described in this document is being used instead of the Nielsen SDK then '''YOU''' as the publisher or Ad network must provide a capability to opt-out of Ad Measurement as the configuration on www.nielsen.com will not be detectable. You may
elect to interpret the iOS / Android “Ad Tracking” setting for the purpose of limit Ad measurement or provide a separate discreet mechanism to allow a user to opt-out of Ad measurement.

Please see '''&uoo''' later in this document for implementation details of the optout indicator.

For additional clarification on privacy policy, please contact your Nielsen representative.

== C10 - Platform ==
To determine this value, Nielsen suggests that the ad network leverage user agent information to determine if the client device is either a mobile or desktop device.

Valid literal values for mobile and desktop data values are as follows:
* plt,MBL
* plt,DSK
<blockquote>'''Note''': If one of the above values cannot be specific, then the parameter should not be included in the call or
should be left empty.</blockquote>

== C12 - App Version (Optional) ==
This is the version of the ad network system software or SDK that is implemented in this extension. Although this field is not required, this feature can be useful for troubleshooting purposes following deployment.
* apv,<N.N>

== C13 - AppID ==
This Nielsen provided ID is unique to the ad network and is required for certification.
* asid,<NNNNNNNNN-NNNN-NNNN-NNNN-NNNNNNNNNNNN>
An App ID will be provided for testing. A separate App ID will be provided for production use. Please request from your Nielsen representative.
<blockquote>'''Note''': If you are a publisher leveraging the non-SDK solution, you will be provided with a unique App ID for each combination of app and device OS type.</blockquote>

== C14 - OS Version (Optional) ==
Operating system version
* osver,<OS Version>
Example: for iOS -> 7.0.4

== UOO - Opt Out (Optional) ==
Opt-out parameter
* <Boolean state>
<Boolean state> is a Boolean representation of whether the user is opting out or not.

The absence of uoo in the tag is interpreted as an implicit opt-in. i.e. not opting out.

The following pairings of opt-out are supported. Important: you must choose one set of paired values only and inform your Nielsen representative.
{| class="wikitable"
|-
! Opt-out !! Opt-in
|-
| uoo=true || uoo=false
|-
| uoo=1 || uoo=0
|-
| uoo=yes || uoo=no
|}
<blockquote>'''Note''': if your Ad server is not capable os supporting the discrete &uoo parameter then you can set the c9 value to <code>devid,optout</code> (for example <code>…&c8=PHN&c9=devid,optout&c10=MBL…</code>)</blockquote>

== Examples of DAR and mDAR Tags ==
For each of the tag examples detailed below, we can support both unsecure (http) and secure (https) flavors.

'''Important note''': the values in the following tags are for illustrative purposes only. Please contact your Nielsen representative for specific parameter values for your use of DAR.

'''Test and Certification'''
* <code><nowiki>http://secure-cert.imrworldwide.com</nowiki>/cgi-bin/m?ci=nlsnci535&am=3&at=view&rt=banner&st=image&ca=nlsn12452&cr=crtve&pc=%3cclientname%3e_plc0001&ce=%3cclientname%3e&c7=osgrp</code>

'''Production'''
* <code><nowiki>http://secure-gl.imrworldwide.com</nowiki>/cgibin/m?ci=nlsnci535&am=3&at=view&rt=banner&st=image&ca=nlsn12452&cr=crtve&pc=<clientname>_plc0001&ce=<clientname>&c7=osgrp,IOS&c8=devgrp,TAB&c9=devid,XXXX-XX-XXXXX-XXXX&c10=plt,MBL &c12=apv,AppVersion&c13=asid,NIELSEN-PROVIDEDID&c14=osver,7.0.4&uoo=1&r=[timestamp]</code>

'''Standard DAR tag (for information and completeness)'''
* <code><nowiki>http://secure-gl.imrworldwide.com</nowiki>/cgi-bin/m?ci=nlsnci535&am=3&at=view&rt=banner&st=image&ca=nlsn12452&cr=crtve&pc=%3cclientname%3e_plc0001&ce=%3cclientname%3e&uoo=1&r=%5btimestamp</code>

== Appendix A: Example Implementation ==
In the below examples, you will see the overall DAR flow (Figure 1) and a detailed illustrative Ad Request / Response model (Figure 2).

<div align="center">'''Figure 1 – End to End Data Flow'''</div>

[[File:mDAR_Dataflow.png|center|link=]]

Nielsen certified publishers and platforms will append the new parameters (below) with the appropriate URL safe values passed to Nielsen’s current DAR tag. The current DAR tag should be acquired using the existing processes for each campaign/placement.

<blockquote><code>'''&c7'''=osgrp,IOS'''&c8'''=devgrp,PHN'''&c9'''=devid,XXXX-XX-XXXXXXXXX'''&c10'''=plt,MBL'''&c12'''=apv,AppVersion'''&c13'''=asid,XXXX-XX-XXXX-XXXX</code></blockquote>

<div align="center">'''Figure 2 – Illustrative Ad Request / Ad Response'''</div>

[[File:ad_response.png|center|link=]]

The above is an example of how an Ad server is supporting the build of mobile DAR tags for its publisher clients. Step 2 in Figure 1 is a summary of steps 1 and 2 in Figure 2 above. Steps 3 and 4 in Figure 1 is a summary of steps 3 through 9 in Figure 2 above.

== Appendix B: Implementation, Testing & Certification ==
Once you have integrated the ping per the above specs, Nielsen requires you to pass through a one-time certification before traffic can be accepted into the production environment.

The overall process is:
# Valid DAR contract or NDA is in place.
# Kick-off meeting with Nielsen onboarding team.
# Confirm meet minimums testing requriements:
## Host Ad/Tag for in-app delivery
## Can pass opt-out back to Nielsen
## Can pass Device ID in cleartext or SHA-256
# Nielsen provides the mDAR testing form that includes the test App ID and the test tag
# Implement the specification and provide Nielsen the completed testing form.
# Identify the live campaigns for intial testing and run the test tag; suggest 5,000-10,000 impressions.
# Nielsen validates the data received from the test and confirms the initial test successful and provides the production App ID.
## Goal is to test that all minimum requirements in step 3 are confirmed passed to Nielsen with no issues.
# Ensure contracts are in place for external test campaign with Nielsen Client Service team.
# Identify another live campaigns for production testing with production tag and app ID.
# Nielsen validates the data received from the final test and confirms certification for any DAR countries tested.
## Goal to test in full DAR E2E environment, receive matches from data provider for demographics and correct identification of mobile impressions.

Mobile DAR Attributes Requirements

2017-08-29T19:15:37Z

Admin2: /* Introduction */

{{Breadcrumb|}} {{Breadcrumb|Digital}} {{Breadcrumb|Digital Ad Ratings}} {{CurrentBreadcrumb}}
[[Category:Digital]]

== Introduction ==
Currently, Nielsen’s DAR tags are well supported online via '''browser'''-based viewing on PCs, MACs, and tablets/smartphones. However, when ads are served to tablets/smartphones via native '''app-store applications''', additional attributes are needed in order for Nielsen clients to employ Nielsen’s mobile DAR (mDAR) measurement product.

One way Nielsen clients can accomplish this is by the use of Nielsen’s native iOS/Android App SDK. Nielsen’s App SDK automatically adds these additional mobile attributes to mDAR measurement pings that are sent to Nielsen’s collection system. However, there is a significant portion of the mobile application universe where it is either not feasible, or desirable to integrate Nielsen’s native App SDK into 3rd party applications.

This document describes additional attributes that must be added to DAR pings to create mDAR-compliant tags by way of a server-side macro replacement. This method is often referred to as Nielsen’s “non-SDK” DAR solution. Nielsen envisions that these attributes be added by ad networks when they respond to ad requests from client mobile devices.

To support the insertion of the Advertising ID, it is assumed that you have published a specification that app publishers follow to pass the appropriate Advertising ID (for example, IDFA) in the Ad request URL. Typically, your Ad server will expand a macro that grabs that ID seen in the Ad request URL and pass it via the DAR pixel outlined below. See [[#Appendix A: Example Implementation]].

Finally, once you have completed your integration, you will be required to submit to a short certification. See [[#Appendix B: Implementation, Testing & Certification]]. Certification also grants inclusion to the approved publisher and platform vendor list.
{| class="wikitable"
|-
! Additional DAR Tag Parameters for Mobile !! Description !! Mandatory?
|-
| &c7 || OS Grouping ||
|-
| &c8 || Device Grouping ||
|-
| &c9 || Advertising ID || <center>✔</center>
|-
| &c10 || Platform ||
|-
| &c12 || App Version ||
|-
| &c13 || AppID (Nielsen assigned App ID) || <center>✔</center>
|-
| &c14 || OS Version ||
|-
| &uoo || Opt-out indicator || When applicable
|}
<blockquote>'''Note''': Clients are encouragesd to make an effort to always fill-in optional parameters.

'''Note''': Do not URL encode the values.</blockquote>

== C7 - OS Grouping (Optional) ==
Valid device OS Grouping data values are the following literal values:
* osgrp,IOS
* osgrp,DROID
* osgrp,ANDROID
<blockquote>'''Note''': If one of the above values cannot be specific, then the parameter should not be included int he call.</blockquote>

== C8 - Device Grouping ==
Valid literal values for phone, tablet, portable media player (iPod) and unknown are as follows:
* devgrp,PHN
* devgrp,TAB
* devgrp,PMP
* devgrp,UNWN
* devgrp,DSK
<blockquote>'''Note''': If one of the above values cannot be specific, then the parameter should not be included in the call or should be left empty</blockquote>

== C9 - Advertising ID ==
This is the advertiser ID for the client’s mobile device. IDFA for iOS, Google Advertising ID for Android:
* devid,<IDFA>
* devid,<IFA>
* devid,<Google Advertising ID>
<blockquote>'''Note''': For Android devices, the Google Advertiser ID should be used as the default and the Android ID as the second option.

'''Note''': If C9 is <empty>, upon receiving the ping, the Nielsen collection server will attempt a 302 redirect to the data provider per the regular DAR pixel for browsers.</blockquote>

As of August 1, 2014, Google is enforcing use of the Advertising ID for advertising and user analytics (http://play.google.com/about/developer-content-policy.html).

<blockquote>'' "Beginning August 1st 2014, all updates and new apps uploaded to the Play Store must use the advertising ID (when available on a device) in lieu of any other device identifiers for any advertising purposes."</blockquote>

It is preferred that the IDFA or Google Advertising ID be sent as is from the mobile device (“cleartext”). However, if mandated, we will support SHA256 hashed values with no-salt. Passing a hashed value (and/or salting) using any other standard will result in a failed match by the data provider upon receiving the ping. In turn, this results in impressions surfacing in the DAR unmeasurable audience totals. Please contact Nielsen if you anticipate a large percentage of hashed values coming in from your publisher clients.

=== Privacy, Ad Tracking, and Ad Targeting ===
In newer iterations of the iOS and Android device operating systems, a facility exists allowing users to “opt-out” of “Ad Tracking”. It is Nielsen’s interpretation that this setting is primarily designed to allow users to specify opt-out of Ad Targeting rather than Ad Measurement. DAR
does not provide Ad Targeting data.

However, it is also Nielsen’s position that the publisher or Ad network should provide a mechanism to also allow a user to opt-out of Ad Measurement. The Nielsen SDK will honor the Nielsen Ad Measurement opt-out settings configurable @ http://www.nielsen.com/us/en/campaigns/privacy-policy-opt-out.html.

However if the integration approach described in this document is being used instead of the Nielsen SDK then '''YOU''' as the publisher or Ad network must provide a capability to opt-out of Ad Measurement as the configuration on www.nielsen.com will not be detectable. You may
elect to interpret the iOS / Android “Ad Tracking” setting for the purpose of limit Ad measurement or provide a separate discreet mechanism to allow a user to opt-out of Ad measurement.

Please see '''&uoo''' later in this document for implementation details of the optout indicator.

For additional clarification on privacy policy, please contact your Nielsen representative.

== C10 - Platform ==
To determine this value, Nielsen suggests that the ad network leverage user agent information to determine if the client device is either a mobile or desktop device.

Valid literal values for mobile and desktop data values are as follows:
* plt,MBL
* plt,DSK
<blockquote>'''Note''': If one of the above values cannot be specific, then the parameter should not be included in the call or
should be left empty.</blockquote>

== C12 - App Version (Optional) ==
This is the version of the ad network system software or SDK that is implemented in this extension. Although this field is not required, this feature can be useful for troubleshooting purposes following deployment.
* apv,<N.N>

== C13 - AppID ==
This Nielsen provided ID is unique to the ad network and is required for certification.
* asid,<NNNNNNNNN-NNNN-NNNN-NNNN-NNNNNNNNNNNN>
An App ID will be provided for testing. A separate App ID will be provided for production use. Please request from your Nielsen representative.
<blockquote>'''Note''': If you are a publisher leveraging the non-SDK solution, you will be provided with a unique App ID for each combination of app and device OS type.</blockquote>

== C14 - OS Version (Optional) ==
Operating system version
* osver,<OS Version>
Example: for iOS -> 7.0.4

== UOO - Opt Out (Optional) ==
Opt-out parameter
* <Boolean state>
<Boolean state> is a Boolean representation of whether the user is opting out or not.

The absence of uoo in the tag is interpreted as an implicit opt-in. i.e. not opting out.

The following pairings of opt-out are supported. Important: you must choose one set of paired values only and inform your Nielsen representative.
{| class="wikitable"
|-
! Opt-out !! Opt-in
|-
| uoo=true || uoo=false
|-
| uoo=1 || uoo=0
|-
| uoo=yes || uoo=no
|}
<blockquote>'''Note''': if your Ad server is not capable os supporting the discrete &uoo parameter then you can set the c9 value to <code>devid,optout</code> (for example <code>…&c8=PHN&c9=devid,optout&c10=MBL…</code>)</blockquote>

== Examples of DAR and mDAR Tags ==
For each of the tag examples detailed below, we can support both unsecure (http) and secure (https) flavors.

'''Important note''': the values in the following tags are for illustrative purposes only. Please contact your Nielsen representative for specific parameter values for your use of DAR.

'''Test and Certification'''
* <code><nowiki>http://secure-cert.imrworldwide.com</nowiki>/cgi-bin/m?ci=nlsnci535&am=3&at=view&rt=banner&st=image&ca=nlsn12452&cr=crtve&pc=%3cclientname%3e_plc0001&ce=%3cclientname%3e&c7=osgrp</code>

'''Production'''
* <code><nowiki>http://secure-gl.imrworldwide.com</nowiki>/cgibin/m?ci=nlsnci535&am=3&at=view&rt=banner&st=image&ca=nlsn12452&cr=crtve&pc=<clientname>_plc0001&ce=<clientname>&c7=osgrp,IOS&c8=devgrp,TAB&c9=devid,XXXX-XX-XXXXX-XXXX&c10=plt,MBL &c12=apv,AppVersion&c13=asid,NIELSEN-PROVIDEDID&c14=osver,7.0.4&uoo=1&r=[timestamp]</code>

'''Standard DAR tag (for information and completeness)'''
* <code><nowiki>http://secure-gl.imrworldwide.com</nowiki>/cgi-bin/m?ci=nlsnci535&am=3&at=view&rt=banner&st=image&ca=nlsn12452&cr=crtve&pc=%3cclientname%3e_plc0001&ce=%3cclientname%3e&uoo=1&r=%5btimestamp</code>

== Appendix A: Example Implementation ==
In the below examples, you will see the overall DAR flow (Figure 1) and a detailed illustrative Ad Request / Response model (Figure 2).

<div align="center">'''Figure 1 – End to End Data Flow'''</div>

[[File:mDAR_Dataflow.png|center|link=]]

Nielsen certified publishers and platforms will append the new parameters (below) with the appropriate URL safe values passed to Nielsen’s current DAR tag. The current DAR tag should be acquired using the existing processes for each campaign/placement.
<code>'''&c7'''=osgrp,IOS'''&c8'''=devgrp,PHN'''&c9'''=devid,XXXX-XX-XXXXXXXXX'''&c10'''=plt,MBL'''&c12'''=apv,AppVersion'''&c13'''=asid,XXXX-XX-XXXX-XXXX</code>

<div align="center">'''Figure 2 – Illustrative Ad Request / Ad Response'''</div>

[[File:ad_response.png|center|link=]]

The above is an example of how an Ad server is supporting the build of mobile DAR tags for its publisher clients. Step 2 in Figure 1 is a summary of steps 1 and 2 in Figure 2 above. Steps 3 and 4 in Figure 1 is a summary of steps 3 through 9 in Figure 2 above.

== Appendix B: Implementation, Testing & Certification ==
Once you have integrated the ping per the above specs, Nielsen requires you to pass through a one-time certification before traffic can be accepted into the production environment.

The overall process is:
# Valid DAR contract or NDA is in place.
# Kick-off meeting with Nielsen onboarding team.
# Confirm meet minimums testing requriements:
## Host Ad/Tag for in-app delivery
## Can pass opt-out back to Nielsen
## Can pass Device ID in cleartext or SHA-256
# Nielsen provides the mDAR testing form that includes the test App ID and the test tag
# Implement the specification and provide Nielsen the completed testing form.
# Identify the live campaigns for intial testing and run the test tag; suggest 5,000-10,000 impressions.
# Nielsen validates the data received from the test and confirms the initial test successful and provides the production App ID.
## Goal is to test that all minimum requirements in step 3 are confirmed passed to Nielsen with no issues.
# Ensure contracts are in place for external test campaign with Nielsen Client Service team.
# Identify another live campaigns for production testing with production tag and app ID.
# Nielsen validates the data received from the final test and confirms certification for any DAR countries tested.
## Goal to test in full DAR E2E environment, receive matches from data provider for demographics and correct identification of mobile impressions.

Mobile DAR Attributes Requirements

2017-08-29T19:13:45Z

Admin2: /* Introduction */

{{Breadcrumb|}} {{Breadcrumb|Digital}} {{Breadcrumb|Digital Ad Ratings}} {{CurrentBreadcrumb}}
[[Category:Digital]]

== Introduction ==
Currently, Nielsen’s DAR tags are well supported online via '''browser'''-based viewing on PCs, MACs, and tablets/smartphones. However, when ads are served to tablets/smartphones via native '''app-store applications''', additional attributes are needed in order for Nielsen clients to employ Nielsen’s mobile DAR (mDAR) measurement product.

One way Nielsen clients can accomplish this is by the use of Nielsen’s native iOS/Android App SDK. Nielsen’s App SDK automatically adds these additional mobile attributes to mDAR measurement pings that are sent to Nielsen’s collection system. However, there is a significant portion of the mobile application universe where it is either not feasible, or desirable to integrate Nielsen’s native App SDK into 3rd party applications.

This document describes additional attributes that must be added to DAR pings to create mDAR-compliant tags by way of a server-side macro replacement. This method is often referred to as Nielsen’s “non-SDK” DAR solution. Nielsen envisions that these attributes be added by ad networks when they respond to ad requests from client mobile devices.

To support the insertion of the Advertising ID, it is assumed that you have published a specification that app publishers follow to pass the appropriate Advertising ID (for example, IDFA) in the Ad request URL. Typically, your Ad server will expand a macro that grabs that ID seen in the Ad request URL and pass it via the DAR pixel outlined below. See [[#Appendix A: Example Implementation]].

Finally, once you have completed your integration, you will be required to submit to a short certification. See [[#Appendix B: Implementation, Testing & Certification]]. Certification also grants inclusion to the approved publisher and platform vendor list.
{| class="wikitable"
|-
! Additional DAR Tag Parameters for Mobile !! Description !! Mandatory?
|-
| &c7 || OS Grouping ||
|-
| &c8 || Device Grouping ||
|-
| &c9 || Advertising ID || ✔
|-
| &c10 || Platform ||
|-
| &c12 || App Version ||
|-
| &c13 || AppID (Nielsen assigned App ID) || ✔
|-
| &c14 || OS Version ||
|-
| &uoo || Opt-out indicator || When applicable
|}
<blockquote>'''Note''': Clients are encouragesd to make an effort to always fill-in optional parameters.

'''Note''': Do not URL encode the values.</blockquote>

== C7 - OS Grouping (Optional) ==
Valid device OS Grouping data values are the following literal values:
* osgrp,IOS
* osgrp,DROID
* osgrp,ANDROID
<blockquote>'''Note''': If one of the above values cannot be specific, then the parameter should not be included int he call.</blockquote>

== C8 - Device Grouping ==
Valid literal values for phone, tablet, portable media player (iPod) and unknown are as follows:
* devgrp,PHN
* devgrp,TAB
* devgrp,PMP
* devgrp,UNWN
* devgrp,DSK
<blockquote>'''Note''': If one of the above values cannot be specific, then the parameter should not be included in the call or should be left empty</blockquote>

== C9 - Advertising ID ==
This is the advertiser ID for the client’s mobile device. IDFA for iOS, Google Advertising ID for Android:
* devid,<IDFA>
* devid,<IFA>
* devid,<Google Advertising ID>
<blockquote>'''Note''': For Android devices, the Google Advertiser ID should be used as the default and the Android ID as the second option.

'''Note''': If C9 is <empty>, upon receiving the ping, the Nielsen collection server will attempt a 302 redirect to the data provider per the regular DAR pixel for browsers.</blockquote>

As of August 1, 2014, Google is enforcing use of the Advertising ID for advertising and user analytics (http://play.google.com/about/developer-content-policy.html).

<blockquote>'' "Beginning August 1st 2014, all updates and new apps uploaded to the Play Store must use the advertising ID (when available on a device) in lieu of any other device identifiers for any advertising purposes."</blockquote>

It is preferred that the IDFA or Google Advertising ID be sent as is from the mobile device (“cleartext”). However, if mandated, we will support SHA256 hashed values with no-salt. Passing a hashed value (and/or salting) using any other standard will result in a failed match by the data provider upon receiving the ping. In turn, this results in impressions surfacing in the DAR unmeasurable audience totals. Please contact Nielsen if you anticipate a large percentage of hashed values coming in from your publisher clients.

=== Privacy, Ad Tracking, and Ad Targeting ===
In newer iterations of the iOS and Android device operating systems, a facility exists allowing users to “opt-out” of “Ad Tracking”. It is Nielsen’s interpretation that this setting is primarily designed to allow users to specify opt-out of Ad Targeting rather than Ad Measurement. DAR
does not provide Ad Targeting data.

However, it is also Nielsen’s position that the publisher or Ad network should provide a mechanism to also allow a user to opt-out of Ad Measurement. The Nielsen SDK will honor the Nielsen Ad Measurement opt-out settings configurable @ http://www.nielsen.com/us/en/campaigns/privacy-policy-opt-out.html.

However if the integration approach described in this document is being used instead of the Nielsen SDK then '''YOU''' as the publisher or Ad network must provide a capability to opt-out of Ad Measurement as the configuration on www.nielsen.com will not be detectable. You may
elect to interpret the iOS / Android “Ad Tracking” setting for the purpose of limit Ad measurement or provide a separate discreet mechanism to allow a user to opt-out of Ad measurement.

Please see '''&uoo''' later in this document for implementation details of the optout indicator.

For additional clarification on privacy policy, please contact your Nielsen representative.

== C10 - Platform ==
To determine this value, Nielsen suggests that the ad network leverage user agent information to determine if the client device is either a mobile or desktop device.

Valid literal values for mobile and desktop data values are as follows:
* plt,MBL
* plt,DSK
<blockquote>'''Note''': If one of the above values cannot be specific, then the parameter should not be included in the call or
should be left empty.</blockquote>

== C12 - App Version (Optional) ==
This is the version of the ad network system software or SDK that is implemented in this extension. Although this field is not required, this feature can be useful for troubleshooting purposes following deployment.
* apv,<N.N>

== C13 - AppID ==
This Nielsen provided ID is unique to the ad network and is required for certification.
* asid,<NNNNNNNNN-NNNN-NNNN-NNNN-NNNNNNNNNNNN>
An App ID will be provided for testing. A separate App ID will be provided for production use. Please request from your Nielsen representative.
<blockquote>'''Note''': If you are a publisher leveraging the non-SDK solution, you will be provided with a unique App ID for each combination of app and device OS type.</blockquote>

== C14 - OS Version (Optional) ==
Operating system version
* osver,<OS Version>
Example: for iOS -> 7.0.4

== UOO - Opt Out (Optional) ==
Opt-out parameter
* <Boolean state>
<Boolean state> is a Boolean representation of whether the user is opting out or not.

The absence of uoo in the tag is interpreted as an implicit opt-in. i.e. not opting out.

The following pairings of opt-out are supported. Important: you must choose one set of paired values only and inform your Nielsen representative.
{| class="wikitable"
|-
! Opt-out !! Opt-in
|-
| uoo=true || uoo=false
|-
| uoo=1 || uoo=0
|-
| uoo=yes || uoo=no
|}
<blockquote>'''Note''': if your Ad server is not capable os supporting the discrete &uoo parameter then you can set the c9 value to <code>devid,optout</code> (for example <code>…&c8=PHN&c9=devid,optout&c10=MBL…</code>)</blockquote>

== Examples of DAR and mDAR Tags ==
For each of the tag examples detailed below, we can support both unsecure (http) and secure (https) flavors.

'''Important note''': the values in the following tags are for illustrative purposes only. Please contact your Nielsen representative for specific parameter values for your use of DAR.

'''Test and Certification'''
* <code><nowiki>http://secure-cert.imrworldwide.com</nowiki>/cgi-bin/m?ci=nlsnci535&am=3&at=view&rt=banner&st=image&ca=nlsn12452&cr=crtve&pc=%3cclientname%3e_plc0001&ce=%3cclientname%3e&c7=osgrp</code>

'''Production'''
* <code><nowiki>http://secure-gl.imrworldwide.com</nowiki>/cgibin/m?ci=nlsnci535&am=3&at=view&rt=banner&st=image&ca=nlsn12452&cr=crtve&pc=<clientname>_plc0001&ce=<clientname>&c7=osgrp,IOS&c8=devgrp,TAB&c9=devid,XXXX-XX-XXXXX-XXXX&c10=plt,MBL &c12=apv,AppVersion&c13=asid,NIELSEN-PROVIDEDID&c14=osver,7.0.4&uoo=1&r=[timestamp]</code>

'''Standard DAR tag (for information and completeness)'''
* <code><nowiki>http://secure-gl.imrworldwide.com</nowiki>/cgi-bin/m?ci=nlsnci535&am=3&at=view&rt=banner&st=image&ca=nlsn12452&cr=crtve&pc=%3cclientname%3e_plc0001&ce=%3cclientname%3e&uoo=1&r=%5btimestamp</code>

== Appendix A: Example Implementation ==
In the below examples, you will see the overall DAR flow (Figure 1) and a detailed illustrative Ad Request / Response model (Figure 2).

<div align="center">'''Figure 1 – End to End Data Flow'''</div>

[[File:mDAR_Dataflow.png|center|link=]]

Nielsen certified publishers and platforms will append the new parameters (below) with the appropriate URL safe values passed to Nielsen’s current DAR tag. The current DAR tag should be acquired using the existing processes for each campaign/placement.
<code>'''&c7'''=osgrp,IOS'''&c8'''=devgrp,PHN'''&c9'''=devid,XXXX-XX-XXXXXXXXX'''&c10'''=plt,MBL'''&c12'''=apv,AppVersion'''&c13'''=asid,XXXX-XX-XXXX-XXXX</code>

<div align="center">'''Figure 2 – Illustrative Ad Request / Ad Response'''</div>

[[File:ad_response.png|center|link=]]

The above is an example of how an Ad server is supporting the build of mobile DAR tags for its publisher clients. Step 2 in Figure 1 is a summary of steps 1 and 2 in Figure 2 above. Steps 3 and 4 in Figure 1 is a summary of steps 3 through 9 in Figure 2 above.

== Appendix B: Implementation, Testing & Certification ==
Once you have integrated the ping per the above specs, Nielsen requires you to pass through a one-time certification before traffic can be accepted into the production environment.

The overall process is:
# Valid DAR contract or NDA is in place.
# Kick-off meeting with Nielsen onboarding team.
# Confirm meet minimums testing requriements:
## Host Ad/Tag for in-app delivery
## Can pass opt-out back to Nielsen
## Can pass Device ID in cleartext or SHA-256
# Nielsen provides the mDAR testing form that includes the test App ID and the test tag
# Implement the specification and provide Nielsen the completed testing form.
# Identify the live campaigns for intial testing and run the test tag; suggest 5,000-10,000 impressions.
# Nielsen validates the data received from the test and confirms the initial test successful and provides the production App ID.
## Goal is to test that all minimum requirements in step 3 are confirmed passed to Nielsen with no issues.
# Ensure contracts are in place for external test campaign with Nielsen Client Service team.
# Identify another live campaigns for production testing with production tag and app ID.
# Nielsen validates the data received from the final test and confirms certification for any DAR countries tested.
## Goal to test in full DAR E2E environment, receive matches from data provider for demographics and correct identification of mobile impressions.

iOS SDK API Reference

2017-07-12T21:16:31Z

Admin2: /* AppApiErrorCode */

{{Breadcrumb|}} {{Breadcrumb|Digital}} {{CurrentBreadcrumb}}
[[Category:Digital]]
The iOS 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. These SDKs leverage the following:
*Nielsen audio watermark technologies for TV audience measurement
*The industry supported ID3 metadata tag specification
*Nielsen Combined Beacon technology
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
*Application crash events
*Time of viewing a sub section / page in the application.

== Importing Frameworks ==
'''Setting up your Xcode Development Environment'''

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

SDK uses the NSURLSession available from iOS 7 instead of the deprecated NSURLConnection.

<blockquote>'''Note''': App SDK supports devices running on iOS 9 and above, as all communications between the SDK and the Census (Collection Facility) use HTTPS.</blockquote>

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 (Not applicable for International (Germany))
* 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

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

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

== Initialization ==
The latest version of App SDK allows instantiating multiple instances of App SDK object and can be used simultaneously without any issues (The sharedInstance API that creates a singleton object in previous versions of App SDK is removed).
*Maximum of four SDK instances per appid are supported in this release. When a fifth SDK instance is launched,
**SDK will return “nil” from [[initWithAppInfo:delegate:]]
**Destroy one or more old SDK instances before creating new ones.

=== Stages of SDK Initialization ===
==== Step 1: App SDK Initialization ====
Initialize the Nielsen App object within the viewDidLoad view controller delegate method using initWithAppInfo:delegate:
<blockquote>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.</blockquote>

==== Step 2: Setting up event and error notifications ====
Once the <code>NielsenAppApi</code> object has been initialized, the next step is to enable notifications regarding ID3 tags extracted from the playing stream. In case of standard AVFoundation player, the SDK NSNotificationCenter API is used to
* Collect HLS timed metadata events (ID3 tags) during viewing sessions.
** Set up a timed metadata event listener method for receiving ID3 tags and calling Nielsen [[sendID3]].
* SDK uses the following NielsenAppApiDelegate protocol methods to notify its delegate (set during initialization) about event / error information.
** nielsenAppApi:eventOccurred
** nielsenAppApi:errorOccurred
<blockquote>'''Note''': Ensure to add to your view controller’s <code>@interface</code>.</blockquote>

<syntaxhighlight lang="objective-c">(void)nielsenAppApi:(NielsenAppApi *)appApi eventOccurred:(NSDictionary *)event {NSLog(@"Sample player is Notified by a Event : %@", event);
}
(void)nielsenAppApi:(NielsenAppApi *)appApi errorOccurred:(NSDictionary *)error {NSLog(@"Sample player is Notified by an Error : %@", error);
}</syntaxhighlight>

===== Sample event confirmation to player application upon successful initialization of SDK =====
<syntaxhighlight lang="console">NielsenSDKSampleDebug[9028:237989] [Nls:0] -I- Analytics framework Status:
{
"Event Description" = "Nielsen App SDK Version, ai.4.0.0.4 is initialized by the Player…";
EventStatus = 2001;
TimeStamp = "2015-07-23 14:51:06 +0000";
}</syntaxhighlight>

==== Step 3: Nielsen App SDK Streaming Sessions ====
After setting up observers for SDK events/errors and a listener method to process incoming Nielsen ID3 tags, the next steps are to
* Call [[play]] while starting or resuming a streaming session.
* Load CMS metadata using [[loadMetadata]].
* During session play, call [[playheadPosition]] every one second until the stream is stopped or interrupted (due to ad breaks or buffering).
* Call [[stop]] when pausing, ending a viewing session, or buffering is detected.

'''Serialized JSON string from NSDictionary'''
<syntaxhighlight lang="objective-c">NSDictionary* appInformation = @
{
@"appid": @"TXXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX",
@"appname": @"Sample App Name",
@"appversion": @"2.0",
@"sfcode": @"uat-cert",
@"nol_devDebug": @"INFO"
}
NSData* jsonDataAppInfo = [NSJSONSerialization dataWithJSONObject:appInformation options:0 error:nil];
NSString *jsonAppInfoString = [[NSString alloc] initWithData:jsonDataAppInfo encoding:NSUTF8StringEncoding];
nlsAppApiMeter = [[NielsenAppApi alloc] initWithAppInfo:jsonAppInfoString delegate:self];</syntaxhighlight>

Nielsen App SDK object handles filtering of ID3 tags and CMS tags, queuing/buffering of data, and all communications with Nielsen collection facility.

===== Nielsen iOS App SDK Application Life Cycle =====

[[File:initialization_appcycle.png|center|link=]]

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 '''Initial state'''.
# '''Idle state''' – The SDK is initialized and is ready to process playing information. Call <code>[[initWithAppInfo:delegate:]]</code> to move into this state. The SDK instance is not processing any data, but is listening for the play event to occur.
# '''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.
## [[playheadPosition]] – Call this API every one second when playhead position timer is fired.
## [[sendID3]] – Call this API when ID3 tags are identified in the stream.
## [[stop]] – Call this API when the playback is paused, switches between content and ad (within the same content playback) or encounters interruptions.
## [[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. SDK instance moves into this state in one of the following scenarios.
## Initialization fails
## [[appDisableApi]] is called
<blockquote>'''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 [[sendID3]] / [[playheadPosition]].</blockquote>

=== 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.
{| class="wikitable"
|-
! API call received !! Initial State !! Idle State !! Processing State !! Disabled State
|-
| <code>[[initWithAppInfo:delegate:]]</code> || IDLE STATE (OR)

DISABLED STATE
|| IDLE STATE || - || -
|-
| <code>[[play]]</code> & <code>[[loadMetadata]]</code>|| - || PROCESSING

STATE
|| - || -
|-
| <code>[[playheadPosition]]</code> || - || - || PROCESSING

STATE
|| -
|-
| <code>[[sendID3]]</code> || - || - || PROCESSING

STATE
|| -
|-
| <code>[[stop]]</code> || - || - || IDLE STATE || -
|-
| <code>[[end]]</code> || - || - || IDLE STATE || -
|-
| <code>[[appDisableApi]]</code>: YES || - || DISABLED

STATE
|| - || -
|-
| <code>[[appDisableApi]]</code>: NO || - || - || - || IDLE STATE (OR)

DISABLED STATE
|-
| <code>[[userOptOut]]</code>: YES || - || - || IDLE STATE || -
|-
| <code>[[userOptOut]]</code>: NO || - || PROCESSING

STATE
| -
| -
|-
| colspan = 5 | '-' 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.

==== JSON for NSDictionary object ====
<syntaxhighlight lang="objective-c">
NSDictionary* appInformation = @{
@"appid": @"TXXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX",
@"appname": @"Sample App Name",
@"appversion": @"2.0",
@"sfcode": @"uat-cert",
@"nol_devDebug": @"INFO"
};
nlsAppApiMeter = [[NielsenAppApi alloc] initWithAppInfo:appInformation delegate:delegate];</syntaxhighlight>

<code>appid</code>, <code>appname</code>, and <code>appversion</code> are mandatory parameters while <code>sfcode</code> is optional. <code>nol_devDebug</code> is meant for creating logs in test environments only.

==== JSON string from raw NSString ====
<syntaxhighlight lang="swift">NSString *appInfoString = @"{\"appid\" : \"TXXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX\", \"appname\" : \"Sample App Name\",\"appversion\" : \"2.0\",\"sfcode\" : \"uat-cert\"}";
NielsenAppAPi *appAPI = [[NielsenAppApi alloc] initWithAppInfo:appInfoString delegate:self];</syntaxhighlight>

==== JSON string from serialized NSDictionary ====
<syntaxhighlight lang="objective-c">NSDictionary* appInformation = @
{
@"appid": @"appid",
@"appname": @"appname",
@"appversion": @"2.0",
@"sfcode": @"sfcode",
@"nol_devDebug": @"INFO"
};
nlsAppApiMeter = [[NielsenAppApi alloc] initWithAppInfo:appInformation delegate:self];</syntaxhighlight>

While using JSON format for sending metadat, ensure enough care in including [[special characters]] in the values for arguments.

==== Example ====
<syntaxhighlight lang="objective-c">{
@"type": @"radio", // To send "radio" in metadata string
@"assetid": @"WXYZ-FM'101",
@"stationType": @"3",
@"provider": @"SampleProvider" // To send "SampleProvider" in metadata string
}</syntaxhighlight>
<blockquote>'''Note''': For mandatory parameters like appid, appname, and appversion, please refer to the parameters table in <code>[[initWithAppInfo:delegate:]]</code></blockquote>

== Retrieving ID3 Tags ==
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.

=== Sample ID3 tags ===
* <code>www.nielsen.com/X100zdCIGeIlgZnkYj6UvQ==/X100zdCIGeIlgZnkYj6UvQ==/AAAB2Jz2_k74GXSzx4npHuI_JwJd3QSUpW30rDkGTcbHEzIMWleCzM-uvNOP9fzJcQMWQLJqzXMCAxParOb5sGijSV9dNM3QiBniJYGZ5GI-lL1fXTTN0IgZ4iWBmeRiPpS9AAAAAAAAAAAAAAAAAAAAAFJWFM5SVhTONNU=/00000/00000/00</code>
* <code>www.nielsen.com/X100zdCIGeIlgZnkYj6UvQ==/R8WHe7pEBeqBhu8jTeXydg==/AAICoyitYqlxT7n6aZ0oMCGheFi4CXFp46AMUPZz1lMr_M9tr3_cjee1SHqxrOiVerMDLeyn9xzocZSKwi746Re8vNOtpNCAZjYABs_J0R25IHpvOc1HS8QHGgD5TgOJeS6gX100zdCIGeIlgZnkYj6UvVJWFNhSVhTiPE0=/00000/46016/00</code>

=== Examples of extracting ID3 tags from the iOS Native Player ===
==== AVPlayer ====
ID3 tags will be received in the Player on AVMetadataItem Callback method.
'''Create & get the AVMetadataItem callback method'''
<syntaxhighlight lang="swift">[self.player addObserver:self
forKeyPath: kTimedMetadataKey
options: NSKeyValueObservingOptionNew
Context: MyStreamingMovieViewControllerTimedMetadataObserverContext];</syntaxhighlight>

<syntaxhighlight lang="objective-c">
– (void)observeValueForKeyPath:(NSString*) path
ofObject: (id)object
change: (NSDictionary*)change
context: (void*)context
{
/* Set the AVPlayerLayer on the view to allow the AVPlayer object to display
its content. */
//[playerLayerView.playerLayer setPlayer:player];
/* AVPlayerItem "status" property value observer. */
if (context == MyStreamingMovieViewControllerTimedMetadataObserverContext)
{
id newMetadataArray = [change objectForKey:NSKeyValueChangeNewKey];
if (newMetadataArray != [NSNull null])
{
array = newMetadataArray;
for (AVMetadataItem *metadataItem in array)
{
[self handleTimedMetadata: metadataItem];
}
}
}
</syntaxhighlight>

<syntaxhighlight lang="objective-c">
– (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;
}
if ([(NSString *)[timedMetadata key] isEqualToString:@"PRIV"]&&[extraString rangeOfString:@"www.nielsen.com"].length> 0)
{
if ([[timedMetadata value] isKindOfClass:[NSData class]])
{
// Sending ID3 Tag
/* The sendID3: sends the extracted Nielsen ID3 payload to the App SDK for analysis. */
[[NielsenAppApi sharedInstance]sendID3: extraString];
NSString *value=[timedMetadata stringValue];
if (value != nil)
{
// NSString *strMessage=[[@"ID3 Tag Received " stringByAppendingFormat:@"%d\n",countForMetadata] stringByAppendingString:value];
[self appendLogConsoleText:extraString];
}
}
}
else
{
NSLog(@"Could not send ID3 tags");
}
countForMetadata++;

}
</syntaxhighlight>

==== Movie Player ====
ID3 tags will be received in the Player on MPTimedMetadata Callback method.
'''Sample Implementation of MPTimedMetadata callback'''
<syntaxhighlight lang="objective-c">
– (void)handleTimedMetadata:(MPTimedMetadata*)timedMetadata
{
id extraAttributeType = [timedMetadata allMetadata];
NSString * extraString= nil;
if ([extraAttributeType isKindOfClass:[NSDictionary class]])
{
extraString = [extraAttributeType valueForKey:@"info"];
}
else if([extraAttributeType isKindOfClass:[NSString class]])
{
extraString = extraAttributeType;
}

if ([(NSString *)[timedMetadata key] isEqualToString:@"PRIV"]&&[extraString rangeOfString:@"www.nielsen.com"].length> 0)
{
if ([[timedMetadata value] isKindOfClass:[NSData class]])
{
// Sending ID3 Tag
[[NielsenAppApi sharedInstance]sendID3: extraString];
NSString *value=[timedMetadata value];
if (value != nil)
{

[self appendLogConsoleText:extraString];
}
}
}
else
{
NSLog(@"Could not send ID3 tags");
}
countForMetadata++;
}
</syntaxhighlight>
<blockquote>'''Note:''' ID3 tags are not applicable for International (Germany)</blockquote>

== IOS SDK API Methods & Properties ==
{| class="wikitable sortable"
|-
! Scenario !! Method / Property !! DTVR !! DAR !! Digital Audio !! 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 || [[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.
|-
| 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)
|}

== 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 to this web page should be called from SDK by invoking [[optOutURL]] and opened in 'WebView' / External browser.
*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 [[optOutStatus]] method.

=== Displaying Opt-Out in a WebView ===
<syntaxhighlight lang="objective-c">NielsenAppApi nAppApiObject;
@property(strong) UIWebView *optOutView;

// create WebView and set self as delegate
self.optOutView=[[UIWebViewalloc]initWithFrame:self.view.bounds];

self.optOutView.scalesPageToFit = yes;
// get Nielsen defined web address and load the page
NSString *webAddress = [nAppApiObject optOutURLString];

if(webAddress == nil)
{ // Handle it gracefully and retry later}
else
{
[optOutView loadRequest:[NSURLRequest requestWithURL:webAddress]];
// show the view to the user
[self.view addSubview:optOutView];
}</syntaxhighlight>

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.

[[File:Privacy policy iOS.jpg|link=]]

*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.
<syntaxhighlight lang="objective-c">
@property (readonly) BOOL optOutStatus;
</syntaxhighlight>
*App should provide a UI control like 'close' or 'back' button to close the 'WebView' / External browser.

=== Sequence Diagram ===
[[File:optoutsequence-ios.jpg|link=]]

== Opt-out SDK Version '''5.1.1.17 or above''' ==
<blockquote>'''Note:''' If using SDK Versions 1.2.3, 4.0.0.8, 5.1.0, 5.1.1.12, skip ahead to: [[#Opt-out SDK Version 1.2.3, 4.0.0.8, 5.1.0, 5.1.1.12|Opt-out SDK Version 1.2.3, 4.0.0.8, 5.1.0, 5.1.1.12]]</blockquote>

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.

[[File:Opt-Out iOS.jpg|link=]]

<blockquote>'''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.</blockquote>

== Opt-out SDK Version '''1.2.3, 4.0.0.8, 5.1.0, 5.1.1.12''' ==
<blockquote>'''Note:''' If using SDK Version 5.1.1.17 or above, refer to documentation above ([[#Opt-out SDK Version 5.1.1.17 or above|Opt-out SDK Version 5.1.1.17 or above]])</blockquote>

When a user clicks the Opt-Out / Opt-In link, the application should invoke [[optOutURL]] to get the link to the Nielsen Privacy page from SDK.
=== Privacy Page ===
[[File:privacy-policy.jpg|link=]]
*There are two click here links – one for Opt-Out and one for Opt-In. Click the required link:
**
[[File:Opt-Out Combined.jpg|link=]]
*Click OK in the dialog that appears, to confirm the action.
*The Opt-Out occurs by opening a Nielsen-defined web page and passing the user choice from the 'WebView'. In order to do this, the application needs to
**Implement the UIWebView delegate method to open the Nielsen Privacy web page
**Capture user's selection
**Pass the selection back to the SDK via the [[userOptOut]].

=== Capture and forward user selection ===
<syntaxhighlight lang="objective-c">-(BOOL)webView:(UIWebView *)webView shouldStartLoadWithRequest:(NSURLRequest *)request navigationType:(UIWebViewNavigationType)navigationType
{
NSString *command = [NSString stringWithFormat:@”%@”,request.URL];
if ([command isEqualToString:kNielsenWebClose]) {
// Close the WebView
[self performSelector:@selector(closeOptOutView) withObject:nil afterDelay:0];
return NO;
}
// Retrieve next URL if it’s not opt-in/out selection
return (![nAppApiObject userOptOut:command]);
}</syntaxhighlight>

*The app gets the user selection string via webviews shouldStartLoadWithRequest and invokes [[userOptOut]] with user selection. The delegate method handles the 'WebView' URL requests, interprets the commands, and calls the SDK accordingly.
**<code>[nAppApiObject userOptOut:command]</code> passes the user's selection on Nielsen Privacy page to the SDK to allow the SDK to perform the required functions.
<blockquote>'''Note:''' When 'WebView' is closed, pass the status returned from 'WebView' to the SDK within the app.</blockquote>
<blockquote>'''Note:''' App SDK manages the user's choice (Opt-Out / Opt-In), the app does not need to manage this status.</blockquote>

== 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:

[[File:TVOs OptOut LimitAdTracking1.png|link=]]

[[File:TVOs OptOut LimitAdTracking2.png|link=]]

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.

<blockquote>'''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.</blockquote>

== 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:
<syntaxhighlight lang="objective-c">
@interface NielsenAppApi: NSObject

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

– (instancetype)initWithAppInfo:(id)appInfo delegate:(id)delegate;

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

– (NSString *)getNielsenId _attribute((deprecated((“Please use nielsenId property instead.”))));
– (NSString *)optOutURLString _attribute((deprecated((“Please use optOutURL property instead.”))));
– (NSString *)getMeterVersion _attribute((deprecated((“Please use meterVersion property instead.”))));
– (NSDictionary *)getLastEventDict _attribute((deprecated((“Please use lastEventDict property instead.”))));
– (NSDictionary *)getLastErrorDict _attribute((deprecated((“Please use lastErrorDict property instead.”))));

@protocol NielsenAppApiDelegate<NSObject>

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

@end
</syntaxhighlight>

== Nielsen Sample Applications ==
Nielsen iOS sample player application consists of two sample application based on native Players integrated with SDK framework. The player demonstrates all the supported functions of the SDK.
*NielsenVideoPlayer
*NielsenRadioPlayer
Implementation of Video and Audio 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 two locations:
**Channels 1 and 2 are configured from the Settings application. Channel URLs and metadata parameters can be modified.
**Channels starting from 3 are configured in specific JSON file. URLs to this JSON config file can be changed from the Settings application.

== Nielsen Privacy Requirements ==
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.
[[File:RatingsDataFlow.png]]

'''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 ===
{| class="wikitable"
|-
! Type of Information !! Parameter !! Transmitted to Nielsen? !! Sent to Provider?
|-
| rowspan="8" | 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
|-
| rowspan="10" | 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
|-
| rowspan="9" | 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
|}
<blockquote>'''Note''': Data is hashed, and encrypted using AES 128 before transmission to data provider.</blockquote>

==== Example ping sent to provider ====
* <code><nowiki>https://provider.com/cgi-bin/brandlift.php</nowiki>?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</code>

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

=== Nielsen Measurement Opt-Out ===
In accordance with Nielsen’s SDK licensing agreement, developers are required to provide basic informational data to users about Nielsen’s Privacy Policy with a navigation to additional information on Nielsen measurement.

Nielsen currently uses Limit Ad Tracking for the latest versions of the SDK (5.1.1.17 and above). However, for older SDK versions, the app must provide a means for the user to opt out, or opt back in to Nielsen Measurement. Users can opt out of Nielsen online measurement research through this feature.
* If the user has this app running on more than one mobile device, the user will need to opt out of this measurement on each device.
<blockquote>'''Note''': Opt Out feature does NOT rely on "Limit Ad Tracking" setting since Nielsen’s systems provide measurement metrics and do not serve ads to users.</blockquote>

In the Description of the app in App Store, include a short description about Nielsen measurement, as below.

<blockquote>'''Sample App Store Disclosure'''
This app features Nielsen proprietary measurement software which will allow you to contribute to market research, like Nielsen’s TV Ratings.

To learn more about our digital measurement products and your choices in regard to them, please visit http://www.nielsen.com/digitalprivacy for more information.

[[File:measurement-samplescreen.jpg]]</blockquote>

Both iOS-based and TVOS-based player applications need to confirm to Nielsen Privacy Requirements. Refer to the Opt-Out implementation guidelines for iOS and TVOS platforms respectively for more details.

== AppApiEventCode ==
An enumeration with predefined App SDK event state transition codes.
<syntaxhighlight lang="objective-c">
typedef NS_ENUM(unsigned int, AppApiEventCode)
{
AppApiStartup = 2001,
AppApiShutdown = 2002,
}AppApiEventCode;
</syntaxhighlight>

=== App SDK Event Codes ===
{| class="wikitable"
|-
! 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.
<syntaxhighlight lang="objective-c">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.
};</syntaxhighlight>

For, 1001-1009, an enumeration with predefined error codes which the App SDK object can generate.
<syntaxhighlight lang="objective-c">
typedef NS_ENUM(unsigned int, AppApiErrorCode)
{
AppApiNetworkConnectionFailure = 1001,
AppApiFileWriteFailure = 1002,
AppApiFileReadFailure = 1003,
AppApiEmptyValue = 1004,
AppApiEmptyAppName = 1005,
AppApiEmptyAppVersion = 1006,
AppApiEmptyAppId = 1007,
AppApiAnExceptionOccured = 1008,
AppApiUnknownExceptionOccured = 1009
};
</syntaxhighlight>

=== App SDK Error Codes ===
{| class="wikitable"
|-
! 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
|}

{| class="wikitable"
|-
! 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
|}

Android SDK API Reference

2017-07-12T20:54:43Z

Admin2: /* App SDK Error Codes */

{{Breadcrumb|}} {{Breadcrumb|Digital}} {{CurrentBreadcrumb}}
[[Category:Digital]]
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.
*Create and initialize an instance object of <code>AppSdk</code> class.
*The player application can use this object to collect HLS timed metadata through a [[sendID3()]] call.
The Nielsen App SDK class is defined as the only public class belonging to the com.nielsen.app.sdk package. It inherits from the closeable interface and exposes the public APIs the client’s app will use. Below is the declaration of the <code>AppSdk</code> class: <code>public class AppSdk implements Closeable</code>

== Setting Up Development Environment ==
'''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.
<blockquote>'''Note''': App SDK 4.0.0 contains AppSDK.jar component only and does not support C/C++ libAppSdk.so components.</blockquote

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.

=== Setting up in Eclipse IDE ===
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.
<syntaxhighlight lang="java"><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"/></syntaxhighlight>
For more details to handle runtime permissions in Android versions, please visit [https://developer.android.com/training/permissions/requesting.html]. 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.

[[File:andr-properties-drm.jpg|link=]]

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

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

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.
Nielsen App SDK uses the following packages/classes from the Google Play service.

'''Library''':
* 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;

=== Setting up in Android Studio IDE ===
Launch '''Android Studio''' and select '''Import project (Eclipse ADT)'''.

[[File:andr-setup-launch.jpg|link=]]

Browse for project destination directory and click '''Next'''.

[[File:andr-import-project.jpg|link=]]

Go to '''File > Project Structure > App > Dependencies'''.

[[File:andr-pro-structure.jpg|link=]]

Click '''+''' to add library dependency.

Select '''play-services''' and click '''OK'''

[[File:andr-choose-library.jpg|link=]]

For more information, refer to https://developer.android.com/google/play-services/setup.html

== Initialization ==
=== Android Application Life Cycle with respect to Nielsen App SDK ===
[[File:andr-init-img1.jpg|link=]]

=== Step 1: App SDK initialization ===
==== For API version 4.0.0 and above ====

[[AppSDK()]] is no longer a singleton object and should be initialized as below.

'''Initialization of App SDK object through a JSON object'''
<syntaxhighlight lang="objective-c">
JSONObject config = null;

try
{
// Prepare AppSdk configuration object (JSONObject)
JSONObject appSdkConfig = new JSONObject()
.put("appid", "TXXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX")
.put("appname", "Sample App Name")
.put("sfcode", "uat-cert")
.put("nol_devDebug", "INFO") // only for debug builds
.put("custom_key1", "custom_value1")
.put("custom_key2", "custom_value2");
// 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);
}
</syntaxhighlight>

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

==== Android Application Life Cycle with respect to Nielsen App SDK ====
[[File:andr-radioandvideo-app.jpg|link=]]

=== Step 2: App SDK libraries inclusion in project ===
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).

=== Step 3: Nielsen App SDK Streaming Sessions ===
After ensuring that the SDK object has been initialized, link the streaming session APIs. The next steps are:
*Call [[play()]] when starting or resuming a streaming session. Use the channelName parameter to pass channel descriptor information. The channel name field is a 32-character free-form text field containing the name of the program or feed being sent (such as ESPN2, Food Network, etc.) which must be inserted on a JSON string.
*Load the CMS metadata by calling the [[loadMetadata()]] on the SDK object.
*Call [[stop()]] when ending or pausing a viewing session.
*During session playback, call the SDK [[setPlayheadPosition()]] and / or [[sendID3()]]
**Call [[setPlayheadPosition()]] every one second until the stream is stopped or paused. Normally this happens on Digital Audio measurements.
**Call [[sendID3()]] if the client relies on the Nielsen ID3 tags for its measurements; this call should happen whenever a new Nielsen ID3 metadata is available for processing. Normally this happens on DTVR and ID3 measurements.
Nielsen App SDK object handles filtering of ID3 tags and CMS tags, queuing/buffering of data, and all communications with Nielsen collection facility.
*The client’s app must clearly identify the mode of operation (live vs. VOD) and stick to the type of playhead coordinates until the playback is completed. The client must reliably provide the appropriated playhead position value depending on the type of content streamed.
*If streaming live video content, the client must pass the current UTC time in seconds as playhead position.
*If streaming VOD (video on demand), the client must stream the offset from the beginning of the file as playhead position.
*For all Digital Audio listening, the client must pass the current UTC time in seconds as playhead position, regardless of station type.

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

=== Sample ID3 tags ===
* <code>www.nielsen.com/X100zdCIGeIlgZnkYj6UvQ==/X100zdCIGeIlgZnkYj6UvQ==/AAAB2Jz2_k74GXSzx4npHuI_JwJd3QSUpW30rDkGTcbHEzIMWleCzM-uvNOP9fzJcQMWQLJqzXMCAxParOb5sGijSV9dNM3QiBniJYGZ5GI-lL1fXTTN0IgZ4iWBmeRiPpS9AAAAAAAAAAAAAAAAAAAAAFJWFM5SVhTONNU=/00000/00000/00</code>
* <code>www.nielsen.com/X100zdCIGeIlgZnkYj6UvQ==/R8WHe7pEBeqBhu8jTeXydg==/AAICoyitYqlxT7n6aZ0oMCGheFi4CXFp46AMUPZz1lMr_M9tr3_cjee1SHqxrOiVerMDLeyn9xzocZSKwi746Re8vNOtpNCAZjYABs_J0R25IHpvOc1HS8QHGgD5TgOJeS6gX100zdCIGeIlgZnkYj6UvVJWFNhSVhTiPE0=/00000/46016/00</code>
<blockquote>'''Note''': ID3 tags are not applicable for International (Germany)</blockquote>

=== Extracting ID3 tags from Android Players ===
==== ID3 Support Matrix ====
{| class="wikitable"
|-
! Player Name !! Minimum supported version !! Description
|-
| Android Native Media Player || Android 6 || Android 6 Media Player allows apps to register a callback to be invoked, when a selected track has the timed metadata available. Currently, only HTTP Live Streaming (HLS) data URI’s embedded with timed ID3 tags, generates TimedMetaData.
|-
| Google ExoPlayer || Android 4.1 ||
|-
| Brightcove Player || Android 4.1 || Support for Android versions 2.3.3 and 4.0 is now deprecated. Learn more about why Brightcove is removing support for these versions as of January 1, 2016 in this [https://support.brightcove.com/en/perform/docs/announcement-brightcove-sdk-android-version-support|announcement]
|-
| Adobe PrimeTime Player || Android 4.2 ||
|-
| VisualOn Player || Android 2.3 || Android 5 is the latest supported version
|-
| NexStream Player || Android 1.6 || Supported till Android 6
|}

==== Android Native Media Player ====
As the Android Media Player versions (prior to Android 6 / Android API 23) do not support ID3, Nielsen has created a library that becomes an extension to the media player, thus MPX. This library extracts the ID3 tags and sends them to the app. For more information on how to use the MPX component, refer to the Nielsen-supplied sample application.

Starting from '''Android 6 (Android API 23)''', Android Native Media Player allows apps to register a callback to be invoked, when a selected track has the timed metadata available. Currently, only HTTP Live Streaming (HLS) data URI’s embedded with timed ID3 tags generate TimedMetadata. Once the HLS video starts, call onTimedMetaDataAvailable() as and when the player observes a TimedMetadata (ID3 tag).

<syntaxhighlight lang="java">@Override
public void onTimedMetaDataAvailable(MediaPlayer mp, TimedMetaData data)
{
byte[] iD3PayloadArray = data.getMetaData();
String iD3Payload = new String(iD3PayloadArray, StandardCharsets.UTF_8);
if (null != iD3Payload && iD3Payload.contains("www.nielsen.com"))
{
int index = iD3Payload.indexOf("www.nielsen.com");
String id3String = iD3Payload.substring(index, (index + 249));
Log.d(TAG, "TimedMetaData ID3 Tag:" + id3String);
appProcessID3tag(id3String);
}
}</syntaxhighlight>

==== ExoPlayer ====
he SDK is designed around an event-driven architecture where components emit events to allow other components to listen and respond to state changes.

'''Player SDK Classes used:'''
<syntaxhighlight lang="java">com.google.android.exoplayer.demo.player.DemoPlayer</syntaxhighlight>

Since Nielsen App SDK is interested in extracting the Timed Metadata (ID3 Tags) in HLS and VOD on the EXO Player, trace the ID3_TAG emitted during video content played using EXOPlayer component as below.

<syntaxhighlight lang="java">DemoPlayer implements ExoPlayer.Listener
—————————————————–
/**
* A listener for receiving ID3 metadata parsed from the media stream.
*/
public interface Id3MetadataListener
{
void onId3Metadata(Map<String, Object> metadata);
}
——————————————————-
MetadataTrackRenderer.MetadataRenderer<Map<String,
Object>> getId3MetadataRenderer()
{
return new MetadataTrackRenderer.MetadataRenderer<Map<String, Object>>()
{
@Override
public void onMetadata(Map<String, Object> metadata)
{
if (id3MetadataListener != null)
{
id3MetadataListener.onId3Metadata(metadata);
}
}
};
}</syntaxhighlight>

Also in ''Player.java'' class:
<syntaxhighlight lang="java">Player implements DemoPlayer.Id3MetadataListener
—————————————————–
@SuppressWarnings("rawtypes")
@Override
public void onId3Metadata(Map<String, Object> metadata)
{
try
{
for (Object o : metadata.entrySet())
{
Map.Entry pairs = (Map.Entry) o;
if (metadata.containsKey(TxxxMetadata.TYPE))
{
TxxxMetadata txxxMetadata = (TxxxMetadata) metadata
.get(TxxxMetadata.TYPE);
}
else
{
String aStr = new String((byte[]) pairs.getValue());
MainActivity.mAppSdk.sendID3(aStr);
}
}
}
catch (Exception e)
{
e.printStackTrace();
Log.d(TAG, "onId3Metadata(): No Id3 tags");
}
}</syntaxhighlight>

[[File:andr-exo-retrievingID3tags.png|link=]]

==== Brightcove Player ====
While the Brightcove player plays the content, EventListener triggers an event when an ID3 packet is received (<code>SeamlessVideoDisplayComponent.ID3_TAG</code>). Upon receiving this event, collect the incoming ID3 tags and only pass the Nielsen payload of the PRIV frame to the App SDK for analysis.

<syntaxhighlight lang="java">brightcoveVideoView.getEventEmitter().on(SeamlessVideoDisplayComponent.ID3_TAG, new EventListener()
{
public void processEvent(Event event)
{
NlsId3Tag nlsID3 = new NlsId3Tag(event.properties.get(SeamlessVideoDisplayComponent.ID3_DATA).toString());
Log.w("ID3", nlsID3.NlsPayload);
// Sent ID3 Tags to App
appProcessID3tag(nlsID3.NlsPayload);
}
});
}</syntaxhighlight>

==== Adobe PrimeTime Player ====
While the Adobe PrimeTime player plays the content, MediaPlayer.PlaybackEventListener triggers a callback when an ID3 packet is received (onTimedMetadata). Upon receiving this event, collect the incoming ID3 tags and only pass the Nielsen payload of the PRIV frame to the App SDK for analysis.
<syntaxhighlight lang="java">public void onTimedMetadata(TimedMetadata id3Metadata)
{
NlsId3Tag nlsID3 = new NlsId3Tag(id3Metadata.getMetadata().toString());
Log.w(LOG_TAG, "ID3 Timed Data –> " + nlsID3.NlsPayload);
Log.w(LOG_TAG, "PayLoad Size –> " + nlsID3.NlsPayload.length());
appProcessID3tag(nlsID3.NlsPayload);
}</syntaxhighlight>

==== VisualOn Player ====
While the VisualOn player plays the content, <code>VOCommonPlayerListener</code> triggers an event when an ID3 packet is received (<code>VO_OSMP_SRC_CUSTOMERTAGID_TIMEDTAG</code>). Upon receiving this event, collect the incoming ID3 tags and only pass the Nielsen payload of the PRIV frame to the App SDK for analysis.

<syntaxhighlight lang="java">case VO_OSMP_SRC_CB_CUSTOMER_TAG:
{
VO_OSMP_SRC_CUSTOMERTAGID tag = VO_OSMP_SRC_CUSTOMERTAGID.valueOf(nParam1);
switch (tag)
{
case VO_OSMP_SRC_CUSTOMERTAGID_TIMEDTAG:
// do something with this tag
int time = nParam2;
byte[] b = (byte[]) obj;
String s = new String(b);
NlsId3Tag nlsID3 = new NlsId3Tag(b);
// Sent ID3 Tags to App
appProcessID3tag(nlsID3.NlsPayload);
if (appid3If != null)
appid3If.onId3(nlsID3.NlsPayload);
break;
case VO_OSMP_SRC_CUSTOMERTAGID_MAX:
// ignore this type of tag
break;
default:
break;
}
break;
}</syntaxhighlight>

==== NextStream Player ====
ID3 tags will be received in the NexStream Player through <code>onTimedMetaRenderRender(NexPlayer mp,NexID3TagInformation metadata)</code> callback API. A sample implementation for the callback is shown below:
<syntaxhighlight lang="java">public void onTimedMetaRenderRender(NexPlayer mp, NexID3TagInformation m)
{
text = m.getPrivateFrame();
if (text != null)
{
data = text.getTextData();
if (data != null)
{
// make sure to identify the beginning of the
// Nielsen ID3 tag payload by searching for the
// "www.nielsen.com" string on the ID3 tag and
// passing to the App SDK all information that
// follows. It should be:
// nlsPayload = "www.nielsen.com" + dataFollowing
nlsPayload = getDataAfterWwwNielsenCom(data);
if (nlsPayload!= NULL)
mAppSdk.sendID3(nlsPayload);
}
}
}</syntaxhighlight>

The [[sendID3()]] sends the extracted Nielsen ID3 payload to the App SDK for analysis.

== Android SDK API Methods & Properties ==
{| class="wikitable sortable"
|-
! Scenario !! Method / Property !! DTVR !! DAR !! Digital Audio !! DCR !! International (Germany) !! Description
|-
| Initialize || [[AppSDK()]] || ✔ || ✔ || ✔ || ✔ || ✔ || 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 when there is a preroll ad that needs to be associated with content metadata. The loadmetadata will first be called to populate the content metadata values and then the loadMetadata for ad metadata will be called. This allows sending a content ping with the ad info, even if the user bails out during the preroll ad.
|-
| Measurement || [[sendID3()]] || ✔ || ✘ || ✘ || ✘ || ✘ || Used to send the ID3 metadata.
|-
| Measurement || [[setPlayheadPosition()]] || ✘ || ✘ || ✔ || ✔ || ✔ || 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 || [[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 || [[userOptOutURLString()]] || ✔ || ✔ || ✔ || ✔ || ✔ || 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 || [[getOptOutStatus()]] || ✘ || ✘ || ✘ || ✘ || ✔ || Call this API to retrieve the Opt-Out or Opt-In state.
|-
| Opt-out
| [[appDisableApi()]]
(kill switch)
|| ✔ || ✔ || ✔ || ✔ || ✔ || Used to disable the SDK.
|-
| Opt-out || [[getAppDisable()]] || ✔ || ✔ || ✔ || ✔ || ✔ || Used to query if the SDK is disabled or not.
|-
| Log || [[getLastEvent()]] || ✔ || ✔ || ✔ || ✔ || ✔ || Used to query the SDK for the last status
|-
| Log || [[getLastError()]] || ✔ || ✔ || ✔ || ✔ || ✔ || Used to query the SDK for the last error
|-
| Log || [[isValid()]] || ✔ || ✔ || ✔ || ✔ || ✔ || Used to check if the SDK was successfully instantiated or not.
|-
| Log || [[getMeterVersion()]] || ✘ || ✘ || ✘ || ✘ || ✔ || Returns the current SDK version.
|-
| Log || [[getNielsenId()]] || ✔ || ✔ || ✔ || ✔ || ✔ || Used to get a string defining the Nielsen ID (NUID) number for the device.
|-
| Log || [[getDeviceId()]] || ✔ || ✔ || ✔ || ✔ || ✔ || Returns the current device id.
|-
| Log || [[appInBackground()]] || ✘ || ✘ || ✘ || ✔ || ✔ || Used to capture the event of app going to background.
|-
| Log || [[appInForeground()]] || ✘ || ✘ || ✘ || ✔ || ✔ || Used to capture the event of app coming to foreground
|-
| Log || [[setDebug()]] || ✘ || ✘ || ✘ || ✘ || ✔ || Used to enable/disable debug flags. Newly introduced in SDK version 5.0.0 for International (Germany)
|}

== 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.
*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.

=== Displaying Opt-Out in a WebView ===
<syntaxhighlight lang="java">
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
}
</syntaxhighlight>

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.

[[File:Privacy policy iOS.jpg|link=]]

<blockquote>'''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.</blockquote>

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

=== Sequence Diagram ===
[[File:optoutsequence-andr.jpg|link=]]

== Opt-out Android SDK Version '''5.1.1.18 or above''' ==
<blockquote>'''Note:''' If using Android SDK Versions 1.2.3, 4.0.0.8, 5.1.0, 5.1.1.14, skip ahead to: [[#Opt-out Android SDK Version 1.2.3, 4.0.0.8, 5.1.0, 5.1.1.14|Opt-out Android SDK Version 1.2.3, 4.0.0.8, 5.1.0, 5.1.1.14]]</blockquote>

Starting from SDK version 5.1.1.18, Opt-Out related behavior has been changed in the following ways:
*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'''.
<blockquote>'''Note:''' For Amazon devices, see [[#Opt-Out Implementation for Amazon Devices|Opt-Out Implementation for Amazon Devices]] below.</blockquote>

[[File:andr-ads.jpg|link=]]

<blockquote>'''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.</blockquote>

== Opt-out Android SDK Version '''1.2.3, 4.0.0.8, 5.1.0, 5.1.1.14''' ==
<blockquote>'''Note:''' If using Android SDK Version 5.1.1.18 or above, refer to documentation above ([[#Opt-out Android SDK Version 5.1.1.18 or above|Opt-out Android SDK Version 5.1.1.18 or above]])</blockquote>

When a user clicks the Opt-Out / Opt-In link, the application should invoke [[optOutURL]] to get the link to the Nielsen Privacy page from SDK.
=== Privacy Page ===
[[File:privacy-policy.jpg|link=]]
*There are two click here links – one for Opt-Out and one for Opt-In. Click the required link:
**Capture user’s selection
**Pass the selection back to the SDK via the [[userOptOut()]].

=== Capture and forward user selection ===
<syntaxhighlight lang="java">
private class MonitorWebView extends WebViewClient
{
private static final String NIELSEN_URL_OPT_OUT = “nielsenappsdk://1”;
private static final String NIELSEN_URL_OPT_IN = “nielsenappsdk://0”;

@Override
public boolean shouldOverrideUrlLoading(WebView view, String url)
{
if (NIELSEN_URL_OPT_OUT.equals(url)
|| NIELSEN_URL_OPT_IN.equals(url))
{
// Get AppSdk instance from the host
AppSdk appSdk = HostApp.getAppSdk();
// Send the URL to the AppSdk instance
appSdk.userOptOut(url);
return true;
}
return false;
}
}
</syntaxhighlight>

<blockquote>'''Note:''' When 'WebView' is closed, pass the status returned from 'WebView' to the SDK within the app.</blockquote>
<blockquote>'''Note:''' App SDK manages the user's choice (Opt-Out / Opt-In), the app does not need to manage this status.</blockquote>

== 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 ===

<syntaxhighlight lang="java">
ContentResolver cr = getContentResolver();
int limitAdTracking = Secure.getInt(cr, "limit_ad_tracking", 2);
</syntaxhighlight>

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

<blockquote>'''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'''.</blockquote>

== Nielsen Sample Applications ==

== Nielsen Privacy Requirements ==
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.
[[File:RatingsDataFlow.png]]

'''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 ===
{| class="wikitable"
|-
! Type of Information !! Parameter !! Transmitted to Nielsen? !! Sent to Provider?
|-
| rowspan="8" | 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
|-
| rowspan="10" | 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
|-
| rowspan="9" | 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
|}
<blockquote>'''Note''': Data is hashed, and encrypted using AES 128 before transmission to data provider.</blockquote>

==== Example ping sent to provider ====
* <code><nowiki>https://provider.com/cgi-bin/brandlift.php</nowiki>?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</code>

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

=== Nielsen Measurement Opt-Out ===
In accordance with Nielsen’s SDK licensing agreement, developers are required to provide basic informational data to users about Nielsen’s Privacy Policy with a navigation to additional information on Nielsen measurement.

Nielsen currently uses Opt Out of Ads for Personalization for the latest versions of the SDK (5.1.1.18 and above). However, for older SDK versions, the app must provide a means for the user to opt out, or opt back in to Nielsen Measurement. Users can opt out of Nielsen online measurement research through this feature.
* If the user has this app running on more than one mobile device, the user will need to opt out of this measurement on each device.
<blockquote>'''Note''': Opt Out feature does NOT rely on "Opt Out of Ads for Personalization" setting since Nielsen’s systems provide measurement metrics and do not serve ads to users.</blockquote>

In the Description of the app in Google Play Store, include a short description about Nielsen measurement, as below.

<blockquote>'''Sample Google Play Store Disclosure'''
This app features Nielsen proprietary measurement software which will allow you to contribute to market research, like Nielsen’s TV Ratings.

To learn more about our digital measurement products and your choices in regard to them, please visit http://www.nielsen.com/digitalprivacy for more information.</blockquote>

== Event and Error Handling ==
=== App SDK Event Codes ===
{| class="wikitable"
|-
! Event Code !! Event Name !! Event Description
|-
| 2000 || EVENT_INITIATE || App SDK is initiated. It will happen as soon as the App SDK is initialized
|-
| 2001 || EVENT_STARTUP || App SDK has started up. It will happen only after App SDK has received a valid config file. This is the location in the code to acquire the value of [[userOptOutURLString()]].
|-
| 2002 || EVENT_SHUTDOWN || App SDK is shutting down. It will happen just before App SDK is destroyed
|}

=== App SDK Error Codes ===
Constants with predefined error codes which the AppSdk object can generate.

{| class="wikitable"
|-
! Error Code !! Error Name !! Description !! Behavior
|-
| 1001 || ERROR_FAILED_CREATE_URL_STRING || Failed generating ping string due to error on parsing || Include last error message from URL parser
|-
| 1002 || ERROR_FAILED_RECEIVE_CONFIG || Failed to receive configuration file from Census || On 5th time, it will log event and keep requesting config 10 min apart
|-
| 1003 || ERROR_FAILED_PARSING_CONFIG || Failed parsing the config file JSON string || Include json error number/short message from iOS or Android
|-
| 1004 || ERROR_FAILED_PARSING_PLAY || Failed parsing the play() JSON string || Include JSON error number/short message from iOS or Android
|-
| 1005 || ERROR_FAILED_PARSING_METADATA || Failed parsing the play() JSON string || Include JSON error number/short message from iOS or Android
|-
| 1006 || ERROR_FAILED_GENERATING_PING || Failed creating ping before adding it to the UPLOAD table) || Include ping nol_url index, cadence to identify ping
|-
| 1007 || ERROR_FAILED_PROCESSOR_START || Failed starting data processor thread. Normally, that means a product || Include processor that failed to start
|-
| 1008 || ERROR_FAILED_PROCESS_ID3 || Failed processing data on a data processor. Normally, that means the input to a product || Include processor and data that failed to process (ID3 tag on a MTVR impression, for example)
|-
| 1009 || ERROR_FAILED_HTTP_SEND || Failed sending HTTP or HTTPS requests || Include HTTP error number
|-
| 1010 || ERROR_FAILED_SENDING_PING || Failed sending pings (on ANDROID, the ping on the UPLOAD table) || Include ping up to 80 char from the end
|-
| 1011 || ERROR_FAILED_SENDING_TSV || Failed sending TSV requests || Include TSV request message
|-
| 1012 || ERROR_FAILED_SENDING_STATION_ID || Failed sending Station ID requests || Include Station ID request message
|-
| 1013 || ERROR_FAILED_ACCESSING_DB || Failed read/write from/to database table || Include SQL statement and data and SQLite error number/message
|-
| 1014 || ERROR_CHANGED_DEVICE_ID || Device ID changed ||
|-
| 1015 || ERROR_CHANGED_NUID || NUID changed ||
|-
| 1016 || ERROR_SDK_NOT_INITIALIZED || App SDK initialization failed ||
|-
| 1017 || ERROR_FAILED_SDK_SUSPEND || App SDK failed to suspend activities ||
|-
| 1018 || ERROR_INVALID_PARAMETERS || App SDK invalid parameters ||
|-
| 1019 || ERROR_INVALID_STATE || App SDK called in incorrect state ||
|-
| 1020 || ERROR_FAILED_PROCESS_PLAYHEAD || App SDK failed processing playhead position ||
|-
| 1021 || ERROR_FAILED_PROCESS_METADATA || App SDK failed processing not-null, syntax valid JSON metadada ||
|-
| 1022 || ERROR_FAILED_PROCESS_STOP || App SDK failed processing stop ||
|}

Android SDK API Reference

2017-07-12T20:06:23Z

Admin2: /* App SDK Event Codes */

{{Breadcrumb|}} {{Breadcrumb|Digital}} {{CurrentBreadcrumb}}
[[Category:Digital]]
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.
*Create and initialize an instance object of <code>AppSdk</code> class.
*The player application can use this object to collect HLS timed metadata through a [[sendID3()]] call.
The Nielsen App SDK class is defined as the only public class belonging to the com.nielsen.app.sdk package. It inherits from the closeable interface and exposes the public APIs the client’s app will use. Below is the declaration of the <code>AppSdk</code> class: <code>public class AppSdk implements Closeable</code>

== Setting Up Development Environment ==
'''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.
<blockquote>'''Note''': App SDK 4.0.0 contains AppSDK.jar component only and does not support C/C++ libAppSdk.so components.</blockquote

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.

=== Setting up in Eclipse IDE ===
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.
<syntaxhighlight lang="java"><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"/></syntaxhighlight>
For more details to handle runtime permissions in Android versions, please visit [https://developer.android.com/training/permissions/requesting.html]. 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.

[[File:andr-properties-drm.jpg|link=]]

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

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

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.
Nielsen App SDK uses the following packages/classes from the Google Play service.

'''Library''':
* 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;

=== Setting up in Android Studio IDE ===
Launch '''Android Studio''' and select '''Import project (Eclipse ADT)'''.

[[File:andr-setup-launch.jpg|link=]]

Browse for project destination directory and click '''Next'''.

[[File:andr-import-project.jpg|link=]]

Go to '''File > Project Structure > App > Dependencies'''.

[[File:andr-pro-structure.jpg|link=]]

Click '''+''' to add library dependency.

Select '''play-services''' and click '''OK'''

[[File:andr-choose-library.jpg|link=]]

For more information, refer to https://developer.android.com/google/play-services/setup.html

== Initialization ==
=== Android Application Life Cycle with respect to Nielsen App SDK ===
[[File:andr-init-img1.jpg|link=]]

=== Step 1: App SDK initialization ===
==== For API version 4.0.0 and above ====

[[AppSDK()]] is no longer a singleton object and should be initialized as below.

'''Initialization of App SDK object through a JSON object'''
<syntaxhighlight lang="objective-c">
JSONObject config = null;

try
{
// Prepare AppSdk configuration object (JSONObject)
JSONObject appSdkConfig = new JSONObject()
.put("appid", "TXXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX")
.put("appname", "Sample App Name")
.put("sfcode", "uat-cert")
.put("nol_devDebug", "INFO") // only for debug builds
.put("custom_key1", "custom_value1")
.put("custom_key2", "custom_value2");
// 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);
}
</syntaxhighlight>

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

==== Android Application Life Cycle with respect to Nielsen App SDK ====
[[File:andr-radioandvideo-app.jpg|link=]]

=== Step 2: App SDK libraries inclusion in project ===
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).

=== Step 3: Nielsen App SDK Streaming Sessions ===
After ensuring that the SDK object has been initialized, link the streaming session APIs. The next steps are:
*Call [[play()]] when starting or resuming a streaming session. Use the channelName parameter to pass channel descriptor information. The channel name field is a 32-character free-form text field containing the name of the program or feed being sent (such as ESPN2, Food Network, etc.) which must be inserted on a JSON string.
*Load the CMS metadata by calling the [[loadMetadata()]] on the SDK object.
*Call [[stop()]] when ending or pausing a viewing session.
*During session playback, call the SDK [[setPlayheadPosition()]] and / or [[sendID3()]]
**Call [[setPlayheadPosition()]] every one second until the stream is stopped or paused. Normally this happens on Digital Audio measurements.
**Call [[sendID3()]] if the client relies on the Nielsen ID3 tags for its measurements; this call should happen whenever a new Nielsen ID3 metadata is available for processing. Normally this happens on DTVR and ID3 measurements.
Nielsen App SDK object handles filtering of ID3 tags and CMS tags, queuing/buffering of data, and all communications with Nielsen collection facility.
*The client’s app must clearly identify the mode of operation (live vs. VOD) and stick to the type of playhead coordinates until the playback is completed. The client must reliably provide the appropriated playhead position value depending on the type of content streamed.
*If streaming live video content, the client must pass the current UTC time in seconds as playhead position.
*If streaming VOD (video on demand), the client must stream the offset from the beginning of the file as playhead position.
*For all Digital Audio listening, the client must pass the current UTC time in seconds as playhead position, regardless of station type.

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

=== Sample ID3 tags ===
* <code>www.nielsen.com/X100zdCIGeIlgZnkYj6UvQ==/X100zdCIGeIlgZnkYj6UvQ==/AAAB2Jz2_k74GXSzx4npHuI_JwJd3QSUpW30rDkGTcbHEzIMWleCzM-uvNOP9fzJcQMWQLJqzXMCAxParOb5sGijSV9dNM3QiBniJYGZ5GI-lL1fXTTN0IgZ4iWBmeRiPpS9AAAAAAAAAAAAAAAAAAAAAFJWFM5SVhTONNU=/00000/00000/00</code>
* <code>www.nielsen.com/X100zdCIGeIlgZnkYj6UvQ==/R8WHe7pEBeqBhu8jTeXydg==/AAICoyitYqlxT7n6aZ0oMCGheFi4CXFp46AMUPZz1lMr_M9tr3_cjee1SHqxrOiVerMDLeyn9xzocZSKwi746Re8vNOtpNCAZjYABs_J0R25IHpvOc1HS8QHGgD5TgOJeS6gX100zdCIGeIlgZnkYj6UvVJWFNhSVhTiPE0=/00000/46016/00</code>
<blockquote>'''Note''': ID3 tags are not applicable for International (Germany)</blockquote>

=== Extracting ID3 tags from Android Players ===
==== ID3 Support Matrix ====
{| class="wikitable"
|-
! Player Name !! Minimum supported version !! Description
|-
| Android Native Media Player || Android 6 || Android 6 Media Player allows apps to register a callback to be invoked, when a selected track has the timed metadata available. Currently, only HTTP Live Streaming (HLS) data URI’s embedded with timed ID3 tags, generates TimedMetaData.
|-
| Google ExoPlayer || Android 4.1 ||
|-
| Brightcove Player || Android 4.1 || Support for Android versions 2.3.3 and 4.0 is now deprecated. Learn more about why Brightcove is removing support for these versions as of January 1, 2016 in this [https://support.brightcove.com/en/perform/docs/announcement-brightcove-sdk-android-version-support|announcement]
|-
| Adobe PrimeTime Player || Android 4.2 ||
|-
| VisualOn Player || Android 2.3 || Android 5 is the latest supported version
|-
| NexStream Player || Android 1.6 || Supported till Android 6
|}

==== Android Native Media Player ====
As the Android Media Player versions (prior to Android 6 / Android API 23) do not support ID3, Nielsen has created a library that becomes an extension to the media player, thus MPX. This library extracts the ID3 tags and sends them to the app. For more information on how to use the MPX component, refer to the Nielsen-supplied sample application.

Starting from '''Android 6 (Android API 23)''', Android Native Media Player allows apps to register a callback to be invoked, when a selected track has the timed metadata available. Currently, only HTTP Live Streaming (HLS) data URI’s embedded with timed ID3 tags generate TimedMetadata. Once the HLS video starts, call onTimedMetaDataAvailable() as and when the player observes a TimedMetadata (ID3 tag).

<syntaxhighlight lang="java">@Override
public void onTimedMetaDataAvailable(MediaPlayer mp, TimedMetaData data)
{
byte[] iD3PayloadArray = data.getMetaData();
String iD3Payload = new String(iD3PayloadArray, StandardCharsets.UTF_8);
if (null != iD3Payload && iD3Payload.contains("www.nielsen.com"))
{
int index = iD3Payload.indexOf("www.nielsen.com");
String id3String = iD3Payload.substring(index, (index + 249));
Log.d(TAG, "TimedMetaData ID3 Tag:" + id3String);
appProcessID3tag(id3String);
}
}</syntaxhighlight>

==== ExoPlayer ====
he SDK is designed around an event-driven architecture where components emit events to allow other components to listen and respond to state changes.

'''Player SDK Classes used:'''
<syntaxhighlight lang="java">com.google.android.exoplayer.demo.player.DemoPlayer</syntaxhighlight>

Since Nielsen App SDK is interested in extracting the Timed Metadata (ID3 Tags) in HLS and VOD on the EXO Player, trace the ID3_TAG emitted during video content played using EXOPlayer component as below.

<syntaxhighlight lang="java">DemoPlayer implements ExoPlayer.Listener
—————————————————–
/**
* A listener for receiving ID3 metadata parsed from the media stream.
*/
public interface Id3MetadataListener
{
void onId3Metadata(Map<String, Object> metadata);
}
——————————————————-
MetadataTrackRenderer.MetadataRenderer<Map<String,
Object>> getId3MetadataRenderer()
{
return new MetadataTrackRenderer.MetadataRenderer<Map<String, Object>>()
{
@Override
public void onMetadata(Map<String, Object> metadata)
{
if (id3MetadataListener != null)
{
id3MetadataListener.onId3Metadata(metadata);
}
}
};
}</syntaxhighlight>

Also in ''Player.java'' class:
<syntaxhighlight lang="java">Player implements DemoPlayer.Id3MetadataListener
—————————————————–
@SuppressWarnings("rawtypes")
@Override
public void onId3Metadata(Map<String, Object> metadata)
{
try
{
for (Object o : metadata.entrySet())
{
Map.Entry pairs = (Map.Entry) o;
if (metadata.containsKey(TxxxMetadata.TYPE))
{
TxxxMetadata txxxMetadata = (TxxxMetadata) metadata
.get(TxxxMetadata.TYPE);
}
else
{
String aStr = new String((byte[]) pairs.getValue());
MainActivity.mAppSdk.sendID3(aStr);
}
}
}
catch (Exception e)
{
e.printStackTrace();
Log.d(TAG, "onId3Metadata(): No Id3 tags");
}
}</syntaxhighlight>

[[File:andr-exo-retrievingID3tags.png|link=]]

==== Brightcove Player ====
While the Brightcove player plays the content, EventListener triggers an event when an ID3 packet is received (<code>SeamlessVideoDisplayComponent.ID3_TAG</code>). Upon receiving this event, collect the incoming ID3 tags and only pass the Nielsen payload of the PRIV frame to the App SDK for analysis.

<syntaxhighlight lang="java">brightcoveVideoView.getEventEmitter().on(SeamlessVideoDisplayComponent.ID3_TAG, new EventListener()
{
public void processEvent(Event event)
{
NlsId3Tag nlsID3 = new NlsId3Tag(event.properties.get(SeamlessVideoDisplayComponent.ID3_DATA).toString());
Log.w("ID3", nlsID3.NlsPayload);
// Sent ID3 Tags to App
appProcessID3tag(nlsID3.NlsPayload);
}
});
}</syntaxhighlight>

==== Adobe PrimeTime Player ====
While the Adobe PrimeTime player plays the content, MediaPlayer.PlaybackEventListener triggers a callback when an ID3 packet is received (onTimedMetadata). Upon receiving this event, collect the incoming ID3 tags and only pass the Nielsen payload of the PRIV frame to the App SDK for analysis.
<syntaxhighlight lang="java">public void onTimedMetadata(TimedMetadata id3Metadata)
{
NlsId3Tag nlsID3 = new NlsId3Tag(id3Metadata.getMetadata().toString());
Log.w(LOG_TAG, "ID3 Timed Data –> " + nlsID3.NlsPayload);
Log.w(LOG_TAG, "PayLoad Size –> " + nlsID3.NlsPayload.length());
appProcessID3tag(nlsID3.NlsPayload);
}</syntaxhighlight>

==== VisualOn Player ====
While the VisualOn player plays the content, <code>VOCommonPlayerListener</code> triggers an event when an ID3 packet is received (<code>VO_OSMP_SRC_CUSTOMERTAGID_TIMEDTAG</code>). Upon receiving this event, collect the incoming ID3 tags and only pass the Nielsen payload of the PRIV frame to the App SDK for analysis.

<syntaxhighlight lang="java">case VO_OSMP_SRC_CB_CUSTOMER_TAG:
{
VO_OSMP_SRC_CUSTOMERTAGID tag = VO_OSMP_SRC_CUSTOMERTAGID.valueOf(nParam1);
switch (tag)
{
case VO_OSMP_SRC_CUSTOMERTAGID_TIMEDTAG:
// do something with this tag
int time = nParam2;
byte[] b = (byte[]) obj;
String s = new String(b);
NlsId3Tag nlsID3 = new NlsId3Tag(b);
// Sent ID3 Tags to App
appProcessID3tag(nlsID3.NlsPayload);
if (appid3If != null)
appid3If.onId3(nlsID3.NlsPayload);
break;
case VO_OSMP_SRC_CUSTOMERTAGID_MAX:
// ignore this type of tag
break;
default:
break;
}
break;
}</syntaxhighlight>

==== NextStream Player ====
ID3 tags will be received in the NexStream Player through <code>onTimedMetaRenderRender(NexPlayer mp,NexID3TagInformation metadata)</code> callback API. A sample implementation for the callback is shown below:
<syntaxhighlight lang="java">public void onTimedMetaRenderRender(NexPlayer mp, NexID3TagInformation m)
{
text = m.getPrivateFrame();
if (text != null)
{
data = text.getTextData();
if (data != null)
{
// make sure to identify the beginning of the
// Nielsen ID3 tag payload by searching for the
// "www.nielsen.com" string on the ID3 tag and
// passing to the App SDK all information that
// follows. It should be:
// nlsPayload = "www.nielsen.com" + dataFollowing
nlsPayload = getDataAfterWwwNielsenCom(data);
if (nlsPayload!= NULL)
mAppSdk.sendID3(nlsPayload);
}
}
}</syntaxhighlight>

The [[sendID3()]] sends the extracted Nielsen ID3 payload to the App SDK for analysis.

== Android SDK API Methods & Properties ==
{| class="wikitable sortable"
|-
! Scenario !! Method / Property !! DTVR !! DAR !! Digital Audio !! DCR !! International (Germany) !! Description
|-
| Initialize || [[AppSDK()]] || ✔ || ✔ || ✔ || ✔ || ✔ || 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 when there is a preroll ad that needs to be associated with content metadata. The loadmetadata will first be called to populate the content metadata values and then the loadMetadata for ad metadata will be called. This allows sending a content ping with the ad info, even if the user bails out during the preroll ad.
|-
| Measurement || [[sendID3()]] || ✔ || ✘ || ✘ || ✘ || ✘ || Used to send the ID3 metadata.
|-
| Measurement || [[setPlayheadPosition()]] || ✘ || ✘ || ✔ || ✔ || ✔ || 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 || [[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 || [[userOptOutURLString()]] || ✔ || ✔ || ✔ || ✔ || ✔ || 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 || [[getOptOutStatus()]] || ✘ || ✘ || ✘ || ✘ || ✔ || Call this API to retrieve the Opt-Out or Opt-In state.
|-
| Opt-out
| [[appDisableApi()]]
(kill switch)
|| ✔ || ✔ || ✔ || ✔ || ✔ || Used to disable the SDK.
|-
| Opt-out || [[getAppDisable()]] || ✔ || ✔ || ✔ || ✔ || ✔ || Used to query if the SDK is disabled or not.
|-
| Log || [[getLastEvent()]] || ✔ || ✔ || ✔ || ✔ || ✔ || Used to query the SDK for the last status
|-
| Log || [[getLastError()]] || ✔ || ✔ || ✔ || ✔ || ✔ || Used to query the SDK for the last error
|-
| Log || [[isValid()]] || ✔ || ✔ || ✔ || ✔ || ✔ || Used to check if the SDK was successfully instantiated or not.
|-
| Log || [[getMeterVersion()]] || ✘ || ✘ || ✘ || ✘ || ✔ || Returns the current SDK version.
|-
| Log || [[getNielsenId()]] || ✔ || ✔ || ✔ || ✔ || ✔ || Used to get a string defining the Nielsen ID (NUID) number for the device.
|-
| Log || [[getDeviceId()]] || ✔ || ✔ || ✔ || ✔ || ✔ || Returns the current device id.
|-
| Log || [[appInBackground()]] || ✘ || ✘ || ✘ || ✔ || ✔ || Used to capture the event of app going to background.
|-
| Log || [[appInForeground()]] || ✘ || ✘ || ✘ || ✔ || ✔ || Used to capture the event of app coming to foreground
|-
| Log || [[setDebug()]] || ✘ || ✘ || ✘ || ✘ || ✔ || Used to enable/disable debug flags. Newly introduced in SDK version 5.0.0 for International (Germany)
|}

== 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.
*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.

=== Displaying Opt-Out in a WebView ===
<syntaxhighlight lang="java">
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
}
</syntaxhighlight>

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.

[[File:Privacy policy iOS.jpg|link=]]

<blockquote>'''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.</blockquote>

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

=== Sequence Diagram ===
[[File:optoutsequence-andr.jpg|link=]]

== Opt-out Android SDK Version '''5.1.1.18 or above''' ==
<blockquote>'''Note:''' If using Android SDK Versions 1.2.3, 4.0.0.8, 5.1.0, 5.1.1.14, skip ahead to: [[#Opt-out Android SDK Version 1.2.3, 4.0.0.8, 5.1.0, 5.1.1.14|Opt-out Android SDK Version 1.2.3, 4.0.0.8, 5.1.0, 5.1.1.14]]</blockquote>

Starting from SDK version 5.1.1.18, Opt-Out related behavior has been changed in the following ways:
*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'''.
<blockquote>'''Note:''' For Amazon devices, see [[#Opt-Out Implementation for Amazon Devices|Opt-Out Implementation for Amazon Devices]] below.</blockquote>

[[File:andr-ads.jpg|link=]]

<blockquote>'''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.</blockquote>

== Opt-out Android SDK Version '''1.2.3, 4.0.0.8, 5.1.0, 5.1.1.14''' ==
<blockquote>'''Note:''' If using Android SDK Version 5.1.1.18 or above, refer to documentation above ([[#Opt-out Android SDK Version 5.1.1.18 or above|Opt-out Android SDK Version 5.1.1.18 or above]])</blockquote>

When a user clicks the Opt-Out / Opt-In link, the application should invoke [[optOutURL]] to get the link to the Nielsen Privacy page from SDK.
=== Privacy Page ===
[[File:privacy-policy.jpg|link=]]
*There are two click here links – one for Opt-Out and one for Opt-In. Click the required link:
**Capture user’s selection
**Pass the selection back to the SDK via the [[userOptOut()]].

=== Capture and forward user selection ===
<syntaxhighlight lang="java">
private class MonitorWebView extends WebViewClient
{
private static final String NIELSEN_URL_OPT_OUT = “nielsenappsdk://1”;
private static final String NIELSEN_URL_OPT_IN = “nielsenappsdk://0”;

@Override
public boolean shouldOverrideUrlLoading(WebView view, String url)
{
if (NIELSEN_URL_OPT_OUT.equals(url)
|| NIELSEN_URL_OPT_IN.equals(url))
{
// Get AppSdk instance from the host
AppSdk appSdk = HostApp.getAppSdk();
// Send the URL to the AppSdk instance
appSdk.userOptOut(url);
return true;
}
return false;
}
}
</syntaxhighlight>

<blockquote>'''Note:''' When 'WebView' is closed, pass the status returned from 'WebView' to the SDK within the app.</blockquote>
<blockquote>'''Note:''' App SDK manages the user's choice (Opt-Out / Opt-In), the app does not need to manage this status.</blockquote>

== 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 ===

<syntaxhighlight lang="java">
ContentResolver cr = getContentResolver();
int limitAdTracking = Secure.getInt(cr, "limit_ad_tracking", 2);
</syntaxhighlight>

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

<blockquote>'''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'''.</blockquote>

== Nielsen Sample Applications ==

== Nielsen Privacy Requirements ==
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.
[[File:RatingsDataFlow.png]]

'''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 ===
{| class="wikitable"
|-
! Type of Information !! Parameter !! Transmitted to Nielsen? !! Sent to Provider?
|-
| rowspan="8" | 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
|-
| rowspan="10" | 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
|-
| rowspan="9" | 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
|}
<blockquote>'''Note''': Data is hashed, and encrypted using AES 128 before transmission to data provider.</blockquote>

==== Example ping sent to provider ====
* <code><nowiki>https://provider.com/cgi-bin/brandlift.php</nowiki>?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</code>

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

=== Nielsen Measurement Opt-Out ===
In accordance with Nielsen’s SDK licensing agreement, developers are required to provide basic informational data to users about Nielsen’s Privacy Policy with a navigation to additional information on Nielsen measurement.

Nielsen currently uses Opt Out of Ads for Personalization for the latest versions of the SDK (5.1.1.18 and above). However, for older SDK versions, the app must provide a means for the user to opt out, or opt back in to Nielsen Measurement. Users can opt out of Nielsen online measurement research through this feature.
* If the user has this app running on more than one mobile device, the user will need to opt out of this measurement on each device.
<blockquote>'''Note''': Opt Out feature does NOT rely on "Opt Out of Ads for Personalization" setting since Nielsen’s systems provide measurement metrics and do not serve ads to users.</blockquote>

In the Description of the app in Google Play Store, include a short description about Nielsen measurement, as below.

<blockquote>'''Sample Google Play Store Disclosure'''
This app features Nielsen proprietary measurement software which will allow you to contribute to market research, like Nielsen’s TV Ratings.

To learn more about our digital measurement products and your choices in regard to them, please visit http://www.nielsen.com/digitalprivacy for more information.</blockquote>

== Event and Error Handling ==
=== App SDK Event Codes ===
{| class="wikitable"
|-
! Event Code !! Event Name !! Event Description
|-
| 2000 || EVENT_INITIATE || App SDK is initiated. It will happen as soon as the App SDK is initialized
|-
| 2001 || EVENT_STARTUP || App SDK has started up. It will happen only after App SDK has received a valid config file. This is the location in the code to acquire the value of [[userOptOutURLString()]].
|-
| 2002 || EVENT_SHUTDOWN || App SDK is shutting down. It will happen just before App SDK is destroyed
|}

=== App SDK Error Codes ===
Constants with predefined error codes which the AppSdk object can generate.

{| class="wikitable"
|-
! Event Code !! Event Name !! Description !! Behavior
|-
| 1001 || ERROR_FAILED_CREATE_URL_STRING || Failed generating ping string due to error on parsing || Include last error message from URL parser
|-
| 1002 || ERROR_FAILED_RECEIVE_CONFIG || Failed to receive configuration file from Census || On 5th time, it will log event and keep requesting config 10 min apart
|-
| 1003 || ERROR_FAILED_PARSING_CONFIG || Failed parsing the config file JSON string || Include json error number/short message from iOS or Android
|-
| 1004 || ERROR_FAILED_PARSING_PLAY || Failed parsing the play() JSON string || Include JSON error number/short message from iOS or Android
|-
| 1005 || ERROR_FAILED_PARSING_METADATA || Failed parsing the play() JSON string || Include JSON error number/short message from iOS or Android
|-
| 1006 || ERROR_FAILED_GENERATING_PING || Failed creating ping before adding it to the UPLOAD table) || Include ping nol_url index, cadence to identify ping
|-
| 1007 || ERROR_FAILED_PROCESSOR_START || Failed starting data processor thread. Normally, that means a product || Include processor that failed to start
|-
| 1008 || ERROR_FAILED_PROCESS_ID3 || Failed processing data on a data processor. Normally, that means the input to a product || Include processor and data that failed to process (ID3 tag on a MTVR impression, for example)
|-
| 1009 || ERROR_FAILED_HTTP_SEND || Failed sending HTTP or HTTPS requests || Include HTTP error number
|-
| 1010 || ERROR_FAILED_SENDING_PING || Failed sending pings (on ANDROID, the ping on the UPLOAD table) || Include ping up to 80 char from the end
|-
| 1011 || ERROR_FAILED_SENDING_TSV || Failed sending TSV requests || Include TSV request message
|-
| 1012 || ERROR_FAILED_SENDING_STATION_ID || Failed sending Station ID requests || Include Station ID request message
|-
| 1013 || ERROR_FAILED_ACCESSING_DB || Failed read/write from/to database table || Include SQL statement and data and SQLite error number/message
|-
| 1014 || ERROR_CHANGED_DEVICE_ID || Device ID changed ||
|-
| 1015 || ERROR_CHANGED_NUID || NUID changed ||
|-
| 1016 || ERROR_SDK_NOT_INITIALIZED || App SDK initialization failed ||
|-
| 1017 || ERROR_FAILED_SDK_SUSPEND || App SDK failed to suspend activities ||
|-
| 1018 || ERROR_INVALID_PARAMETERS || App SDK invalid parameters ||
|-
| 1019 || ERROR_INVALID_STATE || App SDK called in incorrect state ||
|-
| 1020 || ERROR_FAILED_PROCESS_PLAYHEAD || App SDK failed processing playhead position ||
|-
| 1021 || ERROR_FAILED_PROCESS_METADATA || App SDK failed processing not-null, syntax valid JSON metadada ||
|-
| 1022 || ERROR_FAILED_PROCESS_STOP || App SDK failed processing stop ||
|}

Android SDK API Reference

2017-07-12T20:05:59Z

Admin2: /* App SDK Error Codes */

{{Breadcrumb|}} {{Breadcrumb|Digital}} {{CurrentBreadcrumb}}
[[Category:Digital]]
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.
*Create and initialize an instance object of <code>AppSdk</code> class.
*The player application can use this object to collect HLS timed metadata through a [[sendID3()]] call.
The Nielsen App SDK class is defined as the only public class belonging to the com.nielsen.app.sdk package. It inherits from the closeable interface and exposes the public APIs the client’s app will use. Below is the declaration of the <code>AppSdk</code> class: <code>public class AppSdk implements Closeable</code>

== Setting Up Development Environment ==
'''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.
<blockquote>'''Note''': App SDK 4.0.0 contains AppSDK.jar component only and does not support C/C++ libAppSdk.so components.</blockquote

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.

=== Setting up in Eclipse IDE ===
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.
<syntaxhighlight lang="java"><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"/></syntaxhighlight>
For more details to handle runtime permissions in Android versions, please visit [https://developer.android.com/training/permissions/requesting.html]. 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.

[[File:andr-properties-drm.jpg|link=]]

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

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

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.
Nielsen App SDK uses the following packages/classes from the Google Play service.

'''Library''':
* 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;

=== Setting up in Android Studio IDE ===
Launch '''Android Studio''' and select '''Import project (Eclipse ADT)'''.

[[File:andr-setup-launch.jpg|link=]]

Browse for project destination directory and click '''Next'''.

[[File:andr-import-project.jpg|link=]]

Go to '''File > Project Structure > App > Dependencies'''.

[[File:andr-pro-structure.jpg|link=]]

Click '''+''' to add library dependency.

Select '''play-services''' and click '''OK'''

[[File:andr-choose-library.jpg|link=]]

For more information, refer to https://developer.android.com/google/play-services/setup.html

== Initialization ==
=== Android Application Life Cycle with respect to Nielsen App SDK ===
[[File:andr-init-img1.jpg|link=]]

=== Step 1: App SDK initialization ===
==== For API version 4.0.0 and above ====

[[AppSDK()]] is no longer a singleton object and should be initialized as below.

'''Initialization of App SDK object through a JSON object'''
<syntaxhighlight lang="objective-c">
JSONObject config = null;

try
{
// Prepare AppSdk configuration object (JSONObject)
JSONObject appSdkConfig = new JSONObject()
.put("appid", "TXXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX")
.put("appname", "Sample App Name")
.put("sfcode", "uat-cert")
.put("nol_devDebug", "INFO") // only for debug builds
.put("custom_key1", "custom_value1")
.put("custom_key2", "custom_value2");
// 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);
}
</syntaxhighlight>

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

==== Android Application Life Cycle with respect to Nielsen App SDK ====
[[File:andr-radioandvideo-app.jpg|link=]]

=== Step 2: App SDK libraries inclusion in project ===
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).

=== Step 3: Nielsen App SDK Streaming Sessions ===
After ensuring that the SDK object has been initialized, link the streaming session APIs. The next steps are:
*Call [[play()]] when starting or resuming a streaming session. Use the channelName parameter to pass channel descriptor information. The channel name field is a 32-character free-form text field containing the name of the program or feed being sent (such as ESPN2, Food Network, etc.) which must be inserted on a JSON string.
*Load the CMS metadata by calling the [[loadMetadata()]] on the SDK object.
*Call [[stop()]] when ending or pausing a viewing session.
*During session playback, call the SDK [[setPlayheadPosition()]] and / or [[sendID3()]]
**Call [[setPlayheadPosition()]] every one second until the stream is stopped or paused. Normally this happens on Digital Audio measurements.
**Call [[sendID3()]] if the client relies on the Nielsen ID3 tags for its measurements; this call should happen whenever a new Nielsen ID3 metadata is available for processing. Normally this happens on DTVR and ID3 measurements.
Nielsen App SDK object handles filtering of ID3 tags and CMS tags, queuing/buffering of data, and all communications with Nielsen collection facility.
*The client’s app must clearly identify the mode of operation (live vs. VOD) and stick to the type of playhead coordinates until the playback is completed. The client must reliably provide the appropriated playhead position value depending on the type of content streamed.
*If streaming live video content, the client must pass the current UTC time in seconds as playhead position.
*If streaming VOD (video on demand), the client must stream the offset from the beginning of the file as playhead position.
*For all Digital Audio listening, the client must pass the current UTC time in seconds as playhead position, regardless of station type.

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

=== Sample ID3 tags ===
* <code>www.nielsen.com/X100zdCIGeIlgZnkYj6UvQ==/X100zdCIGeIlgZnkYj6UvQ==/AAAB2Jz2_k74GXSzx4npHuI_JwJd3QSUpW30rDkGTcbHEzIMWleCzM-uvNOP9fzJcQMWQLJqzXMCAxParOb5sGijSV9dNM3QiBniJYGZ5GI-lL1fXTTN0IgZ4iWBmeRiPpS9AAAAAAAAAAAAAAAAAAAAAFJWFM5SVhTONNU=/00000/00000/00</code>
* <code>www.nielsen.com/X100zdCIGeIlgZnkYj6UvQ==/R8WHe7pEBeqBhu8jTeXydg==/AAICoyitYqlxT7n6aZ0oMCGheFi4CXFp46AMUPZz1lMr_M9tr3_cjee1SHqxrOiVerMDLeyn9xzocZSKwi746Re8vNOtpNCAZjYABs_J0R25IHpvOc1HS8QHGgD5TgOJeS6gX100zdCIGeIlgZnkYj6UvVJWFNhSVhTiPE0=/00000/46016/00</code>
<blockquote>'''Note''': ID3 tags are not applicable for International (Germany)</blockquote>

=== Extracting ID3 tags from Android Players ===
==== ID3 Support Matrix ====
{| class="wikitable"
|-
! Player Name !! Minimum supported version !! Description
|-
| Android Native Media Player || Android 6 || Android 6 Media Player allows apps to register a callback to be invoked, when a selected track has the timed metadata available. Currently, only HTTP Live Streaming (HLS) data URI’s embedded with timed ID3 tags, generates TimedMetaData.
|-
| Google ExoPlayer || Android 4.1 ||
|-
| Brightcove Player || Android 4.1 || Support for Android versions 2.3.3 and 4.0 is now deprecated. Learn more about why Brightcove is removing support for these versions as of January 1, 2016 in this [https://support.brightcove.com/en/perform/docs/announcement-brightcove-sdk-android-version-support|announcement]
|-
| Adobe PrimeTime Player || Android 4.2 ||
|-
| VisualOn Player || Android 2.3 || Android 5 is the latest supported version
|-
| NexStream Player || Android 1.6 || Supported till Android 6
|}

==== Android Native Media Player ====
As the Android Media Player versions (prior to Android 6 / Android API 23) do not support ID3, Nielsen has created a library that becomes an extension to the media player, thus MPX. This library extracts the ID3 tags and sends them to the app. For more information on how to use the MPX component, refer to the Nielsen-supplied sample application.

Starting from '''Android 6 (Android API 23)''', Android Native Media Player allows apps to register a callback to be invoked, when a selected track has the timed metadata available. Currently, only HTTP Live Streaming (HLS) data URI’s embedded with timed ID3 tags generate TimedMetadata. Once the HLS video starts, call onTimedMetaDataAvailable() as and when the player observes a TimedMetadata (ID3 tag).

<syntaxhighlight lang="java">@Override
public void onTimedMetaDataAvailable(MediaPlayer mp, TimedMetaData data)
{
byte[] iD3PayloadArray = data.getMetaData();
String iD3Payload = new String(iD3PayloadArray, StandardCharsets.UTF_8);
if (null != iD3Payload && iD3Payload.contains("www.nielsen.com"))
{
int index = iD3Payload.indexOf("www.nielsen.com");
String id3String = iD3Payload.substring(index, (index + 249));
Log.d(TAG, "TimedMetaData ID3 Tag:" + id3String);
appProcessID3tag(id3String);
}
}</syntaxhighlight>

==== ExoPlayer ====
he SDK is designed around an event-driven architecture where components emit events to allow other components to listen and respond to state changes.

'''Player SDK Classes used:'''
<syntaxhighlight lang="java">com.google.android.exoplayer.demo.player.DemoPlayer</syntaxhighlight>

Since Nielsen App SDK is interested in extracting the Timed Metadata (ID3 Tags) in HLS and VOD on the EXO Player, trace the ID3_TAG emitted during video content played using EXOPlayer component as below.

<syntaxhighlight lang="java">DemoPlayer implements ExoPlayer.Listener
—————————————————–
/**
* A listener for receiving ID3 metadata parsed from the media stream.
*/
public interface Id3MetadataListener
{
void onId3Metadata(Map<String, Object> metadata);
}
——————————————————-
MetadataTrackRenderer.MetadataRenderer<Map<String,
Object>> getId3MetadataRenderer()
{
return new MetadataTrackRenderer.MetadataRenderer<Map<String, Object>>()
{
@Override
public void onMetadata(Map<String, Object> metadata)
{
if (id3MetadataListener != null)
{
id3MetadataListener.onId3Metadata(metadata);
}
}
};
}</syntaxhighlight>

Also in ''Player.java'' class:
<syntaxhighlight lang="java">Player implements DemoPlayer.Id3MetadataListener
—————————————————–
@SuppressWarnings("rawtypes")
@Override
public void onId3Metadata(Map<String, Object> metadata)
{
try
{
for (Object o : metadata.entrySet())
{
Map.Entry pairs = (Map.Entry) o;
if (metadata.containsKey(TxxxMetadata.TYPE))
{
TxxxMetadata txxxMetadata = (TxxxMetadata) metadata
.get(TxxxMetadata.TYPE);
}
else
{
String aStr = new String((byte[]) pairs.getValue());
MainActivity.mAppSdk.sendID3(aStr);
}
}
}
catch (Exception e)
{
e.printStackTrace();
Log.d(TAG, "onId3Metadata(): No Id3 tags");
}
}</syntaxhighlight>

[[File:andr-exo-retrievingID3tags.png|link=]]

==== Brightcove Player ====
While the Brightcove player plays the content, EventListener triggers an event when an ID3 packet is received (<code>SeamlessVideoDisplayComponent.ID3_TAG</code>). Upon receiving this event, collect the incoming ID3 tags and only pass the Nielsen payload of the PRIV frame to the App SDK for analysis.

<syntaxhighlight lang="java">brightcoveVideoView.getEventEmitter().on(SeamlessVideoDisplayComponent.ID3_TAG, new EventListener()
{
public void processEvent(Event event)
{
NlsId3Tag nlsID3 = new NlsId3Tag(event.properties.get(SeamlessVideoDisplayComponent.ID3_DATA).toString());
Log.w("ID3", nlsID3.NlsPayload);
// Sent ID3 Tags to App
appProcessID3tag(nlsID3.NlsPayload);
}
});
}</syntaxhighlight>

==== Adobe PrimeTime Player ====
While the Adobe PrimeTime player plays the content, MediaPlayer.PlaybackEventListener triggers a callback when an ID3 packet is received (onTimedMetadata). Upon receiving this event, collect the incoming ID3 tags and only pass the Nielsen payload of the PRIV frame to the App SDK for analysis.
<syntaxhighlight lang="java">public void onTimedMetadata(TimedMetadata id3Metadata)
{
NlsId3Tag nlsID3 = new NlsId3Tag(id3Metadata.getMetadata().toString());
Log.w(LOG_TAG, "ID3 Timed Data –> " + nlsID3.NlsPayload);
Log.w(LOG_TAG, "PayLoad Size –> " + nlsID3.NlsPayload.length());
appProcessID3tag(nlsID3.NlsPayload);
}</syntaxhighlight>

==== VisualOn Player ====
While the VisualOn player plays the content, <code>VOCommonPlayerListener</code> triggers an event when an ID3 packet is received (<code>VO_OSMP_SRC_CUSTOMERTAGID_TIMEDTAG</code>). Upon receiving this event, collect the incoming ID3 tags and only pass the Nielsen payload of the PRIV frame to the App SDK for analysis.

<syntaxhighlight lang="java">case VO_OSMP_SRC_CB_CUSTOMER_TAG:
{
VO_OSMP_SRC_CUSTOMERTAGID tag = VO_OSMP_SRC_CUSTOMERTAGID.valueOf(nParam1);
switch (tag)
{
case VO_OSMP_SRC_CUSTOMERTAGID_TIMEDTAG:
// do something with this tag
int time = nParam2;
byte[] b = (byte[]) obj;
String s = new String(b);
NlsId3Tag nlsID3 = new NlsId3Tag(b);
// Sent ID3 Tags to App
appProcessID3tag(nlsID3.NlsPayload);
if (appid3If != null)
appid3If.onId3(nlsID3.NlsPayload);
break;
case VO_OSMP_SRC_CUSTOMERTAGID_MAX:
// ignore this type of tag
break;
default:
break;
}
break;
}</syntaxhighlight>

==== NextStream Player ====
ID3 tags will be received in the NexStream Player through <code>onTimedMetaRenderRender(NexPlayer mp,NexID3TagInformation metadata)</code> callback API. A sample implementation for the callback is shown below:
<syntaxhighlight lang="java">public void onTimedMetaRenderRender(NexPlayer mp, NexID3TagInformation m)
{
text = m.getPrivateFrame();
if (text != null)
{
data = text.getTextData();
if (data != null)
{
// make sure to identify the beginning of the
// Nielsen ID3 tag payload by searching for the
// "www.nielsen.com" string on the ID3 tag and
// passing to the App SDK all information that
// follows. It should be:
// nlsPayload = "www.nielsen.com" + dataFollowing
nlsPayload = getDataAfterWwwNielsenCom(data);
if (nlsPayload!= NULL)
mAppSdk.sendID3(nlsPayload);
}
}
}</syntaxhighlight>

The [[sendID3()]] sends the extracted Nielsen ID3 payload to the App SDK for analysis.

== Android SDK API Methods & Properties ==
{| class="wikitable sortable"
|-
! Scenario !! Method / Property !! DTVR !! DAR !! Digital Audio !! DCR !! International (Germany) !! Description
|-
| Initialize || [[AppSDK()]] || ✔ || ✔ || ✔ || ✔ || ✔ || 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 when there is a preroll ad that needs to be associated with content metadata. The loadmetadata will first be called to populate the content metadata values and then the loadMetadata for ad metadata will be called. This allows sending a content ping with the ad info, even if the user bails out during the preroll ad.
|-
| Measurement || [[sendID3()]] || ✔ || ✘ || ✘ || ✘ || ✘ || Used to send the ID3 metadata.
|-
| Measurement || [[setPlayheadPosition()]] || ✘ || ✘ || ✔ || ✔ || ✔ || 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 || [[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 || [[userOptOutURLString()]] || ✔ || ✔ || ✔ || ✔ || ✔ || 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 || [[getOptOutStatus()]] || ✘ || ✘ || ✘ || ✘ || ✔ || Call this API to retrieve the Opt-Out or Opt-In state.
|-
| Opt-out
| [[appDisableApi()]]
(kill switch)
|| ✔ || ✔ || ✔ || ✔ || ✔ || Used to disable the SDK.
|-
| Opt-out || [[getAppDisable()]] || ✔ || ✔ || ✔ || ✔ || ✔ || Used to query if the SDK is disabled or not.
|-
| Log || [[getLastEvent()]] || ✔ || ✔ || ✔ || ✔ || ✔ || Used to query the SDK for the last status
|-
| Log || [[getLastError()]] || ✔ || ✔ || ✔ || ✔ || ✔ || Used to query the SDK for the last error
|-
| Log || [[isValid()]] || ✔ || ✔ || ✔ || ✔ || ✔ || Used to check if the SDK was successfully instantiated or not.
|-
| Log || [[getMeterVersion()]] || ✘ || ✘ || ✘ || ✘ || ✔ || Returns the current SDK version.
|-
| Log || [[getNielsenId()]] || ✔ || ✔ || ✔ || ✔ || ✔ || Used to get a string defining the Nielsen ID (NUID) number for the device.
|-
| Log || [[getDeviceId()]] || ✔ || ✔ || ✔ || ✔ || ✔ || Returns the current device id.
|-
| Log || [[appInBackground()]] || ✘ || ✘ || ✘ || ✔ || ✔ || Used to capture the event of app going to background.
|-
| Log || [[appInForeground()]] || ✘ || ✘ || ✘ || ✔ || ✔ || Used to capture the event of app coming to foreground
|-
| Log || [[setDebug()]] || ✘ || ✘ || ✘ || ✘ || ✔ || Used to enable/disable debug flags. Newly introduced in SDK version 5.0.0 for International (Germany)
|}

== 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.
*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.

=== Displaying Opt-Out in a WebView ===
<syntaxhighlight lang="java">
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
}
</syntaxhighlight>

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.

[[File:Privacy policy iOS.jpg|link=]]

<blockquote>'''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.</blockquote>

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

=== Sequence Diagram ===
[[File:optoutsequence-andr.jpg|link=]]

== Opt-out Android SDK Version '''5.1.1.18 or above''' ==
<blockquote>'''Note:''' If using Android SDK Versions 1.2.3, 4.0.0.8, 5.1.0, 5.1.1.14, skip ahead to: [[#Opt-out Android SDK Version 1.2.3, 4.0.0.8, 5.1.0, 5.1.1.14|Opt-out Android SDK Version 1.2.3, 4.0.0.8, 5.1.0, 5.1.1.14]]</blockquote>

Starting from SDK version 5.1.1.18, Opt-Out related behavior has been changed in the following ways:
*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'''.
<blockquote>'''Note:''' For Amazon devices, see [[#Opt-Out Implementation for Amazon Devices|Opt-Out Implementation for Amazon Devices]] below.</blockquote>

[[File:andr-ads.jpg|link=]]

<blockquote>'''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.</blockquote>

== Opt-out Android SDK Version '''1.2.3, 4.0.0.8, 5.1.0, 5.1.1.14''' ==
<blockquote>'''Note:''' If using Android SDK Version 5.1.1.18 or above, refer to documentation above ([[#Opt-out Android SDK Version 5.1.1.18 or above|Opt-out Android SDK Version 5.1.1.18 or above]])</blockquote>

When a user clicks the Opt-Out / Opt-In link, the application should invoke [[optOutURL]] to get the link to the Nielsen Privacy page from SDK.
=== Privacy Page ===
[[File:privacy-policy.jpg|link=]]
*There are two click here links – one for Opt-Out and one for Opt-In. Click the required link:
**Capture user’s selection
**Pass the selection back to the SDK via the [[userOptOut()]].

=== Capture and forward user selection ===
<syntaxhighlight lang="java">
private class MonitorWebView extends WebViewClient
{
private static final String NIELSEN_URL_OPT_OUT = “nielsenappsdk://1”;
private static final String NIELSEN_URL_OPT_IN = “nielsenappsdk://0”;

@Override
public boolean shouldOverrideUrlLoading(WebView view, String url)
{
if (NIELSEN_URL_OPT_OUT.equals(url)
|| NIELSEN_URL_OPT_IN.equals(url))
{
// Get AppSdk instance from the host
AppSdk appSdk = HostApp.getAppSdk();
// Send the URL to the AppSdk instance
appSdk.userOptOut(url);
return true;
}
return false;
}
}
</syntaxhighlight>

<blockquote>'''Note:''' When 'WebView' is closed, pass the status returned from 'WebView' to the SDK within the app.</blockquote>
<blockquote>'''Note:''' App SDK manages the user's choice (Opt-Out / Opt-In), the app does not need to manage this status.</blockquote>

== 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 ===

<syntaxhighlight lang="java">
ContentResolver cr = getContentResolver();
int limitAdTracking = Secure.getInt(cr, "limit_ad_tracking", 2);
</syntaxhighlight>

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

<blockquote>'''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'''.</blockquote>

== Nielsen Sample Applications ==

== Nielsen Privacy Requirements ==
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.
[[File:RatingsDataFlow.png]]

'''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 ===
{| class="wikitable"
|-
! Type of Information !! Parameter !! Transmitted to Nielsen? !! Sent to Provider?
|-
| rowspan="8" | 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
|-
| rowspan="10" | 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
|-
| rowspan="9" | 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
|}
<blockquote>'''Note''': Data is hashed, and encrypted using AES 128 before transmission to data provider.</blockquote>

==== Example ping sent to provider ====
* <code><nowiki>https://provider.com/cgi-bin/brandlift.php</nowiki>?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</code>

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

=== Nielsen Measurement Opt-Out ===
In accordance with Nielsen’s SDK licensing agreement, developers are required to provide basic informational data to users about Nielsen’s Privacy Policy with a navigation to additional information on Nielsen measurement.

Nielsen currently uses Opt Out of Ads for Personalization for the latest versions of the SDK (5.1.1.18 and above). However, for older SDK versions, the app must provide a means for the user to opt out, or opt back in to Nielsen Measurement. Users can opt out of Nielsen online measurement research through this feature.
* If the user has this app running on more than one mobile device, the user will need to opt out of this measurement on each device.
<blockquote>'''Note''': Opt Out feature does NOT rely on "Opt Out of Ads for Personalization" setting since Nielsen’s systems provide measurement metrics and do not serve ads to users.</blockquote>

In the Description of the app in Google Play Store, include a short description about Nielsen measurement, as below.

<blockquote>'''Sample Google Play Store Disclosure'''
This app features Nielsen proprietary measurement software which will allow you to contribute to market research, like Nielsen’s TV Ratings.

To learn more about our digital measurement products and your choices in regard to them, please visit http://www.nielsen.com/digitalprivacy for more information.</blockquote>

== Event and Error Handling ==
=== App SDK Event Codes ===
'''App SDK Event Codes '''
{| class="wikitable"
|-
! Event Code !! Event Name !! Event Description
|-
| 2000 || EVENT_INITIATE || App SDK is initiated. It will happen as soon as the App SDK is initialized
|-
| 2001 || EVENT_STARTUP || App SDK has started up. It will happen only after App SDK has received a valid config file. This is the location in the code to acquire the value of [[userOptOutURLString()]].
|-
| 2002 || EVENT_SHUTDOWN || App SDK is shutting down. It will happen just before App SDK is destroyed
|}

=== App SDK Error Codes ===
Constants with predefined error codes which the AppSdk object can generate.

{| class="wikitable"
|-
! Event Code !! Event Name !! Description !! Behavior
|-
| 1001 || ERROR_FAILED_CREATE_URL_STRING || Failed generating ping string due to error on parsing || Include last error message from URL parser
|-
| 1002 || ERROR_FAILED_RECEIVE_CONFIG || Failed to receive configuration file from Census || On 5th time, it will log event and keep requesting config 10 min apart
|-
| 1003 || ERROR_FAILED_PARSING_CONFIG || Failed parsing the config file JSON string || Include json error number/short message from iOS or Android
|-
| 1004 || ERROR_FAILED_PARSING_PLAY || Failed parsing the play() JSON string || Include JSON error number/short message from iOS or Android
|-
| 1005 || ERROR_FAILED_PARSING_METADATA || Failed parsing the play() JSON string || Include JSON error number/short message from iOS or Android
|-
| 1006 || ERROR_FAILED_GENERATING_PING || Failed creating ping before adding it to the UPLOAD table) || Include ping nol_url index, cadence to identify ping
|-
| 1007 || ERROR_FAILED_PROCESSOR_START || Failed starting data processor thread. Normally, that means a product || Include processor that failed to start
|-
| 1008 || ERROR_FAILED_PROCESS_ID3 || Failed processing data on a data processor. Normally, that means the input to a product || Include processor and data that failed to process (ID3 tag on a MTVR impression, for example)
|-
| 1009 || ERROR_FAILED_HTTP_SEND || Failed sending HTTP or HTTPS requests || Include HTTP error number
|-
| 1010 || ERROR_FAILED_SENDING_PING || Failed sending pings (on ANDROID, the ping on the UPLOAD table) || Include ping up to 80 char from the end
|-
| 1011 || ERROR_FAILED_SENDING_TSV || Failed sending TSV requests || Include TSV request message
|-
| 1012 || ERROR_FAILED_SENDING_STATION_ID || Failed sending Station ID requests || Include Station ID request message
|-
| 1013 || ERROR_FAILED_ACCESSING_DB || Failed read/write from/to database table || Include SQL statement and data and SQLite error number/message
|-
| 1014 || ERROR_CHANGED_DEVICE_ID || Device ID changed ||
|-
| 1015 || ERROR_CHANGED_NUID || NUID changed ||
|-
| 1016 || ERROR_SDK_NOT_INITIALIZED || App SDK initialization failed ||
|-
| 1017 || ERROR_FAILED_SDK_SUSPEND || App SDK failed to suspend activities ||
|-
| 1018 || ERROR_INVALID_PARAMETERS || App SDK invalid parameters ||
|-
| 1019 || ERROR_INVALID_STATE || App SDK called in incorrect state ||
|-
| 1020 || ERROR_FAILED_PROCESS_PLAYHEAD || App SDK failed processing playhead position ||
|-
| 1021 || ERROR_FAILED_PROCESS_METADATA || App SDK failed processing not-null, syntax valid JSON metadada ||
|-
| 1022 || ERROR_FAILED_PROCESS_STOP || App SDK failed processing stop ||
|}

Android SDK API Reference

2017-07-12T20:05:16Z

Admin2: /* Event and Error Handling */

{{Breadcrumb|}} {{Breadcrumb|Digital}} {{CurrentBreadcrumb}}
[[Category:Digital]]
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.
*Create and initialize an instance object of <code>AppSdk</code> class.
*The player application can use this object to collect HLS timed metadata through a [[sendID3()]] call.
The Nielsen App SDK class is defined as the only public class belonging to the com.nielsen.app.sdk package. It inherits from the closeable interface and exposes the public APIs the client’s app will use. Below is the declaration of the <code>AppSdk</code> class: <code>public class AppSdk implements Closeable</code>

== Setting Up Development Environment ==
'''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.
<blockquote>'''Note''': App SDK 4.0.0 contains AppSDK.jar component only and does not support C/C++ libAppSdk.so components.</blockquote

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.

=== Setting up in Eclipse IDE ===
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.
<syntaxhighlight lang="java"><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"/></syntaxhighlight>
For more details to handle runtime permissions in Android versions, please visit [https://developer.android.com/training/permissions/requesting.html]. 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.

[[File:andr-properties-drm.jpg|link=]]

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

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

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.
Nielsen App SDK uses the following packages/classes from the Google Play service.

'''Library''':
* 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;

=== Setting up in Android Studio IDE ===
Launch '''Android Studio''' and select '''Import project (Eclipse ADT)'''.

[[File:andr-setup-launch.jpg|link=]]

Browse for project destination directory and click '''Next'''.

[[File:andr-import-project.jpg|link=]]

Go to '''File > Project Structure > App > Dependencies'''.

[[File:andr-pro-structure.jpg|link=]]

Click '''+''' to add library dependency.

Select '''play-services''' and click '''OK'''

[[File:andr-choose-library.jpg|link=]]

For more information, refer to https://developer.android.com/google/play-services/setup.html

== Initialization ==
=== Android Application Life Cycle with respect to Nielsen App SDK ===
[[File:andr-init-img1.jpg|link=]]

=== Step 1: App SDK initialization ===
==== For API version 4.0.0 and above ====

[[AppSDK()]] is no longer a singleton object and should be initialized as below.

'''Initialization of App SDK object through a JSON object'''
<syntaxhighlight lang="objective-c">
JSONObject config = null;

try
{
// Prepare AppSdk configuration object (JSONObject)
JSONObject appSdkConfig = new JSONObject()
.put("appid", "TXXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX")
.put("appname", "Sample App Name")
.put("sfcode", "uat-cert")
.put("nol_devDebug", "INFO") // only for debug builds
.put("custom_key1", "custom_value1")
.put("custom_key2", "custom_value2");
// 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);
}
</syntaxhighlight>

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

==== Android Application Life Cycle with respect to Nielsen App SDK ====
[[File:andr-radioandvideo-app.jpg|link=]]

=== Step 2: App SDK libraries inclusion in project ===
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).

=== Step 3: Nielsen App SDK Streaming Sessions ===
After ensuring that the SDK object has been initialized, link the streaming session APIs. The next steps are:
*Call [[play()]] when starting or resuming a streaming session. Use the channelName parameter to pass channel descriptor information. The channel name field is a 32-character free-form text field containing the name of the program or feed being sent (such as ESPN2, Food Network, etc.) which must be inserted on a JSON string.
*Load the CMS metadata by calling the [[loadMetadata()]] on the SDK object.
*Call [[stop()]] when ending or pausing a viewing session.
*During session playback, call the SDK [[setPlayheadPosition()]] and / or [[sendID3()]]
**Call [[setPlayheadPosition()]] every one second until the stream is stopped or paused. Normally this happens on Digital Audio measurements.
**Call [[sendID3()]] if the client relies on the Nielsen ID3 tags for its measurements; this call should happen whenever a new Nielsen ID3 metadata is available for processing. Normally this happens on DTVR and ID3 measurements.
Nielsen App SDK object handles filtering of ID3 tags and CMS tags, queuing/buffering of data, and all communications with Nielsen collection facility.
*The client’s app must clearly identify the mode of operation (live vs. VOD) and stick to the type of playhead coordinates until the playback is completed. The client must reliably provide the appropriated playhead position value depending on the type of content streamed.
*If streaming live video content, the client must pass the current UTC time in seconds as playhead position.
*If streaming VOD (video on demand), the client must stream the offset from the beginning of the file as playhead position.
*For all Digital Audio listening, the client must pass the current UTC time in seconds as playhead position, regardless of station type.

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

=== Sample ID3 tags ===
* <code>www.nielsen.com/X100zdCIGeIlgZnkYj6UvQ==/X100zdCIGeIlgZnkYj6UvQ==/AAAB2Jz2_k74GXSzx4npHuI_JwJd3QSUpW30rDkGTcbHEzIMWleCzM-uvNOP9fzJcQMWQLJqzXMCAxParOb5sGijSV9dNM3QiBniJYGZ5GI-lL1fXTTN0IgZ4iWBmeRiPpS9AAAAAAAAAAAAAAAAAAAAAFJWFM5SVhTONNU=/00000/00000/00</code>
* <code>www.nielsen.com/X100zdCIGeIlgZnkYj6UvQ==/R8WHe7pEBeqBhu8jTeXydg==/AAICoyitYqlxT7n6aZ0oMCGheFi4CXFp46AMUPZz1lMr_M9tr3_cjee1SHqxrOiVerMDLeyn9xzocZSKwi746Re8vNOtpNCAZjYABs_J0R25IHpvOc1HS8QHGgD5TgOJeS6gX100zdCIGeIlgZnkYj6UvVJWFNhSVhTiPE0=/00000/46016/00</code>
<blockquote>'''Note''': ID3 tags are not applicable for International (Germany)</blockquote>

=== Extracting ID3 tags from Android Players ===
==== ID3 Support Matrix ====
{| class="wikitable"
|-
! Player Name !! Minimum supported version !! Description
|-
| Android Native Media Player || Android 6 || Android 6 Media Player allows apps to register a callback to be invoked, when a selected track has the timed metadata available. Currently, only HTTP Live Streaming (HLS) data URI’s embedded with timed ID3 tags, generates TimedMetaData.
|-
| Google ExoPlayer || Android 4.1 ||
|-
| Brightcove Player || Android 4.1 || Support for Android versions 2.3.3 and 4.0 is now deprecated. Learn more about why Brightcove is removing support for these versions as of January 1, 2016 in this [https://support.brightcove.com/en/perform/docs/announcement-brightcove-sdk-android-version-support|announcement]
|-
| Adobe PrimeTime Player || Android 4.2 ||
|-
| VisualOn Player || Android 2.3 || Android 5 is the latest supported version
|-
| NexStream Player || Android 1.6 || Supported till Android 6
|}

==== Android Native Media Player ====
As the Android Media Player versions (prior to Android 6 / Android API 23) do not support ID3, Nielsen has created a library that becomes an extension to the media player, thus MPX. This library extracts the ID3 tags and sends them to the app. For more information on how to use the MPX component, refer to the Nielsen-supplied sample application.

Starting from '''Android 6 (Android API 23)''', Android Native Media Player allows apps to register a callback to be invoked, when a selected track has the timed metadata available. Currently, only HTTP Live Streaming (HLS) data URI’s embedded with timed ID3 tags generate TimedMetadata. Once the HLS video starts, call onTimedMetaDataAvailable() as and when the player observes a TimedMetadata (ID3 tag).

<syntaxhighlight lang="java">@Override
public void onTimedMetaDataAvailable(MediaPlayer mp, TimedMetaData data)
{
byte[] iD3PayloadArray = data.getMetaData();
String iD3Payload = new String(iD3PayloadArray, StandardCharsets.UTF_8);
if (null != iD3Payload && iD3Payload.contains("www.nielsen.com"))
{
int index = iD3Payload.indexOf("www.nielsen.com");
String id3String = iD3Payload.substring(index, (index + 249));
Log.d(TAG, "TimedMetaData ID3 Tag:" + id3String);
appProcessID3tag(id3String);
}
}</syntaxhighlight>

==== ExoPlayer ====
he SDK is designed around an event-driven architecture where components emit events to allow other components to listen and respond to state changes.

'''Player SDK Classes used:'''
<syntaxhighlight lang="java">com.google.android.exoplayer.demo.player.DemoPlayer</syntaxhighlight>

Since Nielsen App SDK is interested in extracting the Timed Metadata (ID3 Tags) in HLS and VOD on the EXO Player, trace the ID3_TAG emitted during video content played using EXOPlayer component as below.

<syntaxhighlight lang="java">DemoPlayer implements ExoPlayer.Listener
—————————————————–
/**
* A listener for receiving ID3 metadata parsed from the media stream.
*/
public interface Id3MetadataListener
{
void onId3Metadata(Map<String, Object> metadata);
}
——————————————————-
MetadataTrackRenderer.MetadataRenderer<Map<String,
Object>> getId3MetadataRenderer()
{
return new MetadataTrackRenderer.MetadataRenderer<Map<String, Object>>()
{
@Override
public void onMetadata(Map<String, Object> metadata)
{
if (id3MetadataListener != null)
{
id3MetadataListener.onId3Metadata(metadata);
}
}
};
}</syntaxhighlight>

Also in ''Player.java'' class:
<syntaxhighlight lang="java">Player implements DemoPlayer.Id3MetadataListener
—————————————————–
@SuppressWarnings("rawtypes")
@Override
public void onId3Metadata(Map<String, Object> metadata)
{
try
{
for (Object o : metadata.entrySet())
{
Map.Entry pairs = (Map.Entry) o;
if (metadata.containsKey(TxxxMetadata.TYPE))
{
TxxxMetadata txxxMetadata = (TxxxMetadata) metadata
.get(TxxxMetadata.TYPE);
}
else
{
String aStr = new String((byte[]) pairs.getValue());
MainActivity.mAppSdk.sendID3(aStr);
}
}
}
catch (Exception e)
{
e.printStackTrace();
Log.d(TAG, "onId3Metadata(): No Id3 tags");
}
}</syntaxhighlight>

[[File:andr-exo-retrievingID3tags.png|link=]]

==== Brightcove Player ====
While the Brightcove player plays the content, EventListener triggers an event when an ID3 packet is received (<code>SeamlessVideoDisplayComponent.ID3_TAG</code>). Upon receiving this event, collect the incoming ID3 tags and only pass the Nielsen payload of the PRIV frame to the App SDK for analysis.

<syntaxhighlight lang="java">brightcoveVideoView.getEventEmitter().on(SeamlessVideoDisplayComponent.ID3_TAG, new EventListener()
{
public void processEvent(Event event)
{
NlsId3Tag nlsID3 = new NlsId3Tag(event.properties.get(SeamlessVideoDisplayComponent.ID3_DATA).toString());
Log.w("ID3", nlsID3.NlsPayload);
// Sent ID3 Tags to App
appProcessID3tag(nlsID3.NlsPayload);
}
});
}</syntaxhighlight>

==== Adobe PrimeTime Player ====
While the Adobe PrimeTime player plays the content, MediaPlayer.PlaybackEventListener triggers a callback when an ID3 packet is received (onTimedMetadata). Upon receiving this event, collect the incoming ID3 tags and only pass the Nielsen payload of the PRIV frame to the App SDK for analysis.
<syntaxhighlight lang="java">public void onTimedMetadata(TimedMetadata id3Metadata)
{
NlsId3Tag nlsID3 = new NlsId3Tag(id3Metadata.getMetadata().toString());
Log.w(LOG_TAG, "ID3 Timed Data –> " + nlsID3.NlsPayload);
Log.w(LOG_TAG, "PayLoad Size –> " + nlsID3.NlsPayload.length());
appProcessID3tag(nlsID3.NlsPayload);
}</syntaxhighlight>

==== VisualOn Player ====
While the VisualOn player plays the content, <code>VOCommonPlayerListener</code> triggers an event when an ID3 packet is received (<code>VO_OSMP_SRC_CUSTOMERTAGID_TIMEDTAG</code>). Upon receiving this event, collect the incoming ID3 tags and only pass the Nielsen payload of the PRIV frame to the App SDK for analysis.

<syntaxhighlight lang="java">case VO_OSMP_SRC_CB_CUSTOMER_TAG:
{
VO_OSMP_SRC_CUSTOMERTAGID tag = VO_OSMP_SRC_CUSTOMERTAGID.valueOf(nParam1);
switch (tag)
{
case VO_OSMP_SRC_CUSTOMERTAGID_TIMEDTAG:
// do something with this tag
int time = nParam2;
byte[] b = (byte[]) obj;
String s = new String(b);
NlsId3Tag nlsID3 = new NlsId3Tag(b);
// Sent ID3 Tags to App
appProcessID3tag(nlsID3.NlsPayload);
if (appid3If != null)
appid3If.onId3(nlsID3.NlsPayload);
break;
case VO_OSMP_SRC_CUSTOMERTAGID_MAX:
// ignore this type of tag
break;
default:
break;
}
break;
}</syntaxhighlight>

==== NextStream Player ====
ID3 tags will be received in the NexStream Player through <code>onTimedMetaRenderRender(NexPlayer mp,NexID3TagInformation metadata)</code> callback API. A sample implementation for the callback is shown below:
<syntaxhighlight lang="java">public void onTimedMetaRenderRender(NexPlayer mp, NexID3TagInformation m)
{
text = m.getPrivateFrame();
if (text != null)
{
data = text.getTextData();
if (data != null)
{
// make sure to identify the beginning of the
// Nielsen ID3 tag payload by searching for the
// "www.nielsen.com" string on the ID3 tag and
// passing to the App SDK all information that
// follows. It should be:
// nlsPayload = "www.nielsen.com" + dataFollowing
nlsPayload = getDataAfterWwwNielsenCom(data);
if (nlsPayload!= NULL)
mAppSdk.sendID3(nlsPayload);
}
}
}</syntaxhighlight>

The [[sendID3()]] sends the extracted Nielsen ID3 payload to the App SDK for analysis.

== Android SDK API Methods & Properties ==
{| class="wikitable sortable"
|-
! Scenario !! Method / Property !! DTVR !! DAR !! Digital Audio !! DCR !! International (Germany) !! Description
|-
| Initialize || [[AppSDK()]] || ✔ || ✔ || ✔ || ✔ || ✔ || 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 when there is a preroll ad that needs to be associated with content metadata. The loadmetadata will first be called to populate the content metadata values and then the loadMetadata for ad metadata will be called. This allows sending a content ping with the ad info, even if the user bails out during the preroll ad.
|-
| Measurement || [[sendID3()]] || ✔ || ✘ || ✘ || ✘ || ✘ || Used to send the ID3 metadata.
|-
| Measurement || [[setPlayheadPosition()]] || ✘ || ✘ || ✔ || ✔ || ✔ || 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 || [[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 || [[userOptOutURLString()]] || ✔ || ✔ || ✔ || ✔ || ✔ || 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 || [[getOptOutStatus()]] || ✘ || ✘ || ✘ || ✘ || ✔ || Call this API to retrieve the Opt-Out or Opt-In state.
|-
| Opt-out
| [[appDisableApi()]]
(kill switch)
|| ✔ || ✔ || ✔ || ✔ || ✔ || Used to disable the SDK.
|-
| Opt-out || [[getAppDisable()]] || ✔ || ✔ || ✔ || ✔ || ✔ || Used to query if the SDK is disabled or not.
|-
| Log || [[getLastEvent()]] || ✔ || ✔ || ✔ || ✔ || ✔ || Used to query the SDK for the last status
|-
| Log || [[getLastError()]] || ✔ || ✔ || ✔ || ✔ || ✔ || Used to query the SDK for the last error
|-
| Log || [[isValid()]] || ✔ || ✔ || ✔ || ✔ || ✔ || Used to check if the SDK was successfully instantiated or not.
|-
| Log || [[getMeterVersion()]] || ✘ || ✘ || ✘ || ✘ || ✔ || Returns the current SDK version.
|-
| Log || [[getNielsenId()]] || ✔ || ✔ || ✔ || ✔ || ✔ || Used to get a string defining the Nielsen ID (NUID) number for the device.
|-
| Log || [[getDeviceId()]] || ✔ || ✔ || ✔ || ✔ || ✔ || Returns the current device id.
|-
| Log || [[appInBackground()]] || ✘ || ✘ || ✘ || ✔ || ✔ || Used to capture the event of app going to background.
|-
| Log || [[appInForeground()]] || ✘ || ✘ || ✘ || ✔ || ✔ || Used to capture the event of app coming to foreground
|-
| Log || [[setDebug()]] || ✘ || ✘ || ✘ || ✘ || ✔ || Used to enable/disable debug flags. Newly introduced in SDK version 5.0.0 for International (Germany)
|}

== 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.
*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.

=== Displaying Opt-Out in a WebView ===
<syntaxhighlight lang="java">
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
}
</syntaxhighlight>

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.

[[File:Privacy policy iOS.jpg|link=]]

<blockquote>'''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.</blockquote>

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

=== Sequence Diagram ===
[[File:optoutsequence-andr.jpg|link=]]

== Opt-out Android SDK Version '''5.1.1.18 or above''' ==
<blockquote>'''Note:''' If using Android SDK Versions 1.2.3, 4.0.0.8, 5.1.0, 5.1.1.14, skip ahead to: [[#Opt-out Android SDK Version 1.2.3, 4.0.0.8, 5.1.0, 5.1.1.14|Opt-out Android SDK Version 1.2.3, 4.0.0.8, 5.1.0, 5.1.1.14]]</blockquote>

Starting from SDK version 5.1.1.18, Opt-Out related behavior has been changed in the following ways:
*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'''.
<blockquote>'''Note:''' For Amazon devices, see [[#Opt-Out Implementation for Amazon Devices|Opt-Out Implementation for Amazon Devices]] below.</blockquote>

[[File:andr-ads.jpg|link=]]

<blockquote>'''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.</blockquote>

== Opt-out Android SDK Version '''1.2.3, 4.0.0.8, 5.1.0, 5.1.1.14''' ==
<blockquote>'''Note:''' If using Android SDK Version 5.1.1.18 or above, refer to documentation above ([[#Opt-out Android SDK Version 5.1.1.18 or above|Opt-out Android SDK Version 5.1.1.18 or above]])</blockquote>

When a user clicks the Opt-Out / Opt-In link, the application should invoke [[optOutURL]] to get the link to the Nielsen Privacy page from SDK.
=== Privacy Page ===
[[File:privacy-policy.jpg|link=]]
*There are two click here links – one for Opt-Out and one for Opt-In. Click the required link:
**Capture user’s selection
**Pass the selection back to the SDK via the [[userOptOut()]].

=== Capture and forward user selection ===
<syntaxhighlight lang="java">
private class MonitorWebView extends WebViewClient
{
private static final String NIELSEN_URL_OPT_OUT = “nielsenappsdk://1”;
private static final String NIELSEN_URL_OPT_IN = “nielsenappsdk://0”;

@Override
public boolean shouldOverrideUrlLoading(WebView view, String url)
{
if (NIELSEN_URL_OPT_OUT.equals(url)
|| NIELSEN_URL_OPT_IN.equals(url))
{
// Get AppSdk instance from the host
AppSdk appSdk = HostApp.getAppSdk();
// Send the URL to the AppSdk instance
appSdk.userOptOut(url);
return true;
}
return false;
}
}
</syntaxhighlight>

<blockquote>'''Note:''' When 'WebView' is closed, pass the status returned from 'WebView' to the SDK within the app.</blockquote>
<blockquote>'''Note:''' App SDK manages the user's choice (Opt-Out / Opt-In), the app does not need to manage this status.</blockquote>

== 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 ===

<syntaxhighlight lang="java">
ContentResolver cr = getContentResolver();
int limitAdTracking = Secure.getInt(cr, "limit_ad_tracking", 2);
</syntaxhighlight>

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

<blockquote>'''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'''.</blockquote>

== Nielsen Sample Applications ==

== Nielsen Privacy Requirements ==
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.
[[File:RatingsDataFlow.png]]

'''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 ===
{| class="wikitable"
|-
! Type of Information !! Parameter !! Transmitted to Nielsen? !! Sent to Provider?
|-
| rowspan="8" | 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
|-
| rowspan="10" | 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
|-
| rowspan="9" | 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
|}
<blockquote>'''Note''': Data is hashed, and encrypted using AES 128 before transmission to data provider.</blockquote>

==== Example ping sent to provider ====
* <code><nowiki>https://provider.com/cgi-bin/brandlift.php</nowiki>?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</code>

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

=== Nielsen Measurement Opt-Out ===
In accordance with Nielsen’s SDK licensing agreement, developers are required to provide basic informational data to users about Nielsen’s Privacy Policy with a navigation to additional information on Nielsen measurement.

Nielsen currently uses Opt Out of Ads for Personalization for the latest versions of the SDK (5.1.1.18 and above). However, for older SDK versions, the app must provide a means for the user to opt out, or opt back in to Nielsen Measurement. Users can opt out of Nielsen online measurement research through this feature.
* If the user has this app running on more than one mobile device, the user will need to opt out of this measurement on each device.
<blockquote>'''Note''': Opt Out feature does NOT rely on "Opt Out of Ads for Personalization" setting since Nielsen’s systems provide measurement metrics and do not serve ads to users.</blockquote>

In the Description of the app in Google Play Store, include a short description about Nielsen measurement, as below.

<blockquote>'''Sample Google Play Store Disclosure'''
This app features Nielsen proprietary measurement software which will allow you to contribute to market research, like Nielsen’s TV Ratings.

To learn more about our digital measurement products and your choices in regard to them, please visit http://www.nielsen.com/digitalprivacy for more information.</blockquote>

== Event and Error Handling ==
=== App SDK Event Codes ===
'''App SDK Event Codes '''
{| class="wikitable"
|-
! Event Code !! Event Name !! Event Description
|-
| 2000 || EVENT_INITIATE || App SDK is initiated. It will happen as soon as the App SDK is initialized
|-
| 2001 || EVENT_STARTUP || App SDK has started up. It will happen only after App SDK has received a valid config file. This is the location in the code to acquire the value of [[userOptOutURLString()]].
|-
| 2002 || EVENT_SHUTDOWN || App SDK is shutting down. It will happen just before App SDK is destroyed
|}

=== App SDK Error Codes ===
Constants with predefined error codes which the AppSdk object can generate.

{| class="wikitable"
|-
! Event Code !! Event Name !! Description !! Behavior
|-
| 1001 || ERROR_FAILED_CREATE_URL_STRING || Failed generating ping string due to error on parsing || Include last error message from URL parser
|-
| 1002 || ERROR_FAILED_RECEIVE_CONFIG || Failed to receive configuration file from Census || On 5th time, it will log event and keep requesting config 10 min apart
|-
| 1003 || ERROR_FAILED_PARSING_CONFIG || Failed parsing the config file JSON string || Include json error number/short message from iOS or Android
|-
| 1004 || ERROR_FAILED_PARSING_PLAY || Failed parsing the play() JSON string || Include JSON error number/short message from iOS or Android
|-
| 1005 || ERROR_FAILED_PARSING_METADATA || Failed parsing the play() JSON string || Include JSON error number/short message from iOS or Android
|-
| 1006 || ERROR_FAILED_GENERATING_PING || Failed creating ping before adding it to the UPLOAD table) || Include ping nol_url index, cadence to identify ping
|-
| 1007 || ERROR_FAILED_PROCESSOR_START || Failed starting data processor thread. Normally, that means a product || Include processor that failed to start
|-
| 1008 || ERROR_FAILED_PROCESS_ID3 || Failed processing data on a data processor. Normally, that means the input to a product || Include processor and data that failed to process (ID3 tag on a MTVR impression, for example)
|-
| 1009 || ERROR_FAILED_HTTP_SEND || Failed sending HTTP or HTTPS requests || Include HTTP error number
|-
| 1010 || ERROR_FAILED_SENDING_PING || Failed sending pings (on ANDROID, the ping on the UPLOAD table) || Include ping up to 80 char from the end
|-
| 1011 || ERROR_FAILED_SENDING_TSV || Failed sending TSV requests || Include TSV request message
|-
| 1012 || ERROR_FAILED_SENDING_STATION_ID || Failed sending Station ID requests || Include Station ID request message
|-
| 1013 || ERROR_FAILED_ACCESSING_DB || Failed read/write from/to database table || Include SQL statement and data and SQLite error number/message
|-
| 1014 || ERROR_CHANGED_DEVICE_ID || Device ID changed
|-
| 1015 || ERROR_CHANGED_NUID || NUID changed
|-
| 1016 || ERROR_SDK_NOT_INITIALIZED || App SDK initialization failed
|-
| 1017 || ERROR_FAILED_SDK_SUSPEND || App SDK failed to suspend activities
|-
| 1018 || ERROR_INVALID_PARAMETERS || App SDK invalid parameters
|-
| 1019 || ERROR_INVALID_STATE || App SDK called in incorrect state
|-
| 1020 || ERROR_FAILED_PROCESS_PLAYHEAD || App SDK failed processing playhead position
|-
| 1021 || ERROR_FAILED_PROCESS_METADATA || App SDK failed processing not-null, syntax valid JSON metadada
|-
| 1022 || ERROR_FAILED_PROCESS_STOP || App SDK failed processing stop
|}

Android SDK API Reference

2017-07-12T20:04:56Z

Admin2: /* App SDK Error Codes */

{{Breadcrumb|}} {{Breadcrumb|Digital}} {{CurrentBreadcrumb}}
[[Category:Digital]]
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.
*Create and initialize an instance object of <code>AppSdk</code> class.
*The player application can use this object to collect HLS timed metadata through a [[sendID3()]] call.
The Nielsen App SDK class is defined as the only public class belonging to the com.nielsen.app.sdk package. It inherits from the closeable interface and exposes the public APIs the client’s app will use. Below is the declaration of the <code>AppSdk</code> class: <code>public class AppSdk implements Closeable</code>

== Setting Up Development Environment ==
'''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.
<blockquote>'''Note''': App SDK 4.0.0 contains AppSDK.jar component only and does not support C/C++ libAppSdk.so components.</blockquote

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.

=== Setting up in Eclipse IDE ===
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.
<syntaxhighlight lang="java"><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"/></syntaxhighlight>
For more details to handle runtime permissions in Android versions, please visit [https://developer.android.com/training/permissions/requesting.html]. 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.

[[File:andr-properties-drm.jpg|link=]]

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

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

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.
Nielsen App SDK uses the following packages/classes from the Google Play service.

'''Library''':
* 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;

=== Setting up in Android Studio IDE ===
Launch '''Android Studio''' and select '''Import project (Eclipse ADT)'''.

[[File:andr-setup-launch.jpg|link=]]

Browse for project destination directory and click '''Next'''.

[[File:andr-import-project.jpg|link=]]

Go to '''File > Project Structure > App > Dependencies'''.

[[File:andr-pro-structure.jpg|link=]]

Click '''+''' to add library dependency.

Select '''play-services''' and click '''OK'''

[[File:andr-choose-library.jpg|link=]]

For more information, refer to https://developer.android.com/google/play-services/setup.html

== Initialization ==
=== Android Application Life Cycle with respect to Nielsen App SDK ===
[[File:andr-init-img1.jpg|link=]]

=== Step 1: App SDK initialization ===
==== For API version 4.0.0 and above ====

[[AppSDK()]] is no longer a singleton object and should be initialized as below.

'''Initialization of App SDK object through a JSON object'''
<syntaxhighlight lang="objective-c">
JSONObject config = null;

try
{
// Prepare AppSdk configuration object (JSONObject)
JSONObject appSdkConfig = new JSONObject()
.put("appid", "TXXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX")
.put("appname", "Sample App Name")
.put("sfcode", "uat-cert")
.put("nol_devDebug", "INFO") // only for debug builds
.put("custom_key1", "custom_value1")
.put("custom_key2", "custom_value2");
// 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);
}
</syntaxhighlight>

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

==== Android Application Life Cycle with respect to Nielsen App SDK ====
[[File:andr-radioandvideo-app.jpg|link=]]

=== Step 2: App SDK libraries inclusion in project ===
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).

=== Step 3: Nielsen App SDK Streaming Sessions ===
After ensuring that the SDK object has been initialized, link the streaming session APIs. The next steps are:
*Call [[play()]] when starting or resuming a streaming session. Use the channelName parameter to pass channel descriptor information. The channel name field is a 32-character free-form text field containing the name of the program or feed being sent (such as ESPN2, Food Network, etc.) which must be inserted on a JSON string.
*Load the CMS metadata by calling the [[loadMetadata()]] on the SDK object.
*Call [[stop()]] when ending or pausing a viewing session.
*During session playback, call the SDK [[setPlayheadPosition()]] and / or [[sendID3()]]
**Call [[setPlayheadPosition()]] every one second until the stream is stopped or paused. Normally this happens on Digital Audio measurements.
**Call [[sendID3()]] if the client relies on the Nielsen ID3 tags for its measurements; this call should happen whenever a new Nielsen ID3 metadata is available for processing. Normally this happens on DTVR and ID3 measurements.
Nielsen App SDK object handles filtering of ID3 tags and CMS tags, queuing/buffering of data, and all communications with Nielsen collection facility.
*The client’s app must clearly identify the mode of operation (live vs. VOD) and stick to the type of playhead coordinates until the playback is completed. The client must reliably provide the appropriated playhead position value depending on the type of content streamed.
*If streaming live video content, the client must pass the current UTC time in seconds as playhead position.
*If streaming VOD (video on demand), the client must stream the offset from the beginning of the file as playhead position.
*For all Digital Audio listening, the client must pass the current UTC time in seconds as playhead position, regardless of station type.

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

=== Sample ID3 tags ===
* <code>www.nielsen.com/X100zdCIGeIlgZnkYj6UvQ==/X100zdCIGeIlgZnkYj6UvQ==/AAAB2Jz2_k74GXSzx4npHuI_JwJd3QSUpW30rDkGTcbHEzIMWleCzM-uvNOP9fzJcQMWQLJqzXMCAxParOb5sGijSV9dNM3QiBniJYGZ5GI-lL1fXTTN0IgZ4iWBmeRiPpS9AAAAAAAAAAAAAAAAAAAAAFJWFM5SVhTONNU=/00000/00000/00</code>
* <code>www.nielsen.com/X100zdCIGeIlgZnkYj6UvQ==/R8WHe7pEBeqBhu8jTeXydg==/AAICoyitYqlxT7n6aZ0oMCGheFi4CXFp46AMUPZz1lMr_M9tr3_cjee1SHqxrOiVerMDLeyn9xzocZSKwi746Re8vNOtpNCAZjYABs_J0R25IHpvOc1HS8QHGgD5TgOJeS6gX100zdCIGeIlgZnkYj6UvVJWFNhSVhTiPE0=/00000/46016/00</code>
<blockquote>'''Note''': ID3 tags are not applicable for International (Germany)</blockquote>

=== Extracting ID3 tags from Android Players ===
==== ID3 Support Matrix ====
{| class="wikitable"
|-
! Player Name !! Minimum supported version !! Description
|-
| Android Native Media Player || Android 6 || Android 6 Media Player allows apps to register a callback to be invoked, when a selected track has the timed metadata available. Currently, only HTTP Live Streaming (HLS) data URI’s embedded with timed ID3 tags, generates TimedMetaData.
|-
| Google ExoPlayer || Android 4.1 ||
|-
| Brightcove Player || Android 4.1 || Support for Android versions 2.3.3 and 4.0 is now deprecated. Learn more about why Brightcove is removing support for these versions as of January 1, 2016 in this [https://support.brightcove.com/en/perform/docs/announcement-brightcove-sdk-android-version-support|announcement]
|-
| Adobe PrimeTime Player || Android 4.2 ||
|-
| VisualOn Player || Android 2.3 || Android 5 is the latest supported version
|-
| NexStream Player || Android 1.6 || Supported till Android 6
|}

==== Android Native Media Player ====
As the Android Media Player versions (prior to Android 6 / Android API 23) do not support ID3, Nielsen has created a library that becomes an extension to the media player, thus MPX. This library extracts the ID3 tags and sends them to the app. For more information on how to use the MPX component, refer to the Nielsen-supplied sample application.

Starting from '''Android 6 (Android API 23)''', Android Native Media Player allows apps to register a callback to be invoked, when a selected track has the timed metadata available. Currently, only HTTP Live Streaming (HLS) data URI’s embedded with timed ID3 tags generate TimedMetadata. Once the HLS video starts, call onTimedMetaDataAvailable() as and when the player observes a TimedMetadata (ID3 tag).

<syntaxhighlight lang="java">@Override
public void onTimedMetaDataAvailable(MediaPlayer mp, TimedMetaData data)
{
byte[] iD3PayloadArray = data.getMetaData();
String iD3Payload = new String(iD3PayloadArray, StandardCharsets.UTF_8);
if (null != iD3Payload && iD3Payload.contains("www.nielsen.com"))
{
int index = iD3Payload.indexOf("www.nielsen.com");
String id3String = iD3Payload.substring(index, (index + 249));
Log.d(TAG, "TimedMetaData ID3 Tag:" + id3String);
appProcessID3tag(id3String);
}
}</syntaxhighlight>

==== ExoPlayer ====
he SDK is designed around an event-driven architecture where components emit events to allow other components to listen and respond to state changes.

'''Player SDK Classes used:'''
<syntaxhighlight lang="java">com.google.android.exoplayer.demo.player.DemoPlayer</syntaxhighlight>

Since Nielsen App SDK is interested in extracting the Timed Metadata (ID3 Tags) in HLS and VOD on the EXO Player, trace the ID3_TAG emitted during video content played using EXOPlayer component as below.

<syntaxhighlight lang="java">DemoPlayer implements ExoPlayer.Listener
—————————————————–
/**
* A listener for receiving ID3 metadata parsed from the media stream.
*/
public interface Id3MetadataListener
{
void onId3Metadata(Map<String, Object> metadata);
}
——————————————————-
MetadataTrackRenderer.MetadataRenderer<Map<String,
Object>> getId3MetadataRenderer()
{
return new MetadataTrackRenderer.MetadataRenderer<Map<String, Object>>()
{
@Override
public void onMetadata(Map<String, Object> metadata)
{
if (id3MetadataListener != null)
{
id3MetadataListener.onId3Metadata(metadata);
}
}
};
}</syntaxhighlight>

Also in ''Player.java'' class:
<syntaxhighlight lang="java">Player implements DemoPlayer.Id3MetadataListener
—————————————————–
@SuppressWarnings("rawtypes")
@Override
public void onId3Metadata(Map<String, Object> metadata)
{
try
{
for (Object o : metadata.entrySet())
{
Map.Entry pairs = (Map.Entry) o;
if (metadata.containsKey(TxxxMetadata.TYPE))
{
TxxxMetadata txxxMetadata = (TxxxMetadata) metadata
.get(TxxxMetadata.TYPE);
}
else
{
String aStr = new String((byte[]) pairs.getValue());
MainActivity.mAppSdk.sendID3(aStr);
}
}
}
catch (Exception e)
{
e.printStackTrace();
Log.d(TAG, "onId3Metadata(): No Id3 tags");
}
}</syntaxhighlight>

[[File:andr-exo-retrievingID3tags.png|link=]]

==== Brightcove Player ====
While the Brightcove player plays the content, EventListener triggers an event when an ID3 packet is received (<code>SeamlessVideoDisplayComponent.ID3_TAG</code>). Upon receiving this event, collect the incoming ID3 tags and only pass the Nielsen payload of the PRIV frame to the App SDK for analysis.

<syntaxhighlight lang="java">brightcoveVideoView.getEventEmitter().on(SeamlessVideoDisplayComponent.ID3_TAG, new EventListener()
{
public void processEvent(Event event)
{
NlsId3Tag nlsID3 = new NlsId3Tag(event.properties.get(SeamlessVideoDisplayComponent.ID3_DATA).toString());
Log.w("ID3", nlsID3.NlsPayload);
// Sent ID3 Tags to App
appProcessID3tag(nlsID3.NlsPayload);
}
});
}</syntaxhighlight>

==== Adobe PrimeTime Player ====
While the Adobe PrimeTime player plays the content, MediaPlayer.PlaybackEventListener triggers a callback when an ID3 packet is received (onTimedMetadata). Upon receiving this event, collect the incoming ID3 tags and only pass the Nielsen payload of the PRIV frame to the App SDK for analysis.
<syntaxhighlight lang="java">public void onTimedMetadata(TimedMetadata id3Metadata)
{
NlsId3Tag nlsID3 = new NlsId3Tag(id3Metadata.getMetadata().toString());
Log.w(LOG_TAG, "ID3 Timed Data –> " + nlsID3.NlsPayload);
Log.w(LOG_TAG, "PayLoad Size –> " + nlsID3.NlsPayload.length());
appProcessID3tag(nlsID3.NlsPayload);
}</syntaxhighlight>

==== VisualOn Player ====
While the VisualOn player plays the content, <code>VOCommonPlayerListener</code> triggers an event when an ID3 packet is received (<code>VO_OSMP_SRC_CUSTOMERTAGID_TIMEDTAG</code>). Upon receiving this event, collect the incoming ID3 tags and only pass the Nielsen payload of the PRIV frame to the App SDK for analysis.

<syntaxhighlight lang="java">case VO_OSMP_SRC_CB_CUSTOMER_TAG:
{
VO_OSMP_SRC_CUSTOMERTAGID tag = VO_OSMP_SRC_CUSTOMERTAGID.valueOf(nParam1);
switch (tag)
{
case VO_OSMP_SRC_CUSTOMERTAGID_TIMEDTAG:
// do something with this tag
int time = nParam2;
byte[] b = (byte[]) obj;
String s = new String(b);
NlsId3Tag nlsID3 = new NlsId3Tag(b);
// Sent ID3 Tags to App
appProcessID3tag(nlsID3.NlsPayload);
if (appid3If != null)
appid3If.onId3(nlsID3.NlsPayload);
break;
case VO_OSMP_SRC_CUSTOMERTAGID_MAX:
// ignore this type of tag
break;
default:
break;
}
break;
}</syntaxhighlight>

==== NextStream Player ====
ID3 tags will be received in the NexStream Player through <code>onTimedMetaRenderRender(NexPlayer mp,NexID3TagInformation metadata)</code> callback API. A sample implementation for the callback is shown below:
<syntaxhighlight lang="java">public void onTimedMetaRenderRender(NexPlayer mp, NexID3TagInformation m)
{
text = m.getPrivateFrame();
if (text != null)
{
data = text.getTextData();
if (data != null)
{
// make sure to identify the beginning of the
// Nielsen ID3 tag payload by searching for the
// "www.nielsen.com" string on the ID3 tag and
// passing to the App SDK all information that
// follows. It should be:
// nlsPayload = "www.nielsen.com" + dataFollowing
nlsPayload = getDataAfterWwwNielsenCom(data);
if (nlsPayload!= NULL)
mAppSdk.sendID3(nlsPayload);
}
}
}</syntaxhighlight>

The [[sendID3()]] sends the extracted Nielsen ID3 payload to the App SDK for analysis.

== Android SDK API Methods & Properties ==
{| class="wikitable sortable"
|-
! Scenario !! Method / Property !! DTVR !! DAR !! Digital Audio !! DCR !! International (Germany) !! Description
|-
| Initialize || [[AppSDK()]] || ✔ || ✔ || ✔ || ✔ || ✔ || 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 when there is a preroll ad that needs to be associated with content metadata. The loadmetadata will first be called to populate the content metadata values and then the loadMetadata for ad metadata will be called. This allows sending a content ping with the ad info, even if the user bails out during the preroll ad.
|-
| Measurement || [[sendID3()]] || ✔ || ✘ || ✘ || ✘ || ✘ || Used to send the ID3 metadata.
|-
| Measurement || [[setPlayheadPosition()]] || ✘ || ✘ || ✔ || ✔ || ✔ || 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 || [[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 || [[userOptOutURLString()]] || ✔ || ✔ || ✔ || ✔ || ✔ || 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 || [[getOptOutStatus()]] || ✘ || ✘ || ✘ || ✘ || ✔ || Call this API to retrieve the Opt-Out or Opt-In state.
|-
| Opt-out
| [[appDisableApi()]]
(kill switch)
|| ✔ || ✔ || ✔ || ✔ || ✔ || Used to disable the SDK.
|-
| Opt-out || [[getAppDisable()]] || ✔ || ✔ || ✔ || ✔ || ✔ || Used to query if the SDK is disabled or not.
|-
| Log || [[getLastEvent()]] || ✔ || ✔ || ✔ || ✔ || ✔ || Used to query the SDK for the last status
|-
| Log || [[getLastError()]] || ✔ || ✔ || ✔ || ✔ || ✔ || Used to query the SDK for the last error
|-
| Log || [[isValid()]] || ✔ || ✔ || ✔ || ✔ || ✔ || Used to check if the SDK was successfully instantiated or not.
|-
| Log || [[getMeterVersion()]] || ✘ || ✘ || ✘ || ✘ || ✔ || Returns the current SDK version.
|-
| Log || [[getNielsenId()]] || ✔ || ✔ || ✔ || ✔ || ✔ || Used to get a string defining the Nielsen ID (NUID) number for the device.
|-
| Log || [[getDeviceId()]] || ✔ || ✔ || ✔ || ✔ || ✔ || Returns the current device id.
|-
| Log || [[appInBackground()]] || ✘ || ✘ || ✘ || ✔ || ✔ || Used to capture the event of app going to background.
|-
| Log || [[appInForeground()]] || ✘ || ✘ || ✘ || ✔ || ✔ || Used to capture the event of app coming to foreground
|-
| Log || [[setDebug()]] || ✘ || ✘ || ✘ || ✘ || ✔ || Used to enable/disable debug flags. Newly introduced in SDK version 5.0.0 for International (Germany)
|}

== 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.
*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.

=== Displaying Opt-Out in a WebView ===
<syntaxhighlight lang="java">
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
}
</syntaxhighlight>

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.

[[File:Privacy policy iOS.jpg|link=]]

<blockquote>'''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.</blockquote>

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

=== Sequence Diagram ===
[[File:optoutsequence-andr.jpg|link=]]

== Opt-out Android SDK Version '''5.1.1.18 or above''' ==
<blockquote>'''Note:''' If using Android SDK Versions 1.2.3, 4.0.0.8, 5.1.0, 5.1.1.14, skip ahead to: [[#Opt-out Android SDK Version 1.2.3, 4.0.0.8, 5.1.0, 5.1.1.14|Opt-out Android SDK Version 1.2.3, 4.0.0.8, 5.1.0, 5.1.1.14]]</blockquote>

Starting from SDK version 5.1.1.18, Opt-Out related behavior has been changed in the following ways:
*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'''.
<blockquote>'''Note:''' For Amazon devices, see [[#Opt-Out Implementation for Amazon Devices|Opt-Out Implementation for Amazon Devices]] below.</blockquote>

[[File:andr-ads.jpg|link=]]

<blockquote>'''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.</blockquote>

== Opt-out Android SDK Version '''1.2.3, 4.0.0.8, 5.1.0, 5.1.1.14''' ==
<blockquote>'''Note:''' If using Android SDK Version 5.1.1.18 or above, refer to documentation above ([[#Opt-out Android SDK Version 5.1.1.18 or above|Opt-out Android SDK Version 5.1.1.18 or above]])</blockquote>

When a user clicks the Opt-Out / Opt-In link, the application should invoke [[optOutURL]] to get the link to the Nielsen Privacy page from SDK.
=== Privacy Page ===
[[File:privacy-policy.jpg|link=]]
*There are two click here links – one for Opt-Out and one for Opt-In. Click the required link:
**Capture user’s selection
**Pass the selection back to the SDK via the [[userOptOut()]].

=== Capture and forward user selection ===
<syntaxhighlight lang="java">
private class MonitorWebView extends WebViewClient
{
private static final String NIELSEN_URL_OPT_OUT = “nielsenappsdk://1”;
private static final String NIELSEN_URL_OPT_IN = “nielsenappsdk://0”;

@Override
public boolean shouldOverrideUrlLoading(WebView view, String url)
{
if (NIELSEN_URL_OPT_OUT.equals(url)
|| NIELSEN_URL_OPT_IN.equals(url))
{
// Get AppSdk instance from the host
AppSdk appSdk = HostApp.getAppSdk();
// Send the URL to the AppSdk instance
appSdk.userOptOut(url);
return true;
}
return false;
}
}
</syntaxhighlight>

<blockquote>'''Note:''' When 'WebView' is closed, pass the status returned from 'WebView' to the SDK within the app.</blockquote>
<blockquote>'''Note:''' App SDK manages the user's choice (Opt-Out / Opt-In), the app does not need to manage this status.</blockquote>

== 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 ===

<syntaxhighlight lang="java">
ContentResolver cr = getContentResolver();
int limitAdTracking = Secure.getInt(cr, "limit_ad_tracking", 2);
</syntaxhighlight>

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

<blockquote>'''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'''.</blockquote>

== Nielsen Sample Applications ==

== Nielsen Privacy Requirements ==
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.
[[File:RatingsDataFlow.png]]

'''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 ===
{| class="wikitable"
|-
! Type of Information !! Parameter !! Transmitted to Nielsen? !! Sent to Provider?
|-
| rowspan="8" | 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
|-
| rowspan="10" | 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
|-
| rowspan="9" | 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
|}
<blockquote>'''Note''': Data is hashed, and encrypted using AES 128 before transmission to data provider.</blockquote>

==== Example ping sent to provider ====
* <code><nowiki>https://provider.com/cgi-bin/brandlift.php</nowiki>?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</code>

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

=== Nielsen Measurement Opt-Out ===
In accordance with Nielsen’s SDK licensing agreement, developers are required to provide basic informational data to users about Nielsen’s Privacy Policy with a navigation to additional information on Nielsen measurement.

Nielsen currently uses Opt Out of Ads for Personalization for the latest versions of the SDK (5.1.1.18 and above). However, for older SDK versions, the app must provide a means for the user to opt out, or opt back in to Nielsen Measurement. Users can opt out of Nielsen online measurement research through this feature.
* If the user has this app running on more than one mobile device, the user will need to opt out of this measurement on each device.
<blockquote>'''Note''': Opt Out feature does NOT rely on "Opt Out of Ads for Personalization" setting since Nielsen’s systems provide measurement metrics and do not serve ads to users.</blockquote>

In the Description of the app in Google Play Store, include a short description about Nielsen measurement, as below.

<blockquote>'''Sample Google Play Store Disclosure'''
This app features Nielsen proprietary measurement software which will allow you to contribute to market research, like Nielsen’s TV Ratings.

To learn more about our digital measurement products and your choices in regard to them, please visit http://www.nielsen.com/digitalprivacy for more information.</blockquote>

== Event and Error Handling ==
=== App SDK Error Codes ===
Constants with predefined error codes which the AppSdk object can generate.

{| class="wikitable"
|-
! Event Code !! Event Name !! Description !! Behavior
|-
| 1001 || ERROR_FAILED_CREATE_URL_STRING || Failed generating ping string due to error on parsing || Include last error message from URL parser
|-
| 1002 || ERROR_FAILED_RECEIVE_CONFIG || Failed to receive configuration file from Census || On 5th time, it will log event and keep requesting config 10 min apart
|-
| 1003 || ERROR_FAILED_PARSING_CONFIG || Failed parsing the config file JSON string || Include json error number/short message from iOS or Android
|-
| 1004 || ERROR_FAILED_PARSING_PLAY || Failed parsing the play() JSON string || Include JSON error number/short message from iOS or Android
|-
| 1005 || ERROR_FAILED_PARSING_METADATA || Failed parsing the play() JSON string || Include JSON error number/short message from iOS or Android
|-
| 1006 || ERROR_FAILED_GENERATING_PING || Failed creating ping before adding it to the UPLOAD table) || Include ping nol_url index, cadence to identify ping
|-
| 1007 || ERROR_FAILED_PROCESSOR_START || Failed starting data processor thread. Normally, that means a product || Include processor that failed to start
|-
| 1008 || ERROR_FAILED_PROCESS_ID3 || Failed processing data on a data processor. Normally, that means the input to a product || Include processor and data that failed to process (ID3 tag on a MTVR impression, for example)
|-
| 1009 || ERROR_FAILED_HTTP_SEND || Failed sending HTTP or HTTPS requests || Include HTTP error number
|-
| 1010 || ERROR_FAILED_SENDING_PING || Failed sending pings (on ANDROID, the ping on the UPLOAD table) || Include ping up to 80 char from the end
|-
| 1011 || ERROR_FAILED_SENDING_TSV || Failed sending TSV requests || Include TSV request message
|-
| 1012 || ERROR_FAILED_SENDING_STATION_ID || Failed sending Station ID requests || Include Station ID request message
|-
| 1013 || ERROR_FAILED_ACCESSING_DB || Failed read/write from/to database table || Include SQL statement and data and SQLite error number/message
|-
| 1014 || ERROR_CHANGED_DEVICE_ID || Device ID changed
|-
| 1015 || ERROR_CHANGED_NUID || NUID changed
|-
| 1016 || ERROR_SDK_NOT_INITIALIZED || App SDK initialization failed
|-
| 1017 || ERROR_FAILED_SDK_SUSPEND || App SDK failed to suspend activities
|-
| 1018 || ERROR_INVALID_PARAMETERS || App SDK invalid parameters
|-
| 1019 || ERROR_INVALID_STATE || App SDK called in incorrect state
|-
| 1020 || ERROR_FAILED_PROCESS_PLAYHEAD || App SDK failed processing playhead position
|-
| 1021 || ERROR_FAILED_PROCESS_METADATA || App SDK failed processing not-null, syntax valid JSON metadada
|-
| 1022 || ERROR_FAILED_PROCESS_STOP || App SDK failed processing stop
|}

=== App SDK Event Codes ===
'''App SDK Event Codes '''
{| class="wikitable"
|-
! Event Code !! Event Name !! Event Description
|-
| 2000 || EVENT_INITIATE || App SDK is initiated. It will happen as soon as the App SDK is initialized
|-
| 2001 || EVENT_STARTUP || App SDK has started up. It will happen only after App SDK has received a valid config file. This is the location in the code to acquire the value of [[userOptOutURLString()]].
|-
| 2002 || EVENT_SHUTDOWN || App SDK is shutting down. It will happen just before App SDK is destroyed
|}

iOS SDK API Reference

2017-07-12T19:51:51Z

Admin2: /* App SDK Event Codes */

{{Breadcrumb|}} {{Breadcrumb|Digital}} {{CurrentBreadcrumb}}
[[Category:Digital]]
The iOS 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. These SDKs leverage the following:
*Nielsen audio watermark technologies for TV audience measurement
*The industry supported ID3 metadata tag specification
*Nielsen Combined Beacon technology
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
*Application crash events
*Time of viewing a sub section / page in the application.

== Importing Frameworks ==
'''Setting up your Xcode Development Environment'''

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

SDK uses the NSURLSession available from iOS 7 instead of the deprecated NSURLConnection.

<blockquote>'''Note''': App SDK supports devices running on iOS 9 and above, as all communications between the SDK and the Census (Collection Facility) use HTTPS.</blockquote>

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 (Not applicable for International (Germany))
* 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

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

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

== Initialization ==
The latest version of App SDK allows instantiating multiple instances of App SDK object and can be used simultaneously without any issues (The sharedInstance API that creates a singleton object in previous versions of App SDK is removed).
*Maximum of four SDK instances per appid are supported in this release. When a fifth SDK instance is launched,
**SDK will return “nil” from [[initWithAppInfo:delegate:]]
**Destroy one or more old SDK instances before creating new ones.

=== Stages of SDK Initialization ===
==== Step 1: App SDK Initialization ====
Initialize the Nielsen App object within the viewDidLoad view controller delegate method using initWithAppInfo:delegate:
<blockquote>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.</blockquote>

==== Step 2: Setting up event and error notifications ====
Once the <code>NielsenAppApi</code> object has been initialized, the next step is to enable notifications regarding ID3 tags extracted from the playing stream. In case of standard AVFoundation player, the SDK NSNotificationCenter API is used to
* Collect HLS timed metadata events (ID3 tags) during viewing sessions.
** Set up a timed metadata event listener method for receiving ID3 tags and calling Nielsen [[sendID3]].
* SDK uses the following NielsenAppApiDelegate protocol methods to notify its delegate (set during initialization) about event / error information.
** nielsenAppApi:eventOccurred
** nielsenAppApi:errorOccurred
<blockquote>'''Note''': Ensure to add to your view controller’s <code>@interface</code>.</blockquote>

<syntaxhighlight lang="objective-c">(void)nielsenAppApi:(NielsenAppApi *)appApi eventOccurred:(NSDictionary *)event {NSLog(@"Sample player is Notified by a Event : %@", event);
}
(void)nielsenAppApi:(NielsenAppApi *)appApi errorOccurred:(NSDictionary *)error {NSLog(@"Sample player is Notified by an Error : %@", error);
}</syntaxhighlight>

===== Sample event confirmation to player application upon successful initialization of SDK =====
<syntaxhighlight lang="console">NielsenSDKSampleDebug[9028:237989] [Nls:0] -I- Analytics framework Status:
{
"Event Description" = "Nielsen App SDK Version, ai.4.0.0.4 is initialized by the Player…";
EventStatus = 2001;
TimeStamp = "2015-07-23 14:51:06 +0000";
}</syntaxhighlight>

==== Step 3: Nielsen App SDK Streaming Sessions ====
After setting up observers for SDK events/errors and a listener method to process incoming Nielsen ID3 tags, the next steps are to
* Call [[play]] while starting or resuming a streaming session.
* Load CMS metadata using [[loadMetadata]].
* During session play, call [[playheadPosition]] every one second until the stream is stopped or interrupted (due to ad breaks or buffering).
* Call [[stop]] when pausing, ending a viewing session, or buffering is detected.

'''Serialized JSON string from NSDictionary'''
<syntaxhighlight lang="objective-c">NSDictionary* appInformation = @
{
@"appid": @"TXXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX",
@"appname": @"Sample App Name",
@"appversion": @"2.0",
@"sfcode": @"uat-cert",
@"nol_devDebug": @"INFO"
}
NSData* jsonDataAppInfo = [NSJSONSerialization dataWithJSONObject:appInformation options:0 error:nil];
NSString *jsonAppInfoString = [[NSString alloc] initWithData:jsonDataAppInfo encoding:NSUTF8StringEncoding];
nlsAppApiMeter = [[NielsenAppApi alloc] initWithAppInfo:jsonAppInfoString delegate:self];</syntaxhighlight>

Nielsen App SDK object handles filtering of ID3 tags and CMS tags, queuing/buffering of data, and all communications with Nielsen collection facility.

===== Nielsen iOS App SDK Application Life Cycle =====

[[File:initialization_appcycle.png|center|link=]]

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 '''Initial state'''.
# '''Idle state''' – The SDK is initialized and is ready to process playing information. Call <code>[[initWithAppInfo:delegate:]]</code> to move into this state. The SDK instance is not processing any data, but is listening for the play event to occur.
# '''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.
## [[playheadPosition]] – Call this API every one second when playhead position timer is fired.
## [[sendID3]] – Call this API when ID3 tags are identified in the stream.
## [[stop]] – Call this API when the playback is paused, switches between content and ad (within the same content playback) or encounters interruptions.
## [[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. SDK instance moves into this state in one of the following scenarios.
## Initialization fails
## [[appDisableApi]] is called
<blockquote>'''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 [[sendID3]] / [[playheadPosition]].</blockquote>

=== 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.
{| class="wikitable"
|-
! API call received !! Initial State !! Idle State !! Processing State !! Disabled State
|-
| <code>[[initWithAppInfo:delegate:]]</code> || IDLE STATE (OR)

DISABLED STATE
|| IDLE STATE || - || -
|-
| <code>[[play]]</code> & <code>[[loadMetadata]]</code>|| - || PROCESSING

STATE
|| - || -
|-
| <code>[[playheadPosition]]</code> || - || - || PROCESSING

STATE
|| -
|-
| <code>[[sendID3]]</code> || - || - || PROCESSING

STATE
|| -
|-
| <code>[[stop]]</code> || - || - || IDLE STATE || -
|-
| <code>[[end]]</code> || - || - || IDLE STATE || -
|-
| <code>[[appDisableApi]]</code>: YES || - || DISABLED

STATE
|| - || -
|-
| <code>[[appDisableApi]]</code>: NO || - || - || - || IDLE STATE (OR)

DISABLED STATE
|-
| <code>[[userOptOut]]</code>: YES || - || - || IDLE STATE || -
|-
| <code>[[userOptOut]]</code>: NO || - || PROCESSING

STATE
| -
| -
|-
| colspan = 5 | '-' 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.

==== JSON for NSDictionary object ====
<syntaxhighlight lang="objective-c">
NSDictionary* appInformation = @{
@"appid": @"TXXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX",
@"appname": @"Sample App Name",
@"appversion": @"2.0",
@"sfcode": @"uat-cert",
@"nol_devDebug": @"INFO"
};
nlsAppApiMeter = [[NielsenAppApi alloc] initWithAppInfo:appInformation delegate:delegate];</syntaxhighlight>

<code>appid</code>, <code>appname</code>, and <code>appversion</code> are mandatory parameters while <code>sfcode</code> is optional. <code>nol_devDebug</code> is meant for creating logs in test environments only.

==== JSON string from raw NSString ====
<syntaxhighlight lang="swift">NSString *appInfoString = @"{\"appid\" : \"TXXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX\", \"appname\" : \"Sample App Name\",\"appversion\" : \"2.0\",\"sfcode\" : \"uat-cert\"}";
NielsenAppAPi *appAPI = [[NielsenAppApi alloc] initWithAppInfo:appInfoString delegate:self];</syntaxhighlight>

==== JSON string from serialized NSDictionary ====
<syntaxhighlight lang="objective-c">NSDictionary* appInformation = @
{
@"appid": @"appid",
@"appname": @"appname",
@"appversion": @"2.0",
@"sfcode": @"sfcode",
@"nol_devDebug": @"INFO"
};
nlsAppApiMeter = [[NielsenAppApi alloc] initWithAppInfo:appInformation delegate:self];</syntaxhighlight>

While using JSON format for sending metadat, ensure enough care in including [[special characters]] in the values for arguments.

==== Example ====
<syntaxhighlight lang="objective-c">{
@"type": @"radio", // To send "radio" in metadata string
@"assetid": @"WXYZ-FM'101",
@"stationType": @"3",
@"provider": @"SampleProvider" // To send "SampleProvider" in metadata string
}</syntaxhighlight>
<blockquote>'''Note''': For mandatory parameters like appid, appname, and appversion, please refer to the parameters table in <code>[[initWithAppInfo:delegate:]]</code></blockquote>

== Retrieving ID3 Tags ==
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.

=== Sample ID3 tags ===
* <code>www.nielsen.com/X100zdCIGeIlgZnkYj6UvQ==/X100zdCIGeIlgZnkYj6UvQ==/AAAB2Jz2_k74GXSzx4npHuI_JwJd3QSUpW30rDkGTcbHEzIMWleCzM-uvNOP9fzJcQMWQLJqzXMCAxParOb5sGijSV9dNM3QiBniJYGZ5GI-lL1fXTTN0IgZ4iWBmeRiPpS9AAAAAAAAAAAAAAAAAAAAAFJWFM5SVhTONNU=/00000/00000/00</code>
* <code>www.nielsen.com/X100zdCIGeIlgZnkYj6UvQ==/R8WHe7pEBeqBhu8jTeXydg==/AAICoyitYqlxT7n6aZ0oMCGheFi4CXFp46AMUPZz1lMr_M9tr3_cjee1SHqxrOiVerMDLeyn9xzocZSKwi746Re8vNOtpNCAZjYABs_J0R25IHpvOc1HS8QHGgD5TgOJeS6gX100zdCIGeIlgZnkYj6UvVJWFNhSVhTiPE0=/00000/46016/00</code>

=== Examples of extracting ID3 tags from the iOS Native Player ===
==== AVPlayer ====
ID3 tags will be received in the Player on AVMetadataItem Callback method.
'''Create & get the AVMetadataItem callback method'''
<syntaxhighlight lang="swift">[self.player addObserver:self
forKeyPath: kTimedMetadataKey
options: NSKeyValueObservingOptionNew
Context: MyStreamingMovieViewControllerTimedMetadataObserverContext];</syntaxhighlight>

<syntaxhighlight lang="objective-c">
– (void)observeValueForKeyPath:(NSString*) path
ofObject: (id)object
change: (NSDictionary*)change
context: (void*)context
{
/* Set the AVPlayerLayer on the view to allow the AVPlayer object to display
its content. */
//[playerLayerView.playerLayer setPlayer:player];
/* AVPlayerItem "status" property value observer. */
if (context == MyStreamingMovieViewControllerTimedMetadataObserverContext)
{
id newMetadataArray = [change objectForKey:NSKeyValueChangeNewKey];
if (newMetadataArray != [NSNull null])
{
array = newMetadataArray;
for (AVMetadataItem *metadataItem in array)
{
[self handleTimedMetadata: metadataItem];
}
}
}
</syntaxhighlight>

<syntaxhighlight lang="objective-c">
– (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;
}
if ([(NSString *)[timedMetadata key] isEqualToString:@"PRIV"]&&[extraString rangeOfString:@"www.nielsen.com"].length> 0)
{
if ([[timedMetadata value] isKindOfClass:[NSData class]])
{
// Sending ID3 Tag
/* The sendID3: sends the extracted Nielsen ID3 payload to the App SDK for analysis. */
[[NielsenAppApi sharedInstance]sendID3: extraString];
NSString *value=[timedMetadata stringValue];
if (value != nil)
{
// NSString *strMessage=[[@"ID3 Tag Received " stringByAppendingFormat:@"%d\n",countForMetadata] stringByAppendingString:value];
[self appendLogConsoleText:extraString];
}
}
}
else
{
NSLog(@"Could not send ID3 tags");
}
countForMetadata++;

}
</syntaxhighlight>

==== Movie Player ====
ID3 tags will be received in the Player on MPTimedMetadata Callback method.
'''Sample Implementation of MPTimedMetadata callback'''
<syntaxhighlight lang="objective-c">
– (void)handleTimedMetadata:(MPTimedMetadata*)timedMetadata
{
id extraAttributeType = [timedMetadata allMetadata];
NSString * extraString= nil;
if ([extraAttributeType isKindOfClass:[NSDictionary class]])
{
extraString = [extraAttributeType valueForKey:@"info"];
}
else if([extraAttributeType isKindOfClass:[NSString class]])
{
extraString = extraAttributeType;
}

if ([(NSString *)[timedMetadata key] isEqualToString:@"PRIV"]&&[extraString rangeOfString:@"www.nielsen.com"].length> 0)
{
if ([[timedMetadata value] isKindOfClass:[NSData class]])
{
// Sending ID3 Tag
[[NielsenAppApi sharedInstance]sendID3: extraString];
NSString *value=[timedMetadata value];
if (value != nil)
{

[self appendLogConsoleText:extraString];
}
}
}
else
{
NSLog(@"Could not send ID3 tags");
}
countForMetadata++;
}
</syntaxhighlight>
<blockquote>'''Note:''' ID3 tags are not applicable for International (Germany)</blockquote>

== IOS SDK API Methods & Properties ==
{| class="wikitable sortable"
|-
! Scenario !! Method / Property !! DTVR !! DAR !! Digital Audio !! 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 || [[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.
|-
| 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)
|}

== 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 to this web page should be called from SDK by invoking [[optOutURL]] and opened in 'WebView' / External browser.
*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 [[optOutStatus]] method.

=== Displaying Opt-Out in a WebView ===
<syntaxhighlight lang="objective-c">NielsenAppApi nAppApiObject;
@property(strong) UIWebView *optOutView;

// create WebView and set self as delegate
self.optOutView=[[UIWebViewalloc]initWithFrame:self.view.bounds];

self.optOutView.scalesPageToFit = yes;
// get Nielsen defined web address and load the page
NSString *webAddress = [nAppApiObject optOutURLString];

if(webAddress == nil)
{ // Handle it gracefully and retry later}
else
{
[optOutView loadRequest:[NSURLRequest requestWithURL:webAddress]];
// show the view to the user
[self.view addSubview:optOutView];
}</syntaxhighlight>

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.

[[File:Privacy policy iOS.jpg|link=]]

*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.
<syntaxhighlight lang="objective-c">
@property (readonly) BOOL optOutStatus;
</syntaxhighlight>
*App should provide a UI control like 'close' or 'back' button to close the 'WebView' / External browser.

=== Sequence Diagram ===
[[File:optoutsequence-ios.jpg|link=]]

== Opt-out SDK Version '''5.1.1.17 or above''' ==
<blockquote>'''Note:''' If using SDK Versions 1.2.3, 4.0.0.8, 5.1.0, 5.1.1.12, skip ahead to: [[#Opt-out SDK Version 1.2.3, 4.0.0.8, 5.1.0, 5.1.1.12|Opt-out SDK Version 1.2.3, 4.0.0.8, 5.1.0, 5.1.1.12]]</blockquote>

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.

[[File:Opt-Out iOS.jpg|link=]]

<blockquote>'''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.</blockquote>

== Opt-out SDK Version '''1.2.3, 4.0.0.8, 5.1.0, 5.1.1.12''' ==
<blockquote>'''Note:''' If using SDK Version 5.1.1.17 or above, refer to documentation above ([[#Opt-out SDK Version 5.1.1.17 or above|Opt-out SDK Version 5.1.1.17 or above]])</blockquote>

When a user clicks the Opt-Out / Opt-In link, the application should invoke [[optOutURL]] to get the link to the Nielsen Privacy page from SDK.
=== Privacy Page ===
[[File:privacy-policy.jpg|link=]]
*There are two click here links – one for Opt-Out and one for Opt-In. Click the required link:
**
[[File:Opt-Out Combined.jpg|link=]]
*Click OK in the dialog that appears, to confirm the action.
*The Opt-Out occurs by opening a Nielsen-defined web page and passing the user choice from the 'WebView'. In order to do this, the application needs to
**Implement the UIWebView delegate method to open the Nielsen Privacy web page
**Capture user's selection
**Pass the selection back to the SDK via the [[userOptOut]].

=== Capture and forward user selection ===
<syntaxhighlight lang="objective-c">-(BOOL)webView:(UIWebView *)webView shouldStartLoadWithRequest:(NSURLRequest *)request navigationType:(UIWebViewNavigationType)navigationType
{
NSString *command = [NSString stringWithFormat:@”%@”,request.URL];
if ([command isEqualToString:kNielsenWebClose]) {
// Close the WebView
[self performSelector:@selector(closeOptOutView) withObject:nil afterDelay:0];
return NO;
}
// Retrieve next URL if it’s not opt-in/out selection
return (![nAppApiObject userOptOut:command]);
}</syntaxhighlight>

*The app gets the user selection string via webviews shouldStartLoadWithRequest and invokes [[userOptOut]] with user selection. The delegate method handles the 'WebView' URL requests, interprets the commands, and calls the SDK accordingly.
**<code>[nAppApiObject userOptOut:command]</code> passes the user's selection on Nielsen Privacy page to the SDK to allow the SDK to perform the required functions.
<blockquote>'''Note:''' When 'WebView' is closed, pass the status returned from 'WebView' to the SDK within the app.</blockquote>
<blockquote>'''Note:''' App SDK manages the user's choice (Opt-Out / Opt-In), the app does not need to manage this status.</blockquote>

== 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:

[[File:TVOs OptOut LimitAdTracking1.png|link=]]

[[File:TVOs OptOut LimitAdTracking2.png|link=]]

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.

<blockquote>'''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.</blockquote>

== 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:
<syntaxhighlight lang="objective-c">
@interface NielsenAppApi: NSObject

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

– (instancetype)initWithAppInfo:(id)appInfo delegate:(id)delegate;

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

– (NSString *)getNielsenId _attribute((deprecated((“Please use nielsenId property instead.”))));
– (NSString *)optOutURLString _attribute((deprecated((“Please use optOutURL property instead.”))));
– (NSString *)getMeterVersion _attribute((deprecated((“Please use meterVersion property instead.”))));
– (NSDictionary *)getLastEventDict _attribute((deprecated((“Please use lastEventDict property instead.”))));
– (NSDictionary *)getLastErrorDict _attribute((deprecated((“Please use lastErrorDict property instead.”))));

@protocol NielsenAppApiDelegate<NSObject>

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

@end
</syntaxhighlight>

== Nielsen Sample Applications ==
Nielsen iOS sample player application consists of two sample application based on native Players integrated with SDK framework. The player demonstrates all the supported functions of the SDK.
*NielsenVideoPlayer
*NielsenRadioPlayer
Implementation of Video and Audio 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 two locations:
**Channels 1 and 2 are configured from the Settings application. Channel URLs and metadata parameters can be modified.
**Channels starting from 3 are configured in specific JSON file. URLs to this JSON config file can be changed from the Settings application.

== Nielsen Privacy Requirements ==
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.
[[File:RatingsDataFlow.png]]

'''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 ===
{| class="wikitable"
|-
! Type of Information !! Parameter !! Transmitted to Nielsen? !! Sent to Provider?
|-
| rowspan="8" | 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
|-
| rowspan="10" | 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
|-
| rowspan="9" | 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
|}
<blockquote>'''Note''': Data is hashed, and encrypted using AES 128 before transmission to data provider.</blockquote>

==== Example ping sent to provider ====
* <code><nowiki>https://provider.com/cgi-bin/brandlift.php</nowiki>?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</code>

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

=== Nielsen Measurement Opt-Out ===
In accordance with Nielsen’s SDK licensing agreement, developers are required to provide basic informational data to users about Nielsen’s Privacy Policy with a navigation to additional information on Nielsen measurement.

Nielsen currently uses Limit Ad Tracking for the latest versions of the SDK (5.1.1.17 and above). However, for older SDK versions, the app must provide a means for the user to opt out, or opt back in to Nielsen Measurement. Users can opt out of Nielsen online measurement research through this feature.
* If the user has this app running on more than one mobile device, the user will need to opt out of this measurement on each device.
<blockquote>'''Note''': Opt Out feature does NOT rely on "Limit Ad Tracking" setting since Nielsen’s systems provide measurement metrics and do not serve ads to users.</blockquote>

In the Description of the app in App Store, include a short description about Nielsen measurement, as below.

<blockquote>'''Sample App Store Disclosure'''
This app features Nielsen proprietary measurement software which will allow you to contribute to market research, like Nielsen’s TV Ratings.

To learn more about our digital measurement products and your choices in regard to them, please visit http://www.nielsen.com/digitalprivacy for more information.

[[File:measurement-samplescreen.jpg]]</blockquote>

Both iOS-based and TVOS-based player applications need to confirm to Nielsen Privacy Requirements. Refer to the Opt-Out implementation guidelines for iOS and TVOS platforms respectively for more details.

== AppApiEventCode ==
An enumeration with predefined App SDK event state transition codes.
<syntaxhighlight lang="objective-c">
typedef NS_ENUM(unsigned int, AppApiEventCode)
{
AppApiStartup = 2001,
AppApiShutdown = 2002,
}AppApiEventCode;
</syntaxhighlight>

=== App SDK Event Codes ===
{| class="wikitable"
|-
! 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 ==
An enumeration with predefined error codes which the App SDK object can generate.
<syntaxhighlight lang="objective-c">
typedef NS_ENUM(unsigned int, AppApiErrorCode)
{
AppApiNetworkConnectionFailure = 1001,
AppApiFileWriteFailure = 1002,
AppApiFileReadFailure = 1003,
AppApiEmptyValue = 1004,
AppApiEmptyAppName = 1005,
AppApiEmptyAppVersion = 1006,
AppApiEmptyAppId = 1007,
AppApiAnExceptionOccured = 1008,
AppApiUnknownExceptionOccured = 1009
};
</syntaxhighlight>

=== App SDK Error Codes ===
{| class="wikitable"
|-
! Event Code !! Event Name !! Event 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
|}

iOS SDK API Reference

2017-07-12T19:51:38Z

Admin2: /* App SDK Error Codes */

{{Breadcrumb|}} {{Breadcrumb|Digital}} {{CurrentBreadcrumb}}
[[Category:Digital]]
The iOS 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. These SDKs leverage the following:
*Nielsen audio watermark technologies for TV audience measurement
*The industry supported ID3 metadata tag specification
*Nielsen Combined Beacon technology
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
*Application crash events
*Time of viewing a sub section / page in the application.

== Importing Frameworks ==
'''Setting up your Xcode Development Environment'''

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

SDK uses the NSURLSession available from iOS 7 instead of the deprecated NSURLConnection.

<blockquote>'''Note''': App SDK supports devices running on iOS 9 and above, as all communications between the SDK and the Census (Collection Facility) use HTTPS.</blockquote>

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 (Not applicable for International (Germany))
* 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

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

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

== Initialization ==
The latest version of App SDK allows instantiating multiple instances of App SDK object and can be used simultaneously without any issues (The sharedInstance API that creates a singleton object in previous versions of App SDK is removed).
*Maximum of four SDK instances per appid are supported in this release. When a fifth SDK instance is launched,
**SDK will return “nil” from [[initWithAppInfo:delegate:]]
**Destroy one or more old SDK instances before creating new ones.

=== Stages of SDK Initialization ===
==== Step 1: App SDK Initialization ====
Initialize the Nielsen App object within the viewDidLoad view controller delegate method using initWithAppInfo:delegate:
<blockquote>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.</blockquote>

==== Step 2: Setting up event and error notifications ====
Once the <code>NielsenAppApi</code> object has been initialized, the next step is to enable notifications regarding ID3 tags extracted from the playing stream. In case of standard AVFoundation player, the SDK NSNotificationCenter API is used to
* Collect HLS timed metadata events (ID3 tags) during viewing sessions.
** Set up a timed metadata event listener method for receiving ID3 tags and calling Nielsen [[sendID3]].
* SDK uses the following NielsenAppApiDelegate protocol methods to notify its delegate (set during initialization) about event / error information.
** nielsenAppApi:eventOccurred
** nielsenAppApi:errorOccurred
<blockquote>'''Note''': Ensure to add to your view controller’s <code>@interface</code>.</blockquote>

<syntaxhighlight lang="objective-c">(void)nielsenAppApi:(NielsenAppApi *)appApi eventOccurred:(NSDictionary *)event {NSLog(@"Sample player is Notified by a Event : %@", event);
}
(void)nielsenAppApi:(NielsenAppApi *)appApi errorOccurred:(NSDictionary *)error {NSLog(@"Sample player is Notified by an Error : %@", error);
}</syntaxhighlight>

===== Sample event confirmation to player application upon successful initialization of SDK =====
<syntaxhighlight lang="console">NielsenSDKSampleDebug[9028:237989] [Nls:0] -I- Analytics framework Status:
{
"Event Description" = "Nielsen App SDK Version, ai.4.0.0.4 is initialized by the Player…";
EventStatus = 2001;
TimeStamp = "2015-07-23 14:51:06 +0000";
}</syntaxhighlight>

==== Step 3: Nielsen App SDK Streaming Sessions ====
After setting up observers for SDK events/errors and a listener method to process incoming Nielsen ID3 tags, the next steps are to
* Call [[play]] while starting or resuming a streaming session.
* Load CMS metadata using [[loadMetadata]].
* During session play, call [[playheadPosition]] every one second until the stream is stopped or interrupted (due to ad breaks or buffering).
* Call [[stop]] when pausing, ending a viewing session, or buffering is detected.

'''Serialized JSON string from NSDictionary'''
<syntaxhighlight lang="objective-c">NSDictionary* appInformation = @
{
@"appid": @"TXXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX",
@"appname": @"Sample App Name",
@"appversion": @"2.0",
@"sfcode": @"uat-cert",
@"nol_devDebug": @"INFO"
}
NSData* jsonDataAppInfo = [NSJSONSerialization dataWithJSONObject:appInformation options:0 error:nil];
NSString *jsonAppInfoString = [[NSString alloc] initWithData:jsonDataAppInfo encoding:NSUTF8StringEncoding];
nlsAppApiMeter = [[NielsenAppApi alloc] initWithAppInfo:jsonAppInfoString delegate:self];</syntaxhighlight>

Nielsen App SDK object handles filtering of ID3 tags and CMS tags, queuing/buffering of data, and all communications with Nielsen collection facility.

===== Nielsen iOS App SDK Application Life Cycle =====

[[File:initialization_appcycle.png|center|link=]]

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 '''Initial state'''.
# '''Idle state''' – The SDK is initialized and is ready to process playing information. Call <code>[[initWithAppInfo:delegate:]]</code> to move into this state. The SDK instance is not processing any data, but is listening for the play event to occur.
# '''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.
## [[playheadPosition]] – Call this API every one second when playhead position timer is fired.
## [[sendID3]] – Call this API when ID3 tags are identified in the stream.
## [[stop]] – Call this API when the playback is paused, switches between content and ad (within the same content playback) or encounters interruptions.
## [[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. SDK instance moves into this state in one of the following scenarios.
## Initialization fails
## [[appDisableApi]] is called
<blockquote>'''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 [[sendID3]] / [[playheadPosition]].</blockquote>

=== 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.
{| class="wikitable"
|-
! API call received !! Initial State !! Idle State !! Processing State !! Disabled State
|-
| <code>[[initWithAppInfo:delegate:]]</code> || IDLE STATE (OR)

DISABLED STATE
|| IDLE STATE || - || -
|-
| <code>[[play]]</code> & <code>[[loadMetadata]]</code>|| - || PROCESSING

STATE
|| - || -
|-
| <code>[[playheadPosition]]</code> || - || - || PROCESSING

STATE
|| -
|-
| <code>[[sendID3]]</code> || - || - || PROCESSING

STATE
|| -
|-
| <code>[[stop]]</code> || - || - || IDLE STATE || -
|-
| <code>[[end]]</code> || - || - || IDLE STATE || -
|-
| <code>[[appDisableApi]]</code>: YES || - || DISABLED

STATE
|| - || -
|-
| <code>[[appDisableApi]]</code>: NO || - || - || - || IDLE STATE (OR)

DISABLED STATE
|-
| <code>[[userOptOut]]</code>: YES || - || - || IDLE STATE || -
|-
| <code>[[userOptOut]]</code>: NO || - || PROCESSING

STATE
| -
| -
|-
| colspan = 5 | '-' 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.

==== JSON for NSDictionary object ====
<syntaxhighlight lang="objective-c">
NSDictionary* appInformation = @{
@"appid": @"TXXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX",
@"appname": @"Sample App Name",
@"appversion": @"2.0",
@"sfcode": @"uat-cert",
@"nol_devDebug": @"INFO"
};
nlsAppApiMeter = [[NielsenAppApi alloc] initWithAppInfo:appInformation delegate:delegate];</syntaxhighlight>

<code>appid</code>, <code>appname</code>, and <code>appversion</code> are mandatory parameters while <code>sfcode</code> is optional. <code>nol_devDebug</code> is meant for creating logs in test environments only.

==== JSON string from raw NSString ====
<syntaxhighlight lang="swift">NSString *appInfoString = @"{\"appid\" : \"TXXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX\", \"appname\" : \"Sample App Name\",\"appversion\" : \"2.0\",\"sfcode\" : \"uat-cert\"}";
NielsenAppAPi *appAPI = [[NielsenAppApi alloc] initWithAppInfo:appInfoString delegate:self];</syntaxhighlight>

==== JSON string from serialized NSDictionary ====
<syntaxhighlight lang="objective-c">NSDictionary* appInformation = @
{
@"appid": @"appid",
@"appname": @"appname",
@"appversion": @"2.0",
@"sfcode": @"sfcode",
@"nol_devDebug": @"INFO"
};
nlsAppApiMeter = [[NielsenAppApi alloc] initWithAppInfo:appInformation delegate:self];</syntaxhighlight>

While using JSON format for sending metadat, ensure enough care in including [[special characters]] in the values for arguments.

==== Example ====
<syntaxhighlight lang="objective-c">{
@"type": @"radio", // To send "radio" in metadata string
@"assetid": @"WXYZ-FM'101",
@"stationType": @"3",
@"provider": @"SampleProvider" // To send "SampleProvider" in metadata string
}</syntaxhighlight>
<blockquote>'''Note''': For mandatory parameters like appid, appname, and appversion, please refer to the parameters table in <code>[[initWithAppInfo:delegate:]]</code></blockquote>

== Retrieving ID3 Tags ==
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.

=== Sample ID3 tags ===
* <code>www.nielsen.com/X100zdCIGeIlgZnkYj6UvQ==/X100zdCIGeIlgZnkYj6UvQ==/AAAB2Jz2_k74GXSzx4npHuI_JwJd3QSUpW30rDkGTcbHEzIMWleCzM-uvNOP9fzJcQMWQLJqzXMCAxParOb5sGijSV9dNM3QiBniJYGZ5GI-lL1fXTTN0IgZ4iWBmeRiPpS9AAAAAAAAAAAAAAAAAAAAAFJWFM5SVhTONNU=/00000/00000/00</code>
* <code>www.nielsen.com/X100zdCIGeIlgZnkYj6UvQ==/R8WHe7pEBeqBhu8jTeXydg==/AAICoyitYqlxT7n6aZ0oMCGheFi4CXFp46AMUPZz1lMr_M9tr3_cjee1SHqxrOiVerMDLeyn9xzocZSKwi746Re8vNOtpNCAZjYABs_J0R25IHpvOc1HS8QHGgD5TgOJeS6gX100zdCIGeIlgZnkYj6UvVJWFNhSVhTiPE0=/00000/46016/00</code>

=== Examples of extracting ID3 tags from the iOS Native Player ===
==== AVPlayer ====
ID3 tags will be received in the Player on AVMetadataItem Callback method.
'''Create & get the AVMetadataItem callback method'''
<syntaxhighlight lang="swift">[self.player addObserver:self
forKeyPath: kTimedMetadataKey
options: NSKeyValueObservingOptionNew
Context: MyStreamingMovieViewControllerTimedMetadataObserverContext];</syntaxhighlight>

<syntaxhighlight lang="objective-c">
– (void)observeValueForKeyPath:(NSString*) path
ofObject: (id)object
change: (NSDictionary*)change
context: (void*)context
{
/* Set the AVPlayerLayer on the view to allow the AVPlayer object to display
its content. */
//[playerLayerView.playerLayer setPlayer:player];
/* AVPlayerItem "status" property value observer. */
if (context == MyStreamingMovieViewControllerTimedMetadataObserverContext)
{
id newMetadataArray = [change objectForKey:NSKeyValueChangeNewKey];
if (newMetadataArray != [NSNull null])
{
array = newMetadataArray;
for (AVMetadataItem *metadataItem in array)
{
[self handleTimedMetadata: metadataItem];
}
}
}
</syntaxhighlight>

<syntaxhighlight lang="objective-c">
– (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;
}
if ([(NSString *)[timedMetadata key] isEqualToString:@"PRIV"]&&[extraString rangeOfString:@"www.nielsen.com"].length> 0)
{
if ([[timedMetadata value] isKindOfClass:[NSData class]])
{
// Sending ID3 Tag
/* The sendID3: sends the extracted Nielsen ID3 payload to the App SDK for analysis. */
[[NielsenAppApi sharedInstance]sendID3: extraString];
NSString *value=[timedMetadata stringValue];
if (value != nil)
{
// NSString *strMessage=[[@"ID3 Tag Received " stringByAppendingFormat:@"%d\n",countForMetadata] stringByAppendingString:value];
[self appendLogConsoleText:extraString];
}
}
}
else
{
NSLog(@"Could not send ID3 tags");
}
countForMetadata++;

}
</syntaxhighlight>

==== Movie Player ====
ID3 tags will be received in the Player on MPTimedMetadata Callback method.
'''Sample Implementation of MPTimedMetadata callback'''
<syntaxhighlight lang="objective-c">
– (void)handleTimedMetadata:(MPTimedMetadata*)timedMetadata
{
id extraAttributeType = [timedMetadata allMetadata];
NSString * extraString= nil;
if ([extraAttributeType isKindOfClass:[NSDictionary class]])
{
extraString = [extraAttributeType valueForKey:@"info"];
}
else if([extraAttributeType isKindOfClass:[NSString class]])
{
extraString = extraAttributeType;
}

if ([(NSString *)[timedMetadata key] isEqualToString:@"PRIV"]&&[extraString rangeOfString:@"www.nielsen.com"].length> 0)
{
if ([[timedMetadata value] isKindOfClass:[NSData class]])
{
// Sending ID3 Tag
[[NielsenAppApi sharedInstance]sendID3: extraString];
NSString *value=[timedMetadata value];
if (value != nil)
{

[self appendLogConsoleText:extraString];
}
}
}
else
{
NSLog(@"Could not send ID3 tags");
}
countForMetadata++;
}
</syntaxhighlight>
<blockquote>'''Note:''' ID3 tags are not applicable for International (Germany)</blockquote>

== IOS SDK API Methods & Properties ==
{| class="wikitable sortable"
|-
! Scenario !! Method / Property !! DTVR !! DAR !! Digital Audio !! 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 || [[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.
|-
| 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)
|}

== 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 to this web page should be called from SDK by invoking [[optOutURL]] and opened in 'WebView' / External browser.
*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 [[optOutStatus]] method.

=== Displaying Opt-Out in a WebView ===
<syntaxhighlight lang="objective-c">NielsenAppApi nAppApiObject;
@property(strong) UIWebView *optOutView;

// create WebView and set self as delegate
self.optOutView=[[UIWebViewalloc]initWithFrame:self.view.bounds];

self.optOutView.scalesPageToFit = yes;
// get Nielsen defined web address and load the page
NSString *webAddress = [nAppApiObject optOutURLString];

if(webAddress == nil)
{ // Handle it gracefully and retry later}
else
{
[optOutView loadRequest:[NSURLRequest requestWithURL:webAddress]];
// show the view to the user
[self.view addSubview:optOutView];
}</syntaxhighlight>

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.

[[File:Privacy policy iOS.jpg|link=]]

*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.
<syntaxhighlight lang="objective-c">
@property (readonly) BOOL optOutStatus;
</syntaxhighlight>
*App should provide a UI control like 'close' or 'back' button to close the 'WebView' / External browser.

=== Sequence Diagram ===
[[File:optoutsequence-ios.jpg|link=]]

== Opt-out SDK Version '''5.1.1.17 or above''' ==
<blockquote>'''Note:''' If using SDK Versions 1.2.3, 4.0.0.8, 5.1.0, 5.1.1.12, skip ahead to: [[#Opt-out SDK Version 1.2.3, 4.0.0.8, 5.1.0, 5.1.1.12|Opt-out SDK Version 1.2.3, 4.0.0.8, 5.1.0, 5.1.1.12]]</blockquote>

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.

[[File:Opt-Out iOS.jpg|link=]]

<blockquote>'''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.</blockquote>

== Opt-out SDK Version '''1.2.3, 4.0.0.8, 5.1.0, 5.1.1.12''' ==
<blockquote>'''Note:''' If using SDK Version 5.1.1.17 or above, refer to documentation above ([[#Opt-out SDK Version 5.1.1.17 or above|Opt-out SDK Version 5.1.1.17 or above]])</blockquote>

When a user clicks the Opt-Out / Opt-In link, the application should invoke [[optOutURL]] to get the link to the Nielsen Privacy page from SDK.
=== Privacy Page ===
[[File:privacy-policy.jpg|link=]]
*There are two click here links – one for Opt-Out and one for Opt-In. Click the required link:
**
[[File:Opt-Out Combined.jpg|link=]]
*Click OK in the dialog that appears, to confirm the action.
*The Opt-Out occurs by opening a Nielsen-defined web page and passing the user choice from the 'WebView'. In order to do this, the application needs to
**Implement the UIWebView delegate method to open the Nielsen Privacy web page
**Capture user's selection
**Pass the selection back to the SDK via the [[userOptOut]].

=== Capture and forward user selection ===
<syntaxhighlight lang="objective-c">-(BOOL)webView:(UIWebView *)webView shouldStartLoadWithRequest:(NSURLRequest *)request navigationType:(UIWebViewNavigationType)navigationType
{
NSString *command = [NSString stringWithFormat:@”%@”,request.URL];
if ([command isEqualToString:kNielsenWebClose]) {
// Close the WebView
[self performSelector:@selector(closeOptOutView) withObject:nil afterDelay:0];
return NO;
}
// Retrieve next URL if it’s not opt-in/out selection
return (![nAppApiObject userOptOut:command]);
}</syntaxhighlight>

*The app gets the user selection string via webviews shouldStartLoadWithRequest and invokes [[userOptOut]] with user selection. The delegate method handles the 'WebView' URL requests, interprets the commands, and calls the SDK accordingly.
**<code>[nAppApiObject userOptOut:command]</code> passes the user's selection on Nielsen Privacy page to the SDK to allow the SDK to perform the required functions.
<blockquote>'''Note:''' When 'WebView' is closed, pass the status returned from 'WebView' to the SDK within the app.</blockquote>
<blockquote>'''Note:''' App SDK manages the user's choice (Opt-Out / Opt-In), the app does not need to manage this status.</blockquote>

== 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:

[[File:TVOs OptOut LimitAdTracking1.png|link=]]

[[File:TVOs OptOut LimitAdTracking2.png|link=]]

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.

<blockquote>'''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.</blockquote>

== 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:
<syntaxhighlight lang="objective-c">
@interface NielsenAppApi: NSObject

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

– (instancetype)initWithAppInfo:(id)appInfo delegate:(id)delegate;

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

– (NSString *)getNielsenId _attribute((deprecated((“Please use nielsenId property instead.”))));
– (NSString *)optOutURLString _attribute((deprecated((“Please use optOutURL property instead.”))));
– (NSString *)getMeterVersion _attribute((deprecated((“Please use meterVersion property instead.”))));
– (NSDictionary *)getLastEventDict _attribute((deprecated((“Please use lastEventDict property instead.”))));
– (NSDictionary *)getLastErrorDict _attribute((deprecated((“Please use lastErrorDict property instead.”))));

@protocol NielsenAppApiDelegate<NSObject>

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

@end
</syntaxhighlight>

== Nielsen Sample Applications ==
Nielsen iOS sample player application consists of two sample application based on native Players integrated with SDK framework. The player demonstrates all the supported functions of the SDK.
*NielsenVideoPlayer
*NielsenRadioPlayer
Implementation of Video and Audio 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 two locations:
**Channels 1 and 2 are configured from the Settings application. Channel URLs and metadata parameters can be modified.
**Channels starting from 3 are configured in specific JSON file. URLs to this JSON config file can be changed from the Settings application.

== Nielsen Privacy Requirements ==
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.
[[File:RatingsDataFlow.png]]

'''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 ===
{| class="wikitable"
|-
! Type of Information !! Parameter !! Transmitted to Nielsen? !! Sent to Provider?
|-
| rowspan="8" | 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
|-
| rowspan="10" | 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
|-
| rowspan="9" | 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
|}
<blockquote>'''Note''': Data is hashed, and encrypted using AES 128 before transmission to data provider.</blockquote>

==== Example ping sent to provider ====
* <code><nowiki>https://provider.com/cgi-bin/brandlift.php</nowiki>?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</code>

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

=== Nielsen Measurement Opt-Out ===
In accordance with Nielsen’s SDK licensing agreement, developers are required to provide basic informational data to users about Nielsen’s Privacy Policy with a navigation to additional information on Nielsen measurement.

Nielsen currently uses Limit Ad Tracking for the latest versions of the SDK (5.1.1.17 and above). However, for older SDK versions, the app must provide a means for the user to opt out, or opt back in to Nielsen Measurement. Users can opt out of Nielsen online measurement research through this feature.
* If the user has this app running on more than one mobile device, the user will need to opt out of this measurement on each device.
<blockquote>'''Note''': Opt Out feature does NOT rely on "Limit Ad Tracking" setting since Nielsen’s systems provide measurement metrics and do not serve ads to users.</blockquote>

In the Description of the app in App Store, include a short description about Nielsen measurement, as below.

<blockquote>'''Sample App Store Disclosure'''
This app features Nielsen proprietary measurement software which will allow you to contribute to market research, like Nielsen’s TV Ratings.

To learn more about our digital measurement products and your choices in regard to them, please visit http://www.nielsen.com/digitalprivacy for more information.

[[File:measurement-samplescreen.jpg]]</blockquote>

Both iOS-based and TVOS-based player applications need to confirm to Nielsen Privacy Requirements. Refer to the Opt-Out implementation guidelines for iOS and TVOS platforms respectively for more details.

== AppApiEventCode ==
An enumeration with predefined App SDK event state transition codes.
<syntaxhighlight lang="objective-c">
typedef NS_ENUM(unsigned int, AppApiEventCode)
{
AppApiStartup = 2001,
AppApiShutdown = 2002,
}AppApiEventCode;
</syntaxhighlight>

== App SDK Event Codes ==
{| class="wikitable"
|-
! 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 ==
An enumeration with predefined error codes which the App SDK object can generate.
<syntaxhighlight lang="objective-c">
typedef NS_ENUM(unsigned int, AppApiErrorCode)
{
AppApiNetworkConnectionFailure = 1001,
AppApiFileWriteFailure = 1002,
AppApiFileReadFailure = 1003,
AppApiEmptyValue = 1004,
AppApiEmptyAppName = 1005,
AppApiEmptyAppVersion = 1006,
AppApiEmptyAppId = 1007,
AppApiAnExceptionOccured = 1008,
AppApiUnknownExceptionOccured = 1009
};
</syntaxhighlight>

=== App SDK Error Codes ===
{| class="wikitable"
|-
! Event Code !! Event Name !! Event 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
|}

Android SDK API Reference

2017-07-12T19:50:27Z

Admin2: /* App SDK Event Codes */

{{Breadcrumb|}} {{Breadcrumb|Digital}} {{CurrentBreadcrumb}}
[[Category:Digital]]
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.
*Create and initialize an instance object of <code>AppSdk</code> class.
*The player application can use this object to collect HLS timed metadata through a [[sendID3()]] call.
The Nielsen App SDK class is defined as the only public class belonging to the com.nielsen.app.sdk package. It inherits from the closeable interface and exposes the public APIs the client’s app will use. Below is the declaration of the <code>AppSdk</code> class: <code>public class AppSdk implements Closeable</code>

== Setting Up Development Environment ==
'''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.
<blockquote>'''Note''': App SDK 4.0.0 contains AppSDK.jar component only and does not support C/C++ libAppSdk.so components.</blockquote

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.

=== Setting up in Eclipse IDE ===
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.
<syntaxhighlight lang="java"><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"/></syntaxhighlight>
For more details to handle runtime permissions in Android versions, please visit [https://developer.android.com/training/permissions/requesting.html]. 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.

[[File:andr-properties-drm.jpg|link=]]

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

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

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.
Nielsen App SDK uses the following packages/classes from the Google Play service.

'''Library''':
* 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;

=== Setting up in Android Studio IDE ===
Launch '''Android Studio''' and select '''Import project (Eclipse ADT)'''.

[[File:andr-setup-launch.jpg|link=]]

Browse for project destination directory and click '''Next'''.

[[File:andr-import-project.jpg|link=]]

Go to '''File > Project Structure > App > Dependencies'''.

[[File:andr-pro-structure.jpg|link=]]

Click '''+''' to add library dependency.

Select '''play-services''' and click '''OK'''

[[File:andr-choose-library.jpg|link=]]

For more information, refer to https://developer.android.com/google/play-services/setup.html

== Initialization ==
=== Android Application Life Cycle with respect to Nielsen App SDK ===
[[File:andr-init-img1.jpg|link=]]

=== Step 1: App SDK initialization ===
==== For API version 4.0.0 and above ====

[[AppSDK()]] is no longer a singleton object and should be initialized as below.

'''Initialization of App SDK object through a JSON object'''
<syntaxhighlight lang="objective-c">
JSONObject config = null;

try
{
// Prepare AppSdk configuration object (JSONObject)
JSONObject appSdkConfig = new JSONObject()
.put("appid", "TXXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX")
.put("appname", "Sample App Name")
.put("sfcode", "uat-cert")
.put("nol_devDebug", "INFO") // only for debug builds
.put("custom_key1", "custom_value1")
.put("custom_key2", "custom_value2");
// 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);
}
</syntaxhighlight>

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

==== Android Application Life Cycle with respect to Nielsen App SDK ====
[[File:andr-radioandvideo-app.jpg|link=]]

=== Step 2: App SDK libraries inclusion in project ===
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).

=== Step 3: Nielsen App SDK Streaming Sessions ===
After ensuring that the SDK object has been initialized, link the streaming session APIs. The next steps are:
*Call [[play()]] when starting or resuming a streaming session. Use the channelName parameter to pass channel descriptor information. The channel name field is a 32-character free-form text field containing the name of the program or feed being sent (such as ESPN2, Food Network, etc.) which must be inserted on a JSON string.
*Load the CMS metadata by calling the [[loadMetadata()]] on the SDK object.
*Call [[stop()]] when ending or pausing a viewing session.
*During session playback, call the SDK [[setPlayheadPosition()]] and / or [[sendID3()]]
**Call [[setPlayheadPosition()]] every one second until the stream is stopped or paused. Normally this happens on Digital Audio measurements.
**Call [[sendID3()]] if the client relies on the Nielsen ID3 tags for its measurements; this call should happen whenever a new Nielsen ID3 metadata is available for processing. Normally this happens on DTVR and ID3 measurements.
Nielsen App SDK object handles filtering of ID3 tags and CMS tags, queuing/buffering of data, and all communications with Nielsen collection facility.
*The client’s app must clearly identify the mode of operation (live vs. VOD) and stick to the type of playhead coordinates until the playback is completed. The client must reliably provide the appropriated playhead position value depending on the type of content streamed.
*If streaming live video content, the client must pass the current UTC time in seconds as playhead position.
*If streaming VOD (video on demand), the client must stream the offset from the beginning of the file as playhead position.
*For all Digital Audio listening, the client must pass the current UTC time in seconds as playhead position, regardless of station type.

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

=== Sample ID3 tags ===
* <code>www.nielsen.com/X100zdCIGeIlgZnkYj6UvQ==/X100zdCIGeIlgZnkYj6UvQ==/AAAB2Jz2_k74GXSzx4npHuI_JwJd3QSUpW30rDkGTcbHEzIMWleCzM-uvNOP9fzJcQMWQLJqzXMCAxParOb5sGijSV9dNM3QiBniJYGZ5GI-lL1fXTTN0IgZ4iWBmeRiPpS9AAAAAAAAAAAAAAAAAAAAAFJWFM5SVhTONNU=/00000/00000/00</code>
* <code>www.nielsen.com/X100zdCIGeIlgZnkYj6UvQ==/R8WHe7pEBeqBhu8jTeXydg==/AAICoyitYqlxT7n6aZ0oMCGheFi4CXFp46AMUPZz1lMr_M9tr3_cjee1SHqxrOiVerMDLeyn9xzocZSKwi746Re8vNOtpNCAZjYABs_J0R25IHpvOc1HS8QHGgD5TgOJeS6gX100zdCIGeIlgZnkYj6UvVJWFNhSVhTiPE0=/00000/46016/00</code>
<blockquote>'''Note''': ID3 tags are not applicable for International (Germany)</blockquote>

=== Extracting ID3 tags from Android Players ===
==== ID3 Support Matrix ====
{| class="wikitable"
|-
! Player Name !! Minimum supported version !! Description
|-
| Android Native Media Player || Android 6 || Android 6 Media Player allows apps to register a callback to be invoked, when a selected track has the timed metadata available. Currently, only HTTP Live Streaming (HLS) data URI’s embedded with timed ID3 tags, generates TimedMetaData.
|-
| Google ExoPlayer || Android 4.1 ||
|-
| Brightcove Player || Android 4.1 || Support for Android versions 2.3.3 and 4.0 is now deprecated. Learn more about why Brightcove is removing support for these versions as of January 1, 2016 in this [https://support.brightcove.com/en/perform/docs/announcement-brightcove-sdk-android-version-support|announcement]
|-
| Adobe PrimeTime Player || Android 4.2 ||
|-
| VisualOn Player || Android 2.3 || Android 5 is the latest supported version
|-
| NexStream Player || Android 1.6 || Supported till Android 6
|}

==== Android Native Media Player ====
As the Android Media Player versions (prior to Android 6 / Android API 23) do not support ID3, Nielsen has created a library that becomes an extension to the media player, thus MPX. This library extracts the ID3 tags and sends them to the app. For more information on how to use the MPX component, refer to the Nielsen-supplied sample application.

Starting from '''Android 6 (Android API 23)''', Android Native Media Player allows apps to register a callback to be invoked, when a selected track has the timed metadata available. Currently, only HTTP Live Streaming (HLS) data URI’s embedded with timed ID3 tags generate TimedMetadata. Once the HLS video starts, call onTimedMetaDataAvailable() as and when the player observes a TimedMetadata (ID3 tag).

<syntaxhighlight lang="java">@Override
public void onTimedMetaDataAvailable(MediaPlayer mp, TimedMetaData data)
{
byte[] iD3PayloadArray = data.getMetaData();
String iD3Payload = new String(iD3PayloadArray, StandardCharsets.UTF_8);
if (null != iD3Payload && iD3Payload.contains("www.nielsen.com"))
{
int index = iD3Payload.indexOf("www.nielsen.com");
String id3String = iD3Payload.substring(index, (index + 249));
Log.d(TAG, "TimedMetaData ID3 Tag:" + id3String);
appProcessID3tag(id3String);
}
}</syntaxhighlight>

==== ExoPlayer ====
he SDK is designed around an event-driven architecture where components emit events to allow other components to listen and respond to state changes.

'''Player SDK Classes used:'''
<syntaxhighlight lang="java">com.google.android.exoplayer.demo.player.DemoPlayer</syntaxhighlight>

Since Nielsen App SDK is interested in extracting the Timed Metadata (ID3 Tags) in HLS and VOD on the EXO Player, trace the ID3_TAG emitted during video content played using EXOPlayer component as below.

<syntaxhighlight lang="java">DemoPlayer implements ExoPlayer.Listener
—————————————————–
/**
* A listener for receiving ID3 metadata parsed from the media stream.
*/
public interface Id3MetadataListener
{
void onId3Metadata(Map<String, Object> metadata);
}
——————————————————-
MetadataTrackRenderer.MetadataRenderer<Map<String,
Object>> getId3MetadataRenderer()
{
return new MetadataTrackRenderer.MetadataRenderer<Map<String, Object>>()
{
@Override
public void onMetadata(Map<String, Object> metadata)
{
if (id3MetadataListener != null)
{
id3MetadataListener.onId3Metadata(metadata);
}
}
};
}</syntaxhighlight>

Also in ''Player.java'' class:
<syntaxhighlight lang="java">Player implements DemoPlayer.Id3MetadataListener
—————————————————–
@SuppressWarnings("rawtypes")
@Override
public void onId3Metadata(Map<String, Object> metadata)
{
try
{
for (Object o : metadata.entrySet())
{
Map.Entry pairs = (Map.Entry) o;
if (metadata.containsKey(TxxxMetadata.TYPE))
{
TxxxMetadata txxxMetadata = (TxxxMetadata) metadata
.get(TxxxMetadata.TYPE);
}
else
{
String aStr = new String((byte[]) pairs.getValue());
MainActivity.mAppSdk.sendID3(aStr);
}
}
}
catch (Exception e)
{
e.printStackTrace();
Log.d(TAG, "onId3Metadata(): No Id3 tags");
}
}</syntaxhighlight>

[[File:andr-exo-retrievingID3tags.png|link=]]

==== Brightcove Player ====
While the Brightcove player plays the content, EventListener triggers an event when an ID3 packet is received (<code>SeamlessVideoDisplayComponent.ID3_TAG</code>). Upon receiving this event, collect the incoming ID3 tags and only pass the Nielsen payload of the PRIV frame to the App SDK for analysis.

<syntaxhighlight lang="java">brightcoveVideoView.getEventEmitter().on(SeamlessVideoDisplayComponent.ID3_TAG, new EventListener()
{
public void processEvent(Event event)
{
NlsId3Tag nlsID3 = new NlsId3Tag(event.properties.get(SeamlessVideoDisplayComponent.ID3_DATA).toString());
Log.w("ID3", nlsID3.NlsPayload);
// Sent ID3 Tags to App
appProcessID3tag(nlsID3.NlsPayload);
}
});
}</syntaxhighlight>

==== Adobe PrimeTime Player ====
While the Adobe PrimeTime player plays the content, MediaPlayer.PlaybackEventListener triggers a callback when an ID3 packet is received (onTimedMetadata). Upon receiving this event, collect the incoming ID3 tags and only pass the Nielsen payload of the PRIV frame to the App SDK for analysis.
<syntaxhighlight lang="java">public void onTimedMetadata(TimedMetadata id3Metadata)
{
NlsId3Tag nlsID3 = new NlsId3Tag(id3Metadata.getMetadata().toString());
Log.w(LOG_TAG, "ID3 Timed Data –> " + nlsID3.NlsPayload);
Log.w(LOG_TAG, "PayLoad Size –> " + nlsID3.NlsPayload.length());
appProcessID3tag(nlsID3.NlsPayload);
}</syntaxhighlight>

==== VisualOn Player ====
While the VisualOn player plays the content, <code>VOCommonPlayerListener</code> triggers an event when an ID3 packet is received (<code>VO_OSMP_SRC_CUSTOMERTAGID_TIMEDTAG</code>). Upon receiving this event, collect the incoming ID3 tags and only pass the Nielsen payload of the PRIV frame to the App SDK for analysis.

<syntaxhighlight lang="java">case VO_OSMP_SRC_CB_CUSTOMER_TAG:
{
VO_OSMP_SRC_CUSTOMERTAGID tag = VO_OSMP_SRC_CUSTOMERTAGID.valueOf(nParam1);
switch (tag)
{
case VO_OSMP_SRC_CUSTOMERTAGID_TIMEDTAG:
// do something with this tag
int time = nParam2;
byte[] b = (byte[]) obj;
String s = new String(b);
NlsId3Tag nlsID3 = new NlsId3Tag(b);
// Sent ID3 Tags to App
appProcessID3tag(nlsID3.NlsPayload);
if (appid3If != null)
appid3If.onId3(nlsID3.NlsPayload);
break;
case VO_OSMP_SRC_CUSTOMERTAGID_MAX:
// ignore this type of tag
break;
default:
break;
}
break;
}</syntaxhighlight>

==== NextStream Player ====
ID3 tags will be received in the NexStream Player through <code>onTimedMetaRenderRender(NexPlayer mp,NexID3TagInformation metadata)</code> callback API. A sample implementation for the callback is shown below:
<syntaxhighlight lang="java">public void onTimedMetaRenderRender(NexPlayer mp, NexID3TagInformation m)
{
text = m.getPrivateFrame();
if (text != null)
{
data = text.getTextData();
if (data != null)
{
// make sure to identify the beginning of the
// Nielsen ID3 tag payload by searching for the
// "www.nielsen.com" string on the ID3 tag and
// passing to the App SDK all information that
// follows. It should be:
// nlsPayload = "www.nielsen.com" + dataFollowing
nlsPayload = getDataAfterWwwNielsenCom(data);
if (nlsPayload!= NULL)
mAppSdk.sendID3(nlsPayload);
}
}
}</syntaxhighlight>

The [[sendID3()]] sends the extracted Nielsen ID3 payload to the App SDK for analysis.

== Android SDK API Methods & Properties ==
{| class="wikitable sortable"
|-
! Scenario !! Method / Property !! DTVR !! DAR !! Digital Audio !! DCR !! International (Germany) !! Description
|-
| Initialize || [[AppSDK()]] || ✔ || ✔ || ✔ || ✔ || ✔ || 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 when there is a preroll ad that needs to be associated with content metadata. The loadmetadata will first be called to populate the content metadata values and then the loadMetadata for ad metadata will be called. This allows sending a content ping with the ad info, even if the user bails out during the preroll ad.
|-
| Measurement || [[sendID3()]] || ✔ || ✘ || ✘ || ✘ || ✘ || Used to send the ID3 metadata.
|-
| Measurement || [[setPlayheadPosition()]] || ✘ || ✘ || ✔ || ✔ || ✔ || 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 || [[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 || [[userOptOutURLString()]] || ✔ || ✔ || ✔ || ✔ || ✔ || 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 || [[getOptOutStatus()]] || ✘ || ✘ || ✘ || ✘ || ✔ || Call this API to retrieve the Opt-Out or Opt-In state.
|-
| Opt-out
| [[appDisableApi()]]
(kill switch)
|| ✔ || ✔ || ✔ || ✔ || ✔ || Used to disable the SDK.
|-
| Opt-out || [[getAppDisable()]] || ✔ || ✔ || ✔ || ✔ || ✔ || Used to query if the SDK is disabled or not.
|-
| Log || [[getLastEvent()]] || ✔ || ✔ || ✔ || ✔ || ✔ || Used to query the SDK for the last status
|-
| Log || [[getLastError()]] || ✔ || ✔ || ✔ || ✔ || ✔ || Used to query the SDK for the last error
|-
| Log || [[isValid()]] || ✔ || ✔ || ✔ || ✔ || ✔ || Used to check if the SDK was successfully instantiated or not.
|-
| Log || [[getMeterVersion()]] || ✘ || ✘ || ✘ || ✘ || ✔ || Returns the current SDK version.
|-
| Log || [[getNielsenId()]] || ✔ || ✔ || ✔ || ✔ || ✔ || Used to get a string defining the Nielsen ID (NUID) number for the device.
|-
| Log || [[getDeviceId()]] || ✔ || ✔ || ✔ || ✔ || ✔ || Returns the current device id.
|-
| Log || [[appInBackground()]] || ✘ || ✘ || ✘ || ✔ || ✔ || Used to capture the event of app going to background.
|-
| Log || [[appInForeground()]] || ✘ || ✘ || ✘ || ✔ || ✔ || Used to capture the event of app coming to foreground
|-
| Log || [[setDebug()]] || ✘ || ✘ || ✘ || ✘ || ✔ || Used to enable/disable debug flags. Newly introduced in SDK version 5.0.0 for International (Germany)
|}

== 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.
*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.

=== Displaying Opt-Out in a WebView ===
<syntaxhighlight lang="java">
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
}
</syntaxhighlight>

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.

[[File:Privacy policy iOS.jpg|link=]]

<blockquote>'''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.</blockquote>

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

=== Sequence Diagram ===
[[File:optoutsequence-andr.jpg|link=]]

== Opt-out Android SDK Version '''5.1.1.18 or above''' ==
<blockquote>'''Note:''' If using Android SDK Versions 1.2.3, 4.0.0.8, 5.1.0, 5.1.1.14, skip ahead to: [[#Opt-out Android SDK Version 1.2.3, 4.0.0.8, 5.1.0, 5.1.1.14|Opt-out Android SDK Version 1.2.3, 4.0.0.8, 5.1.0, 5.1.1.14]]</blockquote>

Starting from SDK version 5.1.1.18, Opt-Out related behavior has been changed in the following ways:
*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'''.
<blockquote>'''Note:''' For Amazon devices, see [[#Opt-Out Implementation for Amazon Devices|Opt-Out Implementation for Amazon Devices]] below.</blockquote>

[[File:andr-ads.jpg|link=]]

<blockquote>'''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.</blockquote>

== Opt-out Android SDK Version '''1.2.3, 4.0.0.8, 5.1.0, 5.1.1.14''' ==
<blockquote>'''Note:''' If using Android SDK Version 5.1.1.18 or above, refer to documentation above ([[#Opt-out Android SDK Version 5.1.1.18 or above|Opt-out Android SDK Version 5.1.1.18 or above]])</blockquote>

When a user clicks the Opt-Out / Opt-In link, the application should invoke [[optOutURL]] to get the link to the Nielsen Privacy page from SDK.
=== Privacy Page ===
[[File:privacy-policy.jpg|link=]]
*There are two click here links – one for Opt-Out and one for Opt-In. Click the required link:
**Capture user’s selection
**Pass the selection back to the SDK via the [[userOptOut()]].

=== Capture and forward user selection ===
<syntaxhighlight lang="java">
private class MonitorWebView extends WebViewClient
{
private static final String NIELSEN_URL_OPT_OUT = “nielsenappsdk://1”;
private static final String NIELSEN_URL_OPT_IN = “nielsenappsdk://0”;

@Override
public boolean shouldOverrideUrlLoading(WebView view, String url)
{
if (NIELSEN_URL_OPT_OUT.equals(url)
|| NIELSEN_URL_OPT_IN.equals(url))
{
// Get AppSdk instance from the host
AppSdk appSdk = HostApp.getAppSdk();
// Send the URL to the AppSdk instance
appSdk.userOptOut(url);
return true;
}
return false;
}
}
</syntaxhighlight>

<blockquote>'''Note:''' When 'WebView' is closed, pass the status returned from 'WebView' to the SDK within the app.</blockquote>
<blockquote>'''Note:''' App SDK manages the user's choice (Opt-Out / Opt-In), the app does not need to manage this status.</blockquote>

== 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 ===

<syntaxhighlight lang="java">
ContentResolver cr = getContentResolver();
int limitAdTracking = Secure.getInt(cr, "limit_ad_tracking", 2);
</syntaxhighlight>

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

<blockquote>'''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'''.</blockquote>

== Nielsen Sample Applications ==

== Nielsen Privacy Requirements ==
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.
[[File:RatingsDataFlow.png]]

'''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 ===
{| class="wikitable"
|-
! Type of Information !! Parameter !! Transmitted to Nielsen? !! Sent to Provider?
|-
| rowspan="8" | 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
|-
| rowspan="10" | 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
|-
| rowspan="9" | 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
|}
<blockquote>'''Note''': Data is hashed, and encrypted using AES 128 before transmission to data provider.</blockquote>

==== Example ping sent to provider ====
* <code><nowiki>https://provider.com/cgi-bin/brandlift.php</nowiki>?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</code>

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

=== Nielsen Measurement Opt-Out ===
In accordance with Nielsen’s SDK licensing agreement, developers are required to provide basic informational data to users about Nielsen’s Privacy Policy with a navigation to additional information on Nielsen measurement.

Nielsen currently uses Opt Out of Ads for Personalization for the latest versions of the SDK (5.1.1.18 and above). However, for older SDK versions, the app must provide a means for the user to opt out, or opt back in to Nielsen Measurement. Users can opt out of Nielsen online measurement research through this feature.
* If the user has this app running on more than one mobile device, the user will need to opt out of this measurement on each device.
<blockquote>'''Note''': Opt Out feature does NOT rely on "Opt Out of Ads for Personalization" setting since Nielsen’s systems provide measurement metrics and do not serve ads to users.</blockquote>

In the Description of the app in Google Play Store, include a short description about Nielsen measurement, as below.

<blockquote>'''Sample Google Play Store Disclosure'''
This app features Nielsen proprietary measurement software which will allow you to contribute to market research, like Nielsen’s TV Ratings.

To learn more about our digital measurement products and your choices in regard to them, please visit http://www.nielsen.com/digitalprivacy for more information.</blockquote>

== Event and Error Handling ==
=== App SDK Error Codes ===
Constants with predefined error codes which the AppSdk object can generate.
<syntaxhighlight lang="java">public static final int ERROR_FAILED_CREATE_URL_STRING = 1001;
// failed generating ping string due to error on parsing
// description – include last error message from URL parser
public static final int ERROR_FAILED_RECEIVE_CONFIG = 1002;
// failed to receive configuration file from Census
// description – on 5th time, it will log event and keep requesting config 10 min apart
public static final int ERROR_FAILED_PARSING_CONFIG = 1003;
// failed parsing the config file JSON string
// description – include json error number/short message from iOS or Android
public static final int ERROR_FAILED_PARSING_PLAY = 1004;
// failed parsing the play() JSON string
// description – include json error number/short message from iOS or Android
public static final int ERROR_FAILED_PARSING_METADATA = 1005;
// failed parsing the play() JSON string
// description – include JSON error number/short message from iOS or Android
public static final int ERROR_FAILED_GENERATING_PING = 1006;
// failed creating ping before adding it to the UPLOAD table)
// description – include ping nol_url index, cadence to identify ping
public static final int ERROR_FAILED_PROCESSOR_START = 1007;
// failed starting data processor thread. Normally, that means a product
// description – include processor that failed to start
public static final int ERROR_FAILED_PROCESS_ID3 = 1008;
// failed processing data on a data processor. Normally, that means the input to a product
// description – include processor and data that failed to process (ID3 tag on a MTVR impression, for example)
public static final int ERROR_FAILED_HTTP_SEND = 1009;
// failed sending HTTP or HTTPS requests
// description – include HTTP error number
public static final int ERROR_FAILED_SENDING_PING = 1010;
// failed sending pings (on ANDROID, the ping on the UPLOAD table)
// description – include ping up to 80 char from the end
public static final int ERROR_FAILED_SENDING_TSV = 1011;
// failed sending TSV requests
// description – include TSV request message
public static final int ERROR_FAILED_SENDING_STATION_ID = 1012;
// failed sending StationId requests
// description – include Station ID request message
public static final int ERROR_FAILED_ACCESSING_DB = 1013;
// failed read/write from/to database table
// description – include SQL statement and data and SQLite error number/message
public static final int ERROR_CHANGED_DEVICE_ID = 1014;
// device ID changed
// description – none
public static final int ERROR_CHANGED_NUID = 1015;
// NUID changed
// description – none
public static final int ERROR_SDK_NOT_INITIALIZED = 1016;
// App SDK initialization failed
// description – none
public static final int ERROR_FAILED_SDK_SUSPEND = 1017;
// App SDK failed to suspend activities
// description – none
public static final int ERROR_INVALID_PARAMETERS = 1018;
// App SDK invalid parameters
// description – none
public static final int ERROR_INVALID_STATE = 1019;
// App SDK called in incorrect state
// description – none
public static final int ERROR_FAILED_PROCESS_PLAYHEAD = 1020;
// App SDK failed processing playhead position
// description – none
public static final int ERROR_FAILED_PROCESS_METADATA = 1021;
// App SDK failed processing not-null, syntax valid JSON metadada
// description – none
public static final int ERROR_FAILED_PROCESS_STOP = 1022;
// App SDK failed processing stop
// description – none</syntaxhighlight>

=== App SDK Event Codes ===
'''App SDK Event Codes '''
{| class="wikitable"
|-
! Event Code !! Event Name !! Event Description
|-
| 2000 || EVENT_INITIATE || App SDK is initiated. It will happen as soon as the App SDK is initialized
|-
| 2001 || EVENT_STARTUP || App SDK has started up. It will happen only after App SDK has received a valid config file. This is the location in the code to acquire the value of [[userOptOutURLString()]].
|-
| 2002 || EVENT_SHUTDOWN || App SDK is shutting down. It will happen just before App SDK is destroyed
|}

Android SDK API Reference

2017-07-12T19:46:36Z

Admin2: /* Nielsen Privacy Requirements */

{{Breadcrumb|}} {{Breadcrumb|Digital}} {{CurrentBreadcrumb}}
[[Category:Digital]]
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.
*Create and initialize an instance object of <code>AppSdk</code> class.
*The player application can use this object to collect HLS timed metadata through a [[sendID3()]] call.
The Nielsen App SDK class is defined as the only public class belonging to the com.nielsen.app.sdk package. It inherits from the closeable interface and exposes the public APIs the client’s app will use. Below is the declaration of the <code>AppSdk</code> class: <code>public class AppSdk implements Closeable</code>

== Setting Up Development Environment ==
'''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.
<blockquote>'''Note''': App SDK 4.0.0 contains AppSDK.jar component only and does not support C/C++ libAppSdk.so components.</blockquote

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.

=== Setting up in Eclipse IDE ===
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.
<syntaxhighlight lang="java"><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"/></syntaxhighlight>
For more details to handle runtime permissions in Android versions, please visit [https://developer.android.com/training/permissions/requesting.html]. 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.

[[File:andr-properties-drm.jpg|link=]]

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

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

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.
Nielsen App SDK uses the following packages/classes from the Google Play service.

'''Library''':
* 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;

=== Setting up in Android Studio IDE ===
Launch '''Android Studio''' and select '''Import project (Eclipse ADT)'''.

[[File:andr-setup-launch.jpg|link=]]

Browse for project destination directory and click '''Next'''.

[[File:andr-import-project.jpg|link=]]

Go to '''File > Project Structure > App > Dependencies'''.

[[File:andr-pro-structure.jpg|link=]]

Click '''+''' to add library dependency.

Select '''play-services''' and click '''OK'''

[[File:andr-choose-library.jpg|link=]]

For more information, refer to https://developer.android.com/google/play-services/setup.html

== Initialization ==
=== Android Application Life Cycle with respect to Nielsen App SDK ===
[[File:andr-init-img1.jpg|link=]]

=== Step 1: App SDK initialization ===
==== For API version 4.0.0 and above ====

[[AppSDK()]] is no longer a singleton object and should be initialized as below.

'''Initialization of App SDK object through a JSON object'''
<syntaxhighlight lang="objective-c">
JSONObject config = null;

try
{
// Prepare AppSdk configuration object (JSONObject)
JSONObject appSdkConfig = new JSONObject()
.put("appid", "TXXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX")
.put("appname", "Sample App Name")
.put("sfcode", "uat-cert")
.put("nol_devDebug", "INFO") // only for debug builds
.put("custom_key1", "custom_value1")
.put("custom_key2", "custom_value2");
// 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);
}
</syntaxhighlight>

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

==== Android Application Life Cycle with respect to Nielsen App SDK ====
[[File:andr-radioandvideo-app.jpg|link=]]

=== Step 2: App SDK libraries inclusion in project ===
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).

=== Step 3: Nielsen App SDK Streaming Sessions ===
After ensuring that the SDK object has been initialized, link the streaming session APIs. The next steps are:
*Call [[play()]] when starting or resuming a streaming session. Use the channelName parameter to pass channel descriptor information. The channel name field is a 32-character free-form text field containing the name of the program or feed being sent (such as ESPN2, Food Network, etc.) which must be inserted on a JSON string.
*Load the CMS metadata by calling the [[loadMetadata()]] on the SDK object.
*Call [[stop()]] when ending or pausing a viewing session.
*During session playback, call the SDK [[setPlayheadPosition()]] and / or [[sendID3()]]
**Call [[setPlayheadPosition()]] every one second until the stream is stopped or paused. Normally this happens on Digital Audio measurements.
**Call [[sendID3()]] if the client relies on the Nielsen ID3 tags for its measurements; this call should happen whenever a new Nielsen ID3 metadata is available for processing. Normally this happens on DTVR and ID3 measurements.
Nielsen App SDK object handles filtering of ID3 tags and CMS tags, queuing/buffering of data, and all communications with Nielsen collection facility.
*The client’s app must clearly identify the mode of operation (live vs. VOD) and stick to the type of playhead coordinates until the playback is completed. The client must reliably provide the appropriated playhead position value depending on the type of content streamed.
*If streaming live video content, the client must pass the current UTC time in seconds as playhead position.
*If streaming VOD (video on demand), the client must stream the offset from the beginning of the file as playhead position.
*For all Digital Audio listening, the client must pass the current UTC time in seconds as playhead position, regardless of station type.

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

=== Sample ID3 tags ===
* <code>www.nielsen.com/X100zdCIGeIlgZnkYj6UvQ==/X100zdCIGeIlgZnkYj6UvQ==/AAAB2Jz2_k74GXSzx4npHuI_JwJd3QSUpW30rDkGTcbHEzIMWleCzM-uvNOP9fzJcQMWQLJqzXMCAxParOb5sGijSV9dNM3QiBniJYGZ5GI-lL1fXTTN0IgZ4iWBmeRiPpS9AAAAAAAAAAAAAAAAAAAAAFJWFM5SVhTONNU=/00000/00000/00</code>
* <code>www.nielsen.com/X100zdCIGeIlgZnkYj6UvQ==/R8WHe7pEBeqBhu8jTeXydg==/AAICoyitYqlxT7n6aZ0oMCGheFi4CXFp46AMUPZz1lMr_M9tr3_cjee1SHqxrOiVerMDLeyn9xzocZSKwi746Re8vNOtpNCAZjYABs_J0R25IHpvOc1HS8QHGgD5TgOJeS6gX100zdCIGeIlgZnkYj6UvVJWFNhSVhTiPE0=/00000/46016/00</code>
<blockquote>'''Note''': ID3 tags are not applicable for International (Germany)</blockquote>

=== Extracting ID3 tags from Android Players ===
==== ID3 Support Matrix ====
{| class="wikitable"
|-
! Player Name !! Minimum supported version !! Description
|-
| Android Native Media Player || Android 6 || Android 6 Media Player allows apps to register a callback to be invoked, when a selected track has the timed metadata available. Currently, only HTTP Live Streaming (HLS) data URI’s embedded with timed ID3 tags, generates TimedMetaData.
|-
| Google ExoPlayer || Android 4.1 ||
|-
| Brightcove Player || Android 4.1 || Support for Android versions 2.3.3 and 4.0 is now deprecated. Learn more about why Brightcove is removing support for these versions as of January 1, 2016 in this [https://support.brightcove.com/en/perform/docs/announcement-brightcove-sdk-android-version-support|announcement]
|-
| Adobe PrimeTime Player || Android 4.2 ||
|-
| VisualOn Player || Android 2.3 || Android 5 is the latest supported version
|-
| NexStream Player || Android 1.6 || Supported till Android 6
|}

==== Android Native Media Player ====
As the Android Media Player versions (prior to Android 6 / Android API 23) do not support ID3, Nielsen has created a library that becomes an extension to the media player, thus MPX. This library extracts the ID3 tags and sends them to the app. For more information on how to use the MPX component, refer to the Nielsen-supplied sample application.

Starting from '''Android 6 (Android API 23)''', Android Native Media Player allows apps to register a callback to be invoked, when a selected track has the timed metadata available. Currently, only HTTP Live Streaming (HLS) data URI’s embedded with timed ID3 tags generate TimedMetadata. Once the HLS video starts, call onTimedMetaDataAvailable() as and when the player observes a TimedMetadata (ID3 tag).

<syntaxhighlight lang="java">@Override
public void onTimedMetaDataAvailable(MediaPlayer mp, TimedMetaData data)
{
byte[] iD3PayloadArray = data.getMetaData();
String iD3Payload = new String(iD3PayloadArray, StandardCharsets.UTF_8);
if (null != iD3Payload && iD3Payload.contains("www.nielsen.com"))
{
int index = iD3Payload.indexOf("www.nielsen.com");
String id3String = iD3Payload.substring(index, (index + 249));
Log.d(TAG, "TimedMetaData ID3 Tag:" + id3String);
appProcessID3tag(id3String);
}
}</syntaxhighlight>

==== ExoPlayer ====
he SDK is designed around an event-driven architecture where components emit events to allow other components to listen and respond to state changes.

'''Player SDK Classes used:'''
<syntaxhighlight lang="java">com.google.android.exoplayer.demo.player.DemoPlayer</syntaxhighlight>

Since Nielsen App SDK is interested in extracting the Timed Metadata (ID3 Tags) in HLS and VOD on the EXO Player, trace the ID3_TAG emitted during video content played using EXOPlayer component as below.

<syntaxhighlight lang="java">DemoPlayer implements ExoPlayer.Listener
—————————————————–
/**
* A listener for receiving ID3 metadata parsed from the media stream.
*/
public interface Id3MetadataListener
{
void onId3Metadata(Map<String, Object> metadata);
}
——————————————————-
MetadataTrackRenderer.MetadataRenderer<Map<String,
Object>> getId3MetadataRenderer()
{
return new MetadataTrackRenderer.MetadataRenderer<Map<String, Object>>()
{
@Override
public void onMetadata(Map<String, Object> metadata)
{
if (id3MetadataListener != null)
{
id3MetadataListener.onId3Metadata(metadata);
}
}
};
}</syntaxhighlight>

Also in ''Player.java'' class:
<syntaxhighlight lang="java">Player implements DemoPlayer.Id3MetadataListener
—————————————————–
@SuppressWarnings("rawtypes")
@Override
public void onId3Metadata(Map<String, Object> metadata)
{
try
{
for (Object o : metadata.entrySet())
{
Map.Entry pairs = (Map.Entry) o;
if (metadata.containsKey(TxxxMetadata.TYPE))
{
TxxxMetadata txxxMetadata = (TxxxMetadata) metadata
.get(TxxxMetadata.TYPE);
}
else
{
String aStr = new String((byte[]) pairs.getValue());
MainActivity.mAppSdk.sendID3(aStr);
}
}
}
catch (Exception e)
{
e.printStackTrace();
Log.d(TAG, "onId3Metadata(): No Id3 tags");
}
}</syntaxhighlight>

[[File:andr-exo-retrievingID3tags.png|link=]]

==== Brightcove Player ====
While the Brightcove player plays the content, EventListener triggers an event when an ID3 packet is received (<code>SeamlessVideoDisplayComponent.ID3_TAG</code>). Upon receiving this event, collect the incoming ID3 tags and only pass the Nielsen payload of the PRIV frame to the App SDK for analysis.

<syntaxhighlight lang="java">brightcoveVideoView.getEventEmitter().on(SeamlessVideoDisplayComponent.ID3_TAG, new EventListener()
{
public void processEvent(Event event)
{
NlsId3Tag nlsID3 = new NlsId3Tag(event.properties.get(SeamlessVideoDisplayComponent.ID3_DATA).toString());
Log.w("ID3", nlsID3.NlsPayload);
// Sent ID3 Tags to App
appProcessID3tag(nlsID3.NlsPayload);
}
});
}</syntaxhighlight>

==== Adobe PrimeTime Player ====
While the Adobe PrimeTime player plays the content, MediaPlayer.PlaybackEventListener triggers a callback when an ID3 packet is received (onTimedMetadata). Upon receiving this event, collect the incoming ID3 tags and only pass the Nielsen payload of the PRIV frame to the App SDK for analysis.
<syntaxhighlight lang="java">public void onTimedMetadata(TimedMetadata id3Metadata)
{
NlsId3Tag nlsID3 = new NlsId3Tag(id3Metadata.getMetadata().toString());
Log.w(LOG_TAG, "ID3 Timed Data –> " + nlsID3.NlsPayload);
Log.w(LOG_TAG, "PayLoad Size –> " + nlsID3.NlsPayload.length());
appProcessID3tag(nlsID3.NlsPayload);
}</syntaxhighlight>

==== VisualOn Player ====
While the VisualOn player plays the content, <code>VOCommonPlayerListener</code> triggers an event when an ID3 packet is received (<code>VO_OSMP_SRC_CUSTOMERTAGID_TIMEDTAG</code>). Upon receiving this event, collect the incoming ID3 tags and only pass the Nielsen payload of the PRIV frame to the App SDK for analysis.

<syntaxhighlight lang="java">case VO_OSMP_SRC_CB_CUSTOMER_TAG:
{
VO_OSMP_SRC_CUSTOMERTAGID tag = VO_OSMP_SRC_CUSTOMERTAGID.valueOf(nParam1);
switch (tag)
{
case VO_OSMP_SRC_CUSTOMERTAGID_TIMEDTAG:
// do something with this tag
int time = nParam2;
byte[] b = (byte[]) obj;
String s = new String(b);
NlsId3Tag nlsID3 = new NlsId3Tag(b);
// Sent ID3 Tags to App
appProcessID3tag(nlsID3.NlsPayload);
if (appid3If != null)
appid3If.onId3(nlsID3.NlsPayload);
break;
case VO_OSMP_SRC_CUSTOMERTAGID_MAX:
// ignore this type of tag
break;
default:
break;
}
break;
}</syntaxhighlight>

==== NextStream Player ====
ID3 tags will be received in the NexStream Player through <code>onTimedMetaRenderRender(NexPlayer mp,NexID3TagInformation metadata)</code> callback API. A sample implementation for the callback is shown below:
<syntaxhighlight lang="java">public void onTimedMetaRenderRender(NexPlayer mp, NexID3TagInformation m)
{
text = m.getPrivateFrame();
if (text != null)
{
data = text.getTextData();
if (data != null)
{
// make sure to identify the beginning of the
// Nielsen ID3 tag payload by searching for the
// "www.nielsen.com" string on the ID3 tag and
// passing to the App SDK all information that
// follows. It should be:
// nlsPayload = "www.nielsen.com" + dataFollowing
nlsPayload = getDataAfterWwwNielsenCom(data);
if (nlsPayload!= NULL)
mAppSdk.sendID3(nlsPayload);
}
}
}</syntaxhighlight>

The [[sendID3()]] sends the extracted Nielsen ID3 payload to the App SDK for analysis.

== Android SDK API Methods & Properties ==
{| class="wikitable sortable"
|-
! Scenario !! Method / Property !! DTVR !! DAR !! Digital Audio !! DCR !! International (Germany) !! Description
|-
| Initialize || [[AppSDK()]] || ✔ || ✔ || ✔ || ✔ || ✔ || 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 when there is a preroll ad that needs to be associated with content metadata. The loadmetadata will first be called to populate the content metadata values and then the loadMetadata for ad metadata will be called. This allows sending a content ping with the ad info, even if the user bails out during the preroll ad.
|-
| Measurement || [[sendID3()]] || ✔ || ✘ || ✘ || ✘ || ✘ || Used to send the ID3 metadata.
|-
| Measurement || [[setPlayheadPosition()]] || ✘ || ✘ || ✔ || ✔ || ✔ || 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 || [[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 || [[userOptOutURLString()]] || ✔ || ✔ || ✔ || ✔ || ✔ || 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 || [[getOptOutStatus()]] || ✘ || ✘ || ✘ || ✘ || ✔ || Call this API to retrieve the Opt-Out or Opt-In state.
|-
| Opt-out
| [[appDisableApi()]]
(kill switch)
|| ✔ || ✔ || ✔ || ✔ || ✔ || Used to disable the SDK.
|-
| Opt-out || [[getAppDisable()]] || ✔ || ✔ || ✔ || ✔ || ✔ || Used to query if the SDK is disabled or not.
|-
| Log || [[getLastEvent()]] || ✔ || ✔ || ✔ || ✔ || ✔ || Used to query the SDK for the last status
|-
| Log || [[getLastError()]] || ✔ || ✔ || ✔ || ✔ || ✔ || Used to query the SDK for the last error
|-
| Log || [[isValid()]] || ✔ || ✔ || ✔ || ✔ || ✔ || Used to check if the SDK was successfully instantiated or not.
|-
| Log || [[getMeterVersion()]] || ✘ || ✘ || ✘ || ✘ || ✔ || Returns the current SDK version.
|-
| Log || [[getNielsenId()]] || ✔ || ✔ || ✔ || ✔ || ✔ || Used to get a string defining the Nielsen ID (NUID) number for the device.
|-
| Log || [[getDeviceId()]] || ✔ || ✔ || ✔ || ✔ || ✔ || Returns the current device id.
|-
| Log || [[appInBackground()]] || ✘ || ✘ || ✘ || ✔ || ✔ || Used to capture the event of app going to background.
|-
| Log || [[appInForeground()]] || ✘ || ✘ || ✘ || ✔ || ✔ || Used to capture the event of app coming to foreground
|-
| Log || [[setDebug()]] || ✘ || ✘ || ✘ || ✘ || ✔ || Used to enable/disable debug flags. Newly introduced in SDK version 5.0.0 for International (Germany)
|}

== 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.
*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.

=== Displaying Opt-Out in a WebView ===
<syntaxhighlight lang="java">
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
}
</syntaxhighlight>

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.

[[File:Privacy policy iOS.jpg|link=]]

<blockquote>'''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.</blockquote>

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

=== Sequence Diagram ===
[[File:optoutsequence-andr.jpg|link=]]

== Opt-out Android SDK Version '''5.1.1.18 or above''' ==
<blockquote>'''Note:''' If using Android SDK Versions 1.2.3, 4.0.0.8, 5.1.0, 5.1.1.14, skip ahead to: [[#Opt-out Android SDK Version 1.2.3, 4.0.0.8, 5.1.0, 5.1.1.14|Opt-out Android SDK Version 1.2.3, 4.0.0.8, 5.1.0, 5.1.1.14]]</blockquote>

Starting from SDK version 5.1.1.18, Opt-Out related behavior has been changed in the following ways:
*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'''.
<blockquote>'''Note:''' For Amazon devices, see [[#Opt-Out Implementation for Amazon Devices|Opt-Out Implementation for Amazon Devices]] below.</blockquote>

[[File:andr-ads.jpg|link=]]

<blockquote>'''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.</blockquote>

== Opt-out Android SDK Version '''1.2.3, 4.0.0.8, 5.1.0, 5.1.1.14''' ==
<blockquote>'''Note:''' If using Android SDK Version 5.1.1.18 or above, refer to documentation above ([[#Opt-out Android SDK Version 5.1.1.18 or above|Opt-out Android SDK Version 5.1.1.18 or above]])</blockquote>

When a user clicks the Opt-Out / Opt-In link, the application should invoke [[optOutURL]] to get the link to the Nielsen Privacy page from SDK.
=== Privacy Page ===
[[File:privacy-policy.jpg|link=]]
*There are two click here links – one for Opt-Out and one for Opt-In. Click the required link:
**Capture user’s selection
**Pass the selection back to the SDK via the [[userOptOut()]].

=== Capture and forward user selection ===
<syntaxhighlight lang="java">
private class MonitorWebView extends WebViewClient
{
private static final String NIELSEN_URL_OPT_OUT = “nielsenappsdk://1”;
private static final String NIELSEN_URL_OPT_IN = “nielsenappsdk://0”;

@Override
public boolean shouldOverrideUrlLoading(WebView view, String url)
{
if (NIELSEN_URL_OPT_OUT.equals(url)
|| NIELSEN_URL_OPT_IN.equals(url))
{
// Get AppSdk instance from the host
AppSdk appSdk = HostApp.getAppSdk();
// Send the URL to the AppSdk instance
appSdk.userOptOut(url);
return true;
}
return false;
}
}
</syntaxhighlight>

<blockquote>'''Note:''' When 'WebView' is closed, pass the status returned from 'WebView' to the SDK within the app.</blockquote>
<blockquote>'''Note:''' App SDK manages the user's choice (Opt-Out / Opt-In), the app does not need to manage this status.</blockquote>

== 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 ===

<syntaxhighlight lang="java">
ContentResolver cr = getContentResolver();
int limitAdTracking = Secure.getInt(cr, "limit_ad_tracking", 2);
</syntaxhighlight>

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

<blockquote>'''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'''.</blockquote>

== Nielsen Sample Applications ==

== Nielsen Privacy Requirements ==
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.
[[File:RatingsDataFlow.png]]

'''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 ===
{| class="wikitable"
|-
! Type of Information !! Parameter !! Transmitted to Nielsen? !! Sent to Provider?
|-
| rowspan="8" | 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
|-
| rowspan="10" | 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
|-
| rowspan="9" | 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
|}
<blockquote>'''Note''': Data is hashed, and encrypted using AES 128 before transmission to data provider.</blockquote>

==== Example ping sent to provider ====
* <code><nowiki>https://provider.com/cgi-bin/brandlift.php</nowiki>?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</code>

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

=== Nielsen Measurement Opt-Out ===
In accordance with Nielsen’s SDK licensing agreement, developers are required to provide basic informational data to users about Nielsen’s Privacy Policy with a navigation to additional information on Nielsen measurement.

Nielsen currently uses Opt Out of Ads for Personalization for the latest versions of the SDK (5.1.1.18 and above). However, for older SDK versions, the app must provide a means for the user to opt out, or opt back in to Nielsen Measurement. Users can opt out of Nielsen online measurement research through this feature.
* If the user has this app running on more than one mobile device, the user will need to opt out of this measurement on each device.
<blockquote>'''Note''': Opt Out feature does NOT rely on "Opt Out of Ads for Personalization" setting since Nielsen’s systems provide measurement metrics and do not serve ads to users.</blockquote>

In the Description of the app in Google Play Store, include a short description about Nielsen measurement, as below.

<blockquote>'''Sample Google Play Store Disclosure'''
This app features Nielsen proprietary measurement software which will allow you to contribute to market research, like Nielsen’s TV Ratings.

To learn more about our digital measurement products and your choices in regard to them, please visit http://www.nielsen.com/digitalprivacy for more information.</blockquote>

== Event and Error Handling ==
=== App SDK Error Codes ===
Constants with predefined error codes which the AppSdk object can generate.
<syntaxhighlight lang="java">public static final int ERROR_FAILED_CREATE_URL_STRING = 1001;
// failed generating ping string due to error on parsing
// description – include last error message from URL parser
public static final int ERROR_FAILED_RECEIVE_CONFIG = 1002;
// failed to receive configuration file from Census
// description – on 5th time, it will log event and keep requesting config 10 min apart
public static final int ERROR_FAILED_PARSING_CONFIG = 1003;
// failed parsing the config file JSON string
// description – include json error number/short message from iOS or Android
public static final int ERROR_FAILED_PARSING_PLAY = 1004;
// failed parsing the play() JSON string
// description – include json error number/short message from iOS or Android
public static final int ERROR_FAILED_PARSING_METADATA = 1005;
// failed parsing the play() JSON string
// description – include JSON error number/short message from iOS or Android
public static final int ERROR_FAILED_GENERATING_PING = 1006;
// failed creating ping before adding it to the UPLOAD table)
// description – include ping nol_url index, cadence to identify ping
public static final int ERROR_FAILED_PROCESSOR_START = 1007;
// failed starting data processor thread. Normally, that means a product
// description – include processor that failed to start
public static final int ERROR_FAILED_PROCESS_ID3 = 1008;
// failed processing data on a data processor. Normally, that means the input to a product
// description – include processor and data that failed to process (ID3 tag on a MTVR impression, for example)
public static final int ERROR_FAILED_HTTP_SEND = 1009;
// failed sending HTTP or HTTPS requests
// description – include HTTP error number
public static final int ERROR_FAILED_SENDING_PING = 1010;
// failed sending pings (on ANDROID, the ping on the UPLOAD table)
// description – include ping up to 80 char from the end
public static final int ERROR_FAILED_SENDING_TSV = 1011;
// failed sending TSV requests
// description – include TSV request message
public static final int ERROR_FAILED_SENDING_STATION_ID = 1012;
// failed sending StationId requests
// description – include Station ID request message
public static final int ERROR_FAILED_ACCESSING_DB = 1013;
// failed read/write from/to database table
// description – include SQL statement and data and SQLite error number/message
public static final int ERROR_CHANGED_DEVICE_ID = 1014;
// device ID changed
// description – none
public static final int ERROR_CHANGED_NUID = 1015;
// NUID changed
// description – none
public static final int ERROR_SDK_NOT_INITIALIZED = 1016;
// App SDK initialization failed
// description – none
public static final int ERROR_FAILED_SDK_SUSPEND = 1017;
// App SDK failed to suspend activities
// description – none
public static final int ERROR_INVALID_PARAMETERS = 1018;
// App SDK invalid parameters
// description – none
public static final int ERROR_INVALID_STATE = 1019;
// App SDK called in incorrect state
// description – none
public static final int ERROR_FAILED_PROCESS_PLAYHEAD = 1020;
// App SDK failed processing playhead position
// description – none
public static final int ERROR_FAILED_PROCESS_METADATA = 1021;
// App SDK failed processing not-null, syntax valid JSON metadada
// description – none
public static final int ERROR_FAILED_PROCESS_STOP = 1022;
// App SDK failed processing stop
// description – none</syntaxhighlight>

=== App SDK Event Codes ===
<syntaxhighlight lang="java">public static final int EVENT_INITIATE = 2000;
// App SDK is initiated. It will happen as soon as the App SDK is initialized
public static final int EVENT_STARTUP = 2001;
// App SDK has started up. It will happen only after App SDK has received a valid config file. This is the location in the code to acquire the value of userOptOutURLString().
public static final int EVENT_SHUTDOWN = 2002;
// App SDK is shutting down. It will happen just before App SDK is destroyed</syntaxhighlight>

'''App SDK Event Codes '''
{| class="wikitable"
|-
! Event Code !! Event Name !! Event Description
|-
| 2000 || EVENT_INITIATE || App SDK is initiated. It will happen as soon as the App SDK is initialized
|-
| 2001 || EVENT_STARTUP || App SDK has started up. It will happen only after App SDK has received a valid config file
|-
| 2002 || EVENT_SHUTDOWN || App SDK is shutting down. It will happen just before App SDK is destroyed
|}

Android SDK API Reference

2017-07-12T19:42:48Z

Admin2: /* Opt-Out Implementation */

{{Breadcrumb|}} {{Breadcrumb|Digital}} {{CurrentBreadcrumb}}
[[Category:Digital]]
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.
*Create and initialize an instance object of <code>AppSdk</code> class.
*The player application can use this object to collect HLS timed metadata through a [[sendID3()]] call.
The Nielsen App SDK class is defined as the only public class belonging to the com.nielsen.app.sdk package. It inherits from the closeable interface and exposes the public APIs the client’s app will use. Below is the declaration of the <code>AppSdk</code> class: <code>public class AppSdk implements Closeable</code>

== Setting Up Development Environment ==
'''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.
<blockquote>'''Note''': App SDK 4.0.0 contains AppSDK.jar component only and does not support C/C++ libAppSdk.so components.</blockquote

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.

=== Setting up in Eclipse IDE ===
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.
<syntaxhighlight lang="java"><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"/></syntaxhighlight>
For more details to handle runtime permissions in Android versions, please visit [https://developer.android.com/training/permissions/requesting.html]. 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.

[[File:andr-properties-drm.jpg|link=]]

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

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

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.
Nielsen App SDK uses the following packages/classes from the Google Play service.

'''Library''':
* 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;

=== Setting up in Android Studio IDE ===
Launch '''Android Studio''' and select '''Import project (Eclipse ADT)'''.

[[File:andr-setup-launch.jpg|link=]]

Browse for project destination directory and click '''Next'''.

[[File:andr-import-project.jpg|link=]]

Go to '''File > Project Structure > App > Dependencies'''.

[[File:andr-pro-structure.jpg|link=]]

Click '''+''' to add library dependency.

Select '''play-services''' and click '''OK'''

[[File:andr-choose-library.jpg|link=]]

For more information, refer to https://developer.android.com/google/play-services/setup.html

== Initialization ==
=== Android Application Life Cycle with respect to Nielsen App SDK ===
[[File:andr-init-img1.jpg|link=]]

=== Step 1: App SDK initialization ===
==== For API version 4.0.0 and above ====

[[AppSDK()]] is no longer a singleton object and should be initialized as below.

'''Initialization of App SDK object through a JSON object'''
<syntaxhighlight lang="objective-c">
JSONObject config = null;

try
{
// Prepare AppSdk configuration object (JSONObject)
JSONObject appSdkConfig = new JSONObject()
.put("appid", "TXXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX")
.put("appname", "Sample App Name")
.put("sfcode", "uat-cert")
.put("nol_devDebug", "INFO") // only for debug builds
.put("custom_key1", "custom_value1")
.put("custom_key2", "custom_value2");
// 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);
}
</syntaxhighlight>

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

==== Android Application Life Cycle with respect to Nielsen App SDK ====
[[File:andr-radioandvideo-app.jpg|link=]]

=== Step 2: App SDK libraries inclusion in project ===
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).

=== Step 3: Nielsen App SDK Streaming Sessions ===
After ensuring that the SDK object has been initialized, link the streaming session APIs. The next steps are:
*Call [[play()]] when starting or resuming a streaming session. Use the channelName parameter to pass channel descriptor information. The channel name field is a 32-character free-form text field containing the name of the program or feed being sent (such as ESPN2, Food Network, etc.) which must be inserted on a JSON string.
*Load the CMS metadata by calling the [[loadMetadata()]] on the SDK object.
*Call [[stop()]] when ending or pausing a viewing session.
*During session playback, call the SDK [[setPlayheadPosition()]] and / or [[sendID3()]]
**Call [[setPlayheadPosition()]] every one second until the stream is stopped or paused. Normally this happens on Digital Audio measurements.
**Call [[sendID3()]] if the client relies on the Nielsen ID3 tags for its measurements; this call should happen whenever a new Nielsen ID3 metadata is available for processing. Normally this happens on DTVR and ID3 measurements.
Nielsen App SDK object handles filtering of ID3 tags and CMS tags, queuing/buffering of data, and all communications with Nielsen collection facility.
*The client’s app must clearly identify the mode of operation (live vs. VOD) and stick to the type of playhead coordinates until the playback is completed. The client must reliably provide the appropriated playhead position value depending on the type of content streamed.
*If streaming live video content, the client must pass the current UTC time in seconds as playhead position.
*If streaming VOD (video on demand), the client must stream the offset from the beginning of the file as playhead position.
*For all Digital Audio listening, the client must pass the current UTC time in seconds as playhead position, regardless of station type.

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

=== Sample ID3 tags ===
* <code>www.nielsen.com/X100zdCIGeIlgZnkYj6UvQ==/X100zdCIGeIlgZnkYj6UvQ==/AAAB2Jz2_k74GXSzx4npHuI_JwJd3QSUpW30rDkGTcbHEzIMWleCzM-uvNOP9fzJcQMWQLJqzXMCAxParOb5sGijSV9dNM3QiBniJYGZ5GI-lL1fXTTN0IgZ4iWBmeRiPpS9AAAAAAAAAAAAAAAAAAAAAFJWFM5SVhTONNU=/00000/00000/00</code>
* <code>www.nielsen.com/X100zdCIGeIlgZnkYj6UvQ==/R8WHe7pEBeqBhu8jTeXydg==/AAICoyitYqlxT7n6aZ0oMCGheFi4CXFp46AMUPZz1lMr_M9tr3_cjee1SHqxrOiVerMDLeyn9xzocZSKwi746Re8vNOtpNCAZjYABs_J0R25IHpvOc1HS8QHGgD5TgOJeS6gX100zdCIGeIlgZnkYj6UvVJWFNhSVhTiPE0=/00000/46016/00</code>
<blockquote>'''Note''': ID3 tags are not applicable for International (Germany)</blockquote>

=== Extracting ID3 tags from Android Players ===
==== ID3 Support Matrix ====
{| class="wikitable"
|-
! Player Name !! Minimum supported version !! Description
|-
| Android Native Media Player || Android 6 || Android 6 Media Player allows apps to register a callback to be invoked, when a selected track has the timed metadata available. Currently, only HTTP Live Streaming (HLS) data URI’s embedded with timed ID3 tags, generates TimedMetaData.
|-
| Google ExoPlayer || Android 4.1 ||
|-
| Brightcove Player || Android 4.1 || Support for Android versions 2.3.3 and 4.0 is now deprecated. Learn more about why Brightcove is removing support for these versions as of January 1, 2016 in this [https://support.brightcove.com/en/perform/docs/announcement-brightcove-sdk-android-version-support|announcement]
|-
| Adobe PrimeTime Player || Android 4.2 ||
|-
| VisualOn Player || Android 2.3 || Android 5 is the latest supported version
|-
| NexStream Player || Android 1.6 || Supported till Android 6
|}

==== Android Native Media Player ====
As the Android Media Player versions (prior to Android 6 / Android API 23) do not support ID3, Nielsen has created a library that becomes an extension to the media player, thus MPX. This library extracts the ID3 tags and sends them to the app. For more information on how to use the MPX component, refer to the Nielsen-supplied sample application.

Starting from '''Android 6 (Android API 23)''', Android Native Media Player allows apps to register a callback to be invoked, when a selected track has the timed metadata available. Currently, only HTTP Live Streaming (HLS) data URI’s embedded with timed ID3 tags generate TimedMetadata. Once the HLS video starts, call onTimedMetaDataAvailable() as and when the player observes a TimedMetadata (ID3 tag).

<syntaxhighlight lang="java">@Override
public void onTimedMetaDataAvailable(MediaPlayer mp, TimedMetaData data)
{
byte[] iD3PayloadArray = data.getMetaData();
String iD3Payload = new String(iD3PayloadArray, StandardCharsets.UTF_8);
if (null != iD3Payload && iD3Payload.contains("www.nielsen.com"))
{
int index = iD3Payload.indexOf("www.nielsen.com");
String id3String = iD3Payload.substring(index, (index + 249));
Log.d(TAG, "TimedMetaData ID3 Tag:" + id3String);
appProcessID3tag(id3String);
}
}</syntaxhighlight>

==== ExoPlayer ====
he SDK is designed around an event-driven architecture where components emit events to allow other components to listen and respond to state changes.

'''Player SDK Classes used:'''
<syntaxhighlight lang="java">com.google.android.exoplayer.demo.player.DemoPlayer</syntaxhighlight>

Since Nielsen App SDK is interested in extracting the Timed Metadata (ID3 Tags) in HLS and VOD on the EXO Player, trace the ID3_TAG emitted during video content played using EXOPlayer component as below.

<syntaxhighlight lang="java">DemoPlayer implements ExoPlayer.Listener
—————————————————–
/**
* A listener for receiving ID3 metadata parsed from the media stream.
*/
public interface Id3MetadataListener
{
void onId3Metadata(Map<String, Object> metadata);
}
——————————————————-
MetadataTrackRenderer.MetadataRenderer<Map<String,
Object>> getId3MetadataRenderer()
{
return new MetadataTrackRenderer.MetadataRenderer<Map<String, Object>>()
{
@Override
public void onMetadata(Map<String, Object> metadata)
{
if (id3MetadataListener != null)
{
id3MetadataListener.onId3Metadata(metadata);
}
}
};
}</syntaxhighlight>

Also in ''Player.java'' class:
<syntaxhighlight lang="java">Player implements DemoPlayer.Id3MetadataListener
—————————————————–
@SuppressWarnings("rawtypes")
@Override
public void onId3Metadata(Map<String, Object> metadata)
{
try
{
for (Object o : metadata.entrySet())
{
Map.Entry pairs = (Map.Entry) o;
if (metadata.containsKey(TxxxMetadata.TYPE))
{
TxxxMetadata txxxMetadata = (TxxxMetadata) metadata
.get(TxxxMetadata.TYPE);
}
else
{
String aStr = new String((byte[]) pairs.getValue());
MainActivity.mAppSdk.sendID3(aStr);
}
}
}
catch (Exception e)
{
e.printStackTrace();
Log.d(TAG, "onId3Metadata(): No Id3 tags");
}
}</syntaxhighlight>

[[File:andr-exo-retrievingID3tags.png|link=]]

==== Brightcove Player ====
While the Brightcove player plays the content, EventListener triggers an event when an ID3 packet is received (<code>SeamlessVideoDisplayComponent.ID3_TAG</code>). Upon receiving this event, collect the incoming ID3 tags and only pass the Nielsen payload of the PRIV frame to the App SDK for analysis.

<syntaxhighlight lang="java">brightcoveVideoView.getEventEmitter().on(SeamlessVideoDisplayComponent.ID3_TAG, new EventListener()
{
public void processEvent(Event event)
{
NlsId3Tag nlsID3 = new NlsId3Tag(event.properties.get(SeamlessVideoDisplayComponent.ID3_DATA).toString());
Log.w("ID3", nlsID3.NlsPayload);
// Sent ID3 Tags to App
appProcessID3tag(nlsID3.NlsPayload);
}
});
}</syntaxhighlight>

==== Adobe PrimeTime Player ====
While the Adobe PrimeTime player plays the content, MediaPlayer.PlaybackEventListener triggers a callback when an ID3 packet is received (onTimedMetadata). Upon receiving this event, collect the incoming ID3 tags and only pass the Nielsen payload of the PRIV frame to the App SDK for analysis.
<syntaxhighlight lang="java">public void onTimedMetadata(TimedMetadata id3Metadata)
{
NlsId3Tag nlsID3 = new NlsId3Tag(id3Metadata.getMetadata().toString());
Log.w(LOG_TAG, "ID3 Timed Data –> " + nlsID3.NlsPayload);
Log.w(LOG_TAG, "PayLoad Size –> " + nlsID3.NlsPayload.length());
appProcessID3tag(nlsID3.NlsPayload);
}</syntaxhighlight>

==== VisualOn Player ====
While the VisualOn player plays the content, <code>VOCommonPlayerListener</code> triggers an event when an ID3 packet is received (<code>VO_OSMP_SRC_CUSTOMERTAGID_TIMEDTAG</code>). Upon receiving this event, collect the incoming ID3 tags and only pass the Nielsen payload of the PRIV frame to the App SDK for analysis.

<syntaxhighlight lang="java">case VO_OSMP_SRC_CB_CUSTOMER_TAG:
{
VO_OSMP_SRC_CUSTOMERTAGID tag = VO_OSMP_SRC_CUSTOMERTAGID.valueOf(nParam1);
switch (tag)
{
case VO_OSMP_SRC_CUSTOMERTAGID_TIMEDTAG:
// do something with this tag
int time = nParam2;
byte[] b = (byte[]) obj;
String s = new String(b);
NlsId3Tag nlsID3 = new NlsId3Tag(b);
// Sent ID3 Tags to App
appProcessID3tag(nlsID3.NlsPayload);
if (appid3If != null)
appid3If.onId3(nlsID3.NlsPayload);
break;
case VO_OSMP_SRC_CUSTOMERTAGID_MAX:
// ignore this type of tag
break;
default:
break;
}
break;
}</syntaxhighlight>

==== NextStream Player ====
ID3 tags will be received in the NexStream Player through <code>onTimedMetaRenderRender(NexPlayer mp,NexID3TagInformation metadata)</code> callback API. A sample implementation for the callback is shown below:
<syntaxhighlight lang="java">public void onTimedMetaRenderRender(NexPlayer mp, NexID3TagInformation m)
{
text = m.getPrivateFrame();
if (text != null)
{
data = text.getTextData();
if (data != null)
{
// make sure to identify the beginning of the
// Nielsen ID3 tag payload by searching for the
// "www.nielsen.com" string on the ID3 tag and
// passing to the App SDK all information that
// follows. It should be:
// nlsPayload = "www.nielsen.com" + dataFollowing
nlsPayload = getDataAfterWwwNielsenCom(data);
if (nlsPayload!= NULL)
mAppSdk.sendID3(nlsPayload);
}
}
}</syntaxhighlight>

The [[sendID3()]] sends the extracted Nielsen ID3 payload to the App SDK for analysis.

== Android SDK API Methods & Properties ==
{| class="wikitable sortable"
|-
! Scenario !! Method / Property !! DTVR !! DAR !! Digital Audio !! DCR !! International (Germany) !! Description
|-
| Initialize || [[AppSDK()]] || ✔ || ✔ || ✔ || ✔ || ✔ || 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 when there is a preroll ad that needs to be associated with content metadata. The loadmetadata will first be called to populate the content metadata values and then the loadMetadata for ad metadata will be called. This allows sending a content ping with the ad info, even if the user bails out during the preroll ad.
|-
| Measurement || [[sendID3()]] || ✔ || ✘ || ✘ || ✘ || ✘ || Used to send the ID3 metadata.
|-
| Measurement || [[setPlayheadPosition()]] || ✘ || ✘ || ✔ || ✔ || ✔ || 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 || [[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 || [[userOptOutURLString()]] || ✔ || ✔ || ✔ || ✔ || ✔ || 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 || [[getOptOutStatus()]] || ✘ || ✘ || ✘ || ✘ || ✔ || Call this API to retrieve the Opt-Out or Opt-In state.
|-
| Opt-out
| [[appDisableApi()]]
(kill switch)
|| ✔ || ✔ || ✔ || ✔ || ✔ || Used to disable the SDK.
|-
| Opt-out || [[getAppDisable()]] || ✔ || ✔ || ✔ || ✔ || ✔ || Used to query if the SDK is disabled or not.
|-
| Log || [[getLastEvent()]] || ✔ || ✔ || ✔ || ✔ || ✔ || Used to query the SDK for the last status
|-
| Log || [[getLastError()]] || ✔ || ✔ || ✔ || ✔ || ✔ || Used to query the SDK for the last error
|-
| Log || [[isValid()]] || ✔ || ✔ || ✔ || ✔ || ✔ || Used to check if the SDK was successfully instantiated or not.
|-
| Log || [[getMeterVersion()]] || ✘ || ✘ || ✘ || ✘ || ✔ || Returns the current SDK version.
|-
| Log || [[getNielsenId()]] || ✔ || ✔ || ✔ || ✔ || ✔ || Used to get a string defining the Nielsen ID (NUID) number for the device.
|-
| Log || [[getDeviceId()]] || ✔ || ✔ || ✔ || ✔ || ✔ || Returns the current device id.
|-
| Log || [[appInBackground()]] || ✘ || ✘ || ✘ || ✔ || ✔ || Used to capture the event of app going to background.
|-
| Log || [[appInForeground()]] || ✘ || ✘ || ✘ || ✔ || ✔ || Used to capture the event of app coming to foreground
|-
| Log || [[setDebug()]] || ✘ || ✘ || ✘ || ✘ || ✔ || Used to enable/disable debug flags. Newly introduced in SDK version 5.0.0 for International (Germany)
|}

== 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.
*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.

=== Displaying Opt-Out in a WebView ===
<syntaxhighlight lang="java">
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
}
</syntaxhighlight>

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.

[[File:Privacy policy iOS.jpg|link=]]

<blockquote>'''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.</blockquote>

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

=== Sequence Diagram ===
[[File:optoutsequence-andr.jpg|link=]]

== Opt-out Android SDK Version '''5.1.1.18 or above''' ==
<blockquote>'''Note:''' If using Android SDK Versions 1.2.3, 4.0.0.8, 5.1.0, 5.1.1.14, skip ahead to: [[#Opt-out Android SDK Version 1.2.3, 4.0.0.8, 5.1.0, 5.1.1.14|Opt-out Android SDK Version 1.2.3, 4.0.0.8, 5.1.0, 5.1.1.14]]</blockquote>

Starting from SDK version 5.1.1.18, Opt-Out related behavior has been changed in the following ways:
*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'''.
<blockquote>'''Note:''' For Amazon devices, see [[#Opt-Out Implementation for Amazon Devices|Opt-Out Implementation for Amazon Devices]] below.</blockquote>

[[File:andr-ads.jpg|link=]]

<blockquote>'''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.</blockquote>

== Opt-out Android SDK Version '''1.2.3, 4.0.0.8, 5.1.0, 5.1.1.14''' ==
<blockquote>'''Note:''' If using Android SDK Version 5.1.1.18 or above, refer to documentation above ([[#Opt-out Android SDK Version 5.1.1.18 or above|Opt-out Android SDK Version 5.1.1.18 or above]])</blockquote>

When a user clicks the Opt-Out / Opt-In link, the application should invoke [[optOutURL]] to get the link to the Nielsen Privacy page from SDK.
=== Privacy Page ===
[[File:privacy-policy.jpg|link=]]
*There are two click here links – one for Opt-Out and one for Opt-In. Click the required link:
**Capture user’s selection
**Pass the selection back to the SDK via the [[userOptOut()]].

=== Capture and forward user selection ===
<syntaxhighlight lang="java">
private class MonitorWebView extends WebViewClient
{
private static final String NIELSEN_URL_OPT_OUT = “nielsenappsdk://1”;
private static final String NIELSEN_URL_OPT_IN = “nielsenappsdk://0”;

@Override
public boolean shouldOverrideUrlLoading(WebView view, String url)
{
if (NIELSEN_URL_OPT_OUT.equals(url)
|| NIELSEN_URL_OPT_IN.equals(url))
{
// Get AppSdk instance from the host
AppSdk appSdk = HostApp.getAppSdk();
// Send the URL to the AppSdk instance
appSdk.userOptOut(url);
return true;
}
return false;
}
}
</syntaxhighlight>

<blockquote>'''Note:''' When 'WebView' is closed, pass the status returned from 'WebView' to the SDK within the app.</blockquote>
<blockquote>'''Note:''' App SDK manages the user's choice (Opt-Out / Opt-In), the app does not need to manage this status.</blockquote>

== 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 ===

<syntaxhighlight lang="java">
ContentResolver cr = getContentResolver();
int limitAdTracking = Secure.getInt(cr, "limit_ad_tracking", 2);
</syntaxhighlight>

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

<blockquote>'''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'''.</blockquote>

== Nielsen Sample Applications ==

== Nielsen Privacy Requirements ==
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.
[[File:RatingsDataFlow.png]]

'''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 ===
{| class="wikitable"
|-
! Type of Information !! Parameter !! Transmitted to Nielsen? !! Sent to Provider?
|-
| rowspan="8" | 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
|-
| rowspan="10" | 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
|-
| rowspan="9" | 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
|}
<blockquote>'''Note''': Data is hashed, and encrypted using AES 128 before transmission to data provider.</blockquote>

==== Example ping sent to provider ====
* <code><nowiki>https://provider.com/cgi-bin/brandlift.php</nowiki>?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</code>

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

== Event and Error Handling ==
=== App SDK Error Codes ===
Constants with predefined error codes which the AppSdk object can generate.
<syntaxhighlight lang="java">public static final int ERROR_FAILED_CREATE_URL_STRING = 1001;
// failed generating ping string due to error on parsing
// description – include last error message from URL parser
public static final int ERROR_FAILED_RECEIVE_CONFIG = 1002;
// failed to receive configuration file from Census
// description – on 5th time, it will log event and keep requesting config 10 min apart
public static final int ERROR_FAILED_PARSING_CONFIG = 1003;
// failed parsing the config file JSON string
// description – include json error number/short message from iOS or Android
public static final int ERROR_FAILED_PARSING_PLAY = 1004;
// failed parsing the play() JSON string
// description – include json error number/short message from iOS or Android
public static final int ERROR_FAILED_PARSING_METADATA = 1005;
// failed parsing the play() JSON string
// description – include JSON error number/short message from iOS or Android
public static final int ERROR_FAILED_GENERATING_PING = 1006;
// failed creating ping before adding it to the UPLOAD table)
// description – include ping nol_url index, cadence to identify ping
public static final int ERROR_FAILED_PROCESSOR_START = 1007;
// failed starting data processor thread. Normally, that means a product
// description – include processor that failed to start
public static final int ERROR_FAILED_PROCESS_ID3 = 1008;
// failed processing data on a data processor. Normally, that means the input to a product
// description – include processor and data that failed to process (ID3 tag on a MTVR impression, for example)
public static final int ERROR_FAILED_HTTP_SEND = 1009;
// failed sending HTTP or HTTPS requests
// description – include HTTP error number
public static final int ERROR_FAILED_SENDING_PING = 1010;
// failed sending pings (on ANDROID, the ping on the UPLOAD table)
// description – include ping up to 80 char from the end
public static final int ERROR_FAILED_SENDING_TSV = 1011;
// failed sending TSV requests
// description – include TSV request message
public static final int ERROR_FAILED_SENDING_STATION_ID = 1012;
// failed sending StationId requests
// description – include Station ID request message
public static final int ERROR_FAILED_ACCESSING_DB = 1013;
// failed read/write from/to database table
// description – include SQL statement and data and SQLite error number/message
public static final int ERROR_CHANGED_DEVICE_ID = 1014;
// device ID changed
// description – none
public static final int ERROR_CHANGED_NUID = 1015;
// NUID changed
// description – none
public static final int ERROR_SDK_NOT_INITIALIZED = 1016;
// App SDK initialization failed
// description – none
public static final int ERROR_FAILED_SDK_SUSPEND = 1017;
// App SDK failed to suspend activities
// description – none
public static final int ERROR_INVALID_PARAMETERS = 1018;
// App SDK invalid parameters
// description – none
public static final int ERROR_INVALID_STATE = 1019;
// App SDK called in incorrect state
// description – none
public static final int ERROR_FAILED_PROCESS_PLAYHEAD = 1020;
// App SDK failed processing playhead position
// description – none
public static final int ERROR_FAILED_PROCESS_METADATA = 1021;
// App SDK failed processing not-null, syntax valid JSON metadada
// description – none
public static final int ERROR_FAILED_PROCESS_STOP = 1022;
// App SDK failed processing stop
// description – none</syntaxhighlight>

=== App SDK Event Codes ===
<syntaxhighlight lang="java">public static final int EVENT_INITIATE = 2000;
// App SDK is initiated. It will happen as soon as the App SDK is initialized
public static final int EVENT_STARTUP = 2001;
// App SDK has started up. It will happen only after App SDK has received a valid config file. This is the location in the code to acquire the value of userOptOutURLString().
public static final int EVENT_SHUTDOWN = 2002;
// App SDK is shutting down. It will happen just before App SDK is destroyed</syntaxhighlight>

'''App SDK Event Codes '''
{| class="wikitable"
|-
! Event Code !! Event Name !! Event Description
|-
| 2000 || EVENT_INITIATE || App SDK is initiated. It will happen as soon as the App SDK is initialized
|-
| 2001 || EVENT_STARTUP || App SDK has started up. It will happen only after App SDK has received a valid config file
|-
| 2002 || EVENT_SHUTDOWN || App SDK is shutting down. It will happen just before App SDK is destroyed
|}

iOS SDK API Reference

2017-07-12T19:41:44Z

Admin2: /* Opt-Out Implementation */

{{Breadcrumb|}} {{Breadcrumb|Digital}} {{CurrentBreadcrumb}}
[[Category:Digital]]
The iOS 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. These SDKs leverage the following:
*Nielsen audio watermark technologies for TV audience measurement
*The industry supported ID3 metadata tag specification
*Nielsen Combined Beacon technology
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
*Application crash events
*Time of viewing a sub section / page in the application.

== Importing Frameworks ==
'''Setting up your Xcode Development Environment'''

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

SDK uses the NSURLSession available from iOS 7 instead of the deprecated NSURLConnection.

<blockquote>'''Note''': App SDK supports devices running on iOS 9 and above, as all communications between the SDK and the Census (Collection Facility) use HTTPS.</blockquote>

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 (Not applicable for International (Germany))
* 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

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

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

== Initialization ==
The latest version of App SDK allows instantiating multiple instances of App SDK object and can be used simultaneously without any issues (The sharedInstance API that creates a singleton object in previous versions of App SDK is removed).
*Maximum of four SDK instances per appid are supported in this release. When a fifth SDK instance is launched,
**SDK will return “nil” from [[initWithAppInfo:delegate:]]
**Destroy one or more old SDK instances before creating new ones.

=== Stages of SDK Initialization ===
==== Step 1: App SDK Initialization ====
Initialize the Nielsen App object within the viewDidLoad view controller delegate method using initWithAppInfo:delegate:
<blockquote>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.</blockquote>

==== Step 2: Setting up event and error notifications ====
Once the <code>NielsenAppApi</code> object has been initialized, the next step is to enable notifications regarding ID3 tags extracted from the playing stream. In case of standard AVFoundation player, the SDK NSNotificationCenter API is used to
* Collect HLS timed metadata events (ID3 tags) during viewing sessions.
** Set up a timed metadata event listener method for receiving ID3 tags and calling Nielsen [[sendID3]].
* SDK uses the following NielsenAppApiDelegate protocol methods to notify its delegate (set during initialization) about event / error information.
** nielsenAppApi:eventOccurred
** nielsenAppApi:errorOccurred
<blockquote>'''Note''': Ensure to add to your view controller’s <code>@interface</code>.</blockquote>

<syntaxhighlight lang="objective-c">(void)nielsenAppApi:(NielsenAppApi *)appApi eventOccurred:(NSDictionary *)event {NSLog(@"Sample player is Notified by a Event : %@", event);
}
(void)nielsenAppApi:(NielsenAppApi *)appApi errorOccurred:(NSDictionary *)error {NSLog(@"Sample player is Notified by an Error : %@", error);
}</syntaxhighlight>

===== Sample event confirmation to player application upon successful initialization of SDK =====
<syntaxhighlight lang="console">NielsenSDKSampleDebug[9028:237989] [Nls:0] -I- Analytics framework Status:
{
"Event Description" = "Nielsen App SDK Version, ai.4.0.0.4 is initialized by the Player…";
EventStatus = 2001;
TimeStamp = "2015-07-23 14:51:06 +0000";
}</syntaxhighlight>

==== Step 3: Nielsen App SDK Streaming Sessions ====
After setting up observers for SDK events/errors and a listener method to process incoming Nielsen ID3 tags, the next steps are to
* Call [[play]] while starting or resuming a streaming session.
* Load CMS metadata using [[loadMetadata]].
* During session play, call [[playheadPosition]] every one second until the stream is stopped or interrupted (due to ad breaks or buffering).
* Call [[stop]] when pausing, ending a viewing session, or buffering is detected.

'''Serialized JSON string from NSDictionary'''
<syntaxhighlight lang="objective-c">NSDictionary* appInformation = @
{
@"appid": @"TXXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX",
@"appname": @"Sample App Name",
@"appversion": @"2.0",
@"sfcode": @"uat-cert",
@"nol_devDebug": @"INFO"
}
NSData* jsonDataAppInfo = [NSJSONSerialization dataWithJSONObject:appInformation options:0 error:nil];
NSString *jsonAppInfoString = [[NSString alloc] initWithData:jsonDataAppInfo encoding:NSUTF8StringEncoding];
nlsAppApiMeter = [[NielsenAppApi alloc] initWithAppInfo:jsonAppInfoString delegate:self];</syntaxhighlight>

Nielsen App SDK object handles filtering of ID3 tags and CMS tags, queuing/buffering of data, and all communications with Nielsen collection facility.

===== Nielsen iOS App SDK Application Life Cycle =====

[[File:initialization_appcycle.png|center|link=]]

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 '''Initial state'''.
# '''Idle state''' – The SDK is initialized and is ready to process playing information. Call <code>[[initWithAppInfo:delegate:]]</code> to move into this state. The SDK instance is not processing any data, but is listening for the play event to occur.
# '''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.
## [[playheadPosition]] – Call this API every one second when playhead position timer is fired.
## [[sendID3]] – Call this API when ID3 tags are identified in the stream.
## [[stop]] – Call this API when the playback is paused, switches between content and ad (within the same content playback) or encounters interruptions.
## [[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. SDK instance moves into this state in one of the following scenarios.
## Initialization fails
## [[appDisableApi]] is called
<blockquote>'''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 [[sendID3]] / [[playheadPosition]].</blockquote>

=== 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.
{| class="wikitable"
|-
! API call received !! Initial State !! Idle State !! Processing State !! Disabled State
|-
| <code>[[initWithAppInfo:delegate:]]</code> || IDLE STATE (OR)

DISABLED STATE
|| IDLE STATE || - || -
|-
| <code>[[play]]</code> & <code>[[loadMetadata]]</code>|| - || PROCESSING

STATE
|| - || -
|-
| <code>[[playheadPosition]]</code> || - || - || PROCESSING

STATE
|| -
|-
| <code>[[sendID3]]</code> || - || - || PROCESSING

STATE
|| -
|-
| <code>[[stop]]</code> || - || - || IDLE STATE || -
|-
| <code>[[end]]</code> || - || - || IDLE STATE || -
|-
| <code>[[appDisableApi]]</code>: YES || - || DISABLED

STATE
|| - || -
|-
| <code>[[appDisableApi]]</code>: NO || - || - || - || IDLE STATE (OR)

DISABLED STATE
|-
| <code>[[userOptOut]]</code>: YES || - || - || IDLE STATE || -
|-
| <code>[[userOptOut]]</code>: NO || - || PROCESSING

STATE
| -
| -
|-
| colspan = 5 | '-' 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.

==== JSON for NSDictionary object ====
<syntaxhighlight lang="objective-c">
NSDictionary* appInformation = @{
@"appid": @"TXXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX",
@"appname": @"Sample App Name",
@"appversion": @"2.0",
@"sfcode": @"uat-cert",
@"nol_devDebug": @"INFO"
};
nlsAppApiMeter = [[NielsenAppApi alloc] initWithAppInfo:appInformation delegate:delegate];</syntaxhighlight>

<code>appid</code>, <code>appname</code>, and <code>appversion</code> are mandatory parameters while <code>sfcode</code> is optional. <code>nol_devDebug</code> is meant for creating logs in test environments only.

==== JSON string from raw NSString ====
<syntaxhighlight lang="swift">NSString *appInfoString = @"{\"appid\" : \"TXXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX\", \"appname\" : \"Sample App Name\",\"appversion\" : \"2.0\",\"sfcode\" : \"uat-cert\"}";
NielsenAppAPi *appAPI = [[NielsenAppApi alloc] initWithAppInfo:appInfoString delegate:self];</syntaxhighlight>

==== JSON string from serialized NSDictionary ====
<syntaxhighlight lang="objective-c">NSDictionary* appInformation = @
{
@"appid": @"appid",
@"appname": @"appname",
@"appversion": @"2.0",
@"sfcode": @"sfcode",
@"nol_devDebug": @"INFO"
};
nlsAppApiMeter = [[NielsenAppApi alloc] initWithAppInfo:appInformation delegate:self];</syntaxhighlight>

While using JSON format for sending metadat, ensure enough care in including [[special characters]] in the values for arguments.

==== Example ====
<syntaxhighlight lang="objective-c">{
@"type": @"radio", // To send "radio" in metadata string
@"assetid": @"WXYZ-FM'101",
@"stationType": @"3",
@"provider": @"SampleProvider" // To send "SampleProvider" in metadata string
}</syntaxhighlight>
<blockquote>'''Note''': For mandatory parameters like appid, appname, and appversion, please refer to the parameters table in <code>[[initWithAppInfo:delegate:]]</code></blockquote>

== Retrieving ID3 Tags ==
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.

=== Sample ID3 tags ===
* <code>www.nielsen.com/X100zdCIGeIlgZnkYj6UvQ==/X100zdCIGeIlgZnkYj6UvQ==/AAAB2Jz2_k74GXSzx4npHuI_JwJd3QSUpW30rDkGTcbHEzIMWleCzM-uvNOP9fzJcQMWQLJqzXMCAxParOb5sGijSV9dNM3QiBniJYGZ5GI-lL1fXTTN0IgZ4iWBmeRiPpS9AAAAAAAAAAAAAAAAAAAAAFJWFM5SVhTONNU=/00000/00000/00</code>
* <code>www.nielsen.com/X100zdCIGeIlgZnkYj6UvQ==/R8WHe7pEBeqBhu8jTeXydg==/AAICoyitYqlxT7n6aZ0oMCGheFi4CXFp46AMUPZz1lMr_M9tr3_cjee1SHqxrOiVerMDLeyn9xzocZSKwi746Re8vNOtpNCAZjYABs_J0R25IHpvOc1HS8QHGgD5TgOJeS6gX100zdCIGeIlgZnkYj6UvVJWFNhSVhTiPE0=/00000/46016/00</code>

=== Examples of extracting ID3 tags from the iOS Native Player ===
==== AVPlayer ====
ID3 tags will be received in the Player on AVMetadataItem Callback method.
'''Create & get the AVMetadataItem callback method'''
<syntaxhighlight lang="swift">[self.player addObserver:self
forKeyPath: kTimedMetadataKey
options: NSKeyValueObservingOptionNew
Context: MyStreamingMovieViewControllerTimedMetadataObserverContext];</syntaxhighlight>

<syntaxhighlight lang="objective-c">
– (void)observeValueForKeyPath:(NSString*) path
ofObject: (id)object
change: (NSDictionary*)change
context: (void*)context
{
/* Set the AVPlayerLayer on the view to allow the AVPlayer object to display
its content. */
//[playerLayerView.playerLayer setPlayer:player];
/* AVPlayerItem "status" property value observer. */
if (context == MyStreamingMovieViewControllerTimedMetadataObserverContext)
{
id newMetadataArray = [change objectForKey:NSKeyValueChangeNewKey];
if (newMetadataArray != [NSNull null])
{
array = newMetadataArray;
for (AVMetadataItem *metadataItem in array)
{
[self handleTimedMetadata: metadataItem];
}
}
}
</syntaxhighlight>

<syntaxhighlight lang="objective-c">
– (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;
}
if ([(NSString *)[timedMetadata key] isEqualToString:@"PRIV"]&&[extraString rangeOfString:@"www.nielsen.com"].length> 0)
{
if ([[timedMetadata value] isKindOfClass:[NSData class]])
{
// Sending ID3 Tag
/* The sendID3: sends the extracted Nielsen ID3 payload to the App SDK for analysis. */
[[NielsenAppApi sharedInstance]sendID3: extraString];
NSString *value=[timedMetadata stringValue];
if (value != nil)
{
// NSString *strMessage=[[@"ID3 Tag Received " stringByAppendingFormat:@"%d\n",countForMetadata] stringByAppendingString:value];
[self appendLogConsoleText:extraString];
}
}
}
else
{
NSLog(@"Could not send ID3 tags");
}
countForMetadata++;

}
</syntaxhighlight>

==== Movie Player ====
ID3 tags will be received in the Player on MPTimedMetadata Callback method.
'''Sample Implementation of MPTimedMetadata callback'''
<syntaxhighlight lang="objective-c">
– (void)handleTimedMetadata:(MPTimedMetadata*)timedMetadata
{
id extraAttributeType = [timedMetadata allMetadata];
NSString * extraString= nil;
if ([extraAttributeType isKindOfClass:[NSDictionary class]])
{
extraString = [extraAttributeType valueForKey:@"info"];
}
else if([extraAttributeType isKindOfClass:[NSString class]])
{
extraString = extraAttributeType;
}

if ([(NSString *)[timedMetadata key] isEqualToString:@"PRIV"]&&[extraString rangeOfString:@"www.nielsen.com"].length> 0)
{
if ([[timedMetadata value] isKindOfClass:[NSData class]])
{
// Sending ID3 Tag
[[NielsenAppApi sharedInstance]sendID3: extraString];
NSString *value=[timedMetadata value];
if (value != nil)
{

[self appendLogConsoleText:extraString];
}
}
}
else
{
NSLog(@"Could not send ID3 tags");
}
countForMetadata++;
}
</syntaxhighlight>
<blockquote>'''Note:''' ID3 tags are not applicable for International (Germany)</blockquote>

== IOS SDK API Methods & Properties ==
{| class="wikitable sortable"
|-
! Scenario !! Method / Property !! DTVR !! DAR !! Digital Audio !! 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 || [[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.
|-
| 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)
|}

== 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 to this web page should be called from SDK by invoking [[optOutURL]] and opened in 'WebView' / External browser.
*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 [[optOutStatus]] method.

=== Displaying Opt-Out in a WebView ===
<syntaxhighlight lang="objective-c">NielsenAppApi nAppApiObject;
@property(strong) UIWebView *optOutView;

// create WebView and set self as delegate
self.optOutView=[[UIWebViewalloc]initWithFrame:self.view.bounds];

self.optOutView.scalesPageToFit = yes;
// get Nielsen defined web address and load the page
NSString *webAddress = [nAppApiObject optOutURLString];

if(webAddress == nil)
{ // Handle it gracefully and retry later}
else
{
[optOutView loadRequest:[NSURLRequest requestWithURL:webAddress]];
// show the view to the user
[self.view addSubview:optOutView];
}</syntaxhighlight>

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.

[[File:Privacy policy iOS.jpg|link=]]

*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.
<syntaxhighlight lang="objective-c">
@property (readonly) BOOL optOutStatus;
</syntaxhighlight>
*App should provide a UI control like 'close' or 'back' button to close the 'WebView' / External browser.

=== Sequence Diagram ===
[[File:optoutsequence-ios.jpg|link=]]

== Opt-out SDK Version '''5.1.1.17 or above''' ==
<blockquote>'''Note:''' If using SDK Versions 1.2.3, 4.0.0.8, 5.1.0, 5.1.1.12, skip ahead to: [[#Opt-out SDK Version 1.2.3, 4.0.0.8, 5.1.0, 5.1.1.12|Opt-out SDK Version 1.2.3, 4.0.0.8, 5.1.0, 5.1.1.12]]</blockquote>

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.

[[File:Opt-Out iOS.jpg|link=]]

<blockquote>'''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.</blockquote>

== Opt-out SDK Version '''1.2.3, 4.0.0.8, 5.1.0, 5.1.1.12''' ==
<blockquote>'''Note:''' If using SDK Version 5.1.1.17 or above, refer to documentation above ([[#Opt-out SDK Version 5.1.1.17 or above|Opt-out SDK Version 5.1.1.17 or above]])</blockquote>

When a user clicks the Opt-Out / Opt-In link, the application should invoke [[optOutURL]] to get the link to the Nielsen Privacy page from SDK.
=== Privacy Page ===
[[File:privacy-policy.jpg|link=]]
*There are two click here links – one for Opt-Out and one for Opt-In. Click the required link:
**
[[File:Opt-Out Combined.jpg|link=]]
*Click OK in the dialog that appears, to confirm the action.
*The Opt-Out occurs by opening a Nielsen-defined web page and passing the user choice from the 'WebView'. In order to do this, the application needs to
**Implement the UIWebView delegate method to open the Nielsen Privacy web page
**Capture user's selection
**Pass the selection back to the SDK via the [[userOptOut]].

=== Capture and forward user selection ===
<syntaxhighlight lang="objective-c">-(BOOL)webView:(UIWebView *)webView shouldStartLoadWithRequest:(NSURLRequest *)request navigationType:(UIWebViewNavigationType)navigationType
{
NSString *command = [NSString stringWithFormat:@”%@”,request.URL];
if ([command isEqualToString:kNielsenWebClose]) {
// Close the WebView
[self performSelector:@selector(closeOptOutView) withObject:nil afterDelay:0];
return NO;
}
// Retrieve next URL if it’s not opt-in/out selection
return (![nAppApiObject userOptOut:command]);
}</syntaxhighlight>

*The app gets the user selection string via webviews shouldStartLoadWithRequest and invokes [[userOptOut]] with user selection. The delegate method handles the 'WebView' URL requests, interprets the commands, and calls the SDK accordingly.
**<code>[nAppApiObject userOptOut:command]</code> passes the user's selection on Nielsen Privacy page to the SDK to allow the SDK to perform the required functions.
<blockquote>'''Note:''' When 'WebView' is closed, pass the status returned from 'WebView' to the SDK within the app.</blockquote>
<blockquote>'''Note:''' App SDK manages the user's choice (Opt-Out / Opt-In), the app does not need to manage this status.</blockquote>

== 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:

[[File:TVOs OptOut LimitAdTracking1.png|link=]]

[[File:TVOs OptOut LimitAdTracking2.png|link=]]

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.

<blockquote>'''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.</blockquote>

== 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:
<syntaxhighlight lang="objective-c">
@interface NielsenAppApi: NSObject

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

– (instancetype)initWithAppInfo:(id)appInfo delegate:(id)delegate;

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

– (NSString *)getNielsenId _attribute((deprecated((“Please use nielsenId property instead.”))));
– (NSString *)optOutURLString _attribute((deprecated((“Please use optOutURL property instead.”))));
– (NSString *)getMeterVersion _attribute((deprecated((“Please use meterVersion property instead.”))));
– (NSDictionary *)getLastEventDict _attribute((deprecated((“Please use lastEventDict property instead.”))));
– (NSDictionary *)getLastErrorDict _attribute((deprecated((“Please use lastErrorDict property instead.”))));

@protocol NielsenAppApiDelegate<NSObject>

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

@end
</syntaxhighlight>

== Nielsen Sample Applications ==
Nielsen iOS sample player application consists of two sample application based on native Players integrated with SDK framework. The player demonstrates all the supported functions of the SDK.
*NielsenVideoPlayer
*NielsenRadioPlayer
Implementation of Video and Audio 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 two locations:
**Channels 1 and 2 are configured from the Settings application. Channel URLs and metadata parameters can be modified.
**Channels starting from 3 are configured in specific JSON file. URLs to this JSON config file can be changed from the Settings application.

== Nielsen Privacy Requirements ==
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.
[[File:RatingsDataFlow.png]]

'''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 ===
{| class="wikitable"
|-
! Type of Information !! Parameter !! Transmitted to Nielsen? !! Sent to Provider?
|-
| rowspan="8" | 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
|-
| rowspan="10" | 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
|-
| rowspan="9" | 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
|}
<blockquote>'''Note''': Data is hashed, and encrypted using AES 128 before transmission to data provider.</blockquote>

==== Example ping sent to provider ====
* <code><nowiki>https://provider.com/cgi-bin/brandlift.php</nowiki>?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</code>

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

=== Nielsen Measurement Opt-Out ===
In accordance with Nielsen’s SDK licensing agreement, developers are required to provide basic informational data to users about Nielsen’s Privacy Policy with a navigation to additional information on Nielsen measurement.

Nielsen currently uses Limit Ad Tracking for the latest versions of the SDK (5.1.1.17 and above). However, for older SDK versions, the app must provide a means for the user to opt out, or opt back in to Nielsen Measurement. Users can opt out of Nielsen online measurement research through this feature.
* If the user has this app running on more than one mobile device, the user will need to opt out of this measurement on each device.
<blockquote>'''Note''': Opt Out feature does NOT rely on "Limit Ad Tracking" setting since Nielsen’s systems provide measurement metrics and do not serve ads to users.</blockquote>

In the Description of the app in App Store, include a short description about Nielsen measurement, as below.

<blockquote>'''Sample App Store Disclosure'''
This app features Nielsen proprietary measurement software which will allow you to contribute to market research, like Nielsen’s TV Ratings.

To learn more about our digital measurement products and your choices in regard to them, please visit http://www.nielsen.com/digitalprivacy for more information.

[[File:measurement-samplescreen.jpg]]</blockquote>

Both iOS-based and TVOS-based player applications need to confirm to Nielsen Privacy Requirements. Refer to the Opt-Out implementation guidelines for iOS and TVOS platforms respectively for more details.

== AppApiEventCode ==
An enumeration with predefined App SDK event state transition codes.
<syntaxhighlight lang="objective-c">
typedef NS_ENUM(unsigned int, AppApiEventCode)
{
AppApiStartup = 2001,
AppApiShutdown = 2002,
}AppApiEventCode;
</syntaxhighlight>

== App SDK Event Codes ==
{| class="wikitable"
|-
! 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 ==
An enumeration with predefined error codes which the App SDK object can generate.
<syntaxhighlight lang="objective-c">
typedef NS_ENUM(unsigned int, AppApiErrorCode)
{
AppApiNetworkConnectionFailure = 1001,
AppApiFileWriteFailure = 1002,
AppApiFileReadFailure = 1003,
AppApiEmptyValue = 1004,
AppApiEmptyAppName = 1005,
AppApiEmptyAppVersion = 1006,
AppApiEmptyAppId = 1007,
AppApiAnExceptionOccured = 1008,
AppApiUnknownExceptionOccured = 1009
};
</syntaxhighlight>

== App SDK Error Codes ==
{| class="wikitable"
|-
! Event Code !! Event Name !! Event 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
|}

iOS SDK API Reference

2017-07-12T19:40:07Z

Admin2: /* Displaying Opt-Out in a WebView */

{{Breadcrumb|}} {{Breadcrumb|Digital}} {{CurrentBreadcrumb}}
[[Category:Digital]]
The iOS 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. These SDKs leverage the following:
*Nielsen audio watermark technologies for TV audience measurement
*The industry supported ID3 metadata tag specification
*Nielsen Combined Beacon technology
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
*Application crash events
*Time of viewing a sub section / page in the application.

== Importing Frameworks ==
'''Setting up your Xcode Development Environment'''

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

SDK uses the NSURLSession available from iOS 7 instead of the deprecated NSURLConnection.

<blockquote>'''Note''': App SDK supports devices running on iOS 9 and above, as all communications between the SDK and the Census (Collection Facility) use HTTPS.</blockquote>

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 (Not applicable for International (Germany))
* 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

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

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

== Initialization ==
The latest version of App SDK allows instantiating multiple instances of App SDK object and can be used simultaneously without any issues (The sharedInstance API that creates a singleton object in previous versions of App SDK is removed).
*Maximum of four SDK instances per appid are supported in this release. When a fifth SDK instance is launched,
**SDK will return “nil” from [[initWithAppInfo:delegate:]]
**Destroy one or more old SDK instances before creating new ones.

=== Stages of SDK Initialization ===
==== Step 1: App SDK Initialization ====
Initialize the Nielsen App object within the viewDidLoad view controller delegate method using initWithAppInfo:delegate:
<blockquote>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.</blockquote>

==== Step 2: Setting up event and error notifications ====
Once the <code>NielsenAppApi</code> object has been initialized, the next step is to enable notifications regarding ID3 tags extracted from the playing stream. In case of standard AVFoundation player, the SDK NSNotificationCenter API is used to
* Collect HLS timed metadata events (ID3 tags) during viewing sessions.
** Set up a timed metadata event listener method for receiving ID3 tags and calling Nielsen [[sendID3]].
* SDK uses the following NielsenAppApiDelegate protocol methods to notify its delegate (set during initialization) about event / error information.
** nielsenAppApi:eventOccurred
** nielsenAppApi:errorOccurred
<blockquote>'''Note''': Ensure to add to your view controller’s <code>@interface</code>.</blockquote>

<syntaxhighlight lang="objective-c">(void)nielsenAppApi:(NielsenAppApi *)appApi eventOccurred:(NSDictionary *)event {NSLog(@"Sample player is Notified by a Event : %@", event);
}
(void)nielsenAppApi:(NielsenAppApi *)appApi errorOccurred:(NSDictionary *)error {NSLog(@"Sample player is Notified by an Error : %@", error);
}</syntaxhighlight>

===== Sample event confirmation to player application upon successful initialization of SDK =====
<syntaxhighlight lang="console">NielsenSDKSampleDebug[9028:237989] [Nls:0] -I- Analytics framework Status:
{
"Event Description" = "Nielsen App SDK Version, ai.4.0.0.4 is initialized by the Player…";
EventStatus = 2001;
TimeStamp = "2015-07-23 14:51:06 +0000";
}</syntaxhighlight>

==== Step 3: Nielsen App SDK Streaming Sessions ====
After setting up observers for SDK events/errors and a listener method to process incoming Nielsen ID3 tags, the next steps are to
* Call [[play]] while starting or resuming a streaming session.
* Load CMS metadata using [[loadMetadata]].
* During session play, call [[playheadPosition]] every one second until the stream is stopped or interrupted (due to ad breaks or buffering).
* Call [[stop]] when pausing, ending a viewing session, or buffering is detected.

'''Serialized JSON string from NSDictionary'''
<syntaxhighlight lang="objective-c">NSDictionary* appInformation = @
{
@"appid": @"TXXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX",
@"appname": @"Sample App Name",
@"appversion": @"2.0",
@"sfcode": @"uat-cert",
@"nol_devDebug": @"INFO"
}
NSData* jsonDataAppInfo = [NSJSONSerialization dataWithJSONObject:appInformation options:0 error:nil];
NSString *jsonAppInfoString = [[NSString alloc] initWithData:jsonDataAppInfo encoding:NSUTF8StringEncoding];
nlsAppApiMeter = [[NielsenAppApi alloc] initWithAppInfo:jsonAppInfoString delegate:self];</syntaxhighlight>

Nielsen App SDK object handles filtering of ID3 tags and CMS tags, queuing/buffering of data, and all communications with Nielsen collection facility.

===== Nielsen iOS App SDK Application Life Cycle =====

[[File:initialization_appcycle.png|center|link=]]

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 '''Initial state'''.
# '''Idle state''' – The SDK is initialized and is ready to process playing information. Call <code>[[initWithAppInfo:delegate:]]</code> to move into this state. The SDK instance is not processing any data, but is listening for the play event to occur.
# '''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.
## [[playheadPosition]] – Call this API every one second when playhead position timer is fired.
## [[sendID3]] – Call this API when ID3 tags are identified in the stream.
## [[stop]] – Call this API when the playback is paused, switches between content and ad (within the same content playback) or encounters interruptions.
## [[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. SDK instance moves into this state in one of the following scenarios.
## Initialization fails
## [[appDisableApi]] is called
<blockquote>'''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 [[sendID3]] / [[playheadPosition]].</blockquote>

=== 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.
{| class="wikitable"
|-
! API call received !! Initial State !! Idle State !! Processing State !! Disabled State
|-
| <code>[[initWithAppInfo:delegate:]]</code> || IDLE STATE (OR)

DISABLED STATE
|| IDLE STATE || - || -
|-
| <code>[[play]]</code> & <code>[[loadMetadata]]</code>|| - || PROCESSING

STATE
|| - || -
|-
| <code>[[playheadPosition]]</code> || - || - || PROCESSING

STATE
|| -
|-
| <code>[[sendID3]]</code> || - || - || PROCESSING

STATE
|| -
|-
| <code>[[stop]]</code> || - || - || IDLE STATE || -
|-
| <code>[[end]]</code> || - || - || IDLE STATE || -
|-
| <code>[[appDisableApi]]</code>: YES || - || DISABLED

STATE
|| - || -
|-
| <code>[[appDisableApi]]</code>: NO || - || - || - || IDLE STATE (OR)

DISABLED STATE
|-
| <code>[[userOptOut]]</code>: YES || - || - || IDLE STATE || -
|-
| <code>[[userOptOut]]</code>: NO || - || PROCESSING

STATE
| -
| -
|-
| colspan = 5 | '-' 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.

==== JSON for NSDictionary object ====
<syntaxhighlight lang="objective-c">
NSDictionary* appInformation = @{
@"appid": @"TXXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX",
@"appname": @"Sample App Name",
@"appversion": @"2.0",
@"sfcode": @"uat-cert",
@"nol_devDebug": @"INFO"
};
nlsAppApiMeter = [[NielsenAppApi alloc] initWithAppInfo:appInformation delegate:delegate];</syntaxhighlight>

<code>appid</code>, <code>appname</code>, and <code>appversion</code> are mandatory parameters while <code>sfcode</code> is optional. <code>nol_devDebug</code> is meant for creating logs in test environments only.

==== JSON string from raw NSString ====
<syntaxhighlight lang="swift">NSString *appInfoString = @"{\"appid\" : \"TXXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX\", \"appname\" : \"Sample App Name\",\"appversion\" : \"2.0\",\"sfcode\" : \"uat-cert\"}";
NielsenAppAPi *appAPI = [[NielsenAppApi alloc] initWithAppInfo:appInfoString delegate:self];</syntaxhighlight>

==== JSON string from serialized NSDictionary ====
<syntaxhighlight lang="objective-c">NSDictionary* appInformation = @
{
@"appid": @"appid",
@"appname": @"appname",
@"appversion": @"2.0",
@"sfcode": @"sfcode",
@"nol_devDebug": @"INFO"
};
nlsAppApiMeter = [[NielsenAppApi alloc] initWithAppInfo:appInformation delegate:self];</syntaxhighlight>

While using JSON format for sending metadat, ensure enough care in including [[special characters]] in the values for arguments.

==== Example ====
<syntaxhighlight lang="objective-c">{
@"type": @"radio", // To send "radio" in metadata string
@"assetid": @"WXYZ-FM'101",
@"stationType": @"3",
@"provider": @"SampleProvider" // To send "SampleProvider" in metadata string
}</syntaxhighlight>
<blockquote>'''Note''': For mandatory parameters like appid, appname, and appversion, please refer to the parameters table in <code>[[initWithAppInfo:delegate:]]</code></blockquote>

== Retrieving ID3 Tags ==
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.

=== Sample ID3 tags ===
* <code>www.nielsen.com/X100zdCIGeIlgZnkYj6UvQ==/X100zdCIGeIlgZnkYj6UvQ==/AAAB2Jz2_k74GXSzx4npHuI_JwJd3QSUpW30rDkGTcbHEzIMWleCzM-uvNOP9fzJcQMWQLJqzXMCAxParOb5sGijSV9dNM3QiBniJYGZ5GI-lL1fXTTN0IgZ4iWBmeRiPpS9AAAAAAAAAAAAAAAAAAAAAFJWFM5SVhTONNU=/00000/00000/00</code>
* <code>www.nielsen.com/X100zdCIGeIlgZnkYj6UvQ==/R8WHe7pEBeqBhu8jTeXydg==/AAICoyitYqlxT7n6aZ0oMCGheFi4CXFp46AMUPZz1lMr_M9tr3_cjee1SHqxrOiVerMDLeyn9xzocZSKwi746Re8vNOtpNCAZjYABs_J0R25IHpvOc1HS8QHGgD5TgOJeS6gX100zdCIGeIlgZnkYj6UvVJWFNhSVhTiPE0=/00000/46016/00</code>

=== Examples of extracting ID3 tags from the iOS Native Player ===
==== AVPlayer ====
ID3 tags will be received in the Player on AVMetadataItem Callback method.
'''Create & get the AVMetadataItem callback method'''
<syntaxhighlight lang="swift">[self.player addObserver:self
forKeyPath: kTimedMetadataKey
options: NSKeyValueObservingOptionNew
Context: MyStreamingMovieViewControllerTimedMetadataObserverContext];</syntaxhighlight>

<syntaxhighlight lang="objective-c">
– (void)observeValueForKeyPath:(NSString*) path
ofObject: (id)object
change: (NSDictionary*)change
context: (void*)context
{
/* Set the AVPlayerLayer on the view to allow the AVPlayer object to display
its content. */
//[playerLayerView.playerLayer setPlayer:player];
/* AVPlayerItem "status" property value observer. */
if (context == MyStreamingMovieViewControllerTimedMetadataObserverContext)
{
id newMetadataArray = [change objectForKey:NSKeyValueChangeNewKey];
if (newMetadataArray != [NSNull null])
{
array = newMetadataArray;
for (AVMetadataItem *metadataItem in array)
{
[self handleTimedMetadata: metadataItem];
}
}
}
</syntaxhighlight>

<syntaxhighlight lang="objective-c">
– (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;
}
if ([(NSString *)[timedMetadata key] isEqualToString:@"PRIV"]&&[extraString rangeOfString:@"www.nielsen.com"].length> 0)
{
if ([[timedMetadata value] isKindOfClass:[NSData class]])
{
// Sending ID3 Tag
/* The sendID3: sends the extracted Nielsen ID3 payload to the App SDK for analysis. */
[[NielsenAppApi sharedInstance]sendID3: extraString];
NSString *value=[timedMetadata stringValue];
if (value != nil)
{
// NSString *strMessage=[[@"ID3 Tag Received " stringByAppendingFormat:@"%d\n",countForMetadata] stringByAppendingString:value];
[self appendLogConsoleText:extraString];
}
}
}
else
{
NSLog(@"Could not send ID3 tags");
}
countForMetadata++;

}
</syntaxhighlight>

==== Movie Player ====
ID3 tags will be received in the Player on MPTimedMetadata Callback method.
'''Sample Implementation of MPTimedMetadata callback'''
<syntaxhighlight lang="objective-c">
– (void)handleTimedMetadata:(MPTimedMetadata*)timedMetadata
{
id extraAttributeType = [timedMetadata allMetadata];
NSString * extraString= nil;
if ([extraAttributeType isKindOfClass:[NSDictionary class]])
{
extraString = [extraAttributeType valueForKey:@"info"];
}
else if([extraAttributeType isKindOfClass:[NSString class]])
{
extraString = extraAttributeType;
}

if ([(NSString *)[timedMetadata key] isEqualToString:@"PRIV"]&&[extraString rangeOfString:@"www.nielsen.com"].length> 0)
{
if ([[timedMetadata value] isKindOfClass:[NSData class]])
{
// Sending ID3 Tag
[[NielsenAppApi sharedInstance]sendID3: extraString];
NSString *value=[timedMetadata value];
if (value != nil)
{

[self appendLogConsoleText:extraString];
}
}
}
else
{
NSLog(@"Could not send ID3 tags");
}
countForMetadata++;
}
</syntaxhighlight>
<blockquote>'''Note:''' ID3 tags are not applicable for International (Germany)</blockquote>

== IOS SDK API Methods & Properties ==
{| class="wikitable sortable"
|-
! Scenario !! Method / Property !! DTVR !! DAR !! Digital Audio !! 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 || [[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.
|-
| 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)
|}

== 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 to this web page should be called from SDK by invoking [[optOutURL]] and opened in 'WebView' / External browser.
*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 [[optOutStatus]] method.

=== Displaying Opt-Out in a WebView ===
<syntaxhighlight lang="objective-c">NielsenAppApi nAppApiObject;
@property(strong) UIWebView *optOutView;

// create WebView and set self as delegate
self.optOutView=[[UIWebViewalloc]initWithFrame:self.view.bounds];

self.optOutView.scalesPageToFit = yes;
// get Nielsen defined web address and load the page
NSString *webAddress = [nAppApiObject optOutURLString];

if(webAddress == nil)
{ // Handle it gracefully and retry later}
else
{
[optOutView loadRequest:[NSURLRequest requestWithURL:webAddress]];
// show the view to the user
[self.view addSubview:optOutView];
}</syntaxhighlight>

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.

[[File:Privacy policy iOS.jpg|link=]]

*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.
<syntaxhighlight lang="objective-c">
@property (readonly) BOOL optOutStatus;
</syntaxhighlight>
*App should provide a UI control like 'close' or 'back' button to close the 'WebView' / External browser.

=== Sequence Diagram ===
[[File:optoutsequence-ios.jpg|link=]]

== Opt-out SDK Version '''5.1.1.17 or above''' ==
<blockquote>'''Note:''' If using SDK Versions 1.2.3, 4.0.0.8, 5.1.0, 5.1.1.12, skip ahead to: [[#Opt-out SDK Version 1.2.3, 4.0.0.8, 5.1.0, 5.1.1.12|Opt-out SDK Version 1.2.3, 4.0.0.8, 5.1.0, 5.1.1.12]]</blockquote>

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.

[[File:Opt-Out iOS.jpg|link=]]

<blockquote>'''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.</blockquote>

== Opt-out SDK Version '''1.2.3, 4.0.0.8, 5.1.0, 5.1.1.12''' ==
<blockquote>'''Note:''' If using SDK Version 5.1.1.17 or above, refer to documentation above ([[#Opt-out SDK Version 5.1.1.17 or above|Opt-out SDK Version 5.1.1.17 or above]])</blockquote>

When a user clicks the Opt-Out / Opt-In link, the application should invoke [[optOutURL]] to get the link to the Nielsen Privacy page from SDK.
=== Privacy Page ===
[[File:privacy-policy.jpg|link=]]
*There are two click here links – one for Opt-Out and one for Opt-In. Click the required link:
**
[[File:Opt-Out Combined.jpg|link=]]
*Click OK in the dialog that appears, to confirm the action.
*The Opt-Out occurs by opening a Nielsen-defined web page and passing the user choice from the 'WebView'. In order to do this, the application needs to
**Implement the UIWebView delegate method to open the Nielsen Privacy web page
**Capture user's selection
**Pass the selection back to the SDK via the [[userOptOut]].

=== Capture and forward user selection ===
<syntaxhighlight lang="objective-c">-(BOOL)webView:(UIWebView *)webView shouldStartLoadWithRequest:(NSURLRequest *)request navigationType:(UIWebViewNavigationType)navigationType
{
NSString *command = [NSString stringWithFormat:@”%@”,request.URL];
if ([command isEqualToString:kNielsenWebClose]) {
// Close the WebView
[self performSelector:@selector(closeOptOutView) withObject:nil afterDelay:0];
return NO;
}
// Retrieve next URL if it’s not opt-in/out selection
return (![nAppApiObject userOptOut:command]);
}</syntaxhighlight>

*The app gets the user selection string via webviews shouldStartLoadWithRequest and invokes [[userOptOut]] with user selection. The delegate method handles the 'WebView' URL requests, interprets the commands, and calls the SDK accordingly.
**<code>[nAppApiObject userOptOut:command]</code> passes the user's selection on Nielsen Privacy page to the SDK to allow the SDK to perform the required functions.
<blockquote>'''Note:''' When 'WebView' is closed, pass the status returned from 'WebView' to the SDK within the app.</blockquote>
<blockquote>'''Note:''' App SDK manages the user's choice (Opt-Out / Opt-In), the app does not need to manage this status.</blockquote>

== 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:

[[File:TVOs OptOut LimitAdTracking1.png|link=]]

[[File:TVOs OptOut LimitAdTracking2.png|link=]]

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.

<blockquote>'''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.</blockquote>

== 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:
<syntaxhighlight lang="objective-c">
@interface NielsenAppApi: NSObject

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

– (instancetype)initWithAppInfo:(id)appInfo delegate:(id)delegate;

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

– (NSString *)getNielsenId _attribute((deprecated((“Please use nielsenId property instead.”))));
– (NSString *)optOutURLString _attribute((deprecated((“Please use optOutURL property instead.”))));
– (NSString *)getMeterVersion _attribute((deprecated((“Please use meterVersion property instead.”))));
– (NSDictionary *)getLastEventDict _attribute((deprecated((“Please use lastEventDict property instead.”))));
– (NSDictionary *)getLastErrorDict _attribute((deprecated((“Please use lastErrorDict property instead.”))));

@protocol NielsenAppApiDelegate<NSObject>

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

@end
</syntaxhighlight>

== Nielsen Sample Applications ==
Nielsen iOS sample player application consists of two sample application based on native Players integrated with SDK framework. The player demonstrates all the supported functions of the SDK.
*NielsenVideoPlayer
*NielsenRadioPlayer
Implementation of Video and Audio 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 two locations:
**Channels 1 and 2 are configured from the Settings application. Channel URLs and metadata parameters can be modified.
**Channels starting from 3 are configured in specific JSON file. URLs to this JSON config file can be changed from the Settings application.

== Nielsen Privacy Requirements ==
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.
[[File:RatingsDataFlow.png]]

'''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 ===
{| class="wikitable"
|-
! Type of Information !! Parameter !! Transmitted to Nielsen? !! Sent to Provider?
|-
| rowspan="8" | 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
|-
| rowspan="10" | 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
|-
| rowspan="9" | 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
|}
<blockquote>'''Note''': Data is hashed, and encrypted using AES 128 before transmission to data provider.</blockquote>

==== Example ping sent to provider ====
* <code><nowiki>https://provider.com/cgi-bin/brandlift.php</nowiki>?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</code>

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

=== Nielsen Measurement Opt-Out ===
In accordance with Nielsen’s SDK licensing agreement, developers are required to provide basic informational data to users about Nielsen’s Privacy Policy with a navigation to additional information on Nielsen measurement.

Nielsen currently uses Limit Ad Tracking for the latest versions of the SDK (5.1.1.17 and above). However, for older SDK versions, the app must provide a means for the user to opt out, or opt back in to Nielsen Measurement. Users can opt out of Nielsen online measurement research through this feature.
* If the user has this app running on more than one mobile device, the user will need to opt out of this measurement on each device.
<blockquote>'''Note''': Opt Out feature does NOT rely on "Limit Ad Tracking" setting since Nielsen’s systems provide measurement metrics and do not serve ads to users.</blockquote>

In the Description of the app in App Store, include a short description about Nielsen measurement, as below.

<blockquote>'''Sample App Store Disclosure'''
This app features Nielsen proprietary measurement software which will allow you to contribute to market research, like Nielsen’s TV Ratings.

To learn more about our digital measurement products and your choices in regard to them, please visit http://www.nielsen.com/digitalprivacy for more information.

[[File:measurement-samplescreen.jpg]]</blockquote>

Both iOS-based and TVOS-based player applications need to confirm to Nielsen Privacy Requirements. Refer to the Opt-Out implementation guidelines for iOS and TVOS platforms respectively for more details.

=== Opt-Out Implementation ===
==== Limit Ad Tracking ====
'''This implementation is valid for SDK Versions 5.1.1.17 and above.'''

<blockquote>'''Note''': If using SDK Version 1.2.3, 4.0.0.8, 5.1.0 or 5.1.1.12, refer to [[#Legacy_Opt-Out|Legacy Opt-Out Implementation for iOS]].</blockquote>

As a global information and measurement leader, Nielsen is committed to protect the privacy and security of the data they collect, process and use. Nielsen strongly believes that the consumer should have a way to opt out of Nielsen measurement.

The Nielsen digital measurement products help Nielsen and its clients to measure and analyze how consumers engage with media across online, mobile and emerging technologies while offering insights into consumer behavior.

To learn more about our digital measurement products and your choices in regard to them, please visit http://www.nielsen.com/digitalprivacy.

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 optOutURL and opened in ‘WebView’ / External browser.
* 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 optOutStatus method.
'''Displaying Opt-Out in a WebView'''
<syntaxhighlight lang="objective-c">NielsenAppApi nAppApiObject;
@property(strong) UIWebView *optOutView;
// create WebView and set self as delegate
self.optOutView=[[UIWebView alloc]initWithFrame:self.view.bounds];
self.optOutView.scalesPageToFit = yes;
// get Nielsen defined web address and load the page
NSString *webAddress = [nAppApiObject optOutURLString];
If(webAddress == nil)
{
// Handle it gracefully and retry later
}

else
{
[optOutView loadRequest:[NSURLRequest requestWithURL:webAddress]];
// show the view to the user
[self.view addSubview:optOutView];
}</syntaxhighlight>

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.

[[File:Opt-Out_iOS.jpg]]
<blockquote>'''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.</blockquote>

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.

[[File: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.
<syntaxhighlight lang="objective-c">@property (readonly) BOOL optOutStatus;</blockquote>
* App should provide a UI control like ‘close’ or ‘back’ button to close the ‘WebView’ / External browser.

'''Sequence Diagram'''
[[File:optoutsequence-ios.jpg]]

== Event and Error Handling ==
=== Constants / Enumerations ===
The following are the details of Delegate Implementation:

<syntaxhighlight lang="objective-c">
-(void)nielsenAppApi:(NielsenAppApi *)appApi eventOccurred:(NSDictionary *)event
{
NSLog(@"Sample player is Notified by a Event: %@", event);
}
– (void)nielsenAppApi:(NielsenAppApi *)appApi errorOccurred:(NSDictionary *)error
{
NSLog(@"Sample player is Notified by an Error: %@", error);
}
</syntaxhighlight>

==== TVOS Implementation ====
As a global information and measurement leader, Nielsen is committed to protect the privacy and security of the data they collect, process and use. Nielsen strongly believes that the client should have a way to Opt-Out of Nielsen measurement.

The Nielsen digital measurement products are not used to identify consumer in any way. They help Nielsen and its clients to measure and analyze how consumers engage with media across online, mobile and emerging technologies while offering insights into consumer behavior.

To learn more about our digital measurement products and your choices in regard to them, please visit http://www.nielsen.com/digitalprivacy.

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.

[[File:TVOs_OptOut_LimitAdTracking1.png]]

[[File:TVOs_OptOut_LimitAdTracking2.png]]

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.

<blockquote>'''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.</blockquote>

==== Legacy Opt-Out ====
'''Supported SDK Versions''': 1.2.3, 4.0.0.8, 5.1.0, 5.1.1.12.

<blockquote>'''Note''': If using SDK Version 5.1.1.17 or above, refer to [[#Limit Ad Tracking|Limit Ad Tracking iOS Implementation]].</blockquote>

As a global information and measurement leader, Nielsen is committed to protect the privacy and security of the data they collect, process and use. Nielsen strongly believes that the consumer should have a way to Opt-Out of Nielsen measurement.

The Nielsen digital measurement products help Nielsen and its clients to measure and analyze how consumers engage with media across online, mobile and emerging technologies while offering insights into consumer behavior.

To learn more about our digital measurement products and your choices in regard to them, please visit http://www.nielsen.com/digitalprivacy.

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 [[optOutURL]] and opened in ‘WebView’ within the app and NOT in any external browser.
** Opening the Opt-Out page in any external browser takes the application control out of the Nielsen App SDK context.
** As the App SDK does not expose any direct http/https interface to interact with the world to get the user selection on Privacy page, there will be no way to interact/send notification to the App SDK regarding the user selection.
* 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 [[optOutStatus]] method.
<blockquote>'''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.</blockquote>

'''Sequence Diagram'''
[[File:optoutsequence-ios.jpg]]

Below are the steps to implement user Opt-Out using UIWebView.

When a user clicks the Opt-Out / Opt-In link, the application should invoke [[optOutURL]] to get the link to the Nielsen Privacy page from SDK.

'''Implement WebView with Nielsen Opt-Out URL'''
<syntaxhighlight lang="objective-c">NielsenAppApi nAppApiObject;
@property(strong) UIWebView *optOutView;

// create WebView and set self as delegate
self.optOutView=[[UIWebViewalloc]initWithFrame:self.view.bounds];

self.optOutView.scalesPageToFit = yes;
// get Nielsen defined web address and load the page
NSString *webAddress = [nAppApiObject optOutURLString];

if(webAddress == nil)
{ // Handle it gracefully and retry later}
else
{
[optOutView loadRequest:[NSURLRequest requestWithURL:webAddress]];
// show the view to the user
[self.view addSubview:optOutView];
}</syntaxhighlight>

* The Nielsen Privacy Page appears using UIWebView

'''Privacy Page'''

[[File:privacy-policy.jpg]]

* There are two links – one for Opt-Out and one for Opt-In. Click the required link.
* Click OK in the dialog that appears, to confirm the action.
* The Opt-Out occurs by opening a Nielsen-defined web page and passing the user choice from the ‘WebView’. In order to do this, the application needs to
** Implement the UIWebView delegate method to open the Nielsen Privacy web page
** Capture user’s selection
** Pass the selection back to the SDK via the [[userOptOut]].

'''Capture and forward user selection'''
<syntaxhighlight lang="objective-c">-(BOOL)webView:(UIWebView *)webView shouldStartLoadWithRequest:(NSURLRequest *)request navigationType:(UIWebViewNavigationType)navigationType
{
NSString *command = [NSString stringWithFormat:@”%@”,request.URL];
if ([command isEqualToString:kNielsenWebClose]) {
// Close the WebView
[self performSelector:@selector(closeOptOutView) withObject:nil afterDelay:0];
return NO;
}
// Retrieve next URL if it’s not opt-in/out selection
return (![nAppApiObject userOptOut:command]);
}</syntaxhighlight>
* The app gets the user selection string via webviews shouldStartLoadWithRequest and invokes [[userOptOut]] with user selection. The delegate method handles the ‘WebView’ URL requests, interprets the commands, and calls the SDK accordingly.
* <code>[nAppApiObject userOptOut:command]</code> passes the user’s selection on Nielsen Privacy page to the SDK to allow the SDK to perform the required functions.
<blockquote>'''Note''': When ‘WebView’ is closed, pass the status returned from ‘WebView’ to the SDK within the app.</blockquote>

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

== AppApiEventCode ==
An enumeration with predefined App SDK event state transition codes.
<syntaxhighlight lang="objective-c">
typedef NS_ENUM(unsigned int, AppApiEventCode)
{
AppApiStartup = 2001,
AppApiShutdown = 2002,
}AppApiEventCode;
</syntaxhighlight>

== App SDK Event Codes ==
{| class="wikitable"
|-
! 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 ==
An enumeration with predefined error codes which the App SDK object can generate.
<syntaxhighlight lang="objective-c">
typedef NS_ENUM(unsigned int, AppApiErrorCode)
{
AppApiNetworkConnectionFailure = 1001,
AppApiFileWriteFailure = 1002,
AppApiFileReadFailure = 1003,
AppApiEmptyValue = 1004,
AppApiEmptyAppName = 1005,
AppApiEmptyAppVersion = 1006,
AppApiEmptyAppId = 1007,
AppApiAnExceptionOccured = 1008,
AppApiUnknownExceptionOccured = 1009
};
</syntaxhighlight>

== App SDK Error Codes ==
{| class="wikitable"
|-
! Event Code !! Event Name !! Event 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
|}

iOS SDK API Reference

2017-07-12T19:39:20Z

Admin2: /* Capture and forward user selection */

{{Breadcrumb|}} {{Breadcrumb|Digital}} {{CurrentBreadcrumb}}
[[Category:Digital]]
The iOS 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. These SDKs leverage the following:
*Nielsen audio watermark technologies for TV audience measurement
*The industry supported ID3 metadata tag specification
*Nielsen Combined Beacon technology
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
*Application crash events
*Time of viewing a sub section / page in the application.

== Importing Frameworks ==
'''Setting up your Xcode Development Environment'''

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

SDK uses the NSURLSession available from iOS 7 instead of the deprecated NSURLConnection.

<blockquote>'''Note''': App SDK supports devices running on iOS 9 and above, as all communications between the SDK and the Census (Collection Facility) use HTTPS.</blockquote>

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 (Not applicable for International (Germany))
* 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

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

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

== Initialization ==
The latest version of App SDK allows instantiating multiple instances of App SDK object and can be used simultaneously without any issues (The sharedInstance API that creates a singleton object in previous versions of App SDK is removed).
*Maximum of four SDK instances per appid are supported in this release. When a fifth SDK instance is launched,
**SDK will return “nil” from [[initWithAppInfo:delegate:]]
**Destroy one or more old SDK instances before creating new ones.

=== Stages of SDK Initialization ===
==== Step 1: App SDK Initialization ====
Initialize the Nielsen App object within the viewDidLoad view controller delegate method using initWithAppInfo:delegate:
<blockquote>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.</blockquote>

==== Step 2: Setting up event and error notifications ====
Once the <code>NielsenAppApi</code> object has been initialized, the next step is to enable notifications regarding ID3 tags extracted from the playing stream. In case of standard AVFoundation player, the SDK NSNotificationCenter API is used to
* Collect HLS timed metadata events (ID3 tags) during viewing sessions.
** Set up a timed metadata event listener method for receiving ID3 tags and calling Nielsen [[sendID3]].
* SDK uses the following NielsenAppApiDelegate protocol methods to notify its delegate (set during initialization) about event / error information.
** nielsenAppApi:eventOccurred
** nielsenAppApi:errorOccurred
<blockquote>'''Note''': Ensure to add to your view controller’s <code>@interface</code>.</blockquote>

<syntaxhighlight lang="objective-c">(void)nielsenAppApi:(NielsenAppApi *)appApi eventOccurred:(NSDictionary *)event {NSLog(@"Sample player is Notified by a Event : %@", event);
}
(void)nielsenAppApi:(NielsenAppApi *)appApi errorOccurred:(NSDictionary *)error {NSLog(@"Sample player is Notified by an Error : %@", error);
}</syntaxhighlight>

===== Sample event confirmation to player application upon successful initialization of SDK =====
<syntaxhighlight lang="console">NielsenSDKSampleDebug[9028:237989] [Nls:0] -I- Analytics framework Status:
{
"Event Description" = "Nielsen App SDK Version, ai.4.0.0.4 is initialized by the Player…";
EventStatus = 2001;
TimeStamp = "2015-07-23 14:51:06 +0000";
}</syntaxhighlight>

==== Step 3: Nielsen App SDK Streaming Sessions ====
After setting up observers for SDK events/errors and a listener method to process incoming Nielsen ID3 tags, the next steps are to
* Call [[play]] while starting or resuming a streaming session.
* Load CMS metadata using [[loadMetadata]].
* During session play, call [[playheadPosition]] every one second until the stream is stopped or interrupted (due to ad breaks or buffering).
* Call [[stop]] when pausing, ending a viewing session, or buffering is detected.

'''Serialized JSON string from NSDictionary'''
<syntaxhighlight lang="objective-c">NSDictionary* appInformation = @
{
@"appid": @"TXXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX",
@"appname": @"Sample App Name",
@"appversion": @"2.0",
@"sfcode": @"uat-cert",
@"nol_devDebug": @"INFO"
}
NSData* jsonDataAppInfo = [NSJSONSerialization dataWithJSONObject:appInformation options:0 error:nil];
NSString *jsonAppInfoString = [[NSString alloc] initWithData:jsonDataAppInfo encoding:NSUTF8StringEncoding];
nlsAppApiMeter = [[NielsenAppApi alloc] initWithAppInfo:jsonAppInfoString delegate:self];</syntaxhighlight>

Nielsen App SDK object handles filtering of ID3 tags and CMS tags, queuing/buffering of data, and all communications with Nielsen collection facility.

===== Nielsen iOS App SDK Application Life Cycle =====

[[File:initialization_appcycle.png|center|link=]]

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 '''Initial state'''.
# '''Idle state''' – The SDK is initialized and is ready to process playing information. Call <code>[[initWithAppInfo:delegate:]]</code> to move into this state. The SDK instance is not processing any data, but is listening for the play event to occur.
# '''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.
## [[playheadPosition]] – Call this API every one second when playhead position timer is fired.
## [[sendID3]] – Call this API when ID3 tags are identified in the stream.
## [[stop]] – Call this API when the playback is paused, switches between content and ad (within the same content playback) or encounters interruptions.
## [[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. SDK instance moves into this state in one of the following scenarios.
## Initialization fails
## [[appDisableApi]] is called
<blockquote>'''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 [[sendID3]] / [[playheadPosition]].</blockquote>

=== 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.
{| class="wikitable"
|-
! API call received !! Initial State !! Idle State !! Processing State !! Disabled State
|-
| <code>[[initWithAppInfo:delegate:]]</code> || IDLE STATE (OR)

DISABLED STATE
|| IDLE STATE || - || -
|-
| <code>[[play]]</code> & <code>[[loadMetadata]]</code>|| - || PROCESSING

STATE
|| - || -
|-
| <code>[[playheadPosition]]</code> || - || - || PROCESSING

STATE
|| -
|-
| <code>[[sendID3]]</code> || - || - || PROCESSING

STATE
|| -
|-
| <code>[[stop]]</code> || - || - || IDLE STATE || -
|-
| <code>[[end]]</code> || - || - || IDLE STATE || -
|-
| <code>[[appDisableApi]]</code>: YES || - || DISABLED

STATE
|| - || -
|-
| <code>[[appDisableApi]]</code>: NO || - || - || - || IDLE STATE (OR)

DISABLED STATE
|-
| <code>[[userOptOut]]</code>: YES || - || - || IDLE STATE || -
|-
| <code>[[userOptOut]]</code>: NO || - || PROCESSING

STATE
| -
| -
|-
| colspan = 5 | '-' 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.

==== JSON for NSDictionary object ====
<syntaxhighlight lang="objective-c">
NSDictionary* appInformation = @{
@"appid": @"TXXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX",
@"appname": @"Sample App Name",
@"appversion": @"2.0",
@"sfcode": @"uat-cert",
@"nol_devDebug": @"INFO"
};
nlsAppApiMeter = [[NielsenAppApi alloc] initWithAppInfo:appInformation delegate:delegate];</syntaxhighlight>

<code>appid</code>, <code>appname</code>, and <code>appversion</code> are mandatory parameters while <code>sfcode</code> is optional. <code>nol_devDebug</code> is meant for creating logs in test environments only.

==== JSON string from raw NSString ====
<syntaxhighlight lang="swift">NSString *appInfoString = @"{\"appid\" : \"TXXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX\", \"appname\" : \"Sample App Name\",\"appversion\" : \"2.0\",\"sfcode\" : \"uat-cert\"}";
NielsenAppAPi *appAPI = [[NielsenAppApi alloc] initWithAppInfo:appInfoString delegate:self];</syntaxhighlight>

==== JSON string from serialized NSDictionary ====
<syntaxhighlight lang="objective-c">NSDictionary* appInformation = @
{
@"appid": @"appid",
@"appname": @"appname",
@"appversion": @"2.0",
@"sfcode": @"sfcode",
@"nol_devDebug": @"INFO"
};
nlsAppApiMeter = [[NielsenAppApi alloc] initWithAppInfo:appInformation delegate:self];</syntaxhighlight>

While using JSON format for sending metadat, ensure enough care in including [[special characters]] in the values for arguments.

==== Example ====
<syntaxhighlight lang="objective-c">{
@"type": @"radio", // To send "radio" in metadata string
@"assetid": @"WXYZ-FM'101",
@"stationType": @"3",
@"provider": @"SampleProvider" // To send "SampleProvider" in metadata string
}</syntaxhighlight>
<blockquote>'''Note''': For mandatory parameters like appid, appname, and appversion, please refer to the parameters table in <code>[[initWithAppInfo:delegate:]]</code></blockquote>

== Retrieving ID3 Tags ==
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.

=== Sample ID3 tags ===
* <code>www.nielsen.com/X100zdCIGeIlgZnkYj6UvQ==/X100zdCIGeIlgZnkYj6UvQ==/AAAB2Jz2_k74GXSzx4npHuI_JwJd3QSUpW30rDkGTcbHEzIMWleCzM-uvNOP9fzJcQMWQLJqzXMCAxParOb5sGijSV9dNM3QiBniJYGZ5GI-lL1fXTTN0IgZ4iWBmeRiPpS9AAAAAAAAAAAAAAAAAAAAAFJWFM5SVhTONNU=/00000/00000/00</code>
* <code>www.nielsen.com/X100zdCIGeIlgZnkYj6UvQ==/R8WHe7pEBeqBhu8jTeXydg==/AAICoyitYqlxT7n6aZ0oMCGheFi4CXFp46AMUPZz1lMr_M9tr3_cjee1SHqxrOiVerMDLeyn9xzocZSKwi746Re8vNOtpNCAZjYABs_J0R25IHpvOc1HS8QHGgD5TgOJeS6gX100zdCIGeIlgZnkYj6UvVJWFNhSVhTiPE0=/00000/46016/00</code>

=== Examples of extracting ID3 tags from the iOS Native Player ===
==== AVPlayer ====
ID3 tags will be received in the Player on AVMetadataItem Callback method.
'''Create & get the AVMetadataItem callback method'''
<syntaxhighlight lang="swift">[self.player addObserver:self
forKeyPath: kTimedMetadataKey
options: NSKeyValueObservingOptionNew
Context: MyStreamingMovieViewControllerTimedMetadataObserverContext];</syntaxhighlight>

<syntaxhighlight lang="objective-c">
– (void)observeValueForKeyPath:(NSString*) path
ofObject: (id)object
change: (NSDictionary*)change
context: (void*)context
{
/* Set the AVPlayerLayer on the view to allow the AVPlayer object to display
its content. */
//[playerLayerView.playerLayer setPlayer:player];
/* AVPlayerItem "status" property value observer. */
if (context == MyStreamingMovieViewControllerTimedMetadataObserverContext)
{
id newMetadataArray = [change objectForKey:NSKeyValueChangeNewKey];
if (newMetadataArray != [NSNull null])
{
array = newMetadataArray;
for (AVMetadataItem *metadataItem in array)
{
[self handleTimedMetadata: metadataItem];
}
}
}
</syntaxhighlight>

<syntaxhighlight lang="objective-c">
– (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;
}
if ([(NSString *)[timedMetadata key] isEqualToString:@"PRIV"]&&[extraString rangeOfString:@"www.nielsen.com"].length> 0)
{
if ([[timedMetadata value] isKindOfClass:[NSData class]])
{
// Sending ID3 Tag
/* The sendID3: sends the extracted Nielsen ID3 payload to the App SDK for analysis. */
[[NielsenAppApi sharedInstance]sendID3: extraString];
NSString *value=[timedMetadata stringValue];
if (value != nil)
{
// NSString *strMessage=[[@"ID3 Tag Received " stringByAppendingFormat:@"%d\n",countForMetadata] stringByAppendingString:value];
[self appendLogConsoleText:extraString];
}
}
}
else
{
NSLog(@"Could not send ID3 tags");
}
countForMetadata++;

}
</syntaxhighlight>

==== Movie Player ====
ID3 tags will be received in the Player on MPTimedMetadata Callback method.
'''Sample Implementation of MPTimedMetadata callback'''
<syntaxhighlight lang="objective-c">
– (void)handleTimedMetadata:(MPTimedMetadata*)timedMetadata
{
id extraAttributeType = [timedMetadata allMetadata];
NSString * extraString= nil;
if ([extraAttributeType isKindOfClass:[NSDictionary class]])
{
extraString = [extraAttributeType valueForKey:@"info"];
}
else if([extraAttributeType isKindOfClass:[NSString class]])
{
extraString = extraAttributeType;
}

if ([(NSString *)[timedMetadata key] isEqualToString:@"PRIV"]&&[extraString rangeOfString:@"www.nielsen.com"].length> 0)
{
if ([[timedMetadata value] isKindOfClass:[NSData class]])
{
// Sending ID3 Tag
[[NielsenAppApi sharedInstance]sendID3: extraString];
NSString *value=[timedMetadata value];
if (value != nil)
{

[self appendLogConsoleText:extraString];
}
}
}
else
{
NSLog(@"Could not send ID3 tags");
}
countForMetadata++;
}
</syntaxhighlight>
<blockquote>'''Note:''' ID3 tags are not applicable for International (Germany)</blockquote>

== IOS SDK API Methods & Properties ==
{| class="wikitable sortable"
|-
! Scenario !! Method / Property !! DTVR !! DAR !! Digital Audio !! 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 || [[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.
|-
| 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)
|}

== 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 to this web page should be called from SDK by invoking [[optOutURL]] and opened in 'WebView' / External browser.
*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 [[optOutStatus]] method.

=== Displaying Opt-Out in a WebView ===
<syntaxhighlight lang="objective-c">
NielsenAppApi nAppApiObject;
@property(strong) UIWebView *optOutView;
// create WebView and set self as delegate
self.optOutView=[[UIWebView alloc]initWithFrame:self.view.bounds];
self.optOutView.scalesPageToFit = yes;
// get Nielsen defined web address and load the page
NSString *webAddress = [nAppApiObject optOutURLString];
If(webAddress == nil)
{ // Handle it gracefully and retry later} else
{[optOutView loadRequest:[NSURLRequest requestWithURL:webAddress]];
// show the view to the user
[self.view addSubview:optOutView]; }
</syntaxhighlight>

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.

[[File:Privacy policy iOS.jpg|link=]]

*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.
<syntaxhighlight lang="objective-c">
@property (readonly) BOOL optOutStatus;
</syntaxhighlight>
*App should provide a UI control like 'close' or 'back' button to close the 'WebView' / External browser.

=== Sequence Diagram ===
[[File:optoutsequence-ios.jpg|link=]]

== Opt-out SDK Version '''5.1.1.17 or above''' ==
<blockquote>'''Note:''' If using SDK Versions 1.2.3, 4.0.0.8, 5.1.0, 5.1.1.12, skip ahead to: [[#Opt-out SDK Version 1.2.3, 4.0.0.8, 5.1.0, 5.1.1.12|Opt-out SDK Version 1.2.3, 4.0.0.8, 5.1.0, 5.1.1.12]]</blockquote>

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.

[[File:Opt-Out iOS.jpg|link=]]

<blockquote>'''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.</blockquote>

== Opt-out SDK Version '''1.2.3, 4.0.0.8, 5.1.0, 5.1.1.12''' ==
<blockquote>'''Note:''' If using SDK Version 5.1.1.17 or above, refer to documentation above ([[#Opt-out SDK Version 5.1.1.17 or above|Opt-out SDK Version 5.1.1.17 or above]])</blockquote>

When a user clicks the Opt-Out / Opt-In link, the application should invoke [[optOutURL]] to get the link to the Nielsen Privacy page from SDK.
=== Privacy Page ===
[[File:privacy-policy.jpg|link=]]
*There are two click here links – one for Opt-Out and one for Opt-In. Click the required link:
**
[[File:Opt-Out Combined.jpg|link=]]
*Click OK in the dialog that appears, to confirm the action.
*The Opt-Out occurs by opening a Nielsen-defined web page and passing the user choice from the 'WebView'. In order to do this, the application needs to
**Implement the UIWebView delegate method to open the Nielsen Privacy web page
**Capture user's selection
**Pass the selection back to the SDK via the [[userOptOut]].

=== Capture and forward user selection ===
<syntaxhighlight lang="objective-c">-(BOOL)webView:(UIWebView *)webView shouldStartLoadWithRequest:(NSURLRequest *)request navigationType:(UIWebViewNavigationType)navigationType
{
NSString *command = [NSString stringWithFormat:@”%@”,request.URL];
if ([command isEqualToString:kNielsenWebClose]) {
// Close the WebView
[self performSelector:@selector(closeOptOutView) withObject:nil afterDelay:0];
return NO;
}
// Retrieve next URL if it’s not opt-in/out selection
return (![nAppApiObject userOptOut:command]);
}</syntaxhighlight>

*The app gets the user selection string via webviews shouldStartLoadWithRequest and invokes [[userOptOut]] with user selection. The delegate method handles the 'WebView' URL requests, interprets the commands, and calls the SDK accordingly.
**<code>[nAppApiObject userOptOut:command]</code> passes the user's selection on Nielsen Privacy page to the SDK to allow the SDK to perform the required functions.
<blockquote>'''Note:''' When 'WebView' is closed, pass the status returned from 'WebView' to the SDK within the app.</blockquote>
<blockquote>'''Note:''' App SDK manages the user's choice (Opt-Out / Opt-In), the app does not need to manage this status.</blockquote>

== 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:

[[File:TVOs OptOut LimitAdTracking1.png|link=]]

[[File:TVOs OptOut LimitAdTracking2.png|link=]]

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.

<blockquote>'''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.</blockquote>

== 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:
<syntaxhighlight lang="objective-c">
@interface NielsenAppApi: NSObject

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

– (instancetype)initWithAppInfo:(id)appInfo delegate:(id)delegate;

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

– (NSString *)getNielsenId _attribute((deprecated((“Please use nielsenId property instead.”))));
– (NSString *)optOutURLString _attribute((deprecated((“Please use optOutURL property instead.”))));
– (NSString *)getMeterVersion _attribute((deprecated((“Please use meterVersion property instead.”))));
– (NSDictionary *)getLastEventDict _attribute((deprecated((“Please use lastEventDict property instead.”))));
– (NSDictionary *)getLastErrorDict _attribute((deprecated((“Please use lastErrorDict property instead.”))));

@protocol NielsenAppApiDelegate<NSObject>

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

@end
</syntaxhighlight>

== Nielsen Sample Applications ==
Nielsen iOS sample player application consists of two sample application based on native Players integrated with SDK framework. The player demonstrates all the supported functions of the SDK.
*NielsenVideoPlayer
*NielsenRadioPlayer
Implementation of Video and Audio 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 two locations:
**Channels 1 and 2 are configured from the Settings application. Channel URLs and metadata parameters can be modified.
**Channels starting from 3 are configured in specific JSON file. URLs to this JSON config file can be changed from the Settings application.

== Nielsen Privacy Requirements ==
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.
[[File:RatingsDataFlow.png]]

'''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 ===
{| class="wikitable"
|-
! Type of Information !! Parameter !! Transmitted to Nielsen? !! Sent to Provider?
|-
| rowspan="8" | 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
|-
| rowspan="10" | 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
|-
| rowspan="9" | 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
|}
<blockquote>'''Note''': Data is hashed, and encrypted using AES 128 before transmission to data provider.</blockquote>

==== Example ping sent to provider ====
* <code><nowiki>https://provider.com/cgi-bin/brandlift.php</nowiki>?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</code>

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

=== Nielsen Measurement Opt-Out ===
In accordance with Nielsen’s SDK licensing agreement, developers are required to provide basic informational data to users about Nielsen’s Privacy Policy with a navigation to additional information on Nielsen measurement.

Nielsen currently uses Limit Ad Tracking for the latest versions of the SDK (5.1.1.17 and above). However, for older SDK versions, the app must provide a means for the user to opt out, or opt back in to Nielsen Measurement. Users can opt out of Nielsen online measurement research through this feature.
* If the user has this app running on more than one mobile device, the user will need to opt out of this measurement on each device.
<blockquote>'''Note''': Opt Out feature does NOT rely on "Limit Ad Tracking" setting since Nielsen’s systems provide measurement metrics and do not serve ads to users.</blockquote>

In the Description of the app in App Store, include a short description about Nielsen measurement, as below.

<blockquote>'''Sample App Store Disclosure'''
This app features Nielsen proprietary measurement software which will allow you to contribute to market research, like Nielsen’s TV Ratings.

To learn more about our digital measurement products and your choices in regard to them, please visit http://www.nielsen.com/digitalprivacy for more information.

[[File:measurement-samplescreen.jpg]]</blockquote>

Both iOS-based and TVOS-based player applications need to confirm to Nielsen Privacy Requirements. Refer to the Opt-Out implementation guidelines for iOS and TVOS platforms respectively for more details.

=== Opt-Out Implementation ===
==== Limit Ad Tracking ====
'''This implementation is valid for SDK Versions 5.1.1.17 and above.'''

<blockquote>'''Note''': If using SDK Version 1.2.3, 4.0.0.8, 5.1.0 or 5.1.1.12, refer to [[#Legacy_Opt-Out|Legacy Opt-Out Implementation for iOS]].</blockquote>

As a global information and measurement leader, Nielsen is committed to protect the privacy and security of the data they collect, process and use. Nielsen strongly believes that the consumer should have a way to opt out of Nielsen measurement.

The Nielsen digital measurement products help Nielsen and its clients to measure and analyze how consumers engage with media across online, mobile and emerging technologies while offering insights into consumer behavior.

To learn more about our digital measurement products and your choices in regard to them, please visit http://www.nielsen.com/digitalprivacy.

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 optOutURL and opened in ‘WebView’ / External browser.
* 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 optOutStatus method.
'''Displaying Opt-Out in a WebView'''
<syntaxhighlight lang="objective-c">NielsenAppApi nAppApiObject;
@property(strong) UIWebView *optOutView;
// create WebView and set self as delegate
self.optOutView=[[UIWebView alloc]initWithFrame:self.view.bounds];
self.optOutView.scalesPageToFit = yes;
// get Nielsen defined web address and load the page
NSString *webAddress = [nAppApiObject optOutURLString];
If(webAddress == nil)
{
// Handle it gracefully and retry later
}

else
{
[optOutView loadRequest:[NSURLRequest requestWithURL:webAddress]];
// show the view to the user
[self.view addSubview:optOutView];
}</syntaxhighlight>

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.

[[File:Opt-Out_iOS.jpg]]
<blockquote>'''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.</blockquote>

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.

[[File: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.
<syntaxhighlight lang="objective-c">@property (readonly) BOOL optOutStatus;</blockquote>
* App should provide a UI control like ‘close’ or ‘back’ button to close the ‘WebView’ / External browser.

'''Sequence Diagram'''
[[File:optoutsequence-ios.jpg]]

== Event and Error Handling ==
=== Constants / Enumerations ===
The following are the details of Delegate Implementation:

<syntaxhighlight lang="objective-c">
-(void)nielsenAppApi:(NielsenAppApi *)appApi eventOccurred:(NSDictionary *)event
{
NSLog(@"Sample player is Notified by a Event: %@", event);
}
– (void)nielsenAppApi:(NielsenAppApi *)appApi errorOccurred:(NSDictionary *)error
{
NSLog(@"Sample player is Notified by an Error: %@", error);
}
</syntaxhighlight>

==== TVOS Implementation ====
As a global information and measurement leader, Nielsen is committed to protect the privacy and security of the data they collect, process and use. Nielsen strongly believes that the client should have a way to Opt-Out of Nielsen measurement.

The Nielsen digital measurement products are not used to identify consumer in any way. They help Nielsen and its clients to measure and analyze how consumers engage with media across online, mobile and emerging technologies while offering insights into consumer behavior.

To learn more about our digital measurement products and your choices in regard to them, please visit http://www.nielsen.com/digitalprivacy.

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.

[[File:TVOs_OptOut_LimitAdTracking1.png]]

[[File:TVOs_OptOut_LimitAdTracking2.png]]

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.

<blockquote>'''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.</blockquote>

==== Legacy Opt-Out ====
'''Supported SDK Versions''': 1.2.3, 4.0.0.8, 5.1.0, 5.1.1.12.

<blockquote>'''Note''': If using SDK Version 5.1.1.17 or above, refer to [[#Limit Ad Tracking|Limit Ad Tracking iOS Implementation]].</blockquote>

As a global information and measurement leader, Nielsen is committed to protect the privacy and security of the data they collect, process and use. Nielsen strongly believes that the consumer should have a way to Opt-Out of Nielsen measurement.

The Nielsen digital measurement products help Nielsen and its clients to measure and analyze how consumers engage with media across online, mobile and emerging technologies while offering insights into consumer behavior.

To learn more about our digital measurement products and your choices in regard to them, please visit http://www.nielsen.com/digitalprivacy.

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 [[optOutURL]] and opened in ‘WebView’ within the app and NOT in any external browser.
** Opening the Opt-Out page in any external browser takes the application control out of the Nielsen App SDK context.
** As the App SDK does not expose any direct http/https interface to interact with the world to get the user selection on Privacy page, there will be no way to interact/send notification to the App SDK regarding the user selection.
* 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 [[optOutStatus]] method.
<blockquote>'''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.</blockquote>

'''Sequence Diagram'''
[[File:optoutsequence-ios.jpg]]

Below are the steps to implement user Opt-Out using UIWebView.

When a user clicks the Opt-Out / Opt-In link, the application should invoke [[optOutURL]] to get the link to the Nielsen Privacy page from SDK.

'''Implement WebView with Nielsen Opt-Out URL'''
<syntaxhighlight lang="objective-c">NielsenAppApi nAppApiObject;
@property(strong) UIWebView *optOutView;

// create WebView and set self as delegate
self.optOutView=[[UIWebViewalloc]initWithFrame:self.view.bounds];

self.optOutView.scalesPageToFit = yes;
// get Nielsen defined web address and load the page
NSString *webAddress = [nAppApiObject optOutURLString];

if(webAddress == nil)
{ // Handle it gracefully and retry later}
else
{
[optOutView loadRequest:[NSURLRequest requestWithURL:webAddress]];
// show the view to the user
[self.view addSubview:optOutView];
}</syntaxhighlight>

* The Nielsen Privacy Page appears using UIWebView

'''Privacy Page'''

[[File:privacy-policy.jpg]]

* There are two links – one for Opt-Out and one for Opt-In. Click the required link.
* Click OK in the dialog that appears, to confirm the action.
* The Opt-Out occurs by opening a Nielsen-defined web page and passing the user choice from the ‘WebView’. In order to do this, the application needs to
** Implement the UIWebView delegate method to open the Nielsen Privacy web page
** Capture user’s selection
** Pass the selection back to the SDK via the [[userOptOut]].

'''Capture and forward user selection'''
<syntaxhighlight lang="objective-c">-(BOOL)webView:(UIWebView *)webView shouldStartLoadWithRequest:(NSURLRequest *)request navigationType:(UIWebViewNavigationType)navigationType
{
NSString *command = [NSString stringWithFormat:@”%@”,request.URL];
if ([command isEqualToString:kNielsenWebClose]) {
// Close the WebView
[self performSelector:@selector(closeOptOutView) withObject:nil afterDelay:0];
return NO;
}
// Retrieve next URL if it’s not opt-in/out selection
return (![nAppApiObject userOptOut:command]);
}</syntaxhighlight>
* The app gets the user selection string via webviews shouldStartLoadWithRequest and invokes [[userOptOut]] with user selection. The delegate method handles the ‘WebView’ URL requests, interprets the commands, and calls the SDK accordingly.
* <code>[nAppApiObject userOptOut:command]</code> passes the user’s selection on Nielsen Privacy page to the SDK to allow the SDK to perform the required functions.
<blockquote>'''Note''': When ‘WebView’ is closed, pass the status returned from ‘WebView’ to the SDK within the app.</blockquote>

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

== AppApiEventCode ==
An enumeration with predefined App SDK event state transition codes.
<syntaxhighlight lang="objective-c">
typedef NS_ENUM(unsigned int, AppApiEventCode)
{
AppApiStartup = 2001,
AppApiShutdown = 2002,
}AppApiEventCode;
</syntaxhighlight>

== App SDK Event Codes ==
{| class="wikitable"
|-
! 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 ==
An enumeration with predefined error codes which the App SDK object can generate.
<syntaxhighlight lang="objective-c">
typedef NS_ENUM(unsigned int, AppApiErrorCode)
{
AppApiNetworkConnectionFailure = 1001,
AppApiFileWriteFailure = 1002,
AppApiFileReadFailure = 1003,
AppApiEmptyValue = 1004,
AppApiEmptyAppName = 1005,
AppApiEmptyAppVersion = 1006,
AppApiEmptyAppId = 1007,
AppApiAnExceptionOccured = 1008,
AppApiUnknownExceptionOccured = 1009
};
</syntaxhighlight>

== App SDK Error Codes ==
{| class="wikitable"
|-
! Event Code !! Event Name !! Event 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
|}

Android SDK API Reference

2017-07-12T19:32:22Z

Admin2: /* Opt-Out Implementation */

{{Breadcrumb|}} {{Breadcrumb|Digital}} {{CurrentBreadcrumb}}
[[Category:Digital]]
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.
*Create and initialize an instance object of <code>AppSdk</code> class.
*The player application can use this object to collect HLS timed metadata through a [[sendID3()]] call.
The Nielsen App SDK class is defined as the only public class belonging to the com.nielsen.app.sdk package. It inherits from the closeable interface and exposes the public APIs the client’s app will use. Below is the declaration of the <code>AppSdk</code> class: <code>public class AppSdk implements Closeable</code>

== Setting Up Development Environment ==
'''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.
<blockquote>'''Note''': App SDK 4.0.0 contains AppSDK.jar component only and does not support C/C++ libAppSdk.so components.</blockquote

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.

=== Setting up in Eclipse IDE ===
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.
<syntaxhighlight lang="java"><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"/></syntaxhighlight>
For more details to handle runtime permissions in Android versions, please visit [https://developer.android.com/training/permissions/requesting.html]. 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.

[[File:andr-properties-drm.jpg|link=]]

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

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

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.
Nielsen App SDK uses the following packages/classes from the Google Play service.

'''Library''':
* 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;

=== Setting up in Android Studio IDE ===
Launch '''Android Studio''' and select '''Import project (Eclipse ADT)'''.

[[File:andr-setup-launch.jpg|link=]]

Browse for project destination directory and click '''Next'''.

[[File:andr-import-project.jpg|link=]]

Go to '''File > Project Structure > App > Dependencies'''.

[[File:andr-pro-structure.jpg|link=]]

Click '''+''' to add library dependency.

Select '''play-services''' and click '''OK'''

[[File:andr-choose-library.jpg|link=]]

For more information, refer to https://developer.android.com/google/play-services/setup.html

== Initialization ==
=== Android Application Life Cycle with respect to Nielsen App SDK ===
[[File:andr-init-img1.jpg|link=]]

=== Step 1: App SDK initialization ===
==== For API version 4.0.0 and above ====

[[AppSDK()]] is no longer a singleton object and should be initialized as below.

'''Initialization of App SDK object through a JSON object'''
<syntaxhighlight lang="objective-c">
JSONObject config = null;

try
{
// Prepare AppSdk configuration object (JSONObject)
JSONObject appSdkConfig = new JSONObject()
.put("appid", "TXXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX")
.put("appname", "Sample App Name")
.put("sfcode", "uat-cert")
.put("nol_devDebug", "INFO") // only for debug builds
.put("custom_key1", "custom_value1")
.put("custom_key2", "custom_value2");
// 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);
}
</syntaxhighlight>

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

==== Android Application Life Cycle with respect to Nielsen App SDK ====
[[File:andr-radioandvideo-app.jpg|link=]]

=== Step 2: App SDK libraries inclusion in project ===
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).

=== Step 3: Nielsen App SDK Streaming Sessions ===
After ensuring that the SDK object has been initialized, link the streaming session APIs. The next steps are:
*Call [[play()]] when starting or resuming a streaming session. Use the channelName parameter to pass channel descriptor information. The channel name field is a 32-character free-form text field containing the name of the program or feed being sent (such as ESPN2, Food Network, etc.) which must be inserted on a JSON string.
*Load the CMS metadata by calling the [[loadMetadata()]] on the SDK object.
*Call [[stop()]] when ending or pausing a viewing session.
*During session playback, call the SDK [[setPlayheadPosition()]] and / or [[sendID3()]]
**Call [[setPlayheadPosition()]] every one second until the stream is stopped or paused. Normally this happens on Digital Audio measurements.
**Call [[sendID3()]] if the client relies on the Nielsen ID3 tags for its measurements; this call should happen whenever a new Nielsen ID3 metadata is available for processing. Normally this happens on DTVR and ID3 measurements.
Nielsen App SDK object handles filtering of ID3 tags and CMS tags, queuing/buffering of data, and all communications with Nielsen collection facility.
*The client’s app must clearly identify the mode of operation (live vs. VOD) and stick to the type of playhead coordinates until the playback is completed. The client must reliably provide the appropriated playhead position value depending on the type of content streamed.
*If streaming live video content, the client must pass the current UTC time in seconds as playhead position.
*If streaming VOD (video on demand), the client must stream the offset from the beginning of the file as playhead position.
*For all Digital Audio listening, the client must pass the current UTC time in seconds as playhead position, regardless of station type.

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

=== Sample ID3 tags ===
* <code>www.nielsen.com/X100zdCIGeIlgZnkYj6UvQ==/X100zdCIGeIlgZnkYj6UvQ==/AAAB2Jz2_k74GXSzx4npHuI_JwJd3QSUpW30rDkGTcbHEzIMWleCzM-uvNOP9fzJcQMWQLJqzXMCAxParOb5sGijSV9dNM3QiBniJYGZ5GI-lL1fXTTN0IgZ4iWBmeRiPpS9AAAAAAAAAAAAAAAAAAAAAFJWFM5SVhTONNU=/00000/00000/00</code>
* <code>www.nielsen.com/X100zdCIGeIlgZnkYj6UvQ==/R8WHe7pEBeqBhu8jTeXydg==/AAICoyitYqlxT7n6aZ0oMCGheFi4CXFp46AMUPZz1lMr_M9tr3_cjee1SHqxrOiVerMDLeyn9xzocZSKwi746Re8vNOtpNCAZjYABs_J0R25IHpvOc1HS8QHGgD5TgOJeS6gX100zdCIGeIlgZnkYj6UvVJWFNhSVhTiPE0=/00000/46016/00</code>
<blockquote>'''Note''': ID3 tags are not applicable for International (Germany)</blockquote>

=== Extracting ID3 tags from Android Players ===
==== ID3 Support Matrix ====
{| class="wikitable"
|-
! Player Name !! Minimum supported version !! Description
|-
| Android Native Media Player || Android 6 || Android 6 Media Player allows apps to register a callback to be invoked, when a selected track has the timed metadata available. Currently, only HTTP Live Streaming (HLS) data URI’s embedded with timed ID3 tags, generates TimedMetaData.
|-
| Google ExoPlayer || Android 4.1 ||
|-
| Brightcove Player || Android 4.1 || Support for Android versions 2.3.3 and 4.0 is now deprecated. Learn more about why Brightcove is removing support for these versions as of January 1, 2016 in this [https://support.brightcove.com/en/perform/docs/announcement-brightcove-sdk-android-version-support|announcement]
|-
| Adobe PrimeTime Player || Android 4.2 ||
|-
| VisualOn Player || Android 2.3 || Android 5 is the latest supported version
|-
| NexStream Player || Android 1.6 || Supported till Android 6
|}

==== Android Native Media Player ====
As the Android Media Player versions (prior to Android 6 / Android API 23) do not support ID3, Nielsen has created a library that becomes an extension to the media player, thus MPX. This library extracts the ID3 tags and sends them to the app. For more information on how to use the MPX component, refer to the Nielsen-supplied sample application.

Starting from '''Android 6 (Android API 23)''', Android Native Media Player allows apps to register a callback to be invoked, when a selected track has the timed metadata available. Currently, only HTTP Live Streaming (HLS) data URI’s embedded with timed ID3 tags generate TimedMetadata. Once the HLS video starts, call onTimedMetaDataAvailable() as and when the player observes a TimedMetadata (ID3 tag).

<syntaxhighlight lang="java">@Override
public void onTimedMetaDataAvailable(MediaPlayer mp, TimedMetaData data)
{
byte[] iD3PayloadArray = data.getMetaData();
String iD3Payload = new String(iD3PayloadArray, StandardCharsets.UTF_8);
if (null != iD3Payload && iD3Payload.contains("www.nielsen.com"))
{
int index = iD3Payload.indexOf("www.nielsen.com");
String id3String = iD3Payload.substring(index, (index + 249));
Log.d(TAG, "TimedMetaData ID3 Tag:" + id3String);
appProcessID3tag(id3String);
}
}</syntaxhighlight>

==== ExoPlayer ====
he SDK is designed around an event-driven architecture where components emit events to allow other components to listen and respond to state changes.

'''Player SDK Classes used:'''
<syntaxhighlight lang="java">com.google.android.exoplayer.demo.player.DemoPlayer</syntaxhighlight>

Since Nielsen App SDK is interested in extracting the Timed Metadata (ID3 Tags) in HLS and VOD on the EXO Player, trace the ID3_TAG emitted during video content played using EXOPlayer component as below.

<syntaxhighlight lang="java">DemoPlayer implements ExoPlayer.Listener
—————————————————–
/**
* A listener for receiving ID3 metadata parsed from the media stream.
*/
public interface Id3MetadataListener
{
void onId3Metadata(Map<String, Object> metadata);
}
——————————————————-
MetadataTrackRenderer.MetadataRenderer<Map<String,
Object>> getId3MetadataRenderer()
{
return new MetadataTrackRenderer.MetadataRenderer<Map<String, Object>>()
{
@Override
public void onMetadata(Map<String, Object> metadata)
{
if (id3MetadataListener != null)
{
id3MetadataListener.onId3Metadata(metadata);
}
}
};
}</syntaxhighlight>

Also in ''Player.java'' class:
<syntaxhighlight lang="java">Player implements DemoPlayer.Id3MetadataListener
—————————————————–
@SuppressWarnings("rawtypes")
@Override
public void onId3Metadata(Map<String, Object> metadata)
{
try
{
for (Object o : metadata.entrySet())
{
Map.Entry pairs = (Map.Entry) o;
if (metadata.containsKey(TxxxMetadata.TYPE))
{
TxxxMetadata txxxMetadata = (TxxxMetadata) metadata
.get(TxxxMetadata.TYPE);
}
else
{
String aStr = new String((byte[]) pairs.getValue());
MainActivity.mAppSdk.sendID3(aStr);
}
}
}
catch (Exception e)
{
e.printStackTrace();
Log.d(TAG, "onId3Metadata(): No Id3 tags");
}
}</syntaxhighlight>

[[File:andr-exo-retrievingID3tags.png|link=]]

==== Brightcove Player ====
While the Brightcove player plays the content, EventListener triggers an event when an ID3 packet is received (<code>SeamlessVideoDisplayComponent.ID3_TAG</code>). Upon receiving this event, collect the incoming ID3 tags and only pass the Nielsen payload of the PRIV frame to the App SDK for analysis.

<syntaxhighlight lang="java">brightcoveVideoView.getEventEmitter().on(SeamlessVideoDisplayComponent.ID3_TAG, new EventListener()
{
public void processEvent(Event event)
{
NlsId3Tag nlsID3 = new NlsId3Tag(event.properties.get(SeamlessVideoDisplayComponent.ID3_DATA).toString());
Log.w("ID3", nlsID3.NlsPayload);
// Sent ID3 Tags to App
appProcessID3tag(nlsID3.NlsPayload);
}
});
}</syntaxhighlight>

==== Adobe PrimeTime Player ====
While the Adobe PrimeTime player plays the content, MediaPlayer.PlaybackEventListener triggers a callback when an ID3 packet is received (onTimedMetadata). Upon receiving this event, collect the incoming ID3 tags and only pass the Nielsen payload of the PRIV frame to the App SDK for analysis.
<syntaxhighlight lang="java">public void onTimedMetadata(TimedMetadata id3Metadata)
{
NlsId3Tag nlsID3 = new NlsId3Tag(id3Metadata.getMetadata().toString());
Log.w(LOG_TAG, "ID3 Timed Data –> " + nlsID3.NlsPayload);
Log.w(LOG_TAG, "PayLoad Size –> " + nlsID3.NlsPayload.length());
appProcessID3tag(nlsID3.NlsPayload);
}</syntaxhighlight>

==== VisualOn Player ====
While the VisualOn player plays the content, <code>VOCommonPlayerListener</code> triggers an event when an ID3 packet is received (<code>VO_OSMP_SRC_CUSTOMERTAGID_TIMEDTAG</code>). Upon receiving this event, collect the incoming ID3 tags and only pass the Nielsen payload of the PRIV frame to the App SDK for analysis.

<syntaxhighlight lang="java">case VO_OSMP_SRC_CB_CUSTOMER_TAG:
{
VO_OSMP_SRC_CUSTOMERTAGID tag = VO_OSMP_SRC_CUSTOMERTAGID.valueOf(nParam1);
switch (tag)
{
case VO_OSMP_SRC_CUSTOMERTAGID_TIMEDTAG:
// do something with this tag
int time = nParam2;
byte[] b = (byte[]) obj;
String s = new String(b);
NlsId3Tag nlsID3 = new NlsId3Tag(b);
// Sent ID3 Tags to App
appProcessID3tag(nlsID3.NlsPayload);
if (appid3If != null)
appid3If.onId3(nlsID3.NlsPayload);
break;
case VO_OSMP_SRC_CUSTOMERTAGID_MAX:
// ignore this type of tag
break;
default:
break;
}
break;
}</syntaxhighlight>

==== NextStream Player ====
ID3 tags will be received in the NexStream Player through <code>onTimedMetaRenderRender(NexPlayer mp,NexID3TagInformation metadata)</code> callback API. A sample implementation for the callback is shown below:
<syntaxhighlight lang="java">public void onTimedMetaRenderRender(NexPlayer mp, NexID3TagInformation m)
{
text = m.getPrivateFrame();
if (text != null)
{
data = text.getTextData();
if (data != null)
{
// make sure to identify the beginning of the
// Nielsen ID3 tag payload by searching for the
// "www.nielsen.com" string on the ID3 tag and
// passing to the App SDK all information that
// follows. It should be:
// nlsPayload = "www.nielsen.com" + dataFollowing
nlsPayload = getDataAfterWwwNielsenCom(data);
if (nlsPayload!= NULL)
mAppSdk.sendID3(nlsPayload);
}
}
}</syntaxhighlight>

The [[sendID3()]] sends the extracted Nielsen ID3 payload to the App SDK for analysis.

== Android SDK API Methods & Properties ==
{| class="wikitable sortable"
|-
! Scenario !! Method / Property !! DTVR !! DAR !! Digital Audio !! DCR !! International (Germany) !! Description
|-
| Initialize || [[AppSDK()]] || ✔ || ✔ || ✔ || ✔ || ✔ || 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 when there is a preroll ad that needs to be associated with content metadata. The loadmetadata will first be called to populate the content metadata values and then the loadMetadata for ad metadata will be called. This allows sending a content ping with the ad info, even if the user bails out during the preroll ad.
|-
| Measurement || [[sendID3()]] || ✔ || ✘ || ✘ || ✘ || ✘ || Used to send the ID3 metadata.
|-
| Measurement || [[setPlayheadPosition()]] || ✘ || ✘ || ✔ || ✔ || ✔ || 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 || [[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 || [[userOptOutURLString()]] || ✔ || ✔ || ✔ || ✔ || ✔ || 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 || [[getOptOutStatus()]] || ✘ || ✘ || ✘ || ✘ || ✔ || Call this API to retrieve the Opt-Out or Opt-In state.
|-
| Opt-out
| [[appDisableApi()]]
(kill switch)
|| ✔ || ✔ || ✔ || ✔ || ✔ || Used to disable the SDK.
|-
| Opt-out || [[getAppDisable()]] || ✔ || ✔ || ✔ || ✔ || ✔ || Used to query if the SDK is disabled or not.
|-
| Log || [[getLastEvent()]] || ✔ || ✔ || ✔ || ✔ || ✔ || Used to query the SDK for the last status
|-
| Log || [[getLastError()]] || ✔ || ✔ || ✔ || ✔ || ✔ || Used to query the SDK for the last error
|-
| Log || [[isValid()]] || ✔ || ✔ || ✔ || ✔ || ✔ || Used to check if the SDK was successfully instantiated or not.
|-
| Log || [[getMeterVersion()]] || ✘ || ✘ || ✘ || ✘ || ✔ || Returns the current SDK version.
|-
| Log || [[getNielsenId()]] || ✔ || ✔ || ✔ || ✔ || ✔ || Used to get a string defining the Nielsen ID (NUID) number for the device.
|-
| Log || [[getDeviceId()]] || ✔ || ✔ || ✔ || ✔ || ✔ || Returns the current device id.
|-
| Log || [[appInBackground()]] || ✘ || ✘ || ✘ || ✔ || ✔ || Used to capture the event of app going to background.
|-
| Log || [[appInForeground()]] || ✘ || ✘ || ✘ || ✔ || ✔ || Used to capture the event of app coming to foreground
|-
| Log || [[setDebug()]] || ✘ || ✘ || ✘ || ✘ || ✔ || Used to enable/disable debug flags. Newly introduced in SDK version 5.0.0 for International (Germany)
|}

== 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.
*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.

=== Displaying Opt-Out in a WebView ===
<syntaxhighlight lang="java">
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
}
</syntaxhighlight>

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.

[[File:Privacy policy iOS.jpg|link=]]

<blockquote>'''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.</blockquote>

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

=== Sequence Diagram ===
[[File:optoutsequence-andr.jpg|link=]]

== Opt-out Android SDK Version '''5.1.1.18 or above''' ==
<blockquote>'''Note:''' If using Android SDK Versions 1.2.3, 4.0.0.8, 5.1.0, 5.1.1.14, skip ahead to: [[#Opt-out Android SDK Version 1.2.3, 4.0.0.8, 5.1.0, 5.1.1.14|Opt-out Android SDK Version 1.2.3, 4.0.0.8, 5.1.0, 5.1.1.14]]</blockquote>

Starting from SDK version 5.1.1.18, Opt-Out related behavior has been changed in the following ways:
*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'''.
<blockquote>'''Note:''' For Amazon devices, see [[#Opt-Out Implementation for Amazon Devices|Opt-Out Implementation for Amazon Devices]] below.</blockquote>

[[File:andr-ads.jpg|link=]]

<blockquote>'''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.</blockquote>

== Opt-out Android SDK Version '''1.2.3, 4.0.0.8, 5.1.0, 5.1.1.14''' ==
<blockquote>'''Note:''' If using Android SDK Version 5.1.1.18 or above, refer to documentation above ([[#Opt-out Android SDK Version 5.1.1.18 or above|Opt-out Android SDK Version 5.1.1.18 or above]])</blockquote>

When a user clicks the Opt-Out / Opt-In link, the application should invoke [[optOutURL]] to get the link to the Nielsen Privacy page from SDK.
=== Privacy Page ===
[[File:privacy-policy.jpg|link=]]
*There are two click here links – one for Opt-Out and one for Opt-In. Click the required link:
**Capture user’s selection
**Pass the selection back to the SDK via the [[userOptOut()]].

=== Capture and forward user selection ===
<syntaxhighlight lang="java">
private class MonitorWebView extends WebViewClient
{
private static final String NIELSEN_URL_OPT_OUT = “nielsenappsdk://1”;
private static final String NIELSEN_URL_OPT_IN = “nielsenappsdk://0”;

@Override
public boolean shouldOverrideUrlLoading(WebView view, String url)
{
if (NIELSEN_URL_OPT_OUT.equals(url)
|| NIELSEN_URL_OPT_IN.equals(url))
{
// Get AppSdk instance from the host
AppSdk appSdk = HostApp.getAppSdk();
// Send the URL to the AppSdk instance
appSdk.userOptOut(url);
return true;
}
return false;
}
}
</syntaxhighlight>

<blockquote>'''Note:''' When 'WebView' is closed, pass the status returned from 'WebView' to the SDK within the app.</blockquote>
<blockquote>'''Note:''' App SDK manages the user's choice (Opt-Out / Opt-In), the app does not need to manage this status.</blockquote>

== 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 ===

<syntaxhighlight lang="java">
ContentResolver cr = getContentResolver();
int limitAdTracking = Secure.getInt(cr, "limit_ad_tracking", 2);
</syntaxhighlight>

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

<blockquote>'''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'''.</blockquote>

== Nielsen Sample Applications ==

== Nielsen Privacy Requirements ==
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.
[[File:RatingsDataFlow.png]]

'''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 ===
{| class="wikitable"
|-
! Type of Information !! Parameter !! Transmitted to Nielsen? !! Sent to Provider?
|-
| rowspan="8" | 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
|-
| rowspan="10" | 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
|-
| rowspan="9" | 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
|}
<blockquote>'''Note''': Data is hashed, and encrypted using AES 128 before transmission to data provider.</blockquote>

==== Example ping sent to provider ====
* <code><nowiki>https://provider.com/cgi-bin/brandlift.php</nowiki>?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</code>

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

=== Opt-Out Implementation ===
==== Limit Ad Tracking ====

Opt-Out Implementation (Limit Ad Tracking)

'''This implementation is valid for SDK Versions 5.1.1.18 and above.'''

If using SDK Version 1.2.3, 4.0.0.8, 5.1.0 or 5.1.1.14, refer to Legacy Opt-Out.

As a global information and measurement leader, Nielsen is committed to protect the privacy and security of the data they collect, process and use. Nielsen strongly believes that the consumer should have a way to Opt-Out of Nielsen measurement.

The Nielsen digital measurement products help Nielsen and its clients to measure and analyze how consumers engage with media across online, mobile and emerging technologies while offering insights into consumer behavior.

To learn more about our digital measurement products and your choices in regard to them, please visit http://www.nielsen.com/digitalprivacy.

To opt out, users must have access to Nielsen “About Nielsen Measurement” page from within the 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.
* 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.

'''Displaying Opt-Out in a WebView'''
<syntaxhighlight lang="java">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
}</syntaxhighlight>
<blockquote>'''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.</blockquote>

Starting from SDK version 5.1.1.16, Opt-Out related behavior has been changed in multiple ways as mentioned below.
* 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'''.

<blockquote>'''Note''': For more information on FireTV please see Opt-Out Implementation in Amazon Devices.</blockquote>

'''Opting out through Google Settings'''

[[File:andr-ads.jpg]]

'''What SDK integration do developers need to take care of?'''
* Get the Opt-Out URL from SDK in order to show the page to end users in a ‘WebView’ / External browser. There is no change in this process.
* Do not handle/pass the response which is received from the hyperlinks for Opt-Out / Opt-In operations, as these hyperlinks will no longer exist.
* Ensure to provide a button which can close/exit the optout page screen

'''Latest Opt-Out Page'''

[[File:privacy_policy_andr.jpg]]

<blockquote>'''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.</blockquote>
<blockquote>'''Note''': App SDK manages the user’s choice (Opt-Out / Opt-In), the app does not need to manage this status.</blockquote>

'''Sequence Diagram'''

[[File:optoutsequence-andr.jpg]]

==== Legacy Opt-Out Implementation ====
'''Supported SDK Versions''': 1.2.3, 4.0.0.8, 5.1.0, 5.1.1.14.

If using SDK Version 5.1.1.18 or above, refer to Opt-Out Implementation (Limit Ad Tracking).

As a global information and measurement leader, Nielsen is committed to protect the privacy and security of the data they collect, process and use. Nielsen strongly believes that the consumer should have a way to opt-out of Nielsen measurement.

The Nielsen digital measurement products help Nielsen and its clients to measure and analyze how consumers engage with media across online, mobile and emerging technologies while offering insights into consumer behavior.

To learn more about our digital measurement products and your choices in regard to them, please visit http://www.nielsen.com/digitalprivacy.

To opt out, users must have access to Nielsen “About Nielsen Measurement” page from within the 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’ within the app and NOT in any external browser.
** Opening the opt-out page in any external browser takes the application control out of the Nielsen App SDK context.
** As the App SDK does not expose any direct http/https interface to interact with the world to get the user selection on Privacy page, there will be no way to interact/send notification to the App SDK regarding the user selection.
* 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.
<blockquote>'''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.</blockquote>

'''Sequence Diagram'''

[[File:optoutsequence-andr.jpg]]

Below are the steps to implement user opt-out using UIWebView.
* When a user clicks the Opt Out / Opt In link, the application should invoke [[userOptOutURLString()]] to get the link to the Nielsen Privacy page from SDK.
* Present WebView with Nielsen opt-out URL
** <syntaxhighlight lang="java">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
}</syntaxhighlight>
* The Nielsen Privacy page appears using UIWebView
[[File:privacy-policy.jpg]]
* There are two '''click here''' links – one for Opt-Out and one for Opt-In. User clicks the required link.
* Capture user’s selection
* Pass the selection back to the SDK via the [[userOptOut()]].
* Capture and forward user selection
** <syntaxhighlight lang="java">private class MonitorWebView extends WebViewClient
{
private static final String NIELSEN_URL_OPT_OUT = “nielsenappsdk://1”;
private static final String NIELSEN_URL_OPT_IN = “nielsenappsdk://0”;

@Override
public boolean shouldOverrideUrlLoading(WebView view, String url)
{
if (NIELSEN_URL_OPT_OUT.equals(url)
|| NIELSEN_URL_OPT_IN.equals(url))
{
// Get AppSdk instance from the host
AppSdk appSdk = HostApp.getAppSdk();
// Send the URL to the AppSdk instance
appSdk.userOptOut(url);
return true;
}
return false;
}
}</syntaxhighlight>
<blockquote>'''Note''': When ‘WebView’ is closed, pass the status returned from ‘WebView’ to the SDK within the app.</blockquote>
<blockquote>'''Note''': App SDK manages the user’s choice (opt-out/opt-in), the app does not need to manage this status.</blockquote>

==== 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'''
<syntaxhighlight lang="java">ContentResolver cr = getContentResolver();
int limitAdTracking = Secure.getInt(cr, "limit_ad_tracking", 2);</syntaxhighlight>
* 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).
<blockquote>'''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'''.</blockquote>

== Event and Error Handling ==
=== App SDK Error Codes ===
Constants with predefined error codes which the AppSdk object can generate.
<syntaxhighlight lang="java">public static final int ERROR_FAILED_CREATE_URL_STRING = 1001;
// failed generating ping string due to error on parsing
// description – include last error message from URL parser
public static final int ERROR_FAILED_RECEIVE_CONFIG = 1002;
// failed to receive configuration file from Census
// description – on 5th time, it will log event and keep requesting config 10 min apart
public static final int ERROR_FAILED_PARSING_CONFIG = 1003;
// failed parsing the config file JSON string
// description – include json error number/short message from iOS or Android
public static final int ERROR_FAILED_PARSING_PLAY = 1004;
// failed parsing the play() JSON string
// description – include json error number/short message from iOS or Android
public static final int ERROR_FAILED_PARSING_METADATA = 1005;
// failed parsing the play() JSON string
// description – include JSON error number/short message from iOS or Android
public static final int ERROR_FAILED_GENERATING_PING = 1006;
// failed creating ping before adding it to the UPLOAD table)
// description – include ping nol_url index, cadence to identify ping
public static final int ERROR_FAILED_PROCESSOR_START = 1007;
// failed starting data processor thread. Normally, that means a product
// description – include processor that failed to start
public static final int ERROR_FAILED_PROCESS_ID3 = 1008;
// failed processing data on a data processor. Normally, that means the input to a product
// description – include processor and data that failed to process (ID3 tag on a MTVR impression, for example)
public static final int ERROR_FAILED_HTTP_SEND = 1009;
// failed sending HTTP or HTTPS requests
// description – include HTTP error number
public static final int ERROR_FAILED_SENDING_PING = 1010;
// failed sending pings (on ANDROID, the ping on the UPLOAD table)
// description – include ping up to 80 char from the end
public static final int ERROR_FAILED_SENDING_TSV = 1011;
// failed sending TSV requests
// description – include TSV request message
public static final int ERROR_FAILED_SENDING_STATION_ID = 1012;
// failed sending StationId requests
// description – include Station ID request message
public static final int ERROR_FAILED_ACCESSING_DB = 1013;
// failed read/write from/to database table
// description – include SQL statement and data and SQLite error number/message
public static final int ERROR_CHANGED_DEVICE_ID = 1014;
// device ID changed
// description – none
public static final int ERROR_CHANGED_NUID = 1015;
// NUID changed
// description – none
public static final int ERROR_SDK_NOT_INITIALIZED = 1016;
// App SDK initialization failed
// description – none
public static final int ERROR_FAILED_SDK_SUSPEND = 1017;
// App SDK failed to suspend activities
// description – none
public static final int ERROR_INVALID_PARAMETERS = 1018;
// App SDK invalid parameters
// description – none
public static final int ERROR_INVALID_STATE = 1019;
// App SDK called in incorrect state
// description – none
public static final int ERROR_FAILED_PROCESS_PLAYHEAD = 1020;
// App SDK failed processing playhead position
// description – none
public static final int ERROR_FAILED_PROCESS_METADATA = 1021;
// App SDK failed processing not-null, syntax valid JSON metadada
// description – none
public static final int ERROR_FAILED_PROCESS_STOP = 1022;
// App SDK failed processing stop
// description – none</syntaxhighlight>

=== App SDK Event Codes ===
<syntaxhighlight lang="java">public static final int EVENT_INITIATE = 2000;
// App SDK is initiated. It will happen as soon as the App SDK is initialized
public static final int EVENT_STARTUP = 2001;
// App SDK has started up. It will happen only after App SDK has received a valid config file. This is the location in the code to acquire the value of userOptOutURLString().
public static final int EVENT_SHUTDOWN = 2002;
// App SDK is shutting down. It will happen just before App SDK is destroyed</syntaxhighlight>

'''App SDK Event Codes '''
{| class="wikitable"
|-
! Event Code !! Event Name !! Event Description
|-
| 2000 || EVENT_INITIATE || App SDK is initiated. It will happen as soon as the App SDK is initialized
|-
| 2001 || EVENT_STARTUP || App SDK has started up. It will happen only after App SDK has received a valid config file
|-
| 2002 || EVENT_SHUTDOWN || App SDK is shutting down. It will happen just before App SDK is destroyed
|}

Browser SDK API Reference

2017-07-12T19:06:37Z

Admin2: /* Opt-Out Implementation */

{{Breadcrumb|}} {{Breadcrumb|Digital}} {{CurrentBreadcrumb}}
[[Category:Digital]]

== Setting up Development Environment ==
=== Step 1: Configure Content Management System (CMS) ===
Configure CMS to send the required values (see table below). Any internal CMS_variable names can be used for passing the data.

Ensure to capture these CMS_variable names in the SDK Configuration Form.

For more information on setting variable names, see the SDK Configuration Form included within the SDK package.

{| class="wikitable"
|-
! Required Data !! Description !! Value
|-
| dataSrc || Used when both CMS metadata and ID3 data are present in the player. Setting this field tells the SDK whether to use the CMS metadata or the ID3 payload to derive the pings || cms
|-
| sfcode || sfcode will be provided by Nielsen and specifies which Nielsen collection facility the app should connect to. Connect to a development server during development and switch to production server once app has been certified by Nielsen. || uat-cert dcr-cert
|-
| Asset Type || Type of asset: ad or content || preroll, midroll, postroll, or content
|-
| Asset ID || Unique identifier assigned to each asset || GUID, EIDR, ADID, or internal house ID
|-
| OCR Tag || OCR tag provided by Nielsen for implementation on the ad unit || Complete OCR URL
|-
| VC Program Name || VideoCensus program name. If no value is provided, DPR program name is populated in client-defined reporting in VC || Program name used for VC reporting
|-
| Title || Title of asset || Title used for reporting
|-
| Length || Duration of asset || Length in seconds, 86400 for live stream
|-
| Isfullepisode || Full episode flag “yes” or “lf” – full episode “no” or “sf” – non full episode
|-
| segA || Segment A (this is not available for video reporting as the episode title is reported) || custom value
|-
| segB || Segment B || custom value
|-
| segC || Segment C || custom value
|-
| crossId1 || Standard episode ID || custom value
|-
| crossId2 || Content originator (required only for distributors) || custom value
|-
| airdate || Original air date and time in Eastern Time. For non-US countries, it should be local time. || YYYYMMDD HH24:MI:SS
|}

==== Content Management System for Digital Audio ====
Digital Audio measurement is for digital-only audio content. For Digital Audio, clients should provide the parameters shown in CMS Table for Digital Audio.
{| class="wikitable"
|-
! Required Data !! Description !! Value
|-
| dataSrc ** || Source of the data. For Digital Audio, pass dataSrc as “cms”. || cms
|-
type || Type of content . For Digital Audio, set type as “radio”. || radio
|-
assetid || Station identifier, should include call letters and band. || WXYZ-FM
|-
stationType || OTA station flag and / or OTA station type 0: Custom station built per user 1: OTA streaming station with the same ad load 2: OTA station with a different ad load 3: Multicast eRadio or online station 4: On Demand Audio (podcasting) || 0, 1, 2, 3, or 4
|-
provider || Name of Provider || XYZ Provider
|}

=== Step 2: Complete the Nielsen SDK Configuration Form ===
The SDK is designed to map the <code>CMS_variable names</code>. To support the custom mapping, the developer is required to complete the SDK Configuration Form. The form will be provided during onboarding along with this guide.

== Initialization ==
=== Obtain the Nielsen Application ID (apid), sfcode and Browser SDK URLs ===
The Nielsen <code>apid</code> and <code>sfcode</code> are required to enable SDK functionality. Technical Account Manager will provide two apids and two sfcodes for each player configuration:
*'''Test apid and Test sfcode''': Use these IDs during development and testing
*'''Production apid and Production sfcode''': Use these IDs in production environment after Nielsen has tested and certified the player.
Browser SDK can support URLs that use any of the protocols – HTTPS and HTTP. Contact the Technical Account Manager to get the appropriate Browser SDK package that suits the requirements.

=== Initialize Browser SDK ===
To initialize the SDK, parameters must be passed when calling the initialization function (<code>ggInitialize</code>).

Create a global object with the values for the required parameters (sfcode, apid, apn, and nol_sdkDebug).
<syntaxhighlight lang="javascript">
<script type="text/javascript">
var _nolggGlobalParams =
{
apid: "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXX",
sfcode: "dcr-cert",
apn: "sample player name / site name",
nol_sdkDebug: "console"
};
</script>
</syntaxhighlight>
<blockquote>'''Note:''' Use the debug parameter, nol_sdkDebug, for testing only. Remove the parameter before moving to production.</blockquote>

To initialize the SDK , use the following methods:
<syntaxhighlight lang="javascript">
<script type="text/javascript">
var gg = window.NOLCMB.getInstance(instanceName /*optional*/);
gg.ggInitialize(window._nolggGlobalParams);
</syntaxhighlight>
If no parameters are passed to getInstance(), the default instance name is used.
<blockquote>'''Note:''' To create a new instance of the player, send a different / new unique string. Sending the same unique string re-initializes the existing instance of the player.</blockquote>
<blockquote>'''Note:''' To measure static content on a page and integrate the SDK with a player for video measurement, it is recommended to create one SDK instance using <code>_nolggGlobalParams.apid</code>.</blockquote>

=== SDK Initialization – Global Parameters ===
{| class="wikitable"
|-
! Parameters !! Description !! Value !! Required?
|-
| apid || UniqueID assigned to player/site. || Nielsen provided || Yes
|-
| apn || User-defined string value for describing the player/site. || Client provided || Yes
|-
| sfcode || Location of collection environment. During testing, all traffic should be directed to "dcr-cert". || "dcr-cert" – testing "dcr" – production || Yes
|-
| nol_sdkDebug || Enables Debug Mode which allows output to be viewed in console. || "console" || No
|}
<blockquote>'''Note:''' The debug parameter, <code>nol_sdkDebug</code>, is only used for testing and should be removed before moving to production. The output is displayed in console debuggers when enabled.</code>.</blockquote>

== Browser SDK API Methods & Properties ==
{| class="wikitable sortable"
|-
! Method / Property !! Event # !! DTVR !! DAR !! Digital Audio !! DCR !! International (Germany) !! Description
|-
| [[loadMetadata (Browser)]] || 3 || ✔ || ✔ || ✔ || ✔ || ✔ || Used when there is a preroll ad that needs to be associated with content metadata. The loadMetadata will first be called to populate the content metadata values and then the loadMetadata for ad metadata will be called. This allows sending a content ping with the ad info, even if the user bails out during the preroll ad.
|-
| [[play (Browser)]] || 5 || ✔ || ✘ || ✘ || ✔ || ✔ || 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. When the client passes in the channelName, they can change the CMS data stored by passing new values. If this event is not called then the “channel name” value populated will be the default value of “defaultChannelName”.

'''VA Beacon:''' Called when content or ads start playing. The playhead position must be passed.
|-
| [[sendID3 (Browser)]] || 55 || ✔ || ✘ || ✘ || ✘ || ✘ || Used to send the ID3 metadata.
|-
| [[setPlayheadPosition (Browser)]] || 49 || ✘ || ✘ || ✔ || ✔ || ✔ || Used to send the playhead position.
|-
| [[stop (Browser)]] || 7 || ✘ || ✘ || ✘ || ✔ || ✔ || Used when switching between ad and content or content and ad.
|-
| [[end (Browser)]] || 57 || ✔ || ✘ || ✔ || ✔ || ✔ || This is triggered 1) at the end of the content stream, 2) if the user switches to another piece of content 3) when the browser is refreshed or closed
|-
| [[staticstart (Browser)]] || 14 || ✘ || ✘ || ✘ || ✔ || ✔ || Used to send the metadata for the static page.
|-
| [[getOptOutStatus (Browser)]] || 4 || ✘ || ✘ || ✘ || ✘ || ✔ || '''VA Beacon Only:''' Sent only after calling stop. The current position must be passed. Not needed for new International (Germany) implementations.
|-
| [[updateOTT (Browser)]] || - || ✘ || ✘ || ✘ || ✘ || ✔ || Used to notify Browser SDK that the remote OTT device (like Google ChromeCast, Roku, Amazon FireTV, etc.) is connected / disconnected (change of OTT status).
|-
| [[ onPaginate (Browser)]] || 30 || ✘ || ✘ || ✘ || ✔ || ✔ || Used to create a new instance of the SDK object
|-
| [[updateMetadata (Browser)]] || 35 || ✔ || ✔ || ✔ || ✔ || ✔ || This event is used for updating metadata parameters for the content or ad that is being played.
|}

== Retrieving ID3 Tags ==
The video player must have the ability to extract ID3 tags and supply them to the Browser SDK, based on the HLS standard.
*An ID3 tag spans two PES packets.
**In the first PES packet, look for www.nielsen.com, this is the start of the ID3 tag. Continue to parse the first PES packet until the undefined char "\ufffd" is found. This forms the first half of the ID3 tag
**In the second PES packet, identify the end pattern – a regEx of /(\/\d+){3}/ and look to remove the lowest index of either "\x00" and/or "\ufffd". Now the second packet has been appended and the demarcation of the Nielsen-specific data has been defined.

Follow the procedure below, to extract Nielsen ID3 tags from an MPEG-2 transport stream (including HLS streams).
#Parse the Program Map Table (PMT) to find the PID of the metadata stream. Confirm the presence of the metadata descriptor described in section 2.3.3 of Apple’s “HTTP Live Streaming Metadata Spec.pdf”. Only private streams with metadata descriptor present should be considered as ID3-tag metadata streams.
#Parse the HLS/Transport stream for any '''PES header''' with the PID found in step 1.
#Follow standard MPEG-2 parsing procedures to locate the start of the payload of the PES packet.
#Copy the PES payload into a buffer.
#The ID3 tag spans 2 PES packets. Parse the stream for the next packet whose PID is set to the PID found in step 1. Typically the ID3 Tag is of 249 bytes. The steps below guide towards extraction of the ID3 tag
##In the first PES packet, look for "www.nielsen.com" , this is the start of the ID3 tag. Keep on parsing the first PES packet until the undefined char "\ufffd" is found. This forms the first half of the ID3 tag
##In the second PES packet, identify the end pattern, a regEx of /(\/\d+){3}/ and look to remove the lowest index of either “\x00” and/or “\ufffd”. Now the second packet has been appended and the demarcation of the Nielsen specific data has been defined. This segment can be simply substringed.
##Concatenate this substringed segment with the payload derived from the first packet get the ID3 payload.
#Check the length of the contents in the buffer to make sure that it is equal to the size of a Nielsen ID3 tag.
#Ensure that the ID3 byte array is converted into the string and escape it, so that the SDK can consume it.
Repeat steps 2 through 7 for all ID3 tags in the stream.

'''References'''
*[http://www.iso.org/iso/catalogue_detail?csnumber=44169. ISO/IEC 13818-1:2007] Information technology – Generic coding of moving pictures and associated audio information: Systems
*https://developer.apple.com/library/ios/sdk/developers/AudioVideo/Conceptual/HTTP_Live_Streaming_Metadata_Spec/HTTP_Live_Streaming_Metadata_Spec.pdf

=== Sample ID3 tags ===
* <code>www.nielsen.com/X100zdCIGeIlgZnkYj6UvQ==/X100zdCIGeIlgZnkYj6UvQ==/AAAB2Jz2_k74GXSzx4npHuI_JwJd3QSUpW30rDkGTcbHEzIMWleCzM-uvNOP9fzJcQMWQLJqzXMCAxParOb5sGijSV9dNM3QiBniJYGZ5GI-lL1fXTTN0IgZ4iWBmeRiPpS9AAAAAAAAAAAAAAAAAAAAAFJWFM5SVhTONNU=/00000/00000/00</code>
* <code>www.nielsen.com/X100zdCIGeIlgZnkYj6UvQ==/R8WHe7pEBeqBhu8jTeXydg==/AAICoyitYqlxT7n6aZ0oMCGheFi4CXFp46AMUPZz1lMr_M9tr3_cjee1SHqxrOiVerMDLeyn9xzocZSKwi746Re8vNOtpNCAZjYABs_J0R25IHpvOc1HS8QHGgD5TgOJeS6gX100zdCIGeIlgZnkYj6UvVJWFNhSVhTiPE0=/00000/46016/00</code>
<blockquote>'''Note''': ID3 tags are not applicable for International (Germany)</blockquote>

== Browser Opt-Out Implementation ==
The site in which video content is being measure via Nielsen methodology must provide the means for the user to opt-out of, or opt back into Nielsen Measurement.

For Browser-based applications, opt-out setting is stored via Nielsen cookie. Therefore, it is only necessary that users be made aware of measurement opt-out by incorporating the template below in the user interface.

=== Sample Opt Out Template ===
Our properties may feature Nielsen’s proprietary measurement software which will allow to contribute to market research, like Nielsen’s TV Ratings. To learn more about this information, see http://www.nielsen.com/digitalprivacy. Nielsen’s software may collect your choices with regards to it.

== Nielsen Privacy Requirements ==
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.
[[File:RatingsDataFlow.png]]

'''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 ===
{| class="wikitable"
|-
! Type of Information !! Parameter !! Transmitted to Nielsen? !! Sent to Provider?
|-
| rowspan="8" | 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
|-
| rowspan="7" | Device/App Info
|-
| Device OSVersion || Yes || Yes
|-
| Device Model || Yes || No
|-
| Cache Buster || Yes || Yes
|-
| SDKDisabled Flag || Yes || No
|-
| ServerCode || Yes || No
|-
| Channel or URL || Yes || No
|-
| rowspan="9" | 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
|}
<blockquote>'''Note''': Data is hashed, and encrypted using AES 128 before transmission to data provider.</blockquote>

==== Example ping sent to provider ====
* <code><nowiki>https://provider.com/cgi-bin/brandlift.php</nowiki>?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</code>

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

=== Nielsen Measurement Opt-Out ===
The site must provide a means for the user to opt‐out of, or opt back into, Nielsen Measurement. A user can opt-out if they would prefer not to participate in any Nielsen online measurement research. To implement the opt‐out option, it is mandatory to include the following two items in the site’s privacy policy
* A notice that the player includes proprietary measurement software that allows users to contribute to market research (such as Nielsen TV Ratings)
* A link to the Nielsen Digital Measurement Privacy Policy at http://www.nielsen.com/digitalprivacy
On the Nielsen Digital Measurement Privacy Policy page, users can click '''Choices''' to read more detailed information about the measurement software, learn about their options with regard to Nielsen measurement, and, if they do not want to participate in Nielsen online measurement, click a link to receive an opt-out cookie.

The following paragraph is a template for an opt-out statement

<blockquote>Our properties may feature Nielsen proprietary measurement software, which will allow you to contribute to market research, such as Nielsen TV Ratings. To learn more about the information that Nielsen software may collect and your choices with regard to it, refer to Nielsen Digital Measurement Privacy Policy at http://www.nielsen.com/digitalprivacy.</blockquote>

For information, please see Opt-Out Implementation below.

=== Opt-Out Implementation ===
The site must provide the means for the user to opt-out of, or opt back into Nielsen Measurement.

'''Sample Opt Out Template'''

Our properties may feature Nielsen’s proprietary measurement software which will allow to contribute to market research, like Nielsen’s TV Ratings. To learn more about this information, please [http://www.nielsen.com/digitalprivacy| click here]. Nielsen’s software may collect your choices with regards to it.

== Testing ==
See [[Digital Measurement Testing#Testing Browser Implementation|Digital Measurement Testing - Testing Browser Implementation]].

Browser SDK API Reference

2017-07-12T19:05:41Z

Admin2: /* Nielsen Measurement Opt-Out */

{{Breadcrumb|}} {{Breadcrumb|Digital}} {{CurrentBreadcrumb}}
[[Category:Digital]]

== Setting up Development Environment ==
=== Step 1: Configure Content Management System (CMS) ===
Configure CMS to send the required values (see table below). Any internal CMS_variable names can be used for passing the data.

Ensure to capture these CMS_variable names in the SDK Configuration Form.

For more information on setting variable names, see the SDK Configuration Form included within the SDK package.

{| class="wikitable"
|-
! Required Data !! Description !! Value
|-
| dataSrc || Used when both CMS metadata and ID3 data are present in the player. Setting this field tells the SDK whether to use the CMS metadata or the ID3 payload to derive the pings || cms
|-
| sfcode || sfcode will be provided by Nielsen and specifies which Nielsen collection facility the app should connect to. Connect to a development server during development and switch to production server once app has been certified by Nielsen. || uat-cert dcr-cert
|-
| Asset Type || Type of asset: ad or content || preroll, midroll, postroll, or content
|-
| Asset ID || Unique identifier assigned to each asset || GUID, EIDR, ADID, or internal house ID
|-
| OCR Tag || OCR tag provided by Nielsen for implementation on the ad unit || Complete OCR URL
|-
| VC Program Name || VideoCensus program name. If no value is provided, DPR program name is populated in client-defined reporting in VC || Program name used for VC reporting
|-
| Title || Title of asset || Title used for reporting
|-
| Length || Duration of asset || Length in seconds, 86400 for live stream
|-
| Isfullepisode || Full episode flag “yes” or “lf” – full episode “no” or “sf” – non full episode
|-
| segA || Segment A (this is not available for video reporting as the episode title is reported) || custom value
|-
| segB || Segment B || custom value
|-
| segC || Segment C || custom value
|-
| crossId1 || Standard episode ID || custom value
|-
| crossId2 || Content originator (required only for distributors) || custom value
|-
| airdate || Original air date and time in Eastern Time. For non-US countries, it should be local time. || YYYYMMDD HH24:MI:SS
|}

==== Content Management System for Digital Audio ====
Digital Audio measurement is for digital-only audio content. For Digital Audio, clients should provide the parameters shown in CMS Table for Digital Audio.
{| class="wikitable"
|-
! Required Data !! Description !! Value
|-
| dataSrc ** || Source of the data. For Digital Audio, pass dataSrc as “cms”. || cms
|-
type || Type of content . For Digital Audio, set type as “radio”. || radio
|-
assetid || Station identifier, should include call letters and band. || WXYZ-FM
|-
stationType || OTA station flag and / or OTA station type 0: Custom station built per user 1: OTA streaming station with the same ad load 2: OTA station with a different ad load 3: Multicast eRadio or online station 4: On Demand Audio (podcasting) || 0, 1, 2, 3, or 4
|-
provider || Name of Provider || XYZ Provider
|}

=== Step 2: Complete the Nielsen SDK Configuration Form ===
The SDK is designed to map the <code>CMS_variable names</code>. To support the custom mapping, the developer is required to complete the SDK Configuration Form. The form will be provided during onboarding along with this guide.

== Initialization ==
=== Obtain the Nielsen Application ID (apid), sfcode and Browser SDK URLs ===
The Nielsen <code>apid</code> and <code>sfcode</code> are required to enable SDK functionality. Technical Account Manager will provide two apids and two sfcodes for each player configuration:
*'''Test apid and Test sfcode''': Use these IDs during development and testing
*'''Production apid and Production sfcode''': Use these IDs in production environment after Nielsen has tested and certified the player.
Browser SDK can support URLs that use any of the protocols – HTTPS and HTTP. Contact the Technical Account Manager to get the appropriate Browser SDK package that suits the requirements.

=== Initialize Browser SDK ===
To initialize the SDK, parameters must be passed when calling the initialization function (<code>ggInitialize</code>).

Create a global object with the values for the required parameters (sfcode, apid, apn, and nol_sdkDebug).
<syntaxhighlight lang="javascript">
<script type="text/javascript">
var _nolggGlobalParams =
{
apid: "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXX",
sfcode: "dcr-cert",
apn: "sample player name / site name",
nol_sdkDebug: "console"
};
</script>
</syntaxhighlight>
<blockquote>'''Note:''' Use the debug parameter, nol_sdkDebug, for testing only. Remove the parameter before moving to production.</blockquote>

To initialize the SDK , use the following methods:
<syntaxhighlight lang="javascript">
<script type="text/javascript">
var gg = window.NOLCMB.getInstance(instanceName /*optional*/);
gg.ggInitialize(window._nolggGlobalParams);
</syntaxhighlight>
If no parameters are passed to getInstance(), the default instance name is used.
<blockquote>'''Note:''' To create a new instance of the player, send a different / new unique string. Sending the same unique string re-initializes the existing instance of the player.</blockquote>
<blockquote>'''Note:''' To measure static content on a page and integrate the SDK with a player for video measurement, it is recommended to create one SDK instance using <code>_nolggGlobalParams.apid</code>.</blockquote>

=== SDK Initialization – Global Parameters ===
{| class="wikitable"
|-
! Parameters !! Description !! Value !! Required?
|-
| apid || UniqueID assigned to player/site. || Nielsen provided || Yes
|-
| apn || User-defined string value for describing the player/site. || Client provided || Yes
|-
| sfcode || Location of collection environment. During testing, all traffic should be directed to "dcr-cert". || "dcr-cert" – testing "dcr" – production || Yes
|-
| nol_sdkDebug || Enables Debug Mode which allows output to be viewed in console. || "console" || No
|}
<blockquote>'''Note:''' The debug parameter, <code>nol_sdkDebug</code>, is only used for testing and should be removed before moving to production. The output is displayed in console debuggers when enabled.</code>.</blockquote>

== Browser SDK API Methods & Properties ==
{| class="wikitable sortable"
|-
! Method / Property !! Event # !! DTVR !! DAR !! Digital Audio !! DCR !! International (Germany) !! Description
|-
| [[loadMetadata (Browser)]] || 3 || ✔ || ✔ || ✔ || ✔ || ✔ || Used when there is a preroll ad that needs to be associated with content metadata. The loadMetadata will first be called to populate the content metadata values and then the loadMetadata for ad metadata will be called. This allows sending a content ping with the ad info, even if the user bails out during the preroll ad.
|-
| [[play (Browser)]] || 5 || ✔ || ✘ || ✘ || ✔ || ✔ || 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. When the client passes in the channelName, they can change the CMS data stored by passing new values. If this event is not called then the “channel name” value populated will be the default value of “defaultChannelName”.

'''VA Beacon:''' Called when content or ads start playing. The playhead position must be passed.
|-
| [[sendID3 (Browser)]] || 55 || ✔ || ✘ || ✘ || ✘ || ✘ || Used to send the ID3 metadata.
|-
| [[setPlayheadPosition (Browser)]] || 49 || ✘ || ✘ || ✔ || ✔ || ✔ || Used to send the playhead position.
|-
| [[stop (Browser)]] || 7 || ✘ || ✘ || ✘ || ✔ || ✔ || Used when switching between ad and content or content and ad.
|-
| [[end (Browser)]] || 57 || ✔ || ✘ || ✔ || ✔ || ✔ || This is triggered 1) at the end of the content stream, 2) if the user switches to another piece of content 3) when the browser is refreshed or closed
|-
| [[staticstart (Browser)]] || 14 || ✘ || ✘ || ✘ || ✔ || ✔ || Used to send the metadata for the static page.
|-
| [[getOptOutStatus (Browser)]] || 4 || ✘ || ✘ || ✘ || ✘ || ✔ || '''VA Beacon Only:''' Sent only after calling stop. The current position must be passed. Not needed for new International (Germany) implementations.
|-
| [[updateOTT (Browser)]] || - || ✘ || ✘ || ✘ || ✘ || ✔ || Used to notify Browser SDK that the remote OTT device (like Google ChromeCast, Roku, Amazon FireTV, etc.) is connected / disconnected (change of OTT status).
|-
| [[ onPaginate (Browser)]] || 30 || ✘ || ✘ || ✘ || ✔ || ✔ || Used to create a new instance of the SDK object
|-
| [[updateMetadata (Browser)]] || 35 || ✔ || ✔ || ✔ || ✔ || ✔ || This event is used for updating metadata parameters for the content or ad that is being played.
|}

== Retrieving ID3 Tags ==
The video player must have the ability to extract ID3 tags and supply them to the Browser SDK, based on the HLS standard.
*An ID3 tag spans two PES packets.
**In the first PES packet, look for www.nielsen.com, this is the start of the ID3 tag. Continue to parse the first PES packet until the undefined char "\ufffd" is found. This forms the first half of the ID3 tag
**In the second PES packet, identify the end pattern – a regEx of /(\/\d+){3}/ and look to remove the lowest index of either "\x00" and/or "\ufffd". Now the second packet has been appended and the demarcation of the Nielsen-specific data has been defined.

Follow the procedure below, to extract Nielsen ID3 tags from an MPEG-2 transport stream (including HLS streams).
#Parse the Program Map Table (PMT) to find the PID of the metadata stream. Confirm the presence of the metadata descriptor described in section 2.3.3 of Apple’s “HTTP Live Streaming Metadata Spec.pdf”. Only private streams with metadata descriptor present should be considered as ID3-tag metadata streams.
#Parse the HLS/Transport stream for any '''PES header''' with the PID found in step 1.
#Follow standard MPEG-2 parsing procedures to locate the start of the payload of the PES packet.
#Copy the PES payload into a buffer.
#The ID3 tag spans 2 PES packets. Parse the stream for the next packet whose PID is set to the PID found in step 1. Typically the ID3 Tag is of 249 bytes. The steps below guide towards extraction of the ID3 tag
##In the first PES packet, look for "www.nielsen.com" , this is the start of the ID3 tag. Keep on parsing the first PES packet until the undefined char "\ufffd" is found. This forms the first half of the ID3 tag
##In the second PES packet, identify the end pattern, a regEx of /(\/\d+){3}/ and look to remove the lowest index of either “\x00” and/or “\ufffd”. Now the second packet has been appended and the demarcation of the Nielsen specific data has been defined. This segment can be simply substringed.
##Concatenate this substringed segment with the payload derived from the first packet get the ID3 payload.
#Check the length of the contents in the buffer to make sure that it is equal to the size of a Nielsen ID3 tag.
#Ensure that the ID3 byte array is converted into the string and escape it, so that the SDK can consume it.
Repeat steps 2 through 7 for all ID3 tags in the stream.

'''References'''
*[http://www.iso.org/iso/catalogue_detail?csnumber=44169. ISO/IEC 13818-1:2007] Information technology – Generic coding of moving pictures and associated audio information: Systems
*https://developer.apple.com/library/ios/sdk/developers/AudioVideo/Conceptual/HTTP_Live_Streaming_Metadata_Spec/HTTP_Live_Streaming_Metadata_Spec.pdf

=== Sample ID3 tags ===
* <code>www.nielsen.com/X100zdCIGeIlgZnkYj6UvQ==/X100zdCIGeIlgZnkYj6UvQ==/AAAB2Jz2_k74GXSzx4npHuI_JwJd3QSUpW30rDkGTcbHEzIMWleCzM-uvNOP9fzJcQMWQLJqzXMCAxParOb5sGijSV9dNM3QiBniJYGZ5GI-lL1fXTTN0IgZ4iWBmeRiPpS9AAAAAAAAAAAAAAAAAAAAAFJWFM5SVhTONNU=/00000/00000/00</code>
* <code>www.nielsen.com/X100zdCIGeIlgZnkYj6UvQ==/R8WHe7pEBeqBhu8jTeXydg==/AAICoyitYqlxT7n6aZ0oMCGheFi4CXFp46AMUPZz1lMr_M9tr3_cjee1SHqxrOiVerMDLeyn9xzocZSKwi746Re8vNOtpNCAZjYABs_J0R25IHpvOc1HS8QHGgD5TgOJeS6gX100zdCIGeIlgZnkYj6UvVJWFNhSVhTiPE0=/00000/46016/00</code>
<blockquote>'''Note''': ID3 tags are not applicable for International (Germany)</blockquote>

== Browser Opt-Out Implementation ==
The site in which video content is being measure via Nielsen methodology must provide the means for the user to opt-out of, or opt back into Nielsen Measurement.

For Browser-based applications, opt-out setting is stored via Nielsen cookie. Therefore, it is only necessary that users be made aware of measurement opt-out by incorporating the template below in the user interface.

=== Sample Opt Out Template ===
Our properties may feature Nielsen’s proprietary measurement software which will allow to contribute to market research, like Nielsen’s TV Ratings. To learn more about this information, see http://www.nielsen.com/digitalprivacy. Nielsen’s software may collect your choices with regards to it.

== Nielsen Privacy Requirements ==
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.
[[File:RatingsDataFlow.png]]

'''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 ===
{| class="wikitable"
|-
! Type of Information !! Parameter !! Transmitted to Nielsen? !! Sent to Provider?
|-
| rowspan="8" | 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
|-
| rowspan="7" | Device/App Info
|-
| Device OSVersion || Yes || Yes
|-
| Device Model || Yes || No
|-
| Cache Buster || Yes || Yes
|-
| SDKDisabled Flag || Yes || No
|-
| ServerCode || Yes || No
|-
| Channel or URL || Yes || No
|-
| rowspan="9" | 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
|}
<blockquote>'''Note''': Data is hashed, and encrypted using AES 128 before transmission to data provider.</blockquote>

==== Example ping sent to provider ====
* <code><nowiki>https://provider.com/cgi-bin/brandlift.php</nowiki>?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</code>

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

=== Nielsen Measurement Opt-Out ===
The site must provide a means for the user to opt‐out of, or opt back into, Nielsen Measurement. A user can opt-out if they would prefer not to participate in any Nielsen online measurement research. To implement the opt‐out option, it is mandatory to include the following two items in the site’s privacy policy
* A notice that the player includes proprietary measurement software that allows users to contribute to market research (such as Nielsen TV Ratings)
* A link to the Nielsen Digital Measurement Privacy Policy at http://www.nielsen.com/digitalprivacy
On the Nielsen Digital Measurement Privacy Policy page, users can click '''Choices''' to read more detailed information about the measurement software, learn about their options with regard to Nielsen measurement, and, if they do not want to participate in Nielsen online measurement, click a link to receive an opt-out cookie.

The following paragraph is a template for an opt-out statement

<blockquote>Our properties may feature Nielsen proprietary measurement software, which will allow you to contribute to market research, such as Nielsen TV Ratings. To learn more about the information that Nielsen software may collect and your choices with regard to it, refer to Nielsen Digital Measurement Privacy Policy at http://www.nielsen.com/digitalprivacy.</blockquote>

For information, please see Opt-Out Implementation below.

=== Opt-Out Implementation ===

== Testing ==
See [[Digital Measurement Testing#Testing Browser Implementation|Digital Measurement Testing - Testing Browser Implementation]].

Android SDK API Reference

2017-07-12T18:55:19Z

Admin2: /* Nielsen Privacy Requirements */

{{Breadcrumb|}} {{Breadcrumb|Digital}} {{CurrentBreadcrumb}}
[[Category:Digital]]
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.
*Create and initialize an instance object of <code>AppSdk</code> class.
*The player application can use this object to collect HLS timed metadata through a [[sendID3()]] call.
The Nielsen App SDK class is defined as the only public class belonging to the com.nielsen.app.sdk package. It inherits from the closeable interface and exposes the public APIs the client’s app will use. Below is the declaration of the <code>AppSdk</code> class: <code>public class AppSdk implements Closeable</code>

== Setting Up Development Environment ==
'''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.
<blockquote>'''Note''': App SDK 4.0.0 contains AppSDK.jar component only and does not support C/C++ libAppSdk.so components.</blockquote

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.

=== Setting up in Eclipse IDE ===
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.
<syntaxhighlight lang="java"><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"/></syntaxhighlight>
For more details to handle runtime permissions in Android versions, please visit [https://developer.android.com/training/permissions/requesting.html]. 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.

[[File:andr-properties-drm.jpg|link=]]

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

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

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.
Nielsen App SDK uses the following packages/classes from the Google Play service.

'''Library''':
* 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;

=== Setting up in Android Studio IDE ===
Launch '''Android Studio''' and select '''Import project (Eclipse ADT)'''.

[[File:andr-setup-launch.jpg|link=]]

Browse for project destination directory and click '''Next'''.

[[File:andr-import-project.jpg|link=]]

Go to '''File > Project Structure > App > Dependencies'''.

[[File:andr-pro-structure.jpg|link=]]

Click '''+''' to add library dependency.

Select '''play-services''' and click '''OK'''

[[File:andr-choose-library.jpg|link=]]

For more information, refer to https://developer.android.com/google/play-services/setup.html

== Initialization ==
=== Android Application Life Cycle with respect to Nielsen App SDK ===
[[File:andr-init-img1.jpg|link=]]

=== Step 1: App SDK initialization ===
==== For API version 4.0.0 and above ====

[[AppSDK()]] is no longer a singleton object and should be initialized as below.

'''Initialization of App SDK object through a JSON object'''
<syntaxhighlight lang="objective-c">
JSONObject config = null;

try
{
// Prepare AppSdk configuration object (JSONObject)
JSONObject appSdkConfig = new JSONObject()
.put("appid", "TXXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX")
.put("appname", "Sample App Name")
.put("sfcode", "uat-cert")
.put("nol_devDebug", "INFO") // only for debug builds
.put("custom_key1", "custom_value1")
.put("custom_key2", "custom_value2");
// 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);
}
</syntaxhighlight>

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

==== Android Application Life Cycle with respect to Nielsen App SDK ====
[[File:andr-radioandvideo-app.jpg|link=]]

=== Step 2: App SDK libraries inclusion in project ===
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).

=== Step 3: Nielsen App SDK Streaming Sessions ===
After ensuring that the SDK object has been initialized, link the streaming session APIs. The next steps are:
*Call [[play()]] when starting or resuming a streaming session. Use the channelName parameter to pass channel descriptor information. The channel name field is a 32-character free-form text field containing the name of the program or feed being sent (such as ESPN2, Food Network, etc.) which must be inserted on a JSON string.
*Load the CMS metadata by calling the [[loadMetadata()]] on the SDK object.
*Call [[stop()]] when ending or pausing a viewing session.
*During session playback, call the SDK [[setPlayheadPosition()]] and / or [[sendID3()]]
**Call [[setPlayheadPosition()]] every one second until the stream is stopped or paused. Normally this happens on Digital Audio measurements.
**Call [[sendID3()]] if the client relies on the Nielsen ID3 tags for its measurements; this call should happen whenever a new Nielsen ID3 metadata is available for processing. Normally this happens on DTVR and ID3 measurements.
Nielsen App SDK object handles filtering of ID3 tags and CMS tags, queuing/buffering of data, and all communications with Nielsen collection facility.
*The client’s app must clearly identify the mode of operation (live vs. VOD) and stick to the type of playhead coordinates until the playback is completed. The client must reliably provide the appropriated playhead position value depending on the type of content streamed.
*If streaming live video content, the client must pass the current UTC time in seconds as playhead position.
*If streaming VOD (video on demand), the client must stream the offset from the beginning of the file as playhead position.
*For all Digital Audio listening, the client must pass the current UTC time in seconds as playhead position, regardless of station type.

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

=== Sample ID3 tags ===
* <code>www.nielsen.com/X100zdCIGeIlgZnkYj6UvQ==/X100zdCIGeIlgZnkYj6UvQ==/AAAB2Jz2_k74GXSzx4npHuI_JwJd3QSUpW30rDkGTcbHEzIMWleCzM-uvNOP9fzJcQMWQLJqzXMCAxParOb5sGijSV9dNM3QiBniJYGZ5GI-lL1fXTTN0IgZ4iWBmeRiPpS9AAAAAAAAAAAAAAAAAAAAAFJWFM5SVhTONNU=/00000/00000/00</code>
* <code>www.nielsen.com/X100zdCIGeIlgZnkYj6UvQ==/R8WHe7pEBeqBhu8jTeXydg==/AAICoyitYqlxT7n6aZ0oMCGheFi4CXFp46AMUPZz1lMr_M9tr3_cjee1SHqxrOiVerMDLeyn9xzocZSKwi746Re8vNOtpNCAZjYABs_J0R25IHpvOc1HS8QHGgD5TgOJeS6gX100zdCIGeIlgZnkYj6UvVJWFNhSVhTiPE0=/00000/46016/00</code>
<blockquote>'''Note''': ID3 tags are not applicable for International (Germany)</blockquote>

=== Extracting ID3 tags from Android Players ===
==== ID3 Support Matrix ====
{| class="wikitable"
|-
! Player Name !! Minimum supported version !! Description
|-
| Android Native Media Player || Android 6 || Android 6 Media Player allows apps to register a callback to be invoked, when a selected track has the timed metadata available. Currently, only HTTP Live Streaming (HLS) data URI’s embedded with timed ID3 tags, generates TimedMetaData.
|-
| Google ExoPlayer || Android 4.1 ||
|-
| Brightcove Player || Android 4.1 || Support for Android versions 2.3.3 and 4.0 is now deprecated. Learn more about why Brightcove is removing support for these versions as of January 1, 2016 in this [https://support.brightcove.com/en/perform/docs/announcement-brightcove-sdk-android-version-support|announcement]
|-
| Adobe PrimeTime Player || Android 4.2 ||
|-
| VisualOn Player || Android 2.3 || Android 5 is the latest supported version
|-
| NexStream Player || Android 1.6 || Supported till Android 6
|}

==== Android Native Media Player ====
As the Android Media Player versions (prior to Android 6 / Android API 23) do not support ID3, Nielsen has created a library that becomes an extension to the media player, thus MPX. This library extracts the ID3 tags and sends them to the app. For more information on how to use the MPX component, refer to the Nielsen-supplied sample application.

Starting from '''Android 6 (Android API 23)''', Android Native Media Player allows apps to register a callback to be invoked, when a selected track has the timed metadata available. Currently, only HTTP Live Streaming (HLS) data URI’s embedded with timed ID3 tags generate TimedMetadata. Once the HLS video starts, call onTimedMetaDataAvailable() as and when the player observes a TimedMetadata (ID3 tag).

<syntaxhighlight lang="java">@Override
public void onTimedMetaDataAvailable(MediaPlayer mp, TimedMetaData data)
{
byte[] iD3PayloadArray = data.getMetaData();
String iD3Payload = new String(iD3PayloadArray, StandardCharsets.UTF_8);
if (null != iD3Payload && iD3Payload.contains("www.nielsen.com"))
{
int index = iD3Payload.indexOf("www.nielsen.com");
String id3String = iD3Payload.substring(index, (index + 249));
Log.d(TAG, "TimedMetaData ID3 Tag:" + id3String);
appProcessID3tag(id3String);
}
}</syntaxhighlight>

==== ExoPlayer ====
he SDK is designed around an event-driven architecture where components emit events to allow other components to listen and respond to state changes.

'''Player SDK Classes used:'''
<syntaxhighlight lang="java">com.google.android.exoplayer.demo.player.DemoPlayer</syntaxhighlight>

Since Nielsen App SDK is interested in extracting the Timed Metadata (ID3 Tags) in HLS and VOD on the EXO Player, trace the ID3_TAG emitted during video content played using EXOPlayer component as below.

<syntaxhighlight lang="java">DemoPlayer implements ExoPlayer.Listener
—————————————————–
/**
* A listener for receiving ID3 metadata parsed from the media stream.
*/
public interface Id3MetadataListener
{
void onId3Metadata(Map<String, Object> metadata);
}
——————————————————-
MetadataTrackRenderer.MetadataRenderer<Map<String,
Object>> getId3MetadataRenderer()
{
return new MetadataTrackRenderer.MetadataRenderer<Map<String, Object>>()
{
@Override
public void onMetadata(Map<String, Object> metadata)
{
if (id3MetadataListener != null)
{
id3MetadataListener.onId3Metadata(metadata);
}
}
};
}</syntaxhighlight>

Also in ''Player.java'' class:
<syntaxhighlight lang="java">Player implements DemoPlayer.Id3MetadataListener
—————————————————–
@SuppressWarnings("rawtypes")
@Override
public void onId3Metadata(Map<String, Object> metadata)
{
try
{
for (Object o : metadata.entrySet())
{
Map.Entry pairs = (Map.Entry) o;
if (metadata.containsKey(TxxxMetadata.TYPE))
{
TxxxMetadata txxxMetadata = (TxxxMetadata) metadata
.get(TxxxMetadata.TYPE);
}
else
{
String aStr = new String((byte[]) pairs.getValue());
MainActivity.mAppSdk.sendID3(aStr);
}
}
}
catch (Exception e)
{
e.printStackTrace();
Log.d(TAG, "onId3Metadata(): No Id3 tags");
}
}</syntaxhighlight>

[[File:andr-exo-retrievingID3tags.png|link=]]

==== Brightcove Player ====
While the Brightcove player plays the content, EventListener triggers an event when an ID3 packet is received (<code>SeamlessVideoDisplayComponent.ID3_TAG</code>). Upon receiving this event, collect the incoming ID3 tags and only pass the Nielsen payload of the PRIV frame to the App SDK for analysis.

<syntaxhighlight lang="java">brightcoveVideoView.getEventEmitter().on(SeamlessVideoDisplayComponent.ID3_TAG, new EventListener()
{
public void processEvent(Event event)
{
NlsId3Tag nlsID3 = new NlsId3Tag(event.properties.get(SeamlessVideoDisplayComponent.ID3_DATA).toString());
Log.w("ID3", nlsID3.NlsPayload);
// Sent ID3 Tags to App
appProcessID3tag(nlsID3.NlsPayload);
}
});
}</syntaxhighlight>

==== Adobe PrimeTime Player ====
While the Adobe PrimeTime player plays the content, MediaPlayer.PlaybackEventListener triggers a callback when an ID3 packet is received (onTimedMetadata). Upon receiving this event, collect the incoming ID3 tags and only pass the Nielsen payload of the PRIV frame to the App SDK for analysis.
<syntaxhighlight lang="java">public void onTimedMetadata(TimedMetadata id3Metadata)
{
NlsId3Tag nlsID3 = new NlsId3Tag(id3Metadata.getMetadata().toString());
Log.w(LOG_TAG, "ID3 Timed Data –> " + nlsID3.NlsPayload);
Log.w(LOG_TAG, "PayLoad Size –> " + nlsID3.NlsPayload.length());
appProcessID3tag(nlsID3.NlsPayload);
}</syntaxhighlight>

==== VisualOn Player ====
While the VisualOn player plays the content, <code>VOCommonPlayerListener</code> triggers an event when an ID3 packet is received (<code>VO_OSMP_SRC_CUSTOMERTAGID_TIMEDTAG</code>). Upon receiving this event, collect the incoming ID3 tags and only pass the Nielsen payload of the PRIV frame to the App SDK for analysis.

<syntaxhighlight lang="java">case VO_OSMP_SRC_CB_CUSTOMER_TAG:
{
VO_OSMP_SRC_CUSTOMERTAGID tag = VO_OSMP_SRC_CUSTOMERTAGID.valueOf(nParam1);
switch (tag)
{
case VO_OSMP_SRC_CUSTOMERTAGID_TIMEDTAG:
// do something with this tag
int time = nParam2;
byte[] b = (byte[]) obj;
String s = new String(b);
NlsId3Tag nlsID3 = new NlsId3Tag(b);
// Sent ID3 Tags to App
appProcessID3tag(nlsID3.NlsPayload);
if (appid3If != null)
appid3If.onId3(nlsID3.NlsPayload);
break;
case VO_OSMP_SRC_CUSTOMERTAGID_MAX:
// ignore this type of tag
break;
default:
break;
}
break;
}</syntaxhighlight>

==== NextStream Player ====
ID3 tags will be received in the NexStream Player through <code>onTimedMetaRenderRender(NexPlayer mp,NexID3TagInformation metadata)</code> callback API. A sample implementation for the callback is shown below:
<syntaxhighlight lang="java">public void onTimedMetaRenderRender(NexPlayer mp, NexID3TagInformation m)
{
text = m.getPrivateFrame();
if (text != null)
{
data = text.getTextData();
if (data != null)
{
// make sure to identify the beginning of the
// Nielsen ID3 tag payload by searching for the
// "www.nielsen.com" string on the ID3 tag and
// passing to the App SDK all information that
// follows. It should be:
// nlsPayload = "www.nielsen.com" + dataFollowing
nlsPayload = getDataAfterWwwNielsenCom(data);
if (nlsPayload!= NULL)
mAppSdk.sendID3(nlsPayload);
}
}
}</syntaxhighlight>

The [[sendID3()]] sends the extracted Nielsen ID3 payload to the App SDK for analysis.

== Android SDK API Methods & Properties ==
{| class="wikitable sortable"
|-
! Scenario !! Method / Property !! DTVR !! DAR !! Digital Audio !! DCR !! International (Germany) !! Description
|-
| Initialize || [[AppSDK()]] || ✔ || ✔ || ✔ || ✔ || ✔ || 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 when there is a preroll ad that needs to be associated with content metadata. The loadmetadata will first be called to populate the content metadata values and then the loadMetadata for ad metadata will be called. This allows sending a content ping with the ad info, even if the user bails out during the preroll ad.
|-
| Measurement || [[sendID3()]] || ✔ || ✘ || ✘ || ✘ || ✘ || Used to send the ID3 metadata.
|-
| Measurement || [[setPlayheadPosition()]] || ✘ || ✘ || ✔ || ✔ || ✔ || 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 || [[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 || [[userOptOutURLString()]] || ✔ || ✔ || ✔ || ✔ || ✔ || 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 || [[getOptOutStatus()]] || ✘ || ✘ || ✘ || ✘ || ✔ || Call this API to retrieve the Opt-Out or Opt-In state.
|-
| Opt-out
| [[appDisableApi()]]
(kill switch)
|| ✔ || ✔ || ✔ || ✔ || ✔ || Used to disable the SDK.
|-
| Opt-out || [[getAppDisable()]] || ✔ || ✔ || ✔ || ✔ || ✔ || Used to query if the SDK is disabled or not.
|-
| Log || [[getLastEvent()]] || ✔ || ✔ || ✔ || ✔ || ✔ || Used to query the SDK for the last status
|-
| Log || [[getLastError()]] || ✔ || ✔ || ✔ || ✔ || ✔ || Used to query the SDK for the last error
|-
| Log || [[isValid()]] || ✔ || ✔ || ✔ || ✔ || ✔ || Used to check if the SDK was successfully instantiated or not.
|-
| Log || [[getMeterVersion()]] || ✘ || ✘ || ✘ || ✘ || ✔ || Returns the current SDK version.
|-
| Log || [[getNielsenId()]] || ✔ || ✔ || ✔ || ✔ || ✔ || Used to get a string defining the Nielsen ID (NUID) number for the device.
|-
| Log || [[getDeviceId()]] || ✔ || ✔ || ✔ || ✔ || ✔ || Returns the current device id.
|-
| Log || [[appInBackground()]] || ✘ || ✘ || ✘ || ✔ || ✔ || Used to capture the event of app going to background.
|-
| Log || [[appInForeground()]] || ✘ || ✘ || ✘ || ✔ || ✔ || Used to capture the event of app coming to foreground
|-
| Log || [[setDebug()]] || ✘ || ✘ || ✘ || ✘ || ✔ || Used to enable/disable debug flags. Newly introduced in SDK version 5.0.0 for International (Germany)
|}

== 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.
*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.

=== Displaying Opt-Out in a WebView ===
<syntaxhighlight lang="java">
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
}
</syntaxhighlight>

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.

[[File:Privacy policy iOS.jpg|link=]]

<blockquote>'''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.</blockquote>

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

=== Sequence Diagram ===
[[File:optoutsequence-andr.jpg|link=]]

== Opt-out Android SDK Version '''5.1.1.18 or above''' ==
<blockquote>'''Note:''' If using Android SDK Versions 1.2.3, 4.0.0.8, 5.1.0, 5.1.1.14, skip ahead to: [[#Opt-out Android SDK Version 1.2.3, 4.0.0.8, 5.1.0, 5.1.1.14|Opt-out Android SDK Version 1.2.3, 4.0.0.8, 5.1.0, 5.1.1.14]]</blockquote>

Starting from SDK version 5.1.1.18, Opt-Out related behavior has been changed in the following ways:
*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'''.
<blockquote>'''Note:''' For Amazon devices, see [[#Opt-Out Implementation for Amazon Devices|Opt-Out Implementation for Amazon Devices]] below.</blockquote>

[[File:andr-ads.jpg|link=]]

<blockquote>'''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.</blockquote>

== Opt-out Android SDK Version '''1.2.3, 4.0.0.8, 5.1.0, 5.1.1.14''' ==
<blockquote>'''Note:''' If using Android SDK Version 5.1.1.18 or above, refer to documentation above ([[#Opt-out Android SDK Version 5.1.1.18 or above|Opt-out Android SDK Version 5.1.1.18 or above]])</blockquote>

When a user clicks the Opt-Out / Opt-In link, the application should invoke [[optOutURL]] to get the link to the Nielsen Privacy page from SDK.
=== Privacy Page ===
[[File:privacy-policy.jpg|link=]]
*There are two click here links – one for Opt-Out and one for Opt-In. Click the required link:
**Capture user’s selection
**Pass the selection back to the SDK via the [[userOptOut()]].

=== Capture and forward user selection ===
<syntaxhighlight lang="java">
private class MonitorWebView extends WebViewClient
{
private static final String NIELSEN_URL_OPT_OUT = “nielsenappsdk://1”;
private static final String NIELSEN_URL_OPT_IN = “nielsenappsdk://0”;

@Override
public boolean shouldOverrideUrlLoading(WebView view, String url)
{
if (NIELSEN_URL_OPT_OUT.equals(url)
|| NIELSEN_URL_OPT_IN.equals(url))
{
// Get AppSdk instance from the host
AppSdk appSdk = HostApp.getAppSdk();
// Send the URL to the AppSdk instance
appSdk.userOptOut(url);
return true;
}
return false;
}
}
</syntaxhighlight>

<blockquote>'''Note:''' When 'WebView' is closed, pass the status returned from 'WebView' to the SDK within the app.</blockquote>
<blockquote>'''Note:''' App SDK manages the user's choice (Opt-Out / Opt-In), the app does not need to manage this status.</blockquote>

== 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 ===

<syntaxhighlight lang="java">
ContentResolver cr = getContentResolver();
int limitAdTracking = Secure.getInt(cr, "limit_ad_tracking", 2);
</syntaxhighlight>

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

<blockquote>'''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'''.</blockquote>

== Nielsen Sample Applications ==

== Nielsen Privacy Requirements ==
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.
[[File:RatingsDataFlow.png]]

'''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 ===
{| class="wikitable"
|-
! Type of Information !! Parameter !! Transmitted to Nielsen? !! Sent to Provider?
|-
| rowspan="8" | 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
|-
| rowspan="10" | 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
|-
| rowspan="9" | 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
|}
<blockquote>'''Note''': Data is hashed, and encrypted using AES 128 before transmission to data provider.</blockquote>

==== Example ping sent to provider ====
* <code><nowiki>https://provider.com/cgi-bin/brandlift.php</nowiki>?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</code>

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

=== Opt-Out Implementation ===
==== Limit Ad Tracking ====

Opt-Out Implementation (Limit Ad Tracking)

'''This implementation is valid for SDK Versions 5.1.1.18 and above.'''

If using SDK Version 1.2.3, 4.0.0.8, 5.1.0 or 5.1.1.14, refer to Legacy Opt-Out.

As a global information and measurement leader, Nielsen is committed to protect the privacy and security of the data they collect, process and use. Nielsen strongly believes that the consumer should have a way to Opt-Out of Nielsen measurement.

The Nielsen digital measurement products help Nielsen and its clients to measure and analyze how consumers engage with media across online, mobile and emerging technologies while offering insights into consumer behavior.

To learn more about our digital measurement products and your choices in regard to them, please visit http://www.nielsen.com/digitalprivacy.

To opt out, users must have access to Nielsen “About Nielsen Measurement” page from within the 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.
* 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.

'''Displaying Opt-Out in a WebView'''
<syntaxhighlight lang="java">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
}</syntaxhighlight>
<blockquote>'''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.</blockquote>

Starting from SDK version 5.1.1.16, Opt-Out related behavior has been changed in multiple ways as mentioned below.
* 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'''.

<blockquote>'''Note''': For more information on FireTV please see Opt-Out Implementation in Amazon Devices.</blockquote>

'''Opting out through Google Settings'''

[[File:andr-ads.jpg]]

'''What SDK integration do developers need to take care of?'''
* Get the Opt-Out URL from SDK in order to show the page to end users in a ‘WebView’ / External browser. There is no change in this process.
* Do not handle/pass the response which is received from the hyperlinks for Opt-Out / Opt-In operations, as these hyperlinks will no longer exist.
* Ensure to provide a button which can close/exit the optout page screen

'''Latest Opt-Out Page'''

[[File:privacy_policy_andr.jpg]]

<blockquote>'''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.</blockquote>
<blockquote>'''Note''': App SDK manages the user’s choice (Opt-Out / Opt-In), the app does not need to manage this status.</blockquote>

'''Sequence Diagram'''

[[File:optoutsequence-andr.jpg]]

==== 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'''
<syntaxhighlight lang="java">ContentResolver cr = getContentResolver();
int limitAdTracking = Secure.getInt(cr, "limit_ad_tracking", 2);</syntaxhighlight>
* 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).
<blockquote>'''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'''.</blockquote>

== Event and Error Handling ==
=== App SDK Error Codes ===
Constants with predefined error codes which the AppSdk object can generate.
<syntaxhighlight lang="java">public static final int ERROR_FAILED_CREATE_URL_STRING = 1001;
// failed generating ping string due to error on parsing
// description – include last error message from URL parser
public static final int ERROR_FAILED_RECEIVE_CONFIG = 1002;
// failed to receive configuration file from Census
// description – on 5th time, it will log event and keep requesting config 10 min apart
public static final int ERROR_FAILED_PARSING_CONFIG = 1003;
// failed parsing the config file JSON string
// description – include json error number/short message from iOS or Android
public static final int ERROR_FAILED_PARSING_PLAY = 1004;
// failed parsing the play() JSON string
// description – include json error number/short message from iOS or Android
public static final int ERROR_FAILED_PARSING_METADATA = 1005;
// failed parsing the play() JSON string
// description – include JSON error number/short message from iOS or Android
public static final int ERROR_FAILED_GENERATING_PING = 1006;
// failed creating ping before adding it to the UPLOAD table)
// description – include ping nol_url index, cadence to identify ping
public static final int ERROR_FAILED_PROCESSOR_START = 1007;
// failed starting data processor thread. Normally, that means a product
// description – include processor that failed to start
public static final int ERROR_FAILED_PROCESS_ID3 = 1008;
// failed processing data on a data processor. Normally, that means the input to a product
// description – include processor and data that failed to process (ID3 tag on a MTVR impression, for example)
public static final int ERROR_FAILED_HTTP_SEND = 1009;
// failed sending HTTP or HTTPS requests
// description – include HTTP error number
public static final int ERROR_FAILED_SENDING_PING = 1010;
// failed sending pings (on ANDROID, the ping on the UPLOAD table)
// description – include ping up to 80 char from the end
public static final int ERROR_FAILED_SENDING_TSV = 1011;
// failed sending TSV requests
// description – include TSV request message
public static final int ERROR_FAILED_SENDING_STATION_ID = 1012;
// failed sending StationId requests
// description – include Station ID request message
public static final int ERROR_FAILED_ACCESSING_DB = 1013;
// failed read/write from/to database table
// description – include SQL statement and data and SQLite error number/message
public static final int ERROR_CHANGED_DEVICE_ID = 1014;
// device ID changed
// description – none
public static final int ERROR_CHANGED_NUID = 1015;
// NUID changed
// description – none
public static final int ERROR_SDK_NOT_INITIALIZED = 1016;
// App SDK initialization failed
// description – none
public static final int ERROR_FAILED_SDK_SUSPEND = 1017;
// App SDK failed to suspend activities
// description – none
public static final int ERROR_INVALID_PARAMETERS = 1018;
// App SDK invalid parameters
// description – none
public static final int ERROR_INVALID_STATE = 1019;
// App SDK called in incorrect state
// description – none
public static final int ERROR_FAILED_PROCESS_PLAYHEAD = 1020;
// App SDK failed processing playhead position
// description – none
public static final int ERROR_FAILED_PROCESS_METADATA = 1021;
// App SDK failed processing not-null, syntax valid JSON metadada
// description – none
public static final int ERROR_FAILED_PROCESS_STOP = 1022;
// App SDK failed processing stop
// description – none</syntaxhighlight>

=== App SDK Event Codes ===
<syntaxhighlight lang="java">public static final int EVENT_INITIATE = 2000;
// App SDK is initiated. It will happen as soon as the App SDK is initialized
public static final int EVENT_STARTUP = 2001;
// App SDK has started up. It will happen only after App SDK has received a valid config file. This is the location in the code to acquire the value of userOptOutURLString().
public static final int EVENT_SHUTDOWN = 2002;
// App SDK is shutting down. It will happen just before App SDK is destroyed</syntaxhighlight>

'''App SDK Event Codes '''
{| class="wikitable"
|-
! Event Code !! Event Name !! Event Description
|-
| 2000 || EVENT_INITIATE || App SDK is initiated. It will happen as soon as the App SDK is initialized
|-
| 2001 || EVENT_STARTUP || App SDK has started up. It will happen only after App SDK has received a valid config file
|-
| 2002 || EVENT_SHUTDOWN || App SDK is shutting down. It will happen just before App SDK is destroyed
|}

File:privacy policy andr.jpg

2017-07-12T18:50:01Z

Admin2:

Android SDK API Reference

2017-07-12T18:22:09Z

Admin2: /* Opt-out Android SDK Version 5.1.1.18 or above */

{{Breadcrumb|}} {{Breadcrumb|Digital}} {{CurrentBreadcrumb}}
[[Category:Digital]]
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.
*Create and initialize an instance object of <code>AppSdk</code> class.
*The player application can use this object to collect HLS timed metadata through a [[sendID3()]] call.
The Nielsen App SDK class is defined as the only public class belonging to the com.nielsen.app.sdk package. It inherits from the closeable interface and exposes the public APIs the client’s app will use. Below is the declaration of the <code>AppSdk</code> class: <code>public class AppSdk implements Closeable</code>

== Setting Up Development Environment ==
'''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.
<blockquote>'''Note''': App SDK 4.0.0 contains AppSDK.jar component only and does not support C/C++ libAppSdk.so components.</blockquote

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.

=== Setting up in Eclipse IDE ===
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.
<syntaxhighlight lang="java"><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"/></syntaxhighlight>
For more details to handle runtime permissions in Android versions, please visit [https://developer.android.com/training/permissions/requesting.html]. 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.

[[File:andr-properties-drm.jpg|link=]]

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

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

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.
Nielsen App SDK uses the following packages/classes from the Google Play service.

'''Library''':
* 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;

=== Setting up in Android Studio IDE ===
Launch '''Android Studio''' and select '''Import project (Eclipse ADT)'''.

[[File:andr-setup-launch.jpg|link=]]

Browse for project destination directory and click '''Next'''.

[[File:andr-import-project.jpg|link=]]

Go to '''File > Project Structure > App > Dependencies'''.

[[File:andr-pro-structure.jpg|link=]]

Click '''+''' to add library dependency.

Select '''play-services''' and click '''OK'''

[[File:andr-choose-library.jpg|link=]]

For more information, refer to https://developer.android.com/google/play-services/setup.html

== Initialization ==
=== Android Application Life Cycle with respect to Nielsen App SDK ===
[[File:andr-init-img1.jpg|link=]]

=== Step 1: App SDK initialization ===
==== For API version 4.0.0 and above ====

[[AppSDK()]] is no longer a singleton object and should be initialized as below.

'''Initialization of App SDK object through a JSON object'''
<syntaxhighlight lang="objective-c">
JSONObject config = null;

try
{
// Prepare AppSdk configuration object (JSONObject)
JSONObject appSdkConfig = new JSONObject()
.put("appid", "TXXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX")
.put("appname", "Sample App Name")
.put("sfcode", "uat-cert")
.put("nol_devDebug", "INFO") // only for debug builds
.put("custom_key1", "custom_value1")
.put("custom_key2", "custom_value2");
// 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);
}
</syntaxhighlight>

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

==== Android Application Life Cycle with respect to Nielsen App SDK ====
[[File:andr-radioandvideo-app.jpg|link=]]

=== Step 2: App SDK libraries inclusion in project ===
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).

=== Step 3: Nielsen App SDK Streaming Sessions ===
After ensuring that the SDK object has been initialized, link the streaming session APIs. The next steps are:
*Call [[play()]] when starting or resuming a streaming session. Use the channelName parameter to pass channel descriptor information. The channel name field is a 32-character free-form text field containing the name of the program or feed being sent (such as ESPN2, Food Network, etc.) which must be inserted on a JSON string.
*Load the CMS metadata by calling the [[loadMetadata()]] on the SDK object.
*Call [[stop()]] when ending or pausing a viewing session.
*During session playback, call the SDK [[setPlayheadPosition()]] and / or [[sendID3()]]
**Call [[setPlayheadPosition()]] every one second until the stream is stopped or paused. Normally this happens on Digital Audio measurements.
**Call [[sendID3()]] if the client relies on the Nielsen ID3 tags for its measurements; this call should happen whenever a new Nielsen ID3 metadata is available for processing. Normally this happens on DTVR and ID3 measurements.
Nielsen App SDK object handles filtering of ID3 tags and CMS tags, queuing/buffering of data, and all communications with Nielsen collection facility.
*The client’s app must clearly identify the mode of operation (live vs. VOD) and stick to the type of playhead coordinates until the playback is completed. The client must reliably provide the appropriated playhead position value depending on the type of content streamed.
*If streaming live video content, the client must pass the current UTC time in seconds as playhead position.
*If streaming VOD (video on demand), the client must stream the offset from the beginning of the file as playhead position.
*For all Digital Audio listening, the client must pass the current UTC time in seconds as playhead position, regardless of station type.

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

=== Sample ID3 tags ===
* <code>www.nielsen.com/X100zdCIGeIlgZnkYj6UvQ==/X100zdCIGeIlgZnkYj6UvQ==/AAAB2Jz2_k74GXSzx4npHuI_JwJd3QSUpW30rDkGTcbHEzIMWleCzM-uvNOP9fzJcQMWQLJqzXMCAxParOb5sGijSV9dNM3QiBniJYGZ5GI-lL1fXTTN0IgZ4iWBmeRiPpS9AAAAAAAAAAAAAAAAAAAAAFJWFM5SVhTONNU=/00000/00000/00</code>
* <code>www.nielsen.com/X100zdCIGeIlgZnkYj6UvQ==/R8WHe7pEBeqBhu8jTeXydg==/AAICoyitYqlxT7n6aZ0oMCGheFi4CXFp46AMUPZz1lMr_M9tr3_cjee1SHqxrOiVerMDLeyn9xzocZSKwi746Re8vNOtpNCAZjYABs_J0R25IHpvOc1HS8QHGgD5TgOJeS6gX100zdCIGeIlgZnkYj6UvVJWFNhSVhTiPE0=/00000/46016/00</code>
<blockquote>'''Note''': ID3 tags are not applicable for International (Germany)</blockquote>

=== Extracting ID3 tags from Android Players ===
==== ID3 Support Matrix ====
{| class="wikitable"
|-
! Player Name !! Minimum supported version !! Description
|-
| Android Native Media Player || Android 6 || Android 6 Media Player allows apps to register a callback to be invoked, when a selected track has the timed metadata available. Currently, only HTTP Live Streaming (HLS) data URI’s embedded with timed ID3 tags, generates TimedMetaData.
|-
| Google ExoPlayer || Android 4.1 ||
|-
| Brightcove Player || Android 4.1 || Support for Android versions 2.3.3 and 4.0 is now deprecated. Learn more about why Brightcove is removing support for these versions as of January 1, 2016 in this [https://support.brightcove.com/en/perform/docs/announcement-brightcove-sdk-android-version-support|announcement]
|-
| Adobe PrimeTime Player || Android 4.2 ||
|-
| VisualOn Player || Android 2.3 || Android 5 is the latest supported version
|-
| NexStream Player || Android 1.6 || Supported till Android 6
|}

==== Android Native Media Player ====
As the Android Media Player versions (prior to Android 6 / Android API 23) do not support ID3, Nielsen has created a library that becomes an extension to the media player, thus MPX. This library extracts the ID3 tags and sends them to the app. For more information on how to use the MPX component, refer to the Nielsen-supplied sample application.

Starting from '''Android 6 (Android API 23)''', Android Native Media Player allows apps to register a callback to be invoked, when a selected track has the timed metadata available. Currently, only HTTP Live Streaming (HLS) data URI’s embedded with timed ID3 tags generate TimedMetadata. Once the HLS video starts, call onTimedMetaDataAvailable() as and when the player observes a TimedMetadata (ID3 tag).

<syntaxhighlight lang="java">@Override
public void onTimedMetaDataAvailable(MediaPlayer mp, TimedMetaData data)
{
byte[] iD3PayloadArray = data.getMetaData();
String iD3Payload = new String(iD3PayloadArray, StandardCharsets.UTF_8);
if (null != iD3Payload && iD3Payload.contains("www.nielsen.com"))
{
int index = iD3Payload.indexOf("www.nielsen.com");
String id3String = iD3Payload.substring(index, (index + 249));
Log.d(TAG, "TimedMetaData ID3 Tag:" + id3String);
appProcessID3tag(id3String);
}
}</syntaxhighlight>

==== ExoPlayer ====
he SDK is designed around an event-driven architecture where components emit events to allow other components to listen and respond to state changes.

'''Player SDK Classes used:'''
<syntaxhighlight lang="java">com.google.android.exoplayer.demo.player.DemoPlayer</syntaxhighlight>

Since Nielsen App SDK is interested in extracting the Timed Metadata (ID3 Tags) in HLS and VOD on the EXO Player, trace the ID3_TAG emitted during video content played using EXOPlayer component as below.

<syntaxhighlight lang="java">DemoPlayer implements ExoPlayer.Listener
—————————————————–
/**
* A listener for receiving ID3 metadata parsed from the media stream.
*/
public interface Id3MetadataListener
{
void onId3Metadata(Map<String, Object> metadata);
}
——————————————————-
MetadataTrackRenderer.MetadataRenderer<Map<String,
Object>> getId3MetadataRenderer()
{
return new MetadataTrackRenderer.MetadataRenderer<Map<String, Object>>()
{
@Override
public void onMetadata(Map<String, Object> metadata)
{
if (id3MetadataListener != null)
{
id3MetadataListener.onId3Metadata(metadata);
}
}
};
}</syntaxhighlight>

Also in ''Player.java'' class:
<syntaxhighlight lang="java">Player implements DemoPlayer.Id3MetadataListener
—————————————————–
@SuppressWarnings("rawtypes")
@Override
public void onId3Metadata(Map<String, Object> metadata)
{
try
{
for (Object o : metadata.entrySet())
{
Map.Entry pairs = (Map.Entry) o;
if (metadata.containsKey(TxxxMetadata.TYPE))
{
TxxxMetadata txxxMetadata = (TxxxMetadata) metadata
.get(TxxxMetadata.TYPE);
}
else
{
String aStr = new String((byte[]) pairs.getValue());
MainActivity.mAppSdk.sendID3(aStr);
}
}
}
catch (Exception e)
{
e.printStackTrace();
Log.d(TAG, "onId3Metadata(): No Id3 tags");
}
}</syntaxhighlight>

[[File:andr-exo-retrievingID3tags.png|link=]]

==== Brightcove Player ====
While the Brightcove player plays the content, EventListener triggers an event when an ID3 packet is received (<code>SeamlessVideoDisplayComponent.ID3_TAG</code>). Upon receiving this event, collect the incoming ID3 tags and only pass the Nielsen payload of the PRIV frame to the App SDK for analysis.

<syntaxhighlight lang="java">brightcoveVideoView.getEventEmitter().on(SeamlessVideoDisplayComponent.ID3_TAG, new EventListener()
{
public void processEvent(Event event)
{
NlsId3Tag nlsID3 = new NlsId3Tag(event.properties.get(SeamlessVideoDisplayComponent.ID3_DATA).toString());
Log.w("ID3", nlsID3.NlsPayload);
// Sent ID3 Tags to App
appProcessID3tag(nlsID3.NlsPayload);
}
});
}</syntaxhighlight>

==== Adobe PrimeTime Player ====
While the Adobe PrimeTime player plays the content, MediaPlayer.PlaybackEventListener triggers a callback when an ID3 packet is received (onTimedMetadata). Upon receiving this event, collect the incoming ID3 tags and only pass the Nielsen payload of the PRIV frame to the App SDK for analysis.
<syntaxhighlight lang="java">public void onTimedMetadata(TimedMetadata id3Metadata)
{
NlsId3Tag nlsID3 = new NlsId3Tag(id3Metadata.getMetadata().toString());
Log.w(LOG_TAG, "ID3 Timed Data –> " + nlsID3.NlsPayload);
Log.w(LOG_TAG, "PayLoad Size –> " + nlsID3.NlsPayload.length());
appProcessID3tag(nlsID3.NlsPayload);
}</syntaxhighlight>

==== VisualOn Player ====
While the VisualOn player plays the content, <code>VOCommonPlayerListener</code> triggers an event when an ID3 packet is received (<code>VO_OSMP_SRC_CUSTOMERTAGID_TIMEDTAG</code>). Upon receiving this event, collect the incoming ID3 tags and only pass the Nielsen payload of the PRIV frame to the App SDK for analysis.

<syntaxhighlight lang="java">case VO_OSMP_SRC_CB_CUSTOMER_TAG:
{
VO_OSMP_SRC_CUSTOMERTAGID tag = VO_OSMP_SRC_CUSTOMERTAGID.valueOf(nParam1);
switch (tag)
{
case VO_OSMP_SRC_CUSTOMERTAGID_TIMEDTAG:
// do something with this tag
int time = nParam2;
byte[] b = (byte[]) obj;
String s = new String(b);
NlsId3Tag nlsID3 = new NlsId3Tag(b);
// Sent ID3 Tags to App
appProcessID3tag(nlsID3.NlsPayload);
if (appid3If != null)
appid3If.onId3(nlsID3.NlsPayload);
break;
case VO_OSMP_SRC_CUSTOMERTAGID_MAX:
// ignore this type of tag
break;
default:
break;
}
break;
}</syntaxhighlight>

==== NextStream Player ====
ID3 tags will be received in the NexStream Player through <code>onTimedMetaRenderRender(NexPlayer mp,NexID3TagInformation metadata)</code> callback API. A sample implementation for the callback is shown below:
<syntaxhighlight lang="java">public void onTimedMetaRenderRender(NexPlayer mp, NexID3TagInformation m)
{
text = m.getPrivateFrame();
if (text != null)
{
data = text.getTextData();
if (data != null)
{
// make sure to identify the beginning of the
// Nielsen ID3 tag payload by searching for the
// "www.nielsen.com" string on the ID3 tag and
// passing to the App SDK all information that
// follows. It should be:
// nlsPayload = "www.nielsen.com" + dataFollowing
nlsPayload = getDataAfterWwwNielsenCom(data);
if (nlsPayload!= NULL)
mAppSdk.sendID3(nlsPayload);
}
}
}</syntaxhighlight>

The [[sendID3()]] sends the extracted Nielsen ID3 payload to the App SDK for analysis.

== Android SDK API Methods & Properties ==
{| class="wikitable sortable"
|-
! Scenario !! Method / Property !! DTVR !! DAR !! Digital Audio !! DCR !! International (Germany) !! Description
|-
| Initialize || [[AppSDK()]] || ✔ || ✔ || ✔ || ✔ || ✔ || 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 when there is a preroll ad that needs to be associated with content metadata. The loadmetadata will first be called to populate the content metadata values and then the loadMetadata for ad metadata will be called. This allows sending a content ping with the ad info, even if the user bails out during the preroll ad.
|-
| Measurement || [[sendID3()]] || ✔ || ✘ || ✘ || ✘ || ✘ || Used to send the ID3 metadata.
|-
| Measurement || [[setPlayheadPosition()]] || ✘ || ✘ || ✔ || ✔ || ✔ || 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 || [[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 || [[userOptOutURLString()]] || ✔ || ✔ || ✔ || ✔ || ✔ || 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 || [[getOptOutStatus()]] || ✘ || ✘ || ✘ || ✘ || ✔ || Call this API to retrieve the Opt-Out or Opt-In state.
|-
| Opt-out
| [[appDisableApi()]]
(kill switch)
|| ✔ || ✔ || ✔ || ✔ || ✔ || Used to disable the SDK.
|-
| Opt-out || [[getAppDisable()]] || ✔ || ✔ || ✔ || ✔ || ✔ || Used to query if the SDK is disabled or not.
|-
| Log || [[getLastEvent()]] || ✔ || ✔ || ✔ || ✔ || ✔ || Used to query the SDK for the last status
|-
| Log || [[getLastError()]] || ✔ || ✔ || ✔ || ✔ || ✔ || Used to query the SDK for the last error
|-
| Log || [[isValid()]] || ✔ || ✔ || ✔ || ✔ || ✔ || Used to check if the SDK was successfully instantiated or not.
|-
| Log || [[getMeterVersion()]] || ✘ || ✘ || ✘ || ✘ || ✔ || Returns the current SDK version.
|-
| Log || [[getNielsenId()]] || ✔ || ✔ || ✔ || ✔ || ✔ || Used to get a string defining the Nielsen ID (NUID) number for the device.
|-
| Log || [[getDeviceId()]] || ✔ || ✔ || ✔ || ✔ || ✔ || Returns the current device id.
|-
| Log || [[appInBackground()]] || ✘ || ✘ || ✘ || ✔ || ✔ || Used to capture the event of app going to background.
|-
| Log || [[appInForeground()]] || ✘ || ✘ || ✘ || ✔ || ✔ || Used to capture the event of app coming to foreground
|-
| Log || [[setDebug()]] || ✘ || ✘ || ✘ || ✘ || ✔ || Used to enable/disable debug flags. Newly introduced in SDK version 5.0.0 for International (Germany)
|}

== 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.
*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.

=== Displaying Opt-Out in a WebView ===
<syntaxhighlight lang="java">
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
}
</syntaxhighlight>

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.

[[File:Privacy policy iOS.jpg|link=]]

<blockquote>'''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.</blockquote>

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

=== Sequence Diagram ===
[[File:optoutsequence-andr.jpg|link=]]

== Opt-out Android SDK Version '''5.1.1.18 or above''' ==
<blockquote>'''Note:''' If using Android SDK Versions 1.2.3, 4.0.0.8, 5.1.0, 5.1.1.14, skip ahead to: [[#Opt-out Android SDK Version 1.2.3, 4.0.0.8, 5.1.0, 5.1.1.14|Opt-out Android SDK Version 1.2.3, 4.0.0.8, 5.1.0, 5.1.1.14]]</blockquote>

Starting from SDK version 5.1.1.18, Opt-Out related behavior has been changed in the following ways:
*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'''.
<blockquote>'''Note:''' For Amazon devices, see [[#Opt-Out Implementation for Amazon Devices|Opt-Out Implementation for Amazon Devices]] below.</blockquote>

[[File:andr-ads.jpg|link=]]

<blockquote>'''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.</blockquote>

== Opt-out Android SDK Version '''1.2.3, 4.0.0.8, 5.1.0, 5.1.1.14''' ==
<blockquote>'''Note:''' If using Android SDK Version 5.1.1.18 or above, refer to documentation above ([[#Opt-out Android SDK Version 5.1.1.18 or above|Opt-out Android SDK Version 5.1.1.18 or above]])</blockquote>

When a user clicks the Opt-Out / Opt-In link, the application should invoke [[optOutURL]] to get the link to the Nielsen Privacy page from SDK.
=== Privacy Page ===
[[File:privacy-policy.jpg|link=]]
*There are two click here links – one for Opt-Out and one for Opt-In. Click the required link:
**Capture user’s selection
**Pass the selection back to the SDK via the [[userOptOut()]].

=== Capture and forward user selection ===
<syntaxhighlight lang="java">
private class MonitorWebView extends WebViewClient
{
private static final String NIELSEN_URL_OPT_OUT = “nielsenappsdk://1”;
private static final String NIELSEN_URL_OPT_IN = “nielsenappsdk://0”;

@Override
public boolean shouldOverrideUrlLoading(WebView view, String url)
{
if (NIELSEN_URL_OPT_OUT.equals(url)
|| NIELSEN_URL_OPT_IN.equals(url))
{
// Get AppSdk instance from the host
AppSdk appSdk = HostApp.getAppSdk();
// Send the URL to the AppSdk instance
appSdk.userOptOut(url);
return true;
}
return false;
}
}
</syntaxhighlight>

<blockquote>'''Note:''' When 'WebView' is closed, pass the status returned from 'WebView' to the SDK within the app.</blockquote>
<blockquote>'''Note:''' App SDK manages the user's choice (Opt-Out / Opt-In), the app does not need to manage this status.</blockquote>

== 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 ===

<syntaxhighlight lang="java">
ContentResolver cr = getContentResolver();
int limitAdTracking = Secure.getInt(cr, "limit_ad_tracking", 2);
</syntaxhighlight>

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

<blockquote>'''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'''.</blockquote>

== Nielsen Sample Applications ==

== Nielsen Privacy Requirements ==
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.
[[File:RatingsDataFlow.png]]

'''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 ===
{| class="wikitable"
|-
! Type of Information !! Parameter !! Transmitted to Nielsen? !! Sent to Provider?
|-
| rowspan="8" | 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
|-
| rowspan="10" | 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
|-
| rowspan="9" | 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
|}
<blockquote>'''Note''': Data is hashed, and encrypted using AES 128 before transmission to data provider.</blockquote>

==== Example ping sent to provider ====
* <code><nowiki>https://provider.com/cgi-bin/brandlift.php</nowiki>?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</code>

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

== Event and Error Handling ==
=== App SDK Error Codes ===
Constants with predefined error codes which the AppSdk object can generate.
<syntaxhighlight lang="java">public static final int ERROR_FAILED_CREATE_URL_STRING = 1001;
// failed generating ping string due to error on parsing
// description – include last error message from URL parser
public static final int ERROR_FAILED_RECEIVE_CONFIG = 1002;
// failed to receive configuration file from Census
// description – on 5th time, it will log event and keep requesting config 10 min apart
public static final int ERROR_FAILED_PARSING_CONFIG = 1003;
// failed parsing the config file JSON string
// description – include json error number/short message from iOS or Android
public static final int ERROR_FAILED_PARSING_PLAY = 1004;
// failed parsing the play() JSON string
// description – include json error number/short message from iOS or Android
public static final int ERROR_FAILED_PARSING_METADATA = 1005;
// failed parsing the play() JSON string
// description – include JSON error number/short message from iOS or Android
public static final int ERROR_FAILED_GENERATING_PING = 1006;
// failed creating ping before adding it to the UPLOAD table)
// description – include ping nol_url index, cadence to identify ping
public static final int ERROR_FAILED_PROCESSOR_START = 1007;
// failed starting data processor thread. Normally, that means a product
// description – include processor that failed to start
public static final int ERROR_FAILED_PROCESS_ID3 = 1008;
// failed processing data on a data processor. Normally, that means the input to a product
// description – include processor and data that failed to process (ID3 tag on a MTVR impression, for example)
public static final int ERROR_FAILED_HTTP_SEND = 1009;
// failed sending HTTP or HTTPS requests
// description – include HTTP error number
public static final int ERROR_FAILED_SENDING_PING = 1010;
// failed sending pings (on ANDROID, the ping on the UPLOAD table)
// description – include ping up to 80 char from the end
public static final int ERROR_FAILED_SENDING_TSV = 1011;
// failed sending TSV requests
// description – include TSV request message
public static final int ERROR_FAILED_SENDING_STATION_ID = 1012;
// failed sending StationId requests
// description – include Station ID request message
public static final int ERROR_FAILED_ACCESSING_DB = 1013;
// failed read/write from/to database table
// description – include SQL statement and data and SQLite error number/message
public static final int ERROR_CHANGED_DEVICE_ID = 1014;
// device ID changed
// description – none
public static final int ERROR_CHANGED_NUID = 1015;
// NUID changed
// description – none
public static final int ERROR_SDK_NOT_INITIALIZED = 1016;
// App SDK initialization failed
// description – none
public static final int ERROR_FAILED_SDK_SUSPEND = 1017;
// App SDK failed to suspend activities
// description – none
public static final int ERROR_INVALID_PARAMETERS = 1018;
// App SDK invalid parameters
// description – none
public static final int ERROR_INVALID_STATE = 1019;
// App SDK called in incorrect state
// description – none
public static final int ERROR_FAILED_PROCESS_PLAYHEAD = 1020;
// App SDK failed processing playhead position
// description – none
public static final int ERROR_FAILED_PROCESS_METADATA = 1021;
// App SDK failed processing not-null, syntax valid JSON metadada
// description – none
public static final int ERROR_FAILED_PROCESS_STOP = 1022;
// App SDK failed processing stop
// description – none</syntaxhighlight>

=== App SDK Event Codes ===
<syntaxhighlight lang="java">public static final int EVENT_INITIATE = 2000;
// App SDK is initiated. It will happen as soon as the App SDK is initialized
public static final int EVENT_STARTUP = 2001;
// App SDK has started up. It will happen only after App SDK has received a valid config file. This is the location in the code to acquire the value of userOptOutURLString().
public static final int EVENT_SHUTDOWN = 2002;
// App SDK is shutting down. It will happen just before App SDK is destroyed</syntaxhighlight>

'''App SDK Event Codes '''
{| class="wikitable"
|-
! Event Code !! Event Name !! Event Description
|-
| 2000 || EVENT_INITIATE || App SDK is initiated. It will happen as soon as the App SDK is initialized
|-
| 2001 || EVENT_STARTUP || App SDK has started up. It will happen only after App SDK has received a valid config file
|-
| 2002 || EVENT_SHUTDOWN || App SDK is shutting down. It will happen just before App SDK is destroyed
|}

iOS SDK API Reference

2017-07-11T21:53:28Z

Admin2: /* Legacy Opt-Out */

{{Breadcrumb|}} {{Breadcrumb|Digital}} {{CurrentBreadcrumb}}
[[Category:Digital]]
The iOS 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. These SDKs leverage the following:
*Nielsen audio watermark technologies for TV audience measurement
*The industry supported ID3 metadata tag specification
*Nielsen Combined Beacon technology
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
*Application crash events
*Time of viewing a sub section / page in the application.

== Importing Frameworks ==
'''Setting up your Xcode Development Environment'''

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

SDK uses the NSURLSession available from iOS 7 instead of the deprecated NSURLConnection.

<blockquote>'''Note''': App SDK supports devices running on iOS 9 and above, as all communications between the SDK and the Census (Collection Facility) use HTTPS.</blockquote>

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 (Not applicable for International (Germany))
* 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

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

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

== Initialization ==
The latest version of App SDK allows instantiating multiple instances of App SDK object and can be used simultaneously without any issues (The sharedInstance API that creates a singleton object in previous versions of App SDK is removed).
*Maximum of four SDK instances per appid are supported in this release. When a fifth SDK instance is launched,
**SDK will return “nil” from [[initWithAppInfo:delegate:]]
**Destroy one or more old SDK instances before creating new ones.

=== Stages of SDK Initialization ===
==== Step 1: App SDK Initialization ====
Initialize the Nielsen App object within the viewDidLoad view controller delegate method using initWithAppInfo:delegate:
<blockquote>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.</blockquote>

==== Step 2: Setting up event and error notifications ====
Once the <code>NielsenAppApi</code> object has been initialized, the next step is to enable notifications regarding ID3 tags extracted from the playing stream. In case of standard AVFoundation player, the SDK NSNotificationCenter API is used to
* Collect HLS timed metadata events (ID3 tags) during viewing sessions.
** Set up a timed metadata event listener method for receiving ID3 tags and calling Nielsen [[sendID3]].
* SDK uses the following NielsenAppApiDelegate protocol methods to notify its delegate (set during initialization) about event / error information.
** nielsenAppApi:eventOccurred
** nielsenAppApi:errorOccurred
<blockquote>'''Note''': Ensure to add to your view controller’s <code>@interface</code>.</blockquote>

<syntaxhighlight lang="objective-c">(void)nielsenAppApi:(NielsenAppApi *)appApi eventOccurred:(NSDictionary *)event {NSLog(@"Sample player is Notified by a Event : %@", event);
}
(void)nielsenAppApi:(NielsenAppApi *)appApi errorOccurred:(NSDictionary *)error {NSLog(@"Sample player is Notified by an Error : %@", error);
}</syntaxhighlight>

===== Sample event confirmation to player application upon successful initialization of SDK =====
<syntaxhighlight lang="console">NielsenSDKSampleDebug[9028:237989] [Nls:0] -I- Analytics framework Status:
{
"Event Description" = "Nielsen App SDK Version, ai.4.0.0.4 is initialized by the Player…";
EventStatus = 2001;
TimeStamp = "2015-07-23 14:51:06 +0000";
}</syntaxhighlight>

==== Step 3: Nielsen App SDK Streaming Sessions ====
After setting up observers for SDK events/errors and a listener method to process incoming Nielsen ID3 tags, the next steps are to
* Call [[play]] while starting or resuming a streaming session.
* Load CMS metadata using [[loadMetadata]].
* During session play, call [[playheadPosition]] every one second until the stream is stopped or interrupted (due to ad breaks or buffering).
* Call [[stop]] when pausing, ending a viewing session, or buffering is detected.

'''Serialized JSON string from NSDictionary'''
<syntaxhighlight lang="objective-c">NSDictionary* appInformation = @
{
@"appid": @"TXXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX",
@"appname": @"Sample App Name",
@"appversion": @"2.0",
@"sfcode": @"uat-cert",
@"nol_devDebug": @"INFO"
}
NSData* jsonDataAppInfo = [NSJSONSerialization dataWithJSONObject:appInformation options:0 error:nil];
NSString *jsonAppInfoString = [[NSString alloc] initWithData:jsonDataAppInfo encoding:NSUTF8StringEncoding];
nlsAppApiMeter = [[NielsenAppApi alloc] initWithAppInfo:jsonAppInfoString delegate:self];</syntaxhighlight>

Nielsen App SDK object handles filtering of ID3 tags and CMS tags, queuing/buffering of data, and all communications with Nielsen collection facility.

===== Nielsen iOS App SDK Application Life Cycle =====

[[File:initialization_appcycle.png|center|link=]]

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 '''Initial state'''.
# '''Idle state''' – The SDK is initialized and is ready to process playing information. Call <code>[[initWithAppInfo:delegate:]]</code> to move into this state. The SDK instance is not processing any data, but is listening for the play event to occur.
# '''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.
## [[playheadPosition]] – Call this API every one second when playhead position timer is fired.
## [[sendID3]] – Call this API when ID3 tags are identified in the stream.
## [[stop]] – Call this API when the playback is paused, switches between content and ad (within the same content playback) or encounters interruptions.
## [[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. SDK instance moves into this state in one of the following scenarios.
## Initialization fails
## [[appDisableApi]] is called
<blockquote>'''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 [[sendID3]] / [[playheadPosition]].</blockquote>

=== 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.
{| class="wikitable"
|-
! API call received !! Initial State !! Idle State !! Processing State !! Disabled State
|-
| <code>[[initWithAppInfo:delegate:]]</code> || IDLE STATE (OR)

DISABLED STATE
|| IDLE STATE || - || -
|-
| <code>[[play]]</code> & <code>[[loadMetadata]]</code>|| - || PROCESSING

STATE
|| - || -
|-
| <code>[[playheadPosition]]</code> || - || - || PROCESSING

STATE
|| -
|-
| <code>[[sendID3]]</code> || - || - || PROCESSING

STATE
|| -
|-
| <code>[[stop]]</code> || - || - || IDLE STATE || -
|-
| <code>[[end]]</code> || - || - || IDLE STATE || -
|-
| <code>[[appDisableApi]]</code>: YES || - || DISABLED

STATE
|| - || -
|-
| <code>[[appDisableApi]]</code>: NO || - || - || - || IDLE STATE (OR)

DISABLED STATE
|-
| <code>[[userOptOut]]</code>: YES || - || - || IDLE STATE || -
|-
| <code>[[userOptOut]]</code>: NO || - || PROCESSING

STATE
| -
| -
|-
| colspan = 5 | '-' 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.

==== JSON for NSDictionary object ====
<syntaxhighlight lang="objective-c">
NSDictionary* appInformation = @{
@"appid": @"TXXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX",
@"appname": @"Sample App Name",
@"appversion": @"2.0",
@"sfcode": @"uat-cert",
@"nol_devDebug": @"INFO"
};
nlsAppApiMeter = [[NielsenAppApi alloc] initWithAppInfo:appInformation delegate:delegate];</syntaxhighlight>

<code>appid</code>, <code>appname</code>, and <code>appversion</code> are mandatory parameters while <code>sfcode</code> is optional. <code>nol_devDebug</code> is meant for creating logs in test environments only.

==== JSON string from raw NSString ====
<syntaxhighlight lang="swift">NSString *appInfoString = @"{\"appid\" : \"TXXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX\", \"appname\" : \"Sample App Name\",\"appversion\" : \"2.0\",\"sfcode\" : \"uat-cert\"}";
NielsenAppAPi *appAPI = [[NielsenAppApi alloc] initWithAppInfo:appInfoString delegate:self];</syntaxhighlight>

==== JSON string from serialized NSDictionary ====
<syntaxhighlight lang="objective-c">NSDictionary* appInformation = @
{
@"appid": @"appid",
@"appname": @"appname",
@"appversion": @"2.0",
@"sfcode": @"sfcode",
@"nol_devDebug": @"INFO"
};
nlsAppApiMeter = [[NielsenAppApi alloc] initWithAppInfo:appInformation delegate:self];</syntaxhighlight>

While using JSON format for sending metadat, ensure enough care in including [[special characters]] in the values for arguments.

==== Example ====
<syntaxhighlight lang="objective-c">{
@"type": @"radio", // To send "radio" in metadata string
@"assetid": @"WXYZ-FM'101",
@"stationType": @"3",
@"provider": @"SampleProvider" // To send "SampleProvider" in metadata string
}</syntaxhighlight>
<blockquote>'''Note''': For mandatory parameters like appid, appname, and appversion, please refer to the parameters table in <code>[[initWithAppInfo:delegate:]]</code></blockquote>

== Retrieving ID3 Tags ==
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.

=== Sample ID3 tags ===
* <code>www.nielsen.com/X100zdCIGeIlgZnkYj6UvQ==/X100zdCIGeIlgZnkYj6UvQ==/AAAB2Jz2_k74GXSzx4npHuI_JwJd3QSUpW30rDkGTcbHEzIMWleCzM-uvNOP9fzJcQMWQLJqzXMCAxParOb5sGijSV9dNM3QiBniJYGZ5GI-lL1fXTTN0IgZ4iWBmeRiPpS9AAAAAAAAAAAAAAAAAAAAAFJWFM5SVhTONNU=/00000/00000/00</code>
* <code>www.nielsen.com/X100zdCIGeIlgZnkYj6UvQ==/R8WHe7pEBeqBhu8jTeXydg==/AAICoyitYqlxT7n6aZ0oMCGheFi4CXFp46AMUPZz1lMr_M9tr3_cjee1SHqxrOiVerMDLeyn9xzocZSKwi746Re8vNOtpNCAZjYABs_J0R25IHpvOc1HS8QHGgD5TgOJeS6gX100zdCIGeIlgZnkYj6UvVJWFNhSVhTiPE0=/00000/46016/00</code>

=== Examples of extracting ID3 tags from the iOS Native Player ===
==== AVPlayer ====
ID3 tags will be received in the Player on AVMetadataItem Callback method.
'''Create & get the AVMetadataItem callback method'''
<syntaxhighlight lang="swift">[self.player addObserver:self
forKeyPath: kTimedMetadataKey
options: NSKeyValueObservingOptionNew
Context: MyStreamingMovieViewControllerTimedMetadataObserverContext];</syntaxhighlight>

<syntaxhighlight lang="objective-c">
– (void)observeValueForKeyPath:(NSString*) path
ofObject: (id)object
change: (NSDictionary*)change
context: (void*)context
{
/* Set the AVPlayerLayer on the view to allow the AVPlayer object to display
its content. */
//[playerLayerView.playerLayer setPlayer:player];
/* AVPlayerItem "status" property value observer. */
if (context == MyStreamingMovieViewControllerTimedMetadataObserverContext)
{
id newMetadataArray = [change objectForKey:NSKeyValueChangeNewKey];
if (newMetadataArray != [NSNull null])
{
array = newMetadataArray;
for (AVMetadataItem *metadataItem in array)
{
[self handleTimedMetadata: metadataItem];
}
}
}
</syntaxhighlight>

<syntaxhighlight lang="objective-c">
– (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;
}
if ([(NSString *)[timedMetadata key] isEqualToString:@"PRIV"]&&[extraString rangeOfString:@"www.nielsen.com"].length> 0)
{
if ([[timedMetadata value] isKindOfClass:[NSData class]])
{
// Sending ID3 Tag
/* The sendID3: sends the extracted Nielsen ID3 payload to the App SDK for analysis. */
[[NielsenAppApi sharedInstance]sendID3: extraString];
NSString *value=[timedMetadata stringValue];
if (value != nil)
{
// NSString *strMessage=[[@"ID3 Tag Received " stringByAppendingFormat:@"%d\n",countForMetadata] stringByAppendingString:value];
[self appendLogConsoleText:extraString];
}
}
}
else
{
NSLog(@"Could not send ID3 tags");
}
countForMetadata++;

}
</syntaxhighlight>

==== Movie Player ====
ID3 tags will be received in the Player on MPTimedMetadata Callback method.
'''Sample Implementation of MPTimedMetadata callback'''
<syntaxhighlight lang="objective-c">
– (void)handleTimedMetadata:(MPTimedMetadata*)timedMetadata
{
id extraAttributeType = [timedMetadata allMetadata];
NSString * extraString= nil;
if ([extraAttributeType isKindOfClass:[NSDictionary class]])
{
extraString = [extraAttributeType valueForKey:@"info"];
}
else if([extraAttributeType isKindOfClass:[NSString class]])
{
extraString = extraAttributeType;
}

if ([(NSString *)[timedMetadata key] isEqualToString:@"PRIV"]&&[extraString rangeOfString:@"www.nielsen.com"].length> 0)
{
if ([[timedMetadata value] isKindOfClass:[NSData class]])
{
// Sending ID3 Tag
[[NielsenAppApi sharedInstance]sendID3: extraString];
NSString *value=[timedMetadata value];
if (value != nil)
{

[self appendLogConsoleText:extraString];
}
}
}
else
{
NSLog(@"Could not send ID3 tags");
}
countForMetadata++;
}
</syntaxhighlight>
<blockquote>'''Note:''' ID3 tags are not applicable for International (Germany)</blockquote>

== IOS SDK API Methods & Properties ==
{| class="wikitable sortable"
|-
! Scenario !! Method / Property !! DTVR !! DAR !! Digital Audio !! 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 || [[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.
|-
| 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)
|}

== 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 to this web page should be called from SDK by invoking [[optOutURL]] and opened in 'WebView' / External browser.
*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 [[optOutStatus]] method.

=== Displaying Opt-Out in a WebView ===
<syntaxhighlight lang="objective-c">
NielsenAppApi nAppApiObject;
@property(strong) UIWebView *optOutView;
// create WebView and set self as delegate
self.optOutView=[[UIWebView alloc]initWithFrame:self.view.bounds];
self.optOutView.scalesPageToFit = yes;
// get Nielsen defined web address and load the page
NSString *webAddress = [nAppApiObject optOutURLString];
If(webAddress == nil)
{ // Handle it gracefully and retry later} else
{[optOutView loadRequest:[NSURLRequest requestWithURL:webAddress]];
// show the view to the user
[self.view addSubview:optOutView]; }
</syntaxhighlight>

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.

[[File:Privacy policy iOS.jpg|link=]]

*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.
<syntaxhighlight lang="objective-c">
@property (readonly) BOOL optOutStatus;
</syntaxhighlight>
*App should provide a UI control like 'close' or 'back' button to close the 'WebView' / External browser.

=== Sequence Diagram ===
[[File:optoutsequence-ios.jpg|link=]]

== Opt-out SDK Version '''5.1.1.17 or above''' ==
<blockquote>'''Note:''' If using SDK Versions 1.2.3, 4.0.0.8, 5.1.0, 5.1.1.12, skip ahead to: [[#Opt-out SDK Version 1.2.3, 4.0.0.8, 5.1.0, 5.1.1.12|Opt-out SDK Version 1.2.3, 4.0.0.8, 5.1.0, 5.1.1.12]]</blockquote>

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.

[[File:Opt-Out iOS.jpg|link=]]

<blockquote>'''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.</blockquote>

== Opt-out SDK Version '''1.2.3, 4.0.0.8, 5.1.0, 5.1.1.12''' ==
<blockquote>'''Note:''' If using SDK Version 5.1.1.17 or above, refer to documentation above ([[#Opt-out SDK Version 5.1.1.17 or above|Opt-out SDK Version 5.1.1.17 or above]])</blockquote>

When a user clicks the Opt-Out / Opt-In link, the application should invoke [[optOutURL]] to get the link to the Nielsen Privacy page from SDK.
=== Privacy Page ===
[[File:privacy-policy.jpg|link=]]
*There are two click here links – one for Opt-Out and one for Opt-In. Click the required link:
**
[[File:Opt-Out Combined.jpg|link=]]
*Click OK in the dialog that appears, to confirm the action.
*The Opt-Out occurs by opening a Nielsen-defined web page and passing the user choice from the 'WebView'. In order to do this, the application needs to
**Implement the UIWebView delegate method to open the Nielsen Privacy web page
**Capture user's selection
**Pass the selection back to the SDK via the [[userOptOut]].

=== Capture and forward user selection ===
<syntaxhighlight lang="objective-c">
-(BOOL)webView:(UIWebView *)webView
shouldStartLoadWithRequest:(NSURLRequest *)request
navigationType:(UIWebViewNavigationType)navigationType
{
NSString *command = [NSString stringWithFormat:@"%@",
request.URL];
if ([command isEqualToString:kNielsenWebClose]) {
// Close the WebView
[self performSelector:@selector(closeOptOutView)
withObject:nil afterDelay:0];
return NO;
}
// Retrieve next URL if it's not opt-in/out selection
return (![nAppApiObject userOptOut:command]);
}
</syntaxhighlight>

*The app gets the user selection string via webviews shouldStartLoadWithRequest and invokes [[userOptOut]] with user selection. The delegate method handles the 'WebView' URL requests, interprets the commands, and calls the SDK accordingly.
**<code>[nAppApiObject userOptOut:command]</code> passes the user's selection on Nielsen Privacy page to the SDK to allow the SDK to perform the required functions.
<blockquote>'''Note:''' When 'WebView' is closed, pass the status returned from 'WebView' to the SDK within the app.</blockquote>
<blockquote>'''Note:''' App SDK manages the user's choice (Opt-Out / Opt-In), the app does not need to manage this status.</blockquote>

== 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:

[[File:TVOs OptOut LimitAdTracking1.png|link=]]

[[File:TVOs OptOut LimitAdTracking2.png|link=]]

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.

<blockquote>'''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.</blockquote>

== 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:
<syntaxhighlight lang="objective-c">
@interface NielsenAppApi: NSObject

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

– (instancetype)initWithAppInfo:(id)appInfo delegate:(id)delegate;

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

– (NSString *)getNielsenId _attribute((deprecated((“Please use nielsenId property instead.”))));
– (NSString *)optOutURLString _attribute((deprecated((“Please use optOutURL property instead.”))));
– (NSString *)getMeterVersion _attribute((deprecated((“Please use meterVersion property instead.”))));
– (NSDictionary *)getLastEventDict _attribute((deprecated((“Please use lastEventDict property instead.”))));
– (NSDictionary *)getLastErrorDict _attribute((deprecated((“Please use lastErrorDict property instead.”))));

@protocol NielsenAppApiDelegate<NSObject>

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

@end
</syntaxhighlight>

== Nielsen Sample Applications ==
Nielsen iOS sample player application consists of two sample application based on native Players integrated with SDK framework. The player demonstrates all the supported functions of the SDK.
*NielsenVideoPlayer
*NielsenRadioPlayer
Implementation of Video and Audio 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 two locations:
**Channels 1 and 2 are configured from the Settings application. Channel URLs and metadata parameters can be modified.
**Channels starting from 3 are configured in specific JSON file. URLs to this JSON config file can be changed from the Settings application.

== Nielsen Privacy Requirements ==
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.
[[File:RatingsDataFlow.png]]

'''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 ===
{| class="wikitable"
|-
! Type of Information !! Parameter !! Transmitted to Nielsen? !! Sent to Provider?
|-
| rowspan="8" | 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
|-
| rowspan="10" | 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
|-
| rowspan="9" | 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
|}
<blockquote>'''Note''': Data is hashed, and encrypted using AES 128 before transmission to data provider.</blockquote>

==== Example ping sent to provider ====
* <code><nowiki>https://provider.com/cgi-bin/brandlift.php</nowiki>?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</code>

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

=== Nielsen Measurement Opt-Out ===
In accordance with Nielsen’s SDK licensing agreement, developers are required to provide basic informational data to users about Nielsen’s Privacy Policy with a navigation to additional information on Nielsen measurement.

Nielsen currently uses Limit Ad Tracking for the latest versions of the SDK (5.1.1.17 and above). However, for older SDK versions, the app must provide a means for the user to opt out, or opt back in to Nielsen Measurement. Users can opt out of Nielsen online measurement research through this feature.
* If the user has this app running on more than one mobile device, the user will need to opt out of this measurement on each device.
<blockquote>'''Note''': Opt Out feature does NOT rely on "Limit Ad Tracking" setting since Nielsen’s systems provide measurement metrics and do not serve ads to users.</blockquote>

In the Description of the app in App Store, include a short description about Nielsen measurement, as below.

<blockquote>'''Sample App Store Disclosure'''
This app features Nielsen proprietary measurement software which will allow you to contribute to market research, like Nielsen’s TV Ratings.

To learn more about our digital measurement products and your choices in regard to them, please visit http://www.nielsen.com/digitalprivacy for more information.

[[File:measurement-samplescreen.jpg]]</blockquote>

Both iOS-based and TVOS-based player applications need to confirm to Nielsen Privacy Requirements. Refer to the Opt-Out implementation guidelines for iOS and TVOS platforms respectively for more details.

=== Opt-Out Implementation ===
==== Limit Ad Tracking ====
'''This implementation is valid for SDK Versions 5.1.1.17 and above.'''

<blockquote>'''Note''': If using SDK Version 1.2.3, 4.0.0.8, 5.1.0 or 5.1.1.12, refer to [[#Legacy_Opt-Out|Legacy Opt-Out Implementation for iOS]].</blockquote>

As a global information and measurement leader, Nielsen is committed to protect the privacy and security of the data they collect, process and use. Nielsen strongly believes that the consumer should have a way to opt out of Nielsen measurement.

The Nielsen digital measurement products help Nielsen and its clients to measure and analyze how consumers engage with media across online, mobile and emerging technologies while offering insights into consumer behavior.

To learn more about our digital measurement products and your choices in regard to them, please visit http://www.nielsen.com/digitalprivacy.

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 optOutURL and opened in ‘WebView’ / External browser.
* 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 optOutStatus method.
'''Displaying Opt-Out in a WebView'''
<syntaxhighlight lang="objective-c">NielsenAppApi nAppApiObject;
@property(strong) UIWebView *optOutView;
// create WebView and set self as delegate
self.optOutView=[[UIWebView alloc]initWithFrame:self.view.bounds];
self.optOutView.scalesPageToFit = yes;
// get Nielsen defined web address and load the page
NSString *webAddress = [nAppApiObject optOutURLString];
If(webAddress == nil)
{
// Handle it gracefully and retry later
}

else
{
[optOutView loadRequest:[NSURLRequest requestWithURL:webAddress]];
// show the view to the user
[self.view addSubview:optOutView];
}</syntaxhighlight>

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.

[[File:Opt-Out_iOS.jpg]]
<blockquote>'''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.</blockquote>

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.

[[File: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.
<syntaxhighlight lang="objective-c">@property (readonly) BOOL optOutStatus;</blockquote>
* App should provide a UI control like ‘close’ or ‘back’ button to close the ‘WebView’ / External browser.

'''Sequence Diagram'''
[[File:optoutsequence-ios.jpg]]

== Event and Error Handling ==
=== Constants / Enumerations ===
The following are the details of Delegate Implementation:

<syntaxhighlight lang="objective-c">
-(void)nielsenAppApi:(NielsenAppApi *)appApi eventOccurred:(NSDictionary *)event
{
NSLog(@"Sample player is Notified by a Event: %@", event);
}
– (void)nielsenAppApi:(NielsenAppApi *)appApi errorOccurred:(NSDictionary *)error
{
NSLog(@"Sample player is Notified by an Error: %@", error);
}
</syntaxhighlight>

==== TVOS Implementation ====
As a global information and measurement leader, Nielsen is committed to protect the privacy and security of the data they collect, process and use. Nielsen strongly believes that the client should have a way to Opt-Out of Nielsen measurement.

The Nielsen digital measurement products are not used to identify consumer in any way. They help Nielsen and its clients to measure and analyze how consumers engage with media across online, mobile and emerging technologies while offering insights into consumer behavior.

To learn more about our digital measurement products and your choices in regard to them, please visit http://www.nielsen.com/digitalprivacy.

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.

[[File:TVOs_OptOut_LimitAdTracking1.png]]

[[File:TVOs_OptOut_LimitAdTracking2.png]]

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.

<blockquote>'''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.</blockquote>

==== Legacy Opt-Out ====
'''Supported SDK Versions''': 1.2.3, 4.0.0.8, 5.1.0, 5.1.1.12.

<blockquote>'''Note''': If using SDK Version 5.1.1.17 or above, refer to [[#Limit Ad Tracking|Limit Ad Tracking iOS Implementation]].</blockquote>

As a global information and measurement leader, Nielsen is committed to protect the privacy and security of the data they collect, process and use. Nielsen strongly believes that the consumer should have a way to Opt-Out of Nielsen measurement.

The Nielsen digital measurement products help Nielsen and its clients to measure and analyze how consumers engage with media across online, mobile and emerging technologies while offering insights into consumer behavior.

To learn more about our digital measurement products and your choices in regard to them, please visit http://www.nielsen.com/digitalprivacy.

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 [[optOutURL]] and opened in ‘WebView’ within the app and NOT in any external browser.
** Opening the Opt-Out page in any external browser takes the application control out of the Nielsen App SDK context.
** As the App SDK does not expose any direct http/https interface to interact with the world to get the user selection on Privacy page, there will be no way to interact/send notification to the App SDK regarding the user selection.
* 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 [[optOutStatus]] method.
<blockquote>'''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.</blockquote>

'''Sequence Diagram'''
[[File:optoutsequence-ios.jpg]]

Below are the steps to implement user Opt-Out using UIWebView.

When a user clicks the Opt-Out / Opt-In link, the application should invoke [[optOutURL]] to get the link to the Nielsen Privacy page from SDK.

'''Implement WebView with Nielsen Opt-Out URL'''
<syntaxhighlight lang="objective-c">NielsenAppApi nAppApiObject;
@property(strong) UIWebView *optOutView;

// create WebView and set self as delegate
self.optOutView=[[UIWebViewalloc]initWithFrame:self.view.bounds];

self.optOutView.scalesPageToFit = yes;
// get Nielsen defined web address and load the page
NSString *webAddress = [nAppApiObject optOutURLString];

if(webAddress == nil)
{ // Handle it gracefully and retry later}
else
{
[optOutView loadRequest:[NSURLRequest requestWithURL:webAddress]];
// show the view to the user
[self.view addSubview:optOutView];
}</syntaxhighlight>

* The Nielsen Privacy Page appears using UIWebView

'''Privacy Page'''

[[File:privacy-policy.jpg]]

* There are two links – one for Opt-Out and one for Opt-In. Click the required link.
* Click OK in the dialog that appears, to confirm the action.
* The Opt-Out occurs by opening a Nielsen-defined web page and passing the user choice from the ‘WebView’. In order to do this, the application needs to
** Implement the UIWebView delegate method to open the Nielsen Privacy web page
** Capture user’s selection
** Pass the selection back to the SDK via the [[userOptOut]].

'''Capture and forward user selection'''
<syntaxhighlight lang="objective-c">-(BOOL)webView:(UIWebView *)webView shouldStartLoadWithRequest:(NSURLRequest *)request navigationType:(UIWebViewNavigationType)navigationType
{
NSString *command = [NSString stringWithFormat:@”%@”,request.URL];
if ([command isEqualToString:kNielsenWebClose]) {
// Close the WebView
[self performSelector:@selector(closeOptOutView) withObject:nil afterDelay:0];
return NO;
}
// Retrieve next URL if it’s not opt-in/out selection
return (![nAppApiObject userOptOut:command]);
}</syntaxhighlight>
* The app gets the user selection string via webviews shouldStartLoadWithRequest and invokes [[userOptOut]] with user selection. The delegate method handles the ‘WebView’ URL requests, interprets the commands, and calls the SDK accordingly.
* <code>[nAppApiObject userOptOut:command]</code> passes the user’s selection on Nielsen Privacy page to the SDK to allow the SDK to perform the required functions.
<blockquote>'''Note''': When ‘WebView’ is closed, pass the status returned from ‘WebView’ to the SDK within the app.</blockquote>

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

== AppApiEventCode ==
An enumeration with predefined App SDK event state transition codes.
<syntaxhighlight lang="objective-c">
typedef NS_ENUM(unsigned int, AppApiEventCode)
{
AppApiStartup = 2001,
AppApiShutdown = 2002,
}AppApiEventCode;
</syntaxhighlight>

== App SDK Event Codes ==
{| class="wikitable"
|-
! 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 ==
An enumeration with predefined error codes which the App SDK object can generate.
<syntaxhighlight lang="objective-c">
typedef NS_ENUM(unsigned int, AppApiErrorCode)
{
AppApiNetworkConnectionFailure = 1001,
AppApiFileWriteFailure = 1002,
AppApiFileReadFailure = 1003,
AppApiEmptyValue = 1004,
AppApiEmptyAppName = 1005,
AppApiEmptyAppVersion = 1006,
AppApiEmptyAppId = 1007,
AppApiAnExceptionOccured = 1008,
AppApiUnknownExceptionOccured = 1009
};
</syntaxhighlight>

== App SDK Error Codes ==
{| class="wikitable"
|-
! Event Code !! Event Name !! Event 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
|}

iOS SDK API Reference

2017-07-11T21:52:24Z

Admin2: /* Limit Ad Tracking */

{{Breadcrumb|}} {{Breadcrumb|Digital}} {{CurrentBreadcrumb}}
[[Category:Digital]]
The iOS 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. These SDKs leverage the following:
*Nielsen audio watermark technologies for TV audience measurement
*The industry supported ID3 metadata tag specification
*Nielsen Combined Beacon technology
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
*Application crash events
*Time of viewing a sub section / page in the application.

== Importing Frameworks ==
'''Setting up your Xcode Development Environment'''

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

SDK uses the NSURLSession available from iOS 7 instead of the deprecated NSURLConnection.

<blockquote>'''Note''': App SDK supports devices running on iOS 9 and above, as all communications between the SDK and the Census (Collection Facility) use HTTPS.</blockquote>

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 (Not applicable for International (Germany))
* 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

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

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

== Initialization ==
The latest version of App SDK allows instantiating multiple instances of App SDK object and can be used simultaneously without any issues (The sharedInstance API that creates a singleton object in previous versions of App SDK is removed).
*Maximum of four SDK instances per appid are supported in this release. When a fifth SDK instance is launched,
**SDK will return “nil” from [[initWithAppInfo:delegate:]]
**Destroy one or more old SDK instances before creating new ones.

=== Stages of SDK Initialization ===
==== Step 1: App SDK Initialization ====
Initialize the Nielsen App object within the viewDidLoad view controller delegate method using initWithAppInfo:delegate:
<blockquote>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.</blockquote>

==== Step 2: Setting up event and error notifications ====
Once the <code>NielsenAppApi</code> object has been initialized, the next step is to enable notifications regarding ID3 tags extracted from the playing stream. In case of standard AVFoundation player, the SDK NSNotificationCenter API is used to
* Collect HLS timed metadata events (ID3 tags) during viewing sessions.
** Set up a timed metadata event listener method for receiving ID3 tags and calling Nielsen [[sendID3]].
* SDK uses the following NielsenAppApiDelegate protocol methods to notify its delegate (set during initialization) about event / error information.
** nielsenAppApi:eventOccurred
** nielsenAppApi:errorOccurred
<blockquote>'''Note''': Ensure to add to your view controller’s <code>@interface</code>.</blockquote>

<syntaxhighlight lang="objective-c">(void)nielsenAppApi:(NielsenAppApi *)appApi eventOccurred:(NSDictionary *)event {NSLog(@"Sample player is Notified by a Event : %@", event);
}
(void)nielsenAppApi:(NielsenAppApi *)appApi errorOccurred:(NSDictionary *)error {NSLog(@"Sample player is Notified by an Error : %@", error);
}</syntaxhighlight>

===== Sample event confirmation to player application upon successful initialization of SDK =====
<syntaxhighlight lang="console">NielsenSDKSampleDebug[9028:237989] [Nls:0] -I- Analytics framework Status:
{
"Event Description" = "Nielsen App SDK Version, ai.4.0.0.4 is initialized by the Player…";
EventStatus = 2001;
TimeStamp = "2015-07-23 14:51:06 +0000";
}</syntaxhighlight>

==== Step 3: Nielsen App SDK Streaming Sessions ====
After setting up observers for SDK events/errors and a listener method to process incoming Nielsen ID3 tags, the next steps are to
* Call [[play]] while starting or resuming a streaming session.
* Load CMS metadata using [[loadMetadata]].
* During session play, call [[playheadPosition]] every one second until the stream is stopped or interrupted (due to ad breaks or buffering).
* Call [[stop]] when pausing, ending a viewing session, or buffering is detected.

'''Serialized JSON string from NSDictionary'''
<syntaxhighlight lang="objective-c">NSDictionary* appInformation = @
{
@"appid": @"TXXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX",
@"appname": @"Sample App Name",
@"appversion": @"2.0",
@"sfcode": @"uat-cert",
@"nol_devDebug": @"INFO"
}
NSData* jsonDataAppInfo = [NSJSONSerialization dataWithJSONObject:appInformation options:0 error:nil];
NSString *jsonAppInfoString = [[NSString alloc] initWithData:jsonDataAppInfo encoding:NSUTF8StringEncoding];
nlsAppApiMeter = [[NielsenAppApi alloc] initWithAppInfo:jsonAppInfoString delegate:self];</syntaxhighlight>

Nielsen App SDK object handles filtering of ID3 tags and CMS tags, queuing/buffering of data, and all communications with Nielsen collection facility.

===== Nielsen iOS App SDK Application Life Cycle =====

[[File:initialization_appcycle.png|center|link=]]

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 '''Initial state'''.
# '''Idle state''' – The SDK is initialized and is ready to process playing information. Call <code>[[initWithAppInfo:delegate:]]</code> to move into this state. The SDK instance is not processing any data, but is listening for the play event to occur.
# '''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.
## [[playheadPosition]] – Call this API every one second when playhead position timer is fired.
## [[sendID3]] – Call this API when ID3 tags are identified in the stream.
## [[stop]] – Call this API when the playback is paused, switches between content and ad (within the same content playback) or encounters interruptions.
## [[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. SDK instance moves into this state in one of the following scenarios.
## Initialization fails
## [[appDisableApi]] is called
<blockquote>'''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 [[sendID3]] / [[playheadPosition]].</blockquote>

=== 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.
{| class="wikitable"
|-
! API call received !! Initial State !! Idle State !! Processing State !! Disabled State
|-
| <code>[[initWithAppInfo:delegate:]]</code> || IDLE STATE (OR)

DISABLED STATE
|| IDLE STATE || - || -
|-
| <code>[[play]]</code> & <code>[[loadMetadata]]</code>|| - || PROCESSING

STATE
|| - || -
|-
| <code>[[playheadPosition]]</code> || - || - || PROCESSING

STATE
|| -
|-
| <code>[[sendID3]]</code> || - || - || PROCESSING

STATE
|| -
|-
| <code>[[stop]]</code> || - || - || IDLE STATE || -
|-
| <code>[[end]]</code> || - || - || IDLE STATE || -
|-
| <code>[[appDisableApi]]</code>: YES || - || DISABLED

STATE
|| - || -
|-
| <code>[[appDisableApi]]</code>: NO || - || - || - || IDLE STATE (OR)

DISABLED STATE
|-
| <code>[[userOptOut]]</code>: YES || - || - || IDLE STATE || -
|-
| <code>[[userOptOut]]</code>: NO || - || PROCESSING

STATE
| -
| -
|-
| colspan = 5 | '-' 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.

==== JSON for NSDictionary object ====
<syntaxhighlight lang="objective-c">
NSDictionary* appInformation = @{
@"appid": @"TXXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX",
@"appname": @"Sample App Name",
@"appversion": @"2.0",
@"sfcode": @"uat-cert",
@"nol_devDebug": @"INFO"
};
nlsAppApiMeter = [[NielsenAppApi alloc] initWithAppInfo:appInformation delegate:delegate];</syntaxhighlight>

<code>appid</code>, <code>appname</code>, and <code>appversion</code> are mandatory parameters while <code>sfcode</code> is optional. <code>nol_devDebug</code> is meant for creating logs in test environments only.

==== JSON string from raw NSString ====
<syntaxhighlight lang="swift">NSString *appInfoString = @"{\"appid\" : \"TXXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX\", \"appname\" : \"Sample App Name\",\"appversion\" : \"2.0\",\"sfcode\" : \"uat-cert\"}";
NielsenAppAPi *appAPI = [[NielsenAppApi alloc] initWithAppInfo:appInfoString delegate:self];</syntaxhighlight>

==== JSON string from serialized NSDictionary ====
<syntaxhighlight lang="objective-c">NSDictionary* appInformation = @
{
@"appid": @"appid",
@"appname": @"appname",
@"appversion": @"2.0",
@"sfcode": @"sfcode",
@"nol_devDebug": @"INFO"
};
nlsAppApiMeter = [[NielsenAppApi alloc] initWithAppInfo:appInformation delegate:self];</syntaxhighlight>

While using JSON format for sending metadat, ensure enough care in including [[special characters]] in the values for arguments.

==== Example ====
<syntaxhighlight lang="objective-c">{
@"type": @"radio", // To send "radio" in metadata string
@"assetid": @"WXYZ-FM'101",
@"stationType": @"3",
@"provider": @"SampleProvider" // To send "SampleProvider" in metadata string
}</syntaxhighlight>
<blockquote>'''Note''': For mandatory parameters like appid, appname, and appversion, please refer to the parameters table in <code>[[initWithAppInfo:delegate:]]</code></blockquote>

== Retrieving ID3 Tags ==
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.

=== Sample ID3 tags ===
* <code>www.nielsen.com/X100zdCIGeIlgZnkYj6UvQ==/X100zdCIGeIlgZnkYj6UvQ==/AAAB2Jz2_k74GXSzx4npHuI_JwJd3QSUpW30rDkGTcbHEzIMWleCzM-uvNOP9fzJcQMWQLJqzXMCAxParOb5sGijSV9dNM3QiBniJYGZ5GI-lL1fXTTN0IgZ4iWBmeRiPpS9AAAAAAAAAAAAAAAAAAAAAFJWFM5SVhTONNU=/00000/00000/00</code>
* <code>www.nielsen.com/X100zdCIGeIlgZnkYj6UvQ==/R8WHe7pEBeqBhu8jTeXydg==/AAICoyitYqlxT7n6aZ0oMCGheFi4CXFp46AMUPZz1lMr_M9tr3_cjee1SHqxrOiVerMDLeyn9xzocZSKwi746Re8vNOtpNCAZjYABs_J0R25IHpvOc1HS8QHGgD5TgOJeS6gX100zdCIGeIlgZnkYj6UvVJWFNhSVhTiPE0=/00000/46016/00</code>

=== Examples of extracting ID3 tags from the iOS Native Player ===
==== AVPlayer ====
ID3 tags will be received in the Player on AVMetadataItem Callback method.
'''Create & get the AVMetadataItem callback method'''
<syntaxhighlight lang="swift">[self.player addObserver:self
forKeyPath: kTimedMetadataKey
options: NSKeyValueObservingOptionNew
Context: MyStreamingMovieViewControllerTimedMetadataObserverContext];</syntaxhighlight>

<syntaxhighlight lang="objective-c">
– (void)observeValueForKeyPath:(NSString*) path
ofObject: (id)object
change: (NSDictionary*)change
context: (void*)context
{
/* Set the AVPlayerLayer on the view to allow the AVPlayer object to display
its content. */
//[playerLayerView.playerLayer setPlayer:player];
/* AVPlayerItem "status" property value observer. */
if (context == MyStreamingMovieViewControllerTimedMetadataObserverContext)
{
id newMetadataArray = [change objectForKey:NSKeyValueChangeNewKey];
if (newMetadataArray != [NSNull null])
{
array = newMetadataArray;
for (AVMetadataItem *metadataItem in array)
{
[self handleTimedMetadata: metadataItem];
}
}
}
</syntaxhighlight>

<syntaxhighlight lang="objective-c">
– (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;
}
if ([(NSString *)[timedMetadata key] isEqualToString:@"PRIV"]&&[extraString rangeOfString:@"www.nielsen.com"].length> 0)
{
if ([[timedMetadata value] isKindOfClass:[NSData class]])
{
// Sending ID3 Tag
/* The sendID3: sends the extracted Nielsen ID3 payload to the App SDK for analysis. */
[[NielsenAppApi sharedInstance]sendID3: extraString];
NSString *value=[timedMetadata stringValue];
if (value != nil)
{
// NSString *strMessage=[[@"ID3 Tag Received " stringByAppendingFormat:@"%d\n",countForMetadata] stringByAppendingString:value];
[self appendLogConsoleText:extraString];
}
}
}
else
{
NSLog(@"Could not send ID3 tags");
}
countForMetadata++;

}
</syntaxhighlight>

==== Movie Player ====
ID3 tags will be received in the Player on MPTimedMetadata Callback method.
'''Sample Implementation of MPTimedMetadata callback'''
<syntaxhighlight lang="objective-c">
– (void)handleTimedMetadata:(MPTimedMetadata*)timedMetadata
{
id extraAttributeType = [timedMetadata allMetadata];
NSString * extraString= nil;
if ([extraAttributeType isKindOfClass:[NSDictionary class]])
{
extraString = [extraAttributeType valueForKey:@"info"];
}
else if([extraAttributeType isKindOfClass:[NSString class]])
{
extraString = extraAttributeType;
}

if ([(NSString *)[timedMetadata key] isEqualToString:@"PRIV"]&&[extraString rangeOfString:@"www.nielsen.com"].length> 0)
{
if ([[timedMetadata value] isKindOfClass:[NSData class]])
{
// Sending ID3 Tag
[[NielsenAppApi sharedInstance]sendID3: extraString];
NSString *value=[timedMetadata value];
if (value != nil)
{

[self appendLogConsoleText:extraString];
}
}
}
else
{
NSLog(@"Could not send ID3 tags");
}
countForMetadata++;
}
</syntaxhighlight>
<blockquote>'''Note:''' ID3 tags are not applicable for International (Germany)</blockquote>

== IOS SDK API Methods & Properties ==
{| class="wikitable sortable"
|-
! Scenario !! Method / Property !! DTVR !! DAR !! Digital Audio !! 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 || [[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.
|-
| 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)
|}

== 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 to this web page should be called from SDK by invoking [[optOutURL]] and opened in 'WebView' / External browser.
*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 [[optOutStatus]] method.

=== Displaying Opt-Out in a WebView ===
<syntaxhighlight lang="objective-c">
NielsenAppApi nAppApiObject;
@property(strong) UIWebView *optOutView;
// create WebView and set self as delegate
self.optOutView=[[UIWebView alloc]initWithFrame:self.view.bounds];
self.optOutView.scalesPageToFit = yes;
// get Nielsen defined web address and load the page
NSString *webAddress = [nAppApiObject optOutURLString];
If(webAddress == nil)
{ // Handle it gracefully and retry later} else
{[optOutView loadRequest:[NSURLRequest requestWithURL:webAddress]];
// show the view to the user
[self.view addSubview:optOutView]; }
</syntaxhighlight>

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.

[[File:Privacy policy iOS.jpg|link=]]

*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.
<syntaxhighlight lang="objective-c">
@property (readonly) BOOL optOutStatus;
</syntaxhighlight>
*App should provide a UI control like 'close' or 'back' button to close the 'WebView' / External browser.

=== Sequence Diagram ===
[[File:optoutsequence-ios.jpg|link=]]

== Opt-out SDK Version '''5.1.1.17 or above''' ==
<blockquote>'''Note:''' If using SDK Versions 1.2.3, 4.0.0.8, 5.1.0, 5.1.1.12, skip ahead to: [[#Opt-out SDK Version 1.2.3, 4.0.0.8, 5.1.0, 5.1.1.12|Opt-out SDK Version 1.2.3, 4.0.0.8, 5.1.0, 5.1.1.12]]</blockquote>

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.

[[File:Opt-Out iOS.jpg|link=]]

<blockquote>'''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.</blockquote>

== Opt-out SDK Version '''1.2.3, 4.0.0.8, 5.1.0, 5.1.1.12''' ==
<blockquote>'''Note:''' If using SDK Version 5.1.1.17 or above, refer to documentation above ([[#Opt-out SDK Version 5.1.1.17 or above|Opt-out SDK Version 5.1.1.17 or above]])</blockquote>

When a user clicks the Opt-Out / Opt-In link, the application should invoke [[optOutURL]] to get the link to the Nielsen Privacy page from SDK.
=== Privacy Page ===
[[File:privacy-policy.jpg|link=]]
*There are two click here links – one for Opt-Out and one for Opt-In. Click the required link:
**
[[File:Opt-Out Combined.jpg|link=]]
*Click OK in the dialog that appears, to confirm the action.
*The Opt-Out occurs by opening a Nielsen-defined web page and passing the user choice from the 'WebView'. In order to do this, the application needs to
**Implement the UIWebView delegate method to open the Nielsen Privacy web page
**Capture user's selection
**Pass the selection back to the SDK via the [[userOptOut]].

=== Capture and forward user selection ===
<syntaxhighlight lang="objective-c">
-(BOOL)webView:(UIWebView *)webView
shouldStartLoadWithRequest:(NSURLRequest *)request
navigationType:(UIWebViewNavigationType)navigationType
{
NSString *command = [NSString stringWithFormat:@"%@",
request.URL];
if ([command isEqualToString:kNielsenWebClose]) {
// Close the WebView
[self performSelector:@selector(closeOptOutView)
withObject:nil afterDelay:0];
return NO;
}
// Retrieve next URL if it's not opt-in/out selection
return (![nAppApiObject userOptOut:command]);
}
</syntaxhighlight>

*The app gets the user selection string via webviews shouldStartLoadWithRequest and invokes [[userOptOut]] with user selection. The delegate method handles the 'WebView' URL requests, interprets the commands, and calls the SDK accordingly.
**<code>[nAppApiObject userOptOut:command]</code> passes the user's selection on Nielsen Privacy page to the SDK to allow the SDK to perform the required functions.
<blockquote>'''Note:''' When 'WebView' is closed, pass the status returned from 'WebView' to the SDK within the app.</blockquote>
<blockquote>'''Note:''' App SDK manages the user's choice (Opt-Out / Opt-In), the app does not need to manage this status.</blockquote>

== 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:

[[File:TVOs OptOut LimitAdTracking1.png|link=]]

[[File:TVOs OptOut LimitAdTracking2.png|link=]]

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.

<blockquote>'''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.</blockquote>

== 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:
<syntaxhighlight lang="objective-c">
@interface NielsenAppApi: NSObject

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

– (instancetype)initWithAppInfo:(id)appInfo delegate:(id)delegate;

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

– (NSString *)getNielsenId _attribute((deprecated((“Please use nielsenId property instead.”))));
– (NSString *)optOutURLString _attribute((deprecated((“Please use optOutURL property instead.”))));
– (NSString *)getMeterVersion _attribute((deprecated((“Please use meterVersion property instead.”))));
– (NSDictionary *)getLastEventDict _attribute((deprecated((“Please use lastEventDict property instead.”))));
– (NSDictionary *)getLastErrorDict _attribute((deprecated((“Please use lastErrorDict property instead.”))));

@protocol NielsenAppApiDelegate<NSObject>

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

@end
</syntaxhighlight>

== Nielsen Sample Applications ==
Nielsen iOS sample player application consists of two sample application based on native Players integrated with SDK framework. The player demonstrates all the supported functions of the SDK.
*NielsenVideoPlayer
*NielsenRadioPlayer
Implementation of Video and Audio 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 two locations:
**Channels 1 and 2 are configured from the Settings application. Channel URLs and metadata parameters can be modified.
**Channels starting from 3 are configured in specific JSON file. URLs to this JSON config file can be changed from the Settings application.

== Nielsen Privacy Requirements ==
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.
[[File:RatingsDataFlow.png]]

'''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 ===
{| class="wikitable"
|-
! Type of Information !! Parameter !! Transmitted to Nielsen? !! Sent to Provider?
|-
| rowspan="8" | 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
|-
| rowspan="10" | 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
|-
| rowspan="9" | 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
|}
<blockquote>'''Note''': Data is hashed, and encrypted using AES 128 before transmission to data provider.</blockquote>

==== Example ping sent to provider ====
* <code><nowiki>https://provider.com/cgi-bin/brandlift.php</nowiki>?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</code>

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

=== Nielsen Measurement Opt-Out ===
In accordance with Nielsen’s SDK licensing agreement, developers are required to provide basic informational data to users about Nielsen’s Privacy Policy with a navigation to additional information on Nielsen measurement.

Nielsen currently uses Limit Ad Tracking for the latest versions of the SDK (5.1.1.17 and above). However, for older SDK versions, the app must provide a means for the user to opt out, or opt back in to Nielsen Measurement. Users can opt out of Nielsen online measurement research through this feature.
* If the user has this app running on more than one mobile device, the user will need to opt out of this measurement on each device.
<blockquote>'''Note''': Opt Out feature does NOT rely on "Limit Ad Tracking" setting since Nielsen’s systems provide measurement metrics and do not serve ads to users.</blockquote>

In the Description of the app in App Store, include a short description about Nielsen measurement, as below.

<blockquote>'''Sample App Store Disclosure'''
This app features Nielsen proprietary measurement software which will allow you to contribute to market research, like Nielsen’s TV Ratings.

To learn more about our digital measurement products and your choices in regard to them, please visit http://www.nielsen.com/digitalprivacy for more information.

[[File:measurement-samplescreen.jpg]]</blockquote>

Both iOS-based and TVOS-based player applications need to confirm to Nielsen Privacy Requirements. Refer to the Opt-Out implementation guidelines for iOS and TVOS platforms respectively for more details.

=== Opt-Out Implementation ===
==== Limit Ad Tracking ====
'''This implementation is valid for SDK Versions 5.1.1.17 and above.'''

<blockquote>'''Note''': If using SDK Version 1.2.3, 4.0.0.8, 5.1.0 or 5.1.1.12, refer to [[#Legacy_Opt-Out|Legacy Opt-Out Implementation for iOS]].</blockquote>

As a global information and measurement leader, Nielsen is committed to protect the privacy and security of the data they collect, process and use. Nielsen strongly believes that the consumer should have a way to opt out of Nielsen measurement.

The Nielsen digital measurement products help Nielsen and its clients to measure and analyze how consumers engage with media across online, mobile and emerging technologies while offering insights into consumer behavior.

To learn more about our digital measurement products and your choices in regard to them, please visit http://www.nielsen.com/digitalprivacy.

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 optOutURL and opened in ‘WebView’ / External browser.
* 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 optOutStatus method.
'''Displaying Opt-Out in a WebView'''
<syntaxhighlight lang="objective-c">NielsenAppApi nAppApiObject;
@property(strong) UIWebView *optOutView;
// create WebView and set self as delegate
self.optOutView=[[UIWebView alloc]initWithFrame:self.view.bounds];
self.optOutView.scalesPageToFit = yes;
// get Nielsen defined web address and load the page
NSString *webAddress = [nAppApiObject optOutURLString];
If(webAddress == nil)
{
// Handle it gracefully and retry later
}

else
{
[optOutView loadRequest:[NSURLRequest requestWithURL:webAddress]];
// show the view to the user
[self.view addSubview:optOutView];
}</syntaxhighlight>

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.

[[File:Opt-Out_iOS.jpg]]
<blockquote>'''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.</blockquote>

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.

[[File: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.
<syntaxhighlight lang="objective-c">@property (readonly) BOOL optOutStatus;</blockquote>
* App should provide a UI control like ‘close’ or ‘back’ button to close the ‘WebView’ / External browser.

'''Sequence Diagram'''
[[File:optoutsequence-ios.jpg]]

== Event and Error Handling ==
=== Constants / Enumerations ===
The following are the details of Delegate Implementation:

<syntaxhighlight lang="objective-c">
-(void)nielsenAppApi:(NielsenAppApi *)appApi eventOccurred:(NSDictionary *)event
{
NSLog(@"Sample player is Notified by a Event: %@", event);
}
– (void)nielsenAppApi:(NielsenAppApi *)appApi errorOccurred:(NSDictionary *)error
{
NSLog(@"Sample player is Notified by an Error: %@", error);
}
</syntaxhighlight>

==== TVOS Implementation ====
As a global information and measurement leader, Nielsen is committed to protect the privacy and security of the data they collect, process and use. Nielsen strongly believes that the client should have a way to Opt-Out of Nielsen measurement.

The Nielsen digital measurement products are not used to identify consumer in any way. They help Nielsen and its clients to measure and analyze how consumers engage with media across online, mobile and emerging technologies while offering insights into consumer behavior.

To learn more about our digital measurement products and your choices in regard to them, please visit http://www.nielsen.com/digitalprivacy.

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.

[[File:TVOs_OptOut_LimitAdTracking1.png]]

[[File:TVOs_OptOut_LimitAdTracking2.png]]

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.

<blockquote>'''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.</blockquote>

==== Legacy Opt-Out ====
'''Supported SDK Versions''': 1.2.3, 4.0.0.8, 5.1.0, 5.1.1.12.

<blockquote>'''Note''': If using SDK Version 5.1.1.17 or above, refer to Opt-Out Implementation (Limit Ad Tracking).</blockquote>

As a global information and measurement leader, Nielsen is committed to protect the privacy and security of the data they collect, process and use. Nielsen strongly believes that the consumer should have a way to Opt-Out of Nielsen measurement.

The Nielsen digital measurement products help Nielsen and its clients to measure and analyze how consumers engage with media across online, mobile and emerging technologies while offering insights into consumer behavior.

To learn more about our digital measurement products and your choices in regard to them, please visit http://www.nielsen.com/digitalprivacy.

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 [[optOutURL]] and opened in ‘WebView’ within the app and NOT in any external browser.
** Opening the Opt-Out page in any external browser takes the application control out of the Nielsen App SDK context.
** As the App SDK does not expose any direct http/https interface to interact with the world to get the user selection on Privacy page, there will be no way to interact/send notification to the App SDK regarding the user selection.
* 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 [[optOutStatus]] method.
<blockquote>'''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.</blockquote>

'''Sequence Diagram'''
[[File:optoutsequence-ios.jpg]]

Below are the steps to implement user Opt-Out using UIWebView.

When a user clicks the Opt-Out / Opt-In link, the application should invoke [[optOutURL]] to get the link to the Nielsen Privacy page from SDK.

'''Implement WebView with Nielsen Opt-Out URL'''
<syntaxhighlight lang="objective-c">NielsenAppApi nAppApiObject;
@property(strong) UIWebView *optOutView;

// create WebView and set self as delegate
self.optOutView=[[UIWebViewalloc]initWithFrame:self.view.bounds];

self.optOutView.scalesPageToFit = yes;
// get Nielsen defined web address and load the page
NSString *webAddress = [nAppApiObject optOutURLString];

if(webAddress == nil)
{ // Handle it gracefully and retry later}
else
{
[optOutView loadRequest:[NSURLRequest requestWithURL:webAddress]];
// show the view to the user
[self.view addSubview:optOutView];
}</syntaxhighlight>

* The Nielsen Privacy Page appears using UIWebView

'''Privacy Page'''

[[File:privacy-policy.jpg]]

* There are two links – one for Opt-Out and one for Opt-In. Click the required link.
* Click OK in the dialog that appears, to confirm the action.
* The Opt-Out occurs by opening a Nielsen-defined web page and passing the user choice from the ‘WebView’. In order to do this, the application needs to
** Implement the UIWebView delegate method to open the Nielsen Privacy web page
** Capture user’s selection
** Pass the selection back to the SDK via the [[userOptOut]].

'''Capture and forward user selection'''
<syntaxhighlight lang="objective-c">-(BOOL)webView:(UIWebView *)webView shouldStartLoadWithRequest:(NSURLRequest *)request navigationType:(UIWebViewNavigationType)navigationType
{
NSString *command = [NSString stringWithFormat:@”%@”,request.URL];
if ([command isEqualToString:kNielsenWebClose]) {
// Close the WebView
[self performSelector:@selector(closeOptOutView) withObject:nil afterDelay:0];
return NO;
}
// Retrieve next URL if it’s not opt-in/out selection
return (![nAppApiObject userOptOut:command]);
}</syntaxhighlight>
* The app gets the user selection string via webviews shouldStartLoadWithRequest and invokes [[userOptOut]] with user selection. The delegate method handles the ‘WebView’ URL requests, interprets the commands, and calls the SDK accordingly.
* <code>[nAppApiObject userOptOut:command]</code> passes the user’s selection on Nielsen Privacy page to the SDK to allow the SDK to perform the required functions.
<blockquote>'''Note''': When ‘WebView’ is closed, pass the status returned from ‘WebView’ to the SDK within the app.</blockquote>

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

== AppApiEventCode ==
An enumeration with predefined App SDK event state transition codes.
<syntaxhighlight lang="objective-c">
typedef NS_ENUM(unsigned int, AppApiEventCode)
{
AppApiStartup = 2001,
AppApiShutdown = 2002,
}AppApiEventCode;
</syntaxhighlight>

== App SDK Event Codes ==
{| class="wikitable"
|-
! 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 ==
An enumeration with predefined error codes which the App SDK object can generate.
<syntaxhighlight lang="objective-c">
typedef NS_ENUM(unsigned int, AppApiErrorCode)
{
AppApiNetworkConnectionFailure = 1001,
AppApiFileWriteFailure = 1002,
AppApiFileReadFailure = 1003,
AppApiEmptyValue = 1004,
AppApiEmptyAppName = 1005,
AppApiEmptyAppVersion = 1006,
AppApiEmptyAppId = 1007,
AppApiAnExceptionOccured = 1008,
AppApiUnknownExceptionOccured = 1009
};
</syntaxhighlight>

== App SDK Error Codes ==
{| class="wikitable"
|-
! Event Code !! Event Name !! Event 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
|}

iOS SDK API Reference

2017-07-11T21:51:08Z

Admin2: /* App SDK Error Codes */

{{Breadcrumb|}} {{Breadcrumb|Digital}} {{CurrentBreadcrumb}}
[[Category:Digital]]
The iOS 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. These SDKs leverage the following:
*Nielsen audio watermark technologies for TV audience measurement
*The industry supported ID3 metadata tag specification
*Nielsen Combined Beacon technology
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
*Application crash events
*Time of viewing a sub section / page in the application.

== Importing Frameworks ==
'''Setting up your Xcode Development Environment'''

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

SDK uses the NSURLSession available from iOS 7 instead of the deprecated NSURLConnection.

<blockquote>'''Note''': App SDK supports devices running on iOS 9 and above, as all communications between the SDK and the Census (Collection Facility) use HTTPS.</blockquote>

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 (Not applicable for International (Germany))
* 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

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

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

== Initialization ==
The latest version of App SDK allows instantiating multiple instances of App SDK object and can be used simultaneously without any issues (The sharedInstance API that creates a singleton object in previous versions of App SDK is removed).
*Maximum of four SDK instances per appid are supported in this release. When a fifth SDK instance is launched,
**SDK will return “nil” from [[initWithAppInfo:delegate:]]
**Destroy one or more old SDK instances before creating new ones.

=== Stages of SDK Initialization ===
==== Step 1: App SDK Initialization ====
Initialize the Nielsen App object within the viewDidLoad view controller delegate method using initWithAppInfo:delegate:
<blockquote>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.</blockquote>

==== Step 2: Setting up event and error notifications ====
Once the <code>NielsenAppApi</code> object has been initialized, the next step is to enable notifications regarding ID3 tags extracted from the playing stream. In case of standard AVFoundation player, the SDK NSNotificationCenter API is used to
* Collect HLS timed metadata events (ID3 tags) during viewing sessions.
** Set up a timed metadata event listener method for receiving ID3 tags and calling Nielsen [[sendID3]].
* SDK uses the following NielsenAppApiDelegate protocol methods to notify its delegate (set during initialization) about event / error information.
** nielsenAppApi:eventOccurred
** nielsenAppApi:errorOccurred
<blockquote>'''Note''': Ensure to add to your view controller’s <code>@interface</code>.</blockquote>

<syntaxhighlight lang="objective-c">(void)nielsenAppApi:(NielsenAppApi *)appApi eventOccurred:(NSDictionary *)event {NSLog(@"Sample player is Notified by a Event : %@", event);
}
(void)nielsenAppApi:(NielsenAppApi *)appApi errorOccurred:(NSDictionary *)error {NSLog(@"Sample player is Notified by an Error : %@", error);
}</syntaxhighlight>

===== Sample event confirmation to player application upon successful initialization of SDK =====
<syntaxhighlight lang="console">NielsenSDKSampleDebug[9028:237989] [Nls:0] -I- Analytics framework Status:
{
"Event Description" = "Nielsen App SDK Version, ai.4.0.0.4 is initialized by the Player…";
EventStatus = 2001;
TimeStamp = "2015-07-23 14:51:06 +0000";
}</syntaxhighlight>

==== Step 3: Nielsen App SDK Streaming Sessions ====
After setting up observers for SDK events/errors and a listener method to process incoming Nielsen ID3 tags, the next steps are to
* Call [[play]] while starting or resuming a streaming session.
* Load CMS metadata using [[loadMetadata]].
* During session play, call [[playheadPosition]] every one second until the stream is stopped or interrupted (due to ad breaks or buffering).
* Call [[stop]] when pausing, ending a viewing session, or buffering is detected.

'''Serialized JSON string from NSDictionary'''
<syntaxhighlight lang="objective-c">NSDictionary* appInformation = @
{
@"appid": @"TXXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX",
@"appname": @"Sample App Name",
@"appversion": @"2.0",
@"sfcode": @"uat-cert",
@"nol_devDebug": @"INFO"
}
NSData* jsonDataAppInfo = [NSJSONSerialization dataWithJSONObject:appInformation options:0 error:nil];
NSString *jsonAppInfoString = [[NSString alloc] initWithData:jsonDataAppInfo encoding:NSUTF8StringEncoding];
nlsAppApiMeter = [[NielsenAppApi alloc] initWithAppInfo:jsonAppInfoString delegate:self];</syntaxhighlight>

Nielsen App SDK object handles filtering of ID3 tags and CMS tags, queuing/buffering of data, and all communications with Nielsen collection facility.

===== Nielsen iOS App SDK Application Life Cycle =====

[[File:initialization_appcycle.png|center|link=]]

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 '''Initial state'''.
# '''Idle state''' – The SDK is initialized and is ready to process playing information. Call <code>[[initWithAppInfo:delegate:]]</code> to move into this state. The SDK instance is not processing any data, but is listening for the play event to occur.
# '''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.
## [[playheadPosition]] – Call this API every one second when playhead position timer is fired.
## [[sendID3]] – Call this API when ID3 tags are identified in the stream.
## [[stop]] – Call this API when the playback is paused, switches between content and ad (within the same content playback) or encounters interruptions.
## [[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. SDK instance moves into this state in one of the following scenarios.
## Initialization fails
## [[appDisableApi]] is called
<blockquote>'''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 [[sendID3]] / [[playheadPosition]].</blockquote>

=== 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.
{| class="wikitable"
|-
! API call received !! Initial State !! Idle State !! Processing State !! Disabled State
|-
| <code>[[initWithAppInfo:delegate:]]</code> || IDLE STATE (OR)

DISABLED STATE
|| IDLE STATE || - || -
|-
| <code>[[play]]</code> & <code>[[loadMetadata]]</code>|| - || PROCESSING

STATE
|| - || -
|-
| <code>[[playheadPosition]]</code> || - || - || PROCESSING

STATE
|| -
|-
| <code>[[sendID3]]</code> || - || - || PROCESSING

STATE
|| -
|-
| <code>[[stop]]</code> || - || - || IDLE STATE || -
|-
| <code>[[end]]</code> || - || - || IDLE STATE || -
|-
| <code>[[appDisableApi]]</code>: YES || - || DISABLED

STATE
|| - || -
|-
| <code>[[appDisableApi]]</code>: NO || - || - || - || IDLE STATE (OR)

DISABLED STATE
|-
| <code>[[userOptOut]]</code>: YES || - || - || IDLE STATE || -
|-
| <code>[[userOptOut]]</code>: NO || - || PROCESSING

STATE
| -
| -
|-
| colspan = 5 | '-' 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.

==== JSON for NSDictionary object ====
<syntaxhighlight lang="objective-c">
NSDictionary* appInformation = @{
@"appid": @"TXXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX",
@"appname": @"Sample App Name",
@"appversion": @"2.0",
@"sfcode": @"uat-cert",
@"nol_devDebug": @"INFO"
};
nlsAppApiMeter = [[NielsenAppApi alloc] initWithAppInfo:appInformation delegate:delegate];</syntaxhighlight>

<code>appid</code>, <code>appname</code>, and <code>appversion</code> are mandatory parameters while <code>sfcode</code> is optional. <code>nol_devDebug</code> is meant for creating logs in test environments only.

==== JSON string from raw NSString ====
<syntaxhighlight lang="swift">NSString *appInfoString = @"{\"appid\" : \"TXXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX\", \"appname\" : \"Sample App Name\",\"appversion\" : \"2.0\",\"sfcode\" : \"uat-cert\"}";
NielsenAppAPi *appAPI = [[NielsenAppApi alloc] initWithAppInfo:appInfoString delegate:self];</syntaxhighlight>

==== JSON string from serialized NSDictionary ====
<syntaxhighlight lang="objective-c">NSDictionary* appInformation = @
{
@"appid": @"appid",
@"appname": @"appname",
@"appversion": @"2.0",
@"sfcode": @"sfcode",
@"nol_devDebug": @"INFO"
};
nlsAppApiMeter = [[NielsenAppApi alloc] initWithAppInfo:appInformation delegate:self];</syntaxhighlight>

While using JSON format for sending metadat, ensure enough care in including [[special characters]] in the values for arguments.

==== Example ====
<syntaxhighlight lang="objective-c">{
@"type": @"radio", // To send "radio" in metadata string
@"assetid": @"WXYZ-FM'101",
@"stationType": @"3",
@"provider": @"SampleProvider" // To send "SampleProvider" in metadata string
}</syntaxhighlight>
<blockquote>'''Note''': For mandatory parameters like appid, appname, and appversion, please refer to the parameters table in <code>[[initWithAppInfo:delegate:]]</code></blockquote>

== Retrieving ID3 Tags ==
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.

=== Sample ID3 tags ===
* <code>www.nielsen.com/X100zdCIGeIlgZnkYj6UvQ==/X100zdCIGeIlgZnkYj6UvQ==/AAAB2Jz2_k74GXSzx4npHuI_JwJd3QSUpW30rDkGTcbHEzIMWleCzM-uvNOP9fzJcQMWQLJqzXMCAxParOb5sGijSV9dNM3QiBniJYGZ5GI-lL1fXTTN0IgZ4iWBmeRiPpS9AAAAAAAAAAAAAAAAAAAAAFJWFM5SVhTONNU=/00000/00000/00</code>
* <code>www.nielsen.com/X100zdCIGeIlgZnkYj6UvQ==/R8WHe7pEBeqBhu8jTeXydg==/AAICoyitYqlxT7n6aZ0oMCGheFi4CXFp46AMUPZz1lMr_M9tr3_cjee1SHqxrOiVerMDLeyn9xzocZSKwi746Re8vNOtpNCAZjYABs_J0R25IHpvOc1HS8QHGgD5TgOJeS6gX100zdCIGeIlgZnkYj6UvVJWFNhSVhTiPE0=/00000/46016/00</code>

=== Examples of extracting ID3 tags from the iOS Native Player ===
==== AVPlayer ====
ID3 tags will be received in the Player on AVMetadataItem Callback method.
'''Create & get the AVMetadataItem callback method'''
<syntaxhighlight lang="swift">[self.player addObserver:self
forKeyPath: kTimedMetadataKey
options: NSKeyValueObservingOptionNew
Context: MyStreamingMovieViewControllerTimedMetadataObserverContext];</syntaxhighlight>

<syntaxhighlight lang="objective-c">
– (void)observeValueForKeyPath:(NSString*) path
ofObject: (id)object
change: (NSDictionary*)change
context: (void*)context
{
/* Set the AVPlayerLayer on the view to allow the AVPlayer object to display
its content. */
//[playerLayerView.playerLayer setPlayer:player];
/* AVPlayerItem "status" property value observer. */
if (context == MyStreamingMovieViewControllerTimedMetadataObserverContext)
{
id newMetadataArray = [change objectForKey:NSKeyValueChangeNewKey];
if (newMetadataArray != [NSNull null])
{
array = newMetadataArray;
for (AVMetadataItem *metadataItem in array)
{
[self handleTimedMetadata: metadataItem];
}
}
}
</syntaxhighlight>

<syntaxhighlight lang="objective-c">
– (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;
}
if ([(NSString *)[timedMetadata key] isEqualToString:@"PRIV"]&&[extraString rangeOfString:@"www.nielsen.com"].length> 0)
{
if ([[timedMetadata value] isKindOfClass:[NSData class]])
{
// Sending ID3 Tag
/* The sendID3: sends the extracted Nielsen ID3 payload to the App SDK for analysis. */
[[NielsenAppApi sharedInstance]sendID3: extraString];
NSString *value=[timedMetadata stringValue];
if (value != nil)
{
// NSString *strMessage=[[@"ID3 Tag Received " stringByAppendingFormat:@"%d\n",countForMetadata] stringByAppendingString:value];
[self appendLogConsoleText:extraString];
}
}
}
else
{
NSLog(@"Could not send ID3 tags");
}
countForMetadata++;

}
</syntaxhighlight>

==== Movie Player ====
ID3 tags will be received in the Player on MPTimedMetadata Callback method.
'''Sample Implementation of MPTimedMetadata callback'''
<syntaxhighlight lang="objective-c">
– (void)handleTimedMetadata:(MPTimedMetadata*)timedMetadata
{
id extraAttributeType = [timedMetadata allMetadata];
NSString * extraString= nil;
if ([extraAttributeType isKindOfClass:[NSDictionary class]])
{
extraString = [extraAttributeType valueForKey:@"info"];
}
else if([extraAttributeType isKindOfClass:[NSString class]])
{
extraString = extraAttributeType;
}

if ([(NSString *)[timedMetadata key] isEqualToString:@"PRIV"]&&[extraString rangeOfString:@"www.nielsen.com"].length> 0)
{
if ([[timedMetadata value] isKindOfClass:[NSData class]])
{
// Sending ID3 Tag
[[NielsenAppApi sharedInstance]sendID3: extraString];
NSString *value=[timedMetadata value];
if (value != nil)
{

[self appendLogConsoleText:extraString];
}
}
}
else
{
NSLog(@"Could not send ID3 tags");
}
countForMetadata++;
}
</syntaxhighlight>
<blockquote>'''Note:''' ID3 tags are not applicable for International (Germany)</blockquote>

== IOS SDK API Methods & Properties ==
{| class="wikitable sortable"
|-
! Scenario !! Method / Property !! DTVR !! DAR !! Digital Audio !! 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 || [[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.
|-
| 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)
|}

== 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 to this web page should be called from SDK by invoking [[optOutURL]] and opened in 'WebView' / External browser.
*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 [[optOutStatus]] method.

=== Displaying Opt-Out in a WebView ===
<syntaxhighlight lang="objective-c">
NielsenAppApi nAppApiObject;
@property(strong) UIWebView *optOutView;
// create WebView and set self as delegate
self.optOutView=[[UIWebView alloc]initWithFrame:self.view.bounds];
self.optOutView.scalesPageToFit = yes;
// get Nielsen defined web address and load the page
NSString *webAddress = [nAppApiObject optOutURLString];
If(webAddress == nil)
{ // Handle it gracefully and retry later} else
{[optOutView loadRequest:[NSURLRequest requestWithURL:webAddress]];
// show the view to the user
[self.view addSubview:optOutView]; }
</syntaxhighlight>

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.

[[File:Privacy policy iOS.jpg|link=]]

*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.
<syntaxhighlight lang="objective-c">
@property (readonly) BOOL optOutStatus;
</syntaxhighlight>
*App should provide a UI control like 'close' or 'back' button to close the 'WebView' / External browser.

=== Sequence Diagram ===
[[File:optoutsequence-ios.jpg|link=]]

== Opt-out SDK Version '''5.1.1.17 or above''' ==
<blockquote>'''Note:''' If using SDK Versions 1.2.3, 4.0.0.8, 5.1.0, 5.1.1.12, skip ahead to: [[#Opt-out SDK Version 1.2.3, 4.0.0.8, 5.1.0, 5.1.1.12|Opt-out SDK Version 1.2.3, 4.0.0.8, 5.1.0, 5.1.1.12]]</blockquote>

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.

[[File:Opt-Out iOS.jpg|link=]]

<blockquote>'''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.</blockquote>

== Opt-out SDK Version '''1.2.3, 4.0.0.8, 5.1.0, 5.1.1.12''' ==
<blockquote>'''Note:''' If using SDK Version 5.1.1.17 or above, refer to documentation above ([[#Opt-out SDK Version 5.1.1.17 or above|Opt-out SDK Version 5.1.1.17 or above]])</blockquote>

When a user clicks the Opt-Out / Opt-In link, the application should invoke [[optOutURL]] to get the link to the Nielsen Privacy page from SDK.
=== Privacy Page ===
[[File:privacy-policy.jpg|link=]]
*There are two click here links – one for Opt-Out and one for Opt-In. Click the required link:
**
[[File:Opt-Out Combined.jpg|link=]]
*Click OK in the dialog that appears, to confirm the action.
*The Opt-Out occurs by opening a Nielsen-defined web page and passing the user choice from the 'WebView'. In order to do this, the application needs to
**Implement the UIWebView delegate method to open the Nielsen Privacy web page
**Capture user's selection
**Pass the selection back to the SDK via the [[userOptOut]].

=== Capture and forward user selection ===
<syntaxhighlight lang="objective-c">
-(BOOL)webView:(UIWebView *)webView
shouldStartLoadWithRequest:(NSURLRequest *)request
navigationType:(UIWebViewNavigationType)navigationType
{
NSString *command = [NSString stringWithFormat:@"%@",
request.URL];
if ([command isEqualToString:kNielsenWebClose]) {
// Close the WebView
[self performSelector:@selector(closeOptOutView)
withObject:nil afterDelay:0];
return NO;
}
// Retrieve next URL if it's not opt-in/out selection
return (![nAppApiObject userOptOut:command]);
}
</syntaxhighlight>

*The app gets the user selection string via webviews shouldStartLoadWithRequest and invokes [[userOptOut]] with user selection. The delegate method handles the 'WebView' URL requests, interprets the commands, and calls the SDK accordingly.
**<code>[nAppApiObject userOptOut:command]</code> passes the user's selection on Nielsen Privacy page to the SDK to allow the SDK to perform the required functions.
<blockquote>'''Note:''' When 'WebView' is closed, pass the status returned from 'WebView' to the SDK within the app.</blockquote>
<blockquote>'''Note:''' App SDK manages the user's choice (Opt-Out / Opt-In), the app does not need to manage this status.</blockquote>

== 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:

[[File:TVOs OptOut LimitAdTracking1.png|link=]]

[[File:TVOs OptOut LimitAdTracking2.png|link=]]

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.

<blockquote>'''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.</blockquote>

== 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:
<syntaxhighlight lang="objective-c">
@interface NielsenAppApi: NSObject

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

– (instancetype)initWithAppInfo:(id)appInfo delegate:(id)delegate;

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

– (NSString *)getNielsenId _attribute((deprecated((“Please use nielsenId property instead.”))));
– (NSString *)optOutURLString _attribute((deprecated((“Please use optOutURL property instead.”))));
– (NSString *)getMeterVersion _attribute((deprecated((“Please use meterVersion property instead.”))));
– (NSDictionary *)getLastEventDict _attribute((deprecated((“Please use lastEventDict property instead.”))));
– (NSDictionary *)getLastErrorDict _attribute((deprecated((“Please use lastErrorDict property instead.”))));

@protocol NielsenAppApiDelegate<NSObject>

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

@end
</syntaxhighlight>

== Nielsen Sample Applications ==
Nielsen iOS sample player application consists of two sample application based on native Players integrated with SDK framework. The player demonstrates all the supported functions of the SDK.
*NielsenVideoPlayer
*NielsenRadioPlayer
Implementation of Video and Audio 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 two locations:
**Channels 1 and 2 are configured from the Settings application. Channel URLs and metadata parameters can be modified.
**Channels starting from 3 are configured in specific JSON file. URLs to this JSON config file can be changed from the Settings application.

== Nielsen Privacy Requirements ==
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.
[[File:RatingsDataFlow.png]]

'''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 ===
{| class="wikitable"
|-
! Type of Information !! Parameter !! Transmitted to Nielsen? !! Sent to Provider?
|-
| rowspan="8" | 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
|-
| rowspan="10" | 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
|-
| rowspan="9" | 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
|}
<blockquote>'''Note''': Data is hashed, and encrypted using AES 128 before transmission to data provider.</blockquote>

==== Example ping sent to provider ====
* <code><nowiki>https://provider.com/cgi-bin/brandlift.php</nowiki>?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</code>

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

=== Nielsen Measurement Opt-Out ===
In accordance with Nielsen’s SDK licensing agreement, developers are required to provide basic informational data to users about Nielsen’s Privacy Policy with a navigation to additional information on Nielsen measurement.

Nielsen currently uses Limit Ad Tracking for the latest versions of the SDK (5.1.1.17 and above). However, for older SDK versions, the app must provide a means for the user to opt out, or opt back in to Nielsen Measurement. Users can opt out of Nielsen online measurement research through this feature.
* If the user has this app running on more than one mobile device, the user will need to opt out of this measurement on each device.
<blockquote>'''Note''': Opt Out feature does NOT rely on "Limit Ad Tracking" setting since Nielsen’s systems provide measurement metrics and do not serve ads to users.</blockquote>

In the Description of the app in App Store, include a short description about Nielsen measurement, as below.

<blockquote>'''Sample App Store Disclosure'''
This app features Nielsen proprietary measurement software which will allow you to contribute to market research, like Nielsen’s TV Ratings.

To learn more about our digital measurement products and your choices in regard to them, please visit http://www.nielsen.com/digitalprivacy for more information.

[[File:measurement-samplescreen.jpg]]</blockquote>

Both iOS-based and TVOS-based player applications need to confirm to Nielsen Privacy Requirements. Refer to the Opt-Out implementation guidelines for iOS and TVOS platforms respectively for more details.

=== Opt-Out Implementation ===
==== Limit Ad Tracking ====
'''This implementation is valid for SDK Versions 5.1.1.17 and above.'''

<blockquote>'''Note''': If using SDK Version 1.2.3, 4.0.0.8, 5.1.0 or 5.1.1.12, refer to Opt-Out Implementation for iOS.</blockquote>

As a global information and measurement leader, Nielsen is committed to protect the privacy and security of the data they collect, process and use. Nielsen strongly believes that the consumer should have a way to opt out of Nielsen measurement.

The Nielsen digital measurement products help Nielsen and its clients to measure and analyze how consumers engage with media across online, mobile and emerging technologies while offering insights into consumer behavior.

To learn more about our digital measurement products and your choices in regard to them, please visit http://www.nielsen.com/digitalprivacy.

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 optOutURL and opened in ‘WebView’ / External browser.
* 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 optOutStatus method.
'''Displaying Opt-Out in a WebView'''
<syntaxhighlight lang="objective-c">NielsenAppApi nAppApiObject;
@property(strong) UIWebView *optOutView;
// create WebView and set self as delegate
self.optOutView=[[UIWebView alloc]initWithFrame:self.view.bounds];
self.optOutView.scalesPageToFit = yes;
// get Nielsen defined web address and load the page
NSString *webAddress = [nAppApiObject optOutURLString];
If(webAddress == nil)
{
// Handle it gracefully and retry later
}

else
{
[optOutView loadRequest:[NSURLRequest requestWithURL:webAddress]];
// show the view to the user
[self.view addSubview:optOutView];
}</syntaxhighlight>

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.

[[File:Opt-Out_iOS.jpg]]
<blockquote>'''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.</blockquote>

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.

[[File: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.
<syntaxhighlight lang="objective-c">@property (readonly) BOOL optOutStatus;</blockquote>
* App should provide a UI control like ‘close’ or ‘back’ button to close the ‘WebView’ / External browser.

'''Sequence Diagram'''
[[File:optoutsequence-ios.jpg]]

== Event and Error Handling ==
=== Constants / Enumerations ===
The following are the details of Delegate Implementation:

<syntaxhighlight lang="objective-c">
-(void)nielsenAppApi:(NielsenAppApi *)appApi eventOccurred:(NSDictionary *)event
{
NSLog(@"Sample player is Notified by a Event: %@", event);
}
– (void)nielsenAppApi:(NielsenAppApi *)appApi errorOccurred:(NSDictionary *)error
{
NSLog(@"Sample player is Notified by an Error: %@", error);
}
</syntaxhighlight>

==== TVOS Implementation ====
As a global information and measurement leader, Nielsen is committed to protect the privacy and security of the data they collect, process and use. Nielsen strongly believes that the client should have a way to Opt-Out of Nielsen measurement.

The Nielsen digital measurement products are not used to identify consumer in any way. They help Nielsen and its clients to measure and analyze how consumers engage with media across online, mobile and emerging technologies while offering insights into consumer behavior.

To learn more about our digital measurement products and your choices in regard to them, please visit http://www.nielsen.com/digitalprivacy.

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.

[[File:TVOs_OptOut_LimitAdTracking1.png]]

[[File:TVOs_OptOut_LimitAdTracking2.png]]

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.

<blockquote>'''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.</blockquote>

==== Legacy Opt-Out ====
'''Supported SDK Versions''': 1.2.3, 4.0.0.8, 5.1.0, 5.1.1.12.

<blockquote>'''Note''': If using SDK Version 5.1.1.17 or above, refer to Opt-Out Implementation (Limit Ad Tracking).</blockquote>

As a global information and measurement leader, Nielsen is committed to protect the privacy and security of the data they collect, process and use. Nielsen strongly believes that the consumer should have a way to Opt-Out of Nielsen measurement.

The Nielsen digital measurement products help Nielsen and its clients to measure and analyze how consumers engage with media across online, mobile and emerging technologies while offering insights into consumer behavior.

To learn more about our digital measurement products and your choices in regard to them, please visit http://www.nielsen.com/digitalprivacy.

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 [[optOutURL]] and opened in ‘WebView’ within the app and NOT in any external browser.
** Opening the Opt-Out page in any external browser takes the application control out of the Nielsen App SDK context.
** As the App SDK does not expose any direct http/https interface to interact with the world to get the user selection on Privacy page, there will be no way to interact/send notification to the App SDK regarding the user selection.
* 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 [[optOutStatus]] method.
<blockquote>'''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.</blockquote>

'''Sequence Diagram'''
[[File:optoutsequence-ios.jpg]]

Below are the steps to implement user Opt-Out using UIWebView.

When a user clicks the Opt-Out / Opt-In link, the application should invoke [[optOutURL]] to get the link to the Nielsen Privacy page from SDK.

'''Implement WebView with Nielsen Opt-Out URL'''
<syntaxhighlight lang="objective-c">NielsenAppApi nAppApiObject;
@property(strong) UIWebView *optOutView;

// create WebView and set self as delegate
self.optOutView=[[UIWebViewalloc]initWithFrame:self.view.bounds];

self.optOutView.scalesPageToFit = yes;
// get Nielsen defined web address and load the page
NSString *webAddress = [nAppApiObject optOutURLString];

if(webAddress == nil)
{ // Handle it gracefully and retry later}
else
{
[optOutView loadRequest:[NSURLRequest requestWithURL:webAddress]];
// show the view to the user
[self.view addSubview:optOutView];
}</syntaxhighlight>

* The Nielsen Privacy Page appears using UIWebView

'''Privacy Page'''

[[File:privacy-policy.jpg]]

* There are two links – one for Opt-Out and one for Opt-In. Click the required link.
* Click OK in the dialog that appears, to confirm the action.
* The Opt-Out occurs by opening a Nielsen-defined web page and passing the user choice from the ‘WebView’. In order to do this, the application needs to
** Implement the UIWebView delegate method to open the Nielsen Privacy web page
** Capture user’s selection
** Pass the selection back to the SDK via the [[userOptOut]].

'''Capture and forward user selection'''
<syntaxhighlight lang="objective-c">-(BOOL)webView:(UIWebView *)webView shouldStartLoadWithRequest:(NSURLRequest *)request navigationType:(UIWebViewNavigationType)navigationType
{
NSString *command = [NSString stringWithFormat:@”%@”,request.URL];
if ([command isEqualToString:kNielsenWebClose]) {
// Close the WebView
[self performSelector:@selector(closeOptOutView) withObject:nil afterDelay:0];
return NO;
}
// Retrieve next URL if it’s not opt-in/out selection
return (![nAppApiObject userOptOut:command]);
}</syntaxhighlight>
* The app gets the user selection string via webviews shouldStartLoadWithRequest and invokes [[userOptOut]] with user selection. The delegate method handles the ‘WebView’ URL requests, interprets the commands, and calls the SDK accordingly.
* <code>[nAppApiObject userOptOut:command]</code> passes the user’s selection on Nielsen Privacy page to the SDK to allow the SDK to perform the required functions.
<blockquote>'''Note''': When ‘WebView’ is closed, pass the status returned from ‘WebView’ to the SDK within the app.</blockquote>

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

== AppApiEventCode ==
An enumeration with predefined App SDK event state transition codes.
<syntaxhighlight lang="objective-c">
typedef NS_ENUM(unsigned int, AppApiEventCode)
{
AppApiStartup = 2001,
AppApiShutdown = 2002,
}AppApiEventCode;
</syntaxhighlight>

== App SDK Event Codes ==
{| class="wikitable"
|-
! 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 ==
An enumeration with predefined error codes which the App SDK object can generate.
<syntaxhighlight lang="objective-c">
typedef NS_ENUM(unsigned int, AppApiErrorCode)
{
AppApiNetworkConnectionFailure = 1001,
AppApiFileWriteFailure = 1002,
AppApiFileReadFailure = 1003,
AppApiEmptyValue = 1004,
AppApiEmptyAppName = 1005,
AppApiEmptyAppVersion = 1006,
AppApiEmptyAppId = 1007,
AppApiAnExceptionOccured = 1008,
AppApiUnknownExceptionOccured = 1009
};
</syntaxhighlight>

== App SDK Error Codes ==
{| class="wikitable"
|-
! Event Code !! Event Name !! Event 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
|}

iOS SDK API Reference

2017-07-11T21:51:00Z

Admin2: /* AppApiErrorCode */

{{Breadcrumb|}} {{Breadcrumb|Digital}} {{CurrentBreadcrumb}}
[[Category:Digital]]
The iOS 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. These SDKs leverage the following:
*Nielsen audio watermark technologies for TV audience measurement
*The industry supported ID3 metadata tag specification
*Nielsen Combined Beacon technology
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
*Application crash events
*Time of viewing a sub section / page in the application.

== Importing Frameworks ==
'''Setting up your Xcode Development Environment'''

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

SDK uses the NSURLSession available from iOS 7 instead of the deprecated NSURLConnection.

<blockquote>'''Note''': App SDK supports devices running on iOS 9 and above, as all communications between the SDK and the Census (Collection Facility) use HTTPS.</blockquote>

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 (Not applicable for International (Germany))
* 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

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

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

== Initialization ==
The latest version of App SDK allows instantiating multiple instances of App SDK object and can be used simultaneously without any issues (The sharedInstance API that creates a singleton object in previous versions of App SDK is removed).
*Maximum of four SDK instances per appid are supported in this release. When a fifth SDK instance is launched,
**SDK will return “nil” from [[initWithAppInfo:delegate:]]
**Destroy one or more old SDK instances before creating new ones.

=== Stages of SDK Initialization ===
==== Step 1: App SDK Initialization ====
Initialize the Nielsen App object within the viewDidLoad view controller delegate method using initWithAppInfo:delegate:
<blockquote>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.</blockquote>

==== Step 2: Setting up event and error notifications ====
Once the <code>NielsenAppApi</code> object has been initialized, the next step is to enable notifications regarding ID3 tags extracted from the playing stream. In case of standard AVFoundation player, the SDK NSNotificationCenter API is used to
* Collect HLS timed metadata events (ID3 tags) during viewing sessions.
** Set up a timed metadata event listener method for receiving ID3 tags and calling Nielsen [[sendID3]].
* SDK uses the following NielsenAppApiDelegate protocol methods to notify its delegate (set during initialization) about event / error information.
** nielsenAppApi:eventOccurred
** nielsenAppApi:errorOccurred
<blockquote>'''Note''': Ensure to add to your view controller’s <code>@interface</code>.</blockquote>

<syntaxhighlight lang="objective-c">(void)nielsenAppApi:(NielsenAppApi *)appApi eventOccurred:(NSDictionary *)event {NSLog(@"Sample player is Notified by a Event : %@", event);
}
(void)nielsenAppApi:(NielsenAppApi *)appApi errorOccurred:(NSDictionary *)error {NSLog(@"Sample player is Notified by an Error : %@", error);
}</syntaxhighlight>

===== Sample event confirmation to player application upon successful initialization of SDK =====
<syntaxhighlight lang="console">NielsenSDKSampleDebug[9028:237989] [Nls:0] -I- Analytics framework Status:
{
"Event Description" = "Nielsen App SDK Version, ai.4.0.0.4 is initialized by the Player…";
EventStatus = 2001;
TimeStamp = "2015-07-23 14:51:06 +0000";
}</syntaxhighlight>

==== Step 3: Nielsen App SDK Streaming Sessions ====
After setting up observers for SDK events/errors and a listener method to process incoming Nielsen ID3 tags, the next steps are to
* Call [[play]] while starting or resuming a streaming session.
* Load CMS metadata using [[loadMetadata]].
* During session play, call [[playheadPosition]] every one second until the stream is stopped or interrupted (due to ad breaks or buffering).
* Call [[stop]] when pausing, ending a viewing session, or buffering is detected.

'''Serialized JSON string from NSDictionary'''
<syntaxhighlight lang="objective-c">NSDictionary* appInformation = @
{
@"appid": @"TXXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX",
@"appname": @"Sample App Name",
@"appversion": @"2.0",
@"sfcode": @"uat-cert",
@"nol_devDebug": @"INFO"
}
NSData* jsonDataAppInfo = [NSJSONSerialization dataWithJSONObject:appInformation options:0 error:nil];
NSString *jsonAppInfoString = [[NSString alloc] initWithData:jsonDataAppInfo encoding:NSUTF8StringEncoding];
nlsAppApiMeter = [[NielsenAppApi alloc] initWithAppInfo:jsonAppInfoString delegate:self];</syntaxhighlight>

Nielsen App SDK object handles filtering of ID3 tags and CMS tags, queuing/buffering of data, and all communications with Nielsen collection facility.

===== Nielsen iOS App SDK Application Life Cycle =====

[[File:initialization_appcycle.png|center|link=]]

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 '''Initial state'''.
# '''Idle state''' – The SDK is initialized and is ready to process playing information. Call <code>[[initWithAppInfo:delegate:]]</code> to move into this state. The SDK instance is not processing any data, but is listening for the play event to occur.
# '''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.
## [[playheadPosition]] – Call this API every one second when playhead position timer is fired.
## [[sendID3]] – Call this API when ID3 tags are identified in the stream.
## [[stop]] – Call this API when the playback is paused, switches between content and ad (within the same content playback) or encounters interruptions.
## [[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. SDK instance moves into this state in one of the following scenarios.
## Initialization fails
## [[appDisableApi]] is called
<blockquote>'''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 [[sendID3]] / [[playheadPosition]].</blockquote>

=== 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.
{| class="wikitable"
|-
! API call received !! Initial State !! Idle State !! Processing State !! Disabled State
|-
| <code>[[initWithAppInfo:delegate:]]</code> || IDLE STATE (OR)

DISABLED STATE
|| IDLE STATE || - || -
|-
| <code>[[play]]</code> & <code>[[loadMetadata]]</code>|| - || PROCESSING

STATE
|| - || -
|-
| <code>[[playheadPosition]]</code> || - || - || PROCESSING

STATE
|| -
|-
| <code>[[sendID3]]</code> || - || - || PROCESSING

STATE
|| -
|-
| <code>[[stop]]</code> || - || - || IDLE STATE || -
|-
| <code>[[end]]</code> || - || - || IDLE STATE || -
|-
| <code>[[appDisableApi]]</code>: YES || - || DISABLED

STATE
|| - || -
|-
| <code>[[appDisableApi]]</code>: NO || - || - || - || IDLE STATE (OR)

DISABLED STATE
|-
| <code>[[userOptOut]]</code>: YES || - || - || IDLE STATE || -
|-
| <code>[[userOptOut]]</code>: NO || - || PROCESSING

STATE
| -
| -
|-
| colspan = 5 | '-' 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.

==== JSON for NSDictionary object ====
<syntaxhighlight lang="objective-c">
NSDictionary* appInformation = @{
@"appid": @"TXXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX",
@"appname": @"Sample App Name",
@"appversion": @"2.0",
@"sfcode": @"uat-cert",
@"nol_devDebug": @"INFO"
};
nlsAppApiMeter = [[NielsenAppApi alloc] initWithAppInfo:appInformation delegate:delegate];</syntaxhighlight>

<code>appid</code>, <code>appname</code>, and <code>appversion</code> are mandatory parameters while <code>sfcode</code> is optional. <code>nol_devDebug</code> is meant for creating logs in test environments only.

==== JSON string from raw NSString ====
<syntaxhighlight lang="swift">NSString *appInfoString = @"{\"appid\" : \"TXXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX\", \"appname\" : \"Sample App Name\",\"appversion\" : \"2.0\",\"sfcode\" : \"uat-cert\"}";
NielsenAppAPi *appAPI = [[NielsenAppApi alloc] initWithAppInfo:appInfoString delegate:self];</syntaxhighlight>

==== JSON string from serialized NSDictionary ====
<syntaxhighlight lang="objective-c">NSDictionary* appInformation = @
{
@"appid": @"appid",
@"appname": @"appname",
@"appversion": @"2.0",
@"sfcode": @"sfcode",
@"nol_devDebug": @"INFO"
};
nlsAppApiMeter = [[NielsenAppApi alloc] initWithAppInfo:appInformation delegate:self];</syntaxhighlight>

While using JSON format for sending metadat, ensure enough care in including [[special characters]] in the values for arguments.

==== Example ====
<syntaxhighlight lang="objective-c">{
@"type": @"radio", // To send "radio" in metadata string
@"assetid": @"WXYZ-FM'101",
@"stationType": @"3",
@"provider": @"SampleProvider" // To send "SampleProvider" in metadata string
}</syntaxhighlight>
<blockquote>'''Note''': For mandatory parameters like appid, appname, and appversion, please refer to the parameters table in <code>[[initWithAppInfo:delegate:]]</code></blockquote>

== Retrieving ID3 Tags ==
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.

=== Sample ID3 tags ===
* <code>www.nielsen.com/X100zdCIGeIlgZnkYj6UvQ==/X100zdCIGeIlgZnkYj6UvQ==/AAAB2Jz2_k74GXSzx4npHuI_JwJd3QSUpW30rDkGTcbHEzIMWleCzM-uvNOP9fzJcQMWQLJqzXMCAxParOb5sGijSV9dNM3QiBniJYGZ5GI-lL1fXTTN0IgZ4iWBmeRiPpS9AAAAAAAAAAAAAAAAAAAAAFJWFM5SVhTONNU=/00000/00000/00</code>
* <code>www.nielsen.com/X100zdCIGeIlgZnkYj6UvQ==/R8WHe7pEBeqBhu8jTeXydg==/AAICoyitYqlxT7n6aZ0oMCGheFi4CXFp46AMUPZz1lMr_M9tr3_cjee1SHqxrOiVerMDLeyn9xzocZSKwi746Re8vNOtpNCAZjYABs_J0R25IHpvOc1HS8QHGgD5TgOJeS6gX100zdCIGeIlgZnkYj6UvVJWFNhSVhTiPE0=/00000/46016/00</code>

=== Examples of extracting ID3 tags from the iOS Native Player ===
==== AVPlayer ====
ID3 tags will be received in the Player on AVMetadataItem Callback method.
'''Create & get the AVMetadataItem callback method'''
<syntaxhighlight lang="swift">[self.player addObserver:self
forKeyPath: kTimedMetadataKey
options: NSKeyValueObservingOptionNew
Context: MyStreamingMovieViewControllerTimedMetadataObserverContext];</syntaxhighlight>

<syntaxhighlight lang="objective-c">
– (void)observeValueForKeyPath:(NSString*) path
ofObject: (id)object
change: (NSDictionary*)change
context: (void*)context
{
/* Set the AVPlayerLayer on the view to allow the AVPlayer object to display
its content. */
//[playerLayerView.playerLayer setPlayer:player];
/* AVPlayerItem "status" property value observer. */
if (context == MyStreamingMovieViewControllerTimedMetadataObserverContext)
{
id newMetadataArray = [change objectForKey:NSKeyValueChangeNewKey];
if (newMetadataArray != [NSNull null])
{
array = newMetadataArray;
for (AVMetadataItem *metadataItem in array)
{
[self handleTimedMetadata: metadataItem];
}
}
}
</syntaxhighlight>

<syntaxhighlight lang="objective-c">
– (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;
}
if ([(NSString *)[timedMetadata key] isEqualToString:@"PRIV"]&&[extraString rangeOfString:@"www.nielsen.com"].length> 0)
{
if ([[timedMetadata value] isKindOfClass:[NSData class]])
{
// Sending ID3 Tag
/* The sendID3: sends the extracted Nielsen ID3 payload to the App SDK for analysis. */
[[NielsenAppApi sharedInstance]sendID3: extraString];
NSString *value=[timedMetadata stringValue];
if (value != nil)
{
// NSString *strMessage=[[@"ID3 Tag Received " stringByAppendingFormat:@"%d\n",countForMetadata] stringByAppendingString:value];
[self appendLogConsoleText:extraString];
}
}
}
else
{
NSLog(@"Could not send ID3 tags");
}
countForMetadata++;

}
</syntaxhighlight>

==== Movie Player ====
ID3 tags will be received in the Player on MPTimedMetadata Callback method.
'''Sample Implementation of MPTimedMetadata callback'''
<syntaxhighlight lang="objective-c">
– (void)handleTimedMetadata:(MPTimedMetadata*)timedMetadata
{
id extraAttributeType = [timedMetadata allMetadata];
NSString * extraString= nil;
if ([extraAttributeType isKindOfClass:[NSDictionary class]])
{
extraString = [extraAttributeType valueForKey:@"info"];
}
else if([extraAttributeType isKindOfClass:[NSString class]])
{
extraString = extraAttributeType;
}

if ([(NSString *)[timedMetadata key] isEqualToString:@"PRIV"]&&[extraString rangeOfString:@"www.nielsen.com"].length> 0)
{
if ([[timedMetadata value] isKindOfClass:[NSData class]])
{
// Sending ID3 Tag
[[NielsenAppApi sharedInstance]sendID3: extraString];
NSString *value=[timedMetadata value];
if (value != nil)
{

[self appendLogConsoleText:extraString];
}
}
}
else
{
NSLog(@"Could not send ID3 tags");
}
countForMetadata++;
}
</syntaxhighlight>
<blockquote>'''Note:''' ID3 tags are not applicable for International (Germany)</blockquote>

== IOS SDK API Methods & Properties ==
{| class="wikitable sortable"
|-
! Scenario !! Method / Property !! DTVR !! DAR !! Digital Audio !! 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 || [[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.
|-
| 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)
|}

== 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 to this web page should be called from SDK by invoking [[optOutURL]] and opened in 'WebView' / External browser.
*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 [[optOutStatus]] method.

=== Displaying Opt-Out in a WebView ===
<syntaxhighlight lang="objective-c">
NielsenAppApi nAppApiObject;
@property(strong) UIWebView *optOutView;
// create WebView and set self as delegate
self.optOutView=[[UIWebView alloc]initWithFrame:self.view.bounds];
self.optOutView.scalesPageToFit = yes;
// get Nielsen defined web address and load the page
NSString *webAddress = [nAppApiObject optOutURLString];
If(webAddress == nil)
{ // Handle it gracefully and retry later} else
{[optOutView loadRequest:[NSURLRequest requestWithURL:webAddress]];
// show the view to the user
[self.view addSubview:optOutView]; }
</syntaxhighlight>

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.

[[File:Privacy policy iOS.jpg|link=]]

*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.
<syntaxhighlight lang="objective-c">
@property (readonly) BOOL optOutStatus;
</syntaxhighlight>
*App should provide a UI control like 'close' or 'back' button to close the 'WebView' / External browser.

=== Sequence Diagram ===
[[File:optoutsequence-ios.jpg|link=]]

== Opt-out SDK Version '''5.1.1.17 or above''' ==
<blockquote>'''Note:''' If using SDK Versions 1.2.3, 4.0.0.8, 5.1.0, 5.1.1.12, skip ahead to: [[#Opt-out SDK Version 1.2.3, 4.0.0.8, 5.1.0, 5.1.1.12|Opt-out SDK Version 1.2.3, 4.0.0.8, 5.1.0, 5.1.1.12]]</blockquote>

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.

[[File:Opt-Out iOS.jpg|link=]]

<blockquote>'''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.</blockquote>

== Opt-out SDK Version '''1.2.3, 4.0.0.8, 5.1.0, 5.1.1.12''' ==
<blockquote>'''Note:''' If using SDK Version 5.1.1.17 or above, refer to documentation above ([[#Opt-out SDK Version 5.1.1.17 or above|Opt-out SDK Version 5.1.1.17 or above]])</blockquote>

When a user clicks the Opt-Out / Opt-In link, the application should invoke [[optOutURL]] to get the link to the Nielsen Privacy page from SDK.
=== Privacy Page ===
[[File:privacy-policy.jpg|link=]]
*There are two click here links – one for Opt-Out and one for Opt-In. Click the required link:
**
[[File:Opt-Out Combined.jpg|link=]]
*Click OK in the dialog that appears, to confirm the action.
*The Opt-Out occurs by opening a Nielsen-defined web page and passing the user choice from the 'WebView'. In order to do this, the application needs to
**Implement the UIWebView delegate method to open the Nielsen Privacy web page
**Capture user's selection
**Pass the selection back to the SDK via the [[userOptOut]].

=== Capture and forward user selection ===
<syntaxhighlight lang="objective-c">
-(BOOL)webView:(UIWebView *)webView
shouldStartLoadWithRequest:(NSURLRequest *)request
navigationType:(UIWebViewNavigationType)navigationType
{
NSString *command = [NSString stringWithFormat:@"%@",
request.URL];
if ([command isEqualToString:kNielsenWebClose]) {
// Close the WebView
[self performSelector:@selector(closeOptOutView)
withObject:nil afterDelay:0];
return NO;
}
// Retrieve next URL if it's not opt-in/out selection
return (![nAppApiObject userOptOut:command]);
}
</syntaxhighlight>

*The app gets the user selection string via webviews shouldStartLoadWithRequest and invokes [[userOptOut]] with user selection. The delegate method handles the 'WebView' URL requests, interprets the commands, and calls the SDK accordingly.
**<code>[nAppApiObject userOptOut:command]</code> passes the user's selection on Nielsen Privacy page to the SDK to allow the SDK to perform the required functions.
<blockquote>'''Note:''' When 'WebView' is closed, pass the status returned from 'WebView' to the SDK within the app.</blockquote>
<blockquote>'''Note:''' App SDK manages the user's choice (Opt-Out / Opt-In), the app does not need to manage this status.</blockquote>

== 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:

[[File:TVOs OptOut LimitAdTracking1.png|link=]]

[[File:TVOs OptOut LimitAdTracking2.png|link=]]

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.

<blockquote>'''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.</blockquote>

== 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:
<syntaxhighlight lang="objective-c">
@interface NielsenAppApi: NSObject

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

– (instancetype)initWithAppInfo:(id)appInfo delegate:(id)delegate;

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

– (NSString *)getNielsenId _attribute((deprecated((“Please use nielsenId property instead.”))));
– (NSString *)optOutURLString _attribute((deprecated((“Please use optOutURL property instead.”))));
– (NSString *)getMeterVersion _attribute((deprecated((“Please use meterVersion property instead.”))));
– (NSDictionary *)getLastEventDict _attribute((deprecated((“Please use lastEventDict property instead.”))));
– (NSDictionary *)getLastErrorDict _attribute((deprecated((“Please use lastErrorDict property instead.”))));

@protocol NielsenAppApiDelegate<NSObject>

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

@end
</syntaxhighlight>

== Nielsen Sample Applications ==
Nielsen iOS sample player application consists of two sample application based on native Players integrated with SDK framework. The player demonstrates all the supported functions of the SDK.
*NielsenVideoPlayer
*NielsenRadioPlayer
Implementation of Video and Audio 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 two locations:
**Channels 1 and 2 are configured from the Settings application. Channel URLs and metadata parameters can be modified.
**Channels starting from 3 are configured in specific JSON file. URLs to this JSON config file can be changed from the Settings application.

== Nielsen Privacy Requirements ==
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.
[[File:RatingsDataFlow.png]]

'''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 ===
{| class="wikitable"
|-
! Type of Information !! Parameter !! Transmitted to Nielsen? !! Sent to Provider?
|-
| rowspan="8" | 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
|-
| rowspan="10" | 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
|-
| rowspan="9" | 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
|}
<blockquote>'''Note''': Data is hashed, and encrypted using AES 128 before transmission to data provider.</blockquote>

==== Example ping sent to provider ====
* <code><nowiki>https://provider.com/cgi-bin/brandlift.php</nowiki>?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</code>

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

=== Nielsen Measurement Opt-Out ===
In accordance with Nielsen’s SDK licensing agreement, developers are required to provide basic informational data to users about Nielsen’s Privacy Policy with a navigation to additional information on Nielsen measurement.

Nielsen currently uses Limit Ad Tracking for the latest versions of the SDK (5.1.1.17 and above). However, for older SDK versions, the app must provide a means for the user to opt out, or opt back in to Nielsen Measurement. Users can opt out of Nielsen online measurement research through this feature.
* If the user has this app running on more than one mobile device, the user will need to opt out of this measurement on each device.
<blockquote>'''Note''': Opt Out feature does NOT rely on "Limit Ad Tracking" setting since Nielsen’s systems provide measurement metrics and do not serve ads to users.</blockquote>

In the Description of the app in App Store, include a short description about Nielsen measurement, as below.

<blockquote>'''Sample App Store Disclosure'''
This app features Nielsen proprietary measurement software which will allow you to contribute to market research, like Nielsen’s TV Ratings.

To learn more about our digital measurement products and your choices in regard to them, please visit http://www.nielsen.com/digitalprivacy for more information.

[[File:measurement-samplescreen.jpg]]</blockquote>

Both iOS-based and TVOS-based player applications need to confirm to Nielsen Privacy Requirements. Refer to the Opt-Out implementation guidelines for iOS and TVOS platforms respectively for more details.

=== Opt-Out Implementation ===
==== Limit Ad Tracking ====
'''This implementation is valid for SDK Versions 5.1.1.17 and above.'''

<blockquote>'''Note''': If using SDK Version 1.2.3, 4.0.0.8, 5.1.0 or 5.1.1.12, refer to Opt-Out Implementation for iOS.</blockquote>

As a global information and measurement leader, Nielsen is committed to protect the privacy and security of the data they collect, process and use. Nielsen strongly believes that the consumer should have a way to opt out of Nielsen measurement.

The Nielsen digital measurement products help Nielsen and its clients to measure and analyze how consumers engage with media across online, mobile and emerging technologies while offering insights into consumer behavior.

To learn more about our digital measurement products and your choices in regard to them, please visit http://www.nielsen.com/digitalprivacy.

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 optOutURL and opened in ‘WebView’ / External browser.
* 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 optOutStatus method.
'''Displaying Opt-Out in a WebView'''
<syntaxhighlight lang="objective-c">NielsenAppApi nAppApiObject;
@property(strong) UIWebView *optOutView;
// create WebView and set self as delegate
self.optOutView=[[UIWebView alloc]initWithFrame:self.view.bounds];
self.optOutView.scalesPageToFit = yes;
// get Nielsen defined web address and load the page
NSString *webAddress = [nAppApiObject optOutURLString];
If(webAddress == nil)
{
// Handle it gracefully and retry later
}

else
{
[optOutView loadRequest:[NSURLRequest requestWithURL:webAddress]];
// show the view to the user
[self.view addSubview:optOutView];
}</syntaxhighlight>

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.

[[File:Opt-Out_iOS.jpg]]
<blockquote>'''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.</blockquote>

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.

[[File: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.
<syntaxhighlight lang="objective-c">@property (readonly) BOOL optOutStatus;</blockquote>
* App should provide a UI control like ‘close’ or ‘back’ button to close the ‘WebView’ / External browser.

'''Sequence Diagram'''
[[File:optoutsequence-ios.jpg]]

== Event and Error Handling ==
=== Constants / Enumerations ===
The following are the details of Delegate Implementation:

<syntaxhighlight lang="objective-c">
-(void)nielsenAppApi:(NielsenAppApi *)appApi eventOccurred:(NSDictionary *)event
{
NSLog(@"Sample player is Notified by a Event: %@", event);
}
– (void)nielsenAppApi:(NielsenAppApi *)appApi errorOccurred:(NSDictionary *)error
{
NSLog(@"Sample player is Notified by an Error: %@", error);
}
</syntaxhighlight>

==== TVOS Implementation ====
As a global information and measurement leader, Nielsen is committed to protect the privacy and security of the data they collect, process and use. Nielsen strongly believes that the client should have a way to Opt-Out of Nielsen measurement.

The Nielsen digital measurement products are not used to identify consumer in any way. They help Nielsen and its clients to measure and analyze how consumers engage with media across online, mobile and emerging technologies while offering insights into consumer behavior.

To learn more about our digital measurement products and your choices in regard to them, please visit http://www.nielsen.com/digitalprivacy.

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.

[[File:TVOs_OptOut_LimitAdTracking1.png]]

[[File:TVOs_OptOut_LimitAdTracking2.png]]

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.

<blockquote>'''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.</blockquote>

==== Legacy Opt-Out ====
'''Supported SDK Versions''': 1.2.3, 4.0.0.8, 5.1.0, 5.1.1.12.

<blockquote>'''Note''': If using SDK Version 5.1.1.17 or above, refer to Opt-Out Implementation (Limit Ad Tracking).</blockquote>

As a global information and measurement leader, Nielsen is committed to protect the privacy and security of the data they collect, process and use. Nielsen strongly believes that the consumer should have a way to Opt-Out of Nielsen measurement.

The Nielsen digital measurement products help Nielsen and its clients to measure and analyze how consumers engage with media across online, mobile and emerging technologies while offering insights into consumer behavior.

To learn more about our digital measurement products and your choices in regard to them, please visit http://www.nielsen.com/digitalprivacy.

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 [[optOutURL]] and opened in ‘WebView’ within the app and NOT in any external browser.
** Opening the Opt-Out page in any external browser takes the application control out of the Nielsen App SDK context.
** As the App SDK does not expose any direct http/https interface to interact with the world to get the user selection on Privacy page, there will be no way to interact/send notification to the App SDK regarding the user selection.
* 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 [[optOutStatus]] method.
<blockquote>'''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.</blockquote>

'''Sequence Diagram'''
[[File:optoutsequence-ios.jpg]]

Below are the steps to implement user Opt-Out using UIWebView.

When a user clicks the Opt-Out / Opt-In link, the application should invoke [[optOutURL]] to get the link to the Nielsen Privacy page from SDK.

'''Implement WebView with Nielsen Opt-Out URL'''
<syntaxhighlight lang="objective-c">NielsenAppApi nAppApiObject;
@property(strong) UIWebView *optOutView;

// create WebView and set self as delegate
self.optOutView=[[UIWebViewalloc]initWithFrame:self.view.bounds];

self.optOutView.scalesPageToFit = yes;
// get Nielsen defined web address and load the page
NSString *webAddress = [nAppApiObject optOutURLString];

if(webAddress == nil)
{ // Handle it gracefully and retry later}
else
{
[optOutView loadRequest:[NSURLRequest requestWithURL:webAddress]];
// show the view to the user
[self.view addSubview:optOutView];
}</syntaxhighlight>

* The Nielsen Privacy Page appears using UIWebView

'''Privacy Page'''

[[File:privacy-policy.jpg]]

* There are two links – one for Opt-Out and one for Opt-In. Click the required link.
* Click OK in the dialog that appears, to confirm the action.
* The Opt-Out occurs by opening a Nielsen-defined web page and passing the user choice from the ‘WebView’. In order to do this, the application needs to
** Implement the UIWebView delegate method to open the Nielsen Privacy web page
** Capture user’s selection
** Pass the selection back to the SDK via the [[userOptOut]].

'''Capture and forward user selection'''
<syntaxhighlight lang="objective-c">-(BOOL)webView:(UIWebView *)webView shouldStartLoadWithRequest:(NSURLRequest *)request navigationType:(UIWebViewNavigationType)navigationType
{
NSString *command = [NSString stringWithFormat:@”%@”,request.URL];
if ([command isEqualToString:kNielsenWebClose]) {
// Close the WebView
[self performSelector:@selector(closeOptOutView) withObject:nil afterDelay:0];
return NO;
}
// Retrieve next URL if it’s not opt-in/out selection
return (![nAppApiObject userOptOut:command]);
}</syntaxhighlight>
* The app gets the user selection string via webviews shouldStartLoadWithRequest and invokes [[userOptOut]] with user selection. The delegate method handles the ‘WebView’ URL requests, interprets the commands, and calls the SDK accordingly.
* <code>[nAppApiObject userOptOut:command]</code> passes the user’s selection on Nielsen Privacy page to the SDK to allow the SDK to perform the required functions.
<blockquote>'''Note''': When ‘WebView’ is closed, pass the status returned from ‘WebView’ to the SDK within the app.</blockquote>

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

== AppApiEventCode ==
An enumeration with predefined App SDK event state transition codes.
<syntaxhighlight lang="objective-c">
typedef NS_ENUM(unsigned int, AppApiEventCode)
{
AppApiStartup = 2001,
AppApiShutdown = 2002,
}AppApiEventCode;
</syntaxhighlight>

== App SDK Event Codes ==
{| class="wikitable"
|-
! 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 ==
An enumeration with predefined error codes which the App SDK object can generate.
<syntaxhighlight lang="objective-c">
typedef NS_ENUM(unsigned int, AppApiErrorCode)
{
AppApiNetworkConnectionFailure = 1001,
AppApiFileWriteFailure = 1002,
AppApiFileReadFailure = 1003,
AppApiEmptyValue = 1004,
AppApiEmptyAppName = 1005,
AppApiEmptyAppVersion = 1006,
AppApiEmptyAppId = 1007,
AppApiAnExceptionOccured = 1008,
AppApiUnknownExceptionOccured = 1009
};
</syntaxhighlight>

=== App SDK Error Codes ===
{| class="wikitable"
|-
! Event Code !! Event Name !! Event 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
|}

iOS SDK API Reference

2017-07-11T21:50:24Z

Admin2: /* App SDK Event Codes */

{{Breadcrumb|}} {{Breadcrumb|Digital}} {{CurrentBreadcrumb}}
[[Category:Digital]]
The iOS 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. These SDKs leverage the following:
*Nielsen audio watermark technologies for TV audience measurement
*The industry supported ID3 metadata tag specification
*Nielsen Combined Beacon technology
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
*Application crash events
*Time of viewing a sub section / page in the application.

== Importing Frameworks ==
'''Setting up your Xcode Development Environment'''

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

SDK uses the NSURLSession available from iOS 7 instead of the deprecated NSURLConnection.

<blockquote>'''Note''': App SDK supports devices running on iOS 9 and above, as all communications between the SDK and the Census (Collection Facility) use HTTPS.</blockquote>

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 (Not applicable for International (Germany))
* 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

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

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

== Initialization ==
The latest version of App SDK allows instantiating multiple instances of App SDK object and can be used simultaneously without any issues (The sharedInstance API that creates a singleton object in previous versions of App SDK is removed).
*Maximum of four SDK instances per appid are supported in this release. When a fifth SDK instance is launched,
**SDK will return “nil” from [[initWithAppInfo:delegate:]]
**Destroy one or more old SDK instances before creating new ones.

=== Stages of SDK Initialization ===
==== Step 1: App SDK Initialization ====
Initialize the Nielsen App object within the viewDidLoad view controller delegate method using initWithAppInfo:delegate:
<blockquote>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.</blockquote>

==== Step 2: Setting up event and error notifications ====
Once the <code>NielsenAppApi</code> object has been initialized, the next step is to enable notifications regarding ID3 tags extracted from the playing stream. In case of standard AVFoundation player, the SDK NSNotificationCenter API is used to
* Collect HLS timed metadata events (ID3 tags) during viewing sessions.
** Set up a timed metadata event listener method for receiving ID3 tags and calling Nielsen [[sendID3]].
* SDK uses the following NielsenAppApiDelegate protocol methods to notify its delegate (set during initialization) about event / error information.
** nielsenAppApi:eventOccurred
** nielsenAppApi:errorOccurred
<blockquote>'''Note''': Ensure to add to your view controller’s <code>@interface</code>.</blockquote>

<syntaxhighlight lang="objective-c">(void)nielsenAppApi:(NielsenAppApi *)appApi eventOccurred:(NSDictionary *)event {NSLog(@"Sample player is Notified by a Event : %@", event);
}
(void)nielsenAppApi:(NielsenAppApi *)appApi errorOccurred:(NSDictionary *)error {NSLog(@"Sample player is Notified by an Error : %@", error);
}</syntaxhighlight>

===== Sample event confirmation to player application upon successful initialization of SDK =====
<syntaxhighlight lang="console">NielsenSDKSampleDebug[9028:237989] [Nls:0] -I- Analytics framework Status:
{
"Event Description" = "Nielsen App SDK Version, ai.4.0.0.4 is initialized by the Player…";
EventStatus = 2001;
TimeStamp = "2015-07-23 14:51:06 +0000";
}</syntaxhighlight>

==== Step 3: Nielsen App SDK Streaming Sessions ====
After setting up observers for SDK events/errors and a listener method to process incoming Nielsen ID3 tags, the next steps are to
* Call [[play]] while starting or resuming a streaming session.
* Load CMS metadata using [[loadMetadata]].
* During session play, call [[playheadPosition]] every one second until the stream is stopped or interrupted (due to ad breaks or buffering).
* Call [[stop]] when pausing, ending a viewing session, or buffering is detected.

'''Serialized JSON string from NSDictionary'''
<syntaxhighlight lang="objective-c">NSDictionary* appInformation = @
{
@"appid": @"TXXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX",
@"appname": @"Sample App Name",
@"appversion": @"2.0",
@"sfcode": @"uat-cert",
@"nol_devDebug": @"INFO"
}
NSData* jsonDataAppInfo = [NSJSONSerialization dataWithJSONObject:appInformation options:0 error:nil];
NSString *jsonAppInfoString = [[NSString alloc] initWithData:jsonDataAppInfo encoding:NSUTF8StringEncoding];
nlsAppApiMeter = [[NielsenAppApi alloc] initWithAppInfo:jsonAppInfoString delegate:self];</syntaxhighlight>

Nielsen App SDK object handles filtering of ID3 tags and CMS tags, queuing/buffering of data, and all communications with Nielsen collection facility.

===== Nielsen iOS App SDK Application Life Cycle =====

[[File:initialization_appcycle.png|center|link=]]

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 '''Initial state'''.
# '''Idle state''' – The SDK is initialized and is ready to process playing information. Call <code>[[initWithAppInfo:delegate:]]</code> to move into this state. The SDK instance is not processing any data, but is listening for the play event to occur.
# '''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.
## [[playheadPosition]] – Call this API every one second when playhead position timer is fired.
## [[sendID3]] – Call this API when ID3 tags are identified in the stream.
## [[stop]] – Call this API when the playback is paused, switches between content and ad (within the same content playback) or encounters interruptions.
## [[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. SDK instance moves into this state in one of the following scenarios.
## Initialization fails
## [[appDisableApi]] is called
<blockquote>'''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 [[sendID3]] / [[playheadPosition]].</blockquote>

=== 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.
{| class="wikitable"
|-
! API call received !! Initial State !! Idle State !! Processing State !! Disabled State
|-
| <code>[[initWithAppInfo:delegate:]]</code> || IDLE STATE (OR)

DISABLED STATE
|| IDLE STATE || - || -
|-
| <code>[[play]]</code> & <code>[[loadMetadata]]</code>|| - || PROCESSING

STATE
|| - || -
|-
| <code>[[playheadPosition]]</code> || - || - || PROCESSING

STATE
|| -
|-
| <code>[[sendID3]]</code> || - || - || PROCESSING

STATE
|| -
|-
| <code>[[stop]]</code> || - || - || IDLE STATE || -
|-
| <code>[[end]]</code> || - || - || IDLE STATE || -
|-
| <code>[[appDisableApi]]</code>: YES || - || DISABLED

STATE
|| - || -
|-
| <code>[[appDisableApi]]</code>: NO || - || - || - || IDLE STATE (OR)

DISABLED STATE
|-
| <code>[[userOptOut]]</code>: YES || - || - || IDLE STATE || -
|-
| <code>[[userOptOut]]</code>: NO || - || PROCESSING

STATE
| -
| -
|-
| colspan = 5 | '-' 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.

==== JSON for NSDictionary object ====
<syntaxhighlight lang="objective-c">
NSDictionary* appInformation = @{
@"appid": @"TXXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX",
@"appname": @"Sample App Name",
@"appversion": @"2.0",
@"sfcode": @"uat-cert",
@"nol_devDebug": @"INFO"
};
nlsAppApiMeter = [[NielsenAppApi alloc] initWithAppInfo:appInformation delegate:delegate];</syntaxhighlight>

<code>appid</code>, <code>appname</code>, and <code>appversion</code> are mandatory parameters while <code>sfcode</code> is optional. <code>nol_devDebug</code> is meant for creating logs in test environments only.

==== JSON string from raw NSString ====
<syntaxhighlight lang="swift">NSString *appInfoString = @"{\"appid\" : \"TXXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX\", \"appname\" : \"Sample App Name\",\"appversion\" : \"2.0\",\"sfcode\" : \"uat-cert\"}";
NielsenAppAPi *appAPI = [[NielsenAppApi alloc] initWithAppInfo:appInfoString delegate:self];</syntaxhighlight>

==== JSON string from serialized NSDictionary ====
<syntaxhighlight lang="objective-c">NSDictionary* appInformation = @
{
@"appid": @"appid",
@"appname": @"appname",
@"appversion": @"2.0",
@"sfcode": @"sfcode",
@"nol_devDebug": @"INFO"
};
nlsAppApiMeter = [[NielsenAppApi alloc] initWithAppInfo:appInformation delegate:self];</syntaxhighlight>

While using JSON format for sending metadat, ensure enough care in including [[special characters]] in the values for arguments.

==== Example ====
<syntaxhighlight lang="objective-c">{
@"type": @"radio", // To send "radio" in metadata string
@"assetid": @"WXYZ-FM'101",
@"stationType": @"3",
@"provider": @"SampleProvider" // To send "SampleProvider" in metadata string
}</syntaxhighlight>
<blockquote>'''Note''': For mandatory parameters like appid, appname, and appversion, please refer to the parameters table in <code>[[initWithAppInfo:delegate:]]</code></blockquote>

== Retrieving ID3 Tags ==
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.

=== Sample ID3 tags ===
* <code>www.nielsen.com/X100zdCIGeIlgZnkYj6UvQ==/X100zdCIGeIlgZnkYj6UvQ==/AAAB2Jz2_k74GXSzx4npHuI_JwJd3QSUpW30rDkGTcbHEzIMWleCzM-uvNOP9fzJcQMWQLJqzXMCAxParOb5sGijSV9dNM3QiBniJYGZ5GI-lL1fXTTN0IgZ4iWBmeRiPpS9AAAAAAAAAAAAAAAAAAAAAFJWFM5SVhTONNU=/00000/00000/00</code>
* <code>www.nielsen.com/X100zdCIGeIlgZnkYj6UvQ==/R8WHe7pEBeqBhu8jTeXydg==/AAICoyitYqlxT7n6aZ0oMCGheFi4CXFp46AMUPZz1lMr_M9tr3_cjee1SHqxrOiVerMDLeyn9xzocZSKwi746Re8vNOtpNCAZjYABs_J0R25IHpvOc1HS8QHGgD5TgOJeS6gX100zdCIGeIlgZnkYj6UvVJWFNhSVhTiPE0=/00000/46016/00</code>

=== Examples of extracting ID3 tags from the iOS Native Player ===
==== AVPlayer ====
ID3 tags will be received in the Player on AVMetadataItem Callback method.
'''Create & get the AVMetadataItem callback method'''
<syntaxhighlight lang="swift">[self.player addObserver:self
forKeyPath: kTimedMetadataKey
options: NSKeyValueObservingOptionNew
Context: MyStreamingMovieViewControllerTimedMetadataObserverContext];</syntaxhighlight>

<syntaxhighlight lang="objective-c">
– (void)observeValueForKeyPath:(NSString*) path
ofObject: (id)object
change: (NSDictionary*)change
context: (void*)context
{
/* Set the AVPlayerLayer on the view to allow the AVPlayer object to display
its content. */
//[playerLayerView.playerLayer setPlayer:player];
/* AVPlayerItem "status" property value observer. */
if (context == MyStreamingMovieViewControllerTimedMetadataObserverContext)
{
id newMetadataArray = [change objectForKey:NSKeyValueChangeNewKey];
if (newMetadataArray != [NSNull null])
{
array = newMetadataArray;
for (AVMetadataItem *metadataItem in array)
{
[self handleTimedMetadata: metadataItem];
}
}
}
</syntaxhighlight>

<syntaxhighlight lang="objective-c">
– (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;
}
if ([(NSString *)[timedMetadata key] isEqualToString:@"PRIV"]&&[extraString rangeOfString:@"www.nielsen.com"].length> 0)
{
if ([[timedMetadata value] isKindOfClass:[NSData class]])
{
// Sending ID3 Tag
/* The sendID3: sends the extracted Nielsen ID3 payload to the App SDK for analysis. */
[[NielsenAppApi sharedInstance]sendID3: extraString];
NSString *value=[timedMetadata stringValue];
if (value != nil)
{
// NSString *strMessage=[[@"ID3 Tag Received " stringByAppendingFormat:@"%d\n",countForMetadata] stringByAppendingString:value];
[self appendLogConsoleText:extraString];
}
}
}
else
{
NSLog(@"Could not send ID3 tags");
}
countForMetadata++;

}
</syntaxhighlight>

==== Movie Player ====
ID3 tags will be received in the Player on MPTimedMetadata Callback method.
'''Sample Implementation of MPTimedMetadata callback'''
<syntaxhighlight lang="objective-c">
– (void)handleTimedMetadata:(MPTimedMetadata*)timedMetadata
{
id extraAttributeType = [timedMetadata allMetadata];
NSString * extraString= nil;
if ([extraAttributeType isKindOfClass:[NSDictionary class]])
{
extraString = [extraAttributeType valueForKey:@"info"];
}
else if([extraAttributeType isKindOfClass:[NSString class]])
{
extraString = extraAttributeType;
}

if ([(NSString *)[timedMetadata key] isEqualToString:@"PRIV"]&&[extraString rangeOfString:@"www.nielsen.com"].length> 0)
{
if ([[timedMetadata value] isKindOfClass:[NSData class]])
{
// Sending ID3 Tag
[[NielsenAppApi sharedInstance]sendID3: extraString];
NSString *value=[timedMetadata value];
if (value != nil)
{

[self appendLogConsoleText:extraString];
}
}
}
else
{
NSLog(@"Could not send ID3 tags");
}
countForMetadata++;
}
</syntaxhighlight>
<blockquote>'''Note:''' ID3 tags are not applicable for International (Germany)</blockquote>

== IOS SDK API Methods & Properties ==
{| class="wikitable sortable"
|-
! Scenario !! Method / Property !! DTVR !! DAR !! Digital Audio !! 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 || [[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.
|-
| 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)
|}

== 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 to this web page should be called from SDK by invoking [[optOutURL]] and opened in 'WebView' / External browser.
*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 [[optOutStatus]] method.

=== Displaying Opt-Out in a WebView ===
<syntaxhighlight lang="objective-c">
NielsenAppApi nAppApiObject;
@property(strong) UIWebView *optOutView;
// create WebView and set self as delegate
self.optOutView=[[UIWebView alloc]initWithFrame:self.view.bounds];
self.optOutView.scalesPageToFit = yes;
// get Nielsen defined web address and load the page
NSString *webAddress = [nAppApiObject optOutURLString];
If(webAddress == nil)
{ // Handle it gracefully and retry later} else
{[optOutView loadRequest:[NSURLRequest requestWithURL:webAddress]];
// show the view to the user
[self.view addSubview:optOutView]; }
</syntaxhighlight>

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.

[[File:Privacy policy iOS.jpg|link=]]

*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.
<syntaxhighlight lang="objective-c">
@property (readonly) BOOL optOutStatus;
</syntaxhighlight>
*App should provide a UI control like 'close' or 'back' button to close the 'WebView' / External browser.

=== Sequence Diagram ===
[[File:optoutsequence-ios.jpg|link=]]

== Opt-out SDK Version '''5.1.1.17 or above''' ==
<blockquote>'''Note:''' If using SDK Versions 1.2.3, 4.0.0.8, 5.1.0, 5.1.1.12, skip ahead to: [[#Opt-out SDK Version 1.2.3, 4.0.0.8, 5.1.0, 5.1.1.12|Opt-out SDK Version 1.2.3, 4.0.0.8, 5.1.0, 5.1.1.12]]</blockquote>

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.

[[File:Opt-Out iOS.jpg|link=]]

<blockquote>'''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.</blockquote>

== Opt-out SDK Version '''1.2.3, 4.0.0.8, 5.1.0, 5.1.1.12''' ==
<blockquote>'''Note:''' If using SDK Version 5.1.1.17 or above, refer to documentation above ([[#Opt-out SDK Version 5.1.1.17 or above|Opt-out SDK Version 5.1.1.17 or above]])</blockquote>

When a user clicks the Opt-Out / Opt-In link, the application should invoke [[optOutURL]] to get the link to the Nielsen Privacy page from SDK.
=== Privacy Page ===
[[File:privacy-policy.jpg|link=]]
*There are two click here links – one for Opt-Out and one for Opt-In. Click the required link:
**
[[File:Opt-Out Combined.jpg|link=]]
*Click OK in the dialog that appears, to confirm the action.
*The Opt-Out occurs by opening a Nielsen-defined web page and passing the user choice from the 'WebView'. In order to do this, the application needs to
**Implement the UIWebView delegate method to open the Nielsen Privacy web page
**Capture user's selection
**Pass the selection back to the SDK via the [[userOptOut]].

=== Capture and forward user selection ===
<syntaxhighlight lang="objective-c">
-(BOOL)webView:(UIWebView *)webView
shouldStartLoadWithRequest:(NSURLRequest *)request
navigationType:(UIWebViewNavigationType)navigationType
{
NSString *command = [NSString stringWithFormat:@"%@",
request.URL];
if ([command isEqualToString:kNielsenWebClose]) {
// Close the WebView
[self performSelector:@selector(closeOptOutView)
withObject:nil afterDelay:0];
return NO;
}
// Retrieve next URL if it's not opt-in/out selection
return (![nAppApiObject userOptOut:command]);
}
</syntaxhighlight>

*The app gets the user selection string via webviews shouldStartLoadWithRequest and invokes [[userOptOut]] with user selection. The delegate method handles the 'WebView' URL requests, interprets the commands, and calls the SDK accordingly.
**<code>[nAppApiObject userOptOut:command]</code> passes the user's selection on Nielsen Privacy page to the SDK to allow the SDK to perform the required functions.
<blockquote>'''Note:''' When 'WebView' is closed, pass the status returned from 'WebView' to the SDK within the app.</blockquote>
<blockquote>'''Note:''' App SDK manages the user's choice (Opt-Out / Opt-In), the app does not need to manage this status.</blockquote>

== 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:

[[File:TVOs OptOut LimitAdTracking1.png|link=]]

[[File:TVOs OptOut LimitAdTracking2.png|link=]]

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.

<blockquote>'''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.</blockquote>

== 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:
<syntaxhighlight lang="objective-c">
@interface NielsenAppApi: NSObject

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

– (instancetype)initWithAppInfo:(id)appInfo delegate:(id)delegate;

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

– (NSString *)getNielsenId _attribute((deprecated((“Please use nielsenId property instead.”))));
– (NSString *)optOutURLString _attribute((deprecated((“Please use optOutURL property instead.”))));
– (NSString *)getMeterVersion _attribute((deprecated((“Please use meterVersion property instead.”))));
– (NSDictionary *)getLastEventDict _attribute((deprecated((“Please use lastEventDict property instead.”))));
– (NSDictionary *)getLastErrorDict _attribute((deprecated((“Please use lastErrorDict property instead.”))));

@protocol NielsenAppApiDelegate<NSObject>

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

@end
</syntaxhighlight>

== Nielsen Sample Applications ==
Nielsen iOS sample player application consists of two sample application based on native Players integrated with SDK framework. The player demonstrates all the supported functions of the SDK.
*NielsenVideoPlayer
*NielsenRadioPlayer
Implementation of Video and Audio 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 two locations:
**Channels 1 and 2 are configured from the Settings application. Channel URLs and metadata parameters can be modified.
**Channels starting from 3 are configured in specific JSON file. URLs to this JSON config file can be changed from the Settings application.

== Nielsen Privacy Requirements ==
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.
[[File:RatingsDataFlow.png]]

'''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 ===
{| class="wikitable"
|-
! Type of Information !! Parameter !! Transmitted to Nielsen? !! Sent to Provider?
|-
| rowspan="8" | 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
|-
| rowspan="10" | 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
|-
| rowspan="9" | 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
|}
<blockquote>'''Note''': Data is hashed, and encrypted using AES 128 before transmission to data provider.</blockquote>

==== Example ping sent to provider ====
* <code><nowiki>https://provider.com/cgi-bin/brandlift.php</nowiki>?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</code>

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

=== Nielsen Measurement Opt-Out ===
In accordance with Nielsen’s SDK licensing agreement, developers are required to provide basic informational data to users about Nielsen’s Privacy Policy with a navigation to additional information on Nielsen measurement.

Nielsen currently uses Limit Ad Tracking for the latest versions of the SDK (5.1.1.17 and above). However, for older SDK versions, the app must provide a means for the user to opt out, or opt back in to Nielsen Measurement. Users can opt out of Nielsen online measurement research through this feature.
* If the user has this app running on more than one mobile device, the user will need to opt out of this measurement on each device.
<blockquote>'''Note''': Opt Out feature does NOT rely on "Limit Ad Tracking" setting since Nielsen’s systems provide measurement metrics and do not serve ads to users.</blockquote>

In the Description of the app in App Store, include a short description about Nielsen measurement, as below.

<blockquote>'''Sample App Store Disclosure'''
This app features Nielsen proprietary measurement software which will allow you to contribute to market research, like Nielsen’s TV Ratings.

To learn more about our digital measurement products and your choices in regard to them, please visit http://www.nielsen.com/digitalprivacy for more information.

[[File:measurement-samplescreen.jpg]]</blockquote>

Both iOS-based and TVOS-based player applications need to confirm to Nielsen Privacy Requirements. Refer to the Opt-Out implementation guidelines for iOS and TVOS platforms respectively for more details.

=== Opt-Out Implementation ===
==== Limit Ad Tracking ====
'''This implementation is valid for SDK Versions 5.1.1.17 and above.'''

<blockquote>'''Note''': If using SDK Version 1.2.3, 4.0.0.8, 5.1.0 or 5.1.1.12, refer to Opt-Out Implementation for iOS.</blockquote>

As a global information and measurement leader, Nielsen is committed to protect the privacy and security of the data they collect, process and use. Nielsen strongly believes that the consumer should have a way to opt out of Nielsen measurement.

The Nielsen digital measurement products help Nielsen and its clients to measure and analyze how consumers engage with media across online, mobile and emerging technologies while offering insights into consumer behavior.

To learn more about our digital measurement products and your choices in regard to them, please visit http://www.nielsen.com/digitalprivacy.

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 optOutURL and opened in ‘WebView’ / External browser.
* 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 optOutStatus method.
'''Displaying Opt-Out in a WebView'''
<syntaxhighlight lang="objective-c">NielsenAppApi nAppApiObject;
@property(strong) UIWebView *optOutView;
// create WebView and set self as delegate
self.optOutView=[[UIWebView alloc]initWithFrame:self.view.bounds];
self.optOutView.scalesPageToFit = yes;
// get Nielsen defined web address and load the page
NSString *webAddress = [nAppApiObject optOutURLString];
If(webAddress == nil)
{
// Handle it gracefully and retry later
}

else
{
[optOutView loadRequest:[NSURLRequest requestWithURL:webAddress]];
// show the view to the user
[self.view addSubview:optOutView];
}</syntaxhighlight>

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.

[[File:Opt-Out_iOS.jpg]]
<blockquote>'''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.</blockquote>

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.

[[File: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.
<syntaxhighlight lang="objective-c">@property (readonly) BOOL optOutStatus;</blockquote>
* App should provide a UI control like ‘close’ or ‘back’ button to close the ‘WebView’ / External browser.

'''Sequence Diagram'''
[[File:optoutsequence-ios.jpg]]

== Event and Error Handling ==
=== Constants / Enumerations ===
The following are the details of Delegate Implementation:

<syntaxhighlight lang="objective-c">
-(void)nielsenAppApi:(NielsenAppApi *)appApi eventOccurred:(NSDictionary *)event
{
NSLog(@"Sample player is Notified by a Event: %@", event);
}
– (void)nielsenAppApi:(NielsenAppApi *)appApi errorOccurred:(NSDictionary *)error
{
NSLog(@"Sample player is Notified by an Error: %@", error);
}
</syntaxhighlight>

==== TVOS Implementation ====
As a global information and measurement leader, Nielsen is committed to protect the privacy and security of the data they collect, process and use. Nielsen strongly believes that the client should have a way to Opt-Out of Nielsen measurement.

The Nielsen digital measurement products are not used to identify consumer in any way. They help Nielsen and its clients to measure and analyze how consumers engage with media across online, mobile and emerging technologies while offering insights into consumer behavior.

To learn more about our digital measurement products and your choices in regard to them, please visit http://www.nielsen.com/digitalprivacy.

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.

[[File:TVOs_OptOut_LimitAdTracking1.png]]

[[File:TVOs_OptOut_LimitAdTracking2.png]]

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.

<blockquote>'''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.</blockquote>

==== Legacy Opt-Out ====
'''Supported SDK Versions''': 1.2.3, 4.0.0.8, 5.1.0, 5.1.1.12.

<blockquote>'''Note''': If using SDK Version 5.1.1.17 or above, refer to Opt-Out Implementation (Limit Ad Tracking).</blockquote>

As a global information and measurement leader, Nielsen is committed to protect the privacy and security of the data they collect, process and use. Nielsen strongly believes that the consumer should have a way to Opt-Out of Nielsen measurement.

The Nielsen digital measurement products help Nielsen and its clients to measure and analyze how consumers engage with media across online, mobile and emerging technologies while offering insights into consumer behavior.

To learn more about our digital measurement products and your choices in regard to them, please visit http://www.nielsen.com/digitalprivacy.

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 [[optOutURL]] and opened in ‘WebView’ within the app and NOT in any external browser.
** Opening the Opt-Out page in any external browser takes the application control out of the Nielsen App SDK context.
** As the App SDK does not expose any direct http/https interface to interact with the world to get the user selection on Privacy page, there will be no way to interact/send notification to the App SDK regarding the user selection.
* 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 [[optOutStatus]] method.
<blockquote>'''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.</blockquote>

'''Sequence Diagram'''
[[File:optoutsequence-ios.jpg]]

Below are the steps to implement user Opt-Out using UIWebView.

When a user clicks the Opt-Out / Opt-In link, the application should invoke [[optOutURL]] to get the link to the Nielsen Privacy page from SDK.

'''Implement WebView with Nielsen Opt-Out URL'''
<syntaxhighlight lang="objective-c">NielsenAppApi nAppApiObject;
@property(strong) UIWebView *optOutView;

// create WebView and set self as delegate
self.optOutView=[[UIWebViewalloc]initWithFrame:self.view.bounds];

self.optOutView.scalesPageToFit = yes;
// get Nielsen defined web address and load the page
NSString *webAddress = [nAppApiObject optOutURLString];

if(webAddress == nil)
{ // Handle it gracefully and retry later}
else
{
[optOutView loadRequest:[NSURLRequest requestWithURL:webAddress]];
// show the view to the user
[self.view addSubview:optOutView];
}</syntaxhighlight>

* The Nielsen Privacy Page appears using UIWebView

'''Privacy Page'''

[[File:privacy-policy.jpg]]

* There are two links – one for Opt-Out and one for Opt-In. Click the required link.
* Click OK in the dialog that appears, to confirm the action.
* The Opt-Out occurs by opening a Nielsen-defined web page and passing the user choice from the ‘WebView’. In order to do this, the application needs to
** Implement the UIWebView delegate method to open the Nielsen Privacy web page
** Capture user’s selection
** Pass the selection back to the SDK via the [[userOptOut]].

'''Capture and forward user selection'''
<syntaxhighlight lang="objective-c">-(BOOL)webView:(UIWebView *)webView shouldStartLoadWithRequest:(NSURLRequest *)request navigationType:(UIWebViewNavigationType)navigationType
{
NSString *command = [NSString stringWithFormat:@”%@”,request.URL];
if ([command isEqualToString:kNielsenWebClose]) {
// Close the WebView
[self performSelector:@selector(closeOptOutView) withObject:nil afterDelay:0];
return NO;
}
// Retrieve next URL if it’s not opt-in/out selection
return (![nAppApiObject userOptOut:command]);
}</syntaxhighlight>
* The app gets the user selection string via webviews shouldStartLoadWithRequest and invokes [[userOptOut]] with user selection. The delegate method handles the ‘WebView’ URL requests, interprets the commands, and calls the SDK accordingly.
* <code>[nAppApiObject userOptOut:command]</code> passes the user’s selection on Nielsen Privacy page to the SDK to allow the SDK to perform the required functions.
<blockquote>'''Note''': When ‘WebView’ is closed, pass the status returned from ‘WebView’ to the SDK within the app.</blockquote>

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

== AppApiEventCode ==
An enumeration with predefined App SDK event state transition codes.
<syntaxhighlight lang="objective-c">
typedef NS_ENUM(unsigned int, AppApiEventCode)
{
AppApiStartup = 2001,
AppApiShutdown = 2002,
}AppApiEventCode;
</syntaxhighlight>

== App SDK Event Codes ==
{| class="wikitable"
|-
! 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 ===
An enumeration with predefined error codes which the App SDK object can generate.
<syntaxhighlight lang="objective-c">
typedef NS_ENUM(unsigned int, AppApiErrorCode)
{
AppApiNetworkConnectionFailure = 1001,
AppApiFileWriteFailure = 1002,
AppApiFileReadFailure = 1003,
AppApiEmptyValue = 1004,
AppApiEmptyAppName = 1005,
AppApiEmptyAppVersion = 1006,
AppApiEmptyAppId = 1007,
AppApiAnExceptionOccured = 1008,
AppApiUnknownExceptionOccured = 1009
};
</syntaxhighlight>

=== App SDK Error Codes ===
{| class="wikitable"
|-
! Event Code !! Event Name !! Event 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
|}

iOS SDK API Reference

2017-07-11T21:50:12Z

Admin2: /* AppApiEventCode */

{{Breadcrumb|}} {{Breadcrumb|Digital}} {{CurrentBreadcrumb}}
[[Category:Digital]]
The iOS 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. These SDKs leverage the following:
*Nielsen audio watermark technologies for TV audience measurement
*The industry supported ID3 metadata tag specification
*Nielsen Combined Beacon technology
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
*Application crash events
*Time of viewing a sub section / page in the application.

== Importing Frameworks ==
'''Setting up your Xcode Development Environment'''

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

SDK uses the NSURLSession available from iOS 7 instead of the deprecated NSURLConnection.

<blockquote>'''Note''': App SDK supports devices running on iOS 9 and above, as all communications between the SDK and the Census (Collection Facility) use HTTPS.</blockquote>

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 (Not applicable for International (Germany))
* 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

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

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

== Initialization ==
The latest version of App SDK allows instantiating multiple instances of App SDK object and can be used simultaneously without any issues (The sharedInstance API that creates a singleton object in previous versions of App SDK is removed).
*Maximum of four SDK instances per appid are supported in this release. When a fifth SDK instance is launched,
**SDK will return “nil” from [[initWithAppInfo:delegate:]]
**Destroy one or more old SDK instances before creating new ones.

=== Stages of SDK Initialization ===
==== Step 1: App SDK Initialization ====
Initialize the Nielsen App object within the viewDidLoad view controller delegate method using initWithAppInfo:delegate:
<blockquote>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.</blockquote>

==== Step 2: Setting up event and error notifications ====
Once the <code>NielsenAppApi</code> object has been initialized, the next step is to enable notifications regarding ID3 tags extracted from the playing stream. In case of standard AVFoundation player, the SDK NSNotificationCenter API is used to
* Collect HLS timed metadata events (ID3 tags) during viewing sessions.
** Set up a timed metadata event listener method for receiving ID3 tags and calling Nielsen [[sendID3]].
* SDK uses the following NielsenAppApiDelegate protocol methods to notify its delegate (set during initialization) about event / error information.
** nielsenAppApi:eventOccurred
** nielsenAppApi:errorOccurred
<blockquote>'''Note''': Ensure to add to your view controller’s <code>@interface</code>.</blockquote>

<syntaxhighlight lang="objective-c">(void)nielsenAppApi:(NielsenAppApi *)appApi eventOccurred:(NSDictionary *)event {NSLog(@"Sample player is Notified by a Event : %@", event);
}
(void)nielsenAppApi:(NielsenAppApi *)appApi errorOccurred:(NSDictionary *)error {NSLog(@"Sample player is Notified by an Error : %@", error);
}</syntaxhighlight>

===== Sample event confirmation to player application upon successful initialization of SDK =====
<syntaxhighlight lang="console">NielsenSDKSampleDebug[9028:237989] [Nls:0] -I- Analytics framework Status:
{
"Event Description" = "Nielsen App SDK Version, ai.4.0.0.4 is initialized by the Player…";
EventStatus = 2001;
TimeStamp = "2015-07-23 14:51:06 +0000";
}</syntaxhighlight>

==== Step 3: Nielsen App SDK Streaming Sessions ====
After setting up observers for SDK events/errors and a listener method to process incoming Nielsen ID3 tags, the next steps are to
* Call [[play]] while starting or resuming a streaming session.
* Load CMS metadata using [[loadMetadata]].
* During session play, call [[playheadPosition]] every one second until the stream is stopped or interrupted (due to ad breaks or buffering).
* Call [[stop]] when pausing, ending a viewing session, or buffering is detected.

'''Serialized JSON string from NSDictionary'''
<syntaxhighlight lang="objective-c">NSDictionary* appInformation = @
{
@"appid": @"TXXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX",
@"appname": @"Sample App Name",
@"appversion": @"2.0",
@"sfcode": @"uat-cert",
@"nol_devDebug": @"INFO"
}
NSData* jsonDataAppInfo = [NSJSONSerialization dataWithJSONObject:appInformation options:0 error:nil];
NSString *jsonAppInfoString = [[NSString alloc] initWithData:jsonDataAppInfo encoding:NSUTF8StringEncoding];
nlsAppApiMeter = [[NielsenAppApi alloc] initWithAppInfo:jsonAppInfoString delegate:self];</syntaxhighlight>

Nielsen App SDK object handles filtering of ID3 tags and CMS tags, queuing/buffering of data, and all communications with Nielsen collection facility.

===== Nielsen iOS App SDK Application Life Cycle =====

[[File:initialization_appcycle.png|center|link=]]

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 '''Initial state'''.
# '''Idle state''' – The SDK is initialized and is ready to process playing information. Call <code>[[initWithAppInfo:delegate:]]</code> to move into this state. The SDK instance is not processing any data, but is listening for the play event to occur.
# '''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.
## [[playheadPosition]] – Call this API every one second when playhead position timer is fired.
## [[sendID3]] – Call this API when ID3 tags are identified in the stream.
## [[stop]] – Call this API when the playback is paused, switches between content and ad (within the same content playback) or encounters interruptions.
## [[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. SDK instance moves into this state in one of the following scenarios.
## Initialization fails
## [[appDisableApi]] is called
<blockquote>'''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 [[sendID3]] / [[playheadPosition]].</blockquote>

=== 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.
{| class="wikitable"
|-
! API call received !! Initial State !! Idle State !! Processing State !! Disabled State
|-
| <code>[[initWithAppInfo:delegate:]]</code> || IDLE STATE (OR)

DISABLED STATE
|| IDLE STATE || - || -
|-
| <code>[[play]]</code> & <code>[[loadMetadata]]</code>|| - || PROCESSING

STATE
|| - || -
|-
| <code>[[playheadPosition]]</code> || - || - || PROCESSING

STATE
|| -
|-
| <code>[[sendID3]]</code> || - || - || PROCESSING

STATE
|| -
|-
| <code>[[stop]]</code> || - || - || IDLE STATE || -
|-
| <code>[[end]]</code> || - || - || IDLE STATE || -
|-
| <code>[[appDisableApi]]</code>: YES || - || DISABLED

STATE
|| - || -
|-
| <code>[[appDisableApi]]</code>: NO || - || - || - || IDLE STATE (OR)

DISABLED STATE
|-
| <code>[[userOptOut]]</code>: YES || - || - || IDLE STATE || -
|-
| <code>[[userOptOut]]</code>: NO || - || PROCESSING

STATE
| -
| -
|-
| colspan = 5 | '-' 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.

==== JSON for NSDictionary object ====
<syntaxhighlight lang="objective-c">
NSDictionary* appInformation = @{
@"appid": @"TXXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX",
@"appname": @"Sample App Name",
@"appversion": @"2.0",
@"sfcode": @"uat-cert",
@"nol_devDebug": @"INFO"
};
nlsAppApiMeter = [[NielsenAppApi alloc] initWithAppInfo:appInformation delegate:delegate];</syntaxhighlight>

<code>appid</code>, <code>appname</code>, and <code>appversion</code> are mandatory parameters while <code>sfcode</code> is optional. <code>nol_devDebug</code> is meant for creating logs in test environments only.

==== JSON string from raw NSString ====
<syntaxhighlight lang="swift">NSString *appInfoString = @"{\"appid\" : \"TXXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX\", \"appname\" : \"Sample App Name\",\"appversion\" : \"2.0\",\"sfcode\" : \"uat-cert\"}";
NielsenAppAPi *appAPI = [[NielsenAppApi alloc] initWithAppInfo:appInfoString delegate:self];</syntaxhighlight>

==== JSON string from serialized NSDictionary ====
<syntaxhighlight lang="objective-c">NSDictionary* appInformation = @
{
@"appid": @"appid",
@"appname": @"appname",
@"appversion": @"2.0",
@"sfcode": @"sfcode",
@"nol_devDebug": @"INFO"
};
nlsAppApiMeter = [[NielsenAppApi alloc] initWithAppInfo:appInformation delegate:self];</syntaxhighlight>

While using JSON format for sending metadat, ensure enough care in including [[special characters]] in the values for arguments.

==== Example ====
<syntaxhighlight lang="objective-c">{
@"type": @"radio", // To send "radio" in metadata string
@"assetid": @"WXYZ-FM'101",
@"stationType": @"3",
@"provider": @"SampleProvider" // To send "SampleProvider" in metadata string
}</syntaxhighlight>
<blockquote>'''Note''': For mandatory parameters like appid, appname, and appversion, please refer to the parameters table in <code>[[initWithAppInfo:delegate:]]</code></blockquote>

== Retrieving ID3 Tags ==
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.

=== Sample ID3 tags ===
* <code>www.nielsen.com/X100zdCIGeIlgZnkYj6UvQ==/X100zdCIGeIlgZnkYj6UvQ==/AAAB2Jz2_k74GXSzx4npHuI_JwJd3QSUpW30rDkGTcbHEzIMWleCzM-uvNOP9fzJcQMWQLJqzXMCAxParOb5sGijSV9dNM3QiBniJYGZ5GI-lL1fXTTN0IgZ4iWBmeRiPpS9AAAAAAAAAAAAAAAAAAAAAFJWFM5SVhTONNU=/00000/00000/00</code>
* <code>www.nielsen.com/X100zdCIGeIlgZnkYj6UvQ==/R8WHe7pEBeqBhu8jTeXydg==/AAICoyitYqlxT7n6aZ0oMCGheFi4CXFp46AMUPZz1lMr_M9tr3_cjee1SHqxrOiVerMDLeyn9xzocZSKwi746Re8vNOtpNCAZjYABs_J0R25IHpvOc1HS8QHGgD5TgOJeS6gX100zdCIGeIlgZnkYj6UvVJWFNhSVhTiPE0=/00000/46016/00</code>

=== Examples of extracting ID3 tags from the iOS Native Player ===
==== AVPlayer ====
ID3 tags will be received in the Player on AVMetadataItem Callback method.
'''Create & get the AVMetadataItem callback method'''
<syntaxhighlight lang="swift">[self.player addObserver:self
forKeyPath: kTimedMetadataKey
options: NSKeyValueObservingOptionNew
Context: MyStreamingMovieViewControllerTimedMetadataObserverContext];</syntaxhighlight>

<syntaxhighlight lang="objective-c">
– (void)observeValueForKeyPath:(NSString*) path
ofObject: (id)object
change: (NSDictionary*)change
context: (void*)context
{
/* Set the AVPlayerLayer on the view to allow the AVPlayer object to display
its content. */
//[playerLayerView.playerLayer setPlayer:player];
/* AVPlayerItem "status" property value observer. */
if (context == MyStreamingMovieViewControllerTimedMetadataObserverContext)
{
id newMetadataArray = [change objectForKey:NSKeyValueChangeNewKey];
if (newMetadataArray != [NSNull null])
{
array = newMetadataArray;
for (AVMetadataItem *metadataItem in array)
{
[self handleTimedMetadata: metadataItem];
}
}
}
</syntaxhighlight>

<syntaxhighlight lang="objective-c">
– (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;
}
if ([(NSString *)[timedMetadata key] isEqualToString:@"PRIV"]&&[extraString rangeOfString:@"www.nielsen.com"].length> 0)
{
if ([[timedMetadata value] isKindOfClass:[NSData class]])
{
// Sending ID3 Tag
/* The sendID3: sends the extracted Nielsen ID3 payload to the App SDK for analysis. */
[[NielsenAppApi sharedInstance]sendID3: extraString];
NSString *value=[timedMetadata stringValue];
if (value != nil)
{
// NSString *strMessage=[[@"ID3 Tag Received " stringByAppendingFormat:@"%d\n",countForMetadata] stringByAppendingString:value];
[self appendLogConsoleText:extraString];
}
}
}
else
{
NSLog(@"Could not send ID3 tags");
}
countForMetadata++;

}
</syntaxhighlight>

==== Movie Player ====
ID3 tags will be received in the Player on MPTimedMetadata Callback method.
'''Sample Implementation of MPTimedMetadata callback'''
<syntaxhighlight lang="objective-c">
– (void)handleTimedMetadata:(MPTimedMetadata*)timedMetadata
{
id extraAttributeType = [timedMetadata allMetadata];
NSString * extraString= nil;
if ([extraAttributeType isKindOfClass:[NSDictionary class]])
{
extraString = [extraAttributeType valueForKey:@"info"];
}
else if([extraAttributeType isKindOfClass:[NSString class]])
{
extraString = extraAttributeType;
}

if ([(NSString *)[timedMetadata key] isEqualToString:@"PRIV"]&&[extraString rangeOfString:@"www.nielsen.com"].length> 0)
{
if ([[timedMetadata value] isKindOfClass:[NSData class]])
{
// Sending ID3 Tag
[[NielsenAppApi sharedInstance]sendID3: extraString];
NSString *value=[timedMetadata value];
if (value != nil)
{

[self appendLogConsoleText:extraString];
}
}
}
else
{
NSLog(@"Could not send ID3 tags");
}
countForMetadata++;
}
</syntaxhighlight>
<blockquote>'''Note:''' ID3 tags are not applicable for International (Germany)</blockquote>

== IOS SDK API Methods & Properties ==
{| class="wikitable sortable"
|-
! Scenario !! Method / Property !! DTVR !! DAR !! Digital Audio !! 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 || [[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.
|-
| 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)
|}

== 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 to this web page should be called from SDK by invoking [[optOutURL]] and opened in 'WebView' / External browser.
*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 [[optOutStatus]] method.

=== Displaying Opt-Out in a WebView ===
<syntaxhighlight lang="objective-c">
NielsenAppApi nAppApiObject;
@property(strong) UIWebView *optOutView;
// create WebView and set self as delegate
self.optOutView=[[UIWebView alloc]initWithFrame:self.view.bounds];
self.optOutView.scalesPageToFit = yes;
// get Nielsen defined web address and load the page
NSString *webAddress = [nAppApiObject optOutURLString];
If(webAddress == nil)
{ // Handle it gracefully and retry later} else
{[optOutView loadRequest:[NSURLRequest requestWithURL:webAddress]];
// show the view to the user
[self.view addSubview:optOutView]; }
</syntaxhighlight>

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.

[[File:Privacy policy iOS.jpg|link=]]

*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.
<syntaxhighlight lang="objective-c">
@property (readonly) BOOL optOutStatus;
</syntaxhighlight>
*App should provide a UI control like 'close' or 'back' button to close the 'WebView' / External browser.

=== Sequence Diagram ===
[[File:optoutsequence-ios.jpg|link=]]

== Opt-out SDK Version '''5.1.1.17 or above''' ==
<blockquote>'''Note:''' If using SDK Versions 1.2.3, 4.0.0.8, 5.1.0, 5.1.1.12, skip ahead to: [[#Opt-out SDK Version 1.2.3, 4.0.0.8, 5.1.0, 5.1.1.12|Opt-out SDK Version 1.2.3, 4.0.0.8, 5.1.0, 5.1.1.12]]</blockquote>

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.

[[File:Opt-Out iOS.jpg|link=]]

<blockquote>'''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.</blockquote>

== Opt-out SDK Version '''1.2.3, 4.0.0.8, 5.1.0, 5.1.1.12''' ==
<blockquote>'''Note:''' If using SDK Version 5.1.1.17 or above, refer to documentation above ([[#Opt-out SDK Version 5.1.1.17 or above|Opt-out SDK Version 5.1.1.17 or above]])</blockquote>

When a user clicks the Opt-Out / Opt-In link, the application should invoke [[optOutURL]] to get the link to the Nielsen Privacy page from SDK.
=== Privacy Page ===
[[File:privacy-policy.jpg|link=]]
*There are two click here links – one for Opt-Out and one for Opt-In. Click the required link:
**
[[File:Opt-Out Combined.jpg|link=]]
*Click OK in the dialog that appears, to confirm the action.
*The Opt-Out occurs by opening a Nielsen-defined web page and passing the user choice from the 'WebView'. In order to do this, the application needs to
**Implement the UIWebView delegate method to open the Nielsen Privacy web page
**Capture user's selection
**Pass the selection back to the SDK via the [[userOptOut]].

=== Capture and forward user selection ===
<syntaxhighlight lang="objective-c">
-(BOOL)webView:(UIWebView *)webView
shouldStartLoadWithRequest:(NSURLRequest *)request
navigationType:(UIWebViewNavigationType)navigationType
{
NSString *command = [NSString stringWithFormat:@"%@",
request.URL];
if ([command isEqualToString:kNielsenWebClose]) {
// Close the WebView
[self performSelector:@selector(closeOptOutView)
withObject:nil afterDelay:0];
return NO;
}
// Retrieve next URL if it's not opt-in/out selection
return (![nAppApiObject userOptOut:command]);
}
</syntaxhighlight>

*The app gets the user selection string via webviews shouldStartLoadWithRequest and invokes [[userOptOut]] with user selection. The delegate method handles the 'WebView' URL requests, interprets the commands, and calls the SDK accordingly.
**<code>[nAppApiObject userOptOut:command]</code> passes the user's selection on Nielsen Privacy page to the SDK to allow the SDK to perform the required functions.
<blockquote>'''Note:''' When 'WebView' is closed, pass the status returned from 'WebView' to the SDK within the app.</blockquote>
<blockquote>'''Note:''' App SDK manages the user's choice (Opt-Out / Opt-In), the app does not need to manage this status.</blockquote>

== 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:

[[File:TVOs OptOut LimitAdTracking1.png|link=]]

[[File:TVOs OptOut LimitAdTracking2.png|link=]]

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.

<blockquote>'''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.</blockquote>

== 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:
<syntaxhighlight lang="objective-c">
@interface NielsenAppApi: NSObject

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

– (instancetype)initWithAppInfo:(id)appInfo delegate:(id)delegate;

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

– (NSString *)getNielsenId _attribute((deprecated((“Please use nielsenId property instead.”))));
– (NSString *)optOutURLString _attribute((deprecated((“Please use optOutURL property instead.”))));
– (NSString *)getMeterVersion _attribute((deprecated((“Please use meterVersion property instead.”))));
– (NSDictionary *)getLastEventDict _attribute((deprecated((“Please use lastEventDict property instead.”))));
– (NSDictionary *)getLastErrorDict _attribute((deprecated((“Please use lastErrorDict property instead.”))));

@protocol NielsenAppApiDelegate<NSObject>

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

@end
</syntaxhighlight>

== Nielsen Sample Applications ==
Nielsen iOS sample player application consists of two sample application based on native Players integrated with SDK framework. The player demonstrates all the supported functions of the SDK.
*NielsenVideoPlayer
*NielsenRadioPlayer
Implementation of Video and Audio 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 two locations:
**Channels 1 and 2 are configured from the Settings application. Channel URLs and metadata parameters can be modified.
**Channels starting from 3 are configured in specific JSON file. URLs to this JSON config file can be changed from the Settings application.

== Nielsen Privacy Requirements ==
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.
[[File:RatingsDataFlow.png]]

'''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 ===
{| class="wikitable"
|-
! Type of Information !! Parameter !! Transmitted to Nielsen? !! Sent to Provider?
|-
| rowspan="8" | 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
|-
| rowspan="10" | 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
|-
| rowspan="9" | 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
|}
<blockquote>'''Note''': Data is hashed, and encrypted using AES 128 before transmission to data provider.</blockquote>

==== Example ping sent to provider ====
* <code><nowiki>https://provider.com/cgi-bin/brandlift.php</nowiki>?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</code>

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

=== Nielsen Measurement Opt-Out ===
In accordance with Nielsen’s SDK licensing agreement, developers are required to provide basic informational data to users about Nielsen’s Privacy Policy with a navigation to additional information on Nielsen measurement.

Nielsen currently uses Limit Ad Tracking for the latest versions of the SDK (5.1.1.17 and above). However, for older SDK versions, the app must provide a means for the user to opt out, or opt back in to Nielsen Measurement. Users can opt out of Nielsen online measurement research through this feature.
* If the user has this app running on more than one mobile device, the user will need to opt out of this measurement on each device.
<blockquote>'''Note''': Opt Out feature does NOT rely on "Limit Ad Tracking" setting since Nielsen’s systems provide measurement metrics and do not serve ads to users.</blockquote>

In the Description of the app in App Store, include a short description about Nielsen measurement, as below.

<blockquote>'''Sample App Store Disclosure'''
This app features Nielsen proprietary measurement software which will allow you to contribute to market research, like Nielsen’s TV Ratings.

To learn more about our digital measurement products and your choices in regard to them, please visit http://www.nielsen.com/digitalprivacy for more information.

[[File:measurement-samplescreen.jpg]]</blockquote>

Both iOS-based and TVOS-based player applications need to confirm to Nielsen Privacy Requirements. Refer to the Opt-Out implementation guidelines for iOS and TVOS platforms respectively for more details.

=== Opt-Out Implementation ===
==== Limit Ad Tracking ====
'''This implementation is valid for SDK Versions 5.1.1.17 and above.'''

<blockquote>'''Note''': If using SDK Version 1.2.3, 4.0.0.8, 5.1.0 or 5.1.1.12, refer to Opt-Out Implementation for iOS.</blockquote>

As a global information and measurement leader, Nielsen is committed to protect the privacy and security of the data they collect, process and use. Nielsen strongly believes that the consumer should have a way to opt out of Nielsen measurement.

The Nielsen digital measurement products help Nielsen and its clients to measure and analyze how consumers engage with media across online, mobile and emerging technologies while offering insights into consumer behavior.

To learn more about our digital measurement products and your choices in regard to them, please visit http://www.nielsen.com/digitalprivacy.

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 optOutURL and opened in ‘WebView’ / External browser.
* 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 optOutStatus method.
'''Displaying Opt-Out in a WebView'''
<syntaxhighlight lang="objective-c">NielsenAppApi nAppApiObject;
@property(strong) UIWebView *optOutView;
// create WebView and set self as delegate
self.optOutView=[[UIWebView alloc]initWithFrame:self.view.bounds];
self.optOutView.scalesPageToFit = yes;
// get Nielsen defined web address and load the page
NSString *webAddress = [nAppApiObject optOutURLString];
If(webAddress == nil)
{
// Handle it gracefully and retry later
}

else
{
[optOutView loadRequest:[NSURLRequest requestWithURL:webAddress]];
// show the view to the user
[self.view addSubview:optOutView];
}</syntaxhighlight>

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.

[[File:Opt-Out_iOS.jpg]]
<blockquote>'''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.</blockquote>

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.

[[File: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.
<syntaxhighlight lang="objective-c">@property (readonly) BOOL optOutStatus;</blockquote>
* App should provide a UI control like ‘close’ or ‘back’ button to close the ‘WebView’ / External browser.

'''Sequence Diagram'''
[[File:optoutsequence-ios.jpg]]

== Event and Error Handling ==
=== Constants / Enumerations ===
The following are the details of Delegate Implementation:

<syntaxhighlight lang="objective-c">
-(void)nielsenAppApi:(NielsenAppApi *)appApi eventOccurred:(NSDictionary *)event
{
NSLog(@"Sample player is Notified by a Event: %@", event);
}
– (void)nielsenAppApi:(NielsenAppApi *)appApi errorOccurred:(NSDictionary *)error
{
NSLog(@"Sample player is Notified by an Error: %@", error);
}
</syntaxhighlight>

==== TVOS Implementation ====
As a global information and measurement leader, Nielsen is committed to protect the privacy and security of the data they collect, process and use. Nielsen strongly believes that the client should have a way to Opt-Out of Nielsen measurement.

The Nielsen digital measurement products are not used to identify consumer in any way. They help Nielsen and its clients to measure and analyze how consumers engage with media across online, mobile and emerging technologies while offering insights into consumer behavior.

To learn more about our digital measurement products and your choices in regard to them, please visit http://www.nielsen.com/digitalprivacy.

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.

[[File:TVOs_OptOut_LimitAdTracking1.png]]

[[File:TVOs_OptOut_LimitAdTracking2.png]]

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.

<blockquote>'''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.</blockquote>

==== Legacy Opt-Out ====
'''Supported SDK Versions''': 1.2.3, 4.0.0.8, 5.1.0, 5.1.1.12.

<blockquote>'''Note''': If using SDK Version 5.1.1.17 or above, refer to Opt-Out Implementation (Limit Ad Tracking).</blockquote>

As a global information and measurement leader, Nielsen is committed to protect the privacy and security of the data they collect, process and use. Nielsen strongly believes that the consumer should have a way to Opt-Out of Nielsen measurement.

The Nielsen digital measurement products help Nielsen and its clients to measure and analyze how consumers engage with media across online, mobile and emerging technologies while offering insights into consumer behavior.

To learn more about our digital measurement products and your choices in regard to them, please visit http://www.nielsen.com/digitalprivacy.

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 [[optOutURL]] and opened in ‘WebView’ within the app and NOT in any external browser.
** Opening the Opt-Out page in any external browser takes the application control out of the Nielsen App SDK context.
** As the App SDK does not expose any direct http/https interface to interact with the world to get the user selection on Privacy page, there will be no way to interact/send notification to the App SDK regarding the user selection.
* 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 [[optOutStatus]] method.
<blockquote>'''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.</blockquote>

'''Sequence Diagram'''
[[File:optoutsequence-ios.jpg]]

Below are the steps to implement user Opt-Out using UIWebView.

When a user clicks the Opt-Out / Opt-In link, the application should invoke [[optOutURL]] to get the link to the Nielsen Privacy page from SDK.

'''Implement WebView with Nielsen Opt-Out URL'''
<syntaxhighlight lang="objective-c">NielsenAppApi nAppApiObject;
@property(strong) UIWebView *optOutView;

// create WebView and set self as delegate
self.optOutView=[[UIWebViewalloc]initWithFrame:self.view.bounds];

self.optOutView.scalesPageToFit = yes;
// get Nielsen defined web address and load the page
NSString *webAddress = [nAppApiObject optOutURLString];

if(webAddress == nil)
{ // Handle it gracefully and retry later}
else
{
[optOutView loadRequest:[NSURLRequest requestWithURL:webAddress]];
// show the view to the user
[self.view addSubview:optOutView];
}</syntaxhighlight>

* The Nielsen Privacy Page appears using UIWebView

'''Privacy Page'''

[[File:privacy-policy.jpg]]

* There are two links – one for Opt-Out and one for Opt-In. Click the required link.
* Click OK in the dialog that appears, to confirm the action.
* The Opt-Out occurs by opening a Nielsen-defined web page and passing the user choice from the ‘WebView’. In order to do this, the application needs to
** Implement the UIWebView delegate method to open the Nielsen Privacy web page
** Capture user’s selection
** Pass the selection back to the SDK via the [[userOptOut]].

'''Capture and forward user selection'''
<syntaxhighlight lang="objective-c">-(BOOL)webView:(UIWebView *)webView shouldStartLoadWithRequest:(NSURLRequest *)request navigationType:(UIWebViewNavigationType)navigationType
{
NSString *command = [NSString stringWithFormat:@”%@”,request.URL];
if ([command isEqualToString:kNielsenWebClose]) {
// Close the WebView
[self performSelector:@selector(closeOptOutView) withObject:nil afterDelay:0];
return NO;
}
// Retrieve next URL if it’s not opt-in/out selection
return (![nAppApiObject userOptOut:command]);
}</syntaxhighlight>
* The app gets the user selection string via webviews shouldStartLoadWithRequest and invokes [[userOptOut]] with user selection. The delegate method handles the ‘WebView’ URL requests, interprets the commands, and calls the SDK accordingly.
* <code>[nAppApiObject userOptOut:command]</code> passes the user’s selection on Nielsen Privacy page to the SDK to allow the SDK to perform the required functions.
<blockquote>'''Note''': When ‘WebView’ is closed, pass the status returned from ‘WebView’ to the SDK within the app.</blockquote>

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

== AppApiEventCode ==
An enumeration with predefined App SDK event state transition codes.
<syntaxhighlight lang="objective-c">
typedef NS_ENUM(unsigned int, AppApiEventCode)
{
AppApiStartup = 2001,
AppApiShutdown = 2002,
}AppApiEventCode;
</syntaxhighlight>

=== App SDK Event Codes ===
{| class="wikitable"
|-
! 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 ===
An enumeration with predefined error codes which the App SDK object can generate.
<syntaxhighlight lang="objective-c">
typedef NS_ENUM(unsigned int, AppApiErrorCode)
{
AppApiNetworkConnectionFailure = 1001,
AppApiFileWriteFailure = 1002,
AppApiFileReadFailure = 1003,
AppApiEmptyValue = 1004,
AppApiEmptyAppName = 1005,
AppApiEmptyAppVersion = 1006,
AppApiEmptyAppId = 1007,
AppApiAnExceptionOccured = 1008,
AppApiUnknownExceptionOccured = 1009
};
</syntaxhighlight>

=== App SDK Error Codes ===
{| class="wikitable"
|-
! Event Code !! Event Name !! Event 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
|}

iOS SDK API Reference

2017-07-11T21:49:25Z

Admin2: /* Opt-Out Implementation */

{{Breadcrumb|}} {{Breadcrumb|Digital}} {{CurrentBreadcrumb}}
[[Category:Digital]]
The iOS 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. These SDKs leverage the following:
*Nielsen audio watermark technologies for TV audience measurement
*The industry supported ID3 metadata tag specification
*Nielsen Combined Beacon technology
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
*Application crash events
*Time of viewing a sub section / page in the application.

== Importing Frameworks ==
'''Setting up your Xcode Development Environment'''

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

SDK uses the NSURLSession available from iOS 7 instead of the deprecated NSURLConnection.

<blockquote>'''Note''': App SDK supports devices running on iOS 9 and above, as all communications between the SDK and the Census (Collection Facility) use HTTPS.</blockquote>

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 (Not applicable for International (Germany))
* 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

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

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

== Initialization ==
The latest version of App SDK allows instantiating multiple instances of App SDK object and can be used simultaneously without any issues (The sharedInstance API that creates a singleton object in previous versions of App SDK is removed).
*Maximum of four SDK instances per appid are supported in this release. When a fifth SDK instance is launched,
**SDK will return “nil” from [[initWithAppInfo:delegate:]]
**Destroy one or more old SDK instances before creating new ones.

=== Stages of SDK Initialization ===
==== Step 1: App SDK Initialization ====
Initialize the Nielsen App object within the viewDidLoad view controller delegate method using initWithAppInfo:delegate:
<blockquote>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.</blockquote>

==== Step 2: Setting up event and error notifications ====
Once the <code>NielsenAppApi</code> object has been initialized, the next step is to enable notifications regarding ID3 tags extracted from the playing stream. In case of standard AVFoundation player, the SDK NSNotificationCenter API is used to
* Collect HLS timed metadata events (ID3 tags) during viewing sessions.
** Set up a timed metadata event listener method for receiving ID3 tags and calling Nielsen [[sendID3]].
* SDK uses the following NielsenAppApiDelegate protocol methods to notify its delegate (set during initialization) about event / error information.
** nielsenAppApi:eventOccurred
** nielsenAppApi:errorOccurred
<blockquote>'''Note''': Ensure to add to your view controller’s <code>@interface</code>.</blockquote>

<syntaxhighlight lang="objective-c">(void)nielsenAppApi:(NielsenAppApi *)appApi eventOccurred:(NSDictionary *)event {NSLog(@"Sample player is Notified by a Event : %@", event);
}
(void)nielsenAppApi:(NielsenAppApi *)appApi errorOccurred:(NSDictionary *)error {NSLog(@"Sample player is Notified by an Error : %@", error);
}</syntaxhighlight>

===== Sample event confirmation to player application upon successful initialization of SDK =====
<syntaxhighlight lang="console">NielsenSDKSampleDebug[9028:237989] [Nls:0] -I- Analytics framework Status:
{
"Event Description" = "Nielsen App SDK Version, ai.4.0.0.4 is initialized by the Player…";
EventStatus = 2001;
TimeStamp = "2015-07-23 14:51:06 +0000";
}</syntaxhighlight>

==== Step 3: Nielsen App SDK Streaming Sessions ====
After setting up observers for SDK events/errors and a listener method to process incoming Nielsen ID3 tags, the next steps are to
* Call [[play]] while starting or resuming a streaming session.
* Load CMS metadata using [[loadMetadata]].
* During session play, call [[playheadPosition]] every one second until the stream is stopped or interrupted (due to ad breaks or buffering).
* Call [[stop]] when pausing, ending a viewing session, or buffering is detected.

'''Serialized JSON string from NSDictionary'''
<syntaxhighlight lang="objective-c">NSDictionary* appInformation = @
{
@"appid": @"TXXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX",
@"appname": @"Sample App Name",
@"appversion": @"2.0",
@"sfcode": @"uat-cert",
@"nol_devDebug": @"INFO"
}
NSData* jsonDataAppInfo = [NSJSONSerialization dataWithJSONObject:appInformation options:0 error:nil];
NSString *jsonAppInfoString = [[NSString alloc] initWithData:jsonDataAppInfo encoding:NSUTF8StringEncoding];
nlsAppApiMeter = [[NielsenAppApi alloc] initWithAppInfo:jsonAppInfoString delegate:self];</syntaxhighlight>

Nielsen App SDK object handles filtering of ID3 tags and CMS tags, queuing/buffering of data, and all communications with Nielsen collection facility.

===== Nielsen iOS App SDK Application Life Cycle =====

[[File:initialization_appcycle.png|center|link=]]

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 '''Initial state'''.
# '''Idle state''' – The SDK is initialized and is ready to process playing information. Call <code>[[initWithAppInfo:delegate:]]</code> to move into this state. The SDK instance is not processing any data, but is listening for the play event to occur.
# '''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.
## [[playheadPosition]] – Call this API every one second when playhead position timer is fired.
## [[sendID3]] – Call this API when ID3 tags are identified in the stream.
## [[stop]] – Call this API when the playback is paused, switches between content and ad (within the same content playback) or encounters interruptions.
## [[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. SDK instance moves into this state in one of the following scenarios.
## Initialization fails
## [[appDisableApi]] is called
<blockquote>'''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 [[sendID3]] / [[playheadPosition]].</blockquote>

=== 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.
{| class="wikitable"
|-
! API call received !! Initial State !! Idle State !! Processing State !! Disabled State
|-
| <code>[[initWithAppInfo:delegate:]]</code> || IDLE STATE (OR)

DISABLED STATE
|| IDLE STATE || - || -
|-
| <code>[[play]]</code> & <code>[[loadMetadata]]</code>|| - || PROCESSING

STATE
|| - || -
|-
| <code>[[playheadPosition]]</code> || - || - || PROCESSING

STATE
|| -
|-
| <code>[[sendID3]]</code> || - || - || PROCESSING

STATE
|| -
|-
| <code>[[stop]]</code> || - || - || IDLE STATE || -
|-
| <code>[[end]]</code> || - || - || IDLE STATE || -
|-
| <code>[[appDisableApi]]</code>: YES || - || DISABLED

STATE
|| - || -
|-
| <code>[[appDisableApi]]</code>: NO || - || - || - || IDLE STATE (OR)

DISABLED STATE
|-
| <code>[[userOptOut]]</code>: YES || - || - || IDLE STATE || -
|-
| <code>[[userOptOut]]</code>: NO || - || PROCESSING

STATE
| -
| -
|-
| colspan = 5 | '-' 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.

==== JSON for NSDictionary object ====
<syntaxhighlight lang="objective-c">
NSDictionary* appInformation = @{
@"appid": @"TXXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX",
@"appname": @"Sample App Name",
@"appversion": @"2.0",
@"sfcode": @"uat-cert",
@"nol_devDebug": @"INFO"
};
nlsAppApiMeter = [[NielsenAppApi alloc] initWithAppInfo:appInformation delegate:delegate];</syntaxhighlight>

<code>appid</code>, <code>appname</code>, and <code>appversion</code> are mandatory parameters while <code>sfcode</code> is optional. <code>nol_devDebug</code> is meant for creating logs in test environments only.

==== JSON string from raw NSString ====
<syntaxhighlight lang="swift">NSString *appInfoString = @"{\"appid\" : \"TXXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX\", \"appname\" : \"Sample App Name\",\"appversion\" : \"2.0\",\"sfcode\" : \"uat-cert\"}";
NielsenAppAPi *appAPI = [[NielsenAppApi alloc] initWithAppInfo:appInfoString delegate:self];</syntaxhighlight>

==== JSON string from serialized NSDictionary ====
<syntaxhighlight lang="objective-c">NSDictionary* appInformation = @
{
@"appid": @"appid",
@"appname": @"appname",
@"appversion": @"2.0",
@"sfcode": @"sfcode",
@"nol_devDebug": @"INFO"
};
nlsAppApiMeter = [[NielsenAppApi alloc] initWithAppInfo:appInformation delegate:self];</syntaxhighlight>

While using JSON format for sending metadat, ensure enough care in including [[special characters]] in the values for arguments.

==== Example ====
<syntaxhighlight lang="objective-c">{
@"type": @"radio", // To send "radio" in metadata string
@"assetid": @"WXYZ-FM'101",
@"stationType": @"3",
@"provider": @"SampleProvider" // To send "SampleProvider" in metadata string
}</syntaxhighlight>
<blockquote>'''Note''': For mandatory parameters like appid, appname, and appversion, please refer to the parameters table in <code>[[initWithAppInfo:delegate:]]</code></blockquote>

== Retrieving ID3 Tags ==
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.

=== Sample ID3 tags ===
* <code>www.nielsen.com/X100zdCIGeIlgZnkYj6UvQ==/X100zdCIGeIlgZnkYj6UvQ==/AAAB2Jz2_k74GXSzx4npHuI_JwJd3QSUpW30rDkGTcbHEzIMWleCzM-uvNOP9fzJcQMWQLJqzXMCAxParOb5sGijSV9dNM3QiBniJYGZ5GI-lL1fXTTN0IgZ4iWBmeRiPpS9AAAAAAAAAAAAAAAAAAAAAFJWFM5SVhTONNU=/00000/00000/00</code>
* <code>www.nielsen.com/X100zdCIGeIlgZnkYj6UvQ==/R8WHe7pEBeqBhu8jTeXydg==/AAICoyitYqlxT7n6aZ0oMCGheFi4CXFp46AMUPZz1lMr_M9tr3_cjee1SHqxrOiVerMDLeyn9xzocZSKwi746Re8vNOtpNCAZjYABs_J0R25IHpvOc1HS8QHGgD5TgOJeS6gX100zdCIGeIlgZnkYj6UvVJWFNhSVhTiPE0=/00000/46016/00</code>

=== Examples of extracting ID3 tags from the iOS Native Player ===
==== AVPlayer ====
ID3 tags will be received in the Player on AVMetadataItem Callback method.
'''Create & get the AVMetadataItem callback method'''
<syntaxhighlight lang="swift">[self.player addObserver:self
forKeyPath: kTimedMetadataKey
options: NSKeyValueObservingOptionNew
Context: MyStreamingMovieViewControllerTimedMetadataObserverContext];</syntaxhighlight>

<syntaxhighlight lang="objective-c">
– (void)observeValueForKeyPath:(NSString*) path
ofObject: (id)object
change: (NSDictionary*)change
context: (void*)context
{
/* Set the AVPlayerLayer on the view to allow the AVPlayer object to display
its content. */
//[playerLayerView.playerLayer setPlayer:player];
/* AVPlayerItem "status" property value observer. */
if (context == MyStreamingMovieViewControllerTimedMetadataObserverContext)
{
id newMetadataArray = [change objectForKey:NSKeyValueChangeNewKey];
if (newMetadataArray != [NSNull null])
{
array = newMetadataArray;
for (AVMetadataItem *metadataItem in array)
{
[self handleTimedMetadata: metadataItem];
}
}
}
</syntaxhighlight>

<syntaxhighlight lang="objective-c">
– (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;
}
if ([(NSString *)[timedMetadata key] isEqualToString:@"PRIV"]&&[extraString rangeOfString:@"www.nielsen.com"].length> 0)
{
if ([[timedMetadata value] isKindOfClass:[NSData class]])
{
// Sending ID3 Tag
/* The sendID3: sends the extracted Nielsen ID3 payload to the App SDK for analysis. */
[[NielsenAppApi sharedInstance]sendID3: extraString];
NSString *value=[timedMetadata stringValue];
if (value != nil)
{
// NSString *strMessage=[[@"ID3 Tag Received " stringByAppendingFormat:@"%d\n",countForMetadata] stringByAppendingString:value];
[self appendLogConsoleText:extraString];
}
}
}
else
{
NSLog(@"Could not send ID3 tags");
}
countForMetadata++;

}
</syntaxhighlight>

==== Movie Player ====
ID3 tags will be received in the Player on MPTimedMetadata Callback method.
'''Sample Implementation of MPTimedMetadata callback'''
<syntaxhighlight lang="objective-c">
– (void)handleTimedMetadata:(MPTimedMetadata*)timedMetadata
{
id extraAttributeType = [timedMetadata allMetadata];
NSString * extraString= nil;
if ([extraAttributeType isKindOfClass:[NSDictionary class]])
{
extraString = [extraAttributeType valueForKey:@"info"];
}
else if([extraAttributeType isKindOfClass:[NSString class]])
{
extraString = extraAttributeType;
}

if ([(NSString *)[timedMetadata key] isEqualToString:@"PRIV"]&&[extraString rangeOfString:@"www.nielsen.com"].length> 0)
{
if ([[timedMetadata value] isKindOfClass:[NSData class]])
{
// Sending ID3 Tag
[[NielsenAppApi sharedInstance]sendID3: extraString];
NSString *value=[timedMetadata value];
if (value != nil)
{

[self appendLogConsoleText:extraString];
}
}
}
else
{
NSLog(@"Could not send ID3 tags");
}
countForMetadata++;
}
</syntaxhighlight>
<blockquote>'''Note:''' ID3 tags are not applicable for International (Germany)</blockquote>

== IOS SDK API Methods & Properties ==
{| class="wikitable sortable"
|-
! Scenario !! Method / Property !! DTVR !! DAR !! Digital Audio !! 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 || [[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.
|-
| 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)
|}

== 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 to this web page should be called from SDK by invoking [[optOutURL]] and opened in 'WebView' / External browser.
*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 [[optOutStatus]] method.

=== Displaying Opt-Out in a WebView ===
<syntaxhighlight lang="objective-c">
NielsenAppApi nAppApiObject;
@property(strong) UIWebView *optOutView;
// create WebView and set self as delegate
self.optOutView=[[UIWebView alloc]initWithFrame:self.view.bounds];
self.optOutView.scalesPageToFit = yes;
// get Nielsen defined web address and load the page
NSString *webAddress = [nAppApiObject optOutURLString];
If(webAddress == nil)
{ // Handle it gracefully and retry later} else
{[optOutView loadRequest:[NSURLRequest requestWithURL:webAddress]];
// show the view to the user
[self.view addSubview:optOutView]; }
</syntaxhighlight>

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.

[[File:Privacy policy iOS.jpg|link=]]

*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.
<syntaxhighlight lang="objective-c">
@property (readonly) BOOL optOutStatus;
</syntaxhighlight>
*App should provide a UI control like 'close' or 'back' button to close the 'WebView' / External browser.

=== Sequence Diagram ===
[[File:optoutsequence-ios.jpg|link=]]

== Opt-out SDK Version '''5.1.1.17 or above''' ==
<blockquote>'''Note:''' If using SDK Versions 1.2.3, 4.0.0.8, 5.1.0, 5.1.1.12, skip ahead to: [[#Opt-out SDK Version 1.2.3, 4.0.0.8, 5.1.0, 5.1.1.12|Opt-out SDK Version 1.2.3, 4.0.0.8, 5.1.0, 5.1.1.12]]</blockquote>

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.

[[File:Opt-Out iOS.jpg|link=]]

<blockquote>'''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.</blockquote>

== Opt-out SDK Version '''1.2.3, 4.0.0.8, 5.1.0, 5.1.1.12''' ==
<blockquote>'''Note:''' If using SDK Version 5.1.1.17 or above, refer to documentation above ([[#Opt-out SDK Version 5.1.1.17 or above|Opt-out SDK Version 5.1.1.17 or above]])</blockquote>

When a user clicks the Opt-Out / Opt-In link, the application should invoke [[optOutURL]] to get the link to the Nielsen Privacy page from SDK.
=== Privacy Page ===
[[File:privacy-policy.jpg|link=]]
*There are two click here links – one for Opt-Out and one for Opt-In. Click the required link:
**
[[File:Opt-Out Combined.jpg|link=]]
*Click OK in the dialog that appears, to confirm the action.
*The Opt-Out occurs by opening a Nielsen-defined web page and passing the user choice from the 'WebView'. In order to do this, the application needs to
**Implement the UIWebView delegate method to open the Nielsen Privacy web page
**Capture user's selection
**Pass the selection back to the SDK via the [[userOptOut]].

=== Capture and forward user selection ===
<syntaxhighlight lang="objective-c">
-(BOOL)webView:(UIWebView *)webView
shouldStartLoadWithRequest:(NSURLRequest *)request
navigationType:(UIWebViewNavigationType)navigationType
{
NSString *command = [NSString stringWithFormat:@"%@",
request.URL];
if ([command isEqualToString:kNielsenWebClose]) {
// Close the WebView
[self performSelector:@selector(closeOptOutView)
withObject:nil afterDelay:0];
return NO;
}
// Retrieve next URL if it's not opt-in/out selection
return (![nAppApiObject userOptOut:command]);
}
</syntaxhighlight>

*The app gets the user selection string via webviews shouldStartLoadWithRequest and invokes [[userOptOut]] with user selection. The delegate method handles the 'WebView' URL requests, interprets the commands, and calls the SDK accordingly.
**<code>[nAppApiObject userOptOut:command]</code> passes the user's selection on Nielsen Privacy page to the SDK to allow the SDK to perform the required functions.
<blockquote>'''Note:''' When 'WebView' is closed, pass the status returned from 'WebView' to the SDK within the app.</blockquote>
<blockquote>'''Note:''' App SDK manages the user's choice (Opt-Out / Opt-In), the app does not need to manage this status.</blockquote>

== 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:

[[File:TVOs OptOut LimitAdTracking1.png|link=]]

[[File:TVOs OptOut LimitAdTracking2.png|link=]]

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.

<blockquote>'''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.</blockquote>

== 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:
<syntaxhighlight lang="objective-c">
@interface NielsenAppApi: NSObject

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

– (instancetype)initWithAppInfo:(id)appInfo delegate:(id)delegate;

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

– (NSString *)getNielsenId _attribute((deprecated((“Please use nielsenId property instead.”))));
– (NSString *)optOutURLString _attribute((deprecated((“Please use optOutURL property instead.”))));
– (NSString *)getMeterVersion _attribute((deprecated((“Please use meterVersion property instead.”))));
– (NSDictionary *)getLastEventDict _attribute((deprecated((“Please use lastEventDict property instead.”))));
– (NSDictionary *)getLastErrorDict _attribute((deprecated((“Please use lastErrorDict property instead.”))));

@protocol NielsenAppApiDelegate<NSObject>

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

@end
</syntaxhighlight>

== Nielsen Sample Applications ==
Nielsen iOS sample player application consists of two sample application based on native Players integrated with SDK framework. The player demonstrates all the supported functions of the SDK.
*NielsenVideoPlayer
*NielsenRadioPlayer
Implementation of Video and Audio 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 two locations:
**Channels 1 and 2 are configured from the Settings application. Channel URLs and metadata parameters can be modified.
**Channels starting from 3 are configured in specific JSON file. URLs to this JSON config file can be changed from the Settings application.

== Nielsen Privacy Requirements ==
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.
[[File:RatingsDataFlow.png]]

'''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 ===
{| class="wikitable"
|-
! Type of Information !! Parameter !! Transmitted to Nielsen? !! Sent to Provider?
|-
| rowspan="8" | 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
|-
| rowspan="10" | 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
|-
| rowspan="9" | 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
|}
<blockquote>'''Note''': Data is hashed, and encrypted using AES 128 before transmission to data provider.</blockquote>

==== Example ping sent to provider ====
* <code><nowiki>https://provider.com/cgi-bin/brandlift.php</nowiki>?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</code>

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

=== Nielsen Measurement Opt-Out ===
In accordance with Nielsen’s SDK licensing agreement, developers are required to provide basic informational data to users about Nielsen’s Privacy Policy with a navigation to additional information on Nielsen measurement.

Nielsen currently uses Limit Ad Tracking for the latest versions of the SDK (5.1.1.17 and above). However, for older SDK versions, the app must provide a means for the user to opt out, or opt back in to Nielsen Measurement. Users can opt out of Nielsen online measurement research through this feature.
* If the user has this app running on more than one mobile device, the user will need to opt out of this measurement on each device.
<blockquote>'''Note''': Opt Out feature does NOT rely on "Limit Ad Tracking" setting since Nielsen’s systems provide measurement metrics and do not serve ads to users.</blockquote>

In the Description of the app in App Store, include a short description about Nielsen measurement, as below.

<blockquote>'''Sample App Store Disclosure'''
This app features Nielsen proprietary measurement software which will allow you to contribute to market research, like Nielsen’s TV Ratings.

To learn more about our digital measurement products and your choices in regard to them, please visit http://www.nielsen.com/digitalprivacy for more information.

[[File:measurement-samplescreen.jpg]]</blockquote>

Both iOS-based and TVOS-based player applications need to confirm to Nielsen Privacy Requirements. Refer to the Opt-Out implementation guidelines for iOS and TVOS platforms respectively for more details.

=== Opt-Out Implementation ===
==== Limit Ad Tracking ====
'''This implementation is valid for SDK Versions 5.1.1.17 and above.'''

<blockquote>'''Note''': If using SDK Version 1.2.3, 4.0.0.8, 5.1.0 or 5.1.1.12, refer to Opt-Out Implementation for iOS.</blockquote>

As a global information and measurement leader, Nielsen is committed to protect the privacy and security of the data they collect, process and use. Nielsen strongly believes that the consumer should have a way to opt out of Nielsen measurement.

The Nielsen digital measurement products help Nielsen and its clients to measure and analyze how consumers engage with media across online, mobile and emerging technologies while offering insights into consumer behavior.

To learn more about our digital measurement products and your choices in regard to them, please visit http://www.nielsen.com/digitalprivacy.

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 optOutURL and opened in ‘WebView’ / External browser.
* 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 optOutStatus method.
'''Displaying Opt-Out in a WebView'''
<syntaxhighlight lang="objective-c">NielsenAppApi nAppApiObject;
@property(strong) UIWebView *optOutView;
// create WebView and set self as delegate
self.optOutView=[[UIWebView alloc]initWithFrame:self.view.bounds];
self.optOutView.scalesPageToFit = yes;
// get Nielsen defined web address and load the page
NSString *webAddress = [nAppApiObject optOutURLString];
If(webAddress == nil)
{
// Handle it gracefully and retry later
}

else
{
[optOutView loadRequest:[NSURLRequest requestWithURL:webAddress]];
// show the view to the user
[self.view addSubview:optOutView];
}</syntaxhighlight>

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.

[[File:Opt-Out_iOS.jpg]]
<blockquote>'''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.</blockquote>

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.

[[File: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.
<syntaxhighlight lang="objective-c">@property (readonly) BOOL optOutStatus;</blockquote>
* App should provide a UI control like ‘close’ or ‘back’ button to close the ‘WebView’ / External browser.

'''Sequence Diagram'''
[[File:optoutsequence-ios.jpg]]

== Event and Error Handling ==
=== Constants / Enumerations ===
The following are the details of Delegate Implementation:

<syntaxhighlight lang="objective-c">
-(void)nielsenAppApi:(NielsenAppApi *)appApi eventOccurred:(NSDictionary *)event
{
NSLog(@"Sample player is Notified by a Event: %@", event);
}
– (void)nielsenAppApi:(NielsenAppApi *)appApi errorOccurred:(NSDictionary *)error
{
NSLog(@"Sample player is Notified by an Error: %@", error);
}
</syntaxhighlight>

==== TVOS Implementation ====
As a global information and measurement leader, Nielsen is committed to protect the privacy and security of the data they collect, process and use. Nielsen strongly believes that the client should have a way to Opt-Out of Nielsen measurement.

The Nielsen digital measurement products are not used to identify consumer in any way. They help Nielsen and its clients to measure and analyze how consumers engage with media across online, mobile and emerging technologies while offering insights into consumer behavior.

To learn more about our digital measurement products and your choices in regard to them, please visit http://www.nielsen.com/digitalprivacy.

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.

[[File:TVOs_OptOut_LimitAdTracking1.png]]

[[File:TVOs_OptOut_LimitAdTracking2.png]]

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.

<blockquote>'''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.</blockquote>

==== Legacy Opt-Out ====
'''Supported SDK Versions''': 1.2.3, 4.0.0.8, 5.1.0, 5.1.1.12.

<blockquote>'''Note''': If using SDK Version 5.1.1.17 or above, refer to Opt-Out Implementation (Limit Ad Tracking).</blockquote>

As a global information and measurement leader, Nielsen is committed to protect the privacy and security of the data they collect, process and use. Nielsen strongly believes that the consumer should have a way to Opt-Out of Nielsen measurement.

The Nielsen digital measurement products help Nielsen and its clients to measure and analyze how consumers engage with media across online, mobile and emerging technologies while offering insights into consumer behavior.

To learn more about our digital measurement products and your choices in regard to them, please visit http://www.nielsen.com/digitalprivacy.

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 [[optOutURL]] and opened in ‘WebView’ within the app and NOT in any external browser.
** Opening the Opt-Out page in any external browser takes the application control out of the Nielsen App SDK context.
** As the App SDK does not expose any direct http/https interface to interact with the world to get the user selection on Privacy page, there will be no way to interact/send notification to the App SDK regarding the user selection.
* 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 [[optOutStatus]] method.
<blockquote>'''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.</blockquote>

'''Sequence Diagram'''
[[File:optoutsequence-ios.jpg]]

Below are the steps to implement user Opt-Out using UIWebView.

When a user clicks the Opt-Out / Opt-In link, the application should invoke [[optOutURL]] to get the link to the Nielsen Privacy page from SDK.

'''Implement WebView with Nielsen Opt-Out URL'''
<syntaxhighlight lang="objective-c">NielsenAppApi nAppApiObject;
@property(strong) UIWebView *optOutView;

// create WebView and set self as delegate
self.optOutView=[[UIWebViewalloc]initWithFrame:self.view.bounds];

self.optOutView.scalesPageToFit = yes;
// get Nielsen defined web address and load the page
NSString *webAddress = [nAppApiObject optOutURLString];

if(webAddress == nil)
{ // Handle it gracefully and retry later}
else
{
[optOutView loadRequest:[NSURLRequest requestWithURL:webAddress]];
// show the view to the user
[self.view addSubview:optOutView];
}</syntaxhighlight>

* The Nielsen Privacy Page appears using UIWebView

'''Privacy Page'''

[[File:privacy-policy.jpg]]

* There are two links – one for Opt-Out and one for Opt-In. Click the required link.
* Click OK in the dialog that appears, to confirm the action.
* The Opt-Out occurs by opening a Nielsen-defined web page and passing the user choice from the ‘WebView’. In order to do this, the application needs to
** Implement the UIWebView delegate method to open the Nielsen Privacy web page
** Capture user’s selection
** Pass the selection back to the SDK via the [[userOptOut]].

'''Capture and forward user selection'''
<syntaxhighlight lang="objective-c">-(BOOL)webView:(UIWebView *)webView shouldStartLoadWithRequest:(NSURLRequest *)request navigationType:(UIWebViewNavigationType)navigationType
{
NSString *command = [NSString stringWithFormat:@”%@”,request.URL];
if ([command isEqualToString:kNielsenWebClose]) {
// Close the WebView
[self performSelector:@selector(closeOptOutView) withObject:nil afterDelay:0];
return NO;
}
// Retrieve next URL if it’s not opt-in/out selection
return (![nAppApiObject userOptOut:command]);
}</syntaxhighlight>
* The app gets the user selection string via webviews shouldStartLoadWithRequest and invokes [[userOptOut]] with user selection. The delegate method handles the ‘WebView’ URL requests, interprets the commands, and calls the SDK accordingly.
* <code>[nAppApiObject userOptOut:command]</code> passes the user’s selection on Nielsen Privacy page to the SDK to allow the SDK to perform the required functions.
<blockquote>'''Note''': When ‘WebView’ is closed, pass the status returned from ‘WebView’ to the SDK within the app.</blockquote>

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

=== AppApiEventCode ===
An enumeration with predefined App SDK event state transition codes.
<syntaxhighlight lang="objective-c">
typedef NS_ENUM(unsigned int, AppApiEventCode)
{
AppApiStartup = 2001,
AppApiShutdown = 2002,
}AppApiEventCode;
</syntaxhighlight>

=== App SDK Event Codes ===
{| class="wikitable"
|-
! 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 ===
An enumeration with predefined error codes which the App SDK object can generate.
<syntaxhighlight lang="objective-c">
typedef NS_ENUM(unsigned int, AppApiErrorCode)
{
AppApiNetworkConnectionFailure = 1001,
AppApiFileWriteFailure = 1002,
AppApiFileReadFailure = 1003,
AppApiEmptyValue = 1004,
AppApiEmptyAppName = 1005,
AppApiEmptyAppVersion = 1006,
AppApiEmptyAppId = 1007,
AppApiAnExceptionOccured = 1008,
AppApiUnknownExceptionOccured = 1009
};
</syntaxhighlight>

=== App SDK Error Codes ===
{| class="wikitable"
|-
! Event Code !! Event Name !! Event 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
|}

iOS SDK API Reference

2017-07-11T21:16:41Z

Admin2: /* Opt-Out Implementation */

{{Breadcrumb|}} {{Breadcrumb|Digital}} {{CurrentBreadcrumb}}
[[Category:Digital]]
The iOS 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. These SDKs leverage the following:
*Nielsen audio watermark technologies for TV audience measurement
*The industry supported ID3 metadata tag specification
*Nielsen Combined Beacon technology
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
*Application crash events
*Time of viewing a sub section / page in the application.

== Importing Frameworks ==
'''Setting up your Xcode Development Environment'''

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

SDK uses the NSURLSession available from iOS 7 instead of the deprecated NSURLConnection.

<blockquote>'''Note''': App SDK supports devices running on iOS 9 and above, as all communications between the SDK and the Census (Collection Facility) use HTTPS.</blockquote>

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 (Not applicable for International (Germany))
* 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

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

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

== Initialization ==
The latest version of App SDK allows instantiating multiple instances of App SDK object and can be used simultaneously without any issues (The sharedInstance API that creates a singleton object in previous versions of App SDK is removed).
*Maximum of four SDK instances per appid are supported in this release. When a fifth SDK instance is launched,
**SDK will return “nil” from [[initWithAppInfo:delegate:]]
**Destroy one or more old SDK instances before creating new ones.

=== Stages of SDK Initialization ===
==== Step 1: App SDK Initialization ====
Initialize the Nielsen App object within the viewDidLoad view controller delegate method using initWithAppInfo:delegate:
<blockquote>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.</blockquote>

==== Step 2: Setting up event and error notifications ====
Once the <code>NielsenAppApi</code> object has been initialized, the next step is to enable notifications regarding ID3 tags extracted from the playing stream. In case of standard AVFoundation player, the SDK NSNotificationCenter API is used to
* Collect HLS timed metadata events (ID3 tags) during viewing sessions.
** Set up a timed metadata event listener method for receiving ID3 tags and calling Nielsen [[sendID3]].
* SDK uses the following NielsenAppApiDelegate protocol methods to notify its delegate (set during initialization) about event / error information.
** nielsenAppApi:eventOccurred
** nielsenAppApi:errorOccurred
<blockquote>'''Note''': Ensure to add to your view controller’s <code>@interface</code>.</blockquote>

<syntaxhighlight lang="objective-c">(void)nielsenAppApi:(NielsenAppApi *)appApi eventOccurred:(NSDictionary *)event {NSLog(@"Sample player is Notified by a Event : %@", event);
}
(void)nielsenAppApi:(NielsenAppApi *)appApi errorOccurred:(NSDictionary *)error {NSLog(@"Sample player is Notified by an Error : %@", error);
}</syntaxhighlight>

===== Sample event confirmation to player application upon successful initialization of SDK =====
<syntaxhighlight lang="console">NielsenSDKSampleDebug[9028:237989] [Nls:0] -I- Analytics framework Status:
{
"Event Description" = "Nielsen App SDK Version, ai.4.0.0.4 is initialized by the Player…";
EventStatus = 2001;
TimeStamp = "2015-07-23 14:51:06 +0000";
}</syntaxhighlight>

==== Step 3: Nielsen App SDK Streaming Sessions ====
After setting up observers for SDK events/errors and a listener method to process incoming Nielsen ID3 tags, the next steps are to
* Call [[play]] while starting or resuming a streaming session.
* Load CMS metadata using [[loadMetadata]].
* During session play, call [[playheadPosition]] every one second until the stream is stopped or interrupted (due to ad breaks or buffering).
* Call [[stop]] when pausing, ending a viewing session, or buffering is detected.

'''Serialized JSON string from NSDictionary'''
<syntaxhighlight lang="objective-c">NSDictionary* appInformation = @
{
@"appid": @"TXXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX",
@"appname": @"Sample App Name",
@"appversion": @"2.0",
@"sfcode": @"uat-cert",
@"nol_devDebug": @"INFO"
}
NSData* jsonDataAppInfo = [NSJSONSerialization dataWithJSONObject:appInformation options:0 error:nil];
NSString *jsonAppInfoString = [[NSString alloc] initWithData:jsonDataAppInfo encoding:NSUTF8StringEncoding];
nlsAppApiMeter = [[NielsenAppApi alloc] initWithAppInfo:jsonAppInfoString delegate:self];</syntaxhighlight>

Nielsen App SDK object handles filtering of ID3 tags and CMS tags, queuing/buffering of data, and all communications with Nielsen collection facility.

===== Nielsen iOS App SDK Application Life Cycle =====

[[File:initialization_appcycle.png|center|link=]]

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 '''Initial state'''.
# '''Idle state''' – The SDK is initialized and is ready to process playing information. Call <code>[[initWithAppInfo:delegate:]]</code> to move into this state. The SDK instance is not processing any data, but is listening for the play event to occur.
# '''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.
## [[playheadPosition]] – Call this API every one second when playhead position timer is fired.
## [[sendID3]] – Call this API when ID3 tags are identified in the stream.
## [[stop]] – Call this API when the playback is paused, switches between content and ad (within the same content playback) or encounters interruptions.
## [[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. SDK instance moves into this state in one of the following scenarios.
## Initialization fails
## [[appDisableApi]] is called
<blockquote>'''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 [[sendID3]] / [[playheadPosition]].</blockquote>

=== 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.
{| class="wikitable"
|-
! API call received !! Initial State !! Idle State !! Processing State !! Disabled State
|-
| <code>[[initWithAppInfo:delegate:]]</code> || IDLE STATE (OR)

DISABLED STATE
|| IDLE STATE || - || -
|-
| <code>[[play]]</code> & <code>[[loadMetadata]]</code>|| - || PROCESSING

STATE
|| - || -
|-
| <code>[[playheadPosition]]</code> || - || - || PROCESSING

STATE
|| -
|-
| <code>[[sendID3]]</code> || - || - || PROCESSING

STATE
|| -
|-
| <code>[[stop]]</code> || - || - || IDLE STATE || -
|-
| <code>[[end]]</code> || - || - || IDLE STATE || -
|-
| <code>[[appDisableApi]]</code>: YES || - || DISABLED

STATE
|| - || -
|-
| <code>[[appDisableApi]]</code>: NO || - || - || - || IDLE STATE (OR)

DISABLED STATE
|-
| <code>[[userOptOut]]</code>: YES || - || - || IDLE STATE || -
|-
| <code>[[userOptOut]]</code>: NO || - || PROCESSING

STATE
| -
| -
|-
| colspan = 5 | '-' 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.

==== JSON for NSDictionary object ====
<syntaxhighlight lang="objective-c">
NSDictionary* appInformation = @{
@"appid": @"TXXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX",
@"appname": @"Sample App Name",
@"appversion": @"2.0",
@"sfcode": @"uat-cert",
@"nol_devDebug": @"INFO"
};
nlsAppApiMeter = [[NielsenAppApi alloc] initWithAppInfo:appInformation delegate:delegate];</syntaxhighlight>

<code>appid</code>, <code>appname</code>, and <code>appversion</code> are mandatory parameters while <code>sfcode</code> is optional. <code>nol_devDebug</code> is meant for creating logs in test environments only.

==== JSON string from raw NSString ====
<syntaxhighlight lang="swift">NSString *appInfoString = @"{\"appid\" : \"TXXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX\", \"appname\" : \"Sample App Name\",\"appversion\" : \"2.0\",\"sfcode\" : \"uat-cert\"}";
NielsenAppAPi *appAPI = [[NielsenAppApi alloc] initWithAppInfo:appInfoString delegate:self];</syntaxhighlight>

==== JSON string from serialized NSDictionary ====
<syntaxhighlight lang="objective-c">NSDictionary* appInformation = @
{
@"appid": @"appid",
@"appname": @"appname",
@"appversion": @"2.0",
@"sfcode": @"sfcode",
@"nol_devDebug": @"INFO"
};
nlsAppApiMeter = [[NielsenAppApi alloc] initWithAppInfo:appInformation delegate:self];</syntaxhighlight>

While using JSON format for sending metadat, ensure enough care in including [[special characters]] in the values for arguments.

==== Example ====
<syntaxhighlight lang="objective-c">{
@"type": @"radio", // To send "radio" in metadata string
@"assetid": @"WXYZ-FM'101",
@"stationType": @"3",
@"provider": @"SampleProvider" // To send "SampleProvider" in metadata string
}</syntaxhighlight>
<blockquote>'''Note''': For mandatory parameters like appid, appname, and appversion, please refer to the parameters table in <code>[[initWithAppInfo:delegate:]]</code></blockquote>

== Retrieving ID3 Tags ==
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.

=== Sample ID3 tags ===
* <code>www.nielsen.com/X100zdCIGeIlgZnkYj6UvQ==/X100zdCIGeIlgZnkYj6UvQ==/AAAB2Jz2_k74GXSzx4npHuI_JwJd3QSUpW30rDkGTcbHEzIMWleCzM-uvNOP9fzJcQMWQLJqzXMCAxParOb5sGijSV9dNM3QiBniJYGZ5GI-lL1fXTTN0IgZ4iWBmeRiPpS9AAAAAAAAAAAAAAAAAAAAAFJWFM5SVhTONNU=/00000/00000/00</code>
* <code>www.nielsen.com/X100zdCIGeIlgZnkYj6UvQ==/R8WHe7pEBeqBhu8jTeXydg==/AAICoyitYqlxT7n6aZ0oMCGheFi4CXFp46AMUPZz1lMr_M9tr3_cjee1SHqxrOiVerMDLeyn9xzocZSKwi746Re8vNOtpNCAZjYABs_J0R25IHpvOc1HS8QHGgD5TgOJeS6gX100zdCIGeIlgZnkYj6UvVJWFNhSVhTiPE0=/00000/46016/00</code>

=== Examples of extracting ID3 tags from the iOS Native Player ===
==== AVPlayer ====
ID3 tags will be received in the Player on AVMetadataItem Callback method.
'''Create & get the AVMetadataItem callback method'''
<syntaxhighlight lang="swift">[self.player addObserver:self
forKeyPath: kTimedMetadataKey
options: NSKeyValueObservingOptionNew
Context: MyStreamingMovieViewControllerTimedMetadataObserverContext];</syntaxhighlight>

<syntaxhighlight lang="objective-c">
– (void)observeValueForKeyPath:(NSString*) path
ofObject: (id)object
change: (NSDictionary*)change
context: (void*)context
{
/* Set the AVPlayerLayer on the view to allow the AVPlayer object to display
its content. */
//[playerLayerView.playerLayer setPlayer:player];
/* AVPlayerItem "status" property value observer. */
if (context == MyStreamingMovieViewControllerTimedMetadataObserverContext)
{
id newMetadataArray = [change objectForKey:NSKeyValueChangeNewKey];
if (newMetadataArray != [NSNull null])
{
array = newMetadataArray;
for (AVMetadataItem *metadataItem in array)
{
[self handleTimedMetadata: metadataItem];
}
}
}
</syntaxhighlight>

<syntaxhighlight lang="objective-c">
– (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;
}
if ([(NSString *)[timedMetadata key] isEqualToString:@"PRIV"]&&[extraString rangeOfString:@"www.nielsen.com"].length> 0)
{
if ([[timedMetadata value] isKindOfClass:[NSData class]])
{
// Sending ID3 Tag
/* The sendID3: sends the extracted Nielsen ID3 payload to the App SDK for analysis. */
[[NielsenAppApi sharedInstance]sendID3: extraString];
NSString *value=[timedMetadata stringValue];
if (value != nil)
{
// NSString *strMessage=[[@"ID3 Tag Received " stringByAppendingFormat:@"%d\n",countForMetadata] stringByAppendingString:value];
[self appendLogConsoleText:extraString];
}
}
}
else
{
NSLog(@"Could not send ID3 tags");
}
countForMetadata++;

}
</syntaxhighlight>

==== Movie Player ====
ID3 tags will be received in the Player on MPTimedMetadata Callback method.
'''Sample Implementation of MPTimedMetadata callback'''
<syntaxhighlight lang="objective-c">
– (void)handleTimedMetadata:(MPTimedMetadata*)timedMetadata
{
id extraAttributeType = [timedMetadata allMetadata];
NSString * extraString= nil;
if ([extraAttributeType isKindOfClass:[NSDictionary class]])
{
extraString = [extraAttributeType valueForKey:@"info"];
}
else if([extraAttributeType isKindOfClass:[NSString class]])
{
extraString = extraAttributeType;
}

if ([(NSString *)[timedMetadata key] isEqualToString:@"PRIV"]&&[extraString rangeOfString:@"www.nielsen.com"].length> 0)
{
if ([[timedMetadata value] isKindOfClass:[NSData class]])
{
// Sending ID3 Tag
[[NielsenAppApi sharedInstance]sendID3: extraString];
NSString *value=[timedMetadata value];
if (value != nil)
{

[self appendLogConsoleText:extraString];
}
}
}
else
{
NSLog(@"Could not send ID3 tags");
}
countForMetadata++;
}
</syntaxhighlight>
<blockquote>'''Note:''' ID3 tags are not applicable for International (Germany)</blockquote>

== IOS SDK API Methods & Properties ==
{| class="wikitable sortable"
|-
! Scenario !! Method / Property !! DTVR !! DAR !! Digital Audio !! 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 || [[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.
|-
| 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)
|}

== 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 to this web page should be called from SDK by invoking [[optOutURL]] and opened in 'WebView' / External browser.
*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 [[optOutStatus]] method.

=== Displaying Opt-Out in a WebView ===
<syntaxhighlight lang="objective-c">
NielsenAppApi nAppApiObject;
@property(strong) UIWebView *optOutView;
// create WebView and set self as delegate
self.optOutView=[[UIWebView alloc]initWithFrame:self.view.bounds];
self.optOutView.scalesPageToFit = yes;
// get Nielsen defined web address and load the page
NSString *webAddress = [nAppApiObject optOutURLString];
If(webAddress == nil)
{ // Handle it gracefully and retry later} else
{[optOutView loadRequest:[NSURLRequest requestWithURL:webAddress]];
// show the view to the user
[self.view addSubview:optOutView]; }
</syntaxhighlight>

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.

[[File:Privacy policy iOS.jpg|link=]]

*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.
<syntaxhighlight lang="objective-c">
@property (readonly) BOOL optOutStatus;
</syntaxhighlight>
*App should provide a UI control like 'close' or 'back' button to close the 'WebView' / External browser.

=== Sequence Diagram ===
[[File:optoutsequence-ios.jpg|link=]]

== Opt-out SDK Version '''5.1.1.17 or above''' ==
<blockquote>'''Note:''' If using SDK Versions 1.2.3, 4.0.0.8, 5.1.0, 5.1.1.12, skip ahead to: [[#Opt-out SDK Version 1.2.3, 4.0.0.8, 5.1.0, 5.1.1.12|Opt-out SDK Version 1.2.3, 4.0.0.8, 5.1.0, 5.1.1.12]]</blockquote>

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.

[[File:Opt-Out iOS.jpg|link=]]

<blockquote>'''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.</blockquote>

== Opt-out SDK Version '''1.2.3, 4.0.0.8, 5.1.0, 5.1.1.12''' ==
<blockquote>'''Note:''' If using SDK Version 5.1.1.17 or above, refer to documentation above ([[#Opt-out SDK Version 5.1.1.17 or above|Opt-out SDK Version 5.1.1.17 or above]])</blockquote>

When a user clicks the Opt-Out / Opt-In link, the application should invoke [[optOutURL]] to get the link to the Nielsen Privacy page from SDK.
=== Privacy Page ===
[[File:privacy-policy.jpg|link=]]
*There are two click here links – one for Opt-Out and one for Opt-In. Click the required link:
**
[[File:Opt-Out Combined.jpg|link=]]
*Click OK in the dialog that appears, to confirm the action.
*The Opt-Out occurs by opening a Nielsen-defined web page and passing the user choice from the 'WebView'. In order to do this, the application needs to
**Implement the UIWebView delegate method to open the Nielsen Privacy web page
**Capture user's selection
**Pass the selection back to the SDK via the [[userOptOut]].

=== Capture and forward user selection ===
<syntaxhighlight lang="objective-c">
-(BOOL)webView:(UIWebView *)webView
shouldStartLoadWithRequest:(NSURLRequest *)request
navigationType:(UIWebViewNavigationType)navigationType
{
NSString *command = [NSString stringWithFormat:@"%@",
request.URL];
if ([command isEqualToString:kNielsenWebClose]) {
// Close the WebView
[self performSelector:@selector(closeOptOutView)
withObject:nil afterDelay:0];
return NO;
}
// Retrieve next URL if it's not opt-in/out selection
return (![nAppApiObject userOptOut:command]);
}
</syntaxhighlight>

*The app gets the user selection string via webviews shouldStartLoadWithRequest and invokes [[userOptOut]] with user selection. The delegate method handles the 'WebView' URL requests, interprets the commands, and calls the SDK accordingly.
**<code>[nAppApiObject userOptOut:command]</code> passes the user's selection on Nielsen Privacy page to the SDK to allow the SDK to perform the required functions.
<blockquote>'''Note:''' When 'WebView' is closed, pass the status returned from 'WebView' to the SDK within the app.</blockquote>
<blockquote>'''Note:''' App SDK manages the user's choice (Opt-Out / Opt-In), the app does not need to manage this status.</blockquote>

== 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:

[[File:TVOs OptOut LimitAdTracking1.png|link=]]

[[File:TVOs OptOut LimitAdTracking2.png|link=]]

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.

<blockquote>'''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.</blockquote>

== 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:
<syntaxhighlight lang="objective-c">
@interface NielsenAppApi: NSObject

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

– (instancetype)initWithAppInfo:(id)appInfo delegate:(id)delegate;

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

– (NSString *)getNielsenId _attribute((deprecated((“Please use nielsenId property instead.”))));
– (NSString *)optOutURLString _attribute((deprecated((“Please use optOutURL property instead.”))));
– (NSString *)getMeterVersion _attribute((deprecated((“Please use meterVersion property instead.”))));
– (NSDictionary *)getLastEventDict _attribute((deprecated((“Please use lastEventDict property instead.”))));
– (NSDictionary *)getLastErrorDict _attribute((deprecated((“Please use lastErrorDict property instead.”))));

@protocol NielsenAppApiDelegate<NSObject>

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

@end
</syntaxhighlight>

== Nielsen Sample Applications ==
Nielsen iOS sample player application consists of two sample application based on native Players integrated with SDK framework. The player demonstrates all the supported functions of the SDK.
*NielsenVideoPlayer
*NielsenRadioPlayer
Implementation of Video and Audio 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 two locations:
**Channels 1 and 2 are configured from the Settings application. Channel URLs and metadata parameters can be modified.
**Channels starting from 3 are configured in specific JSON file. URLs to this JSON config file can be changed from the Settings application.

== Nielsen Privacy Requirements ==
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.
[[File:RatingsDataFlow.png]]

'''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 ===
{| class="wikitable"
|-
! Type of Information !! Parameter !! Transmitted to Nielsen? !! Sent to Provider?
|-
| rowspan="8" | 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
|-
| rowspan="10" | 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
|-
| rowspan="9" | 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
|}
<blockquote>'''Note''': Data is hashed, and encrypted using AES 128 before transmission to data provider.</blockquote>

==== Example ping sent to provider ====
* <code><nowiki>https://provider.com/cgi-bin/brandlift.php</nowiki>?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</code>

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

=== Nielsen Measurement Opt-Out ===
In accordance with Nielsen’s SDK licensing agreement, developers are required to provide basic informational data to users about Nielsen’s Privacy Policy with a navigation to additional information on Nielsen measurement.

Nielsen currently uses Limit Ad Tracking for the latest versions of the SDK (5.1.1.17 and above). However, for older SDK versions, the app must provide a means for the user to opt out, or opt back in to Nielsen Measurement. Users can opt out of Nielsen online measurement research through this feature.
* If the user has this app running on more than one mobile device, the user will need to opt out of this measurement on each device.
<blockquote>'''Note''': Opt Out feature does NOT rely on "Limit Ad Tracking" setting since Nielsen’s systems provide measurement metrics and do not serve ads to users.</blockquote>

In the Description of the app in App Store, include a short description about Nielsen measurement, as below.

<blockquote>'''Sample App Store Disclosure'''
This app features Nielsen proprietary measurement software which will allow you to contribute to market research, like Nielsen’s TV Ratings.

To learn more about our digital measurement products and your choices in regard to them, please visit http://www.nielsen.com/digitalprivacy for more information.

[[File:measurement-samplescreen.jpg]]</blockquote>

Both iOS-based and TVOS-based player applications need to confirm to Nielsen Privacy Requirements. Refer to the Opt-Out implementation guidelines for iOS and TVOS platforms respectively for more details.

=== Opt-Out Implementation ===
==== Limit Ad Tracking ====
'''This implementation is valid for SDK Versions 5.1.1.17 and above.'''

<blockquote>'''Note''': If using SDK Version 1.2.3, 4.0.0.8, 5.1.0 or 5.1.1.12, refer to Opt-Out Implementation for iOS.</blockquote>

As a global information and measurement leader, Nielsen is committed to protect the privacy and security of the data they collect, process and use. Nielsen strongly believes that the consumer should have a way to opt out of Nielsen measurement.

The Nielsen digital measurement products help Nielsen and its clients to measure and analyze how consumers engage with media across online, mobile and emerging technologies while offering insights into consumer behavior.

To learn more about our digital measurement products and your choices in regard to them, please visit http://www.nielsen.com/digitalprivacy.

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 optOutURL and opened in ‘WebView’ / External browser.
* 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 optOutStatus method.
'''Displaying Opt-Out in a WebView'''
<syntaxhighlight lang="objective-c">NielsenAppApi nAppApiObject;
@property(strong) UIWebView *optOutView;
// create WebView and set self as delegate
self.optOutView=[[UIWebView alloc]initWithFrame:self.view.bounds];
self.optOutView.scalesPageToFit = yes;
// get Nielsen defined web address and load the page
NSString *webAddress = [nAppApiObject optOutURLString];
If(webAddress == nil)
{
// Handle it gracefully and retry later
}

else
{
[optOutView loadRequest:[NSURLRequest requestWithURL:webAddress]];
// show the view to the user
[self.view addSubview:optOutView];
}</syntaxhighlight>

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.

[[File:Opt-Out_iOS.jpg]]
<blockquote>'''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.</blockquote>

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.

[[File: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.
<syntaxhighlight lang="objective-c">@property (readonly) BOOL optOutStatus;</blockquote>
* App should provide a UI control like ‘close’ or ‘back’ button to close the ‘WebView’ / External browser.

'''Sequence Diagram'''
[[File:optoutsequence-ios.jpg]]

== Event and Error Handling ==
=== Constants / Enumerations ===
The following are the details of Delegate Implementation:

<syntaxhighlight lang="objective-c">
-(void)nielsenAppApi:(NielsenAppApi *)appApi eventOccurred:(NSDictionary *)event
{
NSLog(@"Sample player is Notified by a Event: %@", event);
}
– (void)nielsenAppApi:(NielsenAppApi *)appApi errorOccurred:(NSDictionary *)error
{
NSLog(@"Sample player is Notified by an Error: %@", error);
}
</syntaxhighlight>

=== AppApiEventCode ===
An enumeration with predefined App SDK event state transition codes.
<syntaxhighlight lang="objective-c">
typedef NS_ENUM(unsigned int, AppApiEventCode)
{
AppApiStartup = 2001,
AppApiShutdown = 2002,
}AppApiEventCode;
</syntaxhighlight>

=== App SDK Event Codes ===
{| class="wikitable"
|-
! 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 ===
An enumeration with predefined error codes which the App SDK object can generate.
<syntaxhighlight lang="objective-c">
typedef NS_ENUM(unsigned int, AppApiErrorCode)
{
AppApiNetworkConnectionFailure = 1001,
AppApiFileWriteFailure = 1002,
AppApiFileReadFailure = 1003,
AppApiEmptyValue = 1004,
AppApiEmptyAppName = 1005,
AppApiEmptyAppVersion = 1006,
AppApiEmptyAppId = 1007,
AppApiAnExceptionOccured = 1008,
AppApiUnknownExceptionOccured = 1009
};
</syntaxhighlight>

=== App SDK Error Codes ===
{| class="wikitable"
|-
! Event Code !! Event Name !! Event 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
|}