This document provides important information on how to upgrade from older versions of BrowserHawk to BrowserHawk
It also covers some important considerations to keep in mind while planning for your upgrade.
BrowserHawk 14 offers several major new features, improvements and important fixes. For details on what's changed see What's New in BrowserHawk 14.x.
is fully backward compatible with all BrowserHawk code written for BrowserHawk 5.0 and later. This means that you can simply install the BrowserHawk software and should not have any need to update your BrowserHawk code.
However, depending on which features of the product you are using, additional installation or configuration steps may be necessary. Please read this document in its entirety before upgrading.
Obtaining your license key
Before installing BrowserHawk
please read the following to make sure you have a valid license key that will work with this version, prior to installation.
Obtaining & Installing BrowserHawk
Use one of the following links to download version 14.01.
Please see the above section to make sure you have a proper license key for this version prior to installation.
Important notes if upgrading from BH 12.x or earlier
This section outlines some important considerations regarding upgrading to BrowserHawk
and offers some useful tips on areas you may want to focus on.
- All developers: If you are already using the Progressive speed check from an earlier version of BH, you must update the data files used by BH to perform the connection speed test.
As a quick reminder - when you (or someone in your organization) previously set up BH to perform the Progressive connection speed testing, you downloaded these data files from us and stored them on your server.
You then pointed to the location of these files by setting BrowserHawk's SupportFilesRoot property in your code.
Before upgrading, it is mandatory that you replace the speed check data files on your server with the latest set of files from us. Download the files and extract all the data files in the zip to your server where the SupportFilesRoot points to, being sure to overwrite the existing files in the process.
If this step is not followed, and you perform a Progressive speed check for users on very fast connections, you will receive intermittent timeouts and -1 readings for their connection speed.
- All developers: The new OSBitSize and Plugin_FlashBlocked tests require that you place the bhawkcap.swf file in the same web directory as the web pages that run these tests. For example, if your web page that performs these tests is \inetpub\wwwroot\mysite\bhtest.aspx, then the file must be placed in that same directory where the bhtest.aspx file resides. BH for ActiveX and .NET users can find the bhawkcap.swf file in the \Program Files\cyScape\BrowserHawk folder. BH4J users can find this file in the BH4J zip distribution.
- All developers: The new BrowserBitSize test may fall back to using Java to perform this test, depending on the browser and OS. Therefore you must place the jvmdetector.class file in the same web directory as the web pages that run this test. This is the same file used to support the Java based tests such as JavaVendor and JavaVersion. For example, if your web page that performs these tests is \inetpub\wwwroot\mysite\bhtest.aspx, then the file must be placed in that same directory where the bhtest.aspx file resides. BH for ActiveX and .NET users can find the file in the \Program Files\cyScape\BrowserHawk\JVM folder. BH4J users can find this file in the BH4J zip distribution.
- All developers: The OSName property was simplified to return "Windows" for all Windows platforms instead of the details of the OS. For example, "Windows" instead of "Windows 7" (OS details are now in the OSDetails property). And "OS X" instead of "MacOSX". If your code checks this property for the older values please update your code accordingly.
- All developers: The OSDetails property now returns the details of the OS, which consists of the OS name and the version. Previously this property returned only "Microsoft" for Windows platforms and "Macintosh" for Macs. For example, this property now returns values such as "Windows 98", "Windows Vista", "Windows 8", "OS X Leopard", and "OS X Lion".
- All developers: The OSName and OSVersion properties are now available as "basic" properties, no longer requiring an extended property test. This makes testing of these properties instantaneous.
Note: To detect OSVersion for users with Opera browsers prior to Opera 11, you must still use the extended property version of these tests. Likewise to detect the full version details for Firefox users on OS X (such as detecting "10.7.1" instead of just "10.7")
also requires the extended version of these tests.
To use the basic version of these properties instead of the extended properties version, follow these instructions:
BH for ActiveX users: Simply remove "OSName" and "OSVersion" from the call to SetExtProperties. By doing so, you will get the basic version of these properties from the OSName and OSDetails properties automatically, and no extended property test will be performed for these properties.
BH for .NET and Java users: Remove "OSName" and "OSVersion" from the call to AddProperties on the ExtendedOptions class. Then to get the basic version of these properties, access them from the BrowserObj class, instead of from the ExtendedBrowserObj class as you do now.
- All developers: If you have customized your browser defintions using the BrowserHawk Editor, please be sure to backup your maindefs.bdf, maindefs.bdd, and maindefs.mrg files before upgrading, as your customizations will be overwritten during the upgrade process.
- All developers: BrowserHawk 14.01 provides many new features, enhancements, and important updates. See What's New for details.
- All developers: To quickly get up to speed on some of the major new features and changes in BH 14, see the following topics in the documentation:
- All developers: If you have not yet seen the the Rules Enforcement Technology introduced with BH 11, be sure to check out the video tutorials.
- BrowserHawk4J developers: BH4J as of version 11.x and later uses Java version 1.4 as a base platform (previously 1.2). Therefore you must run Java 1.4 or higher to use BH4J 12.0 and later.
- BrowserHawk4J developers: If you are using the BRWS4J you will find new SQL scripts in the BH4J zip distribution (for example, oracle-upgrade.sql). ActiveX/.NET users will have their BRWS updated automatically.
Performing the upgrade to
This section outlines the general procedure for upgrading your software.
- BrowserHawk ActiveX/.NET
If you have BrowserHawk 7.x or higher installed, you can simply run the automated BrowserHawk installation program. There is no need to remove your older BrowserHawk software first, as the installation of
will take care of this for you.
Remember to manually place the bhawkcap.swf and jvmdetector.class files in the appropriate web folder if will use the new BrowserBitSize, OSBitSize, or Plugin_FlashBlocked properties.
Also remember to manually update your progressive speed check files. Details on these steps are outlined in this document above.
TIP: To minimize the chances of needing to reboot after the installation, stop the IIS Admin Service prior to running the installation program. Be sure to restart these services once the installation is complete.
ASP.NET developers: If you manually copied the BrowserHawk.dll into one of your bin directories, as would be the case if you used simple (manual) deployment, you must replace all those copies with the new DLL found in the BrowserHawk\dotnet folder after installation of 14.01. Otherwise you will continue to use the older version. If you did not manually copy the BrowserHawk.dll and used the automated installation previously, there is no need to manually copy over this file (the reference copy of BrowserHawk.dll and version in the GAC will be automatically updated). In any event, you most likely will need to recompile your web application under BH 14.01 and deploy it; otherwise you may receive a run-time error since the older version of BrowserHawk your site was compiled with is no longer present.
- BrowserHawk4J (Java)
Generally it is recommended that you remove all BH4J files and follow the detailed installation instructions found in the readme.txt file within the BrowserHawk zip file.
If you replace your browserhawk.properties file, first take note of any customizations you made to your old file. In particular, be sure that the new file points to your BH4J license key.
If you are running BrowserHawk 12.x and want to just replace the main files that have changed, here is a list of the file changes between 12.x and 14.01 (if you are running BH 11.x or earlier please do a complete reinstall following the instructions in the README file):
- bhawkcap.swf (see notes above for details)
- Update the Progressive speed check files (see notes above for details)
- optional: copy of the updated Javadocs from the docs folder
- optional: updated brws4j SQL scripts (for an example see oracle-upgrade.sql)
- optional: copy over the updated samples
Attention ColdFusion MX developers: You must stop and restart the ColdFusion MX Application Server Service before CFMX will recognize the new files.
See these links for more information about BrowserHawk 12: