Upgrading to BrowserHawk 17.x
detect flash
download BrowserHawk detect disabled cookies BrowserHawk pricing and ordering detect connection speed Contact information for cyScape
detect Acrobat plugin
Information on browser detect, browser compatibility, browser testing, web site usability
BrowserHawk Features and Benefits


This document provides important information on how to upgrade from older versions of BrowserHawk to BrowserHawk 17.01. It also covers some important considerations to keep in mind while planning for your upgrade.

BrowserHawk 17 offers several major new features, improvements and important fixes. For details on what's changed see What's New in BrowserHawk 17.x.

Quick Index:

Backward compatibility

BrowserHawk 17.01 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 17.01 please read the following to make sure you have a valid license key that will work with this version, prior to installation.

  • Customers with ACTIVE Support and Maintenance

    Your upgrade to BrowserHawk 17.01 is free if your Support and Maintenance Plan (SAMP) is current.

    Your SAMP will be current if either:

    • You purchased new or upgraded BrowserHawk licenses within the past 365 days. In this case the key we sent with your order is already coded to run this latest version.
    • Or, you purchased a renewal to your SAMP, and your renewal term is still in effect. In this case the updated license key we sent with your renewal order is already coded to run this latest version. This assumes, however, that you installed the updated key when we sent it. See the note below for information on how to verify your key is valid in case you are not sure.

    Important note: Please confirm that your existing license key is valid for the latest version of BrowserHawk before upgrading, especially if you are not sure whether you previously installed the latest license key sent with a SAMP renewal order. Use the license key validation tool to verify your key is valid.

  • Customers with EXPIRED Support and Maintenance

    If you previously purchased BrowserHawk, but your Support and Maintenance Plan (SAMP) was not renewed and is expired, you may be eligible to purchase an upgrade to BrowserHawk for a limited time only. Your paid upgrade will include one year of support and maintenance, so that all upgrades over the next year as well as your technical support are free. With your order you will receive a license key that runs version 17.01.

  • Upgrading Across Editions

    After comparing editions, if you find features in a higher edition of BrowserHawk of interest, you can purchase an upgrade to the desired edition. For example, you can upgrade from 16.0 Professional to 17.01 Enterprise, or even 17.01 Professional to 17.01 Enterprise.

Obtaining & Installing BrowserHawk 17.01

Use one of the following links to download version 17.01 (v17 links coming soon).

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 or 16.x

This section outlines some important considerations regarding upgrading from BrowserHawk 15.x or 16.x to version 17.01 and offers some useful tips on areas you may want to focus on.

  • 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 17.01 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 or BH 16.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 17.01 provides many new features, enhancements, and important updates. See What's New for details.
  • 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 17.01

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 17.01 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 and cyScappe Update 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 17.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 17.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 BrowserHawk4J 15.x or 16.x and want to just replace the main files that have changed, here is a list of the main changes between 15.x and 17 (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:

    • bhawk4j.jar
    • maindefs.bdd
    • 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.
    • readme.txt
    • 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.

Additional reading

See these links for more information about BrowserHawk 17:

[Back to top] 
detect browser settings, maximize web site ROI, web site usability
Home | Products| Company | Support | Developer | Pricing & Ordering | Downloads | Search
cyScape, BrowserHawk, BrowserHawk To-Go, BrowserHawk IQ and CountryHawk are trademarks or registered
trademarks of cyScape, Inc. Copyright © 2020 cyScape, Inc. All Rights Reserved. web analytics
detect screen size, detect Java, IBASA, Intelligent Browser and System Analysis