Difference between revisions of "DCR Italy Static Browser SDK"

From Engineering Client Portal

m (Admin moved page DCR Italy Static Browser SDK (6.0.0) to DCR Italy Static Browser SDK without leaving a redirect)
(Opt-Out)
 
(20 intermediate revisions by 6 users not shown)
Line 1: Line 1:
{{Breadcrumb|}} {{Breadcrumb|Digital}} {{CurrentBreadcrumb}}
+
{{Breadcrumb|}} {{Breadcrumb|Digital}} {{Breadcrumb|International DCR}} {{CurrentBreadcrumb}}
 
[[Category:Digital]]
 
[[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:
 +
*Site launch events and how long page is viewed
 +
*Time of viewing a sub section / page.
  
 
== Prerequisites ==
 
== Prerequisites ==
Line 11: Line 17:
 
<syntaxhighlight lang="javascript"><script>
 
<syntaxhighlight lang="javascript"><script>
 
   // Static Queue Snippet
 
   // Static Queue Snippet
!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");
+
! 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");
  
 
   // SDK Initialization
 
   // SDK Initialization
  var nSdkInstance = NOLBUNDLE.nlsQ("PXXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXX","nlsnInstance", {nol_sdkDebug: "debug"});
+
var nSdkInstance = NOLBUNDLE.nlsQ("PXXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXX", "nlsnInstance", {
 +
    nol_sdkDebug: "debug"
 +
});
 
    
 
    
 
   // Content Metadata  
 
   // Content Metadata  
Line 20: Line 40:
 
     type: 'static',  
 
     type: 'static',  
 
     assetid: '', // *DYNAMIC METADATA*: unique ID for each article **REQUIRED**
 
     assetid: '', // *DYNAMIC METADATA*: unique ID for each article **REQUIRED**
     section: '', // *DYNAMIC METADATA*: section of site **REQUIRED**
+
     section: 'EntityName_BRW' // *DYNAMIC METADATA*: section of site **REQUIRED**
    segA: '', // *DYNAMIC METADATA*: custom segment
 
    segB: '', // *DYNAMIC METADATA*: custom segment
 
    segC: ''  // *DYNAMIC METADATA*: custom segment
 
 
     };  
 
     };  
 
      
 
      
Line 41: Line 58:
 
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.
 
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.
 
<syntaxhighlight lang="javascript">
 
<syntaxhighlight lang="javascript">
!function(t,n){t[n]=t[n]||
+
! function(t, n) {
{
+
    t[n] = t[n] || {
  nlsQ:function(e,o,c,r,s,i)
+
        nlsQ: function(e, o, c, r, s, i) {
    {
+
            return s = t.document, r = s.createElement("script"), r.async = 1, r.src =
      return s=t.document,
+
                ("http:" === t.location.protocol ? "http:" : "https:") + "//cdn-gl.imrworldwide.com/conf/" +
      r=s.createElement("script"),
+
                e + ".js#name=" + o + "&ns=" + n, i = s.getElementsByTagName("script")[0],
      r.async=1,
+
                i.parentNode.insertBefore(r, i), t[n][o] = t[n][o] || {
      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),
+
                    g: c || {},
      t[o]=t[o]||{g:c,ggPM:function(n,e,c,r,s){(t[o].q=t[o].q||[]).push([n,e,c,r,s])}},t[o]}
+
                    ggPM: function(e, c, r, s, i) {
    }
+
                        (t[n][o].q = t[n][o].q || []).push([e, c, r, s, i])
}
+
                    }
(window,"NOLBUNDLE");</syntaxhighlight>
+
                }, t[n][o]}}}
 +
(window, "NOLBUNDLE");
 +
</syntaxhighlight>
  
  
Line 112: Line 131:
 
| type || asset type || fixed || <code>'static'</code> || Yes
 
| type || asset type || fixed || <code>'static'</code> || Yes
 
|-
 
|-
| assetid || Unique ID for each article || dynamic || custom || 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 || 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) || fixed || custom || No
+
| section || section of the site to be measured </br> EntityName = brand name or sub-brand name || dynamic || <code>EntityName_BRW</code> || Yes
|}
 
 
 
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.
 
 
 
'''Aggregation Limits'''
 
There are limits on the number of unique values that can be aggregated on in reporting. The specific limitations by key are:
 
{| class="wikitable"
 
|-
 
! Key !! Aggregation Limit
 
|-
 
| section || maximum of 25 unique values (section <= 25)
 
|-
 
| segA || Maximum number of unique values allowed across segA, segB, and segC is 25 (segA + segB + segC<= 25)
 
|-
 
| segB || Maximum number of unique values allowed across segA, segB, and segC is 25 (segA + segB + segC<= 25)
 
|-
 
| segC || Maximum number of unique values allowed across segA, segB, and segC is 25 (segA + segB + segC<= 25)
 
 
|}
 
|}
  
Line 143: Line 139:
 
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, include the following two items in your privacy policy
 
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, include the following two items in your 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 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
+
* A link to the Nielsen Digital Measurement Privacy Policy at https://global.nielsen.com/legal/privacy-principles/digital-measurement-privacy-statement/?lang=it.
 
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.
 
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, the properties may feature Nielsen proprietary measurement software, which will allow users to contribute to market research, such as Nielsen TV Ratings. To learn more about the information that Nielsen software may collect and your choices with regard to it, please see the Nielsen Digital Measurement Privacy Policy at http://www.nielsen.com/digitalprivacy.
+
The following paragraph is a template for an opt-out statement, the properties may feature Nielsen proprietary measurement software, which will allow users to contribute to market research, such as Nielsen TV Ratings. To learn more about the information that Nielsen software may collect and your choices with regard to it, please see the Nielsen Digital Measurement Privacy Policy at https://global.nielsen.com/legal/privacy-principles/digital-measurement-privacy-statement/?lang=it.
  
 
'''Opt Back In'''
 
'''Opt Back In'''
  
Once users have opted-out, they can choose to opt back into Nielsen Measurement at anytime by selecting the opt back in link on the Nielsen Digital Privacy Policy page. When a user selects the link, their opt-out cookie will be deleted and they will be able to be measured.
+
Once users have [https://priv-policy.imrworldwide.com/priv/browser/cookie-policy-it-it.html?optout=1 opted-out], they can choose to opt back into Nielsen Measurement at anytime by selecting the [https://priv.imrworldwide.com/priv/browser/cookie-policy-reset-it-it.html?optout=0 opt back in link] on the Nielsen Digital Privacy Policy page. When a user selects the link, their opt-out cookie will be deleted and they will be able to be measured.
 
 
== Infinite Scrolling ==
 
 
 
<code>onPaginate</code> will refire the view ping with the existing/original metadata.
 
 
 
<source lang="javascript">nSdkInstance.ggPM("onPaginate", scrolloffset);</source>
 
<br>
 
{|
 
!width="23%"| Parameter
 
!width="19%"| Description
 
|-
 
| event
 
| <code>onPaginate</code>
 
|-
 
| scrolloffset
 
| The <code>scrolloffset</code> value should be the y-scroll position:
 
|}
 
 
 
=== onPaginate ===
 
 
 
<code>onPageinate</code> is a slightly modified version of <code>staticstart</code> to enable tracking of user’s focus in pages with continuous scrolling. <code>onPaginate</code> event provides the same behavior as <code>staticstart</code> keeping it local to only clients who wish to implement continuous scrolling. (Note: This event <code>onPaginate</code> will not reset the page duration timer.)
 
 
 
* The maximum number of static View pings allowed per session is ‘1’. This is enforced via the <code>nol_maxPingCount</code> parameter in the tag and the cadence of impression.
 
* When an <code>onPaginate</code> event is called at the end of section / a focus shift (within the same page), this filter will reset the current ping count to ‘0’ for the static View ping. This change of value will cause a new View ping when the Browser SDK receives the next <code>staticPosition</code> event (at the section end). This sequence continues through the end of scrolling or till the close of static page session.
 
 
 
[[File:StaticPageEvent35.jpg|center|link=]]
 
  
 
== Going Live ==
 
== Going Live ==
Once the DCR Tracking Code is added to Instant Articles, Nielsen will validate the implementation. Following Nielsen testing, users need to make a couple of updates to the initialization call to ensure that the site is being measured properly.
+
Following Nielsen testing, users need to make a couple of updates to the initialization call to ensure that the site is being measured properly.
 
# '''App ID''': Ensure that correct <apid> is used during initialization<syntaxhighlight lang="javascript">'PXXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX'</syntaxhighlight>
 
# '''App ID''': Ensure that correct <apid> is used during initialization<syntaxhighlight lang="javascript">'PXXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX'</syntaxhighlight>
 
# '''Debug Logging''': Disable logging by deleting <code>{nol_sdkDebug: 'DEBUG'}</code> from initialization call.
 
# '''Debug Logging''': Disable logging by deleting <code>{nol_sdkDebug: 'DEBUG'}</code> from initialization call.
 
#* '''Example Production Initialization Call''' - Refer to the production initialization call below:<syntaxhighlight lang="javascript">var nSdkInstance = NOLBUNDLE.nlsQ("PXXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX", "nlsnInstance");</syntaxhighlight>
 
#* '''Example Production Initialization Call''' - Refer to the production initialization call below:<syntaxhighlight lang="javascript">var nSdkInstance = NOLBUNDLE.nlsQ("PXXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX", "nlsnInstance");</syntaxhighlight>

Latest revision as of 13:15, 13 July 2022

Engineering Portal breadcrumbArrow.png Digital breadcrumbArrow.png International DCR breadcrumbArrow.png DCR Italy Static Browser SDK

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:

  • Site launch events and how long page is viewed
  • Time of viewing a sub section / page.

Prerequisites

To get started, an App ID is needed. The App ID is a unique ID assigned to the player/site/app. This will be provided upon starting the integration.

'PXXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX'

Implementation Steps

Add Tracking Code

The Nielsen DCR Tracking Code must be added to each page.

<script>
  // Static Queue Snippet
! 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");

  // SDK Initialization
var nSdkInstance = NOLBUNDLE.nlsQ("PXXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXX", "nlsnInstance", {
    nol_sdkDebug: "debug"
});
  
  // Content Metadata 
  var nielsenMetadata = {
    type: 'static', 
    assetid: '', // *DYNAMIC METADATA*: unique ID for each article **REQUIRED**
    section: 'EntityName_BRW' // *DYNAMIC METADATA*: section of site **REQUIRED**
    }; 
    
  // Event 'staticstart' Call
  nSdkInstance.ggPM("staticstart", nielsenMetadata);
</script>

Tracking Code Components

The tracking code includes

  • Static Queue Snippet
  • SDK Initialization
  • Content Metadata
  • staticstart Event

Static Queue Snippet

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.

! 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");


SDK Initialization

While creating an SDK instance, initialize the SDK by calling:

Initialization API Call

NOLBUNDLE.nlsQ("PXXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXX", "",{nol_sdkDebug: "debug"})

When the initialization call is made, a unique static config file, <apid>.js, will be downloaded based on the apid and cached by the client-side browser(s).

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

Content Metadata

Metadata can be passed through key-values using the Nielsen reserved keys. The tracking code includes the Nielsen reserved keys and placeholder values.

Pass dynamic metadata for the keys with the <metadataPlaceholder> value (e.g. section: ).

staticstart Event

There is only one event call required:

nSdkInstance.ggPM("staticstart", nielsenMetadata);

The content metadata object is passed as a parameter when calling 'staticstart' event . To know more about configuring metadata refer Step 3.

Pass App ID in Initialization Call

Pass the unique App ID in the first parameter of the initialization call, <apid>.

Example SDK Initialization

var nSdkInstance = NOLBUNDLE.nlsQ("PXXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXX", "nlsnInstance", {nol_sdkDebug: "debug"});

The initialization call has three parameters:

Parameter Description Values
apid Unique ID assigned to player/site. PXXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXX
instanceName Name of SDK instance Any string value
nol_sdkDebug: "debug" Enables Nielsen console logging. Only required for testing {nol_sdkDebug: "debug"}

Update <apid> with the AppID provided. Refer to the Going Live section to know about updating the AppID to production after testing is completed.

Configure Metadata

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

The Nielsen reserved keys are:

Key Description Data Type Value Required?
type asset type fixed 'static' Yes
assetid Unique ID for each article dynamic custom
(no Special Characters)
Yes
section section of the site to be measured
EntityName = brand name or sub-brand name
dynamic EntityName_BRW Yes

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, include the following two items in your privacy policy

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, the properties may feature Nielsen proprietary measurement software, which will allow users to contribute to market research, such as Nielsen TV Ratings. To learn more about the information that Nielsen software may collect and your choices with regard to it, please see the Nielsen Digital Measurement Privacy Policy at https://global.nielsen.com/legal/privacy-principles/digital-measurement-privacy-statement/?lang=it.

Opt Back In

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

Going Live

Following Nielsen testing, users need to make a couple of updates to the initialization call to ensure that the site is being measured properly.

  1. App ID: Ensure that correct <apid> is used during initialization
    'PXXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX'
    
  2. Debug Logging: Disable logging by deleting {nol_sdkDebug: 'DEBUG'} from initialization call.
    • Example Production Initialization Call - Refer to the production initialization call below:
      var nSdkInstance = NOLBUNDLE.nlsQ("PXXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX", "nlsnInstance");