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 15 offers several major new features, improvements and important fixes. For details on what's changed see What's New in BrowserHawk 16.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 16.0.
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 15.x
This section outlines some important considerations regarding upgrading from BrowserHawk 15.x to version
and offers some useful tips on areas you may want to focus on.
- All developers: This update adds support for Edge, for which the Browser property is set to "Edge".
- All developers: In some cases developers may have code like this "if browser = 'IE' and version >= 11 then...". If you want to treat Edge like a modern version of IE in order to be included
in such logic, you will need to update that logic to "if (browser = 'IE' and version >= 11) OR browser = "Edge" then...
- All developers using Flash detection: BrowserHawk has been enhanced to detect the version Flash embedded in Edge, even though it is no longer a plug-in. This information will still be returned in the Plugin_Flash and Plugin_FlashVerEx properties as before. However to detect this you must place a copy of the bhawkcap.swf file in any web directories where pages reside that perform this Flash check. This file can be found in the BrowserHawk distribution.
- All developers: Browserhawk now detects OS X El Captain. OSName will return "OS X", OSVersion will return 10.11, and OSDetails will return "OS X El Captain".
- All developers using Java detection: If you use BrowserHawk to perform Java detection, which is used for the JavaVendor, JavaVersion, MSJVMBuild, OSArch, or the Extended Property versions of OSName, OSDetails and OSVersion properties, then
you must place a new copy of the BrowserHawk applet used for Java testing into your web folder(s). If you are already doing this Java detection you will have a JVMDetector.jar file in one or more of your web folders (if you don't, you can disregard these instructions completely as you are then not using Java detection).
For each folder that contains a copy of JVMDetector.jar, place this new version of the JVMDetector.jar file in the same directory where the .jar file is, as the new one contains an updated security certiicate (the old one as expired).
For users of BrowserHawk for ActiveX or .NET, the updated JVMDetector.jar file can be found in your BrowserHawk installation folder inside the JVM subfolder. Users of BrowserHawk for Java can find this file in the BrowserHawk distribution .zip file.
- All developers: Many of our customers have switched to BrowserHawk IQ, which is the cloud version of BrowserHawk. This version offers numerous advantages over the self-install version, especially if you are using BrowserHawk in a troubleshooting or help desk environment, or if you are using BrowserHawk for gathering statistics on browser configurations.
Click here to learn more and see BrowserHawk IQ in action!
Important Notes if Upgrading From BH 12.x or Earlier
This section outlines some important considerations regarding upgrading from 12.x or earlier to version
and offers some useful tips on areas you may want to focus on.
- All developers using Java detection: Perform the step outlined immediately above in the Important Notes if Upgrading from BH 15.x section.
- 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 16.0 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 16, 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 read the Important Notes section to be aware of any important steps you may need to take in conjunction with this upgrade.
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 16.0. 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 16.0 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 BrowserHawk4J 15.x and want to just replace the main files that have changed, here is a list of the main changes between 15.x and 16 (if you are running BH 14.x or earlier please do a complete reinstall following the instructions in the README file). Remember to restart your web services after replacing these files:
- jvmdetector.jar - replace all older copies of this file with the new one from the zip. If you have any jvmdetector.class files, remove them and make sure the new jvmdetector.jar file is in its place.
- optional: copy over the updated samples
Attention ColdFusion MX developers: You must restart the ColdFusion MX Application Server Service before CFMX will recognize the new files.
See these links for more information about BrowserHawk 16: