DCR Sweden Domless SDK
From Engineering Client Portal
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 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 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 apid 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 npm install https://github.com/NielsenDigitalSDK/bsdk-domless
and import the BsdkInstance into video player component import { BsdkInstance } from 'bsdk-domless'
status.ok()
Initialization of the instance can be done with status.ok() function or use Promise handling approach
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);
}
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. `ggPM` - method to send messages to the Nielsen SDK
2. `processEvent` - method to send app state to the Nielsen SDK, e.g., focus, blur, appclose
Initialization Global Parameters
| 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 |
| hem_unknown | Hashed email using SHA512. This email is used by the MMS reach model. | Required if login feature | {hem_unknown: "924899b875ea6767ab790bd2f4852345fcfec5d203c49be8e8..."}
|
| optout | OptOut global parameter. This optout will be maintained through the session of the SDK instance | Yes | "true" for opted out, "false" for NOT opted out or opted in. The default value is "false". |
| 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
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
Parameters
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
storage
Persistent storage of key/values, similar in behavior to browser localStorage.
e.g. storage.set('nol_lsid', 'umy3w4ik9usw2ppqmw2vkecckxfob1697308388')
Methods
set()
storage.set(key: string, value: string)
get()
storage.get(key: string)
remove()
storage.remove(key: string)
clear()
storage.clear()
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
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
Note: Implementation Hooks are mandatory for the DOM-less SDK to function as expected.
DOM-less SDK API to send app state to the Nielsen SDK, e.g., focus, blur, appclose
The method for calling events is processEvent().
instance.processEvent('event', parameter);
`blur`- This event should be passed to processEvent when the app goes to the background.
instance.processEvent({ type: 'blur', timestamp: Date.now() });
`focus`- This event should be passed to processEvent when the app goes to the foreground.
instance.processEvent({ type: 'focus', timestamp: Date.now() });
`appclose`- This event should be passed prior to closing the app.
instance.processEvent({ type: 'appclose', timestamp: Date.now() });
DOM-less SDK API to send messages to the Nielsen SDK
Video Measurement
The method for calling events is ggPM().
instance.ggPM('event', parameter);
Events
The events are included in the table below:
| 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). See details on how to create MMS metadata for content and ad | 15 |
| 'setPlayheadPosition' |
|
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
instance.ggPM('loadMetadata', contentMetadataObject);
- Event: loadMetadata | Value Pass ( Object ): Pre-roll AD Metadata Object
instance.ggPM('loadMetadata', prerollMetadataObject);
- Event: setPlayheadPosition | Value Pass ( Integer ): playheadPosition
instance.ggPM('setPlayheadPosition', playheadPosition);
- Event: stop | Value Pass ( Integer ): stopPlayheadPosition
instance.ggPM('stop', stopPlayheadPosition);
- Event: end | Value Pass ( Integer ): endPlayheadPosition
instance.ggPM('end', endPlayheadPosition);
Sample DOM-less SDK Implementation
- Sample Implementation on github here.
Review SDK Integration Architecture Diagram
For Content Playback
For Ad Playback
Review SDK Interrupt Scenarios
Review SDK Event Lifecycle
Privacy and Opt-Out
The site must provide a means for the user to opt-out of, or opt back into, Nielsen Measurement. Users can opt out if they prefer not to participate in any Nielsen online measurement research. To implement the User Opt-Out option, include the following two items in your privacy policy.
- A notice that the player (or page in relation to static measurement) 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 at https://www.nielsen.com/legal/privacy-principles/digital-measurement-privacy-statement/?lang=sv (or for English: https://nielsen.com/legal/privacy-principles/digital-measurement-privacy-statement/?lang=en-se)
- We have two separate entities registered with the IAB TCF, Nielsen Marketing Cloud and Nielsen LLC. The one that is relevant to Swedish measurement is Nielsen LLC (ID: 812) and not NMC.
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 via this link, their browser cookies will contain the value TOTAL_OPTOUT. This will prevent a redirect to our data provider from occurring
- Users can opt back in via this link. When a user selects that link, their opt-out cookie will be deleted and they will be able to be measured moving forward.
The following paragraph is a template for a Privacy Statement.
The properties may feature Nielsen proprietary measurement software, allowing users to contribute to market research, such as Nielsen TV Ratings. To learn more about the information that Nielsen software may collect and your choices concerning it, please see the Nielsen Digital Measurement Privacy Policy at https://nielsen.com/legal/privacy-principles/digital-measurement-privacy-statement/?lang=sv
User Opt Back In
Once users have opted-out, they can choose to opt back into Nielsen Measurement at any time 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.
Turning off the First Party ID for Opt-out Users during the SDK Initializazion
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 SDK Initialization Global Parameters.
Setting the SDK global optout Flag for Opt-out Users during the SDK Initialization
The optout Flag is set by default to "false" in the Browser SDK. For Opt-out users, the optout Flag can be set to "true" during the initialization of the SDK Instance, i.e. the parameter optout can be set to "true" (opted out) or "false" (opted in or NOT opted out). See 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
{nol_sdkDebug: 'debug'}from initialization call.
Example Production Initialization Call
Refer to the production initialization call below:
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
);
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.