Video Tracking

Parse.ly video tracking will detect play, pause, and stop events from embedded video platforms on your site. It will also collect your customized metadata.

To integrate video tracking for your video player, please follow the instructions below. If you don’t see your video player listed, then we have a method for custom integrations as well.

Once integrated, the tracker automatically sends videostart and vheartbeat events on your behalf. You’ll be able to confirm your site is firing video views via the process outlined here.

Supported Players:

Brightcove

Because Brightcove embeds that use <iframe> are not supported by the Brightcove JavaScript API, the Parse.ly tracker is only able to automatically track Brightcove embeds that use <video>. However, the Parse.ly Brightcove plugin can be used to track both <iframe> video embeds and players on Google AMP pages.

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.

Note: Make sure the ID of the <video> element starts with a letter, not a digit.

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

If you want to specify an author or section for a JWPlayer video, set custom parameters with those names in your JWPlayer video library.

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.

video.js

Note to Brightcove users: these instructions are for users of plain video.js only. Use the instructions for Brightcove integrations instead.

Any <video> element that includes a class vjs-tech or video-js and does not include the Brightcove-specific data-video-id or data-playlist-id attributes 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/7.6.5/parse-ly-video-tracking/.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.

Note: When creating the ID of the <video> element, be sure that it is unique from other players on page and that it starts with a letter, not a digit.

Vimeo

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

<script src="https://player.vimeo.com/api/player.js"></script>

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.

Wistia

Embedded playlists must use the “API” embed type.

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.

If your page makes use of window.onYouTubeIframeAPIReady, you should include logic similar to the following in that function to avoid overriding the Parse.ly tracker’s usage thereof:

<script type="text/javascript">
  var existingCallback = window.onYouTubeIframeAPIReady;
  window.onYouTubeIframeAPIReady = function() {
    // do page-specific work
    if (typeof existingCallback === "function") {
      existingCallback();
    }
  };
</script>

Custom Integration: PARSELY.video.onPlay

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:

var platform = "myVideoPlatform";
var strategy = {
    platform: platform,
    searchTags: ["DIV"],
    verify: function(elem) {
        return (' ' + elem.className + ' ').indexOf(" my_video ") !== -1;
    },
    subscribe: function(elem) {
        var playerApi = myVideoJsApi(elem);
        playerApi.on("play", function(playedVideoMetadata) {
            // this hypothetical player API calls its event handlers with
            // the metadata of the video as the only argument. with a different
            // player API, you might need to perform some more metadata lookups,
            // possibly from disparate data sources.
            PARSELY.video.onPlay(playerApi, playedVideoMetadata.id, {
                duration: playedVideoMetadata.duration,
                image_url: playedVideoMetadata.image_url,
                pub_date_tmsp: playedVideoMetadata.pub_date_tmsp,
                title: playedVideoMetadata.title,
                author: playedVideoMetadata.author,
                tags: playedVideoMetadata.tags,
                video_platform: platform
            });
        });
        playerApi.on("pause", function(pausedVideoMetadata) {
            PARSELY.video.onPause(playerApi, pausedVideoMetadata.id);
        });
        console.log("Subscribed to custom embed with ID '" + elem.id + "'");
    }
};
PARSELY = window.PARSELY || {};
PARSELY.onload = function() {
    PARSELY.video.addStrategy(strategy);
};

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

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

Customization:

• Specifying Which Players Should be Tracked
• Detecting Dynamically Loaded Video Players
• Tracking Custom or Unsupported Video Players
• Tracking Videos That Play in iframes

Specifying Which Players Should be Tracked

By default, the Parse.ly tracker will automatically detect and track any instance of the supported video players listed above. However, in some cases you may wish to limit automatic tracking to a specific video player or subset of video players. To do this, simply specify an array of strategies that should be tracked like this:

<script>
  window.PARSELY = window.PARSELY || {
    // ... other Parsely configuration options
    video: {
      // ... other Parsely video configuration options
      allowedStrategies: [
        // edit array to only include desired video players
        "brightcove",
        "jwplayer",
        "kaltura",
        "mediaelementjs",
        "theplatform",
        "videojs",
        "vimeo",
        "wistia",
        "youtube"
      ]
    }
    // ... other Parsely configuration options
  };
</script>

If defined, the PARSELY.video.allowedStrategies array will limit automatic detection and tracking to only the specified strategies, which each correspond to a specific video player. Elements in the array should be one of these strings: brightcove, jwplayer, kaltura, mediaelementjs, theplatform, videojs, vimeo, wistia, youtube.

Note: Because automatic detection happens as soon as the Parse.ly tracker is loaded, this (and other configuration options) must be set before loading the tracker.

Detecting Dynamically Loaded Video Players

By default, the Parse.ly tracker will automatically discover any supported video players that are present on the page at the time it loads. If your site is a Single Page Application (SPA), or lazily initializes videos in response to scroll, you can still automatically track those players. You just need to call PARSELY.video.detectVideos() to re-run automatic player detection any time you add a new player instance to the page. This is not necessary for new video assets dynamically loaded into an existing player instance, as they will be tracked automatically.

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>
  window.PARSELY = window.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.

Video Tracking JavaScript API

PARSELY.video.detectVideos()

Tell the Parse.ly tracker to scan the page for any video player instances that are trackable. This is called by default when loading the tracker or calling PARSELY.video.addStrategy().

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.

PARSELY.video.addStrategy(strategy)

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

Tracking Videos That Play in iFrames

Some sites load video players in iframes, either on the page or in a popup modal windows. To track such videos, the iframed page must also include a version of the Parse.ly tracker, with some additional customization. For example purposes, let’s consider a post page at https://example-site.com/postid that contains an iframe, which loads https://example-site.com/parse-ly-video-tracking/id, a page that only contains a video player.

The videoid “child” page needs the tracker to be able to capture video events. But we don’t want to track pageviews for it, because its only purpose is to contain the video, and we’re already tracking views for the page on which it’s embedded. So, for such pages, we need to:

1. Include the basic tracking code (to capture video events)
2. Disable on-load pageview tracking (to prevent pageview events)
3. Pass document.referrer as the urlOverride parameter of the PARSELY.video.trackPlay() function. (to make sure video events are associated with https://example-site.com/postid, the real page)

Put all three together, and this is what the tracking code for https://example-site.com/parse-ly-video-tracking/id should look like:

<script>
  window.PARSELY = window.PARSELY || {
   autotrack: false,
   config: {
     heartbeat_should_honor_autotrack: true
   },
   video: {
     onPlay: function(playerApi, videoId, metadata) {
      PARSELY.video.trackPlay(videoId, metadata, document.referrer);
     }
   }
  };
</script>
<!-- START Parse.ly Include -->
<!-- ...insert the parse.ly tracker code here... -->
<!-- END Parse.ly Include -->

Why do some video players require additional <script> tags?

For the Parse.ly tracker to interact with a video player, it needs access to the player’s API. Some players include an API whenever they’re embedded or used on a page, but others, such as YouTube and Vimeo, require sites to load the API separately, via a <script> tag. Because these elements must be added to the site or page markup itself, the decision to add them is best left to site owners. This setup is comparable to any other “automatic” video tracker on the market.

The Parse.ly tracker is designed to leave as little trace on your site as possible. The only change it makes to the page is adding an id to video elements that don’t already have one.

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

You’ll also need to contact your account manager to complete the upgrade process.