Nielsen BrowserSDK

Video Implementation

last update: 24.6.2021



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


Create Metadata Objects

The metadata received for each asset is used for classification and reporting.

There are two types of asset metadata:

  • content: identify video
  • ad: identify each ad


Content Metadata

Content metadata should remain constant throughout the completion of an episode / clip including the ads play.
See Specification of Metadata for Czech Republic.


Ad Metadata

The ad metadata should be passed for each individual ad.
See Specification of Metadata for Czech Republic.


Call Nielsen APIs

The method for calling SDK API events is ggPM().

nSdkInstance.ggPM('eventName', parameter);


Types of SDK Events

Event Parameter Description Example
loadMetadata content or ad metadata JSON Needs to be called at the beginning of each asset nSdkInstance.ggPM("loadMetadata", metadataObjectContent)
setPlayheadPosition playhead position in seconds as integer Pass playhead position every second during playback. for VOD: pass current position in seconds. for Live: current Unix timestamp (seconds since Jan-1-1970 UTC) - if it's possible to seek back in Live content, then pass related Unix timestamp (not current) nSdkInstance.ggPM("setPlayheadPosition", currentPosition);
stop playhead position in seconds as integer Call when content or ads complete playing and pass playhead position, call stop when pausing playback nSdkInstance.ggPM("stop", parseInt(playerPosition));
end playhead position in seconds as integer Call when the current video asset completes playback and pass the playhead position. nSdkInstance.ggPM("end", parseInt(playerPosition));
  • 'setPlayheadPosition' is used for calculating duration and must be passed every second. The final playhead position must be sent for the current asset being played before calling 'stop', 'end', or 'loadmetadata'.
  • If 1st video in playlist is content - call 'loadMetadata' for content. If 1st video in playlist is ad (not content), call 'loadMetadata' for content and than 'loadMetadata' for add - see below SDK Event Lifecycle.
  • For Ad Pods, events must be called for each individual Ad. Each Ad playhead position should begin at ‘0’ when ad starts.
  • When content has resumed following an ad break, the playhead position update must continue where previous content segment left off. The playhead position should be passed as a rounded number with no decimals.
  • If last video in playlist is content (not ad) - call 'end' at the end of playlist. If last video in playlist in ad (not content), than call 'end' at the end of content video and stop at the end of ad - see bellow SDK Event Sequence. Summary: call 'end' at the end of the content stream, if the user switches to another piece of content, when the browser is refreshed or closed.


SDK Event Sequence

The sample event life-cycle can be used as a reference for identifying the order for calling events.
Playlist for this sample is : preRoll → content → midRoll → content resumed → postRoll

                                    // START OF STREAM
                                    nSdkInstance.ggPM('loadMetadata', contentMetadataObject);
                                    
                                    // PREROLL
                                    nSdkInstance.ggPM('loadMetadata', prerollMetadataObject);
                                    nSdkInstance.ggPM('setPlayheadPosition', playheadPosition);
                                    //
                                    //   pass playhead every second
                                    //
                                    nSdkInstance.ggPM('setPlayheadPosition', playheadPosition);
                                    nSdkInstance.ggPM('stop', playheadPosition);
                                    
                                    // CONTENT
                                    nSdkInstance.ggPM('loadMetadata', contentMetadataObject);
                                    nSdkInstance.ggPM('setPlayheadPosition', playheadPosition);
                                    //
                                    //   pass playhead every second
                                    //
                                    nSdkInstance.ggPM('setPlayheadPosition', playheadPosition);
                                    
                                    // MIDROLL
                                    nSdkInstance.ggPM('loadMetadata', midrollMetadataObject);
                                    nSdkInstance.ggPM('setPlayheadPosition', playheadPosition);
                                    //
                                    //   pass playhead every second
                                    //
                                    nSdkInstance.ggPM('setPlayheadPosition', playheadPosition);
                                    nSdkInstance.ggPM('stop', playheadPosition);
                                    
                                    // CONTENT
                                    nSdkInstance.ggPM('loadMetadata', contentMetadataObject);
                                    nSdkInstance.ggPM('setPlayheadPosition', playheadPosition);
                                    //
                                    //   pass playhead every second
                                    //
                                    nSdkInstance.ggPM('setPlayheadPosition', playheadPosition);
                                    nSdkInstance.ggPM('end', playheadPosition);
                                    
                                    // POSTROLL
                                    nSdkInstance.ggPM('loadmetadata', postrollMetadataObject);
                                    nSdkInstance.ggPM('setPlayheadPosition', playheadPosition);
                                    //
                                    //   pass playhead every second
                                    //
                                    nSdkInstance.ggPM('setPlayheadPosition', playheadPosition);
                                    nSdkInstance.ggPM('stop', playheadPosition);
                                


Interrupt Scenarios

Even when user or system interrupts playback you have to make sure that such interrupt will be handles as follows:


Pause Event

To indicate pause, stop passing the playhead position to the SDK and call STOP event. Once the content resumes, begin sending the playhead again with the correct playhead value.


Other Interrupt Scenarios

The following possible browser interruption scenarios must be handled:

  • Browser/Tab close
  • Leaving the page to another destination
  • Pressing the stop button

There are many cases where the player itself has the ability to detect such situations. If not, these interruption scenarios can be handled through JavaScript. The events that are called will depend on the asset being played (e.g. ad vs. content).

                                    window.addEventListener('beforeunload', function(event)
                                    {
                                      // indicate  inside ad
                                      nSdkInstance.ggPM('stop', playheadPosition);
                                    
                                      // indicate  and  for the content
                                      nSdkInstance.ggPM('end', playheadPosition);
                                      nSdkInstance.ggPM('stop', playheadPosition);
                                    });
Note: may need to add code to support specific browser versions (e.g. older versions of Internet Explorer).


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_P&asn=defChnAsset&fp_id=&fp_cr_tm=&fp_acc_tm=&fp_emm_tm=&ve_id=&devmodel=&manuf=&sysname=&sysversion=&sessionId=rq6kuooh0usvcuw2snmt9ksmqk46v1618835594&tl=Bunny%20in%20woods%201st%20part&prv=1&c6=vc,c04&ca=cz-509218_c04_c1&cg=myProgram&c13=asid,PDA91E2F7-078D-47EC-ACA4-2677EE94E1D1&c32=segA,NA&c33=segB,123&c34=segC,345&c15=apn,&plugv=&playerv=&sup=1&segment2=&segment1=&forward=0&ad=0&cr=4_00_99_V1_00000&c9=devid,&enc=true&c1=nuid,odjuwdfxb4v4mwivy2rlrrzrxpq7c1618823691&at=view&rt=video&c16=sdkv,bj.6.0.0&c27=cln,0&crs=&lat=&lon=&c29=plid,16188355948415206&c30=bldv,6.0.0.587&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&sd=330&devtypid=&pc=NA&c53=fef,n&c54=oad,20161013%2020%3A00%3A00&c55=cref3,&c57=adldf,1&ai=c1&c3=st,c&c64=starttm,1618835603&adid=c1&c58=isLive,false&c59=sesid,e7kads7ngvpgaqvxtbbndtse0ktrj1618835595&c61=createtm,1618835603&c63=pipMode,&c60=cvarall,p0%252Cdcrcz~~p1%252C~~p2%252CTV%2520Ident~~st%252Cc~~p4%252Creferer_demo~~~~&c68=bndlid,&nodeTM=&logTM=&c73=phtype,&c74=dvcnm,&c76=adbsnid,&c77=adsuprt,1&uoo=&evdata=&c71=ottflg,0&c72=otttyp,none&c44=progen,&davty=0&si=https%3A%2F%2Fsdkdemo.admosphere.cz%2Fdemo-browser%2FStandardAPI-video%2F1-mainDemo%2F&c66=mediaurl,&c62=sendTime,1618835603&rnd=195363


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