Domless SDK API Reference

License

Nielsen SDK contains material that is protected by copyright laws, patent laws, trade secret laws, and by international treaty provisions and is Copyright © 2024 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 provides APIs that allows our clients to integrate the Nielsen SDK in DOM-less environments, e.g., React Native, Node, etc.

DOM-less SDK Initialization

Obtain the Nielsen Application ID (apid)

The Nielsen apid is required to enable SDK functionality. Technical Account Manager will provide an apid for each player configuration. Browser 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	Value
apid	UniqueID assigned to player/site.	'XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX'
instanceName	Name of SDK instance	"any string value"
domlessEnv	Type of Dom-less environment like ReactNative, Node, etc.	"domlessEnv": "1", // For ReactNative "domlessEnv": "2", // For Amazon "domlessEnv": "3", // For NodeJS “domlessEnv”: “4”, // For Custom
deviceId	Device Identifier	Alphanumeric string eg.
nol_sdkDebug	Enables Nielsen console logging. Only required for testing	"{nol_sdkDebug: "debug"})"
optout	User optout status	"true", "false"
hem_sha256	SHA256-hashed email address (client-supplied unique 32-character hexadecimal string)	"tMmiiTI7IaAcPpQPFQ65uMVCWH8av9jw4cwf/F5HVRQ="
hem_sha1	SHA1-hashed email address (client-supplied unique 32-character hexadecimal string)	"XvBniTI7IaAcPpQPFQ65uMVCWH8av9jw4cwf/F5HVRQ="
hem_md5	MD5-hashed email address (client-supplied unique 32-character hexadecimal string)	"JnIbdTI7IaAcPpQPFQ65uMVCWH8av9jw4cwf/F5HVRQ="
uid2	An identifier based on a user’s verifiable PII (e.g. hashed email). UID2.0 was initially created by The Trade Desk (TTD) and is now managed by Prebid.	"MTKVpUAzwYAPnHrtfE0wlINOMzhU7UUEjjVdCdRu63k="
uid2_token	Encrypted Unified ID 2.0	"AgAAAAPFR0zA5ogv/yaAPiUsAdZPsfqS8Ql DSGxAB+rr8yekFs3AjLYVk5qqqiyV2XHbSuwzHmxSlLeQeK QI1mp015jsNnpX5/xGgXldcgVz+gFnyh3T8/3agMwRmyrhC xG4oH2C7fc48AQk2eotE7FW0ZDEYM8fD9ZxDaxFUC/OV3OuZA&"
luid	Living Unit ID - Experian Household ID Note: This parameter is applicable only for CTV and First Party Livestream data	"B0EOFEDgD"

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 Methods & Properties

Method/Property	Event #	DTVR	DAR	DCR	Description
play	5	✔	✘	✔	Used when there is an ID3 fed product such as DTVR and the client does not want to send in all the CMS metadata that is sent in loadMetadata. This allows the client to send in at least the required “channel name” value associated to the ID3 feed. When the client passes in the channelName, they can change the CMS data stored by passing new values. If this event is not called then the “channel name” value populated will be the default value of “defaultChannelName”.
stop	7	✘	✘	✔	Used when switching between ad and content or content and ad.
loadMetadata	15	✔	✔	✔	Used when there is a preroll ad that needs to be associated with content metadata. The loadMetadata will first be called to populate the content metadata values and then the loadMetadata for ad metadata will be called. This allows sending a content ping with the ad info, even if the user bails out during the preroll ad.
setPlayheadPosition	49	✘	✘	✔	Used to send the playhead position.
sendID3	55	✔	✘	✘	Used to send the ID3 metadata.
end	57	✔	✘	✔	This is triggered 1) at the end of the content stream, 2) if the user switches to another piece of content 3) when the browser is refreshed or closed
setVolume	61	✔	✘	✔	Used to pass in the player volume levels in %. Default value is -1.
staticstart	14	✘	✘	✔	Used to send the metadata for the static page.
staticend	56	✘	✘	✔	In Single Page Application (SPA) it is imperative that staticend is called prior to the loading of new metadata. This allows the SDK to properly credit the previous section/content being viewed before measuring the new one.
onPaginate	30	✘	✘	✔	Used to initialize the SDK object