Title: Video: Version 1.x Tracking
Author: staff
Published: August 1, 2022
Last modified: July 21, 2026

---

 1. [Installation resources](https://docs.parse.ly/installation-resources/)
 2. [Add-on Features](https://docs.parse.ly/installation-resources/add-on-features/)
 3. [Integrating video tracking](https://docs.parse.ly/installation-resources/add-on-features/integrating-video-tracking/)
 4. Video: Version 1.x Tracking

#  Video: Version 1.x Tracking

#### **Legacy documentation**

This documentation refers to an earlier version of the Parse.ly tracker (versions
below 1.0.0) that requires manual implementation of player events. Newer customers
should start with the [current video tracking documentation](https://docs.parse.ly/parse-ly-video-tracking/-tracking-v2/).
[Upgrade instructions](https://docs.parse.ly/installation-resources/add-on-features/integrating-video-tracking/video-tracking-v1?output_format=md#upgrading-from-v1)
are available at the end of this article.

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 [Parse.ly Support](https://support.parse.ly/hc/en-us).

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:

    ```lang-plain
    < script src="http://content.jwplatform.com/libraries/2SJ3KAcS.js"></script>
    <div id="embed_container">Loading the player...</div>
    <script type="text/javascript">
      var player = jwplayer("embed_container");
      player.setup({
        file: "http://content.jwplatform.com/parse-ly-video-tracking/s/xxxxxxxx.mp4",
        image: "http://content.jwplatform.com/thumbs/xxxxxxxx.jpg",
        mediaid: "myvideoid12345",
        width: 640,
        height: 360,
        title: 'Basic Video Embed',
        description: 'A video with a basic title and description!'
      });
      player.on('ready', function() {
        player.on("play", function(){
          var playlistItem = player.getPlaylistItem(player.getPlaylistIndex());
          PARSELY.video.trackPlay(
            playlistItem.mediaid,
            {
              // required
              title: playlistItem.title,
              // recommended
              image_url: playlistItem.image,
              section: "My Video's Section",
              pub_date_tmsp: 1474393968763,  // milliseconds since unix epoch
              // optional
              tags: ["mytag1", "mytag2"],
              authors: ["My Video's Author"]
            });
        });
        player.on("pause", function(){
          var playlistItem = player.getPlaylistItem(player.getPlaylistIndex());
          PARSELY.video.trackPause(playlistItem.mediaid);
        });
        player.on("stop", function(){
          var playlistItem = player.getPlaylistItem(player.getPlaylistIndex());
          PARSELY.video.trackPause(playlistItem.mediaid);
        });
      });
    </script>
    ```

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

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 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 | 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 Site ID (apikey) and video. |

## Tracking video within iframes

If you’re loading embedded videos via `iframe`, you’ll need to load the Parse.ly
tracker within the `iframe` in addition to the parent page. In doing so, you should
disable automatic pageview tracking within the `iframe`, as shown below:

    ```lang-html
    <script>
      window.PARSELY = window.PARSELY || {
        autotrack: false
      };
    </script>
    <!-- START Parse.ly Include -->
    <!-- ...insert the parse.ly tracker code here... -->
    <!-- END Parse.ly Include -->
    ```

Then, bind `trackPlay` and `trackPause` to the relevant events in the iframe (along
with the appropriate metadata). Finally, pass a `urlOverride` param with the value
of the parent page URL in order to associate it with plays of the `iframe` video.

Note that Parse.ly video tracker versions >=1.0.0 can detect and track `iframe` 
video from a number of players automatically. Consult [the documentation](https://docs.parse.ly/parse-ly-video-tracking/-tracking-v2/)
on those tracker versions for details.

## Upgrading video tracking

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.

| Platform | ID identification function | 
| Brightcove | `videojs().el_.attributes["data-video-id"].value` | 
| JWPlayer | `jwplayer().getPlaylistItem().mediaid` | 
| mediaelement.js | `MediaElement.currentSrc` | 
| video.js | `videojs().currentSrc()` | 
| Vimeo | `Vimeo.Player.getVideoId()` | 
| Wistia | `Wistia.api.data.hashedId` | 
| YouTube | `YT.Player.getVideoData().video_id` |

Contact [Parse.ly Support](https://support.parse.ly/hc/en-us) to complete the upgrade
process.

Last updated: July 21, 2026