BSDK Step By Step: Difference between revisions

Revision as of 14:10, 5 May 2023

Engineering Portal / Digital / BSDK Step By Step

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

→ BSDK DCR Static

Show/hide DCR Static

BSDK DCR Static Introduction

Show/hide Intro

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 on a standard HTML webpage. It includes:

Static Queue Snippet: allows for SDK API calls while SDK and configuration file is loading onto page
SDK Initialization Call: initializes the SDK and static configuration file
DCR Static Metadata: information about the page(s) being tracked
staticStart Event: event that starts SDK measurement

By the end of this guide you'll have a webpage that is running Nielsen's Browser SDK in the background:

BSDK DCR Static Step 1 - Obtain AppID

Show/hide step 1

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

	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 BSDK on the webpage.
Example: PXXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXX

BSDK DCR Static Step 2 - Add Static Queue Snippet

Show/hide step 2

Create HTML page in your preferred editor. In order for SDK to begin tracking, the following code snippet up must be added in a <script> tag to be inserted in <head> tag of the HTML page.

<!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 Static Sample Page</title>
  <link rel="stylesheet" href="https://www.w3schools.com/w3css/4/w3.css">
  <link rel="stylesheet" href="https://fonts.googleapis.com/css?family=Raleway">
  <style>
  body,h1,h2,h3,h4,h5 {font-family: "Raleway", sans-serif}
  </style>
  <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");
  </script>
</head>
<body>
</body>
</html>

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.

BSDK DCR Static Step 3 - Make SDK Initialization Call

Show/hide step 3

Create a variable named nSdkInstance and initialize SDK by passing in your App ID into the NOLBUNDLE.nslq() method. Add the following code after the static queue snippet code:

// SDK Initialization call
var nSdkInstance = NOLBUNDLE.nlsQ("PXXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXX", "staticPage", {
  nol_sdkDebug: 'debug' // ONLY FOR TESTING! REMOVE BEFORE MOVING TO PRODUCTION
});

When the initialization call is made, a unique static config file, PXXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXX.js, will be loaded on to the page based on the appid and cached by the client-side browser(s). Once the static config file is loaded onto the page, the SDK (nlsSDK600.bundle.min.js) will be fully downloaded and initialized. The initialization call has three parameters:

Parameter	Description	Values
App ID (appid)	Unique ID assigned to player/site	PXXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXX
instanceName	Name of SDK instance	Any string value
options	Options to be added during initialization	nol_sdkDebug, optout

NOTE: REMOVE <nol_sdkDebug> OPTION BEFORE GOING INTO PRODUCTION RELEASE

BSDK DCR Static Step 4 - Create DCR Static Metadata Object

Show/hide step 4

Create metadata object which contains information about the static webpage. Add the following code after SDK initialization code:

// DCR Static Metadata Object
var nielsenMetadata = {
  type: 'static', // type of content [required]
  assetid: 'HHF887465-9486', // unique ID for each article [required]
  section: 'HOME', //  section of site [required]
  segA: '', // custom segment [optional]
  segB: '', // custom segment [optional]
  segC: ''  // custom segment [optional]
};

Metadata Object Properties

Key	Description	Fixed/Dynamic	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

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 value (e.g. section:)

BSDK DCR Static Step 5 - Call ggPM staticStart event

Show/hide step 5

Static Start Event

Make BSDK API call ggPM() passing in the event staticstart as the first parameter and metadata variable as the second parameter. Add the following code after creating your DCR Static metadata object:

nSdkInstance.ggPM('staticstart', staticMetadata);

The content metadata object is passed as a parameter when calling staticstart event.

Static End Event

Singe Page Applications (SPA)
The API call for staticend is not a requirement for all DCR Static integrations, however if client integration is a Single Page Application (SPA) it is imperative that staticend is called prior to the loading of new metadata. This allows the BSDK to properly credit the previous section/content being viewed before measuring the new one.

Call ggPM staticend event
Make BSDK API call ggPM() passing in the event staticend as the first parameter and metadata variable as the second parameter. In case metadata for another site section has been previously loaded, the staticend API call for that section should be made prior to loading in new metadata (different assetid/section) using a new staticstart API call.

nSdkInstance.ggPM('staticend', staticMetadata); The content metadata object is passed as a parameter when calling staticend event.

Do not place this call inside beforeunload browser event, because SDK need some time and resources to deliver data to cloud.

NOTE: the information on staticend is provided here for reference. The demo site code does not make use of staticend.

BSDK DCR Static Step 6 - Update Page Content

Show/hide step 6

As mentioned in the Create Metadata Object section, the section metadata property correlates to the section of the website the user is currently on. Examples include the home, about, contact, etc. sections often found on webpages. To properly credit the section of the page the user is currently viewing, you must make sure that the section metadata property correctly corresponds with the section or page of the site that the user is currently on. If a user navigates to the contact section of our website (www.example.com/contact) we would have the following in our metadata object:

// DCR Static Metadata Object
var nielsenMetadata = {
  type: 'static', // type of content [required]
  assetid: 'HHF887465-9486', // unique ID for each article [required]
  section: 'CONTACT', //  section of site [required]
  segA: '', // custom segment [optional]
  segB: '', // custom segment [optional]
  segC: ''  // custom segment [optional]
};

Note: DCR Static is not currently supported in iframe windows.

Keep Going

Show/hide

Congratulations, you've successfully integrated the Browser SDK on your web page!

Final code output:

<!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 Static Test Page</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");

    // SDK Initialization [update with your App Id]
    var nSdkInstance = NOLBUNDLE.nlsQ("PXXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXX", "staticPage", {
      nol_sdkDebug: "debug"
    });

// DCR Static Metadata Object
var nielsenMetadata = {
  type: 'static', // type of content [required]
  assetid: 'HHF887465-9486', // unique ID for each article [required]
  section: 'HOME', //  section of site [required]
  segA: '', // custom segment [optional]
  segB: '', // custom segment [optional]
  segC: ''  // custom segment [optional]
};

    // Call staticStart Event
    nSdkInstance.ggPM("staticstart", nielsenMetadata);
  </script>
</head>
<body class="w3-light-grey">
  <div class="w3-content" style="max-width:1400px">
    <header class="w3-container w3-center w3-padding-32"> 
    <h1><b>DCR Static Sample Web Page</b></h1>
    <p>Sample page with Nielsen's DCR Static Browser SDK integration</p>
  </header>
  <div class="w3-row">
  <div class="w3-col l8 s12">
    <div class="w3-card-4 w3-margin w3-white">
      <img src="/images/n-logo-aud.avif" alt="Nielsen" style="width: 60%;">
      <div class="w3-container">
        <h3><b>DCR Static</b></h3>
        <h5>Sample Page</h5>
      </div>
  
      <div class="w3-container">
        <p>Mauris neque quam, fermentum ut nisl vitae, convallis maximus nisl. Sed mattis nunc id lorem euismod placerat. Vivamus porttitor magna enim, ac accumsan tortor cursus at. Phasellus sed ultricies mi non congue ullam corper. Praesent tincidunt sed
          tellus ut rutrum. Sed vitae justo condimentum, porta lectus vitae, ultricies congue gravida diam non fringilla.</p>
        <div class="w3-row">
          <div class="w3-col m8 s12">
            <p><button class="w3-button w3-padding-large w3-white w3-border"><b>READ MORE »</b></button></p>
          </div>
          <div class="w3-col m4 w3-hide-small">
            <p><span class="w3-padding-large w3-right"><b>Comments  </b> <span class="w3-tag">0</span></span></p>
          </div>
        </div>
      </div>
    </div>
    <hr>
  </div>
  <div class="w3-col l4">
    <div class="w3-card w3-margin w3-margin-top">
    <img src="/images/arrows.jpeg" style="width: 100%; height: 300px;">
      <div class="w3-container w3-white">
        <h4><b>DCR Static</b></h4>
        <p>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.</p>
      </div>
    </div><hr>
    <hr> 
    <div class="w3-card w3-margin">
      <div class="w3-container w3-padding">
        <h4>Tags</h4>
      </div>
      <div class="w3-container w3-white">
      <p><span class="w3-tag w3-black w3-margin-bottom">DCR</span> <span class="w3-tag w3-light-grey w3-small w3-margin-bottom">Static</span> <span class="w3-tag w3-light-grey w3-small w3-margin-bottom">BSDK</span>
        <span class="w3-tag w3-light-grey w3-small w3-margin-bottom">Measurement</span> <span class="w3-tag w3-light-grey w3-small w3-margin-bottom">DCR</span>
      </p>
      </div>
    </div>
  </div>
  </div><br>
  </div>
  <footer class="w3-container w3-dark-grey w3-padding-32 w3-margin-top">
    <button class="w3-button w3-black w3-disabled w3-padding-large w3-margin-bottom">Previous</button>
    <button class="w3-button w3-black w3-padding-large w3-margin-bottom">Next »</button>
    <p>Powered by <a href="https://www.w3schools.com/w3css/default.asp" target="_blank">w3.css</a></p>
  </footer>  
</body>
</html>

Next Steps

Show/hide

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

How to debug BSDK integration?

In your browser's dev tools menu (Chrome and Edge - press F12) you can inspect the various elements and sources. Here you can see pings being sent by the SDK and various JavaScript sources. Debug-level console logs will be shown if BSDK is debug mode (which you configured during this tutorial).

Going Live

In addition to the basic steps above, before going live developers need to make certain privacy disclosures and allow users to opt out of Nielsen measurement. More details can be found here, along with a more comprehensive reference for implementing DCR Static measurement with BSDK.

Once the DCR Tracking Code is added, Nielsen will validate the implementation. Following Nielsen testing, developers 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 is used during initialization PXXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX
Debug Logging: Disable logging by deleting {nol_sdkDebug: 'debug'} from initialization call.

PRODUCTION Initialization Call - Refer to the production initialization call below:

var nSdkInstance = NOLBUNDLE.nlsQ("PXXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX", "staticPage");

→ BSDK DCR Video (coming soon)

→ BSDK DTVR (coming soon)

@@ Line 24: / Line 24: @@
 By the end of this guide you'll have a webpage that is running Nielsen's Browser SDK in the background:
 </br>[[File:BSDK DCR Static Ex.png|1000px]]</br>
 </div>