Developer Guides
Developer GuidesAPI ReferenceHelp CenterEngineering BlogCommunityOpen App

Track video plays

Suggest Edits

Many organizations embed videos on their site or application. These videos are placed inside an iframe on the site. Although we don't have the ability to track events in an iframe by default, you can use the APIs of many companies such as YouTube, Wistia or Vimeo to hook our heap.track API into event listeners. This allows Heap to track what is happening in the iframe!

Tracking Youtube Video Clicks

If you're using YouTube, review their API reference for iframes. This example generates a YouTube video embed and sends a heap.track call for several of the different player states. The way you go about implementing the callbacks is up to you. For example, you can leave out the video Finished/Paused, and remove the onPlayerReady events and function.

Usually an iframe is embedded like this:

<iframe allowfullscreen="" frameborder="0" height="360" src="//www.youtube.com/embed/VIDEO_ID" width="640"></iframe>

This example assumes you replace the iframe with the HTML/code below:

<div id="player"></div>

Then in script tags add the following code. Make sure you replace VIDEO_ID with the video ID unique to your Youtube video.

var tag = document.createElement('script'); 
tag.src = "https://www.youtube.com/iframe_api"; 
var firstScriptTag = document.getElementsByTagName('script')[0]; 
firstScriptTag.parentNode.insertBefore(tag, firstScriptTag); 
var player; 
function onYouTubeIframeAPIReady() { 
	player = new YT.Player('player', { 
		width: '640', 
		height: '390', 
		videoId: 'VIDEO_ID', //replace VIDEO_ID with the videoId from Youtube 
		events: { 
			'onPlayerReady': onPlayerReady, 
			'onStateChange': onPlayerStateChange 
		} 
	}); 
}

function onPlayerReady(event) { 
	console.log('player ready'); 
}

function onPlayerStateChange(newState) { 
	if (newState.data == 1) { 
		heap.track('Video Playing'); 
	} else if (newState.data == 0) { 
		heap.track('Video Finished'); 
	} else if (newState.data == 2) { 
		heap.track('Video Paused'); 
	} 
}

Tracking Vimeo Videos

If you're using Vimeo, review their API docs for player.js to embed a player. To set up tracking on the video player elements, see Mozilla's documentation on Media events.

Tracking Wistia Videos

Implement the following code to track a user's progression through a Wistia video. This will send track events to Heap when the user has viewed 25/50/75/100% of the video, and when they have completed it. 

<script>
  var trackWistiaPlaysInHeap = function(video, percentage){
  var reportingObject = {
    nameOfVideo: video.name(),
    percentageReached: percentage,
    duration: (video.duration() / 60).toFixed(2) + ' minutes total'
  };
    window.heap.track("Wistia Video", reportingObject);
};

/*   Initialize all videos on the page to be handled by
     the Wistia integration */
window._wq = window._wq || [];
_wq.push({ '_all': function(video) {

  /* Define time markers in number of seconds */
  var quarterPlayed = Math.floor(video.duration() / 4),
      halfPlayed = Math.floor(video.duration() / 2),
      threeQuartersPlayed = quarterPlayed * 3;

  /*Track when a video is played */
  video.bind('play', function(){
    trackWistiaPlaysInHeap(video, 0);
  });

  /* Track quarters watched */
  video.bind('secondchange', function(s){
    if (s === quarterPlayed){
      trackWistiaPlaysInHeap(video, 0.25);
    }
    if (s === halfPlayed){
      trackWistiaPlaysInHeap(video, 0.5);
    }
    if (s === threeQuartersPlayed){
      trackWistiaPlaysInHeap(video, 0.75);
    }
  });

  /* Track videos finished */
  video.bind('end', function() {
    trackWistiaPlaysInHeap(video, 1);
  });
}});
</script>

Tracking <video> Elements

The snippet below is used to enable Heap tracking for <video> elements. It assumes there's a single video on the page, and an event is captured on Heap whenever the video is played, paused, or ended. 

// Query video element
var video = document.querySelector('video');

// Enable video tracking
video.onplaying = function(e) {
    heap.track('Video Played');
};
video.onpause = function(e) {
    heap.track('Video Paused');
};
video.onended = function(e) {
    heap.track('Video Ended');
};

Updated about 1 year ago