Best Practices Tutorial

chapter 1 | chapter 2 | chapter 3
chapter 4 | chapter 5
chapter 6 | chapter 7

home | developer central

Chapter 1 - Detecting the Environment

Index | next chapter

Note: The sample project used in this chapter has been updated as of Web Driver 3.0, in order to provide better compatibility with newer browsers. The new sample project also has some additional features; see the Java Starter Project in the Web Driver 3.0 SDK for details.

In writing a simple Web Driver application, you've probably found that you can get a scene running on your own machine with surprisingly few lines of code; but, for an application that you'll want to be viewed on the Internet at large, there are a few things you will want to verify on the user's machine before presenting your content. These items include:

Included in the downloadable version of this tutorial is a project called HelloWorld; this is a sample application that tests for these conditions. This sample project can serve as a template for more extensive content; just replace product.htm and with your custom project, and change the text in default.htm to create a custom splash screen, and you're ready to go.

Testing for the presence of the Web Driver

The initial page in the sample, default.htm, does not contain the Web Driver control- instead, it just contains the link to the install page, which contains the WTHost object and runs the Web Driver detection tests. If you wish to launch your application from an existing web page, that page can take the place of default.htm (just copy the relevant code from default.htm to your page).

The Web Driver installation should launch automatically if the content is being run on a supported browser. If the browser isn't supported, or if the user cancelled the installation for some reason, you'll want to trap the errors that will be raised when the user tries to run Web Driver content without the Web Driver installed.

The code that tests for the WebDriver presence is in load.js, a Javascript file which serves as the function library for both install.htm (the page that launches WTHost) and product.htm (the page that launches the content.) This test starts with the detect() function, which performs multiple checks to confirm that the user is running a Windows based operating system, tests for the web driver in either IE (ActiveX) or a non-IE (plugin) environment, and calls the launch() function if it's present (launch() is defined in default.htm and install.htm, not in load.js.)

function detect()
	// Do a check to make sure that the user is on a Windows machine
	// by searching the userAgent string of the browser object:
	if ( navigator.userAgent.toLowerCase().indexOf( "win" ) == -1 )
		// Let them know that they can't use the Web Driver
		alert( "The Web Driver currently only supports Windows-based operating systems.  If you would like to access our content, please use a computer running the Windows operating system." );
		// Close the window

	// Check for IE:
	if ( document.all )
		if ( !document.wthost ) // [ MSIE ] not installed
		// Launch if the launch function is defined:
		else if ( launch )
	// Non-IE browsers:
		// Netscape check by looking at plugins:
		if ( !navigator.plugins[ "WildTangent Netscape Webdriver Host" ] ) // [ Netscape ] not loaded yet  (must check to prevent failures):
			// if the plugin is not there, increment the attempts
			// counter.  If the counter = 10, they must not have Web Driver
			if ( attempts++ == 10 ) // [ Netscape 4 ] not installed 
			// If the counter < 10 then try again (to give NS 6 time to load the plugin)
			else // [ Netscape 6 ] not loaded
				setTimeout( "detect();", 100 );
		// Launch if the launch function is defined:
		else if ( launch )
			setTimeout( "launch();", 500 );

The test for the presence of the Web Driver is in two parts; one tests for the driver in Internet Explorer (in which document.all will return true), the other tests for it in Netscape (in which document.layers will return true). The Internet Explorer code fork executes ieDetectDriver() to test for the Web Driver; this function is written to the page using document.write() if IE is detected.  Here's how it appears in load.js (line breaks have been added here for readability):

if ( document.all )
	// write out the entire VBScript in one text string!
			function ieDetectDriver\n
				on error resume next\n
				Dim wtObject\n
				Set wtObject = CreateObject("WDMHHost.WTHoster")\n
				if err.number <> 0 then\n
					Set wtObject = Nothing\n
					ieDetectDriver = false\n
					Set wtObject = Nothing\n
					ieDetectDriver = true\n
				end if\n
			end function\n

The above function (which is in VBScript rather than Java, which further ensures that it won't be run in anything but Internet Explorer) attempts to instanciate WTHost as a COM object; if the class WDMHHost.WTHoster isn't registered on the user's system, calling CreateObject() on it throws an error.  The function then traps this error and returns false. Otherwise, no error is trapped and the function returns true. Either way, the test object itself (wtObject in the snippet above) is destroyed by being set to Nothing.

In the Netscape code fork of webDriverExists, we just check for the presence of the WildTangent plugin, its mime type, and if it's enabled; no other functions are called.

So, when the page loads, the presence of the Web Driver is tested. If it fails, the user is asked to confirm launching a new browser to go get it.  The two code snippets that perform this function are reproduced below.

if ( !WT || !WT.object )

function openDownloadWindow()
	// a boolean value that is true if you are in IE and if WTHost is there
	// if true, you know that they have the driver, but they
	// need to updater the version.
	var update = document.all && ieDetectDriver();
	// Open additional info window if user wants it:
	// (different messaging if the install would be an update)
	if ( DOWNLOAD_URL != "" && confirm( ( update ? "A" : "The" ) +" WildTangent Web Driver " + ( update ? "update " : "" ) + "is required.  Would you like to open a new window to download it?" ) )
	// Get rid of current window:

Other potential problems

There are a few other things that can go wrong with a user's system to result in a less than optimal user experience; many of these conditions are detectable through the WT object's getInitStatus() method. Here's the code used to check the various init status values; to avoid bombarding the user with too many errors, the user will be given the option to suppress future errors of the same type.

	// Alert any necessary messages:
	// getInitStatus checks are done in this order...
	var initCheck = [ 7, 8, 0, 2, 1, 3 ];
	var pre = "Warning - You are in ";
	var post = "-bit color. If you experience poor performance, switch to 16-bit color.";
	var msgs = 
			pre + "24" + post,
			pre + "32" + post,
			"Error - Your Direct-X<SUP><FONT SIZE=\"-1\">TM</FONT></SUP> version appears to be out of date. Please update <a href='' target='_blank'>here</a>.",
			"Warning - No 3D hardware acceleration found. Your graphics card may not support 3D acceleration, or your Direct-X version may be too old.",
			"Warning - Unsupported color depth. Must be played in 16-bit color or better.",
			"Warning - Your machine does not have a sound card that supports the ADPCM file format. ADPCM sounds will not be used."
	// Ensure that messages are shown (this cookie gets set when the
	// user checks "Do not show further messages" in the MessageBox):
	deleteCookie( "showMessages" );
	// Loop through messages in order and display errors or warnings:
	for ( var i = 0; i < initCheck.length; i++ )
		var cookieName = "messageCheck" + i;
		// show the message is the "showMessages cookie does not exist,
		// the specific error cookie does not exist,
		// and the initstatus check is true
		if ( !getCookie( "showMessages" ) && !getCookie( cookieName ) &&  WT.getInitStatus( initCheck[i] ) )
			// this shows the message and sets the cookie if requested
			messageBox( msgs[i], cookieName );			

The above code first sets up an array of error messages corresponding to the values that will be passed to the initStatus() function; it then executes initStatus(), and displays the appropriate message if the method returns true, using messageBox() (which also contains the feature to allow the user to suppress future messages). The meaning of the values passed in are listed on the Online Reference; the codes we are interested in are reproduced here:

Value Meaning
7 24 bit color mode was detected.
8 32 bit color mode was detected.
0 A supported version of DirectX was not detected.
2 No hardware accelerated 3D was detected.
1 The display is set to an unsupported color depth.
3 Compressed (ADPCM) sound files are not supported.

Color depth setting (7, 8, 1)

State of the art video cards that don't have anything else to render can easily provide accelerated graphics in 32-bit color.  Slightly older cards (or cards that are also rendering other 3d content at the same time) might have problems accelerating at 32 bits; and even if they can, graphics will run half as fast as under 16 bit color. Almost no cards provide acceleration under 24 bit color; you can assume software mode if 24 bit color is detected. Rather than shutting the game down if these modes are detected, we just notify the user that if any problems are seen, setting the color depth down to 16 bits is a good solution. In addition, the Web Driver can't function at a color depth below 16 bits (such as 256 or 16 colors); the user should also be notified of this situation as well.  Note that you can specify resolution when you set fullscreen mode on the Web Driver; it's usually a good idea to specify a 16 bit color setting when you go fullscreen.

DirectX installation (0)

This shouldn't be a problem on most machines; the Web Driver will work with every supported version of DirectX (5.0 onwards) and will also work with version 3.0, which is no longer supported by Microsoft (but is still the latest version available for Windows NT 4.0, so you might run into it on occasion).

Hardware acceleration (2)

The use of 3d hardware acceleration really sets the Web Driver apart; while there is a powerful software renderer available as well, some advanced 3d content will run at an unacceptable rate in software mode. This test will determine if hardware acceleration is present; if you don't think your game is playable in software mode, you can change this warning into a condition for not launching the content. If no hardware is detected, it could be for the following reasons:

ADPCM sound support (3)

ADPCM sound support is usually present in all versions of Windows from Win98 on- if ADPCM support is absent, this could mean that either the machine is running Windows 95, or ADPCM support has been removed or was not installed when Windows was installed. Since the Web Driver uses ADPCM for sound, if the machine doesn't support it, this will mean that your content will have no sound.

That's it for making sure your user's machine is safe to run most Web Driver content- in the next chapter, we'll look at ways to optimize code flow within the Web Driver event model.

Index | next chapter

�2000 WildTangent Inc. All Rights Reserved. Website Terms & Privacy Statement