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

== Setting up Development Environment ==
=== Step 1: Configure Content Management System (CMS) ===
Configure CMS to send the required values (see table below). Any internal CMS_variable names can be used for passing the data.

Ensure to capture these CMS_variable names in the SDK Configuration Form.

For more information on setting variable names, see the SDK Configuration Form included within the SDK package.

{| class="wikitable"
|-
! Required Data !! Description !! Value
|-
| dataSrc || Used when both CMS metadata and ID3 data are present in the player. Setting this field tells the SDK whether to use the CMS metadata or the ID3 payload to derive the pings || cms
|-
| type || Type of asset: ad or content || preroll, midroll, postroll, or content
|-
| assetid || unique ID assigned to asset || custom
|-
| OCR Tag || OCR tag provided by Nielsen for implementation on the ad unit || Complete OCR URL
|-
| program || Name of program (25 character limit) || custom
|-
| title || Episode title (40 character limit) || custom
|-
| length || Length of content in seconds || Length in seconds, 86400 for live stream
|-
| adloadtype || Type of ad load || "1" - Linear "2" Dynamic(default)
|-
| hadAds || Identify if content includes Ads || "0" - no ads "1" - includes ads "2" unknown(default)
|-
| isfullepisode || Full episode flag || "y" - full episode "n" - non full episode
|-
| segA || Segment A (this is not available for video reporting as the episode title is reported) || custom value
|-
| segB || Custom segment B || custom value
|-
| segC || Custom segment C || custom value
|-
| crossId1 || Standard episode ID || custom value
|-
| crossId2 || Content originator (required only for distributors) || custom value
|-
| airdate || Original air date and time in Eastern Time. For non-US countries, it should be local time. || YYYYMMDD HH24:MI:SS
|}

==== Content Management System for Digital Audio ====
Digital Audio measurement is for digital-only audio content. For Digital Audio, clients should provide the parameters shown in CMS Table for Digital Audio.
{| class="wikitable"
|-
! Required Data !! Description !! Value
|-
| dataSrc ** || Source of the data. For Digital Audio, pass dataSrc as “cms”. || cms
|-
| type || Type of content . For Digital Audio, set type as “radio”. || radio
|-
| assetid || Station identifier, should include call letters and band. || WXYZ-FM
|-
| stationType || OTA station flag and / or OTA station type 0: Custom station built per user 1: OTA streaming station with the same ad load 2: OTA station with a different ad load 3: Multicast eRadio or online station 4: On Demand Audio (podcasting) || 0, 1, 2, 3, or 4
|-
| provider || Name of Provider || XYZ Provider
|}

=== Step 2: Complete the Nielsen SDK Configuration Form ===
The SDK is designed to map the <code>CMS_variable names</code>. To support the custom mapping, the developer is required to complete the SDK Configuration Form. The form will be provided during onboarding along with this guide.

== Initialization ==
=== Obtain the Nielsen Application ID (apid) and Browser SDK URLs ===
The Nielsen <code>apid</code> is required to enable SDK functionality. Technical Account Manager will provide an apid for each player configuration.
Browser SDK can support URLs that use any of the protocols – HTTPS and HTTP.

=== Configure Browser SDK ===
There are two steps required for configuring the SDK:

Add Static Queue Snippet
Create SDK Instance

Add Static Queue Snippet

Add the following script tag to the website:
<syntaxhighlight lang="javascript">
<script type="text/javascript">
!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. As the queue can 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, create an SDK instance by making the initialization call:

Initialization API Call
<syntaxhighlight lang="javascript">
NOLBUNDLE.nlsQ("<apid>", "<instanceName>",{nol_sdkDebug: "debug"})
</syntaxhighlight>

When creating an instance, pass the following three values:

=== SDK Initialization – Global Parameters ===
{| class="wikitable"
|-
! Parameters !! Description !! Value
|-
| apid || UniqueID assigned to player/site. || 'XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX'
|-
| instanceName || Name of SDK instance || "any string value"
|-
| nol_sdkDebug || Enables Nielsen console logging. Only required for testing || "{nol_sdkDebug: "debug"})"
|}

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

<blockquote>'''Note:''' The debug parameter, <code>nol_sdkDebug</code>, is only used for testing and should be removed before moving to production. The output is displayed in console debuggers when enabled.</code>.</blockquote>

When the initialization call is made, a unique static configuration file, <apid>.js, will be downloaded based on the apid and will be 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: “nlsSDK601.bundle.min.js”.

Example SDK Configuration

The configuration should include the Static Queue Snippet and an SDK Instance for an unique App ID as shown in the example:

<syntaxhighlight lang="javascript">
<script type="text/javascript">
!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");
// Created SDK Instance
var nSdkInstance = NOLBUNDLE.nlsQ("XXXXXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXX","nlsnInstance", {nol_sdkDebug: "debug"});
</script>
</syntaxhighlight>

== Browser SDK API Methods & Properties ==
{| class="wikitable sortable"
|-
! Method / Property !! Event # !! DTVR !! DAR !! Digital Audio !! DCR !! International (Germany) !! Description
|-
| [[loadMetadata (Browser)]] || 3 || ✔ || ✔ || ✔ || ✔ || ✔ || Used when there is a preroll ad that needs to be associated with content metadata. The loadMetadata will first be called to populate the content metadata values and then the loadMetadata for ad metadata will be called. This allows sending a content ping with the ad info, even if the user bails out during the preroll ad.
|-
| [[play (Browser)]] || 5 || ✔ || ✘ || ✘ || ✔ || ✔ || Used when there is an ID3 fed product such as DTVR and the client does not want to send in all the CMS metadata that is sent in loadMetadata. This allows the client to send in at least the required “channel name” value associated to the ID3 feed. When the client passes in the channelName, they can change the CMS data stored by passing new values. If this event is not called then the “channel name” value populated will be the default value of “defaultChannelName”.

'''VA Beacon:''' Called when content or ads start playing. The playhead position must be passed.
|-
| [[sendID3 (Browser)]] || 55 || ✔ || ✘ || ✘ || ✘ || ✘ || Used to send the ID3 metadata.
|-
| [[setPlayheadPosition (Browser)]] || 49 || ✘ || ✘ || ✔ || ✔ || ✔ || Used to send the playhead position.
|-
| [[stop (Browser)]] || 7 || ✘ || ✘ || ✘ || ✔ || ✔ || Used when switching between ad and content or content and ad.
|-
| [[end (Browser)]] || 57 || ✔ || ✘ || ✔ || ✔ || ✔ || This is triggered 1) at the end of the content stream, 2) if the user switches to another piece of content 3) when the browser is refreshed or closed
|-
| [[staticstart (Browser)]] || 14 || ✘ || ✘ || ✘ || ✔ || ✔ || Used to send the metadata for the static page.
|-
| [[getOptOutStatus (Browser)]] || 4 || ✘ || ✘ || ✘ || ✘ || ✔ || '''VA Beacon Only:''' Sent only after calling stop. The current position must be passed. Not needed for new International (Germany) implementations.
|-
| [[updateOTT (Browser)]] || - || ✘ || ✘ || ✘ || ✘ || ✔ || Used to notify Browser SDK that the remote OTT device (like Google ChromeCast, Roku, Amazon FireTV, etc.) is connected / disconnected (change of OTT status).
|-
| [[ onPaginate (Browser)]] || 30 || ✘ || ✘ || ✘ || ✔ || ✔ || Used to create a new instance of the SDK object
|-
| [[updateMetadata (Browser)]] || 35 || ✔ || ✔ || ✔ || ✔ || ✔ || This event is used for updating metadata parameters for the content or ad that is being played.
|}

== Retrieving ID3 Tags ==
The video player must have the ability to extract ID3 tags and supply them to the Browser SDK, based on the HLS standard.
*An ID3 tag spans two PES packets.
**In the first PES packet, look for www.nielsen.com, this is the start of the ID3 tag. Continue to parse the first PES packet until the undefined char "\ufffd" is found. This forms the first half of the ID3 tag
**In the second PES packet, identify the end pattern – a regEx of /(\/\d+){3}/ and look to remove the lowest index of either "\x00" and/or "\ufffd". Now the second packet has been appended and the demarcation of the Nielsen-specific data has been defined.

Follow the procedure below, to extract Nielsen ID3 tags from an MPEG-2 transport stream (including HLS streams).
#Parse the Program Map Table (PMT) to find the PID of the metadata stream. Confirm the presence of the metadata descriptor described in section 2.3.3 of Apple’s “HTTP Live Streaming Metadata Spec.pdf”. Only private streams with metadata descriptor present should be considered as ID3-tag metadata streams.
#Parse the HLS/Transport stream for any '''PES header''' with the PID found in step 1.
#Follow standard MPEG-2 parsing procedures to locate the start of the payload of the PES packet.
#Copy the PES payload into a buffer.
#The ID3 tag spans 2 PES packets. Parse the stream for the next packet whose PID is set to the PID found in step 1. Typically the ID3 Tag is of 249 bytes. The steps below guide towards extraction of the ID3 tag
##In the first PES packet, look for "www.nielsen.com" , this is the start of the ID3 tag. Keep on parsing the first PES packet until the undefined char "\ufffd" is found. This forms the first half of the ID3 tag
##In the second PES packet, identify the end pattern, a regEx of /(\/\d+){3}/ and look to remove the lowest index of either “\x00” and/or “\ufffd”. Now the second packet has been appended and the demarcation of the Nielsen specific data has been defined. This segment can be simply substringed.
##Concatenate this substringed segment with the payload derived from the first packet get the ID3 payload.
#Check the length of the contents in the buffer to make sure that it is equal to the size of a Nielsen ID3 tag.
#Ensure that the ID3 byte array is converted into the string and escape it, so that the SDK can consume it.
Repeat steps 2 through 7 for all ID3 tags in the stream.

'''References'''
*[http://www.iso.org/iso/catalogue_detail?csnumber=44169. ISO/IEC 13818-1:2007] Information technology – Generic coding of moving pictures and associated audio information: Systems
*https://developer.apple.com/library/ios/sdk/developers/AudioVideo/Conceptual/HTTP_Live_Streaming_Metadata_Spec/HTTP_Live_Streaming_Metadata_Spec.pdf

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

== Browser Opt-Out Implementation ==
The site in which video content is being measure via Nielsen methodology must provide the means for the user to opt-out of, or opt back into Nielsen Measurement.

For Browser-based applications, opt-out setting is stored via Nielsen cookie. Therefore, it is only necessary that users be made aware of measurement opt-out by incorporating the template below in the user interface.

=== Sample Opt Out Template ===
Our properties may feature Nielsen’s proprietary measurement software which will allow to contribute to market research, like Nielsen’s TV Ratings. To learn more about this information, see http://www.nielsen.com/digitalprivacy. Nielsen’s software may collect your choices with regards to it.

== Nielsen Privacy Requirements ==
Privacy protections that Nielsen ensures to have with each App SDK integration are as follows.
*Disclosure of viewership data collection in app store description
*Disclosure of viewership data collection in EULA / Privacy Policy
*A link in the EULA/Privacy policy, or in another conspicuous location within the App, to a Nielsen-hosted web page outlining what Nielsen is collecting and how it is being used
*Method for users to opt-out of Nielsen measurement, any time while using the application

=== Ratings Data Flow ===
Every view of creditable and watermarked content is measured by Nielsen.
[[File:RatingsDataFlow.png]]

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

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

=== Data Collected ===
{| class="wikitable"
|-
! Type of Information !! Parameter !! Transmitted to Nielsen? !! Sent to Provider?
|-
| rowspan="8" | Nielsen ID3 Watermark
|-
| FinalDistributor Timestamp || Yes || No
|-
| Program Content Timestamp || Yes || No
|-
| Mobile Breakout Code || Yes || No
|-
| Commercial Credit Code – Linear or Dynamic || Yes || No
|-
| Time ShiftedViewing Code || Yes || No
|-
| Segment Number || Yes || No
|-
| Segment View Pattern || Yes || No
|-
| rowspan="7" | Device/App Info
|-
| Device OSVersion || Yes || Yes
|-
| Device Model || Yes || No
|-
| Cache Buster || Yes || Yes
|-
| SDKDisabled Flag || Yes || No
|-
| ServerCode || Yes || No
|-
| Channel or URL || Yes || No
|-
| rowspan="9" | Nielsen Identifiers
|-
| Client ID || Yes || No
|-
| Campaign ID || Yes || Yes
|-
| Nielsen Unique Device ID || Yes || No
|-
| Application ID || Yes || No
|-
| DeviceGroup (ex. Tablet, Smartphone, Desktop) || Yes || Yes
|-
| OS Group (ex. Android, iOS, Windows) || Yes || Yes
|-
| SDKVersion || Yes || No
|-
| IP Address for DMA, Country Code || Yes || Yes
|}
<blockquote>'''Note''': Data is hashed, and encrypted using AES 128 before transmission to data provider.</blockquote>

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

This ping passes the following parameters to the provider:
* Campaign ID – (campaign, placement, creative)
* Country Code
* DMA
* OS Group (ex. iOS, Android)
* DeviceOS Version
* Device Advertiser ID
* DeviceGroup (ex. Tablet, Smartphone, Desktop)
* Cache Buster

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

The following paragraph is a template for an opt-out statement

<blockquote>Our properties may feature Nielsen proprietary measurement software, which will allow you to contribute to market research, such as Nielsen TV Ratings. To learn more about the information that Nielsen software may collect and your choices with regard to it, refer to Nielsen Digital Measurement Privacy Policy at http://www.nielsen.com/digitalprivacy.</blockquote>

For information, please see Opt-Out Implementation below.

=== Opt-Out Implementation ===
The site must provide the means for the user to opt-out of, or opt back into Nielsen Measurement.

'''Sample Opt Out Template'''

Our properties may feature Nielsen’s proprietary measurement software which will allow to contribute to market research, like Nielsen’s TV Ratings. To learn more about this information, please [http://www.nielsen.com/digitalprivacy| click here]. Nielsen’s software may collect your choices with regards to it.

== Testing ==
See [[Digital Measurement Testing#Testing Browser Implementation|Digital Measurement Testing - Testing Browser Implementation]].

Browser SDK API Reference

2017-08-02T21:09:26Z

AndrewKlaasse: section 1: updated tables

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

== Setting up Development Environment ==
=== Step 1: Configure Content Management System (CMS) ===
Configure CMS to send the required values (see table below). Any internal CMS_variable names can be used for passing the data.

Ensure to capture these CMS_variable names in the SDK Configuration Form.

For more information on setting variable names, see the SDK Configuration Form included within the SDK package.

{| class="wikitable"
|-
! Required Data !! Description !! Value
|-
| dataSrc || Used when both CMS metadata and ID3 data are present in the player. Setting this field tells the SDK whether to use the CMS metadata or the ID3 payload to derive the pings || cms
|-
| type || Type of asset: ad or content || preroll, midroll, postroll, or content
|-
| assetid || unique ID assigned to asset || custom
|-
| OCR Tag || OCR tag provided by Nielsen for implementation on the ad unit || Complete OCR URL
|-
| program || Name of program (25 character limit) || custom
|-
| title || Episode title (40 character limit) || custom
|-
| length || Length of content in seconds || Length in seconds, 86400 for live stream
|-
| adloadtype || Type of ad load || "1" - Linear "2" Dynamic(default)
|-
| hadAds || Identify if content includes Ads || "0" - no ads "1" - includes ads "2" unknown(default)
|-
| isfullepisode || Full episode flag || "y" - full episode "n" - non full episode
|-
| segA || Segment A (this is not available for video reporting as the episode title is reported) || custom value
|-
| segB || Custom segment B || custom value
|-
| segC || Custom segment C || custom value
|-
| crossId1 || Standard episode ID || custom value
|-
| crossId2 || Content originator (required only for distributors) || custom value
|-
| airdate || Original air date and time in Eastern Time. For non-US countries, it should be local time. || YYYYMMDD HH24:MI:SS
|}

==== Content Management System for Digital Audio ====
Digital Audio measurement is for digital-only audio content. For Digital Audio, clients should provide the parameters shown in CMS Table for Digital Audio.
{| class="wikitable"
|-
! Required Data !! Description !! Value
|-
| dataSrc ** || Source of the data. For Digital Audio, pass dataSrc as “cms”. || cms
|-
| type || Type of content . For Digital Audio, set type as “radio”. || radio
|-
| assetid || Station identifier, should include call letters and band. || WXYZ-FM
|-
| stationType || OTA station flag and / or OTA station type 0: Custom station built per user 1: OTA streaming station with the same ad load 2: OTA station with a different ad load 3: Multicast eRadio or online station 4: On Demand Audio (podcasting) || 0, 1, 2, 3, or 4
|-
| provider || Name of Provider || XYZ Provider
|}

=== Step 2: Complete the Nielsen SDK Configuration Form ===
The SDK is designed to map the <code>CMS_variable names</code>. To support the custom mapping, the developer is required to complete the SDK Configuration Form. The form will be provided during onboarding along with this guide.

== Initialization ==
=== Obtain the Nielsen Application ID (apid) and Browser SDK URLs ===
The Nielsen <code>apid</code> is required to enable SDK functionality. Technical Account Manager will provide an apid for each player configuration.
Browser SDK can support URLs that use any of the protocols – HTTPS and HTTP. Contact the Technical Account Manager to get the appropriate Browser SDK package that suits the requirements.

=== Initialize Browser SDK ===
To initialize the SDK, parameters must be passed when calling the initialization function (<code>ggInitialize</code>).

Create a global object with the values for the required parameters (sfcode, apid, apn, and nol_sdkDebug).
<syntaxhighlight lang="javascript">
<script type="text/javascript">
var _nolggGlobalParams =
{
apid: "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXX",
sfcode: "dcr-cert",
apn: "sample player name / site name",
nol_sdkDebug: "console"
};
</script>
</syntaxhighlight>
<blockquote>'''Note:''' Use the debug parameter, nol_sdkDebug, for testing only. Remove the parameter before moving to production.</blockquote>

To initialize the SDK , use the following methods:
<syntaxhighlight lang="javascript">
<script type="text/javascript">
var gg = window.NOLCMB.getInstance(instanceName /*optional*/);
gg.ggInitialize(window._nolggGlobalParams);
</syntaxhighlight>
If no parameters are passed to getInstance(), the default instance name is used.
<blockquote>'''Note:''' To create a new instance of the player, send a different / new unique string. Sending the same unique string re-initializes the existing instance of the player.</blockquote>
<blockquote>'''Note:''' To measure static content on a page and integrate the SDK with a player for video measurement, it is recommended to create one SDK instance using <code>_nolggGlobalParams.apid</code>.</blockquote>

=== SDK Initialization – Global Parameters ===
{| class="wikitable"
|-
! Parameters !! Description !! Value !! Required?
|-
| apid || UniqueID assigned to player/site. || Nielsen provided || Yes
|-
| apn || User-defined string value for describing the player/site. || Client provided || Yes
|-
| sfcode || Location of collection environment. During testing, all traffic should be directed to "dcr-cert". || "dcr-cert" – testing "dcr" – production || Yes
|-
| nol_sdkDebug || Enables Debug Mode which allows output to be viewed in console. || "console" || No
|}
<blockquote>'''Note:''' The debug parameter, <code>nol_sdkDebug</code>, is only used for testing and should be removed before moving to production. The output is displayed in console debuggers when enabled.</code>.</blockquote>

== Browser SDK API Methods & Properties ==
{| class="wikitable sortable"
|-
! Method / Property !! Event # !! DTVR !! DAR !! Digital Audio !! DCR !! International (Germany) !! Description
|-
| [[loadMetadata (Browser)]] || 3 || ✔ || ✔ || ✔ || ✔ || ✔ || Used when there is a preroll ad that needs to be associated with content metadata. The loadMetadata will first be called to populate the content metadata values and then the loadMetadata for ad metadata will be called. This allows sending a content ping with the ad info, even if the user bails out during the preroll ad.
|-
| [[play (Browser)]] || 5 || ✔ || ✘ || ✘ || ✔ || ✔ || Used when there is an ID3 fed product such as DTVR and the client does not want to send in all the CMS metadata that is sent in loadMetadata. This allows the client to send in at least the required “channel name” value associated to the ID3 feed. When the client passes in the channelName, they can change the CMS data stored by passing new values. If this event is not called then the “channel name” value populated will be the default value of “defaultChannelName”.

'''VA Beacon:''' Called when content or ads start playing. The playhead position must be passed.
|-
| [[sendID3 (Browser)]] || 55 || ✔ || ✘ || ✘ || ✘ || ✘ || Used to send the ID3 metadata.
|-
| [[setPlayheadPosition (Browser)]] || 49 || ✘ || ✘ || ✔ || ✔ || ✔ || Used to send the playhead position.
|-
| [[stop (Browser)]] || 7 || ✘ || ✘ || ✘ || ✔ || ✔ || Used when switching between ad and content or content and ad.
|-
| [[end (Browser)]] || 57 || ✔ || ✘ || ✔ || ✔ || ✔ || This is triggered 1) at the end of the content stream, 2) if the user switches to another piece of content 3) when the browser is refreshed or closed
|-
| [[staticstart (Browser)]] || 14 || ✘ || ✘ || ✘ || ✔ || ✔ || Used to send the metadata for the static page.
|-
| [[getOptOutStatus (Browser)]] || 4 || ✘ || ✘ || ✘ || ✘ || ✔ || '''VA Beacon Only:''' Sent only after calling stop. The current position must be passed. Not needed for new International (Germany) implementations.
|-
| [[updateOTT (Browser)]] || - || ✘ || ✘ || ✘ || ✘ || ✔ || Used to notify Browser SDK that the remote OTT device (like Google ChromeCast, Roku, Amazon FireTV, etc.) is connected / disconnected (change of OTT status).
|-
| [[ onPaginate (Browser)]] || 30 || ✘ || ✘ || ✘ || ✔ || ✔ || Used to create a new instance of the SDK object
|-
| [[updateMetadata (Browser)]] || 35 || ✔ || ✔ || ✔ || ✔ || ✔ || This event is used for updating metadata parameters for the content or ad that is being played.
|}

== Retrieving ID3 Tags ==
The video player must have the ability to extract ID3 tags and supply them to the Browser SDK, based on the HLS standard.
*An ID3 tag spans two PES packets.
**In the first PES packet, look for www.nielsen.com, this is the start of the ID3 tag. Continue to parse the first PES packet until the undefined char "\ufffd" is found. This forms the first half of the ID3 tag
**In the second PES packet, identify the end pattern – a regEx of /(\/\d+){3}/ and look to remove the lowest index of either "\x00" and/or "\ufffd". Now the second packet has been appended and the demarcation of the Nielsen-specific data has been defined.

Follow the procedure below, to extract Nielsen ID3 tags from an MPEG-2 transport stream (including HLS streams).
#Parse the Program Map Table (PMT) to find the PID of the metadata stream. Confirm the presence of the metadata descriptor described in section 2.3.3 of Apple’s “HTTP Live Streaming Metadata Spec.pdf”. Only private streams with metadata descriptor present should be considered as ID3-tag metadata streams.
#Parse the HLS/Transport stream for any '''PES header''' with the PID found in step 1.
#Follow standard MPEG-2 parsing procedures to locate the start of the payload of the PES packet.
#Copy the PES payload into a buffer.
#The ID3 tag spans 2 PES packets. Parse the stream for the next packet whose PID is set to the PID found in step 1. Typically the ID3 Tag is of 249 bytes. The steps below guide towards extraction of the ID3 tag
##In the first PES packet, look for "www.nielsen.com" , this is the start of the ID3 tag. Keep on parsing the first PES packet until the undefined char "\ufffd" is found. This forms the first half of the ID3 tag
##In the second PES packet, identify the end pattern, a regEx of /(\/\d+){3}/ and look to remove the lowest index of either “\x00” and/or “\ufffd”. Now the second packet has been appended and the demarcation of the Nielsen specific data has been defined. This segment can be simply substringed.
##Concatenate this substringed segment with the payload derived from the first packet get the ID3 payload.
#Check the length of the contents in the buffer to make sure that it is equal to the size of a Nielsen ID3 tag.
#Ensure that the ID3 byte array is converted into the string and escape it, so that the SDK can consume it.
Repeat steps 2 through 7 for all ID3 tags in the stream.

'''References'''
*[http://www.iso.org/iso/catalogue_detail?csnumber=44169. ISO/IEC 13818-1:2007] Information technology – Generic coding of moving pictures and associated audio information: Systems
*https://developer.apple.com/library/ios/sdk/developers/AudioVideo/Conceptual/HTTP_Live_Streaming_Metadata_Spec/HTTP_Live_Streaming_Metadata_Spec.pdf

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

== Browser Opt-Out Implementation ==
The site in which video content is being measure via Nielsen methodology must provide the means for the user to opt-out of, or opt back into Nielsen Measurement.

For Browser-based applications, opt-out setting is stored via Nielsen cookie. Therefore, it is only necessary that users be made aware of measurement opt-out by incorporating the template below in the user interface.

=== Sample Opt Out Template ===
Our properties may feature Nielsen’s proprietary measurement software which will allow to contribute to market research, like Nielsen’s TV Ratings. To learn more about this information, see http://www.nielsen.com/digitalprivacy. Nielsen’s software may collect your choices with regards to it.

== Nielsen Privacy Requirements ==
Privacy protections that Nielsen ensures to have with each App SDK integration are as follows.
*Disclosure of viewership data collection in app store description
*Disclosure of viewership data collection in EULA / Privacy Policy
*A link in the EULA/Privacy policy, or in another conspicuous location within the App, to a Nielsen-hosted web page outlining what Nielsen is collecting and how it is being used
*Method for users to opt-out of Nielsen measurement, any time while using the application

=== Ratings Data Flow ===
Every view of creditable and watermarked content is measured by Nielsen.
[[File:RatingsDataFlow.png]]

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

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

=== Data Collected ===
{| class="wikitable"
|-
! Type of Information !! Parameter !! Transmitted to Nielsen? !! Sent to Provider?
|-
| rowspan="8" | Nielsen ID3 Watermark
|-
| FinalDistributor Timestamp || Yes || No
|-
| Program Content Timestamp || Yes || No
|-
| Mobile Breakout Code || Yes || No
|-
| Commercial Credit Code – Linear or Dynamic || Yes || No
|-
| Time ShiftedViewing Code || Yes || No
|-
| Segment Number || Yes || No
|-
| Segment View Pattern || Yes || No
|-
| rowspan="7" | Device/App Info
|-
| Device OSVersion || Yes || Yes
|-
| Device Model || Yes || No
|-
| Cache Buster || Yes || Yes
|-
| SDKDisabled Flag || Yes || No
|-
| ServerCode || Yes || No
|-
| Channel or URL || Yes || No
|-
| rowspan="9" | Nielsen Identifiers
|-
| Client ID || Yes || No
|-
| Campaign ID || Yes || Yes
|-
| Nielsen Unique Device ID || Yes || No
|-
| Application ID || Yes || No
|-
| DeviceGroup (ex. Tablet, Smartphone, Desktop) || Yes || Yes
|-
| OS Group (ex. Android, iOS, Windows) || Yes || Yes
|-
| SDKVersion || Yes || No
|-
| IP Address for DMA, Country Code || Yes || Yes
|}
<blockquote>'''Note''': Data is hashed, and encrypted using AES 128 before transmission to data provider.</blockquote>

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

This ping passes the following parameters to the provider:
* Campaign ID – (campaign, placement, creative)
* Country Code
* DMA
* OS Group (ex. iOS, Android)
* DeviceOS Version
* Device Advertiser ID
* DeviceGroup (ex. Tablet, Smartphone, Desktop)
* Cache Buster

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

The following paragraph is a template for an opt-out statement

<blockquote>Our properties may feature Nielsen proprietary measurement software, which will allow you to contribute to market research, such as Nielsen TV Ratings. To learn more about the information that Nielsen software may collect and your choices with regard to it, refer to Nielsen Digital Measurement Privacy Policy at http://www.nielsen.com/digitalprivacy.</blockquote>

For information, please see Opt-Out Implementation below.

=== Opt-Out Implementation ===
The site must provide the means for the user to opt-out of, or opt back into Nielsen Measurement.

'''Sample Opt Out Template'''

Our properties may feature Nielsen’s proprietary measurement software which will allow to contribute to market research, like Nielsen’s TV Ratings. To learn more about this information, please [http://www.nielsen.com/digitalprivacy| click here]. Nielsen’s software may collect your choices with regards to it.

== Testing ==
See [[Digital Measurement Testing#Testing Browser Implementation|Digital Measurement Testing - Testing Browser Implementation]].