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
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.
// 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.
// Setup the AdobeHeartbeat plugin, this is passed into Heartbeat()
var ahPlugin = new AdobeHeartbeatPlugin(new SampleAdobeHeartbeatPluginDelegate());
var ahPluginConfig = new AdobeHeartbeatPluginConfig(
ahPluginConfig.ovp = Configuration.HEARTBEAT.OVP;
ahPluginConfig.sdk = Configuration.HEARTBEAT.SDK;
ahPluginConfig.debugLogging = true; // set this to false for production apps.
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.
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.
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._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)
// 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()
- 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.