[DEST-1704][Nielsen DCR] Map events only if load_type property is dynamic. (#421)

* [Nielsen DCR] Map events only if load_type property is dynamic.

* Add support for new setting and update offset logic

* Add unit test

* Update  HISTORY.md and package.json

Co-authored-by: Brie <brienne.mcnally@segment.com>
Co-authored-by: Brie McNally <31782219+briemcnally@users.noreply.github.com>

Author: 3 people

integrations/nielsen-dcr/HISTORY.md

@@ -1,3 +1,32 @@
+2.0.1 / 2020-05-15
+==================
+
+  * Adds new setting `sendCurrentTimeLivestream` that when enabled will default to sending current time in seconds to Nielsen for livestream videos. If a position is passed and this setting is disabled we will calculate an offset of `currentTime` + `position` from properties object.
+
+2.0.0 / 2020-02-06
+==================
+  * Events are mapped to Nielsen DCR only when Segment `load_type` property is set to 'dynamic'.
+
+1.5.0 / 2020-01-27
+==================
+
+  * Supports tracking videos in SPA apps.
+
+1.4.0 / 2020-01-17
+==================
+
+  * Change approach to persisting `content_asset_id` to better keep track of session-level info.
+
+1.3.5 / 2020-01-06
+==================
+
+  * Send unix timestamp in seconds (rather than milliseconds) when livestreams end.
+
+1.3.4 / 2019-10-23
+==================
+
+  * Default content length to `0` if not explicitly defined.
+
 1.3.3 / 2019-10-11
 ==================
 

integrations/nielsen-dcr/lib/index.js

@@ -22,6 +22,7 @@ var NielsenDCR = (module.exports = integration('Nielsen DCR')
   .option('adAssetIdPropertyName', '')
   .option('subbrandPropertyName', '')
   .option('clientIdPropertyName', '')
+  .option('sendCurrentTimeLivestream', false)
   .option('contentLengthPropertyName', 'total_length')
   .option('optout', false)
   .tag(
@@ -74,6 +75,7 @@ NielsenDCR.prototype.initialize = function() {
   // for the currently viewing ad or content so that we can handle video switches in the same session
   this.currentAssetId = null;
   this.currentPosition = 0;
+  this.isDCRStream = false;
   this.heartbeatId = null; // reference to setTimeout
   this.load(protocol, this.ready);
 };
@@ -135,12 +137,11 @@ NielsenDCR.prototype.heartbeat = function(assetId, position, livestream) {
 
   if (livestream) {
     // for livestream events, we calculate a unix timestamp based on the current time an offset value, which should be passed in properties.position
-    this.currentPosition = getOffsetTime(position);
+    this.currentPosition = getOffsetTime(position, self.options);
   } else if (position >= 0) {
     // this.currentPosition defaults to 0 upon initialization
     this.currentPosition = position;
   }
-
   this.heartbeatId = setInterval(function() {
     self._client.ggPM('setPlayheadPosition', self.currentPosition);
     self.currentPosition++;
@@ -157,6 +158,14 @@ NielsenDCR.prototype.getContentMetadata = function(track, type) {
   var propertiesPath = 'properties.';
   if (type && type === 'contentEvent') propertiesPath = 'properties.content.';
 
+  var integrationOpts = track.options(this.name);
+  var adLoadType = formatLoadType(integrationOpts, track, propertiesPath);
+  // adLoadType will be falsy if the `load_type` is NOT 'dynamic' (i.e. it IS 'linear' instead)
+  // we bubble up false to the calling content/playback method so we can early return, as
+  // DCR should not be tracking ratings for content of `load_type` 'linear'
+  if (!adLoadType) return;
+  this.isDCRStream = true;
+
   var customAssetId;
   if (this.options.contentAssetIdPropertyName) {
     customAssetId = track.proxy(
@@ -167,7 +176,6 @@ NielsenDCR.prototype.getContentMetadata = function(track, type) {
     track.proxy(propertiesPath + 'content_asset_id') ||
     track.proxy(propertiesPath + 'asset_id');
   var assetId = customAssetId || assetIdProp;
-  var integrationOpts = track.options(this.name);
   var contentMetadata = {
     type: 'content',
     assetid: assetId,
@@ -176,8 +184,7 @@ NielsenDCR.prototype.getContentMetadata = function(track, type) {
     isfullepisode: track.proxy(propertiesPath + 'full_episode') ? 'y' : 'n',
     mediaURL: track.proxy('context.page.url'),
     airdate: formatAirdate(track.proxy(propertiesPath + 'airdate')),
-    // `adLoadType` may be set in int opts, falling back to `load_type` property per our video spec
-    adloadtype: formatLoadType(integrationOpts, track, propertiesPath),
+    adloadtype: adLoadType,
     // below metadata fields must all be set in event's integrations opts object
     crossId1: find(integrationOpts, 'crossId1'),
     crossId2: find(integrationOpts, 'crossId2'),
@@ -219,8 +226,11 @@ NielsenDCR.prototype.getContentMetadata = function(track, type) {
  */
 
 NielsenDCR.prototype.getAdMetadata = function(track) {
-  var type = track.proxy('properties.type');
+  var integrationOpts = track.options(this.name);
+  var adLoadType = formatLoadType(integrationOpts, track, 'properties');
+  if (!adLoadType) return;
 
+  var type = track.proxy('properties.type');
   if (typeof type === 'string') type = type.replace('-', '');
 
   var customAssetId;
@@ -250,6 +260,7 @@ NielsenDCR.prototype.videoContentStarted = function(track) {
   clearInterval(this.heartbeatId);
 
   var contentMetadata = this.getContentMetadata(track);
+  if (!contentMetadata) return;
   var position = track.proxy('properties.position');
   var livestream = track.proxy('properties.livestream');
 
@@ -276,6 +287,7 @@ NielsenDCR.prototype.videoContentStarted = function(track) {
 
 NielsenDCR.prototype.videoContentPlaying = function(track) {
   clearInterval(this.heartbeatId);
+  if (!this.isDCRStream) return;
 
   var assetId = this.options.contentAssetIdPropertyName
     ? track.proxy('properties.' + this.options.contentAssetIdPropertyName)
@@ -293,12 +305,15 @@ NielsenDCR.prototype.videoContentPlaying = function(track) {
  */
 
 NielsenDCR.prototype.videoContentCompleted = function(track) {
+  var self = this;
+
   clearInterval(this.heartbeatId);
+  if (!this.isDCRStream) return;
 
   var position = track.proxy('properties.position');
   var livestream = track.proxy('properties.livestream');
 
-  if (livestream) position = getOffsetTime(position);
+  if (livestream) position = getOffsetTime(position, self.options);
 
   this._client.ggPM('setPlayheadPosition', position);
   this._client.ggPM('stop', position);
@@ -313,21 +328,24 @@ NielsenDCR.prototype.videoContentCompleted = function(track) {
 NielsenDCR.prototype.videoAdStarted = function(track) {
   clearInterval(this.heartbeatId);
 
-  var contentMetadata = {};
-  var adAssetId = this.options.adAssetIdPropertyName
-    ? track.proxy('properties.' + this.options.adAssetIdPropertyName)
-    : track.proxy('properties.asset_id');
-  var position = track.proxy('properties.position');
   var type = track.proxy('properties.type');
-
   if (typeof type === 'string') type = type.replace('-', '');
   // edge case: if pre-roll, you must load the content metadata first
   // because nielsen ties ad attribution to the content not playback session
+  var contentMetadata = {};
   if (type === 'preroll') {
     contentMetadata = this.getContentMetadata(track, 'contentEvent');
+    if (!contentMetadata) return;
     this._client.ggPM('loadMetadata', contentMetadata);
   }
 
+  if (!this.isDCRStream) return;
+
+  var adAssetId = this.options.adAssetIdPropertyName
+    ? track.proxy('properties.' + this.options.adAssetIdPropertyName)
+    : track.proxy('properties.asset_id');
+  var position = track.proxy('properties.position');
+
   var adMetadata = {
     assetid: adAssetId,
     type: type || 'ad'
@@ -348,6 +366,7 @@ NielsenDCR.prototype.videoAdStarted = function(track) {
 
 NielsenDCR.prototype.videoAdPlaying = function(track) {
   clearInterval(this.heartbeatId);
+  if (!this.isDCRStream) return;
 
   var position = track.proxy('properties.position');
   // first argument below is "null" b/c `heartbeat` doesn't need to keep track of ad asset ids
@@ -363,6 +382,7 @@ NielsenDCR.prototype.videoAdPlaying = function(track) {
 
 NielsenDCR.prototype.videoAdCompleted = function(track) {
   clearInterval(this.heartbeatId);
+  if (!this.isDCRStream) return;
 
   var position = track.proxy('properties.position');
 
@@ -381,12 +401,14 @@ NielsenDCR.prototype.videoAdCompleted = function(track) {
 NielsenDCR.prototype.videoPlaybackPaused = NielsenDCR.prototype.videoPlaybackSeekStarted = NielsenDCR.prototype.videoPlaybackBufferStarted = function(
   track
 ) {
+  var self = this;
   clearInterval(this.heartbeatId);
+  if (!this.isDCRStream) return;
 
   var position = track.proxy('properties.position');
   var livestream = track.proxy('properties.livestream');
 
-  if (livestream) position = getOffsetTime(position);
+  if (livestream) position = getOffsetTime(position, self.options);
 
   this._client.ggPM('stop', position);
 };
@@ -403,6 +425,7 @@ NielsenDCR.prototype.videoPlaybackResumed = NielsenDCR.prototype.videoPlaybackSe
   track
 ) {
   clearInterval(this.heartbeatId);
+  if (!this.isDCRStream) return;
 
   var contentAssetId = this.options.contentAssetIdPropertyName
     ? track.proxy('properties.' + this.options.contentAssetIdPropertyName)
@@ -422,12 +445,13 @@ NielsenDCR.prototype.videoPlaybackResumed = NielsenDCR.prototype.videoPlaybackSe
     this._client.ggPM('end', this.currentPosition);
 
     if (type === 'ad') {
-      this._client.ggPM('loadMetadata', this.getAdMetadata(track));
+      var adMetadata = this.getAdMetadata(track);
+      if (!adMetadata) return;
+      this._client.ggPM('loadMetadata', adMetadata);
     } else if (type === 'content') {
-      this._client.ggPM(
-        'loadMetadata',
-        this.getContentMetadata(track, 'contentEvent')
-      );
+      var contentMetadata = this.getContentMetadata(track, 'contentEvent');
+      if (!contentMetadata) return;
+      this._client.ggPM('loadMetadata', contentMetadata);
     }
   }
 
@@ -438,25 +462,31 @@ NielsenDCR.prototype.videoPlaybackResumed = NielsenDCR.prototype.videoPlaybackSe
  * Video Playback Completed
  * Video Playback Interrupted
  *
+ *
  * @api public
  */
 
 NielsenDCR.prototype.videoPlaybackCompleted = NielsenDCR.prototype.videoPlaybackInterrupted = function(
   track
 ) {
+  var self = this;
   clearInterval(this.heartbeatId);
+  if (!this.isDCRStream) return;
 
   var position = track.proxy('properties.position');
   var livestream = track.proxy('properties.livestream');
 
-  if (livestream) position = getOffsetTime(position);
+  if (livestream) position = getOffsetTime(position, self.options);
 
   this._client.ggPM('setPlayheadPosition', position);
   this._client.ggPM('end', position);
 
-  // reset state
+  // reset state because "Video Playback Completed/Interrupted" are "non-recoverable events"
+  // e.g. they should always be followed by the start of a new video session with either
+  // "Video Content Started" or "Video Ad Started" events
   this.currentPosition = 0;
   this.currentAssetId = null;
+  this.isDCRStream = false;
   this.heartbeatId = null;
 };
 
@@ -488,10 +518,10 @@ function formatLoadType(integrationOpts, track, propertiesPath) {
   var loadType =
     find(integrationOpts, 'ad_load_type') ||
     track.proxy(propertiesPath + 'load_type') ||
-    track.proxy('properties.load_type');
-  // linear or dynamic
-  // linear means original ads that were broadcasted with tv airing. much less common use case
-  loadType = loadType === 'dynamic' ? '2' : '1';
+    track.proxy(propertiesPath + 'loadType');
+  // DCR is meant to track videos with ad `load_type` dynamic only
+  // otherwise, we return `false` so we can easily early return in the calling method
+  loadType = loadType === 'dynamic' ? '2' : false;
   return loadType;
 }
 
@@ -501,14 +531,15 @@ function formatLoadType(integrationOpts, track, propertiesPath) {
  * handles offsets for livestreams, if applicable.
  *
  * @param {*} position Should be negative int representing livestream offset
+ * @param {*} options Integration settings
  * @returns {Number} Unix timestamp in seconds
  *
  * @api private
  */
 
-function getOffsetTime(position) {
+function getOffsetTime(position, options) {
   var date = Math.floor(Date.now() / 1000);
-  if (!position) return date;
+  if (!position || options.sendCurrentTimeLivestream) return date;
 
   try {
     if (typeof position !== 'number') {

integrations/nielsen-dcr/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@segment/analytics.js-integration-nielsen-dcr",
   "description": "The Nielsen DCR analytics.js integration.",
-  "version": "1.5.0",
+  "version": "2.0.1",
   "keywords": [
     "analytics.js",
     "analytics.js-integration",