Video Tracking

This document refers to versions of the Parse.ly tracker >=0.5.0 and <1.0.0. Documentation for video tracking >=1.0.0 can be found here.

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:

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:

Metadata field name Inclusion Description
title required String the title of the video
image_url recommended String URL pointing to a full-sized (i.e. not thumbnail) image representing the video
duration recommended Integer the duration of the video in milliseconds
pub_date_tmsp recommended Integer the date the video was published specified in milliseconds since the Unix epoch
section recommended String the section a video belongs to
authors optional Array the author(s) of the video (an author need not correspond to a person but can be an entity like a studio)
tags optional Array a list of arbitrary tags that provide more context for reporting

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.

Parameter Type Required Description
videoId string yes An identifier indicating the video being played. Should be unique per Parse.ly API key and video.
metadata object yes An object containing metadata about the video being played. (see above for details)
urlOverride string no The URL of the page on which the video is embedded. Defaults to the URL that was sent on the most recent Parse.ly tracker request, usually window.location.href. This parameter is useful in cases such as infinite scroll where PARSELY.lastRequest or window.location.href might not be that of the page on which the video is embedded.

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.

Parameter Type Required Description
videoId string yes An identifier indicating the video being paused. Should be unique per Parse.ly API key and video.
metadata object no An object containing metadata about the video being paused. (see above for details)
urlOverride string no The URL of the page on which the video is embedded. Defaults to the URL that was sent on the most recent Parse.ly tracker request, usually window.location.href. This parameter is useful in cases such as infinite scroll where PARSELY.lastRequest or window.location.href might not be the URL of the page on which the video is embedded.

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.

Parameter Type Required Description
videoId string yes An identifier indicating the video being reset. Should be unique per Parse.ly API key and video.
Do you have an urgent support question?