Video: Version 1.x Tracking

Parse.ly’s JavaScript tracker supports video event tracking on an opt-in basis. If you’d like to enable video tracking on your site, please contact support@parsely.com.

To support tracking starts and view time on your video player, the Parse.ly tracker includes a small public API that JavaScript developers can use to tell the tracker to send event information to Parse.ly. Integrators must write JavaScript that attaches event listeners to each video that call the tracking functions detailed below. Parse.ly’s tracker does not automatically discover videos on the page, and it is the job of the integrator to tell the tracker about each video.

The two calls in the Parse.ly tracker’s public video tracking API are trackPlay and trackPause. In a complete integration, these methods are called whenever the tracked video plays or pauses, allowing accurate tracking of view time and play count.

Here’s an example of how the public video tracker API might be used to instrument an embedded video using JWPlayer:

< script src="http://content.jwplatform.com/libraries/2SJ3KAcS.js"></script>
<div id="embed_container">Loading the player...</div>
<script type="text/javascript">
  var player = jwplayer("embed_container");
  player.setup({
    file: "http://content.jwplatform.com/parse-ly-video-tracking/s/xxxxxxxx.mp4",
    image: "http://content.jwplatform.com/thumbs/xxxxxxxx.jpg",
    mediaid: "myvideoid12345",
    width: 640,
    height: 360,
    title: 'Basic Video Embed',
    description: 'A video with a basic title and description!'
  });
  player.on('ready', function() {
    player.on("play", function(){
      var playlistItem = player.getPlaylistItem(player.getPlaylistIndex());
      PARSELY.video.trackPlay(
        playlistItem.mediaid,
        {
          // required
          title: playlistItem.title,
          // recommended
          image_url: playlistItem.image,
          section: "My Video's Section",
          pub_date_tmsp: 1474393968763,  // milliseconds since unix epoch
          // optional
          tags: ["mytag1", "mytag2"],
          authors: ["My Video's Author"]
        });
    });
    player.on("pause", function(){
      var playlistItem = player.getPlaylistItem(player.getPlaylistIndex());
      PARSELY.video.trackPause(playlistItem.mediaid);
    });
    player.on("stop", function(){
      var playlistItem = player.getPlaylistItem(player.getPlaylistIndex());
      PARSELY.video.trackPause(playlistItem.mediaid);
    });
  });
</script>

The goals of a Parse.ly video integration are to find each video on the page, attach event listeners that will trigger when those videos are started and stopped, and call trackPlay and trackPause in response to those events. In this example, we first instantiate a jwplayer object that represents a video embedded on the page. We then add an event listener to the jwplayer instance for each event we’re interested in.

When using a different video embed provider (YouTube, for example), the integration code will look very similar to the above example. It will still need to discover each video on the page and attach event listeners to those videos, and it will still need to call the Parse.ly tracking functions in response to play and pause events on those videos. The difference between a JWPlayer and a YouTube integration is the JavaScript embedded video API provided by the platform. In the above example, the jwplayer function is provided by the JWPlayer JavaScript API. A YouTube integration would use an analogous function provided by the YouTube JavaScript API, but the idiosyncrasies of that API might lead to code that looks a bit different from the above.

Video Metadata

In the example above, the trackPlay call includes an argument metadata: an object containing metadata about the video. The fields that can be included in this object are as follows:

Although the video ID parameter is all that’s technically needed to track a video, we recommend including several other fields in the metadata object to make it easier for dashboard users to tell your videos apart. In particular, including a recognizable title and image_url in the metadata object ensures that videos can be easily identified in the Parse.ly dashboard. pub_date_tmsp allows users to filter for videos based on publish date within the dashboard or API. Similarly, including image_url, section, and tags can help provide deeper and more accessible insights in the dashboard.

If possible, try to make sure that metadata used for videos aligns with that used for posts. This opens up more possibilities for consolidated analysis across both content types.

Video Tracking JavaScript API

PARSELY.video.trackPlay(videoId, metadata, urlOverride)

Tell the Parse.ly tracker that this video started playing. trackPlay can be called on the initial play after the pageload and/or subsequent plays. This call starts a timer that causes vheartbeat events to be periodically sent until the next call to trackPause. When called for the first time on a given pageload or after a call to reset, this call causes a videostart event to be sent.

PARSELY.video.trackPause(videoId, metadata, urlOverride)

Tell the Parse.ly tracker that this video stopped playing. This call stops the internal vheartbeat timer until the next call to trackPlay.

PARSELY.video.reset(videoId)

Unset the flag that indicates that this video has started playing. The next call to trackPlay will cause a videostart event to be sent.

Tracking video within iframes

If you’re loading embedded videos via iframe, you’ll need to load the Parse.ly tracker within the iframe in addition to the parent page. In doing so, you should disable automatic pageview tracking within the iframe, as shown below:

<script>
  window.PARSELY = window.PARSELY || {
    autotrack: false
  };
</script>
<!-- START Parse.ly Include -->
<!-- ...insert the parse.ly tracker code here... -->
<!-- END Parse.ly Include -->

Then, bind trackPlay and trackPause to the relevant events in the iframe (along with the appropriate metadata). Finally, pass a urlOverride param with the value of the parent page URL in order to associate it with plays of the iframe video.

Note that Parse.ly video tracker versions >=1.0.0 can detect and track iframe video from a number of players automatically. Consult the documentation on those tracker versions for details.