Display Related Videos

You will be automatically redirected in 10 seconds.

This guide explains the features and options of the Related Videos overlay, through which viewers can find and watch additional videos. As of JW Player 7.2.0, the related plugin includes additional functionality, such as the ability to autoplay related videos with a timer. Here is an example of this in action:

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 )
  The URL of an RSS or JSON file with related videos, e.g. http://example.com/related.json
• onclick
  Dictates the behavior when a related thumbnail is clicked. Can be set to:
  • link(default) - Will redirect to another web page. (Based on the link field)
  • play - Will play a related video file inline. (Based on the file field)
• oncomplete
  Configures the behavior of the related plugin when a single video, or playlist, completes.
  • show(default) - Displays a list of related videos instead of a replay button. Setting true will map to this configuration option for legacy purposes.
  • hide - Displays a replay button with the related overlay collapsed. Setting false will map to this configuration option for legacy purposes.
  • autoplay - Will automatically begin the next related video after 10 seconds. If MEDIAID replacement is not used, autoplay will cycle through the feed much like a playlist.
    Note: Setting autoplay will override onclick behavior to play.
• autoplaytimer
  The number of seconds to wait before playing the next related video in your content list. Defaults to 10, or set to 0 to have your next related content to play immediately.
• autoplaymessage
  A custom message that appears during autoplay. Uses xx as a replacement for the countdown timer.
  A macro can also be used to replace aspects of the message, based on the next title included in the related feed with __title__.
  So for example, using the following configuration:

   

  __title__ will play in xx seconds! 
  

  Will display as:
  Awesome Movie Trailer will play in 10 seconds!
• heading
  Single line heading displayed above the grid with related videos when clicked and as a tooltip when the related icon is moused over. The default value is Related Videos.

Related API

Similar to our new Sharing refactor, our Related Plugin has received a brand new API. Similar to sharing, the related api examples below will assume that the following code is implemented:

var relatedPlugin = jwplayer().getPlugin('related');

As with all JW Player API calls, it is best practice to wait for on('ready'). This ensures that the player is completely set up and prepared to send/receive via its API.

Setters

• relatedPlugin.open();
  Opens the related plugin overlay. This will pause content if it is currently playing.
• relatedPlugin.close();
  Closes the related plugin overlay. This will resume content.

Listeners

• relatedPlugin.on('open');
  Triggers when the related plugin is opened.
  Returns:
  • method - The method used to open the plugin. (api, complete, or click)
  • url - URL of the feed that was loaded into the player.
  • items - An array of all objects that have been loaded into the related plugin.
• relatedPlugin.on('close');
  Triggers when the related plugin is closed.
  Returns:
  • method - The method used to close the plugin. (api or click)
• relatedPlugin.on('play');
  Triggers when a user selects an object in a related feed.
  Returns:
  • item - Metadata for the chosen item specified in the feed.
  • auto - Returns true if started via autoplay; false if manually started.
  • position - Ordinal position of the related video that has been chosen.

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.

var playerInstance = jwplayer("container"); 
playerInstance.setup({
file: "/assets/tos.mp4",
related: {
file: "/assets/tos-related.json",
onclick: "link",
oncomplete: 'autoplay',
autoplaytimer: 10
}
});

Feeds

RSS

The RSS feed used for loading related videos is the same as the one used to load playlists. The

<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" />
<guid isPermalink="false">28839</guid>
</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" />
<guid isPermalink="false">8791</guid>
</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 without providing server access. 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.

JSON

As of JW Player 7.2.0, support for JSON feeds has also been added. Formatting for JSON feeds functions in the very same way as our standard JW Player playlists. The same information from our above RSS feeds would be formatted and used in a JSON file as follows:

[ 
{
"title": "Big Buck Bunny",
"link": "http://example.com/watch/28839",
"image": "http://example.com/thumbs/28839.jpg",
"file": "http://example.com/videos/28839.mp4",
"mediaid": "28839"
},{
"title": "Elephant's Dream",
"link": "http://example.com/watch/8791",
"image": "http://example.com/thumbs/8791.jpg",
"file": "http://example.com/videos/8791.mp4",
"mediaid": "8791"
}
]

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:

If you have a playlist with multiple videos and want to display related videos for each item.

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:

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

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

If the items in these JSON 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:

[
{
"title": "Big Buck Bunny",
"link": "http://example.com/watch/28839",
"image": "http://example.com/thumbs/28839.jpg",
"file": "http://example.com/videos/28839.mp4"
"mediaid": "28839"
},{
"title": "Elephant's Dream",
"link": "http://example.com/watch/8791",
"image": "http://example.com/thumbs/8791.jpg",
"file": "http://example.com/8791.mp4",
"mediaid": "8791"
}
]