Display Related Videos

This guide explains the features and options of the Related Videos overlay, through which viewers can find and watch additional videos. Here is a live example:

 
This document applies to users of JW Player Premium and Enterprise. Don't have Premium? Upgrade Now.

Configuration Options

The related videos functionality is activated by setting the related configuration block. Inside this block, the following options can be set. The file option is required, all others are optional:

file ( required )
Location of an RSS file with related videos, e.g. http://example.com/related.xml. See below for more info.
onclick
This determines what to do when the user clicks a thumbnail: jump to the page URL of the related video (link) or play the related video inline (play). The default is link. Note you need to use the MEDIAID replacement functionality if you want to display related videos of related videos (see below)
oncomplete
Whether to display the related videos screen when the video is completed. When set to false, the screen does not automatically pop up. It is true by default.
heading
Single line heading displayed above the grid with related videos. Generally contains a short call-to-action. The default is Related Videos. This heading also displays as a tooltip on the related icon.
dimensions
This sets the width and height of each thumbnail in pixels. The default is 140x80. Set this to a different value to make the thumbnails larger (e.g. 240x160) or smaller (e.g. 120x70). Note the overlay always renders a fixed 10px spacing between the thumbs.

Example Setup

Here is the setup of above example, setting the related videos file property and the link action. See the MP4 Video Embed for more info.

  jwplayer("container").setup({
    file: "/assets/tos.mp4",
    related: {
      file: "/assets/tos-related.xml",,
      onclick: "link"
    }
  });
</script>

Again, note that Related Videos is only available in the Premium and Ads editions of JW Player.

The RSS Feed

The RSS feed used for loading related videos is the same as the one used to load playlists. The <link> element sets the page URL to jump to when clicking a related videos thumbnail:

<rss version="2.0" xmlns:media="http://search.yahoo.com/mrss/">
  <channel>
    <item>
      <title>Big Buck Bunny</title>
      <link>http://example.com/watch/28839</link>
      <media:thumbnail url="http://example.com/thumbs/28839.jpg"/>
      <media:content url="http://example.com/videos/28839.mp4" type="video/mp4" />
    </item>

    <item>
      <title>Elephant's Dream</title>
      <link>http://example.com/watch/8791</link>
      <media:thumbnail url="http://example.com/thumbs/8791.jpg"/>
      <media:content url="http://example.com/videos/8791.mp4" type="video/mp4" />
    </item>
  </channel>
</rss>

Note that RSS feeds are subject to cross-domain security restrictions and therefore won't automatically load from another domain than the player. See Crossdomain File Loading for more info.

If an item in the RSS feed does not contain the title and media:thumbnail elements, it is not displayed in the related videos overlay. If the onclick option is set to link, the link element is also required. If onclick is set to play, the media:content element is also required. If no items are found in the RSS feed, a No related videos found text is displayed instead of the grid of thumbnails.

Media ID Replacement

The Media ID Replacement feature allows JW Player to dynamically construct URLs to related videos RSS feeds. This is required in two situations:

  1. If you have a playlist with multiple videos and want to display related videos for each item.
  2. If you set the onclick option to play and want to display related videos of related videos.

Here is an example embed using a simple playlist with 2 items:

  jwplayer("container").setup({
    playlist: [{ 
       file: "/videos/12345.mp4",
       mediaid: "12345"
    },{
       file: "/videos/67890.mp4",
       mediaid: "67890"
    }],
    related: {
      file: "/related/MEDIAID.xml"
   }
 });

For the first item in the playlist, JW Player will request the RSS feed /related/12345.xml. For the second item, JW Player will request the feed /related/67890.xml.

If the items in these RSS feeds also contain a mediaid (using the guid element), JW Player is able to in turn construct a related videos URL and display related videos of these related videos:

<rss version="2.0" xmlns:media="http://search.yahoo.com/mrss/">
  <channel>
    <item>
      <title>Big Buck Bunny</title>
      <guid isPermalink="false">28839</guid>
      <media:thumbnail url="http://example.com/thumbs/28839.jpg"/>
      <media:content url="http://example.com/videos/28839.mp4" type="video/mp4" />
    </item>

    <item>
      <title>Elephant's Dream</title>
      <guid isPermalink="false">8791</guid>
      <media:thumbnail url="http://example.com/thumbs/8791.jpg"/>
      <media:content url="http://example.com/videos/8791.mp4" type="video/mp4" />
    </item>
  </channel>
</rss>

See the Media Formats reference for more info on the various elements a feed can contain.

Please sign in to leave your feedback for this article.

Still don't have JW Player? Get It Here