Video Tracking

This document refers to Parse.ly's automatic video tracker (>=v1.x). Documentation for earlier versions of the video tracker 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.

The Parse.ly tracker supports most of the commonly used video platforms without requiring integrators to write any code themselves. These supported platforms are listed below. The tracker automatically detects all supported video players on the page and sends videostart and vheartbeat events on your behalf. The Parse.ly JavaScript API also provides a mechanism by which integrators can track video players not supported by default, including custom-built players. Once you've gone through the integration steps, you can confirm your site is firing video views via the process outlined here.

Platform Details

mediaelement.js

The Parse.ly tracker will attempt to track any <video> or <iframe> element that includes the class mejs__player as a mediaelement.js embedded video. To ensure the necessary JavaScript API is accessible to the tracker, include the following script on the page:

<script src="https://cdn.jsdelivr.net/mediaelement/latest/mediaelement-and-player.min.js"></script>

If you want to specify a title for a mediaelement.js video without using the PARSELY.video.onPlay function described below, you can set the title attribute on the <video> or <iframe> element containing your embed.

ID field: MediaElement.currentSrc

video.js

Note to Brightcove users: these instructions are for users of plain video.js only. Instructions for Brightcove integrations can be found below.

Any <video> element that includes a class vjs-tech or video-js and does not include the Brightcove-specificdata-video-id attribute will be treated as a video.js embedded video. To ensure the necessary JavaScript API is accessible to the tracker, include the following script on the page:

<script src="//vjs.zencdn.net/5-unsafe/video.js"></script>

If you want to specify a title for a video.js video without using the PARSELY.video.onPlay function described below, you can set the title attribute on the <video> element containing your embed.

ID field: videojs().currentSrc()

Vimeo

Vimeo does not make video poster images available via JavaScript to Parse.ly's tracker. If you want poster images to appear for your videos in the Parse.ly dashboard, please see PARSELY.video.onPlay below.

ID field: Vimeo.Player.getVideoId()

JWPlayer

Since JWPlayer embeds that use <iframe> are not supported by the JWPlayer JavaScript API, the Parse.ly tracker is only able to track JWPlayer embeds that use <div>.

ID field: jwplayer.getPlaylistItem().mediaid

Kaltura

The "Auto Embed", "Dynamic Embed", and "Legacy Flash Embed" embed styles are supported by the Parse.ly tracker. The src attribute of the <script> tag comprising the embed must include the querystring argument ?externalInterfaceDisabled=false.

ID field: document.getElementById(my_embed_id).evaluate("{mediaProxy.entry.id}")

Wistia

Embedded playlists must use the "API" embed type.

ID field: Wistia.api.data.hashedId

Brightcove

Since Brightcove embeds that use <iframe> are not supported by the Brightcove JavaScript API, the Parse.ly tracker is only able to track Brightcove embeds that use <video>.

To ensure that all necessary metadata is available from your videos, check that mediainfo is defined. In a console on your page:

> var player = window.videojs("my_player_id");
> player.mediainfo
{ ... }  // should not be undefined

Brightcove videos must be initialized by a call to videojs(my_video_id) before the Parse.ly video tracker loads. If all of the videos on your page appear in videojs.players, the tracker can be safely loaded and the videos will be detected properly. If this is impossible, for example because of videos being lazily initialized in response to scroll, you can disable automatic video discovery and use the v1 video tracking API (see "Disabling Automatic Video Discovery" below). The video.js hooks interface can help with tracking logic that must be run on video initialization (the setup hook).

ID field: videojs().el_.attributes["data-video-id"].value

YouTube

To ensure the necessary JavaScript API is accessible to the tracker, include the following script on the page:

<script src="https://www.youtube.com/iframe_api"></script>

The src attribute of the <iframe> element comprising the embed must include the querystring argument ?enablejsapi=1.

ID field: YT.Player.getVideoData().video_id

Customizing Video Metadata

For supported video platforms, the Parse.ly tracker attempts to extract as much relevant metadata as possible from embedded videos. Typically this includes required fields like title, image_url, and link, as well as some optional fields like authors and tags.

Though there is no need to write custom code to extract this metadata when using a supported video platform, in some cases integrators may want to augment or change the metadata sent for each video. For this purpose, the Parse.ly JavaScript API provides the video.onPlay function, which accepts a player instance, video ID, and metadata object, and should call PARSELY.video.trackPlay. This function should be defined on the window.PARSELY object:

<script>
    PARSELY = {
        // ... other Parsely configuration options
        video: {
            onPlay: function(playerApi, videoId, metadata) {
                var metaOverrides = {
                    title: "My Video's Title",
                    section: myDataStore.getVideoSection(videoId),
                    // ...
                };
                for (var key in metaOverrides) {
                    if (metaOverrides[key]) {
                        metadata[key] = metaOverrides[key];
                    }
                }
                PARSELY.video.trackPlay(videoId, metadata);
            }
        }
        // ... other Parsely configuration options
    };
</script>

The fields that can be included in the returned object are as follows:

Metadata field name Inclusion Description
title required String the title of the video
image_url required 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

We recommend including a recognizable title and image_url in the metadata object, since these ensure 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 author, 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.

The trackPlay function also accepts an argument urlOverride that can be used to explicitly specify the url of the page on which the video is playing. This is particularly useful in integrations such as infinite scroll in which the video's "home url" may differ from the browser's current url (window.location.href).

Tracking Custom Video Players

Though many of the most popular video platforms are supported by default, the Parse.ly JavaScript API provides an interface by which integrators can track video starts and view time on unsupported or custom video players. The goal of a custom player integration is to implement a "strategy" - a JavaScript object describing how the Parse.ly tracker can detect and interact with the video players on a page.

Here's an example of a strategy custom-built for an unsupported video player:

Each key of the strategy object is important to the tracker's ability to interact with the video player:

platform

The platform attribute is the human-readable name of the player provider, for example brightcove, youtube, etc. The name given in a custom strategy should not overlap with any of the existing strategy names supported by the tracker.

searchTags

The searchTags attribute is an array of HTML tag names that may comprise the outermost tag of the video player. In many cases, this will be "VIDEO", but it can be any tag that your video player embed uses as its root.

verify

The verify attribute is a function accepting a DOM node and returning a boolean indicating whether it is the root of a video embed of the type with which the strategy is concerned.

subscribe

The subscribe attribute is a function accpting a DOM node that is responsible for initializing event listening logic for the video rooted at that node. Typically, this function will instantiate a JavaScript object encapsulating the video player and register event listeners for play and pause events. The handler responding to play events should collect the necessary metadata and pass it to PARSELY.video.trackPlay along with the video's unique identifying string. The handler responding to pause events should call PARSELY.video.trackPause for the video's ID.

Immediately on load and periodically thereafter, the Parse.ly tracker iterates over all DOM nodes of the types specified in searchTags and calls verify on each of them in turn. The nodes for which verify returned true are passed to successive calls to subscribe.

subcribe can return false in case of an error in the subscription process. If false is returned, subscribe will be called on the failed DOM node on the next retry (retries happen every five seconds).

Disabling Automatic Video Discovery

In some cases, you may want more granular control over the discovery of tracked videos than the automatic tracking interface provides. In these cases, you can set PARSELY.video.autotrack = false to disable the automatic discovery of video embeds. For example:

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

When automatic discovery is disabled, you can use the v1 video tracking interface to track your videos.

Upgrading from v1

Without the proper preparation, an upgrade from the "manual" video tracker to the automatic tracker can cause content to be duplicated in the Parse.ly dashboard. In the manual tracker, the ID of a given video is specified via calls to trackPlay and trackPause. The integrator can choose the ID - it can be anything, as long as it's unique per video. The automatic tracker, on the other hand, chooses these IDs automatically based on information provided by the video platform API being used. Since these IDs are used to uniquely identify videos in the Parse.ly dashboard, a mismatch between IDs assigned by the manual and automatic trackers can lead to duplicated videos.

To avoid this, you can make sure that your manual tracker integration uses the same video ID that the automatic one will choose. The way to find this ID differs per video platform, and the JavaScript property used to access it is noted above in the platform-specific listing. Using these properties to set video ID in your manual integration will make your upgrade to the automatic tracker seamless.

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

PARSELY.video.addStrategy(strategy)

Register a custom video tracking strategy with the Parse.ly tracker.

Parameter Type Required Description
strategy object yes The strategy to register. Should be an object with keys platform, searchTags, verify, and subscribe as described above.
Do you have an urgent support question?