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

Supported Player Embed Methods

Purpose

This guide provides relevent background information on embedding the JW Player.

Introduction

Like every other Flash object, the JW Player has to be embedded into the HTML of a webpage using specific embed codes. Overall, three methods for embedding the JW Player:

  • Using the JW Player's own JavaScript Embedder (jwplayer.js), Recommended
  • Using a generic JavaScript embedder (like SWFObject).
  • Using a HTML tag (like <object> or  <embed>)

For embedding the JW Player for Flash, we recommend using SWFObject, since it works in all browsers and many examples exist on the web to get you up and running quickly.  If you want the new HTML5 features of the JW Player, or if you want to leverage the new and improved JavaScript API, you'll want to use the JW Embedder.  Detailed instructions can be found below.

CONTENTS

Upload

First, a primer on uploading. This may sound obvious, but for the JW Player to work on your website, you must upload the player.swf file from the download to your webserver. To use the JW Player Embedder, which enables HTML5 mode and the JavaScript API, upload jwplayer.js.

Your media files and playlists can be hosted at any domain. Do note that Crossdomain Security Restrictions apply when loading these files from a different domain. In short, playing media files works, but loading playlists across domains will not work by default. Resolve this issue by hosting a crossdomain.xml file.

Note: We recommend putting everything in a folder called “jwplayer” at the root of your site. This enables the "quick embed" method of setting up the player.

JW Embedder

New in version 5.3, the JW Player features its own embedding method. While the previous embed methods can still be used, the built-in embed method has a couple of useful features:

  • Seamless failover between the Flash and HTML5 modes.
  • Automatic integration with the JavaScript API.

For more information on using the JW Embedder, see the JW Embedder Reference Guide.

SWFObject

There’s a wide array of good, open source libraries available for embedding Flash. SWFObject is the most widely used one. It has excellent documentation.

Before embedding any players on the page, make sure to include the swfobject.js script in the <head> of your HTML. You can download the script and host it yourself, or leverage the copy provided by Google:

<script type="text/javascript"
  src="http://ajax.googleapis.com/ajax/libs/swfobject/2.2/swfobject.js">
</script>

With the library set up, you can start embedding players. Here’s an example:

<p id="container1">Please install the Flash Plugin</p>

<script type="text/javascript">
  var flashvars = { file:'/data/bbb.mp4',autostart:'true' };
  var params = { allowfullscreen:'true', allowscriptaccess:'always' };
  var attributes = { id:'player1', name:'player1' };

  swfobject.embedSWF('player.swf','container1','480','270','9.0.115','false',
    flashvars, params, attributes);
</script>

It’s a fairly sizeable chunk of code that contains the embed container, flashvars, params, attributes and instantiation. Let’s walk through them one by one:

  • The container is the HTML element where the player will be placed into. It should be a block-level element, like a <p> or <div>. If a user has a sufficient version of Flash, the text inside the container is removed and replaced by the videoplayer. Otherwise, the contents of the container will remain visible.

  • The flashvars object lists your player Configuration Options. One option that should always be there is file, which points to the file to play. You can insert as many options as you want.

  • The params object includes the Flash plugin parameters. The two parameters in the example (our recommendation) enable both the fullscreen and JavaScript functionality of Flash.

  • The attributes object include the HTML attributes of the player. We recommend always (and only) setting an id and name, to the same value. This will be the id of the player instance if you use its Player API.

  • The instantiation is where all things come together and the actual player embedding takes place. These are all parameters of the SWFObject call:

    • The URL of the player.swf, relative to the page URL.
    • The ID of the container you want to embed the player into.
    • The width of the player, in pixels. Note the JW Player automatically stretches itself to fit.
    • The height of the player, in pixels. Note the JW Player automatically stretches itself to fit.
    • The required version of Flash. We highly recommend setting 9.0.115. This is the first version that supports MP4 and is currently installed on over 98.6% of all computers1. The only feature for which you might restricted to 10.0.0 is RTMP dynamic streaming.
    • The location of a Flash auto-upgrade script. We recommend to not use it. People that do not have Flash 9.0.115 either do not want or are not able (no admin rights) to upgrade.
    • Next, the flashvars, params and attributes are passed, in that order.

It is no problem to embed multiple players on a page. However, make sure to give each player instance a different container id and a different attributess id and name.

Embed Tag

In cases where a JavaScript embed method is not possible (e.g. if your CMS does not allow including JavaScripts), the player can be embedded using plain HTML. There are various combinations of tags for embedding a SWF player:

  • A single <embed> tag (for IE + other browsers).
  • An <object> tag with nested <embed> tag (the first one for IE, the second for other browsers).
  • An <object> tag with nested <object> tag (the first one for IE, the second for other browsers).

We recommend using the single <embed> tag. This works in all current-day browsers (including IE6) and provides the shortest codes. Here is an example embed code that does exactly the same as the SWFObject example above:

<embed
  flashvars="file=/data/bbb.mp4&autostart=true"
  allowfullscreen="true"
  allowscripaccess="always"
  id="player1"
  name="player1"
  src="player.swf"
  width="480"
  height="270"
/>

As you can see, most of the data of the SWFObject embed is also in here:

  • The container is now the embed tag itself. The fallback text cannot be used anymore.
  • The flashvars are merged into a single string, and loaded as an attribute. You should always concatenate the flashvars using so-called querystring parameter encoding: flashvar1=value1&flashvar2=value2&....
  • The params each are individual attributes of the embed tag.
  • The attributes also are individual attributes of the embed tag.
  • The instantiation options (source, width, height) are attributes of the embed tag.

Note:  The Flash version reference is not in the embed tag: this is one of the drawbacks of this method: it’s not possible to detect Flash and selectively hide it, e.g. if the flash version is not sufficient or if the device (iPad ...) doesn’t support Flash.