Video Heartbeat v1.5 Implementation 3: Variables, Metrics and Architecture

Video Heartbeat v1.5 Implementation Posts:

In this post, I would like to discuss about variables, metrics and the core architecture in Adobe Video Heartbeat v1.5.

Video Heartbeat Variables and Metrics

Before you start video heartbeat implementation, you need to understand what you are measuring with video heartbeat, especially, if you are not familiar with Adobe Analytics. Actually, what you measure is based on what your company’s KPI and business goal. You can implement custom variables and metrics as many as you need in your video reports; however, the following business questions will be covered by the default video heartbeat implementation.

The number of the video starts
The number of the video completes
The total amount of time (in seconds) the video was played
Which part of the video was played (Content Segment)
The number of the chapter starts
The number of the chapter completes
The total amount of time (in seconds) the chapter was played
The number of the ad starts
The number of the ad completes
The total amount of time (in seconds) the ad was played

To see the full list of the default variables and metrics in video heartbeat, please see Video Variables and Events on Adobe Online Guide.

Basically, we need variables (row) and metrics (column) in Adobe Analytics reports. Variables such as video name, chapter name, video length or player name will be generated based on the parameters. Metrics such as video start, video complete or the total amount of time watched will be generated based on the method calls. For example:

id, length, playerName parameters are variables
trackChapterStart() method call increments the number of the chapter starts as trackVideoLoad() + trackPlay() method calls will increment the number of the video starts.

Video Heartbeat Architecture and Configuration

Currently, video heartbeat is available for JavaScript, Flash, iOS and Android. Regardless the platform, video heartbeat architecture, configuration, methods and parameters are same. Since my background is a front-end developer, I use JavaScript as the example. In your implementation, you need to work on three things: configuration, parameters and methods.

1. Set the video heartbeat configuration

Video heartbeat requires the six instances in the configuration: Visitor, AppMeasurement, Heartbeat and three heartbeat plugins.

new Visitor() – Required for Adobe Analytics visitor control in a new AppMeasurement library
new AppMeasurement() – Adobe Analytics instance
new Heartbeat() – Main heartbeat instance
new VideoPlayerPlugin() – passed into Heartbeat()
new AdobeAnalyticsPlugin() – passed into Heartbeat()
new AdobeHeartbeatPlugin() – passed into Heartbeat()

 // Set-up the Visitor and AppMeasurement instances.
 var visitor = new Visitor(Configuration.VISITOR.MARKETING_CLOUD_ORG_ID);
 visitor.trackingServer = Configuration.VISITOR.TRACKING_SERVER;

 // Set-up the AppMeasurement component.
 var appMeasurement = new AppMeasurement();
 appMeasurement.visitor = visitor;
 appMeasurement.trackingServer = Configuration.APP_MEASUREMENT.TRACKING_SERVER;
 appMeasurement.account = Configuration.APP_MEASUREMENT.RSID;
 appMeasurement.pageName = Configuration.APP_MEASUREMENT.PAGE_NAME;
 appMeasurement.charSet = "UTF-8";
 appMeasurement.visitorID = "test-vid";

 // Setup the VideoPlayerPlugin, this is passed into Heartbeat()
 this._playerPlugin = new VideoPlayerPlugin(new SampleVideoPlayerPluginDelegate(this._player));
 var playerPluginConfig = new VideoPlayerPluginConfig();
 playerPluginConfig.debugLogging = true; // set this to false for production apps.
 this._playerPlugin.configure(playerPluginConfig);

 // Setup the AdobeAnalyticsPlugin plugin, this is passed into Heartbeat()
 this._aaPlugin = new AdobeAnalyticsPlugin(appMeasurement, new SampleAdobeAnalyticsPluginDelegate());
 var aaPluginConfig = new AdobeAnalyticsPluginConfig();
 aaPluginConfig.channel = Configuration.HEARTBEAT.CHANNEL;
 aaPluginConfig.debugLogging = true; // set this to false for production apps.
 this._aaPlugin.configure(aaPluginConfig);

 // Setup the AdobeHeartbeat plugin, this is passed into Heartbeat()
 var ahPlugin = new AdobeHeartbeatPlugin(new SampleAdobeHeartbeatPluginDelegate());
 var ahPluginConfig = new AdobeHeartbeatPluginConfig(
 Configuration.HEARTBEAT.TRACKING_SERVER,
 Configuration.HEARTBEAT.PUBLISHER);
 ahPluginConfig.ovp = Configuration.HEARTBEAT.OVP;
 ahPluginConfig.sdk = Configuration.HEARTBEAT.SDK;
 ahPluginConfig.debugLogging = true; // set this to false for production apps.
 ahPlugin.configure(ahPluginConfig);

 var plugins = [this._playerPlugin, this._aaPlugin, ahPlugin];

 // Setup and configure the Heartbeat lib.
 this._heartbeat = new Heartbeat(new SampleHeartbeatDelegate(), plugins);
 var configData = new HeartbeatConfig();
 configData.debugLogging = true; // set this to false for production apps.
 this._heartbeat.configure(configData);

// Set-up the Visitor and AppMeasurement instances.

var visitor = new Visitor(Configuration.VISITOR.MARKETING_CLOUD_ORG_ID);

visitor.trackingServer = Configuration.VISITOR.TRACKING_SERVER;

// Set-up the AppMeasurement component.

var appMeasurement = new AppMeasurement();

appMeasurement.visitor = visitor;

appMeasurement.trackingServer = Configuration.APP_MEASUREMENT.TRACKING_SERVER;

appMeasurement.account = Configuration.APP_MEASUREMENT.RSID;

appMeasurement.pageName = Configuration.APP_MEASUREMENT.PAGE_NAME;

appMeasurement.charSet = "UTF-8";

appMeasurement.visitorID = "test-vid";

// Setup the VideoPlayerPlugin, this is passed into Heartbeat()

this._playerPlugin = new VideoPlayerPlugin(new SampleVideoPlayerPluginDelegate(this._player));

var playerPluginConfig = new VideoPlayerPluginConfig();

playerPluginConfig.debugLogging = true; // set this to false for production apps.

this._playerPlugin.configure(playerPluginConfig);

// Setup the AdobeAnalyticsPlugin plugin, this is passed into Heartbeat()

this._aaPlugin = new AdobeAnalyticsPlugin(appMeasurement, new SampleAdobeAnalyticsPluginDelegate());

var aaPluginConfig = new AdobeAnalyticsPluginConfig();

aaPluginConfig.channel = Configuration.HEARTBEAT.CHANNEL;

aaPluginConfig.debugLogging = true; // set this to false for production apps.

this._aaPlugin.configure(aaPluginConfig);

// Setup the AdobeHeartbeat plugin, this is passed into Heartbeat()

var ahPlugin = new AdobeHeartbeatPlugin(new SampleAdobeHeartbeatPluginDelegate());

var ahPluginConfig = new AdobeHeartbeatPluginConfig(

Configuration.HEARTBEAT.TRACKING_SERVER,

Configuration.HEARTBEAT.PUBLISHER);

ahPluginConfig.ovp = Configuration.HEARTBEAT.OVP;

ahPluginConfig.sdk = Configuration.HEARTBEAT.SDK;

ahPluginConfig.debugLogging = true; // set this to false for production apps.

ahPlugin.configure(ahPluginConfig);

var plugins = [this._playerPlugin, this._aaPlugin, ahPlugin];

// Setup and configure the Heartbeat lib.

this._heartbeat = new Heartbeat(new SampleHeartbeatDelegate(), plugins);

var configData = new HeartbeatConfig();

configData.debugLogging = true; // set this to false for production apps.

this._heartbeat.configure(configData);

2. Set the required parameters

Video heartbeat parameters are passed via VideoPlayerPluginDelegate class. To see the full code, please read the Adobe’s sample in SDK.

For video:

this._videoInfo = new VideoInfo();
this._videoInfo.id = "test-video-1"; // video id
this._videoInfo.name = "my-test-video-1-2015-04-21-season1"; // the name of the video (optional)
this._videoInfo.playerName = "html5-player"; // the name of the player
this._videoInfo.length = 600; // length of the video in seconds (10:00 = 600 seconds)
this._videoInfo.streamType = "vod"; // vod, live or liner (continuous stream such as radio)
this._videoInfo.playhead = 0; // current playhead in seconds (0:00 = 0 at the video start)

this._videoInfo = new VideoInfo();

this._videoInfo.id = "test-video-1"; // video id

this._videoInfo.name = "my-test-video-1-2015-04-21-season1"; // the name of the video (optional)

this._videoInfo.playerName = "html5-player"; // the name of the player

this._videoInfo.length = 600; // length of the video in seconds (10:00 = 600 seconds)

this._videoInfo.streamType = "vod"; // vod, live or liner (continuous stream such as radio)

this._videoInfo.playhead = 0; // current playhead in seconds (0:00 = 0 at the video start)

For chapter:

this._chapterInfo = new ChapterInfo();
this._chapterInfo.length = 300; // the length of the chapter in seconds (5:00 = 300)
this._chapterInfo.startTime = 0; the playhead at the chapter start (0:00 = 0 at the chapter start)
this._chapterInfo.position = 1; // the position of the chapter = chapter's index
this._chapterInfo.name = "chapter1-we-came-back!"; // the name of the chapter (optional)

this._chapterInfo = new ChapterInfo();

this._chapterInfo.length = 300; // the length of the chapter in seconds (5:00 = 300)

this._chapterInfo.startTime = 0; the playhead at the chapter start (0:00 = 0 at the chapter start)

this._chapterInfo.position = 1; // the position of the chapter = chapter's index

this._chapterInfo.name = "chapter1-we-came-back!"; // the name of the chapter (optional)

For ad:

// Prepare the ad break info, required to fire the ad start call.
this._adBreakInfo = new AdBreakInfo();
this._adBreakInfo.name = "First Ad-Break";
this._adBreakInfo.position = 1; // the position of the ad. 1 = the first ad
this._adBreakInfo.playerName = "html5-player"; // the name of the player
this._adBreakInfo.startTime = // the ad playhead in seconds (different from the main video's playhead);

// Prepare the ad info.
this._adInfo = new AdInfo();
this._adInfo.id = "ad-1-car-rental"; // ad id
this._adInfo.name = "car-rental-ad-2015-spring"; // the name of the ad (optional)
this._adInfo.length = 30; // the length of the ad in seconds (0:30 = 30)
this._adInfo.position = 1; // the position of the ad. 1 = the first ad

// Prepare the ad break info, required to fire the ad start call.

this._adBreakInfo = new AdBreakInfo();

this._adBreakInfo.name = "First Ad-Break";

this._adBreakInfo.position = 1; // the position of the ad. 1 = the first ad

this._adBreakInfo.playerName = "html5-player"; // the name of the player

this._adBreakInfo.startTime = // the ad playhead in seconds (different from the main video's playhead);

// Prepare the ad info.

this._adInfo = new AdInfo();

this._adInfo.id = "ad-1-car-rental"; // ad id

this._adInfo.name = "car-rental-ad-2015-spring"; // the name of the ad (optional)

this._adInfo.length = 30; // the length of the ad in seconds (0:30 = 30)

this._adInfo.position = 1; // the position of the ad. 1 = the first ad

3. Call the methods at the appropriate timing

The most methods in vide heartbeat are very straight forward. trackChapterStart() increments the number of the chapter start as trackVideoComplete() increments the number of the video completes. However, video start requires two methods, trackVideoLoad() and trackPlay(). The video start call is sent to the analytic server when the trackPlay() is called after trackVideoLoad().

Example video events flow:

Web page loaded, video heartbeat configuration
Auto play or user click the play button: trackVideoLoad()
Ad 1 start, play and complete: trackAdStart(), trackAdComplete()
Main video start: trackPlay()
Chapter 1 start: trackChapterStart()
Chapter 1 complete: trackPause(), trackChapterComplete()
Ad 2 start, play and ad complete: trackAdStart(), trackAdComplete()
Chapter 2 start: trackChapterStart()
Seeking start (user grabs the progress bar): trackPause(), trackSeekStart()
Ad 2 start, play and ad complete: trackAdStart(), trackAdComplete()
Chapter 3 start at the scrubbed point: trackSeekComplete(), trackChapterStart(), trackPlay()
Chapter 3 complete: trackPause(), trackChapterComplete()
Main video complete: trackComplete()
Post-roll ad start, play and ad complete: trackAdStart(), trackAdComplete(), trackVideoUnload()
Replay the same video without refreshing browser: trackVideoLoad(), trackPlay()

Summary:

Video reports with the default implementation answer the major business questions.
The video reports consists of variables and metrics.
Video heartbeat architecture is same in the different platforms.
In your implementation, you need to work on three things: configuration, parameters and methods.

2 thoughts on “Video Heartbeat v1.5 Implementation 3: Variables, Metrics and Architecture”

Sky says:

2015-12-03 at 20:33

How would you set-up Video Heartbeat through DTM?

1. Mika Y says:
  
  2015-12-03 at 22:37
  
  I asked the same question to Adobe few months ago.
  Currently, we can’t set-up video heartbeat through DTM. However, it is on Adobe’s roadmap and they have been working on it.
  Adobe said that video heartbeat in DTM will be available sometimes in 2016.
  So, we implemented page tracking in DTM and video heartbeat in the player javascript files.
  
  Hope this helps.
  Mika