Engineering Client Portal - User contributions [en]

TV

2024-01-31T21:18:58Z

NickParrucci:

[[Category:TV]]
{{Banner|Encoder Support}}




{{Alert|
'''Nielsen Encoder Installation and Configuration Policy 2022 Now Available:'''<br>
'''Official release notification: [https://nielsendownloads.digitalengsdk.com/tv/Encoding/Encoder+Policy+2022+-+04-01-22.pdf Nielsen Encoder Installation and Configuration Policy 2022]

}}

{| class="wikitable"
|-
! style="width: 50px;" |
! Certified Vendors
|-
| rowspan="1" |
| '''[[Nielsen Encoder Certified Vendors]]'''
|-
| rowspan="1" |
| '''[[Nielsen Decoder Certified Vendors]]'''
|-
| rowspan="1" |
| '''[[PCM-to-ID3 Certified Vendors]]'''
|-
|}

{| class="wikitable"
|-
! style="width: 50px;" |
! Reference & Policy Supplements
|-
| rowspan="1" | {{SmallIcon|PDFIcon.png}}
| '''[https://nielsendownloads.digitalengsdk.com/tv/Encoding/Encoder+Policy+2022+-+04-01-22.pdf Nielsen Encoder Installation and Configuration Policy 2022]'''
|-
| rowspan="1" | {{SmallIcon|PDFIcon.png}}
| '''[https://nielsendownloads-blue.digitalengsdk.com/tv/Encoding/Internet_Distribution_Policy_Rev_A.pdf Internet Distribution Policy]'''
|-
| rowspan="1" | {{SmallIcon|PDFIcon.png}}
| '''[https://nielsendownloads.digitalengsdk.com/tv/Encoding/Nielsen+Encoder+Solutions+2023.pdf Nielsen Encoder Solutions 2023]'''
|-
| rowspan="1" | {{SmallIcon|PDFIcon.png}}
| '''[https://nielsendownloads-blue.digitalengsdk.com/tv/Encoding/MVPD%20provided%20Direct%20Feeds%20with%20Unique%20Commercial%20Content.pdf MVPD provided Direct Feeds with Unique Commercial Content]'''
|-
| rowspan="1" | {{SmallIcon|PDFIcon.png}}
| '''[https://nielsendownloads-blue.digitalengsdk.com/tv/Encoder%20Alert%20Distribution%20List%20Instructions_Final.pdf Nielsen Encoder Alert Distribution List - Instructions]'''
|}

{{CategoryIcon|EncodingIcon.png|TV Audio Encoding}}
{| class="wikitable"
|-
! style="width: 75px;" |
! style="width: 35%;" | Software
! style="width: 45px;" | OS
! Download
|-
| {{SmallIcon|CircuitIcon.png}}
| '''[[NWE-3GA]]''' || {{OSIcon|WindowsIcon.png}} ||
{{TVDownloadRequestLink|name=NWE-3GA NWE-3G Software package Rev 2.3.0.9 (New)|dlid=73aeefb5972bb1f556aa5093c14b981d223bec8e}}
{{TVDownloadRequestLink|name=NWE-3GA NWE-3G Software package Rev.2.2.0.1|dlid=53fa2674bebc1a010c50b747ff969a61e4094b43}}

|-

| {{SmallIcon|RackIcon.png}}
| '''[[NWE-TS]]'''
|| {{OSIcon|FirmwareIcon.png}} ||
{{TVDownloadRequestLink|name=NWE-TS Firmware 4.6.10|dlid=31e04631784a2438fc41c81f34a49c33cd513ec6}} <small>''('''New!''' - June 17th, 2019)''</small>
{{TVDownloadRequestLink|name=NWE-TS Firmware 4.5.1|dlid=5126ebc2699eda28002ba6e2e84fb8a1031827f5}}

|-

| {{SmallIcon|RackIcon.png}}
| '''[[Multi-Channel Encoder]]'''
|| {{OSIcon|FirmwareIcon.png}} ||
*[[Encoder Downloads| Multi-Channel Encoder v1.2.4]]

|-

| {{SmallIcon|VODIcon.png}}
| '''[[VOD Content Encoder]]'''
|| {{OSIcon|WindowsIcon.png}} ||
*[[Encoder Downloads| VOD Content Encoder]]

|-

| {{SmallIcon|VODIcon.png}}
| '''[[VOD in TV Ratings]]''' ''<small>(formerly RTVOD)</small>''
|| {{OSIcon|WindowsIcon.png}} ||
*[[Encoder Downloads| VOD in TV Ratings]] ''<small>(formerly RTVOD)</small>''

|-

| {{SmallIcon|ComputerWaveIcon.png}}
| '''[[SpoTTrac®]]'''
|| {{OSIcon|FirmwareIcon.png}} ||
*[[Encoder Downloads| SpoTTrac Firmware]]

|-

| {{SmallIcon|EncoderGrayIcon.png}}
| '''[[NAVE II]]'''
|| {{OSIcon|WindowsIcon.png}} ||
*NAVE II Firmware v38
*NAVE II Manager
|-

| {{SmallIcon|EncoderGrayIcon.png}}
| '''[[NAVE IIC]]'''
|| {{OSIcon|WindowsIcon.png}} ||
*NAVE IIC Firmware v3.4.15
|}

{{CategoryIcon|ID3Icon.png|ID3 Transcoding}}
{| class="wikitable"
|-
! style="width: 75px;" |
! style="width: 35%;" | Software
! style="width: 45px;" | OS
! Download

|-

|rowspan="3"| {{SmallIcon|ID3XcodeIcon.png}}
|rowspan="3"| '''[[ID3 Transcoders]]'''
''<small>(Click for Documentation, Software Updates, and Test Streams)</small>''
|| {{OSIcon|WindowsIcon.png}} ||
{{TVDownloadRequestLink|name=PCM-to-ID3 SDK (Windows) v2.3.2|dlid=ac5b0e72a84b1a6e86da1a8fe0a89e24083468eb}}
{{TVDownloadRequestLink|name=PCM-to-ID3 SDK (Windows Visual Studio 2013) v2.3|dlid=533cee44e69c6859e56acd9cbb38334d6b215c00}}
|-
|| {{OSIcon|LinuxIcon.png}} ||
{{TVDownloadRequestLink|name=PCM-to-ID3 SDK (Linux x64 GLIBC 2.12) v2.3.2|dlid=c499535f6ce9a0326a408b167079e01a0596e141}}
{{TVDownloadRequestLink|name=PCM-to-ID3 SDK (Linux x64 GLIBC 2.17) v2.3.2|dlid=b353e404994a1d26726b196960efe40c30427571}}
{{TVDownloadRequestLink|name=PCM-to-ID3 SDK (Linux x86 GLIBC 2.17) v2.3.2|dlid=f82dfbde6f5f68ccf677b63e32fc83e68fa82cd6}}
|-
|| {{OSIcon|macOSIcon.png}} ||
{{TVDownloadRequestLink|name=PCM-to-ID3 SDK (MacOS) v2.3|dlid=3a9d04be165f39ac956278c8292cd1b87ce34b62}}

|-
|rowspan="1"| {{SmallIcon|ID3DashIcon.png}}
|rowspan="1"| '''[[ID3 in MPEG-DASH]]'''
''<small>(Click for Documentation, and Sample Audio Files)</small>''
|| {{OSIcon|StaticIcon.png}} ||
*[https://nielsendownloads-blue.digitalengsdk.com/tv/ID3%20Transcoding/ID3%20in%20MPEG-DASH/bbb-MPEG-DASH.zip Big Buck Bunny MPEG-DASH Nielsen Tagged]
*[https://nielsendownloads-blue.digitalengsdk.com/tv/ID3%20Transcoding/ID3%20in%20MPEG-DASH/nielsenconsumer-MPEG-DASH.zip Nielsen Consumer MPEG-DASH Nielsen Tagged]
*[https://nielsendownloads-blue.digitalengsdk.com/tv/ID3%20Transcoding/ID3%20in%20MPEG-DASH/nielsenxplatform-MPEG-DASH.zip Nielsen Cross Platform MPEG-DASH Nielsen Tagged]
|-

|rowspan="3"| {{SmallIcon|ID3ValidateIcon.png}}
|rowspan="3"| '''[[PCM-to-ID3 Validator]]'''
''<small>(Click for Documentation, and Downloads)</small>''
|| {{OSIcon|WindowsIcon.png}} ||
{{TVDownloadRequestLink|name=PCM-to-ID3 Validator (Windows) v1.8|dlid=67d34c64d1ed349c1ad92ac47adf62c877f47fcb}}
|-
|| {{OSIcon|LinuxIcon.png}} ||
{{TVDownloadRequestLink|name=PCM-to-ID3 Validator (CentOS) v1.7|dlid=dd6b62c76995aa7e1702c60e02076348ceaf573b}}
|-
|| {{OSIcon|macOSIcon.png}} ||
{{TVDownloadRequestLink|name=PCM-to-ID3 Validator (MacOS) v1.7|dlid=3afc5a7ec29593e2eb47daa9746b6d16cbd785e1}}

|-

|rowspan="3"| {{SmallIcon|ID3ValidateIcon.png}}
|rowspan="3"| '''[[PCM-to-ID3 Validator SDK]]'''
''<small>(Click for Documentation, and Downloads)</small>''
|| {{OSIcon|WindowsIcon.png}} ||
{{TVDownloadRequestLink|name=PCM-to-ID3 Validator SDK (Windows) v1.8|dlid=78a936556ebc5caf57d2fc4d09de3a272ace9fea}}
|-
|| {{OSIcon|LinuxIcon.png}} ||
{{TVDownloadRequestLink|name=PCM-to-ID3 Validator SDK (CentOS) v1.7|dlid=ccb9af4ef45cfcf7aa4406ca63ab3b7c6efdad11}}
|-
|| {{OSIcon|macOSIcon.png}} ||
{{TVDownloadRequestLink|name=PCM-to-ID3 Validator SDK (MacOS) v1.7|dlid=05e99551d28ef4a65eab6168ad2872648346aab2}}
|}

{{CategoryIcon|DiagnosisToolsIcon.png|Diagnostic Tools}}
{| class="wikitable"
|-
! style="width: 75px;" |
! style="width: 35%;" | Software
! style="width: 45px;" | OS
! Download

|-

| {{SmallIcon|NACATIcon.png}}
|| '''[[Nielsen Audio Code Analysis Tool 2|Nielsen Audio Code Analysis Tool 2 (NACAT2)]]'''
|| {{OSIcon|WindowsIcon.png}} ||
{{TVDownloadRequestLink|name=NACAT2 1.4|dlid=83d58832e663a21841b32f771cc2781ae5b5b572}}

|-

| {{SmallIcon|NACATIcon.png}}
|| '''[[Nielsen Audio Code Analysis Tool|Nielsen Audio Code Analysis Tool (NACAT)]]'''
|| {{OSIcon|WindowsIcon.png}} ||
{{TVDownloadRequestLink|name=NACAT installer (Windows) v4.3|dlid=212d5eb338cf66cd20f3846347bc3c8c6b2dfbc4}}

|-

| {{SmallIcon|NDICEIcon.png}}
|| '''[[Nielsen Digital Code Extractor]]'''
|| {{OSIcon|WindowsIcon.png}} ||
{{TVDownloadRequestLink|name=Nielsen Digital Code Extractor Installer|dlid=c0eb8eb1802bd08956f6e215473ef1881274a6df}} <BR> (See special installation instructions in [[Nielsen Digital Code Extractor|guide]])

|-

|rowspan="3"| {{SmallIcon|SDKIcon.png}}
|rowspan="3"| '''[[Decoder SDK Monitor]]'''
|| {{OSIcon|WindowsIcon.png}} ||
{{TVDownloadRequestLink|name=Decoder SDK Monitor (Windows vs2017) v1.4|dlid=b3ae411765cfa2b878c3f50c0824e61d81a58fbb}}
|-
|| {{OSIcon|WindowsIcon.png}} ||
{{TVDownloadRequestLink|name=Decoder SDK Monitor (Windows vs2015) v1.4|dlid=68d1fd697862e663a7aa2efc46377f053c983a5a}}
|-
|| {{OSIcon|LinuxIcon.png}} ||
{{TVDownloadRequestLink|name=Decoder SDK Monitor (CentOS) v1.4|dlid=c978921ba90736bf7f2c82287a0a97af89109bec}}

|-

| {{SmallIcon|NDICEIcon.png}}
|| '''[[Nielsen Monitor Application]]'''
|| {{OSIcon|WindowsIcon.png}} ||
{{TVDownloadRequestLink|name=Nielsen Monitor Application (Windows) v1.4|dlid=6ddf77a8f67dff67b4cbad1fee630ee80318b5bf}}

|-

| {{SmallIcon|NDICEIcon.png}}
|| '''[[Nielsen Monitor Application]]|TEST for Nick REMOVE before prod'''
|| {{OSIcon|WindowsIcon.png}} ||
{{TVDownloadRequestLink|name=testfile|dlid=cf62886426e702be71f6e8dd25c1d7d35a920876}}

|}

Main Page

2024-01-17T16:04:53Z

NickParrucci: Reverted edits by NickParrucci (talk) to last revision by Admin

{{Banner|Engineering Portal}}

<div class="row">
<div class="small-4 large-4 columns" style="text-align: center;">{{NavigationBox|AudioIcon.png|Radio}}</div>
<div class="small-4 large-4 columns" style="text-align: center;">{{NavigationBox|EncoderIcon.png|TV}}</div>
<div class="small-4 large-4 columns" style="text-align: center;">{{NavigationBox|DigitalIcon.png|Digital}}</div>
</div>

Main Page

2024-01-17T16:04:37Z

NickParrucci:

{{Banner|Engineering Portal}}

<div class="row">
<div class="small-4 large-4 columns">{{NavigationBox|AudioIcon.png|Radio}}</div>
<div class="small-4 large-4 columns">{{NavigationBox|EncoderIcon.png|TV}}</div>
<div class="small-4 large-4 columns">{{NavigationBox|DigitalIcon.png|Digital}}</div>
</div>

Main Page

2024-01-17T16:02:17Z

NickParrucci: Reverted edits by NickParrucci (talk) to last revision by Admin

Main Page

2024-01-17T16:02:02Z

NickParrucci:

{{Banner|Engineering Portal}}

<div class="row">
<div>{{NavigationBox|AudioIcon.png|Radio}}</div>
<div>{{NavigationBox|EncoderIcon.png|TV}}</div>
<div>{{NavigationBox|DigitalIcon.png|Digital}}</div>
</div>

Template:NavigationBox

2024-01-17T15:56:46Z

NickParrucci:

[[Image:{{{icon|{{{1}}}}}}|center|200px|link={{{title|{{{2}}}}}}|{{{title|{{{2}}}}}}|class=iconImage]]
<span class="iconText">[[{{{2}}}]]</span>

Main Page

2024-01-16T14:16:38Z

NickParrucci: Reverted edits by NickParrucci (talk) to last revision by Admin

Main Page

2024-01-16T14:15:02Z

NickParrucci:

{{Banner|Engineering Portal}}

<div class="row">
<div class="small-4 large-4 columns" style="margin: auto;">{{NavigationBox|AudioIcon.png|Radio}}</div>
<div class="small-4 large-4 columns" style="margin: auto;">{{NavigationBox|EncoderIcon.png|TV}}</div>
<div class="small-4 large-4 columns" style="margin: auto;">{{NavigationBox|DigitalIcon.png|Digital}}</div>
</div>

Main Page

2024-01-16T14:12:36Z

NickParrucci: Reverted edits by NickParrucci (talk) to last revision by Admin

Main Page

2024-01-16T14:12:01Z

NickParrucci:

Template:DCR Content Metadata

2023-10-25T19:40:20Z

NickParrucci:

{| class="wikitable"
|-
! '''Keys''' !! '''Description''' !! '''Values''' !! '''Required'''!!'''Provider'''
|-
| type || Type of asset ||For Video use: <code>content</code><br> For Static or text <code>static</code> || Yes || Nielsen
|-style="background-color:#e9f9fa;"
| assetid || Unique ID assigned to asset <br> Note: Refrain from using the following special characters [[Special_Characters|(Special Characters)]]. || Examples: <br> <code>BBT345a234 </code> <br> <code>CBSs5e234F2021</code> || Yes || Client
|-
| program ||Complete program or movie title <br> (no abbreviations or shorthand) <br> Note: there is a 25 character limit. ||<code> The Big Bang Theory</code> <br> <code> TheBigBangTheory</code> <br><code> The Dark Knight</code> <br><code> TheDarkKnight</code> <br> || Yes || Client
|-style="background-color:#e9f9fa;"
| title ||Episode title with season and episode number (40 character limit) <br> (Formats accepted: S01E03, S1E3, S1 E3). || Examples: <br> <code>The Pants Alternative S03E18</code> <br> <code>The Pants Alternative S3E18</code> <br> <code>The Pants Alternative S3 E18</code> <br> Can also accept: <code> S3E18</code> <br> Not Valid: <code> 318 </code> or <code> 0318 </code>|| Yes || Client
|-
| crossId1 || Gracenote TMS ID (If available) should be passed for all telecasted content for clients using the Gracenote solution for proper matching purposes. <br>Note: The TMS ID will be a 14 character string. Normally leading with 2 alpha characerts ('EP', 'MV', 'SH' or 'SP'), followed by 12 numbers.
|| The TMS ID will be a 14 character string. <br> Normally being with 'EV,' 'EP', 'SH', 'SP', or 'MV' <br> Followed by 12 numbers after the initial two letter prefix. <br> <br> The Giant Morning Show: <code>SH009311820022</code> <br> The Pants Alternative Episode : <code>EP009311820061</code> || Optional || Nielsen
|-style="background-color:#e9f9fa;"
| crossId2 || Populated by content distributor to contribute viewing from that distributor to the given content originator. || Custom<br>For a full list of acceptable values, please contact your Nielsen reprentative. || Yes, for distributors || Nielsen
|-
| length || Length of content in seconds<br>Note: Integers and decimal values are acceptable for the length parameter. || Examples:
<small>For standard VOD content - <code>300</code> to represent 5 minutes, <code>1320</code> to represent 22 minutes, etc.
<br>If DAI live stream of a discrete program (Live Event/Sporting Event), pass length of content. See example for standard VOD content above.
<br>If unknown DAI live steam, pass a value of <code>0</code>.</small>
|| Yes || Client
|-style="background-color:#e9f9fa;"
| airdate ||Original broadcast or release date for the program <br>For USA, date should be EST <br> Outside USA, date should be local time.<br>If not applicable or available, original broadcast or release date for the Program. || Acceptable Formats:<br><code>YYYY-MM-DDTHH:MI:SS</code><br><code>YYYY-MM-DDHH:MI:SS</code><br><code>YYYY-MM-DDTHH:MI:SS+xx:xx</code><br><code>YYYY-MM-DDTHH:MI:SS-xx:xx</code><br><code>YYYYMMDDHH:MI:SS</code><br><code>YYYYMMDD HH:MI:SS</code><br><code>MM-DD-YYYY</code><br><code>MM/DD/YYYY</code><br><code>YYYYMMDD</code></big> || Yes || Client
|-
| isfullepisode || Full episode flag to identify differences between long form content. || <code>y</code>- full episode, <code>n</code>- non full episode(clip,teaser,promo,etc.)
<small>Also accept:
<br><code>lf</code> or <code>yes</code>- longform
<br><code>sf</code> or <code>no</code>- shortform
|| Yes || Nielsen
|-style="background-color:#e9f9fa;"
| adloadtype || <big><small>Type of ad load:
<code>1</code> Linear – matches TV ad load<br><code>2</code> Dynamic – Dynamic Ad Insertion (DAI)</small></big>
|| <code>2</code> - DCR measures content with dynamic ads || Yes || Nielsen
|-
| segB || One of two custom segment for the clients granular reporting within a brand. || Examples:<br>Genre - <code>horror</code>, <code>comedy</code>, etc.<br>Timeslot - <code>primetime</code>, <code>daytime</code>, etc.<br>News type - <code>breakingnews</code>, <code>weather</code>, etc. || Optional || Client
|-style="background-color:#e9f9fa;"
| segC || One of two custom segment for the clients granular reporting within a brand. || Examples:<br>Genre - <code>horror</code>, <code>comedy</code>, etc.<br>Timeslot - <code>primetime</code>, <code>daytime</code>, etc.<br>News type - <code>breakingnews</code>, <code>weather</code>, etc. || Optional || Client
|}
Custom segments (segB and segC) can be used to aggregate video and/or static content within a single Brand to receive more granular reports within a brand.

Examples regarding usage of segments within SDK:
* All comedy clips and stories for a Brand rolled into a "Comedy" segment
* genre grouping content by Comedy vs. Drama
* group related Text + Video content - i.e. for a show that has a lot of - static pages associated with it
* packaging based on how clients sell inventory
* grouping related types of content either by genre, category or platform.
<br />

File:LGwebos 2.png

2023-10-25T18:31:00Z

NickParrucci:

webos with logs

File:WEBOS 1.png

2023-10-25T18:30:04Z

NickParrucci:

webos screen

webOS

2023-10-25T18:27:32Z

NickParrucci: Created page with "{{Breadcrumb|}} {{Breadcrumb|Digital}} {{Breadcrumb|DCR & DTVR}} {{CurrentBreadcrumb}} Category:Digital __NOTOC__ == Introduction == The following document will highligh..."

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

__NOTOC__
== Introduction ==
The following document will highlight the steps needed to run Browser SDK (BSDK) on LG Smart TVs that are currently running webOS TV 23 on Chromium 94 web engine

The tutorial should be used in combination with the documentation at [https://webostv.developer.lge.com/develop/getting-started/build-your-first-web-app webOS TV Developer] to build an app and verify that the BSDK properly measures the video and static content. In the tutorial we will be using a [https://webostv.developer.lge.com/develop/getting-started/web-app-types#hosted-web-app hosted web app] which will host the content on the web server. We will also use the [https://webostv.developer.lge.com/develop/tools/simulator-introduction webOS TV Simulator] for app development.

== Step 1: Install the webOS TV CLI ==

Navigate [https://webostv.developer.lge.com/develop/tools/simulator-installation here] and install the webOS TV CLI

== Step 2: Install the webOS TV Simulator ==

Navigate [https://webostv.developer.lge.com/develop/tools/simulator-installation here] and install the webOS TV Simulator

=== Step 3: Create App ===

# We will begin creating the app by navigating [https://webostv.developer.lge.com/develop/getting-started/web-app-types#hosted-web-app here] and following the installation steps:
# Run <syntaxhighlight lang="javascript"> ares-generate -t hosted_webapp nlsn-bsdk-webOS </syntaxhighlight> to generate the app and accept all defaults
# Open the generated folder in a text editor or IDE and and create a new folder called app
# Add the following into a video.html file and make sure to update App ID with Nielsen provided App ID while creating the SDK instance

<br>

Add the following script tag to the website:
<syntaxhighlight lang="javascript">
<!DOCTYPE html>
<html lang="en">

<head>
<meta charset="UTF-8">
<meta http-equiv="X-UA-Compatible" content="IE=edge">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<title>DCR Video webOS Sample</title>
<script>
// Static Queue Snippet
!function (e, n) {
function t(e) {
return "object" == typeof e ? JSON.parse(JSON.stringify(e)) : e
}
e[n] = e[n] ||
{
nlsQ: function (o, r, c) {
var s = e.document,
a = s.createElement("script");
a.async = 1,
a.src = ("http:" === e.location.protocol ? "http:" : "https:") + "//cdn-gl.imrworldwide.com/conf/" + o + ".js#name=" + r + "&ns=" + n;
var i = s.getElementsByTagName("script")[0];
return i.parentNode.insertBefore(a, i),
e[n][r] = e[n][r] || {
g: c || {},
ggPM: function (o, c, s, a, i) { e[n][r].q = e[n][r].q || []; try { var l = t([o, c, s, a, i]); e[n][r].q.push(l) } catch (e) { console && console.log && console.log("Error: Cannot register event in Nielsen SDK queue.") } },
trackEvent: function (o) { e[n][r].te = e[n][r].te || []; try { var c = t(o); e[n][r].te.push(c) } catch (e) { console && console.log && console.log("Error: Cannot register event in Nielsen SDK queue.") } }
},
e[n][r]
}
}
}(window, "NOLBUNDLE");

// INSERT CLIENT APP ID
var nSdkInstance = NOLBUNDLE.nlsQ("PXXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX", "videoSdkInstance", {
nol_sdkDebug: "debug",
});

var contentMetadata = {
type: 'content',
assetid: 'VID-123456',
program: 'program name',
title: 'episode title with season and episode number',
length: 'length in seconds',
airdate: '20210321 09:00:00',
isfullepisode: 'y',
adloadtype: '2'
};
</script>
<style>
body {
background-color: white;
}
</style>
</head>
<body>
<h1>DCR Video webOS Sample App</h1>
<div>
<video controls src="https://archive.org/download/BigBuckBunny_124/Content/big_buck_bunny_720p_surround.mp4"
poster="https://peach.blender.org/wp-content/uploads/title_anouncement.jpg?x11217" width="620">
Sorry, your browser doesn't support embedded videos,
but don't worry, you can <a
href="https://archive.org/details/BigBuckBunny_124">download it</a>
and watch it with your favorite video player!
</video>
</div>
</main>
<script>
var media = document.querySelector('video');
var playheadPosition = 0;
var metadataLoaded = false;

// Loadmetadata
// Load contentMetadata object
media.addEventListener('loadedmetadata', (event) => {
// Call SDK loadmetadata event
if (!metadataLoaded) {
nSdkInstance.ggPM("loadmetadata", contentMetadata);
metadataLoaded = true;
}
});

media.addEventListener('play', (event) => {
// Call SDK play event
if (!metadataLoaded) {
nSdkInstance.ggPM("loadmetadata", contentMetadata);
metadataLoaded = true;
}
});

// Player paused
media.addEventListener('pause', function (e) {
nSdkInstance.ggPM("pause", playheadPosition);
});

// Set playhead position
media.addEventListener('timeupdate', function (e) {
var currTime = Math.floor(media.currentTime);
if (playheadPosition < currTime) {
playheadPosition = currTime;
nSdkInstance.ggPM("setplayheadposition", playheadPosition);
}
});

// End
media.addEventListener('ended', function (e) {
nSdkInstance.ggPM("end", playheadPosition);
metadataLoaded = false;
playheadPosition = 0;
});
</script>
</body>
</html>
</syntaxhighlight>
<br>
Click [https://gitlab.com/nielsen-media/digital/shared/sdk/browser-sdk/misc/bsdk-client-documentation/-/wikis/DCR-Video-Quick-Start here] for more information on DCR Video implementation.

3. Navigate to <syntaxhighlight lang="javascript"> index.html </syntaxhighlight> at the root of the directory and update the <syntaxhighlight lang="javascript"> location.href </syntaxhighlight> url to point to <syntaxhighlight lang="javascript"> http://{{LOCAL_SERVER_URL}}/app/video.html </syntaxhighlight>

That is all that we need to run the app on the webOS TV Simulator. Please make sure to update the App ID for SDK initialization to view proper crediting

===Step 4: Open up webOS TV Simulator===

Open up the webOS TV Simulator > navigate to File > Launch App > open the folder containing the app created in the previous step
<br>
[[File:WEBOS 1.png||600px|center|]]

==== Step 5: Debug app====
Click on the Inspect button on the remote to open up developer tools > navigate to the Console tab > check for BSDK initialization and measurement.
[[File:LGwebos 2.png||600px|center|]]

Note - Debug Logging: Disable logging by deleting <syntaxhighlight lang="javascript"> {nol_sdkDebug: 'debug'} </syntaxhighlight> from initialization call.

==== Remote events ====
Build out the app further by including [https://webostv.developer.lge.com/develop/guides/magic-remote remote events] and attaching the player events to corresponding <syntaxhighlight lang="javascript"> keycode: </syntaxhighlight>
<syntaxhighlight lang="javascript">

var media = document.querySelector('video');
window.addEventListener("keydown", function (e) {
switch (e.keyCode) {
case 415: // Play
media.play(); // play video
nSdkInstance.ggPM("play", contentMetadata); // SDK call
break;
case 19: // Pause
media.pause(); // play video
nSdkInstance.ggPM("pause", playheadPosition); // SDK call
break;
case 461: // Back
nSdkInstance.ggPM("stop", playheadPosition); // SDK call
break;
default:
break;
}
});

</syntaxhighlight>
<br>

=== Next steps ===

For further testing on webOS TV apps on the TV, refer to this [https://webostv.developer.lge.com/develop/getting-started/developer-mode-app guide]. If there are any questions or concerns then please reach out to BSDK team. Reference the following guides for product specific information:

* [https://engineeringportal.nielsen.com/docs/DCR_Video_Browser_SDK DCR Video]
* [https://engineeringportal.nielsen.com/docs/DCR_Static_Browser_SDK_(6.0.0) DCR Static]
* [https://engineeringportal.nielsen.com/docs/DTVR_Browser_SDK DTVR]

DCR and DTVR with iOS17 or TVOS17

2023-09-29T12:11:23Z

NickParrucci: /* SDK Versions and Behavior */

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

__NOTOC__

== Overview ==
Summary: The latest version of Nielsen iOS/TVOS AppSDK (currently 9.2.0.0) has the below-mentioned privacy manifest entries and app tracking/opt-out behavior already included. App developers integrating the SDK will automatically have the required entries added to their app's privacy manifest when compiled with Xcode 15 or greater. '''Nielsen Client Developers do not need to make any additional changes to privacy manifest files at the application level to handle Nielsen tracking behavior.'''

Beginning with iOS/TVOS 17, Apple is adding several requirements for App developers around tracking, use of Identifier For Advertisers (IDFA), and certain system APIs as detailed below:
===App Privacy Manifest===
*App privacy manifest files must be updated before submitting apps to the App Store.
**Declare collection/use of user tracking information - app developers/third-party SDKs will be required to list domains that are used to send messages containing the user's device ID (IDFA).
***[https://developer.apple.com/documentation/bundleresources/privacy_manifest_files?changes=_4 Apple:Privacy manifest files]
**Required Reason API - Apple is requiring reasons for apps' usage of certain system APIs that retrieve information about the device or state of some system metrics.
***[https://developer.apple.com/documentation/bundleresources/privacy_manifest_files/describing_use_of_required_reason_api Apple:Describing use of required reason API]

===App Tracking Transparency (ATT) Framework===
When users select "Ask App Not to Track" from the ATT popup, the operating system will behave differently from previous iOS/tvOS versions:
</br>
*In iOS/tvOS versions lower than 17, when "Ask App Not to Track" was selected, apps were blocked from reading the device's IDFA and measurement would be transmitted with a blank device ID.
*With iOS/tvOS 17, if the user selects "Ask App Not to Track", third-party SDKs will not only be blocked from reading the IDFA, the entire app will also be blocked from sending http(s) traffic to domains declared as "tracking domains" in the SDK's privacy manifest file. This will prevent typical measurement pings from going out and will impact volumetric measurement for your apps.
</br>
A new release of the AppSDK (v9.2) aims to address this requirement through explicit distinction of tracking versus non-tracking traffic through the use of 2 domains as described below:
*When a user has opted in (Allow Tracking), measurement data pings will continue to be sent to the imrworldwide.com domain with the available IDFA.
*When a user has opted out (Ask App Not to Track) or with an unknown status, all the measurement data pings will be sent to the non-tracking domain nmrodam.com. These pings will not contain any IDFA tracking.
NOTE: the domain-changing above refers only Nielsen AppSDK with ad framework support. Non-ad framework flavors of AppSDK are not affected.

</br>

'''IMPORTANT NOTE:''' Nielsen iOS/TVOS SDK has the privacy manifest entries and app tracking/opt-out behavior already included. App developers integrating the SDK will automatically have the required entries added to their app's privacy manifest when compiled with Xcode 15 or greater. '''Nielsen Client Developers do not need to make any additional changes to privacy manifest files at the application level to handle Nielsen tracking behavior.''' This functionality is included in Nielsen AppSDK version 9.2.0.0 or greater. With the release of iOS/TVOS 17 in September 2023, Nielsen clients are strongly encouraged to update to AppSDK version 9.2.0.0 (release date: September, 27 2023) or greater as soon as possible to avoid disruption in measurement.

Apple is not currently mandating that SDK developers declare a tracking domain in the SDK-level privacy manifest file, and if one is provided, all traffic from all Nielsen integrations in the app will be blocked for opted-out users. To mitigate this situation, the Nielsen technical team has decided to create 2 versions of the iOS/tvOS AppSDK: one with no tracking domain declared (default) and one with it declared.

The AppSDK 9.2.0.0 build with no tracking domain declared will be made available through Nielsen artifactory and/or direct download from Nielsen Engineering Portal. '''Current integrations using Nielsen artifactory distribution will receive notice to update to this version through CocoaPods/Carthage/SPM distributions automatically.'''

If you have any questions about the AppSDK version that has the tracking domain declared, please reach out to your Nielsen Client Engineer.

== SDK Versions and Behavior ==
NOTE: only AppSDK with ad support is included below, since other flavors are not concerned with IDFA/DeviceID
{| class="wikitable"
|- style="font-weight:bold; text-align:center;"
! Client app Xcode version
! iOS/TVOS Version
! AppSDK Version
! ATT Status
! Opt-out Status
! Tracking declared in privacy manifest (SDK or app level)
! Tracking Domain provided in privacy manifest (SDK or app level)
! Ping/Message Behavior
|-
| 14
| any
| any
| "Allow Tracking"
| false
| n/a
| n/a
| All pings allowed, with DeviceID
|-
| 14
| any
| any
| "Ask App Not to Track"
| true
| n/a
| n/a
| All pings allowed, blank DeviceID
|-
| 15
| 16.x and below
| any
| "Allow Tracking"
| false
| no
| no
| All pings allowed, with DeviceID
|-
| 15
| 16.x and below
| any
| "Ask App Not to Track"
| true
| no
| no
| All pings allowed, blank DeviceID
|-
| 15
| 17 or greater
| 9.1.x.x and below
| "Ask App Not to Track"
| true
| no
| no
| All pings allowed, blank DeviceID
|-
| 15
| 17 or greater
| 9.1.x.x and below
| "Allow Tracking"
| false
| no
| no
| All pings allowed, with DeviceID
|-
| 15
| 17 or greater
| 9.2.0.0 and below
| "Ask App Not to Track"
| true
| yes (App level)
| yes - imrworldwide.com
| All pings allowed, blank DeviceID, SDK pings will use non-tracking domain nmrodram.com
|-
| 15
| 17 or greater
| 9.2.0.0 and greater
| "Allow Tracking"
| false
| yes - (SDK level)
| yes - imrworldwide.com
| All pings allowed, with DeviceID
|-
| 15
| 17 or greater
| 9.2.0.0 and greater
| "Ask App Not to Track"
| true
| yes - (SDK level)
| yes - imrworldwide.com
| All pings allowed, blank DeviceID, SDK pings will use non-tracking domain nmrodram.com, all the app traffic from non-sdk integrations going to tracking domain imrworldwide.com, will be blocked

TVOS SDK Release Notes

2023-09-27T18:11:48Z

NickParrucci:

{{Breadcrumb|}} {{Breadcrumb|Digital}} {{CurrentBreadcrumb}}
[[Category:Digital]]
__NOTOC__
== Release 9.2.0.0 (9-27-2023) ==
*Support for privacy manifest and required reason API introduced in XCode 15.
*Digitally signed SDK framework per Apple recommendation
*DCR Static recognizing metadata with changed assetID for new impressions.
*Limiting ping retries during https failures.
*Other bug fixes and enhancements.

== Release 9.1.0.0 (3-31-2023) ==
*DCR Static duration measurement for AppSDK (currently only AGF).
*Removed use of iOS keychains, started using NSUserDefaults for persistent storage.
*Viewability: allow enabling by product (DCR, DTVR).
*Other bug fixes and enhancements.

== Release 9.0.0.0 (10-07-2022) ==
* Viewability measurement for DTVR, DCR Content and DCR Ad products.
* Audibility measurement for DTVR, DCR Content and DCR Ad products.
* SDK built with XCode 14.
* Other bug fixes and enhancements.

== Release 8.2.0.0 (03-21-2022) ==
* Adopting Swift language internally, built on a mixed model (Swift+Objective C).
* Support for Swift markers to help Swift developers.
* Removed the usage of deprecated iOS network reachability class.
* Disabled iCloud backup/synchronization of SDK keychain items.
* Other bug fixes and enhancements.

== Release 8.1.0.0 (06-28-2021) ==
* Support for XCFramework build distribution.
* Support for MacOS Catalyst platform framework.
* Fixed the device classification for MacOS M1 measurement.
* Support to capture Hashed email and UID.
* Support to collect SDK diagnostic data.
* Other bug fixes and enhancements.

== Release 8.0.0.0 (10-05-2020) ==
* iOS 14 App Transparency Framework support.
* FPID and VendorID support.
* Fixed the device classification for iPADOS measurement.
* Support for Xamarin cross platform framework.
* Other bug fixes and enhancements.

== Release 7.2.0.0 (05-18-2020) ==
* DTVR AQH and IVD requirements for End and pause timeout.
* Support for Hybrid app webview measurement.
* Support for Hybrid app react native webview measurement.
* Support for React Native measurement.
* Other bug fixes and enhancements

== Release 7.1.0.0 (12-09-2019) ==
* Removed usage of deprecated class UIWebView
* Offline viewing measurement enhancements
* Fixed deadlock on SDK shutdown
* Revisited precedence logic for sfcode parameter
* Fix for DCR individual ad pings parameters after channel change
* Using default value for incorrect adModel parameter
* Defaulting isLive parameter value on channel change
* Other fixes and enhancements.

== Release 7.0.0.0 (09-06-2019) ==
* Support for CDN based config.
* Support for Market based EMM UAID pings.
* Changes required for proper DCR Static measurement in multi-instance/multiple appid's case.
* Fixes for OTT synchronization issues between iOS and Android platforms.
* Fixes for EV data parameters in few scenarios.
* Fixes for DCR Static product behaviour in background app refresh and background fetch scenarios.
* DCR Ad reporting improvements.
* Fixes and improvements for the SDK console log messages.
* Other enhancements and fixes.

== Release 6.2.0.0 (02-04-2019) ==
* Introduced Dynamic framework for SDK.
* Removal of Location Module from SDK Code.
* Increased SDK log file size for Debug mode.
* Removed OTT Airplay/mirroring detection that caused crashes in AVAudioSession class.
* DCR performance improvements.
* Fixed the parsing error happening when clientid/vcid provided as empty in metadata.
* Align AppSDK for FW detection with BSDK for DCR measurement.
* Other Bug Fixes/Enhancements.

== Release 6.1.0.1 (9-13-2018) ==
*Nielsen SDK support for Xcode 10 and tvOS 12

== Release 6.0.0.4 (5-24-2018) ==
*If the SDK build target is set to AGF then SDK will send the hello ping to “eu” and “eu-uat” for debug builds. No changes to the non AGF build the default sfcode will continue to be "sdk" and "cert" for debug build.
*The C1 parameter (NUID) will now be sent as encrypted DeviceID.
*New SessionID changes. The sessionID will contain 29 length random characters appended by timestamp.
*Support for multiple SDK instance without any limit.
*New log feature for CAT tool to retrieve the API level information from client apps. This ping will contain the eventType, parameters, SDK version, appid etc.
*Removed Viewability for this release.

== Release 5.1.1.17 (1-23-2017) ==
*Added "seconds" place to the launch ping
*Ability to opt-out using "Limit Ad Tracking" feature
*Improved CPU Performance while apps are running in background
*Opt-Out pages can be served based on user’s language and locale from device

== Release 5.1.1.12 (12-14-2016) ==
*Support for Nielsen TV Brand Effect
*Ability to set CMS parameters at a more global level
*Opt-out pages based on locale and country
*Opt-out policy based on the "Limit Ad Tracking" flag
*Collection of additional device information
*Issue a warning in client developer’s console when ad is played for more than 5 minutes
*Removed the requirement for “type” parameter
*Limit the duration reported for App launch

== Release 5.1.1.7 (9-13-2016) ==
*General bug fix and performance improvements

== Release 5.1.1.5 (7-12-2016) ==
*Includes a sample TVOS application used to assist during integration.
*Support for TVML based optout pages
*General bug fix and performance improvements

== Release 5.1.0.7 (6-15-2016) ==
*Combined SDK for DCR US and International (Germany)
*API to signal end of content (end API)
*Support for Pause timeout
*Updated API to support JSON object instead of string.
*Reporting of media URL and bundle ID
*Updated ping retry logic
*Changes in OptOut process behavioral
*Enhanced Debugging and SDK logging
*Changes to API signature

iOS SDK Release Notes

2023-09-27T18:10:47Z

NickParrucci:

{{Breadcrumb|}} {{Breadcrumb|Digital Downloads}} {{CurrentBreadcrumb}}
[[Category:Digital]]
__NOTOC__
== Release 9.2.0.0 (9-27-2023) ==
*Support for privacy manifest and required reason API introduced in XCode 15.
*Digitally signed SDK framework per Apple recommendation
*DCR Static recognizing metadata with changed assetID for new impressions.
*Limiting ping retries during https failures.
*Other bug fixes and enhancements.

== Release 9.1.0.0 (3-31-2023) ==
*DCR Static duration measurement for AppSDK (currently only AGF).
*Removed use of iOS keychains, started using NSUserDefaults for persistent storage.
*Viewability: allow enabling by product (DCR, DTVR).
*Other bug fixes and enhancements.

== Release 9.0.0.0 (10-07-2022) ==
* Viewability measurement for DTVR, DCR Content and DCR Ad products.
* Audibility measurement for DTVR, DCR Content and DCR Ad products.
* SDK built with XCode 14.
* Other bug fixes and enhancements.

== Release 8.2.0.0 (03-21-2022) ==
* Adopting Swift language internally, built on a mixed model (Swift+Objective C).
* Support for Swift markers to help Swift developers.
* Removed the usage of deprecated iOS network reachability class.
* Disabled iCloud backup/synchronization of SDK keychain items.
* Other bug fixes and enhancements.

== Release 8.1.0.0 (06-28-2021) ==
* Support for XCFramework build distribution.
* Support for MacOS Catalyst platform framework.
* Fixed the device classification for MacOS M1 measurement.
* Support to capture Hashed email and UID.
* Support to collect SDK diagnostic data.
* Other bug fixes and enhancements.

== Release 8.0.0.0 (10-05-2020) ==
* iOS 14 App Transparency Framework support.
* FPID and VendorID support.
* Fixed the device classification for iPADOS measurement.
* Support for Xamarin cross platform framework.
* Other bug fixes and enhancements.

== Release 7.2.0.0 (05-18-2020) ==
* DTVR AQH and IVD requirements for End and pause timeout.
* Support for Hybrid app webview measurement.
* Support for Hybrid app react native webview measurement.
* Support for React Native measurement.
* Other bug fixes and enhancements

== Release 7.1.0.0 (12-09-2019) ==
* Removed usage of deprecated class UIWebView
* Offline viewing measurement enhancements
* Fixed deadlock on SDK shutdown
* Revisited precedence logic for sfcode parameter
* Fix for DCR individual ad pings parameters after channel change
* Using default value for incorrect adModel parameter
* Defaulting isLive parameter value on channel change
* Other fixes and enhancements.

== Release 7.0.0.0 (09-06-2019) ==
* Support for CDN based config.
* Support for Market based EMM UAID pings.
* Changes required for proper DCR Static measurement in multi-instance/multiple appid's case.
* Fixes for OTT synchronization issues between iOS and Android platforms.
* Fixes for EV data parameters in few scenarios.
* Fixes for DCR Static product behaviour in background app refresh and background fetch scenarios.
* DCR Ad reporting improvements.
* Fixes and improvements for the SDK console log messages.
* Other enhancements and fixes.

== Release 6.2.0.0 (02-04-2019) ==
* Introduced Dynamic framework for SDK.
* Removal of Location Module from SDK Code.
* Increased SDK log file size for Debug mode.
* Removed OTT Airplay/mirroring detection that caused crashes in AVAudioSession class.
* DCR performance improvements.
* Fixed the parsing error happening when clientid/vcid provided as empty in metadata.
* Align AppSDK for FW detection with BSDK for DCR measurement.
* Other Bug Fixes/Enhancements.

== Release 6.1.0.1 (9-13-2018) ==
*Support added for Video On Demand in TV Ratings
*Support for Xcode 10 and iOS 12

== Release 6.0.0.4 (5-24-2018) ==
*If the SDK build target is set to AGF then SDK will send the hello ping to “eu” and “eu-uat” for debug builds. No changes to the non AGF build the default sfcode will continue to be "sdk" and "cert" for debug build.
*The C1 parameter (NUID) will now be sent as encrypted DeviceID.
*New SessionID changes. The sessionID will contain 29 length random characters appended by timestamp.
*Support for multiple SDK instance without any limit.
*New log feature for CAT tool to retrieve the API level information from client apps. This ping will contain the eventType, parameters, SDK version, appid etc.
*Removed Viewability for this release.

== Release 5.1.1.29 (7-31-2017) ==
*Genre parameter will be a part of DCR pings and the value will be reflected as part of c44 parameter.
*Merged adModel and adLoadType flags
*Fix for stop event data carried to next session’s duration ping

== Release 5.1.1.25 (5-31-2017) ==
*Enhanced support for Digital Audio
*Ability to pass adloadtype as “linear” or “dynamic”
*Ability to detect end of content and static material through duration pings
*Acceptance of empty parameters with a warning message triggered, if a required parameter is missing
*Acceptance of case-insensitive JSON key values
*Configurable feature to show Ad view counts in the duration pings
*Automatic Pause Detection and Debug build detection
*Change of default ‘type’ from “ad” to “content”
*Removal of “Static” Launch Ping for Non-Static product implementations
*Fix for App crash when multiple threads are accessing the SQLite

== Release 5.1.1.23 (5-5-2017) ==
*Ability to pass adloadtype as “linear” or “dynamic”
*Ability to detect end of content and static material through duration pings
*Acceptance of empty parameters with a warning message triggered, if a required parameter is missing
*Acceptance of case-insensitive JSON key values
*Configurable feature to show Ad view counts in the duration pings
*Automatic Pause Detection and Debug build detection
*Change of default ‘type’ from “ad” to “content”
*Removal of “Static” Launch Ping for Non-Static product implementations
*Fix for App crash when multiple threads are accessing the SQLite

== Release 5.1.1.19 (4-3-2017) ==
*Fix for muting background music apps

== Release 5.1.1.18 (2-3-2017) ==
*Minor bug fixes and performance improvement

== Release 5.1.1.17 (1-23-2017) ==
*Added “seconds” place to the launch ping
*Ability to opt-out using “Limit Ad Tracking” feature
*Improved CPU Performance while apps are running in background
*Opt-Out pages can be served based on user’s language and locale from device

== Release 5.1.1.12 (12-14-2016) ==
*Support for Nielsen TV Brand Effect
*Ability to set CMS parameters at a more global level
*Opt-out pages based on locale and country
*Opt-out policy based on the ‘Limit Ad Tracking’ flag
*Collection of additional device information
*Issue a warning in client developer’s console when ad is played for more than 5 minutes
*Removed the requirement for “type” parameter
*Limit the duration reported for App launch

== Release 5.1.1.9 (10-18-2016) ==
*Fixed Linker error duplicate symbols for Reachability notification in iOS.

== Release 5.1.1.7 (9-13-2016) ==
*Support for iOS 10
*Usage of stop API call is made optional when switching between content or advertising occurs.
*General bug fix and performance improvements

== Release 5.1.1.5 (7-12-2016) ==
*Sending event level (button press data) data to census collections.
*Support for Pause timeout (from 30 minutes to 5 minutes)
*Changes in OTT when switching from mobile to Chromecast
*Self-error Reporting for iOS SDK
*General bug fix and performance improvements

== Release 5.1.0.5 (4-25-2016) ==
*Combined SDK for DCR US and International (Germany)
*API to signal end of content (end API)
*Changes to use of stop API
*Support for OTT measurement
*Support for Pause timeout
*Offline viewing
*Updated API to support JSON object instead of string.
*Reporting of media URL and bundle ID
*Updated ping retry logic
*Changes in OptOut process behavioral
*Enhanced Debugging and SDK logging
*Changes to API signature
*Introduced new API updateOTT to report current OTT status.

== Release 4.0.0.8 (6-9-2015) ==
*Support for Nielsen DCR product (Digital Content Ratings)
**All the products should be migrated to the latest SDK.
**This SDK distribution does not have a native library component or shared object.
*Support for Nielsen App static measurement
*Support for Ad measurement
*Removal of Native C++ code
*Removed singleton restriction
*Support for iOS 9 and iOS 9 PIP mode
*General bug fix and performance improvements

== Release 3.2.1.26 (1-10-2015) ==

Android SDK Release Notes

2023-09-27T18:09:58Z

NickParrucci:

{{Breadcrumb|}} {{Breadcrumb|Digital Downloads}} {{CurrentBreadcrumb}}
[[Category:Digital]]
__NOTOC__
== Release 9.2.0.0 (9-27-2023) ==
*DCR Static recognizing metadata with changed assetID for new impressions.
*Limiting ping retries during https failures.
*Other bug fixes and enhancements.

== Release 9.1.0.0 (3-31-2023) ==
*DCR Static duration measurement for AppSDK (currently only AGF)
*Viewability: allow enabling by product (DCR, DTVR)
*Other bug fixes and enhancements

== Release 9.0.0.0 (10-07-2022) ==
* Viewability measurement for DTVR, DCR Content and DCR Ad products.
* Audibility measurement for DTVR, DCR Content and DCR Ad products.
* Kotlin-Java interoperability implementation in SDK.
* Other bug fixes and enhancements.

== Release 8.2.0.0 (03-21-2022) ==
* Support for EMM AGF AdID-less solution.
* Enabled SDK to capture network availability changes.
* Removed the usage of deprecated network classes.
* Other bug fixes and enhancements.

== Release 8.1.0.0 (06-28-2021) ==
* Support for SDK build variants - AD/NoAD/NoID.
* Support to indicate ID used for AD build variant - AD ID vs Android ID.
* Support to capture Hashed email and UID.
* Support to collect SDK diagnostic data.
* Other bug fixes and enhancements.

== Release 8.0.0.0 (10-05-2020) ==
* FPID and VendorID support.
* Support for Android apps running on ChromeOS.
* Support for Xamarin cross platform framework.
* Other bug fixes and enhancements.

== Release 7.2.0.0 (05-18-2020) ==
* DTVR AQH and IVD requirements for End and pause timeout.
* Support for Hybrid app webview measurement.
* Support for Hybrid app react native webview measurement.
* Support for React Native measurement.
* Other bug fixes and enhancements

== Release 7.1.0.0 (12-09-2019) ==

* Application background/foreground state auto-detection (AndroidX)
* Fixed forward rewind evdata containing negative values
* Offline viewing measurement enhancements
* Revisited precedence logic for sfcode parameter
* Using default value for incorrect adModel parameter
* Defaulting isLive parameter value on channel change
* Other fixes and enhancements.

== Release 7.0.0.0 (09-06-2019) ==

* Support for CDN based config.
* Support for Market based EMM UAID pings.
* Changes required for proper DCR Static measurement in multi-instance/multiple appid's case.
* Fixes for OTT synchronization issues between iOS and Android platforms.
* Fixes for EV data parameters in few scenarios.
* Fixes for DCR Static product behaviour in background app refresh and background fetch scenarios.
* DCR Ad reporting improvements.
* Fixes and improvements for the SDK console log messages.
* Other enhancements and fixes.

== Release 6.2.0.0 (02-04-2019) ==
* Removal of Location Module from SDK Code.
* Fixed the getOptoutStatus() api, so that client can call it in main thread.
* Fixed the parsing error happening when clientid/vcid provided as empty in metadata.
* Align AppSDK for FW detection with BSDK for DCR measurement.
* Other enhancements and fixes.

== Release 6.1.0.1 (9-13-2018) ==
*Support added for Video On Demand in TV Ratings
*Bug fixes and improvements

== Release 6.0.0.4 (5-24-2018) ==
*If the SDK build target is set to AGF then SDK will send the hello ping to “eu” and “eu-uat” for debug builds. No changes to the non AGF build the default sfcode will continue to be "sdk" and "cert" for debug build.
*The C1 parameter (NUID) will now be sent as encrypted DeviceID.
*New SessionID changes. The sessionID will contain 29 length random characters appended by timestamp.
*Support for multiple SDK instance without any limit.
*New log feature for CAT tool to retrieve the API level information from client apps. This ping will contain the eventType, parameters, SDK version, appid etc.
*Removed Viewability for this release.

== Release 5.1.1.26 (7-31-2017) ==
*Genre parameter will be a part of DCR pings and the value is reflected as part of c44 parameter.
*Merged adModel and adLoadType flags
*Fix for stop event data carried to next session’s duration ping
*Fix for last playhead call that is not processed (when there is no time-gap between the last playhead and end call)

== Release 5.1.1.24 (6-2-2017) ==
*Enhanced support for Digital Audio
*Ability to pass adloadtype as “linear” or “dynamic”
*Ability to detect end of content and static material through duration pings
*Acceptance of empty parameters with a warning message triggered, if a required parameter is missing
*Acceptance of case-insensitive JSON key values
*Configurable feature to show Ad view counts in the duration pings
*Automatic Pause Detection and Debug build detection
*Change of default ‘type’ from “ad” to “content”
*Removal of “Static” Launch Ping for Non-Static product implementations
*Fix for metadata carry over between channels after a channel change

== Release 5.1.1.18 (1-24-2017) ==
*Ability to opt-out using “Limit Ad Tracking” feature
*Improved CPU Performance through encryption process change
*Opt-Out pages can be served based on user’s language and locale from device

== Release 5.1.1.14 (12-10-2016) ==
*Support for Nielsen TV Brand Effect
*Ability to set CMS parameters at a more global level
*Collection of additional device information
*Opt-out pages based on locale and country
*Opt-out based on the ‘Limit Ad Tracking’ flag
*Issue a warning in client developer’s console when an ad is being played for more than 5 minutes
*Reduced load time of Android SDK, caused due to encryption.
*Limit the duration reported for App launch
*Modification to accept non-JSON strings
*Fixed
**Incorrect DRM placement ID
**DRM pings sent in bursts in case of time change

== Release 5.1.1.10 (10-19-2016) ==
*Fixed an issue where SDK will send a burst of data pings in Android.

== Release 5.1.1.7 (9-1-2016) ==
*Support for Android N
*Usage of stop API call is made optional when switching between content or advertising occurs.
*General bug fix and performance improvements

== Release 5.1.1.4 (8-1-2016) ==
*Support for Pause timeout (from 30 minutes to 5 minutes)

== Release 5.1.1.3 (7-7-2016) ==
*Sending event level (button press data) data to census collections.
*Changes in OTT when switching from mobile to Chromecast
*General bug fix and performance improvements

== Release 5.1.0.4 (4-25-2016) ==
*Combined SDK for DCR US and International (Germany)
*API to signal end of content (end API)
*Changes to use of stop API
*Support for OTT measurement
*Support for Pause timeout
*Offline viewing
*Updated API to support JSON object instead of string.
*Reporting of media URL and bundle ID
*Updated ping retry logic
*Changes in OptOut process behavioral
*Enhanced Debugging and SDK logging
*Changes to API signature
*Introduced new API updateOTT to report current OTT status.

== Release 4.0.0.8 (6-9-2015) ==
*Support for Nielsen DCR product (Digital Content Ratings)
*All the products should be migrated to the latest SDK.
*This SDK distribution does not have a native library component or shared object.
*Support for Nielsen App static measurement
*Support for Ad measurement
*Removal of Native C++ code
*Removed singleton restriction
*Support for Android 6.0 Marshmallow
*General bug fix and performance improvements

== Release 1.2.3.8 (1-10-2015) ==

DCR Video iOS14 Migration

2023-09-22T18:39:26Z

NickParrucci:

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

__NOTOC__
== Overview ==
NOTE: this page is for historical reference. In addition to dealing with App Tracking Transparency, developers should also be aware of changes related to iOS 17 detailed here: [[Nielsen_Digital_Measurement_and_iOS17_or_TVOS17]]

Apple recently released a new policy on consent requirements for its mobile advertising tool, Identifier for Advertisers (IDFA). With this new policy, (App Tracking Setting) users can choose whether an IDFA may be used by mobile applications. iOS 14 was released on Sept 16th.

== What does this mean for measurement? ==
Apple added a new Framework called “The App Tracking Transparency Framework”. This is now required to control whether the Ad Framework will return the IDFA. If our app requests the IDFA, but advertisingTrackingEnabled=No, then we will get: <code> IDFA = 00000000 -0000-0000-0000-000000000000</code>. If a client is using our APP SDK v7 and below, running on a device with iOS14 installed, as this is a new framework, our SDK will never be able to retrieve the IDFA.

Version 8 of our App SDK will come in two versions. One that is enabled to work with the App Tracking Transparency Framework, and another version that does not use the Ad Framework. A Table outlining the various iOS versions and Nielsen AppSDK versions is located later in this document.

== Transparency Framework ==
Apple was going to force all publishers to check if <code>ATTrackingManager. AuthorizationStatus</code> was equal to authorized. Now however, since they are not forcing publishers to ask the user, as long as the <code>ATTrackingManager.AuthorizationStatus</code> is equal to undefined, or authorized, you are allowed to grab the IDFA value. The change they made was to allow us to use undefined as a valid state.
To display the App Tracking Transparency authorization request for accessing the IDFA, update your info.plist to add the <code>NSUserTrackingUsageDescription</code> key with a custom message describing your usage.

== SDK Versions and Behavior ==
{| class="wikitable"
|- style="font-weight:bold; text-align:center;"
! OS
! SDK Flavor/Version
! LAT/Tracking
! Opt-out Status
! Opt-out URL
! Integration Changes
|-
| iOS/tvOS 13 and below
| Appsdk < 7.2
| LAT works fine
| As per LAT
| LAT URL
| No Changes
|-
| iOS/tvOS 13 and below
| Appsdk without ad framework < 7.2
| NA (Not Applicable)
| User choice opt-out/in
| User choice opt-out/in url
| No Changes
|-
| iOS/tvOS 13 and below
| AppSDK 8.0
| LAT works fine
| As per LAT
| LAT URL
| No Changes
|-
| iOS/tvOS 13 or 14
| Appsdk 8.0 without Ad Framework
| NA (Not Applicable)
| User choice opt-out/in
| User choice opt-out/in url
| No Changes
|-
| iOS/tvOS 14
| Appsdk < 7.2
| No support for new Apple tracking API
| Opt-out will be marked as true
| LAT URL
| style="font-weight:bold;" | Yes, Clients to upgrade to SDK 8.0
|-
| iOS/tvOS 14
| AppSDK 8.0
| Client has implemented the Consent pop-up.
| As per LAT
| LAT URL
| style="font-weight:bold;" | Yes, Clients to implement pop-up and app store verbiage
|-
| iOS/tvOS 14.0 - 14.4<br />APPLE is not enforcing App Transparency Layer (pop-up)
| AppSDK 8.0
| Apple not mandating consent pop-up.
| As per LAT
| LAT URL
|
|-
| iOS/tvOS 14.5+<br />APPLE is enforcing App Transparency Layer (pop-up)
| AppSDK 8.0
| Client has not implemented the consent pop-up.
| As per LAT
| LAT URL
| style="font-weight:bold;" | Yes, Clients to implement pop-up and app store verbiage
|-
| iOS/tvOS 14
| Appsdk 8.0 without Ad Framework
| style="font-weight:bold;" | Clients denied the Ad Framework SDK
| User choice opt-out/in
| User choice opt-out/in url
| style="font-weight:bold;" | Yes, Clients implement webview to pass user choice to the sdk. No changes for AGF no ad framework clients.
|}

== Privacy and Opt-Out ==

=== OS-level Opt-out ===
The Nielsen SDK automatically leverages the iOS's '''Limit Ad Tracking''' or '''AppTracking''' setting.

* If the User's device is running < iOS 13.x, the Nielsen SDK will check the status of '''Limit Ad Tracking''' (Located under Privacy >> Advertising). If this is enabled, the user will be opted out of demographic measurement.
* iOS14 modifies the way Apple manages the collection of a User's Opt-In status through '''AppTracking'''. Starting with Version 8.x+, the Nielsen App SDK will check the iOS version during initialization. If the device is running iOS12 or iOS13, the Limit Ad Tracking setting is requested. If iOS14.x +, then AppTracking is utilized.
If using the Nielsen SDK V7 on a device running iOS14, the value returned will always be isAdvertisingTrackingEnabled = true opting out the user from demographic measurement.
Apple started requiring publishers to secure consent from the user in iOS14.5+. This means the AppTracking Setting must equal approved before the User is Opted in.
* '''Limit Ad Tracking''' is managed using the isAdvertisingTrackingEnabled value.
{| class="wikitable" style="background-color:#F3F3F3;"
|-
! Value Returned in iOS12 / iOS13 using Nielsen SDK < V7.x
! style="color:#222;" | Opt in/out Status
|- style="background-color:#D9EAD3; color:#222;"
| isAdvertisingTrackingEnabled = false
| User will be included in demographic measurement.
|- style="background-color:#FCF0E4; color:#222;"
| isAdvertisingTrackingEnabled = true
| User will NOT be included in demographic measurement.
|}
* '''AppTracking''' is managed using the [https://developer.apple.com/documentation/apptrackingtransparency AppTrackingTransparency framework]. If the value returned when checked is:
{| class="wikitable" style="background-color:#EAECF0;"
|-
! Value Returned is iOS14 using Nielsen SDK > V8.x
! style="color:#222;" | Opt in/out Status
|- style="background-color:#D9EAD3; color:#222;"
| ATTrackingManager.AuthorizationStatus.authorized
| User will be included in demographic measurement.
|- style="background-color:#FCF0E4; color:#222;"
| ATTrackingManager.AuthorizationStatus.notDeterminded<br />ATTrackingManager.AuthorizationStatus.denied<br />ATTrackingManager.AuthorizationStatus.restricted
| User will NOT be included in demographic measurement.
|}

The user is opted out of demographic measurement if the OS-level Limit Ad Tracking setting is enabled, or AppTracking value equals denied or restricted. As a publisher, you cannot override this setting.

== User Choice ==
The User Choice method can be used without the Ad Framework, or in situations where the publisher does not wish to use the [https://developer.apple.com/documentation/apptrackingtransparency App Tracking Transparency Framework].

Nielsen Digital Measurement and iOS17 or TVOS17

2023-09-22T18:36:44Z

NickParrucci:

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

__NOTOC__
===<span style="color: #ff0000;">Please note: this page will be updated as more information becomes available from Apple</span>===

== Overview ==
Beginning with iOS/tvOS 17, Apple is adding several requirements for App developers around tracking, use of Identifier For Advertisers (IDFA), and certain system APIs as detailed below:
===App Privacy Manifest===
*App privacy manifest files must be updated before submitting apps to the App Store.
**Declare collection/use of user tracking information - app developers/third-party SDKs will be required to list domains that are used to send messages containing the user's device ID (IDFA).
***[https://developer.apple.com/documentation/bundleresources/privacy_manifest_files?changes=_4 Apple:Privacy manifest files]
**Required Reason API - Apple is requiring reasons for apps' usage of certain system APIs that retrieve information about the device or state of some system metrics.
***[https://developer.apple.com/documentation/bundleresources/privacy_manifest_files/describing_use_of_required_reason_api Apple:Describing use of required reason API]

===App Tracking Transparency (ATT) Framework===
When users select "Ask App Not to Track" from the ATT popup, the operating system will behave differently from previous iOS/tvOS versions:
</br>
*In iOS/tvOS versions lower than 17, when "Ask App Not to Track" was selected, apps were blocked from reading the device's IDFA and measurement would be transmitted with a blank device ID.
*With iOS/tvOS 17, if the user selects "Ask App Not to Track", third-party SDKs will not only be blocked from reading the IDFA, the SDKs will also be blocked from sending http(s) traffic to domains declared as "tracking domains" in the SDK's privacy manifest file. This will prevent typical measurement pings from going out and will impact volumetric measurement for your apps.
</br>
A new release of the AppSDK (v9.2) aims to address this requirement through explicit distinction of tracking versus non-tracking traffic through the use of 2 domains as described below:
*When a user has opted in (Allow Tracking), measurement data pings will continue to be sent to the imrworldwide.com domain with the available IDFA.
*When a user has opted out (Ask App Not to Track) or with an unknown status, all the measurement data pings will be sent to the non-tracking domain nmrodam.com. These pings will not contain any IDFA tracking.

==Next Steps==
#Move to the latest Nielsen AppSDK release for builds targeting iOS 17 with Xcode 15. Upgrading to the new build of the Digital SDKs should be straightforward through your build configuration. AppSDKs remain backwards compatible and would not require any further integration changes. Please refer to the Integration guide section for further details.
#To be decided if the privacy manifest needs to be modified. For coexisting DAR pixel and Digital SDK integrations please reach out to your Nielsen Client Engineer to determine the path forward.
#Work with your Nielsen Client Engineer once implemented to ensure proper measurement.

==Technical Details==

Technical details about the upcoming iOS/tvOS AppSDK release for Nielsen client app developers can be found here: [[DCR_and_DTVR_with_iOS17_or_TVOS17]]

This page will be updated as more information becomes available.

DCR and DTVR with iOS17 or TVOS17

2023-09-22T18:33:25Z

NickParrucci: Created page with "{{Breadcrumb|}} {{Breadcrumb|Digital}} {{Breadcrumb|DCR & DTVR}} {{CurrentBreadcrumb}} Category:Digital __NOTOC__ == Overview == Summary: The latest version of Nielsen..."

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

__NOTOC__

== Overview ==
Summary: The latest version of Nielsen iOS/TVOS AppSDK (currently 9.2.0.0) has the below-mentioned privacy manifest entries and app tracking/opt-out behavior already included. App developers integrating the SDK will automatically have the required entries added to their app's privacy manifest when compiled with Xcode 15 or greater. '''Nielsen Client Developers do not need to make any additional changes to privacy manifest files at the application level to handle Nielsen tracking behavior.'''

Beginning with iOS/TVOS 17, Apple is adding several requirements for App developers around tracking, use of Identifier For Advertisers (IDFA), and certain system APIs as detailed below:
===App Privacy Manifest===
*App privacy manifest files must be updated before submitting apps to the App Store.
**Declare collection/use of user tracking information - app developers/third-party SDKs will be required to list domains that are used to send messages containing the user's device ID (IDFA).
***[https://developer.apple.com/documentation/bundleresources/privacy_manifest_files?changes=_4 Apple:Privacy manifest files]
**Required Reason API - Apple is requiring reasons for apps' usage of certain system APIs that retrieve information about the device or state of some system metrics.
***[https://developer.apple.com/documentation/bundleresources/privacy_manifest_files/describing_use_of_required_reason_api Apple:Describing use of required reason API]

===App Tracking Transparency (ATT) Framework===
When users select "Ask App Not to Track" from the ATT popup, the operating system will behave differently from previous iOS/tvOS versions:
</br>
*In iOS/tvOS versions lower than 17, when "Ask App Not to Track" was selected, apps were blocked from reading the device's IDFA and measurement would be transmitted with a blank device ID.
*With iOS/tvOS 17, if the user selects "Ask App Not to Track", third-party SDKs will not only be blocked from reading the IDFA, the entire app will also be blocked from sending http(s) traffic to domains declared as "tracking domains" in the SDK's privacy manifest file. This will prevent typical measurement pings from going out and will impact volumetric measurement for your apps.
</br>
A new release of the AppSDK (v9.2) aims to address this requirement through explicit distinction of tracking versus non-tracking traffic through the use of 2 domains as described below:
*When a user has opted in (Allow Tracking), measurement data pings will continue to be sent to the imrworldwide.com domain with the available IDFA.
*When a user has opted out (Ask App Not to Track) or with an unknown status, all the measurement data pings will be sent to the non-tracking domain nmrodam.com. These pings will not contain any IDFA tracking.
NOTE: the domain-changing above refers only Nielsen AppSDK with ad framework support. Non-ad framework flavors of AppSDK are not affected.

</br>

'''IMPORTANT NOTE:''' Nielsen iOS/TVOS SDK has the privacy manifest entries and app tracking/opt-out behavior already included. App developers integrating the SDK will automatically have the required entries added to their app's privacy manifest when compiled with Xcode 15 or greater. '''Nielsen Client Developers do not need to make any additional changes to privacy manifest files at the application level to handle Nielsen tracking behavior.''' This functionality is included in Nielsen AppSDK version 9.2.0.0 or greater. With the release of iOS/TVOS 17 in September 2023, Nielsen clients are strongly encouraged to update to AppSDK version 9.2.0.0 (release date: September, 27 2023) or greater as soon as possible to avoid disruption in measurement.

Apple is not currently mandating that SDK developers declare a tracking domain in the SDK-level privacy manifest file, and if one is provided, all traffic from all Nielsen integrations in the app will be blocked for opted-out users. To mitigate this situation, the Nielsen technical team has decided to create 2 versions of the iOS/tvOS AppSDK: one with no tracking domain declared (default) and one with it declared.

The AppSDK 9.2.0.0 build with no tracking domain declared will be made available through Nielsen artifactory and/or direct download from Nielsen Engineering Portal. '''Current integrations using Nielsen artifactory distribution will receive notice to update to this version through CocoaPods/Carthage/SPM distributions automatically.'''

If you have any questions about the AppSDK version that has the tracking domain declared, please reach out to your Nielsen Client Engineer.

== SDK Versions and Behavior ==
NOTE: only AppSDK with ad support is included below, since other flavors are not concerned with IDFA/DeviceID
{| class="wikitable"
|- style="font-weight:bold; text-align:center;"
! Client app Xcode version
! iOS/TVOS Version
! AppSDK Version
! ATT Status
! Opt-out Status
! Tracking declared in privacy manifest (SDK or app level)
! Tracking Domain provided in privacy manifest (SDK or app level)
! Ping/Message Behavior
|-
| 14
| any
| any
| "Allow Tracking"
| false
| n/a
| n/a
| All pings allowed, with DeviceID
|-
| 14
| any
| any
| "Ask App Not to Track"
| true
| n/a
| n/a
| All pings allowed, blank DeviceID
|-
| 15
| 16.x and below
| any
| "Allow Tracking"
| false
| no
| no
| All pings allowed, with DeviceID
|-
| 15
| 16.x and below
| any
| "Ask App Not to Track"
| true
| no
| no
| All pings allowed, blank DeviceID
|-
| 15
| 17 or greater
| 9.1.x.x and below
| "Allow Tracking"
| false
| no
| no
| All pings allowed, with DeviceID
|-
| 15
| 17 or greater
| 9.1.x.x and below
| "Ask App Not to Track"
| true
| no
| no
| All pings allowed, blank DeviceID
|-
| 15
| 17 or greater
| 9.1.x.x and below
| "Allow Tracking"
| false
| no
| no
| All pings allowed, with DeviceID
|-
| 15
| 17 or greater
| 9.2.0.0 and below
| "Ask App Not to Track"
| true
| yes (App level)
| yes - imrworldwide.com
| All pings allowed, blank DeviceID, SDK pings will use non-tracking domain nmrodram.com
|-
| 15
| 17 or greater
| 9.2.0.0 and greater
| "Allow Tracking"
| false
| yes - (SDK level)
| yes - imrworldwide.com
| All pings allowed, with DeviceID
|-
| 15
| 17 or greater
| 9.2.0.0 and greater
| "Ask App Not to Track"
| true
| yes - (SDK level)
| yes - imrworldwide.com
| All pings allowed, blank DeviceID, SDK pings will use non-tracking domain nmrodram.com, all the app traffic from non-sdk integrations going to tracking domain imrworldwide.com, will be blocked

Nielsen Digital Measurement and iOS17 or TVOS17

2023-09-13T15:55:06Z

NickParrucci: /* Integration Guide */

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

__NOTOC__
===<span style="color: #ff0000;">Please note: this page will be updated as more information becomes available from Apple</span>===

== Overview ==
Beginning with iOS/tvOS 17, Apple is adding several requirements for App developers around tracking, use of Identifier For Advertisers (IDFA), and certain system APIs as detailed below:
===App Privacy Manifest===
*App privacy manifest files must be updated before submitting apps to the App Store.
**Declare collection/use of user tracking information - app developers/third-party SDKs will be required to list domains that are used to send messages containing the user's device ID (IDFA).
***[https://developer.apple.com/documentation/bundleresources/privacy_manifest_files?changes=_4 Apple:Privacy manifest files]
**Required Reason API - Apple is requiring reasons for apps' usage of certain system APIs that retrieve information about the device or state of some system metrics.
***[https://developer.apple.com/documentation/bundleresources/privacy_manifest_files/describing_use_of_required_reason_api Apple:Describing use of required reason API]

===App Tracking Transparency (ATT) Framework===
When users select "Ask App Not to Track" from the ATT popup, the operating system will behave differently from previous iOS/tvOS versions:
</br>
*In iOS/tvOS versions lower than 17, when "Ask App Not to Track" was selected, apps were blocked from reading the device's IDFA and measurement would be transmitted with a blank device ID.
*With iOS/tvOS 17, if the user selects "Ask App Not to Track", third-party SDKs will not only be blocked from reading the IDFA, the SDKs will also be blocked from sending http(s) traffic to domains declared as "tracking domains" in the SDK's privacy manifest file. This will prevent typical measurement pings from going out and will impact volumetric measurement for your apps.
</br>
A new release of the AppSDK (v9.2) aims to address this requirement through explicit distinction of tracking versus non-tracking traffic through the use of 2 domains as described below:
*When a user has opted in (Allow Tracking), measurement data pings will continue to be sent to the imrworldwide.com domain with the available IDFA.
*When a user has opted out (Ask App Not to Track) or with an unknown status, all the measurement data pings will be sent to the non-tracking domain nmrodam.com. These pings will not contain any IDFA tracking.

==Next Steps==
#Move to the latest Nielsen AppSDK release for builds targeting iOS 17 with Xcode 15. Upgrading to the new build of the Digital SDKs should be straightforward through your build configuration. AppSDKs remain backwards compatible and would not require any further integration changes. Please refer to the Integration guide section for further details.
#To be decided if the privacy manifest needs to be modified. For coexisting DAR pixel and Digital SDK integrations please reach out to your Nielsen Client Engineer to determine the path forward.
#Work with your Nielsen Client Engineer once implemented to ensure proper measurement.

==Technical Details==
Technical details about the upcoming iOS/tvOS AppSDK release for Nielsen client app developers will be coming soon.

This page will be updated as more information becomes available.

Nielsen Digital Measurement and iOS17 or TVOS17

2023-09-06T18:17:21Z

NickParrucci: /* Next Steps */

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

__NOTOC__
===<span style="color: #ff0000;">Please note: this page will be updated as more information becomes available from Apple</span>===

== Overview ==
Beginning with iOS/tvOS 17, Apple is adding several requirements for App developers around tracking, use of Identifier For Advertisers (IDFA), and certain system APIs as detailed below:
===App Privacy Manifest===
*App privacy manifest files must be updated before submitting apps to the App Store.
**Declare collection/use of user tracking information - app developers/third-party SDKs will be required to list domains that are used to send messages containing the user's device ID (IDFA).
***[https://developer.apple.com/documentation/bundleresources/privacy_manifest_files?changes=_4 Apple:Privacy manifest files]
**Required Reason API - Apple is requiring reasons for apps' usage of certain system APIs that retrieve information about the device or state of some system metrics.
***[https://developer.apple.com/documentation/bundleresources/privacy_manifest_files/describing_use_of_required_reason_api Apple:Describing use of required reason API]

===App Tracking Transparency (ATT) Framework===
When users select "Ask App Not to Track" from the ATT popup, the operating system will behave differently from previous iOS/tvOS versions:
</br>
*In iOS/tvOS versions lower than 17, when "Ask App Not to Track" was selected, apps were blocked from reading the device's IDFA and measurement would be transmitted with a blank device ID.
*With iOS/tvOS 17, if the user selects "Ask App Not to Track", third-party SDKs will not only be blocked from reading the IDFA, the SDKs will also be blocked from sending http(s) traffic to domains declared as "tracking domains" in the SDK's privacy manifest file. This will prevent typical measurement pings from going out and will impact volumetric measurement for your apps.
</br>
A new release of the AppSDK (v9.2) aims to address this requirement through explicit distinction of tracking versus non-tracking traffic through the use of 2 domains as described below:
*When a user has opted in (Allow Tracking), measurement data pings will continue to be sent to the imrworldwide.com domain with the available IDFA.
*When a user has opted out (Ask App Not to Track) or with an unknown status, all the measurement data pings will be sent to the non-tracking domain nmrodam.com. These pings will not contain any IDFA tracking.

==Next Steps==
#Move to the latest Nielsen AppSDK release for builds targeting iOS 17 with Xcode 15. Upgrading to the new build of the Digital SDKs should be straightforward through your build configuration. AppSDKs remain backwards compatible and would not require any further integration changes. Please refer to the Integration guide section for further details.
#To be decided if the privacy manifest needs to be modified. For coexisting DAR pixel and Digital SDK integrations please reach out to your Nielsen Client Engineer to determine the path forward.
#Work with your Nielsen Client Engineer once implemented to ensure proper measurement.

==Integration Guide==
Technical details about the upcoming iOS/tvOS AppSDK release for Nielsen client app developers will be coming soon.

This page will be updated as more information becomes available.

Nielsen Digital Measurement and iOS17 or TVOS17

2023-09-06T18:15:42Z

NickParrucci: Created page with "{{Breadcrumb|}} {{Breadcrumb|Digital}} {{Breadcrumb|DCR & DTVR}} {{CurrentBreadcrumb}} Category:Digital __NOTOC__ ===<span style="color: #ff0000;">Please note: this page..."

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

__NOTOC__
===<span style="color: #ff0000;">Please note: this page will be updated as more information becomes available from Apple</span>===

== Overview ==
Beginning with iOS/tvOS 17, Apple is adding several requirements for App developers around tracking, use of Identifier For Advertisers (IDFA), and certain system APIs as detailed below:
===App Privacy Manifest===
*App privacy manifest files must be updated before submitting apps to the App Store.
**Declare collection/use of user tracking information - app developers/third-party SDKs will be required to list domains that are used to send messages containing the user's device ID (IDFA).
***[https://developer.apple.com/documentation/bundleresources/privacy_manifest_files?changes=_4 Apple:Privacy manifest files]
**Required Reason API - Apple is requiring reasons for apps' usage of certain system APIs that retrieve information about the device or state of some system metrics.
***[https://developer.apple.com/documentation/bundleresources/privacy_manifest_files/describing_use_of_required_reason_api Apple:Describing use of required reason API]

===App Tracking Transparency (ATT) Framework===
When users select "Ask App Not to Track" from the ATT popup, the operating system will behave differently from previous iOS/tvOS versions:
</br>
*In iOS/tvOS versions lower than 17, when "Ask App Not to Track" was selected, apps were blocked from reading the device's IDFA and measurement would be transmitted with a blank device ID.
*With iOS/tvOS 17, if the user selects "Ask App Not to Track", third-party SDKs will not only be blocked from reading the IDFA, the SDKs will also be blocked from sending http(s) traffic to domains declared as "tracking domains" in the SDK's privacy manifest file. This will prevent typical measurement pings from going out and will impact volumetric measurement for your apps.
</br>
A new release of the AppSDK (v9.2) aims to address this requirement through explicit distinction of tracking versus non-tracking traffic through the use of 2 domains as described below:
*When a user has opted in (Allow Tracking), measurement data pings will continue to be sent to the imrworldwide.com domain with the available IDFA.
*When a user has opted out (Ask App Not to Track) or with an unknown status, all the measurement data pings will be sent to the non-tracking domain nmrodam.com. These pings will not contain any IDFA tracking.

==Next Steps==
#Move to the latest Nielsen AppSDK release for builds targeting iOS 17 with Xcode 15. Upgrading to the new build of the Digital SDKs should be straightforward through your build configuration. AppSDKs remain backwards compatible and would not require any further integration changes. Please refer to the Integration guide section for further details.
#To be decided if the privacy manifest needs to be modified. For coexisting DAR pixel and Digital SDK integrations please reach out to your Nielsen Client Engineer to determine the path forward.
#Work with your Nielsen Client Engineer once implemented to ensure proper measurement

==Integration Guide==
Technical details about the upcoming iOS/tvOS AppSDK release for Nielsen client app developers will be coming soon.

This page will be updated as more information becomes available.

DCR Chromecast browser SDK

2023-09-05T18:27:10Z

NickParrucci: /* SENDER side */

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

== 1. General Cast architecture ==
<br />
[[File:GeneralCastArch.png||600px|center|]]
See https://developers.google.com/cast/docs/developers

=== Sender App ===
is a user controlled JavaScript/HTML5 application which can run on browsers in mobile or desktop devices.

=== Receiver App ===
is an HTML5/JavaScript application placed at a custom URL that handles communication between the Sender app and the Chromecast device.

== 2. Cast scenarios ==

=== 2.1 Pure casting scenario ===
In the Pure casting scenario the video plays on the Chromecast device, while playback stops on the sender app <br />
The sender app should not pass any Nielsen API calls once the pure casting scenario starts. All Nielsen API calls are handled by the receiver app.
[[File:NielsenChromecastCast.png|600px|center]]

=== 2.2 Chromecast mirroring scenario ===
In the Chromecast mirroring scenario the video plays on both the sender and receiver apps. <br />
[[File:NielsenChromecastMirror.png|600px|center]]

== 3.Sender App JavaScript - Nielsen Browser SDK implementation ==

=== 3.1 General ===
By adding the below cast-specific API calls alongside the standard implementation of the Nielsen Browser SDK, a sender app can pass appropriate cast-specific metadata.

=== 3.2 API calls ===

==== 3.2.1 updateOTT ====
The below call should be made to the Browser SDK whenever the player switches from not casting to casting and vice versa.
<br />
<syntaxhighlight lang="java">
nolSDKInstance.ggPM('updateOTT',contentMetadataObject);
</syntaxhighlight>
<br />
Use the updateOTT method to notify the casting BrowserSDK instance whether the remote OTT device (like Google ChromeCast, Roku, Amazon FireTV, etc.) is connected or disconnected (indicated by "ottStatus").

When the OTT device is connected, call updateOTT with "ottStatus": "1" as well as a set of OTT device related parameters in the contentMetadataObject.
<syntaxhighlight lang="java">
var contentMetadataObject ={
type: "content",
ottStatus: "1",
ottType: "casting",
ottDevice: "chromecast",
ottDeviceName: "Google Chromecast",
ottDeviceID: nolSDKInstance.getId(),
ottDeviceManufacturer: "Google",
ottDeviceModel: "ChromeCastModel",
ottDeviceVersion: "1.0.0"
};

</syntaxhighlight>

When the OTT device is disconnected, call updateOTT with “ottStatus”: “0”.

==== 3.2.2 getOptOutStatus() and sessionId ====
<br />
Assign the below mediaInfo metadata parameters in the target load so that they may be passed to the receiver at the beginning of the casting session.
<syntaxhighlight lang="java">
mediaInfo.metadata.kGCKMetadataNlsKeyDeviceID = nolSDKInstance.sessionId; //Session Id
mediaInfo.metadata.kGCKMetadataNlsKeyOptout = nolSDKInstance.getOptOutStatus(); //OptOut status
</syntaxhighlight><br />
Below is a sample code snippet on how the sender browser app should retrieve and relay the information from sender to receiver app.<br />
<syntaxhighlight lang="java">
var mediaInfo = new chrome.cast.media.MediaInfo(
this.mediaContents[mediaIndex]['sources'][0], 'video/mp4');

mediaInfo.metadata = new chrome.cast.media.GenericMediaMetadata();
mediaInfo.metadata.metadataType = chrome.cast.media.MetadataType.GENERIC;
mediaInfo.metadata.title = this.mediaContents[mediaIndex]['title'];
mediaInfo.metadata.length = this.currentMediaDuration;
mediaInfo.metadata.images = [
{'url': MEDIA_SOURCE_ROOT + this.mediaContents[mediaIndex]['thumb']}];

/*Adding custom parameters in metadata to be passed to receiver*/
mediaInfo.metadata.kGCKMetadataNlsKeyDeviceID = nolSDKInstance.sessionId; //Session Id
mediaInfo.metadata.kGCKMetadataNlsKeyOptout = nolSDKInstance.getOptOutStatus(); //OptOut status

var request = new chrome.cast.media.LoadRequest(mediaInfo);
castSession.loadMedia(request).then(
this.playerHandler.loaded.bind(this.playerHandler),
function (errorCode) {
this.playerState = PLAYER_STATE.ERROR;
console.log('Remote media load error: ' +
CastPlayer.getErrorMessage(errorCode));
}.bind(this));
</syntaxhighlight>

== 4. Summary - Sequence of API calls ==
Below is the sequence of API calls from the beginning to the end of casting.

=== SENDER side ===
1) If the video is playing only on the Sender App, the standard Nielsen Browser SDK API calls should be invoked.<br />
2) Once a user presses the cast icon and if the video is playing already, call browser sdk '''end()''' api. <br />
3) Inform the Browser SDK about the Chromecast's status (connected or disconnected) by calling '''updateOTT()''' and passing metadata object. <br />
4) Retrieve the OptOutStatus and sessionId.<br />
5) Pass the optOutStatus and sessionId into the MediaInfo metadata object.<br />
6) When the Start casting (the video should be stopped on the sender device).<br />

=== RECEIVER side ===
Playback has started at ChromeCast device (TV).<br />
7) Retrieve the MediaInfo metadata sent by the sender device. <br />
8) [https://engineeringportal.nielsen.com/docs/DCR_Video_Browser_SDK#Initialization_API_Call Instantiate] the Browser SDK. <br />
9) Pass content/ad metadata by calling '''loadMetaData()'''. <br />
10) Send '''updateOTT''' event to BSDK receiver instance, to relay the sender OTT metadata ( kGCKMetadataNlsKeyDeviceID and kGCKMetadataNlsKeyOptout) received from sender app.<br />
11) Pass content/ad playheads every second by calling '''setPlayheadPosition()'''. <br />
12) Based on the user's interactions or the playlist state, call '''stop()''' (once paused) or '''end()''' (once the content or casting has ended).<br />

=== SENDER side ===
Casting has ended and playback resumes on the sender device.<br />
13) Start a new session by calling content/ad '''loadMetaData()'''.<br />
14) Continue sending API calls as usual.<br />

Below is a sample code snippet on how the receiver app should retrieve the ottMetadata received from sender apps and relay the information to receiver BSDK instance.
<syntaxhighlight lang="java">
sampleplayer.CastPlayer.prototype.onLoad_ = function(event) {
var senderMetadata = event.data.media.metadata,
sessionId = senderMetadata.kGCKMetadataNlsKeyDeviceID,
optout = senderMetadata.kGCKMetadataNlsKeyOptout;
this.cancelDeferredPlay_('new media is loaded');
this.load(new cast.receiver.MediaManager.LoadInfo( (event.data), event.senderId));
var contentMetadata = {
"type": "content",
"dataSrc": "cms",
"assetid": "vid-123",
"assetName": "Test video",
"program": "Test program",
"title": "Clickbaby",
"length":”60”,
"segA": "CustomSegmentValueA",
"segB": "CustomSegmentValueB",
"segC": "CustomSegmentValueC"
};
window.nolSDKInstance.ggPM('loadMetadata', contentMetadata);
var ottMetadataObject ={
ottStatus: "1",
ottType: "casting",
ottDevice: "chromecast",
ottDeviceName: "Google Chromecast",
ottDeviceID: nolSDKInstance.getId(),
ottDeviceManufacturer: "Google",
ottDeviceModel: "ChromeCastModel",
ottDeviceVersion: "1.0.0",
kGCKMetadataNlsKeyOptout : optout,
kGCKMetadataNlsKeyDeviceID : sessionId
};
window.nolSDKInstance.ggPM('updateOTT', ottMetadataObject);};
</syntaxhighlight>
<br />
Chromecast Developer Documentation: <https://developers.google.com/cast/docs/developers> <br />
Browser SDK API Reference: <https://engineeringportal.nielsen.com/docs/Browser_SDK_API_Reference> <br />

DTVR Browser SDK

2023-08-25T20:36:34Z

NickParrucci: /* Configure API calls - setVolume */

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

== Prerequisites ==
Before you start the integration, you will need:
{| class="wikitable"
|-
! style="width: 30px;" |
! style="width: 15%;" | Item
! Description
! Source
|-
|| ☑ || '''App ID (apid)''' || Unique ID assigned to the player/site and configured by product. || Contact Nielsen
|}

== Configure SDK ==
There are two steps required for configuring your SDK: 1. Add Static Queue Snippet and 2. Create SDK Instance.

=== Add Static Queue Snippet ===
Add the following script tag to your website:

<syntaxhighlight lang="javascript">
<script>
! function(t, n) {
t[n] = t[n] || {
nlsQ: function(e, o, c, r, s, i) {
return s = t.document,
r = s.createElement("script"),
r.async = 1,
r.src = ("http:" === t.location.protocol ? "http:" : "https:") + "//cdn-gl.imrworldwide.com/conf/" + e + ".js#name=" + o + "&ns=" + n,
i = s.getElementsByTagName("script")[0],
i.parentNode.insertBefore(r, i),
t[n][o] = t[n][o] || {
g: c || {},
ggPM: function(e, c, r, s, i) {
(t[n][o].q = t[n][o].q || []).push([e, c, r, s, i])
}
}, t[n][o]
}
}
}
(window, "NOLBUNDLE");
</script>
</syntaxhighlight>

The static queue snippet allows the SDK APIs to be called while the actual SDK and configuration file are still being downloaded. Since the queue is able to capture all API calls before the download completes, there is no wait time. Once the SDK is available, the API calls will transition from directing to the queue to the SDK seamlessly.

=== Create SDK Instance ===
To initialize the SDK, you will need to create an SDK instance by making the initialization call:

<syntaxhighlight lang="javascript">
NOLBUNDLE.nlsQ("<apid>", "<instanceName>",{nol_sdkDebug: "debug"})
</syntaxhighlight>
<br />
When creating your instance, you will need to pass three parameter values. The available parameters are listed in the table below:

{| class="wikitable"
|-
! Parameters !! Description !! Value !! Required? (Y/N)
|-
| apid || UniqueID assigned to player/site.
|| "XXXXXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXX" || Yes
|-
| instanceName || User-defined string value for describing the player/site. || Client specified || Yes
|-
| nol_sdkDebug:"debug" || Enables Debug Mode which allows output to be viewed in console. || "{nol_sdkDebug: "debug"}" || No
|-
| containerId || HTML DOM element id of the player container || {"containerId: "player1"} || Yes - if implementing Viewability/Audibility
|}

== SDK Initialization ==
<syntaxhighlight lang="javascript">
var nSdkInstance = NOLBUNDLE.nlsQ("XXXXXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXX", "nlsnInstance", {nol_sdkDebug: "debug"});
</syntaxhighlight>

When the initialization call is made, a unique static configuration file, <apid>.js, will be downloaded based on your apid and cached on the user's browser.

Once the configuration is downloaded, the SDK itself will be downloaded and initialized. All SDK modules are included in one file: "nlsSDK600.bundle.min.js".

=== Example SDK Initialization ===
Your configuration should include the Static Queue Snippet and an SDK Instance for your unique App ID as shown in the example:

<syntaxhighlight lang="javascript">

//Add Static Queue Snippet
<script>
! function(t, n) {
t[n] = t[n] || {
nlsQ: function(e, o, c, r, s, i) {
return s = t.document,
r = s.createElement("script"),
r.async = 1,
r.src = ("http:" === t.location.protocol ? "http:" : "https:") + "//cdn-gl.imrworldwide.com/conf/" + e + ".js#name=" + o + "&ns=" + n,
i = s.getElementsByTagName("script")[0],
i.parentNode.insertBefore(r, i),
t[n][o] = t[n][o] || {
g: c || {},
ggPM: function(e, c, r, s, i) {
(t[n][o].q = t[n][o].q || []).push([e, c, r, s, i])
}
}, t[n][o]
}
}
}
(window, "NOLBUNDLE");

//Create SDK Instance
var nSdkInstance = NOLBUNDLE.nlsQ("XXXXXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXX", "nlsnInstance", {nol_sdkDebug: "debug"});
</script>
</syntaxhighlight>

== SDK Initialization to measure Viewability & Audibility ==
To support Viewability and Audibility metrics in the web page the integrator has to provide a tag value of the player view to let Nielsen SDK know that there is a player that needs to be tracked. It’s called the ‘containerId’ and it should be passed in as a string while initializing the Nielsen browser SDK.

<syntaxhighlight lang="javascript">

NOLBUNDLE.nlsQ("<apid>", "<instanceName>",{containerId: <playerElementID>, nol_sdkDebug: "debug"})

</syntaxhighlight>

=== Example SDK Initialization for Viewability & Audibility ===
Your configuration should include the Static Queue Snippet and an SDK Instance for your unique App ID as shown in the example:

<syntaxhighlight lang="javascript">

//Add Static Queue Snippet
<script>
! function(t, n) {
t[n] = t[n] || {
nlsQ: function(e, o, c, r, s, i) {
return s = t.document,
r = s.createElement("script"),
r.async = 1,
r.src = ("http:" === t.location.protocol ? "http:" : "https:") + "//cdn-gl.imrworldwide.com/conf/" + e + ".js#name=" + o + "&ns=" + n,
i = s.getElementsByTagName("script")[0],
i.parentNode.insertBefore(r, i),
t[n][o] = t[n][o] || {
g: c || {},
ggPM: function(e, c, r, s, i) {
(t[n][o].q = t[n][o].q || []).push([e, c, r, s, i])
}
}, t[n][o]
}
}
}
(window, "NOLBUNDLE");

//Create SDK Instance with containerId
var nSdkInstance = NOLBUNDLE.nlsQ("XXXXXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXX", "nlsnInstance", {containerId: "player1", nol_sdkDebug: "debug"});
</script>
</syntaxhighlight>

== Create Metadata Objects ==
<br />
There are two types of asset metadata:
<br />
*content: identify video
*ad: identify each ad
<br />
The metadata received for each asset is used for classification and reporting.
<br />
Metadata can be passed through key-values using the Nielsen reserved keys. User will need to set up content and ad objects with the required Nielsen keys as shown in the sample code below.
<br />

=== Content Metadata Object ===
<br />
Content metadata should remain constant throughout the completion of an episode or live stream.
<br />
{| class="wikitable"
|-
! Key !! Description !! Values !! Required
|-
| type || type of asset || "content" || ✓
|-
| adModel || linear vs dynamic ad model || * 1) - Linear – matches TV ad load * 2) Dynamic – Dynamic Ad Insertion (DAI) || ✓
|-
|}
<br/>
'''Example Content Object'''
<syntaxhighlight lang="javascript"> var contentMetadataObject =
{
type: 'content',
adModel: '1'
};</syntaxhighlight>

=== Ad Metadata Object ===
<br/>
If Ad is not ID3 tagged, then Ad metadata should be passed for each individual Ad, if ads are available during or before the stream begins.
<br/>
{| class="wikitable"
|-
! Keys !! Description !! Values !! Required
|-
| type || type of Ad || <code>'preroll'</code>, <code>'midroll'</code>, <code>'postroll'</code> <br> <code>'ad'</code> - If specific type can not be identified.|| ✓
|-
| assetid || unique ID assigned to ad || custom (no [[Special Characters]]) || ✓
|}
<br/>
'''Example Ad Object'''
<br/>
<syntaxhighlight lang="javascript"> var adMetadataObject =
{
assetid: 'AD-1',
type: 'preroll'
};</syntaxhighlight>

== SDK Events ==
<br/>
{| class="wikitable"
|-
! Event !! Parameter !! Description
|-
| 'loadMetadata' || content/Ad metadata object || Needs to be called at the beginning of each asset to pass type and adModel
|-
| 'sendID3' || Used to send the ID3 tag payload retrieved from the stream || Needs to be called at the beginning of playback
|-
| 'setVolume' || Used to pass in the player volume levels in % || Needs to be called when the player volume changes. This is applicable only for Audibility feature
|}

== Configure and fire API calls ==
<br />
The syntax for firing events is:
<syntaxhighlight lang="javascript"> nSdkInstance.ggPM("event", parameter object);</syntaxhighlight>
<br />
Event is passed in parameter 1 and the argument is passed in parameter 2.

=== Configure API calls - loadMetadata ===
<br />
Use [[loadMetadata (Browser)]] to pass the metadata object. The data must be passed as a JSON string.
<br />
<syntaxhighlight lang="javascript">nSdkInstance.ggPM("loadMetadata", metadataObject);</syntaxhighlight>

=== Configure API calls - sendID3 ===
<br />
Use [[sendID3 (Browser)]] to send ID3 payload of the HLS content being played. This will allow the ID3 payload to be sent every time an ID3 packet is received (approximately, once in every 10 seconds).
<br />
<syntaxhighlight lang="javascript">nSdkInstance.ggPM("sendID3", ID3_Payload);</syntaxhighlight>
<br />
==== Sample ID3 tags ====
<br />
<syntaxhighlight>
www.nielsen.com/X100zdCIGeIlgZnkYj6UvQ==/X100zdCIGeIlgZnkYj6UvQ==/AAAB2Jz2_k74GXSzx4npHuI_<wbr />JwJd3QSUpW30rDkGTcbHEzIMWleCzM-uvNOP9fzJcQMWQLJqzXMCAxParOb5sGijSV9dNM3QiBniJYGZ5GI-lL1fXTTN0IgZ4iWBmeRiPpS9AAAAAAAAAAAAAAAAAAAAAFJWFM5SVhTONNU=/00000/00000/00</syntaxhighlight>
<br />
<syntaxhighlight>www.nielsen.com/X100zdCIGeIlgZnkYj6UvQ==/R8WHe7pEBeqBhu8jTeXydg==/AAICoyitYqlxT7n6aZ0oMCGhe<wbr />Fi4CXFp46AMUPZz1lMr_M9tr3_cjee1SHqxrOiVerMDLeyn9xzocZSKwi746Re8vNOtpNCAZjYABs_J0R25IHpvOc1HS8<wbr />QHGgD5TgOJeS6gX100zdCIGeIlgZnkYj6UvVJWFNhSVhTiPE0=/00000/46016/00</syntaxhighlight>
<br />
<code>ID3_Payload</code> is the container to pass the retrieved ID3 tag from the streaming. The player should look for 'PRIV' ID3 tags and send 'owner' field (which typically starts from "www.nielsen.com") through this API. Refer to [[Browser SDK API Reference#Retrieving ID3 Tags|Browser SDK API Reference - Retrieving ID3 Tags]] for more information.
<br />
<br />
Refer to [[Browser SDK API Reference#Retrieving ID3 Tags|Browser SDK API Reference - Retrieving ID3 Tags]] section to know more details.

=== Configure API calls - setVolume ===
<br />
Use the setVolume(Browser) to send the player volume for Audibility feature. Player volume should be sent at the beginning of stream and whenever volume changes. By default the volumeLevel is set to -1. VolumeLevel is the Audibility percentage (0-100). If the player is muted, use volumeLevel of 0.

<br />
<syntaxhighlight lang="javascript">nSdkInstance.ggPM("setVolume", volumeLevel);</syntaxhighlight>



== SDK DTVR Event Sequence ==
<br/>
The sample event lifecycle can be used as a reference for identifying the order for calling events.
<br/>
<syntaxhighlight lang="javascript">
nSdkInstance.ggPM('loadMetadata', contentMetadataObject);
nSdkInstance.ggPM('sendID3', ID3_Payload); //call sendID3 every 10 seconds and stop calling during any playback interruptions
</syntaxhighlight>

{{Template:Browser_Privacy_and_Opt-Out}}

== Going Live ==
After the integration has been certified, users will need to make a couple of updates to the initialization call to ensure that player will be measured properly.
Disable debug logging by deleting {nol_sdkDebug: 'DEBUG'} from initialization call.

'''Example Production Initialization Call'''
<syntaxhighlight lang="javascript">
var nSdkInstance = NOLBUNDLE.nlsQ("XXXXXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXX", "nlsnInstance", { optout: "false"});
</syntaxhighlight>

Digital Measurement Metadata

2023-08-21T18:07:16Z

NickParrucci: /* Example Content Object */

{{Breadcrumb|}} {{Breadcrumb|Digital}} {{Breadcrumb|US DCR & DTVR}} {{CurrentBreadcrumb}}
[[Category:Digital]]
__NOTOC__
= Digital Metadata =
Digital Metadata can passed through key-values using the Nielsen reserved keys. The keys and values are listed by product below.

== Digital Content Ratings (DCR) Metadata ==
=== Video Metadata ===
{{DCR Content Metadata}}

==== Example Video Metadata Object ====
<syntaxhighlight lang="javascript">
var contentMetadataObject =
{
type: 'content',
assetid: 'VID-123456',
program: 'The Big Bang Theory',
title: 'The Pants Alternative S03E18', //no abbreviations or shorthand
length: '1320', //lengths in seconds
airdate: '2021-03-21T12:00:00Z',
isfullepisode: 'y',
adloadtype: '2',
segB: 'custom segment B', // optional
segC: 'custom segment C', // optional
crossId1: 'Standard Episode ID', // optional
crossId2: 'Content Originator' //optional
};
</syntaxhighlight>

=== Ad Metadata ===
The Ad Metadata (if applicable) should be passed for each individual ad.
{| class="wikitable"
|-
! Keys !! Description !! Values !! Required
|-
| type || type of Ad || <code>'preroll'</code>, <code>'midroll'</code>, <code>'postroll'</code> <br> <code>'ad'</code> - If specific type can not be identified.|| ✓
|-
| assetid || unique ID assigned to Ad || custom <br>(no [[Special Characters]]) || ✓
|}

==== Example Ad Object ====
<syntaxhighlight lang="javascript">
var adMetadataObject =
{
type: 'preroll',
assetid: 'AD-1'
};
</syntaxhighlight>

=== Static Metadata ===
{| class="wikitable"
|-
! Key !! Description !! Data Type !! Value !! Required?
|-
| type || asset type || fixed || <code>'static'</code> || Yes
|-
| assetid || Unique ID for each article || dynamic || custom <br>(no [[Special Characters]]) || Yes
|-
| section || section of each site (e.g. section value should be first level in page URL: website.com/section). Limit to 25 unique values || dynamic || custom <br>(no [[Special Characters]]) || Yes
|-
| segA || custom segment for reporting: Limit to 25 unique values across custom segments (segA + segB + segC) || dynamic || custom || No
|-
| segB || custom segment for reporting: Limit to 25 unique values across custom segments (segA + segB + segC) || dynamic || custom || No
|-
| segC || custom segment for reporting: Limit to 25 unique values across custom segments (segA + segB + segC) || dynamic || custom || No
|}

The values passed through the Nielsen keys will determine the breakouts that are seen in reporting. The custom segments (A, B & C) will roll into the sub-brand. To not use custom segments A, B and C, do not pass any value in these keys.

==== Example Static Metadata Object ====
<syntaxhighlight lang="javascript">
var contentMetadataObject =
{
type: 'static',
assetid: 'HHF887465-9486', // *DYNAMIC METADATA*: unique ID for each article **REQUIRED**
section: 'SPORTS', // *DYNAMIC METADATA*: section of site **REQUIRED**
segA: 'HD Videos', // *DYNAMIC METADATA*: custom segment
segB: '', // *DYNAMIC METADATA*: custom segment
segC: '' // *DYNAMIC METADATA*: custom segment
};
</syntaxhighlight>

== Digital TV Ratings (DTVR) Metadata ==
=== Content Metadata ===
{| class="wikitable"
|-
! Key !! Description !! Values !! Required
|-
| adModel || linear vs dynamic ad model || * 1) - Linear – matches TV ad load * 2) Dynamic – Dynamic Ad Insertion (DAI) || ✓
|-
|}
====Example Content Object====
<syntaxhighlight lang="javascript"> var contentMetadataObject =
{
adModel: '1'
};
</syntaxhighlight>

==== Custom Variables Extension ====
If you are looking for additional reporting options, reach out to us. We have a [[Custom Variables Extension]] and can work with you to obtain your desired reporting.

Digital Measurement Metadata

2023-08-21T18:06:55Z

NickParrucci:

{{Breadcrumb|}} {{Breadcrumb|Digital}} {{Breadcrumb|US DCR & DTVR}} {{CurrentBreadcrumb}}
[[Category:Digital]]
__NOTOC__
= Digital Metadata =
Digital Metadata can passed through key-values using the Nielsen reserved keys. The keys and values are listed by product below.

== Digital Content Ratings (DCR) Metadata ==
=== Video Metadata ===
{{DCR Content Metadata}}

==== Example Video Metadata Object ====
<syntaxhighlight lang="javascript">
var contentMetadataObject =
{
type: 'content',
assetid: 'VID-123456',
program: 'The Big Bang Theory',
title: 'The Pants Alternative S03E18', //no abbreviations or shorthand
length: '1320', //lengths in seconds
airdate: '2021-03-21T12:00:00Z',
isfullepisode: 'y',
adloadtype: '2',
segB: 'custom segment B', // optional
segC: 'custom segment C', // optional
crossId1: 'Standard Episode ID', // optional
crossId2: 'Content Originator' //optional
};
</syntaxhighlight>

=== Ad Metadata ===
The Ad Metadata (if applicable) should be passed for each individual ad.
{| class="wikitable"
|-
! Keys !! Description !! Values !! Required
|-
| type || type of Ad || <code>'preroll'</code>, <code>'midroll'</code>, <code>'postroll'</code> <br> <code>'ad'</code> - If specific type can not be identified.|| ✓
|-
| assetid || unique ID assigned to Ad || custom <br>(no [[Special Characters]]) || ✓
|}

==== Example Ad Object ====
<syntaxhighlight lang="javascript">
var adMetadataObject =
{
type: 'preroll',
assetid: 'AD-1'
};
</syntaxhighlight>

=== Static Metadata ===
{| class="wikitable"
|-
! Key !! Description !! Data Type !! Value !! Required?
|-
| type || asset type || fixed || <code>'static'</code> || Yes
|-
| assetid || Unique ID for each article || dynamic || custom <br>(no [[Special Characters]]) || Yes
|-
| section || section of each site (e.g. section value should be first level in page URL: website.com/section). Limit to 25 unique values || dynamic || custom <br>(no [[Special Characters]]) || Yes
|-
| segA || custom segment for reporting: Limit to 25 unique values across custom segments (segA + segB + segC) || dynamic || custom || No
|-
| segB || custom segment for reporting: Limit to 25 unique values across custom segments (segA + segB + segC) || dynamic || custom || No
|-
| segC || custom segment for reporting: Limit to 25 unique values across custom segments (segA + segB + segC) || dynamic || custom || No
|}

The values passed through the Nielsen keys will determine the breakouts that are seen in reporting. The custom segments (A, B & C) will roll into the sub-brand. To not use custom segments A, B and C, do not pass any value in these keys.

==== Example Static Metadata Object ====
<syntaxhighlight lang="javascript">
var contentMetadataObject =
{
type: 'static',
assetid: 'HHF887465-9486', // *DYNAMIC METADATA*: unique ID for each article **REQUIRED**
section: 'SPORTS', // *DYNAMIC METADATA*: section of site **REQUIRED**
segA: 'HD Videos', // *DYNAMIC METADATA*: custom segment
segB: '', // *DYNAMIC METADATA*: custom segment
segC: '' // *DYNAMIC METADATA*: custom segment
};
</syntaxhighlight>

== Digital TV Ratings (DTVR) Metadata ==
=== Content Metadata ===
{| class="wikitable"
|-
! Key !! Description !! Values !! Required
|-
| adModel || linear vs dynamic ad model || * 1) - Linear – matches TV ad load * 2) Dynamic – Dynamic Ad Insertion (DAI) || ✓
|-
|}
====Example Content Object====
<syntaxhighlight lang="javascript"> var contentMetadataObject =
{
type: 'content',
adModel: '1'
};
</syntaxhighlight>
==== Custom Variables Extension ====
If you are looking for additional reporting options, reach out to us. We have a [[Custom Variables Extension]] and can work with you to obtain your desired reporting.

Digital Measurement iOS Cocoapods Guide

2023-08-16T14:49:43Z

NickParrucci:

{{Breadcrumb|}} {{Breadcrumb|Digital}} {{Breadcrumb|Digital Downloads}} {{Breadcrumb|Digital Measurement iOS Artifactory Guide}} {{CurrentBreadcrumb}}
[[Category:Digital]]

__NOTOC__
= How to install Nielsen SDK using CocoaPods =
CocoaPods is a dependency manager for Swift and Objective-C Cocoa projects. It has over 30 thousand libraries and is used in over 1.9 million apps. The Nielsen SDK now uses this distribution framework for improved version management and provides a Static and Dynamic Framework.

== Initial Configuration ==
The Nielsen SDK integration requires Cocoapods.
* The XCFramework which requires Cocoapods Version 1.10.1 or higher.
* The Dynamic Framework which requires Cocoapods Version 1.6.1 or higher.
* The Static Framework requires Cocoapods version 1.4.0. or higher.

The full installation guide for this framework is provided on the [https://guides.cocoapods.org/using/getting-started.html Getting Started] page, and how to set up the Podfile is mentioned in [https://guides.cocoapods.org/using/using-cocoapods.html Using Cocoapods] page.

== Repository Credentials ==
The first step is to add the credentials received from Nielsen into your .netrc file.
<blockquote>
[[Image:AlertIcon.png|left|60px|link=|class=smallIcon]] Starting on Sept 21, 2021 the Nielsen SDK has moved to a public repository. Credentials are no longer required.
</blockquote>
<br>

== Verify version of Cocoapods ==
First verify that Cocoapods is installed.
<syntaxhighlight lang=Javascript>
pod --version
</syntaxhighlight>
If it is not, then install.<br >
===== Install via gem =====
<syntaxhighlight lang=Javascript>
sudo gem install cocoapods
</syntaxhighlight>
===== Install using homebrew =====
<syntaxhighlight lang=Javascript>
brew install cocoapods
</syntaxhighlight>
== Add Cocoapod repository ==
=== XCFramework (Cocoapods 1.10.1+) ===
If using '''XCFramework''' (preferred approach), from the command line, type the following:
<syntaxhighlight lang=Javascript>
pod repo add NielsenAppSDK https://github.com/NielsenDigitalSDK/nielsenappsdk-ios-specs-dynamic.git
</syntaxhighlight>
Make sure you run the pod init command in your **project's directory.**
<syntaxhighlight lang=Javascript>
pod init
</syntaxhighlight>
<br>You now need to slightly modify the PodFile that was created in this directory. From the command line, you can use vi or vim to edit. <br> The following must be in the PodFile:
==== Podfile ====
<syntaxhighlight lang=Javascript>
platform :ios, '14.0'
source 'https://github.com/NielsenDigitalSDK/nielsenappsdk-ios-specs-dynamic.git'
source 'https://github.com/CocoaPods/Specs.git'

target 'YourProjectsNameHere' do
use_frameworks!
#Pods for ApplicationTarget
pod 'NielsenAppSDK-XC'
end
</syntaxhighlight>

<blockquote>'''Note''': If you migrate from the iOS dynamic framework to the XCFramework, just add -XC suffix for the pod in the podfile. E.g. NielsenAppSDK should be replaced with NielsenAppSDK-XC. The same Github repo is used for both dynamic and XCFramework.</blockquote>

<blockquote>'''Note''': Although official CocoaPods source is implicit but once you specify NielsenAppSDK source, then CocoaPods source will need to be included in PodFile if you are using some other third party pods along with NielsenAppSDK. Further details are mentioned here https://guides.cocoapods.org/syntax/podfile.html#source</blockquote>

<blockquote>'''Note on TVOS''': Nielsen AppSDK clients with applications on TVOS platform should take into account that TVOS slices are now part of the same XCFramework with iOS slices, so the XCFramework name is the same for both iOS and TVOS. But the TVOS framework imported in the application still has TVOS in its name. This is needed to reduce the number of changes in the existing apps. The code below should be added into the podfiles for TVOS XCFramework users:</blockquote>

<syntaxhighlight lang=Javascript>
# modify XCFramework configuration files to update NielsenAppApi.framework -> NielsenTVAppApi.framework
post_install do |installer|
installer.pods_project.targets.each do |target|
if target.name == 'Pods-NielsenVideoPlayerTVOSPodsXC'
# update Pods-NielsenVideoPlayerTVOSPodsXC.debug.xcconfig file
# update Pods-NielsenVideoPlayerTVOSPodsXC.release.xcconfig file
target.build_configurations.each do |config|
xcconfig_path = config.base_configuration_reference.real_path
puts "post_install: Found #{File.basename(xcconfig_path)}"
xcconfig = File.read(xcconfig_path)
new_xcconfig = xcconfig.sub('-framework "NielsenAppApi"', '-framework "NielsenTVAppApi"')
File.open(xcconfig_path, "w") { |file| file << new_xcconfig }
puts "post_install: Updated #{File.basename(xcconfig_path)} file with a value: NielsenTVAppApi.framework"
end
# update Pods-NielsenVideoPlayerTVOSPodsXC-frameworks.sh file
frameworksh_path = "Pods/Target Support Files/#{target.name}/#{target.name}-frameworks.sh"
if File.exist?(frameworksh_path)
puts "post_install: Found #{File.basename(frameworksh_path)}"
text = File.read(frameworksh_path)
new_contents = text.gsub('NielsenAppApi.framework', 'NielsenTVAppApi.framework')
File.open(frameworksh_path, "w") {|file| file.puts new_contents}
puts "post_install: Updated #{File.basename(frameworksh_path)} file with a value: NielsenTVAppApi.framework"
end
end
end
end
</syntaxhighlight>
<blockquote>If you migrate from the TVOS dynamic framework to the XCFramework, please note that TVOS slices are now part of the same XCFramework with iOS slices. So in addition to appending of the -XC suffix to the pod name in the podfile please remove TVOS. E.g. the naming for the pod NielsenTVOSAppSDK should be changed to NielsenAppSDK-XC.</blockquote>

=== Dynamic Framework (Cocoapods 1.6.1+) ===
<blockquote>'''Note''': We highly recommend to migrate to XCFramework for all our clients.</blockquote>
If using '''Dynamic Framework''', from the command line, type the following:
<syntaxhighlight lang=Javascript>
pod repo add NielsenAppSDK https://github.com/NielsenDigitalSDK/nielsenappsdk-ios-specs-dynamic.git
</syntaxhighlight>
Make sure you run the pod init command in your **project's directory.**
<syntaxhighlight lang=Javascript>
pod init
</syntaxhighlight>
<br>You now need to slightly modify the PodFile that was created in this directory. From the command line, you can use vi or vim to edit. <br> The following must be in the PodFile:
==== Podfile ====
<syntaxhighlight lang=Javascript>
platform :ios, '11.0'
source 'https://github.com/NielsenDigitalSDK/nielsenappsdk-ios-specs-dynamic.git'

target 'YourProjectsNameHere' do
use_frameworks!
#Pods for ApplicationTarget
pod 'NielsenAppSDK'
end
</syntaxhighlight>
<blockquote>'''Note''': If you are building an application on a Mac with Apple M1 chip, please add the following fix to end of the podfile</blockquote>

<syntaxhighlight lang=Javascript>
post_install do |installer|
installer.pods_project.build_configurations.each do |config|
config.build_settings["EXCLUDED_ARCHS[sdk=iphonesimulator*]"] = "arm64"
end
end
</syntaxhighlight>

=== For Static Framework (Cocoapods 1.4+) ===
From the command line, type the following:
<syntaxhighlight lang=Javascript>
pod repo add NielsenAppSDK https://github.com/nielsendigitalsdk/nielsenappsdk-ios-specs.git
</syntaxhighlight>
Make sure you run the pod init command in your **project's directory.**
<syntaxhighlight lang=Javascript>
pod init
</syntaxhighlight>
<br>You now need to slightly modify the PodFile that was created in this directory. From the command line, you can use vi or vim to edit. <br> The following must be in the PodFile:
==== Podfile ====
<syntaxhighlight lang=Javascript>
platform :ios, '11.0'
source 'https://github.com/NielsenDigitalSDK/nielsenappsdk-ios-specs.git'

target 'YourProjectsNameHere' do
#Pods for ApplicationTarget
pod 'NielsenAppSDK'
end
</syntaxhighlight>
<blockquote>'''Note''': If you are building an application on a Mac with Apple M1 chip, please add the following fix to end of the podfile</blockquote>

<syntaxhighlight lang=Javascript>
post_install do |installer|
installer.pods_project.build_configurations.each do |config|
config.build_settings["EXCLUDED_ARCHS[sdk=iphonesimulator*]"] = "arm64"
end
end
</syntaxhighlight>

''NOTE: You can have multiple pods within the Podfile''
<br>
<br>
To select a specific version of the Nielsen SDK, just append the build number. For example, this line is requesting XCFramework build 8.1.0.0:
<syntaxhighlight lang=javascript>
pod 'NielsenAppSDK-XC','8.1.0.0'
</syntaxhighlight>
<br>
If using version control, a warning message will be displayed within the console trace during the build of your app,
and it will show all sdk versions released to-date, allowing a developer to select a more recent build if desired.


== Execute Install ==
Once that has been edited, you can now execute the install:
<syntaxhighlight lang=Swift>
pod install
</syntaxhighlight>
<br>
Cocoapods will automatically create a new file with extension “.xcworkspace”. From this moment, that file should be used for using the target project instead of previous one with extension “.xcodeproj”. Inside of this workspace you will see “Pods” target which will include ready to use NielsenAppApi framework.

Open the file with the extension of <code>.xcworkspace</code> file using Xcode.

== Execute Update ==
When you want to retrieve latest Nielsen SDK version then please use pod update [Nielsen App Flavor Name]:
<syntaxhighlight lang=Swift>
pod update NielsenAppSDK-XC
</syntaxhighlight>
<br>

In case if you set specific version of the Nielsen SDK in your PodFile then you'll also need to update that specific version to latest version in your PodFile before executing pod update command:
<syntaxhighlight lang=Swift>
pod 'NielsenAppSDK-XC','9.0.0.0'
</syntaxhighlight>



== Pod Versions ==
The following Pod versions are now available: (For 'kids' apps, please use the NoId framework (EG: NielsenNoIdAppSDK-XC).

<blockquote>'''Note''': Nielsen SDK builds for tvOS are no longer distributed as separated packages. XCFramework allows to combine iOS and tvOS platforms in a single package. Please use the corresponding XCFramework while migrating from static or dynamic framework for tvOS. E.g. NielsenTVOSAppSDK -> NielsenAppSDK-XC.</blockquote>

{| class="wikitable" style="width: 30%;"
|- style="background-color:#efefef;"
! App Flavor Name
|-
| NielsenAppSDK-XC
|-
| NielsenNoAdAppSDK-XC
|-
| NielsenNoIdAppSDK-XC
|}

We highly recommend to migrate to XCFramework for all our clients. For clients who still have reasons to keep using the old framework packages in the application and do not migrate to XCFramework we distribute "fat" frameworks both static and dynamic for the release 8.1.0.0. Anyway, our plan to stop distributing "fat" frameworks for future releases and to distribute the Nielsen iOS SDK as an XCFramework only.

The following Pod versions are available: (For 'kids' apps, please use the NoId framework (EG: NielsenNoIdAppSDK, NielsenNoIdTVOSAppSDK)

{| class="wikitable" style="width: 30%;"
|- style="background-color:#efefef;"
! App Flavor Name
|-
| NielsenAppSDK
|-
| NielsenNoAdAppSDK
|-
| NielsenNoAdTVOSAppSDK
|-
| NielsenNoIdAppSDK
|-
| NielsenNoIdTVOSAppSDK
|-
| NielsenTVOSAppSDK
|}

=== Regional Builds ===
(For 'kids' apps, please use the NoId framework (EG: NielsenAGFNoIdAppSDK-XC, NielsenAGFNoIdTVOSAppSDK-XC)
{| class="wikitable" style="width: 30%;"
|- style="background-color:#efefef;"
! App Flavor Name
|-
| NielsenAGFAppSDK-XC
|-
| NielsenAGFNoAdAppSDK-XC
|-
| NielsenAGFNoIdAppSDK-XC
|}

Fat frameworks are still available for the release 8.1.0.0.

{| class="wikitable" style="width: 30%;"
|- style="background-color:#efefef;"
! App Flavor Name
|-
| NielsenAGFAppSDK
|-
| NielsenAGFNoAdAppSDK
|-
| NielsenAGFNoAdTVOSAppSDK
|-
| NielsenAGFNoIdAppSDK
|-
| NielsenAGFNoIdTVOSAppSDK
|-
| NielsenAGFTVOSAppSDK
|}

=== Appsdk Suffix Reference ===
The Nielsen AppSDK has various configurations per market and distribution type, which can be determined by reviewing the [[Digital Measurement iOS Suffix Guide|sdk suffix]]. The first part will be the SDK version: 3 digits for the major SDK version and 1 digit for the minor SDK version. EG: <code>ai.8.1.0.0_abc</code>

=== Pod Cache Cleanup ===
If you find any trouble while installing or updating latest Nielsen SDK version then you may need to clean up the pod cache by executing following commands:
<syntaxhighlight lang=Swift>
rm -rf ~/Library/Caches/CocoaPods
rm -rf Pods
rm -rf ~/Library/Developer/Xcode/DerivedData/*
pod deintegrate
pod setup
pod install
</syntaxhighlight>
<br>

=== Xcode 14 Bitcode Changes ===
Starting from Xcode 14, bitcode is no longer required for iOS, watchOS and tvOS applications, and the App Store no longer accepts bitcode submissions from Xcode 14. So if bitcode is enabled to Yes then following error may come while integrating through Cocoapods:

"Xcode setting ENABLE_BITCODE: obtain an updated library from the vendor, or disable bitcode for this target"

To Fix:
Target -> Build Settings -> Build Options -> set Enable Bitcode to No.

[[File:NielsenSamplePlayer.png|1000px|center]]

=== Additional Resources ===

For more information on [https://guides.cocoapods.org/using/getting-started.html CocoaPods] or How to set up the Profile in the [https://guides.cocoapods.org/using/using-cocoapods.html Using Cocoapods] page.
<br>
<br>

File:NielsenChromecastMirror.png

2023-07-31T19:09:00Z

NickParrucci:

mirroring diagram

File:NielsenChromecastCast.png

2023-07-31T19:08:24Z

NickParrucci:

cast diagram

DCR Chromecast browser SDK

2023-07-31T19:07:19Z

NickParrucci: Created page with "{{Breadcrumb|}} {{Breadcrumb|Digital}} {{Breadcrumb|DCR & DTVR}} {{CurrentBreadcrumb}} Category:Digital == 1. General Cast architecture == <br /> File:GeneralCastArch...."

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

== 1. General Cast architecture ==
<br />
[[File:GeneralCastArch.png||600px|center|]]
See https://developers.google.com/cast/docs/developers

=== Sender App ===
is a user controlled JavaScript/HTML5 application which can run on browsers in mobile or desktop devices.

=== Receiver App ===
is an HTML5/JavaScript application placed at a custom URL that handles communication between the Sender app and the Chromecast device.

== 2. Cast scenarios ==

=== 2.1 Pure casting scenario ===
In the Pure casting scenario the video plays on the Chromecast device, while playback stops on the sender app <br />
The sender app should not pass any Nielsen API calls once the pure casting scenario starts. All Nielsen API calls are handled by the receiver app.
[[File:NielsenChromecastCast.png|600px|center]]

=== 2.2 Chromecast mirroring scenario ===
In the Chromecast mirroring scenario the video plays on both the sender and receiver apps. <br />
[[File:NielsenChromecastMirror.png|600px|center]]

== 3.Sender App JavaScript - Nielsen Browser SDK implementation ==

=== 3.1 General ===
By adding the below cast-specific API calls alongside the standard implementation of the Nielsen Browser SDK, a sender app can pass appropriate cast-specific metadata.

=== 3.2 API calls ===

==== 3.2.1 updateOTT ====
The below call should be made to the Browser SDK whenever the player switches from not casting to casting and vice versa.
<br />
<syntaxhighlight lang="java">
nolSDKInstance.ggPM('updateOTT',contentMetadataObject);
</syntaxhighlight>
<br />
Use the updateOTT method to notify the casting BrowserSDK instance whether the remote OTT device (like Google ChromeCast, Roku, Amazon FireTV, etc.) is connected or disconnected (indicated by "ottStatus").

When the OTT device is connected, call updateOTT with "ottStatus": "1" as well as a set of OTT device related parameters in the contentMetadataObject.
<syntaxhighlight lang="java">
var contentMetadataObject ={
type: "content",
ottStatus: "1",
ottType: "casting",
ottDevice: "chromecast",
ottDeviceName: "Google Chromecast",
ottDeviceID: nolSDKInstance.getId(),
ottDeviceManufacturer: "Google",
ottDeviceModel: "ChromeCastModel",
ottDeviceVersion: "1.0.0"
};

</syntaxhighlight>

When the OTT device is disconnected, call updateOTT with “ottStatus”: “0”.

==== 3.2.2 getOptOutStatus() and sessionId ====
<br />
Assign the below mediaInfo metadata parameters in the target load so that they may be passed to the receiver at the beginning of the casting session.
<syntaxhighlight lang="java">
mediaInfo.metadata.kGCKMetadataNlsKeyDeviceID = nolSDKInstance.sessionId; //Session Id
mediaInfo.metadata.kGCKMetadataNlsKeyOptout = nolSDKInstance.getOptOutStatus(); //OptOut status
</syntaxhighlight><br />
Below is a sample code snippet on how the sender browser app should retrieve and relay the information from sender to receiver app.<br />
<syntaxhighlight lang="java">
var mediaInfo = new chrome.cast.media.MediaInfo(
this.mediaContents[mediaIndex]['sources'][0], 'video/mp4');

mediaInfo.metadata = new chrome.cast.media.GenericMediaMetadata();
mediaInfo.metadata.metadataType = chrome.cast.media.MetadataType.GENERIC;
mediaInfo.metadata.title = this.mediaContents[mediaIndex]['title'];
mediaInfo.metadata.length = this.currentMediaDuration;
mediaInfo.metadata.images = [
{'url': MEDIA_SOURCE_ROOT + this.mediaContents[mediaIndex]['thumb']}];

/*Adding custom parameters in metadata to be passed to receiver*/
mediaInfo.metadata.kGCKMetadataNlsKeyDeviceID = nolSDKInstance.sessionId; //Session Id
mediaInfo.metadata.kGCKMetadataNlsKeyOptout = nolSDKInstance.getOptOutStatus(); //OptOut status

var request = new chrome.cast.media.LoadRequest(mediaInfo);
castSession.loadMedia(request).then(
this.playerHandler.loaded.bind(this.playerHandler),
function (errorCode) {
this.playerState = PLAYER_STATE.ERROR;
console.log('Remote media load error: ' +
CastPlayer.getErrorMessage(errorCode));
}.bind(this));
</syntaxhighlight>

== 4. Summary - Sequence of API calls ==
Below is the sequence of API calls from the beginning to the end of casting.

=== SENDER side ===
1) If the video is playing only on the Sender App, the standard Nielsen Browser SDK API calls should be invoked.<br />
2) Once a user presses the cast icon and if the video is playing already, call browser sdk '''end()''' api. <br />
3) Inform the Browser SDK about the Chromecast's status (connected or disconnected) by calling '''updateOTT()''' and passing metadata object. <br />
4) Retrieve the OptOutStatus and sessionId.<br />
5) Pass the optOutStatus and sessionId into the MediaInfo metadata object.<br />
6) When the Start casting (the video should be stopped on the sender device).<br />

=== RECEIVER side ===
Playback has started at ChromeCast device (TV).<br />
7) Retrieve the MediaInfo metadata sent by the sender device. <br />
8) [https://engineeringportal.nielsen.com/docs/DCR_Video_Browser_SDK#Initialization_API_Call Instantiate] the Browser SDK. <br />
9) Pass content/ad metadata by calling '''loadMetaData()'''. <br />
10) Send '''updateOTT''' event to BSDK receiver instance, to relay the sender OTT metadata ( kGCKMetadataNlsKeyDeviceID and kGCKMetadataNlsKeyOptout) received from sender app.<br />
11) Pass content/ad playheads every second by calling '''setPlayheadPosition()'''. <br />
12) Based on the user's interactions or the playlist state, call '''stop()''' (once paused) or '''end()''' (once the content or casting has ended).<br />

=== SENDER side ===
Casting has ended and playback resumes on the sender device.<br />
13) Start a new session by calling content/ad '''loadMetaData()'''.<br />
14) Continue sending API calls as usual.<br />

Below is a sample code snippet on how the receiver app should retrieve the ottMetadata received from sender apps and relay the information to receiver BSDK instance.
<syntaxhighlight lang="java">
sampleplayer.CastPlayer.prototype.onLoad_ = function(event) {
var senderMetadata = event.data.media.metadata,
sessionId = senderMetadata.kGCKMetadataNlsKeyDeviceID,
optout = senderMetadata.kGCKMetadataNlsKeyOptout;
this.cancelDeferredPlay_('new media is loaded');
this.load(new cast.receiver.MediaManager.LoadInfo( (event.data), event.senderId));
var contentMetadata = {
"type": "content",
"dataSrc": "cms",
"assetid": "vid-123",
"assetName": "Test video",
"program": "Test program",
"title": "Clickbaby",
"length":”60”,
"segA": "CustomSegmentValueA",
"segB": "CustomSegmentValueB",
"segC": "CustomSegmentValueC"
};
window.nolSDKInstance.ggPM(15, contentMetadata);
var ottMetadataObject ={
ottStatus: "1",
ottType: "casting",
ottDevice: "chromecast",
ottDeviceName: "Google Chromecast",
ottDeviceID: nolSDKInstance.getId(),
ottDeviceManufacturer: "Google",
ottDeviceModel: "ChromeCastModel",
ottDeviceVersion: "1.0.0",
kGCKMetadataNlsKeyOptout : optout,
kGCKMetadataNlsKeyDeviceID : sessionId
};
window.nolSDKInstance.ggPM('updateOTT', ottMetadataObject);};
</syntaxhighlight>
<br />
Chromecast Developer Documentation: <https://developers.google.com/cast/docs/developers> <br />
Browser SDK API Reference: <https://engineeringportal.nielsen.com/docs/Browser_SDK_API_Reference> <br />

File:GeneralCastArch.png

2023-07-31T19:07:04Z

NickParrucci:

architechture diagram

iOS Step By Step

2023-07-27T13:30:19Z

NickParrucci:

iOS Step By Step

2023-07-27T13:29:26Z

NickParrucci:

{{Breadcrumb|}} {{Breadcrumb|Digital}} {{CurrentBreadcrumb}}
[[Category:Digital]]
__NOTOC__

Provided below are step-by-step quick start guides for implementing Nielsen iOS SDK for DCR Static, DCR Video, and DTVR products. Click each section to get started.

== → iOS DCR Static ==
<span class="mw-customtoggle-myDivision" style="color: cornflowerblue"> Show/hide DCR Static </span>
<div class="mw-collapsible mw-collapsed" id="mw-customcollapsible-myDivision">

==== iOS DCR Static Introduction ====
<span class="mw-customtoggle-myDivisiona-" style="color: cornflowerblue"> Show/hide Intro </span>
<div class="mw-collapsible mw-collapsed" id="mw-customcollapsible-myDivisiona-">

The Digital Content Ratings (DCR) Static product provides content consumption measurement in client mobile apps and webpages. This measurement includes insight into the total time a user spent on a webpage, how they navigated through the page via links, and many other data points.
This tutorial provides the steps to implement the DCR Static product in a sample iOS app. It includes:

*SDK Initialization Call
*DCR Static Metadata: information about the sections being tracked

By the end of this guide you will have the needed steps to integrate Nielsen's AppSDK in the background of your app.
</div>

=== iOS DCR Static Step 1 - Obtain AppID ===
<span class="mw-customtoggle-myDivisiona1" style="color: cornflowerblue"> Show/hide step 1 </span>
<div class="mw-collapsible mw-collapsed" id="mw-customcollapsible-myDivisiona1">

To begin using the iOS SDK (AppSDK) you will need to obtain an Application ID (AppId)

{| class="wikitable"
|-
! !! Item !! Description !! Source
|-
|✅ || App ID (appid) || Unique ID assigned to the player/site and configured by product || Contact your Nielsen TAM

|}

The appid is a 37 character unique ID assigned to the player/site and configured by product and is required when creating a new instance of the AppSDK in the app.
</br>Example: '''PXXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXX'''

</div>

==== iOS DCR Static Step 2 - SDK Initialization ====
<span class="mw-customtoggle-myDivisionc" style="color: cornflowerblue"> Show/hide step 2 </span>
<div class="mw-collapsible mw-collapsed" id="mw-customcollapsible-myDivisionc">

==== How to obtain the NielsenAppApi.Framework ====
The Nielsen AppSDK can either be downloaded directly or can be integrated directly within an application through the use of CocoaPods. We recommend using the CocoaPods-based integration whenever possible to ensure you maintain the most recent changes and enhancements to the Nielsen libraries.
* [[Digital_Measurement_iOS_Artifactory_Guide|Select to obtain CocoaPods implementation guide]]
* [[Special:Downloads|Select to Download Directly]]

==== Configuring Xcode Development Environment ====
Starting with SDK version 6.0.0.0, the Nielsen App SDK is compatible with Apple iOS versions 8.0 and above. In addition, when using the dynamic framework, all the required frameworks are linked automatically as the are needed. More details can be found here: https://stackoverflow.com/questions/24902787/dont-we-need-to-link-framework-to-xcode-project-anymore

<blockquote>'''Note''': All communications between the SDK and the Census (Collection Facility) use HTTPS.</blockquote>

==== Download Framework ====
The first step is to download and copy the [[Special:Downloads|NielsenAppApi.framework]] bundle to the app project directory. (''Not required if using CocaPods'')

==== Add Framework ====
In the General tab for app configuration add NielsenAppApi.framework in the list of Embedded Binaries. (''Not required if using CocaPods'')

==== Add Path ====
Add path to the NielsenAppApi.framework in the Framework Search Paths build setting. (''Not required if using CocaPods'')

==== Import Framework ====
Add NielsenAppApi.framework module in the source file of your app:

==== Using Swift ====
Add the following:
<syntaxhighlight lang="swift">
import NielsenAppApi
</syntaxhighlight>

==== Using Objective-C ====
<syntaxhighlight lang ="objective-c">
@import NielsenAppApi;
</syntaxhighlight>

=== Sample SDK Initialization Code ===
{{ExampleCode|
|Swift =
Swift 4.0 Example:
<code>NielsenInit.swift</code>
<syntaxhighlight lang="swift">
import Foundation
import NielsenAppApi

class NielsenInit : NSObject {
class func createNielsenApi(delegate: NielsenAppApiDelegate) -> NielsenAppApi?{

let appInformation:[String: String] = [
"appid": "PDA7D5EE6-B1B8-4123-9277-2A788XXXXXXX",
"sfcode": "dcr",
"nol_devDebug": "DEBUG"
]
return NielsenAppApi(appInfo:appInformation, delegate:delegate)
}
}
</syntaxhighlight>

Sample code using AVPlayer.
<code>LandingVC.swift</code>

<syntaxhighlight lang="swift">
import UIKit
import NielsenAppApi

class LandingVC: UIViewController, NielsenAppApiDelegate {

var nielsenMain : NielsenAppApi!
var sdkMethods : SDKMethods!
var data : [String : Any]!

class ViewController: UIViewController, NielsenAppApiDelegate, AVPlayerViewControllerDelegate {

// your code//

override func viewDidLoad() {
super.viewDidLoad()
//Getting the instance of NielsenApi
self.nielsenApi = NielsenInit.createNielsenApi(delegate: self)
}
}
override func viewDidAppear(_ animated: Bool) {
self.data = sdkMethods.loadStaticMaster() // This is just an example of populating the metadata
self.nielsenMain.loadMetadata(self.data)
}
</syntaxhighlight>
|Objective C =
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>
<syntaxhighlight lang="objective-c">
#import "NielsenInit.h"
#import <NielsenAppApi/NielsenEventTracker.h>

@implementation NielsenInit

+ (NielsenAppApi *)createNielsenAppApiWithDelegate:(id<NielsenAppApiDelegate>)delegate
{
//Initialising the NielsenEventTracker class by passing app information which returns the instance of NielsenEventTracker.

NSDictionary *appInformation = @{ @"appid": @"PDA7D5EE6-B1B8-4123-9277-2A788XXXXXXX",
@"appversion": @"1.0",
@"sfcode": @"dcr",
@"nol_devDebug": @"DEBUG", };

return [[NielsenAppApi alloc] initWithAppInfo:appInformation delegate:delegate];
}

@end
</syntaxhighlight>

The following would be the <code>NielsenInit.h</code> file:
<syntaxhighlight lang="objective-c">
#import <Foundation/Foundation.h>

@class NielsenAppApi;
@protocol NielsenAppApiDelegate;

@interface NielsenInit : NSObject

+ (NielsenAppApi *)createNielsenAppApiWithDelegate:(id<NielsenAppApiDelegate>)delegate;

@end
</syntaxhighlight>
Sample Code:
<syntaxhighlight lang="objective-c">
@implementation ViewController

- (void)viewDidLoad {
[super viewDidLoad];

//Getting the instance of Nielsen SDK
nielsenApi = [NielsenInit createNielsenAppApiWithDelegate:nil];
</syntaxhighlight>
}}

</div>

=== iOS DCR Static Step 3 - Create/Load DCR Static Metadata Object ===
<span class="mw-customtoggle-myDivisiond" style="color: cornflowerblue"> Show/hide step 3 </span>
<div class="mw-collapsible mw-collapsed" id="mw-customcollapsible-myDivisiond">

==== Configure Metadata ====
Map the Nielsen keys to variables so that the content metadata is dynamically updated.

The Nielsen reserved keys are:
{| class="wikitable"
|-
! Key !! Description !! Data Type !! Value !! Required?
|-
| type || asset type || fixed || <code>'static'</code> || Yes
|-
| assetid || Unique ID for each article || dynamic || custom <br>(no [[Special Characters]]) || No
|-
| section || section of each site (e.g. section value should be first level in page URL: website.com/section). Limit to 25 unique values || dynamic || custom || Yes
|-
| segA || custom segment for reporting: Limit to 25 unique values across custom segments (segA + segB + segC) || dynamic || custom || No
|-
| segB || custom segment for reporting: Limit to 25 unique values across custom segments (segA + segB + segC) || dynamic || custom || No
|-
| segC || custom segment for reporting: Limit to 25 unique values across custom segments (segA + segB + segC) || dynamic || custom || No
|}

The values passed through the Nielsen keys will determine the breakouts that are seen in reporting. The custom segments (A, B & C) will roll into the sub-brand. To not use custom segments A, B and C, do not pass any value in these keys.

==== Configure API calls - loadMetadata ====
Use [[loadMetadata]] to pass 'content' [[Digital Measurement Metadata]]. The CMS data must be passed as a JSON object.
<syntaxhighlight lang="java"> loadMetadata(JSONObject jsonMetadata);</syntaxhighlight>

<blockquote>Note: The [[loadMetadata]] call must have ("type": "static"). </blockquote>

Call [[loadMetadata]] with JSON metadata as below.
<syntaxhighlight lang="java"> new JSONObject()
.put("type", "static")
.put("section", "siteSection")
.put("assetid", "vid345-67483")
.put("segA", "segmentA")
.put("segB", "segmentB")
.put("segC","segmentC")
}</syntaxhighlight>

As soon as this loadMetadata call is made, AppSDK will record a view event and start tracking the section/page time spent (AppSDK 9.1 and above).

==== DCR Static Duration Measurement per Section/Page/Asset ====
If your Nielsen AppID is enabled for DCR Static duration measurement, a view event will be recorded and a timer will be started for each screen/page. Duration will be measured until a new page is loaded or the app is moved to the background. The event which triggers recognition of page view and timer start is the loadMetadata API call with a metadata object of type 'static'. Once a page is viewed and the timer has started, duration will be measured until a new page has loaded ''with associated loadMetadata call having a different '''section name''' from the previous page''. If a new loadMetadata call is made with the same '''section name''', it will be ignored - no new view will be recorded. If it is desired to have a new view event even though the metadata contains the same '''section name''' (example: single-page apps having several assedIDs but common section name), staticEnd API can be called between page views. For the purposes of this overview, staticend will not be used. See [[DCR_Static_iOS_SDK|this page]] for more information. <br>

</div>

=== Keep Going ===
<span class="mw-customtoggle-myDivisiong" style="color: cornflowerblue"> Show/hide </span>
<div class="mw-collapsible mw-collapsed" id="mw-customcollapsible-myDivisiong">

Congratulations, you've successfully integrated the iOS SDK in your app!

You can add static loadMetadata calls for more sections/pages in your app to see what happens when transitioning between sections.

View your application's debug logs and search for the term (AppSDK) to see messages emitted by Nielsen AppSDK.

</div>

=== Next Steps ===
<span class="mw-customtoggle-myDivisioni" style="color: cornflowerblue"> Show/hide </span>
<div class="mw-collapsible mw-collapsed" id="mw-customcollapsible-myDivisioni">

Now that you've integrated DCR Static for the AppSDK, what's next?

====Going Live====

In addition to the basic steps above, before going live developers need to handle app background/foreground events, make certain privacy disclosures, and allow users to opt out of Nielsen measurement. More details can be found [[DCR_Static_iOS_SDK|here]], along with a more comprehensive reference for implementing DCR Static measurement with AppSDK.

Once the DCR Tracking Code is added, Nielsen will validate the implementation. Following Nielsen testing, developers need to make a few updates to the initialization call to ensure that the app is being measured properly.

#'''App ID''': Ensure that correct is used during initialization '''PXXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX'''
#'''Debug Logging''': Disable logging by changing initialization call to use @"nol_devDebug":@"INFO".

</div>

</div>

== → iOS DCR Video ==

<span class="mw-customtoggle-myDivision1" style="color: cornflowerblue"> Show/hide DCR Video </span>
<div class="mw-collapsible mw-collapsed" id="mw-customcollapsible-myDivision1">
==== iOS DCR Video Introduction ====
<span class="mw-customtoggle-myDivisionv2-" style="color: cornflowerblue"> Show/hide Intro </span>
<div class="mw-collapsible mw-collapsed" id="mw-customcollapsible-myDivisionv2-">

The Digital Content Ratings (DCR) Video product provides content consumption measurement in client mobile apps and webpages. This measurement includes insight into the total time a user spent watching the tracked content, video player events, and much more.
This example provides the steps to implement the DCR Video product in a sample iOS app. It includes:

*SDK Initialization
*DCR Video Metadata: information about the content being tracked
*DCR Video Events/API calls

By the end of this guide you will have the needed steps to integrate Nielsen's AppSDK in the background of your app.

</div>

==== iOS DCR Video Step 1 - Obtain AppID ====
<span class="mw-customtoggle-myDivisionv3" style="color: cornflowerblue"> Show/hide step 1 </span>
<div class="mw-collapsible mw-collapsed" id="mw-customcollapsible-myDivisionv3">

To begin using the iOS AppSDK, you will need to obtain an Application ID (AppId)

{| class="wikitable"
|-
! !! Item !! Description !! Source
|-
|✅ || App ID (appid) || Unique ID assigned to the player/site and configured by product || Contact your Nielsen Representative

|}

The appid is a 37 character unique ID assigned to the player/site and configured by product and is required when creating a new instance of the AppSDK in the app.
</br>Example: '''PXXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXX'''

</div>

==== iOS DCR Video Step 2 - SDK Initialization ====
<span class="mw-customtoggle-myDivisionc" style="color: cornflowerblue"> Show/hide step 2 </span>
<div class="mw-collapsible mw-collapsed" id="mw-customcollapsible-myDivisionc">

===== How to obtain the NielsenAppApi.Framework =====
The Nielsen AppSDK can either be downloaded directly or can be integrated directly within an application through the use of CocoaPods. We recommend using the CocoaPods-based integration whenever possible to ensure you maintain the most recent changes and enhancements to the Nielsen libraries.
* [[Digital_Measurement_iOS_Artifactory_Guide|Select to obtain CocoaPods implementation guide]]
* [[Special:Downloads|Select to Download Directly]]

===== Configuring Xcode Development Environment =====
Starting with SDK version 6.0.0.0, the Nielsen App SDK is compatible with Apple iOS versions 8.0 and above. In addition, when using the dynamic framework, all the required frameworks are linked automatically as the are needed. More details can be found here: https://stackoverflow.com/questions/24902787/dont-we-need-to-link-framework-to-xcode-project-anymore

<blockquote>'''Note''': All communications between the SDK and the Census (Collection Facility) use HTTPS.</blockquote>

======= Download Framework =======
The first step is to download and copy the [[Special:Downloads|NielsenAppApi.framework]] bundle to the app project directory. (''Not required if using CocaPods'')

======= Add Framework =======
In the General tab for app configuration add NielsenAppApi.framework in the list of Embedded Binaries. (''Not required if using CocaPods'')

======= Add Path =======
Add path to the NielsenAppApi.framework in the Framework Search Paths build setting. (''Not required if using CocaPods'')

======= Import Framework =======
Add NielsenAppApi.framework module in the source file of your app:

======= Using Swift =======
Add the following:
<syntaxhighlight lang="swift">
import NielsenAppApi
</syntaxhighlight>

======= Using Objective-C =======
<syntaxhighlight lang ="objective-c">
@import NielsenAppApi;
</syntaxhighlight>

======= SDK Initialization =======

The following table contains the list of arguments that can be passed via the AppInfo JSON schema.
{| class="wikitable"
|-
! Parameter / Argument !! Description !! Source !! Required? !! Example
|--style="background-color:#d0f6f8;"
| appid || Unique Nielsen ID for the application. The ID is a GUID data type. If you did not receive your App ID, let us know and we will provide you. || Nielsen-specified || Yes || PXXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX
|--style="background-color:#d0f6f8;"
| nol_devDebug || Enables Nielsen console logging. Only required for testing <br>
|| Nielsen-specified || Optional || DEBUG
|}
==== Debug flag for development environment ====
Player application developers / integrators can use Debug flag to check whether an App SDK API call made is successful. To activate the Debug flag,
Pass the argument <code>@"nol_devDebug":@"DEBUG"</code>, in the JSON string .

Once the flag is active, it logs each API call made and the data passed. The log created by this flag is minimal.
<blockquote>'''Note''': DO NOT activate the Debug flag in a production environment.</blockquote>

=== Swift Example ===
==== Sample SDK Initialization Code ====

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

<br />
<code>ViewController.swift</code>

<syntaxhighlight lang="swift">
class ViewController: UIViewController, NielsenAppApiDelegate, AVPictureInPictureControllerDelegate, CLLocationManagerDelegate {

let avPlayerViewController = AVPlayerViewController()
var avPlayer:AVPlayer?
var nielsenAppApi: NielsenAppApi!

override func viewDidLoad() {
super.viewDidLoad()
self.nielsenAppApi = NielsenInit.createNielsenAppApi(delegate: self)
NSLog("Nielsen SDK initialized")
}}
</syntaxhighlight>

=== Objective C ===
==== Sample SDK Initialization Code ====
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>
<syntaxhighlight lang="objective-c">
#import "NlsAppApiFactory.h"
#import <NielsenAppApi/NielsenAppApi.h>

@implementation NlsAppApiFactory
+ (NielsenAppApi *)createNielsenAppApiWithDelegate:(id<NielsenAppApiDelegate>)delegate;
{
NSDictionary *appInformation = @{
@"appid": "PE392366B-F2C1-4BC4-AB62-A7DAFDC51XXX",
@"nol_devDebug": @"DEBUG"
};
return [[NielsenAppApi alloc] initWithAppInfo:appInformation delegate:delegate];
}
@end
</syntaxhighlight>

The following would be the <code>NlsAppApiFactory.h</code> file:
<syntaxhighlight lang="objective-c">
#import <Foundation/Foundation.h>

@class NielsenAppApi;
@protocol NielsenAppApiDeligate;
@interface NlsAppApiFactory : NSObject
+ (NielsenAppAPI *) createNielsenAppApiWithDelegate:(id<NielsenAppApiDelegate>)delegate;
@end
}}
</syntaxhighlight>
<br>
The following might be in the <code>Viewcontroller.m</code>
<syntaxhighlight lang="objective-c">
@implementation ViewController

- (void)viewDidLoad {
[super viewDidLoad];

//Setting background image
UIImage *backgroundImage = [UIImage imageNamed:@"new_ios_bg.png"];
UIImageView *backgroundImageView=[[UIImageView alloc]initWithFrame:self.view.frame];
backgroundImageView.image=backgroundImage;
[self.view insertSubview:backgroundImageView atIndex:0];

//Mark: In NielsenInit class we are initialising the Nielsen SDK.

//Getting the instance of Nielsen SDK
nielsenApi = [NielsenInit createNielsenAppApiWithDelegate:nil];
}
</syntaxhighlight>

</div>

==== iOS DCR Video Step 3 - Create DCR Video Content Metadata Object ====
<span class="mw-customtoggle-myDivisionv5" style="color: cornflowerblue"> Show/hide step 3 </span>
<div class="mw-collapsible mw-collapsed" id="mw-customcollapsible-myDivisionv5">

===== Configure Metadata =====
The SDK methods handle 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 Nielsen Key names (e.g. appid, program) 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.
<br>
===== Create channelName Metadata =====
channelName should remain constant throughout the completion of an episode or live stream.
<br />
{| class="wikitable"
|-
|--style="background-color:#d0f6f8;"
! Key !! Description !! Values !! Required
|--style="background-color:#d0f6f8;"
| channelName || Any string representing the channel/stream || custom || ✓
|-
|}

===== Create Content Metadata =====
Content metadata should remain constant throughout the entirety of an episode/clip including when ads play.
<blockquote> program and title metadata values should be passed to SDK as UTF-8 strings. </blockquote>
<div style="height: 45em; overflow-y:auto;"><br>
{| class="wikitable"
|-
! '''Keys''' !! '''Description''' !! '''Values''' !! '''Required'''!!'''Provider'''
|-
| type || Type of asset ||For Video use: <code>content</code><br> For Static or text <code>static</code> || Yes || Nielsen
|-style="background-color:#e9f9fa;"
| assetid || Unique ID assigned to asset <br> Note: Refrain from using the following special characters [[Special_Characters|(Special Characters)]]. || Examples: <br> <code>BBT345a234 </code> <br> <code>CBSs5e234F2021</code> || Yes || Client
|-
| program ||Complete program or movie title <br> (no abbreviations or shorthand) <br> Note: there is a 25 character limit. ||<code> The Big Bang Theory</code> <br> <code> TheBigBangTheory</code> <br><code> The Dark Knight</code> <br><code> TheDarkKnight</code> <br> || Yes || Client
|-style="background-color:#e9f9fa;"
| title ||Episode title with season and episode number (40 character limit) <br> (Formats accepted: S01E03, S1E3, S1 E3). || Examples: <br> <code>The Pants Alternative S03E18</code> <br> <code>The Pants Alternative S3E18</code> <br> <code>The Pants Alternative S3 E18</code> <br> Can also accept: <code> S3E18</code> <br> Not Valid: <code> 318 </code> or <code> 0318 </code>|| Yes || Client
|-
| crossId1 || Gracenote TMS ID (If available) should be passed for all telecasted content for clients using the Gracenote solution for proper matching purposes. <br>Note: The TMS ID will be a 14 character string. Normally leading with 2 alpha characerts ('EP', 'MV', 'SH' or 'SP'), followed by 12 numbers.
|| The TMS ID will be a 14 character string. <br> Normally being with 'EV,' 'EP', 'SH', 'SP', or 'MV' <br> Followed by 12 numbers after the initial two letter prefix. <br> <br> The Giant Morning Show: <code>SH009311820022</code> <br> The Pants Alternative Episode : <code>EP009311820061</code> || Optional || Nielsen
|-style="background-color:#e9f9fa;"
| crossId2 || Populated by content distributor to contribute viewing from that distributor to the given content originator. || For a full list of acceptable values, please contact your Nielsen reprentative. || Yes, for distributors || Nielsen
|-
| length || Length of content in seconds<br>Note: Integers and decimals are acceptable values are acceptable for the length parameter. || Examples:
<small>For standard VOD content - <code>300</code> to represent 5 minutes, <code>1320</code> to represent 22 minutes, etc.
<br>If DAI live stream of a discrete program (Live Event/Sporting Event), pass length of content. See example for standard VOD content above.
<br>If unknown DAI live steam, pass a value of <code>0</code>.</small>
|| Yes || Client
|-style="background-color:#e9f9fa;"
| airdate ||Original broadcast or release date for the program <br>For USA, date should be EST <br> Outside USA, date should be local time.<br>If not applicable or available, original broadcast or release date for the Program. || Acceptable Formats:<br><code>YYYY-MM-DDTHH:MI:SS</code><br><code>YYYY-MM-DDHH:MI:SS</code><br><code>YYYY-MM-DDTHH:MI:SS+xx:xx</code><br><code>YYYY-MM-DDTHH:MI:SS-xx:xx</code><br><code>YYYYMMDDHH:MI:SS</code><br><code>YYYYMMDD HH:MI:SS</code><br><code>MM-DD-YYYY</code><br><code>MM/DD/YYYY</code><br><code>YYYYMMDD</code></big> || Yes || Client
|-
| isfullepisode || Full episode flag to identify differences between long form content. || <code>y</code>- full episode, <code>n</code>- non full episode(clip,teaser,promo,etc.)
<small>Also accept:
<br><code>lf</code> or <code>yes</code>- longform
<br><code>sf</code> or <code>no</code>- shortform
|| Yes || Nielsen
|-style="background-color:#e9f9fa;"
| adloadtype || <big><small>Type of ad load:
<code>1</code> Linear – matches TV ad load<br><code>2</code> Dynamic – Dynamic Ad Insertion (DAI)</small></big>
|| <code>2</code> - DCR measures content with dynamic ads || Yes || Nielsen
|-
| segB || One of two custom segment for the clients granular reporting within a brand. || Examples:<br>Genre - <code>horror</code>, <code>comedy</code>, etc.<br>Timeslot - <code>primetime</code>, <code>daytime</code>, etc.<br>News type - <code>breakingnews</code>, <code>weather</code>, etc. || Optional || Client
|-style="background-color:#e9f9fa;"
| segC || One of two custom segment for the clients granular reporting within a brand. || Examples:<br>Genre - <code>horror</code>, <code>comedy</code>, etc.<br>Timeslot - <code>primetime</code>, <code>daytime</code>, etc.<br>News type - <code>breakingnews</code>, <code>weather</code>, etc. || Optional || Client
|}
</div>

Custom segments (segB and segC) can be used to aggregate video and/or static content within a single Brand to receive more granular reports within a brand.

Examples regarding usage of segments within SDK:
* All comedy clips and stories for a Brand rolled into a "Comedy" segment
* genre grouping content by Comedy vs. Drama
* group related Text + Video content - i.e. for a show that has a lot of - static pages associated with it
* packaging based on how clients sell inventory
* grouping related types of content either by genre, category or platform.
<br />

===== Metadata Example =====
<code>Swift</code>
<syntaxhighlight lang="swift">

let contentMetadata = [
"type": "content",
"assetid": "C77664",
"program": "The Big Bang Theory",
"title": "The Pants Alternative S03E18", //Formats accepted: S01E03, S1E3, S1 E3
"crossId1": "EP009311820061", //optional
"crossId2": "Content Originator", //optional
"length": "3600",
"airdate": "2022-03-21T10:05:00",
"isfullepisode": "Yes",
"adloadtype": "2",
"segB": "CustomSegmentValueB", //optional
"segC": "CustomSegmentValueC" //optional

];
</syntaxhighlight>
<br>
<code>Objective-C</code>
<syntaxhighlight lang="objective-c">
NSDictionary * contentMetadata = @ {
@ "type": @ "content",
@ "assetid": @ "C77664",
@ "program": @ "The Big Bang Theory",
@ "title": @ "The Pants Alternative S03E18", //Formats accepted: S01E03, S1E3, S1 E3
@ "crossId1": @ "EP009311820061", //optional
@ "crossId2": @ "Content Originator", //optional
@ "length": @ "3600",
@ "airdate": @ "2022-03-21T10:05:00",
@ "isfullepisode": @ "y",
@ "adloadtype": @ "2",
@ "segB": @ "CustomSegmentValueB", //optional
@ "segC": @ "CustomSegmentValueC" //optional

}
</syntaxhighlight>

</div>

==== iOS DCR Video Step 4 - Basic Set of Events - Sample Playback ====
<span class="mw-customtoggle-myDivisionv6" style="color: cornflowerblue"> Show/hide step 4 </span>
<div class="mw-collapsible mw-collapsed" id="mw-customcollapsible-myDivisionv6">

=== SDK Events ===
{| class="wikitable"
|-
! Event !! Parameter !! Description
|-
| 'play' || || Call at start of each new stream
|-
| 'loadMetadata' || content/ad metadata object || Needs to be called at the beginning of each asset
|-
| 'playheadPosition' || playhead position as integer<br/>
VOD: current position in seconds <br/>
Live: current UNIX timestamp (seconds since Jan-1-1970 UTC) <br/>
Note: 'PlayheadPosition' has to be called every second
||
Pass playhead position every second during playback
|-
| 'stop' || playhead position || Call during any interruption to content or Ad playback and at the end of each Ad.
|-
| 'end' || playhead position in seconds || Call when the current video asset completes playback and pass the playhead position. <br/>
Example: At the end of the content stream, if the user switches to another piece of content, when the browser is refreshed or closed.
|}
<blockquote>Note: For livestream, send the UNIX timestamp, for VOD send the time in seconds as integer. The final playhead position must be sent for the current asset being played before calling <code>'''stop'''</code>, <code>'''end'''</code> or<code> '''loadmetadata'''</code>,.</blockquote>

=== Life cycle of SDK instance ===
Life cycle of SDK instance includes four general states:
# '''Initial state''' – The SDK is not initialized and hence, not ready to process playing information. Once the SDK is moved out of this state, it needs instantiation of the new SDK instance in order to get the instance in the '''Idle state'''.
# '''Idle state''' – The SDK is initialized and is ready to process playing information. Once Initialized, the SDK instance is not processing any data, but is listening for an event to occur.
# '''Processing state''' – The SDK instance is processing playing information. The <code>'''play'''</code> and <code>'''loadMetadata''' </code> calls move the SDK instance into this state. In this state, the SDK instance will be able to process the following calls.
## <code>'''playheadPosition'''</code> – Call this API every one second when playhead position is active. If a LIVE event, use the current UNIX timestamp (seconds since Jan-1-1970 UTC).
## <code>'''stop'''</code> – Call this API when the content or Ad playback is interrupted and at the end of each Ad.
## <code>'''end'''</code> – Call when content completes. When called, the SDK instance exits from Processing state.
# '''Disabled state''' – The SDK instance is disabled and is not processing playing information.
## <code>'''appDisableApi'''</code> is set to <code>true</code>

<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 <code>'''loadMetadata''' </code> and <code>'''playheadPosition'''</code> </blockquote>

=== API Call Sequence ===
==== Sample Use Case: Content has no Advertisements ====
Call [[play()]] at start of stream

Call [[loadMetadata()]] with JSON metadata for content as below.
<syntaxhighlight lang="json">{
"type": "content",
"assetid": "vid345-67483",
"program": "ProgramName",
"title": "Program S3, EP1",
"length": "3600",
...
}</syntaxhighlight>
Call [[playheadPosition|playheadPosition()]] every one second until a pause / stop.
Use the sample API sequence below as a reference to identify the specific events that need to be called during content playback without ads.
{| class="wikitable"
|-
! Type !! Sample code !! Description
|-
| rowspan="2" | Start of stream || <code>mAppSdk.play(); </code> || // Call at start of each new stream
|-
| <code>mAppSdk.loadMetadata(contentMetaDataObject);</code> || // contentMetadataObject contains the JSON metadata for the content being played
|-style="background-color:#d8f5d7;"
| Content || <code>mAppSdk.setPlayheadPosition(playheadPosition);</code> || // position is position of the playhead while the content is being played
|-
| Interruption || <code>mAppSdk.stop();</code> || // call stop when content playback is interrupted
|-style="background-color:#d8f5d7;"
| rowspan="2" | Resume Content || <code>mAppSdk.loadMetadata(contentMetaDataObject);</code> || // Call loadMetadata and pass content metadata object when content resumes
|- style="background-color:#d8f5d7;"
|<code>mAppSdk.setPlayheadPosition(playheadPosition);</code> || // continue pasing playhead position every second starting from position where content is resumed
|-
| End of Stream || <code>mAppSdk.end();</code> || // Content playback is completed.
|}

</div>

==== Keep Going ====
<span class="mw-customtoggle-myDivisionv9" style="color: cornflowerblue"> Show/hide </span>
<div class="mw-collapsible mw-collapsed" id="mw-customcollapsible-myDivisionv9">

Congratulations, you've successfully integrated the iOS SDK in your app for a basic content playback scenario!

You can add more content to see channel-change scenarios or continue to next steps below.

View your application's debug logs and search for the term (AppSDK) to see messages emitted by Nielsen AppSDK during video playback.

</div>

==== Next Steps ====
<span class="mw-customtoggle-myDivisionv10" style="color: cornflowerblue"> Show/hide </span>
<div class="mw-collapsible mw-collapsed" id="mw-customcollapsible-myDivisionv10">
====Going Live====

In addition to the basic steps above, before going live developers need to handle app background/foreground events, make certain privacy disclosures, handle interruption events (stop, fast-forward, rewind), remove iOS simulator slices, and allow users to opt out of Nielsen measurement. More details can be found [[DCR_Video_iOS_SDK|here]], along with a more comprehensive reference for implementing DCR Video measurement with AppSDK.

Once the DCR Tracking Code is added, Nielsen will validate the implementation. Following Nielsen testing, developers need to make a few updates to the initialization call to ensure that the app is being measured properly.

#'''App ID''': Ensure that correct is used during initialization '''PXXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX'''
#'''Debug Logging''': Disable logging by changing initialization call to use @"nol_devDebug":@"INFO".

</div>

</div>

== → iOS DTVR (coming soon) ==

<syntaxhighlight lang="objectivec">
- (NSDictionary *)loadDtvr{

//Loading DTVR data
NSDictionary *dtvr = @{ @"adModel":@"1" ,
@"type":@"content",};
return dtvr;
}
</syntaxhighlight>
</div>

==== iOS DTVR Step 4 - Basic Set of Events - Sample Playback ====
<span class="mw-customtoggle-myDivisionv600" style="color: cornflowerblue"> Show/hide step 4 </span>
<div class="mw-collapsible mw-collapsed" id="mw-customcollapsible-myDivisionv600">

===== SDK Events/APIs =====

{| class="wikitable"
|-
! Event !! Parameter !! Description
|-
| 'loadMetadata' || content/ad metadata object || Needs to be called at the beginning of each asset to pass type and adModel.
|-
| 'sendID3' || Used to send the ID3 tag payload retrieved from the stream || Needs to be called at the beginning of playback
|}

===== Configure API calls - loadMetadata =====
Use <code>loadMetadata</code> to pass the metadata object created above.
{{ExampleCode|
|Objective C = <syntaxhighlight lang="objective-c">[nielsenApi loadMetadata:(dtvr)];</syntaxhighlight>
|Swift = <syntaxhighlight lang="swift">self.nielsenAppApi?.loadMetadata(dtvr)</syntaxhighlight>
}}

===== Configure API calls - sendID3 =====
[[sendID3]] API is a Nielsen AppSDK receiver for timed metadata events (ID3 tags) provided through iOS’s NSNotificationCenter notification system. This API filters out Nielsen-specific ID3 tags from the system and uses them to create duration data. These ID3 tags are used by Nielsen SDK for DTVR measurement, and the stream that is played must contain ID3 tags and have these tags extracted and passed to SDK using the below procedure in order for DTVR measurement to occur.
{{ExampleCode|
|Objective C = <syntaxhighlight lang="objective-c">[nielsenApi sendID3:extraString];</syntaxhighlight>
|Swift = <syntaxhighlight lang="swift"> [nielsenApi sendID3:extraString];</syntaxhighlight>}}
'''Sample ID3 tags'''
* <code>www.nielsen.com/X100zdCIGeIlgZnkYj6UvQ==/X100zdCIGeIlgZnkYj6UvQ==/AAAB2Jz2_k74GXSzx4npHuI_<wbr />JwJd3QSUpW30rDkGTcbHEzIMWleCzM-uvNOP9fzJcQMWQLJqzXMCAxParOb5sGijSV9dNM3QiBniJYGZ5GI-lL1fXTTN0IgZ4iWBmeRiPpS9AAAAAAAAAAAAAAAAAAAAAFJWFM5SVhTONNU=/00000/00000/00</code>
* <code>www.nielsen.com/X100zdCIGeIlgZnkYj6UvQ==/R8WHe7pEBeqBhu8jTeXydg==/AAICoyitYqlxT7n6aZ0oMCGhe<wbr />Fi4CXFp46AMUPZz1lMr_M9tr3_cjee1SHqxrOiVerMDLeyn9xzocZSKwi746Re8vNOtpNCAZjYABs_J0R25IHpvOc1HS8<wbr />QHGgD5TgOJeS6gX100zdCIGeIlgZnkYj6UvVJWFNhSVhTiPE0=/00000/46016/00</code>
Refer to [[iOS SDK API Reference#Retrieving ID3 Tags|Retrieving ID3 Tags]] section to know more details.

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

As Apple has deprecated the use of [https://developer.apple.com/documentation/avfoundation/avplayeritem/1389602-timedmetadata?language=objc timedMetadata], we now recommend using [https://developer.apple.com/documentation/avfoundation/avplayeritemmetadataoutput?language=objc AVPlayerItemMetadataOutput] for extracting ID3 tags from the iOS Native Player.

If any other player apart from the iOS native player is used, check and ensure that the player has the capability to extract metadata such as ID3 tags.

===== Examples of extracting ID3 tags from the iOS Native Player =====
{{ExampleCode|
|Swift = <syntaxhighlight lang="swift">
//First, ensure your class conforms to the AVPlayerItemMetadataOutputPushDelegate protocol.
class YourClass: AVPlayerItemMetadataOutputPushDelegate {

}
</syntaxhighlight>
------------------------------------------------------
<syntaxhighlight lang="swift">
// Then create an instance of AVPlayerItemMetadataOutput and add it to the player item
let metadataOutput = AVPlayerItemMetadataOutput(identifiers: nil)
playerItem.add(metadataOutput)

// and set the delegate and a dispatch queue
metadataOutput.setDelegate(self, queue: DispatchQueue.main)
</syntaxhighlight>
------------------------------------------------------
<syntaxhighlight lang="swift">
// After that below callback function of AVPlayerItemMetadataOutputPushDelegate
// protocol will be triggered whenever ID3 tag is received from stream.
func metadataOutput(_ output: AVPlayerItemMetadataOutput, didOutputTimedMetadataGroups groups: [AVTimedMetadataGroup], from track: AVPlayerItemTrack?) {
for group in groups {
for item in group.items {
// Handle the metadata item
handleTimedMetadata(metadataItem: item)
}
}
}
</syntaxhighlight>
------------------------------------------------------
<syntaxhighlight lang="swift">
// Then further metadata item can be handled like below
func handleTimedMetadata(metadataItem: AVMetadataItem) {
guard let key = metadataItem.key as? String,
let extraString = metadataItem.extraAttributes?[AVMetadataExtraAttributeInfoKey] as? String else {
return
}
// If the extra string(tag) starts with "www.nielsen.com", then only sending to SDK
if key == "PRIV" && extraString.hasPrefix("www.nielsen.com") {
DispatchQueue.global(qos: .default).async {
self.nielsenApi?.sendID3(extraString)
}
}
}

</syntaxhighlight>
|Objective C = <syntaxhighlight lang="objective-c">
//First, ensure your class conforms to the AVPlayerItemMetadataOutputPushDelegate protocol.
@interface YourClass : NSObject <AVPlayerItemMetadataOutputPushDelegate>

@end

</syntaxhighlight>
------------------------------
<syntaxhighlight lang="objective-c">
// Then create an instance of AVPlayerItemMetadataOutput and add it to the player item
AVPlayerItemMetadataOutput *metadataOutput = [[AVPlayerItemMetadataOutput alloc] initWithIdentifiers:nil];
[playerItem addOutput:metadataOutput];

// and set the delegate and a dispatch queue
[metadataOutput setDelegate:self queue:dispatch_get_main_queue()];
</syntaxhighlight>
------------------------------
<syntaxhighlight lang="objective-c">
// After that below callback function of AVPlayerItemMetadataOutputPushDelegate
// protocol will be triggered whenever ID3 tag is received from stream.
- (void)metadataOutput:(AVPlayerItemMetadataOutput *)output didOutputTimedMetadataGroups:(NSArray<AVTimedMetadataGroup *> *)groups fromPlayerItemTrack:(AVPlayerItemTrack *)track {
for (AVTimedMetadataGroup *group in groups) {
for (AVMetadataItem *item in group.items) {
// Handle the metadata item
[self handleTimedMetadata:item];
}
}
}
</syntaxhighlight>
------------------------------
<syntaxhighlight lang="objective-c">
// Then further metadata item can be handled like below
- (void)handleTimedMetadata:(AVMetadataItem *)item {
NSString *key = (NSString *)item.key;
NSString *extraString = item.extraAttributes[AVMetadataExtraAttributeInfoKey];
// If the key is "PRIV" and the extra string starts with "www.nielsen.com", send it to the Nielsen API
if ([key isEqualToString:@"PRIV"] && [extraString hasPrefix:@"www.nielsen.com"]) {
dispatch_async(dispatch_get_global_queue(DISPATCH_QUEUE_PRIORITY_DEFAULT, 0), ^{
[self.nielsenApi sendID3:extraString];
});
}
}
</syntaxhighlight>
}}

===== Life cycle of SDK instance =====
Life cycle of SDK instance includes four general states:
# '''Initial state''' – The SDK is not initialized and hence, not ready to process playing information.
# '''Idle state''' – The SDK is initialized and is ready to process playing information. Once Initialized, the SDK instance is not processing any data, but is listening for the loadMetadata and sendID3 events to occur.
# '''Processing state''' – The SDK instance is processing playing information. For DTVR, the <code>'''loadMetadata''' </code> call moves the SDK instance into this state. In this state, the SDK instance will be able to process sendID3 calls and measure content.
# '''Disabled state''' – The SDK instance is disabled.

</div>

==== Keep Going ====
<span class="mw-customtoggle-myDivisionv900" style="color: cornflowerblue"> Show/hide </span>
<div class="mw-collapsible mw-collapsed" id="mw-customcollapsible-myDivisionv900">

Congratulations, you've successfully integrated the iOS SDK in your app for a basic content playback scenario!

You can add more content to see channel-change scenarios or continue to next steps below.

View your application's debug logs and search for the term (AppSDK) to see messages emitted by Nielsen AppSDK during video playback.

</div>

==== Next Steps ====
<span class="mw-customtoggle-myDivisionv1000" style="color: cornflowerblue"> Show/hide </span>
<div class="mw-collapsible mw-collapsed" id="mw-customcollapsible-myDivisionv1000">
====Going Live====

In addition to the basic steps above, before going live developers need to handle app background/foreground events, make certain privacy disclosures, handle interruption events (stop, fast-forward, rewind), remove iOS simulator slices, and allow users to opt out of Nielsen measurement. More details can be found [[DTVR_iOS_SDK|here]], along with a more comprehensive reference for implementing DTVR measurement with AppSDK.

Once the DTVR Tracking Code is added, Nielsen will validate the implementation. Following Nielsen testing, developers need to make a few updates to the initialization call to ensure that the app is being measured properly.

#'''App ID''': Ensure that correct is used during initialization '''PXXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX'''
#'''Debug Logging''': Disable logging by changing initialization call to use @"nol_devDebug":@"INFO".

</div>
-->

</div>

iOS Step By Step

2023-07-27T13:26:30Z

NickParrucci:

{{Breadcrumb|}} {{Breadcrumb|Digital}} {{CurrentBreadcrumb}}
[[Category:Digital]]
__NOTOC__

Provided below are step-by-step quick start guides for implementing Nielsen iOS SDK for DCR Static, DCR Video, and DTVR products. Click each section to get started.

== → iOS DCR Static ==
<span class="mw-customtoggle-myDivision" style="color: cornflowerblue"> Show/hide DCR Static </span>
<div class="mw-collapsible mw-collapsed" id="mw-customcollapsible-myDivision">

==== iOS DCR Static Introduction ====
<span class="mw-customtoggle-myDivisiona-" style="color: cornflowerblue"> Show/hide Intro </span>
<div class="mw-collapsible mw-collapsed" id="mw-customcollapsible-myDivisiona-">

The Digital Content Ratings (DCR) Static product provides content consumption measurement in client mobile apps and webpages. This measurement includes insight into the total time a user spent on a webpage, how they navigated through the page via links, and many other data points.
This tutorial provides the steps to implement the DCR Static product in a sample iOS app. It includes:

*SDK Initialization Call
*DCR Static Metadata: information about the sections being tracked

By the end of this guide you will have the needed steps to integrate Nielsen's AppSDK in the background of your app.
</div>

=== iOS DCR Static Step 1 - Obtain AppID ===
<span class="mw-customtoggle-myDivisiona1" style="color: cornflowerblue"> Show/hide step 1 </span>
<div class="mw-collapsible mw-collapsed" id="mw-customcollapsible-myDivisiona1">

To begin using the iOS SDK (AppSDK) you will need to obtain an Application ID (AppId)

{| class="wikitable"
|-
! !! Item !! Description !! Source
|-
|✅ || App ID (appid) || Unique ID assigned to the player/site and configured by product || Contact your Nielsen TAM

|}

The appid is a 37 character unique ID assigned to the player/site and configured by product and is required when creating a new instance of the AppSDK in the app.
</br>Example: '''PXXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXX'''

</div>

==== iOS DCR Static Step 2 - SDK Initialization ====
<span class="mw-customtoggle-myDivisionc" style="color: cornflowerblue"> Show/hide step 2 </span>
<div class="mw-collapsible mw-collapsed" id="mw-customcollapsible-myDivisionc">

==== How to obtain the NielsenAppApi.Framework ====
The Nielsen AppSDK can either be downloaded directly or can be integrated directly within an application through the use of CocoaPods. We recommend using the CocoaPods-based integration whenever possible to ensure you maintain the most recent changes and enhancements to the Nielsen libraries.
* [[Digital_Measurement_iOS_Artifactory_Guide|Select to obtain CocoaPods implementation guide]]
* [[Special:Downloads|Select to Download Directly]]

==== Configuring Xcode Development Environment ====
Starting with SDK version 6.0.0.0, the Nielsen App SDK is compatible with Apple iOS versions 8.0 and above. In addition, when using the dynamic framework, all the required frameworks are linked automatically as the are needed. More details can be found here: https://stackoverflow.com/questions/24902787/dont-we-need-to-link-framework-to-xcode-project-anymore

<blockquote>'''Note''': All communications between the SDK and the Census (Collection Facility) use HTTPS.</blockquote>

==== Download Framework ====
The first step is to download and copy the [[Special:Downloads|NielsenAppApi.framework]] bundle to the app project directory. (''Not required if using CocaPods'')

==== Add Framework ====
In the General tab for app configuration add NielsenAppApi.framework in the list of Embedded Binaries. (''Not required if using CocaPods'')

==== Add Path ====
Add path to the NielsenAppApi.framework in the Framework Search Paths build setting. (''Not required if using CocaPods'')

==== Import Framework ====
Add NielsenAppApi.framework module in the source file of your app:

==== Using Swift ====
Add the following:
<syntaxhighlight lang="swift">
import NielsenAppApi
</syntaxhighlight>

==== Using Objective-C ====
<syntaxhighlight lang ="objective-c">
@import NielsenAppApi;
</syntaxhighlight>

=== Sample SDK Initialization Code ===
{{ExampleCode|
|Swift =
Swift 4.0 Example:
<code>NielsenInit.swift</code>
<syntaxhighlight lang="swift">
import Foundation
import NielsenAppApi

class NielsenInit : NSObject {
class func createNielsenApi(delegate: NielsenAppApiDelegate) -> NielsenAppApi?{

let appInformation:[String: String] = [
"appid": "PDA7D5EE6-B1B8-4123-9277-2A788XXXXXXX",
"sfcode": "dcr",
"nol_devDebug": "DEBUG"
]
return NielsenAppApi(appInfo:appInformation, delegate:delegate)
}
}
</syntaxhighlight>

Sample code using AVPlayer.
<code>LandingVC.swift</code>

<syntaxhighlight lang="swift">
import UIKit
import NielsenAppApi

class LandingVC: UIViewController, NielsenAppApiDelegate {

var nielsenMain : NielsenAppApi!
var sdkMethods : SDKMethods!
var data : [String : Any]!

class ViewController: UIViewController, NielsenAppApiDelegate, AVPlayerViewControllerDelegate {

// your code//

override func viewDidLoad() {
super.viewDidLoad()
//Getting the instance of NielsenApi
self.nielsenApi = NielsenInit.createNielsenApi(delegate: self)
}
}
override func viewDidAppear(_ animated: Bool) {
self.data = sdkMethods.loadStaticMaster() // This is just an example of populating the metadata
self.nielsenMain.loadMetadata(self.data)
}
</syntaxhighlight>
|Objective C =
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>
<syntaxhighlight lang="objective-c">
#import "NielsenInit.h"
#import <NielsenAppApi/NielsenEventTracker.h>

@implementation NielsenInit

+ (NielsenAppApi *)createNielsenAppApiWithDelegate:(id<NielsenAppApiDelegate>)delegate
{
//Initialising the NielsenEventTracker class by passing app information which returns the instance of NielsenEventTracker.

NSDictionary *appInformation = @{ @"appid": @"PDA7D5EE6-B1B8-4123-9277-2A788XXXXXXX",
@"appversion": @"1.0",
@"sfcode": @"dcr",
@"nol_devDebug": @"DEBUG", };

return [[NielsenAppApi alloc] initWithAppInfo:appInformation delegate:delegate];
}

@end
</syntaxhighlight>

The following would be the <code>NielsenInit.h</code> file:
<syntaxhighlight lang="objective-c">
#import <Foundation/Foundation.h>

@class NielsenAppApi;
@protocol NielsenAppApiDelegate;

@interface NielsenInit : NSObject

+ (NielsenAppApi *)createNielsenAppApiWithDelegate:(id<NielsenAppApiDelegate>)delegate;

@end
</syntaxhighlight>
Sample Code:
<syntaxhighlight lang="objective-c">
@implementation ViewController

- (void)viewDidLoad {
[super viewDidLoad];

//Getting the instance of Nielsen SDK
nielsenApi = [NielsenInit createNielsenAppApiWithDelegate:nil];
</syntaxhighlight>
}}

</div>

=== iOS DCR Static Step 3 - Create/Load DCR Static Metadata Object ===
<span class="mw-customtoggle-myDivisiond" style="color: cornflowerblue"> Show/hide step 3 </span>
<div class="mw-collapsible mw-collapsed" id="mw-customcollapsible-myDivisiond">

==== Configure Metadata ====
Map the Nielsen keys to variables so that the content metadata is dynamically updated.

The Nielsen reserved keys are:
{| class="wikitable"
|-
! Key !! Description !! Data Type !! Value !! Required?
|-
| type || asset type || fixed || <code>'static'</code> || Yes
|-
| assetid || Unique ID for each article || dynamic || custom <br>(no [[Special Characters]]) || No
|-
| section || section of each site (e.g. section value should be first level in page URL: website.com/section). Limit to 25 unique values || dynamic || custom || Yes
|-
| segA || custom segment for reporting: Limit to 25 unique values across custom segments (segA + segB + segC) || dynamic || custom || No
|-
| segB || custom segment for reporting: Limit to 25 unique values across custom segments (segA + segB + segC) || dynamic || custom || No
|-
| segC || custom segment for reporting: Limit to 25 unique values across custom segments (segA + segB + segC) || dynamic || custom || No
|}

The values passed through the Nielsen keys will determine the breakouts that are seen in reporting. The custom segments (A, B & C) will roll into the sub-brand. To not use custom segments A, B and C, do not pass any value in these keys.

==== Configure API calls - loadMetadata ====
Use [[loadMetadata]] to pass 'content' [[Digital Measurement Metadata]]. The CMS data must be passed as a JSON object.
<syntaxhighlight lang="java"> loadMetadata(JSONObject jsonMetadata);</syntaxhighlight>

<blockquote>Note: The [[loadMetadata]] call must have ("type": "static"). </blockquote>

Call [[loadMetadata]] with JSON metadata as below.
<syntaxhighlight lang="java"> new JSONObject()
.put("type", "static")
.put("section", "siteSection")
.put("assetid", "vid345-67483")
.put("segA", "segmentA")
.put("segB", "segmentB")
.put("segC","segmentC")
}</syntaxhighlight>

As soon as this loadMetadata call is made, AppSDK will record a view event and start tracking the section/page time spent (AppSDK 9.1 and above).

==== DCR Static Duration Measurement per Section/Page/Asset ====
If your Nielsen AppID is enabled for DCR Static duration measurement, a view event will be recorded and a timer will be started for each screen/page. Duration will be measured until a new page is loaded or the app is moved to the background. The event which triggers recognition of page view and timer start is the loadMetadata API call with a metadata object of type 'static'. Once a page is viewed and the timer has started, duration will be measured until a new page has loaded ''with associated loadMetadata call having a different '''section name''' from the previous page''. If a new loadMetadata call is made with the same '''section name''', it will be ignored - no new view will be recorded. If it is desired to have a new view event even though the metadata contains the same '''section name''' (example: single-page apps having several assedIDs but common section name), staticEnd API can be called between page views. For the purposes of this overview, staticend will not be used. See [[DCR_Static_iOS_SDK|this page]] for more information. <br>

</div>

=== Keep Going ===
<span class="mw-customtoggle-myDivisiong" style="color: cornflowerblue"> Show/hide </span>
<div class="mw-collapsible mw-collapsed" id="mw-customcollapsible-myDivisiong">

Congratulations, you've successfully integrated the iOS SDK in your app!

You can add static loadMetadata calls for more sections/pages in your app to see what happens when transitioning between sections.

View your application's debug logs and search for the term (AppSDK) to see messages emitted by Nielsen AppSDK.

</div>

=== Next Steps ===
<span class="mw-customtoggle-myDivisioni" style="color: cornflowerblue"> Show/hide </span>
<div class="mw-collapsible mw-collapsed" id="mw-customcollapsible-myDivisioni">

Now that you've integrated DCR Static for the AppSDK, what's next?

====Going Live====

In addition to the basic steps above, before going live developers need to handle app background/foreground events, make certain privacy disclosures, and allow users to opt out of Nielsen measurement. More details can be found [[DCR_Static_iOS_SDK|here]], along with a more comprehensive reference for implementing DCR Static measurement with AppSDK.

Once the DCR Tracking Code is added, Nielsen will validate the implementation. Following Nielsen testing, developers need to make a few updates to the initialization call to ensure that the app is being measured properly.

#'''App ID''': Ensure that correct is used during initialization '''PXXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX'''
#'''Debug Logging''': Disable logging by changing initialization call to use @"nol_devDebug":@"INFO".

</div>

</div>

== → iOS DCR Video ==

<span class="mw-customtoggle-myDivision1" style="color: cornflowerblue"> Show/hide DCR Video </span>
<div class="mw-collapsible mw-collapsed" id="mw-customcollapsible-myDivision1">
==== iOS DCR Video Introduction ====
<span class="mw-customtoggle-myDivisionv2-" style="color: cornflowerblue"> Show/hide Intro </span>
<div class="mw-collapsible mw-collapsed" id="mw-customcollapsible-myDivisionv2-">

The Digital Content Ratings (DCR) Video product provides content consumption measurement in client mobile apps and webpages. This measurement includes insight into the total time a user spent watching the tracked content, video player events, and much more.
This example provides the steps to implement the DCR Video product in a sample iOS app. It includes:

*SDK Initialization
*DCR Video Metadata: information about the content being tracked
*DCR Video Events/API calls

By the end of this guide you will have the needed steps to integrate Nielsen's AppSDK in the background of your app.

</div>

==== iOS DCR Video Step 1 - Obtain AppID ====
<span class="mw-customtoggle-myDivisionv3" style="color: cornflowerblue"> Show/hide step 1 </span>
<div class="mw-collapsible mw-collapsed" id="mw-customcollapsible-myDivisionv3">

To begin using the iOS AppSDK, you will need to obtain an Application ID (AppId)

{| class="wikitable"
|-
! !! Item !! Description !! Source
|-
|✅ || App ID (appid) || Unique ID assigned to the player/site and configured by product || Contact your Nielsen Representative

|}

The appid is a 37 character unique ID assigned to the player/site and configured by product and is required when creating a new instance of the AppSDK in the app.
</br>Example: '''PXXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXX'''

</div>

==== iOS DCR Video Step 2 - SDK Initialization ====
<span class="mw-customtoggle-myDivisionc" style="color: cornflowerblue"> Show/hide step 2 </span>
<div class="mw-collapsible mw-collapsed" id="mw-customcollapsible-myDivisionc">

===== How to obtain the NielsenAppApi.Framework =====
The Nielsen AppSDK can either be downloaded directly or can be integrated directly within an application through the use of CocoaPods. We recommend using the CocoaPods-based integration whenever possible to ensure you maintain the most recent changes and enhancements to the Nielsen libraries.
* [[Digital_Measurement_iOS_Artifactory_Guide|Select to obtain CocoaPods implementation guide]]
* [[Special:Downloads|Select to Download Directly]]

===== Configuring Xcode Development Environment =====
Starting with SDK version 6.0.0.0, the Nielsen App SDK is compatible with Apple iOS versions 8.0 and above. In addition, when using the dynamic framework, all the required frameworks are linked automatically as the are needed. More details can be found here: https://stackoverflow.com/questions/24902787/dont-we-need-to-link-framework-to-xcode-project-anymore

<blockquote>'''Note''': All communications between the SDK and the Census (Collection Facility) use HTTPS.</blockquote>

======= Download Framework =======
The first step is to download and copy the [[Special:Downloads|NielsenAppApi.framework]] bundle to the app project directory. (''Not required if using CocaPods'')

======= Add Framework =======
In the General tab for app configuration add NielsenAppApi.framework in the list of Embedded Binaries. (''Not required if using CocaPods'')

======= Add Path =======
Add path to the NielsenAppApi.framework in the Framework Search Paths build setting. (''Not required if using CocaPods'')

======= Import Framework =======
Add NielsenAppApi.framework module in the source file of your app:

======= Using Swift =======
Add the following:
<syntaxhighlight lang="swift">
import NielsenAppApi
</syntaxhighlight>

======= Using Objective-C =======
<syntaxhighlight lang ="objective-c">
@import NielsenAppApi;
</syntaxhighlight>

======= SDK Initialization =======

The following table contains the list of arguments that can be passed via the AppInfo JSON schema.
{| class="wikitable"
|-
! Parameter / Argument !! Description !! Source !! Required? !! Example
|--style="background-color:#d0f6f8;"
| appid || Unique Nielsen ID for the application. The ID is a GUID data type. If you did not receive your App ID, let us know and we will provide you. || Nielsen-specified || Yes || PXXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX
|--style="background-color:#d0f6f8;"
| nol_devDebug || Enables Nielsen console logging. Only required for testing <br>
|| Nielsen-specified || Optional || DEBUG
|}
==== Debug flag for development environment ====
Player application developers / integrators can use Debug flag to check whether an App SDK API call made is successful. To activate the Debug flag,
Pass the argument <code>@"nol_devDebug":@"DEBUG"</code>, in the JSON string .

Once the flag is active, it logs each API call made and the data passed. The log created by this flag is minimal.
<blockquote>'''Note''': DO NOT activate the Debug flag in a production environment.</blockquote>

=== Swift Example ===
==== Sample SDK Initialization Code ====

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

<br />
<code>ViewController.swift</code>

<syntaxhighlight lang="swift">
class ViewController: UIViewController, NielsenAppApiDelegate, AVPictureInPictureControllerDelegate, CLLocationManagerDelegate {

let avPlayerViewController = AVPlayerViewController()
var avPlayer:AVPlayer?
var nielsenAppApi: NielsenAppApi!

override func viewDidLoad() {
super.viewDidLoad()
self.nielsenAppApi = NielsenInit.createNielsenAppApi(delegate: self)
NSLog("Nielsen SDK initialized")
}}
</syntaxhighlight>

=== Objective C ===
==== Sample SDK Initialization Code ====
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>
<syntaxhighlight lang="objective-c">
#import "NlsAppApiFactory.h"
#import <NielsenAppApi/NielsenAppApi.h>

@implementation NlsAppApiFactory
+ (NielsenAppApi *)createNielsenAppApiWithDelegate:(id<NielsenAppApiDelegate>)delegate;
{
NSDictionary *appInformation = @{
@"appid": "PE392366B-F2C1-4BC4-AB62-A7DAFDC51XXX",
@"nol_devDebug": @"DEBUG"
};
return [[NielsenAppApi alloc] initWithAppInfo:appInformation delegate:delegate];
}
@end
</syntaxhighlight>

The following would be the <code>NlsAppApiFactory.h</code> file:
<syntaxhighlight lang="objective-c">
#import <Foundation/Foundation.h>

@class NielsenAppApi;
@protocol NielsenAppApiDeligate;
@interface NlsAppApiFactory : NSObject
+ (NielsenAppAPI *) createNielsenAppApiWithDelegate:(id<NielsenAppApiDelegate>)delegate;
@end
}}
</syntaxhighlight>
<br>
The following might be in the <code>Viewcontroller.m</code>
<syntaxhighlight lang="objective-c">
@implementation ViewController

- (void)viewDidLoad {
[super viewDidLoad];

//Setting background image
UIImage *backgroundImage = [UIImage imageNamed:@"new_ios_bg.png"];
UIImageView *backgroundImageView=[[UIImageView alloc]initWithFrame:self.view.frame];
backgroundImageView.image=backgroundImage;
[self.view insertSubview:backgroundImageView atIndex:0];

//Mark: In NielsenInit class we are initialising the Nielsen SDK.

//Getting the instance of Nielsen SDK
nielsenApi = [NielsenInit createNielsenAppApiWithDelegate:nil];
}
</syntaxhighlight>

</div>

==== iOS DCR Video Step 3 - Create DCR Video Content Metadata Object ====
<span class="mw-customtoggle-myDivisionv5" style="color: cornflowerblue"> Show/hide step 3 </span>
<div class="mw-collapsible mw-collapsed" id="mw-customcollapsible-myDivisionv5">

===== Configure Metadata =====
The SDK methods handle 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 Nielsen Key names (e.g. appid, program) 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.
<br>
===== Create channelName Metadata =====
channelName should remain constant throughout the completion of an episode or live stream.
<br />
{| class="wikitable"
|-
|--style="background-color:#d0f6f8;"
! Key !! Description !! Values !! Required
|--style="background-color:#d0f6f8;"
| channelName || Any string representing the channel/stream || custom || ✓
|-
|}

===== Create Content Metadata =====
Content metadata should remain constant throughout the entirety of an episode/clip including when ads play.
<blockquote> program and title metadata values should be passed to SDK as UTF-8 strings. </blockquote>
<div style="height: 45em; overflow-y:auto;"><br>
{| class="wikitable"
|-
! '''Keys''' !! '''Description''' !! '''Values''' !! '''Required'''!!'''Provider'''
|-
| type || Type of asset ||For Video use: <code>content</code><br> For Static or text <code>static</code> || Yes || Nielsen
|-style="background-color:#e9f9fa;"
| assetid || Unique ID assigned to asset <br> Note: Refrain from using the following special characters [[Special_Characters|(Special Characters)]]. || Examples: <br> <code>BBT345a234 </code> <br> <code>CBSs5e234F2021</code> || Yes || Client
|-
| program ||Complete program or movie title <br> (no abbreviations or shorthand) <br> Note: there is a 25 character limit. ||<code> The Big Bang Theory</code> <br> <code> TheBigBangTheory</code> <br><code> The Dark Knight</code> <br><code> TheDarkKnight</code> <br> || Yes || Client
|-style="background-color:#e9f9fa;"
| title ||Episode title with season and episode number (40 character limit) <br> (Formats accepted: S01E03, S1E3, S1 E3). || Examples: <br> <code>The Pants Alternative S03E18</code> <br> <code>The Pants Alternative S3E18</code> <br> <code>The Pants Alternative S3 E18</code> <br> Can also accept: <code> S3E18</code> <br> Not Valid: <code> 318 </code> or <code> 0318 </code>|| Yes || Client
|-
| crossId1 || Gracenote TMS ID (If available) should be passed for all telecasted content for clients using the Gracenote solution for proper matching purposes. <br>Note: The TMS ID will be a 14 character string. Normally leading with 2 alpha characerts ('EP', 'MV', 'SH' or 'SP'), followed by 12 numbers.
|| The TMS ID will be a 14 character string. <br> Normally being with 'EV,' 'EP', 'SH', 'SP', or 'MV' <br> Followed by 12 numbers after the initial two letter prefix. <br> <br> The Giant Morning Show: <code>SH009311820022</code> <br> The Pants Alternative Episode : <code>EP009311820061</code> || Optional || Nielsen
|-style="background-color:#e9f9fa;"
| crossId2 || Populated by content distributor to contribute viewing from that distributor to the given content originator. || For a full list of acceptable values, please contact your Nielsen reprentative. || Yes, for distributors || Nielsen
|-
| length || Length of content in seconds<br>Note: Integers and decimals are acceptable values are acceptable for the length parameter. || Examples:
<small>For standard VOD content - <code>300</code> to represent 5 minutes, <code>1320</code> to represent 22 minutes, etc.
<br>If DAI live stream of a discrete program (Live Event/Sporting Event), pass length of content. See example for standard VOD content above.
<br>If unknown DAI live steam, pass a value of <code>0</code>.</small>
|| Yes || Client
|-style="background-color:#e9f9fa;"
| airdate ||Original broadcast or release date for the program <br>For USA, date should be EST <br> Outside USA, date should be local time.<br>If not applicable or available, original broadcast or release date for the Program. || Acceptable Formats:<br><code>YYYY-MM-DDTHH:MI:SS</code><br><code>YYYY-MM-DDHH:MI:SS</code><br><code>YYYY-MM-DDTHH:MI:SS+xx:xx</code><br><code>YYYY-MM-DDTHH:MI:SS-xx:xx</code><br><code>YYYYMMDDHH:MI:SS</code><br><code>YYYYMMDD HH:MI:SS</code><br><code>MM-DD-YYYY</code><br><code>MM/DD/YYYY</code><br><code>YYYYMMDD</code></big> || Yes || Client
|-
| isfullepisode || Full episode flag to identify differences between long form content. || <code>y</code>- full episode, <code>n</code>- non full episode(clip,teaser,promo,etc.)
<small>Also accept:
<br><code>lf</code> or <code>yes</code>- longform
<br><code>sf</code> or <code>no</code>- shortform
|| Yes || Nielsen
|-style="background-color:#e9f9fa;"
| adloadtype || <big><small>Type of ad load:
<code>1</code> Linear – matches TV ad load<br><code>2</code> Dynamic – Dynamic Ad Insertion (DAI)</small></big>
|| <code>2</code> - DCR measures content with dynamic ads || Yes || Nielsen
|-
| segB || One of two custom segment for the clients granular reporting within a brand. || Examples:<br>Genre - <code>horror</code>, <code>comedy</code>, etc.<br>Timeslot - <code>primetime</code>, <code>daytime</code>, etc.<br>News type - <code>breakingnews</code>, <code>weather</code>, etc. || Optional || Client
|-style="background-color:#e9f9fa;"
| segC || One of two custom segment for the clients granular reporting within a brand. || Examples:<br>Genre - <code>horror</code>, <code>comedy</code>, etc.<br>Timeslot - <code>primetime</code>, <code>daytime</code>, etc.<br>News type - <code>breakingnews</code>, <code>weather</code>, etc. || Optional || Client
|}
</div>

Custom segments (segB and segC) can be used to aggregate video and/or static content within a single Brand to receive more granular reports within a brand.

Examples regarding usage of segments within SDK:
* All comedy clips and stories for a Brand rolled into a "Comedy" segment
* genre grouping content by Comedy vs. Drama
* group related Text + Video content - i.e. for a show that has a lot of - static pages associated with it
* packaging based on how clients sell inventory
* grouping related types of content either by genre, category or platform.
<br />

===== Metadata Example =====
<code>Swift</code>
<syntaxhighlight lang="swift">

let contentMetadata = [
"type": "content",
"assetid": "C77664",
"program": "The Big Bang Theory",
"title": "The Pants Alternative S03E18", //Formats accepted: S01E03, S1E3, S1 E3
"crossId1": "EP009311820061", //optional
"crossId2": "Content Originator", //optional
"length": "3600",
"airdate": "2022-03-21T10:05:00",
"isfullepisode": "Yes",
"adloadtype": "2",
"segB": "CustomSegmentValueB", //optional
"segC": "CustomSegmentValueC" //optional

];
</syntaxhighlight>
<br>
<code>Objective-C</code>
<syntaxhighlight lang="objective-c">
NSDictionary * contentMetadata = @ {
@ "type": @ "content",
@ "assetid": @ "C77664",
@ "program": @ "The Big Bang Theory",
@ "title": @ "The Pants Alternative S03E18", //Formats accepted: S01E03, S1E3, S1 E3
@ "crossId1": @ "EP009311820061", //optional
@ "crossId2": @ "Content Originator", //optional
@ "length": @ "3600",
@ "airdate": @ "2022-03-21T10:05:00",
@ "isfullepisode": @ "y",
@ "adloadtype": @ "2",
@ "segB": @ "CustomSegmentValueB", //optional
@ "segC": @ "CustomSegmentValueC" //optional

}
</syntaxhighlight>

</div>

==== iOS DCR Video Step 4 - Basic Set of Events - Sample Playback ====
<span class="mw-customtoggle-myDivisionv6" style="color: cornflowerblue"> Show/hide step 4 </span>
<div class="mw-collapsible mw-collapsed" id="mw-customcollapsible-myDivisionv6">

=== SDK Events ===
{| class="wikitable"
|-
! Event !! Parameter !! Description
|-
| 'play' || || Call at start of each new stream
|-
| 'loadMetadata' || content/ad metadata object || Needs to be called at the beginning of each asset
|-
| 'playheadPosition' || playhead position as integer<br/>
VOD: current position in seconds <br/>
Live: current UNIX timestamp (seconds since Jan-1-1970 UTC) <br/>
Note: 'PlayheadPosition' has to be called every second
||
Pass playhead position every second during playback
|-
| 'stop' || playhead position || Call during any interruption to content or Ad playback and at the end of each Ad.
|-
| 'end' || playhead position in seconds || Call when the current video asset completes playback and pass the playhead position. <br/>
Example: At the end of the content stream, if the user switches to another piece of content, when the browser is refreshed or closed.
|}
<blockquote>Note: For livestream, send the UNIX timestamp, for VOD send the time in seconds as integer. The final playhead position must be sent for the current asset being played before calling <code>'''stop'''</code>, <code>'''end'''</code> or<code> '''loadmetadata'''</code>,.</blockquote>

=== Life cycle of SDK instance ===
Life cycle of SDK instance includes four general states:
# '''Initial state''' – The SDK is not initialized and hence, not ready to process playing information. Once the SDK is moved out of this state, it needs instantiation of the new SDK instance in order to get the instance in the '''Idle state'''.
# '''Idle state''' – The SDK is initialized and is ready to process playing information. Once Initialized, the SDK instance is not processing any data, but is listening for an event to occur.
# '''Processing state''' – The SDK instance is processing playing information. The <code>'''play'''</code> and <code>'''loadMetadata''' </code> calls move the SDK instance into this state. In this state, the SDK instance will be able to process the following calls.
## <code>'''playheadPosition'''</code> – Call this API every one second when playhead position is active. If a LIVE event, use the current UNIX timestamp (seconds since Jan-1-1970 UTC).
## <code>'''stop'''</code> – Call this API when the content or Ad playback is interrupted and at the end of each Ad.
## <code>'''end'''</code> – Call when content completes. When called, the SDK instance exits from Processing state.
# '''Disabled state''' – The SDK instance is disabled and is not processing playing information.
## <code>'''appDisableApi'''</code> is set to <code>true</code>

<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 <code>'''loadMetadata''' </code> and <code>'''playheadPosition'''</code> </blockquote>

=== API Call Sequence ===
==== Sample Use Case: Content has no Advertisements ====
Call [[play()]] at start of stream

Call [[loadMetadata()]] with JSON metadata for content as below.
<syntaxhighlight lang="json">{
"type": "content",
"assetid": "vid345-67483",
"program": "ProgramName",
"title": "Program S3, EP1",
"length": "3600",
...
}</syntaxhighlight>
Call [[playheadPosition|playheadPosition()]] every one second until a pause / stop.
Use the sample API sequence below as a reference to identify the specific events that need to be called during content playback without ads.
{| class="wikitable"
|-
! Type !! Sample code !! Description
|-
| rowspan="2" | Start of stream || <code>mAppSdk.play(); </code> || // Call at start of each new stream
|-
| <code>mAppSdk.loadMetadata(contentMetaDataObject);</code> || // contentMetadataObject contains the JSON metadata for the content being played
|-style="background-color:#d8f5d7;"
| Content || <code>mAppSdk.setPlayheadPosition(playheadPosition);</code> || // position is position of the playhead while the content is being played
|-
| Interruption || <code>mAppSdk.stop();</code> || // call stop when content playback is interrupted
|-style="background-color:#d8f5d7;"
| rowspan="2" | Resume Content || <code>mAppSdk.loadMetadata(contentMetaDataObject);</code> || // Call loadMetadata and pass content metadata object when content resumes
|- style="background-color:#d8f5d7;"
|<code>mAppSdk.setPlayheadPosition(playheadPosition);</code> || // continue pasing playhead position every second starting from position where content is resumed
|-
| End of Stream || <code>mAppSdk.end();</code> || // Content playback is completed.
|}

</div>

==== Keep Going ====
<span class="mw-customtoggle-myDivisionv9" style="color: cornflowerblue"> Show/hide </span>
<div class="mw-collapsible mw-collapsed" id="mw-customcollapsible-myDivisionv9">

Congratulations, you've successfully integrated the iOS SDK in your app for a basic content playback scenario!

You can add more content to see channel-change scenarios or continue to next steps below.

View your application's debug logs and search for the term (AppSDK) to see messages emitted by Nielsen AppSDK during video playback.

</div>

==== Next Steps ====
<span class="mw-customtoggle-myDivisionv10" style="color: cornflowerblue"> Show/hide </span>
<div class="mw-collapsible mw-collapsed" id="mw-customcollapsible-myDivisionv10">
====Going Live====

In addition to the basic steps above, before going live developers need to handle app background/foreground events, make certain privacy disclosures, handle interruption events (stop, fast-forward, rewind), remove iOS simulator slices, and allow users to opt out of Nielsen measurement. More details can be found [[DCR_Video_iOS_SDK|here]], along with a more comprehensive reference for implementing DCR Video measurement with AppSDK.

Once the DCR Tracking Code is added, Nielsen will validate the implementation. Following Nielsen testing, developers need to make a few updates to the initialization call to ensure that the app is being measured properly.

#'''App ID''': Ensure that correct is used during initialization '''PXXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX'''
#'''Debug Logging''': Disable logging by changing initialization call to use @"nol_devDebug":@"INFO".

</div>

</div>

== → iOS DTVR (coming soon) ==


<syntaxhighlight lang="objectivec">
- (NSDictionary *)loadDtvr{

//Loading DTVR data
NSDictionary *dtvr = @{ @"adModel":@"1" ,
@"type":@"content",};
return dtvr;
}
</syntaxhighlight>
</div>

==== iOS DTVR Step 4 - Basic Set of Events - Sample Playback ====
<span class="mw-customtoggle-myDivisionv600" style="color: cornflowerblue"> Show/hide step 4 </span>
<div class="mw-collapsible mw-collapsed" id="mw-customcollapsible-myDivisionv600">

===== SDK Events/APIs =====

{| class="wikitable"
|-
! Event !! Parameter !! Description
|-
| 'loadMetadata' || content/ad metadata object || Needs to be called at the beginning of each asset to pass type and adModel.
|-
| 'sendID3' || Used to send the ID3 tag payload retrieved from the stream || Needs to be called at the beginning of playback
|}

===== Configure API calls - loadMetadata =====
Use <code>loadMetadata</code> to pass the metadata object created above.
{{ExampleCode|
|Objective C = <syntaxhighlight lang="objective-c">[nielsenApi loadMetadata:(dtvr)];</syntaxhighlight>
|Swift = <syntaxhighlight lang="swift">self.nielsenAppApi?.loadMetadata(dtvr)</syntaxhighlight>
}}

===== Configure API calls - sendID3 =====
[[sendID3]] API is a Nielsen AppSDK receiver for timed metadata events (ID3 tags) provided through iOS’s NSNotificationCenter notification system. This API filters out Nielsen-specific ID3 tags from the system and uses them to create duration data. These ID3 tags are used by Nielsen SDK for DTVR measurement, and the stream that is played must contain ID3 tags and have these tags extracted and passed to SDK using the below procedure in order for DTVR measurement to occur.
{{ExampleCode|
|Objective C = <syntaxhighlight lang="objective-c">[nielsenApi sendID3:extraString];</syntaxhighlight>
|Swift = <syntaxhighlight lang="swift"> [nielsenApi sendID3:extraString];</syntaxhighlight>}}
'''Sample ID3 tags'''
* <code>www.nielsen.com/X100zdCIGeIlgZnkYj6UvQ==/X100zdCIGeIlgZnkYj6UvQ==/AAAB2Jz2_k74GXSzx4npHuI_<wbr />JwJd3QSUpW30rDkGTcbHEzIMWleCzM-uvNOP9fzJcQMWQLJqzXMCAxParOb5sGijSV9dNM3QiBniJYGZ5GI-lL1fXTTN0IgZ4iWBmeRiPpS9AAAAAAAAAAAAAAAAAAAAAFJWFM5SVhTONNU=/00000/00000/00</code>
* <code>www.nielsen.com/X100zdCIGeIlgZnkYj6UvQ==/R8WHe7pEBeqBhu8jTeXydg==/AAICoyitYqlxT7n6aZ0oMCGhe<wbr />Fi4CXFp46AMUPZz1lMr_M9tr3_cjee1SHqxrOiVerMDLeyn9xzocZSKwi746Re8vNOtpNCAZjYABs_J0R25IHpvOc1HS8<wbr />QHGgD5TgOJeS6gX100zdCIGeIlgZnkYj6UvVJWFNhSVhTiPE0=/00000/46016/00</code>
Refer to [[iOS SDK API Reference#Retrieving ID3 Tags|Retrieving ID3 Tags]] section to know more details.

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

As Apple has deprecated the use of [https://developer.apple.com/documentation/avfoundation/avplayeritem/1389602-timedmetadata?language=objc timedMetadata], we now recommend using [https://developer.apple.com/documentation/avfoundation/avplayeritemmetadataoutput?language=objc AVPlayerItemMetadataOutput] for extracting ID3 tags from the iOS Native Player.

If any other player apart from the iOS native player is used, check and ensure that the player has the capability to extract metadata such as ID3 tags.

===== Examples of extracting ID3 tags from the iOS Native Player =====
{{ExampleCode|
|Swift = <syntaxhighlight lang="swift">
//First, ensure your class conforms to the AVPlayerItemMetadataOutputPushDelegate protocol.
class YourClass: AVPlayerItemMetadataOutputPushDelegate {

}
</syntaxhighlight>
------------------------------------------------------
<syntaxhighlight lang="swift">
// Then create an instance of AVPlayerItemMetadataOutput and add it to the player item
let metadataOutput = AVPlayerItemMetadataOutput(identifiers: nil)
playerItem.add(metadataOutput)

// and set the delegate and a dispatch queue
metadataOutput.setDelegate(self, queue: DispatchQueue.main)
</syntaxhighlight>
------------------------------------------------------
<syntaxhighlight lang="swift">
// After that below callback function of AVPlayerItemMetadataOutputPushDelegate
// protocol will be triggered whenever ID3 tag is received from stream.
func metadataOutput(_ output: AVPlayerItemMetadataOutput, didOutputTimedMetadataGroups groups: [AVTimedMetadataGroup], from track: AVPlayerItemTrack?) {
for group in groups {
for item in group.items {
// Handle the metadata item
handleTimedMetadata(metadataItem: item)
}
}
}
</syntaxhighlight>
------------------------------------------------------
<syntaxhighlight lang="swift">
// Then further metadata item can be handled like below
func handleTimedMetadata(metadataItem: AVMetadataItem) {
guard let key = metadataItem.key as? String,
let extraString = metadataItem.extraAttributes?[AVMetadataExtraAttributeInfoKey] as? String else {
return
}
// If the extra string(tag) starts with "www.nielsen.com", then only sending to SDK
if key == "PRIV" && extraString.hasPrefix("www.nielsen.com") {
DispatchQueue.global(qos: .default).async {
self.nielsenApi?.sendID3(extraString)
}
}
}

</syntaxhighlight>
|Objective C = <syntaxhighlight lang="objective-c">
//First, ensure your class conforms to the AVPlayerItemMetadataOutputPushDelegate protocol.
@interface YourClass : NSObject <AVPlayerItemMetadataOutputPushDelegate>

@end

</syntaxhighlight>
------------------------------
<syntaxhighlight lang="objective-c">
// Then create an instance of AVPlayerItemMetadataOutput and add it to the player item
AVPlayerItemMetadataOutput *metadataOutput = [[AVPlayerItemMetadataOutput alloc] initWithIdentifiers:nil];
[playerItem addOutput:metadataOutput];

// and set the delegate and a dispatch queue
[metadataOutput setDelegate:self queue:dispatch_get_main_queue()];
</syntaxhighlight>
------------------------------
<syntaxhighlight lang="objective-c">
// After that below callback function of AVPlayerItemMetadataOutputPushDelegate
// protocol will be triggered whenever ID3 tag is received from stream.
- (void)metadataOutput:(AVPlayerItemMetadataOutput *)output didOutputTimedMetadataGroups:(NSArray<AVTimedMetadataGroup *> *)groups fromPlayerItemTrack:(AVPlayerItemTrack *)track {
for (AVTimedMetadataGroup *group in groups) {
for (AVMetadataItem *item in group.items) {
// Handle the metadata item
[self handleTimedMetadata:item];
}
}
}
</syntaxhighlight>
------------------------------
<syntaxhighlight lang="objective-c">
// Then further metadata item can be handled like below
- (void)handleTimedMetadata:(AVMetadataItem *)item {
NSString *key = (NSString *)item.key;
NSString *extraString = item.extraAttributes[AVMetadataExtraAttributeInfoKey];
// If the key is "PRIV" and the extra string starts with "www.nielsen.com", send it to the Nielsen API
if ([key isEqualToString:@"PRIV"] && [extraString hasPrefix:@"www.nielsen.com"]) {
dispatch_async(dispatch_get_global_queue(DISPATCH_QUEUE_PRIORITY_DEFAULT, 0), ^{
[self.nielsenApi sendID3:extraString];
});
}
}
</syntaxhighlight>
}}

===== Life cycle of SDK instance =====
Life cycle of SDK instance includes four general states:
# '''Initial state''' – The SDK is not initialized and hence, not ready to process playing information.
# '''Idle state''' – The SDK is initialized and is ready to process playing information. Once Initialized, the SDK instance is not processing any data, but is listening for the loadMetadata and sendID3 events to occur.
# '''Processing state''' – The SDK instance is processing playing information. For DTVR, the <code>'''loadMetadata''' </code> call moves the SDK instance into this state. In this state, the SDK instance will be able to process sendID3 calls and measure content.
# '''Disabled state''' – The SDK instance is disabled.

</div>

==== Keep Going ====
<span class="mw-customtoggle-myDivisionv900" style="color: cornflowerblue"> Show/hide </span>
<div class="mw-collapsible mw-collapsed" id="mw-customcollapsible-myDivisionv900">

Congratulations, you've successfully integrated the iOS SDK in your app for a basic content playback scenario!

You can add more content to see channel-change scenarios or continue to next steps below.

View your application's debug logs and search for the term (AppSDK) to see messages emitted by Nielsen AppSDK during video playback.

</div>

==== Next Steps ====
<span class="mw-customtoggle-myDivisionv1000" style="color: cornflowerblue"> Show/hide </span>
<div class="mw-collapsible mw-collapsed" id="mw-customcollapsible-myDivisionv1000">
====Going Live====

In addition to the basic steps above, before going live developers need to handle app background/foreground events, make certain privacy disclosures, handle interruption events (stop, fast-forward, rewind), remove iOS simulator slices, and allow users to opt out of Nielsen measurement. More details can be found [[DTVR_iOS_SDK|here]], along with a more comprehensive reference for implementing DTVR measurement with AppSDK.

Once the DTVR Tracking Code is added, Nielsen will validate the implementation. Following Nielsen testing, developers need to make a few updates to the initialization call to ensure that the app is being measured properly.

#'''App ID''': Ensure that correct is used during initialization '''PXXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX'''
#'''Debug Logging''': Disable logging by changing initialization call to use @"nol_devDebug":@"INFO".

</div>

</div>
-->

iOS Step By Step

2023-07-27T13:25:16Z

NickParrucci:

iOS Step By Step

2023-07-27T13:24:32Z

NickParrucci:

Android Step By Step

2023-07-27T13:14:43Z

NickParrucci: /* Going Live */

{{Breadcrumb|}} {{Breadcrumb|Digital}} {{CurrentBreadcrumb}}
[[Category:Digital]]
__NOTOC__

Provided below are step-by-step quick start guides for implementing Nielsen Android SDK for DCR Static, DCR Video, and DTVR products. Click each section to get started.

== → Android DCR Static ==
<span class="mw-customtoggle-myDivision" style="color: cornflowerblue"> Show/hide DCR Static </span>
<div class="mw-collapsible mw-collapsed" id="mw-customcollapsible-myDivision">

==== Android DCR Static Introduction ====
<span class="mw-customtoggle-myDivision1" style="color: cornflowerblue"> Show/hide Intro </span>
<div class="mw-collapsible mw-collapsed" id="mw-customcollapsible-myDivision1">

The Digital Content Ratings (DCR) Static product provides content consumption measurement on client webpages. This measurement includes insight into the total time a user spent on a webpage, how they navigated through the page via links, and many other data points.
This tutorial provides the steps to implement the DCR Static product in a sample Android app. It includes:

*SDK Initialization Call
*DCR Static Metadata: information about the sections being tracked

By the end of this guide you will have the needed steps to integrate Nielsen's AppSDK in the background of your app.
</div>

=== Android DCR Static Step 1 - Obtain AppID ===
<span class="mw-customtoggle-myDivision2" style="color: cornflowerblue"> Show/hide step 1 </span>
<div class="mw-collapsible mw-collapsed" id="mw-customcollapsible-myDivision2">

To begin using the Android SDK (AppSDK) you will need to obtain an Application ID (AppId)

{| class="wikitable"
|-
! !! Item !! Description !! Source
|-
|✅ || App ID (appid) || Unique ID assigned to the player/site and configured by product || Contact your Nielsen TAM

|}

The appid is a 37 character unique ID assigned to the player/site and configured by product and is required when creating a new instance of the AppSDK in the app.
</br>Example: '''PXXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXX'''

</div>

=== Android DCR Static Step 2 - SDK Initialization ===
<span class="mw-customtoggle-myDivision3" style="color: cornflowerblue"> Show/hide step 2 </span>
<div class="mw-collapsible mw-collapsed" id="mw-customcollapsible-myDivision3">

==== How to obtain the NielsenAppApi ====
The Nielsen AppSDK can either be downloaded directly or can be integrated into an application through the use of Gradle. We recommend using the Gradle-based integration whenever possible to ensure you maintain the most recent changes and enhancements to the Nielsen libraries.
* [[Digital_Measurement_Android_Artifactory_Guide|Select to obtain Gradle implementation guide]]
* [[Special:Downloads|Select to Download Directly]]

==== SDK Initialization ====

The following table contains the list of arguments that can be passed via the AppInfo JSON schema.
{| class="wikitable"
|-
! Parameter / Argument !! Description !! Source !! Required? !! Example
|-
| appid || Unique Nielsen ID for the application. The ID is a GUID data type. If you did not receive your App ID, let us know and we will provide you. || Nielsen-specified || Yes || PXXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX
|-
| nol_devDebug || Enables Nielsen console logging. Only required for testing
|| Nielsen-specified || Optional || "DEBUG"
|}

==== Debug flag for development environment ====
Player application developers / integrators can use Debug flag to check whether an App SDK API call made is successful. To activate the Debug flag,
Pass the argument <code>@"nol_devDebug":@"INFO"</code>, in the JSON string . The permitted values are:

* '''INFO''': Displays the API calls and the input data from the application (validate player name, app ID, etc.). It can be used as certification Aid.
* '''WARN''': Indicates potential integration / configuration errors or SDK issues.
* '''ERROR''': Indicates important integration errors or non-recoverable SDK issues.
* '''DEBUG''': Debug logs, used by the developers to debug more complex issues.

Once the flag is active, it logs each API call made and the data passed. The log created by this flag is minimal.
<blockquote>'''Note''': DO NOT activate the Debug flag in a production environment.</blockquote>

==== Sample SDK Initialization Code ====

'''Initialization of App SDK object through a JSON object'''
<syntaxhighlight lang="java">try
{
// Prepare AppSdk configuration object (JSONObject)
JSONObject appSdkConfig = new JSONObject()
.put("appid", "PDA7D5EE6-B1B8-XXXX-XXXX-2A788BCXXXCA")
.put("nol_devDebug", "DEBUG"); // only for debug builds

// Pass appSdkConfig to the AppSdk constructor
mAppSdk = new AppSdk(appContext, appSdkConfig, appSdkListener);
}
catch (JSONException e)
{
Log.e(TAG, "Couldn’t prepare JSONObject for appSdkConfig", e);
}
</syntaxhighlight>
Here, <code>appContext</code> is the App context object and <code>appSdkConfig</code> is JSON object for holding the parameters (<code>appid</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.

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

</div>

=== Android DCR Static Step 3 - Create/Load DCR Static Metadata Object ===
<span class="mw-customtoggle-myDivision4" style="color: cornflowerblue"> Show/hide step 3 </span>
<div class="mw-collapsible mw-collapsed" id="mw-customcollapsible-myDivision4">

==== Configure Metadata ====
Map the Nielsen keys to variables so that the content metadata is dynamically updated.

The Nielsen reserved keys are:
{| class="wikitable"
|-
! Key !! Description !! Data Type !! Value !! Required?
|-
| type || asset type || fixed || <code>'static'</code> || Yes
|-
| assetid || Unique ID for each article || dynamic || custom <br>(no [[Special Characters]]) || No
|-
| section || section of each site (e.g. section value should be first level in page URL: website.com/section). Limit to 25 unique values || dynamic || custom || Yes
|-
| segA || custom segment for reporting: Limit to 25 unique values across custom segments (segA + segB + segC) || dynamic || custom || No
|-
| segB || custom segment for reporting: Limit to 25 unique values across custom segments (segA + segB + segC) || dynamic || custom || No
|-
| segC || custom segment for reporting: Limit to 25 unique values across custom segments (segA + segB + segC) || dynamic || custom || No
|}

The values passed through the Nielsen keys will determine the breakouts that are seen in reporting. The custom segments (A, B & C) will roll into the sub-brand. To not use custom segments A, B and C, do not pass any value in these keys.

==== Configure API calls - loadMetadata ====
Use [[loadMetadata]] to pass 'content' [[Digital Measurement Metadata]]. The CMS data must be passed as a JSON object.
<syntaxhighlight lang="java"> loadMetadata(JSONObject jsonMetadata);</syntaxhighlight>
Refer to [[Digital Measurement Metadata]] for the list of parameters to be passed in the JSON object.
<blockquote>Note: The [[loadMetadata]] call must have ("type": "static"). </blockquote>

Call [[loadMetadata]] with JSON metadata as below.
<syntaxhighlight lang="java"> new JSONObject()
.put("type", "static")
.put("section", "siteSection")
.put("assetid", "vid345-67483")
.put("segA", "segmentA")
.put("segB", "segmentB")
.put("segC","segmentC")
}</syntaxhighlight>

As soon as this loadMetadata call is made, AppSDK will record a view event and start tracking the section/page time spent (AppSDK 9.1 and above).

==== DCR Static Duration Measurement per Section/Page/Asset ====
If your Nielsen AppID is enabled for DCR Static duration measurement, a view event will be recorded and a timer will be started for each screen/page. Duration will be measured until a new page is loaded or the app is moved to the background. The event which triggers recognition of page view and timer start is the loadMetadata API call with a metadata object of type 'static'. Once a page is viewed and the timer has started, duration will be measured until a new page has loaded ''with associated loadMetadata call having a different '''section name''' from the previous page''. If a new loadMetadata call is made with the same '''section name''', it will be ignored - no new view will be recorded. If it is desired to have a new view event even though the metadata contains the same '''section name''' (example: single-page apps having several assedIDs but common section name), staticEnd API can be called between page views. For the purposes of this overview, staticend will not be used. See [[DCR_Static_Android_SDK|this page]] for more information. <br>

</div>

=== Keep Going ===
<span class="mw-customtoggle-myDivision5" style="color: cornflowerblue"> Show/hide </span>
<div class="mw-collapsible mw-collapsed" id="mw-customcollapsible-myDivision5">

Congratulations, you've successfully integrated the Android SDK in your app!

You can add static loadMetadata calls for more sections/pages in your app to see what happens when transitioning between sections.

View your application's debug logs and search for the term (AppSDK) to see messages emitted by Nielsen AppSDK.

</div>

=== Next Steps ===
<span class="mw-customtoggle-myDivision6" style="color: cornflowerblue"> Show/hide </span>
<div class="mw-collapsible mw-collapsed" id="mw-customcollapsible-myDivision6">

Now that you've integrated DCR Static for the AppSDK, what's next?

====Going Live====

In addition to the basic steps above, before going live developers need to handle app background/foreground events, make certain privacy disclosures, and allow users to opt out of Nielsen measurement. More details can be found [[DCR_Static_Android_SDK|here]], along with a more comprehensive reference for implementing DCR Static measurement with AppSDK.

Once the DCR Tracking Code is added, Nielsen will validate the implementation. Following Nielsen testing, developers need to make a few updates to the initialization call to ensure that the app is being measured properly.

#'''App ID''': Ensure that correct is used during initialization '''PXXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX'''
#'''Debug Logging''': Disable logging by changing initialization call to use @"nol_devDebug":@"INFO".

</div>

</div>

== → Android DCR Video ==

<span class="mw-customtoggle-myDivision7" style="color: cornflowerblue"> Show/hide DCR Video </span>
<div class="mw-collapsible mw-collapsed" id="mw-customcollapsible-myDivision7">
==== Android DCR Video Introduction ====
<span class="mw-customtoggle-myDivisionv8" style="color: cornflowerblue"> Show/hide Intro </span>
<div class="mw-collapsible mw-collapsed" id="mw-customcollapsible-myDivisionv8">

The Digital Content Ratings (DCR) Video product provides content consumption measurement on client webpages. This measurement includes insight into the total time a user spent watching the tracked content, video player events, and much more.
This example provides the steps to implement the DCR Video product in a sample Android app. It includes:

*SDK Initialization
*DCR Video Metadata: information about the content being tracked
*DCR Video Events/API calls

By the end of this guide you will have the needed steps to integrate Nielsen's AppSDK in the background of your app.

</div>

==== Android DCR Video Step 1 - Obtain AppID ====
<span class="mw-customtoggle-myDivisionv9" style="color: cornflowerblue"> Show/hide step 1 </span>
<div class="mw-collapsible mw-collapsed" id="mw-customcollapsible-myDivisionv9">

To begin using the Android AppSDK, you will need to obtain an Application ID (AppId)

{| class="wikitable"
|-
! !! Item !! Description !! Source
|-
|✅ || App ID (appid) || Unique ID assigned to the player/site and configured by product || Contact your Nielsen Representative

|}

The appid is a 37 character unique ID assigned to the player/site and configured by product and is required when creating a new instance of the AppSDK in the app.
</br>Example: '''PXXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXX'''

</div>

==== Android DCR Video Step 2 - SDK Initialization ====
<span class="mw-customtoggle-myDivision10" style="color: cornflowerblue"> Show/hide step 2 </span>
<div class="mw-collapsible mw-collapsed" id="mw-customcollapsible-myDivision10">

===== Setting up your Development Environment =====
===== Configuring Android Development Environment =====
*The Nielsen App SDK (located in the [https://engineeringportal.nielsen.com/docs/Special:Downloads Downloads section] of the website) class is the primary application interface to the Nielsen App SDK on Android.
*The Nielsen App SDK class is defined as the only public class belonging to the com.nielsen.app.sdk package.
*The Nielsen App SDK can also be added via [https://engineeringportal.nielsen.com/docs/Digital_Measurement_Android_Artifactory_Guide Artifact Repository].

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.

Once SDK is downloaded ensure to unzip the Nielsen SDK and copy the AppSdk.jar in your app (Android Studio) libs folder, then right click the AppSdk.jar and select '''Add As Library'''.
Ensure the AppSdk.jar file is added in 'build.gradle (App Level) file.
* App SDK 1.2 provides support for x86, mips, and armeabi-7a architecture.

===== Google Play Services =====
Add the Google Play Services in the project,
Steps: Android Studio -> File -> Project Structure ->(In module selection) select App -> Dependencies (tab) -> Click "+" button and search for <code>"*play-services*"</code>. Then select the most recent version of the play-services Artifact.
Ensure it is added in build.gradle (App level) file

===== Google AD ID Permissions =====
The following is required if target API level is set to 31 (Android 12) with the Ad Version of the Nielsen SDK.

<syntaxhighlight lang="java">
<uses-permission android:name="com.google.android.gms.permission.AD_ID"/>
</syntaxhighlight>
</br>

====== Manifest File ======
* Add the following permissions on the project’s ''AndroidManifest.xml'' file.
<syntaxhighlight lang="java">
<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].

* In <code>AndroidManifest.xml </code>under <code><application></code> add the following metadata

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

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

===== Library =====
Nielsen App SDK uses the following packages/classes from the Google Play service.
* google-play-services_lib

===== Classes/package =====
* com.google.android.gms.ads.identifier.AdvertisingIdClient;
* com.google.android.gms.ads.identifier.AdvertisingIdClient.Info;
* com.google.android.gms.common.ConnectionResult;
* com.google.android.gms.common.GooglePlayServicesUtil;
* com.google.android.gms.common.GooglePlayServicesRepairableException;
* com.google.android.gms.common.GooglePlayServicesNotAvailableException;

===== SDK Initialization =====

The following table contains the list of arguments that can be passed via the AppInfo JSON schema.
{| class="wikitable"
|-
! Parameter / Argument !! Description !! Source !! Required? !! Example
|-
| appid || Unique Nielsen ID for the application. The ID is a GUID data type. If you did not receive your App ID, let us know and we will provide you. || Nielsen-specified || Yes || PXXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX
|-
| nol_devDebug || Enables Nielsen console logging. Only required for testing
|| Nielsen-specified || Optional || "DEBUG"
|}
== Debug flag for development environment ==
Player application developers / integrators can use Debug flag to check whether an App SDK API call made is successful. To activate the Debug flag,
Pass the argument <code>@"nol_devDebug":@"DEBUG"</code>, in the JSON string . The permitted values are:

* '''INFO''': Displays the API calls and the input data from the application (validate player name, app ID, etc.). It can be used as certification Aid.
* '''WARN''': Indicates potential integration / configuration errors or SDK issues.
* '''ERROR''': Indicates important integration errors or non-recoverable SDK issues.
* '''DEBUG''': Debug logs, used by the developers to debug more complex issues.

Once the flag is active, it logs each API call made and the data passed. The log created by this flag is minimal.
<blockquote>'''Note''': DO NOT activate the Debug flag in a production environment.</blockquote>

==== Sample SDK Initialization Code ====

'''Initialization of App SDK object through a JSON object'''
<syntaxhighlight lang="java">try
{
// Prepare AppSdk configuration object (JSONObject)
JSONObject appSdkConfig = new JSONObject()
.put("appid", "PDA7D5EE6-B1B8-XXXX-XXXX-2A788BCXXXCA")
.put("nol_devDebug", "DEBUG"); // only for debug builds

// Pass appSdkConfig to the AppSdk constructor
mAppSdk = new AppSdk(appContext, appSdkConfig, appSdkListener);
}
catch (JSONException e)
{
Log.e(TAG, "Couldn’t prepare JSONObject for appSdkConfig", e);
}
</syntaxhighlight>
Here, <code>appContext</code> is the App context object and <code>appSdkConfig</code> is JSON object for holding the parameters (<code>appid</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.

The integration of Nielsen App SDK will depend on type of client app.<br />
* 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).

</div>

==== Android DCR Video Step 3 - Create DCR Video Content Metadata Object ====
<span class="mw-customtoggle-myDivisionv11" style="color: cornflowerblue"> Show/hide step 3 </span>
<div class="mw-collapsible mw-collapsed" id="mw-customcollapsible-myDivisionv11">

===== Handling JSON Metadata =====
The SDK methods handle 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.
<syntaxhighlight lang="java">
JSONObject contentMetadata = new JSONObject()
//SDK Metadata
.put("type", "content")
.put("assetid", "vid345-67483")
.put("program", "The Big Bang Theory")
.put("title", "The Pants Alternative S03E18")
.put("crossId1", "EP009311820061") //optional
.put("crossId2", "Content Originator") //optional
.put("length", "3600")
.put("isfullepisode", "yes")
.put("airdate", "2022-03-21T10:05:00")
.put("adloadtype", "2")
.put("segB", "CustomSegmentValueB") //optional
.put("segC", "CustomSegmentValueC") //optional

</syntaxhighlight>

=== Content metadata ===
Content metadata should remain constant throughout the entirety of an episode/clip.

{| class="wikitable"
|-
! '''Keys''' !! '''Description''' !! '''Values''' !! '''Required'''!!'''Provider'''
|-
| type || Type of asset ||For Video use: <code>content</code><br> For Static or text <code>static</code> || Yes || Nielsen
|-style="background-color:#e9f9fa;"
| assetid || Unique ID assigned to asset <br> Note: Refrain from using the following special characters [[Special_Characters|(Special Characters)]]. || Examples: <br> <code>BBT345a234 </code> <br> <code>CBSs5e234F2021</code> || Yes || Client
|-
| program ||Complete program or movie title <br> (no abbreviations or shorthand) <br> Note: there is a 25 character limit. ||<code> The Big Bang Theory</code> <br> <code> TheBigBangTheory</code> <br><code> The Dark Knight</code> <br><code> TheDarkKnight</code> <br> || Yes || Client
|-style="background-color:#e9f9fa;"
| title ||Episode title with season and episode number (40 character limit) <br> (Formats accepted: S01E03, S1E3, S1 E3). || Examples: <br> <code>The Pants Alternative S03E18</code> <br> <code>The Pants Alternative S3E18</code> <br> <code>The Pants Alternative S3 E18</code> <br> Can also accept: <code> S3E18</code> <br> Not Valid: <code> 318 </code> or <code> 0318 </code>|| Yes || Client
|-
| crossId1 || Gracenote TMS ID (If available) should be passed for all telecasted content for clients using the Gracenote solution for proper matching purposes. <br>Note: The TMS ID will be a 14 character string. Normally leading with 2 alpha characerts ('EP', 'MV', 'SH' or 'SP'), followed by 12 numbers.
|| The TMS ID will be a 14 character string. <br> Normally being with 'EV,' 'EP', 'SH', 'SP', or 'MV' <br> Followed by 12 numbers after the initial two letter prefix. <br> <br> The Giant Morning Show: <code>SH009311820022</code> <br> The Pants Alternative Episode : <code>EP009311820061</code> || Optional || Nielsen
|-style="background-color:#e9f9fa;"
| crossId2 || Populated by content distributor to contribute viewing from that distributor to the given content originator. || Custom<br>For a full list of acceptable values, please contact your Nielsen reprentative. || Yes, for distributors || Nielsen
|-
| length || Length of content in seconds<br>Note: Integers and decimals are acceptable values are acceptable for the length parameter. || Examples:
<small>For standard VOD content - <code>300</code> to represent 5 minutes, <code>1320</code> to represent 22 minutes, etc.
<br>If DAI live stream of a discrete program (Live Event/Sporting Event), pass length of content. See example for standard VOD content above.
<br>If unknown DAI live steam, pass a value of <code>0</code>.</small>
|| Yes || Client
|-style="background-color:#e9f9fa;"
| airdate ||Original broadcast or release date for the program <br>For USA, date should be EST <br> Outside USA, date should be local time.<br>If not applicable or available, original broadcast or release date for the Program. || Acceptable Formats:<br><code>YYYY-MM-DDTHH:MI:SS</code><br><code>YYYY-MM-DDHH:MI:SS</code><br><code>YYYY-MM-DDTHH:MI:SS+xx:xx</code><br><code>YYYY-MM-DDTHH:MI:SS-xx:xx</code><br><code>YYYYMMDDHH:MI:SS</code><br><code>YYYYMMDD HH:MI:SS</code><br><code>MM-DD-YYYY</code><br><code>MM/DD/YYYY</code><br><code>YYYYMMDD</code></big> || Yes || Client
|-
| isfullepisode || Full episode flag to identify differences between long form content. || <code>y</code>- full episode, <code>n</code>- non full episode(clip,teaser,promo,etc.)
<small>Also accept:
<br><code>lf</code> or <code>yes</code>- longform
<br><code>sf</code> or <code>no</code>- shortform
|| Yes || Nielsen
|-style="background-color:#e9f9fa;"
| adloadtype || <big><small>Type of ad load:
<code>1</code> Linear – matches TV ad load<br><code>2</code> Dynamic – Dynamic Ad Insertion (DAI)</small></big>
|| <code>2</code> - DCR measures content with dynamic ads || Yes || Nielsen
|-
| segB || One of two custom segment for the clients granular reporting within a brand. || Examples:<br>Genre - <code>horror</code>, <code>comedy</code>, etc.<br>Timeslot - <code>primetime</code>, <code>daytime</code>, etc.<br>News type - <code>breakingnews</code>, <code>weather</code>, etc. || Optional || Client
|-style="background-color:#e9f9fa;"
| segC || One of two custom segment for the clients granular reporting within a brand. || Examples:<br>Genre - <code>horror</code>, <code>comedy</code>, etc.<br>Timeslot - <code>primetime</code>, <code>daytime</code>, etc.<br>News type - <code>breakingnews</code>, <code>weather</code>, etc. || Optional || Client
|}
Custom segments (segB and segC) can be used to aggregate video and/or static content within a single Brand to receive more granular reports within a brand.

Examples regarding usage of segments within SDK:
* All comedy clips and stories for a Brand rolled into a "Comedy" segment
* genre grouping content by Comedy vs. Drama
* group related Text + Video content - i.e. for a show that has a lot of - static pages associated with it
* packaging based on how clients sell inventory
* grouping related types of content either by genre, category or platform.
<br />

</div>

==== Android DCR Video Step 4 - Basic Set of Events - Sample Playback ====
<span class="mw-customtoggle-myDivisionv12" style="color: cornflowerblue"> Show/hide step 4 </span>
<div class="mw-collapsible mw-collapsed" id="mw-customcollapsible-myDivisionv12">

===== Configure API Calls =====

===== SDK Events =====
{| class="wikitable"
|-
! Event !! Parameter !! Description
|-
| 'play' || || Call at start of each new stream
|-
| 'loadMetadata' || content/ad metadata object || Needs to be called at the beginning of each asset
|-
| 'setPlayheadPosition' || playhead position as integer<br/>
VOD: || current position in seconds <br/>
Live: current Unix timestamp (seconds since Jan-1-1970 UTC) <br/>
Note: 'setPlayheadPosition' has to be called every second
||
Pass playhead position every second during playback
|-
| 'stop' || playhead position || Call during any interruption to content or Ad playback and at the end of each Ad.
|-
| 'end' || playhead position in seconds || Call when the current video asset completes playback and pass the playhead position. <br/>
Example: At the end of the content stream, if the user switches to another piece of content, when the browser is refreshed or closed.
|}
<blockquote>Note: For livestream, send the Unix timestamp; for VOD send the time in seconds as integer. The final playhead position must be sent for the current asset being played before calling <code>'''stop'''</code>, <code>'''end'''</code> or<code> '''loadmetadata'''</code>,.</blockquote>

=== Life cycle of SDK instance ===
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. Once Initialized, 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. The <code>'''play'''</code> and <code>'''loadMetadata''' </code> calls move the SDK instance into this state. In this state, the SDK instance will be able to process the following calls.
## <code>'''setplayheadPosition'''</code> – Call this API every one second when playhead position timer is fired. If a LIVE event, use the current Unix timestamp (seconds since Jan-1-1970 UTC).
## <code>'''stop'''</code> – Call this API when the playback is paused, switches between content and ad (within the same content playback) or encounters interruptions.
## <code>'''end'''</code> – Call when content completes. When called, the SDK instance exits from Processing state.
# '''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
## <code>'''appDisableApi'''</code> is set to <code>true</code>

'''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, <code>'''loadMetadata''' </code> and <code>'''playheadPosition'''</code> </blockquote>

=== API Call Sequence ===
==== Sample Use Case: Content has no Advertisements ====
Call [[play()]] at start of stream

Call [[loadMetadata()]] with JSON metadata for content as below.
<syntaxhighlight lang="json">{
"type": "content",
"assetid": "vid345-67483",
"program": "ProgramName",
"title": "Program S3, EP1",
"length": "3600",
...
}</syntaxhighlight>
Call [[setPlayheadPosition()]] every one second until a pause / stop.
Use the sample API sequence below as a reference to identify the specific events that need to be called during content playback without ads.
{| class="wikitable"
|-
! Type !! Sample code !! Description
|-
| rowspan="2" | Start of stream || <code>mAppSdk.play(); </code> || // Call at start of each new stream
|-
| <code>mAppSdk.loadMetadata(contentMetaDataObject);</code> || // contentMetadataObject contains the JSON metadata for the content being played
|-
| Content || <code>mAppSdk.setPlayheadPosition(playheadPosition);</code> || // position is position of the playhead while the content is being played
|-
| Interruption || <code>mAppSdk.stop();</code> || // call stop when content playback is interrupted
|-
| rowspan="2" | Resume Content || <code>mAppSdk.loadMetadata(contentMetaDataObject);</code> || // Call loadMetadata and pass content metadata object when content resumes
|-
|<code>mAppSdk.setPlayheadPosition(playheadPosition);</code> || // continue pasing playhead position every second starting from position where content is resumed
|-
| End of Stream || <code>mAppSdk.end();</code> || // Content playback is completed.
|}

</div>

==== Keep Going ====
<span class="mw-customtoggle-myDivisionv13" style="color: cornflowerblue"> Show/hide </span>
<div class="mw-collapsible mw-collapsed" id="mw-customcollapsible-myDivisionv13">

Congratulations, you've successfully integrated the Android SDK in your app for a basic content playback scenario!

You can add more content to see channel-change scenarios or continue to next steps below.

View your application's debug logs and search for the term (AppSDK) to see messages emitted by Nielsen AppSDK during video playback.

</div>

==== Next Steps ====
<span class="mw-customtoggle-myDivisionv14" style="color: cornflowerblue"> Show/hide </span>
<div class="mw-collapsible mw-collapsed" id="mw-customcollapsible-myDivisionv14">
====Going Live====

In addition to the basic steps above, before going live developers need to handle app background/foreground events, make certain privacy disclosures, handle interruption events (stop, fast-forward, rewind), and allow users to opt out of Nielsen measurement. More details can be found [[DCR_Video_Android_SDK|here]], along with a more comprehensive reference for implementing DCR Video measurement with AppSDK.

Once the DCR Tracking Code is added, Nielsen will validate the implementation. Following Nielsen testing, developers need to make a few updates to the initialization call to ensure that the app is being measured properly.

#'''App ID''': Ensure that correct is used during initialization '''PXXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX'''
#'''Debug Logging''': Disable logging by changing initialization call to use @"nol_devDebug":@"INFO".

</div>

</div>

== → Android DTVR (coming soon) ==

</div>

Android Step By Step

2023-07-27T13:13:17Z

NickParrucci:

{{Breadcrumb|}} {{Breadcrumb|Digital}} {{CurrentBreadcrumb}}
[[Category:Digital]]
__NOTOC__

Provided below are step-by-step quick start guides for implementing Nielsen Android SDK for DCR Static, DCR Video, and DTVR products. Click each section to get started.

== → Android DCR Static ==
<span class="mw-customtoggle-myDivision" style="color: cornflowerblue"> Show/hide DCR Static </span>
<div class="mw-collapsible mw-collapsed" id="mw-customcollapsible-myDivision">

==== Android DCR Static Introduction ====
<span class="mw-customtoggle-myDivision1" style="color: cornflowerblue"> Show/hide Intro </span>
<div class="mw-collapsible mw-collapsed" id="mw-customcollapsible-myDivision1">

The Digital Content Ratings (DCR) Static product provides content consumption measurement on client webpages. This measurement includes insight into the total time a user spent on a webpage, how they navigated through the page via links, and many other data points.
This tutorial provides the steps to implement the DCR Static product in a sample Android app. It includes:

*SDK Initialization Call
*DCR Static Metadata: information about the sections being tracked

By the end of this guide you will have the needed steps to integrate Nielsen's AppSDK in the background of your app.
</div>

=== Android DCR Static Step 1 - Obtain AppID ===
<span class="mw-customtoggle-myDivision2" style="color: cornflowerblue"> Show/hide step 1 </span>
<div class="mw-collapsible mw-collapsed" id="mw-customcollapsible-myDivision2">

To begin using the Android SDK (AppSDK) you will need to obtain an Application ID (AppId)

{| class="wikitable"
|-
! !! Item !! Description !! Source
|-
|✅ || App ID (appid) || Unique ID assigned to the player/site and configured by product || Contact your Nielsen TAM

|}

The appid is a 37 character unique ID assigned to the player/site and configured by product and is required when creating a new instance of the AppSDK in the app.
</br>Example: '''PXXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXX'''

</div>

=== Android DCR Static Step 2 - SDK Initialization ===
<span class="mw-customtoggle-myDivision3" style="color: cornflowerblue"> Show/hide step 2 </span>
<div class="mw-collapsible mw-collapsed" id="mw-customcollapsible-myDivision3">

==== How to obtain the NielsenAppApi ====
The Nielsen AppSDK can either be downloaded directly or can be integrated into an application through the use of Gradle. We recommend using the Gradle-based integration whenever possible to ensure you maintain the most recent changes and enhancements to the Nielsen libraries.
* [[Digital_Measurement_Android_Artifactory_Guide|Select to obtain Gradle implementation guide]]
* [[Special:Downloads|Select to Download Directly]]

==== SDK Initialization ====

The following table contains the list of arguments that can be passed via the AppInfo JSON schema.
{| class="wikitable"
|-
! Parameter / Argument !! Description !! Source !! Required? !! Example
|-
| appid || Unique Nielsen ID for the application. The ID is a GUID data type. If you did not receive your App ID, let us know and we will provide you. || Nielsen-specified || Yes || PXXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX
|-
| nol_devDebug || Enables Nielsen console logging. Only required for testing
|| Nielsen-specified || Optional || "DEBUG"
|}

==== Debug flag for development environment ====
Player application developers / integrators can use Debug flag to check whether an App SDK API call made is successful. To activate the Debug flag,
Pass the argument <code>@"nol_devDebug":@"INFO"</code>, in the JSON string . The permitted values are:

* '''INFO''': Displays the API calls and the input data from the application (validate player name, app ID, etc.). It can be used as certification Aid.
* '''WARN''': Indicates potential integration / configuration errors or SDK issues.
* '''ERROR''': Indicates important integration errors or non-recoverable SDK issues.
* '''DEBUG''': Debug logs, used by the developers to debug more complex issues.

Once the flag is active, it logs each API call made and the data passed. The log created by this flag is minimal.
<blockquote>'''Note''': DO NOT activate the Debug flag in a production environment.</blockquote>

==== Sample SDK Initialization Code ====

'''Initialization of App SDK object through a JSON object'''
<syntaxhighlight lang="java">try
{
// Prepare AppSdk configuration object (JSONObject)
JSONObject appSdkConfig = new JSONObject()
.put("appid", "PDA7D5EE6-B1B8-XXXX-XXXX-2A788BCXXXCA")
.put("nol_devDebug", "DEBUG"); // only for debug builds

// Pass appSdkConfig to the AppSdk constructor
mAppSdk = new AppSdk(appContext, appSdkConfig, appSdkListener);
}
catch (JSONException e)
{
Log.e(TAG, "Couldn’t prepare JSONObject for appSdkConfig", e);
}
</syntaxhighlight>
Here, <code>appContext</code> is the App context object and <code>appSdkConfig</code> is JSON object for holding the parameters (<code>appid</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.

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

</div>

=== Android DCR Static Step 3 - Create/Load DCR Static Metadata Object ===
<span class="mw-customtoggle-myDivision4" style="color: cornflowerblue"> Show/hide step 3 </span>
<div class="mw-collapsible mw-collapsed" id="mw-customcollapsible-myDivision4">

==== Configure Metadata ====
Map the Nielsen keys to variables so that the content metadata is dynamically updated.

The Nielsen reserved keys are:
{| class="wikitable"
|-
! Key !! Description !! Data Type !! Value !! Required?
|-
| type || asset type || fixed || <code>'static'</code> || Yes
|-
| assetid || Unique ID for each article || dynamic || custom <br>(no [[Special Characters]]) || No
|-
| section || section of each site (e.g. section value should be first level in page URL: website.com/section). Limit to 25 unique values || dynamic || custom || Yes
|-
| segA || custom segment for reporting: Limit to 25 unique values across custom segments (segA + segB + segC) || dynamic || custom || No
|-
| segB || custom segment for reporting: Limit to 25 unique values across custom segments (segA + segB + segC) || dynamic || custom || No
|-
| segC || custom segment for reporting: Limit to 25 unique values across custom segments (segA + segB + segC) || dynamic || custom || No
|}

The values passed through the Nielsen keys will determine the breakouts that are seen in reporting. The custom segments (A, B & C) will roll into the sub-brand. To not use custom segments A, B and C, do not pass any value in these keys.

==== Configure API calls - loadMetadata ====
Use [[loadMetadata]] to pass 'content' [[Digital Measurement Metadata]]. The CMS data must be passed as a JSON object.
<syntaxhighlight lang="java"> loadMetadata(JSONObject jsonMetadata);</syntaxhighlight>
Refer to [[Digital Measurement Metadata]] for the list of parameters to be passed in the JSON object.
<blockquote>Note: The [[loadMetadata]] call must have ("type": "static"). </blockquote>

Call [[loadMetadata]] with JSON metadata as below.
<syntaxhighlight lang="java"> new JSONObject()
.put("type", "static")
.put("section", "siteSection")
.put("assetid", "vid345-67483")
.put("segA", "segmentA")
.put("segB", "segmentB")
.put("segC","segmentC")
}</syntaxhighlight>

As soon as this loadMetadata call is made, AppSDK will record a view event and start tracking the section/page time spent (AppSDK 9.1 and above).

==== DCR Static Duration Measurement per Section/Page/Asset ====
If your Nielsen AppID is enabled for DCR Static duration measurement, a view event will be recorded and a timer will be started for each screen/page. Duration will be measured until a new page is loaded or the app is moved to the background. The event which triggers recognition of page view and timer start is the loadMetadata API call with a metadata object of type 'static'. Once a page is viewed and the timer has started, duration will be measured until a new page has loaded ''with associated loadMetadata call having a different '''section name''' from the previous page''. If a new loadMetadata call is made with the same '''section name''', it will be ignored - no new view will be recorded. If it is desired to have a new view event even though the metadata contains the same '''section name''' (example: single-page apps having several assedIDs but common section name), staticEnd API can be called between page views. For the purposes of this overview, staticend will not be used. See [[DCR_Static_Android_SDK|this page]] for more information. <br>

</div>

=== Keep Going ===
<span class="mw-customtoggle-myDivision5" style="color: cornflowerblue"> Show/hide </span>
<div class="mw-collapsible mw-collapsed" id="mw-customcollapsible-myDivision5">

Congratulations, you've successfully integrated the Android SDK in your app!

You can add static loadMetadata calls for more sections/pages in your app to see what happens when transitioning between sections.

View your application's debug logs and search for the term (AppSDK) to see messages emitted by Nielsen AppSDK.

</div>

=== Next Steps ===
<span class="mw-customtoggle-myDivision6" style="color: cornflowerblue"> Show/hide </span>
<div class="mw-collapsible mw-collapsed" id="mw-customcollapsible-myDivision6">

Now that you've integrated DCR Static for the AppSDK, what's next?

====Going Live====

In addition to the basic steps above, before going live developers need to handle app background/foreground events, make certain privacy disclosures, and allow users to opt out of Nielsen measurement. More details can be found [[DCR_Static_Android_SDK|here]], along with a more comprehensive reference for implementing DCR Static measurement with AppSDK.

Once the DCR Tracking Code is added, Nielsen will validate the implementation. Following Nielsen testing, developers need to make a few updates to the initialization call to ensure that the app is being measured properly.

#'''App ID''': Ensure that correct is used during initialization '''PXXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX'''
#'''Debug Logging''': Disable logging by changing initialization call to use @"nol_devDebug":@"INFO".

</div>

</div>

== → Android DCR Video ==

<span class="mw-customtoggle-myDivision7" style="color: cornflowerblue"> Show/hide DCR Video </span>
<div class="mw-collapsible mw-collapsed" id="mw-customcollapsible-myDivision7">
==== Android DCR Video Introduction ====
<span class="mw-customtoggle-myDivisionv8" style="color: cornflowerblue"> Show/hide Intro </span>
<div class="mw-collapsible mw-collapsed" id="mw-customcollapsible-myDivisionv8">

The Digital Content Ratings (DCR) Video product provides content consumption measurement on client webpages. This measurement includes insight into the total time a user spent watching the tracked content, video player events, and much more.
This example provides the steps to implement the DCR Video product in a sample Android app. It includes:

*SDK Initialization
*DCR Video Metadata: information about the content being tracked
*DCR Video Events/API calls

By the end of this guide you will have the needed steps to integrate Nielsen's AppSDK in the background of your app.

</div>

==== Android DCR Video Step 1 - Obtain AppID ====
<span class="mw-customtoggle-myDivisionv9" style="color: cornflowerblue"> Show/hide step 1 </span>
<div class="mw-collapsible mw-collapsed" id="mw-customcollapsible-myDivisionv9">

To begin using the Android AppSDK, you will need to obtain an Application ID (AppId)

{| class="wikitable"
|-
! !! Item !! Description !! Source
|-
|✅ || App ID (appid) || Unique ID assigned to the player/site and configured by product || Contact your Nielsen Representative

|}

The appid is a 37 character unique ID assigned to the player/site and configured by product and is required when creating a new instance of the AppSDK in the app.
</br>Example: '''PXXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXX'''

</div>

==== Android DCR Video Step 2 - SDK Initialization ====
<span class="mw-customtoggle-myDivision10" style="color: cornflowerblue"> Show/hide step 2 </span>
<div class="mw-collapsible mw-collapsed" id="mw-customcollapsible-myDivision10">

===== Setting up your Development Environment =====
===== Configuring Android Development Environment =====
*The Nielsen App SDK (located in the [https://engineeringportal.nielsen.com/docs/Special:Downloads Downloads section] of the website) class is the primary application interface to the Nielsen App SDK on Android.
*The Nielsen App SDK class is defined as the only public class belonging to the com.nielsen.app.sdk package.
*The Nielsen App SDK can also be added via [https://engineeringportal.nielsen.com/docs/Digital_Measurement_Android_Artifactory_Guide Artifact Repository].

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.

Once SDK is downloaded ensure to unzip the Nielsen SDK and copy the AppSdk.jar in your app (Android Studio) libs folder, then right click the AppSdk.jar and select '''Add As Library'''.
Ensure the AppSdk.jar file is added in 'build.gradle (App Level) file.
* App SDK 1.2 provides support for x86, mips, and armeabi-7a architecture.

===== Google Play Services =====
Add the Google Play Services in the project,
Steps: Android Studio -> File -> Project Structure ->(In module selection) select App -> Dependencies (tab) -> Click "+" button and search for <code>"*play-services*"</code>. Then select the most recent version of the play-services Artifact.
Ensure it is added in build.gradle (App level) file

===== Google AD ID Permissions =====
The following is required if target API level is set to 31 (Android 12) with the Ad Version of the Nielsen SDK.

<syntaxhighlight lang="java">
<uses-permission android:name="com.google.android.gms.permission.AD_ID"/>
</syntaxhighlight>
</br>

====== Manifest File ======
* Add the following permissions on the project’s ''AndroidManifest.xml'' file.
<syntaxhighlight lang="java">
<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].

* In <code>AndroidManifest.xml </code>under <code><application></code> add the following metadata

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

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

===== Library =====
Nielsen App SDK uses the following packages/classes from the Google Play service.
* google-play-services_lib

===== Classes/package =====
* com.google.android.gms.ads.identifier.AdvertisingIdClient;
* com.google.android.gms.ads.identifier.AdvertisingIdClient.Info;
* com.google.android.gms.common.ConnectionResult;
* com.google.android.gms.common.GooglePlayServicesUtil;
* com.google.android.gms.common.GooglePlayServicesRepairableException;
* com.google.android.gms.common.GooglePlayServicesNotAvailableException;

===== SDK Initialization =====

The following table contains the list of arguments that can be passed via the AppInfo JSON schema.
{| class="wikitable"
|-
! Parameter / Argument !! Description !! Source !! Required? !! Example
|-
| appid || Unique Nielsen ID for the application. The ID is a GUID data type. If you did not receive your App ID, let us know and we will provide you. || Nielsen-specified || Yes || PXXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX
|-
| nol_devDebug || Enables Nielsen console logging. Only required for testing
|| Nielsen-specified || Optional || "DEBUG"
|}
== Debug flag for development environment ==
Player application developers / integrators can use Debug flag to check whether an App SDK API call made is successful. To activate the Debug flag,
Pass the argument <code>@"nol_devDebug":@"DEBUG"</code>, in the JSON string . The permitted values are:

* '''INFO''': Displays the API calls and the input data from the application (validate player name, app ID, etc.). It can be used as certification Aid.
* '''WARN''': Indicates potential integration / configuration errors or SDK issues.
* '''ERROR''': Indicates important integration errors or non-recoverable SDK issues.
* '''DEBUG''': Debug logs, used by the developers to debug more complex issues.

Once the flag is active, it logs each API call made and the data passed. The log created by this flag is minimal.
<blockquote>'''Note''': DO NOT activate the Debug flag in a production environment.</blockquote>

==== Sample SDK Initialization Code ====

'''Initialization of App SDK object through a JSON object'''
<syntaxhighlight lang="java">try
{
// Prepare AppSdk configuration object (JSONObject)
JSONObject appSdkConfig = new JSONObject()
.put("appid", "PDA7D5EE6-B1B8-XXXX-XXXX-2A788BCXXXCA")
.put("nol_devDebug", "DEBUG"); // only for debug builds

// Pass appSdkConfig to the AppSdk constructor
mAppSdk = new AppSdk(appContext, appSdkConfig, appSdkListener);
}
catch (JSONException e)
{
Log.e(TAG, "Couldn’t prepare JSONObject for appSdkConfig", e);
}
</syntaxhighlight>
Here, <code>appContext</code> is the App context object and <code>appSdkConfig</code> is JSON object for holding the parameters (<code>appid</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.

The integration of Nielsen App SDK will depend on type of client app.<br />
* 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).

</div>

==== Android DCR Video Step 3 - Create DCR Video Content Metadata Object ====
<span class="mw-customtoggle-myDivisionv11" style="color: cornflowerblue"> Show/hide step 3 </span>
<div class="mw-collapsible mw-collapsed" id="mw-customcollapsible-myDivisionv11">

===== Handling JSON Metadata =====
The SDK methods handle 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.
<syntaxhighlight lang="java">
JSONObject contentMetadata = new JSONObject()
//SDK Metadata
.put("type", "content")
.put("assetid", "vid345-67483")
.put("program", "The Big Bang Theory")
.put("title", "The Pants Alternative S03E18")
.put("crossId1", "EP009311820061") //optional
.put("crossId2", "Content Originator") //optional
.put("length", "3600")
.put("isfullepisode", "yes")
.put("airdate", "2022-03-21T10:05:00")
.put("adloadtype", "2")
.put("segB", "CustomSegmentValueB") //optional
.put("segC", "CustomSegmentValueC") //optional

</syntaxhighlight>

=== Content metadata ===
Content metadata should remain constant throughout the entirety of an episode/clip.

{| class="wikitable"
|-
! '''Keys''' !! '''Description''' !! '''Values''' !! '''Required'''!!'''Provider'''
|-
| type || Type of asset ||For Video use: <code>content</code><br> For Static or text <code>static</code> || Yes || Nielsen
|-style="background-color:#e9f9fa;"
| assetid || Unique ID assigned to asset <br> Note: Refrain from using the following special characters [[Special_Characters|(Special Characters)]]. || Examples: <br> <code>BBT345a234 </code> <br> <code>CBSs5e234F2021</code> || Yes || Client
|-
| program ||Complete program or movie title <br> (no abbreviations or shorthand) <br> Note: there is a 25 character limit. ||<code> The Big Bang Theory</code> <br> <code> TheBigBangTheory</code> <br><code> The Dark Knight</code> <br><code> TheDarkKnight</code> <br> || Yes || Client
|-style="background-color:#e9f9fa;"
| title ||Episode title with season and episode number (40 character limit) <br> (Formats accepted: S01E03, S1E3, S1 E3). || Examples: <br> <code>The Pants Alternative S03E18</code> <br> <code>The Pants Alternative S3E18</code> <br> <code>The Pants Alternative S3 E18</code> <br> Can also accept: <code> S3E18</code> <br> Not Valid: <code> 318 </code> or <code> 0318 </code>|| Yes || Client
|-
| crossId1 || Gracenote TMS ID (If available) should be passed for all telecasted content for clients using the Gracenote solution for proper matching purposes. <br>Note: The TMS ID will be a 14 character string. Normally leading with 2 alpha characerts ('EP', 'MV', 'SH' or 'SP'), followed by 12 numbers.
|| The TMS ID will be a 14 character string. <br> Normally being with 'EV,' 'EP', 'SH', 'SP', or 'MV' <br> Followed by 12 numbers after the initial two letter prefix. <br> <br> The Giant Morning Show: <code>SH009311820022</code> <br> The Pants Alternative Episode : <code>EP009311820061</code> || Optional || Nielsen
|-style="background-color:#e9f9fa;"
| crossId2 || Populated by content distributor to contribute viewing from that distributor to the given content originator. || Custom<br>For a full list of acceptable values, please contact your Nielsen reprentative. || Yes, for distributors || Nielsen
|-
| length || Length of content in seconds<br>Note: Integers and decimals are acceptable values are acceptable for the length parameter. || Examples:
<small>For standard VOD content - <code>300</code> to represent 5 minutes, <code>1320</code> to represent 22 minutes, etc.
<br>If DAI live stream of a discrete program (Live Event/Sporting Event), pass length of content. See example for standard VOD content above.
<br>If unknown DAI live steam, pass a value of <code>0</code>.</small>
|| Yes || Client
|-style="background-color:#e9f9fa;"
| airdate ||Original broadcast or release date for the program <br>For USA, date should be EST <br> Outside USA, date should be local time.<br>If not applicable or available, original broadcast or release date for the Program. || Acceptable Formats:<br><code>YYYY-MM-DDTHH:MI:SS</code><br><code>YYYY-MM-DDHH:MI:SS</code><br><code>YYYY-MM-DDTHH:MI:SS+xx:xx</code><br><code>YYYY-MM-DDTHH:MI:SS-xx:xx</code><br><code>YYYYMMDDHH:MI:SS</code><br><code>YYYYMMDD HH:MI:SS</code><br><code>MM-DD-YYYY</code><br><code>MM/DD/YYYY</code><br><code>YYYYMMDD</code></big> || Yes || Client
|-
| isfullepisode || Full episode flag to identify differences between long form content. || <code>y</code>- full episode, <code>n</code>- non full episode(clip,teaser,promo,etc.)
<small>Also accept:
<br><code>lf</code> or <code>yes</code>- longform
<br><code>sf</code> or <code>no</code>- shortform
|| Yes || Nielsen
|-style="background-color:#e9f9fa;"
| adloadtype || <big><small>Type of ad load:
<code>1</code> Linear – matches TV ad load<br><code>2</code> Dynamic – Dynamic Ad Insertion (DAI)</small></big>
|| <code>2</code> - DCR measures content with dynamic ads || Yes || Nielsen
|-
| segB || One of two custom segment for the clients granular reporting within a brand. || Examples:<br>Genre - <code>horror</code>, <code>comedy</code>, etc.<br>Timeslot - <code>primetime</code>, <code>daytime</code>, etc.<br>News type - <code>breakingnews</code>, <code>weather</code>, etc. || Optional || Client
|-style="background-color:#e9f9fa;"
| segC || One of two custom segment for the clients granular reporting within a brand. || Examples:<br>Genre - <code>horror</code>, <code>comedy</code>, etc.<br>Timeslot - <code>primetime</code>, <code>daytime</code>, etc.<br>News type - <code>breakingnews</code>, <code>weather</code>, etc. || Optional || Client
|}
Custom segments (segB and segC) can be used to aggregate video and/or static content within a single Brand to receive more granular reports within a brand.

Examples regarding usage of segments within SDK:
* All comedy clips and stories for a Brand rolled into a "Comedy" segment
* genre grouping content by Comedy vs. Drama
* group related Text + Video content - i.e. for a show that has a lot of - static pages associated with it
* packaging based on how clients sell inventory
* grouping related types of content either by genre, category or platform.
<br />

</div>

==== Android DCR Video Step 4 - Basic Set of Events - Sample Playback ====
<span class="mw-customtoggle-myDivisionv12" style="color: cornflowerblue"> Show/hide step 4 </span>
<div class="mw-collapsible mw-collapsed" id="mw-customcollapsible-myDivisionv12">

===== Configure API Calls =====

===== SDK Events =====
{| class="wikitable"
|-
! Event !! Parameter !! Description
|-
| 'play' || || Call at start of each new stream
|-
| 'loadMetadata' || content/ad metadata object || Needs to be called at the beginning of each asset
|-
| 'setPlayheadPosition' || playhead position as integer<br/>
VOD: || current position in seconds <br/>
Live: current Unix timestamp (seconds since Jan-1-1970 UTC) <br/>
Note: 'setPlayheadPosition' has to be called every second
||
Pass playhead position every second during playback
|-
| 'stop' || playhead position || Call during any interruption to content or Ad playback and at the end of each Ad.
|-
| 'end' || playhead position in seconds || Call when the current video asset completes playback and pass the playhead position. <br/>
Example: At the end of the content stream, if the user switches to another piece of content, when the browser is refreshed or closed.
|}
<blockquote>Note: For livestream, send the Unix timestamp; for VOD send the time in seconds as integer. The final playhead position must be sent for the current asset being played before calling <code>'''stop'''</code>, <code>'''end'''</code> or<code> '''loadmetadata'''</code>,.</blockquote>

=== Life cycle of SDK instance ===
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. Once Initialized, 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. The <code>'''play'''</code> and <code>'''loadMetadata''' </code> calls move the SDK instance into this state. In this state, the SDK instance will be able to process the following calls.
## <code>'''setplayheadPosition'''</code> – Call this API every one second when playhead position timer is fired. If a LIVE event, use the current Unix timestamp (seconds since Jan-1-1970 UTC).
## <code>'''stop'''</code> – Call this API when the playback is paused, switches between content and ad (within the same content playback) or encounters interruptions.
## <code>'''end'''</code> – Call when content completes. When called, the SDK instance exits from Processing state.
# '''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
## <code>'''appDisableApi'''</code> is set to <code>true</code>

'''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, <code>'''loadMetadata''' </code> and <code>'''playheadPosition'''</code> </blockquote>

=== API Call Sequence ===
==== Sample Use Case: Content has no Advertisements ====
Call [[play()]] at start of stream

Call [[loadMetadata()]] with JSON metadata for content as below.
<syntaxhighlight lang="json">{
"type": "content",
"assetid": "vid345-67483",
"program": "ProgramName",
"title": "Program S3, EP1",
"length": "3600",
...
}</syntaxhighlight>
Call [[setPlayheadPosition()]] every one second until a pause / stop.
Use the sample API sequence below as a reference to identify the specific events that need to be called during content playback without ads.
{| class="wikitable"
|-
! Type !! Sample code !! Description
|-
| rowspan="2" | Start of stream || <code>mAppSdk.play(); </code> || // Call at start of each new stream
|-
| <code>mAppSdk.loadMetadata(contentMetaDataObject);</code> || // contentMetadataObject contains the JSON metadata for the content being played
|-
| Content || <code>mAppSdk.setPlayheadPosition(playheadPosition);</code> || // position is position of the playhead while the content is being played
|-
| Interruption || <code>mAppSdk.stop();</code> || // call stop when content playback is interrupted
|-
| rowspan="2" | Resume Content || <code>mAppSdk.loadMetadata(contentMetaDataObject);</code> || // Call loadMetadata and pass content metadata object when content resumes
|-
|<code>mAppSdk.setPlayheadPosition(playheadPosition);</code> || // continue pasing playhead position every second starting from position where content is resumed
|-
| End of Stream || <code>mAppSdk.end();</code> || // Content playback is completed.
|}

</div>

==== Keep Going ====
<span class="mw-customtoggle-myDivisionv13" style="color: cornflowerblue"> Show/hide </span>
<div class="mw-collapsible mw-collapsed" id="mw-customcollapsible-myDivisionv13">

Congratulations, you've successfully integrated the Android SDK in your app for a basic content playback scenario!

You can add more content to see channel-change scenarios or continue to next steps below.

View your application's debug logs and search for the term (AppSDK) to see messages emitted by Nielsen AppSDK during video playback.

</div>

==== Next Steps ====
<span class="mw-customtoggle-myDivisionv14" style="color: cornflowerblue"> Show/hide </span>
<div class="mw-collapsible mw-collapsed" id="mw-customcollapsible-myDivisionv14">
====Going Live====

In addition to the basic steps above, before going live developers need to handle app background/foreground events, make certain privacy disclosures, handle interruption events (stop, fast-forward, rewind), and allow users to opt out of Nielsen measurement. More details can be found [[DCR_Video_iOS_SDK|here]], along with a more comprehensive reference for implementing DCR Video measurement with AppSDK.

Once the DCR Tracking Code is added, Nielsen will validate the implementation. Following Nielsen testing, developers need to make a few updates to the initialization call to ensure that the app is being measured properly.

#'''App ID''': Ensure that correct is used during initialization '''PXXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX'''
#'''Debug Logging''': Disable logging by changing initialization call to use @"nol_devDebug":@"INFO".

</div>

</div>

== → Android DTVR (coming soon) ==

</div>

DCR Italy Static iOS SDK

2023-07-20T12:16:40Z

NickParrucci:

DCR Italy Video iOS SDK

2023-07-20T12:16:06Z

NickParrucci:

{{Breadcrumb|}} {{Breadcrumb|Digital}} {{Breadcrumb|International DCR}} {{CurrentBreadcrumb}}
[[Category:Digital]]

== Overview ==
The Nielsen SDK is one of multiple framework SDKs that Nielsen provides to enable measuring linear (live) and on-demand TV viewing using TVs, mobile devices, etc.
The App SDK is the framework for mobile application developers to integrate Nielsen Measurement into their media player applications. It supports a variety of Nielsen Measurement Products like Digital in TV Ratings, Digital Content Ratings ([[DCR & DTVR]]), and [[Digital Ad Ratings]] (DAR). Nielsen SDKs are also equipped to measure static content and can track key life cycle events of an application like:
*Application launch events and how long app was running
*Time of viewing a page / sub section in the application.

== Prerequisites ==
Before you start the integration, you will need:
{| class="wikitable"
|-
! style="width: 15%;" | Item
! Description
! Source
|-
|| '''App ID (appid)''' || Unique ID assigned to the player/site and configured by product. || Provided by Nielsen
|-
|| '''Nielsen SDK''' || Includes SDK frameworks and '''sample implementation'''; ''See [[iOS SDK Release Notes]]'' || [[Special:Downloads|Download]]
|-
|| '''sfcode''' || Unique identifier for the environment that the SDK should point to || Provided by Nielsen
|}

If need App ID(s) or our SDKs, feel free to reach out to us and we will be happy to help you get started.
Refer to [[Digital Measurement Onboarding]] guide for information on how to get a Nielsen App SDK and appid.

=== Notes for WebView Contents ===
<code>Please note that if within your APP user can surf '''static contents''' recalled from your website the [[DCR_Italy_Static_Browser_SDK|browser static SDK]] have to inhibit from this pages.</code>
__TOC__

== Implementation ==
This guide covers implementation steps for iOS using Xcode utilizing the Standard Nielsen SDK for DCR.

<code>If you are building an app for the 'kids category' please review the [[DCR_Italy_Video_iOS_SDK#Special_Note_Regarding_Apps_in_the_Kids_Category|Opt Out Requirement.]]</code>

=== How to obtain the NielsenAppApi.Framework ===
The Nielsen AppSDK can either be downloaded directly or can be integrated directly within an application through the use of CocoaPods. We recommend using the CocoaPods-based integration whenever possible to ensure you maintain the most recent changes and enhancements to the Nielsen libraries.
* [[Digital_Measurement_iOS_Artifactory_Guide|Select to obtain CocoaPods implementation guide]]
* [[Special:Downloads|Select to Download Directly]]
* [[DCR_Video_iOS_SDK_xcframework|Using the XCFramework bundle]]

== Special Notes regarding iOS14 ==
=== Permission to Track ===

Apple recently released a new policy on consent requirements, that require the user's permission, to track them using their device's advertising identifier (IDFA). To request the user's permission, use the AppTrackingTransparency framework.

For more information, see:
* [https://developer.apple.com/documentation/apptrackingtransparency App Tracking Transparency]
* [https://developer.apple.com/design/human-interface-guidelines/ios/app-architecture/requesting-permission/ Human Interface Guidelines]
* [https://developer.apple.com/documentation/adsupport AdSupport Framework]

More detailed information on how the Nielsen SDK versions work with the AppTrackingTransparency framework is located on our [[ DCR Video iOS14 Migration|DCR Video iOS14 Migration]] page.

== Setting up your Development Environment ==
Prior to SDK Version 6.2.0.0 the IOS framework has been distributed as a static library packaged into framework bundle format. Apple recommends to use dynamic framework, it has some benefits over static libraries like less executable file size of an app, faster startup time and native support in xCode IDE. Nielsen AppSDK has been transformed into dynamic framework in this release ([[iOS_Static_Framework_Setup|static framework]] is still available).

If migrating from the static library to this new dynamic framework, once implemented, unless your specific application requires, you can remove the following Frameworks that were once required:<code> [AdSupport, JavascriptCore, SystemConfiguration, Security, AVFoundation, libc++] </code>
<br>

The '''Dynamic framework''' is created as a fat framework. It means that it contains slices required for devices (armv7, arm64) as well as slices required for simulators (i386, x86_64). Simulator slices are needed to let clients build and debug their app on the simulators, but they should be removed before sending the app to the AppStore. The example of the shell script that should be added as a Run Script phase in the application can be [[DCR_Video_iOS_SDK#Removing_Simulators_.28Dynamic_Framework_Only.29|found below]].

'''[[DCR_Video_iOS_SDK_xcframework|XCFramework]]''' is solution for the problems described above Apple recommends to use XCFrameworks. In XCFramework, we no longer build a single framework with multiple architectures. Instead, we build one small framework for each combination of architecture and target and store it in its own folder. The top-level XCFramework folder have folders like ios-arm64, ios-arm64-simulator, etc. Each of these folders is its own framework, complete with headers, modules, and binary.

=== Configuring Xcode Development Environment ===
Starting with SDK version 6.0.0.0, the Nielsen App SDK is compatible with Apple iOS versions 8.0 and above. In addition, when using the dynamic framework, all the required frameworks are linked automatically as the are needed. More details can be found here: https://stackoverflow.com/questions/24902787/dont-we-need-to-link-framework-to-xcode-project-anymore

<blockquote>'''Note''': All communications between the SDK and the Census (Collection Facility) use HTTPS.</blockquote>

=== Special Note for Static Framework ===
Starting from 8.2.0.0 release framework is build from the mixed (swift + objc) source code.
If [[iOS_Static_Framework_Setup|static (xc)framework is integrated additional settings]] should be applied to fix build or runtime issues.

=== Download Framework ===
The first step is to download and copy the [[Special:Downloads|NielsenAppApi.framework]] bundle to the app project directory. (''Not required if using CocaPods'')

=== Add Framework ===
In the General tab for app configuration add NielsenAppApi.framework in the list of Embedded Binaries. (''Not required if using CocaPods'')

=== Add Path ===
Add path to the NielsenAppApi.framework in the Framework Search Paths build setting. (''Not required if using CocaPods'')

=== Import Framework ===
Add NielsenAppApi.framework module in the source file of your app:

==== Using Swift ====
Add the following:
<syntaxhighlight lang="swift">
import NielsenAppApi
</syntaxhighlight>

==== Using Objective-C ====
<syntaxhighlight lang ="objective-c">
@import NielsenAppApi;
</syntaxhighlight>

==== xCode 12 building errors ====
Developers who uses "fat" framework in their apps started reporting the following error that they get building the app in xCode 12.3+:
<blockquote>Building for iOS Simulator, but the linked and embedded framework 'MyFramework.framework' was built for iOS + iOS Simulator.</blockquote>
The binary framework contains different code for the same architecture in multiple places, and Xcode doesn’t know how to handle it. There is workaround that people recommend to use in such cases:
* https://stackoverflow.com/questions/63267897/building-for-ios-simulator-but-the-linked-framework-framework-was-built
* https://stackoverflow.com/questions/63932158/xcode12-issus-ld-building-for-ios-simulator-but-linking-in-object-file-built

==== IPA processing failure ====
<code>Assertion failed: Expected 4 archs in otool output:</code>

The error above is due to the "fat" (simulator+device) framework which will not appear if you have not enabled Bitcode. To build your app with full Bitcode support, it is recommended that you use a [[DCR_Video_iOS_SDK_xcframework|XCFramework]] to avoid the 4 archs in otool output message.

== SDK Initialization ==
The latest version of the Nielsen App SDK allows instantiating multiple instances of the SDK object, which can be used simultaneously without any issue. The sharedInstance API that creates a singleton object was deprecated prior to version 5.1.1. [[Dual_Instances_of_SDK|(Click here for an example of multiple instances)]]

The following table contains the list of arguments that can be passed via the AppInfo JSON schema.
*The appid is provided by the Nielsen Technical Account Manager (TAM). The appid is a GUID data type and is specific to the application.
{| class="wikitable"
|-
! Parameter / Argument !! Description !! Source !! Required? !! Example
|-
| appid || Unique Nielsen ID for the application. The ID is a GUID data type. If you did not receive your App ID, let us know and we will provide you. || Nielsen-specified || Yes || PXXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX
|-
| appname || Name of the application
|| Client-defined || Yes || "Nielsen Sample App"
|-
| appversion || Current version of the app used
|| Client-defined || Yes || "1.0.2"
|-
| sfcode || Nielsen collection facility to which the SDK should connect.
Italian Clients:
*"it"
|| Nielsen-specified || Yes || "it"
|-
| nol_devDebug || Enables Nielsen console logging. Only required for testing
|| Nielsen-specified || Yes for Debugging / Testing App || "DEBUG"
|}

== Debug flag for development environment ==
Player application developers / integrators can use Debug flag to check whether an App SDK API call made is successful. To activate the Debug flag,
Pass the argument <code>@"nol_devDebug":@"DEBUG"</code>, in the JSON string . The permitted values are:

* '''INFO''': Displays the API calls and the input data from the application (validate player name, app ID, etc.). It can be used as certification Aid.
* '''WARN''': Indicates potential integration / configuration errors or SDK issues.
* '''ERROR''': Indicates important integration errors or non-recoverable SDK issues.
* '''DEBUG''': Debug logs, used by the developers to debug more complex issues.

Once the flag is active, it logs each API call made and the data passed. The log created by this flag is minimal.
<blockquote>'''Note''': Activate the Debug flag in a Test environment.</blockquote>

=== Sample SDK Initialization Code ===

==== App tracking transparency framework ====

To display the App Tracking Transparency authorization request for accessing the IDFA, update your <code>info.plist</code> to add the <code>NSUserTrackingUsageDescription</code> key with a custom message describing your usage. Below is an example description text:
<code><key>NSUserTrackingUsageDescription</key></code>
<code><string>This identifier will be used to deliver personalized ads to you.</string></code>

The system automatically generates the prompt’s title, which includes the name of your app, then the usage description appears as part of the App Tracking

To present the authorization request, call requestTrackingAuthorizationWithCompletionHandler.

<blockquote>Please NOTE: It is important to initialize the NielsenSDK after the ATTrackingManager has Authorized usage. When the SDK initializes, it checks the status of the ATTrackingManager.</blockquote>

You can find an example in the file [[Special:Downloads|Global iOS SDK Download]] from the '''SDK Downloads''' section, folder name NielsenSampleVideoPlayer.

====Swift 4.0 Example:====
<code>NielsenInit.swift</code>
<syntaxhighlight lang="swift">
import Foundation
import NielsenAppApi

class NielsenInit : NSObject {
class func createNielsenApi(delegate: NielsenAppApiDelegate) -> NielsenAppApi?{

let appInformation:[String: String] = [
"appid": "PDA7D5EE6-B1B8-4123-9277-2A788XXXXXXX",
"appversion": "1.0.2",
"appname": "Nielsen Sample App",
"sfcode": "it",
"nol_devDebug": "DEBUG"
]
return NielsenAppApi(appInfo:appInformation, delegate:delegate)
}
}
</syntaxhighlight>

===Sample code using AVPlayer===
<code>ViewController.swift</code>

<syntaxhighlight lang="swift">
class ViewController: UIViewController, NielsenAppApiDelegate, AVPictureInPictureControllerDelegate, CLLocationManagerDelegate {

let avPlayerViewController = AVPlayerViewController()
var avPlayer:AVPlayer?
var nielsenAppApi: NielsenAppApi!

override func viewDidLoad() {
super.viewDidLoad()

self.nielsenAppApi = NielsenInit.createNielsenAppApi(delegate: self)
NSLog("Nielsen SDK initialized")

}
}
</syntaxhighlight>

===Objective C ====
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>
<syntaxhighlight lang="objective-c">
#import "NlsAppApiFactory.h"
#import <NielsenAppApi/NielsenAppApi.h>

@implementation NlsAppApiFactory

+ (NielsenAppApi *)createNielsenAppApiWithDelegate:(id<NielsenAppApiDelegate>)delegate;
{

NSDictionary *appInformation = @{
@"appid": "PDA7D5EE6-B1B8-4123-9277-2A788XXXXXXX",
@"appversion": "1.0.2",
@"appname": "Nielsen Sample App",
@"sfcode": "it",
@"nol_devDebug": @"DEBUG"
};

return [[NielsenAppApi alloc] initWithAppInfo:appInformation delegate:delegate];
}

@end
</syntaxhighlight>

The following would be the <code>NlsAppApiFactory.h</code> file:
<syntaxhighlight lang="objective-c">
#import <Foundation/Foundation.h>

@class NielsenAppApi;
@protocol NielsenAppApiDelegate;

@interface NlsAppApiFactory : NSObject

+ (NielsenAppAPI *) createNielsenAppApiWithDelegate:(id<NielsenAppApiDelegate>)delegate;

@end
</syntaxhighlight>

=== Sample Code: ===
<syntaxhighlight lang="objective-c">
@implementation ViewController

- (void)viewDidLoad {
[super viewDidLoad];

//Getting the instance of Nielsen SDK
nielsenApi = [NlsAppApiFactory createNielsenAppApiWithDelegate:nil];
}}
</syntaxhighlight>



== APP SDK Error & Event Codes ==
To view the Error and Event codes for iOS, please review the [[APP SDK Event Codes|App SDK Event Code]] Reference page.

== Configure Metadata ==
=== 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 Nielsen Key names (e.g. appid, program) 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.
{{ExampleCode|
|Swift =
<syntaxhighlight lang="swift">

let channelInfo = [
"channelName": "My Channel Name 1",
];

let contentMetadata = [
"type": "content",
"assetid": "88675545",
"title": "Program S3, EP1",
"isfullepisode":"y",
"adloadtype":"2",
"program":"Program Name",
"length":"3600",
"airdate":"20171020 10:05:00"
];
</syntaxhighlight>
|Objective C = <syntaxhighlight lang="objective-c">
NSDictionary *channelInfo = @
{
@"channelName":@"My Channel Name 1",
}

NSDictionary * contentMetadata = @ {
@ "type": @ "content",
@ "assetid": @ "88675545",
@ "title": @ "Program S3, EP1",
@ "isfullepisode": @ "y",
@ "program": @ "Program Name",
@ "length": @ "3600",
@ "airdate": @ "20200321 10:05:00",
@ "adloadtype": @ "2"
}
</syntaxhighlight>
}}


=== Configure metadata ===
Configure metadata should remain constant throughout the completion of an episode or live stream
{| class="wikitable"
|-
! Keys !! Description !! Values !! Required
|-
| channelName || Any string representing the channel/stream || custom || Yes
|}

=== Content Metadata ===
Content metadata should remain constant throughout the entirety of an episode/clip including when ads play.
{| class="wikitable"
|-
! Keys !! Description !! Values !! Required
|-
| type || type of asset || <code>'content'</code> || Yes
|-
| assetid || unique ID assigned to asset (32 Character limit) || custom (no [[Special Characters|Special Characters]]) || Yes
|-
| program || name of program (100 character limit) || custom || Yes
|-
| title || name of program (100 character limit) || custom || Yes
|-
| length || length of content in seconds || <code>seconds</code> (0 for live stream) || Yes
|-
| airdate || the airdate in the linear TV || YYYYMMDD HH24:MI:SS || Yes
|-
| isfullepisode || full episode flag || <code>'y'</code>- full episode, <code>'n'</code>- non full episode || Yes
|-
| adloadtype || type of ad load:
*<code>'1'</code> Linear – matches TV ad load
*<code>'2'</code> Dynamic – Dynamic Ad Insertion (DAI)
|| <code>'2'</code> - DCR measures content with dynamic ads
|| Yes

|}

=== Ad Metadata ===
The Ad Metadata (if applicable) should be passed for each individual ad.
{| class="wikitable"
|-
! Keys !! Description !! Values !! Required
|-
| type || type of Ad || <code>'preroll'</code>, <code>'midroll'</code>, <code>'postroll'</code> || Yes
|-
| assetid || unique ID assigned to Ad || custom (no [[Special Characters|Special Characters]]) || Yes
|}

=== Example Ad Object ===
<syntaxhighlight lang="javascript">
// create Ad object
"ad": {
"type": "preroll",
"assetid": "AD-ID123"
}
</syntaxhighlight>

== Configure API Calls ==

=== Sample API Sequence ===
A Sample API sequence could follow this flow:
{| class="wikitable"
|-
! Type !! Sample code !! Description
|-
|On App Start||<syntaxhighlight lang=Swift>
NielsenInit.createMainBrandApi(delegate: self)
self.data = loadStaticMetadata()
self.nielsenMeter .loadMetadata(self.data)</syntaxhighlight> || // Pass Static Metadata here if applicable
|-
| rowspan="2" | Start of stream || <code>nielsenMeter.play()</code> || // Call at start of each new stream
|-
| <code>nielsenMeter.loadMetadata(contentMetadata)</code> || // MetadataObject contains the JSON metadata<br> for the content being played
|-
| Content || <code>nielsenMeter.playheadPosition(pos);</code> || // playheadPosition is position of the playhead <br>while the content is being played
|-
| End of Stream || <code>nielsenMeter.end()</code> || // Content playback is completed.
|}

=== SDK Events ===
{| class="wikitable"
|-
! Event !! Parameter !! Description
|-
| 'play' || || Call at start of each new stream
|-
| 'loadMetadata' || content/ad metadata object || Needs to be called at the beginning of each asset
|-
| 'playheadPosition' || playhead position as integer<br/>
VOD: current position in seconds <br/>
Live: current UNIX timestamp (seconds since Jan-1-1970 UTC) <br/>
Note: 'PlayheadPosition' has to be called every second
||
Pass playhead position every second during playback
|-
| 'stop' || playhead position || Call during any interruption to content or Ad playback and at the end of each Ad.
|-
| 'end' || playhead position in seconds || Call when the current video asset completes playback and pass the playhead position. <br/>
Example: At the end of the content stream, if the user switches to another piece of content, when the videoplayer is reloaded or closed.
|}
<blockquote>Note: For livestream, send the UNIX timestamp, for VOD send the time in seconds as integer. The final playhead position must be sent for the current asset being played before calling <code>'''stop'''</code>, <code>'''end'''</code> or<code> '''loadmetadata'''</code>,.</blockquote>

=== Life cycle of SDK instance ===
Life cycle of SDK instance includes four general states:
# '''Initial state''' – The SDK is not initialized and hence, not ready to process playing information. Once the SDK is moved out of this state, it needs instantiation of the new SDK instance in order to get the instance in the '''Idle state'''.
# '''Idle state''' – The SDK is initialized and is ready to process playing information. Once Initialized, the SDK instance is not processing any data, but is listening for an event to occur.
# '''Processing state''' – The SDK instance is processing playing information. The <code>'''play'''</code> and <code>'''loadMetadata''' </code> calls move the SDK instance into this state. In this state, the SDK instance will be able to process the following calls.
## <code>'''playheadPosition'''</code> – Call this API every one second when playhead position is active. If a LIVE event, use the current UNIX timestamp (seconds since Jan-1-1970 UTC).
## <code>'''stop'''</code> – Call this API when the content or Ad playback is interrupted and at the end of each Ad.
## <code>'''end'''</code> – Call when content completes. When called, the SDK instance exits from Processing state.
# '''Disabled state''' – The SDK instance is disabled and is not processing playing information.
## <code>'''appDisableApi'''</code> is set to <code>true</code>

<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 <code>'''loadMetadata''' </code> and <code>'''playheadPosition'''</code> </blockquote>

=== API Call Sequence ===
==== Use Case 1: Content has no Advertisements ====
Call [[play()]] at start of stream

Call [[loadMetadata()]] with JSON metadata for content as below.
<syntaxhighlight lang="json">{
"type": "content",
"assetid": "88675545",
"title": "Program S3, EP1",
"isfullepisode":"y",
"adloadtype":"2",
"program":"Program Name",
"length":"3600",
"airdate":"20171020 10:05:00"
}</syntaxhighlight>
Call [[playheadPosition|playheadPosition()]] every one second until a pause / stop.
Use the sample API sequence below as a reference to identify the specific events that need to be called during content playback without ads.
{| class="wikitable"
|-
! Type !! Sample code !! Description
|-
| rowspan="2" | Start of stream || <code>mAppSdk.play(); </code> || // Call at start of each new stream
|-
| <code>mAppSdk.loadMetadata(contentMetaDataObject);</code> || // contentMetadataObject contains the JSON metadata for the content being played
|-
| Content || <code>mAppSdk.setPlayheadPosition(playheadPosition);</code> || // position is position of the playhead while the content is being played
|-
| Interruption || <code>mAppSdk.stop();</code> || // call stop when content playback is interrupted
|-
| rowspan="2" | Resume Content || <code>mAppSdk.loadMetadata(contentMetaDataObject);</code> || // Call loadMetadata and pass content metadata object when content resumes
|-
|<code>mAppSdk.setPlayheadPosition(playheadPosition);</code> || // continue pasing playhead position every second starting from position where content is resumed
|-
| End of Stream || <code>mAppSdk.end();</code> || // Content playback is completed.
|}

==== Use Case 2: Content has Advertisements ====

<blockquote>Note:
*For Audiweb there is no need to tag ads in video stream ... please see 1st example about how to use the SDK without ads.</blockquote>

Call [[play()]] at start of stream

Call [[loadMetadata()]] with JSON metadata for ad as below.
<syntaxhighlight lang="json">{
"type": "preroll",
"assetid": "ad123"
}</syntaxhighlight>
<blockquote>Note: In case the individual ad details are not available, send ad pod (presence) details through the [[loadMetadata]] and playhead position through [[playheadPosition]].</blockquote>

Call [[playheadPosition|playheadPosition()]] every one second until a pause / stop / another [[loadMetadata()]] is called. Playhead should be passed for the entire duration of ad pod, if the ad pod details are passed as part of [[loadMetadata()]].

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"
|-
! Type !! Sample code !! Description
|-
| rowspan="2" | Start of stream || <code>mAppSdk.play(); </code> || // stream starts
|-
| <code>mAppSdk.loadMetadata(contentMetaDataObject);</code> || // contentMetadataObject contains the JSON metadata for the content being played
|-
| rowspan="3" | Preroll || <code>mAppSdk.loadMetadata(prerollMetadataObject);</code> || // prerollMetadataObject contains the JSON metadata for the preroll ad
|-
| <code>mAppSdk.playheadPosition(playheadPosition);</code> || // position is position of the playhead while the preroll ad is being played
|-
| <code>mAppSdk.stop();</code> || // Call stop after preroll occurs
|-
| rowspan="2" | Content || <code>mAppSdk.loadMetadata(contentMetaDataObject);</code> || // contentMetadataObject contains the JSON metadata for the content being played
|-
| <code>mAppSdk.playheadPosition(playheadPosition);</code> || // position is position of the playhead while the content is being played
|-
| rowspan="3" | Midroll || <code>mAppSdk.loadMetadata(midrollMetaDataObject);</code> || // midrollMetadataObject contains the JSON metadata for the midroll ad
|-
| <code>mAppSdk.playheadPosition(playheadPosition);</code> || // position is position of the playhead while the midroll ad is being played
|-
| <code>mAppSdk.stop();</code> || // Call stop after midroll occurs
|-
| rowspan="2" | Content Resumes || <code>mAppSdk.loadMetadata(contentMetaDataObject);</code> || // contentMetadataObject contains the JSON metadata for the content being played
|-
| <code>mAppSdk.playheadPosition(playheadPosition);</code> || // position is position of the playhead while the content is being played
|-
| End of Stream || <code>mAppSdk.end();</code> || // Call end() at the end of content
|-
| rowspan="3" | Postroll || <code>mAppSdk.loadMetadata(postrollMetaDataObject);</code> || // postrollMetadataObject contains the JSON metadata for the postroll ad
|-
| <code>mAppSdk.playheadPosition(playheadPosition);</code> || // position is position of the playhead while the postroll ad is being played
|-
| <code>mAppSdk.stop();</code> || // Call stop after postroll occurs
|}

<blockquote>Note: Each Ad playhead should 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>

== Sequence of Calls ==
=== play ===
Call <code>play</code> at the start of each new stream. If changing videos or watching a new video, call <code>play()</code> each time.
{{ExampleCode|
|Objective C = <syntaxhighlight lang="objective-c"> [nielsenAppApi play:()];</syntaxhighlight>
|Swift = <syntaxhighlight lang="swift">nielsenAppApi?.play();</syntaxhighlight>
}}

=== loadMetadata ===
{{ExampleCode|
|Objective C = <syntaxhighlight lang="objective-c">[nielsenApi loadMetadata:(contentMetadata)];</syntaxhighlight>
|Swift = <syntaxhighlight lang="swift">self.nielsenAppApi?.loadMetadata(contentMetadata)</syntaxhighlight>
}}

=== playheadPosition ===
{{ExampleCode|
|Objective C = <syntaxhighlight lang="objective-c">

-(void) setPlayHeadPosition {

//Setting play head position
CMTime timeInterval = CMTimeMakeWithSeconds(1, 1);
[player addPeriodicTimeObserverForInterval:(timeInterval) queue:dispatch_get_main_queue() usingBlock:^(CMTime time){
NSTimeInterval seconds = CMTimeGetSeconds(time);
NSInteger intSec = seconds;

//Sending data dictionary to SDK with updated playHead position.
[nielsenApi playheadPosition:(intSec)];
}];
}
</syntaxhighlight>

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

=== stop ===
{{ExampleCode|
|Objective C = <syntaxhighlight lang="objective-c">[nielsenApi stop];</syntaxhighlight>
|Swift = <syntaxhighlight lang="swift">nielsenApi.stop()</syntaxhighlight>
}}

=== end ===
When content stop is initiated and content cannot be resumed from the same position (it can only be restarted from the beginning of stream).
{{ExampleCode|
|Objective C = <syntaxhighlight lang="objective-c">[nielsenApi end];</syntaxhighlight>
|Swift = <syntaxhighlight lang="swift">nielsenApi.end()</syntaxhighlight>
}}

== Handling Foreground and Background states ==
For iOS, background/foreground detection is handled by the app lifecylce APIs which are provided by [https://developer.apple.com/library/content/documentation/iPhone/Conceptual/iPhoneOSProgrammingGuide/TheAppLifeCycle/TheAppLifeCycle.html Apple:]

Foreground/Background state measurement is a requirement of Nielsen AppSDK implementation which is especially crucial for static measurement.

== 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
* App going in the Background/Foreground
* 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 API calls – <code>'loadMetadata'</code> and <code>'playheadPosition'</code> for the new viewing session, once the playback resumes.
Please see the [https://engineeringportal.nielsen.com/docs/Digital_Measurement_Interruption_Scenarios Interruption Scenarios Page] for more details

== Privacy and Opt-Out ==
There are two primary methods for implementing user Opt-out preferences:

*[[DCR_Italy_Video_iOS_SDK#OS-level_Opt-out|OS-level Opt-out]] - managed by AppTracking or Limit Ad Tracking setting on device (preferred approach).
*[[DCR_Italy_Video_iOS_SDK#User_Choice|User Choice]] - Direct call to SDK. Can be used without the Ad Framework

=== Special Note Regarding Apps in the Kids Category ===
If you are building an app that will be listed in the Kids Category:

Ensure that you are using the [https://nielsendownloads-green.digitalengsdk.com/digital/Nielsen-iOS-App-SDK-GlobalNoId_latest.zip NoID version:] of the Nielsen SDK Framework. Also, you can use the [[Digital_Measurement_iOS_Artifactory_Guide|Artifactory method.]]
Immediately following the initialization of the Nielsen SDK ensure you call the userOptOut API with Opt out selection:
<syntaxhighlight lang="swift">NielsenAppApi?.userOptOut("nielsenappsdk://1"); // User opt-outv</syntaxhighlight>

=== OS-level Opt-out ===
''OS-level Opt-out'' method available on Nielsen iOS

The Nielsen SDK automatically leverages the iOS's '''Limit Ad Tracking''' or '''AppTracking''' setting.

*If the User's device is running < iOS 13.x, the Nielsen SDK will check the status of '''Limit Ad Tracking'''.
*iOS14 modifies the way Apple manages the collection of a User's Opt-In status through '''AppTracking'''. Starting with Version 8.x+, the Nielsen App SDK will check the iOS version during initialization. If the device is running iOS12 or iOS13, the Limit Ad Tracking setting is requested. If iOS14.x +, then AppTracking is utilized.

==== Get the latest Nielsen opt-out URL ====

*Get the current Nielsen opt-out URL via [[optOutURL|optOutURL]]
*Display a WebView element whose loadUrl is set to the value obtained from [[optOutURL|optOutURL]]

==== Webview Example ====
The below code is an example of displaying the Nielsen Privacy page to the user.
<blockquote>Note: Apple released a policy update stating that the App Store will no longer accept updates for apps using the deprecated UIWebView (no specific date has been confirmed). Since then, we’ve recommended that you adopt WKWebView instead of UIWebView and WebView.
</blockquote>
<syntaxhighlight lang="swift">
import UIKit
import WebKit
import NielsenAppApi

class OptOutVC: UIViewController, NielsenAppApiDelegate, WKNavigationDelegate {
var webView: WKWebView!
var nielsenApi: NielsenAppApi!

override func loadView() {
webView = WKWebView()
webView.navigationDelegate = self
view = webView }

override func viewDidLoad() {
super.viewDidLoad()
self.view.backgroundColor = UIColor(patternImage: UIImage(named: "new_ios_bg.png")!)
self.nielsenApi = NielsenInit.createNielsenApi(delegate: self) //create an instance

if let appApi = self.nielsenApi {
//Getting the optPut URL from SDK
if let url = URL(string: appApi.optOutURL) { //query the nielsensdk for the current privacy page
webView.load(URLRequest(url: url))
webView.allowsBackForwardNavigationGestures = true
}}}}
</syntaxhighlight>

=== User Choice ===
The User Choice method can be used without the Ad Framework, or in situations where the publisher does not wish to use the [https://developer.apple.com/documentation/apptrackingtransparency App Tracking Transparency Framework.]

==== The User Choice opt-out method works as follows: ====

*Get the Nielsen opt-out URL via [[optOutURL|optOutURL]]
*Display a WebView element whose loadUrl is set to the value obtained from [[optOutURL|optOutURL]]
*Detect if the WebView URL changes to a special URL that indicates Opt-in, or Opt-out and close the WebView
**Opt-out if the WebView URL = <code>nielsenappsdk://1</code>
**Opt-in if the WebView URL = <code>nielsenappsdk://0</code>
*Pass the detected URL to the [[userOptOut|userOptOut]] function
Example:
<syntaxhighlight lang="swift">NielsenAppApi?.userOptOut("nielsenappsdk://1"); // User opt-out </syntaxhighlight>

==== Opt-out example code ====
<blockquote>Note: Apple released a policy update stating that the App Store will no longer accept updates for apps using the deprecated UIWebView (no specific date has been confirmed). Since then, we’ve recommended that you adopt WKWebView instead of UIWebView and WebView.
</blockquote>

===== Objective-C =====

<syntaxhighlight lang="objective-c">
- (void)webView:(WKWebView *)webView decidePolicyForNavigationAction:(WKNavigationAction *)
navigationAction decisionHandler:(void (^)(WKNavigationActionPolicy))decisionHandler {

NSURLRequest *request = [navigationAction request];
NSString *url = [[request URL]absoluteString];

if([url isEqualToString:self.NIELSEN_URL_OPT_OUT] || [url isEqualToString:self.NIELSEN_URL_OPT_IN]){
[self.nielsenApi userOptOut:url];
decisionHandler(WKNavigationActionPolicyAllow);
}else{
decisionHandler(WKNavigationActionPolicyCancel);
}
}
</syntaxhighlight>

===== Swift =====
<syntaxhighlight lang="swift">
var webView: WKWebView!
var NIELSEN_URL_OPT_OUT : String = "nielsenappsdk://1"
var NIELSEN_URL_OPT_IN : String = "nielsenappsdk://0"

func webView(_ webView: WKWebView, decidePolicyFor navigationAction: WKNavigationAction,
decisionHandler: @escaping (WKNavigationActionPolicy) -> Void) {

let urlStr = navigationAction.request.url?.absoluteString

if(urlStr == NIELSEN_URL_OPT_OUT || urlStr == NIELSEN_URL_OPT_IN){
let appApi = self.nielsenApi
appApi?.userOptOut(urlStr)
decisionHandler(.allow)

}else{
decisionHandler(.cancel)
}
}
</syntaxhighlight>

=== Retrieve current Opt-Out preference ===
Whether the user is opted out via OS-level Opt-out or via User Choice Opt-out, the current Opt-Out status as detected by the SDK is available via the [[optOutStatus|optOutStatus]] property in the Nielsen SDK API

==== Required Privacy Links ====
Users must either have access to the "About Nielsen Measurement" page, or have similar text available within the native app. 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.

In addition, the following text must be included in your app store description.

Si prega di notare che questa app include il software di misurazione proprietario di Nielsen che contribuisce alla ricerca di mercato. Per ulteriori informazioni, si prega di consultare il seguente link [https://global.nielsen.com/legal/privacy-principles/digital-measurement-privacy-statement/?lang=it https://global.nielsen.com/legal/privacy-principles/digital-measurement-privacy-statement/?lang=it]

== Going Live ==
Following Nielsen testing, you will need to:

# '''Disable Debug Logging''': Disable logging by deleting <code>{nol_devDebug: 'DEBUG'}</code> from initialization call.
# '''Notify Nielsen''': Once you are ready to go live, let us know so we can enable you for reporting. We will not be able to collect or report data prior to receiving notification from you.

== Removing Simulators (Dynamic Framework Only)==

Simulator slices are needed to let clients build and debug their app on the simulators, but they should be removed before sending the app to the AppStore. Here is an example Shell script that could be added as a Run Script phase in the application.

<syntaxhighlight lang='bash'>

APP_PATH="${TARGET_BUILD_DIR}/${WRAPPER_NAME}"

# This script loops through the frameworks embedded in the application and
# removes unused architectures.
find "$APP_PATH" -name '*.framework' -type d | while read -r FRAMEWORK
do
FRAMEWORK_EXECUTABLE_NAME=$(defaults read "$FRAMEWORK/Info.plist" CFBundleExecutable)
FRAMEWORK_EXECUTABLE_PATH="$FRAMEWORK/$FRAMEWORK_EXECUTABLE_NAME"
echo "Executable is $FRAMEWORK_EXECUTABLE_PATH"

EXTRACTED_ARCHS=()

for ARCH in $ARCHS
do
echo "Extracting $ARCH from $FRAMEWORK_EXECUTABLE_NAME"
lipo -extract "$ARCH" "$FRAMEWORK_EXECUTABLE_PATH" -o "$FRAMEWORK_EXECUTABLE_PATH-$ARCH"
EXTRACTED_ARCHS+=("$FRAMEWORK_EXECUTABLE_PATH-$ARCH")
done

echo "Merging extracted architectures: ${ARCHS}"
lipo -o "$FRAMEWORK_EXECUTABLE_PATH-merged" -create "${EXTRACTED_ARCHS[@]}"
rm "${EXTRACTED_ARCHS[@]}"

echo "Replacing original executable with thinned version"
rm "$FRAMEWORK_EXECUTABLE_PATH"
mv "$FRAMEWORK_EXECUTABLE_PATH-merged" "$FRAMEWORK_EXECUTABLE_PATH"

done
</syntaxhighlight>

== Sample Applications ==
You can find some examples in the file [[Special:Downloads|Global iOS SDK Download]] from the '''SDK Downloads''' section

DCR Poland Video iOS SDK

2023-07-20T12:15:50Z

NickParrucci:

{{Breadcrumb|}} {{Breadcrumb|Digital}} {{Breadcrumb|International DCR}} {{CurrentBreadcrumb}}
[[Category:Digital]]

__TOC__

== Overview ==
The Nielsen SDK is one of multiple framework SDKs that Nielsen provides to enable measuring linear (live) and on-demand TV viewing using TVs, mobile devices, etc.
The App SDK is the framework for mobile application developers to integrate Nielsen Measurement into their media player applications. It supports a variety of Nielsen Measurement Products like Digital in TV Ratings, Digital Content Ratings ([[DCR & DTVR]]), and [[Digital Ad Ratings]] (DAR). Nielsen SDKs are also equipped to measure static content and can track key life cycle events of an application like:
*Application launch events and how long app was running

== Prerequisites ==
To start using the App SDK, the following items are required:
{| class="wikitable"
|-
! style="width: 30px;" |
! style="width: 15%;" | Item
! Description
! Source
|-
|| ☑ || '''App ID (appid)''' || Unique ID assigned to the player/site and configured by product. || Contact Nielsen
|-
|| ☑ || '''sfcode''' || Environment that the SDK must point to || Contact Nielsen
|-
|| ☑ || '''Nielsen SDK''' || Includes SDK frameworks and '''sample implementation'''; ''See [[iOS SDK Release Notes]]'' || [[Special:Downloads|Download]]
|}

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

== Implementation ==
This guide covers implementation steps for iOS using Xcode utilizing the Standard Nielsen SDK for DCR.

=== How to obtain the NielsenAppApi.Framework ===
The Nielsen AppSDK can either be downloaded directly or can be integrated directly within an application through the use of CocoaPods. We recommend using the CocoaPods-based integration whenever possible to ensure you maintain the most recent changes and enhancements to the Nielsen libraries.
* [[Digital_Measurement_iOS_Artifactory_Guide|Select to obtain CocoaPods implementation guide]]
* [[Special:Downloads|Select to Download Directly]]
* [[DCR_Video_iOS_SDK_xcframework|Using the XCFramework bundle]]

== Special Notes regarding iOS14 ==
=== Permission to Track ===

Apple recently released a new policy on consent requirements, that require the user's permission, to track them using their device's advertising identifier (IDFA). To request the user's permission, use the AppTrackingTransparency framework.

For more information, see:
* [https://developer.apple.com/documentation/apptrackingtransparency App Tracking Transparency]
* [https://developer.apple.com/design/human-interface-guidelines/ios/app-architecture/requesting-permission/ Human Interface Guidelines]
* [https://developer.apple.com/documentation/adsupport AdSupport Framework]

More detailed information on how the Nielsen SDK versions work with the AppTrackingTransparency framework is located on our [[ DCR Video iOS14 Migration|DCR Video iOS14 Migration]] page.

== Setting up your Development Environment ==
Prior to SDK Version 6.2.0.0 the IOS framework has been distributed as a static library packaged into framework bundle format. Apple recommends to use dynamic framework, it has some benefits over static libraries like less executable file size of an app, faster startup time and native support in xCode IDE. Nielsen AppSDK has been transformed into dynamic framework in this release ([[iOS_Static_Framework_Setup|static framework]] is still available).

If migrating from the static library to this new dynamic framework, once implemented, unless your specific application requires, you can remove the following Frameworks that were once required:<code> [AdSupport, JavascriptCore, SystemConfiguration, Security, AVFoundation, libc++] </code>
<br>

The '''Dynamic framework''' is created as a fat framework. It means that it contains slices required for devices (armv7, arm64) as well as slices required for simulators (i386, x86_64). Simulator slices are needed to let clients build and debug their app on the simulators, but they should be removed before sending the app to the AppStore. The example of the shell script that should be added as a Run Script phase in the application can be [[DCR_Video_iOS_SDK#Removing_Simulators_.28Dynamic_Framework_Only.29|found below]].

'''[[DCR_Video_iOS_SDK_xcframework|XCFramework]]''' is solution for the problems described above Apple recommends to use XCFrameworks. In XCFramework, we no longer build a single framework with multiple architectures. Instead, we build one small framework for each combination of architecture and target and store it in its own folder. The top-level XCFramework folder have folders like ios-arm64, ios-arm64-simulator, etc. Each of these folders is its own framework, complete with headers, modules, and binary.

=== Configuring Xcode Development Environment ===
Starting with SDK version 6.0.0.0, the Nielsen App SDK is compatible with Apple iOS versions 8.0 and above. In addition, when using the dynamic framework, all the required frameworks are linked automatically as the are needed. More details can be found here: https://stackoverflow.com/questions/24902787/dont-we-need-to-link-framework-to-xcode-project-anymore

<blockquote>'''Note''': All communications between the SDK and the Census (Collection Facility) use HTTPS.</blockquote>

=== Special Note for Static Framework ===
Starting from 8.2.0.0 release framework is build from the mixed (swift + objc) source code.
If [[iOS_Static_Framework_Setup|static (xc)framework is integrated additional settings]] should be applied to fix build or runtime issues.

=== Download Framework ===
The first step is to download and copy the [[Special:Downloads|NielsenAppApi.framework]] bundle to the app project directory. (''Not required if using CocaPods'')

=== Add Framework ===
In the General tab for app configuration add NielsenAppApi.framework in the list of Embedded Binaries. (''Not required if using CocaPods'')

=== Add Path ===
Add path to the NielsenAppApi.framework in the Framework Search Paths build setting. (''Not required if using CocaPods'')

=== Import Framework ===
Add NielsenAppApi.framework module in the source file of your app:

==== Using Swift ====
Add the following:
<syntaxhighlight lang="swift">
import NielsenAppApi
</syntaxhighlight>

==== Using Objective-C ====
<syntaxhighlight lang ="objective-c">
@import NielsenAppApi;
</syntaxhighlight>

==== xCode 12 building errors ====
Developers who uses "fat" framework in their apps started reporting the following error that they get building the app in xCode 12.3+:
<blockquote>Building for iOS Simulator, but the linked and embedded framework 'MyFramework.framework' was built for iOS + iOS Simulator.</blockquote>
The binary framework contains different code for the same architecture in multiple places, and Xcode doesn’t know how to handle it. There is workaround that people recommend to use in such cases:
* https://stackoverflow.com/questions/63267897/building-for-ios-simulator-but-the-linked-framework-framework-was-built
* https://stackoverflow.com/questions/63932158/xcode12-issus-ld-building-for-ios-simulator-but-linking-in-object-file-built

==== IPA processing failure ====
<code>Assertion failed: Expected 4 archs in otool output:</code>

The error above is due to the "fat" (simulator+device) framework which will not appear if you have not enabled Bitcode. To build your app with full Bitcode support, it is recommended that you use a [[DCR_Video_iOS_SDK_xcframework|XCFramework]] to avoid the 4 archs in otool output message.

== SDK Initialization ==
The latest version of the Nielsen App SDK allows instantiating multiple instances of the SDK object, which can be used simultaneously without any issue. The sharedInstance API that creates a singleton object was deprecated prior to version 5.1.1. [[Dual_Instances_of_SDK|(Click here for an example of multiple instances)]]

The following table contains the list of arguments that can be passed via the AppInfo JSON schema.

* The appid is provided by the Nielsen Technical Account Manager (TAM). The appid is a GUID data type and is specific to the application.
{| class="wikitable"
|-
! Parameter / Argument !! Description !! Source !! Required? !! Example
|-
| appid || Unique id for the application assigned by Nielsen. It is GUID data type.|| Nielsen-specified || Yes || PXXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX
|-
| appname || Name of the application || Client-defined || Optional; automatically detected in SDK 6.0.0.4 and above || Nielsen Sample App
|-
| sfcode || Nielsen collection facility to which the SDK should connect.
* "pl"
|| Nielsen-specified || Yes || pl
|-
| nol_devDebug || Enables Nielsen console logging. Only required for testing
|| Nielsen-specified || Optional || "DEBUG"
|}

== Debug flag for development environment ==
Player application developers / integrators can use Debug flag to check whether an App SDK API call made is successful. To activate the Debug flag,
Pass the argument <code>@"nol_devDebug":@"INFO"</code>, in the JSON string . The permitted values are:

* '''INFO''': Displays the API calls and the input data from the application (validate player name, app ID, etc.). It can be used as certification Aid.
* '''WARN''': Indicates potential integration / configuration errors or SDK issues.
* '''ERROR''': Indicates important integration errors or non-recoverable SDK issues.
* '''DEBUG''': Debug logs, used by the developers to debug more complex issues.

Once the flag is active, it logs each API call made and the data passed. The log created by this flag is minimal.
<blockquote>'''Note''': DO NOT activate the Debug flag in a production environment.</blockquote>

=== Sample SDK Initialization Code ===
{{ExampleCode|
|Swift =
Swift 4.0 Example:
<code>NielsenInit.swift</code>
<syntaxhighlight lang="swift">
import Foundation
import NielsenAppApi

class NielsenInit : NSObject {
class func createNielsenApi(delegate: NielsenAppApiDelegate) -> NielsenAppApi?{

let appInformation:[String: String] = [
"appid": "PDA7D5EE6-B1B8-4123-9277-2A788XXXXXXX",
"sfcode": "pl",
"nol_devDebug": "DEBUG"
]
return NielsenAppApi(appInfo:appInformation, delegate:delegate)
}
}
</syntaxhighlight>

Sample code using AVPlayer.
<code>ViewController.swift</code>

<syntaxhighlight lang="swift">
class ViewController: UIViewController, NielsenAppApiDelegate, AVPlayerViewControllerDelegate {

// your code//

override func viewDidLoad() {
super.viewDidLoad()

//Getting the instance of NielsenApi
self.nielsenApi = NielsenInit.createNielsenApi(delegate: self)

}
}
</syntaxhighlight>
|Objective C =
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>
<syntaxhighlight lang="objective-c">
#import "NielsenInit.h"
#import <NielsenAppApi/NielsenAppApi.h>

@implementation NielsenInit

+ (NielsenAppApi *)createNielsenAppApiWithDelegate:(id<NielsenAppApiDelegate>)delegate
{
NSDictionary *appInformation = @{ @"appid": @"PDA7D5EE6-B1B8-4123-9277-2A788XXXXXXX",
@"appversion": @"1.0",
@"sfcode": @"pl",
@"nol_devDebug": @"DEBUG", };

return [[NielsenAppApi alloc] initWithAppInfo:appInformation delegate:delegate];
}

@end
</syntaxhighlight>

The following would be the <code>NielsenInit.h</code> file:
<syntaxhighlight lang="objective-c">
#import <Foundation/Foundation.h>

@class NielsenAppApi;
@protocol NielsenAppApiDelegate;

@interface NielsenInit : NSObject

+ (NielsenAppApi *)createNielsenAppApiWithDelegate:(id<NielsenAppApiDelegate>)delegate;

@end
</syntaxhighlight>
Sample Code:
<syntaxhighlight lang="objective-c">
@implementation ViewController

- (void)viewDidLoad {
[super viewDidLoad];

//Getting the instance of Nielsen SDK
nielsenApi = [NielsenInit createNielsenAppApiWithDelegate:nil];
</syntaxhighlight>
}}

== APP SDK Error & Event Codes ==
To view the Error and Event codes for iOS and Android, please review the [[APP SDK Event Codes|App SDK Event Code]] Reference page.

== Configure Payload ==
=== Handling JSON Metadata ===
All the SDK methods handles only two types of objects: NSString, NSDictionary. The parameters passed must be either a JSON formatted string or a NSDictionary object. The JSON passed in the SDK must be well-formed.
* NSDictionary object
** If an object of unexpected type is passed to the method, the error message will be logged.
** If string has invalid JSON format, the error message will be logged.
* JSON value must be string value.
** This includes boolean and numeric values. For example, a value of true should be represented with "true", number value 123 should be "123".
** All the Variable Names like appid, appname, sfcode, dataSrc, title, type etc. are case-sensitive. Use the correct variable name as specified in the documentation.
* JSON string can be prepared using either raw NSString or serialized NSDictionary.
{{ExampleCode|
|Swift =
<syntaxhighlight lang="swift">
let channelInfo = [
"channelName": "My Channel Name 1",
];

let contentMetadata = [
"type": "content",
"assetid": "C77664",
"title": "Program S2, E3",
"isfullepisode": "Yes",
"program": "Program Name",
"length": "3600",
"airdate": "20171020 10:05:00",
"adloadtype": "2",
"segB": "CustomSegmentValueB", //optional
"segC": "CustomSegmentValueC", //optional
];
</syntaxhighlight>
|Objective C = <syntaxhighlight lang="objective-c">
NSDictionary * channelInfo = @ {
@ "channelName": @ "My Channel Name 1",
}

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

=== ChannelName metadata ===
channelName should remain constant throughout the completion of an episode or live stream.
{| class="wikitable"
|-
! Key !! Description !! Values !! Required
|-
| channelName || ChannelInfo refers to the Channel name. This can be a free-form value
value such as a friendly name for the content being played. the SDK<br/>
will pass the application name automatically.
|| custom || No
|-
|}

==== Content Metadata ====
Content metadata should remain constant throughout the entirety of an episode / clip including when ads play.
{| class="wikitable"
|-
! Key !! Description !! Values !! Required
|-
| type || type of asset || "content" || ✓
|-
| assetid || unique ID assigned to asset (max 64 characters; only characters 0-9, a-z, A-Z underscore and minus are allowed - no special characters or vowel mutations) || custom (no [[Special Characters]])|| ✓
|-
| program || (string) name of program (max 254 characters) || custom || ✓
|-
| title || (string) episode title (max 254 characters) || custom - no backslash allowed in string (because of 3rd party data processing) || ✓
|-
| length || (int) length of content in seconds || 86400 seconds for live stream. For Event-Livestreams planned length. For VoD video length|| ✓
|-
| airdate || The airdate in the linear TV. Original (local) air date and time (hh:mm:ss as 24h time stamp); if not known set it to eg. "19700101 00:00:00" || YYYY-MM-DDTHH:MI:SS<br>
YYYY-MM-DDHH:MI:SS<br>
YYYY-MM-DDTHH:MI:SS+xx:xx<br>
YYYY-MM-DDTHH:MI:SS-xx:xx<br>
YYYYMMDDHH:MI:SS<br>
YYYYMMDD HH:MI:SS<br>
MM-DD-YYYY<br>
MM/DD/YYYY<br>
(pass beginning of epoch if unknown)
|| ✓
|-
| isfullepisode || full episode flag || "y"- full episode, "n"- non full episode || ✓
|-
| adloadtype || type of ad load:
<code>"1"</code> Linear – matches TV ad load

<code>"2"</code> Dynamic – Dynamic Ad Insertion (DAI)
|| <code>"2"</code> - DCR measures content with dynamic ads || ✓
|-
| progen || program genre || custom ||
|-
| segB || custom segment || custom ||
|-
| segC || custom segment || custom ||
|-
| crossId1 || standard episode ID || custom ||
|-
| clientid ||
parent ID – value is automatically populated through provided AppID.<br/>
In order to override the brand configured to the AppID, pass parent <br/>
value here and the sub-brand ID associated to that brand in the subbrand <br/>
key (e.g. multiple brands in App)
||
provided by Nielsen
||
|-
| subbrand || vcid/sub-brand ID – value is automatically populated through provided<br/>
AppID. In order to override the sub-brand configured to the AppID, value can <br/>
be passed here (e.g. multiple sub-brands in App)
||
provided by Nielsen
||
|}

=== Ad Metadata ===
The ad metadata (if applicable) should be passed for each individual ad, if ads are available during or before the stream begins.
{| class="wikitable"
|-
! Keys !! Description !! Values !! Required
|-
| type || type of ad || <code>'preroll'</code>, <code>'midroll'</code>, <code>'postroll'</code>|| ✓
|-
| assetid || unique ID assigned to ad || custom <br>(no [[Special Characters]]) || ✓
|}

=== Example Ad Object ===
{{ExampleCode|
|Swift =
<syntaxhighlight lang="swift">
let adMetadata = [
"type": "preroll",
"assetid": "123456"
];
</syntaxhighlight>
|Objective C = <syntaxhighlight lang="objective-c">
NSDictionary * adMetadata = @ {
@ "type": @ "preroll",
@ "assetid": @ "AD-ID123"
}
</syntaxhighlight>
}}

== Nielsen API Documentation ==
=== play ===
Use <code>play</code> to pass the channel descriptor information through channelName parameter when the user taps the '''Play''' button on the player. Pass in channelName metadata as described above.
{{ExampleCode|
|Objective C = <syntaxhighlight lang="objective-c"> [nielsenApi play:([NSDictionary *channel loadChannelInfo)];</syntaxhighlight>
|Swift = <syntaxhighlight lang="swift">nielsenApi?.play(channelInfo);</syntaxhighlight>
}}

=== loadMetadata ===
Call to inform SDK about asset being played. Pass in metadata as described here [[#Configure Payload]], [[#Content Metadata]]
{{ExampleCode|
|Objective C = <syntaxhighlight lang="objective-c">[nielsenApi loadMetadata:(contentMetadata)];</syntaxhighlight>
|Swift = <syntaxhighlight lang="swift">nielsenApi?.loadMetadata(contentMetadata)</syntaxhighlight>
}}

=== playheadPosition ===
Call to inform Nielsen SDK about position in video asset (for VOD pass second within video, for livestreams UTC timestamp in seconds).
{{ExampleCode|
|Objective C = <syntaxhighlight lang="objective-c">[nielsenApi playheadPosition:secondsAsInt];</syntaxhighlight>
|Swift = <syntaxhighlight lang="swift">nielsenApi?.playheadPosition(secondsAsInt)</syntaxhighlight>
}}

=== stop ===
Call to indicate interruption during playback, e.g. pause. (more on interruption scenarios here: [[#Interruptions during playback]] )
{{ExampleCode|
|Objective C = <syntaxhighlight lang="objective-c">[nielsenApi stop];</syntaxhighlight>
|Swift = <syntaxhighlight lang="swift">nielsenApi?.stop()</syntaxhighlight>
}}

=== end ===
Call when content finished playback and content cannot be resumed from the same position (it can only be restarted from the beginning of stream).
{{ExampleCode|
|Objective C = <syntaxhighlight lang="objective-c">[nielsenApi end];</syntaxhighlight>
|Swift = <syntaxhighlight lang="swift">nielsenApi?.end()</syntaxhighlight>
}}

== Call Nielsen APIs ==
[[File:appsdkTimeline-DCR.png|icon|link=]]
=== Sample API Sequence ===
A Sample API sequence could follow this flow:
{| class="wikitable"
|-
! Type !! Sample code !! Description
|-
|On App Start||<syntaxhighlight lang=Swift>
nielsenApi = NielsenInit.createNielsenApi(delegate: self);
data = loadStaticMetadata();
nielsenApi.loadMetadata(self.data);</syntaxhighlight> || // Pass Static Metadata here if applicable
|-
| rowspan="2" | Start of stream || <code>nielsenApi.play(channelName)</code> || // channelName now automatically generated by Nielsen SDK
|-
| <code>nielsenApi.loadMetadata(contentMetadata)</code> || // MetadataObject contains the JSON metadata<br> for the content being played
|-
| Content || <code>nielsenApi.playheadPosition(pos);</code> || // playheadPosition is position of the playhead <br>while the content is being played
|-
| End of Stream || <code>nielsenApi.end()</code> || // Content playback is completed.
|}

=== Life cycle of SDK instance ===
Life cycle of SDK instance includes four general states:
# '''Initial state''' – The SDK is not initialized and hence, not ready to process playing information. Once the SDK is moved out of this state, it needs instantiation of the new SDK instance in order to get the instance in the '''Idle state'''.
# '''Idle state''' – The SDK is initialized and is ready to process playing information. Once Initialized, the SDK instance is not processing any data, but is listening for an event to occur.
# '''Processing state''' – The SDK instance is processing playing information. The <code>'''play'''</code> and <code>'''loadMetadata''' </code> calls move the SDK instance into this state. In this state, the SDK instance will be able to process the following calls.
## <code>'''playheadPosition'''</code> – Call this API every one second when playhead position is active. If a LIVE event, use the current UNIX timestamp (seconds since Jan-1-1970 UTC).
## <code>'''stop'''</code> – Call this API when the playback is paused, switches between content and ad (within the same content playback) or encounters interruptions.
## <code>'''end'''</code> – SDK instance exits from Processing state when this API is called.
# '''Disabled state''' – The SDK instance is disabled and is not processing playing information.
## <code>'''appDisableApi'''</code> is set to <code>true</code>

<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 <code>'''play'''</code>, <code>'''loadMetadata''' </code> and <code>'''playheadPosition'''</code> </blockquote>

== API Call Sequence ==
=== Use Case 1: Content has no Advertisements ===
Call [[play()]] with channelName JSON as below.
<syntaxhighlight lang="json">{
"channelName": "TheMovieTitle"
}</syntaxhighlight>
Call [[loadMetadata()]] with JSON metadata for content as below.
<syntaxhighlight lang="json">{
"type": "content",
"assetid": "vid345-67483",
"program": "ProgramName",
"title": "Program S3, EP1",
"length": "3600",
...
}</syntaxhighlight>
Call [[playheadPosition|playheadPosition()]] every one second until a pause / stop.
Use the sample API sequence below as a reference to identify the specific events that need to be called during content playback without ads.
{| class="wikitable"
|-
! Type !! Sample code !! Description
|-
| rowspan="2" | Start of stream || <code>nielsenApi.play(channelName); </code> || // channelName now automatically generated by Nielsen SDK
|-
| <code>nielsenApi.loadMetadata(contentMetaDataObject);</code> || // contentMetadataObject contains the JSON metadata for the content being played
|-
| Content || <code>nielsenApi.playheadPosition(playheadPosition);</code> || // position is position of the playhead while the content is being played
|-
| End of Stream || <code>nielsenApi.end();</code> || // Content playback is completed.
|}

=== Use Case 2: Content has Advertisements ===
Call [[play()]] with channelName JSON as below.
<syntaxhighlight lang="json">{
"channelName": "TheMovieTitle"
}</syntaxhighlight>
Call [[loadMetadata()]] with JSON metadata for ad as below.
<syntaxhighlight lang="json">{
"type": "preroll",
"assetid": "ad=123"
}</syntaxhighlight>
<blockquote>Note: In case the individual ad details are not available, send ad pod (presence) details through the [[loadMetadata]] and playhead position through [[playheadPosition]].</blockquote>

Call [[playheadPosition|playheadPosition()]] every one second until a pause / stop / another [[loadMetadata()]] is called. Playhead should be passed for the entire duration of ad pod, if the ad pod details are passed as part of [[loadMetadata()]].

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"
|-
! Type !! Sample code !! Description
|-
| rowspan="2" | Start of stream || <code>nielsenApi.play(channelName); </code> || // channelName now automatically generated by Nielsen SDK
|-
| <code>nielsenApi.loadMetadata(contentMetaDataObject);</code> || // contentMetadataObject contains the JSON metadata for the content being played
|-
| rowspan="3" | Preroll || <code>nielsenApi.loadMetadata(prerollMetadataObject);</code> || // prerollMetadataObject contains the JSON metadata for the preroll ad
|-
| <code>nielsenApi.playheadPosition(playheadPosition);</code> || // position is position of the playhead while the preroll ad is being played
|-
| <code>nielsenApi.stop();</code> || // Call stop after preroll occurs
|-
| rowspan="3" | Content || <code>nielsenApi.loadMetadata(contentMetaDataObject);</code> || // contentMetadataObject contains the JSON metadata for the content being played
|-
| <code>nielsenApi.playheadPosition(playheadPosition);</code> || // position is position of the playhead while the content is being played
|-
| <code>nielsenApi.stop();</code> || // Call stop after the content is paused (ad starts)
|-
| rowspan="6" | Midroll || <code>nielsenApi.loadMetadata(midrollMetaDataObject);</code> || // midrollMetadataObject contains the JSON metadata for the midroll ad
|-
| <code>nielsenApi.playheadPosition(playheadPosition);</code> || // position is position of the playhead while the midroll ad is being played
|-
| <code>nielsenApi.stop();</code> || // App moves to background(midroll pauses)
|-
| <code>nielsenApi.loadMetadata(midrollMetaDataObject);</code> || // App moves to foreground (midroll resumes)
|-
| <code>nielsenApi.playheadPosition(playheadPosition);</code> || // playheadPosition is position of the playhead while the midroll ad is being played
|-
| <code>nielsenApi.stop();</code> || // Call stop after midroll occurs
|-
| rowspan="3" | Content (End of stream) || <code>nielsenApi.loadMetadata(contentMetaDataObject);</code> || // contentMetadataObject contains the JSON metadata for the content being played
|-
| <code>nielsenApi.playheadPosition(playheadPosition);</code> || // position is position of the playhead while the content is being played
|-
| <code>nielsenApi.stop();</code> || // Always call stop irrespective of postroll is followed or not
|-
| End of Stream || <code>nielsenApi.end();</code> || // Call end() at the end of content
|-
| rowspan="3" | Postroll || <code>nielsenApi.loadMetadata(postrollMetaDataObject);</code> || // postrollMetadataObject contains the JSON metadata for the postroll ad
|-
| <code>nielsenApi.playheadPosition(playheadPosition);</code> || // position is position of the playhead while the postroll ad is being played
|-
| <code>nielsenApi.stop();</code> || // Call stop after postroll occurs
|}

<blockquote>Note: Each Ad playhead should 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>

== Handling Foreground and Background states ==
For iOS, background/foreground detection is handled by the app lifecylce APIs which are provided by [https://developer.apple.com/library/content/documentation/iPhone/Conceptual/iPhoneOSProgrammingGuide/TheAppLifeCycle/TheAppLifeCycle.html Apple:]

Foreground/Background state measurement is a requirement of Nielsen AppSDK implementation which is especially crucial for static measurement.

== 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 and withhold sending playhead position.
* Start sending API calls – <code>'loadMetadata'</code> and <code>'playheadPosition'</code> for the new viewing session, once the playback resumes.
Please see the [https://engineeringportal.nielsen.com/docs/Digital_Measurement_Interruption_Scenarios Interruption Scenarios Page] for more details

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

== Privacy and Opt-Out ==
There are three primary methods for implementing user Opt-out preferences:
# '''[[#OS-level_Opt-out|OS-level Opt-out]]''' - managed by ''Limit Ad Tracking'' setting on device ('''preferred approach''').
# '''[[#Legacy_Opt-out|Legacy Opt-out]]''' - Direct call to SDK; used only for older versions of Nielsen iOS SDK (< 5.1.1.18)
# '''[[#App_Level_Opt_Out|App Level Opt-Out]]''' - Where [https://developer.apple.com/documentation/adsupport Ad Framework] cannot be leveraged

=== OS-level Opt-out ===
''OS-level Opt-out'' method available on Nielsen iOS '''SDK Versions 5.1.1.18 and above'''.

The Nielsen SDK automatically leverages the iOS's ''Limit Ad Tracking'' setting. The user is opted out of demographic measurement if the OS-level ''"Limit Ad Tracking"'' setting is ''enabled''. As a publisher, you cannot override this setting.

=== Legacy Opt-out ===
The ''Legacy opt-out'' method is only necessary for Nielsen iOS '''SDK versions less than 5.1.1.18'''.

Nielsen iOS SDK 5.1.1.17 and above will check for ''OS-level opt-out'' first, if available. The user will be opted out if indicated at the OS-level '''OR''' the App-level.

==== The legacy opt-out method works as follows: ====
* Get the legacy Nielsen opt-out URL via [[optOutURL]]
* Display a WebView element whose loadUrl is set to the value obtained from [[optOutURL]]
* Detect if the WebView URL changes to a special URL that indicates Opt-in, or Opt-out and close the WebView
** Opt-out if the WebView URL = <code>nielsenappsdk://1</code>
** Opt-in if the WebView URL = <code>nielsenappsdk://0</code>
* Pass the detected URL to the [[userOptOut]] function
** Example: <syntaxhighlight lang=swift>NielsenAppApi?.userOptOut("nielsenappsdk://1"); // User opt-out</syntaxhighlight>

==== Legacy Opt-out example code ====
{{ExampleCode|
|Objective C = <syntaxhighlight lang="objective-c">
- (void)webView:(WKWebView *)webView decidePolicyForNavigationAction:(WKNavigationAction *)navigationAction decisionHandler:(void (^)(WKNavigationActionPolicy))decisionHandler {

NSURLRequest *request = [navigationAction request];
NSString *url = [[request URL]absoluteString];

if([url isEqualToString:self.NIELSEN_URL_OPT_OUT] || [url isEqualToString:self.NIELSEN_URL_OPT_IN]){
[self.nielsenApi userOptOut:url];
decisionHandler(WKNavigationActionPolicyAllow);
}else{
decisionHandler(WKNavigationActionPolicyCancel);
}
}
</syntaxhighlight>
|Swift = <syntaxhighlight lang="swift">

var webView: WKWebView!
var NIELSEN_URL_OPT_OUT : String = "nielsenappsdk://1"
var NIELSEN_URL_OPT_IN : String = "nielsenappsdk://0"

func webView(_ webView: WKWebView, decidePolicyFor navigationAction: WKNavigationAction, decisionHandler: @escaping (WKNavigationActionPolicy) -> Void) {

let urlStr = navigationAction.request.url?.absoluteString

if(urlStr == NIELSEN_URL_OPT_OUT || urlStr == NIELSEN_URL_OPT_IN){
let appApi = self.nielsenApi
appApi?.userOptOut(urlStr)
decisionHandler(.allow)

}else{
decisionHandler(.cancel)
}
}
</syntaxhighlight>
}}

=== Retrieve current Opt-Out preference ===
Whether the user is opted out via OS-level Opt-out or via App-level Opt-out, the current Opt-Out status as detected by the SDK is available via the [[optOutStatus]] property in the Nielsen SDK API

=== First Party ID (FPID)===
- The broadcaster must enableFPID in the initialization settings which is set to <code>true</code> or <code>false</code> depending on user consent. This is to be set by the broadcaster when initializing our SDK.<br>

- The <code>enableFpid</code> flag is needed to enable/disable FPID usage for the AppID. The default value for this flag is true. If this flag is changed from true to false, then the AppSDK should wipe out the stored FPID and use a blank value for the FPID parameter in all the pings.<br>

- Generated FPID value is stored in the persistent memory until the application is uninstalled from a device or until FPID is wiped out or until it is expired.<br>

- The default value for this parameter is 180 days. Once this timeout is reached, the FPID should be regenerated.<br>

- Example: disable FPID during init call
<syntaxhighlight lang="swift">
class NielsenInit : NSObject {
class func createNielsenApi(delegate: NielsenAppApiDelegate) -> NielsenAppApi?{

let appInformation:[String: String] = [
"appid": "PDA7D5EE6-B1B8-4123-9277-2A788XXXXXXX",
"sfcode": "pl", // sfcode for Poland
"enableFpid": "false" //false = FPID is disabled, true= FPID is enabled
"nol_devDebug": "DEBUG" // only for debug builds and see the Nielsen logs
]
return NielsenAppApi(appInfo:appInformation, delegate:delegate)
}
}
</syntaxhighlight>

=== Required Privacy Links ===
Users must either have access to the "About Nielsen Measurement" page, or have similar text available within the native app. 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.

In addition, the following text must be included in your app store description.
<blockquote>
'''"Please note: This app features Nielsen’s proprietary measurement software which contributes to market research, like Nielsen’s TV Ratings. Please see https://priv-policy.imrworldwide.com/priv/mobile/pl/pl/optout.html for more information"'''</blockquote>

==== Webview Example ====
The below code is an example of displaying the Nielsen Privacy page to the user.
{{ExampleCode|
|Objective C = <syntaxhighlight lang="objective-c">
- (void)viewDidLoad {

[super viewDidLoad];

//Setting background image
UIImage *backgroundImage = [UIImage imageNamed:@"new_ios_bg.png"];
UIImageView *backgroundImageView=[[UIImageView alloc]initWithFrame:self.view.frame];
backgroundImageView.image=backgroundImage;
[self.view insertSubview:backgroundImageView atIndex:0];

self.nielsenApi = [NielsenInit createNielsenAppApiWithDelegate:nil];

//Initialising the webview
WKWebViewConfiguration *theConfiguration = [[WKWebViewConfiguration alloc] init];
_wkwebView = [[WKWebView alloc] initWithFrame:self.view.frame configuration:theConfiguration];
_wkwebView.navigationDelegate = self;

//Getting the optPut URL from SDK
NSURL *nsurl=[NSURL URLWithString:[self.nielsenApi optOutURL]];

//Setting url request in webview
NSURLRequest *nsrequest=[NSURLRequest requestWithURL:nsurl];

//Setting url request in webview
[_wkwebView loadRequest:nsrequest];

//Adding webview to the controller view
[self.view addSubview:_wkwebView];
}

</syntaxhighlight>
|Swift = <syntaxhighlight lang="swift">
import UIKit
import WebKit
import NielsenAppApi

class OptOutVC: UIViewController, NielsenAppApiDelegate, WKNavigationDelegate {

var webView: WKWebView!
var nielsenApi: NielsenAppApi!

override func loadView() {
webView = WKWebView()
webView.navigationDelegate = self
view = webView
}

override func viewDidLoad() {
super.viewDidLoad()
self.view.backgroundColor = UIColor(patternImage: UIImage(named: "new_ios_bg.png")!)
self.nielsenApi = NielsenInit.createNielsenApi(delegate: self)

if let appApi = self.nielsenApi {
//Getting the optPut URL from SDK
if let url = URL(string: appApi.optOutURL) {
webView.load(URLRequest(url: url))
webView.allowsBackForwardNavigationGestures = true
}
}
}

}
</syntaxhighlight>
}}
<br>

=== App Level Opt Out ===
This is only used if the Ad Framework is not available. 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 <code>userOptOut</code>.

==== Capture and forward user selection ====
{{ExampleCode|
|Objective C = <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 <code>userOptOut</code> 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. The App SDK manages the user's choice (Opt-Out / Opt-In), the app does not need to manage this status.</blockquote>
|Swift = <syntaxhighlight lang="swift">
func webView(webView: UIWebView, shouldStartLoadWithRequest request: NSURLRequest, navigationType: UIWebViewNavigationType) -> Bool {

let command = request.url?.absoluteString
if command == "kNielsenWebClose"{

self.perform(#selector(closeOptOutView), with: nil, afterDelay: 0)

return false
}
return NielsenAppApi.optOutURL
}

</syntaxhighlight>
*The app gets the user selection string via webviews shouldStartLoadWithRequest and invokes <code>userOptOut</code> 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. The App SDK manages the user's choice (Opt-Out / Opt-In), the app does not need to manage this status.</blockquote>
}}

== AirPlay ==
To implement OTT measurement, report OTT changes to the SDK using public API interface: [[updateOTT]]

In order to detect AirPlay and mirroring changes we use AVAudioSessionPortDescription properties that are different on different iOS versions. We found that on iOS versions 8 - 10 <code>AVAudioSessionPortDescription</code> has the following values:<br>
<code>
AirPlay: type = AirPlay; name = Apple TV 4K; UID = DC:56:E7:53:72:85-airplay <br>
Mirroring: type = AirPlay; name = Apple TV 4K; UID = DC:56:E7:53:72:85-screen
</code><br>

For iOS 11+ some parameters like name and UID have different values:<br>
<code>
AirPlay: type = AirPlay; name = AirPlay; UID = 0eb63aae-5915-45f1-b0f7-0102a0e50d53 <br>
Mirroring: type = AirPlay; name = Apple TV 4K; UID = 4335E8A9-1C0A-4251-9000-28CA5FA2F3CF-192731714653291-screen<br>
</code>

The following code snipped is suggested for AirPlay / mirroring detection on iOS devices.

{{ExampleCode|
|Objective C =
<syntaxhighlight lang="objective-c">
– (void)updateOTT:(id)ottInfo;
</syntaxhighlight>
=== Subscribe to AVAudioSessionRouteChangeNotification ===
<syntaxhighlight lang="objective-c">
[[NSNotificationCenter defaultCenter] addObserver:self selector:@selector(handleRouteChanged:) name:AVAudioSessionRouteChangeNotification object:nil];
</syntaxhighlight>

=== Handle AVAudioSessionRouteChangeNotification and prepare OTT dictionary:===
<syntaxhighlight lang="objective-c">
- (void)handleRouteChanged:(NSNotification *)notification
{
NSMutableDictionary *ottDict = [NSMutableDictionary dictionaryWithDictionary: @{@"ottStatus": @"0"}];

AVAudioSession *audioSession = [AVAudioSession sharedInstance];
AVAudioSessionRouteDescription *currentRoute = audioSession.currentRoute;
for (AVAudioSessionPortDescription *outputPort in currentRoute.outputs) {
if ([outputPort.portType isEqualToString:AVAudioSessionPortAirPlay]) {
ottDict[@"ottStatus"] = @"1";
ottDict[@"ottDeviceModel"] = outputPort.portName;
ottDict[@"ottDeviceID"] = outputPort.UID;

if ([outputPort.portName isEqualToString:@"AirPlay"]) {
ottDict[@"ottDevice"] = @"airplay";
ottDict[@"ottType"] = @"airplay";
}
else {
if ([outputPort.portName containsString:@"Apple TV"]) {
ottDict[@"ottDevice"] = @"appleTV";
}
else {
ottDict[@"ottDevice"] = @"other";
}

if ([outputPort.UID hasSuffix:@"airplay"]) {
ottDict[@"ottType"] = @"airplay";
}
else if ([outputPort.UID hasSuffix:@"screen"]) {
ottDict[@"ottType"] = @"mirroring";
}
else {
ottDict[@"ottType"] = @"other";
}
}
}
}

// report OTT status update to Nielsen SDK
[self reportOTTWithDict:ottDict];
}
</syntaxhighlight>

=== Report OTT update to the Nielsen SDK ===
<syntaxhighlight lang="objective-c">
- (void)reportOTTWithDict:(NSDictionary *)ottDict
{
[self.nielsenSDK updateOTT:ottDict];
}
</syntaxhighlight>

|Swift =
<syntaxhighlight lang="swift">
nielsenSdk.updateOTT(currentStatus)
</syntaxhighlight>

=== Subscribe to AVAudioSessionRouteChangeNotification ===
<syntaxhighlight lang="swift">
NotificationCenter.default.addObserver(self, selector: #selector(handleRouteChanged(_:)), name: NSNotification.Name.AVAudioSessionRouteChange, object: nil)
</syntaxhighlight>

=== Handle AVAudioSessionRouteChangeNotification and prepare OTT dictionary:===

<syntaxhighlight lang ="Swift">
func handleRouteChanged(_ notification: Notification) {
var currentStatus: [String: String] = ["ottStatus": "0"]

let session = AVAudioSession.sharedInstance()
let currentRoute = session.currentRoute
for outputPort in currentRoute.outputs {
if outputPort.portType == AVAudioSessionPortAirPlay {
currentStatus["ottStatus"] = "1"
currentStatus["ottDeviceModel"] = outputPort.portName
currentStatus["ottDeviceID"] = outputPort.uid

if outputPort.portName == "AirPlay" {
currentStatus["ottDevice"] = "airplay"
currentStatus["ottType"] = "airplay"
}
else {
if outputPort.portName.contains("Apple TV") {
currentStatus["ottDevice"] = "appleTV"
}
else {
currentStatus["ottDevice"] = "other"
}

if outputPort.uid.hasSuffix("airplay") {
currentStatus["ottType"] = "airplay"
}
else if outputPort.uid.hasSuffix("screen") {
currentStatus["ottType"] = "mirroring"
}
else {
currentStatus["ottType"] = "other"
}
}
}
}

// report OTT status update to Nielsen SDK
self.reportOTTUpdate(currentStatus)
}
</syntaxhighlight>

=== Report OTT update to the Nielsen SDK===
<syntaxhighlight lang ="Swift">
func reportOTTUpdate(_ ottDict: [String: String]) {
if let nielsenSdk = self.nielsenAppApi {
nielsenSdk.updateOTT(currentStatus)
}
}
</syntaxhighlight>
}}

== Going Live ==
Following Nielsen testing, users need to make one update to the initialization call to ensure that the site is being measured properly.

# '''Debug Logging''': Disable logging by deleting <code>{nol_sdkDebug: 'DEBUG'}</code> from initialization call.
<br/>
'''Note''': before going live you have to inform Nielsen team - this is necessary, because Nielsen team has to adjust internal configuration parameter to enable data collection. Without that notification no data will be collected and no data will be reported.

== Removing Simulators (Dynamic Framework Only)==

Simulator slices are needed to let clients build and debug their app on the simulators, but they should be removed before sending the app to the AppStore. Here is an example Shell script that could be added as a Run Script phase in the application.

<syntaxhighlight lang='bash'>

APP_PATH="${TARGET_BUILD_DIR}/${WRAPPER_NAME}"

# This script loops through the frameworks embedded in the application and
# removes unused architectures.
find "$APP_PATH" -name '*.framework' -type d | while read -r FRAMEWORK
do
FRAMEWORK_EXECUTABLE_NAME=$(defaults read "$FRAMEWORK/Info.plist" CFBundleExecutable)
FRAMEWORK_EXECUTABLE_PATH="$FRAMEWORK/$FRAMEWORK_EXECUTABLE_NAME"
echo "Executable is $FRAMEWORK_EXECUTABLE_PATH"

EXTRACTED_ARCHS=()

for ARCH in $ARCHS
do
echo "Extracting $ARCH from $FRAMEWORK_EXECUTABLE_NAME"
lipo -extract "$ARCH" "$FRAMEWORK_EXECUTABLE_PATH" -o "$FRAMEWORK_EXECUTABLE_PATH-$ARCH"
EXTRACTED_ARCHS+=("$FRAMEWORK_EXECUTABLE_PATH-$ARCH")
done

echo "Merging extracted architectures: ${ARCHS}"
lipo -o "$FRAMEWORK_EXECUTABLE_PATH-merged" -create "${EXTRACTED_ARCHS[@]}"
rm "${EXTRACTED_ARCHS[@]}"

echo "Replacing original executable with thinned version"
rm "$FRAMEWORK_EXECUTABLE_PATH"
mv "$FRAMEWORK_EXECUTABLE_PATH-merged" "$FRAMEWORK_EXECUTABLE_PATH"

done
</syntaxhighlight>

== Sample Applications ==
The below sample applications have been designed to show the Simplified API's functionality and are broken into two distinct categories:
* '''Basic''' - To show the functionality of the Nielsen Simplified API using a standard no-frills player.
** [[Swift Basic Sample|Swift 4.0 Sample]]
** [[Objective-c Basic example|Objective-C Sample]]
** [[Android Basic example|Android Studio Example]]

* '''Advanced''' - Nielsen Simplified API integrated into a custom video player.
** [https://engineeringportal.nielsen.com/docs/Special:Downloads Swift 4.0 Sample]
** [https://engineeringportal.nielsen.com/docs/Special:Downloads Objective-C Sample]
** [https://engineeringportal.nielsen.com/docs/Special:Downloads Java/Android Studio Sample]

iOS Static Framework Setup

2023-07-20T12:15:20Z

NickParrucci:

{{Breadcrumb|}} {{Breadcrumb|Digital}} {{Breadcrumb|DCR & DTVR}} {{Breadcrumb|DCR Video iOS SDK}} {{CurrentBreadcrumb}}
[[Category:Digital]]
__NOTOC__
= Configuring Xcode Development Environment for Static Framework =
== Importing Frameworks ==
The first step is to ensure that the following frameworks and libraries are imported into the Frameworks folder of the Xcode project before creating an instance of the Nielsen App SDK object.
* UIKit.framework
* Foundation.framework
* AdSupport.framework
* JavascriptCore.framework
* WebKit.framework
* SystemConfiguration.framework
* Security.framework
** Nielsen Analytics framework makes use of a number of functions in this library.
* AVFoundation.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
=== Mixed Nielsen SDK static (xc)frameworks integration errors ===
Starting from 8.2.0.0 release framework is build from the mixed (swift + objc) source code.<br>
If static (xc)framework is integrated additional settings should be applied to fix build or runtime issues:

==== Empty Swift file ====
If static mixed (xc)framework is integrated into pure ObjC application, link issue occurs during building:

<p style="color:red;">
Undefined symbol: _OBJC_CLASS_$__TtCs12_SwiftObject<br>
Undefined symbol: nominal type descriptor for Dispatch.DispatchSpecificKey<br>
Undefined symbol: Dispatch.DispatchSpecificKey.init() -> Dispatch.DispatchSpecificKey<A><br>
Undefined symbol: static (extension in Dispatch):__C.OS_dispatch_queue.getSpecific<A>(key: Dispatch.DispatchSpecificKey<A>) -> A?<br>
Undefined symbol: (extension in Dispatch):__C.OS_dispatch_queue.label.getter : Swift.String<br>
Undefined symbol: _swift_weakDestroy<br>
Undefined symbol: _swift_deallocObject<br>
Undefined symbol: type metadata accessor for Network.NWPathMonitor<br>
Undefined symbol: Network.NWPathMonitor.init() -> Network.NWPathMonitor<br>
Undefined symbol: _swift_weakInit<br>
...<br>
</p>

To fix it an empty file with .swift extension should be added into the Application project target(s).

[[File:Screen Shot 2022-02-22 at 12.34.12.png|frame|center]]

==== -ObjC linker flag ====
Static library doesn't automatically load every source code entity. This leads to the runtime exception kind of:
<p style="color:red;">
unrecognized selector sent to class 0x1087b7a50, AppApiExceptionName=NSInvalidArgumentException
</p>

This is a known swift issue:
https://bugs.swift.org/browse/SR-6004

To fix:<br>
Build Settings → Other Linker flags -> -ObjC

[[File:Screen Shot 2022-02-22 at 12.45.15.png|frame|center]]

=== Using Objective-C ===
Add the code
<syntaxhighlight lang ="objective-c">
#import <NielsenAppApi/NielsenAppApi.h>
</syntaxhighlight>
to the View Controller’s header file.

DCR Italy AUDIO iOS SDK

2023-07-20T12:15:08Z

NickParrucci:

{{Breadcrumb|}} {{Breadcrumb|Digital}} {{Breadcrumb|International DCR}} {{CurrentBreadcrumb}}
[[Category:Digital]]

== Overview ==
The Nielsen SDK is one of multiple framework SDKs that Nielsen provides to enable measuring linear (live) and on-demand TV viewing using TVs, mobile devices, etc.
The App SDK is the framework for mobile application developers to integrate Nielsen Measurement into their media player applications. It supports a variety of Nielsen Measurement Products like Digital in TV Ratings, Digital Content Ratings ([[DCR & DTVR]]), and [[Digital Ad Ratings]] (DAR). Nielsen SDKs are also equipped to measure static content and can track key life cycle events of an application like:
*Application launch events and how long app was running
*Time of viewing a page / sub section in the application.

== Prerequisites ==
Before you start the integration, you will need:
{| class="wikitable"
|-
! style="width: 15%;" | Item
! Description
! Source
|-
|| '''App ID (appid)''' || Unique ID assigned to the player/site and configured by product. || Provided by Nielsen
|-
|| '''Nielsen SDK''' || Includes SDK frameworks and '''sample implementation'''; ''See [[iOS SDK Release Notes]]'' || [[Special:Downloads|Download]]
|-
|| '''sfcode''' || Unique identifier for the environment that the SDK should point to || Provided by Nielsen
|}

If need App ID(s) or our SDKs, feel free to reach out to us and we will be happy to help you get started.
Refer to [[Digital Measurement Onboarding]] guide for information on how to get a Nielsen App SDK and appid.

=== Notes for WebView Contents ===
<code>Please note that if within your APP user can surf '''static contents''' recalled from your website the [[DCR_Italy_Static_Browser_SDK|browser static SDK]] have to inhibit from this pages.</code>
__TOC__

== Implementation ==
This guide covers implementation steps for iOS using Xcode utilizing the Standard Nielsen SDK for DCR.

<code>If you are building an app for the 'kids category' please review the [[DCR_Italy_Video_iOS_SDK#Special_Note_Regarding_Apps_in_the_Kids_Category|Opt Out Requirement.]]</code>

=== How to obtain the NielsenAppApi.Framework ===
The Nielsen AppSDK can either be downloaded directly or can be integrated directly within an application through the use of CocoaPods. We recommend using the CocoaPods-based integration whenever possible to ensure you maintain the most recent changes and enhancements to the Nielsen libraries.
* [[Digital_Measurement_iOS_Artifactory_Guide|Select to obtain CocoaPods implementation guide]]
* [[Special:Downloads|Select to Download Directly]]
* [[DCR_Video_iOS_SDK_xcframework|Using the XCFramework bundle]]

== Special Notes regarding iOS14 ==
=== Permission to Track ===

Apple recently released a new policy on consent requirements, that require the user's permission, to track them using their device's advertising identifier (IDFA). To request the user's permission, use the AppTrackingTransparency framework.

For more information, see:
* [https://developer.apple.com/documentation/apptrackingtransparency App Tracking Transparency]
* [https://developer.apple.com/design/human-interface-guidelines/ios/app-architecture/requesting-permission/ Human Interface Guidelines]
* [https://developer.apple.com/documentation/adsupport AdSupport Framework]

More detailed information on how the Nielsen SDK versions work with the AppTrackingTransparency framework is located on our [[ DCR Video iOS14 Migration|DCR Audio/Video iOS14 Migration]] page.

== Setting up your Development Environment ==
Prior to SDK Version 6.2.0.0 the IOS framework has been distributed as a static library packaged into framework bundle format. Apple recommends to use dynamic framework, it has some benefits over static libraries like less executable file size of an app, faster startup time and native support in xCode IDE. Nielsen AppSDK has been transformed into dynamic framework in this release ([[iOS_Static_Framework_Setup|static framework]] is still available).

If migrating from the static library to this new dynamic framework, once implemented, unless your specific application requires, you can remove the following Frameworks that were once required:<code> [AdSupport, JavascriptCore, SystemConfiguration, Security, AVFoundation, libc++] </code>
<br>

The '''Dynamic framework''' is created as a fat framework. It means that it contains slices required for devices (armv7, arm64) as well as slices required for simulators (i386, x86_64). Simulator slices are needed to let clients build and debug their app on the simulators, but they should be removed before sending the app to the AppStore. The example of the shell script that should be added as a Run Script phase in the application can be [[DCR_Video_iOS_SDK#Removing_Simulators_.28Dynamic_Framework_Only.29|found below]].

'''[[DCR_Video_iOS_SDK_xcframework|XCFramework]]''' is solution for the problems described above Apple recommends to use XCFrameworks. In XCFramework, we no longer build a single framework with multiple architectures. Instead, we build one small framework for each combination of architecture and target and store it in its own folder. The top-level XCFramework folder have folders like ios-arm64, ios-arm64-simulator, etc. Each of these folders is its own framework, complete with headers, modules, and binary.

=== Configuring Xcode Development Environment ===
Starting with SDK version 6.0.0.0, the Nielsen App SDK is compatible with Apple iOS versions 8.0 and above. In addition, when using the dynamic framework, all the required frameworks are linked automatically as the are needed. More details can be found here: https://stackoverflow.com/questions/24902787/dont-we-need-to-link-framework-to-xcode-project-anymore

<blockquote>'''Note''': All communications between the SDK and the Census (Collection Facility) use HTTPS.</blockquote>

=== Special Note for Static Framework ===
Starting from 8.2.0.0 release framework is build from the mixed (swift + objc) source code.
If [[iOS_Static_Framework_Setup|static (xc)framework is integrated additional settings]] should be applied to fix build or runtime issues.

=== Download Framework ===
The first step is to download and copy the [[Special:Downloads|NielsenAppApi.framework]] bundle to the app project directory. (''Not required if using CocaPods'')

=== Add Framework ===
In the General tab for app configuration add NielsenAppApi.framework in the list of Embedded Binaries. (''Not required if using CocaPods'')

=== Add Path ===
Add path to the NielsenAppApi.framework in the Framework Search Paths build setting. (''Not required if using CocaPods'')

=== Import Framework ===
Add NielsenAppApi.framework module in the source file of your app:

==== Using Swift ====
Add the following:
<syntaxhighlight lang="swift">
import NielsenAppApi
</syntaxhighlight>

==== Using Objective-C ====
<syntaxhighlight lang ="objective-c">
@import NielsenAppApi;
</syntaxhighlight>

==== xCode 12 building errors ====
Developers who uses "fat" framework in their apps started reporting the following error that they get building the app in xCode 12.3+:
<blockquote>Building for iOS Simulator, but the linked and embedded framework 'MyFramework.framework' was built for iOS + iOS Simulator.</blockquote>
The binary framework contains different code for the same architecture in multiple places, and Xcode doesn’t know how to handle it. There is workaround that people recommend to use in such cases:
* https://stackoverflow.com/questions/63267897/building-for-ios-simulator-but-the-linked-framework-framework-was-built
* https://stackoverflow.com/questions/63932158/xcode12-issus-ld-building-for-ios-simulator-but-linking-in-object-file-built

==== IPA processing failure ====
<code>Assertion failed: Expected 4 archs in otool output:</code>

The error above is due to the "fat" (simulator+device) framework which will not appear if you have not enabled Bitcode. To build your app with full Bitcode support, it is recommended that you use a [[DCR_Video_iOS_SDK_xcframework|XCFramework]] to avoid the 4 archs in otool output message.

== SDK Initialization ==
The latest version of the Nielsen App SDK allows instantiating multiple instances of the SDK object, which can be used simultaneously without any issue. The sharedInstance API that creates a singleton object was deprecated prior to version 5.1.1. [[Dual_Instances_of_SDK|(Click here for an example of multiple instances)]]

The following table contains the list of arguments that can be passed via the AppInfo JSON schema.
*The appid is provided by the Nielsen Technical Account Manager (TAM). The appid is a GUID data type and is specific to the application.
{| class="wikitable"
|-
! Parameter / Argument !! Description !! Source !! Required? !! Example
|-
| appid || Unique Nielsen ID for the application. The ID is a GUID data type. If you did not receive your App ID, let us know and we will provide you. || Nielsen-specified || Yes || PXXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX
|-
| appname || Name of the application
|| Client-defined || Yes || "Nielsen Sample App"
|-
| appversion || Current version of the app used
|| Client-defined || Yes || "1.0.2"
|-
| sfcode || Nielsen collection facility to which the SDK should connect.

|| Nielsen-specified || Yes ||
|-
| nol_devDebug || Enables Nielsen console logging. Only required for testing
|| Nielsen-specified || Yes for Debugging / Testing App || "DEBUG"
|}

== Debug flag for development environment ==
Player application developers / integrators can use Debug flag to check whether an App SDK API call made is successful. To activate the Debug flag,
Pass the argument <code>@"nol_devDebug":@"DEBUG"</code>, in the JSON string . The permitted values are:

* '''INFO''': Displays the API calls and the input data from the application (validate player name, app ID, etc.). It can be used as certification Aid.
* '''WARN''': Indicates potential integration / configuration errors or SDK issues.
* '''ERROR''': Indicates important integration errors or non-recoverable SDK issues.
* '''DEBUG''': Debug logs, used by the developers to debug more complex issues.

Once the flag is active, it logs each API call made and the data passed. The log created by this flag is minimal.
<blockquote>'''Note''': Activate the Debug flag in a Test environment.</blockquote>

=== Sample SDK Initialization Code ===

==== App tracking transparency framework ====

To display the App Tracking Transparency authorization request for accessing the IDFA, update your <code>info.plist</code> to add the <code>NSUserTrackingUsageDescription</code> key with a custom message describing your usage. Below is an example description text:
<code><key>NSUserTrackingUsageDescription</key></code>
<code><string>This identifier will be used to deliver personalized ads to you.</string></code>

The system automatically generates the prompt’s title, which includes the name of your app, then the usage description appears as part of the App Tracking

To present the authorization request, call requestTrackingAuthorizationWithCompletionHandler.

<blockquote>Please NOTE: It is important to initialize the NielsenSDK after the ATTrackingManager has Authorized usage. When the SDK initializes, it checks the status of the ATTrackingManager.</blockquote>

You can find an example in the file [[Special:Downloads|Global iOS SDK Download]] from the '''SDK Downloads''' section, folder name NielsenSampleVideoPlayer.

====Swift 4.0 Example:====
<code>NielsenInit.swift</code>
<syntaxhighlight lang="swift">
import Foundation
import NielsenAppApi

class NielsenInit : NSObject {
class func createNielsenApi(delegate: NielsenAppApiDelegate) -> NielsenAppApi?{

let appInformation:[String: String] = [
"appid": "PDA7D5EE6-B1B8-4123-9277-2A788XXXXXXX",
"appversion": "1.0.2",
"appname": "Nielsen Sample App",
"nol_devDebug": "DEBUG"
]
return NielsenAppApi(appInfo:appInformation, delegate:delegate)
}
}
</syntaxhighlight>

===Sample code using AVPlayer===
<code>ViewController.swift</code>

<syntaxhighlight lang="swift">
class ViewController: UIViewController, NielsenAppApiDelegate, AVPictureInPictureControllerDelegate, CLLocationManagerDelegate {

let avPlayerViewController = AVPlayerViewController()
var avPlayer:AVPlayer?
var nielsenAppApi: NielsenAppApi!

override func viewDidLoad() {
super.viewDidLoad()

self.nielsenAppApi = NielsenInit.createNielsenAppApi(delegate: self)
NSLog("Nielsen SDK initialized")

}
}
</syntaxhighlight>

===Objective C ====
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>
<syntaxhighlight lang="objective-c">
#import "NlsAppApiFactory.h"
#import <NielsenAppApi/NielsenAppApi.h>

@implementation NlsAppApiFactory

+ (NielsenAppApi *)createNielsenAppApiWithDelegate:(id<NielsenAppApiDelegate>)delegate;
{

NSDictionary *appInformation = @{
@"appid": "PDA7D5EE6-B1B8-4123-9277-2A788XXXXXXX",
@"appversion": "1.0.2",
@"appname": "Nielsen Sample App",
@"nol_devDebug": @"DEBUG"
};

return [[NielsenAppApi alloc] initWithAppInfo:appInformation delegate:delegate];
}

@end
</syntaxhighlight>

The following would be the <code>NlsAppApiFactory.h</code> file:
<syntaxhighlight lang="objective-c">
#import <Foundation/Foundation.h>

@class NielsenAppApi;
@protocol NielsenAppApiDelegate;

@interface NlsAppApiFactory : NSObject

+ (NielsenAppAPI *) createNielsenAppApiWithDelegate:(id<NielsenAppApiDelegate>)delegate;

@end
</syntaxhighlight>

=== Sample Code: ===
<syntaxhighlight lang="objective-c">
@implementation ViewController

- (void)viewDidLoad {
[super viewDidLoad];

//Getting the instance of Nielsen SDK
nielsenApi = [NlsAppApiFactory createNielsenAppApiWithDelegate:nil];
}}
</syntaxhighlight>



== APP SDK Error & Event Codes ==
To view the Error and Event codes for iOS, please review the [[APP SDK Event Codes|App SDK Event Code]] Reference page.

== Configure Metadata ==
=== 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 Nielsen Key names (e.g. appid, program) 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.

Example for Audio measurement:
{{ExampleCode|
|Swift =
<syntaxhighlight lang="swift">

let channelInfo = [
"channelName": "My Channel Name 1",
];

let contentMetadata = [
"type": "content",
"isAudio": "true",
"assetid": "88675545",
"title": "Program S3, EP1",
"isfullepisode":"y",
"adloadtype":"2",
"program":"Program Name",
"length":"3600",
"airdate":"20171020 10:05:00"
];
</syntaxhighlight>
|Objective C = <syntaxhighlight lang="objective-c">
NSDictionary *channelInfo = @
{
@"channelName":@"My Channel Name 1",
}

NSDictionary * contentMetadata = @ {
@ "type": @ "content",
@ "isAudio": @"true",
@ "assetid": @ "88675545",
@ "title": @ "Program S3, EP1",
@ "isfullepisode": @ "y",
@ "program": @ "Program Name",
@ "length": @ "3600",
@ "airdate": @ "20200321 10:05:00",
@ "adloadtype": @ "2"
}
</syntaxhighlight>
}}


=== Configure metadata ===
Configure metadata should remain constant throughout the completion of an episode or live stream
{| class="wikitable"
|-
! Keys !! Description !! Values !! Required
|-
| channelName || Any string representing the channel/stream || custom || Yes
|}

=== Create Metadata Objects ===
There are two types of asset metadata:
*content: identify audio /video
*ad: identify each ad

The metadata received for each asset is used for classification and reporting.

Metadata can be passed through key-values using the Nielsen reserved keys. User will need to set up content and ad objects with the required Nielsen keys as shown in the sample code below.

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

{| class="wikitable"
|-
! Keys !! Description !! Values !! Required
|-
| type || type of asset || <code>'content'</code> || Yes
|-
| isAudio || indicate measurement of audio ads or audio content || <code>'true'</code> || Yes
|-
| assetid || unique ID assigned to asset (32 Character limit) || custom (no [[Special Characters|Special Characters]]) || Yes
|-
| program || name of program (100 character limit) || custom || Yes
|-
| title || name of program (100 character limit) || custom || Yes
|-
| length || length of content in seconds || Length of content in seconds (86400 seconds for live stream (24/7). For Event-Live streams planned length. For AOD video length)|| Yes
|-
| airdate || The airdate in the linear over-the-air broadcast. Original (local) air date and time (hh:mm:ss as 24h time stamp); if not known set it to eg. "19700101 00:00:00" || YYYYMMDD HH24:MI:SS
(if not known set it to eg. "19700101 00:00:00")
|| Yes
|-
| isfullepisode || full episode flag || <code>'y'</code>- full episode, <code>'n'</code>- non full episode || Yes
|-
| adloadtype || type of ad load:
*<code>'1'</code> Linear – matches TV ad load
*<code>'2'</code> Dynamic – Dynamic Ad Insertion (DAI)
|| <code>'2'</code> - DCR measures content with dynamic ads
|| Yes

|}

===== Example Audio Content Object =====

<syntaxhighlight lang="swift">

let contentMetadata = [
"type": "content",
"isAudio": "true",
"assetid": "88675545",
"title": "Program S3, EP1",
"isfullepisode":"y",
"adloadtype":"2",
"program":"Program Name",
"length":"3600",
"airdate":"20171020 10:05:00"
];
</syntaxhighlight>

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

'''Don't pass audio key "isAudio" into the loadmetadata call for video measurement'''.

{| class="wikitable"
|-
! Keys !! Description !! Values !! Required
|-
| type || type of asset || <code>'content'</code> || Yes
|-
| assetid || unique ID assigned to asset (32 Character limit) || custom (no [[Special Characters|Special Characters]]) || Yes
|-
| program || name of program (100 character limit) || custom || Yes
|-
| title || name of program (100 character limit) || custom || Yes
|-
| length || length of content in seconds || Length of content in seconds (86400 seconds for live stream (24/7). For Event-Live streams planned length. For AOD video length)|| Yes
|-
| airdate || The airdate in the linear over-the-air broadcast. Original (local) air date and time (hh:mm:ss as 24h time stamp); if not known set it to eg. "19700101 00:00:00" || YYYYMMDD HH24:MI:SS
(if not known set it to eg. "19700101 00:00:00")
|| Yes
|-
| isfullepisode || full episode flag || <code>'y'</code>- full episode, <code>'n'</code>- non full episode || Yes
|-
| adloadtype || type of ad load:
*<code>'1'</code> Linear – matches TV ad load
*<code>'2'</code> Dynamic – Dynamic Ad Insertion (DAI)
|| <code>'2'</code> - DCR measures content with dynamic ads
|| Yes

|}

===== Example Video Content Object =====

<syntaxhighlight lang="swift">

let contentMetadata = [
"type": "content",
"assetid": "88675545",
"title": "Program S3, EP1",
"isfullepisode":"y",
"adloadtype":"2",
"program":"Program Name",
"length":"3600",
"airdate":"20171020 10:05:00"
];
</syntaxhighlight>

==== Ad Metadata ====
The Ad Metadata (if applicable) should be passed for each individual ad.
{| class="wikitable"
|-
! Keys !! Description !! Values !! Required
|-
| type || type of Ad || <code>'preroll'</code>, <code>'midroll'</code>, <code>'postroll'</code> || Yes
|-
| assetid || unique ID assigned to Ad || custom (no [[Special Characters|Special Characters]]) || Yes
|}

==== Example Ad Object ====

<syntaxhighlight lang="swift">

let adMetadata = [
"assetid" : "unique_postroll_ad_id",
"type" : "preroll"
]
</syntaxhighlight>

== Configure API Calls ==

=== Sample API Sequence ===
A Sample API sequence could follow this flow:
{| class="wikitable"
|-
! Type !! Sample code !! Description
|-
|On App Start||<syntaxhighlight lang=Swift>
NielsenInit.createMainBrandApi(delegate: self)
self.data = loadStaticMetadata()
self.nielsenMeter .loadMetadata(self.data)</syntaxhighlight> || // Pass Static Metadata here if applicable
|-
| rowspan="2" | Start of stream || <code>nielsenMeter.play()</code> || // Call at start of each new stream
|-
| <code>nielsenMeter.loadMetadata(contentMetadata)</code> || // MetadataObject contains the JSON metadata<br> for the content being played
|-
| Content || <code>nielsenMeter.playheadPosition(pos);</code> || // playheadPosition is position of the playhead <br>while the content is being played
|-
| End of Stream || <code>nielsenMeter.end()</code> || // Content playback is completed.
|}

=== SDK Events ===
{| class="wikitable"
|-
! Event !! Parameter !! Description
|-
| 'play' || || Call at start of each new stream
|-
| 'loadMetadata' || content/ad metadata object || Needs to be called at the beginning of each asset
|-
| 'playheadPosition' || playhead position as integer<br/>
AOD: current position in seconds <br/>
Live: current UNIX timestamp (seconds since Jan-1-1970 UTC) <br/>
Note: 'PlayheadPosition' has to be called every second
||
Pass playhead position every second during playback
|-
| 'stop' || playhead position || Call during any interruption to content or Ad playback and at the end of each Ad.
|-
| 'end' || playhead position in seconds || Call when the current audio asset completes playback and pass the playhead position. <br/>
Example: At the end of the content stream, if the user switches to another piece of content, when the media player is reloaded or closed.
|}
<blockquote>Note: For livestream, send the UNIX timestamp, for AOD send the time in seconds as integer. The final playhead position must be sent for the current asset being played before calling <code>'''stop'''</code>, <code>'''end'''</code> or<code> '''loadmetadata'''</code>,.</blockquote>

=== Life cycle of SDK instance ===
Life cycle of SDK instance includes four general states:
# '''Initial state''' – The SDK is not initialized and hence, not ready to process playing information. Once the SDK is moved out of this state, it needs instantiation of the new SDK instance in order to get the instance in the '''Idle state'''.
# '''Idle state''' – The SDK is initialized and is ready to process playing information. Once Initialized, the SDK instance is not processing any data, but is listening for an event to occur.
# '''Processing state''' – The SDK instance is processing playing information. The <code>'''play'''</code> and <code>'''loadMetadata''' </code> calls move the SDK instance into this state. In this state, the SDK instance will be able to process the following calls.
## <code>'''playheadPosition'''</code> – Call this API every one second when playhead position is active. If a LIVE event, use the current UNIX timestamp (seconds since Jan-1-1970 UTC).
## <code>'''stop'''</code> – Call this API when the content or Ad playback is interrupted and at the end of each Ad.
## <code>'''end'''</code> – Call when content completes. When called, the SDK instance exits from Processing state.
# '''Disabled state''' – The SDK instance is disabled and is not processing playing information.
## <code>'''appDisableApi'''</code> is set to <code>true</code>

<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 <code>'''loadMetadata''' </code> and <code>'''playheadPosition'''</code> </blockquote>

=== API Call Sequence ===
==== Use Case 1: Content has no Advertisements ====
Call [[play()]] at start of stream

Call [[loadMetadata()]] with JSON metadata for content as below.
<syntaxhighlight lang="json">{
"type": "content",
"isAudio": "true",
"assetid": "88675545",
"title": "Program S3, EP1",
"isfullepisode":"y",
"adloadtype":"2",
"program":"Program Name",
"length":"3600",
"airdate":"20171020 10:05:00"
}</syntaxhighlight>
Call [[playheadPosition|playheadPosition()]] every one second until a pause / stop.
Use the sample API sequence below as a reference to identify the specific events that need to be called during content playback without ads.
{| class="wikitable"
|-
! Type !! Sample code !! Description
|-
| rowspan="2" | Start of stream || <code>mAppSdk.play(); </code> || // Call at start of each new stream
|-
| <code>mAppSdk.loadMetadata(contentMetaDataObject);</code> || // contentMetadataObject contains the JSON metadata for the content being played
|-
| Content || <code>mAppSdk.setPlayheadPosition(playheadPosition);</code> || // position is position of the playhead while the content is being played
|-
| Interruption || <code>mAppSdk.stop();</code> || // call stop when content playback is interrupted
|-
| rowspan="2" | Resume Content || <code>mAppSdk.loadMetadata(contentMetaDataObject);</code> || // Call loadMetadata and pass content metadata object when content resumes
|-
|<code>mAppSdk.setPlayheadPosition(playheadPosition);</code> || // continue pasing playhead position every second starting from position where content is resumed
|-
| End of Stream || <code>mAppSdk.end();</code> || // Content playback is completed.
|}

==== Use Case 2: Content has Advertisements ====

Call [[play()]] at start of stream

Call [[loadMetadata()]] with JSON metadata for ad as below.
<syntaxhighlight lang="json">{
"type": "preroll",
"assetid": "ad123"
}</syntaxhighlight>
<blockquote>Note: In case the individual ad details are not available, send ad pod (presence) details through the [[loadMetadata]] and playhead position through [[playheadPosition]].</blockquote>

Call [[playheadPosition|playheadPosition()]] every one second until a pause / stop / another [[loadMetadata()]] is called. Playhead should be passed for the entire duration of ad pod, if the ad pod details are passed as part of [[loadMetadata()]].

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"
|-
! Type !! Sample code !! Description
|-
| rowspan="2" | Start of stream || <code>mAppSdk.play(); </code> || // stream starts
|-
| <code>mAppSdk.loadMetadata(contentMetaDataObject);</code> || // contentMetadataObject contains the JSON metadata for the content being played
|-
| rowspan="3" | Preroll || <code>mAppSdk.loadMetadata(prerollMetadataObject);</code> || // prerollMetadataObject contains the JSON metadata for the preroll ad
|-
| <code>mAppSdk.playheadPosition(playheadPosition);</code> || // position is position of the playhead while the preroll ad is being played
|-
| <code>mAppSdk.stop();</code> || // Call stop after preroll occurs
|-
| rowspan="2" | Content || <code>mAppSdk.loadMetadata(contentMetaDataObject);</code> || // contentMetadataObject contains the JSON metadata for the content being played
|-
| <code>mAppSdk.playheadPosition(playheadPosition);</code> || // position is position of the playhead while the content is being played
|-
| rowspan="3" | Midroll || <code>mAppSdk.loadMetadata(midrollMetaDataObject);</code> || // midrollMetadataObject contains the JSON metadata for the midroll ad
|-
| <code>mAppSdk.playheadPosition(playheadPosition);</code> || // position is position of the playhead while the midroll ad is being played
|-
| <code>mAppSdk.stop();</code> || // Call stop after midroll occurs
|-
| rowspan="2" | Content Resumes || <code>mAppSdk.loadMetadata(contentMetaDataObject);</code> || // contentMetadataObject contains the JSON metadata for the content being played
|-
| <code>mAppSdk.playheadPosition(playheadPosition);</code> || // position is position of the playhead while the content is being played
|-
| End of Stream || <code>mAppSdk.end();</code> || // Call end() at the end of content
|-
| rowspan="3" | Postroll || <code>mAppSdk.loadMetadata(postrollMetaDataObject);</code> || // postrollMetadataObject contains the JSON metadata for the postroll ad
|-
| <code>mAppSdk.playheadPosition(playheadPosition);</code> || // position is position of the playhead while the postroll ad is being played
|-
| <code>mAppSdk.stop();</code> || // Call stop after postroll occurs
|}

<blockquote>Note: Each Ad playhead should 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>

== Sequence of Calls ==
=== play ===
Call <code>play</code> at the start of each new stream. If changing audio or listening to a new audio, call <code>play()</code> each time.
{{ExampleCode|
|Objective C = <syntaxhighlight lang="objective-c"> [nielsenAppApi play:()];</syntaxhighlight>
|Swift = <syntaxhighlight lang="swift">nielsenAppApi?.play();</syntaxhighlight>
}}

=== loadMetadata ===
{{ExampleCode|
|Objective C = <syntaxhighlight lang="objective-c">[nielsenApi loadMetadata:(contentMetadata)];</syntaxhighlight>
|Swift = <syntaxhighlight lang="swift">self.nielsenAppApi?.loadMetadata(contentMetadata)</syntaxhighlight>
}}

=== playheadPosition ===
{{ExampleCode|
|Objective C = <syntaxhighlight lang="objective-c">

-(void) setPlayHeadPosition {

//Setting play head position
CMTime timeInterval = CMTimeMakeWithSeconds(1, 1);
[player addPeriodicTimeObserverForInterval:(timeInterval) queue:dispatch_get_main_queue() usingBlock:^(CMTime time){
NSTimeInterval seconds = CMTimeGetSeconds(time);
NSInteger intSec = seconds;

//Sending data dictionary to SDK with updated playHead position.
[nielsenApi playheadPosition:(intSec)];
}];
}
</syntaxhighlight>

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

=== stop ===
{{ExampleCode|
|Objective C = <syntaxhighlight lang="objective-c">[nielsenApi stop];</syntaxhighlight>
|Swift = <syntaxhighlight lang="swift">nielsenApi.stop()</syntaxhighlight>
}}

=== end ===
When content stop is initiated and content cannot be resumed from the same position (it can only be restarted from the beginning of stream).
{{ExampleCode|
|Objective C = <syntaxhighlight lang="objective-c">[nielsenApi end];</syntaxhighlight>
|Swift = <syntaxhighlight lang="swift">nielsenApi.end()</syntaxhighlight>
}}

== Handling Foreground and Background states ==
For iOS, background/foreground detection is handled by the app lifecylce APIs which are provided by [https://developer.apple.com/library/content/documentation/iPhone/Conceptual/iPhoneOSProgrammingGuide/TheAppLifeCycle/TheAppLifeCycle.html Apple:]

Foreground/Background state measurement is a requirement of Nielsen AppSDK implementation which is especially crucial for static measurement.

== 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
* App going in the Background/Foreground
* 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 API calls – <code>'loadMetadata'</code> and <code>'playheadPosition'</code> for the new viewing session, once the playback resumes.
Please see the [https://engineeringportal.nielsen.com/docs/Digital_Measurement_Interruption_Scenarios Interruption Scenarios Page] for more details

== Privacy and Opt-Out ==
There are two primary methods for implementing user Opt-out preferences:

*[[DCR_Italy_Video_iOS_SDK#OS-level_Opt-out|OS-level Opt-out]] - managed by AppTracking or Limit Ad Tracking setting on device (preferred approach).
*[[DCR_Italy_Video_iOS_SDK#User_Choice|User Choice]] - Direct call to SDK. Can be used without the Ad Framework

=== Special Note Regarding Apps in the Kids Category ===
If you are building an app that will be listed in the Kids Category:

Ensure that you are using the [https://nielsendownloads-green.digitalengsdk.com/digital/Nielsen-iOS-App-SDK-GlobalNoId_latest.zip NoID version:] of the Nielsen SDK Framework. Also, you can use the [[Digital_Measurement_iOS_Artifactory_Guide|Artifactory method.]]
Immediately following the initialization of the Nielsen SDK ensure you call the userOptOut API with Opt out selection:
<syntaxhighlight lang="swift">NielsenAppApi?.userOptOut("nielsenappsdk://1"); // User opt-outv</syntaxhighlight>

=== OS-level Opt-out ===
''OS-level Opt-out'' method available on Nielsen iOS

The Nielsen SDK automatically leverages the iOS's '''Limit Ad Tracking''' or '''AppTracking''' setting.

*If the User's device is running < iOS 13.x, the Nielsen SDK will check the status of '''Limit Ad Tracking'''.
*iOS14 modifies the way Apple manages the collection of a User's Opt-In status through '''AppTracking'''. Starting with Version 8.x+, the Nielsen App SDK will check the iOS version during initialization. If the device is running iOS12 or iOS13, the Limit Ad Tracking setting is requested. If iOS14.x +, then AppTracking is utilized.

==== Get the latest Nielsen opt-out URL ====

*Get the current Nielsen opt-out URL via [[optOutURL|optOutURL]]
*Display a WebView element whose loadUrl is set to the value obtained from [[optOutURL|optOutURL]]

==== Webview Example ====
The below code is an example of displaying the Nielsen Privacy page to the user.
<blockquote>Note: Apple released a policy update stating that the App Store will no longer accept updates for apps using the deprecated UIWebView (no specific date has been confirmed). Since then, we’ve recommended that you adopt WKWebView instead of UIWebView and WebView.
</blockquote>
<syntaxhighlight lang="swift">
import UIKit
import WebKit
import NielsenAppApi

class OptOutVC: UIViewController, NielsenAppApiDelegate, WKNavigationDelegate {
var webView: WKWebView!
var nielsenApi: NielsenAppApi!

override func loadView() {
webView = WKWebView()
webView.navigationDelegate = self
view = webView }

override func viewDidLoad() {
super.viewDidLoad()
self.view.backgroundColor = UIColor(patternImage: UIImage(named: "new_ios_bg.png")!)
self.nielsenApi = NielsenInit.createNielsenApi(delegate: self) //create an instance

if let appApi = self.nielsenApi {
//Getting the optPut URL from SDK
if let url = URL(string: appApi.optOutURL) { //query the nielsensdk for the current privacy page
webView.load(URLRequest(url: url))
webView.allowsBackForwardNavigationGestures = true
}}}}
</syntaxhighlight>

=== User Choice ===
The User Choice method can be used without the Ad Framework, or in situations where the publisher does not wish to use the [https://developer.apple.com/documentation/apptrackingtransparency App Tracking Transparency Framework.]

==== The User Choice opt-out method works as follows: ====

*Get the Nielsen opt-out URL via [[optOutURL|optOutURL]]
*Display a WebView element whose loadUrl is set to the value obtained from [[optOutURL|optOutURL]]
*Detect if the WebView URL changes to a special URL that indicates Opt-in, or Opt-out and close the WebView
**Opt-out if the WebView URL = <code>nielsenappsdk://1</code>
**Opt-in if the WebView URL = <code>nielsenappsdk://0</code>
*Pass the detected URL to the [[userOptOut|userOptOut]] function
Example:
<syntaxhighlight lang="swift">NielsenAppApi?.userOptOut("nielsenappsdk://1"); // User opt-out </syntaxhighlight>

==== Opt-out example code ====
<blockquote>Note: Apple released a policy update stating that the App Store will no longer accept updates for apps using the deprecated UIWebView (no specific date has been confirmed). Since then, we’ve recommended that you adopt WKWebView instead of UIWebView and WebView.
</blockquote>

===== Objective-C =====

<syntaxhighlight lang="objective-c">
- (void)webView:(WKWebView *)webView decidePolicyForNavigationAction:(WKNavigationAction *)
navigationAction decisionHandler:(void (^)(WKNavigationActionPolicy))decisionHandler {

NSURLRequest *request = [navigationAction request];
NSString *url = [[request URL]absoluteString];

if([url isEqualToString:self.NIELSEN_URL_OPT_OUT] || [url isEqualToString:self.NIELSEN_URL_OPT_IN]){
[self.nielsenApi userOptOut:url];
decisionHandler(WKNavigationActionPolicyAllow);
}else{
decisionHandler(WKNavigationActionPolicyCancel);
}
}
</syntaxhighlight>

===== Swift =====
<syntaxhighlight lang="swift">
var webView: WKWebView!
var NIELSEN_URL_OPT_OUT : String = "nielsenappsdk://1"
var NIELSEN_URL_OPT_IN : String = "nielsenappsdk://0"

func webView(_ webView: WKWebView, decidePolicyFor navigationAction: WKNavigationAction,
decisionHandler: @escaping (WKNavigationActionPolicy) -> Void) {

let urlStr = navigationAction.request.url?.absoluteString

if(urlStr == NIELSEN_URL_OPT_OUT || urlStr == NIELSEN_URL_OPT_IN){
let appApi = self.nielsenApi
appApi?.userOptOut(urlStr)
decisionHandler(.allow)

}else{
decisionHandler(.cancel)
}
}
</syntaxhighlight>

=== Retrieve current Opt-Out preference ===
Whether the user is opted out via OS-level Opt-out or via User Choice Opt-out, the current Opt-Out status as detected by the SDK is available via the [[optOutStatus|optOutStatus]] property in the Nielsen SDK API

==== Required Privacy Links ====
Users must either have access to the "About Nielsen Measurement" page, or have similar text available within the native app. 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.

In addition, the following text must be included in your app store description.

Si prega di notare che questa app include il software di misurazione proprietario di Nielsen che contribuisce alla ricerca di mercato. Per ulteriori informazioni, si prega di consultare il seguente link [https://global.nielsen.com/legal/privacy-principles/digital-measurement-privacy-statement/?lang=it https://global.nielsen.com/legal/privacy-principles/digital-measurement-privacy-statement/?lang=it]

== Going Live ==
Following Nielsen testing, you will need to:

# '''Disable Debug Logging''': Disable logging by deleting <code>{nol_devDebug: 'DEBUG'}</code> from initialization call.
# '''Notify Nielsen''': Once you are ready to go live, let us know so we can enable you for reporting. We will not be able to collect or report data prior to receiving notification from you.

== Removing Simulators (Dynamic Framework Only)==

Simulator slices are needed to let clients build and debug their app on the simulators, but they should be removed before sending the app to the AppStore. Here is an example Shell script that could be added as a Run Script phase in the application.

<syntaxhighlight lang='bash'>

APP_PATH="${TARGET_BUILD_DIR}/${WRAPPER_NAME}"

# This script loops through the frameworks embedded in the application and
# removes unused architectures.
find "$APP_PATH" -name '*.framework' -type d | while read -r FRAMEWORK
do
FRAMEWORK_EXECUTABLE_NAME=$(defaults read "$FRAMEWORK/Info.plist" CFBundleExecutable)
FRAMEWORK_EXECUTABLE_PATH="$FRAMEWORK/$FRAMEWORK_EXECUTABLE_NAME"
echo "Executable is $FRAMEWORK_EXECUTABLE_PATH"

EXTRACTED_ARCHS=()

for ARCH in $ARCHS
do
echo "Extracting $ARCH from $FRAMEWORK_EXECUTABLE_NAME"
lipo -extract "$ARCH" "$FRAMEWORK_EXECUTABLE_PATH" -o "$FRAMEWORK_EXECUTABLE_PATH-$ARCH"
EXTRACTED_ARCHS+=("$FRAMEWORK_EXECUTABLE_PATH-$ARCH")
done

echo "Merging extracted architectures: ${ARCHS}"
lipo -o "$FRAMEWORK_EXECUTABLE_PATH-merged" -create "${EXTRACTED_ARCHS[@]}"
rm "${EXTRACTED_ARCHS[@]}"

echo "Replacing original executable with thinned version"
rm "$FRAMEWORK_EXECUTABLE_PATH"
mv "$FRAMEWORK_EXECUTABLE_PATH-merged" "$FRAMEWORK_EXECUTABLE_PATH"

done
</syntaxhighlight>

== Sample Applications ==
You can find some examples in the file [[Special:Downloads|Global iOS SDK Download]] from the '''SDK Downloads''' section

DCR KSA Video iOS SDK

2023-07-20T12:14:38Z

NickParrucci:

{{Breadcrumb|}} {{Breadcrumb|Digital}} {{Breadcrumb|International DCR}} {{CurrentBreadcrumb}}
[[Category:Digital]]
__TOC__

== Overview ==
The Nielsen SDK is one of the multiple framework SDKs that Nielsen provides to enable measuring linear (live) and on-demand TV viewing using TVs, mobile devices, etc.
The App SDK is the framework for mobile application developers to integrate Nielsen Measurement into their media player applications. It supports a variety of Nielsen Measurement Products like Digital Content Ratings (DCR), and [[Digital Ad Ratings]] (DAR). Nielsen SDKs are also equipped to measure static content and can track key life cycle events of an application like:
*Application launch events and how long app was running
{{iOS_SpecialNotes_for_iOS14}}

{{iOS_Prerequisites_and_Implementation_Overview}}

== Setting up your Development Environment ==
Prior to SDK Version 6.2.0.0 the IOS framework has been distributed as a static library packaged into framework bundle format. Apple recommends to use dynamic framework, it has some benefits over static libraries like less executable file size of an app, faster startup time and native support in xCode IDE. Nielsen AppSDK has been transformed into dynamic framework in this release ([[iOS_Static_Framework_Setup|static framework]] is still available).

If migrating from the static library to this new dynamic framework, once implemented, unless your specific application requires, you can remove the following Frameworks that were once required:<code> [AdSupport, JavascriptCore, SystemConfiguration, Security, AVFoundation, libc++] </code>
<br>

The '''Dynamic framework''' is created as a fat framework. It means that it contains slices required for devices (armv7, arm64) as well as slices required for simulators (i386, x86_64). Simulator slices are needed to let clients build and debug their app on the simulators, but they should be removed before sending the app to the AppStore. The example of the shell script that should be added as a Run Script phase in the application can be [[DCR_Video_iOS_SDK#Removing_Simulators_.28Dynamic_Framework_Only.29|found below]].

'''[[DCR_Video_iOS_SDK_xcframework|XCFramework]]''' is solution for the problems described above Apple recommends to use XCFrameworks. In XCFramework, we no longer build a single framework with multiple architectures. Instead, we build one small framework for each combination of architecture and target and store it in its own folder. The top-level XCFramework folder have folders like ios-arm64, ios-arm64-simulator, etc. Each of these folders is its own framework, complete with headers, modules, and binary.

=== Configuring Xcode Development Environment ===
Starting with SDK version 6.0.0.0, the Nielsen App SDK is compatible with Apple iOS versions 8.0 and above. In addition, when using the dynamic framework, all the required frameworks are linked automatically as the are needed. More details can be found here: https://stackoverflow.com/questions/24902787/dont-we-need-to-link-framework-to-xcode-project-anymore

<blockquote>'''Note''': All communications between the SDK and the Census (Collection Facility) use HTTPS.</blockquote>

=== Special Note for Static Framework ===
Starting from 8.2.0.0 release framework is build from the mixed (swift + objc) source code.
If [[iOS_Static_Framework_Setup|static (xc)framework is integrated additional settings]] should be applied to fix build or runtime issues.

=== Download Framework ===
The first step is to download and copy the [[Special:Downloads|NielsenAppApi.framework]] bundle to the app project directory. (''Not required if using CocaPods'')

=== Add Framework ===
In the General tab for app configuration add NielsenAppApi.framework in the list of Embedded Binaries. (''Not required if using CocaPods'')

=== Add Path ===
Add path to the NielsenAppApi.framework in the Framework Search Paths build setting. (''Not required if using CocaPods'')

=== Import Framework ===
Add NielsenAppApi.framework module in the source file of your app:

==== Using Swift ====
Add the following:
<syntaxhighlight lang="swift">
import NielsenAppApi
</syntaxhighlight>

==== Using Objective-C ====
<syntaxhighlight lang ="objective-c">
@import NielsenAppApi;
</syntaxhighlight>

==== xCode 12 building errors ====
Developers who uses "fat" framework in their apps started reporting the following error that they get building the app in xCode 12.3+:
<blockquote>Building for iOS Simulator, but the linked and embedded framework 'MyFramework.framework' was built for iOS + iOS Simulator.</blockquote>
The binary framework contains different code for the same architecture in multiple places, and Xcode doesn’t know how to handle it. There is workaround that people recommend to use in such cases:
* https://stackoverflow.com/questions/63267897/building-for-ios-simulator-but-the-linked-framework-framework-was-built
* https://stackoverflow.com/questions/63932158/xcode12-issus-ld-building-for-ios-simulator-but-linking-in-object-file-built

==== IPA processing failure ====
<code>Assertion failed: Expected 4 archs in otool output:</code>

The error above is due to the "fat" (simulator+device) framework which will not appear if you have not enabled Bitcode. To build your app with full Bitcode support, it is recommended that you use a [[DCR_Video_iOS_SDK_xcframework|XCFramework]] to avoid the 4 archs in otool output message.

== Create SDK Instance ==
The latest version of the Nielsen App SDK allows instantiating multiple instances of the SDK object when needed, which can then be used simultaneously. '''For the general use case where only one video is played at the same time in the App, a single instance of SDK object can then be used to play back and measure all watched streams one after another.'''

The following table contains the list of arguments that can be passed via the AppInfo JSON schema.
{| class="wikitable"
|-
! Parameter / Argument !! Description !! Source !! Required/Obligatory? !! Example
|-
| appid || Unique id for the application assigned by Nielsen. It is GUID data type.|| Nielsen-specified || Yes || "PXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX"
|-
| appname || Name of the application || Client-defined || Yes || "Nielsen Sample App"
|-
| appversion || Current version of the app used || Client-defined || Yes || "1.0.4"
|-
| sfcode || Nielsen collection facility to which the SDK should connect.
|| Nielsen-specified || Yes || "ksa"
|-
| nol_devDebug || Enables Nielsen console logging. Only required for testing
|| Nielsen-specified || Optional || "DEBUG"

|}
<br />

== Debug flag for development environment ==
Player application developers / integrators can use Debug flag to check whether an App SDK API call made is successful. To activate the Debug flag,
Pass the argument <code>@"nol_devDebug":@"DEBUG"</code>, in the JSON string.

* '''DEBUG''': Debug logs, used by the developers to debug more complex issues.

Once the flag is active, it logs each API call made and the data passed. The log created by this flag is minimal.
<blockquote>'''Note''': DO NOT activate the Debug flag in a production environment.</blockquote>

==== Sample SDK Initialization Code ====

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>

===== Using Objective-C=====
<syntaxhighlight lang="objective-c">
#import "NlsAppApiFactory.h"
#import <NielsenAppApi/NielsenAppApi.h>

@implementation NlsAppApiFactory

+ (NielsenAppApi *)createNielsenAppApiWithDelegate:(id<NielsenAppApiDelegate>)delegate;
{
NSDictionary *appInformation = @{
@"appid": "PXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX",
@"appversion": "1.0",
@"appname": "app name here",
@"sfcode": "ksa",
@"nol_devDebug": @"DEBUG"
};
return [[NielsenAppApi alloc] initWithAppInfo:appInformation delegate:delegate];
}
@end
</syntaxhighlight>

The following would be the <code>NlsAppApiFactory.h</code> file:
<syntaxhighlight lang="objective-c">
#import <Foundation/Foundation.h>

@class NielsenAppApi;
@protocol NielsenAppApiDeligate;

@interface NlsAppApiFactory : NSObject

+ (NielsenAppAPI *) createNielsenAppApiWithDelegate:(id<NielsenAppApiDelegate>)delegate;

@end
</syntaxhighlight>

===== Using Swift =====

<code>NielsenInit.swift</code>
<syntaxhighlight lang="swift">
class NielsenInit: NSObject {
class func createNielsenAppApi(delegate: NielsenAppApiDelegate) -> NielsenAppApi?{
let appInformation:[String: String] = [
"appid": "PXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX",
"appversion": "1.0",
"appname": "app name here",
"sfcode": "ksa",
"nol_devDebug": "DEBUG"
]
return NielsenAppApi(appInfo:appInformation, delegate:delegate)
}
}
</syntaxhighlight>

Sample code using AVPlayer.
<br />
<code>ViewController.swift</code>

<syntaxhighlight lang="swift">
class ViewController: UIViewController, NielsenAppApiDelegate, AVPictureInPictureControllerDelegate, CLLocationManagerDelegate {

let avPlayerViewController = AVPlayerViewController()
var avPlayer:AVPlayer?
var nielsenAppApi: NielsenAppApi!

override func viewDidLoad() {
super.viewDidLoad()

self.nielsenAppApi = NielsenInit.createNielsenAppApi(delegate: self)
NSLog("Nielsen SDK initialized")

}
}
</syntaxhighlight>

==== APP SDK Error & Event Codes ====
To view the Error and Event codes for iOS and Android, please review the [[APP SDK Event Codes|App SDK Event Code]] Reference page.

==== Life cycle of SDK instance ====
The 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. Once Initialized, 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. API calls "play" and "loadMetadata" move the SDK instance into this state. In this state, the SDK instance will be able to process the API calls (see below)
# '''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
## <code>appDisableApi</code> is called

<syntaxhighlight lang="objective-c">
@property (assign) BOOL appDisableApi;
</syntaxhighlight>

== Create Metadata Objects ==
The parameters passed must be either a JSON formatted NSString 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, 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.<br />

=== Create channelName Metadata ===
channelName should remain constant throughout the completion of an episode or live stream.
<br />
{| class="wikitable"
|-
! Key !! Description !! Values !! Required
|-
| channelName || Any string representing the channel/stream || custom || Yes
|-
|}

===Create Content Metadata ===
Content metadata should remain constant throughout the entirety of an episode/clip including when ads play.
{| class="wikitable"
|-
! Keys !! Description !! Values !! Required
|-
| type || type of asset || <code>'content'</code> || Yes
|-
| assetid || unique ID assigned to asset (32 Character limit) || custom (no [[Special Characters|Special Characters]]) || Yes
|-
| program || name of program (100 character limit) || custom || Yes
|-
| title || name of program (100 character limit) || custom || Yes
|-
| length || length of content in seconds || Length of content in seconds (86400 seconds for live stream (24/7). For Event-Live streams planned length. For VoD video length) || Yes
|-
| airdate || the airdate in the linear TV || YYYYMMDD HH24:MI:SS || Yes
|-
| isfullepisode || full episode flag || <code>'y'</code>- full episode, <code>'n'</code>- non full episode || Yes
|-
| adloadtype || type of ad load:
*<code>'1'</code> Linear – matches TV ad load
*<code>'2'</code> Dynamic – Dynamic Ad Insertion (DAI)
|| <code>'2'</code> - DCR measures content with dynamic ads
|| Yes

|}

===Create Ad Metadata ===
The Ad Metadata (if applicable) should be passed for each individual ad.
{| class="wikitable"
|-
! Keys !! Description !! Values !! Required
|-
| type || type of Ad || <code>'preroll'</code>, <code>'midroll'</code>, <code>'postroll'</code> || Yes
|-
| assetid || unique ID assigned to Ad || custom (no [[Special Characters|Special Characters]]) || Yes
|}

'''Note:''' All metadata values should be passed as UTF-8 strings.

<blockquote> URL Character Limit: There is a URL character limit of 2K characters due to browser limitations. Exceeding this value could impair data delivery on particular browsers. </blockquote>

=== MetaData Example ===

==== Using Objective-C ====
<syntaxhighlight lang="objective-c">
NSDictionary *channelInfo = @
{
@"channelName":@"My Channel Name 1",
}

NSDictionary *contentMetadata = @
{
@ "type": @ "content",
@ "assetid": @ "88675545",
@ "title": @ "Program S3, EP1",
@ "isfullepisode": @ "y",
@ "program": @ "Program Name",
@ "length": @ "3600",
@ "airdate": @ "20200321 10:05:00",
@ "adloadtype": @ "2"
}

NSDictionary *adMetadata = @
{
@"type" : "postroll",
@"assetid" : "AD-ID123"
}
</syntaxhighlight>

==== Using Swift ====
<syntaxhighlight lang="swift">
let channelInfo = [
"channelName": "My Channel Name 1",
]

let contentMetadata = [
"type": "content",
"assetid": "88675545",
"title": "Program S3, EP1",
"isfullepisode":"y",
"adloadtype":"2",
"program":"Program Name",
"length":"3600",
"airdate":"20171020 10:05:00"
]

let adMetadata = [
"type": "preroll",
"assetid" : "ad123"
]

</syntaxhighlight>

== Start the Measurement ==

=== Overview of SDK API Calls ===

==== play ====
The play method prepares the SDK for reporting once an asset has loaded and playback has begun. Use play to pass the channel descriptor information through channelName parameter when the user taps the '''Play''' button on the player. Call play only when initially starting the video.
===== Using Objective-C =====
<syntaxhighlight lang="objective-c">[self.nielsenAppApi play:channelInfo];</syntaxhighlight>
===== Using Swift =====
<syntaxhighlight lang="swift">self.nielsenAppApi?.play(channelInfo);</syntaxhighlight>
<br />

==== loadMetadata ====
Needs to be called at the beginning of each asset, pass JSON object for relevant content or ad. Make sure to pass as 1st loadMetadata for content at the begining of playlist - see below API call sequence examples.
===== Using Objective-C =====
<syntaxhighlight lang="objective-c">[self.nielsenAppApi loadMetadata:metadataDict];</syntaxhighlight>
===== Using Swift =====
<syntaxhighlight lang="swift">self.nielsenAppApi?.loadMetadata(metadataDict)</syntaxhighlight>
<br />

==== playheadPosition ====
Pass playhead position every second during playback. for VOD: pass current position in seconds. for Live: current Unix timestamp (seconds since Jan-1-1970 UTC) - if it is possible to seek back in Live content, then pass related Unix time (not current). Pass whole number that increments only by 1 like 1,2,3..
===== Using Objective-C =====
<syntaxhighlight lang="objective-c">
[self.nielsenAppApi playheadPosition:pos];
</syntaxhighlight>
===== Using Swift =====
<syntaxhighlight lang="swift">
self.nielsenAppApi?.playheadPosition(pos);
</syntaxhighlight>
<br />

==== stop ====
Call when
* ads complete playing
* when a user pauses playback
* upon any user interruption scenario - see bellow chapter Interruption scenario
===== Using Objective-C =====
<syntaxhighlight lang="objective-c">[self.nielsenAppApi stop];</syntaxhighlight>
===== Using Swift =====
<syntaxhighlight lang="swift">self.nielsenAppApi?.stop;</syntaxhighlight>
<br />

==== end ====
Call when the content asset completes playback. Stops measurement progress.
===== Using Objective-C =====
<syntaxhighlight lang="objective-c">[self.nielsenAppApi end];</syntaxhighlight>
===== Using Swift =====
<syntaxhighlight lang="swift">self.nielsenAppApi?.end</syntaxhighlight>
<br />

=== API Call Sequence ===
==== Use Case 1: Content has no Ads ====
Call [[play()]] with channelName JSON as below.
<syntaxhighlight lang="json">{
"channelName": "ChannelName"
}</syntaxhighlight>
Call [[loadMetadata()]] with JSON metadata for content as below.
<syntaxhighlight lang="json">{
"type": "content",
"assetid": "vid345-67483",
"program": "ProgramName",
"title": "Program S3, EP1",
"length": "3600",
...
}</syntaxhighlight>
Call [[playheadPosition|playheadPosition()]] every one second until a pause.
Use the sample API sequence below as a reference to identify the specific events that need to be called during content playback without ads.
{| class="wikitable"
|-
! Type !! Sample code !! Description
|-
| rowspan="2" | Start of stream || <code>mAppSdk.play(channelName); </code> || // channelName contains JSON metadata of channel/video name being played
|-
| <code>mAppSdk.loadMetadata(contentMetaDataObject);</code> || // contentMetadataObject contains the JSON metadata for the content being played
|-
| Content || <code>mAppSdk.playheadPosition(playheadPosition);</code> || // position is position of the playhead while the content is being played
|-
| End of Stream || <code>mAppSdk.end();</code> || // Content playback is completed.
|}

==== Use Case 2: Content has Ads ====
Call [[play()]] with channelName JSON as below.
<syntaxhighlight lang="json">{
"channelName": "ChannelName"
}</syntaxhighlight>
Call [[loadMetadata()]] with JSON metadata for ad as below.
<syntaxhighlight lang="json">{
"type": "preroll",
"assetid": "ad_123",
...
}</syntaxhighlight>
<blockquote>Note: In case the individual ad details are not available, send ad pod (presence) details through the [[loadMetadata]] and playhead position through [[playheadPosition]].</blockquote>

Call [[playheadPosition|playheadPosition()]] every one second until a pause / another [[loadMetadata()]] is called. Playhead should be passed for the entire duration of ad pod, if the ad pod details are passed as part of [[loadMetadata()]].

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"
|-
! Type !! Sample code !! Description
|-
| rowspan="2" | Start of stream || <code>mAppSdk.play(channelName); </code> || // channelName contains JSON metadata of channel/video name being played
|-
| <code>mAppSdk.loadMetadata(contentMetaDataObject);</code> || // contentMetadataObject contains the JSON metadata for the content being played
|-
| rowspan="3" | Preroll || <code>mAppSdk.loadMetadata(prerollMetadataObject);</code> || // prerollMetadataObject contains the JSON metadata for the preroll ad
|-
| <code>mAppSdk.playheadPosition(playheadPosition);</code> || // position is position of the playhead while the preroll ad is being played
|-
| <code>mAppSdk.stop();</code> || // Call stop after preroll occurs
|-
| rowspan="2" | Content || <code>mAppSdk.loadMetadata(contentMetaDataObject);</code> || // contentMetadataObject contains the JSON metadata for the content being played
|-
| <code>mAppSdk.setPlayheadPosition(playheadPosition);</code> || // position is position of the playhead while the content is being played
|-
| rowspan="6" | Midroll || <code>mAppSdk.loadMetadata(midrollMetaDataObject);</code> || // midrollMetadataObject contains the JSON metadata for the midroll ad
|-
| <code>mAppSdk.playheadPosition(playheadPosition);</code> || // position is position of the playhead while the midroll ad is being played
|-
| <code>mAppSdk.stop();</code> || // App moves to background(midroll pauses)
|-
| <code>mAppSdk.loadMetadata(midrollMetaDataObject);</code> || // App moves to foreground (midroll resumes)
|-
| <code>mAppSdk.playheadPosition(playheadPosition);</code> || // playheadPosition is position of the playhead while the midroll ad is being played
|-
| <code>mAppSdk.stop();</code> || // Call stop after midroll occurs
|-
| rowspan="2" | Content (End of stream) || <code>mAppSdk.loadMetadata(contentMetaDataObject);</code> || // contentMetadataObject contains the JSON metadata for the content being played
|-
| <code>mAppSdk.playheadPosition(playheadPosition);</code> || // position is position of the playhead while the content is being played
|-
| End of Stream || <code>mAppSdk.end();</code> || // Call end() at the end of content
|-
| rowspan="3" | Postroll || <code>mAppSdk.loadMetadata(postrollMetaDataObject);</code> || // postrollMetadataObject contains the JSON metadata for the postroll ad
|-
| <code>mAppSdk.playheadPosition(playheadPosition);</code> || // position is position of the playhead while the postroll ad is being played
|-
| <code>mAppSdk.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>

== Stop/Resume the Measurement for video Playback Interruptions ==
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 <code>stop</code> immediately (except when content is buffering) and withhold sending playhead position.
* Once the playback resumes, start sending pings <code>playheadPosition</code> for the new viewing session.
Please see the [[Digital Measurement FAQ]] for more details

== Review SDK Integration Architecture Diagram ==

=== For Content Playback ===

[[File:nlsn-sdk-achitecture-diagram-content-v1.png||SDK Integration Architecture Diagram - Content]]

=== For Ad Playback ===
[[File:nlsn-sdk-achitecture-diagram-ad-v1.png||SDK Integration Architecture Diagram - Ad]]

{{iOS_NoID_Privacy_and_Opt-Out}}

{{iOS_Airplay}}
== Test your player by yourself ==
=== Guide ===
1. Connect your PC and test device (tablet or phone) via same router.<br />
2. PC side: run Proxy sw (like Charles) and get local IP<br />
3. Test device: modify Wifi setting to pass through Proxy IP from step 2.<br />
4. Test device: run your player, launch video<br />
5. PC side: filter traffic by "nmrodam" and confirm presence of SDK pings<br />

=== Example of SDK ping (https call) ===
<code><nowiki>https://secure-ksa.nmrodam.com/cgi-bin/gn?prd=dcr&ci=se-910685&ch=se-910685_c01_P&asn=defChnAsset&fp_id=a2nfmy17lyvkhlxqstvmgypqly90m1629966210&fp_cr_tm=1629966210&fp_acc_tm=1629966210&fp_emm_tm=1629966210&ve_id=20A7CFD5-9860-4256-A6CE-45C251F4C243&sessionId=yvx0rtsxydmaxueji8zgfzj0f2f1w1629966209&tl=&prv=1&c6=vc,c01&ca=se-910685_c01_51HERB1501&cg=Play%20%3E%20Webbtv%20%3E%20Nyheter&c13=asid,P3D8D326A-2DBC-486A-8FD8-9AF4452B2A41&c32=segA,NA&c33=segB,NA&c34=segC,NA&c15=apn,Aftonbladet&plugv=&playerv=&sup=1&segment2=&segment1=&forward=0&ad=1&cr=4_00_99_D1_00000&c9=devid,12b9377cbe7e5c94e8a70d9d23929523d14afa954793130f8a3959c7b849aca8&enc=true&c1=nuid,12b9377cbe7e5c94e8a70d9d23929523d14afa954793130f8a3959c7b849aca8&at=timer&rt=video&c16=sdkv,ai.8.1.0&c27=cln,15&crs=&lat=&lon=&c29=plid,16299662096458868&c30=bldv,ai.8.1.0.0_gsxaoni&st=dcr&c7=osgrp,&c8=devgrp,&c10=plt,&c40=adbid,&c14=osver,iOS14.6&c26=dmap,1&dd=&hrd=&wkd=&c35=adrsid,&c36=cref1,&c37=cref2,&c11=agg,1&c12=apv,5.47.83.0.25245&c51=adl,15&c52=noad,1&sd=15&pc=NA&c53=fef,n&c54=oad,&c55=cref3,&c57=adldf,2&ai=51HERB1501&c3=st,a&c64=starttm,1629966240&adid=51HERB1501&c58=isLive,false&c59=sesid,iqal6k21r0de8gm901kif5xznar7q1629966240&c61=createtm,1629966255&c63=pipMode,&ci_userid=&is_auto_play=&pl_title=&is_prem=&is_prog=&ad_origin=&adidx=1%2F1&is_tpad=&ci_passthr=&c62=sendTime,1629966255&c68=bndlid,se.aftonbladet.Aftonbladet&c69=cvw,&nodeTM=&logTM=&c73=phtype,&c74=dvcnm,&c76=adbsnid,&uoo=&c44=progen,&davty=1&si=&c66=mediaurl,&sdd=retry,0~~retryreason,~~devmodel,iPhone9%2C4~~devtypid,iPhone9%2C4~~sysname,iOS~~sysversion,14.6~~manuf,Apple&cat_id=a6f7fb13-8801-484c-9692-6db6dfb470aa&vtoff=0&rnd=1629966255319</nowiki></code>

== Provide your app for certification ==
Once ready please send your application to Nielsen local staff for certification.

== Going Live ==
Following Nielsen testing, you will need to:

# '''Disable Debug Logging''': Disable logging by deleting <code>{nol_devDebug: 'DEBUG'}</code> from initialization call.
# '''Notify Nielsen''': Once you are ready to go live, let us know so we can enable you for reporting. We will not be able to collect or report data prior to receiving notification from you.

DCR Ireland Video iOS SDK

2023-07-20T12:14:01Z

NickParrucci:

{{Breadcrumb|}} {{Breadcrumb|Digital}} {{Breadcrumb|International DCR}} {{CurrentBreadcrumb}}
[[Category:Digital]]
__TOC__

== Overview ==
The Nielsen SDK is one of the multiple framework SDKs that Nielsen provides to enable measuring linear (live) and on-demand TV viewing using TVs, mobile devices, etc.
The App SDK is the framework for mobile application developers to integrate Nielsen Measurement into their media player applications. It supports a variety of Nielsen Measurement Products like Digital Content Ratings (DCR), and [[Digital Ad Ratings]] (DAR). Nielsen SDKs are also equipped to measure static content and can track key life cycle events of an application like:
*Application launch events and how long app was running
{{iOS_SpecialNotes_for_iOS14}}

{{iOS_Prerequisites_and_Implementation_Overview}}

== Setting up your Development Environment ==
Prior to SDK Version 6.2.0.0 the IOS framework has been distributed as a static library packaged into framework bundle format. Apple recommends to use dynamic framework, it has some benefits over static libraries like less executable file size of an app, faster startup time and native support in xCode IDE. Nielsen AppSDK has been transformed into dynamic framework in this release ([[iOS_Static_Framework_Setup|static framework]] is still available).

If migrating from the static library to this new dynamic framework, once implemented, unless your specific application requires, you can remove the following Frameworks that were once required:<code> [AdSupport, JavascriptCore, SystemConfiguration, Security, AVFoundation, libc++] </code>
<br>

The '''Dynamic framework''' is created as a fat framework. It means that it contains slices required for devices (armv7, arm64) as well as slices required for simulators (i386, x86_64). Simulator slices are needed to let clients build and debug their app on the simulators, but they should be removed before sending the app to the AppStore. The example of the shell script that should be added as a Run Script phase in the application can be [[DCR_Video_iOS_SDK#Removing_Simulators_.28Dynamic_Framework_Only.29|found below]].

'''[[DCR_Video_iOS_SDK_xcframework|XCFramework]]''' is solution for the problems described above Apple recommends to use XCFrameworks. In XCFramework, we no longer build a single framework with multiple architectures. Instead, we build one small framework for each combination of architecture and target and store it in its own folder. The top-level XCFramework folder have folders like ios-arm64, ios-arm64-simulator, etc. Each of these folders is its own framework, complete with headers, modules, and binary.

=== Configuring Xcode Development Environment ===
Starting with SDK version 6.0.0.0, the Nielsen App SDK is compatible with Apple iOS versions 8.0 and above. In addition, when using the dynamic framework, all the required frameworks are linked automatically as the are needed. More details can be found here: https://stackoverflow.com/questions/24902787/dont-we-need-to-link-framework-to-xcode-project-anymore

<blockquote>'''Note''': All communications between the SDK and the Census (Collection Facility) use HTTPS.</blockquote>

=== Special Note for Static Framework ===
Starting from 8.2.0.0 release framework is build from the mixed (swift + objc) source code.
If [[iOS_Static_Framework_Setup|static (xc)framework is integrated additional settings]] should be applied to fix build or runtime issues.

=== Download Framework ===
The first step is to download and copy the [[Special:Downloads|NielsenAppApi.framework]] bundle to the app project directory. (''Not required if using CocaPods'')

=== Add Framework ===
In the General tab for app configuration add NielsenAppApi.framework in the list of Embedded Binaries. (''Not required if using CocaPods'')

=== Add Path ===
Add path to the NielsenAppApi.framework in the Framework Search Paths build setting. (''Not required if using CocaPods'')

=== Import Framework ===
Add NielsenAppApi.framework module in the source file of your app:

==== Using Swift ====
Add the following:
<syntaxhighlight lang="swift">
import NielsenAppApi
</syntaxhighlight>

==== Using Objective-C ====
<syntaxhighlight lang ="objective-c">
@import NielsenAppApi;
</syntaxhighlight>

==== xCode 12 building errors ====
Developers who uses "fat" framework in their apps started reporting the following error that they get building the app in xCode 12.3+:
<blockquote>Building for iOS Simulator, but the linked and embedded framework 'MyFramework.framework' was built for iOS + iOS Simulator.</blockquote>
The binary framework contains different code for the same architecture in multiple places, and Xcode doesn’t know how to handle it. There is workaround that people recommend to use in such cases:
* https://stackoverflow.com/questions/63267897/building-for-ios-simulator-but-the-linked-framework-framework-was-built
* https://stackoverflow.com/questions/63932158/xcode12-issus-ld-building-for-ios-simulator-but-linking-in-object-file-built

==== IPA processing failure ====
<code>Assertion failed: Expected 4 archs in otool output:</code>

The error above is due to the "fat" (simulator+device) framework which will not appear if you have not enabled Bitcode. To build your app with full Bitcode support, it is recommended that you use a [[DCR_Video_iOS_SDK_xcframework|XCFramework]] to avoid the 4 archs in otool output message.

== Create SDK Instance ==
The latest version of the Nielsen App SDK allows instantiating multiple instances of the SDK object when needed, which can then be used simultaneously. '''For the general use case where only one video is played at the same time in the App, a single instance of SDK object can then be used to play back and measure all watched streams one after another.'''

The following table contains the list of arguments that can be passed via the AppInfo JSON schema.
{| class="wikitable"
|-
! Parameter / Argument !! Description !! Source !! Required/Obligatory? !! Example
|-
| appid || Unique id for the application assigned by Nielsen. It is GUID data type.|| Nielsen-specified || Yes || "PXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX"
|-
| appname || Name of the application || Client-defined || Yes || "Nielsen Sample App"
|-
| appversion || Current version of the app used || Client-defined || Yes || "1.0.2"
|-
| sfcode || Nielsen collection facility to which the SDK should connect.
|| Nielsen-specified || Yes || "ire"
|-
| nol_devDebug || Enables Nielsen console logging. Only required for testing
|| Nielsen-specified || Optional || "DEBUG"

|}
<br />

== Debug flag for development environment ==
Player application developers / integrators can use Debug flag to check whether an App SDK API call made is successful. To activate the Debug flag,
Pass the argument <code>@"nol_devDebug":@"DEBUG"</code>, in the JSON string.

* '''DEBUG''': Debug logs, used by the developers to debug more complex issues.

Once the flag is active, it logs each API call made and the data passed. The log created by this flag is minimal.
<blockquote>'''Note''': DO NOT activate the Debug flag in a production environment.</blockquote>

==== Sample SDK Initialization Code ====

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>

===== Using Objective-C=====
<syntaxhighlight lang="objective-c">
#import "NlsAppApiFactory.h"
#import <NielsenAppApi/NielsenAppApi.h>

@implementation NlsAppApiFactory

+ (NielsenAppApi *)createNielsenAppApiWithDelegate:(id<NielsenAppApiDelegate>)delegate;
{
NSDictionary *appInformation = @{
@"appid": "PXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX",
@"appversion": "1.0",
@"appname": "app name here",
@"sfcode": "ire",
@"nol_devDebug": @"DEBUG"
};
return [[NielsenAppApi alloc] initWithAppInfo:appInformation delegate:delegate];
}
@end
</syntaxhighlight>

The following would be the <code>NlsAppApiFactory.h</code> file:
<syntaxhighlight lang="objective-c">
#import <Foundation/Foundation.h>

@class NielsenAppApi;
@protocol NielsenAppApiDeligate;

@interface NlsAppApiFactory : NSObject

+ (NielsenAppAPI *) createNielsenAppApiWithDelegate:(id<NielsenAppApiDelegate>)delegate;

@end
</syntaxhighlight>

===== Using Swift =====

<code>NielsenInit.swift</code>
<syntaxhighlight lang="swift">
class NielsenInit: NSObject {
class func createNielsenAppApi(delegate: NielsenAppApiDelegate) -> NielsenAppApi?{
let appInformation:[String: String] = [
"appid": "PXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX",
"appversion": "1.0",
"appname": "app name here",
"sfcode": "ire",
"nol_devDebug": "DEBUG"
]
return NielsenAppApi(appInfo:appInformation, delegate:delegate)
}
}
</syntaxhighlight>

Sample code using AVPlayer.
<br />
<code>ViewController.swift</code>

<syntaxhighlight lang="swift">
class ViewController: UIViewController, NielsenAppApiDelegate, AVPictureInPictureControllerDelegate, CLLocationManagerDelegate {

let avPlayerViewController = AVPlayerViewController()
var avPlayer:AVPlayer?
var nielsenAppApi: NielsenAppApi!

override func viewDidLoad() {
super.viewDidLoad()

self.nielsenAppApi = NielsenInit.createNielsenAppApi(delegate: self)
NSLog("Nielsen SDK initialized")

}
}
</syntaxhighlight>

==== APP SDK Error & Event Codes ====
To view the Error and Event codes for iOS and Android, please review the [[APP SDK Event Codes|App SDK Event Code]] Reference page.

==== Life cycle of SDK instance ====
The 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. Once Initialized, 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. API calls "play" and "loadMetadata" move the SDK instance into this state. In this state, the SDK instance will be able to process the API calls (see below)
# '''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
## <code>appDisableApi</code> is called

<syntaxhighlight lang="objective-c">
@property (assign) BOOL appDisableApi;
</syntaxhighlight>

== Create Metadata Objects ==
The parameters passed must be either a JSON formatted NSString 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, 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.<br />

=== Create channelName Metadata ===
channelName should remain constant throughout the completion of an episode or live stream.
<br />
{| class="wikitable"
|-
! Key !! Description !! Values !! Required
|-
| channelName || Any string representing the channel/stream || custom || Yes
|-
|}

===Create Content Metadata ===
Content metadata should remain constant throughout the entirety of an episode/clip including when ads play.
{| class="wikitable"
|-
! Keys !! Description !! Values !! Required
|-
| type || type of asset || <code>'content'</code> || Yes
|-
| assetid || unique ID assigned to asset (32 Character limit) || custom (no [[Special Characters|Special Characters]]) || Yes
|-
| program || name of program (100 character limit) || custom || Yes
|-
| title || name of program (100 character limit) || custom || Yes
|-
| length || length of content in seconds || Length of content in seconds (86400 seconds for live stream (24/7). For Event-Live streams planned length. For VoD video length) || Yes
|-
| airdate || the airdate in the linear TV || YYYYMMDD HH24:MI:SS || Yes
|-
| isfullepisode || full episode flag || <code>'y'</code>- full episode, <code>'n'</code>- non full episode || Yes
|-
| adloadtype || type of ad load:
*<code>'1'</code> Linear – matches TV ad load
*<code>'2'</code> Dynamic – Dynamic Ad Insertion (DAI)
|| <code>'2'</code> - DCR measures content with dynamic ads
|| Yes
|-
| segB || custom segment for the clients granular reporting within a brand
|| Example: ChannelName
|| Optional
|-
| segC || custom segment for the clients granular reporting within a brand
|| Example: PlayerName
|| Optional
|}

===Create Ad Metadata ===
The Ad Metadata (if applicable) should be passed for each individual ad.
{| class="wikitable"
|-
! Keys !! Description !! Values !! Required
|-
| type || type of Ad || <code>'preroll'</code>, <code>'midroll'</code>, <code>'postroll'</code> || Yes
|-
| assetid || unique ID assigned to Ad || custom (no [[Special Characters|Special Characters]]) || Yes
|}

'''Note:''' All metadata values should be passed as UTF-8 strings.

<blockquote> URL Character Limit: There is a URL character limit of 2K characters due to browser limitations. Exceeding this value could impair data delivery on particular browsers. </blockquote>

=== MetaData Example ===

==== Using Objective-C ====
<syntaxhighlight lang="objective-c">
NSDictionary *channelInfo = @
{
@"channelName":@"My Channel Name 1",
}

NSDictionary *contentMetadata = @
{
@ "type": @ "content",
@ "assetid": @ "88675545",
@ "title": @ "Program S3, EP1",
@ "isfullepisode": @ "y",
@ "program": @ "Program Name",
@ "length": @ "3600",
@ "airdate": @ "20200321 10:05:00",
@ "adloadtype": @ "2"
@ "segB": @ "ChannelName", //optional
@ "segC": @ "PlayerName" //optional
}

NSDictionary *adMetadata = @
{
@"type" : "postroll",
@"assetid" : "AD-ID123"
}
</syntaxhighlight>

==== Using Swift ====
<syntaxhighlight lang="swift">
let channelInfo = [
"channelName": "My Channel Name 1",
]

let contentMetadata = [
"type": "content",
"assetid": "88675545",
"title": "Program S3, EP1",
"isfullepisode":"y",
"adloadtype":"2",
"program":"Program Name",
"length":"3600",
"airdate":"20171020 10:05:00"
"segB": "ChannelName", //optional
"segC": "PlayerName" //optional
]

let adMetadata = [
"type": "preroll",
"assetid" : "ad123"
]

</syntaxhighlight>

== Start the Measurement ==

=== Overview of SDK API Calls ===

==== play ====
The play method prepares the SDK for reporting once an asset has loaded and playback has begun. Use play to pass the channel descriptor information through channelName parameter when the user taps the '''Play''' button on the player. Call play only when initially starting the video.
===== Using Objective-C =====
<syntaxhighlight lang="objective-c">[self.nielsenAppApi play:channelInfo];</syntaxhighlight>
===== Using Swift =====
<syntaxhighlight lang="swift">self.nielsenAppApi?.play(channelInfo);</syntaxhighlight>
<br />

==== loadMetadata ====
Needs to be called at the beginning of each asset, pass JSON object for relevant content or ad. Make sure to pass as 1st loadMetadata for content at the begining of playlist - see below API call sequence examples.
===== Using Objective-C =====
<syntaxhighlight lang="objective-c">[self.nielsenAppApi loadMetadata:metadataDict];</syntaxhighlight>
===== Using Swift =====
<syntaxhighlight lang="swift">self.nielsenAppApi?.loadMetadata(metadataDict)</syntaxhighlight>
<br />

==== playheadPosition ====
Pass playhead position every second during playback. for VOD: pass current position in seconds. for Live: current Unix timestamp (seconds since Jan-1-1970 UTC) - if it is possible to seek back in Live content, then pass related Unix time (not current). Pass whole number that increments only by 1 like 1,2,3..
===== Using Objective-C =====
<syntaxhighlight lang="objective-c">
[self.nielsenAppApi playheadPosition:pos];
</syntaxhighlight>
===== Using Swift =====
<syntaxhighlight lang="swift">
self.nielsenAppApi?.playheadPosition(pos);
</syntaxhighlight>
<br />

==== stop ====
Call when
* ads complete playing
* when a user pauses playback
* upon any user interruption scenario - see bellow chapter Interruption scenario
===== Using Objective-C =====
<syntaxhighlight lang="objective-c">[self.nielsenAppApi stop];</syntaxhighlight>
===== Using Swift =====
<syntaxhighlight lang="swift">self.nielsenAppApi?.stop;</syntaxhighlight>
<br />

==== end ====
Call when the content asset completes playback. Stops measurement progress.
===== Using Objective-C =====
<syntaxhighlight lang="objective-c">[self.nielsenAppApi end];</syntaxhighlight>
===== Using Swift =====
<syntaxhighlight lang="swift">self.nielsenAppApi?.end</syntaxhighlight>
<br />

=== API Call Sequence ===
==== Use Case 1: Content has no Ads ====
Call [[play()]] with channelName JSON as below.
<syntaxhighlight lang="json">{
"channelName": "ChannelName"
}</syntaxhighlight>
Call [[loadMetadata()]] with JSON metadata for content as below.
<syntaxhighlight lang="json">{
"type": "content",
"assetid": "vid345-67483",
"program": "ProgramName",
"title": "Program S3, EP1",
"length": "3600",
...
}</syntaxhighlight>
Call [[playheadPosition|playheadPosition()]] every one second until a pause.
Use the sample API sequence below as a reference to identify the specific events that need to be called during content playback without ads.
{| class="wikitable"
|-
! Type !! Sample code !! Description
|-
| rowspan="2" | Start of stream || <code>mAppSdk.play(channelName); </code> || // channelName contains JSON metadata of channel/video name being played
|-
| <code>mAppSdk.loadMetadata(contentMetaDataObject);</code> || // contentMetadataObject contains the JSON metadata for the content being played
|-
| Content || <code>mAppSdk.playheadPosition(playheadPosition);</code> || // position is position of the playhead while the content is being played
|-
| End of Stream || <code>mAppSdk.end();</code> || // Content playback is completed.
|}

==== Use Case 2: Content has Ads ====
Call [[play()]] with channelName JSON as below.
<syntaxhighlight lang="json">{
"channelName": "ChannelName"
}</syntaxhighlight>
Call [[loadMetadata()]] with JSON metadata for ad as below.
<syntaxhighlight lang="json">{
"type": "preroll",
"assetid": "ad_123",
...
}</syntaxhighlight>
<blockquote>Note: In case the individual ad details are not available, send ad pod (presence) details through the [[loadMetadata]] and playhead position through [[playheadPosition]].</blockquote>

Call [[playheadPosition|playheadPosition()]] every one second until a pause / another [[loadMetadata()]] is called. Playhead should be passed for the entire duration of ad pod, if the ad pod details are passed as part of [[loadMetadata()]].

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"
|-
! Type !! Sample code !! Description
|-
| rowspan="2" | Start of stream || <code>mAppSdk.play(channelName); </code> || // channelName contains JSON metadata of channel/video name being played
|-
| <code>mAppSdk.loadMetadata(contentMetaDataObject);</code> || // contentMetadataObject contains the JSON metadata for the content being played
|-
| rowspan="3" | Preroll || <code>mAppSdk.loadMetadata(prerollMetadataObject);</code> || // prerollMetadataObject contains the JSON metadata for the preroll ad
|-
| <code>mAppSdk.playheadPosition(playheadPosition);</code> || // position is position of the playhead while the preroll ad is being played
|-
| <code>mAppSdk.stop();</code> || // Call stop after preroll occurs
|-
| rowspan="2" | Content || <code>mAppSdk.loadMetadata(contentMetaDataObject);</code> || // contentMetadataObject contains the JSON metadata for the content being played
|-
| <code>mAppSdk.setPlayheadPosition(playheadPosition);</code> || // position is position of the playhead while the content is being played
|-
| rowspan="6" | Midroll || <code>mAppSdk.loadMetadata(midrollMetaDataObject);</code> || // midrollMetadataObject contains the JSON metadata for the midroll ad
|-
| <code>mAppSdk.playheadPosition(playheadPosition);</code> || // position is position of the playhead while the midroll ad is being played
|-
| <code>mAppSdk.stop();</code> || // App moves to background(midroll pauses)
|-
| <code>mAppSdk.loadMetadata(midrollMetaDataObject);</code> || // App moves to foreground (midroll resumes)
|-
| <code>mAppSdk.playheadPosition(playheadPosition);</code> || // playheadPosition is position of the playhead while the midroll ad is being played
|-
| <code>mAppSdk.stop();</code> || // Call stop after midroll occurs
|-
| rowspan="2" | Content (End of stream) || <code>mAppSdk.loadMetadata(contentMetaDataObject);</code> || // contentMetadataObject contains the JSON metadata for the content being played
|-
| <code>mAppSdk.playheadPosition(playheadPosition);</code> || // position is position of the playhead while the content is being played
|-
| End of Stream || <code>mAppSdk.end();</code> || // Call end() at the end of content
|-
| rowspan="3" | Postroll || <code>mAppSdk.loadMetadata(postrollMetaDataObject);</code> || // postrollMetadataObject contains the JSON metadata for the postroll ad
|-
| <code>mAppSdk.playheadPosition(playheadPosition);</code> || // position is position of the playhead while the postroll ad is being played
|-
| <code>mAppSdk.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>

== Stop/Resume the Measurement for video Playback Interruptions ==
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 <code>stop</code> immediately (except when content is buffering) and withhold sending playhead position.
* Once the playback resumes, start sending pings <code>playheadPosition</code> for the new viewing session.
Please see the [[Digital Measurement FAQ]] for more details

== Review SDK Integration Architecture Diagram ==

=== For Content Playback ===

[[File:nlsn-sdk-achitecture-diagram-content-v1.png||SDK Integration Architecture Diagram - Content]]

=== For Ad Playback ===
[[File:nlsn-sdk-achitecture-diagram-ad-v1.png||SDK Integration Architecture Diagram - Ad]]

{{iOS_NoID_Privacy_and_Opt-Out}}

{{iOS_Airplay}}
== Test your player by yourself ==
=== Guide ===
1. Connect your PC and test device (tablet or phone) via same router.<br />
2. PC side: run Proxy sw (like Charles) and get local IP<br />
3. Test device: modify Wifi setting to pass through Proxy IP from step 2.<br />
4. Test device: run your player, launch video<br />
5. PC side: filter traffic by "nmrodam" and confirm presence of SDK pings<br />

=== Example of SDK ping (https call) ===
<code><nowiki>https://secure-ire.nmrodam.com/cgi-bin/gn?prd=dcr&ci=se-910685&ch=se-910685_c01_P&asn=defChnAsset&fp_id=a2nfmy17lyvkhlxqstvmgypqly90m1629966210&fp_cr_tm=1629966210&fp_acc_tm=1629966210&fp_emm_tm=1629966210&ve_id=20A7CFD5-9860-4256-A6CE-45C251F4C243&sessionId=yvx0rtsxydmaxueji8zgfzj0f2f1w1629966209&tl=&prv=1&c6=vc,c01&ca=se-910685_c01_51HERB1501&cg=Play%20%3E%20Webbtv%20%3E%20Nyheter&c13=asid,P3D8D326A-2DBC-486A-8FD8-9AF4452B2A41&c32=segA,NA&c33=segB,NA&c34=segC,NA&c15=apn,Aftonbladet&plugv=&playerv=&sup=1&segment2=&segment1=&forward=0&ad=1&cr=4_00_99_D1_00000&c9=devid,12b9377cbe7e5c94e8a70d9d23929523d14afa954793130f8a3959c7b849aca8&enc=true&c1=nuid,12b9377cbe7e5c94e8a70d9d23929523d14afa954793130f8a3959c7b849aca8&at=timer&rt=video&c16=sdkv,ai.8.1.0&c27=cln,15&crs=&lat=&lon=&c29=plid,16299662096458868&c30=bldv,ai.8.1.0.0_gsxaoni&st=dcr&c7=osgrp,&c8=devgrp,&c10=plt,&c40=adbid,&c14=osver,iOS14.6&c26=dmap,1&dd=&hrd=&wkd=&c35=adrsid,&c36=cref1,&c37=cref2,&c11=agg,1&c12=apv,5.47.83.0.25245&c51=adl,15&c52=noad,1&sd=15&pc=NA&c53=fef,n&c54=oad,&c55=cref3,&c57=adldf,2&ai=51HERB1501&c3=st,a&c64=starttm,1629966240&adid=51HERB1501&c58=isLive,false&c59=sesid,iqal6k21r0de8gm901kif5xznar7q1629966240&c61=createtm,1629966255&c63=pipMode,&ci_userid=&is_auto_play=&pl_title=&is_prem=&is_prog=&ad_origin=&adidx=1%2F1&is_tpad=&ci_passthr=&c62=sendTime,1629966255&c68=bndlid,se.aftonbladet.Aftonbladet&c69=cvw,&nodeTM=&logTM=&c73=phtype,&c74=dvcnm,&c76=adbsnid,&uoo=&c44=progen,&davty=1&si=&c66=mediaurl,&sdd=retry,0~~retryreason,~~devmodel,iPhone9%2C4~~devtypid,iPhone9%2C4~~sysname,iOS~~sysversion,14.6~~manuf,Apple&cat_id=a6f7fb13-8801-484c-9692-6db6dfb470aa&vtoff=0&rnd=1629966255319</nowiki></code>

== Provide your app for certification ==
Once ready please send your application to Nielsen local staff for certification.

== Going Live ==
Following Nielsen testing, you will need to:

# '''Disable Debug Logging''': Disable logging by deleting <code>{nol_devDebug: 'DEBUG'}</code> from initialization call.
# '''Notify Nielsen''': Once you are ready to go live, let us know so we can enable you for reporting. We will not be able to collect or report data prior to receiving notification from you.

DCR Video iOS SDK

2023-06-21T18:53:39Z

NickParrucci:

Template:Android SDK Initialization

2023-06-09T19:40:02Z

NickParrucci:

== SDK Initialization ==
The latest version of the Nielsen App SDK allows instantiating multiple instances of the SDK object, which can be used simultaneously without any issue. The sharedInstance API that creates a singleton object was deprecated prior to version 5.1.1. (Version 4.0 for Android)

The following table contains the list of arguments that can be passed via the AppInfo JSON schema.
{| class="wikitable"
|-
! Parameter / Argument !! Description !! Source !! Required? !! Example
|-
| appid || Unique Nielsen ID for the application. The ID is a GUID data type. If you did not receive your App ID, let us know and we will provide you. || Nielsen-specified || Yes || PXXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX
|-
| nol_devDebug || Enables Nielsen console logging. Only required for testing
|| Nielsen-specified || Optional || "DEBUG"
|}
== Debug flag for development environment ==
Player application developers / integrators can use Debug flag to check whether an App SDK API call made is successful. To activate the Debug flag,
Pass the argument <code>@"nol_devDebug":@"INFO"</code>, in the JSON string . The permitted values are:

* '''INFO''': Displays the API calls and the input data from the application (validate player name, app ID, etc.). It can be used as certification Aid.
* '''WARN''': Indicates potential integration / configuration errors or SDK issues.
* '''ERROR''': Indicates important integration errors or non-recoverable SDK issues.
* '''DEBUG''': Debug logs, used by the developers to debug more complex issues.

Once the flag is active, it logs each API call made and the data passed. The log created by this flag is minimal.
<blockquote>'''Note''': DO NOT activate the Debug flag in a production environment.</blockquote>

==== Sample SDK Initialization Code ====
[[AppSDK()]] is no longer a singleton object and should be initialized as below.

'''Initialization of App SDK object through a JSON object'''
<syntaxhighlight lang="java">try
{
// Prepare AppSdk configuration object (JSONObject)
JSONObject appSdkConfig = new JSONObject()
.put("appid", "PDA7D5EE6-B1B8-XXXX-XXXX-2A788BCXXXCA")
.put("nol_devDebug", "DEBUG"); // only for debug builds

// Pass appSdkConfig to the AppSdk constructor
mAppSdk = new AppSdk(appContext, appSdkConfig, appSdkListener);
}
catch (JSONException e)
{
Log.e(TAG, "Couldn’t prepare JSONObject for appSdkConfig", e);
}
</syntaxhighlight>
Here, <code>appContext</code> is the App context object and <code>appSdkConfig</code> is JSON object for holding the parameters (<code>appid</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.

The integration of Nielsen App SDK will depend on type of client app.<br />
* 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).

== Initializing Viewability and Audibility Measurement ==
If your Nielsen integration will be enabled for viewability/audibility measurement, your app should call trackViewability after initializing the SDK (previous paragraphs).

Viewability metrics allow AppSDK to track the visibility of the player and collect information about how much of the player container is visible to the end user during playback. Audibility metrics report on the device volume level.

The viewability pings will be fired following the same rules as measurement pings. Viewability pings will be POST requests, not GET requests like other data pings. POST body for viewability requests will contain the key-value pairs in JSON format. The key parameters in the URL schemes are '''invs, inau, inss, invp''' and '''ines''' which will contain the collected viewability data. This data will be formatted according to the specific rules so that downstream it will be possible to match measurement and viewability data for a session.

Audibility metrics will capture the volume level as well as mute/unmute state of the device during playback.

== Calling trackViewability for player view ==

== Input Parameters ==
{| class="wikitable"
|-
! Parameter !! Description
|-
| data || JSONObject object with the following objects and keys:
{| class="wikitable"
|-
| viewTag (mandatory) || value of String type, tag identifier for the target player view object. This tag can be assigned for the player view either programmatically or in the layout xml, as explained in above section.
|-
| viewContainer (mandatory) || Reference to the activity object. It is needed to identify and search the target player view in current visible screen. This parameter can not be nil. This should be the current activity object where target view is loaded. If the player view is rendered in a fragment, please provide the parent activity reference of the fragment.
|-
| friendlyObstructions (optional) || an array of tags of the views which should be ignored during the intersection ratio calculation. Those are views like loading activity indicator, player controls, view with a watermark, etc. which are displayed in front of the target view, but should not reduce the viewability intersection ratio. The tags of such should be wrapped into the String objects before adding into the array. This parameter is nullable, empty array is also accepted.
|}
|}

== Syntax ==
<br/>
<syntaxhighlight lang="java">
void trackViewability(JSONObject);
</syntaxhighlight>

== Usage Example ==
<syntaxhighlight lang="objective-c">
String targetViewTag = targetView.getTag().toString();
String activityObj = MainActivity.this;
JSONArray friendlyTags = new JSONArray();
friendlyTags.put("friendlyViewTag1");
friendlyTags.put("friendlyViewTag2");

JSONObject json = new JSONObject();
json.put("viewContainer", activityObj);
json.put("viewTag", targetViewTag);
json.put("friendlyObstructions", friendlyTags);
sdkInstance.trackViewability(json);
</syntaxhighlight>
<br>
[[File:PlayerScreen_ViewContainer-ViewTag-FriendlyViews.png|300px]]<br>

== Setting tag for a player view in layout xml ==
<br>
<syntaxhighlight lang="objective-c">
<SurfaceView
android:id="@+id/playerView"
android:tag="playerViewTag"
android:layout_width="match_parent"
android:layout_height="match_parent"
/>
</syntaxhighlight>

== Setting tag for a player view in Activity/Fragment ==
<br>
<syntaxhighlight lang="objective-c">
mPlayerView = (SurfaceView) findViewById(R.id.playerView);
mPlayerView.setTag("playerViewTag");
</syntaxhighlight>

=== Data Collected ===
{| class="wikitable"
|-
! Parameter !! Description
|-
| Measured Value || Value is different for different request parameters:
{| class="wikitable"
|-
| '''invs''' || Intersection ratio for the target view in percent (from 0 to 100). Default threshold for this value is 5. Example: ['''50''',1,1528457356,10]
|-
| '''inau''' || Volume level on the device in percent (from 0 to 100), where 0 - mute, 100 - max volume level. Default threshold for this value is 1. Example: ['''30''',1,1528457356,10]
|-
| '''inss''' || Device screen size as "WxH", where W - is width in pixels, H - is height in pixels. Example: ['''"1024x768"''',1,1528457356,10]
|-
| '''invp''' || Current window size. This is different than the device screen size in a multiple scene mode or on a desktop. Format is "WxH", where W - is width in pixels, H - is height in pixels. Example: ['''"800x600"''',1,1528457356,10]
|-
| '''ines''' || Player view size as "WxH", where W - is width in pixels, H - is height in pixels. Example: ['''"300x200"''',1,1528457356,10]
|}
|-
| Start offset || Value contains the first playhead or the first id3 offset with non-null CID after start, flush or resume. Example playhead: [50,'''1''',1528457356,10]. Example id3 offset: [50,'''70100''',1528457356,10]
|-
| Start timestamp || Timestamp value when the time period related to this time series item was started. Example: [50,1,'''1528457356''',10]
|-
| Duration || Duration value is calculated as a difference between the last playhead and the first playhead for the current time series item. Example: [50,1,1528457356,'''10''']
|}

DTVR Android SDK

2023-06-09T19:19:11Z

NickParrucci:

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

== Overview ==
The Nielsen SDK is one of multiple framework SDKs that Nielsen provides to enable measuring linear (live) and on-demand TV viewing using TVs, mobile devices, etc.
The App SDK is the framework for mobile application developers to integrate Nielsen Measurement into their media player applications. It supports a variety of Nielsen Measurement Products like Digital in TV Ratings, Digital Content Ratings ([[DCR & DTVR]]), and [[Digital Ad Ratings]] (DAR). Nielsen SDKs are also equipped to measure static content and can track key life cycle events of an application like:
*Application launch events and how long app was running
*Time of viewing a sub section / page in the application.

If the content being played contains ID3 tags, when played on a mobile device or within a browser, these tags can be sent to Nielsen for collection/processing via the Nielsen SDK.
<blockquote>
VOD in TV Ratings (formally knows as Recently Telecast VOD) support is now available; however, you must notify us to ensure accurate reporting.
</blockquote>

== Prerequisites ==
Before you start the integration, you will need:
{| class="wikitable"
|-
! style="width: 15%;" | Item
! Description
! Source
|-style="background-color:#d0f6f8;"
|| '''App ID (appid)''' || Unique ID assigned to the player/site and configured by product. || Provided by Nielsen
|-style="background-color:#d0f6f8;"
|| '''Nielsen SDK''' || Includes SDK frameworks and '''sample implementation'''; ''See [[Android SDK Release Notes]]'' || [[Special:Downloads|Download]]
|}

If need App ID(s) or our SDKs, feel free to reach out to us and we will be happy to help you get started.
Refer to [[Digital Measurement Onboarding]] guide for information on how to get a Nielsen App SDK and appid.

{{Android_Implementation}}
__TOC__

{{Android_Setting_Up_Development_Envrionment}}

{{Android_SDK_Initialization}}

== APP SDK Error & Event Codes ==
To view the Error and Event codes for iOS and Android, please review the [[APP SDK Event Codes|App SDK Event Code]] Reference page.

== Content Metadata and SDK Events ==
=== Content Metadata ===
Content metadata should remain constant throughout the completion of an episode or live stream.
{| class="wikitable"
|-
! Key !! Description !! Values !! Required
|-
| type || type of asset || "content" ||
|-
| adModel || linear vs dynamic ad model || 1 = Linear matches TV ad load || ✓
|-
|}


------------------------
<syntaxhighlight lang="java">
public JSONObject loadDtvr() {
try {
dtvr = new JSONObject()
.put( "type","content")
.put("adModel", "1");
}
return dtvr;
}
</syntaxhighlight>

=== SDK Events ===
{| class="wikitable"
|-
! Event !! Parameter !! Description
|-
| 'loadMetadata' || content/ad metadata object || Needs to be called at the beginning of each asset to pass type and adModel.
|-
|'play'||||Call when starting or resuming a streaming session. '''Note:''' Not required starting at SDK version 7.2.0 or higher.
|-
| 'sendID3' || Used to send the ID3 tag payload retrieved from the stream || Needs to be called at the beginning of playback
||
|-
| 'stop' || playhead position || Call when content or ads complete playing and pass playhead position
'''Note:'''no longer required for SDK version 7.2 or higher.
|}

=== Configure API calls - play ===
Call play at start of new stream:
<syntaxhighlight lang="java"> appSdk.play();</syntaxhighlight>

'''Note:''' no longer required for SDK version 7.2 or higher.

=== Configure API calls - loadMetadata ===
Use <code>loadMetadata</code> to pass ‘content’ and ‘ad’ <code>Digital Measurement Metadata</code>. The CMS data must be passed as a JSON object.
<syntaxhighlight lang="java"> appSdk.loadMetadata(data);</syntaxhighlight>

=== Configure API calls - sendID3 ===
[[sendID3]] API is a receiver for timed metadata events (ID3 tags. This API filters out Nielsen-specific ID3 tags from the system and buffers the data for transfer to Nielsen’s collection facility.
<syntaxhighlight lang="java"> //Sending ID3 tag to SDK.
appSdk.sendID3(id3String);</syntaxhighlight>
'''Sample ID3 tags'''
* <code>www.nielsen.com/X100zdCIGeIlgZnkYj6UvQ==/X100zdCIGeIlgZnkYj6UvQ==/AAAB2Jz2_k74GXSzx4npHuI_<wbr />JwJd3QSUpW30rDkGTcbHEzIMWleCzM-uvNOP9fzJcQMWQLJqzXMCAxParOb5sGijSV9dNM3QiBniJYGZ5GI-lL1fXTTN0IgZ4iWBmeRiPpS9AAAAAAAAAAAAAAAAAAAAAFJWFM5SVhTONNU=/00000/00000/00</code>
* <code>www.nielsen.com/X100zdCIGeIlgZnkYj6UvQ==/R8WHe7pEBeqBhu8jTeXydg==/AAICoyitYqlxT7n6aZ0oMCGhe<wbr />Fi4CXFp46AMUPZz1lMr_M9tr3_cjee1SHqxrOiVerMDLeyn9xzocZSKwi746Re8vNOtpNCAZjYABs_J0R25IHpvOc1HS8<wbr />QHGgD5TgOJeS6gX100zdCIGeIlgZnkYj6UvVJWFNhSVhTiPE0=/00000/46016/00</code>
Refer to [[Android SDK API Reference#Retrieving ID3 Tags|Retrieving ID3 Tags]] section to know more details.

===Configure API calls - stop ===
Call <code>stop</code> in case of interruptions during playback like flight mode, Wi-Fi toggle, etc.
<syntaxhighlight lang="java">[nielsenApi stop];</syntaxhighlight>

'''Note:''' no longer required for SDK version 7.2 or higher.

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

=== Examples of extracting ID3 tags fromAndroid 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 mediaPlayer, TimedMetaData timedMetaData) {

if(timedMetaData != null && timedMetaData.getMetaData() != null && mMediaPlayer.isPlaying()){

//getting metadata.
String iD3Payload = new String(timedMetaData.getMetaData(), StandardCharsets.UTF_8);

//If tag metadata contains "www.nielsen.com", then only sending to SDK
if (null != iD3Payload && iD3Payload.contains("www.nielsen.com"))
{
//getting index
int index = iD3Payload.indexOf("www.nielsen.com");

//getting substring as ID3 tag will be of 249 characters
String id3String = iD3Payload.substring(index, (index + 249));
Log.d(TAG, "TimedMetaData ID3 Tag:" + id3String);

//Sending ID3 tag to SDK.
appSdk.sendID3(id3String);
}
}
}
}</syntaxhighlight>

== Life cycle of SDK instance ==
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. Once Initialized, 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. The <code>'''play'''</code> call moves the SDK instance into this state. In this state, the SDK instance will be able to process the following calls.
## <code>'''stop'''</code> – Call this API when the playback is paused, switches between content and ad (within the same content playback) or encounters interruptions.
## <code>'''end'''</code> – 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
## <code>'''appDisableApi'''</code> is set to <code>true</code> ''(This is testing purposes only. Not for User Opt-Out.)''

<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 </code>stop</code> to stop the measurement.

== Handling Foreground and Background states ==
Foreground/Background state measurement is a requirement of Nielsen AppSDK implementation which is especially crucial for static measurement. It may be implemented in multiple ways for Android. This includes
* Enable the Nielsen SDK to measure background/foreground state by makingthe relevant update to the AndroidManifest.
* Integrate Nielsen’s SdkBgFgDetectionUtility class within your Custom Application Class.
* Custom implementation of the required methods within your application.

=== ForeGround/Background Measurement via AndroidManifest ===
The simplest way to measure the app background/foreground state is to add the following application tag to the Manifest XML. Integrating this into the Manifest XML will enable the SDK to measure app state directly. This approach is supported for Android 4.0 and up only; it requires that the application class is not in use for some other purpose.
<syntaxhighlight lang="java">
<application android:name="com.nielsen.app.sdk.AppSdkApplication">
</syntaxhighlight>

=== Using the Android SdkBgFbDetectionUtility Class ===
For developers who are already using the application class, it is recommended that background/foreground state is implemented using the [https://engineeringportal.nielsen.com/docs/Android_Background_Foreground SdkBgFgDetectionUtility class]. The [https://engineeringportal.nielsen.com/docs/Android_Background_Foreground SdkBgFgDetectionUtility class] is compatible with Android 4+ and has been made available to Nielsen clients.

=== Manual Background/ForeGround State Management ===
In cases where the developer is not able to use the AndroidManifest.xml solution nor the Nielsen provided [https://engineeringportal.nielsen.com/docs/Android_Background_Foreground SdkBgFgDetectionUtility class] the developer will need to manually identify the change of state through the application and call the respective API (appInForeground() or appInBackground()) to inform the SDK regarding the change of state from background to foreground or foreground to background.

The SDK is informed about app state using the below methods.
<syntaxhighlight lang="java">
AppLaunchMeasurementManager.appInForeground(getApplicationContext());
AppLaunchMeasurementManager.appInBackground(getApplicationContext());
</syntaxhighlight>
Within the lifecycle of individual activities, onResume() and onPause() are best suited to providing indication of the app state.

Correct measurement of the foreground/background state is crucial to Static App measurement within Nielsen Digital Content Ratings (DCR).

== Interruptions during playback ==
As part of integrating Nielsen App SDK with the player application, the 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.

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

{{Template:Android_Privacy_and_Opt-Out}}

== Going Live ==
Following Nielsen testing, you will need to:

# '''Disable Debug Logging''': Disable logging by deleting <code>{nol_devDebug: 'DEBUG'}</code> from initialization call.
# '''Notify Nielsen''': Once you are ready to go live, let us know so we can enable you for reporting. We will not be able to collect or report data prior to receiving notification from you.

== Sample Applications ==
The below sample applications have been designed to show the API's functionality and are broken into two distinct categories:
* '''Basic''' - To show the functionality of the Nielsen API using a standard no-frills player.
** [[Android Basic example|Android Studio Example]]

* '''Advanced''' - Nielsen API integrated into a custom video player is contained in the ZIP package.