Difference between revisions of "DCR Static Browser SDK (6.0.0)"

From Engineering Client Portal

(Add Tracking Code)
(36 intermediate revisions by 6 users not shown)
Line 1: Line 1:
{{Breadcrumb|}} {{Breadcrumb|Digital}} {{Breadcrumb|Digital Content Ratings}}  {{CurrentBreadcrumb}}
+
{{Breadcrumb|}} {{Breadcrumb|Digital}} {{Breadcrumb|US DCR & DTVR}}  {{CurrentBreadcrumb}}
 
[[Category:Digital]]
 
[[Category:Digital]]
 +
___NOTOC___
  
= 6.0.0 =
+
== Prerequisites ==
 +
To start using the App SDK, the following items are required:
 +
{| class="wikitable"
 +
|-
 +
! style="width: 30px;" |
 +
! style="width: 15%;" | Item
 +
! Description
 +
! Source
 +
|-style="background-color:#d0f6f8;"
 +
|| ☑ || '''App ID (appid)''' || Unique ID assigned to the player/site and configured by product. || Contact Nielsen
 +
|}
  
== Prerequisites ==
+
== Release Notes ==
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.
+
The release notes on the Browser SDK can be located here: '''[[Browser SDK Release Notes|Release Notes]]'''
<syntaxhighlight lang="javascript">'PXXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX'</syntaxhighlight>
 
  
 
== Implementation Steps ==
 
== Implementation Steps ==
Line 13: Line 23:
 
<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[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]}}} (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  
 
   var nielsenMetadata = {
 
   var nielsenMetadata = {
 
     type: 'static',  
 
     type: 'static',  
     assetid: '', // *DYNAMIC METADATA*: unique ID for each article **REQUIRED**
+
     assetid: 'HHF887465-9486', // *DYNAMIC METADATA*: unique ID for each article **REQUIRED**
     section: '', // *DYNAMIC METADATA*: section of site **REQUIRED**
+
     section: 'SPORTS', // *DYNAMIC METADATA*: section of site **REQUIRED**
     segA: '', // *DYNAMIC METADATA*: custom segment
+
     segA: 'HDVIDEOS', // *DYNAMIC METADATA*: custom segment
 
     segB: '', // *DYNAMIC METADATA*: custom segment
 
     segB: '', // *DYNAMIC METADATA*: custom segment
 
     segC: ''  // *DYNAMIC METADATA*: custom segment
 
     segC: ''  // *DYNAMIC METADATA*: custom segment
Line 31: Line 55:
 
   nSdkInstance.ggPM("staticstart", nielsenMetadata);
 
   nSdkInstance.ggPM("staticstart", nielsenMetadata);
 
</script></syntaxhighlight>
 
</script></syntaxhighlight>
 +
<blockquote>For DCR static, BSDK cannot be run in an iframe because the blur/focus events of the parent page may not propagate to the iframe. The iframe events typically trigger when the iframe itself is clicked. The BSDK is dependent on the blur/focus events of the browser to detect active viewing of the page. Because the root page events do not propagate to the iframe, this would impact incorrect DCR static crediting.</blockquote>
  
==== Tracking Code Components ====
+
=== Tracking Code Components ===
 
The tracking code includes
 
The tracking code includes
 
* Static Queue Snippet
 
* Static Queue Snippet
Line 43: Line 68:
 
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 81: Line 108:
 
<syntaxhighlight lang="javascript">nSdkInstance.ggPM("staticstart", nielsenMetadata);</syntaxhighlight>
 
<syntaxhighlight lang="javascript">nSdkInstance.ggPM("staticstart", nielsenMetadata);</syntaxhighlight>
  
The content metadata object is passed as a parameter when calling 'staticstart' event . To know more about configuring metadata refer [[Bundled_SDK_-_Static#Configure_Metadata|Step 3]].
+
The content metadata object is passed as a parameter when calling 'staticstart' event . To know more about configuring metadata refer [[DCR_Static_Browser_SDK_(6.0.0)#Configure_Metadata|Configure Metadata]].
  
 
=== Pass App ID in Initialization Call ===
 
=== Pass App ID in Initialization Call ===
Line 102: Line 129:
 
|}
 
|}
  
Update <code><apid></code> with the AppID provided. Refer to the [[Bundled_SDK_-_Static#Going_Live|Going Live]] section to know about updating the AppID to production after testing is completed.
+
Update <code><apid></code> with the AppID provided. Refer to the [[#Going_Live|Going Live]] section to know about updating the AppID to production after testing is completed.
 +
 
 +
{{Template:Browser_Metadata}}
  
=== Configure Metadata ===
+
{{Template:Browser_Privacy_and_Opt-Out}}
Map the Nielsen keys to variables so that the content metadata is dynamically updated.
 
  
The Nielsen reserved keys are:
+
== Infinite Scrolling ==
{| class="wikitable"
 
|-
 
! Key !! Description !! Data Type !! Value !! Required?
 
|-
 
| type || asset type || fixed || <code>'static'</code> || Yes
 
|-
 
| assetid || Unique ID for each article || dynamic || custom || 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
 
|}
 
  
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.
+
<code>onPaginate</code> will refire the view ping with the existing/original metadata.
  
'''Aggregation Limits'''
+
<source lang="javascript">nSdkInstance.ggPM("onPaginate", scrolloffset);</source>
There are limits on the number of unique values that can be aggregated on in reporting. The specific limitations by key are:
+
<br>
{| class="wikitable"
+
{|
|-
+
!width="23%"| Parameter
! Key !! Aggregation Limit
+
!width="19%"| Description
|-
 
| 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)
+
| event
 +
| <code>onPaginate</code>
 
|-
 
|-
| segB || Maximum number of unique values allowed across segA, segB, and segC is 25 (segA + segB + segC<= 25)
+
| scrolloffset
|-
+
| The <code>scrolloffset</code> value should be the y-scroll position:
| segC || Maximum number of unique values allowed across segA, segB, and segC is 25 (segA + segB + segC<= 25)
 
 
|}
 
|}
  
== Opt-Out ==
+
=== onPaginate ===
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 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, 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.
+
<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.)
  
'''Opt Back In'''
+
* 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.
 +
*One of the following must occur before an onPaginate event should be sent : user-initiated action, more than 50% of the content has changed or an ad, or the potential for an ad, is being loaded
  
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.
+
[[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.
+
Once the DCR Tracking Code is added, 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.
 
# '''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>
 
= 5.1.1 =
 
== Prerequisites ==
 
To start using the Browser SDK, the following details are required:
 
* '''App ID (apid):''' Unique ID assigned to the player/site and configured by product.
 
* '''sfcode:''' Unique identifier for the environment that the SDK should point to. During testing, please use the sfcode as "dcr-cert".
 
If you do not have any of these pre-requisites or if you have any questions, please contact our SDK sales support team.
 
 
== Import Library ==
 
In the HTML head section of each page, call the Nielsen library using the script tag, as shown below.
 
<syntaxhighlight lang="html">  <script type="javascript" src="http://secure-dcr-cert.imrworldwide.com/novms/js/2/ggcmb510.js"></script></syntaxhighlight>
 
 
== Define GlobalParams ==
 
<syntaxhighlight lang="html">  <script type="javascript">
 
  var _nolggGlobalParams =
 
    {
 
      sfcode: "dcr-cert",
 
      apid: "TXXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX",
 
      apn: "test-setup",
 
      nol_sdkdebug: "console"
 
    };
 
    </script></syntaxhighlight>
 
 
== Initialize SDK ==
 
Initialize Browser SDK as soon as the Parent / Main Page is loaded. During the initialization, custom parameters can be appended to the global parameter object. These custom (extended) parameters are optional. Use them only if the player application can handle the custom parameter data.
 
 
The Nielsen Browser SDK supports multiple processing instances. To create an instance, call the <code>getInstance()</code> function
 
<syntaxhighlight lang="javascript">    var nSdkInstance=NOLCMB.getInstance(instanceName);</syntaxhighlight>
 
All subsequent calls to getInstance with the same instanceName will return an already created SDK instance with that name. This will allow accessing the same object from different parts of the code.
 
 
The "instanceName" parameter is optional and will be set to "default" if missing. To use a single default SDK instance, call
 
<syntaxhighlight lang="javascript">    var nSdkInstance=NOLCMB.getInstance();</syntaxhighlight>
 
In order to initialize the SDK, parameters must be passed when calling the initialization function (ggInitialize). The available parameters are listed in the table below.
 
{| class="wikitable"
 
|-
 
! Parameters !! Description !! Value !! Required? (Y/N)
 
|-
 
| apid || UniqueID assigned to player/site. There are two IDs provided for
 
# Test: begins with ‘T’ and is used for testing, and
 
# Production: begins with ‘P’ and is used when testing is completed in live environment.
 
|| Nielsen assigned || Yes
 
|-
 
| apn || User-defined string value for describing the player/site || Client-specified || Yes
 
|-
 
| sfcode || Location of collection environment. During testing, all traffic should be directed to <code>dcr-cert</code>. || "dcr-cert" – testing
 
"dcr" – production || Yes
 
|-
 
| nsdkv || Nielsen SDK Version currently being used. || Nielsen assigned (‘511’ for Browser SDK 5.1.0, etc.) || Yes
 
|-
 
| nol_sdkdebug || Enables Debug Mode which allows output to be viewed in console. || <code>"console"</code> || No
 
|}
 
 
<syntaxhighlight lang="javascript">    var gg = window.NOLCMB.getInstance(instanceName /*optional*/);
 
    gg.ggInitialize(window._nolggGlobalParams);</syntaxhighlight>
 
 
== Fire Event: staticStart ==
 
Use [[staticStart]] to pass details about content section. The CMS data must be passed as a JSON string (before closing <body>).
 
<syntaxhighlight lang="javascript">    ggPM(staticStart, metadataObject);</syntaxhighlight>
 
Trigger [[staticStart]], as below, for the static content when the page is loaded.
 
<syntaxhighlight lang="javascript">    gg.ggPM("staticstart",
 
    {
 
        type:"static",
 
        assetid:"static123",
 
        section:"siteSection",
 
        segA:"segmentA",
 
        segB:"segmentB",
 
        segC:"segmentC"
 
    }
 
    );</syntaxhighlight>
 
 
 
{| class="wikitable"
 
|-
 
! Key !! Description !! Values !! Reported for Static?
 
|-
 
| type || Type of audio / video Measurement content (content, etc.). || "static" || No
 
|-
 
| assetid || Unique ID assigned to content || custom || No
 
|-
 
| assetName || Unique name for the asset || custom || No
 
|-
 
| section || Section of the site || custom || No
 
|-
 
| segA || Custom Segment A || custom || Yes
 
|-
 
| segB || Custom Segment B || custom || Yes
 
|-
 
| segC || Custom Segment C || custom || Yes
 
|}
 
 
'''INSERT FLOW CHART HERE'''
 
 
== Dynamic Metadata ==
 
An alternative method for passing in assetid, section, segA-segC (if used), is to pass these values dynamically instead of hardcoding these values per site section. The code below provides an example of how this can be achieved.
 
<syntaxhighlight lang="javascript">    <script type="text/JavaScript">
 
    var temp =
 
    $("meta[property='og:url']").attr("content").replace("https://xyz.com/discover/","");
 
 
    var _nolggGlobalParams =
 
    {
 
        sfcode: "dcr-cert",
 
        apid: "TXXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX",
 
        apn: "test-static"
 
    };
 
    var gg = NOLCMB.getInstance(_nolggGlobalParams);
 
    gg.ggInitialize(_nolggGlobalParams);
 
    var staticmeta =
 
    {
 
        type: "static",
 
        assetid: "temp",
 
        section: "temp",
 
        segA: "Test Site",
 
        segB: "Videos",
 
        segC: "Comedy"
 
    };
 
    staticmeta.section = temp;
 
    gg.ggPM("staticstart",staticmeta);
 
    </script></syntaxhighlight>
 
 
== Tagging a Page ==
 
Refer to the [[BSDK_Tagging|sample code]] for Tagging a page with static <Page Measurement> content.
 
 
== Nielsen Measurement Opt-Out Implementation ==
 
As a global information and measurement leader, we are committed to protecting the privacy and security of the data we collect, process and use. Our digital measurement products are not used to identify the consumer in any way, but they help us and our clients measure and analyze how consumers engage with media across online, mobile and emerging technologies, and offer insights into consumer behavior.
 
 
When the user wants to opt in or opt out of Nielsen measurement, a new dynamic page (with content similar to [http://secure-us.imrworldwide.com/nielsen_app_optout.html]) should be displayed.
 
 
For more details, refer to [[Opt-Out Implementation]] and Nielsen Digital Privacy.
 
* Use [[getOptOutStatus]] to retrieve the user’s current Opt-Out status.
 
 
== Pre-Certification Checklists ==
 
After the website is ready to be sent for Nielsen Certification, please go through the Pre-Certification Checklist and ensure the webpage behaves as expected, before submitting to Nielsen.
 
 
== Testing an Implementation - Browser ==
 
[[Testing App Implementation | Click here]] for information on Testing the Browser Implementation.
 
 
<headertabs />
 

Revision as of 18:08, 30 April 2021

Engineering Portal breadcrumbArrow.png Digital breadcrumbArrow.png US DCR & DTVR breadcrumbArrow.png DCR Static Browser SDK (6.0.0)
__

Prerequisites

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

Item Description Source
App ID (appid) Unique ID assigned to the player/site and configured by product. Contact Nielsen

Release Notes

The release notes on the Browser SDK can be located here: Release Notes

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: 'HHF887465-9486', // *DYNAMIC METADATA*: unique ID for each article **REQUIRED**
    section: 'SPORTS', // *DYNAMIC METADATA*: section of site **REQUIRED**
    segA: 'HDVIDEOS', // *DYNAMIC METADATA*: custom segment
    segB: '', // *DYNAMIC METADATA*: custom segment
    segC: ''  // *DYNAMIC METADATA*: custom segment
    }; 
    
  // Event 'staticstart' Call
  nSdkInstance.ggPM("staticstart", nielsenMetadata);
</script>

For DCR static, BSDK cannot be run in an iframe because the blur/focus events of the parent page may not propagate to the iframe. The iframe events typically trigger when the iframe itself is clicked. The BSDK is dependent on the blur/focus events of the browser to detect active viewing of the page. Because the root page events do not propagate to the iframe, this would impact incorrect DCR static crediting.

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 Configure Metadata.

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 each site (e.g. section value should be first level in page URL: website.com/section). Limit to 25 unique values dynamic custom
(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.

Aggregation Limits There are limits on the number of unique values that can be aggregated on in reporting. The specific limitations by key are:

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)

Privacy and Opt-Out

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

  1. User Opt Out - Provide a link to the Nielsen Privacy Policy page when a User can make their selection
  2. Initialization Opt Out - Global OptOut Parameter

User 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 User Opt-Out option, include the following two items in your privacy policy.

  • A notice that the player (or page in relation to static measurement) 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 https://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.

  • Once users have opted out via this link, their browser cookies will contain the value TOTAL_OPTOUT. This will prevent a redirect to our data provider from occurring
  • Users can opt back in via this link. When a user selects that link, their opt-out cookie will be deleted and they will be able to be measured moving forward.


The following paragraph is a template for a Privacy 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://www.nielsen.com/digitalprivacy

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

Initialization Opt Out

The BSDK600 now supports the ability to optout on initialization of the SDK by allowing an optout global parameter to be passed. This optout will be maintained through the session of the SDK instance. Specifications and limitations are specified below.

Type Supported Values Notes Optout
optout True, Yes, or 1 Case is insensitive and can be string or bool

Example: nlsQ("XXXXXXXX-BH45-JKY6-BKH7-67GJKY68GJK7", "myInstance", { optout: true});

Ping parameter will set uoo=true.
optout False, No, or 0 Case is insensitive and can be string or bool

Example: nlsQ("XXXXXXXX-BH45-JKY6-BKH7-67GJKY68GJK7", "myInstance", { optout: false});

Ping parameter will set uoo to blank.

Example of using OptOut

var nSdkInstance = NOLBUNDLE.nlsQ("XXXXXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXX", "nlsnInstance", {
  nol_sdkDebug: "debug",
  optout: "true"
});

Opt Out Overview

Browser Cookie uoo value in session ping Final Optout Status
Default Value no uoo value or uoo=0 Not Opted Out
Default Value uoo=1 Opted Out
TOTAL_OPTOUT uoo=0 Opted Out
TOTAL_OPTOUT uoo=1 Opted Out

Infinite Scrolling

onPaginate will refire the view ping with the existing/original metadata.
nSdkInstance.ggPM("onPaginate", scrolloffset);


Parameter Description
event onPaginate
scrolloffset The scrolloffset value should be the y-scroll position:

onPaginate

onPageinate is a slightly modified version of staticstart to enable tracking of user’s focus in pages with continuous scrolling. onPaginate event provides the same behavior as staticstart keeping it local to only clients who wish to implement continuous scrolling. (Note: This event onPaginate will not reset the page duration timer.)

  • The maximum number of static View pings allowed per session is ‘1’. This is enforced via the nol_maxPingCount parameter in the tag and the cadence of impression.
  • When an onPaginate 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 staticPosition event (at the section end). This sequence continues through the end of scrolling or till the close of static page session.
  • One of the following must occur before an onPaginate event should be sent : user-initiated action, more than 50% of the content has changed or an ad, or the potential for an ad, is being loaded
StaticPageEvent35.jpg

Going Live

Once the DCR Tracking Code is added, 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.

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