DCR Germany Static Browser SDK: Difference between revisions

From Engineering Client Portal
No edit summary
 
(4 intermediate revisions by the same user not shown)
Line 74: Line 74:


== Step 3: Create Metadata Object ==
== Step 3: Create Metadata Object ==
 
The full description of the other key/value pairs for Metadata can be found here:
{| class="wikitable"
'''[[AGF Metadata Convention#Static Measurement|AGF Metadata Convention for Static Measurement]]'''
|-
! Key !! Description !! Values !! Required (Obligatory)
|-
| assetid || unique ID assigned to each article/page; only characters 0-9, a-z, A-Z underscore and minus are allowed - no special characters or vowel mutations) || custom (no [[Special Characters]])|| ✓
|-
| section || section of each site (e.g. section value should be first level in page URL: website.com/section) || custom || ✓
|-
| segA ||  custom segment for reporting: unique values across custom segments (segA + segB + segC) || custom || ✓
|-
| segB ||  custom segment for reporting: unique values across custom segments (segA + segB + segC) || custom ||
|-
| segC ||  custom segment for reporting: unique values across custom segments (segA + segB + segC) || custom ||
|-
| subbrand ||  vcid/sub-brand ID – value is automatically populated through provided App ID. In order to override the sub-brand configured to the App ID, value can be passed here (e.g. multiple sub-brands in App) || provided by Nielsen ||
|}
=== Example Web Page Metadata Object ===
=== Example Web Page Metadata Object ===
<syntaxhighlight lang="html">
<syntaxhighlight lang="html">
Line 99: Line 84:
section:  "Unique_section_ID",  
section:  "Unique_section_ID",  
     segA: "Unique_section_segA",  
     segA: "Unique_section_segA",  
     segB: "Optional_section_segB",
     segB: "Mandatory_section_segB",
     segC: "Optional_section_segC",
     segC: "Optional_section_segC",
     subbrand: "subbrand_received_from_Nielsen"
     subbrand: "subbrand_received_from_Nielsen"
Line 114: Line 99:


The content metadata object is passed as a parameter.
The content metadata object is passed as a parameter.
<br>
<blockquote>
[[Image:AlertIcon.png|left|60px|link=|class=smallIcon]] When using the same Browser SDK instance to measure different pages, Call <code>"staticend"</code> to stop the static measurement of the current page before starting a new measurement with <code>"staticstart"</code> for the next page.'''
</blockquote>
== Step 5: Include the measurement of Advertising Medium (Werbeträger) if applicable  ==
=== Description ===
A page impression is a user action on the page that leads or could lead to an advertisement being called up. Each user action may only be counted once.
However, a page impression occurs when the content of the viewport of the respective device is completely reloaded/rendered by scrolling/swiping and replaced by new
content.
When counting views, a distinction is made between content
views (CPI) and advertising medium views after a user action (WPI). There can be
only one content view per page. Each additional user action on the same page (click,
scroll or swipe, e.g. click through an image gallery) will lead to an advertising medium view (WPI) accordingly. The implementation should follow the IVW guidelines for
defining user actions.
'''Note''':
The differentiation between the measurement of Content vs. advertising medium is achieved by setting accordingly the "segB" value in the metadata object  , see '''[[AGF Metadata Convention#Static Measurement|AGF Metadata Convention for Static Measurement]]'''
=== Implementation Details ===
How to trigger a page impression for advertising medium?
In order to trigger a a new view for an advertising medium, you have to stop the measurement of the page and start the measurement of the advertising medium, see example code below:
* Stop static measurement for the page(current metadata):
<syntaxhighlight lang="javascript">
  // Event 'staticend' Call
  nSdkInstance.ggPM("staticend", window.articlemetadata);
</syntaxhighlight>
* Start static measurement for the advertising medium after user interaction(new metadata):
<syntaxhighlight lang="javascript">
  // Event 'staticstart' Call
  nSdkInstance.ggPM("staticstart", window.adMediummetadata);
</syntaxhighlight>
== Step 6: Implement bfcache detection for mobile devices (i.e. back button) ==
On mobile devices some content can be loaded by the browser from the cache on mobile devices and in this case no Browser SDK measurement will occur.
Please use the 'Pagehow' event in order to enable the browser SDK measurement by calling browser SDK (BSDK) APIs. Namely end the current measurement("staticend") and then start a new measurement for the page loaded from bfcache ("staticstart"): see simple example below.
<syntaxhighlight lang="javascript">
function bfcacheHandler() {
//Use 'pageshow' event in order to control Nielsen Browser SDK
//This is the addEventListener for detecting bfcache.
window.addEventListener("pageshow", (event) => {
if (event.persisted) {
console.log("This page was restored from the bfcache.");
// glaobal Browser SDK Instance used to measure all pages
//## window.nSdkInstance
// terminate the measurement of the previous page
window.nSdkInstance.ggPM("staticend", previousarticlemetadata);
// start the measurement of the new page loaded from bfcache
window.nSdkInstance.ggPM("staticstart", newarticlemetadata);
} else {
console.log("This page was loaded normally.");
}
});
}
</syntaxhighlight>


== Step 5: Review Privacy and Opt-Out ==
== Step 7: Review Privacy and Opt-Out ==
The Browser SDK measurement is working without cookies and other personal information. No user can be identified personally, therefore an opt-out functionality is not required. The Nielsen Browser SDK measurement is utilizing a cookieless domain.
The Browser SDK measurement is working without cookies and other personal information. No user can be identified personally, therefore an opt-out functionality is not required. The Nielsen Browser SDK measurement is utilizing a cookieless domain.


In order to disclose Nielsen measurement privacy statement, please include the following items in your privacy policy:
In order to disclose Nielsen measurement privacy statement, please include the following items in your privacy policy:
* A notice that the player includes third party measurement software that allows users to contribute to market research with anonymous data.
* A notice that the player includes third party measurement software that allows users to contribute to market research with anonymous data.
* A link to the Nielsen Digital Measurement Privacy Policy located at https://www.nielsen.com/de/de/legal/privacy-statement/digital-measurement/ .
* A link to the Nielsen Digital Measurement Privacy Policy located at https://nielsen.com/legal/privacy-principles/digital-measurement-privacy-statement/?lang=de .


==Step 6:  Testing ==
==Step 8:  Testing ==
'''Monitoring Tools'''
'''Monitoring Tools'''
Testing the Browser Implementation
Testing the Browser Implementation
Line 128: Line 179:
The steps to test the implementation are given below.
The steps to test the implementation are given below.


'''Step 6.1'''
'''Step 8.1'''


Filter HTTP traffic with the string "nmr" to capture traffic from the SDK. This will capture traffic going to Nielsen servers.
Filter HTTP traffic with the string "nmr" to capture traffic from the SDK. This will capture traffic going to Nielsen servers.


'''Step 6.2'''
'''Step 8.2'''


Verify that the Nielsen SDK is being downloaded correctly and is the correct version.
Verify that the Nielsen SDK is being downloaded correctly and is the correct version.
Line 138: Line 189:




'''Step 6.3'''
'''Step 8.3'''


When the page is loaded for the first time, the Browser SDK fires a View ping as soon as content is loaded. Utilizing your HTTP traffic filter tool, you can now validate the metadata that is being sent to the Nielsen collection servers.
When the page is loaded for the first time, the Browser SDK fires a View ping as soon as content is loaded. Utilizing your HTTP traffic filter tool, you can now validate the metadata that is being sent to the Nielsen collection servers.
Line 145: Line 196:
<syntaxhighlight lang="html">https://secure-eu.nmrodam.com/cgi-bin/gn?prd=dcr&ci=us-500207&ch=us-500207_c77_Main-GTM_P&asn=Main-GTM&sessionId=8l2XGnAW6IC3Cc2MIMh0RYRTqimuU1553108759&prv=1&c6=vc,c77&ca=NA&c13=asid,P00BEB680-1F1A-47BB-922D-1BD2F1BA79A7&c32=...</syntaxhighlight>
<syntaxhighlight lang="html">https://secure-eu.nmrodam.com/cgi-bin/gn?prd=dcr&ci=us-500207&ch=us-500207_c77_Main-GTM_P&asn=Main-GTM&sessionId=8l2XGnAW6IC3Cc2MIMh0RYRTqimuU1553108759&prv=1&c6=vc,c77&ca=NA&c13=asid,P00BEB680-1F1A-47BB-922D-1BD2F1BA79A7&c32=...</syntaxhighlight>


'''Step 6.4'''
'''Step 8.4'''


The first duration ping is fired after 5 minutes of content is viewed and is indicated by the cr value containing a D. This should fire every 5 minutes but only when the page is in focus.
The first duration ping is fired after 5 minutes of content is viewed and is indicated by the cr value containing a D. This should fire every 5 minutes but only when the page is in focus.
Line 155: Line 206:




== Step 7: Going Live ==
== Step 9: 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.
Following Nielsen testing, users need to make a couple of updates to the initialization call to ensure that the site is being measured properly.
# '''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.
Line 168: Line 219:
'''Note''': before going live you have to inform Nielsen - this is necessary, because Nielsen team has to adjust internal configuration parameter to enable data collection. Without that notification no data will be collected and no data will be reported.
'''Note''': before going live you have to inform Nielsen - this is necessary, because Nielsen team has to adjust internal configuration parameter to enable data collection. Without that notification no data will be collected and no data will be reported.


== Step 8: Review the Sample Implementation for your Reference ==
== Step 10: Review the Sample Implementation for your Reference ==
The Sample Implementation for AGF located [https://nielsenonlinesupport.com/agf/sdkRefImpStaticDE/bsdkstatic.htm here].
The Sample Implementation for AGF located [https://nielsenonlinesupport.com/agf/sdkRefImpStaticDE/bsdkstatic.htm here].

Latest revision as of 11:15, 14 July 2023

Engineering Portal / Digital / AGF Implementation Documentation / DCR Germany 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 Browser SDK is the framework for browsers developers to integrate Nielsen Measurement into their Web pages. It supports static content measurement and can track key life cycle events of pages like:

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

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 AppID is needed. The AppID is a unique ID assigned to the player/site/app. This will be provided upon starting the integration from Nielsen. 

  apid: "XXXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX" // eg. PDA7D5EE6-B1B8-XXXX-XXXX-2A788BCXXXCA

Step 1: Add 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.

Add the following script tag to the website i.e. within the <head></head> tag : 

	// Add 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.nmrodam.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");


Step 2: Create SDK Instance

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

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


The initialization call has the below parameters:

Parameter Description Required Values
apid Unique ID assigned to player/site Yes 'PXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX'
instanceName Name of SDK instance Yes "any string value"
nol_sdkDebug Enables Nielsen console logging. Only required for testing No "{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".

Step 3: Create Metadata Object

The full description of the other key/value pairs for Metadata can be found here: AGF Metadata Convention for Static Measurement

Example Web Page Metadata Object

<script>
  window.articlemetadata = {
    type: "static",
    assetid: "Unique_page_ID", 
	section:  "Unique_section_ID", 
    segA: "Unique_section_segA", 
    segB: "Mandatory_section_segB",
    segC: "Optional_section_segC",
    subbrand: "subbrand_received_from_Nielsen"
    };
</script>

Step 4: Call staticstart Event

Start static measurement : 

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

The content metadata object is passed as a parameter.

AlertIcon.png

When using the same Browser SDK instance to measure different pages, Call "staticend" to stop the static measurement of the current page before starting a new measurement with "staticstart" for the next page.

Step 5: Include the measurement of Advertising Medium (Werbeträger) if applicable

Description

A page impression is a user action on the page that leads or could lead to an advertisement being called up. Each user action may only be counted once.

However, a page impression occurs when the content of the viewport of the respective device is completely reloaded/rendered by scrolling/swiping and replaced by new content.

When counting views, a distinction is made between content views (CPI) and advertising medium views after a user action (WPI). There can be only one content view per page. Each additional user action on the same page (click, scroll or swipe, e.g. click through an image gallery) will lead to an advertising medium view (WPI) accordingly. The implementation should follow the IVW guidelines for defining user actions.

Note: The differentiation between the measurement of Content vs. advertising medium is achieved by setting accordingly the "segB" value in the metadata object , see AGF Metadata Convention for Static Measurement

Implementation Details

How to trigger a page impression for advertising medium? In order to trigger a a new view for an advertising medium, you have to stop the measurement of the page and start the measurement of the advertising medium, see example code below:

  • Stop static measurement for the page(current metadata):
  // Event 'staticend' Call
  nSdkInstance.ggPM("staticend", window.articlemetadata);
  • Start static measurement for the advertising medium after user interaction(new metadata):
  // Event 'staticstart' Call
  nSdkInstance.ggPM("staticstart", window.adMediummetadata);


Step 6: Implement bfcache detection for mobile devices (i.e. back button)

On mobile devices some content can be loaded by the browser from the cache on mobile devices and in this case no Browser SDK measurement will occur. Please use the 'Pagehow' event in order to enable the browser SDK measurement by calling browser SDK (BSDK) APIs. Namely end the current measurement("staticend") and then start a new measurement for the page loaded from bfcache ("staticstart"): see simple example below. 

function bfcacheHandler() {
//Use 'pageshow' event in order to control Nielsen Browser SDK

//This is the addEventListener for detecting bfcache.

window.addEventListener("pageshow", (event) => {
if (event.persisted) {
console.log("This page was restored from the bfcache.");
// glaobal Browser SDK Instance used to measure all pages
//## window.nSdkInstance
// terminate the measurement of the previous page
window.nSdkInstance.ggPM("staticend", previousarticlemetadata);
// start the measurement of the new page loaded from bfcache
window.nSdkInstance.ggPM("staticstart", newarticlemetadata);
} else {
console.log("This page was loaded normally.");
}
});
}

Step 7: Review Privacy and Opt-Out

The Browser SDK measurement is working without cookies and other personal information. No user can be identified personally, therefore an opt-out functionality is not required. The Nielsen Browser SDK measurement is utilizing a cookieless domain.

In order to disclose Nielsen measurement privacy statement, please include the following items in your privacy policy:

Step 8: Testing

Monitoring Tools Testing the Browser Implementation

The steps to test the implementation are given below.

Step 8.1

Filter HTTP traffic with the string "nmr" to capture traffic from the SDK. This will capture traffic going to Nielsen servers.

Step 8.2

Verify that the Nielsen SDK is being downloaded correctly and is the correct version. 

http://cdn-gl.nmrodam.com/novms/js/2/nlsSDK600.bundle.min.js


Step 8.3

When the page is loaded for the first time, the Browser SDK fires a View ping as soon as content is loaded. Utilizing your HTTP traffic filter tool, you can now validate the metadata that is being sent to the Nielsen collection servers.

Example View Ping Below: 

https://secure-eu.nmrodam.com/cgi-bin/gn?prd=dcr&ci=us-500207&ch=us-500207_c77_Main-GTM_P&asn=Main-GTM&sessionId=8l2XGnAW6IC3Cc2MIMh0RYRTqimuU1553108759&prv=1&c6=vc,c77&ca=NA&c13=asid,P00BEB680-1F1A-47BB-922D-1BD2F1BA79A7&c32=...

Step 8.4

The first duration ping is fired after 5 minutes of content is viewed and is indicated by the cr value containing a D. This should fire every 5 minutes but only when the page is in focus. 

http://secure-eu.nmrodam.com/cgi-bin/gn?prd=dcr&st=dcr&rt=text&forward=0&sup=0
&ad=0&asn=%2Fsdk2%2Findex2.html&ci=us-500270&c6=vc,c77&c9=devid,&c11=agg,1
&c12=apv,3&c13=asid,PAA3A8EF7-E6D2-4A9E-9787-BDXXXXXXXXXX&c15=apn,Test2
&c16=sdkv,bj.5.1.5&c26=dmap,1&c29=plid,14767465028039340&c30=bldv,1.0.0.15&c32=segA,USA
&c33=segB,CA&c34=segC,RSM&at=timer&cr=D&c27=cln,300&rnd=857576


Step 9: 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. 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("P14273221-CF5C-46BF-A832-994AEFB7XXXX");


Note: before going live you have to inform Nielsen - this is necessary, because Nielsen team has to adjust internal configuration parameter to enable data collection. Without that notification no data will be collected and no data will be reported.

Step 10: Review the Sample Implementation for your Reference

The Sample Implementation for AGF located here.

Retrieved from "https://engineeringportal.nielsen.com/w/index.php?title=DCR_Germany_Static_Browser_SDK&oldid=6414"