JWPlayer 6 Heartbeat

Loading the player …


Video Heartbeat is the current video analytics measurement strategy for Adobe’s Marketing Cloud. Heartbeat has been around since October of 2013, see blog post. With some recent improvements to the library (v.1.5.2) implementing Heartbeat is easier and more robust than ever before. In this blog post I will be covering tips for implementing the Video Heartbeat library for a JW Player 6 video player.  Please see the complete documentation on Video Heartbeat for greater details on pre-requisites, implementation, and reporting set-up.

The video player at the top of this post is tagged with the Video Heartbeat code, hosted in Adobe’s Dynamic Tag Management (DTM) solution.  A link to a sample player outside of DTM can be found here. See notes on DTM below for more information on the differences between the DTM and standard delivery methods.

Getting Started
In order to implement Video Heartbeat for your JWPlayer 6 Player you will need the fol­low­ing items:
Abil­ity to add code to your site: In addi­tion to analytics changes, you may also need to modify the video player code.

A copy of the latest Video Heartbeat Library for JavaScript: The latest libraries, documentation and sample players can be found on the Adobe GitHub Video Heartbeat.

Installation of jQuery library on your site: The Video Heartbeat solution currently relies on jQuery for extending the delegates, using the $.extend() method found in jQuery 1.1.4 or higher.

Adobe Marketing Cloud Prerequisites: The solution requires the following to be in place:

  • Video Heartbeat stream contract for analytics
  • Regional Data Collection (RDC) analytics servers (omtrdc.net not 2o7.net)
  • Marketing Cloud Organization ID (####@Adobe)
  • Visitor ID API JavaScript
  • appMeasurement  or H code version H27 or higher

Measurement Plan
I am not going to cover the mea­sure­ment plan here, but I strongly encour­age you to map out what aspects of video play­back you need to cap­ture and select the Analytics variables you will use before you start mod­i­fy­ing your code.  A mea­sure­ment plan will help with imple­men­ta­tion and pro­vide doc­u­men­ta­tion into the future.

Measurement Library
No changes need to be made within your appMeasurement or H-code libraries.  The Video Heartbeat solution relies on context data variables for all data collection, so no mapping of variables needs to be done within the analytics code itself, instead all mapping is done by processing rules.  It is highly recommended that you use the latest appMeasurement.js library for the most reliable compatibility.

Heartbeat Bridge
The Heartbeat Bridge javascript file, found here, combines all the declarations, objects and extensions into one generic helper file, to be used with any javascript heartbeat implementation.  It simplifies the integration steps by providing a single file with all the Heartbeat library extensions.  The Heartbeat Bridge file should be loaded between the Heartbeat library and the player delegate files.

JWPlayer 6 Player Delegate
The player delegate javascript file replaces the Milestone player mapping file, with a new version updated with the Heartbeat tracking methods.  The script contained in the Heartbeat Bridge file, found here, map the video player events to the Heartbeat methods and populate the Video Info object with the data for the current video asset.  The example code provided on this site only sets the very basic data and does not include Chapters, Ads, or QoS.  This file should be considered as a starting off point for building your own player delegate.

Script Load Order
The load order of the javascript files is critical to having a successful implementation.  The correct load order is:

  • jQuery
  • VisitorAPI
  • appMeasurement
  • Video Heartbeat Library
  • Heartbeat Bridge
  • Player Delegate

Note:  The Player Delegate methods should not be called until after the video player loads on the page.  You may need to write additional logic to insure this load order, depending on your implementation.  In the sample players I have wrapped the player delegate in a function and added a page level call to the function, which fires after the player object loads on the page.

DTM
When using Adobe’s Dynamic Tag Manager (DTM) service for hosting the video solution, note that load order is still very important. In the sample player at the top of this page, the video files are included in a separate page load file, with three sequential javascript files included in the rule in the following order:

  • Video Heartbeat Library
  • Heartbeat Bridge
  • Player Delegate

Also note, in the HeartbeatBridge.js file, the following change was made to reference the Marketing Cloud Visitor ID service properly in the Adobe Heartbeat Plugin script:
Original Bridge code:
var ahPluginConfig = new AdobeHeartbeatPluginConfig("heartbeats.omtrdc.net", s.visitor.marketingCloudOrgID);

DTM Bridge code:
var ahPluginConfig = new AdobeHeartbeatPluginConfig("heartbeats.omtrdc.net", _satellite.getVisitorId().marketingCloudOrgID);

Player Metadata
Additional data about the content, player, or context, can be added through context data variables within the player delegate file, using the aaPlugin.setVideoMetadata() method. Metadata can only be set on video start, ad start and chapter start. Note that on video complete the metadata object should be set to null. Within the JWPlayer 6 Player Delegate file included in this blog post, a Metadata object is being set on video start and cleared on video complete. Only data included as metadata data can be correctly tied to video time spent and video complete metrics within the analytics reporting interface.

Metadata context data variables require custom processing rules to be included in the report suite set-up, to map context data variables to custom eVars.

Validation
After completing implementation use a packet sniffer to check the tracking calls. You should see two sets of calls, one going to your standard analytics tracking server and a second set going to the heartbeats.omtrdc.net tracking server. Important items to note include that both sets of tracking calls use and reference the same “mid” variable value. Also note that metadata is sent on both the analytics start call and the heartbeat start call. Finally, verify that heartbeat calls stop when the video is paused and that the “l:event:playhead” variable found in the heartbeat calls always reflects the correct playhead position at the time that the call was sent.

After enabling Video Reporting within your Analytics Report Suite and Heartbeat calls have been sent to the analytics and heartbeat servers you will begin to see all your video data within the Video reports in the Adobe Analytics tools. I recommend utilizing the solution variables found in Video Reporting and creating processing rules for any transferring or copying of video data to custom eVars and events. This will provide the most flexibility and control over your current and historic video data.