DCR Sweden Domless SDK

Engineering Portal / Digital / International DCR / DCR Sweden Domless SDK

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

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'	VOD: current position in seconds. Pass whole number that increments only by 1 like 0,1,2,3... 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,...	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

• Handle Video Playback Interruption

Review SDK Event Lifecycle

• SDK Call Sequence

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.

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