Custom video tracking

Parse.ly automatically detects and tracks supported video players. If your site uses a custom or unsupported video player, implement tracking using a custom strategy. The custom strategy is a JavaScript object that tells the Parse.ly tracker how to detect and interact with your player.

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);
};

Before you begin

1. Complete installation of the Parse.ly Dashboard.
2. Review the video tracking user guide, installation guide, and API reference.

How it works

The Parse.ly tracker scans the page for video players on load and periodically thereafter. It checks DOM nodes matching your searchTags, calls verify on each to identify your player, then calls subscribe to initialize tracking. If subscribe returns false, it retries every five seconds.

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

Strategy object keys

platform

The human-readable name of the player provider (for example, brightcove or youtube). Don’t use a name that overlaps with existing Parse.ly strategy names.

searchTags

An array of HTML tag names that may contain your video player. In many cases this is ["VIDEO"], but it can be any tag your embed uses as its root element.

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