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