Recipe 2.1 Detecting the Player Version

2.1.1 Problem

You want to know the user's Flash Player version.

2.1.2 Solution

Use a plugin-detection script that runs in the browser before loading the Flash Player, or use ActionScript (System.capabilities.version, getVersion( ), or $version) within the Flash Player, as supported by the minimum Player version you expect to encounter.

2.1.3 Discussion

There are two broad categories of Flash Player version detection: you can attempt to detect the Player version with a browser-based script before the Player loads, or you can use ActionScript within the Flash Player to check the version that is currently running.

The problem with the first method is that it doesn't work on all platforms and with all browsers, as explained in part at http://www.macromedia.com/support/flash/ts/documents/browser_support_matrix.htm.

Therefore, you should guard against a "false negative" in your detection approach; even if you fail to detect the Flash Player plugin, you should give the user the option of telling you that he has the plugin installed and would like to view your Flash content (i.e., don't force visitors to the Macromedia Flash installation page just because you can't detect their Player version).

There is a wealth of existing documentation on detecting the presence and version of the Flash Player plugin with a browser script, so refer to the following URLs for explanations and examples.

Macromedia Technote 14526, "How to detect the presence of the Flash Player," is a good starting point:

http://www.macromedia.com/support/flash/ts/documents/uber_detection.htm

See also the Player-detection discussion in the Flash Deployment Kit:

http://www.macromedia.com/support/flash/player/flash_deployment_readme/

The standard third-party browser-based Flash plugin-detection tool is the Moock Flash Player Inspector:

http://www.moock.org/webdesign/flash/detection/moockfpi/

Testing the Flash Player version from ActionScript can be problematic because the user might not have the Player installed at all (in which case your movie and its ActionScript code are never executed), or the installed version may not support the latest ActionScript techniques. Therefore, it is typical to use the lowest common denominator for checking Flash Player versions (you can use the more modern techniques if you are sure the user will have at least a known minimum version). Naturally, if your movie is running in the Standalone Player, you can't use the browser-based plugin-detection scripts, but you can build the executable with whatever version of Flash you choose.

For maximum compatibility, use the _level0.$version property, which returns a string of the form:

OS MajorVersion,MinorVersion,Build,Patch

The $version property is supported in Flash Player 4.0.11.0 and later. For example, the following returned string indicates the Windows Player version 6.0, build number 40.0:

WIN 6,0,40,0

You can extract the operating system, major version, and minor version using the String.split( ) method, making it easier to work with the results:

// Split $version into an array with two elements using a space as the delimiter.  // This creates an array with two elements, such as "WIN" and "6,0,40,0". playerParts = _root.$version.split(" "); // Store the OS name in playerOS. playerOS = playerParts[0]; // Split the remaining version string using a comma as the delimiter. This creates an // array with four elements, such as "6", "0", "40", and "0". playerVersion = playerParts[1].split(","); // Convert the major and minor version, the build, and the patch into numbers and // store them for later use. playerMajorMinor = Number(playerVersion[0] + "." + playerVersion[1]); playerBuild = Number(playerVersion[2]); playerPatch = Number(playerVersion[3]);

You can use the version number to make a decision, such as sending the user to an error page that says, "This site requires Flash 5 or later":

if (playerMajorMinor < 5.0) {   getURL ("http://www.person13.com/flashplugin/versionerrorpage.html"); } else {   getURL ("http://www.person13.com/ascb/modernmovie.swf"); }

Why check the Player version from within Flash at all? Why not just publish a Flash 5 .swf file if your site requires the Flash 5 Player? In some browsers, such as Internet Explorer for Windows, the browser will automatically attempt to load the later plugin if the currently installed plugin is too old. But by using a Flash-based detection script, you can detect the plugin more accurately than you can in some browsers. Furthermore, you can customize the user experience to make it more user-friendly. Therefore, if you expect visitors to have older versions of the plugin, you should publish a Flash 4 .swf file that acts as a gatekeeper to Flash content requiring newer versions of the plugin. That is, the Flash 4 .swf should detect the version and then branch to another .swf file containing code implemented in the more modern version you are supporting.

Flash 5 added support for the getVersion( ) global function, which returns the same version information string as $version. Use $version to detect the Player version unless you are sure that the user has at least Flash 5 installed. Likewise, Flash 6 supports the more modern System.capabilities.version property, which again returns the same string as $version. The advantage of $version is, of course, that it is supported in older versions of the Player. And since the purpose in most cases is to detect the correct Player version, it doesn't generally make sense to use a technique that is not available in older versions of the Player. The exception is if you want to detect only versions and revisions since the Flash 5 and Flash 6 Players, respectively.

Put the following code in a System.as file and include it (using the #include directive) to more readily perform version checking in your movies. This code will work with Flash 5 or later.

// Create a System object if it doesn't exist already. if (System == undefined) {   System = new Object(  ); } // Create a System.capabilities object if it doesn't exist already. if (System.capabilities == undefined) {   System.capabilities = new Object(  ); } // The extractPlayer(  ) method extracts the OS and major and minor versions of the // Player and saves them as properties of the System.capabilities object. System.capabilities.extractPlayer = function (  ) {   var playerParts = _level0.$version.split(" ");   this.playerOS = playerParts[0];   var playerVersion = playerParts[1].split(",");   this.playerMajorMinor = Number(playerVersion[0] + "." + playerVersion[1]);   this.playerBuild = Number(playerVersion[2]);   this.playerPatch = Number(playerVersion[3]); } // The following methods return the playerOS, playerMajorMinor, playerBuild, and // playerPatch. If necessary, extractPlayer(  ) is called first. System.capabilities.getPlayerOS = function (  ) {   if (this.playerOS == undefined) {     this.extractPlayer(  );   }   return this.playerOS; } System.capabilities.getPlayerMajorMinor = function (  ) {   if (this.playerMajorMinor == undefined) {     this.extractPlayer(  );   }   return this.playerMajorMinor; } System.capabilities.getPlayerBuild = function (  ) {   if (this.playerBuild == undefined) {     this.extractPlayer(  );   }   return this.playerBuild; } System.capabilities.getPlayerPatch = function (  ) {   if (this.playerPatch == undefined) {     this.extractPlayer(  );   }   return this.playerPatch; } // Test each get method to see that it works. trace(System.capabilities.getPlayerOS(  )); trace(System.capabilities.getPlayerMajorMinor(  )); trace(System.capabilities.getPlayerBuild(  )); trace(System.capabilities.getPlayerPatch(  ));

You can use the preceding code to easily check the various portions of the version string. For example, if your movie uses scroll pane components, you should require Player 6.0.40.0 or later because previous revisions had bugs related to scroll panes. For example:

// Display an error message if not using at least version 6.0.40.0. if ( !(System.capabilities.getPlayerMajorMinor(  ) >= 6 &&         System.capabilities.getPlayerBuild(  ) >= 40) ) {   outputTextField.text = "You need version 6.0.40.0 or later of the " +                          "Flash Player in order to view this movie correctly." }

For testing purposes, older versions of the Flash Player can be obtained from:

http://www.macromedia.com/support/flash/ts/documents/oldplayers.htm