YouTube iFrame Player with Heartbeat


YouTube is the most popular video player and video service in the world. In this blog post I will cover the basics of adding the Adobe Video Heartbeat Analytics solution to the YouTube iFrame Player.

The YouTube iFrame 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 YouTube iFrame Player you will need the following items:
Ability to add code to your site: In addition 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.

Familiarity with the YouTube Player API: YouTube iFrame Player API

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 measurement plan here, but I strongly encourage you to map out what aspects of video playback you need to capture and select the Analytics variables you will use before you start modifying your code.  A measurement plan will help with implementation and provide documentation 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.

HTML5 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, maps the video player events to the Heartbeat methods and populates 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.

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 YouTube iFrame 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.