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();
     }

nielsen/src/integration/NielsenHandler.ts

@@ -1,21 +1,40 @@
 import type {
     Ad,
+    AdBreakEvent,
+    AdEvent,
     AddTrackEvent,
     ChromelessPlayer,
+    DurationChangeEvent,
     TextTrack,
     TextTrackEnterCueEvent,
+    TimeUpdateEvent,
     VolumeChangeEvent
 } from 'theoplayer';
 import { loadNielsenLibrary } from '../nielsen/NOLBUNDLE';
-import { AdMetadata, ContentMetadata, NielsenOptions } from '../nielsen/Types';
-import { getAdType } from '../utils/Util';
+import {
+    AdMetadata,
+    DCRContentMetadata,
+    DTVRContentMetadata,
+    NielsenConfiguration,
+    NielsenCountry,
+    NielsenDCRContentMetadata,
+    NielsenOptions
+} from '../nielsen/Types';
+import { buildDCRAdMetadata, buildDCRContentMetadata, getAdType } from '../utils/Util';
 
 const EMSG_PRIV_SUFFIX = 'PRIV{';
 const EMSG_PAYLOAD_SUFFIX = 'payload=';
 
 export class NielsenHandler {
     private player: ChromelessPlayer;
 
+    private dcrEnabled: boolean;
+    private dtvrEnabled: boolean;
+    private country: NielsenCountry = NielsenCountry.US;
+
+    private metadata: DCRContentMetadata | undefined;
+    private lastReportedPlayheadPosition: number | undefined;
+
     private nSdkInstance: any;
 
     private sessionInProgress: boolean = false;
@@ -24,46 +43,79 @@ export class NielsenHandler {
 
     private decoder = new TextDecoder('utf-8');
 
-    constructor(player: ChromelessPlayer, appId: string, instanceName: string, options?: NielsenOptions) {
+    constructor(
+        player: ChromelessPlayer,
+        appId: string,
+        instanceName: string,
+        options?: NielsenOptions,
+        configuration?: NielsenConfiguration
+    ) {
         this.player = player;
-        this.nSdkInstance = loadNielsenLibrary(appId, instanceName, options);
+        this.dcrEnabled = configuration?.enableDCR ?? false;
+        this.dtvrEnabled = configuration?.enableDTVR ?? true;
+        this.country = configuration?.country ?? NielsenCountry.US;
+        this.nSdkInstance = loadNielsenLibrary(appId, instanceName, options, this.country);
 
         this.addEventListeners();
     }
 
     updateMetadata(metadata: { [key: string]: string }): void {
-        this.nSdkInstance.ggPM('updateMetadata', metadata);
+        switch (this.country) {
+            case NielsenCountry.US: {
+                const { type, vidtype, assetid, ...updateableParameters } = metadata;
+                console.log(`[NIELSEN] updateMetadata: ${{ type, vidtype, assetid }} will not be updated`);
+                this.nSdkInstance.ggPM('updateMetadata', updateableParameters);
+                break;
+            }
+            case NielsenCountry.CZ:
+            default:
+        }
+    }
+
+    updateDCRContentMetadata(metadata: NielsenDCRContentMetadata): void {
+        if (!this.dcrEnabled) return;
+        this.metadata = buildDCRContentMetadata(metadata, this.country);
     }
 
     private addEventListeners(): void {
         this.player.addEventListener('play', this.onPlay);
+        this.player.addEventListener('pause', this.onInterrupt);
+        this.player.addEventListener('waiting', this.onInterrupt);
         this.player.addEventListener('ended', this.onEnd);
         this.player.addEventListener('sourcechange', this.onSourceChange);
         this.player.addEventListener('volumechange', this.onVolumeChange);
         this.player.addEventListener('loadedmetadata', this.onLoadMetadata);
         this.player.addEventListener('durationchange', this.onDurationChange);
+        this.player.addEventListener('timeupdate', this.onTimeUpdate);
 
         this.player.textTracks.addEventListener('addtrack', this.onAddTrack);
 
         if (this.player.ads) {
             this.player.ads.addEventListener('adbegin', this.onAdBegin);
+            this.player.ads.addEventListener('adend', this.onAdEnd);
+            this.player.ads.addEventListener('adbreakbegin', this.onAdBreakBegin);
         }
 
         window.addEventListener('beforeunload', this.onEnd);
     }
 
     private removeEventListeners(): void {
         this.player.removeEventListener('play', this.onPlay);
+        this.player.removeEventListener('pause', this.onInterrupt);
+        this.player.removeEventListener('waiting', this.onInterrupt);
         this.player.removeEventListener('ended', this.onEnd);
         this.player.removeEventListener('sourcechange', this.onSourceChange);
         this.player.removeEventListener('volumechange', this.onVolumeChange);
         this.player.removeEventListener('loadedmetadata', this.onLoadMetadata);
         this.player.removeEventListener('durationchange', this.onDurationChange);
+        this.player.removeEventListener('timeupdate', this.onTimeUpdate);
 
         this.player.textTracks.removeEventListener('addtrack', this.onAddTrack);
 
         if (this.player.ads) {
             this.player.ads.removeEventListener('adbegin', this.onAdBegin);
+            this.player.ads.removeEventListener('adend', this.onAdEnd);
+            this.player.ads.removeEventListener('adbreakbegin', this.onAdBreakBegin);
         }
 
         window.removeEventListener('beforeunload', this.onEnd);
@@ -73,7 +125,13 @@ export class NielsenHandler {
         this.maybeSendPlayEvent();
     };
 
+    private onInterrupt = () => {
+        if (!this.dcrEnabled) return;
+        this.nSdkInstance.ggPM('stop', this.getPlayHeadPosition());
+    };
+
     private onEnd = () => {
+        if (this.dcrEnabled && this.player.ads?.playing) this.nSdkInstance.ggPM('stop', this.getPlayHeadPosition());
         this.endSession();
     };
 
@@ -83,24 +141,36 @@ export class NielsenHandler {
     };
 
     private onVolumeChange = (event: VolumeChangeEvent) => {
+        if (!this.dtvrEnabled) return;
         const volumeLevel = this.player.muted ? 0 : event.volume * 100;
         this.nSdkInstance.ggPM('setVolume', volumeLevel);
     };
 
-    private onDurationChange = () => {
+    private onDurationChange = ({ duration }: DurationChangeEvent) => {
+        if (isNaN(duration)) return;
         this.duration = this.player.duration;
         this.maybeSendPlayEvent();
     };
 
+    private onTimeUpdate = ({ currentTime }: TimeUpdateEvent) => {
+        if (!this.dcrEnabled) return;
+        const currentTimeFloor = Math.floor(currentTime);
+        if (currentTimeFloor === this.lastReportedPlayheadPosition) return;
+        this.lastReportedPlayheadPosition = currentTimeFloor;
+        this.nSdkInstance.ggPM('setPlayheadPosition', currentTimeFloor);
+    };
+
     private onLoadMetadata = () => {
-        const data: ContentMetadata = {
+        if (!this.dtvrEnabled) return;
+        const data: DTVRContentMetadata = {
             type: 'content',
             adModel: '1' // Always '1' for DTVR
         };
         this.nSdkInstance.ggPM('loadMetadata', data);
     };
 
     private onAddTrack = (event: AddTrackEvent) => {
+        if (!this.dtvrEnabled) return;
         if (event.track.kind === 'metadata') {
             const track = event.track as TextTrack;
             if (track.type === 'id3' || track.type === 'emsg') {
@@ -164,25 +234,54 @@ export class NielsenHandler {
         }
     };
 
-    private onAdBegin = () => {
-        const currentAd = this.player.ads!.currentAds.filter((ad: Ad) => ad.type === 'linear');
-        const type = getAdType(this.player.ads!.currentAdBreak!);
-        const adMetadata: AdMetadata = {
-            type,
-            assetid: currentAd[0].id!
-        };
-        this.nSdkInstance.ggPM('loadMetadata', adMetadata);
+    private onAdBegin = ({ ad }: AdEvent<'adbegin'>) => {
+        if (ad.type !== 'linear') return;
+        const { adBreak } = ad;
+        const { timeOffset } = adBreak;
+        const offset = this.player.ads?.dai?.contentTimeForStreamTime(timeOffset) ?? timeOffset;
+        const duration = this.player.ads?.dai?.contentTimeForStreamTime(this.duration) ?? this.duration;
+        const type = getAdType(offset, duration);
+        if (this.dtvrEnabled) {
+            const dtvrAdMetadata: AdMetadata = {
+                type,
+                assetid: ad.id!
+            };
+            this.nSdkInstance.ggPM('loadMetadata', dtvrAdMetadata);
+        }
+        if (this.dcrEnabled) {
+            const dcrAdMetadata = buildDCRAdMetadata(ad, this.country, this.duration);
+            this.nSdkInstance.ggPM('loadMetadata', dcrAdMetadata);
+        }
+    };
+
+    private onAdEnd = () => {
+        if (!this.dcrEnabled) return;
+        this.nSdkInstance.ggPM('stop', this.getPlayHeadPosition());
+    };
+
+    private onAdBreakBegin = ({ adBreak }: AdBreakEvent<'adbreakbegin'>) => {
+        if (!this.dcrEnabled) return;
+        const { timeOffset } = adBreak;
+        const offset = this.player.ads?.dai?.contentTimeForStreamTime(timeOffset) ?? timeOffset;
+        const duration = this.player.ads?.dai?.contentTimeForStreamTime(this.duration) ?? this.duration;
+        const isPostroll = getAdType(offset, duration) === 'postroll';
+        if (!isPostroll) return;
+        this.endSession();
     };
 
     private maybeSendPlayEvent(): void {
-        if (!this.sessionInProgress && !Number.isNaN(this.duration)) {
-            this.sessionInProgress = true;
+        if (this.sessionInProgress || Number.isNaN(this.duration)) return;
+        this.sessionInProgress = true;
+        if (this.dtvrEnabled) {
             const metadataObject = {
                 channelName: this.player.src,
                 length: this.duration
             };
             this.nSdkInstance.ggPM('play', metadataObject);
         }
+        if (this.dcrEnabled) {
+            this.nSdkInstance.ggPM('loadMetadata', this.metadata);
+        }
     }
 
     private endSession(): void {