Merge pull request #45 from THEOplayer/feature/nielsen-dcr

Feature/nielsen dcr

.changeset/chilly-yaks-bake.md

@@ -0,0 +1,5 @@
+---
+"@theoplayer/nielsen-connector-web": minor
+---
+
+Add DCR support (CZ and US).

nielsen/README.md

@@ -12,39 +12,79 @@ npm install @theoplayer/nielsen-connector-web
 
 ### Configuring the connector
 
-Create the connector by providing the `THEOplayer` instance, the Nielsen App ID, the channelName for the asset 
-and optionally some Nielsen configuration.
+Create the connector by providing the following mandatory parameters:
+
+-   The `THEOplayer` instance
+-   the Nielsen App ID
+-   the channelName for the asset
+
+and optionally the following parameters:
+
+-   a `NielsenOptions` object
+-   a `NielsenConfiguration` object (if none is provided, the default configuration disables DCR, enables DTVR and sets the country to US)
 
 ```js
-import {NielsenConnector} from "../../dist/THEOplayerNielsenConnector";
+import { NielsenConnector } from '../../dist/THEOplayerNielsenConnector';
 
 const appId = '<your app ID>';
 const channelName = '<your channel name>';
-// Optional
+
+// Non-mandatory options
 const options: NielsenOptions = {
-    containerId: 'THEOplayer', 
+    containerId: 'THEOplayer',
     optout: false
-}
+};
+
+// Non-mandatory configuration (e.g. for DCR tracking with the Czech Republic SDK)
+const configuration: NielsenConfiguration = {
+    country: NielsenCountry.CZ,
+    enableDTVR: false,
+    enableDCR: true
+};
 const nielsenConnector = new NielsenConnector(player, appId, channelName, options);
 ```
 
 The `NielsenOptions` can have the following fields:
 
 | Key             | Value                                                           |
-|-----------------|-----------------------------------------------------------------|
-| ` containerId ` | HTML DOM element id of the player container.                    |
+| --------------- | --------------------------------------------------------------- |
+| `containerId`   | HTML DOM element id of the player container.                    |
 | ` nol_sdkDebug` | Enables Debug Mode which allows output to be viewed in console. |
-| ` optout `      | Whether to opt-out of Nielsen Measurement.                      |
+| `optout`        | Whether to opt-out of Nielsen Measurement.                      |
 
-### Passing metadata dynamically
+### Passing metadata dynamically (DTVR)
 
-The connector allows updating the current asset's metadata at any time:
+The connector allows updating the current asset's metadata at any time. Note that Nielsen's [documentation](<https://engineeringportal.nielsen.com/wiki/updateMetadata_(Browser)>) prohibits updating of the values for `type`, `vidtype` or `assetid` parameters
 
 ```js
 const metadata = {
     ['channelName']: 'newChannelName',
     ['customTag1']: 'customValue1',
-    ['customTag2']: 'customValue2'    
-}
+    ['customTag2']: 'customValue2'
+};
 nielsenConnector.updateMetadata(metadata);
 ```
+
+### Passing metadata when setting a source to the player (DCR)
+
+This can be achieved through the `updateDCRContentMetadata` method, e.g.:
+
+```js
+const metadata: NielsenDCRContentMetadataCZ = {
+    assetid: 'cz-500358-98731568435405',
+    program: 'Animated Test Content',
+    title: 'Big Buck Bunny',
+    length: '596',
+    airdate: '20230620 20:00:00',
+    isfullepisode: true,
+    crossId1: '915 954 39504',
+    c2: '651678089925925',
+    segB: '011',
+    adloadtype: AdLoadType.linear,
+    hasAds: HasAds.supports_ads
+};
+
+nielsenConnector.updateDCRContentMetadata(metadata);
+```
+
+Note that types are included in the package: `NielsenDCRContentMetadataUS`, `NielsenDCRContentMetadataCZ`. Please contact your THEO Technologies representative if you need support for another International DCR SDK.

nielsen/package.json

@@ -20,7 +20,7 @@
     "bundle": "rollup -c rollup.config.mjs",
     "watch": "npm run bundle -- --watch",
     "build": "npm run clean && npm run bundle",
-    "serve": "http-server",
+    "serve": "http-server ./.. -o /nielsen/test/pages/main.html",
     "test": "jest"
   },
   "author": "THEO Technologies NV",

nielsen/src/index.ts

@@ -1,2 +1,11 @@
 export { NielsenConnector } from './integration/NielsenConnector';
-export { NielsenOptions } from './nielsen/Types';
+export {
+    NielsenOptions,
+    NielsenDCRContentMetadata,
+    NielsenDCRContentMetadataCZ,
+    NielsenDCRContentMetadataUS,
+    NielsenConfiguration,
+    NielsenCountry,
+    AdLoadType,
+    HasAds
+} from './nielsen/Types';

nielsen/src/integration/NielsenConnector.ts

@@ -1,5 +1,5 @@
 import type { ChromelessPlayer } from 'theoplayer';
-import { NielsenOptions } from '../nielsen/Types';
+import { NielsenConfiguration, NielsenDCRContentMetadata, NielsenOptions } from '../nielsen/Types';
 import { NielsenHandler } from './NielsenHandler';
 
 export class NielsenConnector {
@@ -13,14 +13,24 @@ export class NielsenConnector {
      * @param instanceName  User-defined string value for describing the player/site.
      * @param options       Additional options.
      */
-    constructor(player: ChromelessPlayer, appId: string, instanceName: string, options?: NielsenOptions) {
-        this.nielsenHandler = new NielsenHandler(player, appId, instanceName, options);
+    constructor(
+        player: ChromelessPlayer,
+        appId: string,
+        instanceName: string,
+        options?: NielsenOptions,
+        configuration?: NielsenConfiguration
+    ) {
+        this.nielsenHandler = new NielsenHandler(player, appId, instanceName, options, configuration);
     }
 
     updateMetadata(metadata: { [key: string]: string }): void {
         this.nielsenHandler.updateMetadata(metadata);
     }
 
+    updateDCRContentMetadata(metadata: NielsenDCRContentMetadata): void {
+        this.nielsenHandler.updateDCRContentMetadata(metadata);
+    }
+
     destroy() {
         this.nielsenHandler.destroy();
     }