Engineering Client Portal - User contributions [en]

TVOS SDK Release Notes

2026-03-24T14:14:32Z

AmySockanathan: Update TVOS page with all release notes.

{{Breadcrumb|}} {{Breadcrumb|Digital}} {{CurrentBreadcrumb}}
[[Category:Digital]]
__NOTOC__
== Release 10.2.0.0 (03-24-2026) ==

* iOS Digital Signature Certificate Renewal
* Fixes for Viewabiity defects
* Ad length warning - Fixed the ad tracking logic so now, the 300-second warning will only fire if the current ad actually plays for more than 5 minutes, and that error state will no longer bleed over into the next ad.
* SDK Code Signature fix (Global Flavor only) - The Global direct binary available on the Engineering Portal now correctly includes the SDK code signature for manual integrations.

== Release 10.1.0.0 (10-17-2025) ==

* Support for FPID multi-instance integrations.
* Support for Flutter cross-platform plugin.
* Support for Apple's iOS26/tvOS26 Log Visibility Changes.
* Other bug fixes and enhancements.

== Release 10.0.0.0 (04-04-2025) ==

* Support for DTVR Subminute product.
* Support for DCR video playhead bridging.
* Support for VisionOS platform.
* Change in DemographicID behavior for Chromecast.
* Other bug fixes and enhancements.

== Release 9.4.0.0 (07-09-2024) ==

* Support for privacy manifest with content tracking domain for Ad flavors.
* Support for content tracking and no-tracking domains across sdk flavors and products.
* Other bug fixes and enhancements.

== Release 9.3.0.0 (05-10-2024) ==

* Support for privacy manifest with tracking domain for Ad flavors.
* Support for capturing user opt-out during initialization.
* Other bug fixes and enhancements.

== Release 9.2.0.0 (9-27-2023) ==
*Support for privacy manifest and required reason API introduced in XCode 15.
*Digitally signed SDK framework per Apple recommendation
*DCR Static recognizing metadata with changed assetID for new impressions.
*Limiting ping retries during https failures.
*Other bug fixes and enhancements.

== Release 9.1.0.0 (3-31-2023) ==
*DCR Static duration measurement for AppSDK (currently only AGF).
*Removed use of iOS keychains, started using NSUserDefaults for persistent storage.
*Viewability: allow enabling by product (DCR, DTVR).
*Other bug fixes and enhancements.

== Release 9.0.0.0 (10-07-2022) ==
* Viewability measurement for DTVR, DCR Content and DCR Ad products.
* Audibility measurement for DTVR, DCR Content and DCR Ad products.
* SDK built with XCode 14.
* Other bug fixes and enhancements.

== Release 8.2.0.0 (03-21-2022) ==
* Adopting Swift language internally, built on a mixed model (Swift+Objective C).
* Support for Swift markers to help Swift developers.
* Removed the usage of deprecated iOS network reachability class.
* Disabled iCloud backup/synchronization of SDK keychain items.
* Other bug fixes and enhancements.

== Release 8.1.0.0 (06-28-2021) ==
* Support for XCFramework build distribution.
* Support for MacOS Catalyst platform framework.
* Fixed the device classification for MacOS M1 measurement.
* Support to capture Hashed email and UID.
* Support to collect SDK diagnostic data.
* Other bug fixes and enhancements.

== Release 8.0.0.0 (10-05-2020) ==
* iOS 14 App Transparency Framework support.
* FPID and VendorID support.
* Fixed the device classification for iPADOS measurement.
* Support for Xamarin cross platform framework.
* Other bug fixes and enhancements.

== Release 7.2.0.0 (05-18-2020) ==
* DTVR AQH and IVD requirements for End and pause timeout.
* Support for Hybrid app webview measurement.
* Support for Hybrid app react native webview measurement.
* Support for React Native measurement.
* Other bug fixes and enhancements

== Release 7.1.0.0 (12-09-2019) ==
* Removed usage of deprecated class UIWebView
* Offline viewing measurement enhancements
* Fixed deadlock on SDK shutdown
* Revisited precedence logic for sfcode parameter
* Fix for DCR individual ad pings parameters after channel change
* Using default value for incorrect adModel parameter
* Defaulting isLive parameter value on channel change
* Other fixes and enhancements.

== Release 7.0.0.0 (09-06-2019) ==
* Support for CDN based config.
* Support for Market based EMM UAID pings.
* Changes required for proper DCR Static measurement in multi-instance/multiple appid's case.
* Fixes for OTT synchronization issues between iOS and Android platforms.
* Fixes for EV data parameters in few scenarios.
* Fixes for DCR Static product behaviour in background app refresh and background fetch scenarios.
* DCR Ad reporting improvements.
* Fixes and improvements for the SDK console log messages.
* Other enhancements and fixes.

== Release 6.2.0.0 (02-04-2019) ==
* Introduced Dynamic framework for SDK.
* Removal of Location Module from SDK Code.
* Increased SDK log file size for Debug mode.
* Removed OTT Airplay/mirroring detection that caused crashes in AVAudioSession class.
* DCR performance improvements.
* Fixed the parsing error happening when clientid/vcid provided as empty in metadata.
* Align AppSDK for FW detection with BSDK for DCR measurement.
* Other Bug Fixes/Enhancements.

== Release 6.1.0.1 (9-13-2018) ==
*Nielsen SDK support for Xcode 10 and tvOS 12

== Release 6.0.0.4 (5-24-2018) ==
*If the SDK build target is set to AGF then SDK will send the hello ping to “eu” and “eu-uat” for debug builds. No changes to the non AGF build the default sfcode will continue to be "sdk" and "cert" for debug build.
*The C1 parameter (NUID) will now be sent as encrypted DeviceID.
*New SessionID changes. The sessionID will contain 29 length random characters appended by timestamp.
*Support for multiple SDK instance without any limit.
*New log feature for CAT tool to retrieve the API level information from client apps. This ping will contain the eventType, parameters, SDK version, appid etc.
*Removed Viewability for this release.

== Release 5.1.1.17 (1-23-2017) ==
*Added "seconds" place to the launch ping
*Ability to opt-out using "Limit Ad Tracking" feature
*Improved CPU Performance while apps are running in background
*Opt-Out pages can be served based on user’s language and locale from device

== Release 5.1.1.12 (12-14-2016) ==
*Support for Nielsen TV Brand Effect
*Ability to set CMS parameters at a more global level
*Opt-out pages based on locale and country
*Opt-out policy based on the "Limit Ad Tracking" flag
*Collection of additional device information
*Issue a warning in client developer’s console when ad is played for more than 5 minutes
*Removed the requirement for “type” parameter
*Limit the duration reported for App launch

== Release 5.1.1.7 (9-13-2016) ==
*General bug fix and performance improvements

== Release 5.1.1.5 (7-12-2016) ==
*Includes a sample TVOS application used to assist during integration.
*Support for TVML based optout pages
*General bug fix and performance improvements

== Release 5.1.0.7 (6-15-2016) ==
*Combined SDK for DCR US and International (Germany)
*API to signal end of content (end API)
*Support for Pause timeout
*Updated API to support JSON object instead of string.
*Reporting of media URL and bundle ID
*Updated ping retry logic
*Changes in OptOut process behavioral
*Enhanced Debugging and SDK logging
*Changes to API signature

iOS SDK Release Notes

2026-03-23T14:25:37Z

AmySockanathan: Changed the release date of 10.2 to 3/24/2026

[[Category:Digital]]
__NOTOC__

{{Breadcrumb|}} {{Breadcrumb|Digital Downloads}} {{CurrentBreadcrumb}}

== Release 10.2.0.0 (03-24-2026) ==
*iOS Digital Signature Certificate Renewal
*Fixes for Viewabiity defects
*Ad length warning - Fixed the ad tracking logic so now, the 300-second warning will only fire if the current ad actually plays for more than 5 minutes, and that error state will no longer bleed over into the next ad.
*SDK Code Signature fix (Global Flavor only) - The Global direct binary available on the Engineering Portal now correctly includes the SDK code signature for manual integrations.

== Release 10.1.0.0 (10-17-2025) ==
*Support for FPID multi-instance integrations.
*Support for Flutter cross-platform plugin.
*Support for Apple's iOS26/tvOS26 Log Visibility Changes.
*Other bug fixes and enhancements.

== Release 10.0.0.0 (04-04-2025) ==
*Support for DTVR Subminute product.
*Support for DCR video playhead bridging.
*Support for VisionOS platform.
*Change in DemographicID behavior for Chromecast.
*Other bug fixes and enhancements.

== '''Release 9.4.0.0 (07-09-2024)''' ==
*Support for privacy manifest with content tracking domain for Ad flavors.
*Support for content tracking and no-tracking domains across sdk flavors and products.
*Other bug fixes and enhancements.
== Release 9.3.0.0 (05-10-2024) ==
*Support for privacy manifest with tracking domain for Ad flavors.
*Support for capturing user opt-out during initialization.
*Other bug fixes and enhancements.
== Release 9.2.0.0 (9-27-2023) ==
*Support for privacy manifest and required reason API introduced in XCode 15.
*Digitally signed SDK framework per Apple recommendation
*DCR Static recognizing metadata with changed assetID for new impressions.
*Limiting ping retries during https failures.
*Other bug fixes and enhancements.

== Release 9.1.0.0 (3-31-2023) ==
*DCR Static duration measurement for AppSDK (currently only AGF).
*Removed use of iOS keychains, started using NSUserDefaults for persistent storage.
*Viewability: allow enabling by product (DCR, DTVR).
*Other bug fixes and enhancements.

== Release 9.0.0.0 (10-07-2022) ==
* Viewability measurement for DTVR, DCR Content and DCR Ad products.
* Audibility measurement for DTVR, DCR Content and DCR Ad products.
* SDK built with XCode 14.
* Other bug fixes and enhancements.

== Release 8.2.0.0 (03-21-2022) ==
* Adopting Swift language internally, built on a mixed model (Swift+Objective C).
* Support for Swift markers to help Swift developers.
* Removed the usage of deprecated iOS network reachability class.
* Disabled iCloud backup/synchronization of SDK keychain items.
* Other bug fixes and enhancements.

== Release 8.1.0.0 (06-28-2021) ==
* Support for XCFramework build distribution.
* Support for MacOS Catalyst platform framework.
* Fixed the device classification for MacOS M1 measurement.
* Support to capture Hashed email and UID.
* Support to collect SDK diagnostic data.
* Other bug fixes and enhancements.

== Release 8.0.0.0 (10-05-2020) ==
* iOS 14 App Transparency Framework support.
* FPID and VendorID support.
* Fixed the device classification for iPADOS measurement.
* Support for Xamarin cross platform framework.
* Other bug fixes and enhancements.

== Release 7.2.0.0 (05-18-2020) ==
* DTVR AQH and IVD requirements for End and pause timeout.
* Support for Hybrid app webview measurement.
* Support for Hybrid app react native webview measurement.
* Support for React Native measurement.
* Other bug fixes and enhancements

== Release 7.1.0.0 (12-09-2019) ==
* Removed usage of deprecated class UIWebView
* Offline viewing measurement enhancements
* Fixed deadlock on SDK shutdown
* Revisited precedence logic for sfcode parameter
* Fix for DCR individual ad pings parameters after channel change
* Using default value for incorrect adModel parameter
* Defaulting isLive parameter value on channel change
* Other fixes and enhancements.

== Release 7.0.0.0 (09-06-2019) ==
* Support for CDN based config.
* Support for Market based EMM UAID pings.
* Changes required for proper DCR Static measurement in multi-instance/multiple appid's case.
* Fixes for OTT synchronization issues between iOS and Android platforms.
* Fixes for EV data parameters in few scenarios.
* Fixes for DCR Static product behaviour in background app refresh and background fetch scenarios.
* DCR Ad reporting improvements.
* Fixes and improvements for the SDK console log messages.
* Other enhancements and fixes.

== Release 6.2.0.0 (02-04-2019) ==
* Introduced Dynamic framework for SDK.
* Removal of Location Module from SDK Code.
* Increased SDK log file size for Debug mode.
* Removed OTT Airplay/mirroring detection that caused crashes in AVAudioSession class.
* DCR performance improvements.
* Fixed the parsing error happening when clientid/vcid provided as empty in metadata.
* Align AppSDK for FW detection with BSDK for DCR measurement.
* Other Bug Fixes/Enhancements.

== Release 6.1.0.1 (9-13-2018) ==
*Support added for Video On Demand in TV Ratings
*Support for Xcode 10 and iOS 12

== Release 6.0.0.4 (5-24-2018) ==
*If the SDK build target is set to AGF then SDK will send the hello ping to “eu” and “eu-uat” for debug builds. No changes to the non AGF build the default sfcode will continue to be "sdk" and "cert" for debug build.
*The C1 parameter (NUID) will now be sent as encrypted DeviceID.
*New SessionID changes. The sessionID will contain 29 length random characters appended by timestamp.
*Support for multiple SDK instance without any limit.
*New log feature for CAT tool to retrieve the API level information from client apps. This ping will contain the eventType, parameters, SDK version, appid etc.
*Removed Viewability for this release.

== Release 5.1.1.29 (7-31-2017) ==
*Genre parameter will be a part of DCR pings and the value will be reflected as part of c44 parameter.
*Merged adModel and adLoadType flags
*Fix for stop event data carried to next session’s duration ping

== Release 5.1.1.25 (5-31-2017) ==
*Enhanced support for Digital Audio
*Ability to pass adloadtype as “linear” or “dynamic”
*Ability to detect end of content and static material through duration pings
*Acceptance of empty parameters with a warning message triggered, if a required parameter is missing
*Acceptance of case-insensitive JSON key values
*Configurable feature to show Ad view counts in the duration pings
*Automatic Pause Detection and Debug build detection
*Change of default ‘type’ from “ad” to “content”
*Removal of “Static” Launch Ping for Non-Static product implementations
*Fix for App crash when multiple threads are accessing the SQLite

== Release 5.1.1.23 (5-5-2017) ==
*Ability to pass adloadtype as “linear” or “dynamic”
*Ability to detect end of content and static material through duration pings
*Acceptance of empty parameters with a warning message triggered, if a required parameter is missing
*Acceptance of case-insensitive JSON key values
*Configurable feature to show Ad view counts in the duration pings
*Automatic Pause Detection and Debug build detection
*Change of default ‘type’ from “ad” to “content”
*Removal of “Static” Launch Ping for Non-Static product implementations
*Fix for App crash when multiple threads are accessing the SQLite

== Release 5.1.1.19 (4-3-2017) ==
*Fix for muting background music apps

== Release 5.1.1.18 (2-3-2017) ==
*Minor bug fixes and performance improvement

== Release 5.1.1.17 (1-23-2017) ==
*Added “seconds” place to the launch ping
*Ability to opt-out using “Limit Ad Tracking” feature
*Improved CPU Performance while apps are running in background
*Opt-Out pages can be served based on user’s language and locale from device

== Release 5.1.1.12 (12-14-2016) ==
*Support for Nielsen TV Brand Effect
*Ability to set CMS parameters at a more global level
*Opt-out pages based on locale and country
*Opt-out policy based on the ‘Limit Ad Tracking’ flag
*Collection of additional device information
*Issue a warning in client developer’s console when ad is played for more than 5 minutes
*Removed the requirement for “type” parameter
*Limit the duration reported for App launch

== Release 5.1.1.9 (10-18-2016) ==
*Fixed Linker error duplicate symbols for Reachability notification in iOS.

== Release 5.1.1.7 (9-13-2016) ==
*Support for iOS 10
*Usage of stop API call is made optional when switching between content or advertising occurs.
*General bug fix and performance improvements

== Release 5.1.1.5 (7-12-2016) ==
*Sending event level (button press data) data to census collections.
*Support for Pause timeout (from 30 minutes to 5 minutes)
*Changes in OTT when switching from mobile to Chromecast
*Self-error Reporting for iOS SDK
*General bug fix and performance improvements

== Release 5.1.0.5 (4-25-2016) ==
*Combined SDK for DCR US and International (Germany)
*API to signal end of content (end API)
*Changes to use of stop API
*Support for OTT measurement
*Support for Pause timeout
*Offline viewing
*Updated API to support JSON object instead of string.
*Reporting of media URL and bundle ID
*Updated ping retry logic
*Changes in OptOut process behavioral
*Enhanced Debugging and SDK logging
*Changes to API signature
*Introduced new API updateOTT to report current OTT status.

== Release 4.0.0.8 (6-9-2015) ==
*Support for Nielsen DCR product (Digital Content Ratings)
**All the products should be migrated to the latest SDK.
**This SDK distribution does not have a native library component or shared object.
*Support for Nielsen App static measurement
*Support for Ad measurement
*Removal of Native C++ code
*Removed singleton restriction
*Support for iOS 9 and iOS 9 PIP mode
*General bug fix and performance improvements

== Release 3.2.1.26 (1-10-2015) ==

Android SDK Release Notes

2026-03-23T14:24:50Z

AmySockanathan: Changed release 10.2 date to 3/24/2026

[[Category:Digital]]
__NOTOC__

{{Breadcrumb|}} {{Breadcrumb|Digital Downloads}} {{CurrentBreadcrumb}}
== Release 10.2.0.0 (03-24-2026) ==
*[[Mitigation of Android 15 background]] network access restrictions.
*Fixed Viewabiity defects.
*Ad length warning - Fixed the ad tracking logic so now, the 300-second warning will only fire if the current ad actually plays for more than 5 minutes, and that error state will no longer bleed over into the next ad.

== Release 10.1.0.0 (10-17-2025) ==
*Support for FPID multi-instance integrations.
*Support for Flutter cross-platform plugin.
*Other bug fixes and enhancements.

== Release 10.0.0.0 (04-04-2025) ==
*Support for DTVR Subminute product.
*Support for DCR video playhead bridging.
*Support for Ethernet network connection for TV platforms.
*Change in DemographicID behavior for Chromecast.
*Other bug fixes and enhancements.

== Release 9.2.0.0 (9-27-2023) ==
*DCR Static recognizing metadata with changed assetID for new impressions.
*Limiting ping retries during https failures.
*Other bug fixes and enhancements.

== Release 9.1.0.0 (3-31-2023) ==
*DCR Static duration measurement for AppSDK (currently only AGF)
*Viewability: allow enabling by product (DCR, DTVR)
*Other bug fixes and enhancements

== Release 9.0.0.0 (10-07-2022) ==
* Viewability measurement for DTVR, DCR Content and DCR Ad products.
* Audibility measurement for DTVR, DCR Content and DCR Ad products.
* Kotlin-Java interoperability implementation in SDK.
* Other bug fixes and enhancements.

== Release 8.2.0.0 (03-21-2022) ==
* Support for EMM AGF AdID-less solution.
* Enabled SDK to capture network availability changes.
* Removed the usage of deprecated network classes.
* Other bug fixes and enhancements.

== Release 8.1.0.0 (06-28-2021) ==
* Support for SDK build variants - AD/NoAD/NoID.
* Support to indicate ID used for AD build variant - AD ID vs Android ID.
* Support to capture Hashed email and UID.
* Support to collect SDK diagnostic data.
* Other bug fixes and enhancements.

== Release 8.0.0.0 (10-05-2020) ==
* FPID and VendorID support.
* Support for Android apps running on ChromeOS.
* Support for Xamarin cross platform framework.
* Other bug fixes and enhancements.

== Release 7.2.0.0 (05-18-2020) ==
* DTVR AQH and IVD requirements for End and pause timeout.
* Support for Hybrid app webview measurement.
* Support for Hybrid app react native webview measurement.
* Support for React Native measurement.
* Other bug fixes and enhancements

== Release 7.1.0.0 (12-09-2019) ==

* Application background/foreground state auto-detection (AndroidX)
* Fixed forward rewind evdata containing negative values
* Offline viewing measurement enhancements
* Revisited precedence logic for sfcode parameter
* Using default value for incorrect adModel parameter
* Defaulting isLive parameter value on channel change
* Other fixes and enhancements.

== Release 7.0.0.0 (09-06-2019) ==

* Support for CDN based config.
* Support for Market based EMM UAID pings.
* Changes required for proper DCR Static measurement in multi-instance/multiple appid's case.
* Fixes for OTT synchronization issues between iOS and Android platforms.
* Fixes for EV data parameters in few scenarios.
* Fixes for DCR Static product behaviour in background app refresh and background fetch scenarios.
* DCR Ad reporting improvements.
* Fixes and improvements for the SDK console log messages.
* Other enhancements and fixes.

== Release 6.2.0.0 (02-04-2019) ==
* Removal of Location Module from SDK Code.
* Fixed the getOptoutStatus() api, so that client can call it in main thread.
* Fixed the parsing error happening when clientid/vcid provided as empty in metadata.
* Align AppSDK for FW detection with BSDK for DCR measurement.
* Other enhancements and fixes.

== Release 6.1.0.1 (9-13-2018) ==
*Support added for Video On Demand in TV Ratings
*Bug fixes and improvements

== Release 6.0.0.4 (5-24-2018) ==
*If the SDK build target is set to AGF then SDK will send the hello ping to “eu” and “eu-uat” for debug builds. No changes to the non AGF build the default sfcode will continue to be "sdk" and "cert" for debug build.
*The C1 parameter (NUID) will now be sent as encrypted DeviceID.
*New SessionID changes. The sessionID will contain 29 length random characters appended by timestamp.
*Support for multiple SDK instance without any limit.
*New log feature for CAT tool to retrieve the API level information from client apps. This ping will contain the eventType, parameters, SDK version, appid etc.
*Removed Viewability for this release.

== Release 5.1.1.26 (7-31-2017) ==
*Genre parameter will be a part of DCR pings and the value is reflected as part of c44 parameter.
*Merged adModel and adLoadType flags
*Fix for stop event data carried to next session’s duration ping
*Fix for last playhead call that is not processed (when there is no time-gap between the last playhead and end call)

== Release 5.1.1.24 (6-2-2017) ==
*Enhanced support for Digital Audio
*Ability to pass adloadtype as “linear” or “dynamic”
*Ability to detect end of content and static material through duration pings
*Acceptance of empty parameters with a warning message triggered, if a required parameter is missing
*Acceptance of case-insensitive JSON key values
*Configurable feature to show Ad view counts in the duration pings
*Automatic Pause Detection and Debug build detection
*Change of default ‘type’ from “ad” to “content”
*Removal of “Static” Launch Ping for Non-Static product implementations
*Fix for metadata carry over between channels after a channel change

== Release 5.1.1.18 (1-24-2017) ==
*Ability to opt-out using “Limit Ad Tracking” feature
*Improved CPU Performance through encryption process change
*Opt-Out pages can be served based on user’s language and locale from device

== Release 5.1.1.14 (12-10-2016) ==
*Support for Nielsen TV Brand Effect
*Ability to set CMS parameters at a more global level
*Collection of additional device information
*Opt-out pages based on locale and country
*Opt-out based on the ‘Limit Ad Tracking’ flag
*Issue a warning in client developer’s console when an ad is being played for more than 5 minutes
*Reduced load time of Android SDK, caused due to encryption.
*Limit the duration reported for App launch
*Modification to accept non-JSON strings
*Fixed
**Incorrect DRM placement ID
**DRM pings sent in bursts in case of time change

== Release 5.1.1.10 (10-19-2016) ==
*Fixed an issue where SDK will send a burst of data pings in Android.

== Release 5.1.1.7 (9-1-2016) ==
*Support for Android N
*Usage of stop API call is made optional when switching between content or advertising occurs.
*General bug fix and performance improvements

== Release 5.1.1.4 (8-1-2016) ==
*Support for Pause timeout (from 30 minutes to 5 minutes)

== Release 5.1.1.3 (7-7-2016) ==
*Sending event level (button press data) data to census collections.
*Changes in OTT when switching from mobile to Chromecast
*General bug fix and performance improvements

== Release 5.1.0.4 (4-25-2016) ==
*Combined SDK for DCR US and International (Germany)
*API to signal end of content (end API)
*Changes to use of stop API
*Support for OTT measurement
*Support for Pause timeout
*Offline viewing
*Updated API to support JSON object instead of string.
*Reporting of media URL and bundle ID
*Updated ping retry logic
*Changes in OptOut process behavioral
*Enhanced Debugging and SDK logging
*Changes to API signature
*Introduced new API updateOTT to report current OTT status.

== Release 4.0.0.8 (6-9-2015) ==
*Support for Nielsen DCR product (Digital Content Ratings)
*All the products should be migrated to the latest SDK.
*This SDK distribution does not have a native library component or shared object.
*Support for Nielsen App static measurement
*Support for Ad measurement
*Removal of Native C++ code
*Removed singleton restriction
*Support for Android 6.0 Marshmallow
*General bug fix and performance improvements

== Release 1.2.3.8 (1-10-2015) ==

Mitigation of Android 15 background

2026-03-20T14:49:29Z

AmySockanathan: /* Observation */

==Mitigation of Android 15 background network access restrictions==
===Observation===
On devices running Android 15 and 16, ping HTTP requests consistently fail while the application is in a background state.
These failed pings currently undergo five retry attempts, which consistently result in a 404 error response.
Once the retry limit is reached, the failed requests are purged from the pending database table.
The OS's aggressive background restrictions prevent the SDK from establishing a stable network handshake.

===Root Cause===
Below writeup has been taken directly from the official [https://developer.android.com/about/versions/15/behavior-changes-all#background-network-access Android developer documentation] which states that -

“In Android 15, apps that start a network request outside of a valid process lifecycle receive an exception. Typically, an UnknownHostException or other socket-related IOException. Network requests that happen outside of a valid lifecycle are usually due to apps unknowingly continuing a network request even after the app is no longer active.

To mitigate this exception, ensure your network requests are lifecycle aware and cancelled upon leaving a valid process lifecycle by using lifecycle aware components. If it is important that the network request should happen even when the user leaves the application, consider scheduling the network request using WorkManager or continue a user visible task using Foreground Service.”

===Conclusion Of Background Behaviour Changes===
Starting with Android 15, the system has introduced stricter limitations on background network access! So we have transitioned our background operations to use the WorkManager API, which is now a required dependency. Without the WorkManager library, background network calls may be blocked or fail silently, leading to data loss on devices running Android 15 or later.

===WorkManager Integration (Client Side)===
Client apps must add the WorkManager library once they have integrated version '''10.2.0.0''' of the AppSDK. Starting with this version, the WorkManager library is a mandatory dependency and missing it will '''fail the AppSDK initialization'''.

The AppSDK will flash the below error message to the console -

<code>“AppApi initialize failed! Starting with Android 15, the system has introduced stricter limitations on background network access! So we have transitioned our background operations to use the WorkManager API, which is now a required dependency. Without the WorkManager library, background network calls may be blocked or fail silently, leading to data synchronization issues on newer devices. Please add the androidx.work:work-runtime dependency to your project's build.gradle file“</code>

'''Note:''' ''Please add the'' '''androidx.work:work-runtime''' ''dependency to the project's build.gradle file.''

Mitigation of Android 15 background

2026-03-20T14:47:30Z

AmySockanathan: /* Observation */

==Mitigation of Android 15 background network access restrictions==
===Observation===
On devices running Android 15 and 16, ping HTTP requests consistently fail while the application is in a background state.

These failed pings currently undergo five retry attempts, which consistently result in a 404 error response.

Once the retry limit is reached, the failed requests are purged from the pending database table.

The OS's aggressive background restrictions prevent the SDK from establishing a stable network handshake.

===Root Cause===
Below writeup has been taken directly from the official [https://developer.android.com/about/versions/15/behavior-changes-all#background-network-access Android developer documentation] which states that -

“In Android 15, apps that start a network request outside of a valid process lifecycle receive an exception. Typically, an UnknownHostException or other socket-related IOException. Network requests that happen outside of a valid lifecycle are usually due to apps unknowingly continuing a network request even after the app is no longer active.

To mitigate this exception, ensure your network requests are lifecycle aware and cancelled upon leaving a valid process lifecycle by using lifecycle aware components. If it is important that the network request should happen even when the user leaves the application, consider scheduling the network request using WorkManager or continue a user visible task using Foreground Service.”

===Conclusion Of Background Behaviour Changes===
Starting with Android 15, the system has introduced stricter limitations on background network access! So we have transitioned our background operations to use the WorkManager API, which is now a required dependency. Without the WorkManager library, background network calls may be blocked or fail silently, leading to data loss on devices running Android 15 or later.

===WorkManager Integration (Client Side)===
Client apps must add the WorkManager library once they have integrated version '''10.2.0.0''' of the AppSDK. Starting with this version, the WorkManager library is a mandatory dependency and missing it will '''fail the AppSDK initialization'''.

The AppSDK will flash the below error message to the console -

<code>“AppApi initialize failed! Starting with Android 15, the system has introduced stricter limitations on background network access! So we have transitioned our background operations to use the WorkManager API, which is now a required dependency. Without the WorkManager library, background network calls may be blocked or fail silently, leading to data synchronization issues on newer devices. Please add the androidx.work:work-runtime dependency to your project's build.gradle file“</code>

'''Note:''' ''Please add the'' '''androidx.work:work-runtime''' ''dependency to the project's build.gradle file.''

iOS SDK Release Notes

2026-03-19T19:41:55Z

AmySockanathan: Add 10.2.0.0 release notes

[[Category:Digital]]
__NOTOC__

{{Breadcrumb|}} {{Breadcrumb|Digital Downloads}} {{CurrentBreadcrumb}}

== Release 10.2.0.0 (03-23-2026) ==
*iOS Digital Signature Certificate Renewal
*Fixes for Viewabiity defects
*Ad length warning - Fixed the ad tracking logic so now, the 300-second warning will only fire if the current ad actually plays for more than 5 minutes, and that error state will no longer bleed over into the next ad.
*SDK Code Signature fix (Global Flavor only) - The Global direct binary available on the Engineering Portal now correctly includes the SDK code signature for manual integrations.

== Release 10.1.0.0 (10-17-2025) ==
*Support for FPID multi-instance integrations.
*Support for Flutter cross-platform plugin.
*Support for Apple's iOS26/tvOS26 Log Visibility Changes.
*Other bug fixes and enhancements.

== Release 10.0.0.0 (04-04-2025) ==
*Support for DTVR Subminute product.
*Support for DCR video playhead bridging.
*Support for VisionOS platform.
*Change in DemographicID behavior for Chromecast.
*Other bug fixes and enhancements.

== '''Release 9.4.0.0 (07-09-2024)''' ==
*Support for privacy manifest with content tracking domain for Ad flavors.
*Support for content tracking and no-tracking domains across sdk flavors and products.
*Other bug fixes and enhancements.
== Release 9.3.0.0 (05-10-2024) ==
*Support for privacy manifest with tracking domain for Ad flavors.
*Support for capturing user opt-out during initialization.
*Other bug fixes and enhancements.
== Release 9.2.0.0 (9-27-2023) ==
*Support for privacy manifest and required reason API introduced in XCode 15.
*Digitally signed SDK framework per Apple recommendation
*DCR Static recognizing metadata with changed assetID for new impressions.
*Limiting ping retries during https failures.
*Other bug fixes and enhancements.

== Release 9.1.0.0 (3-31-2023) ==
*DCR Static duration measurement for AppSDK (currently only AGF).
*Removed use of iOS keychains, started using NSUserDefaults for persistent storage.
*Viewability: allow enabling by product (DCR, DTVR).
*Other bug fixes and enhancements.

== Release 9.0.0.0 (10-07-2022) ==
* Viewability measurement for DTVR, DCR Content and DCR Ad products.
* Audibility measurement for DTVR, DCR Content and DCR Ad products.
* SDK built with XCode 14.
* Other bug fixes and enhancements.

== Release 8.2.0.0 (03-21-2022) ==
* Adopting Swift language internally, built on a mixed model (Swift+Objective C).
* Support for Swift markers to help Swift developers.
* Removed the usage of deprecated iOS network reachability class.
* Disabled iCloud backup/synchronization of SDK keychain items.
* Other bug fixes and enhancements.

== Release 8.1.0.0 (06-28-2021) ==
* Support for XCFramework build distribution.
* Support for MacOS Catalyst platform framework.
* Fixed the device classification for MacOS M1 measurement.
* Support to capture Hashed email and UID.
* Support to collect SDK diagnostic data.
* Other bug fixes and enhancements.

== Release 8.0.0.0 (10-05-2020) ==
* iOS 14 App Transparency Framework support.
* FPID and VendorID support.
* Fixed the device classification for iPADOS measurement.
* Support for Xamarin cross platform framework.
* Other bug fixes and enhancements.

== Release 7.2.0.0 (05-18-2020) ==
* DTVR AQH and IVD requirements for End and pause timeout.
* Support for Hybrid app webview measurement.
* Support for Hybrid app react native webview measurement.
* Support for React Native measurement.
* Other bug fixes and enhancements

== Release 7.1.0.0 (12-09-2019) ==
* Removed usage of deprecated class UIWebView
* Offline viewing measurement enhancements
* Fixed deadlock on SDK shutdown
* Revisited precedence logic for sfcode parameter
* Fix for DCR individual ad pings parameters after channel change
* Using default value for incorrect adModel parameter
* Defaulting isLive parameter value on channel change
* Other fixes and enhancements.

== Release 7.0.0.0 (09-06-2019) ==
* Support for CDN based config.
* Support for Market based EMM UAID pings.
* Changes required for proper DCR Static measurement in multi-instance/multiple appid's case.
* Fixes for OTT synchronization issues between iOS and Android platforms.
* Fixes for EV data parameters in few scenarios.
* Fixes for DCR Static product behaviour in background app refresh and background fetch scenarios.
* DCR Ad reporting improvements.
* Fixes and improvements for the SDK console log messages.
* Other enhancements and fixes.

== Release 6.2.0.0 (02-04-2019) ==
* Introduced Dynamic framework for SDK.
* Removal of Location Module from SDK Code.
* Increased SDK log file size for Debug mode.
* Removed OTT Airplay/mirroring detection that caused crashes in AVAudioSession class.
* DCR performance improvements.
* Fixed the parsing error happening when clientid/vcid provided as empty in metadata.
* Align AppSDK for FW detection with BSDK for DCR measurement.
* Other Bug Fixes/Enhancements.

== Release 6.1.0.1 (9-13-2018) ==
*Support added for Video On Demand in TV Ratings
*Support for Xcode 10 and iOS 12

== Release 6.0.0.4 (5-24-2018) ==
*If the SDK build target is set to AGF then SDK will send the hello ping to “eu” and “eu-uat” for debug builds. No changes to the non AGF build the default sfcode will continue to be "sdk" and "cert" for debug build.
*The C1 parameter (NUID) will now be sent as encrypted DeviceID.
*New SessionID changes. The sessionID will contain 29 length random characters appended by timestamp.
*Support for multiple SDK instance without any limit.
*New log feature for CAT tool to retrieve the API level information from client apps. This ping will contain the eventType, parameters, SDK version, appid etc.
*Removed Viewability for this release.

== Release 5.1.1.29 (7-31-2017) ==
*Genre parameter will be a part of DCR pings and the value will be reflected as part of c44 parameter.
*Merged adModel and adLoadType flags
*Fix for stop event data carried to next session’s duration ping

== Release 5.1.1.25 (5-31-2017) ==
*Enhanced support for Digital Audio
*Ability to pass adloadtype as “linear” or “dynamic”
*Ability to detect end of content and static material through duration pings
*Acceptance of empty parameters with a warning message triggered, if a required parameter is missing
*Acceptance of case-insensitive JSON key values
*Configurable feature to show Ad view counts in the duration pings
*Automatic Pause Detection and Debug build detection
*Change of default ‘type’ from “ad” to “content”
*Removal of “Static” Launch Ping for Non-Static product implementations
*Fix for App crash when multiple threads are accessing the SQLite

== Release 5.1.1.23 (5-5-2017) ==
*Ability to pass adloadtype as “linear” or “dynamic”
*Ability to detect end of content and static material through duration pings
*Acceptance of empty parameters with a warning message triggered, if a required parameter is missing
*Acceptance of case-insensitive JSON key values
*Configurable feature to show Ad view counts in the duration pings
*Automatic Pause Detection and Debug build detection
*Change of default ‘type’ from “ad” to “content”
*Removal of “Static” Launch Ping for Non-Static product implementations
*Fix for App crash when multiple threads are accessing the SQLite

== Release 5.1.1.19 (4-3-2017) ==
*Fix for muting background music apps

== Release 5.1.1.18 (2-3-2017) ==
*Minor bug fixes and performance improvement

== Release 5.1.1.17 (1-23-2017) ==
*Added “seconds” place to the launch ping
*Ability to opt-out using “Limit Ad Tracking” feature
*Improved CPU Performance while apps are running in background
*Opt-Out pages can be served based on user’s language and locale from device

== Release 5.1.1.12 (12-14-2016) ==
*Support for Nielsen TV Brand Effect
*Ability to set CMS parameters at a more global level
*Opt-out pages based on locale and country
*Opt-out policy based on the ‘Limit Ad Tracking’ flag
*Collection of additional device information
*Issue a warning in client developer’s console when ad is played for more than 5 minutes
*Removed the requirement for “type” parameter
*Limit the duration reported for App launch

== Release 5.1.1.9 (10-18-2016) ==
*Fixed Linker error duplicate symbols for Reachability notification in iOS.

== Release 5.1.1.7 (9-13-2016) ==
*Support for iOS 10
*Usage of stop API call is made optional when switching between content or advertising occurs.
*General bug fix and performance improvements

== Release 5.1.1.5 (7-12-2016) ==
*Sending event level (button press data) data to census collections.
*Support for Pause timeout (from 30 minutes to 5 minutes)
*Changes in OTT when switching from mobile to Chromecast
*Self-error Reporting for iOS SDK
*General bug fix and performance improvements

== Release 5.1.0.5 (4-25-2016) ==
*Combined SDK for DCR US and International (Germany)
*API to signal end of content (end API)
*Changes to use of stop API
*Support for OTT measurement
*Support for Pause timeout
*Offline viewing
*Updated API to support JSON object instead of string.
*Reporting of media URL and bundle ID
*Updated ping retry logic
*Changes in OptOut process behavioral
*Enhanced Debugging and SDK logging
*Changes to API signature
*Introduced new API updateOTT to report current OTT status.

== Release 4.0.0.8 (6-9-2015) ==
*Support for Nielsen DCR product (Digital Content Ratings)
**All the products should be migrated to the latest SDK.
**This SDK distribution does not have a native library component or shared object.
*Support for Nielsen App static measurement
*Support for Ad measurement
*Removal of Native C++ code
*Removed singleton restriction
*Support for iOS 9 and iOS 9 PIP mode
*General bug fix and performance improvements

== Release 3.2.1.26 (1-10-2015) ==

Mitigation of Android 15 background

2026-03-19T19:36:40Z

AmySockanathan: /* The Root Cause */

==Mitigation of Android 15 background network access restrictions==
===Observation===
On devices running Android 15 and 16, ping HTTP requests consistently fail while the application is in a background state.

These failed pings currently undergo five retry attempts, which consistently result in a 404 error response.

Once the retry limit is reached, the failed requests are purged from the pending database table.

The OS's aggressive background restrictions prevent the SDK from establishing a stable network handshake.

===Root Cause===
Below writeup has been taken directly from the official [https://developer.android.com/about/versions/15/behavior-changes-all#background-network-access Android developer documentation] which states that -

“In Android 15, apps that start a network request outside of a valid process lifecycle receive an exception. Typically, an UnknownHostException or other socket-related IOException. Network requests that happen outside of a valid lifecycle are usually due to apps unknowingly continuing a network request even after the app is no longer active.

To mitigate this exception, ensure your network requests are lifecycle aware and cancelled upon leaving a valid process lifecycle by using lifecycle aware components. If it is important that the network request should happen even when the user leaves the application, consider scheduling the network request using WorkManager or continue a user visible task using Foreground Service.”

===Conclusion Of Background Behaviour Changes===
Starting with Android 15, the system has introduced stricter limitations on background network access! So we have transitioned our background operations to use the WorkManager API, which is now a required dependency. Without the WorkManager library, background network calls may be blocked or fail silently, leading to data loss on devices running Android 15 or later.

===WorkManager Integration (Client Side)===
Client apps must add the WorkManager library once they have integrated version '''10.2.0.0''' of the AppSDK. Starting with this version, the WorkManager library is a mandatory dependency and missing it will '''fail the AppSDK initialization'''.

The AppSDK will flash the below error message to the console -

<code>“AppApi initialize failed! Starting with Android 15, the system has introduced stricter limitations on background network access! So we have transitioned our background operations to use the WorkManager API, which is now a required dependency. Without the WorkManager library, background network calls may be blocked or fail silently, leading to data synchronization issues on newer devices. Please add the androidx.work:work-runtime dependency to your project's build.gradle file“</code>

'''Note:''' ''Please add the'' '''androidx.work:work-runtime''' ''dependency to the project's build.gradle file.''

Mitigation of Android 15 background

2026-03-19T19:35:49Z

AmySockanathan: Create a new page for "Mitigation of Android 15 background"

==Mitigation of Android 15 background network access restrictions==
===Observation===
On devices running Android 15 and 16, ping HTTP requests consistently fail while the application is in a background state.

These failed pings currently undergo five retry attempts, which consistently result in a 404 error response.

Once the retry limit is reached, the failed requests are purged from the pending database table.

The OS's aggressive background restrictions prevent the SDK from establishing a stable network handshake.

===The Root Cause===
Below writeup has been taken directly from the official [https://developer.android.com/about/versions/15/behavior-changes-all#background-network-access Android developer documentation] which states that -

“In Android 15, apps that start a network request outside of a valid process lifecycle receive an exception. Typically, an UnknownHostException or other socket-related IOException. Network requests that happen outside of a valid lifecycle are usually due to apps unknowingly continuing a network request even after the app is no longer active.

To mitigate this exception, ensure your network requests are lifecycle aware and cancelled upon leaving a valid process lifecycle by using lifecycle aware components. If it is important that the network request should happen even when the user leaves the application, consider scheduling the network request using WorkManager or continue a user visible task using Foreground Service.”

===Conclusion Of Background Behaviour Changes===
Starting with Android 15, the system has introduced stricter limitations on background network access! So we have transitioned our background operations to use the WorkManager API, which is now a required dependency. Without the WorkManager library, background network calls may be blocked or fail silently, leading to data loss on devices running Android 15 or later.

===WorkManager Integration (Client Side)===
Client apps must add the WorkManager library once they have integrated version '''10.2.0.0''' of the AppSDK. Starting with this version, the WorkManager library is a mandatory dependency and missing it will '''fail the AppSDK initialization'''.

The AppSDK will flash the below error message to the console -

<code>“AppApi initialize failed! Starting with Android 15, the system has introduced stricter limitations on background network access! So we have transitioned our background operations to use the WorkManager API, which is now a required dependency. Without the WorkManager library, background network calls may be blocked or fail silently, leading to data synchronization issues on newer devices. Please add the androidx.work:work-runtime dependency to your project's build.gradle file“</code>

'''Note:''' ''Please add the'' '''androidx.work:work-runtime''' ''dependency to the project's build.gradle file.''

Android SDK Release Notes

2026-03-19T19:21:06Z

AmySockanathan: Add the link to new page for "mitigation of Android 15 background issue"

[[Category:Digital]]
__NOTOC__

{{Breadcrumb|}} {{Breadcrumb|Digital Downloads}} {{CurrentBreadcrumb}}
== Release 10.2.0.0 (03-23-2026) ==
*[[Mitigation of Android 15 background]] network access restrictions.
*Fixed Viewabiity defects.
*Ad length warning - Fixed the ad tracking logic so now, the 300-second warning will only fire if the current ad actually plays for more than 5 minutes, and that error state will no longer bleed over into the next ad.

== Release 10.1.0.0 (10-17-2025) ==
*Support for FPID multi-instance integrations.
*Support for Flutter cross-platform plugin.
*Other bug fixes and enhancements.

== Release 10.0.0.0 (04-04-2025) ==
*Support for DTVR Subminute product.
*Support for DCR video playhead bridging.
*Support for Ethernet network connection for TV platforms.
*Change in DemographicID behavior for Chromecast.
*Other bug fixes and enhancements.

== Release 9.2.0.0 (9-27-2023) ==
*DCR Static recognizing metadata with changed assetID for new impressions.
*Limiting ping retries during https failures.
*Other bug fixes and enhancements.

== Release 9.1.0.0 (3-31-2023) ==
*DCR Static duration measurement for AppSDK (currently only AGF)
*Viewability: allow enabling by product (DCR, DTVR)
*Other bug fixes and enhancements

== Release 9.0.0.0 (10-07-2022) ==
* Viewability measurement for DTVR, DCR Content and DCR Ad products.
* Audibility measurement for DTVR, DCR Content and DCR Ad products.
* Kotlin-Java interoperability implementation in SDK.
* Other bug fixes and enhancements.

== Release 8.2.0.0 (03-21-2022) ==
* Support for EMM AGF AdID-less solution.
* Enabled SDK to capture network availability changes.
* Removed the usage of deprecated network classes.
* Other bug fixes and enhancements.

== Release 8.1.0.0 (06-28-2021) ==
* Support for SDK build variants - AD/NoAD/NoID.
* Support to indicate ID used for AD build variant - AD ID vs Android ID.
* Support to capture Hashed email and UID.
* Support to collect SDK diagnostic data.
* Other bug fixes and enhancements.

== Release 8.0.0.0 (10-05-2020) ==
* FPID and VendorID support.
* Support for Android apps running on ChromeOS.
* Support for Xamarin cross platform framework.
* Other bug fixes and enhancements.

== Release 7.2.0.0 (05-18-2020) ==
* DTVR AQH and IVD requirements for End and pause timeout.
* Support for Hybrid app webview measurement.
* Support for Hybrid app react native webview measurement.
* Support for React Native measurement.
* Other bug fixes and enhancements

== Release 7.1.0.0 (12-09-2019) ==

* Application background/foreground state auto-detection (AndroidX)
* Fixed forward rewind evdata containing negative values
* Offline viewing measurement enhancements
* Revisited precedence logic for sfcode parameter
* Using default value for incorrect adModel parameter
* Defaulting isLive parameter value on channel change
* Other fixes and enhancements.

== Release 7.0.0.0 (09-06-2019) ==

* Support for CDN based config.
* Support for Market based EMM UAID pings.
* Changes required for proper DCR Static measurement in multi-instance/multiple appid's case.
* Fixes for OTT synchronization issues between iOS and Android platforms.
* Fixes for EV data parameters in few scenarios.
* Fixes for DCR Static product behaviour in background app refresh and background fetch scenarios.
* DCR Ad reporting improvements.
* Fixes and improvements for the SDK console log messages.
* Other enhancements and fixes.

== Release 6.2.0.0 (02-04-2019) ==
* Removal of Location Module from SDK Code.
* Fixed the getOptoutStatus() api, so that client can call it in main thread.
* Fixed the parsing error happening when clientid/vcid provided as empty in metadata.
* Align AppSDK for FW detection with BSDK for DCR measurement.
* Other enhancements and fixes.

== Release 6.1.0.1 (9-13-2018) ==
*Support added for Video On Demand in TV Ratings
*Bug fixes and improvements

== Release 6.0.0.4 (5-24-2018) ==
*If the SDK build target is set to AGF then SDK will send the hello ping to “eu” and “eu-uat” for debug builds. No changes to the non AGF build the default sfcode will continue to be "sdk" and "cert" for debug build.
*The C1 parameter (NUID) will now be sent as encrypted DeviceID.
*New SessionID changes. The sessionID will contain 29 length random characters appended by timestamp.
*Support for multiple SDK instance without any limit.
*New log feature for CAT tool to retrieve the API level information from client apps. This ping will contain the eventType, parameters, SDK version, appid etc.
*Removed Viewability for this release.

== Release 5.1.1.26 (7-31-2017) ==
*Genre parameter will be a part of DCR pings and the value is reflected as part of c44 parameter.
*Merged adModel and adLoadType flags
*Fix for stop event data carried to next session’s duration ping
*Fix for last playhead call that is not processed (when there is no time-gap between the last playhead and end call)

== Release 5.1.1.24 (6-2-2017) ==
*Enhanced support for Digital Audio
*Ability to pass adloadtype as “linear” or “dynamic”
*Ability to detect end of content and static material through duration pings
*Acceptance of empty parameters with a warning message triggered, if a required parameter is missing
*Acceptance of case-insensitive JSON key values
*Configurable feature to show Ad view counts in the duration pings
*Automatic Pause Detection and Debug build detection
*Change of default ‘type’ from “ad” to “content”
*Removal of “Static” Launch Ping for Non-Static product implementations
*Fix for metadata carry over between channels after a channel change

== Release 5.1.1.18 (1-24-2017) ==
*Ability to opt-out using “Limit Ad Tracking” feature
*Improved CPU Performance through encryption process change
*Opt-Out pages can be served based on user’s language and locale from device

== Release 5.1.1.14 (12-10-2016) ==
*Support for Nielsen TV Brand Effect
*Ability to set CMS parameters at a more global level
*Collection of additional device information
*Opt-out pages based on locale and country
*Opt-out based on the ‘Limit Ad Tracking’ flag
*Issue a warning in client developer’s console when an ad is being played for more than 5 minutes
*Reduced load time of Android SDK, caused due to encryption.
*Limit the duration reported for App launch
*Modification to accept non-JSON strings
*Fixed
**Incorrect DRM placement ID
**DRM pings sent in bursts in case of time change

== Release 5.1.1.10 (10-19-2016) ==
*Fixed an issue where SDK will send a burst of data pings in Android.

== Release 5.1.1.7 (9-1-2016) ==
*Support for Android N
*Usage of stop API call is made optional when switching between content or advertising occurs.
*General bug fix and performance improvements

== Release 5.1.1.4 (8-1-2016) ==
*Support for Pause timeout (from 30 minutes to 5 minutes)

== Release 5.1.1.3 (7-7-2016) ==
*Sending event level (button press data) data to census collections.
*Changes in OTT when switching from mobile to Chromecast
*General bug fix and performance improvements

== Release 5.1.0.4 (4-25-2016) ==
*Combined SDK for DCR US and International (Germany)
*API to signal end of content (end API)
*Changes to use of stop API
*Support for OTT measurement
*Support for Pause timeout
*Offline viewing
*Updated API to support JSON object instead of string.
*Reporting of media URL and bundle ID
*Updated ping retry logic
*Changes in OptOut process behavioral
*Enhanced Debugging and SDK logging
*Changes to API signature
*Introduced new API updateOTT to report current OTT status.

== Release 4.0.0.8 (6-9-2015) ==
*Support for Nielsen DCR product (Digital Content Ratings)
*All the products should be migrated to the latest SDK.
*This SDK distribution does not have a native library component or shared object.
*Support for Nielsen App static measurement
*Support for Ad measurement
*Removal of Native C++ code
*Removed singleton restriction
*Support for Android 6.0 Marshmallow
*General bug fix and performance improvements

== Release 1.2.3.8 (1-10-2015) ==

Android SDK Release Notes

2026-03-19T19:09:44Z

AmySockanathan: Android 10.2.0. release notes

[[Category:Digital]]
__NOTOC__

{{Breadcrumb|}} {{Breadcrumb|Digital Downloads}} {{CurrentBreadcrumb}}
== Release 10.2.0.0 (03-23-2026) ==
*Mitigation of Android 15 background network access restrictions.
*Fixed Viewabiity defects.
*Ad length warning - Fixed the ad tracking logic so now, the 300-second warning will only fire if the current ad actually plays for more than 5 minutes, and that error state will no longer bleed over into the next ad.

== Release 10.1.0.0 (10-17-2025) ==
*Support for FPID multi-instance integrations.
*Support for Flutter cross-platform plugin.
*Other bug fixes and enhancements.

== Release 10.0.0.0 (04-04-2025) ==
*Support for DTVR Subminute product.
*Support for DCR video playhead bridging.
*Support for Ethernet network connection for TV platforms.
*Change in DemographicID behavior for Chromecast.
*Other bug fixes and enhancements.

== Release 9.2.0.0 (9-27-2023) ==
*DCR Static recognizing metadata with changed assetID for new impressions.
*Limiting ping retries during https failures.
*Other bug fixes and enhancements.

== Release 9.1.0.0 (3-31-2023) ==
*DCR Static duration measurement for AppSDK (currently only AGF)
*Viewability: allow enabling by product (DCR, DTVR)
*Other bug fixes and enhancements

== Release 9.0.0.0 (10-07-2022) ==
* Viewability measurement for DTVR, DCR Content and DCR Ad products.
* Audibility measurement for DTVR, DCR Content and DCR Ad products.
* Kotlin-Java interoperability implementation in SDK.
* Other bug fixes and enhancements.

== Release 8.2.0.0 (03-21-2022) ==
* Support for EMM AGF AdID-less solution.
* Enabled SDK to capture network availability changes.
* Removed the usage of deprecated network classes.
* Other bug fixes and enhancements.

== Release 8.1.0.0 (06-28-2021) ==
* Support for SDK build variants - AD/NoAD/NoID.
* Support to indicate ID used for AD build variant - AD ID vs Android ID.
* Support to capture Hashed email and UID.
* Support to collect SDK diagnostic data.
* Other bug fixes and enhancements.

== Release 8.0.0.0 (10-05-2020) ==
* FPID and VendorID support.
* Support for Android apps running on ChromeOS.
* Support for Xamarin cross platform framework.
* Other bug fixes and enhancements.

== Release 7.2.0.0 (05-18-2020) ==
* DTVR AQH and IVD requirements for End and pause timeout.
* Support for Hybrid app webview measurement.
* Support for Hybrid app react native webview measurement.
* Support for React Native measurement.
* Other bug fixes and enhancements

== Release 7.1.0.0 (12-09-2019) ==

* Application background/foreground state auto-detection (AndroidX)
* Fixed forward rewind evdata containing negative values
* Offline viewing measurement enhancements
* Revisited precedence logic for sfcode parameter
* Using default value for incorrect adModel parameter
* Defaulting isLive parameter value on channel change
* Other fixes and enhancements.

== Release 7.0.0.0 (09-06-2019) ==

* Support for CDN based config.
* Support for Market based EMM UAID pings.
* Changes required for proper DCR Static measurement in multi-instance/multiple appid's case.
* Fixes for OTT synchronization issues between iOS and Android platforms.
* Fixes for EV data parameters in few scenarios.
* Fixes for DCR Static product behaviour in background app refresh and background fetch scenarios.
* DCR Ad reporting improvements.
* Fixes and improvements for the SDK console log messages.
* Other enhancements and fixes.

== Release 6.2.0.0 (02-04-2019) ==
* Removal of Location Module from SDK Code.
* Fixed the getOptoutStatus() api, so that client can call it in main thread.
* Fixed the parsing error happening when clientid/vcid provided as empty in metadata.
* Align AppSDK for FW detection with BSDK for DCR measurement.
* Other enhancements and fixes.

== Release 6.1.0.1 (9-13-2018) ==
*Support added for Video On Demand in TV Ratings
*Bug fixes and improvements

== Release 6.0.0.4 (5-24-2018) ==
*If the SDK build target is set to AGF then SDK will send the hello ping to “eu” and “eu-uat” for debug builds. No changes to the non AGF build the default sfcode will continue to be "sdk" and "cert" for debug build.
*The C1 parameter (NUID) will now be sent as encrypted DeviceID.
*New SessionID changes. The sessionID will contain 29 length random characters appended by timestamp.
*Support for multiple SDK instance without any limit.
*New log feature for CAT tool to retrieve the API level information from client apps. This ping will contain the eventType, parameters, SDK version, appid etc.
*Removed Viewability for this release.

== Release 5.1.1.26 (7-31-2017) ==
*Genre parameter will be a part of DCR pings and the value is reflected as part of c44 parameter.
*Merged adModel and adLoadType flags
*Fix for stop event data carried to next session’s duration ping
*Fix for last playhead call that is not processed (when there is no time-gap between the last playhead and end call)

== Release 5.1.1.24 (6-2-2017) ==
*Enhanced support for Digital Audio
*Ability to pass adloadtype as “linear” or “dynamic”
*Ability to detect end of content and static material through duration pings
*Acceptance of empty parameters with a warning message triggered, if a required parameter is missing
*Acceptance of case-insensitive JSON key values
*Configurable feature to show Ad view counts in the duration pings
*Automatic Pause Detection and Debug build detection
*Change of default ‘type’ from “ad” to “content”
*Removal of “Static” Launch Ping for Non-Static product implementations
*Fix for metadata carry over between channels after a channel change

== Release 5.1.1.18 (1-24-2017) ==
*Ability to opt-out using “Limit Ad Tracking” feature
*Improved CPU Performance through encryption process change
*Opt-Out pages can be served based on user’s language and locale from device

== Release 5.1.1.14 (12-10-2016) ==
*Support for Nielsen TV Brand Effect
*Ability to set CMS parameters at a more global level
*Collection of additional device information
*Opt-out pages based on locale and country
*Opt-out based on the ‘Limit Ad Tracking’ flag
*Issue a warning in client developer’s console when an ad is being played for more than 5 minutes
*Reduced load time of Android SDK, caused due to encryption.
*Limit the duration reported for App launch
*Modification to accept non-JSON strings
*Fixed
**Incorrect DRM placement ID
**DRM pings sent in bursts in case of time change

== Release 5.1.1.10 (10-19-2016) ==
*Fixed an issue where SDK will send a burst of data pings in Android.

== Release 5.1.1.7 (9-1-2016) ==
*Support for Android N
*Usage of stop API call is made optional when switching between content or advertising occurs.
*General bug fix and performance improvements

== Release 5.1.1.4 (8-1-2016) ==
*Support for Pause timeout (from 30 minutes to 5 minutes)

== Release 5.1.1.3 (7-7-2016) ==
*Sending event level (button press data) data to census collections.
*Changes in OTT when switching from mobile to Chromecast
*General bug fix and performance improvements

== Release 5.1.0.4 (4-25-2016) ==
*Combined SDK for DCR US and International (Germany)
*API to signal end of content (end API)
*Changes to use of stop API
*Support for OTT measurement
*Support for Pause timeout
*Offline viewing
*Updated API to support JSON object instead of string.
*Reporting of media URL and bundle ID
*Updated ping retry logic
*Changes in OptOut process behavioral
*Enhanced Debugging and SDK logging
*Changes to API signature
*Introduced new API updateOTT to report current OTT status.

== Release 4.0.0.8 (6-9-2015) ==
*Support for Nielsen DCR product (Digital Content Ratings)
*All the products should be migrated to the latest SDK.
*This SDK distribution does not have a native library component or shared object.
*Support for Nielsen App static measurement
*Support for Ad measurement
*Removal of Native C++ code
*Removed singleton restriction
*Support for Android 6.0 Marshmallow
*General bug fix and performance improvements

== Release 1.2.3.8 (1-10-2015) ==

Browser SDK Release Notes

2026-03-06T15:48:15Z

AmySockanathan: Release notes for R1 2026 BSDK release

{{Breadcrumb|}} {{Breadcrumb|Digital}} {{CurrentBreadcrumb}}
[[Category:Digital]]
__NOTOC__

== Release R1(v6.0.0.747) (03-04-2026) ==

* Added support for Viewability & Audibility
* Last DTVR Subminute ping for iOS-Safari browser was not fired through the POST request.
* Fix for some RTVOD sceanrios
* Fix to not fire a DTVR Subminute timer ping with the evdata containing 00000 offset when FD channel transitions from a valid CID to null

== Release R1(v6.0.0.734) (07-08-2025) ==

* Support for DTVR Subminute feature

== Release V1(v6.0.110) (05-21-2024) ==

* Suppression of v60/v52/v53 legacy pings

== Release R2(v6.0.0.702) (10-30-2024) ==

* 2nd release of DOMless SDK
* Support DCR Static
* Support Debug interface which can be used to view API calls and SDK pings
* Support caching of pings when network is not available

== Release R1(v6.0.0.692) (07-31-2024) ==

* DOMless SDK Release with support for Amazon, ReactNative and other DOM less platforms

== Release R6(v6.0.0.673) (09-05-2023) ==

* Fix for stream id of stream 2 is populated in the last duration ping of stream 1 when mandatory END is not called

== Release R5(v6.0.0.673) (08-14-2023) (AGF Release) ==

* Fix for stream id of stream 2 is populated in the last duration ping of stream 1 when mandatory END is not called

== Release R4(v6.0.0.672) (08-01-2023) ==

* Viewability build with support for Viewability and Audibility features

== Release R3(v6.0.0.663) (05-30-2023) ==

* Support to measure static on hbbtv with the iFrame fixes.

== Release R2(v.6.0.0.648) (05-03-2023) (AGF Release) ==

* Support to measure DCR static when browser sdk is initialized on parent page while video is played within the iFrame
* Fix to propagate correct starttm value in postroll content trailing ping
* Fix the 1st party cookie expiry date
* Fix first party id time to live parameter (nol_fpid_ttl) override
* Update the sessionURL in BSDK600 code with FPID parameters
* SIVT support for DCR & DTVR
* StaticEnd support for Hybrid App

== Release R1.2(v6.0.0.662) (04-19-2023) ==
* Support to measure DCR static when browser sdk is initialized on parent page while video is played within the iFrame
* Support to measure DCR static on a Single Page Application when staticEnd is not called while navigating from one page to another

== Release R1(v6.0.0.648) (03-06-2023) ==
* SIVT support for DCR & DTVR
* StaticEnd support for Hybrid App

== Release R4(v6.0.0.623) (05-02-2022) ==
* Fix the 1st party cookie expiry date
* Fix first party id time to live parameter (nol_fpid_ttl) override
* Update the sessionURL in BSDK600 code with FPID parameters

== Release R3(v6.0.0.618) (03-29-2022) ==
* Fix to measure dcr static while video is in focus and within an iFrame
* Fix to propagate correct starttm value in postroll content trailing ping

== Release v6.0.0.355 ==
* Performance improvements through the use of cachable configuration via the Static Queue Snippet.
* Dynamic Configuration File
* Session Ping/UAID - A unique identifier of the device which allows for a single facebook ping per session.
* Support for iOS 12.2

== Release 5.1.0 (Build 2) ==
*Support for DCR Static Lite Measurement
*Advanced Dynamic Script Initialization
*Removal of Configuration file dependency

== Release 5.0.0 (Build 17) ==
*Support for Nielsen Digital Content Ratings (DCR) product
*Support for measurement of static content
*Support for Ad measurement
*Support for Facebook Pings
*Support for multiple instances of the SDK
*General bug fix and performance improvements

Domless SDK API Reference

2026-01-27T21:27:38Z

AmySockanathan: /* SetInterval */

==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 [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 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 <code>apid</code> 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 <code>npm install <nowiki>https://github.com/NielsenDigitalSDK/bsdk-domless</nowiki></code> and import the <code>BsdkInstance</code> into video player component
import { BsdkInstance } from 'bsdk-domless'
======status.ok()======
Initialization of the instance can be done with <code>status.ok()</code> 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: ImplementationHooks are mandatory for the DOM-less SDK instance. Please refer to the ImplementationHooks 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'''
!'''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 ===
====='''''<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>'''''=====

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.setItem('nol_lsid', 'umy3w4ik9usw2ppqmw2vkecckxfob1697308388')

===== Methods =====
<blockquote>setItem()

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

getItem()

storage.getItem(key: string)

removeItem()

storage.removeItem(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>

==== SetTimeout ====
Function to set a timer in milliseconds to execute a block of code on expiry

e.g. SetTimeout(callback , 1000)
===== Parameters =====
<blockquote>callback Required

● A function to execute when the timer expires

timeout Required

● number - The time that the timer should wait before the callback function is executed. This is in milliseconds.
</blockquote>

==== SetInterval ====
Function to repeatedly call a function with a fixed time delay in milliseconds between each call.

e.g. SetInterval(callback , 1000)
===== Parameters =====
<blockquote>callback Required

● A function to be executed every interval specified

interval Required

● number - The delay in milliseconds between the execution of the function
</blockquote>

==== ClearTimeout ====
Function to cancel the timeout previously set by SetTimeout

e.g. ClearTimeout(1000)
===== Parameters =====
<blockquote>timeout Required

● number - The time that the timer should wait before the callback function is executed
</blockquote>
==== ClearInterval ====
Function to cancel the timed repeating call which was previously established through SetInterval

e.g. ClearInterval(1000)
===== Parameters =====
<blockquote>interval Required

● number - The delay between the execution of the function
</blockquote>
==== Nielsen Debug Node.js Server for Event Tracking ====
We are excited to announce the beta version of our Debug Node.js server, designed to track requests and events sent from our Dom-less SDK using WebSocket connections. While this feature is not officially released, we are currently looking for users interested in beta testing.

If you'd like to try this tool and provide feedback, please reach out to your Nielsen Technical Account Manager (TAM) for more information. Your insights would be invaluable in helping us refine this feature for a future release!

== DOM-less SDK API Methods & Properties ==
{| class="wikitable"
|+
!Method/Property
!Event #
!DTVR
!DAR
!DCR
!Description
|-
|[[play (Browser)|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 (Browser)|stop]]
|7
|✘
|✘
|✔
|Used when switching between ad and content or content and ad.
|-
|[[loadMetadata (Browser)|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 (Browser)|setPlayheadPosition]]
|49
|✘
|✘
|✔
|Used to send the playhead position.
|-
|[[sendID3 (Browser)|sendID3]]
|55
|✔
|✘
|✘
|Used to send the ID3 metadata.
|-
|[[end (Browser)|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 (Browser)|setVolume]]
|61
|✔
|✘
|✔
|Used to pass in the player volume levels in %. Default value is -1.
|-
|[[staticstart (Browser)|staticstart]]
|14
|✘
|✘
|✔
|Used to send the metadata for the static page.
|-
|[[StaticEnd (Browser)|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 (Browser)|onPaginate]]
|30
|✘
|✘
|✔
|Used to initialize the SDK object
|}

Domless SDK API Reference

2026-01-27T21:27:03Z

AmySockanathan: /* SetTimeout */

==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 [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 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 <code>apid</code> 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 <code>npm install <nowiki>https://github.com/NielsenDigitalSDK/bsdk-domless</nowiki></code> and import the <code>BsdkInstance</code> into video player component
import { BsdkInstance } from 'bsdk-domless'
======status.ok()======
Initialization of the instance can be done with <code>status.ok()</code> 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: ImplementationHooks are mandatory for the DOM-less SDK instance. Please refer to the ImplementationHooks 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'''
!'''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 ===
====='''''<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>'''''=====

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.setItem('nol_lsid', 'umy3w4ik9usw2ppqmw2vkecckxfob1697308388')

===== Methods =====
<blockquote>setItem()

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

getItem()

storage.getItem(key: string)

removeItem()

storage.removeItem(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>

==== SetTimeout ====
Function to set a timer in milliseconds to execute a block of code on expiry

e.g. SetTimeout(callback , 1000)
===== Parameters =====
<blockquote>callback Required

● A function to execute when the timer expires

timeout Required

● number - The time that the timer should wait before the callback function is executed. This is in milliseconds.
</blockquote>

==== SetInterval ====
Function to repeatedly call a function with a fixed time delay between each call.

e.g. SetInterval(callback , 1000)
===== Parameters =====
<blockquote>callback Required

● A function to be executed every interval specified

interval Required

● number - The delay between the execution of the function
</blockquote>
==== ClearTimeout ====
Function to cancel the timeout previously set by SetTimeout

e.g. ClearTimeout(1000)
===== Parameters =====
<blockquote>timeout Required

● number - The time that the timer should wait before the callback function is executed
</blockquote>
==== ClearInterval ====
Function to cancel the timed repeating call which was previously established through SetInterval

e.g. ClearInterval(1000)
===== Parameters =====
<blockquote>interval Required

● number - The delay between the execution of the function
</blockquote>
==== Nielsen Debug Node.js Server for Event Tracking ====
We are excited to announce the beta version of our Debug Node.js server, designed to track requests and events sent from our Dom-less SDK using WebSocket connections. While this feature is not officially released, we are currently looking for users interested in beta testing.

If you'd like to try this tool and provide feedback, please reach out to your Nielsen Technical Account Manager (TAM) for more information. Your insights would be invaluable in helping us refine this feature for a future release!

== DOM-less SDK API Methods & Properties ==
{| class="wikitable"
|+
!Method/Property
!Event #
!DTVR
!DAR
!DCR
!Description
|-
|[[play (Browser)|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 (Browser)|stop]]
|7
|✘
|✘
|✔
|Used when switching between ad and content or content and ad.
|-
|[[loadMetadata (Browser)|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 (Browser)|setPlayheadPosition]]
|49
|✘
|✘
|✔
|Used to send the playhead position.
|-
|[[sendID3 (Browser)|sendID3]]
|55
|✔
|✘
|✘
|Used to send the ID3 metadata.
|-
|[[end (Browser)|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 (Browser)|setVolume]]
|61
|✔
|✘
|✔
|Used to pass in the player volume levels in %. Default value is -1.
|-
|[[staticstart (Browser)|staticstart]]
|14
|✘
|✘
|✔
|Used to send the metadata for the static page.
|-
|[[StaticEnd (Browser)|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 (Browser)|onPaginate]]
|30
|✘
|✘
|✔
|Used to initialize the SDK object
|}

Domless SDK API Reference

2026-01-27T21:23:27Z

AmySockanathan: Implementation Hooks: Added settimeout, setinterval, cleartimeout and clearinterval

==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 [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 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 <code>apid</code> 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 <code>npm install <nowiki>https://github.com/NielsenDigitalSDK/bsdk-domless</nowiki></code> and import the <code>BsdkInstance</code> into video player component
import { BsdkInstance } from 'bsdk-domless'
======status.ok()======
Initialization of the instance can be done with <code>status.ok()</code> 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: ImplementationHooks are mandatory for the DOM-less SDK instance. Please refer to the ImplementationHooks 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'''
!'''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 ===
====='''''<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>'''''=====

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.setItem('nol_lsid', 'umy3w4ik9usw2ppqmw2vkecckxfob1697308388')

===== Methods =====
<blockquote>setItem()

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

getItem()

storage.getItem(key: string)

removeItem()

storage.removeItem(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>

==== SetTimeout ====
Function to set a timer to execute a block of code on expiry

e.g. SetTimeout(callback , 1000)
===== Parameters =====
<blockquote>callback Required

● A function to execute when the timer expires

timeout Required

● number - The time that the timer should wait before the callback function is executed
</blockquote>
==== SetInterval ====
Function to repeatedly call a function with a fixed time delay between each call.

e.g. SetInterval(callback , 1000)
===== Parameters =====
<blockquote>callback Required

● A function to be executed every interval specified

interval Required

● number - The delay between the execution of the function
</blockquote>
==== ClearTimeout ====
Function to cancel the timeout previously set by SetTimeout

e.g. ClearTimeout(1000)
===== Parameters =====
<blockquote>timeout Required

● number - The time that the timer should wait before the callback function is executed
</blockquote>
==== ClearInterval ====
Function to cancel the timed repeating call which was previously established through SetInterval

e.g. ClearInterval(1000)
===== Parameters =====
<blockquote>interval Required

● number - The delay between the execution of the function
</blockquote>
==== Nielsen Debug Node.js Server for Event Tracking ====
We are excited to announce the beta version of our Debug Node.js server, designed to track requests and events sent from our Dom-less SDK using WebSocket connections. While this feature is not officially released, we are currently looking for users interested in beta testing.

If you'd like to try this tool and provide feedback, please reach out to your Nielsen Technical Account Manager (TAM) for more information. Your insights would be invaluable in helping us refine this feature for a future release!

== DOM-less SDK API Methods & Properties ==
{| class="wikitable"
|+
!Method/Property
!Event #
!DTVR
!DAR
!DCR
!Description
|-
|[[play (Browser)|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 (Browser)|stop]]
|7
|✘
|✘
|✔
|Used when switching between ad and content or content and ad.
|-
|[[loadMetadata (Browser)|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 (Browser)|setPlayheadPosition]]
|49
|✘
|✘
|✔
|Used to send the playhead position.
|-
|[[sendID3 (Browser)|sendID3]]
|55
|✔
|✘
|✘
|Used to send the ID3 metadata.
|-
|[[end (Browser)|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 (Browser)|setVolume]]
|61
|✔
|✘
|✔
|Used to pass in the player volume levels in %. Default value is -1.
|-
|[[staticstart (Browser)|staticstart]]
|14
|✘
|✘
|✔
|Used to send the metadata for the static page.
|-
|[[StaticEnd (Browser)|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 (Browser)|onPaginate]]
|30
|✘
|✘
|✔
|Used to initialize the SDK object
|}

Domless SDK API Reference

2025-11-25T13:45:34Z

AmySockanathan: /* storage */

==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 [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 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 <code>apid</code> 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 <code>npm install <nowiki>https://github.com/NielsenDigitalSDK/bsdk-domless</nowiki></code> and import the <code>BsdkInstance</code> into video player component
import { BsdkInstance } from 'bsdk-domless'
======status.ok()======
Initialization of the instance can be done with <code>status.ok()</code> 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: ImplementationHooks are mandatory for the DOM-less SDK instance. Please refer to the ImplementationHooks 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'''
!'''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 =====
<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.setItem('nol_lsid', 'umy3w4ik9usw2ppqmw2vkecckxfob1697308388')

===== Methods =====
<blockquote>setItem()

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

getItem()

storage.getItem(key: string)

removeItem()

storage.removeItem(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>'''''=====

==== Nielsen Debug Node.js Server for Event Tracking ====
We are excited to announce the beta version of our Debug Node.js server, designed to track requests and events sent from our Dom-less SDK using WebSocket connections. While this feature is not officially released, we are currently looking for users interested in beta testing.

If you'd like to try this tool and provide feedback, please reach out to your Nielsen Technical Account Manager (TAM) for more information. Your insights would be invaluable in helping us refine this feature for a future release!

== DOM-less SDK API Methods & Properties ==
{| class="wikitable"
|+
!Method/Property
!Event #
!DTVR
!DAR
!DCR
!Description
|-
|[[play (Browser)|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 (Browser)|stop]]
|7
|✘
|✘
|✔
|Used when switching between ad and content or content and ad.
|-
|[[loadMetadata (Browser)|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 (Browser)|setPlayheadPosition]]
|49
|✘
|✘
|✔
|Used to send the playhead position.
|-
|[[sendID3 (Browser)|sendID3]]
|55
|✔
|✘
|✘
|Used to send the ID3 metadata.
|-
|[[end (Browser)|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 (Browser)|setVolume]]
|61
|✔
|✘
|✔
|Used to pass in the player volume levels in %. Default value is -1.
|-
|[[staticstart (Browser)|staticstart]]
|14
|✘
|✘
|✔
|Used to send the metadata for the static page.
|-
|[[StaticEnd (Browser)|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 (Browser)|onPaginate]]
|30
|✘
|✘
|✔
|Used to initialize the SDK object
|}

Domless SDK API Reference

2025-11-25T13:17:19Z

AmySockanathan: /* Methods */

==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 [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 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 <code>apid</code> 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 <code>npm install <nowiki>https://github.com/NielsenDigitalSDK/bsdk-domless</nowiki></code> and import the <code>BsdkInstance</code> into video player component
import { BsdkInstance } from 'bsdk-domless'
======status.ok()======
Initialization of the instance can be done with <code>status.ok()</code> 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: ImplementationHooks are mandatory for the DOM-less SDK instance. Please refer to the ImplementationHooks 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'''
!'''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 =====
<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>setItem()

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

getItem()

storage.getItem(key: string)

removeItem()

storage.removeItem(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>'''''=====

==== Nielsen Debug Node.js Server for Event Tracking ====
We are excited to announce the beta version of our Debug Node.js server, designed to track requests and events sent from our Dom-less SDK using WebSocket connections. While this feature is not officially released, we are currently looking for users interested in beta testing.

If you'd like to try this tool and provide feedback, please reach out to your Nielsen Technical Account Manager (TAM) for more information. Your insights would be invaluable in helping us refine this feature for a future release!

== DOM-less SDK API Methods & Properties ==
{| class="wikitable"
|+
!Method/Property
!Event #
!DTVR
!DAR
!DCR
!Description
|-
|[[play (Browser)|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 (Browser)|stop]]
|7
|✘
|✘
|✔
|Used when switching between ad and content or content and ad.
|-
|[[loadMetadata (Browser)|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 (Browser)|setPlayheadPosition]]
|49
|✘
|✘
|✔
|Used to send the playhead position.
|-
|[[sendID3 (Browser)|sendID3]]
|55
|✔
|✘
|✘
|Used to send the ID3 metadata.
|-
|[[end (Browser)|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 (Browser)|setVolume]]
|61
|✔
|✘
|✔
|Used to pass in the player volume levels in %. Default value is -1.
|-
|[[staticstart (Browser)|staticstart]]
|14
|✘
|✘
|✔
|Used to send the metadata for the static page.
|-
|[[StaticEnd (Browser)|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 (Browser)|onPaginate]]
|30
|✘
|✘
|✔
|Used to initialize the SDK object
|}

Domless SDK API Reference

2025-11-25T00:55:22Z

AmySockanathan: Replace Storage set, get and remove function names with setItem, getItem and removeItem.

==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 [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 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 <code>apid</code> 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 <code>npm install <nowiki>https://github.com/NielsenDigitalSDK/bsdk-domless</nowiki></code> and import the <code>BsdkInstance</code> into video player component
import { BsdkInstance } from 'bsdk-domless'
======status.ok()======
Initialization of the instance can be done with <code>status.ok()</code> 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: ImplementationHooks are mandatory for the DOM-less SDK instance. Please refer to the ImplementationHooks 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'''
!'''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 =====
<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>setItem()

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

getItem()

storage.get(key: string)

removeItem()

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>'''''=====

==== Nielsen Debug Node.js Server for Event Tracking ====
We are excited to announce the beta version of our Debug Node.js server, designed to track requests and events sent from our Dom-less SDK using WebSocket connections. While this feature is not officially released, we are currently looking for users interested in beta testing.

If you'd like to try this tool and provide feedback, please reach out to your Nielsen Technical Account Manager (TAM) for more information. Your insights would be invaluable in helping us refine this feature for a future release!

== DOM-less SDK API Methods & Properties ==
{| class="wikitable"
|+
!Method/Property
!Event #
!DTVR
!DAR
!DCR
!Description
|-
|[[play (Browser)|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 (Browser)|stop]]
|7
|✘
|✘
|✔
|Used when switching between ad and content or content and ad.
|-
|[[loadMetadata (Browser)|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 (Browser)|setPlayheadPosition]]
|49
|✘
|✘
|✔
|Used to send the playhead position.
|-
|[[sendID3 (Browser)|sendID3]]
|55
|✔
|✘
|✘
|Used to send the ID3 metadata.
|-
|[[end (Browser)|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 (Browser)|setVolume]]
|61
|✔
|✘
|✔
|Used to pass in the player volume levels in %. Default value is -1.
|-
|[[staticstart (Browser)|staticstart]]
|14
|✘
|✘
|✔
|Used to send the metadata for the static page.
|-
|[[StaticEnd (Browser)|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 (Browser)|onPaginate]]
|30
|✘
|✘
|✔
|Used to initialize the SDK object
|}

Third Party Encoding Facilities

2025-08-28T17:12:25Z

AmySockanathan: Creating new page for Third Party Encoding Facilities

This is a test page

TV

2025-08-28T17:11:20Z

AmySockanathan: Adding section for Third Party Encoding Faclities

[[Category:TV]]
{{Banner|Encoder Support|{{Breadcrumb|}} {{CurrentBreadcrumb}}}}





{{Alert|
'''Nielsen Encoder Installation and Configuration Policy 2022 Now Available:'''<br>
'''Official release notification: [https://nielsendownloads.digitalengsdk.com/tv/Nielsen-Encoder-Policy-Rev-H-2025-03.pdf.pdf Nielsen Encoder Installation and Configuration Policy 2025]

}}

{| class="wikitable"
|-
! style="width: 50px;" |
! Certified Vendors
|-
| rowspan="1" |
| '''[[Nielsen Encoder Certified Vendors]]'''
|-
| rowspan="1" |
| '''[[Nielsen Decoder Certified Vendors]]'''
|-
| rowspan="1" |
| '''[[PCM-to-ID3 Certified Vendors]]'''
|-
|}
{| class="wikitable"
|-
! style="width: 50px;" |
! Third Party Encoding Facilities
|-
| rowspan="1" |
| '''[[Third Party Encoding Facilities]]'''
|-
|}

{| class="wikitable"
|-
! style="width: 50px;" |
! Reference & Policy Supplements
|-
| rowspan="1" | {{SmallIcon|PDFIcon.png}}
| '''[https://nielsendownloads.digitalengsdk.com/tv/Nielsen-Encoder-Policy-Rev-H-2025-03.pdf.pdf Nielsen Encoder Installation and Configuration Policy 2025]'''
|-



|-
| rowspan="1" | {{SmallIcon|PDFIcon.png}}
| '''[https://nielsendownloads.digitalengsdk.com/tv/Encoding/Nielsen+Encoder+Solutions+2024.pdf Nielsen Encoder Solutions 2024]'''
|-
| rowspan="1" | {{SmallIcon|PDFIcon.png}}
| '''[https://nielsendownloads-blue.digitalengsdk.com/tv/Encoding/MVPD%20provided%20Direct%20Feeds%20with%20Unique%20Commercial%20Content.pdf MVPD provided Direct Feeds with Unique Commercial Content]'''
|-
| rowspan="1" | {{SmallIcon|PDFIcon.png}}
| '''[https://nielsendownloads-blue.digitalengsdk.com/tv/Encoder%20Alert%20Distribution%20List%20Instructions_Final.pdf Nielsen Encoder Alert Distribution List - Instructions]'''
|}

{{CategoryIcon|EncodingIcon.png|TV Audio Encoding}}
{| class="wikitable"
|-
! style="width: 75px;" |
! style="width: 35%;" | Software
! style="width: 45px;" | OS
! Download
|-

| {{SmallIcon|CircuitIcon.png}}
| '''[[NWE-3GA]]''' || {{OSIcon|WindowsIcon.png}} ||
{{TVDownloadRequestLink|name=NWE-3GA Software package Rev 2.5.0.0 |dlid= 5a3f0ecbef6bfe4c9339fb8346a0064a645ebebf}} <small>''('''New!''')''</small>

|-


|-
| {{SmallIcon|RackIcon.png}}
| '''[[NWE-TS]]'''
|| {{OSIcon|FirmwareIcon.png}} ||

{{TVDownloadRequestLink|name=NWE-TS Firmware 4.8.1|dlid=ee2f22f3a7347b52627e2d393fab7f3d90d90943}} <small>''('''New!''')''</small>
{{TVDownloadRequestLink|name=NWE-TS Firmware 4.6.10|dlid=31e04631784a2438fc41c81f34a49c33cd513ec6}}

|-

| {{SmallIcon|VODIcon.png}}
| '''[[VOD Content Encoder]]'''
|| {{OSIcon|WindowsIcon.png}} ||
*[[Encoder Downloads| VOD Content Encoder]]

|-

| {{SmallIcon|VODIcon.png}}
| '''[[VOD in TV Ratings]]''' ''<small>(formerly RTVOD)</small>''
|| {{OSIcon|WindowsIcon.png}} ||
*[[Encoder Downloads| VOD in TV Ratings]] ''<small>(formerly RTVOD)</small>''

|-

| {{SmallIcon|ComputerWaveIcon.png}}
| '''[[SpoTTrac®]]'''
|| {{OSIcon|FirmwareIcon.png}} ||
*[[Encoder Downloads| SpoTTrac Firmware]]

|-

| {{SmallIcon|EncoderGrayIcon.png}}
| '''[[NAVE II]]'''
|| {{OSIcon|WindowsIcon.png}} ||
*NAVE II Firmware v38
*NAVE II Manager
|-

| {{SmallIcon|EncoderGrayIcon.png}}
| '''[[NAVE IIC]]'''
|| {{OSIcon|WindowsIcon.png}} ||
*NAVE IIC Firmware v3.4.15
|}

{{CategoryIcon|ID3Icon.png|ID3 Transcoding}}
{| class="wikitable"
|-
! style="width: 75px;" |
! style="width: 35%;" | Software
! style="width: 45px;" | OS
! Download

|-

|rowspan="3"| {{SmallIcon|ID3XcodeIcon.png}}
|rowspan="3"| '''[[ID3 Transcoders]]'''
''<small>(Click for Documentation, Software Updates, and Test Streams)</small>''
|| {{OSIcon|WindowsIcon.png}} ||
{{TVDownloadRequestLink|name=PCM-to-ID3 SDK (Windows) v2.3.2|dlid=ac5b0e72a84b1a6e86da1a8fe0a89e24083468eb}}
{{TVDownloadRequestLink|name=PCM-to-ID3 SDK (Windows Visual Studio 2013) v2.3|dlid=533cee44e69c6859e56acd9cbb38334d6b215c00}}
|-
|| {{OSIcon|LinuxIcon.png}} ||
{{TVDownloadRequestLink|name=PCM-to-ID3 SDK (Linux x64 GLIBC 2.12) v2.3.2|dlid=c499535f6ce9a0326a408b167079e01a0596e141}}
{{TVDownloadRequestLink|name=PCM-to-ID3 SDK (Linux x64 GLIBC 2.17) v2.3.2|dlid=b353e404994a1d26726b196960efe40c30427571}}
{{TVDownloadRequestLink|name=PCM-to-ID3 SDK (Linux x86 GLIBC 2.17) v2.3.2|dlid=f82dfbde6f5f68ccf677b63e32fc83e68fa82cd6}}
|-
|| {{OSIcon|macOSIcon.png}} ||
{{TVDownloadRequestLink|name=PCM-to-ID3 SDK (MacOS) v2.3|dlid=3a9d04be165f39ac956278c8292cd1b87ce34b62}}

|-
|rowspan="1"| {{SmallIcon|ID3DashIcon.png}}
|rowspan="1"| '''[[ID3 in MPEG-DASH]]'''
''<small>(Click for Documentation, and Sample Audio Files)</small>''
|| {{OSIcon|StaticIcon.png}} ||
*[https://nielsendownloads-blue.digitalengsdk.com/tv/ID3%20Transcoding/ID3%20in%20MPEG-DASH/bbb-MPEG-DASH.zip Big Buck Bunny MPEG-DASH Nielsen Tagged]
*[https://nielsendownloads-blue.digitalengsdk.com/tv/ID3%20Transcoding/ID3%20in%20MPEG-DASH/nielsenconsumer-MPEG-DASH.zip Nielsen Consumer MPEG-DASH Nielsen Tagged]
*[https://nielsendownloads-blue.digitalengsdk.com/tv/ID3%20Transcoding/ID3%20in%20MPEG-DASH/nielsenxplatform-MPEG-DASH.zip Nielsen Cross Platform MPEG-DASH Nielsen Tagged]
|-

|rowspan="3"| {{SmallIcon|ID3ValidateIcon.png}}
|rowspan="3"| '''[[PCM-to-ID3 Validator]]'''
''<small>(Click for Documentation, and Downloads)</small>''
|| {{OSIcon|WindowsIcon.png}} ||
{{TVDownloadRequestLink|name=PCM-to-ID3 Validator (Windows) v1.8|dlid=67d34c64d1ed349c1ad92ac47adf62c877f47fcb}}
|-
|| {{OSIcon|LinuxIcon.png}} ||
{{TVDownloadRequestLink|name=PCM-to-ID3 Validator (CentOS) v1.7|dlid=dd6b62c76995aa7e1702c60e02076348ceaf573b}}
|-
|| {{OSIcon|macOSIcon.png}} ||
{{TVDownloadRequestLink|name=PCM-to-ID3 Validator (MacOS) v1.7|dlid=3afc5a7ec29593e2eb47daa9746b6d16cbd785e1}}

|-

|rowspan="3"| {{SmallIcon|ID3ValidateIcon.png}}
|rowspan="3"| '''[[PCM-to-ID3 Validator SDK]]'''
''<small>(Click for Documentation, and Downloads)</small>''
|| {{OSIcon|WindowsIcon.png}} ||
{{TVDownloadRequestLink|name=PCM-to-ID3 Validator SDK (Windows) v1.8|dlid=78a936556ebc5caf57d2fc4d09de3a272ace9fea}}
|-
|| {{OSIcon|LinuxIcon.png}} ||
{{TVDownloadRequestLink|name=PCM-to-ID3 Validator SDK (CentOS) v1.7|dlid=ccb9af4ef45cfcf7aa4406ca63ab3b7c6efdad11}}
|-
|| {{OSIcon|macOSIcon.png}} ||
{{TVDownloadRequestLink|name=PCM-to-ID3 Validator SDK (MacOS) v1.7|dlid=05e99551d28ef4a65eab6168ad2872648346aab2}}
|}

{{CategoryIcon|DiagnosisToolsIcon.png|Diagnostic Tools}}
{| class="wikitable"
|-
! style="width: 75px;" |
! style="width: 35%;" | Software
! style="width: 45px;" | OS
! Download

|-

| {{SmallIcon|NACATIcon.png}}
|| '''[[Nielsen Audio Code Analysis Tool 3 for TV|Nielsen Audio Code Analysis Tool 3 (NACAT3)]]'''
|| {{OSIcon|WindowsIcon.png}} ||
{{TVDownloadRequestLink|name=NACAT3 3.0.0.1|dlid=ce2cba3d4b4231a0978c632028c1a45479a8184d}} <small>''('''New!''')''</small>

|-

| {{SmallIcon|NDICEIcon.png}}
|| '''[[Nielsen Digital Code Extractor]]'''
|| {{OSIcon|WindowsIcon.png}} ||
{{TVDownloadRequestLink|name=Nielsen Digital Code Extractor Installer|dlid=c0eb8eb1802bd08956f6e215473ef1881274a6df}} <BR> (See special installation instructions in [[Nielsen Digital Code Extractor|guide]])

|-

|rowspan="3"| {{SmallIcon|SDKIcon.png}}
|rowspan="3"| '''[[Decoder SDK Monitor]]'''
|| {{OSIcon|WindowsIcon.png}} ||
{{TVDownloadRequestLink|name=Decoder SDK Monitor (Windows vs2017) v1.4|dlid=b3ae411765cfa2b878c3f50c0824e61d81a58fbb}}
|-
|| {{OSIcon|WindowsIcon.png}} ||
{{TVDownloadRequestLink|name=Decoder SDK Monitor (Windows vs2015) v1.4|dlid=68d1fd697862e663a7aa2efc46377f053c983a5a}}
|-
|| {{OSIcon|LinuxIcon.png}} ||
{{TVDownloadRequestLink|name=Decoder SDK Monitor (CentOS) v1.4|dlid=c978921ba90736bf7f2c82287a0a97af89109bec}}

|-

| {{SmallIcon|NDICEIcon.png}}
|| '''[[Nielsen Monitor Application]]'''
|| {{OSIcon|WindowsIcon.png}} ||
{{TVDownloadRequestLink|name=Nielsen Monitor Application (Windows) v1.4|dlid=6ddf77a8f67dff67b4cbad1fee630ee80318b5bf}}

|}

Digital Measurement Android Artifactory Guide

2025-08-14T18:06:46Z

AmySockanathan: Update "grade" to "gradle"

{{Breadcrumb|}} {{Breadcrumb|Digital}} {{Breadcrumb|Digital Downloads}} {{CurrentBreadcrumb}}
[[Category:Digital]]
__NOTOC__
The Nielsen AppSDK can either be downloaded directly from the [http://engineeringportal.nielsen.com Engineering Portal], or can be integrated directly within an application through the use of a CocoaPod or Gradle.

= How to install the Nielsen AppSDK using Gradle for Android =
Below are the steps which need to be performed by app developers to integrate the Nielsen App SDK within an Android application.

== Add Nielsen Maven Repository ==

Please add the Nielsen maven repository inside the repositories section of your app's module build.gradle file like below:
<br>
<source lang="android">
repositories {
//Copy below code inside repository section of app’s build.gradle file
maven { url 'https://raw.githubusercontent.com/NielsenDigitalSDK/nielsenappsdk-android/master/'
}
</source>
<br>
<blockquote>
[[Image:AlertIcon.png|left|60px|link=|class=smallIcon]] Starting on Sept 21, 2021 the Nielsen SDK has moved to a public repository. Credentials are no longer required.
</blockquote>
<br>

== Add gradle dependency ==

Please add Nielsen app SDK as compile time dependency inside build.gradle file as below
=== gradle 4.x and above ===
For gradle version starting with 4.x add the following line inside dependencies section of build.gradle file.<br>
<source lang="html">implementation 'com.nielsenappsdk.${market}:${flavor}:${version}'</source>
<br>
<source lang="html">
dependencies { ....
implementation 'com.nielsenappsdk.global:ad:+' // Using + will provide the latest version
}
</source>

=== gradle prior to 4.x ===
For gradle version previous to 4.x add below line inside dependencies section of build.gradle file.
<source lang="html">compile 'com.nielsenappsdk.${market}:${flavor}:${version}'</source>
<br>
<source lang="html">
dependencies { ....
compile 'com.nielsenappsdk.global:ad:+' // Using + will provide the latest version
}
</source>

== Version and Flavor Control ==
With version 8.1.0.0+ of the Nielsen appSDK, it is possible to request a specific '''${flavor}''' that reads the '''Google Ad ID''', '''Android ID''', or is '''Kid app''' friendly (noID). For example:<br>
<source lang="html">implementation 'com.nielsenappsdk.${market}:${flavor}:${version}'</source>
* if the flavor selected is equal to <code>ad</code> the Nielsen SDK will try to obtain the googleAdID if the user has not opted out.
* If the flavor is <code>noad</code> then the Nielsen SDK will attempt to obtain the AndroidID.
* If the flavor selected is <code>noid</code> then the Nielsen SDK will not request any identifier which is required for many kid apps.
<blockquote>To ensure backward compatability, <code> implementation 'com.nielsenappsdk:${market}:${version}'</code> will continue to be supported.</blockquote>
{| class="wikitable"
|-
! SDK Version
! ${market}
! ${flavor}
! ${version}
! Examples
|-
| Appsdk 8.1.0.0+
|<code>global</code><br /><code>agf</code>
|<code>ad</code><br /><code>noad</code><br /><code>noid</code>
| + is most recent version<br /><code>8.1.0.0</code>
|<code>'com.nielsenappsdk.global:ad:+'<br />'com.nielsenappsdk.global:noad:+'<br />'com.nielsenappsdk.global:noad:8.1.0.0'</code>
|-
| AppSDK 7 to 8.0.0.0
|<code>globalx</code><br /><code>global</code><br /><code>agf</code><br /><code>agfx</code>
|not used
| + is most recent version<br /><code>7.1.0.0</code><br /><code>8.0.0.0</code>
|<code>'com.nielsenappsdk:globalx:+'<br />'com.nielsenappsdk:global:8.0.0.0'<br />'com.nielsenappsdk:agf:8.0.0.0'</code><br /><br />
|}
<blockquote>If using version control, a warning message will be displayed within the console trace during the build of your app,
and it will show all sdk versions released to-date, allowing a developer to select a more recent build if desired. </blockquote> Starting with Version 8.x, the Nielsen SDK will only support Androidx.

== Ensuring you have the latest release information ==
It is recommended to use <code>+</code> for <code>${version}</code> to ensure you receive the most recent version of the NielsenSDK; however, if you are specifying the exact version of the SDK, please use only the first 3 digits. EG: 8.1.0<br>

A sample if using AppSDK 8.1.0.0 + would be:
<source lang="html">
dependencies { ....
implementation 'com.nielsenappsdk.global:ad:+'
}
</source>
<br>
If using AppSDK 7 to 8.0.0.0
<source lang="html">
dependencies { ....
implementation 'com.nielsenappsdk:globalx:8.0.0'
}
</source>

In addition, please add below gradle task inside your <code> build.gradle (Module:app)</code> or <code>build.gradle(Project:My-app)</code> file to fetch latest release details of nielsen app sdk as below:

<blockquote>Please note: The <code> build.gradle (Module:app)</code> can overwrite the <code>build.gradle(Project:My-app)</code>.</blockquote>

<source lang="java">task NielsenSdkReleaseCheck {
def p = ['curl',"https://raw.githubusercontent.com/NielsenDigitalSDK/" +
"nielsenappsdk-android/master/com/nielsenappsdk/global/" +
"NielsenAppSdk-ReadMe.md"].execute().text
project.logger.log(LogLevel.ERROR,p)
}
preBuild.dependsOn('NielsenSdkReleaseCheck')
</source>

=== App Suffix Reference ===
The Nielsen AppSDK has various configurations per market and distribution type, which can be determined by reviewing the [[Digital Measurement Android Suffix Guide|sdk suffix]]. The first part will be the SDK version: 3 digits for the major SDK version and 1 digit for the minor SDK version. EG: <code>aa.8.1.0.0_abc</code>

== Sync ==

If you are finished with all previous steps then you can sync your build.gradle and after successful build you are ready to use Nielsen App SDK library in your code.

== Sample file ==
The below is an example of a very basic app build.gradle file
<syntaxhighlight lang=Java>
plugins {
id 'com.android.application'
}

android {
compileSdkVersion 30
buildToolsVersion "30.0.3"

defaultConfig {
applicationId "com.nielsen.simplestandardandroidart"
minSdkVersion 23
targetSdkVersion 30
versionCode 1
versionName "1.0"

testInstrumentationRunner "androidx.test.runner.AndroidJUnitRunner"
}

buildTypes {
release {
minifyEnabled false
proguardFiles getDefaultProguardFile('proguard-android-optimize.txt'), 'proguard-rules.pro'
}
}
repositories {
//Copy below code inside repository section of app’s build.gradle file
maven { url 'https://raw.githubusercontent.com/NielsenDigitalSDK/nielsenappsdk-android/master/'
}
}
compileOptions {
sourceCompatibility JavaVersion.VERSION_1_8
targetCompatibility JavaVersion.VERSION_1_8
}
}

dependencies {

implementation 'androidx.appcompat:appcompat:1.2.0'
implementation 'com.google.android.material:material:1.1.0'
implementation 'androidx.constraintlayout:constraintlayout:2.0.4'
testImplementation 'junit:junit:4.+'
androidTestImplementation 'androidx.test.ext:junit:1.1.2'
androidTestImplementation 'androidx.test.espresso:espresso-core:3.3.0'
implementation 'androidx.lifecycle:lifecycle-extensions:2.2.0'
implementation 'com.google.android.gms:play-services-ads:20.3.0'
implementation 'com.nielsenappsdk.global:ad:+'
}

task NielsenSdkReleaseCheck {
def p = ['curl',"https://raw.githubusercontent.com/NielsenDigitalSDK/" +
"nielsenappsdk-android/master/com/nielsenappsdk/global/" +
"NielsenAppSdk-ReadMe.md"].execute().text
project.logger.log(LogLevel.ERROR,p)
}
preBuild.dependsOn('NielsenSdkReleaseCheck')
</syntaxhighlight>

Template:Browser Privacy and Opt-Out

2025-08-05T20:46:45Z

AmySockanathan: Remove Opt Out Overview

== Privacy and Opt-Out ==
There are two primary methods for implementing user Opt-out preferences:
# [[#User Opt Out|User Opt Out]] - Provide a link to the Nielsen Privacy Policy page when a User can make their selection
# [[#Initialization Opt Out|Initialization Opt Out]] - Global OptOut Parameter

=== User Opt Out ===
The site must provide a means for the user to opt-out of, or opt back into, Nielsen Measurement. A user can opt-out if they would 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/digitalprivacy

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 opt-out.

The following paragraph is a template for a Privacy Statement.
<blockquote>
The properties may feature Nielsen proprietary measurement software, which will allow 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 with regard to it, please see the Nielsen Digital Measurement Privacy Policy at https://www.nielsen.com/digitalprivacy
</blockquote>

==== User Opt Back In ====
Once users have opted-out, they can choose to opt back into Nielsen Measurement at anytime by selecting the opt back in link on the Nielsen Digital Privacy Policy page. When a user selects the link, they will be able to be measured.

=== Initialization Opt Out ===
The BSDK600 now supports the ability to optout on initialization of the SDK by allowing an optout global parameter to be passed. This optout will be maintained through the session of the SDK instance. Specifications and limitations are specified below.

{| class="wikitable"
|-
! Type
! Supported Values
! Notes
! Optout
|-
||optout||True, Yes, or 1|| Case is insensitive and can be string or bool
Example: nlsQ("XXXXXXXX-BH45-JKY6-BKH7-67GJKY68GJK7", "myInstance", { optout: true});
|| Ping parameter will set uoo=true.
|-
||optout|| False, No, or 0 || Case is insensitive and can be string or bool
Example: nlsQ("XXXXXXXX-BH45-JKY6-BKH7-67GJKY68GJK7", "myInstance", { optout: false});
|| Ping parameter will set uoo to blank.
|-
|}
==== Example of using OptOut ====

<syntaxhighlight lang="javascript">
var nSdkInstance = NOLBUNDLE.nlsQ("XXXXXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXX", "nlsnInstance", {
nol_sdkDebug: "debug",
optout: "true"
});
</syntaxhighlight>

Template:Browser Privacy and Opt-Out

2025-08-05T20:45:34Z

AmySockanathan: Remove details of optout process

TV

2025-07-23T19:49:58Z

AmySockanathan: Changed link to Nielsen Audio Code Analysis Tool 3 to TV page

[[Category:TV]]
{{Banner|Encoder Support|{{Breadcrumb|}} {{CurrentBreadcrumb}}}}





{{Alert|
'''Nielsen Encoder Installation and Configuration Policy 2022 Now Available:'''<br>
'''Official release notification: [https://nielsendownloads.digitalengsdk.com/tv/Nielsen-Encoder-Policy-Rev-H-2025-03.pdf.pdf Nielsen Encoder Installation and Configuration Policy 2025]

}}

{| class="wikitable"
|-
! style="width: 50px;" |
! Certified Vendors
|-
| rowspan="1" |
| '''[[Nielsen Encoder Certified Vendors]]'''
|-
| rowspan="1" |
| '''[[Nielsen Decoder Certified Vendors]]'''
|-
| rowspan="1" |
| '''[[PCM-to-ID3 Certified Vendors]]'''
|-
|}

{| class="wikitable"
|-
! style="width: 50px;" |
! Reference & Policy Supplements
|-
| rowspan="1" | {{SmallIcon|PDFIcon.png}}
| '''[https://nielsendownloads.digitalengsdk.com/tv/Nielsen-Encoder-Policy-Rev-H-2025-03.pdf.pdf Nielsen Encoder Installation and Configuration Policy 2025]'''
|-



|-
| rowspan="1" | {{SmallIcon|PDFIcon.png}}
| '''[https://nielsendownloads.digitalengsdk.com/tv/Encoding/Nielsen+Encoder+Solutions+2024.pdf Nielsen Encoder Solutions 2024]'''
|-
| rowspan="1" | {{SmallIcon|PDFIcon.png}}
| '''[https://nielsendownloads-blue.digitalengsdk.com/tv/Encoding/MVPD%20provided%20Direct%20Feeds%20with%20Unique%20Commercial%20Content.pdf MVPD provided Direct Feeds with Unique Commercial Content]'''
|-
| rowspan="1" | {{SmallIcon|PDFIcon.png}}
| '''[https://nielsendownloads-blue.digitalengsdk.com/tv/Encoder%20Alert%20Distribution%20List%20Instructions_Final.pdf Nielsen Encoder Alert Distribution List - Instructions]'''
|}

{{CategoryIcon|EncodingIcon.png|TV Audio Encoding}}
{| class="wikitable"
|-
! style="width: 75px;" |
! style="width: 35%;" | Software
! style="width: 45px;" | OS
! Download
|-

| {{SmallIcon|CircuitIcon.png}}
| '''[[NWE-3GA]]''' || {{OSIcon|WindowsIcon.png}} ||
{{TVDownloadRequestLink|name=NWE-3GA Software package Rev 2.5.0.0 |dlid= 5a3f0ecbef6bfe4c9339fb8346a0064a645ebebf}} <small>''('''New!''')''</small>

|-


|-
| {{SmallIcon|RackIcon.png}}
| '''[[NWE-TS]]'''
|| {{OSIcon|FirmwareIcon.png}} ||

{{TVDownloadRequestLink|name=NWE-TS Firmware 4.8.1|dlid=ee2f22f3a7347b52627e2d393fab7f3d90d90943}} <small>''('''New!''')''</small>
{{TVDownloadRequestLink|name=NWE-TS Firmware 4.6.10|dlid=31e04631784a2438fc41c81f34a49c33cd513ec6}}

|-

| {{SmallIcon|VODIcon.png}}
| '''[[VOD Content Encoder]]'''
|| {{OSIcon|WindowsIcon.png}} ||
*[[Encoder Downloads| VOD Content Encoder]]

|-

| {{SmallIcon|VODIcon.png}}
| '''[[VOD in TV Ratings]]''' ''<small>(formerly RTVOD)</small>''
|| {{OSIcon|WindowsIcon.png}} ||
*[[Encoder Downloads| VOD in TV Ratings]] ''<small>(formerly RTVOD)</small>''

|-

| {{SmallIcon|ComputerWaveIcon.png}}
| '''[[SpoTTrac®]]'''
|| {{OSIcon|FirmwareIcon.png}} ||
*[[Encoder Downloads| SpoTTrac Firmware]]

|-

| {{SmallIcon|EncoderGrayIcon.png}}
| '''[[NAVE II]]'''
|| {{OSIcon|WindowsIcon.png}} ||
*NAVE II Firmware v38
*NAVE II Manager
|-

| {{SmallIcon|EncoderGrayIcon.png}}
| '''[[NAVE IIC]]'''
|| {{OSIcon|WindowsIcon.png}} ||
*NAVE IIC Firmware v3.4.15
|}

{{CategoryIcon|ID3Icon.png|ID3 Transcoding}}
{| class="wikitable"
|-
! style="width: 75px;" |
! style="width: 35%;" | Software
! style="width: 45px;" | OS
! Download

|-

|rowspan="3"| {{SmallIcon|ID3XcodeIcon.png}}
|rowspan="3"| '''[[ID3 Transcoders]]'''
''<small>(Click for Documentation, Software Updates, and Test Streams)</small>''
|| {{OSIcon|WindowsIcon.png}} ||
{{TVDownloadRequestLink|name=PCM-to-ID3 SDK (Windows) v2.3.2|dlid=ac5b0e72a84b1a6e86da1a8fe0a89e24083468eb}}
{{TVDownloadRequestLink|name=PCM-to-ID3 SDK (Windows Visual Studio 2013) v2.3|dlid=533cee44e69c6859e56acd9cbb38334d6b215c00}}
|-
|| {{OSIcon|LinuxIcon.png}} ||
{{TVDownloadRequestLink|name=PCM-to-ID3 SDK (Linux x64 GLIBC 2.12) v2.3.2|dlid=c499535f6ce9a0326a408b167079e01a0596e141}}
{{TVDownloadRequestLink|name=PCM-to-ID3 SDK (Linux x64 GLIBC 2.17) v2.3.2|dlid=b353e404994a1d26726b196960efe40c30427571}}
{{TVDownloadRequestLink|name=PCM-to-ID3 SDK (Linux x86 GLIBC 2.17) v2.3.2|dlid=f82dfbde6f5f68ccf677b63e32fc83e68fa82cd6}}
|-
|| {{OSIcon|macOSIcon.png}} ||
{{TVDownloadRequestLink|name=PCM-to-ID3 SDK (MacOS) v2.3|dlid=3a9d04be165f39ac956278c8292cd1b87ce34b62}}

|-
|rowspan="1"| {{SmallIcon|ID3DashIcon.png}}
|rowspan="1"| '''[[ID3 in MPEG-DASH]]'''
''<small>(Click for Documentation, and Sample Audio Files)</small>''
|| {{OSIcon|StaticIcon.png}} ||
*[https://nielsendownloads-blue.digitalengsdk.com/tv/ID3%20Transcoding/ID3%20in%20MPEG-DASH/bbb-MPEG-DASH.zip Big Buck Bunny MPEG-DASH Nielsen Tagged]
*[https://nielsendownloads-blue.digitalengsdk.com/tv/ID3%20Transcoding/ID3%20in%20MPEG-DASH/nielsenconsumer-MPEG-DASH.zip Nielsen Consumer MPEG-DASH Nielsen Tagged]
*[https://nielsendownloads-blue.digitalengsdk.com/tv/ID3%20Transcoding/ID3%20in%20MPEG-DASH/nielsenxplatform-MPEG-DASH.zip Nielsen Cross Platform MPEG-DASH Nielsen Tagged]
|-

|rowspan="3"| {{SmallIcon|ID3ValidateIcon.png}}
|rowspan="3"| '''[[PCM-to-ID3 Validator]]'''
''<small>(Click for Documentation, and Downloads)</small>''
|| {{OSIcon|WindowsIcon.png}} ||
{{TVDownloadRequestLink|name=PCM-to-ID3 Validator (Windows) v1.8|dlid=67d34c64d1ed349c1ad92ac47adf62c877f47fcb}}
|-
|| {{OSIcon|LinuxIcon.png}} ||
{{TVDownloadRequestLink|name=PCM-to-ID3 Validator (CentOS) v1.7|dlid=dd6b62c76995aa7e1702c60e02076348ceaf573b}}
|-
|| {{OSIcon|macOSIcon.png}} ||
{{TVDownloadRequestLink|name=PCM-to-ID3 Validator (MacOS) v1.7|dlid=3afc5a7ec29593e2eb47daa9746b6d16cbd785e1}}

|-

|rowspan="3"| {{SmallIcon|ID3ValidateIcon.png}}
|rowspan="3"| '''[[PCM-to-ID3 Validator SDK]]'''
''<small>(Click for Documentation, and Downloads)</small>''
|| {{OSIcon|WindowsIcon.png}} ||
{{TVDownloadRequestLink|name=PCM-to-ID3 Validator SDK (Windows) v1.8|dlid=78a936556ebc5caf57d2fc4d09de3a272ace9fea}}
|-
|| {{OSIcon|LinuxIcon.png}} ||
{{TVDownloadRequestLink|name=PCM-to-ID3 Validator SDK (CentOS) v1.7|dlid=ccb9af4ef45cfcf7aa4406ca63ab3b7c6efdad11}}
|-
|| {{OSIcon|macOSIcon.png}} ||
{{TVDownloadRequestLink|name=PCM-to-ID3 Validator SDK (MacOS) v1.7|dlid=05e99551d28ef4a65eab6168ad2872648346aab2}}
|}

{{CategoryIcon|DiagnosisToolsIcon.png|Diagnostic Tools}}
{| class="wikitable"
|-
! style="width: 75px;" |
! style="width: 35%;" | Software
! style="width: 45px;" | OS
! Download

|-

| {{SmallIcon|NACATIcon.png}}
|| '''[[Nielsen Audio Code Analysis Tool 3 for TV|Nielsen Audio Code Analysis Tool 3 (NACAT3)]]'''
|| {{OSIcon|WindowsIcon.png}} ||
{{TVDownloadRequestLink|name=NACAT3 3.0.0.1|dlid=ce2cba3d4b4231a0978c632028c1a45479a8184d}} <small>''('''New!''')''</small>

|-

| {{SmallIcon|NDICEIcon.png}}
|| '''[[Nielsen Digital Code Extractor]]'''
|| {{OSIcon|WindowsIcon.png}} ||
{{TVDownloadRequestLink|name=Nielsen Digital Code Extractor Installer|dlid=c0eb8eb1802bd08956f6e215473ef1881274a6df}} <BR> (See special installation instructions in [[Nielsen Digital Code Extractor|guide]])

|-

|rowspan="3"| {{SmallIcon|SDKIcon.png}}
|rowspan="3"| '''[[Decoder SDK Monitor]]'''
|| {{OSIcon|WindowsIcon.png}} ||
{{TVDownloadRequestLink|name=Decoder SDK Monitor (Windows vs2017) v1.4|dlid=b3ae411765cfa2b878c3f50c0824e61d81a58fbb}}
|-
|| {{OSIcon|WindowsIcon.png}} ||
{{TVDownloadRequestLink|name=Decoder SDK Monitor (Windows vs2015) v1.4|dlid=68d1fd697862e663a7aa2efc46377f053c983a5a}}
|-
|| {{OSIcon|LinuxIcon.png}} ||
{{TVDownloadRequestLink|name=Decoder SDK Monitor (CentOS) v1.4|dlid=c978921ba90736bf7f2c82287a0a97af89109bec}}

|-

| {{SmallIcon|NDICEIcon.png}}
|| '''[[Nielsen Monitor Application]]'''
|| {{OSIcon|WindowsIcon.png}} ||
{{TVDownloadRequestLink|name=Nielsen Monitor Application (Windows) v1.4|dlid=6ddf77a8f67dff67b4cbad1fee630ee80318b5bf}}

|}

Nielsen Audio Code Analysis Tool 3 for TV

2025-07-23T18:58:29Z

AmySockanathan: /* Software Downloads */

[[Category:TV]]
{{Breadcrumb|}} {{Breadcrumb|TV}} {{CurrentBreadcrumb}}

''' NACAT3® — Nielsen Audio Code Analysis Tool''' — The Nielsen Company has developed NACAT, a Microsoft® Windows 10/11 operating system (64-bit) PC tool to aid in diagnosing audio watermarks embedded in an audio stream.

NACAT is a Graphical User Interface (GUI) application that captures audio, extracts Nielsen codes from that audio, decodes Nielsen audio codes (including UCC), and reports the extracted audio codes.
The Nielsen EVS department uses the NACAT application for monitoring, assisting in troubleshooting, and verifying NAVE encoder installations.

'''This release has significant enhancements.'''

This version incorporates Decoder SDK v6.0.16 with its underlying UCC/Commercial Codes and sub-minute capabilities.

Enhancements include decode, display, and log both the left and right channels simultaneously for more complete monitoring. NACAT3® enables decoding of all 6 channels.

NACAT 3 for Radio requires the use of a code mapping file (SIDMAP). To request a SIDMAP file that contains the mapping for your station/station groups audio codes, please email encoding@nielsen.com. You will need to provide the list of station call letters or station ownership for the codes you’re requesting.

== Documentation ==
*[https://nielsendownloads.digitalengsdk.com/radio/Diagnostic+Tools/NACAT3%C2%AE+%E2%80%94+Nielsen+Audio+Code+Analysis+Tool.pdf NACAT3® Product Overview]

== Software Downloads ==
{{TVDownloadRequestLink|name=NACAT3 3.0.0.1|dlid=ce2cba3d4b4231a0978c632028c1a45479a8184d}}

Nielsen Audio Code Analysis Tool 3 for TV

2025-07-23T18:45:17Z

AmySockanathan: NACAT3 - Nielsen Audio Code Analysis Tool page for TV

Browser SDK Release Notes

2025-07-15T16:26:42Z

AmySockanathan: Update Release notes

{{Breadcrumb|}} {{Breadcrumb|Digital}} {{CurrentBreadcrumb}}
[[Category:Digital]]
__NOTOC__

== Release R1(v6.0.0.734) (07-08-2025) ==

* Support for DTVR Subminute feature

== Release V1(v6.0.110) (05-21-2024) ==

* Suppression of v60/v52/v53 legacy pings

== Release R2(v6.0.0.702) (10-30-2024) ==

* 2nd release of DOMless SDK
* Support DCR Static
* Support Debug interface which can be used to view API calls and SDK pings
* Support caching of pings when network is not available

== Release R1(v6.0.0.692) (07-31-2024) ==

* DOMless SDK Release with support for Amazon, ReactNative and other DOM less platforms

== Release R6(v6.0.0.673) (09-05-2023) ==

* Fix for stream id of stream 2 is populated in the last duration ping of stream 1 when mandatory END is not called

== Release R5(v6.0.0.673) (08-14-2023) (AGF Release) ==

* Fix for stream id of stream 2 is populated in the last duration ping of stream 1 when mandatory END is not called

== Release R4(v6.0.0.672) (08-01-2023) ==

* Viewability build with support for Viewability and Audibility features

== Release R3(v6.0.0.663) (05-30-2023) ==

* Support to measure static on hbbtv with the iFrame fixes.

== Release R2(v.6.0.0.648) (05-03-2023) (AGF Release) ==

* Support to measure DCR static when browser sdk is initialized on parent page while video is played within the iFrame
* Fix to propagate correct starttm value in postroll content trailing ping
* Fix the 1st party cookie expiry date
* Fix first party id time to live parameter (nol_fpid_ttl) override
* Update the sessionURL in BSDK600 code with FPID parameters
* SIVT support for DCR & DTVR
* StaticEnd support for Hybrid App

== Release R1.2(v6.0.0.662) (04-19-2023) ==
* Support to measure DCR static when browser sdk is initialized on parent page while video is played within the iFrame
* Support to measure DCR static on a Single Page Application when staticEnd is not called while navigating from one page to another

== Release R1(v6.0.0.648) (03-06-2023) ==
* SIVT support for DCR & DTVR
* StaticEnd support for Hybrid App

== Release R4(v6.0.0.623) (05-02-2022) ==
* Fix the 1st party cookie expiry date
* Fix first party id time to live parameter (nol_fpid_ttl) override
* Update the sessionURL in BSDK600 code with FPID parameters

== Release R3(v6.0.0.618) (03-29-2022) ==
* Fix to measure dcr static while video is in focus and within an iFrame
* Fix to propagate correct starttm value in postroll content trailing ping

== Release v6.0.0.355 ==
* Performance improvements through the use of cachable configuration via the Static Queue Snippet.
* Dynamic Configuration File
* Session Ping/UAID - A unique identifier of the device which allows for a single facebook ping per session.
* Support for iOS 12.2

== Release 5.1.0 (Build 2) ==
*Support for DCR Static Lite Measurement
*Advanced Dynamic Script Initialization
*Removal of Configuration file dependency

== Release 5.0.0 (Build 17) ==
*Support for Nielsen Digital Content Ratings (DCR) product
*Support for measurement of static content
*Support for Ad measurement
*Support for Facebook Pings
*Support for multiple instances of the SDK
*General bug fix and performance improvements

DTVR Domless SDK

2025-06-09T19:49:45Z

AmySockanathan: Add information about Implementation hooks

== 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 [[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).

== DOM-less SDK DTVR Video Introduction ==
The Nielsen DOM-less SDK is a Javascript based cross-platform library that clients can use to integrate the Nielsen Digital Content Rating or Digital TV Rating measurement in ReactNative or NodeJS apps.

The Digital TV Ratings (DTVR) 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 example provides the steps to implement the DTVR Video product in a sample NodeJS app. It includes:

* DOM-less SDK Initialization
* DTVR Metadata: information about the content being tracked
* DTVR Events/API calls

By the end of this guide you will have the needed steps to integrate Nielsen's DOM-less SDK in your app.

=== DOM-less SDK DTVR Video Step 1 - Obtain AppID ===
To begin using the DOM-less SDK you will need to obtain an Application ID (AppId)
{| class="wikitable"
!
!Item
!Description
!Source
|-
|✅
|App ID (appid)
|Unique ID assigned to the player/site and configured by product
|Contact your Nielsen TAM
|}
The appid is a 37 character unique ID assigned to the player/site and configured by product and is required when creating a new instance of the DOM-less SDK on the app.

Example: '''PXXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXX'''

=== DOM-less SDK DTVR Video Step 2 - SDK Initialization ===
This project is an API that allows clients to integrate the Nielsen SDK in DOM-less environments like React Native, NodeJS, etc.

Refer to the " [[Domless_SDK_API_Reference#DOM-less SDK Initialization|DOM-less SDK initialization]] " section in the [[Domless_SDK_API_Reference|DOM-less SDK API Reference Guide]].

==== SDK Initialization ====
The following table contains the list of arguments that can be passed
{| class="wikitable"
!Parameter / Argument
!Description
!Source
!Required?
!Example
|-
|appid
|Unique Nielsen ID for the application. The ID is a GUID data type. If you did not receive your App ID, let us know and we will provide you.
|Nielsen-specified
|Yes
|PXXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX
|-
|instanceName
|DOM-less SDK instance name
|Client provided
|Yes
|String eg. abcdefg
|-
|appName
|Application name
|Client provided
|Yes
|appName: 'BSDK RN Sample App'
|-
|deviceId
|Device ID
|Client provided
|Yes
|deviceId: '38400000-8cf0-11bd-b23e-10b96e40000d'
|-
|nol_sdkDebug
|Enables Nielsen console logging. Only required for testing
|Client-provided
|No
|nol_sdkDebug: 'debug'
|-
|domlessEnv
|Specify the domless environment.
"1" for ReactNative "2" for Amazon "3" for NodeJS "4" for Custom
|Client-provided
|Yes
|domlessEnv: '1'
|}

====Implementation Hooks====
Implementation hooks are essential for the DOM-less SDK to work as expected. Please refer to the "[[Domless_SDK_API_Reference#Implementation Hooks | Implementation Hooks]] " section in the [[Domless_SDK_API_Reference | DOM-less SDK API Reference Guide]].

====Nielsen Debug Node.js Server for Event Tracking====
We are excited to announce the beta version of our Debug Node.js server, designed to track requests and events sent from our Dom-less SDK using WebSocket connections. While this feature is not officially released, we are currently looking for users interested in beta testing.

If you'd like to try this tool and provide feedback, please reach out to your Nielsen Technical Account Manager (TAM) for more information. Your insights would be invaluable in helping us refine this feature for a future release!

=== DOM-less SDK DTVR Video Step 3 - Create DTVR Metadata Object ===

==== Events that can be passed to `ggPM` method ====
1. <code>loadMetadata</code> - This event is used to send DTVR metadata to the Nielsen SDK. This event should be called when the video metadata is loaded.
instance.ggPM('loadMetadata', {
'type': 'content',
'adModel': '1'
});
2. <code>sendID3</code> - This event is used to send the id3 event to the Nielsen SDK. This event should be called when the id3 event is triggered, passing the id3 data from the stream.
instance.ggPM('sendID3', '<id3 metadata received>');
3. <code>end</code> - This event is used to send the end event to the Nielsen SDK. This event should be called when the video playback is finished, passing the playhead at that time.
instance.ggPM('end', 300);

====== Events that can be passed to and processed by <code>processEvent</code> method ======
1. <code>`blur`</code> - This event should be passed to processEvent when the app goes to the background.
instance.processEvent({'type': 'blur', 'timestamp': Date.now()});
2. <code>`focus`</code> - This event should be passed to processEvent when the app goes to the foreground.
instance.processEvent({'type': 'focus', 'timestamp': Date.now()});
3. <code>`appclose`</code> - This event should be passed prior to closing the app.
instance.processEvent({'type': 'appclose', 'timestamp': Date.now()});

===== ID3 Tags =====
ID3_Payload is the container to pass the retrieved ID3 tag from the stream. The player should look for 'PRIV' ID3 tags and send 'owner' field (which typically starts from "www.nielsen.com") through this API. Refer to DTVR Event Listeners section below for more information.

'''Sample ID3 Tags'''

<code>www.nielsen.com/X100zdCIGeIlgZnkYj6UvQ==/X100zdCIGeIlgZnkYj6UvQ==/AAAB2Jz2_k74GXSzx4npHuI_<wbr />JwJd3QSUpW30rDkGTcbHEzIMWleCzM-uvNOP9fzJcQMWQLJqzXMCAxParOb5sGijSV9dNM3QiBniJYGZ5GI-lL1fXTTN0IgZ4iWBmeRiPpS9AAAAAAAAAAAAAAAAAAAAAFJWFM5SVhTONNU=/00000/00000/00

www.nielsen.com/X100zdCIGeIlgZnkYj6UvQ==/R8WHe7pEBeqBhu8jTeXydg==/AAICoyitYqlxT7n6aZ0oMCGhe<wbr />Fi4CXFp46AMUPZz1lMr_M9tr3_cjee1SHqxrOiVerMDLeyn9xzocZSKwi746Re8vNOtpNCAZjYABs_J0R25IHpvOc1HS8<wbr />QHGgD5TgOJeS6gX100zdCIGeIlgZnkYj6UvVJWFNhSVhTiPE0=/00000/46016/00
</code>

=== DOM-less SDK DTVR Step 4 - Basic Set of Events - Sample Playback ===

==== Sample Nielsen BSDK-Domless NodeJS Example ====

* [https://github.com/NielsenDigitalSDK/bsdk-domless-samples/tree/main/nodejs Nielsen bsdk-domless NodeJS Repository Example]

==== Sample DTVR Video Integration ====
<syntaxhighlight lang="javascript">
import { BsdkInstance } from 'bsdk-domless';
const nsdkConfig = {
app_id: 'PXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX',
instance_name: 'videoInstance',
};
const implementationHooks = {
Log: {
info: function (log: string) {
console.info(log);
},
debug: function (log: string) {
console.debug(log);
},
warn: function (log: string) {
console.warn(log);
},
error: function (error: string) {
console.error(error);
}
},
Storage: {
setItem: async function (key: any, value: string) {
/**
* Sets a string value for given key. This operation can either modify an existing entry,
* if it did exist for given key, or add new one otherwise.
* In order to store object value, you need to serialize it, e.g. using JSON.stringify().
*/
},
getItem: async function (key: any) {
/**
* Gets a string value for given key. This function can either return a string value for
* existing key or return null otherwise.
* In order to store object value, you need to deserialize it, e.g. using JSON.parse().
*/
},
removeItem: async function (key: any) {
/**
* Removes item for a key, invokes (optional) callback once completed.
*/
}
},
Fetch: async function (url: string | URL | Request, options: any) {
/**
* We require that client pass in User-Agent header via options in Fetch request
*/
const clientOpts = {
headers: {
"User-Agent": "react-native-domless/1.6.7.42 Dalvik/2.1.0 (Linux; U; Android 5.1.1; Android SDK built for x86 Build/LMY48X)"
}
}
const data = Object.assign(options, clientOpts);
const response = await fetch(url, data);
if (response.ok) {
return response;
} else {
throw new Error('Request failed');
}
},
SetTimeout: function (callback: () => void, timeout: number | undefined) {
return setTimeout(callback, timeout);
},
SetInterval: function (callback: () => void, interval: number | undefined) {
return setInterval(callback, interval);
},
ClearTimeout: function (timeout: string | number | NodeJS.Timeout | undefined) {
return clearTimeout(timeout);
},
ClearInterval: function (interval: string | number | NodeJS.Timeout | undefined) {
return clearInterval(interval);
}
};
const nSdkInstance = new BsdkInstance(
nsdkConfig.app_id,
nsdkConfig.instance_name,
{
appName: 'BSDK RN Sample App',
deviceId: 'testDeviceId',
nol_sdkDebug: 'debug', // remove debug flag when going to production
domlessEnv: // "1" for React Native | "2" for Amazon | "3" for NodeJS | "4" for Custom
// reference SDK interface documentation
// for additonal metadata properties
},
implementationHooks
);
// Sample VideoPlayer component
const VideoPlayer = (props) => {
/**
* Implementation of video player component will vary across the board, for Nielsen DOM-less SDK integration
* clients need only setup event listeners with corresponding ggPM() calls.
* Please refer to chosen video player documentation on available events
*/
const video = useRef<Video>(null);
let previousPlayhead = 0; // keep track of previous playhead position
let metadataLoaded = false; // in case of replay scenario set flag for metadata load
// Sample video metadata
const videometadata = {
'type': 'content',
'adModel': '1'
}
const setUpEventListeners = (): void => {
video.addEventListener('ended', onEnded);
video.addEventListener('playing', onPlay);
video.addEventListener('metadata', onMetadata )
};

const onEnded = () => {
// Nielsen SDK ggPM 'end' event
if (nSdkInstance) {
nSdkInstance.then((instance: any) => {
instance.ggPM('end', Math.round(video.currentTime));
metadataLoaded = false;
});
}
};

// NOTE: some players may have an event when video metadata is loaded, recommended to use if available. E.g. loadedmetadata
const onPlay = () => {
// Nielsen SDK ggPM 'loadMetadata' event
if (nSdkInstance && !metadataLoaded) {
nSdkInstance.then((instance: any) => {
instance.ggPM('loadMetadata', videometadata);
metadataLoaded = true;
});
}
};

// NOTE: retireval of ID3 tags will vary by player and is primarily used for DTVR measurement
const onMetadata = (data) = {
if (data.metadata && data.metadata.key === 'PRIV') {
nSdkInstance.then(instance => {
instance.ggPM('sendID3', data.metadata.info);
});
}
};

return (
<View>
<Video
source={{ uri: 'https://www.w3schools.com/html/mov_bbb.mp4' }}
/>
</View>
);
};
</syntaxhighlight>

Domless SDK API Reference

2025-06-09T19:28:52Z

AmySockanathan: /* Note: Implementation Hooks are mandatory for the DOM-less SDK to function as expected. */

==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 [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 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 <code>apid</code> 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 <code>npm install <nowiki>https://github.com/NielsenDigitalSDK/bsdk-domless</nowiki></code> and import the <code>BsdkInstance</code> into video player component
import { BsdkInstance } from 'bsdk-domless'
======status.ok()======
Initialization of the instance can be done with <code>status.ok()</code> 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: ImplementationHooks are mandatory for the DOM-less SDK instance. Please refer to the ImplementationHooks 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'''
!'''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 =====
<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>'''''=====

==== Nielsen Debug Node.js Server for Event Tracking ====
We are excited to announce the beta version of our Debug Node.js server, designed to track requests and events sent from our Dom-less SDK using WebSocket connections. While this feature is not officially released, we are currently looking for users interested in beta testing.

If you'd like to try this tool and provide feedback, please reach out to your Nielsen Technical Account Manager (TAM) for more information. Your insights would be invaluable in helping us refine this feature for a future release!

== DOM-less SDK API Methods & Properties ==
{| class="wikitable"
|+
!Method/Property
!Event #
!DTVR
!DAR
!DCR
!Description
|-
|[[play (Browser)|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 (Browser)|stop]]
|7
|✘
|✘
|✔
|Used when switching between ad and content or content and ad.
|-
|[[loadMetadata (Browser)|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 (Browser)|setPlayheadPosition]]
|49
|✘
|✘
|✔
|Used to send the playhead position.
|-
|[[sendID3 (Browser)|sendID3]]
|55
|✔
|✘
|✘
|Used to send the ID3 metadata.
|-
|[[end (Browser)|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 (Browser)|setVolume]]
|61
|✔
|✘
|✔
|Used to pass in the player volume levels in %. Default value is -1.
|-
|[[staticstart (Browser)|staticstart]]
|14
|✘
|✘
|✔
|Used to send the metadata for the static page.
|-
|[[StaticEnd (Browser)|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 (Browser)|onPaginate]]
|30
|✘
|✘
|✔
|Used to initialize the SDK object
|}

Domless SDK API Reference

2025-06-09T19:28:24Z

AmySockanathan: Add color

==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 [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 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 <code>apid</code> 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 <code>npm install <nowiki>https://github.com/NielsenDigitalSDK/bsdk-domless</nowiki></code> and import the <code>BsdkInstance</code> into video player component
import { BsdkInstance } from 'bsdk-domless'
======status.ok()======
Initialization of the instance can be done with <code>status.ok()</code> 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: ImplementationHooks are mandatory for the DOM-less SDK instance. Please refer to the ImplementationHooks 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'''
!'''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 =====
<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: purple; font-weight: bold; font-size: 20px">Note: Implementation Hooks are mandatory for the DOM-less SDK to function as expected.</pre>'''''=====

==== Nielsen Debug Node.js Server for Event Tracking ====
We are excited to announce the beta version of our Debug Node.js server, designed to track requests and events sent from our Dom-less SDK using WebSocket connections. While this feature is not officially released, we are currently looking for users interested in beta testing.

If you'd like to try this tool and provide feedback, please reach out to your Nielsen Technical Account Manager (TAM) for more information. Your insights would be invaluable in helping us refine this feature for a future release!

== DOM-less SDK API Methods & Properties ==
{| class="wikitable"
|+
!Method/Property
!Event #
!DTVR
!DAR
!DCR
!Description
|-
|[[play (Browser)|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 (Browser)|stop]]
|7
|✘
|✘
|✔
|Used when switching between ad and content or content and ad.
|-
|[[loadMetadata (Browser)|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 (Browser)|setPlayheadPosition]]
|49
|✘
|✘
|✔
|Used to send the playhead position.
|-
|[[sendID3 (Browser)|sendID3]]
|55
|✔
|✘
|✘
|Used to send the ID3 metadata.
|-
|[[end (Browser)|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 (Browser)|setVolume]]
|61
|✔
|✘
|✔
|Used to pass in the player volume levels in %. Default value is -1.
|-
|[[staticstart (Browser)|staticstart]]
|14
|✘
|✘
|✔
|Used to send the metadata for the static page.
|-
|[[StaticEnd (Browser)|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 (Browser)|onPaginate]]
|30
|✘
|✘
|✔
|Used to initialize the SDK object
|}

DCR Video Domless SDK

2025-06-09T18:48:01Z

AmySockanathan: /* Implementation Hooks */

== 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 [[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).

== DOM-less SDK DCR Video Introduction ==
The Nielsen DOM-less SDK is a Javascript based cross-platform library that clients can use to integrate the Nielsen Digital Content Rating or Digital TV Rating measurement in apps for dom-less platforms like ReactNative, NodeJS etc. apps.

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 example provides the 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

By the end of this guide you will have the needed steps to integrate Nielsen's DOM-less SDK in your app.

=== DOM-less SDK DCR Video Step 1 - Obtain AppID ===
To begin using the DOM-less SDK you will need to obtain an Application ID (AppId)
{| class="wikitable"
!
!Item
!Description
!Source
|-
|✅
|App ID (appid)
|Unique ID assigned to the player/site and configured by product
|Contact your Nielsen TAM
|}
The appid is a 37 character unique ID assigned to the player/site and configured by product and is required when creating a new instance of the DOM-less SDK on the app.

Example: '''PXXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXX'''

=== DOM-less SDK DCR Video Step 2 - SDK Initialization ===
This project is an API that allows clients to integrate the Nielsen SDK in DOM-less environments like React Native, NodeJS, etc.

Refer to the "[[Domless_SDK_API_Reference#DOM-less SDK Initialization | DOM-less SDK initialization]] " section in the [[Domless_SDK_API_Reference | DOM-less SDK API Reference Guide]].

==== SDK Initialization ====
The following table contains the list of arguments that can be passed
{| class="wikitable"
!Parameter / Argument
!Description
!Source
!Required?
!Example
|-
|appid
|Unique Nielsen ID for the application. The ID is a GUID data type. If you did not receive your App ID, let us know and we will provide you.
|Nielsen-specified
|Yes
|PXXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX
|-
|instanceName
|DOM-less SDK instance name
|Client provided
|Yes
|String eg. abcdefg
|-
|appName
|Application name
|Client provided
|Yes
|appName: 'BSDK RN Sample App'
|-
|deviceId
|Device ID
|Client provided
|Yes
|deviceId: '38400000-8cf0-11bd-b23e-10b96e40000d'
|-
|nol_sdkDebug
|Enables Nielsen console logging. Only required for testing
|Client-provided
|No
|nol_sdkDebug: 'debug'
|-
|domlessEnv
|Specify the domless environment.
"1" for ReactNative
"2" for Amazon
"3" for NodeJS
"4" for Custom
|Client-provided
|Yes
|domlessEnv: '1'
|}

====Implementation Hooks====
Implementation hooks are essential for the DOM-less SDK to work as expected. Please refer to the "[[Domless_SDK_API_Reference#Implementation Hooks | Implementation Hooks]] " section in the [[Domless_SDK_API_Reference | DOM-less SDK API Reference Guide]].

====Nielsen Debug Node.js Server for Event Tracking====
We are excited to announce the beta version of our Debug Node.js server, designed to track requests and events sent from our Dom-less SDK using WebSocket connections. While this feature is not officially released, we are currently looking for users interested in beta testing.

If you'd like to try this tool and provide feedback, please reach out to your Nielsen Technical Account Manager (TAM) for more information. Your insights would be invaluable in helping us refine this feature for a future release!

=== DOM-less SDK DCR Video Step 3 - Create DCR Video Content Metadata Object ===

==== Events that can be passed to `ggPM` method ====
1. <code>loadMetadata</code> - This event is used to send DCR Video metadata to the Nielsen SDK. This event should be called when the video metadata is loaded.

<syntaxhighlight lang="javascript">
instance.ggPM('loadMetadata', {

'type': 'content',
'assetid': 'VID-123456',
'program': 'program name',
'title': 'episode title with season and episode number',
'length': 'length in seconds',
'airdate': '20210321 09:00:00',
'isfullepisode': 'y',
'adloadtype': '2',
'segB': 'custom segment B', // optional
'segC': 'custom segment C', // optional
'crossId1': 'Standard Episode ID', // optional
'crossId2': 'Content Originator' //optional

});
</syntaxhighlight>

2. <code>setPlayheadPosition</code> - This event is used to send the current playhead position to the Nielsen SDK. This event should be called when the video is playing.

<syntaxhighlight lang="javascript">

instance.ggPM('setPlayheadPosition', 10);

</syntaxhighlight>

3. <code>end</code> - This event is used to send the end event to the Nielsen SDK. This event should be called when the video playback is finished, passing the playhead at that time.

<syntaxhighlight lang="javascript">

instance.ggPM('end', 300);

</syntaxhighlight>

4. <code>stop</code> - This event is used to send the stop event to the Nielsen SDK. This event should be called when transitioning from ads to content and content to ads, passing the playhead at that time.

<syntaxhighlight lang="javascript">

instance.ggPM('stop', 120);
</syntaxhighlight>

5. <code>updateMetadata</code> - This event allows updating metadata for the content or ad that is being played.
This event cannot be used to update values for type, vidtype, or assetid parameters.

<syntaxhighlight lang="javascript">

instance.ggPM('updateMetadata', {
length: 90,
segC: "My segC"
});

</syntaxhighlight>

====== Events that can be passed to and processed by <code>processEvent</code> method ======
1. <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>

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

3. <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 DCR Video Step 4 - Basic Set of Events - Sample Playback ===

==== Sample Nielsen BSDK-Domless NodeJS Example ====
*[https://github.com/NielsenDigitalSDK/bsdk-domless-samples/tree/main/nodejs Nielsen bsdk-domless NodeJS Example]

==== Sample DCR Video Integration ====
<syntaxhighlight lang="javascript">

import { BsdkInstance } from 'bsdk-domless';

const nsdkConfig = {
app_id: 'PXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX',
instance_name: 'videoInstance',
};

const implementationHooks = {
Log: {
info: function (log: string) {
console.info(log);
},
debug: function (log: string) {
console.debug(log);
},
warn: function (log: string) {
console.warn(log);
},
error: function (error: string) {
console.error(error);
}
},
Storage: {
setItem: async function (key: any, value: string) {
/**
* Sets a string value for given key. This operation can either modify an existing entry,
* if it did exist for given key, or add new one otherwise.
* In order to store object value, you need to serialize it, e.g. using JSON.stringify().
*/
},
getItem: async function (key: any) {
/**
* Gets a string value for given key. This function can either return a string value for
* existing key or return null otherwise.
* In order to store object value, you need to deserialize it, e.g. using JSON.parse().
*/
},
removeItem: async function (key: any) {
/**
* Removes item for a key, invokes (optional) callback once completed.
*/
}
},
Fetch: async function (url: string | URL | Request, options: any) {
/**
* We require that client pass in User-Agent header via options in Fetch request
*/
const clientOpts = {
headers: {
"User-Agent": "react-native-domless/1.6.7.42 Dalvik/2.1.0 (Linux; U; Android 5.1.1; Android SDK built for x86 Build/LMY48X)"
}
}
const data = Object.assign(options, clientOpts);
const response = await fetch(url, data);
if (response.ok) {
return response;
} else {
throw new Error('Request failed');
}
},
SetTimeout: function (callback: () => void, timeout: number | undefined) {
return setTimeout(callback, timeout); },
SetInterval: function (callback: () => void, interval: number | undefined) {
return setInterval(callback, interval);
},
ClearTimeout: function (timeout: string | number | NodeJS.Timeout | undefined) {
clearTimeout(timeout);
},
ClearInterval: function (interval: string | number | NodeJS.Timeout | undefined) {
clearInterval(interval);
}
};

const nSdkInstance = new BsdkInstance(
nsdkConfig.app_id,
nsdkConfig.instance_name,
{
appName: 'BSDK RN Sample App',
deviceId: 'testDeviceId',
nol_sdkDebug: 'debug', // remove debug flag when going to production
domlessEnv: // "1" for React Native | "2" for Amazon | "3" for NodeJS | "4" for Custom
// reference SDK interface documentation
// for additonal metadata properties
},
implementationHooks );

// Sample VideoPlayer component
const VideoPlayer = (props) => {
/**
* Implementation of video player component will vary across the board, for Nielsen DOM-less SDK integration
* clients need only setup event listeners with corresponding ggPM() calls.
*
* Please refer to chosen video player documentation on available events
*/

const video = useRef<Video>(null);
let previousPlayhead = 0; // keep track of previous playhead position
let metadataLoaded = false; // in case of replay scenario set flag for metadata load

// Sample video metadata
const videometadata = {
'type': 'content',
'assetid': 'VID-123456',
'program': 'program name',
'title': 'episode title with season and episode number',
'length': 'length in seconds',
'airdate': '20210321 09:00:00',
'isfullepisode': 'y',
'adloadtype': '2',
'segB': 'custom segment B', // optional
'segC': 'custom segment C', // optional
'crossId1': 'Standard Episode ID', // optional
'crossId2': 'Content Originator' //optional
}

const setUpEventListeners = (): void => {
video.addEventListener('ended', onEnded);
video.addEventListener('timeupdate', onTimeUpdate);
video.addEventListener('playing', onPlay);
};

const onEnded = () => {
// Nielsen SDK ggPM 'end' event
if (nSdkInstance) {
nSdkInstance.then((instance: any) => {
instance.ggPM('end', Math.round(video.currentTime));
metadataLoaded = false;
});
}
};

const onTimeUpdate = () => {
const currPlayhead = Math.round(video.current?.currentTime!);
if (currPlayhead > 0 && currPlayhead !== previousPlayhead) {
previousPlayhead = currPlayhead;
// Nielsen SDK ggPM 'setPlayheadPosition' event
if (nSdkInstance) {
nSdkInstance.then((instance: any) => {
instance.ggPM('setPlayheadPosition', currPlayhead);
});
}
}
};

// NOTE: some players may have an event when video metadata is loaded, recommended to use if available. E.g. loadedmetadata
const onPlay = () => {
// Nielsen SDK ggPM 'loadmetadata' event
if (nSdkInstance && !metadataLoaded) {
nSdkInstance.then((instance: any) => {
instance.ggPM('loadMetadata', videometadata);
metadataLoaded = true;
});
}
};

return (
<View>
<Video
source={{ uri: 'https://www.w3schools.com/html/mov_bbb.mp4' }}
/>
</View>
);
};

</syntaxhighlight>

DCR Video Domless SDK

2025-06-06T19:22:20Z

AmySockanathan: Implementationhooks

== 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 [[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).

== DOM-less SDK DCR Video Introduction ==
The Nielsen DOM-less SDK is a Javascript based cross-platform library that clients can use to integrate the Nielsen Digital Content Rating or Digital TV Rating measurement in apps for dom-less platforms like ReactNative, NodeJS etc. apps.

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 example provides the 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

By the end of this guide you will have the needed steps to integrate Nielsen's DOM-less SDK in your app.

=== DOM-less SDK DCR Video Step 1 - Obtain AppID ===
To begin using the DOM-less SDK you will need to obtain an Application ID (AppId)
{| class="wikitable"
!
!Item
!Description
!Source
|-
|✅
|App ID (appid)
|Unique ID assigned to the player/site and configured by product
|Contact your Nielsen TAM
|}
The appid is a 37 character unique ID assigned to the player/site and configured by product and is required when creating a new instance of the DOM-less SDK on the app.

Example: '''PXXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXX'''

=== DOM-less SDK DCR Video Step 2 - SDK Initialization ===
This project is an API that allows clients to integrate the Nielsen SDK in DOM-less environments like React Native, NodeJS, etc.

Refer to the "[[Domless_SDK_API_Reference#DOM-less SDK Initialization | DOM-less SDK initialization]] " section in the [[Domless_SDK_API_Reference | DOM-less SDK API Reference Guide]].

==== SDK Initialization ====
The following table contains the list of arguments that can be passed
{| class="wikitable"
!Parameter / Argument
!Description
!Source
!Required?
!Example
|-
|appid
|Unique Nielsen ID for the application. The ID is a GUID data type. If you did not receive your App ID, let us know and we will provide you.
|Nielsen-specified
|Yes
|PXXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX
|-
|instanceName
|DOM-less SDK instance name
|Client provided
|Yes
|String eg. abcdefg
|-
|appName
|Application name
|Client provided
|Yes
|appName: 'BSDK RN Sample App'
|-
|deviceId
|Device ID
|Client provided
|Yes
|deviceId: '38400000-8cf0-11bd-b23e-10b96e40000d'
|-
|nol_sdkDebug
|Enables Nielsen console logging. Only required for testing
|Client-provided
|No
|nol_sdkDebug: 'debug'
|-
|domlessEnv
|Specify the domless environment.
"1" for ReactNative
"2" for Amazon
"3" for NodeJS
"4" for Custom
|Client-provided
|Yes
|domlessEnv: '1'
|}

====Implementation Hooks====
Implementation hooks are essential for the DOM-less SDK to work as expected. Please refer to the "[[Domless_SDK_API_Reference#ImplementationHooks | ImplementationHooks]] " section in the [[Domless_SDK_API_Reference | DOM-less SDK API Reference Guide]].

====Nielsen Debug Node.js Server for Event Tracking====
We are excited to announce the beta version of our Debug Node.js server, designed to track requests and events sent from our Dom-less SDK using WebSocket connections. While this feature is not officially released, we are currently looking for users interested in beta testing.

If you'd like to try this tool and provide feedback, please reach out to your Nielsen Technical Account Manager (TAM) for more information. Your insights would be invaluable in helping us refine this feature for a future release!

=== DOM-less SDK DCR Video Step 3 - Create DCR Video Content Metadata Object ===

==== Events that can be passed to `ggPM` method ====
1. <code>loadMetadata</code> - This event is used to send DCR Video metadata to the Nielsen SDK. This event should be called when the video metadata is loaded.

<syntaxhighlight lang="javascript">
instance.ggPM('loadMetadata', {

'type': 'content',
'assetid': 'VID-123456',
'program': 'program name',
'title': 'episode title with season and episode number',
'length': 'length in seconds',
'airdate': '20210321 09:00:00',
'isfullepisode': 'y',
'adloadtype': '2',
'segB': 'custom segment B', // optional
'segC': 'custom segment C', // optional
'crossId1': 'Standard Episode ID', // optional
'crossId2': 'Content Originator' //optional

});
</syntaxhighlight>

2. <code>setPlayheadPosition</code> - This event is used to send the current playhead position to the Nielsen SDK. This event should be called when the video is playing.

<syntaxhighlight lang="javascript">

instance.ggPM('setPlayheadPosition', 10);

</syntaxhighlight>

3. <code>end</code> - This event is used to send the end event to the Nielsen SDK. This event should be called when the video playback is finished, passing the playhead at that time.

<syntaxhighlight lang="javascript">

instance.ggPM('end', 300);

</syntaxhighlight>

4. <code>stop</code> - This event is used to send the stop event to the Nielsen SDK. This event should be called when transitioning from ads to content and content to ads, passing the playhead at that time.

<syntaxhighlight lang="javascript">

instance.ggPM('stop', 120);
</syntaxhighlight>

5. <code>updateMetadata</code> - This event allows updating metadata for the content or ad that is being played.
This event cannot be used to update values for type, vidtype, or assetid parameters.

<syntaxhighlight lang="javascript">

instance.ggPM('updateMetadata', {
length: 90,
segC: "My segC"
});

</syntaxhighlight>

====== Events that can be passed to and processed by <code>processEvent</code> method ======
1. <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>

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

3. <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 DCR Video Step 4 - Basic Set of Events - Sample Playback ===

==== Sample Nielsen BSDK-Domless NodeJS Example ====
*[https://github.com/NielsenDigitalSDK/bsdk-domless-samples/tree/main/nodejs Nielsen bsdk-domless NodeJS Example]

==== Sample DCR Video Integration ====
<syntaxhighlight lang="javascript">

import { BsdkInstance } from 'bsdk-domless';

const nsdkConfig = {
app_id: 'PXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX',
instance_name: 'videoInstance',
};

const implementationHooks = {
Log: {
info: function (log: string) {
console.info(log);
},
debug: function (log: string) {
console.debug(log);
},
warn: function (log: string) {
console.warn(log);
},
error: function (error: string) {
console.error(error);
}
},
Storage: {
setItem: async function (key: any, value: string) {
/**
* Sets a string value for given key. This operation can either modify an existing entry,
* if it did exist for given key, or add new one otherwise.
* In order to store object value, you need to serialize it, e.g. using JSON.stringify().
*/
},
getItem: async function (key: any) {
/**
* Gets a string value for given key. This function can either return a string value for
* existing key or return null otherwise.
* In order to store object value, you need to deserialize it, e.g. using JSON.parse().
*/
},
removeItem: async function (key: any) {
/**
* Removes item for a key, invokes (optional) callback once completed.
*/
}
},
Fetch: async function (url: string | URL | Request, options: any) {
/**
* We require that client pass in User-Agent header via options in Fetch request
*/
const clientOpts = {
headers: {
"User-Agent": "react-native-domless/1.6.7.42 Dalvik/2.1.0 (Linux; U; Android 5.1.1; Android SDK built for x86 Build/LMY48X)"
}
}
const data = Object.assign(options, clientOpts);
const response = await fetch(url, data);
if (response.ok) {
return response;
} else {
throw new Error('Request failed');
}
},
SetTimeout: function (callback: () => void, timeout: number | undefined) {
return setTimeout(callback, timeout); },
SetInterval: function (callback: () => void, interval: number | undefined) {
return setInterval(callback, interval);
},
ClearTimeout: function (timeout: string | number | NodeJS.Timeout | undefined) {
clearTimeout(timeout);
},
ClearInterval: function (interval: string | number | NodeJS.Timeout | undefined) {
clearInterval(interval);
}
};

const nSdkInstance = new BsdkInstance(
nsdkConfig.app_id,
nsdkConfig.instance_name,
{
appName: 'BSDK RN Sample App',
deviceId: 'testDeviceId',
nol_sdkDebug: 'debug', // remove debug flag when going to production
domlessEnv: // "1" for React Native | "2" for Amazon | "3" for NodeJS | "4" for Custom
// reference SDK interface documentation
// for additonal metadata properties
},
implementationHooks );

// Sample VideoPlayer component
const VideoPlayer = (props) => {
/**
* Implementation of video player component will vary across the board, for Nielsen DOM-less SDK integration
* clients need only setup event listeners with corresponding ggPM() calls.
*
* Please refer to chosen video player documentation on available events
*/

const video = useRef<Video>(null);
let previousPlayhead = 0; // keep track of previous playhead position
let metadataLoaded = false; // in case of replay scenario set flag for metadata load

// Sample video metadata
const videometadata = {
'type': 'content',
'assetid': 'VID-123456',
'program': 'program name',
'title': 'episode title with season and episode number',
'length': 'length in seconds',
'airdate': '20210321 09:00:00',
'isfullepisode': 'y',
'adloadtype': '2',
'segB': 'custom segment B', // optional
'segC': 'custom segment C', // optional
'crossId1': 'Standard Episode ID', // optional
'crossId2': 'Content Originator' //optional
}

const setUpEventListeners = (): void => {
video.addEventListener('ended', onEnded);
video.addEventListener('timeupdate', onTimeUpdate);
video.addEventListener('playing', onPlay);
};

const onEnded = () => {
// Nielsen SDK ggPM 'end' event
if (nSdkInstance) {
nSdkInstance.then((instance: any) => {
instance.ggPM('end', Math.round(video.currentTime));
metadataLoaded = false;
});
}
};

const onTimeUpdate = () => {
const currPlayhead = Math.round(video.current?.currentTime!);
if (currPlayhead > 0 && currPlayhead !== previousPlayhead) {
previousPlayhead = currPlayhead;
// Nielsen SDK ggPM 'setPlayheadPosition' event
if (nSdkInstance) {
nSdkInstance.then((instance: any) => {
instance.ggPM('setPlayheadPosition', currPlayhead);
});
}
}
};

// NOTE: some players may have an event when video metadata is loaded, recommended to use if available. E.g. loadedmetadata
const onPlay = () => {
// Nielsen SDK ggPM 'loadmetadata' event
if (nSdkInstance && !metadataLoaded) {
nSdkInstance.then((instance: any) => {
instance.ggPM('loadMetadata', videometadata);
metadataLoaded = true;
});
}
};

return (
<View>
<Video
source={{ uri: 'https://www.w3schools.com/html/mov_bbb.mp4' }}
/>
</View>
);
};

</syntaxhighlight>

Domless SDK API Reference

2025-06-06T19:17:17Z

AmySockanathan: Add implementation hooks

==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 [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 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 <code>apid</code> 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 <code>npm install <nowiki>https://github.com/NielsenDigitalSDK/bsdk-domless</nowiki></code> and import the <code>BsdkInstance</code> into video player component
import { BsdkInstance } from 'bsdk-domless'
======status.ok()======
Initialization of the instance can be done with <code>status.ok()</code> 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: ImplementationHooks are mandatory for the DOM-less SDK instance. Please refer to the ImplementationHooks 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'''
!'''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 =====
<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>

===== '''''Note: ImplementationHooks are mandatory for the DOM-less SDK to function as expected.''''' =====

==== Nielsen Debug Node.js Server for Event Tracking ====
We are excited to announce the beta version of our Debug Node.js server, designed to track requests and events sent from our Dom-less SDK using WebSocket connections. While this feature is not officially released, we are currently looking for users interested in beta testing.

If you'd like to try this tool and provide feedback, please reach out to your Nielsen Technical Account Manager (TAM) for more information. Your insights would be invaluable in helping us refine this feature for a future release!

== DOM-less SDK API Methods & Properties ==
{| class="wikitable"
|+
!Method/Property
!Event #
!DTVR
!DAR
!DCR
!Description
|-
|[[play (Browser)|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 (Browser)|stop]]
|7
|✘
|✘
|✔
|Used when switching between ad and content or content and ad.
|-
|[[loadMetadata (Browser)|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 (Browser)|setPlayheadPosition]]
|49
|✘
|✘
|✔
|Used to send the playhead position.
|-
|[[sendID3 (Browser)|sendID3]]
|55
|✔
|✘
|✘
|Used to send the ID3 metadata.
|-
|[[end (Browser)|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 (Browser)|setVolume]]
|61
|✔
|✘
|✔
|Used to pass in the player volume levels in %. Default value is -1.
|-
|[[staticstart (Browser)|staticstart]]
|14
|✘
|✘
|✔
|Used to send the metadata for the static page.
|-
|[[StaticEnd (Browser)|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 (Browser)|onPaginate]]
|30
|✘
|✘
|✔
|Used to initialize the SDK object
|}

Domless SDK API Reference

2025-06-06T19:09:42Z

AmySockanathan: /* Implementation Hooks */

==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 [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 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 <code>apid</code> 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 <code>npm install <nowiki>https://github.com/NielsenDigitalSDK/bsdk-domless</nowiki></code> and import the <code>BsdkInstance</code> into video player component
import { BsdkInstance } from 'bsdk-domless'
======status.ok()======
Initialization of the instance can be done with <code>status.ok()</code> 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);
}

====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'''
!'''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 =====
<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>

===== '''''Note: ImplementationHooks are mandatory for the DOM-less SDK to function as expected.''''' =====

==== Nielsen Debug Node.js Server for Event Tracking ====
We are excited to announce the beta version of our Debug Node.js server, designed to track requests and events sent from our Dom-less SDK using WebSocket connections. While this feature is not officially released, we are currently looking for users interested in beta testing.

If you'd like to try this tool and provide feedback, please reach out to your Nielsen Technical Account Manager (TAM) for more information. Your insights would be invaluable in helping us refine this feature for a future release!

== DOM-less SDK API Methods & Properties ==
{| class="wikitable"
|+
!Method/Property
!Event #
!DTVR
!DAR
!DCR
!Description
|-
|[[play (Browser)|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 (Browser)|stop]]
|7
|✘
|✘
|✔
|Used when switching between ad and content or content and ad.
|-
|[[loadMetadata (Browser)|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 (Browser)|setPlayheadPosition]]
|49
|✘
|✘
|✔
|Used to send the playhead position.
|-
|[[sendID3 (Browser)|sendID3]]
|55
|✔
|✘
|✘
|Used to send the ID3 metadata.
|-
|[[end (Browser)|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 (Browser)|setVolume]]
|61
|✔
|✘
|✔
|Used to pass in the player volume levels in %. Default value is -1.
|-
|[[staticstart (Browser)|staticstart]]
|14
|✘
|✘
|✔
|Used to send the metadata for the static page.
|-
|[[StaticEnd (Browser)|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 (Browser)|onPaginate]]
|30
|✘
|✘
|✔
|Used to initialize the SDK object
|}

Domless SDK API Reference

2025-06-06T18:57:12Z

AmySockanathan: Add information about implementation hooks

==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 [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 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 <code>apid</code> 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 <code>npm install <nowiki>https://github.com/NielsenDigitalSDK/bsdk-domless</nowiki></code> and import the <code>BsdkInstance</code> into video player component
import { BsdkInstance } from 'bsdk-domless'
======status.ok()======
Initialization of the instance can be done with <code>status.ok()</code> 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);
}

====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'''
!'''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 BSDK pings.

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

==== Nielsen Debug Node.js Server for Event Tracking ====
We are excited to announce the beta version of our Debug Node.js server, designed to track requests and events sent from our Dom-less SDK using WebSocket connections. While this feature is not officially released, we are currently looking for users interested in beta testing.

If you'd like to try this tool and provide feedback, please reach out to your Nielsen Technical Account Manager (TAM) for more information. Your insights would be invaluable in helping us refine this feature for a future release!

== DOM-less SDK API Methods & Properties ==
{| class="wikitable"
|+
!Method/Property
!Event #
!DTVR
!DAR
!DCR
!Description
|-
|[[play (Browser)|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 (Browser)|stop]]
|7
|✘
|✘
|✔
|Used when switching between ad and content or content and ad.
|-
|[[loadMetadata (Browser)|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 (Browser)|setPlayheadPosition]]
|49
|✘
|✘
|✔
|Used to send the playhead position.
|-
|[[sendID3 (Browser)|sendID3]]
|55
|✔
|✘
|✘
|Used to send the ID3 metadata.
|-
|[[end (Browser)|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 (Browser)|setVolume]]
|61
|✔
|✘
|✔
|Used to pass in the player volume levels in %. Default value is -1.
|-
|[[staticstart (Browser)|staticstart]]
|14
|✘
|✘
|✔
|Used to send the metadata for the static page.
|-
|[[StaticEnd (Browser)|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 (Browser)|onPaginate]]
|30
|✘
|✘
|✔
|Used to initialize the SDK object
|}

Browser SDK API Reference

2025-05-30T14:18:47Z

AmySockanathan: Updatemetadata/35 is not applicable to DTVR but only for DCRVideo & VRI

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

== Setting up Development Environment ==
=== Step 1: Configure Content Management System (CMS) ===
Configure CMS to send the required values (see table below). Any internal CMS_variable names can be used for passing the data.

Ensure to capture these CMS_variable names in the SDK Configuration Form.

For more information on setting variable names, see the SDK Configuration Form included within the SDK package.

{| class="wikitable"
|-
! Required Data !! Description !! Value
|-
| dataSrc || Used when both CMS metadata and ID3 data are present in the player. Setting this field tells the SDK whether to use the CMS metadata or the ID3 payload to derive the pings || cms
|-
| type || Type of asset: ad or content || preroll, midroll, postroll, or content
|-
| assetid || unique ID assigned to asset || custom <br>(no [[Special Characters]])
|-
| OCR Tag || OCR tag provided by Nielsen for implementation on the ad unit || Complete OCR URL
|-
| program || Name of program (25 character limit) || custom
|-
| title || Episode title (40 character limit) || custom
|-
| length || Length of content in seconds || Length in seconds, 0 for live stream
|-
| adloadtype || Type of ad load || "1" - Linear "2" - Dynamic(default)
|-
| hasAds || Identify if content includes Ads || "0" - no ads "1" - includes ads "2" - unknown(default)
|-
| isfullepisode || Full episode flag || "y" - full episode "n" - non full episode
|-
| segA || Segment A (this is not available for video reporting as the episode title is reported) || custom value
|-
| segB || Custom segment B || custom value
|-
| segC || Custom segment C || custom value
|-
| crossId1 || Standard episode ID || custom value
|-
| crossId2 || Content originator (required only for distributors) || custom value
|-
| airdate || Original air date and time in Eastern Time. For non-US countries, it should be local time. || YYYYMMDD HH24:MI:SS
|-
| containerId || HTML DOM element of the Player container (for Viewability&Audibility feature only) || custom value
|-
|luid
|Living Unit ID - Experian Household ID
'''Note: This parameter is applicable only for CTV and First Party Livestream data'''
|"B0EOFEDgD"
|}

=== Step 2: Complete the Nielsen SDK Configuration Form ===
The SDK is designed to map the <code>CMS_variable names</code>. To support the custom mapping, the developer is required to complete the SDK Configuration Form. The form will be provided during onboarding along with this guide.

== Initialization ==
=== Obtain the Nielsen Application ID (apid) and Browser SDK URLs ===
The Nielsen <code>apid</code> 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 Browser SDK ===
There are two steps required for configuring the SDK:

'''Add Static Queue Snippet'''

*Add Static Queue Snippet
*Create SDK Instance

Add the following script tag to the website:
<syntaxhighlight lang="javascript">

<script type="text/javascript">
!function(t,n)
{
t[n]=t[n]||
{
nlsQ:function(e,o,c,r,s,i)
{
return s=t.document,
r=s.createElement("script"),
r.async=1,
r.src=("http:"===t.location.protocol?"http:":"https:")+"//cdn-gl.imrworldwide.com/conf/"+e+".js#name="+o+"&ns="+n,
i=s.getElementsByTagName("script")[0],
i.parentNode.insertBefore(r,i),
t[n][o]=t[n][o]||{g:c||{},
ggPM:function(e,c,r,s,i){(t[n][o].q=t[n][o].q||[]).push([e,c,r,s,i])}},t[n][o]
}
}
}
(window,"NOLBUNDLE");
</script>

</syntaxhighlight>

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.

'''Create SDK Instance'''

To initialize the SDK, create an SDK instance by making the initialization call:

'''Initialization API Call'''
<syntaxhighlight lang="javascript">

NOLBUNDLE.nlsQ("<apid>", "<instanceName>",{nol_sdkDebug: "debug"})

</syntaxhighlight>

When creating an instance, pass the following three values:

=== SDK Initialization – Global Parameters <span class="anchor" id="SDK Initialization Global Parameters"></span> ===
{| class="wikitable"
|-
! Parameters !! Description !! Value
|-
| apid || UniqueID assigned to player/site. || 'XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX'
|-
| instanceName || Name of SDK instance || "any string value"
|-
| nol_sdkDebug || Enables Nielsen console logging. Only required for testing || "{nol_sdkDebug: "debug"})"
|-
| containerId || HTML DOM element id of the player container. Only for Viewability & Audibility feature. || {containerId: "playerId1"}
|-
| 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&"
|}

{{example_bsdk_init}}

'''Example SDK Configuration'''

The configuration should include the Static Queue Snippet and an SDK Instance for an unique App ID as shown in the example:

<syntaxhighlight lang="javascript">

<script type="text/javascript">
!function(t,n)
{
t[n]=t[n]||
{
nlsQ:function(e,o,c,r,s,i)
{
return s=t.document,
r=s.createElement("script"),
r.async=1,
r.src=("http:"===t.location.protocol?"http:":"https:")+"//cdn-gl.imrworldwide.com/conf/"+e+".js#name="+o+"&ns="+n,
i=s.getElementsByTagName("script")[0],
i.parentNode.insertBefore(r,i),
t[n][o]=t[n][o]||{g:c||{},
ggPM:function(e,c,r,s,i){(t[n][o].q=t[n][o].q||[]).push([e,c,r,s,i])}},t[n][o]
}
}
}
(window,"NOLBUNDLE");
// Created SDK Instance
var nSdkInstance = NOLBUNDLE.nlsQ("XXXXXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXX","nlsnInstance", {nol_sdkDebug: "debug"});
</script>

</syntaxhighlight>

=== Multiple SDK Instances ===
The Browser SDK allows instantiating multiple instances of the object, which can be used simultaneously without any problems, however they must be instantiated with their own unique instance names. There is no maximum number of instances that is enforced in the browser.

The below examples will make use of the same AppId, however using different AppIds will work as well. The principles below follow the same initialization rules stated above for a single instance and simply require a unique instance name and variable name with which the returned instance is assigned.

For more information around the possible parameters that can be passed as well as deeper descriptions for the API calls, please refer to the section on [[#SDK Initialization Global Parameters|'''SDK Initialization - Global Parameters''']].

'''Example of 2 instances on the same page'''

<syntaxhighlight lang="javascript">
//Add Static Queue Snippet
<script>
!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.imrworldwide.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");

//Create SDK Instance(s)
// Notice the unique instance name given to each instance below and the unique variable name for each instance
var nSdkInstanceLive = NOLBUNDLE.nlsQ("XXXXXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXX", "instanceLive", {
nol_sdkDebug: 'debug',
optout: 'false'
});

var nSdkInstanceVod = NOLBUNDLE.nlsQ("XXXXXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXX", "instanceVod", {
nol_sdkDebug: 'debug',
optout: 'false'
});

</script>
</syntaxhighlight>

'''Example of 2 instances using a parent page and iFrame'''

<big>Parent Page (index.html)</big>

<syntaxhighlight lang="javascript">
<!DOCTYPE html>
<html lang="en">

<head>
<meta charset="UTF-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<meta http-equiv="X-UA-Compatible" content="ie=edge">
<title>DCR Static/DCR Video</title>
<script>
/* NLSQUEUE build v*/
!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.imrworldwide.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");

// SDK Initialization
var nSdkInstance = NOLBUNDLE.nlsQ("XXXXXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXX", "staticPage", {
nol_sdkDebug: 'debug',
});

// Static Metadata
var staticMetadata = {
assetid: 'staticTestPage',
type: 'static'
};

// Event 'staticstart' call
nSdkInstance.ggPM(14, staticMetadata);
</script>
</head>

<body>
<h1>DCR Static on Parent/DCR Video in iFrame</h1>
<p>Static measurement is current on parent page when window is in focus</p>
<iframe src="./dcr-video.html" frameborder="0" width="650" height="500" style="background-color: rgb(42, 217, 248);" id="video-iframe"></iframe>
</body>

</html>
</syntaxhighlight>

<big>Nested iFrame Referenced on Parent Page (dcr-video.html)</big>

<syntaxhighlight lang="javascript">
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
<meta http-equiv="X-UA-Compatible" content="ie=edge" />
<title>iFrame Same Source</title>
<script>
/* NLSQUEUE build v*/
!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.imrworldwide.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");

// SDK Initialization
var nSdkInstance = NOLBUNDLE.nlsQ("XXXXXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXX", "videoPlayer", {
nol_sdkDebug: 'debug',
});

var contentMetadata = {
type: "content",
length: "300",
title: "Skydiving Across Europe",
program: "latacg",
censuscategory: "Enlisted",
assetid: "204558915992",
section: "ProgramAsset8",
tv: "true",
adModel: "0",
dataSrc: "cms",
segA: "S07E04:NBC",
segB: "teams",
segC:"AtlanataFalcons",
}
</script>
</head>
<body>
<p>I'm iframe SDK DCR Video measurement, DCR static measurement should continue when clicking "play" on video</p>
<main>
<video
controls
src="https://archive.org/download/BigBuckBunny_124/Content/big_buck_bunny_720p_surround.mp4"
poster="https://peach.blender.org/wp-content/uploads/title_anouncement.jpg?x11217"
width="620">
Sorry, your browser doesn't support embedded videos, but don't worry, you can
<a href="https://archive.org/details/BigBuckBunny_124">download it</a>
and watch it with your favorite video player!
</video>
</main>
<script src="../player.js"></script>
</body>
</html>

</syntaxhighlight>

=== SDK Initialization to measure the Viewability & Audibility ===
To support viewability metrics in the web page the integrator has to provide a tag value of the player view to let Nielsen SDK know that there is a player that needs to be tracked. It’s called the ‘containerId’ and it should be passed in the as string while initializing the Nielsen browser SDK.

NOLBUNDLE.nlsQ("<apid>", "<instanceName>",{containerId: <playerElementID>, nol_sdkDebug: "debug"})

'''Example SDK Initialization for Viewability'''

Your configuration should include the Static Queue Snippet and an SDK Instance for your unique App ID as shown in the example:
<syntaxhighlight lang="javascript">
//Add Static Queue Snippet
<script>
! function(t, n) {
t[n] = t[n] || {
nlsQ: function(e, o, c, r, s, i) {
return s = t.document,
r = s.createElement("script"),
r.async = 1,
r.src = ("http:" === t.location.protocol ? "http:" : "https:") + "//cdn-gl.imrworldwide.com/conf/" + e + ".js#name=" + o + "&ns=" + n,
i = s.getElementsByTagName("script")[0],
i.parentNode.insertBefore(r, i),
t[n][o] = t[n][o] || {
g: c || {},
ggPM: function(e, c, r, s, i) {
(t[n][o].q = t[n][o].q || []).push([e, c, r, s, i])
}
}, t[n][o]
}
}
}
(window, "NOLBUNDLE");

//Create SDK Instance
var nSdkInstance = NOLBUNDLE.nlsQ("XXXXXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXX", "nlsnInstance", {containerId: “player1”, nol_sdkDebug: "debug"});
</script>

</syntaxhighlight>

== Browser SDK API Methods & Properties ==
{| class="wikitable sortable"
|-
! Method / Property !! Event # !! DTVR !! DAR !! DCR !! Description
|-
| [[loadMetadata (Browser)|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.
|-
| [[play (Browser)|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”.
|-
| [[sendID3 (Browser)|sendID3]] || 55 || ✔ || ✘ || ✘ || Used to send the ID3 metadata.
|-
| [[setPlayheadPosition (Browser)|setPlayheadPosition]] || 49 || ✘ || ✘ || ✔ || Used to send the playhead position.
|-
| [[stop (Browser)|stop]] || 7 || ✘ || ✘ || ✔ || Used when switching between ad and content or content and ad.
|-
| [[end (Browser)|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
|-
| [[staticstart (Browser)|staticstart]] || 14 || ✘ || ✘ || ✔ || Used to send the metadata for the static page.
|-
| [[StaticEnd (Browser)|staticend]] || 56 || ✘ || ✘ || ✔ || In Single Page Application (SPA) it is imperative that staticend is called prior to the loading of new metadata. This allows the Browser SDK to properly credit the previous section/content being viewed before measuring the new one.
|-
| [[updateOTT (Browser)|updateOTT]] || - || ✘ || ✘ || ✔ || Used to notify Browser SDK that the remote OTT device (like Google ChromeCast, Roku, Amazon FireTV, etc.) is connected / disconnected (change of OTT status).
|-
| [[ onPaginate (Browser)|onPaginate]] || 30 || ✘ || ✘ || ✔ || Used to create a new instance of the SDK object
|-
| [[updateMetadata (Browser)|updateMetadata]] || 35 || ✘ || ✘ || ✔ || This event is used for updating metadata parameters for the content or ad that is being played.
|-
| [[setVolume_(Browser)|setVolume]] || 61 || ✔ || ✘ || ✔ || Used to pass in the player volume levels in %. Default value is -1.
|}

== Retrieving ID3 Tags ==
The video player must have the ability to extract ID3 tags and supply them to the Browser SDK, based on the HLS standard.
*An ID3 tag spans two PES packets.
**In the first PES packet, look for www.nielsen.com, this is the start of the ID3 tag. Continue to parse the first PES packet until the undefined char "\ufffd" is found. This forms the first half of the ID3 tag
**In the second PES packet, identify the end pattern – a regEx of /(\/\d+){3}/ and look to remove the lowest index of either "\x00" and/or "\ufffd". Now the second packet has been appended and the demarcation of the Nielsen-specific data has been defined.

Follow the procedure below, to extract Nielsen ID3 tags from an MPEG-2 transport stream (including HLS streams).
#Parse the Program Map Table (PMT) to find the PID of the metadata stream. Confirm the presence of the metadata descriptor described in section 2.3.3 of Apple’s “HTTP Live Streaming Metadata Spec.pdf”. Only private streams with metadata descriptor present should be considered as ID3-tag metadata streams.
#Parse the HLS/Transport stream for any '''PES header''' with the PID found in step 1.
#Follow standard MPEG-2 parsing procedures to locate the start of the payload of the PES packet.
#Copy the PES payload into a buffer.
#The ID3 tag spans 2 PES packets. Parse the stream for the next packet whose PID is set to the PID found in step 1. Typically the ID3 Tag is of 249 bytes. The steps below guide towards extraction of the ID3 tag
##In the first PES packet, look for "www.nielsen.com" , this is the start of the ID3 tag. Keep on parsing the first PES packet until the undefined char "\ufffd" is found. This forms the first half of the ID3 tag
##In the second PES packet, identify the end pattern, a regEx of /(\/\d+){3}/ and look to remove the lowest index of either “\x00” and/or “\ufffd”. Now the second packet has been appended and the demarcation of the Nielsen specific data has been defined. This segment can be simply substringed.
##Concatenate this substringed segment with the payload derived from the first packet get the ID3 payload.
#Check the length of the contents in the buffer to make sure that it is equal to the size of a Nielsen ID3 tag.
#Ensure that the ID3 byte array is converted into the string and escape it, so that the SDK can consume it.
Repeat steps 2 through 7 for all ID3 tags in the stream.

'''References'''
*[http://www.iso.org/iso/catalogue_detail?csnumber=44169. ISO/IEC 13818-1:2007] Information technology – Generic coding of moving pictures and associated audio information: Systems
*https://developer.apple.com/library/content/documentation/AudioVideo/Conceptual/HTTP_Live_Streaming_Metadata_Spec/

=== Sample ID3 tags ===
* <code>www.nielsen.com/X100zdCIGeIlgZnkYj6UvQ==/X100zdCIGeIlgZnkYj6UvQ==/AAAB2Jz2_k74GXSzx4npHuI_<wbr />JwJd3QSUpW30rDkGTcbHEzIMWleCzM-uvNOP9fzJcQMWQLJqzXMCAxParOb5sGijSV9dNM3QiBniJYGZ5GI-lL1fXTTN0IgZ4iWBmeRiPpS9AAAAAAAAAAAAAAAAAAAAAFJWFM5SVhTONNU=/00000/00000/00</code>
* <code>www.nielsen.com/X100zdCIGeIlgZnkYj6UvQ==/R8WHe7pEBeqBhu8jTeXydg==/AAICoyitYqlxT7n6aZ0oMCGhe<wbr />Fi4CXFp46AMUPZz1lMr_M9tr3_cjee1SHqxrOiVerMDLeyn9xzocZSKwi746Re8vNOtpNCAZjYABs_J0R25IHpvOc1HS8<wbr />QHGgD5TgOJeS6gX100zdCIGeIlgZnkYj6UvVJWFNhSVhTiPE0=/00000/46016/00</code>
<blockquote>'''Note''': ID3 tags are not applicable for International (Germany)</blockquote>

== Browser Opt-Out Implementation ==
The site in which video content is being measure via Nielsen methodology must provide the means for the user to opt-out of, or opt back into Nielsen Measurement.

For Browser-based applications, opt-out setting is stored via Nielsen cookie. Therefore, it is only necessary that users be made aware of measurement opt-out by incorporating the template below in the user interface.

=== Sample Opt Out Template ===
Our properties may feature Nielsen’s proprietary measurement software which will allow to contribute to market research, like Nielsen’s TV Ratings. To learn more about this information, see https://www.nielsen.com/digitalprivacy. Nielsen’s software may collect your choices with regards to it.

== Nielsen Privacy Requirements ==
Privacy protections that Nielsen ensures to have with each App SDK integration are as follows.
*Disclosure of viewership data collection in EULA / Privacy Policy
*A link in the EULA/Privacy policy, or in another conspicuous location within the App, to a Nielsen-hosted web page outlining what Nielsen is collecting and how it is being used
*Method for users to opt-out of Nielsen measurement, any time while using the application

=== Ratings Data Flow ===
Every view of creditable and watermarked content is measured by Nielsen.
[[File:RatingsDataFlow.png]]

'''Information NOT Shared'''
* '''With Nielsen'''
** User's Identity
* '''With Data Provider'''
** Content information
** Whether user is viewing an ad or video content
** Player used to play the streaming (audio / video, etc.)
** Values being de-duped / aggregating for

Nielsen collects only what it needs for audience measurement. Every view of creditable, watermarked content will be measured by Nielsen.

=== Data Collected ===
{| class="wikitable"
|-
! Type of Information !! Parameter !! Transmitted to Nielsen? !! Sent to Provider?
|-
| rowspan="8" | Nielsen ID3 Watermark
|-
| FinalDistributor Timestamp || Yes || No
|-
| Program Content Timestamp || Yes || No
|-
| Mobile Breakout Code || Yes || No
|-
| Commercial Credit Code – Linear or Dynamic || Yes || No
|-
| Time ShiftedViewing Code || Yes || No
|-
| Segment Number || Yes || No
|-
| Segment View Pattern || Yes || No
|-
| rowspan="7" | Device/App Info
|-
| Device OSVersion || Yes || Yes
|-
| Device Model || Yes || No
|-
| Cache Buster || Yes || Yes
|-
| SDKDisabled Flag || Yes || No
|-
| ServerCode || Yes || No
|-
| Channel or URL || Yes || No
|-
| rowspan="9" | Nielsen Identifiers
|-
| Client ID || Yes || No
|-
| Campaign ID || Yes || Yes
|-
| Nielsen Unique Device ID || Yes || No
|-
| Application ID || Yes || No
|-
| DeviceGroup (ex. Tablet, Smartphone, Desktop) || Yes || Yes
|-
| OS Group (ex. Android, iOS, Windows) || Yes || Yes
|-
| SDKVersion || Yes || No
|-
| IP Address for DMA, Country Code || Yes || Yes
|}
<blockquote>'''Note''': Data is hashed, and encrypted using AES 128 before transmission to data provider.</blockquote>

{{Viewability_Data_Collected}}

==== Example ping sent to provider ====
* <code><nowiki>https://provider.com/cgi-bin/brandlift.php</nowiki>?campaign_id=ff12725d724fac7934cf6003f096b4cd<wbr />&placement_id=a4164b8fba9ee7c873a9c72c7091bb58<wbr />&creative_id=25280139b61a947e127a52f56c8a2fdd<wbr />&segment1=9000<wbr />&segment2=41<wbr />&segment3=iOS<wbr />&OSVer=iOS6.1<wbr />&c9=<wbr />&devgrp=tablet<wbr />&h=f5f243fe6d<wbr />&rnd=1376971827360</code>

This ping passes the following parameters to the provider:
* Campaign ID – (campaign, placement, creative)
* Country Code
* DMA
* OS Group (ex. iOS, Android)
* DeviceOS Version
* Device Advertiser ID
* DeviceGroup (ex. Tablet, Smartphone, Desktop)
* Cache Buster

{{Template:Browser_Privacy_and_Opt-Out}}

=== Opt-Out Implementation ===
The site must provide the means for the user to opt-out of, or opt back into Nielsen Measurement.

'''Sample Opt Out Template'''

Our properties may feature Nielsen’s proprietary measurement software which will allow to contribute to market research, like Nielsen’s TV Ratings. To learn more about this information, please [http://priv-policy.imrworldwide.com/priv/mobile/us/en/optout.html| click here]. Nielsen’s software may collect your choices with regards to it.

== Testing ==
See [[Digital Measurement Testing#Testing Browser Implementation|Digital Measurement Testing - Testing Browser Implementation]].

DCR Video & Static Cloud API

2025-04-23T21:23:18Z

AmySockanathan: /* Send UAID Ping */

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

This guide shows you how to integrate the Nielsen Cloud API to enable Digital Content Ratings (DCR), and fuel other measurement products on your over-the-top (OTT) Apps.
*For Roku Apps, please see [[DCR Video & Static Roku Cloud API]]
*For Mobile Apps, please see [[DCR Video & Static Mobile Cloud API]]

==Prerequisites==
To get started, you will need a Nielsen App ID. The App ID is a unique ID assigned to your app. This will be provided to you upon starting the integration.

<syntaxhighlight lang="javascript">XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX</syntaxhighlight>

==Integration==
We will cover the steps for constructing the Cloud API Calls.

===Request Overview===

====URL Structure====

The Cloud API Calls are HTTPS GET Requests with the URL structure:

<syntaxhighlight lang="javascript">[endpoint]/[appid]/[sessionID]/a?b=[payload]</syntaxhighlight>

The URL includes the following components:

*<code>[endpoint]</code>: location of data collection environment
*<code>[appid]</code>: provided App ID
*<code>[sessionID]</code>: unique value for each user session
*<code>[payload]</code>: metadata and events

====Endpoint====

There are endpoints for testing and production:

*Testing: <code>https://sandbox2-cloudapi.imrworldwide.com/nmapi/v2/</code>
*Production: <code>https://cloudapi.imrworldwide.com/nmapi/v2/</code>

During testing, all calls should be pointed to the testing endpoint. We will review the update to the production endpoint during the Go Live section of this guide.

====URL Example====
As you move through the integration steps, you can reference the below URL structure with the expanded payload:

<syntaxhighlight lang="javascript">
https://sandbox2-cloudapi.imrworldwide.com/nmapi/v2/[appid]/[sessionID]/a?b=
{
"devInfo": [deviceInfo],
"metadata": {
"static": [static_metadata],
"content": [content_metadata],
"ad": [ad metadata]
},
"event": [event],
"position": [playhead_position],
"type": [asset type],
"utc": [Unix time in ms]
}
</syntaxhighlight>

===Create Session ID and send UAID ping===
A unique Session ID <code>[sessionID]</code> must be created upon app launch and provided in the URL. This will allow measurement to occur for the entire duration that a user is within the app.

A Session ID needs to be completely unique so it is recommended to use a version 4 UUID or another method of your choosing to guarantee there are no repeats.

Upon exiting the app, the session will need to be terminated using the delete event. Sessions will automatically expire after 30 minutes of cloud inactivity.

==== Send UAID Ping ====
An UAID Ping must be sent using the created unique Session ID <code>[sessionID]</code> upon start of the first stream playback.
<syntaxhighlight lang="javascript">https://[sessionID].redinuid.imrworldwide.com/ </syntaxhighlight>

===Define URL Structure===
Define the URL structure using your provided <code>[appid]</code> and a unique <code>[sessionID]</code>.

<syntaxhighlight lang="javascript">https://sandbox2-cloudapi.imrworldwide.com/nmapi/v2/[appid]/[sessionID]/a?b=[payload]</syntaxhighlight>

===Configure Payload===

All Cloud API requests must contain the following payload data:

*''devInfo'': device and app info
*''metadata'': asset metadata
*''event metadata'': type of event

The payload can be passed through key-values using the Nielsen reserved keys. The specific keys and descriptions are highlighted in the tables included in this section.

'''Payload Example'''

The example below should be referenced when following the steps for configuring the request payload.

<syntaxhighlight lang="javascript">
// 3.1 Configure Payload: devInfo
payload = {
"devInfo": {
"devId": "AD-ID",
"hem_sha256": "55C06A30DAA5D5F382FDEB8C702EC57875CC9D91A7C78BB620053FD81DC4335C",
"uid2": "tMmiiTI7IaAcPpQPFQ65uMVCWH8av9jw4cwf/F5HVRQ=",
"uid2_token": "7be25cf9-8c40-5cc2-871e-19bf41940288MTKVpUAzwYAPnHrtfE0wlINOMzhU7UUEjjVdCdRu63k=uid_token=AgAAAAPFR0zA5ogv/yaAPiUsAdZPsfqS8QlDSGxAB+rr8yekFs3AjLYVk5qqqiyV2XHbSuwzHmxSlLeQeKQI1mp015jsNnpX5/xGgXldcgVz+gFnyh3T8/3agMwRmyrhCxG4oH2C7fc48AQk2eotE7FW0ZDEYM8fD9ZxDaxFUC/OV3OuZA&",
"apn": "AppName",
"apv": "1.0",
"uoo": "false"
},

// 3.2 Configure Payload: metadata
"metadata": {
"static": {}, // object for measuring static content
"content": { // object for measuring video content
"type": "content", // "content" for video
"assetid": "VIDEO-ID123", // unique ID for video
"isfullepisode": "y", // full episode flag
"program": "Program Name", // program name
"title": "Episode Title S3 - EP1", // episode name
"length": "1800", // content duration in seconds
"segB": "Custom Segment B", // custom segment
"segC": "Custom Segment C", // custom segment
"crossId1": "Standard Episode ID", // episode ID
"crossId2": "Content Originator ID", // content orginator (required for distributors)
"airdate": "20161013 20:00:00", // airdate
"adloadtype": "2" //ad load flag
"hasAds": "1", // content contains ads = 1 / no ads = 0
"progen": "CV" // program genre abbreviation
},
"ad": {
"type": "preroll", // type of ad
"assetid": "AD-ID123" // unique ID for ad
}
},

// 3.3 Configure Payload: events
"event": "playhead", //event name
"position": "300", // position in seconds
"type": "content", //"content" or "ad"
"utc": "1456448742000" //unix timestamp in milliseconds
}
</syntaxhighlight>

=====Configure Payload: devInfo=====
An object <code>"devInfo"</code> will need to be created to capture App and Device information.

{| class="wikitable"
|-
! Keys !! Description !! Values !! Required
|-
| devId || unique ID to identify user (e.g. Advertising ID, Roku Device ID) || custom || Yes
|-
| hem_sha256 || SHA-256 hashed email Note: email normalization rules applied before hashing || custom || Yes
|-
| uid2 || Trade Desk Unified ID 2.0 This should be the unencrypted, non-tokenized UID2.0 in the clear || custom || Yes
|-
| uid2_token ||Trade Desk Unified ID 2.0 UID2 token || custom || Yes
|-
| apn || app name || custom || Yes
|-
| apv || app build version || custom || Yes
|-
| uoo || device opt-out status || <code>"true"</code> or <code>"false"</code> || Yes
|-
|}

'''Example devInfo Object'''
<syntaxhighlight lang="javascript">
// create devInfo object
"devInfo": {
"devId": "AD-ID",
"hem_sha256": "55C06A30DAA5D5F382FDEB8C702EC57875CC9D91A7C78BB620053FD81DC4335C",
"uid2": "tMmiiTI7IaAcPpQPFQ65uMVCWH8av9jw4cwf/F5HVRQ=",
"uid2_token": "7be25cf9-8c40-5cc2-871e-19bf41940288MTKVpUAzwYAPnHrtfE0wlINOMzhU7UUEjjVdCdRu63k=uid_token=AgAAAAPFR0zA5ogv/yaAPiUsAdZPsfqS8QlDSGxAB+rr8yekFs3AjLYVk5qqqiyV2XHbSuwzHmxSlLeQeKQI1mp015jsNnpX5/xGgXldcgVz+gFnyh3T8/3agMwRmyrhCxG4oH2C7fc48AQk2eotE7FW0ZDEYM8fD9ZxDaxFUC/OV3OuZA&",
"apn": "AppName",
"apv": "1.0",
"uoo": "false"
},
</syntaxhighlight>

==== 3.2 Configure Payload: metadata ====
Asset metadata can be passed through <code>"metadata"</code>. There are two asset types: <code>"content"</code> for video and <code>"ad"</code> for ads. The metadata received for each asset is used for classification and reporting.

You will need to set up <code>"metadata"</code> objects for <code>"content"</code> and <code>"ad"</code> with the required Nielsen keys as shown in the sample code below.

===== Content Metadata =====
Content metadata should remain constant throughout the entirety of an episode/clip including when ads play.

{| class="wikitable"
|-
! Keys !! Description !! Values !! Required
|-
| type || type of asset || <code>"content"</code> || Yes
|-
| assetid || unique ID assigned to asset || custom <br>(no [[Special Characters]]) || Yes
|-
| program ||name of program (25 character limit) || custom || Yes
|-
| title ||name of program (25 character limit) || custom || Yes
|-
| length || length of content in seconds || <code>seconds</code> (0 for live stream) || Yes
|-
| segB || custom segment B || custom || No
|-
| segC || custom segment C || custom || No
|-
| airdate || the airdate in the linear TV || YYYYMMDD HH24:MI:SS || Yes
|-
| isfullepisode || full episode flag || <code>"y"</code>- full episode, <code>"n"</code>- non full episode || Yes
|-
| crossId1 || standard episode ID || custom || No
|-
| crossId2 || content originator (only required for distributors) || Nielsen || No
|-
| adloadtype || type of ad load:
<code>"1"</code> Linear – matches TV ad load

<code>"2"</code> Dynamic – Dynamic Ad Insertion (DAI)
|| <code>"2"</code> - DCR measures content with dynamic ads || Yes
|-
| hasAds || ads indicator
<code>"1"</code>: ads included

<code>"0"</code>: ads not included
|| <code>"1"</code> or <code>"0"</code> || Yes
|-
| subbrand || sub brand override || Nielsen || No
|-
| progen || program genre abbreviation - see [[DCR OTT Genre List]] for accepted values || <code>"CV"</code> for Comedy Variety || Yes
|}

'''Example Content Object'''
<syntaxhighlight lang='json'>// create content object
"content": {
"type": "content",
"assetid": "VIDEO-ID123",
"isfullepisode": "y",
"program": "Program Name",
"title": "Episode Title S3 - EP1",
"length": "1800",
"segB": "Custom Segment B",
"segC": "Custom Segment C",
"crossId1": "Standard Episode ID",
"crossId2": "Content Originator ID",
"airdate": "20161013 20:00:00",
"adloadtype": "2",
"hasAds": "1",
"subbrand": "c05",
"progen": "CV"
}</syntaxhighlight>

===== Ad Metadata =====
The ad metadata should be passed for each individual ad.

{| class="wikitable"
|-
! Keys !! Description !! Values !! Required
|-
| type || type of ad || <code>"preroll"</code>, <code>"midroll"</code>, or <code>"postroll"</code> || Yes
|-
| assetid || unique ID assigned to ad || custom || Yes
|}

===== Example Ad Object =====
<syntaxhighlight lang="javascript">
// create ad object
"ad": {
"type": "preroll",
"assetid": "AD-ID123"
}
</syntaxhighlight>

=== Configure Payload: Events ===

The last part of the payload is for enabling events so content is measured correctly when viewed. The events and required parameters are included below.

==== Event Types ====

The available events are:
{| class="wikitable"
|-
! Event !! Description
|-
| <code>"playhead"</code> || Playhead position in seconds, must be passed as a whole number every 10 seconds. The final playhead position should be sent before an asset has changed to properly capture full duration. When content is paused, stop passing playhead position until content is resumed. On playhead scrubbing, send current playhead position, followed by the playhead position the user scrubs to. For Live streams, you may use Unix Time (in seconds) as the playhead position. Note that ad playheads must also use Unix Time if Unix Time is used for content playheads.
|-
| <code>"complete"</code> || The complete event must be sent when the content has completed full playback. Before calling the complete event, a final playhead update with the final position is required to be sent to receive full duration credit. For Live streams, a complete event must be sent at program boundaries.
|-
| <code>"delete"</code> || The delete event is optional and can be sent when the viewing session is terminated (typically on App close). A new session ID must be generated after sending a delete event. Delete should not be sent on app interruptions or foreground/background events. All creditable duration will be summarized for all asset types when delete occurs (content and ads).
|}

===== Event Parameters =====

The following parameters need to be passed when calling events:

{| class="wikitable"
|-
! Parameter !! Description !! Value !! Required
|-
| <code>"event"</code> || event type || <code>"playhead"</code>, <code>"complete"</code>, or <code>"delete"</code> || Yes
|-
| <code>"position"</code> || playhead position in seconds or Unix time in seconds || <code>"300"</code> || Yes
|-
| <code>"type"</code> || asset type || <code>"content"</code>, <code>"ad"</code> || Yes
|-
| <code>"utc"</code> || Unix timestamp in milliseconds. Must be passed every 10 seconds. || <code>"1472760000000"</code> || Yes
|}

===== Example Event =====
You can call events by passing values in the required parameters:

<syntaxhighlight lang="javascript">
"devInfo": [deviceInfo],
"metadata": {
"static": [static metadata],
"content": [content metadata],
"ad": [ad metadata]
},
// Event Parameters
"event": [event], // event name
"position": [playheadPosition], //position in seconds
"type": [asset type], // values are "content" or "ad"
"utc": "1472760000000" //unix timestamp in milliseconds
}
</syntaxhighlight>

'''Note:''' The full payload including "devInfo" and "metadata" must be populated in each event request.

===== Sample Event Lifecycle =====
The sample event lifecycle can be used as a reference for identifying the order for calling events and values to pass.

<syntaxhighlight lang="javascript">
// Start of Session: session ID created when App is opened

// Preroll
Ad Playhead {"event": "playhead", "position": "0", "type": "ad", "utc": "1472760000000"}

// Content
Content Playhead {"event": "playhead", "position": "0", "type": "content", "utc": "1472760000000"}

// Midroll
Midroll Playhead {"event": "playhead", "position": "0", "type": "ad", "utc": "1472760000000"}

// Content resumes at 15 minutes
Content Playhead {"event": "playhead", "position": "900", "type": "content", "utc": "1472760000000"}

// Content completes at 30 minutes
Complete {"event": "complete", "position": "1800", "type": "content", "utc": "1472760000000"}

// Postroll
Ad Playhead {"event": "playhead", "position": "0", "type": "ad", "utc": "1472760000000"}

//End of Session: The delete event should be called when the App is exited. The values for position and type not required to be passed.
Delete { "event": "delete", "position": "", "type": "", "utc": "1472760000000"}
</syntaxhighlight>

'''Sample Event Lifecycle - Detailed Storyline'''
This detailed event sequence provides additional insight for the correct events to call when handling certain playback scenarios.
<syntaxhighlight lang='javascript'>// SESSION STARTS
// Start of Session: session ID created when App is opened

// PREROLL
// Preroll Start - Start each Ad with a position of "0", resetting to '0' for each Ad, and Ad break.
Ad Playhead {"event": "playhead", "position": "0", "type": "ad", "utc": "1472760000000"}

// Preroll Stop - End each Ad with the final position of the Ad.
Ad Playhead {"event": "playhead", "position": "15", "type": "ad", "utc": "1472761500000"}

// CONTENT
// Content Start - Start new content streams with a position of "0" incrementing the position every 10 seconds.
Content Playhead {"event": "playhead", "position": "0", "type": "content", "utc": "1472761500000"}

// Content Stop Before Ad Break - Send a playhead update including the current content positon before an Ad break.
Content Playhead {"event": "playhead", "position": "299", "type": "content", "utc": "1472787400000"}

// MIDROLL
// Midroll Start - Start each Ad with a position of "0", resetting to '0' for each Ad, and Ad break.
Midroll Playhead {"event": "playhead", "position": "0", "type": "ad", "utc": "1472787500000"}

// Midroll Stop - End each Ad with the final position of the Ad.
Ad Playhead {"event": "playhead", "position": "60", "type": "ad", "utc": "1472793500000"}

// CONTENT
// Content resumes at 5 minutes - Send playhead update with the current resumed position, and begin incrimenting the positon every 10 seconds.
Content Playhead {"event": "playhead", "position": "300", "type": "content", "utc": "1472799500000"}

// Content completes at 10:12 - Make sure to send in the playhead event with the final content position before sending the complete event.
Final Content Playhead {"event": "playhead", "position": "612", "type": "content", "utc": "1472830700000"}

Complete {"event": "complete", "position": "612", "type": "content", "utc": "1472830800000"}

// POSTROLL
// Postroll Start - Start each Ad with a position of "0", resetting to '0' for each Ad, and Ad break.
Ad Playhead {"event": "playhead", "position": "0", "type": "ad", "utc": "1472830900000"}

// Postroll Stop - End each Ad with the final position of the Ad.
Ad Playhead {"event": "playhead", "position": "45", "type": "ad", "utc": "1472835300000"}

// SESSION ENDS

//End of Session: The delete event should be called when the App is exited. The values for position and type not required to be passed.
Delete { "event": "delete", "position": "", "type": "", "utc": "1472835400000"} </syntaxhighlight>

=====Handling Playhead=====
Calling <code>"playhead"</code> is critical for accurate duration crediting. You can reference the below guidance to determine the correct playhead position to pass depending on the playback scenario.

'''Playhead: General'''
* Playhead position must start at 0 for each new asset, and be passed at least every 10 seconds.
* Final postion must be sent at the end of content or an ad
* Playheads should be sent in seconds only, not milliseconds

'''Playhead: Ads'''
* The final position must be sent when switching from content to ad, or ad to content.
* Each ad playhead position should be 0 at ad start.
* For Ad Pods, playhead must be called, and reset to 0 for each individual ad.
* The last content position before an Ad should be sent before switching to Ads.
* When content has resumed following an ad break, the playhead position update must continue where the previous content segment left off.

'''Playhead: User Actions'''
* Upon user scrubbing, the current position must be sent before a user scrubs, and the new position should be sent where the user lands, and begin sending in the 10 second updates thereafter.
* On pause, send the current position and then discontinue sending playhead event updates.
* If a user exits a stream early, the last current position must be sent in a playhead update to receive accurate duration.

===== Interruption Scenarios =====

As part of configuring events, you will need to handle all possible interruption scenarios such as:

*Wi-Fi OFF / ON
*App going Background / Foreground (Video players only, not for Audio players)
*App Crash or Exit

When playback is interrupted, the app needs to send delete immediately.

Once playback resumes, a new session will need to be created with a unique session ID. All of the required metadata and events will need to be sent.

'''Note:''' The session will automatically timeout after 30 minutes of inactivity.

=== Example Request ===

Now that we walked through the Cloud API integration steps, your requests should have the following components: Session ID, App ID, and Payload. You can reference the example below when your reviewing your integration.

<syntaxhighlight lang="javascript">
// 1. Create Session ID
sessionID = dfc7dc6a-66a7-4705-9fba-adaaf7e3d5e0 // Example sessionID created using a UUID Generator

// 2. Define URL Structure with App ID and Session ID
sessionURL = https://sandbox2-cloudapi.imrworldwide.com/nmapi/v2/[appid]/[sessionID]/a?b=

// 3. Configure Payload
// 3.1 Configure Payload: devInfo
payload = {
"devInfo": {
"devId": "AD-ID",
"apn": "AppName",
"apv": "1.0",
"uoo": "false"
},

// 3.2 Configure Payload: metadata
"metadata": {
"static": {}, // object for measuring static content
"content": { // object for measuring video content
"type": "content", // "content" for video
"assetid": "VIDEO-ID123", // unique ID for video
"isfullepisode": "y", // full episode flag
"program": "Program Name", // program name
"title": "Episode Title S3 - EP1", // episode name
"length": "1800", // content duration in seconds
"segB": "Custom Segment B", // custom segment
"segC": "Custom Segment C", // custom segment
"crossId1": "Standard Episode ID", // episode ID
"crossId2": "Content Originator ID", // content orginator (required for distributors)
"airdate": "20161013 20:00:00", // airdate
"adloadtype": "2", // ad load flag
"hasAds": "1", // content contains ads = 1 / no ads = 0
"progen": "CV" // program genre abbreviation
},
"ad": {
"type": "preroll", // type of ad
"assetid": "AD-ID123" // unique ID for ad
}
},

// 3.3 Configure Payload: events
"event": "playhead", //event name
"position": "300", // position in seconds
"type": "content", //"content" or "ad"
"utc": "1456448742000" //unix timestamp in milliseconds
}

// Append payload to URL
var image = new Image()
image.onerror = function() {
// wait and send again
}
(new Image).src = sessionURL+encodeURIComponent(JSON.stringify(payload));
</syntaxhighlight>

To ensure that the GET request does not receive a CORS issue, make sure to use the IMAGE request in conjunction with the content-type "text/plain" so CORS preflight is not triggered, causing the request to be rejected.

==== Enable Debug Logging ====

Now that you have set up the Cloud API requests, you can enable debug logging to validate your integration. Enabling debug logging is required for Nielsen certification.

==== GET Request ====

Display GET Request to console using a name to identify each event (e.g. playhead).

<syntaxhighlight lang="javascript">
console.log("Event", image);
</syntaxhighlight>

==== Payload ====

Output payload to identify required metadata and events.

<syntaxhighlight lang="javascript">
console.log("Event Payload", payload);
</syntaxhighlight>

==== HTTPS Response Code ====

Confirm request was completed by viewing HTTPS response code.

<syntaxhighlight lang="javascript">
code = msg.GetResponseCode();
console.log("Response Code", code);
</syntaxhighlight>

You can reference the HTTPS Response Code table when reviewing your requests:

{| class="wikitable"
|-
! Status Code !! Status Text !! Description
|-
| <code>200</code> || OK || request received
|-
| <code>403</code> || Forbidden || invalid App ID
|-
| <code>404</code> || Not Found || JSON issue
|}

== Opt-Out ==
Your app must provide a means for the user to Opt-Out, or Opt-In to Nielsen Measurement. This requirement can be fulfilled by checking the device OS for the user's setting of "Limit Ad Tracking" or similar option. If the device offers "Limit Ad Tracking" settings, you should set <code>uoo=true</code> or <code>uoo=false</code> depending on the user's privacy setting. Also, ensure that the <code>devId</code> is set to a blank value if the user elects to opt-out.

If the device does not have OS-level "Do Not Track" settings, you can implement opt-out by creating an Opt-Out/Opt-In button, toggle switch, or slider within the app "Settings", or "About" section to allow the user selection.

[[File:Nielsen Opt-Out.png|link=]]

You will need to store the User Opt-Out (uoo) status, so that it can be retrieved and populated in the <code>"devInfo"</code> metadata which will be sent in every Cloud API event (playhead, complete, & delete).

{| class="wikitable"
|-
! uoo Key !! Description !! Values
|-
| uoo || Device is Opted-In to Nielsen Measurement (Recommended Default Setting) || <code>"false"</code>
|-
| uoo || Device is Opted-Out of Nielsen Measurement || <code>"true"</code>
|}

===== devInfo Opt-In JSON Payload Example =====

<syntaxhighlight lang="javascript">
"devInfo": {
"apn": "Cloud API Sample App",
"apv": "1",
"devId": "7be25cf9-8c40-5cc2-871e-19bf41940288",
"uoo": "false"
},
</syntaxhighlight>

===== devInfo Opt-Out JSON Payload Example =====

<syntaxhighlight lang="javascript">
"devInfo": {
"apn": "Cloud API Sample App",
"apv": "1",
"devId": "", //devId must be blank when a user elects to Opt-Out.
"uoo": "true"
},
</syntaxhighlight>

===== Privacy Information Template To Include In Opt-Out Screen =====

Additionally, all applications must display the Nielsen privacy policy within their application, typically in the Settings/About screen of your application. The Nielsen privacy policy text is listed below.

<blockquote>
'''''ABOUT NIELSEN MEASUREMENT'''''

Television and the way we watch it have come a long way since Nielsen began measuring TV audiences in 1950. Today, the ability to watch our favorite shows at any time and on multiple devices amplifies the need for exceptionally adept and flexible audience measurement capabilities.

Consumers are changing with the times, and the same goes for us. As technology continues to evolve and media companies try new ways to attract viewers, understanding what consumers are watching — and what they're watching on — is more important than ever. Today, viewing video is a personal and mobile experience — anytime and anywhere. Our capabilities provide relevant metrics that are necessary to inform successful marketing and programming and drive continued growth. As a global information and measurement leader, we are committed to protecting the privacy and security of the data we collect, process and use. While our digital measurement products are not used to identify you in any way, they help us and our clients measure and analyze how consumers engage with media across online, mobile and emerging technologies, and offer insights into consumer behavior.

'''''YOUR CHOICES'''''

Nielsen believes that you should have a choice about whether to contribute to our research and insights. To opt out or opt in to Nielsen measurement, please toggle your "Limit Ad Tracking" (or similar setting) on your device, or make the appropriate selection within the application's settings. If you have this app on more than one device, you will need to opt out of this app on each device. To learn more about our digital measurement products and your choices in regard to them, please visit https://www.nielsen.com/digitalprivacy.

</blockquote>

== Testing ==
Before providing an app build to Nielsen for testing, it is important to run validation checks once you have enabled debug logging.

=== Payload Validation ===

Ensure that all of the required payload data is populating while testing several videos. The following areas are critical to measurement:
*devInfo
*Asset metadata for both content, and ads
*Events
*Opt-Out status

=== Player Events ===
Review event calls:

==== playhead ====
*Playhead position updates every 10 seconds starting at position '0' for each new asset.
*Final playhead position is sent on content, or ad before switching between assets.
*Content metadata remains constant throughout an episode, or clip play.
*Ad metadata is populated appropriately for each individual ad.
*Playhead position update resumes for content after an ad break, and resets to 0 for each individual ad.
*For scrubbing, last current position should be sent while scrubbing occurs, and the new position should also be sent where the user scrubs to.
*Exiting a stream early should execute the last current position in a playhead update to receive accurate duration.
*Upon pause, the current position should be sent, and playhead updates should stop incrementing until resume play occurs.

==== complete ====
*Check that the complete event executes upon content complete after the final playhead update is sent
*Do not execute the complete event for ads

==== delete ====
*Check to see that the delete event occurs upon app exit, if the platform has the necessary exit callback events.

==== GET Request Format ====
*Ensure that the event payloads are formatted in JSON
*Check to see that each of the Cloud API GET requests are properly encoded

==== HTTPS Response ====
*Make sure that each of the Cloud API Get requests are received by the Nielsen Cloud API properly through use of the HTTPS Response Code outputs enabled in console.

==== Opt-Out ====
*Test the "uoo" key gets populated accurately for both Opt-In and Opt-Out selections by validating the Cloud API events called after the user Opt-Out/Opt-In selection.
*Test that the devId field is populated with a blank value if a user has elected to Opt-Out. For example: "devId": "",
*If the device supports "Limit Ad Tracking" or has device "Opt-Out" settings, test that uoo=true, and that devId is set to a blank value if enabled in the device settings.

== Go Live ==
After your integration has been certified, you will need to: Change Endpoint and Disable Logging.

'''Change Endpoint:''' You will need to update to the production endpoint:

*Testing: <code>https://sandbox2-cloudapi.imrworldwide.com/nmapi/v2/</code>
*Production: <code>https://cloudapi.imrworldwide.com/nmapi/v2/</code>

Your production URL structure should now be:
<code>https://cloudapi.imrworldwide.com/nmapi/v2/[appid]/[sessionID]/a?b=[payload]</code>

'''Disable Logging:''' You can now disable debug logging

DCR Video & Static Cloud API

2025-04-23T21:20:56Z

AmySockanathan: /* Send UAID Ping */

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

This guide shows you how to integrate the Nielsen Cloud API to enable Digital Content Ratings (DCR), and fuel other measurement products on your over-the-top (OTT) Apps.
*For Roku Apps, please see [[DCR Video & Static Roku Cloud API]]
*For Mobile Apps, please see [[DCR Video & Static Mobile Cloud API]]

==Prerequisites==
To get started, you will need a Nielsen App ID. The App ID is a unique ID assigned to your app. This will be provided to you upon starting the integration.

<syntaxhighlight lang="javascript">XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX</syntaxhighlight>

==Integration==
We will cover the steps for constructing the Cloud API Calls.

===Request Overview===

====URL Structure====

The Cloud API Calls are HTTPS GET Requests with the URL structure:

<syntaxhighlight lang="javascript">[endpoint]/[appid]/[sessionID]/a?b=[payload]</syntaxhighlight>

The URL includes the following components:

*<code>[endpoint]</code>: location of data collection environment
*<code>[appid]</code>: provided App ID
*<code>[sessionID]</code>: unique value for each user session
*<code>[payload]</code>: metadata and events

====Endpoint====

There are endpoints for testing and production:

*Testing: <code>https://sandbox2-cloudapi.imrworldwide.com/nmapi/v2/</code>
*Production: <code>https://cloudapi.imrworldwide.com/nmapi/v2/</code>

During testing, all calls should be pointed to the testing endpoint. We will review the update to the production endpoint during the Go Live section of this guide.

====URL Example====
As you move through the integration steps, you can reference the below URL structure with the expanded payload:

<syntaxhighlight lang="javascript">
https://sandbox2-cloudapi.imrworldwide.com/nmapi/v2/[appid]/[sessionID]/a?b=
{
"devInfo": [deviceInfo],
"metadata": {
"static": [static_metadata],
"content": [content_metadata],
"ad": [ad metadata]
},
"event": [event],
"position": [playhead_position],
"type": [asset type],
"utc": [Unix time in ms]
}
</syntaxhighlight>

===Create Session ID and send UAID ping===
A unique Session ID <code>[sessionID]</code> must be created upon app launch and provided in the URL. This will allow measurement to occur for the entire duration that a user is within the app.

A Session ID needs to be completely unique so it is recommended to use a version 4 UUID or another method of your choosing to guarantee there are no repeats.

Upon exiting the app, the session will need to be terminated using the delete event. Sessions will automatically expire after 30 minutes of cloud inactivity.

==== Send UAID Ping ====
An UAID Ping must be sent using the created unique Session ID <code>[sessionID]</code> upon start of the first stream playback.
<code>https://[sessionID].redinuid.imrworldwide<nowiki/>.com/ </code>

===Define URL Structure===
Define the URL structure using your provided <code>[appid]</code> and a unique <code>[sessionID]</code>.

<syntaxhighlight lang="javascript">https://sandbox2-cloudapi.imrworldwide.com/nmapi/v2/[appid]/[sessionID]/a?b=[payload]</syntaxhighlight>

===Configure Payload===

All Cloud API requests must contain the following payload data:

*''devInfo'': device and app info
*''metadata'': asset metadata
*''event metadata'': type of event

The payload can be passed through key-values using the Nielsen reserved keys. The specific keys and descriptions are highlighted in the tables included in this section.

'''Payload Example'''

The example below should be referenced when following the steps for configuring the request payload.

<syntaxhighlight lang="javascript">
// 3.1 Configure Payload: devInfo
payload = {
"devInfo": {
"devId": "AD-ID",
"hem_sha256": "55C06A30DAA5D5F382FDEB8C702EC57875CC9D91A7C78BB620053FD81DC4335C",
"uid2": "tMmiiTI7IaAcPpQPFQ65uMVCWH8av9jw4cwf/F5HVRQ=",
"uid2_token": "7be25cf9-8c40-5cc2-871e-19bf41940288MTKVpUAzwYAPnHrtfE0wlINOMzhU7UUEjjVdCdRu63k=uid_token=AgAAAAPFR0zA5ogv/yaAPiUsAdZPsfqS8QlDSGxAB+rr8yekFs3AjLYVk5qqqiyV2XHbSuwzHmxSlLeQeKQI1mp015jsNnpX5/xGgXldcgVz+gFnyh3T8/3agMwRmyrhCxG4oH2C7fc48AQk2eotE7FW0ZDEYM8fD9ZxDaxFUC/OV3OuZA&",
"apn": "AppName",
"apv": "1.0",
"uoo": "false"
},

// 3.2 Configure Payload: metadata
"metadata": {
"static": {}, // object for measuring static content
"content": { // object for measuring video content
"type": "content", // "content" for video
"assetid": "VIDEO-ID123", // unique ID for video
"isfullepisode": "y", // full episode flag
"program": "Program Name", // program name
"title": "Episode Title S3 - EP1", // episode name
"length": "1800", // content duration in seconds
"segB": "Custom Segment B", // custom segment
"segC": "Custom Segment C", // custom segment
"crossId1": "Standard Episode ID", // episode ID
"crossId2": "Content Originator ID", // content orginator (required for distributors)
"airdate": "20161013 20:00:00", // airdate
"adloadtype": "2" //ad load flag
"hasAds": "1", // content contains ads = 1 / no ads = 0
"progen": "CV" // program genre abbreviation
},
"ad": {
"type": "preroll", // type of ad
"assetid": "AD-ID123" // unique ID for ad
}
},

// 3.3 Configure Payload: events
"event": "playhead", //event name
"position": "300", // position in seconds
"type": "content", //"content" or "ad"
"utc": "1456448742000" //unix timestamp in milliseconds
}
</syntaxhighlight>

=====Configure Payload: devInfo=====
An object <code>"devInfo"</code> will need to be created to capture App and Device information.

{| class="wikitable"
|-
! Keys !! Description !! Values !! Required
|-
| devId || unique ID to identify user (e.g. Advertising ID, Roku Device ID) || custom || Yes
|-
| hem_sha256 || SHA-256 hashed email Note: email normalization rules applied before hashing || custom || Yes
|-
| uid2 || Trade Desk Unified ID 2.0 This should be the unencrypted, non-tokenized UID2.0 in the clear || custom || Yes
|-
| uid2_token ||Trade Desk Unified ID 2.0 UID2 token || custom || Yes
|-
| apn || app name || custom || Yes
|-
| apv || app build version || custom || Yes
|-
| uoo || device opt-out status || <code>"true"</code> or <code>"false"</code> || Yes
|-
|}

'''Example devInfo Object'''
<syntaxhighlight lang="javascript">
// create devInfo object
"devInfo": {
"devId": "AD-ID",
"hem_sha256": "55C06A30DAA5D5F382FDEB8C702EC57875CC9D91A7C78BB620053FD81DC4335C",
"uid2": "tMmiiTI7IaAcPpQPFQ65uMVCWH8av9jw4cwf/F5HVRQ=",
"uid2_token": "7be25cf9-8c40-5cc2-871e-19bf41940288MTKVpUAzwYAPnHrtfE0wlINOMzhU7UUEjjVdCdRu63k=uid_token=AgAAAAPFR0zA5ogv/yaAPiUsAdZPsfqS8QlDSGxAB+rr8yekFs3AjLYVk5qqqiyV2XHbSuwzHmxSlLeQeKQI1mp015jsNnpX5/xGgXldcgVz+gFnyh3T8/3agMwRmyrhCxG4oH2C7fc48AQk2eotE7FW0ZDEYM8fD9ZxDaxFUC/OV3OuZA&",
"apn": "AppName",
"apv": "1.0",
"uoo": "false"
},
</syntaxhighlight>

==== 3.2 Configure Payload: metadata ====
Asset metadata can be passed through <code>"metadata"</code>. There are two asset types: <code>"content"</code> for video and <code>"ad"</code> for ads. The metadata received for each asset is used for classification and reporting.

You will need to set up <code>"metadata"</code> objects for <code>"content"</code> and <code>"ad"</code> with the required Nielsen keys as shown in the sample code below.

===== Content Metadata =====
Content metadata should remain constant throughout the entirety of an episode/clip including when ads play.

{| class="wikitable"
|-
! Keys !! Description !! Values !! Required
|-
| type || type of asset || <code>"content"</code> || Yes
|-
| assetid || unique ID assigned to asset || custom <br>(no [[Special Characters]]) || Yes
|-
| program ||name of program (25 character limit) || custom || Yes
|-
| title ||name of program (25 character limit) || custom || Yes
|-
| length || length of content in seconds || <code>seconds</code> (0 for live stream) || Yes
|-
| segB || custom segment B || custom || No
|-
| segC || custom segment C || custom || No
|-
| airdate || the airdate in the linear TV || YYYYMMDD HH24:MI:SS || Yes
|-
| isfullepisode || full episode flag || <code>"y"</code>- full episode, <code>"n"</code>- non full episode || Yes
|-
| crossId1 || standard episode ID || custom || No
|-
| crossId2 || content originator (only required for distributors) || Nielsen || No
|-
| adloadtype || type of ad load:
<code>"1"</code> Linear – matches TV ad load

<code>"2"</code> Dynamic – Dynamic Ad Insertion (DAI)
|| <code>"2"</code> - DCR measures content with dynamic ads || Yes
|-
| hasAds || ads indicator
<code>"1"</code>: ads included

<code>"0"</code>: ads not included
|| <code>"1"</code> or <code>"0"</code> || Yes
|-
| subbrand || sub brand override || Nielsen || No
|-
| progen || program genre abbreviation - see [[DCR OTT Genre List]] for accepted values || <code>"CV"</code> for Comedy Variety || Yes
|}

'''Example Content Object'''
<syntaxhighlight lang='json'>// create content object
"content": {
"type": "content",
"assetid": "VIDEO-ID123",
"isfullepisode": "y",
"program": "Program Name",
"title": "Episode Title S3 - EP1",
"length": "1800",
"segB": "Custom Segment B",
"segC": "Custom Segment C",
"crossId1": "Standard Episode ID",
"crossId2": "Content Originator ID",
"airdate": "20161013 20:00:00",
"adloadtype": "2",
"hasAds": "1",
"subbrand": "c05",
"progen": "CV"
}</syntaxhighlight>

===== Ad Metadata =====
The ad metadata should be passed for each individual ad.

{| class="wikitable"
|-
! Keys !! Description !! Values !! Required
|-
| type || type of ad || <code>"preroll"</code>, <code>"midroll"</code>, or <code>"postroll"</code> || Yes
|-
| assetid || unique ID assigned to ad || custom || Yes
|}

===== Example Ad Object =====
<syntaxhighlight lang="javascript">
// create ad object
"ad": {
"type": "preroll",
"assetid": "AD-ID123"
}
</syntaxhighlight>

=== Configure Payload: Events ===

The last part of the payload is for enabling events so content is measured correctly when viewed. The events and required parameters are included below.

==== Event Types ====

The available events are:
{| class="wikitable"
|-
! Event !! Description
|-
| <code>"playhead"</code> || Playhead position in seconds, must be passed as a whole number every 10 seconds. The final playhead position should be sent before an asset has changed to properly capture full duration. When content is paused, stop passing playhead position until content is resumed. On playhead scrubbing, send current playhead position, followed by the playhead position the user scrubs to. For Live streams, you may use Unix Time (in seconds) as the playhead position. Note that ad playheads must also use Unix Time if Unix Time is used for content playheads.
|-
| <code>"complete"</code> || The complete event must be sent when the content has completed full playback. Before calling the complete event, a final playhead update with the final position is required to be sent to receive full duration credit. For Live streams, a complete event must be sent at program boundaries.
|-
| <code>"delete"</code> || The delete event is optional and can be sent when the viewing session is terminated (typically on App close). A new session ID must be generated after sending a delete event. Delete should not be sent on app interruptions or foreground/background events. All creditable duration will be summarized for all asset types when delete occurs (content and ads).
|}

===== Event Parameters =====

The following parameters need to be passed when calling events:

{| class="wikitable"
|-
! Parameter !! Description !! Value !! Required
|-
| <code>"event"</code> || event type || <code>"playhead"</code>, <code>"complete"</code>, or <code>"delete"</code> || Yes
|-
| <code>"position"</code> || playhead position in seconds or Unix time in seconds || <code>"300"</code> || Yes
|-
| <code>"type"</code> || asset type || <code>"content"</code>, <code>"ad"</code> || Yes
|-
| <code>"utc"</code> || Unix timestamp in milliseconds. Must be passed every 10 seconds. || <code>"1472760000000"</code> || Yes
|}

===== Example Event =====
You can call events by passing values in the required parameters:

<syntaxhighlight lang="javascript">
"devInfo": [deviceInfo],
"metadata": {
"static": [static metadata],
"content": [content metadata],
"ad": [ad metadata]
},
// Event Parameters
"event": [event], // event name
"position": [playheadPosition], //position in seconds
"type": [asset type], // values are "content" or "ad"
"utc": "1472760000000" //unix timestamp in milliseconds
}
</syntaxhighlight>

'''Note:''' The full payload including "devInfo" and "metadata" must be populated in each event request.

===== Sample Event Lifecycle =====
The sample event lifecycle can be used as a reference for identifying the order for calling events and values to pass.

<syntaxhighlight lang="javascript">
// Start of Session: session ID created when App is opened

// Preroll
Ad Playhead {"event": "playhead", "position": "0", "type": "ad", "utc": "1472760000000"}

// Content
Content Playhead {"event": "playhead", "position": "0", "type": "content", "utc": "1472760000000"}

// Midroll
Midroll Playhead {"event": "playhead", "position": "0", "type": "ad", "utc": "1472760000000"}

// Content resumes at 15 minutes
Content Playhead {"event": "playhead", "position": "900", "type": "content", "utc": "1472760000000"}

// Content completes at 30 minutes
Complete {"event": "complete", "position": "1800", "type": "content", "utc": "1472760000000"}

// Postroll
Ad Playhead {"event": "playhead", "position": "0", "type": "ad", "utc": "1472760000000"}

//End of Session: The delete event should be called when the App is exited. The values for position and type not required to be passed.
Delete { "event": "delete", "position": "", "type": "", "utc": "1472760000000"}
</syntaxhighlight>

'''Sample Event Lifecycle - Detailed Storyline'''
This detailed event sequence provides additional insight for the correct events to call when handling certain playback scenarios.
<syntaxhighlight lang='javascript'>// SESSION STARTS
// Start of Session: session ID created when App is opened

// PREROLL
// Preroll Start - Start each Ad with a position of "0", resetting to '0' for each Ad, and Ad break.
Ad Playhead {"event": "playhead", "position": "0", "type": "ad", "utc": "1472760000000"}

// Preroll Stop - End each Ad with the final position of the Ad.
Ad Playhead {"event": "playhead", "position": "15", "type": "ad", "utc": "1472761500000"}

// CONTENT
// Content Start - Start new content streams with a position of "0" incrementing the position every 10 seconds.
Content Playhead {"event": "playhead", "position": "0", "type": "content", "utc": "1472761500000"}

// Content Stop Before Ad Break - Send a playhead update including the current content positon before an Ad break.
Content Playhead {"event": "playhead", "position": "299", "type": "content", "utc": "1472787400000"}

// MIDROLL
// Midroll Start - Start each Ad with a position of "0", resetting to '0' for each Ad, and Ad break.
Midroll Playhead {"event": "playhead", "position": "0", "type": "ad", "utc": "1472787500000"}

// Midroll Stop - End each Ad with the final position of the Ad.
Ad Playhead {"event": "playhead", "position": "60", "type": "ad", "utc": "1472793500000"}

// CONTENT
// Content resumes at 5 minutes - Send playhead update with the current resumed position, and begin incrimenting the positon every 10 seconds.
Content Playhead {"event": "playhead", "position": "300", "type": "content", "utc": "1472799500000"}

// Content completes at 10:12 - Make sure to send in the playhead event with the final content position before sending the complete event.
Final Content Playhead {"event": "playhead", "position": "612", "type": "content", "utc": "1472830700000"}

Complete {"event": "complete", "position": "612", "type": "content", "utc": "1472830800000"}

// POSTROLL
// Postroll Start - Start each Ad with a position of "0", resetting to '0' for each Ad, and Ad break.
Ad Playhead {"event": "playhead", "position": "0", "type": "ad", "utc": "1472830900000"}

// Postroll Stop - End each Ad with the final position of the Ad.
Ad Playhead {"event": "playhead", "position": "45", "type": "ad", "utc": "1472835300000"}

// SESSION ENDS

//End of Session: The delete event should be called when the App is exited. The values for position and type not required to be passed.
Delete { "event": "delete", "position": "", "type": "", "utc": "1472835400000"} </syntaxhighlight>

=====Handling Playhead=====
Calling <code>"playhead"</code> is critical for accurate duration crediting. You can reference the below guidance to determine the correct playhead position to pass depending on the playback scenario.

'''Playhead: General'''
* Playhead position must start at 0 for each new asset, and be passed at least every 10 seconds.
* Final postion must be sent at the end of content or an ad
* Playheads should be sent in seconds only, not milliseconds

'''Playhead: Ads'''
* The final position must be sent when switching from content to ad, or ad to content.
* Each ad playhead position should be 0 at ad start.
* For Ad Pods, playhead must be called, and reset to 0 for each individual ad.
* The last content position before an Ad should be sent before switching to Ads.
* When content has resumed following an ad break, the playhead position update must continue where the previous content segment left off.

'''Playhead: User Actions'''
* Upon user scrubbing, the current position must be sent before a user scrubs, and the new position should be sent where the user lands, and begin sending in the 10 second updates thereafter.
* On pause, send the current position and then discontinue sending playhead event updates.
* If a user exits a stream early, the last current position must be sent in a playhead update to receive accurate duration.

===== Interruption Scenarios =====

As part of configuring events, you will need to handle all possible interruption scenarios such as:

*Wi-Fi OFF / ON
*App going Background / Foreground (Video players only, not for Audio players)
*App Crash or Exit

When playback is interrupted, the app needs to send delete immediately.

Once playback resumes, a new session will need to be created with a unique session ID. All of the required metadata and events will need to be sent.

'''Note:''' The session will automatically timeout after 30 minutes of inactivity.

=== Example Request ===

Now that we walked through the Cloud API integration steps, your requests should have the following components: Session ID, App ID, and Payload. You can reference the example below when your reviewing your integration.

<syntaxhighlight lang="javascript">
// 1. Create Session ID
sessionID = dfc7dc6a-66a7-4705-9fba-adaaf7e3d5e0 // Example sessionID created using a UUID Generator

// 2. Define URL Structure with App ID and Session ID
sessionURL = https://sandbox2-cloudapi.imrworldwide.com/nmapi/v2/[appid]/[sessionID]/a?b=

// 3. Configure Payload
// 3.1 Configure Payload: devInfo
payload = {
"devInfo": {
"devId": "AD-ID",
"apn": "AppName",
"apv": "1.0",
"uoo": "false"
},

// 3.2 Configure Payload: metadata
"metadata": {
"static": {}, // object for measuring static content
"content": { // object for measuring video content
"type": "content", // "content" for video
"assetid": "VIDEO-ID123", // unique ID for video
"isfullepisode": "y", // full episode flag
"program": "Program Name", // program name
"title": "Episode Title S3 - EP1", // episode name
"length": "1800", // content duration in seconds
"segB": "Custom Segment B", // custom segment
"segC": "Custom Segment C", // custom segment
"crossId1": "Standard Episode ID", // episode ID
"crossId2": "Content Originator ID", // content orginator (required for distributors)
"airdate": "20161013 20:00:00", // airdate
"adloadtype": "2", // ad load flag
"hasAds": "1", // content contains ads = 1 / no ads = 0
"progen": "CV" // program genre abbreviation
},
"ad": {
"type": "preroll", // type of ad
"assetid": "AD-ID123" // unique ID for ad
}
},

// 3.3 Configure Payload: events
"event": "playhead", //event name
"position": "300", // position in seconds
"type": "content", //"content" or "ad"
"utc": "1456448742000" //unix timestamp in milliseconds
}

// Append payload to URL
var image = new Image()
image.onerror = function() {
// wait and send again
}
(new Image).src = sessionURL+encodeURIComponent(JSON.stringify(payload));
</syntaxhighlight>

To ensure that the GET request does not receive a CORS issue, make sure to use the IMAGE request in conjunction with the content-type "text/plain" so CORS preflight is not triggered, causing the request to be rejected.

==== Enable Debug Logging ====

Now that you have set up the Cloud API requests, you can enable debug logging to validate your integration. Enabling debug logging is required for Nielsen certification.

==== GET Request ====

Display GET Request to console using a name to identify each event (e.g. playhead).

<syntaxhighlight lang="javascript">
console.log("Event", image);
</syntaxhighlight>

==== Payload ====

Output payload to identify required metadata and events.

<syntaxhighlight lang="javascript">
console.log("Event Payload", payload);
</syntaxhighlight>

==== HTTPS Response Code ====

Confirm request was completed by viewing HTTPS response code.

<syntaxhighlight lang="javascript">
code = msg.GetResponseCode();
console.log("Response Code", code);
</syntaxhighlight>

You can reference the HTTPS Response Code table when reviewing your requests:

{| class="wikitable"
|-
! Status Code !! Status Text !! Description
|-
| <code>200</code> || OK || request received
|-
| <code>403</code> || Forbidden || invalid App ID
|-
| <code>404</code> || Not Found || JSON issue
|}

== Opt-Out ==
Your app must provide a means for the user to Opt-Out, or Opt-In to Nielsen Measurement. This requirement can be fulfilled by checking the device OS for the user's setting of "Limit Ad Tracking" or similar option. If the device offers "Limit Ad Tracking" settings, you should set <code>uoo=true</code> or <code>uoo=false</code> depending on the user's privacy setting. Also, ensure that the <code>devId</code> is set to a blank value if the user elects to opt-out.

If the device does not have OS-level "Do Not Track" settings, you can implement opt-out by creating an Opt-Out/Opt-In button, toggle switch, or slider within the app "Settings", or "About" section to allow the user selection.

[[File:Nielsen Opt-Out.png|link=]]

You will need to store the User Opt-Out (uoo) status, so that it can be retrieved and populated in the <code>"devInfo"</code> metadata which will be sent in every Cloud API event (playhead, complete, & delete).

{| class="wikitable"
|-
! uoo Key !! Description !! Values
|-
| uoo || Device is Opted-In to Nielsen Measurement (Recommended Default Setting) || <code>"false"</code>
|-
| uoo || Device is Opted-Out of Nielsen Measurement || <code>"true"</code>
|}

===== devInfo Opt-In JSON Payload Example =====

<syntaxhighlight lang="javascript">
"devInfo": {
"apn": "Cloud API Sample App",
"apv": "1",
"devId": "7be25cf9-8c40-5cc2-871e-19bf41940288",
"uoo": "false"
},
</syntaxhighlight>

===== devInfo Opt-Out JSON Payload Example =====

<syntaxhighlight lang="javascript">
"devInfo": {
"apn": "Cloud API Sample App",
"apv": "1",
"devId": "", //devId must be blank when a user elects to Opt-Out.
"uoo": "true"
},
</syntaxhighlight>

===== Privacy Information Template To Include In Opt-Out Screen =====

Additionally, all applications must display the Nielsen privacy policy within their application, typically in the Settings/About screen of your application. The Nielsen privacy policy text is listed below.

<blockquote>
'''''ABOUT NIELSEN MEASUREMENT'''''

Television and the way we watch it have come a long way since Nielsen began measuring TV audiences in 1950. Today, the ability to watch our favorite shows at any time and on multiple devices amplifies the need for exceptionally adept and flexible audience measurement capabilities.

Consumers are changing with the times, and the same goes for us. As technology continues to evolve and media companies try new ways to attract viewers, understanding what consumers are watching — and what they're watching on — is more important than ever. Today, viewing video is a personal and mobile experience — anytime and anywhere. Our capabilities provide relevant metrics that are necessary to inform successful marketing and programming and drive continued growth. As a global information and measurement leader, we are committed to protecting the privacy and security of the data we collect, process and use. While our digital measurement products are not used to identify you in any way, they help us and our clients measure and analyze how consumers engage with media across online, mobile and emerging technologies, and offer insights into consumer behavior.

'''''YOUR CHOICES'''''

Nielsen believes that you should have a choice about whether to contribute to our research and insights. To opt out or opt in to Nielsen measurement, please toggle your "Limit Ad Tracking" (or similar setting) on your device, or make the appropriate selection within the application's settings. If you have this app on more than one device, you will need to opt out of this app on each device. To learn more about our digital measurement products and your choices in regard to them, please visit https://www.nielsen.com/digitalprivacy.

</blockquote>

== Testing ==
Before providing an app build to Nielsen for testing, it is important to run validation checks once you have enabled debug logging.

=== Payload Validation ===

Ensure that all of the required payload data is populating while testing several videos. The following areas are critical to measurement:
*devInfo
*Asset metadata for both content, and ads
*Events
*Opt-Out status

=== Player Events ===
Review event calls:

==== playhead ====
*Playhead position updates every 10 seconds starting at position '0' for each new asset.
*Final playhead position is sent on content, or ad before switching between assets.
*Content metadata remains constant throughout an episode, or clip play.
*Ad metadata is populated appropriately for each individual ad.
*Playhead position update resumes for content after an ad break, and resets to 0 for each individual ad.
*For scrubbing, last current position should be sent while scrubbing occurs, and the new position should also be sent where the user scrubs to.
*Exiting a stream early should execute the last current position in a playhead update to receive accurate duration.
*Upon pause, the current position should be sent, and playhead updates should stop incrementing until resume play occurs.

==== complete ====
*Check that the complete event executes upon content complete after the final playhead update is sent
*Do not execute the complete event for ads

==== delete ====
*Check to see that the delete event occurs upon app exit, if the platform has the necessary exit callback events.

==== GET Request Format ====
*Ensure that the event payloads are formatted in JSON
*Check to see that each of the Cloud API GET requests are properly encoded

==== HTTPS Response ====
*Make sure that each of the Cloud API Get requests are received by the Nielsen Cloud API properly through use of the HTTPS Response Code outputs enabled in console.

==== Opt-Out ====
*Test the "uoo" key gets populated accurately for both Opt-In and Opt-Out selections by validating the Cloud API events called after the user Opt-Out/Opt-In selection.
*Test that the devId field is populated with a blank value if a user has elected to Opt-Out. For example: "devId": "",
*If the device supports "Limit Ad Tracking" or has device "Opt-Out" settings, test that uoo=true, and that devId is set to a blank value if enabled in the device settings.

== Go Live ==
After your integration has been certified, you will need to: Change Endpoint and Disable Logging.

'''Change Endpoint:''' You will need to update to the production endpoint:

*Testing: <code>https://sandbox2-cloudapi.imrworldwide.com/nmapi/v2/</code>
*Production: <code>https://cloudapi.imrworldwide.com/nmapi/v2/</code>

Your production URL structure should now be:
<code>https://cloudapi.imrworldwide.com/nmapi/v2/[appid]/[sessionID]/a?b=[payload]</code>

'''Disable Logging:''' You can now disable debug logging

DCR Video & Static Cloud API

2025-04-23T21:14:43Z

AmySockanathan: Send UAID ping documentation

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

This guide shows you how to integrate the Nielsen Cloud API to enable Digital Content Ratings (DCR), and fuel other measurement products on your over-the-top (OTT) Apps.
*For Roku Apps, please see [[DCR Video & Static Roku Cloud API]]
*For Mobile Apps, please see [[DCR Video & Static Mobile Cloud API]]

==Prerequisites==
To get started, you will need a Nielsen App ID. The App ID is a unique ID assigned to your app. This will be provided to you upon starting the integration.

<syntaxhighlight lang="javascript">XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX</syntaxhighlight>

==Integration==
We will cover the steps for constructing the Cloud API Calls.

===Request Overview===

====URL Structure====

The Cloud API Calls are HTTPS GET Requests with the URL structure:

<syntaxhighlight lang="javascript">[endpoint]/[appid]/[sessionID]/a?b=[payload]</syntaxhighlight>

The URL includes the following components:

*<code>[endpoint]</code>: location of data collection environment
*<code>[appid]</code>: provided App ID
*<code>[sessionID]</code>: unique value for each user session
*<code>[payload]</code>: metadata and events

====Endpoint====

There are endpoints for testing and production:

*Testing: <code>https://sandbox2-cloudapi.imrworldwide.com/nmapi/v2/</code>
*Production: <code>https://cloudapi.imrworldwide.com/nmapi/v2/</code>

During testing, all calls should be pointed to the testing endpoint. We will review the update to the production endpoint during the Go Live section of this guide.

====URL Example====
As you move through the integration steps, you can reference the below URL structure with the expanded payload:

<syntaxhighlight lang="javascript">
https://sandbox2-cloudapi.imrworldwide.com/nmapi/v2/[appid]/[sessionID]/a?b=
{
"devInfo": [deviceInfo],
"metadata": {
"static": [static_metadata],
"content": [content_metadata],
"ad": [ad metadata]
},
"event": [event],
"position": [playhead_position],
"type": [asset type],
"utc": [Unix time in ms]
}
</syntaxhighlight>

===Create Session ID and send UAID ping===
A unique Session ID <code>[sessionID]</code> must be created upon app launch and provided in the URL. This will allow measurement to occur for the entire duration that a user is within the app.

A Session ID needs to be completely unique so it is recommended to use a version 4 UUID or another method of your choosing to guarantee there are no repeats.

Upon exiting the app, the session will need to be terminated using the delete event. Sessions will automatically expire after 30 minutes of cloud inactivity.

==== Send UAID Ping ====
An UAID Ping must be sent using the created unique Session ID <code>[sessionID]</code> upon start of the first stream playback.
https://[sessionID].redinuid.imrworldwide<nowiki/>.com/

===Define URL Structure===
Define the URL structure using your provided <code>[appid]</code> and a unique <code>[sessionID]</code>.

<syntaxhighlight lang="javascript">https://sandbox2-cloudapi.imrworldwide.com/nmapi/v2/[appid]/[sessionID]/a?b=[payload]</syntaxhighlight>

===Configure Payload===

All Cloud API requests must contain the following payload data:

*''devInfo'': device and app info
*''metadata'': asset metadata
*''event metadata'': type of event

The payload can be passed through key-values using the Nielsen reserved keys. The specific keys and descriptions are highlighted in the tables included in this section.

'''Payload Example'''

The example below should be referenced when following the steps for configuring the request payload.

<syntaxhighlight lang="javascript">
// 3.1 Configure Payload: devInfo
payload = {
"devInfo": {
"devId": "AD-ID",
"hem_sha256": "55C06A30DAA5D5F382FDEB8C702EC57875CC9D91A7C78BB620053FD81DC4335C",
"uid2": "tMmiiTI7IaAcPpQPFQ65uMVCWH8av9jw4cwf/F5HVRQ=",
"uid2_token": "7be25cf9-8c40-5cc2-871e-19bf41940288MTKVpUAzwYAPnHrtfE0wlINOMzhU7UUEjjVdCdRu63k=uid_token=AgAAAAPFR0zA5ogv/yaAPiUsAdZPsfqS8QlDSGxAB+rr8yekFs3AjLYVk5qqqiyV2XHbSuwzHmxSlLeQeKQI1mp015jsNnpX5/xGgXldcgVz+gFnyh3T8/3agMwRmyrhCxG4oH2C7fc48AQk2eotE7FW0ZDEYM8fD9ZxDaxFUC/OV3OuZA&",
"apn": "AppName",
"apv": "1.0",
"uoo": "false"
},

// 3.2 Configure Payload: metadata
"metadata": {
"static": {}, // object for measuring static content
"content": { // object for measuring video content
"type": "content", // "content" for video
"assetid": "VIDEO-ID123", // unique ID for video
"isfullepisode": "y", // full episode flag
"program": "Program Name", // program name
"title": "Episode Title S3 - EP1", // episode name
"length": "1800", // content duration in seconds
"segB": "Custom Segment B", // custom segment
"segC": "Custom Segment C", // custom segment
"crossId1": "Standard Episode ID", // episode ID
"crossId2": "Content Originator ID", // content orginator (required for distributors)
"airdate": "20161013 20:00:00", // airdate
"adloadtype": "2" //ad load flag
"hasAds": "1", // content contains ads = 1 / no ads = 0
"progen": "CV" // program genre abbreviation
},
"ad": {
"type": "preroll", // type of ad
"assetid": "AD-ID123" // unique ID for ad
}
},

// 3.3 Configure Payload: events
"event": "playhead", //event name
"position": "300", // position in seconds
"type": "content", //"content" or "ad"
"utc": "1456448742000" //unix timestamp in milliseconds
}
</syntaxhighlight>

=====Configure Payload: devInfo=====
An object <code>"devInfo"</code> will need to be created to capture App and Device information.

{| class="wikitable"
|-
! Keys !! Description !! Values !! Required
|-
| devId || unique ID to identify user (e.g. Advertising ID, Roku Device ID) || custom || Yes
|-
| hem_sha256 || SHA-256 hashed email Note: email normalization rules applied before hashing || custom || Yes
|-
| uid2 || Trade Desk Unified ID 2.0 This should be the unencrypted, non-tokenized UID2.0 in the clear || custom || Yes
|-
| uid2_token ||Trade Desk Unified ID 2.0 UID2 token || custom || Yes
|-
| apn || app name || custom || Yes
|-
| apv || app build version || custom || Yes
|-
| uoo || device opt-out status || <code>"true"</code> or <code>"false"</code> || Yes
|-
|}

'''Example devInfo Object'''
<syntaxhighlight lang="javascript">
// create devInfo object
"devInfo": {
"devId": "AD-ID",
"hem_sha256": "55C06A30DAA5D5F382FDEB8C702EC57875CC9D91A7C78BB620053FD81DC4335C",
"uid2": "tMmiiTI7IaAcPpQPFQ65uMVCWH8av9jw4cwf/F5HVRQ=",
"uid2_token": "7be25cf9-8c40-5cc2-871e-19bf41940288MTKVpUAzwYAPnHrtfE0wlINOMzhU7UUEjjVdCdRu63k=uid_token=AgAAAAPFR0zA5ogv/yaAPiUsAdZPsfqS8QlDSGxAB+rr8yekFs3AjLYVk5qqqiyV2XHbSuwzHmxSlLeQeKQI1mp015jsNnpX5/xGgXldcgVz+gFnyh3T8/3agMwRmyrhCxG4oH2C7fc48AQk2eotE7FW0ZDEYM8fD9ZxDaxFUC/OV3OuZA&",
"apn": "AppName",
"apv": "1.0",
"uoo": "false"
},
</syntaxhighlight>

==== 3.2 Configure Payload: metadata ====
Asset metadata can be passed through <code>"metadata"</code>. There are two asset types: <code>"content"</code> for video and <code>"ad"</code> for ads. The metadata received for each asset is used for classification and reporting.

You will need to set up <code>"metadata"</code> objects for <code>"content"</code> and <code>"ad"</code> with the required Nielsen keys as shown in the sample code below.

===== Content Metadata =====
Content metadata should remain constant throughout the entirety of an episode/clip including when ads play.

{| class="wikitable"
|-
! Keys !! Description !! Values !! Required
|-
| type || type of asset || <code>"content"</code> || Yes
|-
| assetid || unique ID assigned to asset || custom <br>(no [[Special Characters]]) || Yes
|-
| program ||name of program (25 character limit) || custom || Yes
|-
| title ||name of program (25 character limit) || custom || Yes
|-
| length || length of content in seconds || <code>seconds</code> (0 for live stream) || Yes
|-
| segB || custom segment B || custom || No
|-
| segC || custom segment C || custom || No
|-
| airdate || the airdate in the linear TV || YYYYMMDD HH24:MI:SS || Yes
|-
| isfullepisode || full episode flag || <code>"y"</code>- full episode, <code>"n"</code>- non full episode || Yes
|-
| crossId1 || standard episode ID || custom || No
|-
| crossId2 || content originator (only required for distributors) || Nielsen || No
|-
| adloadtype || type of ad load:
<code>"1"</code> Linear – matches TV ad load

<code>"2"</code> Dynamic – Dynamic Ad Insertion (DAI)
|| <code>"2"</code> - DCR measures content with dynamic ads || Yes
|-
| hasAds || ads indicator
<code>"1"</code>: ads included

<code>"0"</code>: ads not included
|| <code>"1"</code> or <code>"0"</code> || Yes
|-
| subbrand || sub brand override || Nielsen || No
|-
| progen || program genre abbreviation - see [[DCR OTT Genre List]] for accepted values || <code>"CV"</code> for Comedy Variety || Yes
|}

'''Example Content Object'''
<syntaxhighlight lang='json'>// create content object
"content": {
"type": "content",
"assetid": "VIDEO-ID123",
"isfullepisode": "y",
"program": "Program Name",
"title": "Episode Title S3 - EP1",
"length": "1800",
"segB": "Custom Segment B",
"segC": "Custom Segment C",
"crossId1": "Standard Episode ID",
"crossId2": "Content Originator ID",
"airdate": "20161013 20:00:00",
"adloadtype": "2",
"hasAds": "1",
"subbrand": "c05",
"progen": "CV"
}</syntaxhighlight>

===== Ad Metadata =====
The ad metadata should be passed for each individual ad.

{| class="wikitable"
|-
! Keys !! Description !! Values !! Required
|-
| type || type of ad || <code>"preroll"</code>, <code>"midroll"</code>, or <code>"postroll"</code> || Yes
|-
| assetid || unique ID assigned to ad || custom || Yes
|}

===== Example Ad Object =====
<syntaxhighlight lang="javascript">
// create ad object
"ad": {
"type": "preroll",
"assetid": "AD-ID123"
}
</syntaxhighlight>

=== Configure Payload: Events ===

The last part of the payload is for enabling events so content is measured correctly when viewed. The events and required parameters are included below.

==== Event Types ====

The available events are:
{| class="wikitable"
|-
! Event !! Description
|-
| <code>"playhead"</code> || Playhead position in seconds, must be passed as a whole number every 10 seconds. The final playhead position should be sent before an asset has changed to properly capture full duration. When content is paused, stop passing playhead position until content is resumed. On playhead scrubbing, send current playhead position, followed by the playhead position the user scrubs to. For Live streams, you may use Unix Time (in seconds) as the playhead position. Note that ad playheads must also use Unix Time if Unix Time is used for content playheads.
|-
| <code>"complete"</code> || The complete event must be sent when the content has completed full playback. Before calling the complete event, a final playhead update with the final position is required to be sent to receive full duration credit. For Live streams, a complete event must be sent at program boundaries.
|-
| <code>"delete"</code> || The delete event is optional and can be sent when the viewing session is terminated (typically on App close). A new session ID must be generated after sending a delete event. Delete should not be sent on app interruptions or foreground/background events. All creditable duration will be summarized for all asset types when delete occurs (content and ads).
|}

===== Event Parameters =====

The following parameters need to be passed when calling events:

{| class="wikitable"
|-
! Parameter !! Description !! Value !! Required
|-
| <code>"event"</code> || event type || <code>"playhead"</code>, <code>"complete"</code>, or <code>"delete"</code> || Yes
|-
| <code>"position"</code> || playhead position in seconds or Unix time in seconds || <code>"300"</code> || Yes
|-
| <code>"type"</code> || asset type || <code>"content"</code>, <code>"ad"</code> || Yes
|-
| <code>"utc"</code> || Unix timestamp in milliseconds. Must be passed every 10 seconds. || <code>"1472760000000"</code> || Yes
|}

===== Example Event =====
You can call events by passing values in the required parameters:

<syntaxhighlight lang="javascript">
"devInfo": [deviceInfo],
"metadata": {
"static": [static metadata],
"content": [content metadata],
"ad": [ad metadata]
},
// Event Parameters
"event": [event], // event name
"position": [playheadPosition], //position in seconds
"type": [asset type], // values are "content" or "ad"
"utc": "1472760000000" //unix timestamp in milliseconds
}
</syntaxhighlight>

'''Note:''' The full payload including "devInfo" and "metadata" must be populated in each event request.

===== Sample Event Lifecycle =====
The sample event lifecycle can be used as a reference for identifying the order for calling events and values to pass.

<syntaxhighlight lang="javascript">
// Start of Session: session ID created when App is opened

// Preroll
Ad Playhead {"event": "playhead", "position": "0", "type": "ad", "utc": "1472760000000"}

// Content
Content Playhead {"event": "playhead", "position": "0", "type": "content", "utc": "1472760000000"}

// Midroll
Midroll Playhead {"event": "playhead", "position": "0", "type": "ad", "utc": "1472760000000"}

// Content resumes at 15 minutes
Content Playhead {"event": "playhead", "position": "900", "type": "content", "utc": "1472760000000"}

// Content completes at 30 minutes
Complete {"event": "complete", "position": "1800", "type": "content", "utc": "1472760000000"}

// Postroll
Ad Playhead {"event": "playhead", "position": "0", "type": "ad", "utc": "1472760000000"}

//End of Session: The delete event should be called when the App is exited. The values for position and type not required to be passed.
Delete { "event": "delete", "position": "", "type": "", "utc": "1472760000000"}
</syntaxhighlight>

'''Sample Event Lifecycle - Detailed Storyline'''
This detailed event sequence provides additional insight for the correct events to call when handling certain playback scenarios.
<syntaxhighlight lang='javascript'>// SESSION STARTS
// Start of Session: session ID created when App is opened

// PREROLL
// Preroll Start - Start each Ad with a position of "0", resetting to '0' for each Ad, and Ad break.
Ad Playhead {"event": "playhead", "position": "0", "type": "ad", "utc": "1472760000000"}

// Preroll Stop - End each Ad with the final position of the Ad.
Ad Playhead {"event": "playhead", "position": "15", "type": "ad", "utc": "1472761500000"}

// CONTENT
// Content Start - Start new content streams with a position of "0" incrementing the position every 10 seconds.
Content Playhead {"event": "playhead", "position": "0", "type": "content", "utc": "1472761500000"}

// Content Stop Before Ad Break - Send a playhead update including the current content positon before an Ad break.
Content Playhead {"event": "playhead", "position": "299", "type": "content", "utc": "1472787400000"}

// MIDROLL
// Midroll Start - Start each Ad with a position of "0", resetting to '0' for each Ad, and Ad break.
Midroll Playhead {"event": "playhead", "position": "0", "type": "ad", "utc": "1472787500000"}

// Midroll Stop - End each Ad with the final position of the Ad.
Ad Playhead {"event": "playhead", "position": "60", "type": "ad", "utc": "1472793500000"}

// CONTENT
// Content resumes at 5 minutes - Send playhead update with the current resumed position, and begin incrimenting the positon every 10 seconds.
Content Playhead {"event": "playhead", "position": "300", "type": "content", "utc": "1472799500000"}

// Content completes at 10:12 - Make sure to send in the playhead event with the final content position before sending the complete event.
Final Content Playhead {"event": "playhead", "position": "612", "type": "content", "utc": "1472830700000"}

Complete {"event": "complete", "position": "612", "type": "content", "utc": "1472830800000"}

// POSTROLL
// Postroll Start - Start each Ad with a position of "0", resetting to '0' for each Ad, and Ad break.
Ad Playhead {"event": "playhead", "position": "0", "type": "ad", "utc": "1472830900000"}

// Postroll Stop - End each Ad with the final position of the Ad.
Ad Playhead {"event": "playhead", "position": "45", "type": "ad", "utc": "1472835300000"}

// SESSION ENDS

//End of Session: The delete event should be called when the App is exited. The values for position and type not required to be passed.
Delete { "event": "delete", "position": "", "type": "", "utc": "1472835400000"} </syntaxhighlight>

=====Handling Playhead=====
Calling <code>"playhead"</code> is critical for accurate duration crediting. You can reference the below guidance to determine the correct playhead position to pass depending on the playback scenario.

'''Playhead: General'''
* Playhead position must start at 0 for each new asset, and be passed at least every 10 seconds.
* Final postion must be sent at the end of content or an ad
* Playheads should be sent in seconds only, not milliseconds

'''Playhead: Ads'''
* The final position must be sent when switching from content to ad, or ad to content.
* Each ad playhead position should be 0 at ad start.
* For Ad Pods, playhead must be called, and reset to 0 for each individual ad.
* The last content position before an Ad should be sent before switching to Ads.
* When content has resumed following an ad break, the playhead position update must continue where the previous content segment left off.

'''Playhead: User Actions'''
* Upon user scrubbing, the current position must be sent before a user scrubs, and the new position should be sent where the user lands, and begin sending in the 10 second updates thereafter.
* On pause, send the current position and then discontinue sending playhead event updates.
* If a user exits a stream early, the last current position must be sent in a playhead update to receive accurate duration.

===== Interruption Scenarios =====

As part of configuring events, you will need to handle all possible interruption scenarios such as:

*Wi-Fi OFF / ON
*App going Background / Foreground (Video players only, not for Audio players)
*App Crash or Exit

When playback is interrupted, the app needs to send delete immediately.

Once playback resumes, a new session will need to be created with a unique session ID. All of the required metadata and events will need to be sent.

'''Note:''' The session will automatically timeout after 30 minutes of inactivity.

=== Example Request ===

Now that we walked through the Cloud API integration steps, your requests should have the following components: Session ID, App ID, and Payload. You can reference the example below when your reviewing your integration.

<syntaxhighlight lang="javascript">
// 1. Create Session ID
sessionID = dfc7dc6a-66a7-4705-9fba-adaaf7e3d5e0 // Example sessionID created using a UUID Generator

// 2. Define URL Structure with App ID and Session ID
sessionURL = https://sandbox2-cloudapi.imrworldwide.com/nmapi/v2/[appid]/[sessionID]/a?b=

// 3. Configure Payload
// 3.1 Configure Payload: devInfo
payload = {
"devInfo": {
"devId": "AD-ID",
"apn": "AppName",
"apv": "1.0",
"uoo": "false"
},

// 3.2 Configure Payload: metadata
"metadata": {
"static": {}, // object for measuring static content
"content": { // object for measuring video content
"type": "content", // "content" for video
"assetid": "VIDEO-ID123", // unique ID for video
"isfullepisode": "y", // full episode flag
"program": "Program Name", // program name
"title": "Episode Title S3 - EP1", // episode name
"length": "1800", // content duration in seconds
"segB": "Custom Segment B", // custom segment
"segC": "Custom Segment C", // custom segment
"crossId1": "Standard Episode ID", // episode ID
"crossId2": "Content Originator ID", // content orginator (required for distributors)
"airdate": "20161013 20:00:00", // airdate
"adloadtype": "2", // ad load flag
"hasAds": "1", // content contains ads = 1 / no ads = 0
"progen": "CV" // program genre abbreviation
},
"ad": {
"type": "preroll", // type of ad
"assetid": "AD-ID123" // unique ID for ad
}
},

// 3.3 Configure Payload: events
"event": "playhead", //event name
"position": "300", // position in seconds
"type": "content", //"content" or "ad"
"utc": "1456448742000" //unix timestamp in milliseconds
}

// Append payload to URL
var image = new Image()
image.onerror = function() {
// wait and send again
}
(new Image).src = sessionURL+encodeURIComponent(JSON.stringify(payload));
</syntaxhighlight>

To ensure that the GET request does not receive a CORS issue, make sure to use the IMAGE request in conjunction with the content-type "text/plain" so CORS preflight is not triggered, causing the request to be rejected.

==== Enable Debug Logging ====

Now that you have set up the Cloud API requests, you can enable debug logging to validate your integration. Enabling debug logging is required for Nielsen certification.

==== GET Request ====

Display GET Request to console using a name to identify each event (e.g. playhead).

<syntaxhighlight lang="javascript">
console.log("Event", image);
</syntaxhighlight>

==== Payload ====

Output payload to identify required metadata and events.

<syntaxhighlight lang="javascript">
console.log("Event Payload", payload);
</syntaxhighlight>

==== HTTPS Response Code ====

Confirm request was completed by viewing HTTPS response code.

<syntaxhighlight lang="javascript">
code = msg.GetResponseCode();
console.log("Response Code", code);
</syntaxhighlight>

You can reference the HTTPS Response Code table when reviewing your requests:

{| class="wikitable"
|-
! Status Code !! Status Text !! Description
|-
| <code>200</code> || OK || request received
|-
| <code>403</code> || Forbidden || invalid App ID
|-
| <code>404</code> || Not Found || JSON issue
|}

== Opt-Out ==
Your app must provide a means for the user to Opt-Out, or Opt-In to Nielsen Measurement. This requirement can be fulfilled by checking the device OS for the user's setting of "Limit Ad Tracking" or similar option. If the device offers "Limit Ad Tracking" settings, you should set <code>uoo=true</code> or <code>uoo=false</code> depending on the user's privacy setting. Also, ensure that the <code>devId</code> is set to a blank value if the user elects to opt-out.

If the device does not have OS-level "Do Not Track" settings, you can implement opt-out by creating an Opt-Out/Opt-In button, toggle switch, or slider within the app "Settings", or "About" section to allow the user selection.

[[File:Nielsen Opt-Out.png|link=]]

You will need to store the User Opt-Out (uoo) status, so that it can be retrieved and populated in the <code>"devInfo"</code> metadata which will be sent in every Cloud API event (playhead, complete, & delete).

{| class="wikitable"
|-
! uoo Key !! Description !! Values
|-
| uoo || Device is Opted-In to Nielsen Measurement (Recommended Default Setting) || <code>"false"</code>
|-
| uoo || Device is Opted-Out of Nielsen Measurement || <code>"true"</code>
|}

===== devInfo Opt-In JSON Payload Example =====

<syntaxhighlight lang="javascript">
"devInfo": {
"apn": "Cloud API Sample App",
"apv": "1",
"devId": "7be25cf9-8c40-5cc2-871e-19bf41940288",
"uoo": "false"
},
</syntaxhighlight>

===== devInfo Opt-Out JSON Payload Example =====

<syntaxhighlight lang="javascript">
"devInfo": {
"apn": "Cloud API Sample App",
"apv": "1",
"devId": "", //devId must be blank when a user elects to Opt-Out.
"uoo": "true"
},
</syntaxhighlight>

===== Privacy Information Template To Include In Opt-Out Screen =====

Additionally, all applications must display the Nielsen privacy policy within their application, typically in the Settings/About screen of your application. The Nielsen privacy policy text is listed below.

<blockquote>
'''''ABOUT NIELSEN MEASUREMENT'''''

Television and the way we watch it have come a long way since Nielsen began measuring TV audiences in 1950. Today, the ability to watch our favorite shows at any time and on multiple devices amplifies the need for exceptionally adept and flexible audience measurement capabilities.

Consumers are changing with the times, and the same goes for us. As technology continues to evolve and media companies try new ways to attract viewers, understanding what consumers are watching — and what they're watching on — is more important than ever. Today, viewing video is a personal and mobile experience — anytime and anywhere. Our capabilities provide relevant metrics that are necessary to inform successful marketing and programming and drive continued growth. As a global information and measurement leader, we are committed to protecting the privacy and security of the data we collect, process and use. While our digital measurement products are not used to identify you in any way, they help us and our clients measure and analyze how consumers engage with media across online, mobile and emerging technologies, and offer insights into consumer behavior.

'''''YOUR CHOICES'''''

Nielsen believes that you should have a choice about whether to contribute to our research and insights. To opt out or opt in to Nielsen measurement, please toggle your "Limit Ad Tracking" (or similar setting) on your device, or make the appropriate selection within the application's settings. If you have this app on more than one device, you will need to opt out of this app on each device. To learn more about our digital measurement products and your choices in regard to them, please visit https://www.nielsen.com/digitalprivacy.

</blockquote>

== Testing ==
Before providing an app build to Nielsen for testing, it is important to run validation checks once you have enabled debug logging.

=== Payload Validation ===

Ensure that all of the required payload data is populating while testing several videos. The following areas are critical to measurement:
*devInfo
*Asset metadata for both content, and ads
*Events
*Opt-Out status

=== Player Events ===
Review event calls:

==== playhead ====
*Playhead position updates every 10 seconds starting at position '0' for each new asset.
*Final playhead position is sent on content, or ad before switching between assets.
*Content metadata remains constant throughout an episode, or clip play.
*Ad metadata is populated appropriately for each individual ad.
*Playhead position update resumes for content after an ad break, and resets to 0 for each individual ad.
*For scrubbing, last current position should be sent while scrubbing occurs, and the new position should also be sent where the user scrubs to.
*Exiting a stream early should execute the last current position in a playhead update to receive accurate duration.
*Upon pause, the current position should be sent, and playhead updates should stop incrementing until resume play occurs.

==== complete ====
*Check that the complete event executes upon content complete after the final playhead update is sent
*Do not execute the complete event for ads

==== delete ====
*Check to see that the delete event occurs upon app exit, if the platform has the necessary exit callback events.

==== GET Request Format ====
*Ensure that the event payloads are formatted in JSON
*Check to see that each of the Cloud API GET requests are properly encoded

==== HTTPS Response ====
*Make sure that each of the Cloud API Get requests are received by the Nielsen Cloud API properly through use of the HTTPS Response Code outputs enabled in console.

==== Opt-Out ====
*Test the "uoo" key gets populated accurately for both Opt-In and Opt-Out selections by validating the Cloud API events called after the user Opt-Out/Opt-In selection.
*Test that the devId field is populated with a blank value if a user has elected to Opt-Out. For example: "devId": "",
*If the device supports "Limit Ad Tracking" or has device "Opt-Out" settings, test that uoo=true, and that devId is set to a blank value if enabled in the device settings.

== Go Live ==
After your integration has been certified, you will need to: Change Endpoint and Disable Logging.

'''Change Endpoint:''' You will need to update to the production endpoint:

*Testing: <code>https://sandbox2-cloudapi.imrworldwide.com/nmapi/v2/</code>
*Production: <code>https://cloudapi.imrworldwide.com/nmapi/v2/</code>

Your production URL structure should now be:
<code>https://cloudapi.imrworldwide.com/nmapi/v2/[appid]/[sessionID]/a?b=[payload]</code>

'''Disable Logging:''' You can now disable debug logging

Browser SDK API Reference

2024-12-11T20:17:13Z

AmySockanathan: /* Multiple SDK Instances */

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

== Setting up Development Environment ==
=== Step 1: Configure Content Management System (CMS) ===
Configure CMS to send the required values (see table below). Any internal CMS_variable names can be used for passing the data.

Ensure to capture these CMS_variable names in the SDK Configuration Form.

For more information on setting variable names, see the SDK Configuration Form included within the SDK package.

{| class="wikitable"
|-
! Required Data !! Description !! Value
|-
| dataSrc || Used when both CMS metadata and ID3 data are present in the player. Setting this field tells the SDK whether to use the CMS metadata or the ID3 payload to derive the pings || cms
|-
| type || Type of asset: ad or content || preroll, midroll, postroll, or content
|-
| assetid || unique ID assigned to asset || custom <br>(no [[Special Characters]])
|-
| OCR Tag || OCR tag provided by Nielsen for implementation on the ad unit || Complete OCR URL
|-
| program || Name of program (25 character limit) || custom
|-
| title || Episode title (40 character limit) || custom
|-
| length || Length of content in seconds || Length in seconds, 0 for live stream
|-
| adloadtype || Type of ad load || "1" - Linear "2" - Dynamic(default)
|-
| hasAds || Identify if content includes Ads || "0" - no ads "1" - includes ads "2" - unknown(default)
|-
| isfullepisode || Full episode flag || "y" - full episode "n" - non full episode
|-
| segA || Segment A (this is not available for video reporting as the episode title is reported) || custom value
|-
| segB || Custom segment B || custom value
|-
| segC || Custom segment C || custom value
|-
| crossId1 || Standard episode ID || custom value
|-
| crossId2 || Content originator (required only for distributors) || custom value
|-
| airdate || Original air date and time in Eastern Time. For non-US countries, it should be local time. || YYYYMMDD HH24:MI:SS
|-
| containerId || HTML DOM element of the Player container (for Viewability&Audibility feature only) || custom value
|-
|luid
|Living Unit ID - Experian Household ID
'''Note: This parameter is applicable only for CTV and First Party Livestream data'''
|"B0EOFEDgD"
|}

=== Step 2: Complete the Nielsen SDK Configuration Form ===
The SDK is designed to map the <code>CMS_variable names</code>. To support the custom mapping, the developer is required to complete the SDK Configuration Form. The form will be provided during onboarding along with this guide.

== Initialization ==
=== Obtain the Nielsen Application ID (apid) and Browser SDK URLs ===
The Nielsen <code>apid</code> 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 Browser SDK ===
There are two steps required for configuring the SDK:

'''Add Static Queue Snippet'''

*Add Static Queue Snippet
*Create SDK Instance

Add the following script tag to the website:
<syntaxhighlight lang="javascript">

<script type="text/javascript">
!function(t,n)
{
t[n]=t[n]||
{
nlsQ:function(e,o,c,r,s,i)
{
return s=t.document,
r=s.createElement("script"),
r.async=1,
r.src=("http:"===t.location.protocol?"http:":"https:")+"//cdn-gl.imrworldwide.com/conf/"+e+".js#name="+o+"&ns="+n,
i=s.getElementsByTagName("script")[0],
i.parentNode.insertBefore(r,i),
t[n][o]=t[n][o]||{g:c||{},
ggPM:function(e,c,r,s,i){(t[n][o].q=t[n][o].q||[]).push([e,c,r,s,i])}},t[n][o]
}
}
}
(window,"NOLBUNDLE");
</script>

</syntaxhighlight>

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.

'''Create SDK Instance'''

To initialize the SDK, create an SDK instance by making the initialization call:

'''Initialization API Call'''
<syntaxhighlight lang="javascript">

NOLBUNDLE.nlsQ("<apid>", "<instanceName>",{nol_sdkDebug: "debug"})

</syntaxhighlight>

When creating an instance, pass the following three values:

=== SDK Initialization – Global Parameters <span class="anchor" id="SDK Initialization Global Parameters"></span> ===
{| class="wikitable"
|-
! Parameters !! Description !! Value
|-
| apid || UniqueID assigned to player/site. || 'XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX'
|-
| instanceName || Name of SDK instance || "any string value"
|-
| nol_sdkDebug || Enables Nielsen console logging. Only required for testing || "{nol_sdkDebug: "debug"})"
|-
| containerId || HTML DOM element id of the player container. Only for Viewability & Audibility feature. || {containerId: "playerId1"}
|-
| 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&"
|}

{{example_bsdk_init}}

'''Example SDK Configuration'''

The configuration should include the Static Queue Snippet and an SDK Instance for an unique App ID as shown in the example:

<syntaxhighlight lang="javascript">

<script type="text/javascript">
!function(t,n)
{
t[n]=t[n]||
{
nlsQ:function(e,o,c,r,s,i)
{
return s=t.document,
r=s.createElement("script"),
r.async=1,
r.src=("http:"===t.location.protocol?"http:":"https:")+"//cdn-gl.imrworldwide.com/conf/"+e+".js#name="+o+"&ns="+n,
i=s.getElementsByTagName("script")[0],
i.parentNode.insertBefore(r,i),
t[n][o]=t[n][o]||{g:c||{},
ggPM:function(e,c,r,s,i){(t[n][o].q=t[n][o].q||[]).push([e,c,r,s,i])}},t[n][o]
}
}
}
(window,"NOLBUNDLE");
// Created SDK Instance
var nSdkInstance = NOLBUNDLE.nlsQ("XXXXXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXX","nlsnInstance", {nol_sdkDebug: "debug"});
</script>

</syntaxhighlight>

=== Multiple SDK Instances ===
The Browser SDK allows instantiating multiple instances of the object, which can be used simultaneously without any problems, however they must be instantiated with their own unique instance names. There is no maximum number of instances that is enforced in the browser.

The below examples will make use of the same AppId, however using different AppIds will work as well. The principles below follow the same initialization rules stated above for a single instance and simply require a unique instance name and variable name with which the returned instance is assigned.

For more information around the possible parameters that can be passed as well as deeper descriptions for the API calls, please refer to the section on [[#SDK Initialization Global Parameters|'''SDK Initialization - Global Parameters''']].

'''Example of 2 instances on the same page'''

<syntaxhighlight lang="javascript">
//Add Static Queue Snippet
<script>
!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.imrworldwide.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");

//Create SDK Instance(s)
// Notice the unique instance name given to each instance below and the unique variable name for each instance
var nSdkInstanceLive = NOLBUNDLE.nlsQ("XXXXXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXX", "instanceLive", {
nol_sdkDebug: 'debug',
optout: 'false'
});

var nSdkInstanceVod = NOLBUNDLE.nlsQ("XXXXXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXX", "instanceVod", {
nol_sdkDebug: 'debug',
optout: 'false'
});

</script>
</syntaxhighlight>

'''Example of 2 instances using a parent page and iFrame'''

<big>Parent Page (index.html)</big>

<syntaxhighlight lang="javascript">
<!DOCTYPE html>
<html lang="en">

<head>
<meta charset="UTF-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<meta http-equiv="X-UA-Compatible" content="ie=edge">
<title>DCR Static/DCR Video</title>
<script>
/* NLSQUEUE build v*/
!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.imrworldwide.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");

// SDK Initialization
var nSdkInstance = NOLBUNDLE.nlsQ("XXXXXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXX", "staticPage", {
nol_sdkDebug: 'debug',
});

// Static Metadata
var staticMetadata = {
assetid: 'staticTestPage',
type: 'static'
};

// Event 'staticstart' call
nSdkInstance.ggPM(14, staticMetadata);
</script>
</head>

<body>
<h1>DCR Static on Parent/DCR Video in iFrame</h1>
<p>Static measurement is current on parent page when window is in focus</p>
<iframe src="./dcr-video.html" frameborder="0" width="650" height="500" style="background-color: rgb(42, 217, 248);" id="video-iframe"></iframe>
</body>

</html>
</syntaxhighlight>

<big>Nested iFrame Referenced on Parent Page (dcr-video.html)</big>

<syntaxhighlight lang="javascript">
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
<meta http-equiv="X-UA-Compatible" content="ie=edge" />
<title>iFrame Same Source</title>
<script>
/* NLSQUEUE build v*/
!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.imrworldwide.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");

// SDK Initialization
var nSdkInstance = NOLBUNDLE.nlsQ("XXXXXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXX", "videoPlayer", {
nol_sdkDebug: 'debug',
});

var contentMetadata = {
type: "content",
length: "300",
title: "Skydiving Across Europe",
program: "latacg",
censuscategory: "Enlisted",
assetid: "204558915992",
section: "ProgramAsset8",
tv: "true",
adModel: "0",
dataSrc: "cms",
segA: "S07E04:NBC",
segB: "teams",
segC:"AtlanataFalcons",
}
</script>
</head>
<body>
<p>I'm iframe SDK DCR Video measurement, DCR static measurement should continue when clicking "play" on video</p>
<main>
<video
controls
src="https://archive.org/download/BigBuckBunny_124/Content/big_buck_bunny_720p_surround.mp4"
poster="https://peach.blender.org/wp-content/uploads/title_anouncement.jpg?x11217"
width="620">
Sorry, your browser doesn't support embedded videos, but don't worry, you can
<a href="https://archive.org/details/BigBuckBunny_124">download it</a>
and watch it with your favorite video player!
</video>
</main>
<script src="../player.js"></script>
</body>
</html>

</syntaxhighlight>

=== SDK Initialization to measure the Viewability & Audibility ===
To support viewability metrics in the web page the integrator has to provide a tag value of the player view to let Nielsen SDK know that there is a player that needs to be tracked. It’s called the ‘containerId’ and it should be passed in the as string while initializing the Nielsen browser SDK.

NOLBUNDLE.nlsQ("<apid>", "<instanceName>",{containerId: <playerElementID>, nol_sdkDebug: "debug"})

'''Example SDK Initialization for Viewability'''

Your configuration should include the Static Queue Snippet and an SDK Instance for your unique App ID as shown in the example:
<syntaxhighlight lang="javascript">
//Add Static Queue Snippet
<script>
! function(t, n) {
t[n] = t[n] || {
nlsQ: function(e, o, c, r, s, i) {
return s = t.document,
r = s.createElement("script"),
r.async = 1,
r.src = ("http:" === t.location.protocol ? "http:" : "https:") + "//cdn-gl.imrworldwide.com/conf/" + e + ".js#name=" + o + "&ns=" + n,
i = s.getElementsByTagName("script")[0],
i.parentNode.insertBefore(r, i),
t[n][o] = t[n][o] || {
g: c || {},
ggPM: function(e, c, r, s, i) {
(t[n][o].q = t[n][o].q || []).push([e, c, r, s, i])
}
}, t[n][o]
}
}
}
(window, "NOLBUNDLE");

//Create SDK Instance
var nSdkInstance = NOLBUNDLE.nlsQ("XXXXXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXX", "nlsnInstance", {containerId: “player1”, nol_sdkDebug: "debug"});
</script>

</syntaxhighlight>

== Browser SDK API Methods & Properties ==
{| class="wikitable sortable"
|-
! Method / Property !! Event # !! DTVR !! DAR !! DCR !! Description
|-
| [[loadMetadata (Browser)|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.
|-
| [[play (Browser)|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”.
|-
| [[sendID3 (Browser)|sendID3]] || 55 || ✔ || ✘ || ✘ || Used to send the ID3 metadata.
|-
| [[setPlayheadPosition (Browser)|setPlayheadPosition]] || 49 || ✘ || ✘ || ✔ || Used to send the playhead position.
|-
| [[stop (Browser)|stop]] || 7 || ✘ || ✘ || ✔ || Used when switching between ad and content or content and ad.
|-
| [[end (Browser)|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
|-
| [[staticstart (Browser)|staticstart]] || 14 || ✘ || ✘ || ✔ || Used to send the metadata for the static page.
|-
| [[StaticEnd (Browser)|staticend]] || 56 || ✘ || ✘ || ✔ || In Single Page Application (SPA) it is imperative that staticend is called prior to the loading of new metadata. This allows the Browser SDK to properly credit the previous section/content being viewed before measuring the new one.
|-
| [[updateOTT (Browser)|updateOTT]] || - || ✘ || ✘ || ✔ || Used to notify Browser SDK that the remote OTT device (like Google ChromeCast, Roku, Amazon FireTV, etc.) is connected / disconnected (change of OTT status).
|-
| [[ onPaginate (Browser)|onPaginate]] || 30 || ✘ || ✘ || ✔ || Used to create a new instance of the SDK object
|-
| [[updateMetadata (Browser)|updateMetadata]] || 35 || ✔ || ✔ || ✔ || This event is used for updating metadata parameters for the content or ad that is being played.
|-
| [[setVolume_(Browser)|setVolume]] || 61 || ✔ || ✘ || ✔ || Used to pass in the player volume levels in %. Default value is -1.
|}

== Retrieving ID3 Tags ==
The video player must have the ability to extract ID3 tags and supply them to the Browser SDK, based on the HLS standard.
*An ID3 tag spans two PES packets.
**In the first PES packet, look for www.nielsen.com, this is the start of the ID3 tag. Continue to parse the first PES packet until the undefined char "\ufffd" is found. This forms the first half of the ID3 tag
**In the second PES packet, identify the end pattern – a regEx of /(\/\d+){3}/ and look to remove the lowest index of either "\x00" and/or "\ufffd". Now the second packet has been appended and the demarcation of the Nielsen-specific data has been defined.

Follow the procedure below, to extract Nielsen ID3 tags from an MPEG-2 transport stream (including HLS streams).
#Parse the Program Map Table (PMT) to find the PID of the metadata stream. Confirm the presence of the metadata descriptor described in section 2.3.3 of Apple’s “HTTP Live Streaming Metadata Spec.pdf”. Only private streams with metadata descriptor present should be considered as ID3-tag metadata streams.
#Parse the HLS/Transport stream for any '''PES header''' with the PID found in step 1.
#Follow standard MPEG-2 parsing procedures to locate the start of the payload of the PES packet.
#Copy the PES payload into a buffer.
#The ID3 tag spans 2 PES packets. Parse the stream for the next packet whose PID is set to the PID found in step 1. Typically the ID3 Tag is of 249 bytes. The steps below guide towards extraction of the ID3 tag
##In the first PES packet, look for "www.nielsen.com" , this is the start of the ID3 tag. Keep on parsing the first PES packet until the undefined char "\ufffd" is found. This forms the first half of the ID3 tag
##In the second PES packet, identify the end pattern, a regEx of /(\/\d+){3}/ and look to remove the lowest index of either “\x00” and/or “\ufffd”. Now the second packet has been appended and the demarcation of the Nielsen specific data has been defined. This segment can be simply substringed.
##Concatenate this substringed segment with the payload derived from the first packet get the ID3 payload.
#Check the length of the contents in the buffer to make sure that it is equal to the size of a Nielsen ID3 tag.
#Ensure that the ID3 byte array is converted into the string and escape it, so that the SDK can consume it.
Repeat steps 2 through 7 for all ID3 tags in the stream.

'''References'''
*[http://www.iso.org/iso/catalogue_detail?csnumber=44169. ISO/IEC 13818-1:2007] Information technology – Generic coding of moving pictures and associated audio information: Systems
*https://developer.apple.com/library/content/documentation/AudioVideo/Conceptual/HTTP_Live_Streaming_Metadata_Spec/

=== Sample ID3 tags ===
* <code>www.nielsen.com/X100zdCIGeIlgZnkYj6UvQ==/X100zdCIGeIlgZnkYj6UvQ==/AAAB2Jz2_k74GXSzx4npHuI_<wbr />JwJd3QSUpW30rDkGTcbHEzIMWleCzM-uvNOP9fzJcQMWQLJqzXMCAxParOb5sGijSV9dNM3QiBniJYGZ5GI-lL1fXTTN0IgZ4iWBmeRiPpS9AAAAAAAAAAAAAAAAAAAAAFJWFM5SVhTONNU=/00000/00000/00</code>
* <code>www.nielsen.com/X100zdCIGeIlgZnkYj6UvQ==/R8WHe7pEBeqBhu8jTeXydg==/AAICoyitYqlxT7n6aZ0oMCGhe<wbr />Fi4CXFp46AMUPZz1lMr_M9tr3_cjee1SHqxrOiVerMDLeyn9xzocZSKwi746Re8vNOtpNCAZjYABs_J0R25IHpvOc1HS8<wbr />QHGgD5TgOJeS6gX100zdCIGeIlgZnkYj6UvVJWFNhSVhTiPE0=/00000/46016/00</code>
<blockquote>'''Note''': ID3 tags are not applicable for International (Germany)</blockquote>

== Browser Opt-Out Implementation ==
The site in which video content is being measure via Nielsen methodology must provide the means for the user to opt-out of, or opt back into Nielsen Measurement.

For Browser-based applications, opt-out setting is stored via Nielsen cookie. Therefore, it is only necessary that users be made aware of measurement opt-out by incorporating the template below in the user interface.

=== Sample Opt Out Template ===
Our properties may feature Nielsen’s proprietary measurement software which will allow to contribute to market research, like Nielsen’s TV Ratings. To learn more about this information, see https://www.nielsen.com/digitalprivacy. Nielsen’s software may collect your choices with regards to it.

== Nielsen Privacy Requirements ==
Privacy protections that Nielsen ensures to have with each App SDK integration are as follows.
*Disclosure of viewership data collection in EULA / Privacy Policy
*A link in the EULA/Privacy policy, or in another conspicuous location within the App, to a Nielsen-hosted web page outlining what Nielsen is collecting and how it is being used
*Method for users to opt-out of Nielsen measurement, any time while using the application

=== Ratings Data Flow ===
Every view of creditable and watermarked content is measured by Nielsen.
[[File:RatingsDataFlow.png]]

'''Information NOT Shared'''
* '''With Nielsen'''
** User's Identity
* '''With Data Provider'''
** Content information
** Whether user is viewing an ad or video content
** Player used to play the streaming (audio / video, etc.)
** Values being de-duped / aggregating for

Nielsen collects only what it needs for audience measurement. Every view of creditable, watermarked content will be measured by Nielsen.

=== Data Collected ===
{| class="wikitable"
|-
! Type of Information !! Parameter !! Transmitted to Nielsen? !! Sent to Provider?
|-
| rowspan="8" | Nielsen ID3 Watermark
|-
| FinalDistributor Timestamp || Yes || No
|-
| Program Content Timestamp || Yes || No
|-
| Mobile Breakout Code || Yes || No
|-
| Commercial Credit Code – Linear or Dynamic || Yes || No
|-
| Time ShiftedViewing Code || Yes || No
|-
| Segment Number || Yes || No
|-
| Segment View Pattern || Yes || No
|-
| rowspan="7" | Device/App Info
|-
| Device OSVersion || Yes || Yes
|-
| Device Model || Yes || No
|-
| Cache Buster || Yes || Yes
|-
| SDKDisabled Flag || Yes || No
|-
| ServerCode || Yes || No
|-
| Channel or URL || Yes || No
|-
| rowspan="9" | Nielsen Identifiers
|-
| Client ID || Yes || No
|-
| Campaign ID || Yes || Yes
|-
| Nielsen Unique Device ID || Yes || No
|-
| Application ID || Yes || No
|-
| DeviceGroup (ex. Tablet, Smartphone, Desktop) || Yes || Yes
|-
| OS Group (ex. Android, iOS, Windows) || Yes || Yes
|-
| SDKVersion || Yes || No
|-
| IP Address for DMA, Country Code || Yes || Yes
|}
<blockquote>'''Note''': Data is hashed, and encrypted using AES 128 before transmission to data provider.</blockquote>

{{Viewability_Data_Collected}}

==== Example ping sent to provider ====
* <code><nowiki>https://provider.com/cgi-bin/brandlift.php</nowiki>?campaign_id=ff12725d724fac7934cf6003f096b4cd<wbr />&placement_id=a4164b8fba9ee7c873a9c72c7091bb58<wbr />&creative_id=25280139b61a947e127a52f56c8a2fdd<wbr />&segment1=9000<wbr />&segment2=41<wbr />&segment3=iOS<wbr />&OSVer=iOS6.1<wbr />&c9=<wbr />&devgrp=tablet<wbr />&h=f5f243fe6d<wbr />&rnd=1376971827360</code>

This ping passes the following parameters to the provider:
* Campaign ID – (campaign, placement, creative)
* Country Code
* DMA
* OS Group (ex. iOS, Android)
* DeviceOS Version
* Device Advertiser ID
* DeviceGroup (ex. Tablet, Smartphone, Desktop)
* Cache Buster

{{Template:Browser_Privacy_and_Opt-Out}}

=== Opt-Out Implementation ===
The site must provide the means for the user to opt-out of, or opt back into Nielsen Measurement.

'''Sample Opt Out Template'''

Our properties may feature Nielsen’s proprietary measurement software which will allow to contribute to market research, like Nielsen’s TV Ratings. To learn more about this information, please [http://priv-policy.imrworldwide.com/priv/mobile/us/en/optout.html| click here]. Nielsen’s software may collect your choices with regards to it.

== Testing ==
See [[Digital Measurement Testing#Testing Browser Implementation|Digital Measurement Testing - Testing Browser Implementation]].

Browser SDK API Reference

2024-12-11T20:15:57Z

AmySockanathan: Add Anchor name for SDK Initiailization Global Parameters

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

== Setting up Development Environment ==
=== Step 1: Configure Content Management System (CMS) ===
Configure CMS to send the required values (see table below). Any internal CMS_variable names can be used for passing the data.

Ensure to capture these CMS_variable names in the SDK Configuration Form.

For more information on setting variable names, see the SDK Configuration Form included within the SDK package.

{| class="wikitable"
|-
! Required Data !! Description !! Value
|-
| dataSrc || Used when both CMS metadata and ID3 data are present in the player. Setting this field tells the SDK whether to use the CMS metadata or the ID3 payload to derive the pings || cms
|-
| type || Type of asset: ad or content || preroll, midroll, postroll, or content
|-
| assetid || unique ID assigned to asset || custom <br>(no [[Special Characters]])
|-
| OCR Tag || OCR tag provided by Nielsen for implementation on the ad unit || Complete OCR URL
|-
| program || Name of program (25 character limit) || custom
|-
| title || Episode title (40 character limit) || custom
|-
| length || Length of content in seconds || Length in seconds, 0 for live stream
|-
| adloadtype || Type of ad load || "1" - Linear "2" - Dynamic(default)
|-
| hasAds || Identify if content includes Ads || "0" - no ads "1" - includes ads "2" - unknown(default)
|-
| isfullepisode || Full episode flag || "y" - full episode "n" - non full episode
|-
| segA || Segment A (this is not available for video reporting as the episode title is reported) || custom value
|-
| segB || Custom segment B || custom value
|-
| segC || Custom segment C || custom value
|-
| crossId1 || Standard episode ID || custom value
|-
| crossId2 || Content originator (required only for distributors) || custom value
|-
| airdate || Original air date and time in Eastern Time. For non-US countries, it should be local time. || YYYYMMDD HH24:MI:SS
|-
| containerId || HTML DOM element of the Player container (for Viewability&Audibility feature only) || custom value
|-
|luid
|Living Unit ID - Experian Household ID
'''Note: This parameter is applicable only for CTV and First Party Livestream data'''
|"B0EOFEDgD"
|}

=== Step 2: Complete the Nielsen SDK Configuration Form ===
The SDK is designed to map the <code>CMS_variable names</code>. To support the custom mapping, the developer is required to complete the SDK Configuration Form. The form will be provided during onboarding along with this guide.

== Initialization ==
=== Obtain the Nielsen Application ID (apid) and Browser SDK URLs ===
The Nielsen <code>apid</code> 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 Browser SDK ===
There are two steps required for configuring the SDK:

'''Add Static Queue Snippet'''

*Add Static Queue Snippet
*Create SDK Instance

Add the following script tag to the website:
<syntaxhighlight lang="javascript">

<script type="text/javascript">
!function(t,n)
{
t[n]=t[n]||
{
nlsQ:function(e,o,c,r,s,i)
{
return s=t.document,
r=s.createElement("script"),
r.async=1,
r.src=("http:"===t.location.protocol?"http:":"https:")+"//cdn-gl.imrworldwide.com/conf/"+e+".js#name="+o+"&ns="+n,
i=s.getElementsByTagName("script")[0],
i.parentNode.insertBefore(r,i),
t[n][o]=t[n][o]||{g:c||{},
ggPM:function(e,c,r,s,i){(t[n][o].q=t[n][o].q||[]).push([e,c,r,s,i])}},t[n][o]
}
}
}
(window,"NOLBUNDLE");
</script>

</syntaxhighlight>

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.

'''Create SDK Instance'''

To initialize the SDK, create an SDK instance by making the initialization call:

'''Initialization API Call'''
<syntaxhighlight lang="javascript">

NOLBUNDLE.nlsQ("<apid>", "<instanceName>",{nol_sdkDebug: "debug"})

</syntaxhighlight>

When creating an instance, pass the following three values:

=== SDK Initialization – Global Parameters <span class="anchor" id="SDK Initialization Global Parameters"></span> ===
{| class="wikitable"
|-
! Parameters !! Description !! Value
|-
| apid || UniqueID assigned to player/site. || 'XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX'
|-
| instanceName || Name of SDK instance || "any string value"
|-
| nol_sdkDebug || Enables Nielsen console logging. Only required for testing || "{nol_sdkDebug: "debug"})"
|-
| containerId || HTML DOM element id of the player container. Only for Viewability & Audibility feature. || {containerId: "playerId1"}
|-
| 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&"
|}

{{example_bsdk_init}}

'''Example SDK Configuration'''

The configuration should include the Static Queue Snippet and an SDK Instance for an unique App ID as shown in the example:

<syntaxhighlight lang="javascript">

<script type="text/javascript">
!function(t,n)
{
t[n]=t[n]||
{
nlsQ:function(e,o,c,r,s,i)
{
return s=t.document,
r=s.createElement("script"),
r.async=1,
r.src=("http:"===t.location.protocol?"http:":"https:")+"//cdn-gl.imrworldwide.com/conf/"+e+".js#name="+o+"&ns="+n,
i=s.getElementsByTagName("script")[0],
i.parentNode.insertBefore(r,i),
t[n][o]=t[n][o]||{g:c||{},
ggPM:function(e,c,r,s,i){(t[n][o].q=t[n][o].q||[]).push([e,c,r,s,i])}},t[n][o]
}
}
}
(window,"NOLBUNDLE");
// Created SDK Instance
var nSdkInstance = NOLBUNDLE.nlsQ("XXXXXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXX","nlsnInstance", {nol_sdkDebug: "debug"});
</script>

</syntaxhighlight>

=== Multiple SDK Instances ===
The Browser SDK allows instantiating multiple instances of the object, which can be used simultaneously without any problems, however they must be instantiated with their own unique instance names. There is no maximum number of instances that is enforced in the browser.

The below examples will make use of the same AppId, however using different AppIds will work as well. The principles below follow the same initialization rules stated above for a single instance and simply require a unique instance name and variable name with which the returned instance is assigned.

For more information around the possible parameters that can be passed as well as deeper descriptions for the API calls, please refer to the section on [[#SDK_Initialization|'''SDK Initialization - Global Parameters''']].

'''Example of 2 instances on the same page'''

<syntaxhighlight lang="javascript">
//Add Static Queue Snippet
<script>
!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.imrworldwide.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");

//Create SDK Instance(s)
// Notice the unique instance name given to each instance below and the unique variable name for each instance
var nSdkInstanceLive = NOLBUNDLE.nlsQ("XXXXXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXX", "instanceLive", {
nol_sdkDebug: 'debug',
optout: 'false'
});

var nSdkInstanceVod = NOLBUNDLE.nlsQ("XXXXXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXX", "instanceVod", {
nol_sdkDebug: 'debug',
optout: 'false'
});

</script>
</syntaxhighlight>

'''Example of 2 instances using a parent page and iFrame'''

<big>Parent Page (index.html)</big>

<syntaxhighlight lang="javascript">
<!DOCTYPE html>
<html lang="en">

<head>
<meta charset="UTF-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<meta http-equiv="X-UA-Compatible" content="ie=edge">
<title>DCR Static/DCR Video</title>
<script>
/* NLSQUEUE build v*/
!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.imrworldwide.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");

// SDK Initialization
var nSdkInstance = NOLBUNDLE.nlsQ("XXXXXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXX", "staticPage", {
nol_sdkDebug: 'debug',
});

// Static Metadata
var staticMetadata = {
assetid: 'staticTestPage',
type: 'static'
};

// Event 'staticstart' call
nSdkInstance.ggPM(14, staticMetadata);
</script>
</head>

<body>
<h1>DCR Static on Parent/DCR Video in iFrame</h1>
<p>Static measurement is current on parent page when window is in focus</p>
<iframe src="./dcr-video.html" frameborder="0" width="650" height="500" style="background-color: rgb(42, 217, 248);" id="video-iframe"></iframe>
</body>

</html>
</syntaxhighlight>

<big>Nested iFrame Referenced on Parent Page (dcr-video.html)</big>

<syntaxhighlight lang="javascript">
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
<meta http-equiv="X-UA-Compatible" content="ie=edge" />
<title>iFrame Same Source</title>
<script>
/* NLSQUEUE build v*/
!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.imrworldwide.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");

// SDK Initialization
var nSdkInstance = NOLBUNDLE.nlsQ("XXXXXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXX", "videoPlayer", {
nol_sdkDebug: 'debug',
});

var contentMetadata = {
type: "content",
length: "300",
title: "Skydiving Across Europe",
program: "latacg",
censuscategory: "Enlisted",
assetid: "204558915992",
section: "ProgramAsset8",
tv: "true",
adModel: "0",
dataSrc: "cms",
segA: "S07E04:NBC",
segB: "teams",
segC:"AtlanataFalcons",
}
</script>
</head>
<body>
<p>I'm iframe SDK DCR Video measurement, DCR static measurement should continue when clicking "play" on video</p>
<main>
<video
controls
src="https://archive.org/download/BigBuckBunny_124/Content/big_buck_bunny_720p_surround.mp4"
poster="https://peach.blender.org/wp-content/uploads/title_anouncement.jpg?x11217"
width="620">
Sorry, your browser doesn't support embedded videos, but don't worry, you can
<a href="https://archive.org/details/BigBuckBunny_124">download it</a>
and watch it with your favorite video player!
</video>
</main>
<script src="../player.js"></script>
</body>
</html>

</syntaxhighlight>

=== SDK Initialization to measure the Viewability & Audibility ===
To support viewability metrics in the web page the integrator has to provide a tag value of the player view to let Nielsen SDK know that there is a player that needs to be tracked. It’s called the ‘containerId’ and it should be passed in the as string while initializing the Nielsen browser SDK.

NOLBUNDLE.nlsQ("<apid>", "<instanceName>",{containerId: <playerElementID>, nol_sdkDebug: "debug"})

'''Example SDK Initialization for Viewability'''

Your configuration should include the Static Queue Snippet and an SDK Instance for your unique App ID as shown in the example:
<syntaxhighlight lang="javascript">
//Add Static Queue Snippet
<script>
! function(t, n) {
t[n] = t[n] || {
nlsQ: function(e, o, c, r, s, i) {
return s = t.document,
r = s.createElement("script"),
r.async = 1,
r.src = ("http:" === t.location.protocol ? "http:" : "https:") + "//cdn-gl.imrworldwide.com/conf/" + e + ".js#name=" + o + "&ns=" + n,
i = s.getElementsByTagName("script")[0],
i.parentNode.insertBefore(r, i),
t[n][o] = t[n][o] || {
g: c || {},
ggPM: function(e, c, r, s, i) {
(t[n][o].q = t[n][o].q || []).push([e, c, r, s, i])
}
}, t[n][o]
}
}
}
(window, "NOLBUNDLE");

//Create SDK Instance
var nSdkInstance = NOLBUNDLE.nlsQ("XXXXXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXX", "nlsnInstance", {containerId: “player1”, nol_sdkDebug: "debug"});
</script>

</syntaxhighlight>

== Browser SDK API Methods & Properties ==
{| class="wikitable sortable"
|-
! Method / Property !! Event # !! DTVR !! DAR !! DCR !! Description
|-
| [[loadMetadata (Browser)|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.
|-
| [[play (Browser)|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”.
|-
| [[sendID3 (Browser)|sendID3]] || 55 || ✔ || ✘ || ✘ || Used to send the ID3 metadata.
|-
| [[setPlayheadPosition (Browser)|setPlayheadPosition]] || 49 || ✘ || ✘ || ✔ || Used to send the playhead position.
|-
| [[stop (Browser)|stop]] || 7 || ✘ || ✘ || ✔ || Used when switching between ad and content or content and ad.
|-
| [[end (Browser)|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
|-
| [[staticstart (Browser)|staticstart]] || 14 || ✘ || ✘ || ✔ || Used to send the metadata for the static page.
|-
| [[StaticEnd (Browser)|staticend]] || 56 || ✘ || ✘ || ✔ || In Single Page Application (SPA) it is imperative that staticend is called prior to the loading of new metadata. This allows the Browser SDK to properly credit the previous section/content being viewed before measuring the new one.
|-
| [[updateOTT (Browser)|updateOTT]] || - || ✘ || ✘ || ✔ || Used to notify Browser SDK that the remote OTT device (like Google ChromeCast, Roku, Amazon FireTV, etc.) is connected / disconnected (change of OTT status).
|-
| [[ onPaginate (Browser)|onPaginate]] || 30 || ✘ || ✘ || ✔ || Used to create a new instance of the SDK object
|-
| [[updateMetadata (Browser)|updateMetadata]] || 35 || ✔ || ✔ || ✔ || This event is used for updating metadata parameters for the content or ad that is being played.
|-
| [[setVolume_(Browser)|setVolume]] || 61 || ✔ || ✘ || ✔ || Used to pass in the player volume levels in %. Default value is -1.
|}

== Retrieving ID3 Tags ==
The video player must have the ability to extract ID3 tags and supply them to the Browser SDK, based on the HLS standard.
*An ID3 tag spans two PES packets.
**In the first PES packet, look for www.nielsen.com, this is the start of the ID3 tag. Continue to parse the first PES packet until the undefined char "\ufffd" is found. This forms the first half of the ID3 tag
**In the second PES packet, identify the end pattern – a regEx of /(\/\d+){3}/ and look to remove the lowest index of either "\x00" and/or "\ufffd". Now the second packet has been appended and the demarcation of the Nielsen-specific data has been defined.

Follow the procedure below, to extract Nielsen ID3 tags from an MPEG-2 transport stream (including HLS streams).
#Parse the Program Map Table (PMT) to find the PID of the metadata stream. Confirm the presence of the metadata descriptor described in section 2.3.3 of Apple’s “HTTP Live Streaming Metadata Spec.pdf”. Only private streams with metadata descriptor present should be considered as ID3-tag metadata streams.
#Parse the HLS/Transport stream for any '''PES header''' with the PID found in step 1.
#Follow standard MPEG-2 parsing procedures to locate the start of the payload of the PES packet.
#Copy the PES payload into a buffer.
#The ID3 tag spans 2 PES packets. Parse the stream for the next packet whose PID is set to the PID found in step 1. Typically the ID3 Tag is of 249 bytes. The steps below guide towards extraction of the ID3 tag
##In the first PES packet, look for "www.nielsen.com" , this is the start of the ID3 tag. Keep on parsing the first PES packet until the undefined char "\ufffd" is found. This forms the first half of the ID3 tag
##In the second PES packet, identify the end pattern, a regEx of /(\/\d+){3}/ and look to remove the lowest index of either “\x00” and/or “\ufffd”. Now the second packet has been appended and the demarcation of the Nielsen specific data has been defined. This segment can be simply substringed.
##Concatenate this substringed segment with the payload derived from the first packet get the ID3 payload.
#Check the length of the contents in the buffer to make sure that it is equal to the size of a Nielsen ID3 tag.
#Ensure that the ID3 byte array is converted into the string and escape it, so that the SDK can consume it.
Repeat steps 2 through 7 for all ID3 tags in the stream.

'''References'''
*[http://www.iso.org/iso/catalogue_detail?csnumber=44169. ISO/IEC 13818-1:2007] Information technology – Generic coding of moving pictures and associated audio information: Systems
*https://developer.apple.com/library/content/documentation/AudioVideo/Conceptual/HTTP_Live_Streaming_Metadata_Spec/

=== Sample ID3 tags ===
* <code>www.nielsen.com/X100zdCIGeIlgZnkYj6UvQ==/X100zdCIGeIlgZnkYj6UvQ==/AAAB2Jz2_k74GXSzx4npHuI_<wbr />JwJd3QSUpW30rDkGTcbHEzIMWleCzM-uvNOP9fzJcQMWQLJqzXMCAxParOb5sGijSV9dNM3QiBniJYGZ5GI-lL1fXTTN0IgZ4iWBmeRiPpS9AAAAAAAAAAAAAAAAAAAAAFJWFM5SVhTONNU=/00000/00000/00</code>
* <code>www.nielsen.com/X100zdCIGeIlgZnkYj6UvQ==/R8WHe7pEBeqBhu8jTeXydg==/AAICoyitYqlxT7n6aZ0oMCGhe<wbr />Fi4CXFp46AMUPZz1lMr_M9tr3_cjee1SHqxrOiVerMDLeyn9xzocZSKwi746Re8vNOtpNCAZjYABs_J0R25IHpvOc1HS8<wbr />QHGgD5TgOJeS6gX100zdCIGeIlgZnkYj6UvVJWFNhSVhTiPE0=/00000/46016/00</code>
<blockquote>'''Note''': ID3 tags are not applicable for International (Germany)</blockquote>

== Browser Opt-Out Implementation ==
The site in which video content is being measure via Nielsen methodology must provide the means for the user to opt-out of, or opt back into Nielsen Measurement.

For Browser-based applications, opt-out setting is stored via Nielsen cookie. Therefore, it is only necessary that users be made aware of measurement opt-out by incorporating the template below in the user interface.

=== Sample Opt Out Template ===
Our properties may feature Nielsen’s proprietary measurement software which will allow to contribute to market research, like Nielsen’s TV Ratings. To learn more about this information, see https://www.nielsen.com/digitalprivacy. Nielsen’s software may collect your choices with regards to it.

== Nielsen Privacy Requirements ==
Privacy protections that Nielsen ensures to have with each App SDK integration are as follows.
*Disclosure of viewership data collection in EULA / Privacy Policy
*A link in the EULA/Privacy policy, or in another conspicuous location within the App, to a Nielsen-hosted web page outlining what Nielsen is collecting and how it is being used
*Method for users to opt-out of Nielsen measurement, any time while using the application

=== Ratings Data Flow ===
Every view of creditable and watermarked content is measured by Nielsen.
[[File:RatingsDataFlow.png]]

'''Information NOT Shared'''
* '''With Nielsen'''
** User's Identity
* '''With Data Provider'''
** Content information
** Whether user is viewing an ad or video content
** Player used to play the streaming (audio / video, etc.)
** Values being de-duped / aggregating for

Nielsen collects only what it needs for audience measurement. Every view of creditable, watermarked content will be measured by Nielsen.

=== Data Collected ===
{| class="wikitable"
|-
! Type of Information !! Parameter !! Transmitted to Nielsen? !! Sent to Provider?
|-
| rowspan="8" | Nielsen ID3 Watermark
|-
| FinalDistributor Timestamp || Yes || No
|-
| Program Content Timestamp || Yes || No
|-
| Mobile Breakout Code || Yes || No
|-
| Commercial Credit Code – Linear or Dynamic || Yes || No
|-
| Time ShiftedViewing Code || Yes || No
|-
| Segment Number || Yes || No
|-
| Segment View Pattern || Yes || No
|-
| rowspan="7" | Device/App Info
|-
| Device OSVersion || Yes || Yes
|-
| Device Model || Yes || No
|-
| Cache Buster || Yes || Yes
|-
| SDKDisabled Flag || Yes || No
|-
| ServerCode || Yes || No
|-
| Channel or URL || Yes || No
|-
| rowspan="9" | Nielsen Identifiers
|-
| Client ID || Yes || No
|-
| Campaign ID || Yes || Yes
|-
| Nielsen Unique Device ID || Yes || No
|-
| Application ID || Yes || No
|-
| DeviceGroup (ex. Tablet, Smartphone, Desktop) || Yes || Yes
|-
| OS Group (ex. Android, iOS, Windows) || Yes || Yes
|-
| SDKVersion || Yes || No
|-
| IP Address for DMA, Country Code || Yes || Yes
|}
<blockquote>'''Note''': Data is hashed, and encrypted using AES 128 before transmission to data provider.</blockquote>

{{Viewability_Data_Collected}}

==== Example ping sent to provider ====
* <code><nowiki>https://provider.com/cgi-bin/brandlift.php</nowiki>?campaign_id=ff12725d724fac7934cf6003f096b4cd<wbr />&placement_id=a4164b8fba9ee7c873a9c72c7091bb58<wbr />&creative_id=25280139b61a947e127a52f56c8a2fdd<wbr />&segment1=9000<wbr />&segment2=41<wbr />&segment3=iOS<wbr />&OSVer=iOS6.1<wbr />&c9=<wbr />&devgrp=tablet<wbr />&h=f5f243fe6d<wbr />&rnd=1376971827360</code>

This ping passes the following parameters to the provider:
* Campaign ID – (campaign, placement, creative)
* Country Code
* DMA
* OS Group (ex. iOS, Android)
* DeviceOS Version
* Device Advertiser ID
* DeviceGroup (ex. Tablet, Smartphone, Desktop)
* Cache Buster

{{Template:Browser_Privacy_and_Opt-Out}}

=== Opt-Out Implementation ===
The site must provide the means for the user to opt-out of, or opt back into Nielsen Measurement.

'''Sample Opt Out Template'''

Our properties may feature Nielsen’s proprietary measurement software which will allow to contribute to market research, like Nielsen’s TV Ratings. To learn more about this information, please [http://priv-policy.imrworldwide.com/priv/mobile/us/en/optout.html| click here]. Nielsen’s software may collect your choices with regards to it.

== Testing ==
See [[Digital Measurement Testing#Testing Browser Implementation|Digital Measurement Testing - Testing Browser Implementation]].

Browser SDK API Reference

2024-12-11T20:08:30Z

AmySockanathan: /* Multiple SDK Instances */

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

== Setting up Development Environment ==
=== Step 1: Configure Content Management System (CMS) ===
Configure CMS to send the required values (see table below). Any internal CMS_variable names can be used for passing the data.

Ensure to capture these CMS_variable names in the SDK Configuration Form.

For more information on setting variable names, see the SDK Configuration Form included within the SDK package.

{| class="wikitable"
|-
! Required Data !! Description !! Value
|-
| dataSrc || Used when both CMS metadata and ID3 data are present in the player. Setting this field tells the SDK whether to use the CMS metadata or the ID3 payload to derive the pings || cms
|-
| type || Type of asset: ad or content || preroll, midroll, postroll, or content
|-
| assetid || unique ID assigned to asset || custom <br>(no [[Special Characters]])
|-
| OCR Tag || OCR tag provided by Nielsen for implementation on the ad unit || Complete OCR URL
|-
| program || Name of program (25 character limit) || custom
|-
| title || Episode title (40 character limit) || custom
|-
| length || Length of content in seconds || Length in seconds, 0 for live stream
|-
| adloadtype || Type of ad load || "1" - Linear "2" - Dynamic(default)
|-
| hasAds || Identify if content includes Ads || "0" - no ads "1" - includes ads "2" - unknown(default)
|-
| isfullepisode || Full episode flag || "y" - full episode "n" - non full episode
|-
| segA || Segment A (this is not available for video reporting as the episode title is reported) || custom value
|-
| segB || Custom segment B || custom value
|-
| segC || Custom segment C || custom value
|-
| crossId1 || Standard episode ID || custom value
|-
| crossId2 || Content originator (required only for distributors) || custom value
|-
| airdate || Original air date and time in Eastern Time. For non-US countries, it should be local time. || YYYYMMDD HH24:MI:SS
|-
| containerId || HTML DOM element of the Player container (for Viewability&Audibility feature only) || custom value
|-
|luid
|Living Unit ID - Experian Household ID
'''Note: This parameter is applicable only for CTV and First Party Livestream data'''
|"B0EOFEDgD"
|}

=== Step 2: Complete the Nielsen SDK Configuration Form ===
The SDK is designed to map the <code>CMS_variable names</code>. To support the custom mapping, the developer is required to complete the SDK Configuration Form. The form will be provided during onboarding along with this guide.

== Initialization ==
=== Obtain the Nielsen Application ID (apid) and Browser SDK URLs ===
The Nielsen <code>apid</code> 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 Browser SDK ===
There are two steps required for configuring the SDK:

'''Add Static Queue Snippet'''

*Add Static Queue Snippet
*Create SDK Instance

Add the following script tag to the website:
<syntaxhighlight lang="javascript">

<script type="text/javascript">
!function(t,n)
{
t[n]=t[n]||
{
nlsQ:function(e,o,c,r,s,i)
{
return s=t.document,
r=s.createElement("script"),
r.async=1,
r.src=("http:"===t.location.protocol?"http:":"https:")+"//cdn-gl.imrworldwide.com/conf/"+e+".js#name="+o+"&ns="+n,
i=s.getElementsByTagName("script")[0],
i.parentNode.insertBefore(r,i),
t[n][o]=t[n][o]||{g:c||{},
ggPM:function(e,c,r,s,i){(t[n][o].q=t[n][o].q||[]).push([e,c,r,s,i])}},t[n][o]
}
}
}
(window,"NOLBUNDLE");
</script>

</syntaxhighlight>

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.

'''Create SDK Instance'''

To initialize the SDK, create an SDK instance by making the initialization call:

'''Initialization API Call'''
<syntaxhighlight lang="javascript">

NOLBUNDLE.nlsQ("<apid>", "<instanceName>",{nol_sdkDebug: "debug"})

</syntaxhighlight>

When creating an instance, pass the following three values:

=== SDK Initialization – Global Parameters ===
{| class="wikitable"
|-
! Parameters !! Description !! Value
|-
| apid || UniqueID assigned to player/site. || 'XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX'
|-
| instanceName || Name of SDK instance || "any string value"
|-
| nol_sdkDebug || Enables Nielsen console logging. Only required for testing || "{nol_sdkDebug: "debug"})"
|-
| containerId || HTML DOM element id of the player container. Only for Viewability & Audibility feature. || {containerId: "playerId1"}
|-
| 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&"
|}

{{example_bsdk_init}}

'''Example SDK Configuration'''

The configuration should include the Static Queue Snippet and an SDK Instance for an unique App ID as shown in the example:

<syntaxhighlight lang="javascript">

<script type="text/javascript">
!function(t,n)
{
t[n]=t[n]||
{
nlsQ:function(e,o,c,r,s,i)
{
return s=t.document,
r=s.createElement("script"),
r.async=1,
r.src=("http:"===t.location.protocol?"http:":"https:")+"//cdn-gl.imrworldwide.com/conf/"+e+".js#name="+o+"&ns="+n,
i=s.getElementsByTagName("script")[0],
i.parentNode.insertBefore(r,i),
t[n][o]=t[n][o]||{g:c||{},
ggPM:function(e,c,r,s,i){(t[n][o].q=t[n][o].q||[]).push([e,c,r,s,i])}},t[n][o]
}
}
}
(window,"NOLBUNDLE");
// Created SDK Instance
var nSdkInstance = NOLBUNDLE.nlsQ("XXXXXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXX","nlsnInstance", {nol_sdkDebug: "debug"});
</script>

</syntaxhighlight>

=== Multiple SDK Instances ===
The Browser SDK allows instantiating multiple instances of the object, which can be used simultaneously without any problems, however they must be instantiated with their own unique instance names. There is no maximum number of instances that is enforced in the browser.

The below examples will make use of the same AppId, however using different AppIds will work as well. The principles below follow the same initialization rules stated above for a single instance and simply require a unique instance name and variable name with which the returned instance is assigned.

For more information around the possible parameters that can be passed as well as deeper descriptions for the API calls, please refer to the section on [[#SDK_Initialization|'''SDK Initialization - Global Parameters''']].

'''Example of 2 instances on the same page'''

<syntaxhighlight lang="javascript">
//Add Static Queue Snippet
<script>
!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.imrworldwide.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");

//Create SDK Instance(s)
// Notice the unique instance name given to each instance below and the unique variable name for each instance
var nSdkInstanceLive = NOLBUNDLE.nlsQ("XXXXXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXX", "instanceLive", {
nol_sdkDebug: 'debug',
optout: 'false'
});

var nSdkInstanceVod = NOLBUNDLE.nlsQ("XXXXXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXX", "instanceVod", {
nol_sdkDebug: 'debug',
optout: 'false'
});

</script>
</syntaxhighlight>

'''Example of 2 instances using a parent page and iFrame'''

<big>Parent Page (index.html)</big>

<syntaxhighlight lang="javascript">
<!DOCTYPE html>
<html lang="en">

<head>
<meta charset="UTF-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<meta http-equiv="X-UA-Compatible" content="ie=edge">
<title>DCR Static/DCR Video</title>
<script>
/* NLSQUEUE build v*/
!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.imrworldwide.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");

// SDK Initialization
var nSdkInstance = NOLBUNDLE.nlsQ("XXXXXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXX", "staticPage", {
nol_sdkDebug: 'debug',
});

// Static Metadata
var staticMetadata = {
assetid: 'staticTestPage',
type: 'static'
};

// Event 'staticstart' call
nSdkInstance.ggPM(14, staticMetadata);
</script>
</head>

<body>
<h1>DCR Static on Parent/DCR Video in iFrame</h1>
<p>Static measurement is current on parent page when window is in focus</p>
<iframe src="./dcr-video.html" frameborder="0" width="650" height="500" style="background-color: rgb(42, 217, 248);" id="video-iframe"></iframe>
</body>

</html>
</syntaxhighlight>

<big>Nested iFrame Referenced on Parent Page (dcr-video.html)</big>

<syntaxhighlight lang="javascript">
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
<meta http-equiv="X-UA-Compatible" content="ie=edge" />
<title>iFrame Same Source</title>
<script>
/* NLSQUEUE build v*/
!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.imrworldwide.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");

// SDK Initialization
var nSdkInstance = NOLBUNDLE.nlsQ("XXXXXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXX", "videoPlayer", {
nol_sdkDebug: 'debug',
});

var contentMetadata = {
type: "content",
length: "300",
title: "Skydiving Across Europe",
program: "latacg",
censuscategory: "Enlisted",
assetid: "204558915992",
section: "ProgramAsset8",
tv: "true",
adModel: "0",
dataSrc: "cms",
segA: "S07E04:NBC",
segB: "teams",
segC:"AtlanataFalcons",
}
</script>
</head>
<body>
<p>I'm iframe SDK DCR Video measurement, DCR static measurement should continue when clicking "play" on video</p>
<main>
<video
controls
src="https://archive.org/download/BigBuckBunny_124/Content/big_buck_bunny_720p_surround.mp4"
poster="https://peach.blender.org/wp-content/uploads/title_anouncement.jpg?x11217"
width="620">
Sorry, your browser doesn't support embedded videos, but don't worry, you can
<a href="https://archive.org/details/BigBuckBunny_124">download it</a>
and watch it with your favorite video player!
</video>
</main>
<script src="../player.js"></script>
</body>
</html>

</syntaxhighlight>

=== SDK Initialization to measure the Viewability & Audibility ===
To support viewability metrics in the web page the integrator has to provide a tag value of the player view to let Nielsen SDK know that there is a player that needs to be tracked. It’s called the ‘containerId’ and it should be passed in the as string while initializing the Nielsen browser SDK.

NOLBUNDLE.nlsQ("<apid>", "<instanceName>",{containerId: <playerElementID>, nol_sdkDebug: "debug"})

'''Example SDK Initialization for Viewability'''

Your configuration should include the Static Queue Snippet and an SDK Instance for your unique App ID as shown in the example:
<syntaxhighlight lang="javascript">
//Add Static Queue Snippet
<script>
! function(t, n) {
t[n] = t[n] || {
nlsQ: function(e, o, c, r, s, i) {
return s = t.document,
r = s.createElement("script"),
r.async = 1,
r.src = ("http:" === t.location.protocol ? "http:" : "https:") + "//cdn-gl.imrworldwide.com/conf/" + e + ".js#name=" + o + "&ns=" + n,
i = s.getElementsByTagName("script")[0],
i.parentNode.insertBefore(r, i),
t[n][o] = t[n][o] || {
g: c || {},
ggPM: function(e, c, r, s, i) {
(t[n][o].q = t[n][o].q || []).push([e, c, r, s, i])
}
}, t[n][o]
}
}
}
(window, "NOLBUNDLE");

//Create SDK Instance
var nSdkInstance = NOLBUNDLE.nlsQ("XXXXXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXX", "nlsnInstance", {containerId: “player1”, nol_sdkDebug: "debug"});
</script>

</syntaxhighlight>

== Browser SDK API Methods & Properties ==
{| class="wikitable sortable"
|-
! Method / Property !! Event # !! DTVR !! DAR !! DCR !! Description
|-
| [[loadMetadata (Browser)|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.
|-
| [[play (Browser)|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”.
|-
| [[sendID3 (Browser)|sendID3]] || 55 || ✔ || ✘ || ✘ || Used to send the ID3 metadata.
|-
| [[setPlayheadPosition (Browser)|setPlayheadPosition]] || 49 || ✘ || ✘ || ✔ || Used to send the playhead position.
|-
| [[stop (Browser)|stop]] || 7 || ✘ || ✘ || ✔ || Used when switching between ad and content or content and ad.
|-
| [[end (Browser)|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
|-
| [[staticstart (Browser)|staticstart]] || 14 || ✘ || ✘ || ✔ || Used to send the metadata for the static page.
|-
| [[StaticEnd (Browser)|staticend]] || 56 || ✘ || ✘ || ✔ || In Single Page Application (SPA) it is imperative that staticend is called prior to the loading of new metadata. This allows the Browser SDK to properly credit the previous section/content being viewed before measuring the new one.
|-
| [[updateOTT (Browser)|updateOTT]] || - || ✘ || ✘ || ✔ || Used to notify Browser SDK that the remote OTT device (like Google ChromeCast, Roku, Amazon FireTV, etc.) is connected / disconnected (change of OTT status).
|-
| [[ onPaginate (Browser)|onPaginate]] || 30 || ✘ || ✘ || ✔ || Used to create a new instance of the SDK object
|-
| [[updateMetadata (Browser)|updateMetadata]] || 35 || ✔ || ✔ || ✔ || This event is used for updating metadata parameters for the content or ad that is being played.
|-
| [[setVolume_(Browser)|setVolume]] || 61 || ✔ || ✘ || ✔ || Used to pass in the player volume levels in %. Default value is -1.
|}

== Retrieving ID3 Tags ==
The video player must have the ability to extract ID3 tags and supply them to the Browser SDK, based on the HLS standard.
*An ID3 tag spans two PES packets.
**In the first PES packet, look for www.nielsen.com, this is the start of the ID3 tag. Continue to parse the first PES packet until the undefined char "\ufffd" is found. This forms the first half of the ID3 tag
**In the second PES packet, identify the end pattern – a regEx of /(\/\d+){3}/ and look to remove the lowest index of either "\x00" and/or "\ufffd". Now the second packet has been appended and the demarcation of the Nielsen-specific data has been defined.

Follow the procedure below, to extract Nielsen ID3 tags from an MPEG-2 transport stream (including HLS streams).
#Parse the Program Map Table (PMT) to find the PID of the metadata stream. Confirm the presence of the metadata descriptor described in section 2.3.3 of Apple’s “HTTP Live Streaming Metadata Spec.pdf”. Only private streams with metadata descriptor present should be considered as ID3-tag metadata streams.
#Parse the HLS/Transport stream for any '''PES header''' with the PID found in step 1.
#Follow standard MPEG-2 parsing procedures to locate the start of the payload of the PES packet.
#Copy the PES payload into a buffer.
#The ID3 tag spans 2 PES packets. Parse the stream for the next packet whose PID is set to the PID found in step 1. Typically the ID3 Tag is of 249 bytes. The steps below guide towards extraction of the ID3 tag
##In the first PES packet, look for "www.nielsen.com" , this is the start of the ID3 tag. Keep on parsing the first PES packet until the undefined char "\ufffd" is found. This forms the first half of the ID3 tag
##In the second PES packet, identify the end pattern, a regEx of /(\/\d+){3}/ and look to remove the lowest index of either “\x00” and/or “\ufffd”. Now the second packet has been appended and the demarcation of the Nielsen specific data has been defined. This segment can be simply substringed.
##Concatenate this substringed segment with the payload derived from the first packet get the ID3 payload.
#Check the length of the contents in the buffer to make sure that it is equal to the size of a Nielsen ID3 tag.
#Ensure that the ID3 byte array is converted into the string and escape it, so that the SDK can consume it.
Repeat steps 2 through 7 for all ID3 tags in the stream.

'''References'''
*[http://www.iso.org/iso/catalogue_detail?csnumber=44169. ISO/IEC 13818-1:2007] Information technology – Generic coding of moving pictures and associated audio information: Systems
*https://developer.apple.com/library/content/documentation/AudioVideo/Conceptual/HTTP_Live_Streaming_Metadata_Spec/

=== Sample ID3 tags ===
* <code>www.nielsen.com/X100zdCIGeIlgZnkYj6UvQ==/X100zdCIGeIlgZnkYj6UvQ==/AAAB2Jz2_k74GXSzx4npHuI_<wbr />JwJd3QSUpW30rDkGTcbHEzIMWleCzM-uvNOP9fzJcQMWQLJqzXMCAxParOb5sGijSV9dNM3QiBniJYGZ5GI-lL1fXTTN0IgZ4iWBmeRiPpS9AAAAAAAAAAAAAAAAAAAAAFJWFM5SVhTONNU=/00000/00000/00</code>
* <code>www.nielsen.com/X100zdCIGeIlgZnkYj6UvQ==/R8WHe7pEBeqBhu8jTeXydg==/AAICoyitYqlxT7n6aZ0oMCGhe<wbr />Fi4CXFp46AMUPZz1lMr_M9tr3_cjee1SHqxrOiVerMDLeyn9xzocZSKwi746Re8vNOtpNCAZjYABs_J0R25IHpvOc1HS8<wbr />QHGgD5TgOJeS6gX100zdCIGeIlgZnkYj6UvVJWFNhSVhTiPE0=/00000/46016/00</code>
<blockquote>'''Note''': ID3 tags are not applicable for International (Germany)</blockquote>

== Browser Opt-Out Implementation ==
The site in which video content is being measure via Nielsen methodology must provide the means for the user to opt-out of, or opt back into Nielsen Measurement.

For Browser-based applications, opt-out setting is stored via Nielsen cookie. Therefore, it is only necessary that users be made aware of measurement opt-out by incorporating the template below in the user interface.

=== Sample Opt Out Template ===
Our properties may feature Nielsen’s proprietary measurement software which will allow to contribute to market research, like Nielsen’s TV Ratings. To learn more about this information, see https://www.nielsen.com/digitalprivacy. Nielsen’s software may collect your choices with regards to it.

== Nielsen Privacy Requirements ==
Privacy protections that Nielsen ensures to have with each App SDK integration are as follows.
*Disclosure of viewership data collection in EULA / Privacy Policy
*A link in the EULA/Privacy policy, or in another conspicuous location within the App, to a Nielsen-hosted web page outlining what Nielsen is collecting and how it is being used
*Method for users to opt-out of Nielsen measurement, any time while using the application

=== Ratings Data Flow ===
Every view of creditable and watermarked content is measured by Nielsen.
[[File:RatingsDataFlow.png]]

'''Information NOT Shared'''
* '''With Nielsen'''
** User's Identity
* '''With Data Provider'''
** Content information
** Whether user is viewing an ad or video content
** Player used to play the streaming (audio / video, etc.)
** Values being de-duped / aggregating for

Nielsen collects only what it needs for audience measurement. Every view of creditable, watermarked content will be measured by Nielsen.

=== Data Collected ===
{| class="wikitable"
|-
! Type of Information !! Parameter !! Transmitted to Nielsen? !! Sent to Provider?
|-
| rowspan="8" | Nielsen ID3 Watermark
|-
| FinalDistributor Timestamp || Yes || No
|-
| Program Content Timestamp || Yes || No
|-
| Mobile Breakout Code || Yes || No
|-
| Commercial Credit Code – Linear or Dynamic || Yes || No
|-
| Time ShiftedViewing Code || Yes || No
|-
| Segment Number || Yes || No
|-
| Segment View Pattern || Yes || No
|-
| rowspan="7" | Device/App Info
|-
| Device OSVersion || Yes || Yes
|-
| Device Model || Yes || No
|-
| Cache Buster || Yes || Yes
|-
| SDKDisabled Flag || Yes || No
|-
| ServerCode || Yes || No
|-
| Channel or URL || Yes || No
|-
| rowspan="9" | Nielsen Identifiers
|-
| Client ID || Yes || No
|-
| Campaign ID || Yes || Yes
|-
| Nielsen Unique Device ID || Yes || No
|-
| Application ID || Yes || No
|-
| DeviceGroup (ex. Tablet, Smartphone, Desktop) || Yes || Yes
|-
| OS Group (ex. Android, iOS, Windows) || Yes || Yes
|-
| SDKVersion || Yes || No
|-
| IP Address for DMA, Country Code || Yes || Yes
|}
<blockquote>'''Note''': Data is hashed, and encrypted using AES 128 before transmission to data provider.</blockquote>

{{Viewability_Data_Collected}}

==== Example ping sent to provider ====
* <code><nowiki>https://provider.com/cgi-bin/brandlift.php</nowiki>?campaign_id=ff12725d724fac7934cf6003f096b4cd<wbr />&placement_id=a4164b8fba9ee7c873a9c72c7091bb58<wbr />&creative_id=25280139b61a947e127a52f56c8a2fdd<wbr />&segment1=9000<wbr />&segment2=41<wbr />&segment3=iOS<wbr />&OSVer=iOS6.1<wbr />&c9=<wbr />&devgrp=tablet<wbr />&h=f5f243fe6d<wbr />&rnd=1376971827360</code>

This ping passes the following parameters to the provider:
* Campaign ID – (campaign, placement, creative)
* Country Code
* DMA
* OS Group (ex. iOS, Android)
* DeviceOS Version
* Device Advertiser ID
* DeviceGroup (ex. Tablet, Smartphone, Desktop)
* Cache Buster

{{Template:Browser_Privacy_and_Opt-Out}}

=== Opt-Out Implementation ===
The site must provide the means for the user to opt-out of, or opt back into Nielsen Measurement.

'''Sample Opt Out Template'''

Our properties may feature Nielsen’s proprietary measurement software which will allow to contribute to market research, like Nielsen’s TV Ratings. To learn more about this information, please [http://priv-policy.imrworldwide.com/priv/mobile/us/en/optout.html| click here]. Nielsen’s software may collect your choices with regards to it.

== Testing ==
See [[Digital Measurement Testing#Testing Browser Implementation|Digital Measurement Testing - Testing Browser Implementation]].

Browser SDK API Reference

2024-12-11T20:02:17Z

AmySockanathan:

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

== Setting up Development Environment ==
=== Step 1: Configure Content Management System (CMS) ===
Configure CMS to send the required values (see table below). Any internal CMS_variable names can be used for passing the data.

Ensure to capture these CMS_variable names in the SDK Configuration Form.

For more information on setting variable names, see the SDK Configuration Form included within the SDK package.

{| class="wikitable"
|-
! Required Data !! Description !! Value
|-
| dataSrc || Used when both CMS metadata and ID3 data are present in the player. Setting this field tells the SDK whether to use the CMS metadata or the ID3 payload to derive the pings || cms
|-
| type || Type of asset: ad or content || preroll, midroll, postroll, or content
|-
| assetid || unique ID assigned to asset || custom <br>(no [[Special Characters]])
|-
| OCR Tag || OCR tag provided by Nielsen for implementation on the ad unit || Complete OCR URL
|-
| program || Name of program (25 character limit) || custom
|-
| title || Episode title (40 character limit) || custom
|-
| length || Length of content in seconds || Length in seconds, 0 for live stream
|-
| adloadtype || Type of ad load || "1" - Linear "2" - Dynamic(default)
|-
| hasAds || Identify if content includes Ads || "0" - no ads "1" - includes ads "2" - unknown(default)
|-
| isfullepisode || Full episode flag || "y" - full episode "n" - non full episode
|-
| segA || Segment A (this is not available for video reporting as the episode title is reported) || custom value
|-
| segB || Custom segment B || custom value
|-
| segC || Custom segment C || custom value
|-
| crossId1 || Standard episode ID || custom value
|-
| crossId2 || Content originator (required only for distributors) || custom value
|-
| airdate || Original air date and time in Eastern Time. For non-US countries, it should be local time. || YYYYMMDD HH24:MI:SS
|-
| containerId || HTML DOM element of the Player container (for Viewability&Audibility feature only) || custom value
|-
|luid
|Living Unit ID - Experian Household ID
'''Note: This parameter is applicable only for CTV and First Party Livestream data'''
|"B0EOFEDgD"
|}

=== Step 2: Complete the Nielsen SDK Configuration Form ===
The SDK is designed to map the <code>CMS_variable names</code>. To support the custom mapping, the developer is required to complete the SDK Configuration Form. The form will be provided during onboarding along with this guide.

== Initialization ==
=== Obtain the Nielsen Application ID (apid) and Browser SDK URLs ===
The Nielsen <code>apid</code> 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 Browser SDK ===
There are two steps required for configuring the SDK:

'''Add Static Queue Snippet'''

*Add Static Queue Snippet
*Create SDK Instance

Add the following script tag to the website:
<syntaxhighlight lang="javascript">

<script type="text/javascript">
!function(t,n)
{
t[n]=t[n]||
{
nlsQ:function(e,o,c,r,s,i)
{
return s=t.document,
r=s.createElement("script"),
r.async=1,
r.src=("http:"===t.location.protocol?"http:":"https:")+"//cdn-gl.imrworldwide.com/conf/"+e+".js#name="+o+"&ns="+n,
i=s.getElementsByTagName("script")[0],
i.parentNode.insertBefore(r,i),
t[n][o]=t[n][o]||{g:c||{},
ggPM:function(e,c,r,s,i){(t[n][o].q=t[n][o].q||[]).push([e,c,r,s,i])}},t[n][o]
}
}
}
(window,"NOLBUNDLE");
</script>

</syntaxhighlight>

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.

'''Create SDK Instance'''

To initialize the SDK, create an SDK instance by making the initialization call:

'''Initialization API Call'''
<syntaxhighlight lang="javascript">

NOLBUNDLE.nlsQ("<apid>", "<instanceName>",{nol_sdkDebug: "debug"})

</syntaxhighlight>

When creating an instance, pass the following three values:

=== SDK Initialization – Global Parameters ===
{| class="wikitable"
|-
! Parameters !! Description !! Value
|-
| apid || UniqueID assigned to player/site. || 'XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX'
|-
| instanceName || Name of SDK instance || "any string value"
|-
| nol_sdkDebug || Enables Nielsen console logging. Only required for testing || "{nol_sdkDebug: "debug"})"
|-
| containerId || HTML DOM element id of the player container. Only for Viewability & Audibility feature. || {containerId: "playerId1"}
|-
| 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&"
|}

{{example_bsdk_init}}

'''Example SDK Configuration'''

The configuration should include the Static Queue Snippet and an SDK Instance for an unique App ID as shown in the example:

<syntaxhighlight lang="javascript">

<script type="text/javascript">
!function(t,n)
{
t[n]=t[n]||
{
nlsQ:function(e,o,c,r,s,i)
{
return s=t.document,
r=s.createElement("script"),
r.async=1,
r.src=("http:"===t.location.protocol?"http:":"https:")+"//cdn-gl.imrworldwide.com/conf/"+e+".js#name="+o+"&ns="+n,
i=s.getElementsByTagName("script")[0],
i.parentNode.insertBefore(r,i),
t[n][o]=t[n][o]||{g:c||{},
ggPM:function(e,c,r,s,i){(t[n][o].q=t[n][o].q||[]).push([e,c,r,s,i])}},t[n][o]
}
}
}
(window,"NOLBUNDLE");
// Created SDK Instance
var nSdkInstance = NOLBUNDLE.nlsQ("XXXXXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXX","nlsnInstance", {nol_sdkDebug: "debug"});
</script>

</syntaxhighlight>

=== Multiple SDK Instances ===
The Browser SDK allows instantiating multiple instances of the object, which can be used simultaneously without any problems, however they must be instantiated with their own unique instance names. There is no maximum number of instances that is enforced in the browser.

The below examples will make use of the same AppId, however using different AppIds will work as well. The principles below follow the same initialization rules stated above for a single instance and simply require a unique instance name and variable name with which the returned instance is assigned.

For more information around the possible parameters that can be passed as well as deeper descriptions for the API calls, please refer to the section on [[#SDK_Initialization_-_Global Parameters|'''SDK Initialization - Global Parameters''']].

'''Example of 2 instances on the same page'''

<syntaxhighlight lang="javascript">
//Add Static Queue Snippet
<script>
!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.imrworldwide.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");

//Create SDK Instance(s)
// Notice the unique instance name given to each instance below and the unique variable name for each instance
var nSdkInstanceLive = NOLBUNDLE.nlsQ("XXXXXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXX", "instanceLive", {
nol_sdkDebug: 'debug',
optout: 'false'
});

var nSdkInstanceVod = NOLBUNDLE.nlsQ("XXXXXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXX", "instanceVod", {
nol_sdkDebug: 'debug',
optout: 'false'
});

</script>
</syntaxhighlight>

'''Example of 2 instances using a parent page and iFrame'''

<big>Parent Page (index.html)</big>

<syntaxhighlight lang="javascript">
<!DOCTYPE html>
<html lang="en">

<head>
<meta charset="UTF-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<meta http-equiv="X-UA-Compatible" content="ie=edge">
<title>DCR Static/DCR Video</title>
<script>
/* NLSQUEUE build v*/
!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.imrworldwide.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");

// SDK Initialization
var nSdkInstance = NOLBUNDLE.nlsQ("XXXXXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXX", "staticPage", {
nol_sdkDebug: 'debug',
});

// Static Metadata
var staticMetadata = {
assetid: 'staticTestPage',
type: 'static'
};

// Event 'staticstart' call
nSdkInstance.ggPM(14, staticMetadata);
</script>
</head>

<body>
<h1>DCR Static on Parent/DCR Video in iFrame</h1>
<p>Static measurement is current on parent page when window is in focus</p>
<iframe src="./dcr-video.html" frameborder="0" width="650" height="500" style="background-color: rgb(42, 217, 248);" id="video-iframe"></iframe>
</body>

</html>
</syntaxhighlight>

<big>Nested iFrame Referenced on Parent Page (dcr-video.html)</big>

<syntaxhighlight lang="javascript">
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
<meta http-equiv="X-UA-Compatible" content="ie=edge" />
<title>iFrame Same Source</title>
<script>
/* NLSQUEUE build v*/
!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.imrworldwide.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");

// SDK Initialization
var nSdkInstance = NOLBUNDLE.nlsQ("XXXXXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXX", "videoPlayer", {
nol_sdkDebug: 'debug',
});

var contentMetadata = {
type: "content",
length: "300",
title: "Skydiving Across Europe",
program: "latacg",
censuscategory: "Enlisted",
assetid: "204558915992",
section: "ProgramAsset8",
tv: "true",
adModel: "0",
dataSrc: "cms",
segA: "S07E04:NBC",
segB: "teams",
segC:"AtlanataFalcons",
}
</script>
</head>
<body>
<p>I'm iframe SDK DCR Video measurement, DCR static measurement should continue when clicking "play" on video</p>
<main>
<video
controls
src="https://archive.org/download/BigBuckBunny_124/Content/big_buck_bunny_720p_surround.mp4"
poster="https://peach.blender.org/wp-content/uploads/title_anouncement.jpg?x11217"
width="620">
Sorry, your browser doesn't support embedded videos, but don't worry, you can
<a href="https://archive.org/details/BigBuckBunny_124">download it</a>
and watch it with your favorite video player!
</video>
</main>
<script src="../player.js"></script>
</body>
</html>

</syntaxhighlight>

=== SDK Initialization to measure the Viewability & Audibility ===
To support viewability metrics in the web page the integrator has to provide a tag value of the player view to let Nielsen SDK know that there is a player that needs to be tracked. It’s called the ‘containerId’ and it should be passed in the as string while initializing the Nielsen browser SDK.

NOLBUNDLE.nlsQ("<apid>", "<instanceName>",{containerId: <playerElementID>, nol_sdkDebug: "debug"})

'''Example SDK Initialization for Viewability'''

Your configuration should include the Static Queue Snippet and an SDK Instance for your unique App ID as shown in the example:
<syntaxhighlight lang="javascript">
//Add Static Queue Snippet
<script>
! function(t, n) {
t[n] = t[n] || {
nlsQ: function(e, o, c, r, s, i) {
return s = t.document,
r = s.createElement("script"),
r.async = 1,
r.src = ("http:" === t.location.protocol ? "http:" : "https:") + "//cdn-gl.imrworldwide.com/conf/" + e + ".js#name=" + o + "&ns=" + n,
i = s.getElementsByTagName("script")[0],
i.parentNode.insertBefore(r, i),
t[n][o] = t[n][o] || {
g: c || {},
ggPM: function(e, c, r, s, i) {
(t[n][o].q = t[n][o].q || []).push([e, c, r, s, i])
}
}, t[n][o]
}
}
}
(window, "NOLBUNDLE");

//Create SDK Instance
var nSdkInstance = NOLBUNDLE.nlsQ("XXXXXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXX", "nlsnInstance", {containerId: “player1”, nol_sdkDebug: "debug"});
</script>

</syntaxhighlight>

== Browser SDK API Methods & Properties ==
{| class="wikitable sortable"
|-
! Method / Property !! Event # !! DTVR !! DAR !! DCR !! Description
|-
| [[loadMetadata (Browser)|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.
|-
| [[play (Browser)|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”.
|-
| [[sendID3 (Browser)|sendID3]] || 55 || ✔ || ✘ || ✘ || Used to send the ID3 metadata.
|-
| [[setPlayheadPosition (Browser)|setPlayheadPosition]] || 49 || ✘ || ✘ || ✔ || Used to send the playhead position.
|-
| [[stop (Browser)|stop]] || 7 || ✘ || ✘ || ✔ || Used when switching between ad and content or content and ad.
|-
| [[end (Browser)|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
|-
| [[staticstart (Browser)|staticstart]] || 14 || ✘ || ✘ || ✔ || Used to send the metadata for the static page.
|-
| [[StaticEnd (Browser)|staticend]] || 56 || ✘ || ✘ || ✔ || In Single Page Application (SPA) it is imperative that staticend is called prior to the loading of new metadata. This allows the Browser SDK to properly credit the previous section/content being viewed before measuring the new one.
|-
| [[updateOTT (Browser)|updateOTT]] || - || ✘ || ✘ || ✔ || Used to notify Browser SDK that the remote OTT device (like Google ChromeCast, Roku, Amazon FireTV, etc.) is connected / disconnected (change of OTT status).
|-
| [[ onPaginate (Browser)|onPaginate]] || 30 || ✘ || ✘ || ✔ || Used to create a new instance of the SDK object
|-
| [[updateMetadata (Browser)|updateMetadata]] || 35 || ✔ || ✔ || ✔ || This event is used for updating metadata parameters for the content or ad that is being played.
|-
| [[setVolume_(Browser)|setVolume]] || 61 || ✔ || ✘ || ✔ || Used to pass in the player volume levels in %. Default value is -1.
|}

== Retrieving ID3 Tags ==
The video player must have the ability to extract ID3 tags and supply them to the Browser SDK, based on the HLS standard.
*An ID3 tag spans two PES packets.
**In the first PES packet, look for www.nielsen.com, this is the start of the ID3 tag. Continue to parse the first PES packet until the undefined char "\ufffd" is found. This forms the first half of the ID3 tag
**In the second PES packet, identify the end pattern – a regEx of /(\/\d+){3}/ and look to remove the lowest index of either "\x00" and/or "\ufffd". Now the second packet has been appended and the demarcation of the Nielsen-specific data has been defined.

Follow the procedure below, to extract Nielsen ID3 tags from an MPEG-2 transport stream (including HLS streams).
#Parse the Program Map Table (PMT) to find the PID of the metadata stream. Confirm the presence of the metadata descriptor described in section 2.3.3 of Apple’s “HTTP Live Streaming Metadata Spec.pdf”. Only private streams with metadata descriptor present should be considered as ID3-tag metadata streams.
#Parse the HLS/Transport stream for any '''PES header''' with the PID found in step 1.
#Follow standard MPEG-2 parsing procedures to locate the start of the payload of the PES packet.
#Copy the PES payload into a buffer.
#The ID3 tag spans 2 PES packets. Parse the stream for the next packet whose PID is set to the PID found in step 1. Typically the ID3 Tag is of 249 bytes. The steps below guide towards extraction of the ID3 tag
##In the first PES packet, look for "www.nielsen.com" , this is the start of the ID3 tag. Keep on parsing the first PES packet until the undefined char "\ufffd" is found. This forms the first half of the ID3 tag
##In the second PES packet, identify the end pattern, a regEx of /(\/\d+){3}/ and look to remove the lowest index of either “\x00” and/or “\ufffd”. Now the second packet has been appended and the demarcation of the Nielsen specific data has been defined. This segment can be simply substringed.
##Concatenate this substringed segment with the payload derived from the first packet get the ID3 payload.
#Check the length of the contents in the buffer to make sure that it is equal to the size of a Nielsen ID3 tag.
#Ensure that the ID3 byte array is converted into the string and escape it, so that the SDK can consume it.
Repeat steps 2 through 7 for all ID3 tags in the stream.

'''References'''
*[http://www.iso.org/iso/catalogue_detail?csnumber=44169. ISO/IEC 13818-1:2007] Information technology – Generic coding of moving pictures and associated audio information: Systems
*https://developer.apple.com/library/content/documentation/AudioVideo/Conceptual/HTTP_Live_Streaming_Metadata_Spec/

=== Sample ID3 tags ===
* <code>www.nielsen.com/X100zdCIGeIlgZnkYj6UvQ==/X100zdCIGeIlgZnkYj6UvQ==/AAAB2Jz2_k74GXSzx4npHuI_<wbr />JwJd3QSUpW30rDkGTcbHEzIMWleCzM-uvNOP9fzJcQMWQLJqzXMCAxParOb5sGijSV9dNM3QiBniJYGZ5GI-lL1fXTTN0IgZ4iWBmeRiPpS9AAAAAAAAAAAAAAAAAAAAAFJWFM5SVhTONNU=/00000/00000/00</code>
* <code>www.nielsen.com/X100zdCIGeIlgZnkYj6UvQ==/R8WHe7pEBeqBhu8jTeXydg==/AAICoyitYqlxT7n6aZ0oMCGhe<wbr />Fi4CXFp46AMUPZz1lMr_M9tr3_cjee1SHqxrOiVerMDLeyn9xzocZSKwi746Re8vNOtpNCAZjYABs_J0R25IHpvOc1HS8<wbr />QHGgD5TgOJeS6gX100zdCIGeIlgZnkYj6UvVJWFNhSVhTiPE0=/00000/46016/00</code>
<blockquote>'''Note''': ID3 tags are not applicable for International (Germany)</blockquote>

== Browser Opt-Out Implementation ==
The site in which video content is being measure via Nielsen methodology must provide the means for the user to opt-out of, or opt back into Nielsen Measurement.

For Browser-based applications, opt-out setting is stored via Nielsen cookie. Therefore, it is only necessary that users be made aware of measurement opt-out by incorporating the template below in the user interface.

=== Sample Opt Out Template ===
Our properties may feature Nielsen’s proprietary measurement software which will allow to contribute to market research, like Nielsen’s TV Ratings. To learn more about this information, see https://www.nielsen.com/digitalprivacy. Nielsen’s software may collect your choices with regards to it.

== Nielsen Privacy Requirements ==
Privacy protections that Nielsen ensures to have with each App SDK integration are as follows.
*Disclosure of viewership data collection in EULA / Privacy Policy
*A link in the EULA/Privacy policy, or in another conspicuous location within the App, to a Nielsen-hosted web page outlining what Nielsen is collecting and how it is being used
*Method for users to opt-out of Nielsen measurement, any time while using the application

=== Ratings Data Flow ===
Every view of creditable and watermarked content is measured by Nielsen.
[[File:RatingsDataFlow.png]]

'''Information NOT Shared'''
* '''With Nielsen'''
** User's Identity
* '''With Data Provider'''
** Content information
** Whether user is viewing an ad or video content
** Player used to play the streaming (audio / video, etc.)
** Values being de-duped / aggregating for

Nielsen collects only what it needs for audience measurement. Every view of creditable, watermarked content will be measured by Nielsen.

=== Data Collected ===
{| class="wikitable"
|-
! Type of Information !! Parameter !! Transmitted to Nielsen? !! Sent to Provider?
|-
| rowspan="8" | Nielsen ID3 Watermark
|-
| FinalDistributor Timestamp || Yes || No
|-
| Program Content Timestamp || Yes || No
|-
| Mobile Breakout Code || Yes || No
|-
| Commercial Credit Code – Linear or Dynamic || Yes || No
|-
| Time ShiftedViewing Code || Yes || No
|-
| Segment Number || Yes || No
|-
| Segment View Pattern || Yes || No
|-
| rowspan="7" | Device/App Info
|-
| Device OSVersion || Yes || Yes
|-
| Device Model || Yes || No
|-
| Cache Buster || Yes || Yes
|-
| SDKDisabled Flag || Yes || No
|-
| ServerCode || Yes || No
|-
| Channel or URL || Yes || No
|-
| rowspan="9" | Nielsen Identifiers
|-
| Client ID || Yes || No
|-
| Campaign ID || Yes || Yes
|-
| Nielsen Unique Device ID || Yes || No
|-
| Application ID || Yes || No
|-
| DeviceGroup (ex. Tablet, Smartphone, Desktop) || Yes || Yes
|-
| OS Group (ex. Android, iOS, Windows) || Yes || Yes
|-
| SDKVersion || Yes || No
|-
| IP Address for DMA, Country Code || Yes || Yes
|}
<blockquote>'''Note''': Data is hashed, and encrypted using AES 128 before transmission to data provider.</blockquote>

{{Viewability_Data_Collected}}

==== Example ping sent to provider ====
* <code><nowiki>https://provider.com/cgi-bin/brandlift.php</nowiki>?campaign_id=ff12725d724fac7934cf6003f096b4cd<wbr />&placement_id=a4164b8fba9ee7c873a9c72c7091bb58<wbr />&creative_id=25280139b61a947e127a52f56c8a2fdd<wbr />&segment1=9000<wbr />&segment2=41<wbr />&segment3=iOS<wbr />&OSVer=iOS6.1<wbr />&c9=<wbr />&devgrp=tablet<wbr />&h=f5f243fe6d<wbr />&rnd=1376971827360</code>

This ping passes the following parameters to the provider:
* Campaign ID – (campaign, placement, creative)
* Country Code
* DMA
* OS Group (ex. iOS, Android)
* DeviceOS Version
* Device Advertiser ID
* DeviceGroup (ex. Tablet, Smartphone, Desktop)
* Cache Buster

{{Template:Browser_Privacy_and_Opt-Out}}

=== Opt-Out Implementation ===
The site must provide the means for the user to opt-out of, or opt back into Nielsen Measurement.

'''Sample Opt Out Template'''

Our properties may feature Nielsen’s proprietary measurement software which will allow to contribute to market research, like Nielsen’s TV Ratings. To learn more about this information, please [http://priv-policy.imrworldwide.com/priv/mobile/us/en/optout.html| click here]. Nielsen’s software may collect your choices with regards to it.

== Testing ==
See [[Digital Measurement Testing#Testing Browser Implementation|Digital Measurement Testing - Testing Browser Implementation]].

Browser SDK API Reference

2024-12-11T16:27:08Z

AmySockanathan: /* Multiple SDK Instances */

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

== Setting up Development Environment ==
=== Step 1: Configure Content Management System (CMS) ===
Configure CMS to send the required values (see table below). Any internal CMS_variable names can be used for passing the data.

Ensure to capture these CMS_variable names in the SDK Configuration Form.

For more information on setting variable names, see the SDK Configuration Form included within the SDK package.

{| class="wikitable"
|-
! Required Data !! Description !! Value
|-
| dataSrc || Used when both CMS metadata and ID3 data are present in the player. Setting this field tells the SDK whether to use the CMS metadata or the ID3 payload to derive the pings || cms
|-
| type || Type of asset: ad or content || preroll, midroll, postroll, or content
|-
| assetid || unique ID assigned to asset || custom <br>(no [[Special Characters]])
|-
| OCR Tag || OCR tag provided by Nielsen for implementation on the ad unit || Complete OCR URL
|-
| program || Name of program (25 character limit) || custom
|-
| title || Episode title (40 character limit) || custom
|-
| length || Length of content in seconds || Length in seconds, 0 for live stream
|-
| adloadtype || Type of ad load || "1" - Linear "2" - Dynamic(default)
|-
| hasAds || Identify if content includes Ads || "0" - no ads "1" - includes ads "2" - unknown(default)
|-
| isfullepisode || Full episode flag || "y" - full episode "n" - non full episode
|-
| segA || Segment A (this is not available for video reporting as the episode title is reported) || custom value
|-
| segB || Custom segment B || custom value
|-
| segC || Custom segment C || custom value
|-
| crossId1 || Standard episode ID || custom value
|-
| crossId2 || Content originator (required only for distributors) || custom value
|-
| airdate || Original air date and time in Eastern Time. For non-US countries, it should be local time. || YYYYMMDD HH24:MI:SS
|-
| containerId || HTML DOM element of the Player container (for Viewability&Audibility feature only) || custom value
|-
|luid
|Living Unit ID - Experian Household ID
'''Note: This parameter is applicable only for CTV and First Party Livestream data'''
|"B0EOFEDgD"
|}

=== Step 2: Complete the Nielsen SDK Configuration Form ===
The SDK is designed to map the <code>CMS_variable names</code>. To support the custom mapping, the developer is required to complete the SDK Configuration Form. The form will be provided during onboarding along with this guide.

== Initialization ==
=== Obtain the Nielsen Application ID (apid) and Browser SDK URLs ===
The Nielsen <code>apid</code> 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 Browser SDK ===
There are two steps required for configuring the SDK:

'''Add Static Queue Snippet'''

*Add Static Queue Snippet
*Create SDK Instance

Add the following script tag to the website:
<syntaxhighlight lang="javascript">

<script type="text/javascript">
!function(t,n)
{
t[n]=t[n]||
{
nlsQ:function(e,o,c,r,s,i)
{
return s=t.document,
r=s.createElement("script"),
r.async=1,
r.src=("http:"===t.location.protocol?"http:":"https:")+"//cdn-gl.imrworldwide.com/conf/"+e+".js#name="+o+"&ns="+n,
i=s.getElementsByTagName("script")[0],
i.parentNode.insertBefore(r,i),
t[n][o]=t[n][o]||{g:c||{},
ggPM:function(e,c,r,s,i){(t[n][o].q=t[n][o].q||[]).push([e,c,r,s,i])}},t[n][o]
}
}
}
(window,"NOLBUNDLE");
</script>

</syntaxhighlight>

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.

'''Create SDK Instance'''

To initialize the SDK, create an SDK instance by making the initialization call:

'''Initialization API Call'''
<syntaxhighlight lang="javascript">

NOLBUNDLE.nlsQ("<apid>", "<instanceName>",{nol_sdkDebug: "debug"})

</syntaxhighlight>

When creating an instance, pass the following three values:

=== SDK Initialization – Global Parameters ===
{| class="wikitable"
|-
! Parameters !! Description !! Value
|-
| apid || UniqueID assigned to player/site. || 'XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX'
|-
| instanceName || Name of SDK instance || "any string value"
|-
| nol_sdkDebug || Enables Nielsen console logging. Only required for testing || "{nol_sdkDebug: "debug"})"
|-
| containerId || HTML DOM element id of the player container. Only for Viewability & Audibility feature. || {containerId: "playerId1"}
|-
| 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&"
|}

{{example_bsdk_init}}

'''Example SDK Configuration'''

The configuration should include the Static Queue Snippet and an SDK Instance for an unique App ID as shown in the example:

<syntaxhighlight lang="javascript">

<script type="text/javascript">
!function(t,n)
{
t[n]=t[n]||
{
nlsQ:function(e,o,c,r,s,i)
{
return s=t.document,
r=s.createElement("script"),
r.async=1,
r.src=("http:"===t.location.protocol?"http:":"https:")+"//cdn-gl.imrworldwide.com/conf/"+e+".js#name="+o+"&ns="+n,
i=s.getElementsByTagName("script")[0],
i.parentNode.insertBefore(r,i),
t[n][o]=t[n][o]||{g:c||{},
ggPM:function(e,c,r,s,i){(t[n][o].q=t[n][o].q||[]).push([e,c,r,s,i])}},t[n][o]
}
}
}
(window,"NOLBUNDLE");
// Created SDK Instance
var nSdkInstance = NOLBUNDLE.nlsQ("XXXXXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXX","nlsnInstance", {nol_sdkDebug: "debug"});
</script>

</syntaxhighlight>

=== Multiple SDK Instances ===
The Browser SDK allows instantiating multiple instances of the object, which can be used simultaneously without any problems, however they must be instantiated with their own unique instance names. There is no maximum number of instances that is enforced in the browser.

The below examples will make use of the same AppId, however using different AppIds will work as well. The principles below follow the same initialization rules stated above for a single instance and simply require a unique instance name and variable name with which the returned instance is assigned.

For more information around the possible parameters that can be passed as well as deeper descriptions for the API calls, please refer to the section on [[#SDK Initialization - Global Parameters|'''SDK Initialization - Global Parameters''']].

'''Example of 2 instances on the same page'''

<syntaxhighlight lang="javascript">
//Add Static Queue Snippet
<script>
!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.imrworldwide.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");

//Create SDK Instance(s)
// Notice the unique instance name given to each instance below and the unique variable name for each instance
var nSdkInstanceLive = NOLBUNDLE.nlsQ("XXXXXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXX", "instanceLive", {
nol_sdkDebug: 'debug',
optout: 'false'
});

var nSdkInstanceVod = NOLBUNDLE.nlsQ("XXXXXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXX", "instanceVod", {
nol_sdkDebug: 'debug',
optout: 'false'
});

</script>
</syntaxhighlight>

'''Example of 2 instances using a parent page and iFrame'''

<big>Parent Page (index.html)</big>

<syntaxhighlight lang="javascript">
<!DOCTYPE html>
<html lang="en">

<head>
<meta charset="UTF-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<meta http-equiv="X-UA-Compatible" content="ie=edge">
<title>DCR Static/DCR Video</title>
<script>
/* NLSQUEUE build v*/
!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.imrworldwide.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");

// SDK Initialization
var nSdkInstance = NOLBUNDLE.nlsQ("XXXXXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXX", "staticPage", {
nol_sdkDebug: 'debug',
});

// Static Metadata
var staticMetadata = {
assetid: 'staticTestPage',
type: 'static'
};

// Event 'staticstart' call
nSdkInstance.ggPM(14, staticMetadata);
</script>
</head>

<body>
<h1>DCR Static on Parent/DCR Video in iFrame</h1>
<p>Static measurement is current on parent page when window is in focus</p>
<iframe src="./dcr-video.html" frameborder="0" width="650" height="500" style="background-color: rgb(42, 217, 248);" id="video-iframe"></iframe>
</body>

</html>
</syntaxhighlight>

<big>Nested iFrame Referenced on Parent Page (dcr-video.html)</big>

<syntaxhighlight lang="javascript">
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
<meta http-equiv="X-UA-Compatible" content="ie=edge" />
<title>iFrame Same Source</title>
<script>
/* NLSQUEUE build v*/
!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.imrworldwide.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");

// SDK Initialization
var nSdkInstance = NOLBUNDLE.nlsQ("XXXXXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXX", "videoPlayer", {
nol_sdkDebug: 'debug',
});

var contentMetadata = {
type: "content",
length: "300",
title: "Skydiving Across Europe",
program: "latacg",
censuscategory: "Enlisted",
assetid: "204558915992",
section: "ProgramAsset8",
tv: "true",
adModel: "0",
dataSrc: "cms",
segA: "S07E04:NBC",
segB: "teams",
segC:"AtlanataFalcons",
}
</script>
</head>
<body>
<p>I'm iframe SDK DCR Video measurement, DCR static measurement should continue when clicking "play" on video</p>
<main>
<video
controls
src="https://archive.org/download/BigBuckBunny_124/Content/big_buck_bunny_720p_surround.mp4"
poster="https://peach.blender.org/wp-content/uploads/title_anouncement.jpg?x11217"
width="620">
Sorry, your browser doesn't support embedded videos, but don't worry, you can
<a href="https://archive.org/details/BigBuckBunny_124">download it</a>
and watch it with your favorite video player!
</video>
</main>
<script src="../player.js"></script>
</body>
</html>

</syntaxhighlight>

=== SDK Initialization to measure the Viewability & Audibility ===
To support viewability metrics in the web page the integrator has to provide a tag value of the player view to let Nielsen SDK know that there is a player that needs to be tracked. It’s called the ‘containerId’ and it should be passed in the as string while initializing the Nielsen browser SDK.

NOLBUNDLE.nlsQ("<apid>", "<instanceName>",{containerId: <playerElementID>, nol_sdkDebug: "debug"})

'''Example SDK Initialization for Viewability'''

Your configuration should include the Static Queue Snippet and an SDK Instance for your unique App ID as shown in the example:
<syntaxhighlight lang="javascript">
//Add Static Queue Snippet
<script>
! function(t, n) {
t[n] = t[n] || {
nlsQ: function(e, o, c, r, s, i) {
return s = t.document,
r = s.createElement("script"),
r.async = 1,
r.src = ("http:" === t.location.protocol ? "http:" : "https:") + "//cdn-gl.imrworldwide.com/conf/" + e + ".js#name=" + o + "&ns=" + n,
i = s.getElementsByTagName("script")[0],
i.parentNode.insertBefore(r, i),
t[n][o] = t[n][o] || {
g: c || {},
ggPM: function(e, c, r, s, i) {
(t[n][o].q = t[n][o].q || []).push([e, c, r, s, i])
}
}, t[n][o]
}
}
}
(window, "NOLBUNDLE");

//Create SDK Instance
var nSdkInstance = NOLBUNDLE.nlsQ("XXXXXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXX", "nlsnInstance", {containerId: “player1”, nol_sdkDebug: "debug"});
</script>

</syntaxhighlight>

== Browser SDK API Methods & Properties ==
{| class="wikitable sortable"
|-
! Method / Property !! Event # !! DTVR !! DAR !! DCR !! Description
|-
| [[loadMetadata (Browser)|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.
|-
| [[play (Browser)|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”.
|-
| [[sendID3 (Browser)|sendID3]] || 55 || ✔ || ✘ || ✘ || Used to send the ID3 metadata.
|-
| [[setPlayheadPosition (Browser)|setPlayheadPosition]] || 49 || ✘ || ✘ || ✔ || Used to send the playhead position.
|-
| [[stop (Browser)|stop]] || 7 || ✘ || ✘ || ✔ || Used when switching between ad and content or content and ad.
|-
| [[end (Browser)|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
|-
| [[staticstart (Browser)|staticstart]] || 14 || ✘ || ✘ || ✔ || Used to send the metadata for the static page.
|-
| [[StaticEnd (Browser)|staticend]] || 56 || ✘ || ✘ || ✔ || In Single Page Application (SPA) it is imperative that staticend is called prior to the loading of new metadata. This allows the Browser SDK to properly credit the previous section/content being viewed before measuring the new one.
|-
| [[updateOTT (Browser)|updateOTT]] || - || ✘ || ✘ || ✔ || Used to notify Browser SDK that the remote OTT device (like Google ChromeCast, Roku, Amazon FireTV, etc.) is connected / disconnected (change of OTT status).
|-
| [[ onPaginate (Browser)|onPaginate]] || 30 || ✘ || ✘ || ✔ || Used to create a new instance of the SDK object
|-
| [[updateMetadata (Browser)|updateMetadata]] || 35 || ✔ || ✔ || ✔ || This event is used for updating metadata parameters for the content or ad that is being played.
|-
| [[setVolume_(Browser)|setVolume]] || 61 || ✔ || ✘ || ✔ || Used to pass in the player volume levels in %. Default value is -1.
|}

== Retrieving ID3 Tags ==
The video player must have the ability to extract ID3 tags and supply them to the Browser SDK, based on the HLS standard.
*An ID3 tag spans two PES packets.
**In the first PES packet, look for www.nielsen.com, this is the start of the ID3 tag. Continue to parse the first PES packet until the undefined char "\ufffd" is found. This forms the first half of the ID3 tag
**In the second PES packet, identify the end pattern – a regEx of /(\/\d+){3}/ and look to remove the lowest index of either "\x00" and/or "\ufffd". Now the second packet has been appended and the demarcation of the Nielsen-specific data has been defined.

Follow the procedure below, to extract Nielsen ID3 tags from an MPEG-2 transport stream (including HLS streams).
#Parse the Program Map Table (PMT) to find the PID of the metadata stream. Confirm the presence of the metadata descriptor described in section 2.3.3 of Apple’s “HTTP Live Streaming Metadata Spec.pdf”. Only private streams with metadata descriptor present should be considered as ID3-tag metadata streams.
#Parse the HLS/Transport stream for any '''PES header''' with the PID found in step 1.
#Follow standard MPEG-2 parsing procedures to locate the start of the payload of the PES packet.
#Copy the PES payload into a buffer.
#The ID3 tag spans 2 PES packets. Parse the stream for the next packet whose PID is set to the PID found in step 1. Typically the ID3 Tag is of 249 bytes. The steps below guide towards extraction of the ID3 tag
##In the first PES packet, look for "www.nielsen.com" , this is the start of the ID3 tag. Keep on parsing the first PES packet until the undefined char "\ufffd" is found. This forms the first half of the ID3 tag
##In the second PES packet, identify the end pattern, a regEx of /(\/\d+){3}/ and look to remove the lowest index of either “\x00” and/or “\ufffd”. Now the second packet has been appended and the demarcation of the Nielsen specific data has been defined. This segment can be simply substringed.
##Concatenate this substringed segment with the payload derived from the first packet get the ID3 payload.
#Check the length of the contents in the buffer to make sure that it is equal to the size of a Nielsen ID3 tag.
#Ensure that the ID3 byte array is converted into the string and escape it, so that the SDK can consume it.
Repeat steps 2 through 7 for all ID3 tags in the stream.

'''References'''
*[http://www.iso.org/iso/catalogue_detail?csnumber=44169. ISO/IEC 13818-1:2007] Information technology – Generic coding of moving pictures and associated audio information: Systems
*https://developer.apple.com/library/content/documentation/AudioVideo/Conceptual/HTTP_Live_Streaming_Metadata_Spec/

=== Sample ID3 tags ===
* <code>www.nielsen.com/X100zdCIGeIlgZnkYj6UvQ==/X100zdCIGeIlgZnkYj6UvQ==/AAAB2Jz2_k74GXSzx4npHuI_<wbr />JwJd3QSUpW30rDkGTcbHEzIMWleCzM-uvNOP9fzJcQMWQLJqzXMCAxParOb5sGijSV9dNM3QiBniJYGZ5GI-lL1fXTTN0IgZ4iWBmeRiPpS9AAAAAAAAAAAAAAAAAAAAAFJWFM5SVhTONNU=/00000/00000/00</code>
* <code>www.nielsen.com/X100zdCIGeIlgZnkYj6UvQ==/R8WHe7pEBeqBhu8jTeXydg==/AAICoyitYqlxT7n6aZ0oMCGhe<wbr />Fi4CXFp46AMUPZz1lMr_M9tr3_cjee1SHqxrOiVerMDLeyn9xzocZSKwi746Re8vNOtpNCAZjYABs_J0R25IHpvOc1HS8<wbr />QHGgD5TgOJeS6gX100zdCIGeIlgZnkYj6UvVJWFNhSVhTiPE0=/00000/46016/00</code>
<blockquote>'''Note''': ID3 tags are not applicable for International (Germany)</blockquote>

== Browser Opt-Out Implementation ==
The site in which video content is being measure via Nielsen methodology must provide the means for the user to opt-out of, or opt back into Nielsen Measurement.

For Browser-based applications, opt-out setting is stored via Nielsen cookie. Therefore, it is only necessary that users be made aware of measurement opt-out by incorporating the template below in the user interface.

=== Sample Opt Out Template ===
Our properties may feature Nielsen’s proprietary measurement software which will allow to contribute to market research, like Nielsen’s TV Ratings. To learn more about this information, see https://www.nielsen.com/digitalprivacy. Nielsen’s software may collect your choices with regards to it.

== Nielsen Privacy Requirements ==
Privacy protections that Nielsen ensures to have with each App SDK integration are as follows.
*Disclosure of viewership data collection in EULA / Privacy Policy
*A link in the EULA/Privacy policy, or in another conspicuous location within the App, to a Nielsen-hosted web page outlining what Nielsen is collecting and how it is being used
*Method for users to opt-out of Nielsen measurement, any time while using the application

=== Ratings Data Flow ===
Every view of creditable and watermarked content is measured by Nielsen.
[[File:RatingsDataFlow.png]]

'''Information NOT Shared'''
* '''With Nielsen'''
** User's Identity
* '''With Data Provider'''
** Content information
** Whether user is viewing an ad or video content
** Player used to play the streaming (audio / video, etc.)
** Values being de-duped / aggregating for

Nielsen collects only what it needs for audience measurement. Every view of creditable, watermarked content will be measured by Nielsen.

=== Data Collected ===
{| class="wikitable"
|-
! Type of Information !! Parameter !! Transmitted to Nielsen? !! Sent to Provider?
|-
| rowspan="8" | Nielsen ID3 Watermark
|-
| FinalDistributor Timestamp || Yes || No
|-
| Program Content Timestamp || Yes || No
|-
| Mobile Breakout Code || Yes || No
|-
| Commercial Credit Code – Linear or Dynamic || Yes || No
|-
| Time ShiftedViewing Code || Yes || No
|-
| Segment Number || Yes || No
|-
| Segment View Pattern || Yes || No
|-
| rowspan="7" | Device/App Info
|-
| Device OSVersion || Yes || Yes
|-
| Device Model || Yes || No
|-
| Cache Buster || Yes || Yes
|-
| SDKDisabled Flag || Yes || No
|-
| ServerCode || Yes || No
|-
| Channel or URL || Yes || No
|-
| rowspan="9" | Nielsen Identifiers
|-
| Client ID || Yes || No
|-
| Campaign ID || Yes || Yes
|-
| Nielsen Unique Device ID || Yes || No
|-
| Application ID || Yes || No
|-
| DeviceGroup (ex. Tablet, Smartphone, Desktop) || Yes || Yes
|-
| OS Group (ex. Android, iOS, Windows) || Yes || Yes
|-
| SDKVersion || Yes || No
|-
| IP Address for DMA, Country Code || Yes || Yes
|}
<blockquote>'''Note''': Data is hashed, and encrypted using AES 128 before transmission to data provider.</blockquote>

{{Viewability_Data_Collected}}

==== Example ping sent to provider ====
* <code><nowiki>https://provider.com/cgi-bin/brandlift.php</nowiki>?campaign_id=ff12725d724fac7934cf6003f096b4cd<wbr />&placement_id=a4164b8fba9ee7c873a9c72c7091bb58<wbr />&creative_id=25280139b61a947e127a52f56c8a2fdd<wbr />&segment1=9000<wbr />&segment2=41<wbr />&segment3=iOS<wbr />&OSVer=iOS6.1<wbr />&c9=<wbr />&devgrp=tablet<wbr />&h=f5f243fe6d<wbr />&rnd=1376971827360</code>

This ping passes the following parameters to the provider:
* Campaign ID – (campaign, placement, creative)
* Country Code
* DMA
* OS Group (ex. iOS, Android)
* DeviceOS Version
* Device Advertiser ID
* DeviceGroup (ex. Tablet, Smartphone, Desktop)
* Cache Buster

{{Template:Browser_Privacy_and_Opt-Out}}

=== Opt-Out Implementation ===
The site must provide the means for the user to opt-out of, or opt back into Nielsen Measurement.

'''Sample Opt Out Template'''

Our properties may feature Nielsen’s proprietary measurement software which will allow to contribute to market research, like Nielsen’s TV Ratings. To learn more about this information, please [http://priv-policy.imrworldwide.com/priv/mobile/us/en/optout.html| click here]. Nielsen’s software may collect your choices with regards to it.

== Testing ==
See [[Digital Measurement Testing#Testing Browser Implementation|Digital Measurement Testing - Testing Browser Implementation]].

Browser SDK API Reference

2024-12-10T18:04:18Z

AmySockanathan: /* Multiple SDK Instances */

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

== Setting up Development Environment ==
=== Step 1: Configure Content Management System (CMS) ===
Configure CMS to send the required values (see table below). Any internal CMS_variable names can be used for passing the data.

Ensure to capture these CMS_variable names in the SDK Configuration Form.

For more information on setting variable names, see the SDK Configuration Form included within the SDK package.

{| class="wikitable"
|-
! Required Data !! Description !! Value
|-
| dataSrc || Used when both CMS metadata and ID3 data are present in the player. Setting this field tells the SDK whether to use the CMS metadata or the ID3 payload to derive the pings || cms
|-
| type || Type of asset: ad or content || preroll, midroll, postroll, or content
|-
| assetid || unique ID assigned to asset || custom <br>(no [[Special Characters]])
|-
| OCR Tag || OCR tag provided by Nielsen for implementation on the ad unit || Complete OCR URL
|-
| program || Name of program (25 character limit) || custom
|-
| title || Episode title (40 character limit) || custom
|-
| length || Length of content in seconds || Length in seconds, 0 for live stream
|-
| adloadtype || Type of ad load || "1" - Linear "2" - Dynamic(default)
|-
| hasAds || Identify if content includes Ads || "0" - no ads "1" - includes ads "2" - unknown(default)
|-
| isfullepisode || Full episode flag || "y" - full episode "n" - non full episode
|-
| segA || Segment A (this is not available for video reporting as the episode title is reported) || custom value
|-
| segB || Custom segment B || custom value
|-
| segC || Custom segment C || custom value
|-
| crossId1 || Standard episode ID || custom value
|-
| crossId2 || Content originator (required only for distributors) || custom value
|-
| airdate || Original air date and time in Eastern Time. For non-US countries, it should be local time. || YYYYMMDD HH24:MI:SS
|-
| containerId || HTML DOM element of the Player container (for Viewability&Audibility feature only) || custom value
|-
|luid
|Living Unit ID - Experian Household ID
'''Note: This parameter is applicable only for CTV and First Party Livestream data'''
|"B0EOFEDgD"
|}

=== Step 2: Complete the Nielsen SDK Configuration Form ===
The SDK is designed to map the <code>CMS_variable names</code>. To support the custom mapping, the developer is required to complete the SDK Configuration Form. The form will be provided during onboarding along with this guide.

== Initialization ==
=== Obtain the Nielsen Application ID (apid) and Browser SDK URLs ===
The Nielsen <code>apid</code> 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 Browser SDK ===
There are two steps required for configuring the SDK:

'''Add Static Queue Snippet'''

*Add Static Queue Snippet
*Create SDK Instance

Add the following script tag to the website:
<syntaxhighlight lang="javascript">

<script type="text/javascript">
!function(t,n)
{
t[n]=t[n]||
{
nlsQ:function(e,o,c,r,s,i)
{
return s=t.document,
r=s.createElement("script"),
r.async=1,
r.src=("http:"===t.location.protocol?"http:":"https:")+"//cdn-gl.imrworldwide.com/conf/"+e+".js#name="+o+"&ns="+n,
i=s.getElementsByTagName("script")[0],
i.parentNode.insertBefore(r,i),
t[n][o]=t[n][o]||{g:c||{},
ggPM:function(e,c,r,s,i){(t[n][o].q=t[n][o].q||[]).push([e,c,r,s,i])}},t[n][o]
}
}
}
(window,"NOLBUNDLE");
</script>

</syntaxhighlight>

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.

'''Create SDK Instance'''

To initialize the SDK, create an SDK instance by making the initialization call:

'''Initialization API Call'''
<syntaxhighlight lang="javascript">

NOLBUNDLE.nlsQ("<apid>", "<instanceName>",{nol_sdkDebug: "debug"})

</syntaxhighlight>

When creating an instance, pass the following three values:

=== SDK Initialization – Global Parameters ===
{| class="wikitable"
|-
! Parameters !! Description !! Value
|-
| apid || UniqueID assigned to player/site. || 'XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX'
|-
| instanceName || Name of SDK instance || "any string value"
|-
| nol_sdkDebug || Enables Nielsen console logging. Only required for testing || "{nol_sdkDebug: "debug"})"
|-
| containerId || HTML DOM element id of the player container. Only for Viewability & Audibility feature. || {containerId: "playerId1"}
|-
| 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&"
|}

{{example_bsdk_init}}

'''Example SDK Configuration'''

The configuration should include the Static Queue Snippet and an SDK Instance for an unique App ID as shown in the example:

<syntaxhighlight lang="javascript">

<script type="text/javascript">
!function(t,n)
{
t[n]=t[n]||
{
nlsQ:function(e,o,c,r,s,i)
{
return s=t.document,
r=s.createElement("script"),
r.async=1,
r.src=("http:"===t.location.protocol?"http:":"https:")+"//cdn-gl.imrworldwide.com/conf/"+e+".js#name="+o+"&ns="+n,
i=s.getElementsByTagName("script")[0],
i.parentNode.insertBefore(r,i),
t[n][o]=t[n][o]||{g:c||{},
ggPM:function(e,c,r,s,i){(t[n][o].q=t[n][o].q||[]).push([e,c,r,s,i])}},t[n][o]
}
}
}
(window,"NOLBUNDLE");
// Created SDK Instance
var nSdkInstance = NOLBUNDLE.nlsQ("XXXXXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXX","nlsnInstance", {nol_sdkDebug: "debug"});
</script>

</syntaxhighlight>

=== Multiple SDK Instances ===
The Browser SDK allows instantiating multiple instances of the object, which can be used simultaneously without any problems, however they must be instantiated with their own unique instance names. There is no maximum number of instances that is enforced in the browser.

The below examples will make use of the same AppId, however using different AppIds will work as well. The principles below follow the same initialization rules stated above for a single instance and simply require a unique instance name and variable name with which the returned instance is assigned.

For more information around the possible parameters that can be passed as well as deeper descriptions for the API calls, please refer to the section on [[Browser SDK API Reference#SDK Initialization - Global Parameters|SDK Initialization - Global Parameters]].

'''Example of 2 instances on the same page'''

<syntaxhighlight lang="javascript">
//Add Static Queue Snippet
<script>
!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.imrworldwide.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");

//Create SDK Instance(s)
// Notice the unique instance name given to each instance below and the unique variable name for each instance
var nSdkInstanceLive = NOLBUNDLE.nlsQ("XXXXXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXX", "instanceLive", {
nol_sdkDebug: 'debug',
optout: 'false'
});

var nSdkInstanceVod = NOLBUNDLE.nlsQ("XXXXXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXX", "instanceVod", {
nol_sdkDebug: 'debug',
optout: 'false'
});

</script>
</syntaxhighlight>

'''Example of 2 instances using a parent page and iFrame'''

<big>Parent Page (index.html)</big>

<syntaxhighlight lang="javascript">
<!DOCTYPE html>
<html lang="en">

<head>
<meta charset="UTF-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<meta http-equiv="X-UA-Compatible" content="ie=edge">
<title>DCR Static/DCR Video</title>
<script>
/* NLSQUEUE build v*/
!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.imrworldwide.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");

// SDK Initialization
var nSdkInstance = NOLBUNDLE.nlsQ("XXXXXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXX", "staticPage", {
nol_sdkDebug: 'debug',
});

// Static Metadata
var staticMetadata = {
assetid: 'staticTestPage',
type: 'static'
};

// Event 'staticstart' call
nSdkInstance.ggPM(14, staticMetadata);
</script>
</head>

<body>
<h1>DCR Static on Parent/DCR Video in iFrame</h1>
<p>Static measurement is current on parent page when window is in focus</p>
<iframe src="./dcr-video.html" frameborder="0" width="650" height="500" style="background-color: rgb(42, 217, 248);" id="video-iframe"></iframe>
</body>

</html>
</syntaxhighlight>

<big>Nested iFrame Referenced on Parent Page (dcr-video.html)</big>

<syntaxhighlight lang="javascript">
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
<meta http-equiv="X-UA-Compatible" content="ie=edge" />
<title>iFrame Same Source</title>
<script>
/* NLSQUEUE build v*/
!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.imrworldwide.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");

// SDK Initialization
var nSdkInstance = NOLBUNDLE.nlsQ("XXXXXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXX", "videoPlayer", {
nol_sdkDebug: 'debug',
});

var contentMetadata = {
type: "content",
length: "300",
title: "Skydiving Across Europe",
program: "latacg",
censuscategory: "Enlisted",
assetid: "204558915992",
section: "ProgramAsset8",
tv: "true",
adModel: "0",
dataSrc: "cms",
segA: "S07E04:NBC",
segB: "teams",
segC:"AtlanataFalcons",
}
</script>
</head>
<body>
<p>I'm iframe SDK DCR Video measurement, DCR static measurement should continue when clicking "play" on video</p>
<main>
<video
controls
src="https://archive.org/download/BigBuckBunny_124/Content/big_buck_bunny_720p_surround.mp4"
poster="https://peach.blender.org/wp-content/uploads/title_anouncement.jpg?x11217"
width="620">
Sorry, your browser doesn't support embedded videos, but don't worry, you can
<a href="https://archive.org/details/BigBuckBunny_124">download it</a>
and watch it with your favorite video player!
</video>
</main>
<script src="../player.js"></script>
</body>
</html>

</syntaxhighlight>

=== SDK Initialization to measure the Viewability & Audibility ===
To support viewability metrics in the web page the integrator has to provide a tag value of the player view to let Nielsen SDK know that there is a player that needs to be tracked. It’s called the ‘containerId’ and it should be passed in the as string while initializing the Nielsen browser SDK.

NOLBUNDLE.nlsQ("<apid>", "<instanceName>",{containerId: <playerElementID>, nol_sdkDebug: "debug"})

'''Example SDK Initialization for Viewability'''

Your configuration should include the Static Queue Snippet and an SDK Instance for your unique App ID as shown in the example:
<syntaxhighlight lang="javascript">
//Add Static Queue Snippet
<script>
! function(t, n) {
t[n] = t[n] || {
nlsQ: function(e, o, c, r, s, i) {
return s = t.document,
r = s.createElement("script"),
r.async = 1,
r.src = ("http:" === t.location.protocol ? "http:" : "https:") + "//cdn-gl.imrworldwide.com/conf/" + e + ".js#name=" + o + "&ns=" + n,
i = s.getElementsByTagName("script")[0],
i.parentNode.insertBefore(r, i),
t[n][o] = t[n][o] || {
g: c || {},
ggPM: function(e, c, r, s, i) {
(t[n][o].q = t[n][o].q || []).push([e, c, r, s, i])
}
}, t[n][o]
}
}
}
(window, "NOLBUNDLE");

//Create SDK Instance
var nSdkInstance = NOLBUNDLE.nlsQ("XXXXXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXX", "nlsnInstance", {containerId: “player1”, nol_sdkDebug: "debug"});
</script>

</syntaxhighlight>

== Browser SDK API Methods & Properties ==
{| class="wikitable sortable"
|-
! Method / Property !! Event # !! DTVR !! DAR !! DCR !! Description
|-
| [[loadMetadata (Browser)|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.
|-
| [[play (Browser)|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”.
|-
| [[sendID3 (Browser)|sendID3]] || 55 || ✔ || ✘ || ✘ || Used to send the ID3 metadata.
|-
| [[setPlayheadPosition (Browser)|setPlayheadPosition]] || 49 || ✘ || ✘ || ✔ || Used to send the playhead position.
|-
| [[stop (Browser)|stop]] || 7 || ✘ || ✘ || ✔ || Used when switching between ad and content or content and ad.
|-
| [[end (Browser)|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
|-
| [[staticstart (Browser)|staticstart]] || 14 || ✘ || ✘ || ✔ || Used to send the metadata for the static page.
|-
| [[StaticEnd (Browser)|staticend]] || 56 || ✘ || ✘ || ✔ || In Single Page Application (SPA) it is imperative that staticend is called prior to the loading of new metadata. This allows the Browser SDK to properly credit the previous section/content being viewed before measuring the new one.
|-
| [[updateOTT (Browser)|updateOTT]] || - || ✘ || ✘ || ✔ || Used to notify Browser SDK that the remote OTT device (like Google ChromeCast, Roku, Amazon FireTV, etc.) is connected / disconnected (change of OTT status).
|-
| [[ onPaginate (Browser)|onPaginate]] || 30 || ✘ || ✘ || ✔ || Used to create a new instance of the SDK object
|-
| [[updateMetadata (Browser)|updateMetadata]] || 35 || ✔ || ✔ || ✔ || This event is used for updating metadata parameters for the content or ad that is being played.
|-
| [[setVolume_(Browser)|setVolume]] || 61 || ✔ || ✘ || ✔ || Used to pass in the player volume levels in %. Default value is -1.
|}

== Retrieving ID3 Tags ==
The video player must have the ability to extract ID3 tags and supply them to the Browser SDK, based on the HLS standard.
*An ID3 tag spans two PES packets.
**In the first PES packet, look for www.nielsen.com, this is the start of the ID3 tag. Continue to parse the first PES packet until the undefined char "\ufffd" is found. This forms the first half of the ID3 tag
**In the second PES packet, identify the end pattern – a regEx of /(\/\d+){3}/ and look to remove the lowest index of either "\x00" and/or "\ufffd". Now the second packet has been appended and the demarcation of the Nielsen-specific data has been defined.

Follow the procedure below, to extract Nielsen ID3 tags from an MPEG-2 transport stream (including HLS streams).
#Parse the Program Map Table (PMT) to find the PID of the metadata stream. Confirm the presence of the metadata descriptor described in section 2.3.3 of Apple’s “HTTP Live Streaming Metadata Spec.pdf”. Only private streams with metadata descriptor present should be considered as ID3-tag metadata streams.
#Parse the HLS/Transport stream for any '''PES header''' with the PID found in step 1.
#Follow standard MPEG-2 parsing procedures to locate the start of the payload of the PES packet.
#Copy the PES payload into a buffer.
#The ID3 tag spans 2 PES packets. Parse the stream for the next packet whose PID is set to the PID found in step 1. Typically the ID3 Tag is of 249 bytes. The steps below guide towards extraction of the ID3 tag
##In the first PES packet, look for "www.nielsen.com" , this is the start of the ID3 tag. Keep on parsing the first PES packet until the undefined char "\ufffd" is found. This forms the first half of the ID3 tag
##In the second PES packet, identify the end pattern, a regEx of /(\/\d+){3}/ and look to remove the lowest index of either “\x00” and/or “\ufffd”. Now the second packet has been appended and the demarcation of the Nielsen specific data has been defined. This segment can be simply substringed.
##Concatenate this substringed segment with the payload derived from the first packet get the ID3 payload.
#Check the length of the contents in the buffer to make sure that it is equal to the size of a Nielsen ID3 tag.
#Ensure that the ID3 byte array is converted into the string and escape it, so that the SDK can consume it.
Repeat steps 2 through 7 for all ID3 tags in the stream.

'''References'''
*[http://www.iso.org/iso/catalogue_detail?csnumber=44169. ISO/IEC 13818-1:2007] Information technology – Generic coding of moving pictures and associated audio information: Systems
*https://developer.apple.com/library/content/documentation/AudioVideo/Conceptual/HTTP_Live_Streaming_Metadata_Spec/

=== Sample ID3 tags ===
* <code>www.nielsen.com/X100zdCIGeIlgZnkYj6UvQ==/X100zdCIGeIlgZnkYj6UvQ==/AAAB2Jz2_k74GXSzx4npHuI_<wbr />JwJd3QSUpW30rDkGTcbHEzIMWleCzM-uvNOP9fzJcQMWQLJqzXMCAxParOb5sGijSV9dNM3QiBniJYGZ5GI-lL1fXTTN0IgZ4iWBmeRiPpS9AAAAAAAAAAAAAAAAAAAAAFJWFM5SVhTONNU=/00000/00000/00</code>
* <code>www.nielsen.com/X100zdCIGeIlgZnkYj6UvQ==/R8WHe7pEBeqBhu8jTeXydg==/AAICoyitYqlxT7n6aZ0oMCGhe<wbr />Fi4CXFp46AMUPZz1lMr_M9tr3_cjee1SHqxrOiVerMDLeyn9xzocZSKwi746Re8vNOtpNCAZjYABs_J0R25IHpvOc1HS8<wbr />QHGgD5TgOJeS6gX100zdCIGeIlgZnkYj6UvVJWFNhSVhTiPE0=/00000/46016/00</code>
<blockquote>'''Note''': ID3 tags are not applicable for International (Germany)</blockquote>

== Browser Opt-Out Implementation ==
The site in which video content is being measure via Nielsen methodology must provide the means for the user to opt-out of, or opt back into Nielsen Measurement.

For Browser-based applications, opt-out setting is stored via Nielsen cookie. Therefore, it is only necessary that users be made aware of measurement opt-out by incorporating the template below in the user interface.

=== Sample Opt Out Template ===
Our properties may feature Nielsen’s proprietary measurement software which will allow to contribute to market research, like Nielsen’s TV Ratings. To learn more about this information, see https://www.nielsen.com/digitalprivacy. Nielsen’s software may collect your choices with regards to it.

== Nielsen Privacy Requirements ==
Privacy protections that Nielsen ensures to have with each App SDK integration are as follows.
*Disclosure of viewership data collection in EULA / Privacy Policy
*A link in the EULA/Privacy policy, or in another conspicuous location within the App, to a Nielsen-hosted web page outlining what Nielsen is collecting and how it is being used
*Method for users to opt-out of Nielsen measurement, any time while using the application

=== Ratings Data Flow ===
Every view of creditable and watermarked content is measured by Nielsen.
[[File:RatingsDataFlow.png]]

'''Information NOT Shared'''
* '''With Nielsen'''
** User's Identity
* '''With Data Provider'''
** Content information
** Whether user is viewing an ad or video content
** Player used to play the streaming (audio / video, etc.)
** Values being de-duped / aggregating for

Nielsen collects only what it needs for audience measurement. Every view of creditable, watermarked content will be measured by Nielsen.

=== Data Collected ===
{| class="wikitable"
|-
! Type of Information !! Parameter !! Transmitted to Nielsen? !! Sent to Provider?
|-
| rowspan="8" | Nielsen ID3 Watermark
|-
| FinalDistributor Timestamp || Yes || No
|-
| Program Content Timestamp || Yes || No
|-
| Mobile Breakout Code || Yes || No
|-
| Commercial Credit Code – Linear or Dynamic || Yes || No
|-
| Time ShiftedViewing Code || Yes || No
|-
| Segment Number || Yes || No
|-
| Segment View Pattern || Yes || No
|-
| rowspan="7" | Device/App Info
|-
| Device OSVersion || Yes || Yes
|-
| Device Model || Yes || No
|-
| Cache Buster || Yes || Yes
|-
| SDKDisabled Flag || Yes || No
|-
| ServerCode || Yes || No
|-
| Channel or URL || Yes || No
|-
| rowspan="9" | Nielsen Identifiers
|-
| Client ID || Yes || No
|-
| Campaign ID || Yes || Yes
|-
| Nielsen Unique Device ID || Yes || No
|-
| Application ID || Yes || No
|-
| DeviceGroup (ex. Tablet, Smartphone, Desktop) || Yes || Yes
|-
| OS Group (ex. Android, iOS, Windows) || Yes || Yes
|-
| SDKVersion || Yes || No
|-
| IP Address for DMA, Country Code || Yes || Yes
|}
<blockquote>'''Note''': Data is hashed, and encrypted using AES 128 before transmission to data provider.</blockquote>

{{Viewability_Data_Collected}}

==== Example ping sent to provider ====
* <code><nowiki>https://provider.com/cgi-bin/brandlift.php</nowiki>?campaign_id=ff12725d724fac7934cf6003f096b4cd<wbr />&placement_id=a4164b8fba9ee7c873a9c72c7091bb58<wbr />&creative_id=25280139b61a947e127a52f56c8a2fdd<wbr />&segment1=9000<wbr />&segment2=41<wbr />&segment3=iOS<wbr />&OSVer=iOS6.1<wbr />&c9=<wbr />&devgrp=tablet<wbr />&h=f5f243fe6d<wbr />&rnd=1376971827360</code>

This ping passes the following parameters to the provider:
* Campaign ID – (campaign, placement, creative)
* Country Code
* DMA
* OS Group (ex. iOS, Android)
* DeviceOS Version
* Device Advertiser ID
* DeviceGroup (ex. Tablet, Smartphone, Desktop)
* Cache Buster

{{Template:Browser_Privacy_and_Opt-Out}}

=== Opt-Out Implementation ===
The site must provide the means for the user to opt-out of, or opt back into Nielsen Measurement.

'''Sample Opt Out Template'''

Our properties may feature Nielsen’s proprietary measurement software which will allow to contribute to market research, like Nielsen’s TV Ratings. To learn more about this information, please [http://priv-policy.imrworldwide.com/priv/mobile/us/en/optout.html| click here]. Nielsen’s software may collect your choices with regards to it.

== Testing ==
See [[Digital Measurement Testing#Testing Browser Implementation|Digital Measurement Testing - Testing Browser Implementation]].

Browser SDK API Reference

2024-12-10T18:01:28Z

AmySockanathan: Multiple SDK instances

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

== Setting up Development Environment ==
=== Step 1: Configure Content Management System (CMS) ===
Configure CMS to send the required values (see table below). Any internal CMS_variable names can be used for passing the data.

Ensure to capture these CMS_variable names in the SDK Configuration Form.

For more information on setting variable names, see the SDK Configuration Form included within the SDK package.

{| class="wikitable"
|-
! Required Data !! Description !! Value
|-
| dataSrc || Used when both CMS metadata and ID3 data are present in the player. Setting this field tells the SDK whether to use the CMS metadata or the ID3 payload to derive the pings || cms
|-
| type || Type of asset: ad or content || preroll, midroll, postroll, or content
|-
| assetid || unique ID assigned to asset || custom <br>(no [[Special Characters]])
|-
| OCR Tag || OCR tag provided by Nielsen for implementation on the ad unit || Complete OCR URL
|-
| program || Name of program (25 character limit) || custom
|-
| title || Episode title (40 character limit) || custom
|-
| length || Length of content in seconds || Length in seconds, 0 for live stream
|-
| adloadtype || Type of ad load || "1" - Linear "2" - Dynamic(default)
|-
| hasAds || Identify if content includes Ads || "0" - no ads "1" - includes ads "2" - unknown(default)
|-
| isfullepisode || Full episode flag || "y" - full episode "n" - non full episode
|-
| segA || Segment A (this is not available for video reporting as the episode title is reported) || custom value
|-
| segB || Custom segment B || custom value
|-
| segC || Custom segment C || custom value
|-
| crossId1 || Standard episode ID || custom value
|-
| crossId2 || Content originator (required only for distributors) || custom value
|-
| airdate || Original air date and time in Eastern Time. For non-US countries, it should be local time. || YYYYMMDD HH24:MI:SS
|-
| containerId || HTML DOM element of the Player container (for Viewability&Audibility feature only) || custom value
|-
|luid
|Living Unit ID - Experian Household ID
'''Note: This parameter is applicable only for CTV and First Party Livestream data'''
|"B0EOFEDgD"
|}

=== Step 2: Complete the Nielsen SDK Configuration Form ===
The SDK is designed to map the <code>CMS_variable names</code>. To support the custom mapping, the developer is required to complete the SDK Configuration Form. The form will be provided during onboarding along with this guide.

== Initialization ==
=== Obtain the Nielsen Application ID (apid) and Browser SDK URLs ===
The Nielsen <code>apid</code> 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 Browser SDK ===
There are two steps required for configuring the SDK:

'''Add Static Queue Snippet'''

*Add Static Queue Snippet
*Create SDK Instance

Add the following script tag to the website:
<syntaxhighlight lang="javascript">

<script type="text/javascript">
!function(t,n)
{
t[n]=t[n]||
{
nlsQ:function(e,o,c,r,s,i)
{
return s=t.document,
r=s.createElement("script"),
r.async=1,
r.src=("http:"===t.location.protocol?"http:":"https:")+"//cdn-gl.imrworldwide.com/conf/"+e+".js#name="+o+"&ns="+n,
i=s.getElementsByTagName("script")[0],
i.parentNode.insertBefore(r,i),
t[n][o]=t[n][o]||{g:c||{},
ggPM:function(e,c,r,s,i){(t[n][o].q=t[n][o].q||[]).push([e,c,r,s,i])}},t[n][o]
}
}
}
(window,"NOLBUNDLE");
</script>

</syntaxhighlight>

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.

'''Create SDK Instance'''

To initialize the SDK, create an SDK instance by making the initialization call:

'''Initialization API Call'''
<syntaxhighlight lang="javascript">

NOLBUNDLE.nlsQ("<apid>", "<instanceName>",{nol_sdkDebug: "debug"})

</syntaxhighlight>

When creating an instance, pass the following three values:

=== SDK Initialization – Global Parameters ===
{| class="wikitable"
|-
! Parameters !! Description !! Value
|-
| apid || UniqueID assigned to player/site. || 'XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX'
|-
| instanceName || Name of SDK instance || "any string value"
|-
| nol_sdkDebug || Enables Nielsen console logging. Only required for testing || "{nol_sdkDebug: "debug"})"
|-
| containerId || HTML DOM element id of the player container. Only for Viewability & Audibility feature. || {containerId: "playerId1"}
|-
| 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&"
|}

{{example_bsdk_init}}

'''Example SDK Configuration'''

The configuration should include the Static Queue Snippet and an SDK Instance for an unique App ID as shown in the example:

<syntaxhighlight lang="javascript">

<script type="text/javascript">
!function(t,n)
{
t[n]=t[n]||
{
nlsQ:function(e,o,c,r,s,i)
{
return s=t.document,
r=s.createElement("script"),
r.async=1,
r.src=("http:"===t.location.protocol?"http:":"https:")+"//cdn-gl.imrworldwide.com/conf/"+e+".js#name="+o+"&ns="+n,
i=s.getElementsByTagName("script")[0],
i.parentNode.insertBefore(r,i),
t[n][o]=t[n][o]||{g:c||{},
ggPM:function(e,c,r,s,i){(t[n][o].q=t[n][o].q||[]).push([e,c,r,s,i])}},t[n][o]
}
}
}
(window,"NOLBUNDLE");
// Created SDK Instance
var nSdkInstance = NOLBUNDLE.nlsQ("XXXXXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXX","nlsnInstance", {nol_sdkDebug: "debug"});
</script>

</syntaxhighlight>

=== Multiple SDK Instances ===
The Browser SDK allows instantiating multiple instances of the object, which can be used simultaneously without any problems, however they must be instantiated with their own unique instance names. There is no maximum number of instances that is enforced in the browser.

The below examples will make use of the same AppId, however using different AppIds will work as well. The principles below follow the same initialization rules stated above for a single instance and simply require a unique instance name and variable name with which the returned instance is assigned.

For more information around the possible parameters that can be passed as well as deeper descriptions for the API calls, please refer to the section on " [[Browser SDK API Reference#SDK Initialization - Global Parameters|SDK Initialization - Global Parameters]]".

'''Example of 2 instances on the same page'''

<syntaxhighlight lang="javascript">
//Add Static Queue Snippet
<script>
!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.imrworldwide.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");

//Create SDK Instance(s)
// Notice the unique instance name given to each instance below and the unique variable name for each instance
var nSdkInstanceLive = NOLBUNDLE.nlsQ("XXXXXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXX", "instanceLive", {
nol_sdkDebug: 'debug',
optout: 'false'
});

var nSdkInstanceVod = NOLBUNDLE.nlsQ("XXXXXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXX", "instanceVod", {
nol_sdkDebug: 'debug',
optout: 'false'
});

</script>
</syntaxhighlight>

'''Example of 2 instances using a parent page and iFrame'''

<big>Parent Page (index.html)</big>

<syntaxhighlight lang="javascript">
<!DOCTYPE html>
<html lang="en">

<head>
<meta charset="UTF-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<meta http-equiv="X-UA-Compatible" content="ie=edge">
<title>DCR Static/DCR Video</title>
<script>
/* NLSQUEUE build v*/
!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.imrworldwide.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");

// SDK Initialization
var nSdkInstance = NOLBUNDLE.nlsQ("XXXXXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXX", "staticPage", {
nol_sdkDebug: 'debug',
});

// Static Metadata
var staticMetadata = {
assetid: 'staticTestPage',
type: 'static'
};

// Event 'staticstart' call
nSdkInstance.ggPM(14, staticMetadata);
</script>
</head>

<body>
<h1>DCR Static on Parent/DCR Video in iFrame</h1>
<p>Static measurement is current on parent page when window is in focus</p>
<iframe src="./dcr-video.html" frameborder="0" width="650" height="500" style="background-color: rgb(42, 217, 248);" id="video-iframe"></iframe>
</body>

</html>
</syntaxhighlight>

<big>Nested iFrame Referenced on Parent Page (dcr-video.html)</big>

<syntaxhighlight lang="javascript">
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
<meta http-equiv="X-UA-Compatible" content="ie=edge" />
<title>iFrame Same Source</title>
<script>
/* NLSQUEUE build v*/
!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.imrworldwide.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");

// SDK Initialization
var nSdkInstance = NOLBUNDLE.nlsQ("XXXXXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXX", "videoPlayer", {
nol_sdkDebug: 'debug',
});

var contentMetadata = {
type: "content",
length: "300",
title: "Skydiving Across Europe",
program: "latacg",
censuscategory: "Enlisted",
assetid: "204558915992",
section: "ProgramAsset8",
tv: "true",
adModel: "0",
dataSrc: "cms",
segA: "S07E04:NBC",
segB: "teams",
segC:"AtlanataFalcons",
}
</script>
</head>
<body>
<p>I'm iframe SDK DCR Video measurement, DCR static measurement should continue when clicking "play" on video</p>
<main>
<video
controls
src="https://archive.org/download/BigBuckBunny_124/Content/big_buck_bunny_720p_surround.mp4"
poster="https://peach.blender.org/wp-content/uploads/title_anouncement.jpg?x11217"
width="620">
Sorry, your browser doesn't support embedded videos, but don't worry, you can
<a href="https://archive.org/details/BigBuckBunny_124">download it</a>
and watch it with your favorite video player!
</video>
</main>
<script src="../player.js"></script>
</body>
</html>

</syntaxhighlight>

=== SDK Initialization to measure the Viewability & Audibility ===
To support viewability metrics in the web page the integrator has to provide a tag value of the player view to let Nielsen SDK know that there is a player that needs to be tracked. It’s called the ‘containerId’ and it should be passed in the as string while initializing the Nielsen browser SDK.

NOLBUNDLE.nlsQ("<apid>", "<instanceName>",{containerId: <playerElementID>, nol_sdkDebug: "debug"})

'''Example SDK Initialization for Viewability'''

Your configuration should include the Static Queue Snippet and an SDK Instance for your unique App ID as shown in the example:
<syntaxhighlight lang="javascript">
//Add Static Queue Snippet
<script>
! function(t, n) {
t[n] = t[n] || {
nlsQ: function(e, o, c, r, s, i) {
return s = t.document,
r = s.createElement("script"),
r.async = 1,
r.src = ("http:" === t.location.protocol ? "http:" : "https:") + "//cdn-gl.imrworldwide.com/conf/" + e + ".js#name=" + o + "&ns=" + n,
i = s.getElementsByTagName("script")[0],
i.parentNode.insertBefore(r, i),
t[n][o] = t[n][o] || {
g: c || {},
ggPM: function(e, c, r, s, i) {
(t[n][o].q = t[n][o].q || []).push([e, c, r, s, i])
}
}, t[n][o]
}
}
}
(window, "NOLBUNDLE");

//Create SDK Instance
var nSdkInstance = NOLBUNDLE.nlsQ("XXXXXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXX", "nlsnInstance", {containerId: “player1”, nol_sdkDebug: "debug"});
</script>

</syntaxhighlight>

== Browser SDK API Methods & Properties ==
{| class="wikitable sortable"
|-
! Method / Property !! Event # !! DTVR !! DAR !! DCR !! Description
|-
| [[loadMetadata (Browser)|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.
|-
| [[play (Browser)|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”.
|-
| [[sendID3 (Browser)|sendID3]] || 55 || ✔ || ✘ || ✘ || Used to send the ID3 metadata.
|-
| [[setPlayheadPosition (Browser)|setPlayheadPosition]] || 49 || ✘ || ✘ || ✔ || Used to send the playhead position.
|-
| [[stop (Browser)|stop]] || 7 || ✘ || ✘ || ✔ || Used when switching between ad and content or content and ad.
|-
| [[end (Browser)|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
|-
| [[staticstart (Browser)|staticstart]] || 14 || ✘ || ✘ || ✔ || Used to send the metadata for the static page.
|-
| [[StaticEnd (Browser)|staticend]] || 56 || ✘ || ✘ || ✔ || In Single Page Application (SPA) it is imperative that staticend is called prior to the loading of new metadata. This allows the Browser SDK to properly credit the previous section/content being viewed before measuring the new one.
|-
| [[updateOTT (Browser)|updateOTT]] || - || ✘ || ✘ || ✔ || Used to notify Browser SDK that the remote OTT device (like Google ChromeCast, Roku, Amazon FireTV, etc.) is connected / disconnected (change of OTT status).
|-
| [[ onPaginate (Browser)|onPaginate]] || 30 || ✘ || ✘ || ✔ || Used to create a new instance of the SDK object
|-
| [[updateMetadata (Browser)|updateMetadata]] || 35 || ✔ || ✔ || ✔ || This event is used for updating metadata parameters for the content or ad that is being played.
|-
| [[setVolume_(Browser)|setVolume]] || 61 || ✔ || ✘ || ✔ || Used to pass in the player volume levels in %. Default value is -1.
|}

== Retrieving ID3 Tags ==
The video player must have the ability to extract ID3 tags and supply them to the Browser SDK, based on the HLS standard.
*An ID3 tag spans two PES packets.
**In the first PES packet, look for www.nielsen.com, this is the start of the ID3 tag. Continue to parse the first PES packet until the undefined char "\ufffd" is found. This forms the first half of the ID3 tag
**In the second PES packet, identify the end pattern – a regEx of /(\/\d+){3}/ and look to remove the lowest index of either "\x00" and/or "\ufffd". Now the second packet has been appended and the demarcation of the Nielsen-specific data has been defined.

Follow the procedure below, to extract Nielsen ID3 tags from an MPEG-2 transport stream (including HLS streams).
#Parse the Program Map Table (PMT) to find the PID of the metadata stream. Confirm the presence of the metadata descriptor described in section 2.3.3 of Apple’s “HTTP Live Streaming Metadata Spec.pdf”. Only private streams with metadata descriptor present should be considered as ID3-tag metadata streams.
#Parse the HLS/Transport stream for any '''PES header''' with the PID found in step 1.
#Follow standard MPEG-2 parsing procedures to locate the start of the payload of the PES packet.
#Copy the PES payload into a buffer.
#The ID3 tag spans 2 PES packets. Parse the stream for the next packet whose PID is set to the PID found in step 1. Typically the ID3 Tag is of 249 bytes. The steps below guide towards extraction of the ID3 tag
##In the first PES packet, look for "www.nielsen.com" , this is the start of the ID3 tag. Keep on parsing the first PES packet until the undefined char "\ufffd" is found. This forms the first half of the ID3 tag
##In the second PES packet, identify the end pattern, a regEx of /(\/\d+){3}/ and look to remove the lowest index of either “\x00” and/or “\ufffd”. Now the second packet has been appended and the demarcation of the Nielsen specific data has been defined. This segment can be simply substringed.
##Concatenate this substringed segment with the payload derived from the first packet get the ID3 payload.
#Check the length of the contents in the buffer to make sure that it is equal to the size of a Nielsen ID3 tag.
#Ensure that the ID3 byte array is converted into the string and escape it, so that the SDK can consume it.
Repeat steps 2 through 7 for all ID3 tags in the stream.

'''References'''
*[http://www.iso.org/iso/catalogue_detail?csnumber=44169. ISO/IEC 13818-1:2007] Information technology – Generic coding of moving pictures and associated audio information: Systems
*https://developer.apple.com/library/content/documentation/AudioVideo/Conceptual/HTTP_Live_Streaming_Metadata_Spec/

=== Sample ID3 tags ===
* <code>www.nielsen.com/X100zdCIGeIlgZnkYj6UvQ==/X100zdCIGeIlgZnkYj6UvQ==/AAAB2Jz2_k74GXSzx4npHuI_<wbr />JwJd3QSUpW30rDkGTcbHEzIMWleCzM-uvNOP9fzJcQMWQLJqzXMCAxParOb5sGijSV9dNM3QiBniJYGZ5GI-lL1fXTTN0IgZ4iWBmeRiPpS9AAAAAAAAAAAAAAAAAAAAAFJWFM5SVhTONNU=/00000/00000/00</code>
* <code>www.nielsen.com/X100zdCIGeIlgZnkYj6UvQ==/R8WHe7pEBeqBhu8jTeXydg==/AAICoyitYqlxT7n6aZ0oMCGhe<wbr />Fi4CXFp46AMUPZz1lMr_M9tr3_cjee1SHqxrOiVerMDLeyn9xzocZSKwi746Re8vNOtpNCAZjYABs_J0R25IHpvOc1HS8<wbr />QHGgD5TgOJeS6gX100zdCIGeIlgZnkYj6UvVJWFNhSVhTiPE0=/00000/46016/00</code>
<blockquote>'''Note''': ID3 tags are not applicable for International (Germany)</blockquote>

== Browser Opt-Out Implementation ==
The site in which video content is being measure via Nielsen methodology must provide the means for the user to opt-out of, or opt back into Nielsen Measurement.

For Browser-based applications, opt-out setting is stored via Nielsen cookie. Therefore, it is only necessary that users be made aware of measurement opt-out by incorporating the template below in the user interface.

=== Sample Opt Out Template ===
Our properties may feature Nielsen’s proprietary measurement software which will allow to contribute to market research, like Nielsen’s TV Ratings. To learn more about this information, see https://www.nielsen.com/digitalprivacy. Nielsen’s software may collect your choices with regards to it.

== Nielsen Privacy Requirements ==
Privacy protections that Nielsen ensures to have with each App SDK integration are as follows.
*Disclosure of viewership data collection in EULA / Privacy Policy
*A link in the EULA/Privacy policy, or in another conspicuous location within the App, to a Nielsen-hosted web page outlining what Nielsen is collecting and how it is being used
*Method for users to opt-out of Nielsen measurement, any time while using the application

=== Ratings Data Flow ===
Every view of creditable and watermarked content is measured by Nielsen.
[[File:RatingsDataFlow.png]]

'''Information NOT Shared'''
* '''With Nielsen'''
** User's Identity
* '''With Data Provider'''
** Content information
** Whether user is viewing an ad or video content
** Player used to play the streaming (audio / video, etc.)
** Values being de-duped / aggregating for

Nielsen collects only what it needs for audience measurement. Every view of creditable, watermarked content will be measured by Nielsen.

=== Data Collected ===
{| class="wikitable"
|-
! Type of Information !! Parameter !! Transmitted to Nielsen? !! Sent to Provider?
|-
| rowspan="8" | Nielsen ID3 Watermark
|-
| FinalDistributor Timestamp || Yes || No
|-
| Program Content Timestamp || Yes || No
|-
| Mobile Breakout Code || Yes || No
|-
| Commercial Credit Code – Linear or Dynamic || Yes || No
|-
| Time ShiftedViewing Code || Yes || No
|-
| Segment Number || Yes || No
|-
| Segment View Pattern || Yes || No
|-
| rowspan="7" | Device/App Info
|-
| Device OSVersion || Yes || Yes
|-
| Device Model || Yes || No
|-
| Cache Buster || Yes || Yes
|-
| SDKDisabled Flag || Yes || No
|-
| ServerCode || Yes || No
|-
| Channel or URL || Yes || No
|-
| rowspan="9" | Nielsen Identifiers
|-
| Client ID || Yes || No
|-
| Campaign ID || Yes || Yes
|-
| Nielsen Unique Device ID || Yes || No
|-
| Application ID || Yes || No
|-
| DeviceGroup (ex. Tablet, Smartphone, Desktop) || Yes || Yes
|-
| OS Group (ex. Android, iOS, Windows) || Yes || Yes
|-
| SDKVersion || Yes || No
|-
| IP Address for DMA, Country Code || Yes || Yes
|}
<blockquote>'''Note''': Data is hashed, and encrypted using AES 128 before transmission to data provider.</blockquote>

{{Viewability_Data_Collected}}

==== Example ping sent to provider ====
* <code><nowiki>https://provider.com/cgi-bin/brandlift.php</nowiki>?campaign_id=ff12725d724fac7934cf6003f096b4cd<wbr />&placement_id=a4164b8fba9ee7c873a9c72c7091bb58<wbr />&creative_id=25280139b61a947e127a52f56c8a2fdd<wbr />&segment1=9000<wbr />&segment2=41<wbr />&segment3=iOS<wbr />&OSVer=iOS6.1<wbr />&c9=<wbr />&devgrp=tablet<wbr />&h=f5f243fe6d<wbr />&rnd=1376971827360</code>

This ping passes the following parameters to the provider:
* Campaign ID – (campaign, placement, creative)
* Country Code
* DMA
* OS Group (ex. iOS, Android)
* DeviceOS Version
* Device Advertiser ID
* DeviceGroup (ex. Tablet, Smartphone, Desktop)
* Cache Buster

{{Template:Browser_Privacy_and_Opt-Out}}

=== Opt-Out Implementation ===
The site must provide the means for the user to opt-out of, or opt back into Nielsen Measurement.

'''Sample Opt Out Template'''

Our properties may feature Nielsen’s proprietary measurement software which will allow to contribute to market research, like Nielsen’s TV Ratings. To learn more about this information, please [http://priv-policy.imrworldwide.com/priv/mobile/us/en/optout.html| click here]. Nielsen’s software may collect your choices with regards to it.

== Testing ==
See [[Digital Measurement Testing#Testing Browser Implementation|Digital Measurement Testing - Testing Browser Implementation]].

Browser SDK API Reference

2024-12-09T20:00:10Z

AmySockanathan: /* Multiple SDK Instances */

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

== Setting up Development Environment ==
=== Step 1: Configure Content Management System (CMS) ===
Configure CMS to send the required values (see table below). Any internal CMS_variable names can be used for passing the data.

Ensure to capture these CMS_variable names in the SDK Configuration Form.

For more information on setting variable names, see the SDK Configuration Form included within the SDK package.

{| class="wikitable"
|-
! Required Data !! Description !! Value
|-
| dataSrc || Used when both CMS metadata and ID3 data are present in the player. Setting this field tells the SDK whether to use the CMS metadata or the ID3 payload to derive the pings || cms
|-
| type || Type of asset: ad or content || preroll, midroll, postroll, or content
|-
| assetid || unique ID assigned to asset || custom <br>(no [[Special Characters]])
|-
| OCR Tag || OCR tag provided by Nielsen for implementation on the ad unit || Complete OCR URL
|-
| program || Name of program (25 character limit) || custom
|-
| title || Episode title (40 character limit) || custom
|-
| length || Length of content in seconds || Length in seconds, 0 for live stream
|-
| adloadtype || Type of ad load || "1" - Linear "2" - Dynamic(default)
|-
| hasAds || Identify if content includes Ads || "0" - no ads "1" - includes ads "2" - unknown(default)
|-
| isfullepisode || Full episode flag || "y" - full episode "n" - non full episode
|-
| segA || Segment A (this is not available for video reporting as the episode title is reported) || custom value
|-
| segB || Custom segment B || custom value
|-
| segC || Custom segment C || custom value
|-
| crossId1 || Standard episode ID || custom value
|-
| crossId2 || Content originator (required only for distributors) || custom value
|-
| airdate || Original air date and time in Eastern Time. For non-US countries, it should be local time. || YYYYMMDD HH24:MI:SS
|-
| containerId || HTML DOM element of the Player container (for Viewability&Audibility feature only) || custom value
|-
|luid
|Living Unit ID - Experian Household ID
'''Note: This parameter is applicable only for CTV and First Party Livestream data'''
|"B0EOFEDgD"
|}

=== Step 2: Complete the Nielsen SDK Configuration Form ===
The SDK is designed to map the <code>CMS_variable names</code>. To support the custom mapping, the developer is required to complete the SDK Configuration Form. The form will be provided during onboarding along with this guide.

== Initialization ==
=== Obtain the Nielsen Application ID (apid) and Browser SDK URLs ===
The Nielsen <code>apid</code> 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 Browser SDK ===
There are two steps required for configuring the SDK:

'''Add Static Queue Snippet'''

*Add Static Queue Snippet
*Create SDK Instance

Add the following script tag to the website:
<syntaxhighlight lang="javascript">

<script type="text/javascript">
!function(t,n)
{
t[n]=t[n]||
{
nlsQ:function(e,o,c,r,s,i)
{
return s=t.document,
r=s.createElement("script"),
r.async=1,
r.src=("http:"===t.location.protocol?"http:":"https:")+"//cdn-gl.imrworldwide.com/conf/"+e+".js#name="+o+"&ns="+n,
i=s.getElementsByTagName("script")[0],
i.parentNode.insertBefore(r,i),
t[n][o]=t[n][o]||{g:c||{},
ggPM:function(e,c,r,s,i){(t[n][o].q=t[n][o].q||[]).push([e,c,r,s,i])}},t[n][o]
}
}
}
(window,"NOLBUNDLE");
</script>

</syntaxhighlight>

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.

'''Create SDK Instance'''

To initialize the SDK, create an SDK instance by making the initialization call:

'''Initialization API Call'''
<syntaxhighlight lang="javascript">

NOLBUNDLE.nlsQ("<apid>", "<instanceName>",{nol_sdkDebug: "debug"})

</syntaxhighlight>

When creating an instance, pass the following three values:

=== SDK Initialization – Global Parameters ===
{| class="wikitable"
|-
! Parameters !! Description !! Value
|-
| apid || UniqueID assigned to player/site. || 'XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX'
|-
| instanceName || Name of SDK instance || "any string value"
|-
| nol_sdkDebug || Enables Nielsen console logging. Only required for testing || "{nol_sdkDebug: "debug"})"
|-
| containerId || HTML DOM element id of the player container. Only for Viewability & Audibility feature. || {containerId: "playerId1"}
|-
| 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&"
|}

{{example_bsdk_init}}

'''Example SDK Configuration'''

The configuration should include the Static Queue Snippet and an SDK Instance for an unique App ID as shown in the example:

<syntaxhighlight lang="javascript">

<script type="text/javascript">
!function(t,n)
{
t[n]=t[n]||
{
nlsQ:function(e,o,c,r,s,i)
{
return s=t.document,
r=s.createElement("script"),
r.async=1,
r.src=("http:"===t.location.protocol?"http:":"https:")+"//cdn-gl.imrworldwide.com/conf/"+e+".js#name="+o+"&ns="+n,
i=s.getElementsByTagName("script")[0],
i.parentNode.insertBefore(r,i),
t[n][o]=t[n][o]||{g:c||{},
ggPM:function(e,c,r,s,i){(t[n][o].q=t[n][o].q||[]).push([e,c,r,s,i])}},t[n][o]
}
}
}
(window,"NOLBUNDLE");
// Created SDK Instance
var nSdkInstance = NOLBUNDLE.nlsQ("XXXXXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXX","nlsnInstance", {nol_sdkDebug: "debug"});
</script>

</syntaxhighlight>

=== Multiple SDK Instances ===
The Browser SDK allows instantiating multiple instances of the object, which can be used simultaneously without any problems, however they must be instantiated with their own unique instance names. There is no maximum number of instances that is enforced in the browser.

The below examples will make use of the same AppId, however using different AppIds will work as well. The principles below follow the same initialization rules stated above for a single instance and simply require a unique instance name and variable name with which the returned instance is assigned.

For more information around the possible parameters that can be passed as well as deeper descriptions for the API calls, please refer to the section on "[[#SDK_Initialization_-_Global_Parameters | SDK Initialization - Global Parameters]]".

'''Example of 2 instances on the same page'''

<syntaxhighlight lang="javascript">
//Add Static Queue Snippet
<script>
!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.imrworldwide.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");

//Create SDK Instance(s)
// Notice the unique instance name given to each instance below and the unique variable name for each instance
var nSdkInstanceLive = NOLBUNDLE.nlsQ("XXXXXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXX", "instanceLive", {
nol_sdkDebug: 'debug',
optout: 'false'
});

var nSdkInstanceVod = NOLBUNDLE.nlsQ("XXXXXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXX", "instanceVod", {
nol_sdkDebug: 'debug',
optout: 'false'
});

</script>
</syntaxhighlight>

'''Example of 2 instances using a parent page and iFrame'''

<big>Parent Page (index.html)</big>

<syntaxhighlight lang="javascript">
<!DOCTYPE html>
<html lang="en">

<head>
<meta charset="UTF-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<meta http-equiv="X-UA-Compatible" content="ie=edge">
<title>DCR Static/DCR Video</title>
<script>
/* NLSQUEUE build v*/
!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.imrworldwide.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");

// SDK Initialization
var nSdkInstance = NOLBUNDLE.nlsQ("XXXXXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXX", "staticPage", {
nol_sdkDebug: 'debug',
});

// Static Metadata
var staticMetadata = {
assetid: 'staticTestPage',
type: 'static'
};

// Event 'staticstart' call
nSdkInstance.ggPM(14, staticMetadata);
</script>
</head>

<body>
<h1>DCR Static on Parent/DCR Video in iFrame</h1>
<p>Static measurement is current on parent page when window is in focus</p>
<iframe src="./dcr-video.html" frameborder="0" width="650" height="500" style="background-color: rgb(42, 217, 248);" id="video-iframe"></iframe>
</body>

</html>
</syntaxhighlight>

<big>Nested iFrame Referenced on Parent Page (dcr-video.html)</big>

<syntaxhighlight lang="javascript">
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
<meta http-equiv="X-UA-Compatible" content="ie=edge" />
<title>iFrame Same Source</title>
<script>
/* NLSQUEUE build v*/
!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.imrworldwide.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");

// SDK Initialization
var nSdkInstance = NOLBUNDLE.nlsQ("XXXXXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXX", "videoPlayer", {
nol_sdkDebug: 'debug',
});

var contentMetadata = {
type: "content",
length: "300",
title: "Skydiving Across Europe",
program: "latacg",
censuscategory: "Enlisted",
assetid: "204558915992",
section: "ProgramAsset8",
tv: "true",
adModel: "0",
dataSrc: "cms",
segA: "S07E04:NBC",
segB: "teams",
segC:"AtlanataFalcons",
}
</script>
</head>
<body>
<p>I'm iframe SDK DCR Video measurement, DCR static measurement should continue when clicking "play" on video</p>
<main>
<video
controls
src="https://archive.org/download/BigBuckBunny_124/Content/big_buck_bunny_720p_surround.mp4"
poster="https://peach.blender.org/wp-content/uploads/title_anouncement.jpg?x11217"
width="620">
Sorry, your browser doesn't support embedded videos, but don't worry, you can
<a href="https://archive.org/details/BigBuckBunny_124">download it</a>
and watch it with your favorite video player!
</video>
</main>
<script src="../player.js"></script>
</body>
</html>

</syntaxhighlight>

=== SDK Initialization to measure the Viewability & Audibility ===
To support viewability metrics in the web page the integrator has to provide a tag value of the player view to let Nielsen SDK know that there is a player that needs to be tracked. It’s called the ‘containerId’ and it should be passed in the as string while initializing the Nielsen browser SDK.

NOLBUNDLE.nlsQ("<apid>", "<instanceName>",{containerId: <playerElementID>, nol_sdkDebug: "debug"})

'''Example SDK Initialization for Viewability'''

Your configuration should include the Static Queue Snippet and an SDK Instance for your unique App ID as shown in the example:
<syntaxhighlight lang="javascript">
//Add Static Queue Snippet
<script>
! function(t, n) {
t[n] = t[n] || {
nlsQ: function(e, o, c, r, s, i) {
return s = t.document,
r = s.createElement("script"),
r.async = 1,
r.src = ("http:" === t.location.protocol ? "http:" : "https:") + "//cdn-gl.imrworldwide.com/conf/" + e + ".js#name=" + o + "&ns=" + n,
i = s.getElementsByTagName("script")[0],
i.parentNode.insertBefore(r, i),
t[n][o] = t[n][o] || {
g: c || {},
ggPM: function(e, c, r, s, i) {
(t[n][o].q = t[n][o].q || []).push([e, c, r, s, i])
}
}, t[n][o]
}
}
}
(window, "NOLBUNDLE");

//Create SDK Instance
var nSdkInstance = NOLBUNDLE.nlsQ("XXXXXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXX", "nlsnInstance", {containerId: “player1”, nol_sdkDebug: "debug"});
</script>

</syntaxhighlight>

== Browser SDK API Methods & Properties ==
{| class="wikitable sortable"
|-
! Method / Property !! Event # !! DTVR !! DAR !! DCR !! Description
|-
| [[loadMetadata (Browser)|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.
|-
| [[play (Browser)|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”.
|-
| [[sendID3 (Browser)|sendID3]] || 55 || ✔ || ✘ || ✘ || Used to send the ID3 metadata.
|-
| [[setPlayheadPosition (Browser)|setPlayheadPosition]] || 49 || ✘ || ✘ || ✔ || Used to send the playhead position.
|-
| [[stop (Browser)|stop]] || 7 || ✘ || ✘ || ✔ || Used when switching between ad and content or content and ad.
|-
| [[end (Browser)|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
|-
| [[staticstart (Browser)|staticstart]] || 14 || ✘ || ✘ || ✔ || Used to send the metadata for the static page.
|-
| [[StaticEnd (Browser)|staticend]] || 56 || ✘ || ✘ || ✔ || In Single Page Application (SPA) it is imperative that staticend is called prior to the loading of new metadata. This allows the Browser SDK to properly credit the previous section/content being viewed before measuring the new one.
|-
| [[updateOTT (Browser)|updateOTT]] || - || ✘ || ✘ || ✔ || Used to notify Browser SDK that the remote OTT device (like Google ChromeCast, Roku, Amazon FireTV, etc.) is connected / disconnected (change of OTT status).
|-
| [[ onPaginate (Browser)|onPaginate]] || 30 || ✘ || ✘ || ✔ || Used to create a new instance of the SDK object
|-
| [[updateMetadata (Browser)|updateMetadata]] || 35 || ✔ || ✔ || ✔ || This event is used for updating metadata parameters for the content or ad that is being played.
|-
| [[setVolume_(Browser)|setVolume]] || 61 || ✔ || ✘ || ✔ || Used to pass in the player volume levels in %. Default value is -1.
|}

== Retrieving ID3 Tags ==
The video player must have the ability to extract ID3 tags and supply them to the Browser SDK, based on the HLS standard.
*An ID3 tag spans two PES packets.
**In the first PES packet, look for www.nielsen.com, this is the start of the ID3 tag. Continue to parse the first PES packet until the undefined char "\ufffd" is found. This forms the first half of the ID3 tag
**In the second PES packet, identify the end pattern – a regEx of /(\/\d+){3}/ and look to remove the lowest index of either "\x00" and/or "\ufffd". Now the second packet has been appended and the demarcation of the Nielsen-specific data has been defined.

Follow the procedure below, to extract Nielsen ID3 tags from an MPEG-2 transport stream (including HLS streams).
#Parse the Program Map Table (PMT) to find the PID of the metadata stream. Confirm the presence of the metadata descriptor described in section 2.3.3 of Apple’s “HTTP Live Streaming Metadata Spec.pdf”. Only private streams with metadata descriptor present should be considered as ID3-tag metadata streams.
#Parse the HLS/Transport stream for any '''PES header''' with the PID found in step 1.
#Follow standard MPEG-2 parsing procedures to locate the start of the payload of the PES packet.
#Copy the PES payload into a buffer.
#The ID3 tag spans 2 PES packets. Parse the stream for the next packet whose PID is set to the PID found in step 1. Typically the ID3 Tag is of 249 bytes. The steps below guide towards extraction of the ID3 tag
##In the first PES packet, look for "www.nielsen.com" , this is the start of the ID3 tag. Keep on parsing the first PES packet until the undefined char "\ufffd" is found. This forms the first half of the ID3 tag
##In the second PES packet, identify the end pattern, a regEx of /(\/\d+){3}/ and look to remove the lowest index of either “\x00” and/or “\ufffd”. Now the second packet has been appended and the demarcation of the Nielsen specific data has been defined. This segment can be simply substringed.
##Concatenate this substringed segment with the payload derived from the first packet get the ID3 payload.
#Check the length of the contents in the buffer to make sure that it is equal to the size of a Nielsen ID3 tag.
#Ensure that the ID3 byte array is converted into the string and escape it, so that the SDK can consume it.
Repeat steps 2 through 7 for all ID3 tags in the stream.

'''References'''
*[http://www.iso.org/iso/catalogue_detail?csnumber=44169. ISO/IEC 13818-1:2007] Information technology – Generic coding of moving pictures and associated audio information: Systems
*https://developer.apple.com/library/content/documentation/AudioVideo/Conceptual/HTTP_Live_Streaming_Metadata_Spec/

=== Sample ID3 tags ===
* <code>www.nielsen.com/X100zdCIGeIlgZnkYj6UvQ==/X100zdCIGeIlgZnkYj6UvQ==/AAAB2Jz2_k74GXSzx4npHuI_<wbr />JwJd3QSUpW30rDkGTcbHEzIMWleCzM-uvNOP9fzJcQMWQLJqzXMCAxParOb5sGijSV9dNM3QiBniJYGZ5GI-lL1fXTTN0IgZ4iWBmeRiPpS9AAAAAAAAAAAAAAAAAAAAAFJWFM5SVhTONNU=/00000/00000/00</code>
* <code>www.nielsen.com/X100zdCIGeIlgZnkYj6UvQ==/R8WHe7pEBeqBhu8jTeXydg==/AAICoyitYqlxT7n6aZ0oMCGhe<wbr />Fi4CXFp46AMUPZz1lMr_M9tr3_cjee1SHqxrOiVerMDLeyn9xzocZSKwi746Re8vNOtpNCAZjYABs_J0R25IHpvOc1HS8<wbr />QHGgD5TgOJeS6gX100zdCIGeIlgZnkYj6UvVJWFNhSVhTiPE0=/00000/46016/00</code>
<blockquote>'''Note''': ID3 tags are not applicable for International (Germany)</blockquote>

== Browser Opt-Out Implementation ==
The site in which video content is being measure via Nielsen methodology must provide the means for the user to opt-out of, or opt back into Nielsen Measurement.

For Browser-based applications, opt-out setting is stored via Nielsen cookie. Therefore, it is only necessary that users be made aware of measurement opt-out by incorporating the template below in the user interface.

=== Sample Opt Out Template ===
Our properties may feature Nielsen’s proprietary measurement software which will allow to contribute to market research, like Nielsen’s TV Ratings. To learn more about this information, see https://www.nielsen.com/digitalprivacy. Nielsen’s software may collect your choices with regards to it.

== Nielsen Privacy Requirements ==
Privacy protections that Nielsen ensures to have with each App SDK integration are as follows.
*Disclosure of viewership data collection in EULA / Privacy Policy
*A link in the EULA/Privacy policy, or in another conspicuous location within the App, to a Nielsen-hosted web page outlining what Nielsen is collecting and how it is being used
*Method for users to opt-out of Nielsen measurement, any time while using the application

=== Ratings Data Flow ===
Every view of creditable and watermarked content is measured by Nielsen.
[[File:RatingsDataFlow.png]]

'''Information NOT Shared'''
* '''With Nielsen'''
** User's Identity
* '''With Data Provider'''
** Content information
** Whether user is viewing an ad or video content
** Player used to play the streaming (audio / video, etc.)
** Values being de-duped / aggregating for

Nielsen collects only what it needs for audience measurement. Every view of creditable, watermarked content will be measured by Nielsen.

=== Data Collected ===
{| class="wikitable"
|-
! Type of Information !! Parameter !! Transmitted to Nielsen? !! Sent to Provider?
|-
| rowspan="8" | Nielsen ID3 Watermark
|-
| FinalDistributor Timestamp || Yes || No
|-
| Program Content Timestamp || Yes || No
|-
| Mobile Breakout Code || Yes || No
|-
| Commercial Credit Code – Linear or Dynamic || Yes || No
|-
| Time ShiftedViewing Code || Yes || No
|-
| Segment Number || Yes || No
|-
| Segment View Pattern || Yes || No
|-
| rowspan="7" | Device/App Info
|-
| Device OSVersion || Yes || Yes
|-
| Device Model || Yes || No
|-
| Cache Buster || Yes || Yes
|-
| SDKDisabled Flag || Yes || No
|-
| ServerCode || Yes || No
|-
| Channel or URL || Yes || No
|-
| rowspan="9" | Nielsen Identifiers
|-
| Client ID || Yes || No
|-
| Campaign ID || Yes || Yes
|-
| Nielsen Unique Device ID || Yes || No
|-
| Application ID || Yes || No
|-
| DeviceGroup (ex. Tablet, Smartphone, Desktop) || Yes || Yes
|-
| OS Group (ex. Android, iOS, Windows) || Yes || Yes
|-
| SDKVersion || Yes || No
|-
| IP Address for DMA, Country Code || Yes || Yes
|}
<blockquote>'''Note''': Data is hashed, and encrypted using AES 128 before transmission to data provider.</blockquote>

{{Viewability_Data_Collected}}

==== Example ping sent to provider ====
* <code><nowiki>https://provider.com/cgi-bin/brandlift.php</nowiki>?campaign_id=ff12725d724fac7934cf6003f096b4cd<wbr />&placement_id=a4164b8fba9ee7c873a9c72c7091bb58<wbr />&creative_id=25280139b61a947e127a52f56c8a2fdd<wbr />&segment1=9000<wbr />&segment2=41<wbr />&segment3=iOS<wbr />&OSVer=iOS6.1<wbr />&c9=<wbr />&devgrp=tablet<wbr />&h=f5f243fe6d<wbr />&rnd=1376971827360</code>

This ping passes the following parameters to the provider:
* Campaign ID – (campaign, placement, creative)
* Country Code
* DMA
* OS Group (ex. iOS, Android)
* DeviceOS Version
* Device Advertiser ID
* DeviceGroup (ex. Tablet, Smartphone, Desktop)
* Cache Buster

{{Template:Browser_Privacy_and_Opt-Out}}

=== Opt-Out Implementation ===
The site must provide the means for the user to opt-out of, or opt back into Nielsen Measurement.

'''Sample Opt Out Template'''

Our properties may feature Nielsen’s proprietary measurement software which will allow to contribute to market research, like Nielsen’s TV Ratings. To learn more about this information, please [http://priv-policy.imrworldwide.com/priv/mobile/us/en/optout.html| click here]. Nielsen’s software may collect your choices with regards to it.

== Testing ==
See [[Digital Measurement Testing#Testing Browser Implementation|Digital Measurement Testing - Testing Browser Implementation]].

Browser SDK API Reference

2024-12-09T19:52:05Z

AmySockanathan: /* Multiple SDK Instances */

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

== Setting up Development Environment ==
=== Step 1: Configure Content Management System (CMS) ===
Configure CMS to send the required values (see table below). Any internal CMS_variable names can be used for passing the data.

Ensure to capture these CMS_variable names in the SDK Configuration Form.

For more information on setting variable names, see the SDK Configuration Form included within the SDK package.

{| class="wikitable"
|-
! Required Data !! Description !! Value
|-
| dataSrc || Used when both CMS metadata and ID3 data are present in the player. Setting this field tells the SDK whether to use the CMS metadata or the ID3 payload to derive the pings || cms
|-
| type || Type of asset: ad or content || preroll, midroll, postroll, or content
|-
| assetid || unique ID assigned to asset || custom <br>(no [[Special Characters]])
|-
| OCR Tag || OCR tag provided by Nielsen for implementation on the ad unit || Complete OCR URL
|-
| program || Name of program (25 character limit) || custom
|-
| title || Episode title (40 character limit) || custom
|-
| length || Length of content in seconds || Length in seconds, 0 for live stream
|-
| adloadtype || Type of ad load || "1" - Linear "2" - Dynamic(default)
|-
| hasAds || Identify if content includes Ads || "0" - no ads "1" - includes ads "2" - unknown(default)
|-
| isfullepisode || Full episode flag || "y" - full episode "n" - non full episode
|-
| segA || Segment A (this is not available for video reporting as the episode title is reported) || custom value
|-
| segB || Custom segment B || custom value
|-
| segC || Custom segment C || custom value
|-
| crossId1 || Standard episode ID || custom value
|-
| crossId2 || Content originator (required only for distributors) || custom value
|-
| airdate || Original air date and time in Eastern Time. For non-US countries, it should be local time. || YYYYMMDD HH24:MI:SS
|-
| containerId || HTML DOM element of the Player container (for Viewability&Audibility feature only) || custom value
|-
|luid
|Living Unit ID - Experian Household ID
'''Note: This parameter is applicable only for CTV and First Party Livestream data'''
|"B0EOFEDgD"
|}

=== Step 2: Complete the Nielsen SDK Configuration Form ===
The SDK is designed to map the <code>CMS_variable names</code>. To support the custom mapping, the developer is required to complete the SDK Configuration Form. The form will be provided during onboarding along with this guide.

== Initialization ==
=== Obtain the Nielsen Application ID (apid) and Browser SDK URLs ===
The Nielsen <code>apid</code> 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 Browser SDK ===
There are two steps required for configuring the SDK:

'''Add Static Queue Snippet'''

*Add Static Queue Snippet
*Create SDK Instance

Add the following script tag to the website:
<syntaxhighlight lang="javascript">

<script type="text/javascript">
!function(t,n)
{
t[n]=t[n]||
{
nlsQ:function(e,o,c,r,s,i)
{
return s=t.document,
r=s.createElement("script"),
r.async=1,
r.src=("http:"===t.location.protocol?"http:":"https:")+"//cdn-gl.imrworldwide.com/conf/"+e+".js#name="+o+"&ns="+n,
i=s.getElementsByTagName("script")[0],
i.parentNode.insertBefore(r,i),
t[n][o]=t[n][o]||{g:c||{},
ggPM:function(e,c,r,s,i){(t[n][o].q=t[n][o].q||[]).push([e,c,r,s,i])}},t[n][o]
}
}
}
(window,"NOLBUNDLE");
</script>

</syntaxhighlight>

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.

'''Create SDK Instance'''

To initialize the SDK, create an SDK instance by making the initialization call:

'''Initialization API Call'''
<syntaxhighlight lang="javascript">

NOLBUNDLE.nlsQ("<apid>", "<instanceName>",{nol_sdkDebug: "debug"})

</syntaxhighlight>

When creating an instance, pass the following three values:

=== SDK Initialization – Global Parameters ===
{| class="wikitable"
|-
! Parameters !! Description !! Value
|-
| apid || UniqueID assigned to player/site. || 'XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX'
|-
| instanceName || Name of SDK instance || "any string value"
|-
| nol_sdkDebug || Enables Nielsen console logging. Only required for testing || "{nol_sdkDebug: "debug"})"
|-
| containerId || HTML DOM element id of the player container. Only for Viewability & Audibility feature. || {containerId: "playerId1"}
|-
| 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&"
|}

{{example_bsdk_init}}

'''Example SDK Configuration'''

The configuration should include the Static Queue Snippet and an SDK Instance for an unique App ID as shown in the example:

<syntaxhighlight lang="javascript">

<script type="text/javascript">
!function(t,n)
{
t[n]=t[n]||
{
nlsQ:function(e,o,c,r,s,i)
{
return s=t.document,
r=s.createElement("script"),
r.async=1,
r.src=("http:"===t.location.protocol?"http:":"https:")+"//cdn-gl.imrworldwide.com/conf/"+e+".js#name="+o+"&ns="+n,
i=s.getElementsByTagName("script")[0],
i.parentNode.insertBefore(r,i),
t[n][o]=t[n][o]||{g:c||{},
ggPM:function(e,c,r,s,i){(t[n][o].q=t[n][o].q||[]).push([e,c,r,s,i])}},t[n][o]
}
}
}
(window,"NOLBUNDLE");
// Created SDK Instance
var nSdkInstance = NOLBUNDLE.nlsQ("XXXXXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXX","nlsnInstance", {nol_sdkDebug: "debug"});
</script>

</syntaxhighlight>

=== Multiple SDK Instances ===
The Browser SDK allows instantiating multiple instances of the object, which can be used simultaneously without any problems, however they must be instantiated with their own unique instance names. There is no maximum number of instances that is enforced in the browser.

The below examples will make use of the same AppId, however using different AppIds will work as well. The principles below follow the same initialization rules stated above for a single instance and simply require a unique instance name and variable name with which the returned instance is assigned.

For more information around the possible parameters that can be passed as well as deeper descriptions for the API calls, please refer to the section on "[[SDK_Initialization_-_Global_Parameters | SDK Initialization - Global Parameters]]".

'''Example of 2 instances on the same page'''

<syntaxhighlight lang="javascript">
//Add Static Queue Snippet
<script>
!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.imrworldwide.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");

//Create SDK Instance(s)
// Notice the unique instance name given to each instance below and the unique variable name for each instance
var nSdkInstanceLive = NOLBUNDLE.nlsQ("XXXXXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXX", "instanceLive", {
nol_sdkDebug: 'debug',
optout: 'false'
});

var nSdkInstanceVod = NOLBUNDLE.nlsQ("XXXXXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXX", "instanceVod", {
nol_sdkDebug: 'debug',
optout: 'false'
});

</script>
</syntaxhighlight>

'''Example of 2 instances using a parent page and iFrame'''

<big>Parent Page (index.html)</big>

<syntaxhighlight lang="javascript">
<!DOCTYPE html>
<html lang="en">

<head>
<meta charset="UTF-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<meta http-equiv="X-UA-Compatible" content="ie=edge">
<title>DCR Static/DCR Video</title>
<script>
/* NLSQUEUE build v*/
!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.imrworldwide.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");

// SDK Initialization
var nSdkInstance = NOLBUNDLE.nlsQ("XXXXXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXX", "staticPage", {
nol_sdkDebug: 'debug',
});

// Static Metadata
var staticMetadata = {
assetid: 'staticTestPage',
type: 'static'
};

// Event 'staticstart' call
nSdkInstance.ggPM(14, staticMetadata);
</script>
</head>

<body>
<h1>DCR Static on Parent/DCR Video in iFrame</h1>
<p>Static measurement is current on parent page when window is in focus</p>
<iframe src="./dcr-video.html" frameborder="0" width="650" height="500" style="background-color: rgb(42, 217, 248);" id="video-iframe"></iframe>
</body>

</html>
</syntaxhighlight>

<big>Nested iFrame Referenced on Parent Page (dcr-video.html)</big>

<syntaxhighlight lang="javascript">
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
<meta http-equiv="X-UA-Compatible" content="ie=edge" />
<title>iFrame Same Source</title>
<script>
/* NLSQUEUE build v*/
!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.imrworldwide.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");

// SDK Initialization
var nSdkInstance = NOLBUNDLE.nlsQ("XXXXXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXX", "videoPlayer", {
nol_sdkDebug: 'debug',
});

var contentMetadata = {
type: "content",
length: "300",
title: "Skydiving Across Europe",
program: "latacg",
censuscategory: "Enlisted",
assetid: "204558915992",
section: "ProgramAsset8",
tv: "true",
adModel: "0",
dataSrc: "cms",
segA: "S07E04:NBC",
segB: "teams",
segC:"AtlanataFalcons",
}
</script>
</head>
<body>
<p>I'm iframe SDK DCR Video measurement, DCR static measurement should continue when clicking "play" on video</p>
<main>
<video
controls
src="https://archive.org/download/BigBuckBunny_124/Content/big_buck_bunny_720p_surround.mp4"
poster="https://peach.blender.org/wp-content/uploads/title_anouncement.jpg?x11217"
width="620">
Sorry, your browser doesn't support embedded videos, but don't worry, you can
<a href="https://archive.org/details/BigBuckBunny_124">download it</a>
and watch it with your favorite video player!
</video>
</main>
<script src="../player.js"></script>
</body>
</html>

</syntaxhighlight>

=== SDK Initialization to measure the Viewability & Audibility ===
To support viewability metrics in the web page the integrator has to provide a tag value of the player view to let Nielsen SDK know that there is a player that needs to be tracked. It’s called the ‘containerId’ and it should be passed in the as string while initializing the Nielsen browser SDK.

NOLBUNDLE.nlsQ("<apid>", "<instanceName>",{containerId: <playerElementID>, nol_sdkDebug: "debug"})

'''Example SDK Initialization for Viewability'''

Your configuration should include the Static Queue Snippet and an SDK Instance for your unique App ID as shown in the example:
<syntaxhighlight lang="javascript">
//Add Static Queue Snippet
<script>
! function(t, n) {
t[n] = t[n] || {
nlsQ: function(e, o, c, r, s, i) {
return s = t.document,
r = s.createElement("script"),
r.async = 1,
r.src = ("http:" === t.location.protocol ? "http:" : "https:") + "//cdn-gl.imrworldwide.com/conf/" + e + ".js#name=" + o + "&ns=" + n,
i = s.getElementsByTagName("script")[0],
i.parentNode.insertBefore(r, i),
t[n][o] = t[n][o] || {
g: c || {},
ggPM: function(e, c, r, s, i) {
(t[n][o].q = t[n][o].q || []).push([e, c, r, s, i])
}
}, t[n][o]
}
}
}
(window, "NOLBUNDLE");

//Create SDK Instance
var nSdkInstance = NOLBUNDLE.nlsQ("XXXXXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXX", "nlsnInstance", {containerId: “player1”, nol_sdkDebug: "debug"});
</script>

</syntaxhighlight>

== Browser SDK API Methods & Properties ==
{| class="wikitable sortable"
|-
! Method / Property !! Event # !! DTVR !! DAR !! DCR !! Description
|-
| [[loadMetadata (Browser)|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.
|-
| [[play (Browser)|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”.
|-
| [[sendID3 (Browser)|sendID3]] || 55 || ✔ || ✘ || ✘ || Used to send the ID3 metadata.
|-
| [[setPlayheadPosition (Browser)|setPlayheadPosition]] || 49 || ✘ || ✘ || ✔ || Used to send the playhead position.
|-
| [[stop (Browser)|stop]] || 7 || ✘ || ✘ || ✔ || Used when switching between ad and content or content and ad.
|-
| [[end (Browser)|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
|-
| [[staticstart (Browser)|staticstart]] || 14 || ✘ || ✘ || ✔ || Used to send the metadata for the static page.
|-
| [[StaticEnd (Browser)|staticend]] || 56 || ✘ || ✘ || ✔ || In Single Page Application (SPA) it is imperative that staticend is called prior to the loading of new metadata. This allows the Browser SDK to properly credit the previous section/content being viewed before measuring the new one.
|-
| [[updateOTT (Browser)|updateOTT]] || - || ✘ || ✘ || ✔ || Used to notify Browser SDK that the remote OTT device (like Google ChromeCast, Roku, Amazon FireTV, etc.) is connected / disconnected (change of OTT status).
|-
| [[ onPaginate (Browser)|onPaginate]] || 30 || ✘ || ✘ || ✔ || Used to create a new instance of the SDK object
|-
| [[updateMetadata (Browser)|updateMetadata]] || 35 || ✔ || ✔ || ✔ || This event is used for updating metadata parameters for the content or ad that is being played.
|-
| [[setVolume_(Browser)|setVolume]] || 61 || ✔ || ✘ || ✔ || Used to pass in the player volume levels in %. Default value is -1.
|}

== Retrieving ID3 Tags ==
The video player must have the ability to extract ID3 tags and supply them to the Browser SDK, based on the HLS standard.
*An ID3 tag spans two PES packets.
**In the first PES packet, look for www.nielsen.com, this is the start of the ID3 tag. Continue to parse the first PES packet until the undefined char "\ufffd" is found. This forms the first half of the ID3 tag
**In the second PES packet, identify the end pattern – a regEx of /(\/\d+){3}/ and look to remove the lowest index of either "\x00" and/or "\ufffd". Now the second packet has been appended and the demarcation of the Nielsen-specific data has been defined.

Follow the procedure below, to extract Nielsen ID3 tags from an MPEG-2 transport stream (including HLS streams).
#Parse the Program Map Table (PMT) to find the PID of the metadata stream. Confirm the presence of the metadata descriptor described in section 2.3.3 of Apple’s “HTTP Live Streaming Metadata Spec.pdf”. Only private streams with metadata descriptor present should be considered as ID3-tag metadata streams.
#Parse the HLS/Transport stream for any '''PES header''' with the PID found in step 1.
#Follow standard MPEG-2 parsing procedures to locate the start of the payload of the PES packet.
#Copy the PES payload into a buffer.
#The ID3 tag spans 2 PES packets. Parse the stream for the next packet whose PID is set to the PID found in step 1. Typically the ID3 Tag is of 249 bytes. The steps below guide towards extraction of the ID3 tag
##In the first PES packet, look for "www.nielsen.com" , this is the start of the ID3 tag. Keep on parsing the first PES packet until the undefined char "\ufffd" is found. This forms the first half of the ID3 tag
##In the second PES packet, identify the end pattern, a regEx of /(\/\d+){3}/ and look to remove the lowest index of either “\x00” and/or “\ufffd”. Now the second packet has been appended and the demarcation of the Nielsen specific data has been defined. This segment can be simply substringed.
##Concatenate this substringed segment with the payload derived from the first packet get the ID3 payload.
#Check the length of the contents in the buffer to make sure that it is equal to the size of a Nielsen ID3 tag.
#Ensure that the ID3 byte array is converted into the string and escape it, so that the SDK can consume it.
Repeat steps 2 through 7 for all ID3 tags in the stream.

'''References'''
*[http://www.iso.org/iso/catalogue_detail?csnumber=44169. ISO/IEC 13818-1:2007] Information technology – Generic coding of moving pictures and associated audio information: Systems
*https://developer.apple.com/library/content/documentation/AudioVideo/Conceptual/HTTP_Live_Streaming_Metadata_Spec/

=== Sample ID3 tags ===
* <code>www.nielsen.com/X100zdCIGeIlgZnkYj6UvQ==/X100zdCIGeIlgZnkYj6UvQ==/AAAB2Jz2_k74GXSzx4npHuI_<wbr />JwJd3QSUpW30rDkGTcbHEzIMWleCzM-uvNOP9fzJcQMWQLJqzXMCAxParOb5sGijSV9dNM3QiBniJYGZ5GI-lL1fXTTN0IgZ4iWBmeRiPpS9AAAAAAAAAAAAAAAAAAAAAFJWFM5SVhTONNU=/00000/00000/00</code>
* <code>www.nielsen.com/X100zdCIGeIlgZnkYj6UvQ==/R8WHe7pEBeqBhu8jTeXydg==/AAICoyitYqlxT7n6aZ0oMCGhe<wbr />Fi4CXFp46AMUPZz1lMr_M9tr3_cjee1SHqxrOiVerMDLeyn9xzocZSKwi746Re8vNOtpNCAZjYABs_J0R25IHpvOc1HS8<wbr />QHGgD5TgOJeS6gX100zdCIGeIlgZnkYj6UvVJWFNhSVhTiPE0=/00000/46016/00</code>
<blockquote>'''Note''': ID3 tags are not applicable for International (Germany)</blockquote>

== Browser Opt-Out Implementation ==
The site in which video content is being measure via Nielsen methodology must provide the means for the user to opt-out of, or opt back into Nielsen Measurement.

For Browser-based applications, opt-out setting is stored via Nielsen cookie. Therefore, it is only necessary that users be made aware of measurement opt-out by incorporating the template below in the user interface.

=== Sample Opt Out Template ===
Our properties may feature Nielsen’s proprietary measurement software which will allow to contribute to market research, like Nielsen’s TV Ratings. To learn more about this information, see https://www.nielsen.com/digitalprivacy. Nielsen’s software may collect your choices with regards to it.

== Nielsen Privacy Requirements ==
Privacy protections that Nielsen ensures to have with each App SDK integration are as follows.
*Disclosure of viewership data collection in EULA / Privacy Policy
*A link in the EULA/Privacy policy, or in another conspicuous location within the App, to a Nielsen-hosted web page outlining what Nielsen is collecting and how it is being used
*Method for users to opt-out of Nielsen measurement, any time while using the application

=== Ratings Data Flow ===
Every view of creditable and watermarked content is measured by Nielsen.
[[File:RatingsDataFlow.png]]

'''Information NOT Shared'''
* '''With Nielsen'''
** User's Identity
* '''With Data Provider'''
** Content information
** Whether user is viewing an ad or video content
** Player used to play the streaming (audio / video, etc.)
** Values being de-duped / aggregating for

Nielsen collects only what it needs for audience measurement. Every view of creditable, watermarked content will be measured by Nielsen.

=== Data Collected ===
{| class="wikitable"
|-
! Type of Information !! Parameter !! Transmitted to Nielsen? !! Sent to Provider?
|-
| rowspan="8" | Nielsen ID3 Watermark
|-
| FinalDistributor Timestamp || Yes || No
|-
| Program Content Timestamp || Yes || No
|-
| Mobile Breakout Code || Yes || No
|-
| Commercial Credit Code – Linear or Dynamic || Yes || No
|-
| Time ShiftedViewing Code || Yes || No
|-
| Segment Number || Yes || No
|-
| Segment View Pattern || Yes || No
|-
| rowspan="7" | Device/App Info
|-
| Device OSVersion || Yes || Yes
|-
| Device Model || Yes || No
|-
| Cache Buster || Yes || Yes
|-
| SDKDisabled Flag || Yes || No
|-
| ServerCode || Yes || No
|-
| Channel or URL || Yes || No
|-
| rowspan="9" | Nielsen Identifiers
|-
| Client ID || Yes || No
|-
| Campaign ID || Yes || Yes
|-
| Nielsen Unique Device ID || Yes || No
|-
| Application ID || Yes || No
|-
| DeviceGroup (ex. Tablet, Smartphone, Desktop) || Yes || Yes
|-
| OS Group (ex. Android, iOS, Windows) || Yes || Yes
|-
| SDKVersion || Yes || No
|-
| IP Address for DMA, Country Code || Yes || Yes
|}
<blockquote>'''Note''': Data is hashed, and encrypted using AES 128 before transmission to data provider.</blockquote>

{{Viewability_Data_Collected}}

==== Example ping sent to provider ====
* <code><nowiki>https://provider.com/cgi-bin/brandlift.php</nowiki>?campaign_id=ff12725d724fac7934cf6003f096b4cd<wbr />&placement_id=a4164b8fba9ee7c873a9c72c7091bb58<wbr />&creative_id=25280139b61a947e127a52f56c8a2fdd<wbr />&segment1=9000<wbr />&segment2=41<wbr />&segment3=iOS<wbr />&OSVer=iOS6.1<wbr />&c9=<wbr />&devgrp=tablet<wbr />&h=f5f243fe6d<wbr />&rnd=1376971827360</code>

This ping passes the following parameters to the provider:
* Campaign ID – (campaign, placement, creative)
* Country Code
* DMA
* OS Group (ex. iOS, Android)
* DeviceOS Version
* Device Advertiser ID
* DeviceGroup (ex. Tablet, Smartphone, Desktop)
* Cache Buster

{{Template:Browser_Privacy_and_Opt-Out}}

=== Opt-Out Implementation ===
The site must provide the means for the user to opt-out of, or opt back into Nielsen Measurement.

'''Sample Opt Out Template'''

Our properties may feature Nielsen’s proprietary measurement software which will allow to contribute to market research, like Nielsen’s TV Ratings. To learn more about this information, please [http://priv-policy.imrworldwide.com/priv/mobile/us/en/optout.html| click here]. Nielsen’s software may collect your choices with regards to it.

== Testing ==
See [[Digital Measurement Testing#Testing Browser Implementation|Digital Measurement Testing - Testing Browser Implementation]].

Browser SDK API Reference

2024-12-09T19:41:19Z

AmySockanathan: /* Multiple SDK Instances */

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

== Setting up Development Environment ==
=== Step 1: Configure Content Management System (CMS) ===
Configure CMS to send the required values (see table below). Any internal CMS_variable names can be used for passing the data.

Ensure to capture these CMS_variable names in the SDK Configuration Form.

For more information on setting variable names, see the SDK Configuration Form included within the SDK package.

{| class="wikitable"
|-
! Required Data !! Description !! Value
|-
| dataSrc || Used when both CMS metadata and ID3 data are present in the player. Setting this field tells the SDK whether to use the CMS metadata or the ID3 payload to derive the pings || cms
|-
| type || Type of asset: ad or content || preroll, midroll, postroll, or content
|-
| assetid || unique ID assigned to asset || custom <br>(no [[Special Characters]])
|-
| OCR Tag || OCR tag provided by Nielsen for implementation on the ad unit || Complete OCR URL
|-
| program || Name of program (25 character limit) || custom
|-
| title || Episode title (40 character limit) || custom
|-
| length || Length of content in seconds || Length in seconds, 0 for live stream
|-
| adloadtype || Type of ad load || "1" - Linear "2" - Dynamic(default)
|-
| hasAds || Identify if content includes Ads || "0" - no ads "1" - includes ads "2" - unknown(default)
|-
| isfullepisode || Full episode flag || "y" - full episode "n" - non full episode
|-
| segA || Segment A (this is not available for video reporting as the episode title is reported) || custom value
|-
| segB || Custom segment B || custom value
|-
| segC || Custom segment C || custom value
|-
| crossId1 || Standard episode ID || custom value
|-
| crossId2 || Content originator (required only for distributors) || custom value
|-
| airdate || Original air date and time in Eastern Time. For non-US countries, it should be local time. || YYYYMMDD HH24:MI:SS
|-
| containerId || HTML DOM element of the Player container (for Viewability&Audibility feature only) || custom value
|-
|luid
|Living Unit ID - Experian Household ID
'''Note: This parameter is applicable only for CTV and First Party Livestream data'''
|"B0EOFEDgD"
|}

=== Step 2: Complete the Nielsen SDK Configuration Form ===
The SDK is designed to map the <code>CMS_variable names</code>. To support the custom mapping, the developer is required to complete the SDK Configuration Form. The form will be provided during onboarding along with this guide.

== Initialization ==
=== Obtain the Nielsen Application ID (apid) and Browser SDK URLs ===
The Nielsen <code>apid</code> 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 Browser SDK ===
There are two steps required for configuring the SDK:

'''Add Static Queue Snippet'''

*Add Static Queue Snippet
*Create SDK Instance

Add the following script tag to the website:
<syntaxhighlight lang="javascript">

<script type="text/javascript">
!function(t,n)
{
t[n]=t[n]||
{
nlsQ:function(e,o,c,r,s,i)
{
return s=t.document,
r=s.createElement("script"),
r.async=1,
r.src=("http:"===t.location.protocol?"http:":"https:")+"//cdn-gl.imrworldwide.com/conf/"+e+".js#name="+o+"&ns="+n,
i=s.getElementsByTagName("script")[0],
i.parentNode.insertBefore(r,i),
t[n][o]=t[n][o]||{g:c||{},
ggPM:function(e,c,r,s,i){(t[n][o].q=t[n][o].q||[]).push([e,c,r,s,i])}},t[n][o]
}
}
}
(window,"NOLBUNDLE");
</script>

</syntaxhighlight>

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.

'''Create SDK Instance'''

To initialize the SDK, create an SDK instance by making the initialization call:

'''Initialization API Call'''
<syntaxhighlight lang="javascript">

NOLBUNDLE.nlsQ("<apid>", "<instanceName>",{nol_sdkDebug: "debug"})

</syntaxhighlight>

When creating an instance, pass the following three values:

=== SDK Initialization – Global Parameters ===
{| class="wikitable"
|-
! Parameters !! Description !! Value
|-
| apid || UniqueID assigned to player/site. || 'XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX'
|-
| instanceName || Name of SDK instance || "any string value"
|-
| nol_sdkDebug || Enables Nielsen console logging. Only required for testing || "{nol_sdkDebug: "debug"})"
|-
| containerId || HTML DOM element id of the player container. Only for Viewability & Audibility feature. || {containerId: "playerId1"}
|-
| 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&"
|}

{{example_bsdk_init}}

'''Example SDK Configuration'''

The configuration should include the Static Queue Snippet and an SDK Instance for an unique App ID as shown in the example:

<syntaxhighlight lang="javascript">

<script type="text/javascript">
!function(t,n)
{
t[n]=t[n]||
{
nlsQ:function(e,o,c,r,s,i)
{
return s=t.document,
r=s.createElement("script"),
r.async=1,
r.src=("http:"===t.location.protocol?"http:":"https:")+"//cdn-gl.imrworldwide.com/conf/"+e+".js#name="+o+"&ns="+n,
i=s.getElementsByTagName("script")[0],
i.parentNode.insertBefore(r,i),
t[n][o]=t[n][o]||{g:c||{},
ggPM:function(e,c,r,s,i){(t[n][o].q=t[n][o].q||[]).push([e,c,r,s,i])}},t[n][o]
}
}
}
(window,"NOLBUNDLE");
// Created SDK Instance
var nSdkInstance = NOLBUNDLE.nlsQ("XXXXXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXX","nlsnInstance", {nol_sdkDebug: "debug"});
</script>

</syntaxhighlight>

=== Multiple SDK Instances ===
The Browser SDK allows instantiating multiple instances of the object, which can be used simultaneously without any problems, however they must be instantiated with their own unique instance names. There is no maximum number of instances that is enforced in the browser.

The below examples will make use of the same AppId, however using different AppIds will work as well. The principles below follow the same initialization rules stated above for a single instance and simply require a unique instance name and variable name with which the returned instance is assigned.

For more information around the possible parameters that can be passed as well as deeper descriptions for the API calls, please refer to the section on "[[Browser_SDK_API_Reference#SDK_Initialization_-_Global_Parameters | SDK Initialization - Global Parameters]]".

'''Example of 2 instances on the same page'''

<syntaxhighlight lang="javascript">
//Add Static Queue Snippet
<script>
!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.imrworldwide.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");

//Create SDK Instance(s)
// Notice the unique instance name given to each instance below and the unique variable name for each instance
var nSdkInstanceLive = NOLBUNDLE.nlsQ("XXXXXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXX", "instanceLive", {
nol_sdkDebug: 'debug',
optout: 'false'
});

var nSdkInstanceVod = NOLBUNDLE.nlsQ("XXXXXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXX", "instanceVod", {
nol_sdkDebug: 'debug',
optout: 'false'
});

</script>
</syntaxhighlight>

'''Example of 2 instances using a parent page and iFrame'''

<big>Parent Page (index.html)</big>

<syntaxhighlight lang="javascript">
<!DOCTYPE html>
<html lang="en">

<head>
<meta charset="UTF-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<meta http-equiv="X-UA-Compatible" content="ie=edge">
<title>DCR Static/DCR Video</title>
<script>
/* NLSQUEUE build v*/
!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.imrworldwide.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");

// SDK Initialization
var nSdkInstance = NOLBUNDLE.nlsQ("XXXXXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXX", "staticPage", {
nol_sdkDebug: 'debug',
});

// Static Metadata
var staticMetadata = {
assetid: 'staticTestPage',
type: 'static'
};

// Event 'staticstart' call
nSdkInstance.ggPM(14, staticMetadata);
</script>
</head>

<body>
<h1>DCR Static on Parent/DCR Video in iFrame</h1>
<p>Static measurement is current on parent page when window is in focus</p>
<iframe src="./dcr-video.html" frameborder="0" width="650" height="500" style="background-color: rgb(42, 217, 248);" id="video-iframe"></iframe>
</body>

</html>
</syntaxhighlight>

<big>Nested iFrame Referenced on Parent Page (dcr-video.html)</big>

<syntaxhighlight lang="javascript">
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
<meta http-equiv="X-UA-Compatible" content="ie=edge" />
<title>iFrame Same Source</title>
<script>
/* NLSQUEUE build v*/
!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.imrworldwide.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");

// SDK Initialization
var nSdkInstance = NOLBUNDLE.nlsQ("XXXXXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXX", "videoPlayer", {
nol_sdkDebug: 'debug',
});

var contentMetadata = {
type: "content",
length: "300",
title: "Skydiving Across Europe",
program: "latacg",
censuscategory: "Enlisted",
assetid: "204558915992",
section: "ProgramAsset8",
tv: "true",
adModel: "0",
dataSrc: "cms",
segA: "S07E04:NBC",
segB: "teams",
segC:"AtlanataFalcons",
}
</script>
</head>
<body>
<p>I'm iframe SDK DCR Video measurement, DCR static measurement should continue when clicking "play" on video</p>
<main>
<video
controls
src="https://archive.org/download/BigBuckBunny_124/Content/big_buck_bunny_720p_surround.mp4"
poster="https://peach.blender.org/wp-content/uploads/title_anouncement.jpg?x11217"
width="620">
Sorry, your browser doesn't support embedded videos, but don't worry, you can
<a href="https://archive.org/details/BigBuckBunny_124">download it</a>
and watch it with your favorite video player!
</video>
</main>
<script src="../player.js"></script>
</body>
</html>

</syntaxhighlight>

=== SDK Initialization to measure the Viewability & Audibility ===
To support viewability metrics in the web page the integrator has to provide a tag value of the player view to let Nielsen SDK know that there is a player that needs to be tracked. It’s called the ‘containerId’ and it should be passed in the as string while initializing the Nielsen browser SDK.

NOLBUNDLE.nlsQ("<apid>", "<instanceName>",{containerId: <playerElementID>, nol_sdkDebug: "debug"})

'''Example SDK Initialization for Viewability'''

Your configuration should include the Static Queue Snippet and an SDK Instance for your unique App ID as shown in the example:
<syntaxhighlight lang="javascript">
//Add Static Queue Snippet
<script>
! function(t, n) {
t[n] = t[n] || {
nlsQ: function(e, o, c, r, s, i) {
return s = t.document,
r = s.createElement("script"),
r.async = 1,
r.src = ("http:" === t.location.protocol ? "http:" : "https:") + "//cdn-gl.imrworldwide.com/conf/" + e + ".js#name=" + o + "&ns=" + n,
i = s.getElementsByTagName("script")[0],
i.parentNode.insertBefore(r, i),
t[n][o] = t[n][o] || {
g: c || {},
ggPM: function(e, c, r, s, i) {
(t[n][o].q = t[n][o].q || []).push([e, c, r, s, i])
}
}, t[n][o]
}
}
}
(window, "NOLBUNDLE");

//Create SDK Instance
var nSdkInstance = NOLBUNDLE.nlsQ("XXXXXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXX", "nlsnInstance", {containerId: “player1”, nol_sdkDebug: "debug"});
</script>

</syntaxhighlight>

== Browser SDK API Methods & Properties ==
{| class="wikitable sortable"
|-
! Method / Property !! Event # !! DTVR !! DAR !! DCR !! Description
|-
| [[loadMetadata (Browser)|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.
|-
| [[play (Browser)|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”.
|-
| [[sendID3 (Browser)|sendID3]] || 55 || ✔ || ✘ || ✘ || Used to send the ID3 metadata.
|-
| [[setPlayheadPosition (Browser)|setPlayheadPosition]] || 49 || ✘ || ✘ || ✔ || Used to send the playhead position.
|-
| [[stop (Browser)|stop]] || 7 || ✘ || ✘ || ✔ || Used when switching between ad and content or content and ad.
|-
| [[end (Browser)|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
|-
| [[staticstart (Browser)|staticstart]] || 14 || ✘ || ✘ || ✔ || Used to send the metadata for the static page.
|-
| [[StaticEnd (Browser)|staticend]] || 56 || ✘ || ✘ || ✔ || In Single Page Application (SPA) it is imperative that staticend is called prior to the loading of new metadata. This allows the Browser SDK to properly credit the previous section/content being viewed before measuring the new one.
|-
| [[updateOTT (Browser)|updateOTT]] || - || ✘ || ✘ || ✔ || Used to notify Browser SDK that the remote OTT device (like Google ChromeCast, Roku, Amazon FireTV, etc.) is connected / disconnected (change of OTT status).
|-
| [[ onPaginate (Browser)|onPaginate]] || 30 || ✘ || ✘ || ✔ || Used to create a new instance of the SDK object
|-
| [[updateMetadata (Browser)|updateMetadata]] || 35 || ✔ || ✔ || ✔ || This event is used for updating metadata parameters for the content or ad that is being played.
|-
| [[setVolume_(Browser)|setVolume]] || 61 || ✔ || ✘ || ✔ || Used to pass in the player volume levels in %. Default value is -1.
|}

== Retrieving ID3 Tags ==
The video player must have the ability to extract ID3 tags and supply them to the Browser SDK, based on the HLS standard.
*An ID3 tag spans two PES packets.
**In the first PES packet, look for www.nielsen.com, this is the start of the ID3 tag. Continue to parse the first PES packet until the undefined char "\ufffd" is found. This forms the first half of the ID3 tag
**In the second PES packet, identify the end pattern – a regEx of /(\/\d+){3}/ and look to remove the lowest index of either "\x00" and/or "\ufffd". Now the second packet has been appended and the demarcation of the Nielsen-specific data has been defined.

Follow the procedure below, to extract Nielsen ID3 tags from an MPEG-2 transport stream (including HLS streams).
#Parse the Program Map Table (PMT) to find the PID of the metadata stream. Confirm the presence of the metadata descriptor described in section 2.3.3 of Apple’s “HTTP Live Streaming Metadata Spec.pdf”. Only private streams with metadata descriptor present should be considered as ID3-tag metadata streams.
#Parse the HLS/Transport stream for any '''PES header''' with the PID found in step 1.
#Follow standard MPEG-2 parsing procedures to locate the start of the payload of the PES packet.
#Copy the PES payload into a buffer.
#The ID3 tag spans 2 PES packets. Parse the stream for the next packet whose PID is set to the PID found in step 1. Typically the ID3 Tag is of 249 bytes. The steps below guide towards extraction of the ID3 tag
##In the first PES packet, look for "www.nielsen.com" , this is the start of the ID3 tag. Keep on parsing the first PES packet until the undefined char "\ufffd" is found. This forms the first half of the ID3 tag
##In the second PES packet, identify the end pattern, a regEx of /(\/\d+){3}/ and look to remove the lowest index of either “\x00” and/or “\ufffd”. Now the second packet has been appended and the demarcation of the Nielsen specific data has been defined. This segment can be simply substringed.
##Concatenate this substringed segment with the payload derived from the first packet get the ID3 payload.
#Check the length of the contents in the buffer to make sure that it is equal to the size of a Nielsen ID3 tag.
#Ensure that the ID3 byte array is converted into the string and escape it, so that the SDK can consume it.
Repeat steps 2 through 7 for all ID3 tags in the stream.

'''References'''
*[http://www.iso.org/iso/catalogue_detail?csnumber=44169. ISO/IEC 13818-1:2007] Information technology – Generic coding of moving pictures and associated audio information: Systems
*https://developer.apple.com/library/content/documentation/AudioVideo/Conceptual/HTTP_Live_Streaming_Metadata_Spec/

=== Sample ID3 tags ===
* <code>www.nielsen.com/X100zdCIGeIlgZnkYj6UvQ==/X100zdCIGeIlgZnkYj6UvQ==/AAAB2Jz2_k74GXSzx4npHuI_<wbr />JwJd3QSUpW30rDkGTcbHEzIMWleCzM-uvNOP9fzJcQMWQLJqzXMCAxParOb5sGijSV9dNM3QiBniJYGZ5GI-lL1fXTTN0IgZ4iWBmeRiPpS9AAAAAAAAAAAAAAAAAAAAAFJWFM5SVhTONNU=/00000/00000/00</code>
* <code>www.nielsen.com/X100zdCIGeIlgZnkYj6UvQ==/R8WHe7pEBeqBhu8jTeXydg==/AAICoyitYqlxT7n6aZ0oMCGhe<wbr />Fi4CXFp46AMUPZz1lMr_M9tr3_cjee1SHqxrOiVerMDLeyn9xzocZSKwi746Re8vNOtpNCAZjYABs_J0R25IHpvOc1HS8<wbr />QHGgD5TgOJeS6gX100zdCIGeIlgZnkYj6UvVJWFNhSVhTiPE0=/00000/46016/00</code>
<blockquote>'''Note''': ID3 tags are not applicable for International (Germany)</blockquote>

== Browser Opt-Out Implementation ==
The site in which video content is being measure via Nielsen methodology must provide the means for the user to opt-out of, or opt back into Nielsen Measurement.

For Browser-based applications, opt-out setting is stored via Nielsen cookie. Therefore, it is only necessary that users be made aware of measurement opt-out by incorporating the template below in the user interface.

=== Sample Opt Out Template ===
Our properties may feature Nielsen’s proprietary measurement software which will allow to contribute to market research, like Nielsen’s TV Ratings. To learn more about this information, see https://www.nielsen.com/digitalprivacy. Nielsen’s software may collect your choices with regards to it.

== Nielsen Privacy Requirements ==
Privacy protections that Nielsen ensures to have with each App SDK integration are as follows.
*Disclosure of viewership data collection in EULA / Privacy Policy
*A link in the EULA/Privacy policy, or in another conspicuous location within the App, to a Nielsen-hosted web page outlining what Nielsen is collecting and how it is being used
*Method for users to opt-out of Nielsen measurement, any time while using the application

=== Ratings Data Flow ===
Every view of creditable and watermarked content is measured by Nielsen.
[[File:RatingsDataFlow.png]]

'''Information NOT Shared'''
* '''With Nielsen'''
** User's Identity
* '''With Data Provider'''
** Content information
** Whether user is viewing an ad or video content
** Player used to play the streaming (audio / video, etc.)
** Values being de-duped / aggregating for

Nielsen collects only what it needs for audience measurement. Every view of creditable, watermarked content will be measured by Nielsen.

=== Data Collected ===
{| class="wikitable"
|-
! Type of Information !! Parameter !! Transmitted to Nielsen? !! Sent to Provider?
|-
| rowspan="8" | Nielsen ID3 Watermark
|-
| FinalDistributor Timestamp || Yes || No
|-
| Program Content Timestamp || Yes || No
|-
| Mobile Breakout Code || Yes || No
|-
| Commercial Credit Code – Linear or Dynamic || Yes || No
|-
| Time ShiftedViewing Code || Yes || No
|-
| Segment Number || Yes || No
|-
| Segment View Pattern || Yes || No
|-
| rowspan="7" | Device/App Info
|-
| Device OSVersion || Yes || Yes
|-
| Device Model || Yes || No
|-
| Cache Buster || Yes || Yes
|-
| SDKDisabled Flag || Yes || No
|-
| ServerCode || Yes || No
|-
| Channel or URL || Yes || No
|-
| rowspan="9" | Nielsen Identifiers
|-
| Client ID || Yes || No
|-
| Campaign ID || Yes || Yes
|-
| Nielsen Unique Device ID || Yes || No
|-
| Application ID || Yes || No
|-
| DeviceGroup (ex. Tablet, Smartphone, Desktop) || Yes || Yes
|-
| OS Group (ex. Android, iOS, Windows) || Yes || Yes
|-
| SDKVersion || Yes || No
|-
| IP Address for DMA, Country Code || Yes || Yes
|}
<blockquote>'''Note''': Data is hashed, and encrypted using AES 128 before transmission to data provider.</blockquote>

{{Viewability_Data_Collected}}

==== Example ping sent to provider ====
* <code><nowiki>https://provider.com/cgi-bin/brandlift.php</nowiki>?campaign_id=ff12725d724fac7934cf6003f096b4cd<wbr />&placement_id=a4164b8fba9ee7c873a9c72c7091bb58<wbr />&creative_id=25280139b61a947e127a52f56c8a2fdd<wbr />&segment1=9000<wbr />&segment2=41<wbr />&segment3=iOS<wbr />&OSVer=iOS6.1<wbr />&c9=<wbr />&devgrp=tablet<wbr />&h=f5f243fe6d<wbr />&rnd=1376971827360</code>

This ping passes the following parameters to the provider:
* Campaign ID – (campaign, placement, creative)
* Country Code
* DMA
* OS Group (ex. iOS, Android)
* DeviceOS Version
* Device Advertiser ID
* DeviceGroup (ex. Tablet, Smartphone, Desktop)
* Cache Buster

{{Template:Browser_Privacy_and_Opt-Out}}

=== Opt-Out Implementation ===
The site must provide the means for the user to opt-out of, or opt back into Nielsen Measurement.

'''Sample Opt Out Template'''

Our properties may feature Nielsen’s proprietary measurement software which will allow to contribute to market research, like Nielsen’s TV Ratings. To learn more about this information, please [http://priv-policy.imrworldwide.com/priv/mobile/us/en/optout.html| click here]. Nielsen’s software may collect your choices with regards to it.

== Testing ==
See [[Digital Measurement Testing#Testing Browser Implementation|Digital Measurement Testing - Testing Browser Implementation]].

Browser SDK API Reference

2024-12-09T19:40:20Z

AmySockanathan: /* Multiple SDK Instances */

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

== Setting up Development Environment ==
=== Step 1: Configure Content Management System (CMS) ===
Configure CMS to send the required values (see table below). Any internal CMS_variable names can be used for passing the data.

Ensure to capture these CMS_variable names in the SDK Configuration Form.

For more information on setting variable names, see the SDK Configuration Form included within the SDK package.

{| class="wikitable"
|-
! Required Data !! Description !! Value
|-
| dataSrc || Used when both CMS metadata and ID3 data are present in the player. Setting this field tells the SDK whether to use the CMS metadata or the ID3 payload to derive the pings || cms
|-
| type || Type of asset: ad or content || preroll, midroll, postroll, or content
|-
| assetid || unique ID assigned to asset || custom <br>(no [[Special Characters]])
|-
| OCR Tag || OCR tag provided by Nielsen for implementation on the ad unit || Complete OCR URL
|-
| program || Name of program (25 character limit) || custom
|-
| title || Episode title (40 character limit) || custom
|-
| length || Length of content in seconds || Length in seconds, 0 for live stream
|-
| adloadtype || Type of ad load || "1" - Linear "2" - Dynamic(default)
|-
| hasAds || Identify if content includes Ads || "0" - no ads "1" - includes ads "2" - unknown(default)
|-
| isfullepisode || Full episode flag || "y" - full episode "n" - non full episode
|-
| segA || Segment A (this is not available for video reporting as the episode title is reported) || custom value
|-
| segB || Custom segment B || custom value
|-
| segC || Custom segment C || custom value
|-
| crossId1 || Standard episode ID || custom value
|-
| crossId2 || Content originator (required only for distributors) || custom value
|-
| airdate || Original air date and time in Eastern Time. For non-US countries, it should be local time. || YYYYMMDD HH24:MI:SS
|-
| containerId || HTML DOM element of the Player container (for Viewability&Audibility feature only) || custom value
|-
|luid
|Living Unit ID - Experian Household ID
'''Note: This parameter is applicable only for CTV and First Party Livestream data'''
|"B0EOFEDgD"
|}

=== Step 2: Complete the Nielsen SDK Configuration Form ===
The SDK is designed to map the <code>CMS_variable names</code>. To support the custom mapping, the developer is required to complete the SDK Configuration Form. The form will be provided during onboarding along with this guide.

== Initialization ==
=== Obtain the Nielsen Application ID (apid) and Browser SDK URLs ===
The Nielsen <code>apid</code> 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 Browser SDK ===
There are two steps required for configuring the SDK:

'''Add Static Queue Snippet'''

*Add Static Queue Snippet
*Create SDK Instance

Add the following script tag to the website:
<syntaxhighlight lang="javascript">

<script type="text/javascript">
!function(t,n)
{
t[n]=t[n]||
{
nlsQ:function(e,o,c,r,s,i)
{
return s=t.document,
r=s.createElement("script"),
r.async=1,
r.src=("http:"===t.location.protocol?"http:":"https:")+"//cdn-gl.imrworldwide.com/conf/"+e+".js#name="+o+"&ns="+n,
i=s.getElementsByTagName("script")[0],
i.parentNode.insertBefore(r,i),
t[n][o]=t[n][o]||{g:c||{},
ggPM:function(e,c,r,s,i){(t[n][o].q=t[n][o].q||[]).push([e,c,r,s,i])}},t[n][o]
}
}
}
(window,"NOLBUNDLE");
</script>

</syntaxhighlight>

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.

'''Create SDK Instance'''

To initialize the SDK, create an SDK instance by making the initialization call:

'''Initialization API Call'''
<syntaxhighlight lang="javascript">

NOLBUNDLE.nlsQ("<apid>", "<instanceName>",{nol_sdkDebug: "debug"})

</syntaxhighlight>

When creating an instance, pass the following three values:

=== SDK Initialization – Global Parameters ===
{| class="wikitable"
|-
! Parameters !! Description !! Value
|-
| apid || UniqueID assigned to player/site. || 'XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX'
|-
| instanceName || Name of SDK instance || "any string value"
|-
| nol_sdkDebug || Enables Nielsen console logging. Only required for testing || "{nol_sdkDebug: "debug"})"
|-
| containerId || HTML DOM element id of the player container. Only for Viewability & Audibility feature. || {containerId: "playerId1"}
|-
| 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&"
|}

{{example_bsdk_init}}

'''Example SDK Configuration'''

The configuration should include the Static Queue Snippet and an SDK Instance for an unique App ID as shown in the example:

<syntaxhighlight lang="javascript">

<script type="text/javascript">
!function(t,n)
{
t[n]=t[n]||
{
nlsQ:function(e,o,c,r,s,i)
{
return s=t.document,
r=s.createElement("script"),
r.async=1,
r.src=("http:"===t.location.protocol?"http:":"https:")+"//cdn-gl.imrworldwide.com/conf/"+e+".js#name="+o+"&ns="+n,
i=s.getElementsByTagName("script")[0],
i.parentNode.insertBefore(r,i),
t[n][o]=t[n][o]||{g:c||{},
ggPM:function(e,c,r,s,i){(t[n][o].q=t[n][o].q||[]).push([e,c,r,s,i])}},t[n][o]
}
}
}
(window,"NOLBUNDLE");
// Created SDK Instance
var nSdkInstance = NOLBUNDLE.nlsQ("XXXXXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXX","nlsnInstance", {nol_sdkDebug: "debug"});
</script>

</syntaxhighlight>

=== Multiple SDK Instances ===
The Browser SDK allows instantiating multiple instances of the object, which can be used simultaneously without any problems, however they must be instantiated with their own unique instance names. There is no maximum number of instances that is enforced in the browser.

The below examples will make use of the same AppId, however using different AppIds will work as well. The principles below follow the same initialization rules stated above for a single instance and simply require a unique instance name and variable name with which the returned instance is assigned.

For more information around the possible parameters that can be passed as well as deeper descriptions for the API calls, please refer to the section on "[[Browser_SDK_API_Reference#SDK Initialization - Global Parameters | SDK Initialization - Global Parameters]]".

'''Example of 2 instances on the same page'''

<syntaxhighlight lang="javascript">
//Add Static Queue Snippet
<script>
!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.imrworldwide.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");

//Create SDK Instance(s)
// Notice the unique instance name given to each instance below and the unique variable name for each instance
var nSdkInstanceLive = NOLBUNDLE.nlsQ("XXXXXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXX", "instanceLive", {
nol_sdkDebug: 'debug',
optout: 'false'
});

var nSdkInstanceVod = NOLBUNDLE.nlsQ("XXXXXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXX", "instanceVod", {
nol_sdkDebug: 'debug',
optout: 'false'
});

</script>
</syntaxhighlight>

'''Example of 2 instances using a parent page and iFrame'''

<big>Parent Page (index.html)</big>

<syntaxhighlight lang="javascript">
<!DOCTYPE html>
<html lang="en">

<head>
<meta charset="UTF-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<meta http-equiv="X-UA-Compatible" content="ie=edge">
<title>DCR Static/DCR Video</title>
<script>
/* NLSQUEUE build v*/
!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.imrworldwide.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");

// SDK Initialization
var nSdkInstance = NOLBUNDLE.nlsQ("XXXXXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXX", "staticPage", {
nol_sdkDebug: 'debug',
});

// Static Metadata
var staticMetadata = {
assetid: 'staticTestPage',
type: 'static'
};

// Event 'staticstart' call
nSdkInstance.ggPM(14, staticMetadata);
</script>
</head>

<body>
<h1>DCR Static on Parent/DCR Video in iFrame</h1>
<p>Static measurement is current on parent page when window is in focus</p>
<iframe src="./dcr-video.html" frameborder="0" width="650" height="500" style="background-color: rgb(42, 217, 248);" id="video-iframe"></iframe>
</body>

</html>
</syntaxhighlight>

<big>Nested iFrame Referenced on Parent Page (dcr-video.html)</big>

<syntaxhighlight lang="javascript">
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
<meta http-equiv="X-UA-Compatible" content="ie=edge" />
<title>iFrame Same Source</title>
<script>
/* NLSQUEUE build v*/
!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.imrworldwide.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");

// SDK Initialization
var nSdkInstance = NOLBUNDLE.nlsQ("XXXXXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXX", "videoPlayer", {
nol_sdkDebug: 'debug',
});

var contentMetadata = {
type: "content",
length: "300",
title: "Skydiving Across Europe",
program: "latacg",
censuscategory: "Enlisted",
assetid: "204558915992",
section: "ProgramAsset8",
tv: "true",
adModel: "0",
dataSrc: "cms",
segA: "S07E04:NBC",
segB: "teams",
segC:"AtlanataFalcons",
}
</script>
</head>
<body>
<p>I'm iframe SDK DCR Video measurement, DCR static measurement should continue when clicking "play" on video</p>
<main>
<video
controls
src="https://archive.org/download/BigBuckBunny_124/Content/big_buck_bunny_720p_surround.mp4"
poster="https://peach.blender.org/wp-content/uploads/title_anouncement.jpg?x11217"
width="620">
Sorry, your browser doesn't support embedded videos, but don't worry, you can
<a href="https://archive.org/details/BigBuckBunny_124">download it</a>
and watch it with your favorite video player!
</video>
</main>
<script src="../player.js"></script>
</body>
</html>

</syntaxhighlight>

=== SDK Initialization to measure the Viewability & Audibility ===
To support viewability metrics in the web page the integrator has to provide a tag value of the player view to let Nielsen SDK know that there is a player that needs to be tracked. It’s called the ‘containerId’ and it should be passed in the as string while initializing the Nielsen browser SDK.

NOLBUNDLE.nlsQ("<apid>", "<instanceName>",{containerId: <playerElementID>, nol_sdkDebug: "debug"})

'''Example SDK Initialization for Viewability'''

Your configuration should include the Static Queue Snippet and an SDK Instance for your unique App ID as shown in the example:
<syntaxhighlight lang="javascript">
//Add Static Queue Snippet
<script>
! function(t, n) {
t[n] = t[n] || {
nlsQ: function(e, o, c, r, s, i) {
return s = t.document,
r = s.createElement("script"),
r.async = 1,
r.src = ("http:" === t.location.protocol ? "http:" : "https:") + "//cdn-gl.imrworldwide.com/conf/" + e + ".js#name=" + o + "&ns=" + n,
i = s.getElementsByTagName("script")[0],
i.parentNode.insertBefore(r, i),
t[n][o] = t[n][o] || {
g: c || {},
ggPM: function(e, c, r, s, i) {
(t[n][o].q = t[n][o].q || []).push([e, c, r, s, i])
}
}, t[n][o]
}
}
}
(window, "NOLBUNDLE");

//Create SDK Instance
var nSdkInstance = NOLBUNDLE.nlsQ("XXXXXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXX", "nlsnInstance", {containerId: “player1”, nol_sdkDebug: "debug"});
</script>

</syntaxhighlight>

== Browser SDK API Methods & Properties ==
{| class="wikitable sortable"
|-
! Method / Property !! Event # !! DTVR !! DAR !! DCR !! Description
|-
| [[loadMetadata (Browser)|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.
|-
| [[play (Browser)|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”.
|-
| [[sendID3 (Browser)|sendID3]] || 55 || ✔ || ✘ || ✘ || Used to send the ID3 metadata.
|-
| [[setPlayheadPosition (Browser)|setPlayheadPosition]] || 49 || ✘ || ✘ || ✔ || Used to send the playhead position.
|-
| [[stop (Browser)|stop]] || 7 || ✘ || ✘ || ✔ || Used when switching between ad and content or content and ad.
|-
| [[end (Browser)|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
|-
| [[staticstart (Browser)|staticstart]] || 14 || ✘ || ✘ || ✔ || Used to send the metadata for the static page.
|-
| [[StaticEnd (Browser)|staticend]] || 56 || ✘ || ✘ || ✔ || In Single Page Application (SPA) it is imperative that staticend is called prior to the loading of new metadata. This allows the Browser SDK to properly credit the previous section/content being viewed before measuring the new one.
|-
| [[updateOTT (Browser)|updateOTT]] || - || ✘ || ✘ || ✔ || Used to notify Browser SDK that the remote OTT device (like Google ChromeCast, Roku, Amazon FireTV, etc.) is connected / disconnected (change of OTT status).
|-
| [[ onPaginate (Browser)|onPaginate]] || 30 || ✘ || ✘ || ✔ || Used to create a new instance of the SDK object
|-
| [[updateMetadata (Browser)|updateMetadata]] || 35 || ✔ || ✔ || ✔ || This event is used for updating metadata parameters for the content or ad that is being played.
|-
| [[setVolume_(Browser)|setVolume]] || 61 || ✔ || ✘ || ✔ || Used to pass in the player volume levels in %. Default value is -1.
|}

== Retrieving ID3 Tags ==
The video player must have the ability to extract ID3 tags and supply them to the Browser SDK, based on the HLS standard.
*An ID3 tag spans two PES packets.
**In the first PES packet, look for www.nielsen.com, this is the start of the ID3 tag. Continue to parse the first PES packet until the undefined char "\ufffd" is found. This forms the first half of the ID3 tag
**In the second PES packet, identify the end pattern – a regEx of /(\/\d+){3}/ and look to remove the lowest index of either "\x00" and/or "\ufffd". Now the second packet has been appended and the demarcation of the Nielsen-specific data has been defined.

Follow the procedure below, to extract Nielsen ID3 tags from an MPEG-2 transport stream (including HLS streams).
#Parse the Program Map Table (PMT) to find the PID of the metadata stream. Confirm the presence of the metadata descriptor described in section 2.3.3 of Apple’s “HTTP Live Streaming Metadata Spec.pdf”. Only private streams with metadata descriptor present should be considered as ID3-tag metadata streams.
#Parse the HLS/Transport stream for any '''PES header''' with the PID found in step 1.
#Follow standard MPEG-2 parsing procedures to locate the start of the payload of the PES packet.
#Copy the PES payload into a buffer.
#The ID3 tag spans 2 PES packets. Parse the stream for the next packet whose PID is set to the PID found in step 1. Typically the ID3 Tag is of 249 bytes. The steps below guide towards extraction of the ID3 tag
##In the first PES packet, look for "www.nielsen.com" , this is the start of the ID3 tag. Keep on parsing the first PES packet until the undefined char "\ufffd" is found. This forms the first half of the ID3 tag
##In the second PES packet, identify the end pattern, a regEx of /(\/\d+){3}/ and look to remove the lowest index of either “\x00” and/or “\ufffd”. Now the second packet has been appended and the demarcation of the Nielsen specific data has been defined. This segment can be simply substringed.
##Concatenate this substringed segment with the payload derived from the first packet get the ID3 payload.
#Check the length of the contents in the buffer to make sure that it is equal to the size of a Nielsen ID3 tag.
#Ensure that the ID3 byte array is converted into the string and escape it, so that the SDK can consume it.
Repeat steps 2 through 7 for all ID3 tags in the stream.

'''References'''
*[http://www.iso.org/iso/catalogue_detail?csnumber=44169. ISO/IEC 13818-1:2007] Information technology – Generic coding of moving pictures and associated audio information: Systems
*https://developer.apple.com/library/content/documentation/AudioVideo/Conceptual/HTTP_Live_Streaming_Metadata_Spec/

=== Sample ID3 tags ===
* <code>www.nielsen.com/X100zdCIGeIlgZnkYj6UvQ==/X100zdCIGeIlgZnkYj6UvQ==/AAAB2Jz2_k74GXSzx4npHuI_<wbr />JwJd3QSUpW30rDkGTcbHEzIMWleCzM-uvNOP9fzJcQMWQLJqzXMCAxParOb5sGijSV9dNM3QiBniJYGZ5GI-lL1fXTTN0IgZ4iWBmeRiPpS9AAAAAAAAAAAAAAAAAAAAAFJWFM5SVhTONNU=/00000/00000/00</code>
* <code>www.nielsen.com/X100zdCIGeIlgZnkYj6UvQ==/R8WHe7pEBeqBhu8jTeXydg==/AAICoyitYqlxT7n6aZ0oMCGhe<wbr />Fi4CXFp46AMUPZz1lMr_M9tr3_cjee1SHqxrOiVerMDLeyn9xzocZSKwi746Re8vNOtpNCAZjYABs_J0R25IHpvOc1HS8<wbr />QHGgD5TgOJeS6gX100zdCIGeIlgZnkYj6UvVJWFNhSVhTiPE0=/00000/46016/00</code>
<blockquote>'''Note''': ID3 tags are not applicable for International (Germany)</blockquote>

== Browser Opt-Out Implementation ==
The site in which video content is being measure via Nielsen methodology must provide the means for the user to opt-out of, or opt back into Nielsen Measurement.

For Browser-based applications, opt-out setting is stored via Nielsen cookie. Therefore, it is only necessary that users be made aware of measurement opt-out by incorporating the template below in the user interface.

=== Sample Opt Out Template ===
Our properties may feature Nielsen’s proprietary measurement software which will allow to contribute to market research, like Nielsen’s TV Ratings. To learn more about this information, see https://www.nielsen.com/digitalprivacy. Nielsen’s software may collect your choices with regards to it.

== Nielsen Privacy Requirements ==
Privacy protections that Nielsen ensures to have with each App SDK integration are as follows.
*Disclosure of viewership data collection in EULA / Privacy Policy
*A link in the EULA/Privacy policy, or in another conspicuous location within the App, to a Nielsen-hosted web page outlining what Nielsen is collecting and how it is being used
*Method for users to opt-out of Nielsen measurement, any time while using the application

=== Ratings Data Flow ===
Every view of creditable and watermarked content is measured by Nielsen.
[[File:RatingsDataFlow.png]]

'''Information NOT Shared'''
* '''With Nielsen'''
** User's Identity
* '''With Data Provider'''
** Content information
** Whether user is viewing an ad or video content
** Player used to play the streaming (audio / video, etc.)
** Values being de-duped / aggregating for

Nielsen collects only what it needs for audience measurement. Every view of creditable, watermarked content will be measured by Nielsen.

=== Data Collected ===
{| class="wikitable"
|-
! Type of Information !! Parameter !! Transmitted to Nielsen? !! Sent to Provider?
|-
| rowspan="8" | Nielsen ID3 Watermark
|-
| FinalDistributor Timestamp || Yes || No
|-
| Program Content Timestamp || Yes || No
|-
| Mobile Breakout Code || Yes || No
|-
| Commercial Credit Code – Linear or Dynamic || Yes || No
|-
| Time ShiftedViewing Code || Yes || No
|-
| Segment Number || Yes || No
|-
| Segment View Pattern || Yes || No
|-
| rowspan="7" | Device/App Info
|-
| Device OSVersion || Yes || Yes
|-
| Device Model || Yes || No
|-
| Cache Buster || Yes || Yes
|-
| SDKDisabled Flag || Yes || No
|-
| ServerCode || Yes || No
|-
| Channel or URL || Yes || No
|-
| rowspan="9" | Nielsen Identifiers
|-
| Client ID || Yes || No
|-
| Campaign ID || Yes || Yes
|-
| Nielsen Unique Device ID || Yes || No
|-
| Application ID || Yes || No
|-
| DeviceGroup (ex. Tablet, Smartphone, Desktop) || Yes || Yes
|-
| OS Group (ex. Android, iOS, Windows) || Yes || Yes
|-
| SDKVersion || Yes || No
|-
| IP Address for DMA, Country Code || Yes || Yes
|}
<blockquote>'''Note''': Data is hashed, and encrypted using AES 128 before transmission to data provider.</blockquote>

{{Viewability_Data_Collected}}

==== Example ping sent to provider ====
* <code><nowiki>https://provider.com/cgi-bin/brandlift.php</nowiki>?campaign_id=ff12725d724fac7934cf6003f096b4cd<wbr />&placement_id=a4164b8fba9ee7c873a9c72c7091bb58<wbr />&creative_id=25280139b61a947e127a52f56c8a2fdd<wbr />&segment1=9000<wbr />&segment2=41<wbr />&segment3=iOS<wbr />&OSVer=iOS6.1<wbr />&c9=<wbr />&devgrp=tablet<wbr />&h=f5f243fe6d<wbr />&rnd=1376971827360</code>

This ping passes the following parameters to the provider:
* Campaign ID – (campaign, placement, creative)
* Country Code
* DMA
* OS Group (ex. iOS, Android)
* DeviceOS Version
* Device Advertiser ID
* DeviceGroup (ex. Tablet, Smartphone, Desktop)
* Cache Buster

{{Template:Browser_Privacy_and_Opt-Out}}

=== Opt-Out Implementation ===
The site must provide the means for the user to opt-out of, or opt back into Nielsen Measurement.

'''Sample Opt Out Template'''

Our properties may feature Nielsen’s proprietary measurement software which will allow to contribute to market research, like Nielsen’s TV Ratings. To learn more about this information, please [http://priv-policy.imrworldwide.com/priv/mobile/us/en/optout.html| click here]. Nielsen’s software may collect your choices with regards to it.

== Testing ==
See [[Digital Measurement Testing#Testing Browser Implementation|Digital Measurement Testing - Testing Browser Implementation]].

Browser SDK API Reference

2024-12-09T19:36:21Z

AmySockanathan:

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

== Setting up Development Environment ==
=== Step 1: Configure Content Management System (CMS) ===
Configure CMS to send the required values (see table below). Any internal CMS_variable names can be used for passing the data.

Ensure to capture these CMS_variable names in the SDK Configuration Form.

For more information on setting variable names, see the SDK Configuration Form included within the SDK package.

{| class="wikitable"
|-
! Required Data !! Description !! Value
|-
| dataSrc || Used when both CMS metadata and ID3 data are present in the player. Setting this field tells the SDK whether to use the CMS metadata or the ID3 payload to derive the pings || cms
|-
| type || Type of asset: ad or content || preroll, midroll, postroll, or content
|-
| assetid || unique ID assigned to asset || custom <br>(no [[Special Characters]])
|-
| OCR Tag || OCR tag provided by Nielsen for implementation on the ad unit || Complete OCR URL
|-
| program || Name of program (25 character limit) || custom
|-
| title || Episode title (40 character limit) || custom
|-
| length || Length of content in seconds || Length in seconds, 0 for live stream
|-
| adloadtype || Type of ad load || "1" - Linear "2" - Dynamic(default)
|-
| hasAds || Identify if content includes Ads || "0" - no ads "1" - includes ads "2" - unknown(default)
|-
| isfullepisode || Full episode flag || "y" - full episode "n" - non full episode
|-
| segA || Segment A (this is not available for video reporting as the episode title is reported) || custom value
|-
| segB || Custom segment B || custom value
|-
| segC || Custom segment C || custom value
|-
| crossId1 || Standard episode ID || custom value
|-
| crossId2 || Content originator (required only for distributors) || custom value
|-
| airdate || Original air date and time in Eastern Time. For non-US countries, it should be local time. || YYYYMMDD HH24:MI:SS
|-
| containerId || HTML DOM element of the Player container (for Viewability&Audibility feature only) || custom value
|-
|luid
|Living Unit ID - Experian Household ID
'''Note: This parameter is applicable only for CTV and First Party Livestream data'''
|"B0EOFEDgD"
|}

=== Step 2: Complete the Nielsen SDK Configuration Form ===
The SDK is designed to map the <code>CMS_variable names</code>. To support the custom mapping, the developer is required to complete the SDK Configuration Form. The form will be provided during onboarding along with this guide.

== Initialization ==
=== Obtain the Nielsen Application ID (apid) and Browser SDK URLs ===
The Nielsen <code>apid</code> 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 Browser SDK ===
There are two steps required for configuring the SDK:

'''Add Static Queue Snippet'''

*Add Static Queue Snippet
*Create SDK Instance

Add the following script tag to the website:
<syntaxhighlight lang="javascript">

<script type="text/javascript">
!function(t,n)
{
t[n]=t[n]||
{
nlsQ:function(e,o,c,r,s,i)
{
return s=t.document,
r=s.createElement("script"),
r.async=1,
r.src=("http:"===t.location.protocol?"http:":"https:")+"//cdn-gl.imrworldwide.com/conf/"+e+".js#name="+o+"&ns="+n,
i=s.getElementsByTagName("script")[0],
i.parentNode.insertBefore(r,i),
t[n][o]=t[n][o]||{g:c||{},
ggPM:function(e,c,r,s,i){(t[n][o].q=t[n][o].q||[]).push([e,c,r,s,i])}},t[n][o]
}
}
}
(window,"NOLBUNDLE");
</script>

</syntaxhighlight>

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.

'''Create SDK Instance'''

To initialize the SDK, create an SDK instance by making the initialization call:

'''Initialization API Call'''
<syntaxhighlight lang="javascript">

NOLBUNDLE.nlsQ("<apid>", "<instanceName>",{nol_sdkDebug: "debug"})

</syntaxhighlight>

When creating an instance, pass the following three values:

=== SDK Initialization – Global Parameters ===
{| class="wikitable"
|-
! Parameters !! Description !! Value
|-
| apid || UniqueID assigned to player/site. || 'XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX'
|-
| instanceName || Name of SDK instance || "any string value"
|-
| nol_sdkDebug || Enables Nielsen console logging. Only required for testing || "{nol_sdkDebug: "debug"})"
|-
| containerId || HTML DOM element id of the player container. Only for Viewability & Audibility feature. || {containerId: "playerId1"}
|-
| 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&"
|}

{{example_bsdk_init}}

'''Example SDK Configuration'''

The configuration should include the Static Queue Snippet and an SDK Instance for an unique App ID as shown in the example:

<syntaxhighlight lang="javascript">

<script type="text/javascript">
!function(t,n)
{
t[n]=t[n]||
{
nlsQ:function(e,o,c,r,s,i)
{
return s=t.document,
r=s.createElement("script"),
r.async=1,
r.src=("http:"===t.location.protocol?"http:":"https:")+"//cdn-gl.imrworldwide.com/conf/"+e+".js#name="+o+"&ns="+n,
i=s.getElementsByTagName("script")[0],
i.parentNode.insertBefore(r,i),
t[n][o]=t[n][o]||{g:c||{},
ggPM:function(e,c,r,s,i){(t[n][o].q=t[n][o].q||[]).push([e,c,r,s,i])}},t[n][o]
}
}
}
(window,"NOLBUNDLE");
// Created SDK Instance
var nSdkInstance = NOLBUNDLE.nlsQ("XXXXXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXX","nlsnInstance", {nol_sdkDebug: "debug"});
</script>

</syntaxhighlight>

=== Multiple SDK Instances ===
The Browser SDK allows instantiating multiple instances of the object, which can be used simultaneously without any problems, however they must be instantiated with their own unique instance names. There is no maximum number of instances that is enforced in the browser.

The below examples will make use of the same AppId, however using different AppIds will work as well. The principles below follow the same initialization rules stated above for a single instance and simply require a unique instance name and variable name with which the returned instance is assigned.

For more information around the possible parameters that can be passed as well as deeper descriptions for the API calls, please refer to the section on "[[SDK Initialization - Global Parameters#Browser_SDK_API_Reference | SDK Initialization - Global Parameters]]".

'''Example of 2 instances on the same page'''

<syntaxhighlight lang="javascript">
//Add Static Queue Snippet
<script>
!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.imrworldwide.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");

//Create SDK Instance(s)
// Notice the unique instance name given to each instance below and the unique variable name for each instance
var nSdkInstanceLive = NOLBUNDLE.nlsQ("XXXXXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXX", "instanceLive", {
nol_sdkDebug: 'debug',
optout: 'false'
});

var nSdkInstanceVod = NOLBUNDLE.nlsQ("XXXXXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXX", "instanceVod", {
nol_sdkDebug: 'debug',
optout: 'false'
});

</script>
</syntaxhighlight>

'''Example of 2 instances using a parent page and iFrame'''

<big>Parent Page (index.html)</big>

<syntaxhighlight lang="javascript">
<!DOCTYPE html>
<html lang="en">

<head>
<meta charset="UTF-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<meta http-equiv="X-UA-Compatible" content="ie=edge">
<title>DCR Static/DCR Video</title>
<script>
/* NLSQUEUE build v*/
!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.imrworldwide.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");

// SDK Initialization
var nSdkInstance = NOLBUNDLE.nlsQ("XXXXXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXX", "staticPage", {
nol_sdkDebug: 'debug',
});

// Static Metadata
var staticMetadata = {
assetid: 'staticTestPage',
type: 'static'
};

// Event 'staticstart' call
nSdkInstance.ggPM(14, staticMetadata);
</script>
</head>

<body>
<h1>DCR Static on Parent/DCR Video in iFrame</h1>
<p>Static measurement is current on parent page when window is in focus</p>
<iframe src="./dcr-video.html" frameborder="0" width="650" height="500" style="background-color: rgb(42, 217, 248);" id="video-iframe"></iframe>
</body>

</html>
</syntaxhighlight>

<big>Nested iFrame Referenced on Parent Page (dcr-video.html)</big>

<syntaxhighlight lang="javascript">
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
<meta http-equiv="X-UA-Compatible" content="ie=edge" />
<title>iFrame Same Source</title>
<script>
/* NLSQUEUE build v*/
!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.imrworldwide.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");

// SDK Initialization
var nSdkInstance = NOLBUNDLE.nlsQ("XXXXXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXX", "videoPlayer", {
nol_sdkDebug: 'debug',
});

var contentMetadata = {
type: "content",
length: "300",
title: "Skydiving Across Europe",
program: "latacg",
censuscategory: "Enlisted",
assetid: "204558915992",
section: "ProgramAsset8",
tv: "true",
adModel: "0",
dataSrc: "cms",
segA: "S07E04:NBC",
segB: "teams",
segC:"AtlanataFalcons",
}
</script>
</head>
<body>
<p>I'm iframe SDK DCR Video measurement, DCR static measurement should continue when clicking "play" on video</p>
<main>
<video
controls
src="https://archive.org/download/BigBuckBunny_124/Content/big_buck_bunny_720p_surround.mp4"
poster="https://peach.blender.org/wp-content/uploads/title_anouncement.jpg?x11217"
width="620">
Sorry, your browser doesn't support embedded videos, but don't worry, you can
<a href="https://archive.org/details/BigBuckBunny_124">download it</a>
and watch it with your favorite video player!
</video>
</main>
<script src="../player.js"></script>
</body>
</html>

</syntaxhighlight>

=== SDK Initialization to measure the Viewability & Audibility ===
To support viewability metrics in the web page the integrator has to provide a tag value of the player view to let Nielsen SDK know that there is a player that needs to be tracked. It’s called the ‘containerId’ and it should be passed in the as string while initializing the Nielsen browser SDK.

NOLBUNDLE.nlsQ("<apid>", "<instanceName>",{containerId: <playerElementID>, nol_sdkDebug: "debug"})

'''Example SDK Initialization for Viewability'''

Your configuration should include the Static Queue Snippet and an SDK Instance for your unique App ID as shown in the example:
<syntaxhighlight lang="javascript">
//Add Static Queue Snippet
<script>
! function(t, n) {
t[n] = t[n] || {
nlsQ: function(e, o, c, r, s, i) {
return s = t.document,
r = s.createElement("script"),
r.async = 1,
r.src = ("http:" === t.location.protocol ? "http:" : "https:") + "//cdn-gl.imrworldwide.com/conf/" + e + ".js#name=" + o + "&ns=" + n,
i = s.getElementsByTagName("script")[0],
i.parentNode.insertBefore(r, i),
t[n][o] = t[n][o] || {
g: c || {},
ggPM: function(e, c, r, s, i) {
(t[n][o].q = t[n][o].q || []).push([e, c, r, s, i])
}
}, t[n][o]
}
}
}
(window, "NOLBUNDLE");

//Create SDK Instance
var nSdkInstance = NOLBUNDLE.nlsQ("XXXXXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXX", "nlsnInstance", {containerId: “player1”, nol_sdkDebug: "debug"});
</script>

</syntaxhighlight>

== Browser SDK API Methods & Properties ==
{| class="wikitable sortable"
|-
! Method / Property !! Event # !! DTVR !! DAR !! DCR !! Description
|-
| [[loadMetadata (Browser)|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.
|-
| [[play (Browser)|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”.
|-
| [[sendID3 (Browser)|sendID3]] || 55 || ✔ || ✘ || ✘ || Used to send the ID3 metadata.
|-
| [[setPlayheadPosition (Browser)|setPlayheadPosition]] || 49 || ✘ || ✘ || ✔ || Used to send the playhead position.
|-
| [[stop (Browser)|stop]] || 7 || ✘ || ✘ || ✔ || Used when switching between ad and content or content and ad.
|-
| [[end (Browser)|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
|-
| [[staticstart (Browser)|staticstart]] || 14 || ✘ || ✘ || ✔ || Used to send the metadata for the static page.
|-
| [[StaticEnd (Browser)|staticend]] || 56 || ✘ || ✘ || ✔ || In Single Page Application (SPA) it is imperative that staticend is called prior to the loading of new metadata. This allows the Browser SDK to properly credit the previous section/content being viewed before measuring the new one.
|-
| [[updateOTT (Browser)|updateOTT]] || - || ✘ || ✘ || ✔ || Used to notify Browser SDK that the remote OTT device (like Google ChromeCast, Roku, Amazon FireTV, etc.) is connected / disconnected (change of OTT status).
|-
| [[ onPaginate (Browser)|onPaginate]] || 30 || ✘ || ✘ || ✔ || Used to create a new instance of the SDK object
|-
| [[updateMetadata (Browser)|updateMetadata]] || 35 || ✔ || ✔ || ✔ || This event is used for updating metadata parameters for the content or ad that is being played.
|-
| [[setVolume_(Browser)|setVolume]] || 61 || ✔ || ✘ || ✔ || Used to pass in the player volume levels in %. Default value is -1.
|}

== Retrieving ID3 Tags ==
The video player must have the ability to extract ID3 tags and supply them to the Browser SDK, based on the HLS standard.
*An ID3 tag spans two PES packets.
**In the first PES packet, look for www.nielsen.com, this is the start of the ID3 tag. Continue to parse the first PES packet until the undefined char "\ufffd" is found. This forms the first half of the ID3 tag
**In the second PES packet, identify the end pattern – a regEx of /(\/\d+){3}/ and look to remove the lowest index of either "\x00" and/or "\ufffd". Now the second packet has been appended and the demarcation of the Nielsen-specific data has been defined.

Follow the procedure below, to extract Nielsen ID3 tags from an MPEG-2 transport stream (including HLS streams).
#Parse the Program Map Table (PMT) to find the PID of the metadata stream. Confirm the presence of the metadata descriptor described in section 2.3.3 of Apple’s “HTTP Live Streaming Metadata Spec.pdf”. Only private streams with metadata descriptor present should be considered as ID3-tag metadata streams.
#Parse the HLS/Transport stream for any '''PES header''' with the PID found in step 1.
#Follow standard MPEG-2 parsing procedures to locate the start of the payload of the PES packet.
#Copy the PES payload into a buffer.
#The ID3 tag spans 2 PES packets. Parse the stream for the next packet whose PID is set to the PID found in step 1. Typically the ID3 Tag is of 249 bytes. The steps below guide towards extraction of the ID3 tag
##In the first PES packet, look for "www.nielsen.com" , this is the start of the ID3 tag. Keep on parsing the first PES packet until the undefined char "\ufffd" is found. This forms the first half of the ID3 tag
##In the second PES packet, identify the end pattern, a regEx of /(\/\d+){3}/ and look to remove the lowest index of either “\x00” and/or “\ufffd”. Now the second packet has been appended and the demarcation of the Nielsen specific data has been defined. This segment can be simply substringed.
##Concatenate this substringed segment with the payload derived from the first packet get the ID3 payload.
#Check the length of the contents in the buffer to make sure that it is equal to the size of a Nielsen ID3 tag.
#Ensure that the ID3 byte array is converted into the string and escape it, so that the SDK can consume it.
Repeat steps 2 through 7 for all ID3 tags in the stream.

'''References'''
*[http://www.iso.org/iso/catalogue_detail?csnumber=44169. ISO/IEC 13818-1:2007] Information technology – Generic coding of moving pictures and associated audio information: Systems
*https://developer.apple.com/library/content/documentation/AudioVideo/Conceptual/HTTP_Live_Streaming_Metadata_Spec/

=== Sample ID3 tags ===
* <code>www.nielsen.com/X100zdCIGeIlgZnkYj6UvQ==/X100zdCIGeIlgZnkYj6UvQ==/AAAB2Jz2_k74GXSzx4npHuI_<wbr />JwJd3QSUpW30rDkGTcbHEzIMWleCzM-uvNOP9fzJcQMWQLJqzXMCAxParOb5sGijSV9dNM3QiBniJYGZ5GI-lL1fXTTN0IgZ4iWBmeRiPpS9AAAAAAAAAAAAAAAAAAAAAFJWFM5SVhTONNU=/00000/00000/00</code>
* <code>www.nielsen.com/X100zdCIGeIlgZnkYj6UvQ==/R8WHe7pEBeqBhu8jTeXydg==/AAICoyitYqlxT7n6aZ0oMCGhe<wbr />Fi4CXFp46AMUPZz1lMr_M9tr3_cjee1SHqxrOiVerMDLeyn9xzocZSKwi746Re8vNOtpNCAZjYABs_J0R25IHpvOc1HS8<wbr />QHGgD5TgOJeS6gX100zdCIGeIlgZnkYj6UvVJWFNhSVhTiPE0=/00000/46016/00</code>
<blockquote>'''Note''': ID3 tags are not applicable for International (Germany)</blockquote>

== Browser Opt-Out Implementation ==
The site in which video content is being measure via Nielsen methodology must provide the means for the user to opt-out of, or opt back into Nielsen Measurement.

For Browser-based applications, opt-out setting is stored via Nielsen cookie. Therefore, it is only necessary that users be made aware of measurement opt-out by incorporating the template below in the user interface.

=== Sample Opt Out Template ===
Our properties may feature Nielsen’s proprietary measurement software which will allow to contribute to market research, like Nielsen’s TV Ratings. To learn more about this information, see https://www.nielsen.com/digitalprivacy. Nielsen’s software may collect your choices with regards to it.

== Nielsen Privacy Requirements ==
Privacy protections that Nielsen ensures to have with each App SDK integration are as follows.
*Disclosure of viewership data collection in EULA / Privacy Policy
*A link in the EULA/Privacy policy, or in another conspicuous location within the App, to a Nielsen-hosted web page outlining what Nielsen is collecting and how it is being used
*Method for users to opt-out of Nielsen measurement, any time while using the application

=== Ratings Data Flow ===
Every view of creditable and watermarked content is measured by Nielsen.
[[File:RatingsDataFlow.png]]

'''Information NOT Shared'''
* '''With Nielsen'''
** User's Identity
* '''With Data Provider'''
** Content information
** Whether user is viewing an ad or video content
** Player used to play the streaming (audio / video, etc.)
** Values being de-duped / aggregating for

Nielsen collects only what it needs for audience measurement. Every view of creditable, watermarked content will be measured by Nielsen.

=== Data Collected ===
{| class="wikitable"
|-
! Type of Information !! Parameter !! Transmitted to Nielsen? !! Sent to Provider?
|-
| rowspan="8" | Nielsen ID3 Watermark
|-
| FinalDistributor Timestamp || Yes || No
|-
| Program Content Timestamp || Yes || No
|-
| Mobile Breakout Code || Yes || No
|-
| Commercial Credit Code – Linear or Dynamic || Yes || No
|-
| Time ShiftedViewing Code || Yes || No
|-
| Segment Number || Yes || No
|-
| Segment View Pattern || Yes || No
|-
| rowspan="7" | Device/App Info
|-
| Device OSVersion || Yes || Yes
|-
| Device Model || Yes || No
|-
| Cache Buster || Yes || Yes
|-
| SDKDisabled Flag || Yes || No
|-
| ServerCode || Yes || No
|-
| Channel or URL || Yes || No
|-
| rowspan="9" | Nielsen Identifiers
|-
| Client ID || Yes || No
|-
| Campaign ID || Yes || Yes
|-
| Nielsen Unique Device ID || Yes || No
|-
| Application ID || Yes || No
|-
| DeviceGroup (ex. Tablet, Smartphone, Desktop) || Yes || Yes
|-
| OS Group (ex. Android, iOS, Windows) || Yes || Yes
|-
| SDKVersion || Yes || No
|-
| IP Address for DMA, Country Code || Yes || Yes
|}
<blockquote>'''Note''': Data is hashed, and encrypted using AES 128 before transmission to data provider.</blockquote>

{{Viewability_Data_Collected}}

==== Example ping sent to provider ====
* <code><nowiki>https://provider.com/cgi-bin/brandlift.php</nowiki>?campaign_id=ff12725d724fac7934cf6003f096b4cd<wbr />&placement_id=a4164b8fba9ee7c873a9c72c7091bb58<wbr />&creative_id=25280139b61a947e127a52f56c8a2fdd<wbr />&segment1=9000<wbr />&segment2=41<wbr />&segment3=iOS<wbr />&OSVer=iOS6.1<wbr />&c9=<wbr />&devgrp=tablet<wbr />&h=f5f243fe6d<wbr />&rnd=1376971827360</code>

This ping passes the following parameters to the provider:
* Campaign ID – (campaign, placement, creative)
* Country Code
* DMA
* OS Group (ex. iOS, Android)
* DeviceOS Version
* Device Advertiser ID
* DeviceGroup (ex. Tablet, Smartphone, Desktop)
* Cache Buster

{{Template:Browser_Privacy_and_Opt-Out}}

=== Opt-Out Implementation ===
The site must provide the means for the user to opt-out of, or opt back into Nielsen Measurement.

'''Sample Opt Out Template'''

Our properties may feature Nielsen’s proprietary measurement software which will allow to contribute to market research, like Nielsen’s TV Ratings. To learn more about this information, please [http://priv-policy.imrworldwide.com/priv/mobile/us/en/optout.html| click here]. Nielsen’s software may collect your choices with regards to it.

== Testing ==
See [[Digital Measurement Testing#Testing Browser Implementation|Digital Measurement Testing - Testing Browser Implementation]].