View source for DCR Denmark Domless SDK

{{Breadcrumb|}} {{Breadcrumb|Digital}} {{Breadcrumb|International DCR}}  {{CurrentBreadcrumb}}
[[Category:Digital]]

==License==
Nielsen SDK contains material that is protected by copyright laws, patent laws, trade secret laws, and by international treaty provisions and is Copyright © 2025 The Nielsen Company (US) LLC. All intellectual property rights and licenses therein are reserved by The Nielsen Company (US) LLC and its licensors. Please read the license agreement presented [https://engineeringportal.nielsen.com/wiki/Special:ClickThrough here], which must be accepted in order to download the Nielsen SDKs. For more information, reach out to your Nielsen Technical Account Manager(TAM).

== Overview ==

The Nielsen DOM-less SDK is a Javascript based cross-platform library that provides APIs that allows our clients to integrate the Nielsen SDK in DOM-less environments, e.g. ReactNative, NodeJS, etc. The new Amazon Vega/Kepler OS was certified by Nielsen for the DOM-less SDK Integration. 

The Nielsen DOM-less SDK can be used for '''Video''' and '''Static''' measurements.

The Digital Content Ratings (DCR) Video product provides content consumption measurement on client mobile apps or webpages. This measurement includes insight into the total time a user spent watching the tracked content, video player events, and much more. This guide also includes a link to [[#Sample DOM-less SDK Implementation| github sample implementation]] with steps to implement the DCR Video product in a sample NodeJS app. It includes:
* DOM-less SDK Initialization
* DCR Video Metadata: information about the content being tracked
* DCR Video Events/API calls

==DOM-less SDK Initialization==

===Obtain the Nielsen Application ID (apid)===
The Nielsen <code>apid</code> is required to enable SDK functionality. A Technical Account Manager(TAM) will provide an apid for each player configuration.DOM-less SDK can support URLs that use any of the protocols – HTTPS and HTTP.

===Configure the DOM-less SDK===

====Installation====
Install with <code>npm install <nowiki>https://github.com/NielsenDigitalSDK/bsdk-domless</nowiki></code> 
<br> and import the <code>BsdkInstance</code> into video player component <code> import { BsdkInstance } from 'bsdk-domless' </code>

======status.ok()======

Initialization of the instance can be done with <code>status.ok()</code> function or use Promise handling approach

<syntaxhighlight lang="javascript">
const instance = await new BsdkInstance(appID, instanceName, instanceMetadata, implementationHooks);
if (instance && instance.status.ok()) {
      expect(instance).not.toBe(undefined);
      expect(instance.status.ok()).toBe(true);
}
</syntaxhighlight>

Note: Implementation Hooks are mandatory for the DOM-less SDK instance. Please refer to the Implementation Hooks section below for details.

====Exposed Interface====
The exposed interface is as follows:

1. <code>`ggPM`</code> - method to send messages to the Nielsen SDK

2. <code>`processEvent`</code> - method to send app state to the Nielsen SDK, e.g., focus, blur, appclose

===Initialization Global Parameters===
{| class="wikitable"
|+
!'''Parameter'''
!'''Description'''
!'''Required'''
!'''Value'''
|-
|apid
|UniqueID assigned to player/site.
|Yes
|'XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX'
|-
|instanceName
|Name of SDK instance
|Yes
|"any string value"
|-
|domlessEnv
|Type of DOM-less environment like ReactNative, Node, etc.
|Yes
|"domlessEnv": "1", // For ReactNative
"domlessEnv": "2", // For Amazon

"domlessEnv": "3", // For NodeJS

“domlessEnv”: “4”, // For Custom
|-
|enableFpid
|Optional:turn on or off the First Party ID
|No
|"true" for turn on,  "false" for turn off. The default value is "true".
|-
|nol_sdkDebug
|Enables Nielsen console logging. Only required for testing
|No
|"{nol_sdkDebug: "debug"}"
|-
|}

=== Implementation Hooks ===
This object captures the required entities for the DOM-less SDK to operate correctly. These are normally platform dependent and are expected to be passed on to the DOM-less SDK as part of its initialization. See below for the descriptions of each key.

==== '''log''' ====
Log the DOM-less SDK messages to an external stream, e.g. the browser console, stdout.

e.g. Log.debug('debug', 'NIELSEN TAGS EXPECTED TO FIRE:')

===== Methods =====
<blockquote>info()

Log.info(label: string, ...message: string[]): void

debug()

Log.debug(label: string, ...message: string[]): void

warn()

Log.warn(label: string, ...message: string[]): void

error()

Log.error(label: string, ...message: string[]): void</blockquote>

===== Parameters =====
<blockquote>label Required

● string - severity type, e.g. info, debug, warn, error or custom label

message Required

● string - message that will be output to the console</blockquote>

==== storage ====
Persistent storage of key/values, similar in behavior to browser localStorage.

e.g. storage.set('nol_lsid', 'umy3w4ik9usw2ppqmw2vkecckxfob1697308388')

===== Methods =====
<blockquote>set()

storage.set(key: string, value: string)

get()

storage.get(key: string)

remove()

storage.remove(key: string)

clear()

storage.clear()</blockquote>

==== fetch ====
Function to fetch resources from the network. Required for the transmission of the DOM-less SDK requests (pings) to the Nielsen endpoints.

e.g. Fetch(resource: string, options: object)

===== Parameters =====
<blockquote>resource Required

● A string that provides the URL of the resource to fetch

options Optional Object containing settings to apply to the request:

method

● string - request method: "GET", "POST". If one is not provided SDK will default to "GET"

headers

● object - headers to add to the outgoing request, an object literal with String values

body

● string - body to add to the request; SDK will send out string

mode

● string - mode for request: cors, no-cors, same-origin

referrer

● string - a string specifying the referrer of the request</blockquote>

====='''''<pre style="color: green; font-weight: bold; font-size: 20px">Note: Implementation Hooks are mandatory for the DOM-less SDK to function as expected.</pre>'''''=====

== DOM-less SDK API to send app state to the Nielsen SDK, e.g., focus, blur, appclose==

The method for calling events is <code>processEvent()</code>.

<syntaxhighlight lang="javascript">
instance.processEvent('event', parameter);
</syntaxhighlight>

* <code>`blur`</code> - This event should be passed to processEvent when the app goes to the background.

<syntaxhighlight lang="javascript">
instance.processEvent({ type: 'blur', timestamp: Date.now() });
</syntaxhighlight>

* <code>`focus`</code> - This event should be passed to processEvent when the app goes to the foreground.

<syntaxhighlight lang="javascript">
instance.processEvent({ type: 'focus', timestamp: Date.now() });
</syntaxhighlight>

* <code>`appclose`</code> - This event should be passed prior to closing the app.

<syntaxhighlight lang="javascript">
instance.processEvent({ type: 'appclose', timestamp: Date.now() });
</syntaxhighlight>

== DOM-less SDK API to send messages to the Nielsen SDK==

=== Video Measurement ===

The method for calling events is ggPM().

<syntaxhighlight lang="javascript">
instance.ggPM('event', parameter);
</syntaxhighlight>

=== Events ===
The events are included in the table below:
{| class="wikitable"
|-
! Event name !! Values to pass !!  Description !!Event #
|-
| 'loadMetadata'  || content/ad metadata object || Needs to be called at the beginning of each content/ad metadata object and after stop event when resuming '''video content''' (not after pausing and resuming an ad). ''[[DCR Denmark Video Browser SDK#Create Metadata Objects|See details on how to create Denmark specific metadata for content and ad]]''
||15
|-
| 'setPlayheadPosition'
||
* VOD: current position in seconds. Pass whole number that increments only by 1 like 0,1,2,3... <br/>
* Live: Unix timestamp matching the broadcast time for Content (seconds since Jan-1-1970 UTC). Pass whole number that increments only by 1 like 1631098029,1631098030,1631098031,1631098032,... <br/>
||
Pass playhead position every second during playback
||49
|-
| 'stop' || playhead position in seconds  || Call when ads complete playing and on pause event (when resume will be available). The playhead position must be passed when calling stop
||7
|-
| 'end' || playhead position in seconds || This event has to be called once for the current video asset at the end of the playback.
At the end of the content stream, if the user switches to another piece of content or when the browser is refreshed or closed.
||57
|}

'''Note:''' Playhead position as integer

'''Note:''' 'setPlayheadPosition' has to be called every second

==== Example Events ====


*'''Event:''' loadMetadata  |  '''Value Pass ( Object ):''' Content Metadata Object

<syntaxhighlight lang="javascript">
  instance.ggPM('loadMetadata', contentMetadataObject); 
</syntaxhighlight>


*'''Event:''' loadMetadata  |  '''Value Pass  ( Object ):''' Pre-roll AD Metadata Object

<syntaxhighlight lang="javascript">
  instance.ggPM('loadMetadata', prerollMetadataObject); 
</syntaxhighlight>


*'''Event:''' setPlayheadPosition  |  '''Value Pass ( Integer ):''' playheadPosition

<syntaxhighlight lang="javascript">
  instance.ggPM('setPlayheadPosition', playheadPosition); 
</syntaxhighlight>


*'''Event:''' stop  |  '''Value Pass ( Integer ):''' stopPlayheadPosition 

<syntaxhighlight lang="javascript">
  instance.ggPM('stop', stopPlayheadPosition); 
</syntaxhighlight>


*'''Event:''' end  |  '''Value Pass ( Integer ):''' endPlayheadPosition 

<syntaxhighlight lang="javascript">
  instance.ggPM('end', endPlayheadPosition); 
</syntaxhighlight>

==== Sample DOM-less SDK Implementation ====

* Sample Implementation on github [https://github.com/NielsenDigitalSDK/bsdk-domless here].

==== Review SDK Integration Architecture Diagram ====

===== For Content Playback =====

[[File:nlsn-sdk-achitecture-diagram-content-v1.png||SDK Integration Architecture Diagram - Content]]

===== For Ad Playback =====
[[File:nlsn-sdk-achitecture-diagram-ad-v1.png||SDK Integration Architecture Diagram - Ad]]

==== Review SDK Interrupt Scenarios ====
* [[DCR Denmark Video Browser SDK#Handle Video Playback Interruption|Handle Video Playback Interruption]]

==== Review SDK Event Lifecycle ====
* [[DCR Denmark Video Browser SDK#SDK Call Sequence |SDK Call Sequence ]]


== Disclose Nielsen Privacy Statement ==

The Browser SDK video measurement does not set cross-domain cookies, therefore no centralized opt-out functionality is available. The Nielsen Browser SDK does not set cookies associated with the collection domain. The SDK sets specific cookie for the domain where the player is hosted (first party) and this cookie is not used across websites.
The only personal information collected with the SDK network pings is the IP address, which is  anonymized immediately after collection.

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.
* A link to the Nielsen Digital Measurement Privacy Policy located at https://nielsen.com/legal/privacy-principles/digital-measurement-privacy-statement/?lang=da .

=== Turning off the First Party ID for Opt-out Users during the SDK Initialization ===
The First Party ID(FPID) is enabled by default in the Browser SDK. For Opt-out users, the First Party ID can be turned off during the initialization of the SDK Instance, i.e. the parameter enableFpid can be set to "false" (FPID disabled) or "true" (FPID enabled). See [[#Initialization Global Parameters|SDK Initialization Global Parameters]].


== Certification ==

While Nielsen is working on adding Support to the Certification Tool for DOM-less SDK in the future, the Certification process for the DOM-less will require detailed SDK Logs from a MMS Client integrating Nielsen DOM-less SDK. In this regard, a client will execute test cases locally and share logs for each test case with a Nielsen Technical Account Manager in charge of the Certification. 

== Going Live ==
Following Nielsen testing, disable Nielsen SDK logging by adjusting the Nielsen SDK Initialization Call, this will ensure that the App or Website is being measured properly.
# '''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">
const instance = new BsdkInstance(
        nsdkConfig.app_id,
        nsdkConfig.instance_name,
        {
            appName: 'BSDK RN Sample App',
            domlessEnv: '1'// "1" for React Native | "2" for Amazon | "3" for NodeJS | "4" for Custom
            // reference SDK interface documentation
            // for additional metadata properties
        },
    implementationHooks
);
</syntaxhighlight>


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