Nielsen BrowserSDK

Static Implementation

last update: 24.6.2021



About

This guide will show you how to enable page measurement (aka Static) on your website(s). The Nielsen Tracking Code must be added to each page with different metadata.


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. If not, please contact Nielsen local staff - See Czech Contacts.

PXXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX"


Configure SDK

Add the following script tag (Static Queue Snippet) to the header of your website:

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");
                                    var nSdkInstance = NOLBUNDLE.nlsQ("PXXXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX", "nlsnInstance");
                                

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 (already added in above code):

var nSdkInstance = NOLBUNDLE.nlsQ("appid", "instanceName", {debugMode"});

When creating an instance, pass the following values:

Parameter Description Required Values
appId Unique ID assigned to player/site Yes 'PXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX'
instanceName Name of SDK instance or Player Yes "any string value"
debugMode Enables Nielsen console logging. Only required for testing No "{nol_sdkDebug: "debug"})"


Example SDK Initialization

To initialize the SDK, create an SDK instance by making the initialization call (already added in above code):

For development phase - including DEBUG mode:

var nSdkInstance = NOLBUNDLE.nlsQ("PXXXXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXX", "myPlayerName", {nol_sdkDebug: "debug"});

For production phase (after approval):

var nSdkInstance = NOLBUNDLE.nlsQ("XXXXXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXX","myPlayerName");


Nielsen SDK js files

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

URL example https://cdn-gl.imrworldwide.com/conf/PD81D031A-112E-467E-9D2A-02ED46CB8DB5.js,

Once the static config file is downloaded, the SDK will be fully downloaded and initialized

URL https://cdn-gl.imrworldwide.com/novms/js/2/nlsSDK600.eu.bundle.min.js


Multiple Instances

If you need to measure multiple static elements at the same time - for example 2 different buttons at entry screen of HbbTV app - instantiate 2 different SDK instances - one for each measured element.

                    var nSdkInstance1 =NOLBUNDLE.nlsQ("PXXXXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXX","myPlayerName");
                    var nSdkInstance2 =NOLBUNDLE.nlsQ("PXXXXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXX","myPlayerName");


Create Metadata Objects

                                    // Content Metadata
                                    var nielsenMetadata = {
                                      type: 'static',
                                      assetid: 'value',
                                      section: 'value',
                                      segA: 'value',
                                      segB: 'value',
                                      segC: 'value',
                                      nol_c1: 'p1, value',
                                      nol_c2: 'p2, value'
                                      };
                                

Metadata can be passed through key-values using the Nielsen reserved keys. See Specification of Metadata for Czech Republic.


Call staticStart Event

Start static measurement :

                            // Event 'staticstart' Call
                            nSdkInstance.ggPM("staticstart", nielsenMetadata);

The content metadata object is passed as a parameter.


Call staticEnd Event

Please consider 2 types of staticend implementation:

  • Automaticall API call - Nielsen SDK can auto-detect when static page is closing and then API call staticend is called automatically. You dont need to call staticend in such situation.
  • In special cases or enviroments (like HbbTV) this may not be reliable. To stop static measurement - please call staticend directly in your app. The content metadata object is passed as a parameter. Make sure to give Nielsen SDK some time and resources to deliver data to cloud.
                                    // Event 'staticend' Call
                                    nSdkInstance.ggPM("staticend", nielsenMetadata);
                                

Outgoing data ping must be always present when closing static page.


API sequence for HbbTV

Level 1. Red button - call staticStart once Red button appears, call staticEnd once dissapears or if user opens main menu.

Level 2. Main menu (launched via Red Button) - call staticStart once menu appears, call staticEnd once user opens any app or close main menu.

Level 3. App (launched from Main Menu) - call staticStart/staticEnd on every page of app.


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

  • 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

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

The following paragraph is a template for an opt-out statement (in Czech):

Tato aplikace obsahuje proprietární měřicí software společnosti Nielsen, který uživatelům umožní přispívat k průzkumu trhu. Chcete-li se dozvědět více o informacích, které může software Nielsen shromažďovat a o Vaší možnosti měření deaktivovat, přečtěte si zásady ochrany osobních údajů Nielsen Digital Measurement na Nielsen Digital Measurement Privacy Policy


Opt-out status

Optional : to retrieve Opt-Out status call getOptOutStatus() , result is boolean value true (OptOuted = not measuring) or false (not OptOuted = measuring).

nSdkInstance.getOptOutStatus();


Test your player by yourself


SDK API calls

Use the Chrome and install add-on to verify SDK API calls: "Nielsen SDK Inspector" (https://chrome.google.com/webstore/search/%20Nielsen%20SDK%20Inspector)


Outgoing pings

to verify outgoing pings use Charles Proxy or any other proxy sw capable to sniff your network traffic. Filter URLs to "imrworld". Example of such ping :

https://secure-cz.imrworldwide.com/cgi-bin/gn?prd=dcr&ci=cz-509218&ch=cz-509218_c04_static%20section%20example_P&asn=static%20section%20example&sessionId=Ulj29VLVHrMp9ACe91tPZcx0LeepQ1558442561&prv=1&c6=vc,c04&ca=NA&c13=asid,PDA91E2F7-078D-47EC-ACA4-2677EE94E1D1&c32=segA,segA%2520example&c33=segB,segB%2520example&c34=segC,segC%2520example&c15=apn,&sup=1&segment2=&segment1=&forward=0&plugv=&playerv=&ad=0&cr=D&c9=devid,&enc=true&c1=nuid,OPTOUT&at=timer&rt=text&c16=sdkv,bj.6.0.0&c27=cln,6&crs=&lat=&lon=&c29=plid,15584425619895419&c30=bldv,6.0.0.333&st=dcr&c7=osgrp,&c8=devgrp,&c10=plt,&c40=adbid,&c14=osver,NA&c26=dmap,1&dd=&hrd=&wkd=&c35=adrsid,&c36=cref1,&c37=cref2,&c11=agg,1&c12=apv,&c51=adl,0&c52=noad,0&devtypid=&pc=NA&c53=fef,n&c54=oad,&c55=cref3,&c57=adldf,2&ai=static%20assetid%20example&c3=st,c&c64=starttm,1558442563&adid=static%20assetid%20example&c58=isLive,false&c59=sesid,&c61=createtm,1558442569&c63=pipMode,&uoo=&c68=bndlid,&nodeTM=&logTM=&c73=phtype,&c74=dvcnm,&c76=adbsnid,&c44=progen,&davty=1&si=https%3A%2F%2Fsdkdemo.admosphere.cz%2FBrowserSdk6static%2Fdemo1%2F&c66=mediaurl,&c62=sendTime,1558442569&rnd=415542


Provide your implementation for certification

Once ready please send your implementation to Nielsen local staff for verification - see Contacts.


Going Live

After the integration has been certified (but not prior that), users will need to disable debug logging by deleting {nol_sdkDebug: 'DEBUG'} from initialization call.


Demos

See live demos with sample implementation available at http://sdkdemo.admosphere.cz/


Contacts

Company

Nielsen Admosphere

Českobratrská 2778/1

130 00 Praha 3

www.nielsen-admosphere.cz


Administration, testing, certification and technical support

Tomáš Kuchler

Technical Account Manager

+420 777 814 468

tomas.kuchler@admosphere.cz


NielsenSDK Team

SDKsupport@admosphere.cz