Skip to content

Video: Metadata Configuration

Version 2.x information

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 nameInclusionDescription
titlerequiredString the title of the video
image_urlrequiredString URL pointing to a full-sized (i.e. not thumbnail) image representing the video
durationrecommendedInteger the duration of the video in milliseconds
pub_date_tmsprecommendedInteger the date the video was published specified in milliseconds since the Unix epoch
sectionrecommendedString the section a video belongs to
authorsoptionalArray the author(s) of the video (an author need not correspond to a person but can be an entity like a studio)
tagsoptionalArray 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).

Version 1.x information

Information about providing video metadata for legacy versions of Parse.ly’s video tracking code can be found on the version 1.x page.

Last updated: December 02, 2022

Last updated: December 02, 2022