Video Tracking
#Looking for old video tracking documentation?
This documentation refers to the latest versions of Parse.ly's automatic video tracker (versions greater than 1.x). If you're using an earlier version of the tracker, you'll want either the legacy video tracking documentation or information about upgrading.
If you're unsure of your tracker version, contact support@parsely.com
The newest version of Parse.ly's video tracker, described below, automatically detects play
, pause
, and stop
events from most commonly used video platforms
without requiring integrators to write any custom JavaScript. It will also detect metadata (which can be customized if needed).
However, depending on the platform and site, integration may require adding additional script tags to your site templates or modifying existing video markup (Why?). Once integrated, 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.
Note that video content must be embedded in order to be trackable.
Parse.ly's video tracking is a paid add-on feature. If you'd like to enable video tracking on your site, please contact value@parsely.com.
#Supported Players:
#Customization:
- Specifying Which Players Should be Tracked
- Customizing Video Metadata
- Detecting Dynamically Loaded Video Players
- Tracking Custom or Unsupported Video Players
- Tracking Videos That Play in iframes
#Platform Details
#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.
ID field: videojs().el_.attributes["data-video-id"].value
#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.
ID field: jwplayer().getPlaylistItem().mediaid
#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. 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/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.
Note: Make sure the ID of the <video>
element starts with a letter, not a digit.
ID field: videojs().currentSrc()
#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.
ID field: Vimeo.Player.getVideoId()
#Wistia
Embedded playlists must use the "API" embed type.
ID field: Wistia.api.data.hashedId
#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>
ID field: YT.Player.getVideoData().video_id
#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.
#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>
window.PARSELY = window.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
).
#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.
#Tracking Custom or Unsupported 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:
Loading code...
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).
#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.
#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.
You'll also need to contact your account manager to complete the upgrade process.
#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.
Parameter | Type | Required | Description |
---|---|---|---|
videoId | string | yes | An identifier indicating the video being played. Should be unique per Parse.ly Site ID (apikey) 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 Site ID (apikey) 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 Site ID (apikey) 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. |
#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/videoid
, 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:
- Include the basic tracking code (to capture video events)
- Disable on-load pageview tracking (to prevent pageview events)
- Pass
document.referrer
as theurlOverride
parameter of thePARSELY.video.trackPlay()
function. (to make sure video events are associated withhttps://example-site.com/postid
, the real page)
Put all three together, and this is what the tracking code for https://example-site.com/videoid
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.