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.
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.
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)
- appMeasurement or H code version H27 or higher
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.
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.
HTML5 Player Delegate
Script Load Order
- 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.
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.
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.