Please read: SWFObject 2.0 has been released and is now hosted on github: https://github.com/swfobject/swfobject. Please consider the information found here obsolete.

If you are curious what Geoff is up to these days, you can follow him on Twitter.

SWFObject is a small Javascript file used for embedding Adobe Flash content. The script can detect the Flash plug-in in all major web browsers (on Mac and PC) and is designed to make embedding Flash movies as easy as possible. It is also very search engine friendly, degrades gracefully, can be used in valid HTML and XHTML 1.0 documents*, and is forward compatible, so it should work for years to come.

* Pages sent as text/html, not application/xhtml+xml.

Table of Contents

• What’s new in this version?
• How it works
• SWFObject Examples
• Using ExpressInstall with SWFObject
• Download
• Why it’s better than the rest
• FAQ

What’s new in this version?

For a full list of changes, please see my SWFObject 1.5 blog post.

How it works

[For the über nerds, you can view the raw javascript here.]

Using SWFObject is easy. Simply include the swfobject.js Javascript file, then use a small amount of Javascript on your page to embed your Flash movie. Here is an example showing the minimum amount of code needed to embed a Flash movie:

<script type="text/javascript" src="swfobject.js"></script> <div id="flashcontent"> This text is replaced by the Flash movie. </div> <script type="text/javascript"> var so = new SWFObject("movie.swf", "mymovie", "400", "200", "8", "#336699"); so.write("flashcontent"); </script>

Here is a breakdown of what the code does:

<div id="flashcontent">[...]</div>

Prepare an HTML element that will hold our Flash movie. The content placed in the ‘holder’ element will be replaced by the Flash content, so users with the Flash plug-in installed will never see the content inside this element. This feature has the added bonus of letting search engines index your alternate content.

var so = new SWFObject(swf, id, width, height, version, background-color [, quality, xiRedirectUrl, redirectUrl, detectKey]);

Create a new SWFObject and pass in the required arguments:

• swf – The file path and name to your swf file.
• id – The ID of your object or embed tag. The embed tag will also have this value set as it’s name attribute for files that take advantage of swliveconnect.
• width – The width of your Flash movie.
• height – The height of your Flash movie.
• version – The required player version for your Flash content. This can be a string in the format of ‘majorVersion.minorVersion.revision’. An example would be: "6.0.65". Or you can just require the major version, such as "6".
• background-color – This is the hex value of the background color of your Flash movie.

Optional arguments are:

• quality – The quality you wish your Flash movie to play at. If no quality is specified, the default is "high".
• xiRedirectUrl – If you would like to redirect users who complete the ExpressInstall upgrade, you can specify an alternate URL here
• redirectUrl – If you wish to redirect users who don’t have the correct plug-in version, use this parameter and they will be redirected.
• detectKey – This is the url variable name the SWFObject script will look for when bypassing the detection. Default is ‘detectflash’. Example: To bypass the Flash detection and simply write the Flash movie to the page, you could add ?detectflash=false to the url of the document containing the Flash movie.

so.write("flashcontent");

Tell the SWFObject script to write the Flash content to the page (if the correct version of the plug-in is installed on the user’s system) by replacing the content inside the specified HTML element.

The Details

SWFObject works quietly in the background of your HTML document. When developing pages that use SWFObject, you should start with your alternate (non-Flash) content first. Get your pages working without your Flash movies, then add them in later with little Javascript snippets that replace your alternate content with the Flash movies. This ensures that the alternate content will be indexed by search engines, and that users without the Flash plug-in will still see a working HTML page. Whether you provide upgrade instructions or not is up to you. If your alternate content can suffice, there may be no reason at all to tell people they are missing out on Flash content.

SWFObject works in all the current web browsers, including, on PC: IE5/5.5/6, Netscape 7/8, Firefox, Mozilla, and Opera. On Mac: IE5.2, Safari, Firefox, Netscape 6/7, Mozilla, and Opera 7.5+, and should continue to work well into the future.

SWFObject detects Flash player versions in these browsers from version 3 and up, and will allow users to interact with your Flash content without ‘activating’ it first. For more information on this, see this blog post on the Internet Explorer Eolas patent dispute.

SWFObject can detect minor versions and revision versions of the Flash Player as well, simply by passing the string value of the version you want. An example of requiring Flash player v.6.0 r65 (or 6,0,65,0) would be:

var so = new SWFObject("movie.swf", "mymovie", "200", "100", "6.0.65", "#336699");

SWFObject’s built in plug-in detection can be bypassed. If a new browser is ever launched or for some reason the plug-in detection fails on a user’s system, you can include a bypass link that will disable the detection built into SWFObject, and it will always write the Flash content to the page. To use the bypass link, simply link to the page with your Flash content on it, and include a single url variable called ‘detectflash’ and set it to ‘false.’ Here is an example of what that link would look like:

<a href="mypage.html?detectflash=false">Bypass link</a>

SWFObject Examples

The example given above is what you need for the bare bones use of SWFObject, but what if you want to use some of the other parameters the Flash plug-in has to offer? SWFObject makes it very easy to add any extra parameter you may need. The examples below are a number of different methods you may wish to use to embed your Flash content.

A simple example adding a few extra parameters

<script type="text/javascript"> var so = new SWFObject("movie.swf", "mymovie", "400", "100%", "8", "#336699"); so.addParam("quality", "low"); so.addParam("wmode", "transparent"); so.addParam("salign", "t"); so.write("flashcontent"); </script>

Here is a full list of the current parameters and their possible values on adobe.com.

Passing variables into your movies using the “Flashvars” parameter:

Using Flashvars is the easiest way to get data from your HTML into your Flash movie, but you can only pass the data in when your movie first loads. Normally, you would add a parameter called “flashvars” and then for the value, you passing a string of name/value pairs like this: variable1=value1&variable2=value2&variable3=value3 and so on. SWFObject makes this a bit easier by allowing you to add as many variables as you like in a similar manner in which you add additional parameters. Here is an example of passing values into your Flash movie using Flashvars:

<script type="text/javascript"> var so = new SWFObject("movie.swf", "mymovie", "400", "200", "8", "#336699"); so.addVariable("variable1", "value1"); so.addVariable("variable2", "value2"); so.addVariable("variable3", "value3"); so.write("flashcontent"); </script>

Once this is done, all of the variables you pass in will be available immediately inside the Flash movie. Just access them as you would any variable on the _root timeline.

The SWFObject script also comes with an extra function which allows you to pull variable values from the url string. An example is you have a url that looks like this: http://www.example.com/page.html?variable1=value1&variable2=value2. Using the function getQueryParamValue() you can easily pull these values from the url and then pass them into your Flash movie. Here is an example, we’ll assume that the url looks like the above example:

<script type="text/javascript"> var so = new SWFObject("movie.swf", "mymovie", "400", "200", "8", "#336699"); so.addVariable("variable1", getQueryParamValue("variable1")); so.addVariable("variable2", getQueryParamValue("variable2")); so.write("flashcontent"); </script>

The getQueryParamValue() function also supports reading variables from the location.hash, as used sometimes when deep linking into your Flash applications. For an example of how deep linking to your Flash movies using the location.hash variable, check out this demo of Slideshow Pro, which uses the SWFObject embed.

Using Express Install with SWFObject

SWFObject has full support for the Adobe Flash Player Express Install feature. Your users never have to leave your site to upgrade their player.

To use ExpressInstall, you must first upload the expressinstall.swf to your web server. Then, use the useExpressInstall method to specify the path to your expressinstall.swf. If no path is specified, SWFObject will look in the same folder as the current HTML page.

<script type="text/javascript"> var so = new SWFObject("movie.swf", "mymovie", "200", "100", "8", "#336699"); so.useExpressInstall('expressinstall.swf'); so.write("flashcontent"); </script>

If you want to see ExpressInstall in action, you can install Flash player 7 (or 6.0.65) and visit this page.

If you wish to customize the Express Install feature, the source code to the expressinstall.swf is included with SWFObject.

If your Flash movie is in a popup window, or you wish to redirect the user to a different location after they complete the ExpressInstall update, you can use the xiRedirectUrl attribute to redirect the user back to your landing page instead of the actual page with your Flash movie.

<script type="text/javascript"> var so = new SWFObject("movie.swf", "mymovie", "200", "100", "8", "#336699"); so.useExpressInstall('expressinstall.swf'); so.setAttribute('xiRedirectUrl', 'http://www.example.com/upgradefinished.html'); // must be the absolute URL to your site so.write("flashcontent"); </script>

Why it’s is better than the rest

Over the years there have been many methods to detect Flash player versions and embed Flash movies into HTML documents. This section will take a look at each of the most popular methods and point out the problems with each.

1) The default Adobe provided embed

Everyone knows the default Adobe provided Flash embed. It consists of an Object tag with an Embed tag placed inside as a fallback mechanism. This is the most popular Flash embed method and is the default choice when publishing your Flash movie from the Adobe Flash IDE. This is the most compatible way to embed a Flash movie, and will work in the widest range of browsers. Here is a sample of the default Flash embed code:

<object classid="clsid:d27cdb6e-ae6d-11cf-96b8-444553540000" codebase="http://fpdownload.macromedia.com/pub/shockwave/cabs/flash/swflash.cab#version=7,0,0,0" width="550" height="400" id="Untitled-1" align="middle"> <param name="allowScriptAccess" value="sameDomain" /> <param name="movie" value="mymovie.swf" /> <param name="quality" value="high" /> <param name="bgcolor" value="#ffffff" /> <embed src="mymovie.swf" quality="high" bgcolor="#ffffff" width="550" height="400" name="mymovie" align="middle" allowScriptAccess="sameDomain" type="application/x-shockwave-flash" pluginspage="http://www.adobe.com/go/getflashplayer" /> </object>

While this is the most common method of embedding your Flash movies, it does have a few issues.

• There is noplug-in detection. – With no plug-in detection, users may see broken or no content, and if there is no plug-in installed at all, they will either get the ‘ActiveX install’ dialog box on IE —a box many users now fear because of rampant spyware and malware— or the ‘strange puzzle piece’ box in Mozilla based browsers. Neither of these plug-in install systems are very user friendly, and usually don’t explain themselves very well as to what exactly a user is installing.
• With changes from the Eolas patent dispute, users will have to first click on your Flash content to ‘activate’ it before interacting with it. More info here.
• It is not valid HTML or XHTML – There is no such thing as an embed tag in any version of HTML or XHTML. However, since many browsers handle object tags differently (or not at all, or the implementation is too buggy), the embed tag was needed as a fallback mechanism.

2) Object tag only / Flash satay

This method gained popularity after the A List Apart article came out back in 2002. Here are two examples of ‘object tag only’ embedding and Flash satay:

‘Object tag only’

<object classid="clsid:D27CDB6E-AE6D-11cf-96B8-444553540000" codebase="http://download.macromedia.com/pub/shockwave/cabs/flash/swflash.cab#version=6,0,40,0" width="300" height="120"> <param name="movie" value="http://www.macromedia.com/shockwave/download/triggerpages_mmcom/flash.swf"> <param name="quality" value="high"> <param name="bgcolor" value="#FFFFFF"> <!--[if !IE]> <--> <object data="http://www.macromedia.com/shockwave/download/triggerpages_mmcom/flash.swf" width="300" height="120" type="application/x-shockwave-flash"> <param name="quality" value="high"> <param name="bgcolor" value="#FFFFFF"> <param name="pluginurl" value="http://www.adobe.com/go/getflashplayer"> FAIL (the browser should render some flash content, not this). </object> <!--> <![endif]--> </object>

Flash satay

<object type="application/x-shockwave-flash data="c.swf?path=movie.swf" width="400" height="300"> <param name="movie" value="c.swf?path=movie.swf" /> <img src="noflash.gif" width="200" height="100" alt="" /> </object>

• Accessibility issues. – Using Flash Satay, some screen readers (like JAWS) will ignore your Flash content.
• With changes from the Eolas patent dispute, users will have to first click on your Flash content to ‘activate’ it before interacting with it. More info here.
• There is noplug-in detection. – Same as above – With no plug-in detection, users may see broken or no content. When the Flash player encounters a Flash movie embedded in a page, it will try to play it no matter what the version is. So if you have Flash player 6 installed, and encounter a Flash 7 movie, your plug-in will try to play it, possibly causing odd behavior.
• Some methods of Flash satay don’t stream the Flash movie to the player – So this method may require ‘holder’ swf movies that your movie is loaded in to. This makes passing variables from FlashVars parameters a hassle and make it a pain to maintain Flash content as you now have twice as many swf files floating around your web server.
• Older Safari versions ignore param tags – Up until version 2.0 (on Tiger) or 1.3 (on Panther) and possibly 1.2.8 (pre Panther) Safari would completely ignore the param tag. This meant that if you tried to set other options using them, like Flashvars or Align, Salign, etc. Safari would not see those values.

3) Detection: The ‘small flash movie on the index page’ method

This method involves placing a single Flash movie on the index page of your website, and this Flash movie then checks the $version variable in the Flash player and redirects the user either to the Flash content inside the site, or an upgrade page.

Problems with this method include:

• There is noplug-in detection on internal pages. – If a user sends an internal url to another user, that new user bypasses the Flash detection on the index page.
• With changes from the Eolas patent dispute, users will have to first click on your Flash content to ‘activate’ it before interacting with it. More info here.
• It is not valid HTML or XHTML – Again, the embed tag required to place the Flash movies in your HTML documents will not validate.
• Hurts your search engine ranking – Since you are now using your index page as an empty Flash detection page, when people search for you in Google or other search engines, often the description text ends up showing up as “Detecting Flash Player” or even no description at all. This is a huge waste of prime website real estate that should be used to promote your company or products. Often times developers will not include a link to the other content in the site (since the Flash movie contains the links) so the rest of the site won’t be indexed either.

4) The Adobe Flash Player Detection Kit

Adobe has done an excellent job with the new Flash 8 detection kit – but not quite excellent enough. It contains two different ways to detect the Flash plug-in:

1. The classic “small Flash movie on the index page” – (See above)
2. Javascript – Yes, that’s right, Flash now includes a Javascript plug-in detection template. Unfortunately, it’s very not very user friendly at all, mixing Javascript, VBscript, and all your HTML all into one page. This has many of the drawbacks as past Javascript detection and embed techniques, and doesn’t do anything to make your life easier as a Flash/HTML developer. And it doesn’t validate as XHTML or HTML (If you care about that sort of thing).

I’ve put together a more in-depth look at the Adobe detection kit over here.

5) Use raw Javascript to detect and embed your movies

It’s hard to critique this method as it usually varies from site to site. However, most Javascript Flash detection schemes I have come across generally suffer from the same faults:

• Unreliable plug-in Detection – Often the detection only works with current versions of the Flash player, and needs to be manually updated as new versions of the plug-in are released.
• Adds more code to the page – Making it even harder to update or change your content. This method also makes it harder for designers or other people that may be working with your pages to change or add Flash movies.
• An overly complicated solution – Many Flash embedding scripts can grow to large file sizes or be overly complicated. SWFObject is designed to be simple and small.

FAQ

SWFObject now has a forum for people looking for help implementing it. Please send all support requests to the forum, there are plenty of capable people there to help you.

Still having problems? Try reading through the previous SWFObject posts [1, 2, 3] on this blog (especially the comments), as many common questions have been covered there.

Thanks

Toby Boudreaux gave me tons of advice, helped make the code for SWFObject much cleaner and name spaced it all at the same time.