Order Now AdSolution Sign Up | Login » Bits on the Run Sign Up | Login »

AddOns

Related Videos Reference Guide

Purpose

The purpose of this guide is to give you a feature overview of the Related plugin for JW Player.

Introduction

The Related plugin for the JW Player presents a screen with related videos to your viewers. This screen is shown when a video is completed or when a viewer presses the related button. Upon clicking a related video, the viewer is either redirected to the page with that video, or the related video is loaded in the player.

Related Example Player

The list of related videos is loaded using an mRSS feed. The plugin automatically renders as many thumbs as fit the screen. Buttons for re-playing the video and for closing the overlay are shown in the top corners.

The plugin works in both Flash and HTML5, including touch devices like the iPad/iPhone and Android. When using a playlist, every entry can have its own related videos.

Configuration Options

The Related plugin supports the following configuration options:

file ( undefined )
Location of the mRSS file with related videos, e.g. http://example.com/related.xml. See below section for more info.
onclick ( link )
What to do when the user clicks a thumb: play the related video in the player (play) or jump to the play page of the related video (link).
oncomplete ( true )
Whether to display the related videos screen when the video is completed. When set false, the screen does not automatically pop up.
usedock ( true )
Whether to add a button to the player to pop up the related videos screen manually. When set false, this button is omitted.
heading ( Watch related videos )
Single line heading displayed above the grid with related videos. Generally contains a short call-to-action.
dimensions ( 140x80 )
The width and height of each thumbnail in pixels. Set this to a different value to make the thumbnails larger (e.g. 160x90) or smaller (e.g. 120x70). Note the plugin always renders a fixed 10px spacing between the thumbs.

Example

Here is a basic example of the plugin, setting just a related.file:

<div id='player'>Get Flash to see the video</div>
<script type="text/javascript>
  jwplayer('player').setup({
    file: '/assets/bbb.mp4',
    flashplayer: '/assets/player.swf',
    plugins: {
      'related-1': {
        file: '/assets/bbb-related.xml'
      }
    }
  });
</script>

This example uses the - preferred - JW Embedder method. Please see our Supported Embed Methods guide for other options like SWFObject.

The mRSS Feed

The mRSS feed used for loading the related videos should be identical to those loading a JW Player playlist. Here's an example feed with 2 related videos:

<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:content url="http://example.com/video/28839.mp4"/>
      <media:thumbnail url="http://example.com/thumbs/28839.jpg"/>
    </item>

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

Note the following properties are required for every item in the feed. Items that do not contain these properties are ignored:

If the mRSS feed has 0 valid entries, or if the mRSS feed fails loading or parsing:

Related Related Videos

For every item in the mRSS feed, you can include a <jwplayer:related.file> property. When using the onclick=play option, this will then define the related videos for your related videos. With this trick, you can create an endless carrousel of related videos for users that can't get enough watching your videos.

If no per-item related files are loaded, the global related videos file will remain active.

Device Support

On touch devices (iPhone, iPad, Android), the related plugin fully functions, with one exception: the dock button is not available when the video is playing. This because no custom controls can be shown when a video plays in fullscreen.

Realted plugin on iPhone

Before playback starts and after it completes, the player is displayed inline in the page and the related videos screen is available.

Playlist Support

Related videos can be assigned to one or more videos in a playlist. The functionality is available for both inline and mRSS playlists. Instead of setting the related file URL in the plugin configuration, they are set in the playlist.

Since the mRSS playlist format defines no elements for linking to related files, it should be set using the JWPlayer XML namespace. In practice, the namespace is enabled by:

Example

The config solely needs a reference to the plugin:

<div id='player'>Get Flash to see the video</div>
<script type="text/javascript>
  jwplayer('player').setup({
    flashplayer: '/assets/player.swf',
    playlistfile: '/assets/playlist.xml',
    plugins: {
      'related-1': {}
    }
  });
</script>

In the playlist.xml, the jwplayer:related.file element defines the related videos feed for each entry:

<rss version="2.0" xmlns:jwplayer="http://developer.longtailvideo.com/">
  <channel>
    <item>
      <title>My first video</title>
      <description>This one starts the playlist.</description>
      <jwplayer:file>video.mp4</jwplayer:file>
      <jwplayer:related.file>video-related.xml</jwplayer:related.file>
    </item>

    <item>
      <title>My second video</title>
      <description>This one concludes it all.</description>
      <jwplayer:file>video-2.mp4</jwplayer:file>
      <jwplayer:related.file>video-2-related.xml</jwplayer:related.file>
    </item>
  </channel>
</rss>

Note the xmlns:jwplayer at the top! It is needed to validate the jwplayer:related.file elements.

Changelog

Version 1.0

Version 1.1