Returns: An immutable BrowserObj instance containing extended property values for the associated browser. This is a static method.
Syntax:
ExtendedBrowserObj extBrowObj = BrowserObj.GetExtendedBrowser(ExtendedOptions options);
ExtendedBrowserObj extBrowObj = BrowserObj.GetExtendedBrowser(long pluginTypes);
ExtendedBrowserObj extBrowObj = BrowserObj.GetExtendedBrowser(long pluginTypes, bool keepReferrer);
ExtendedBrowserObj extBrowObj = BrowserObj.GetExtendedBrowser(long pluginTypes, bool keepReferrer, string bodyTag, string pageTitle, string pageMessage);
Like the GetBrowser method, the GetExtendedBrowser method is one of the most fundamental methods in BrowserHawk. Whereas GetBrowser obtains a BrowserObj instance, GetExtendedBrowser is used to obtain an immutable instance of the ExtendedBrowserObj class. The ExtendedBrowserObj class which represents the extended browser capabilities for a particular browser.
This method must be used within the context of an ASP.NET page so that BrowserHawk can obtain the HttpContext associated with the current visitor.
Shown in the syntax above are various signatures for this method. The recommended approach for maximum flexibility and readability of your code is to create an ExtendedOptiions class, set its properties as desired, and to pass the ExtendedOptions class into GetExtendedBrowser. However you can use the other method signatures shown as a shortcut if you prefer.
C# Example:
<%
ExtendedOptions options = new ExtendedOptions();
options.AddProperties("JavaScriptEnabled");
ExtendedBrowserObj extBrow = BrowserObj.GetExtendedBrowser(options);
%>
<html>
JavaScriptEnabled: <% Response.Write(extBrow.JavaScriptEnabled); %>
</html>
Note: Extended property information is exposed through the ExtendedBrowserObj class. For basic property information see the BrowserObj class.
Note: To use the GetExtendedBrowser method you must have either the Professional or Enterprise Edition of BrowserHawk and use the component from an ASP.NET page or other environment where the HTTP context is available.
When the GetExtendedBrowser method is invoked, BrowserHawk silently sends a test page to the user's browser, determine the values for the properties requested (as set by the instance of the ExtendedOptions class passed in), and then continues with the loading of your page.
The GetExtendedBrowser method MUST be called before the <HTML> tag is sent to the browser. Therefore the best place to invoke this method from is the top of your ASP.NET script, preferably as the first ASP code to execute in the script. If using VS.NET Code Behind pages, call GetExtendedBrowser from within the first lines of your Page_Load event. Any line of your script that comes after calling the method can then access these properties to get the appropriate values. If you try accessing the extended properties before calling this method, the extended properties will contain only their default values.
Tip: See the section on Detecting Extended Properties for an important discussion on the various requestTypes that can be used when performing extended property checks.
Before calling this method you must first create an instance of the ExtendedOptions class to set the list of extended properties you want this method to detect, and to specify additional preferences if desired. Note that detecting all plug-ins may cause a delay in the loading of the page while the detection is performed. This is because BrowserHawk now detects over 100 properties, and performing all tests at once can be a time consuming operation. Therefore it is recommended for optimal efficiency that you ask BrowserHawk to detect just the plug-ins and other extended information you are interested in rather than everything.
The time it takes to execute the test will depend on a variety of factors, including the number of properties you are testing for, and how fast it takes certain tests to execute. Most tests execute almost instantaneously. However some test, such as connection speed, Java version/vendor, and RealPlayer build number can take several seconds to execute depending on the user's computer speed and in some cases the speed of their connection.
GetExtendedBrowser only works with Internet Explorer, Netscape, Mozilla, Opera, Chrome, and Safari browsers. For all other browsers or search engines this method performs no operations and returns immediately. Therefore, it is not necessary to test the browser type prior to calling this method.
Pass in a requestType of 0 (auto-select) to have BrowserHawk automatically select the most appropriate requestType for the user and the situation in which you are using this method.
If you have a load balanced web farm, and you are testing for disabled cookies or using a requestType of 0 or 1, you must set the CookieDomain property to your root domain (i.e. "mycompany.com") prior to calling GetExtPropertiesEx. Otherwise BrowserHawk will not be able to properly determine the browser settings assuming a different web server answers the redirect issued by this method.
If you use GetExtendedBrowser from the Session_OnStart event of global.asax, you must do so as the last line of code in that event, as code which follows the call to GetExtendedBrowser will not be executed.
If you use the GetExtendedBrowser method from ASP.NET code that is executed with a POST request, you must specify a value of 0 or 3 for the requestType parameter.. Otherwise the Request.Form collection will be emptied.
A side effect of using the requestType of 2 is that your query string will be modified to contain extended information for the properties you ask BrowserHawk to check. These values are mandatory and cannot be avoided when cookies are disabled. Any information you have stored on your own in the query string will however be preserved. Use the requestType of 0 or 1 to minimize the use of the query string.
A side effect of this method with all requestTypes in the loss of the referrer information from any page that uses this method. If you need to capture the referring URL to a page that uses this method, simply set "referrer" with AddProperties as part of the ExtendedOptions class you pass into GetExtendedBrowser. To get the referrer then simply check the ExtendedBrowserObj.Referrer property. Note that for your convenience any of BrowserHawk's reserved name/value pairs are automatically removed from the referrer.
If the user changes their browser settings (such as the window size, cookie enabled/disabled settings, etc) and then presses their Reload button on your test page, BrowserHawk will disregard the new settings and return the properties as originally detected. This behavior is by design. This is necessary because it is not possible to detect the difference between a user pressing Reload, and the browser requesting the page again due to a print or 'Save Page As' request by the user. Without this behavior, In the later cases the browser would print/save the BH test page instead of your actual page. With this in mind, if you ask the user to change their settings, provide them with a link back to the test page and ask them to click on it to retry after making the changes, rather than pressing their Reload button.
Using this method to detect the Adobe Acrobat plug-in and/or its version number may cause the Acrobat splash screen to appear for users with Internet Explorer on Windows who are running Acrobat 4. While we realize the appearance of this splash screen is less than ideal, it is an unfortunate side effect of the testing and cannot be avoided. You will need to asses whether detecting this plug-in is worth the trade-off in having the splash screen appear. This does not apply to Acrobat 5 and later.
Use the Translate method to translate the various properties into a meaningful value for display to an end-user.
After performing the extended property check store the results for the extended properties you are interested in into a session variable if you may need this information again later during the visitor's session. It is not recommended that you call this particular method for each page request that a user makes.
If the visitor's JavaScript is disabled the GetExtendedBrowser method will set the JavaScriptEnabled property to False, and all other properties which depend on this method being called will contain their default values. Therefore after calling GetExtendedBrowser you should check to make sure JavaScriptEnabled is not False before relying on the values of the other properties.
For visitors using Internet Explorer version 3.0 or 3.01 only: After calling the GetExtendedBrowser method visitors with this browser will experience different behavior from their browser's Back button. For these visitors, their Back button will keep returning them to the current page. In order to back up to the previous page, the visitor will have to press their back button twice within a couple of seconds to actually back up. This is an unfortunate side effect of the test that only affects users of IE 3.0 and 3.01. If you find this bothersome the alternative is to check to see if the visitor has this browser and if so do not call GetExtendedBrowser. This issue only affects visitors with IE 3.0 or 3.01.
In certain cases where the visitor is using an old IE browser which does not have a properly installed and working VBScript scripting engine, or in rare cases where the visitor's browser does not properly process the client-side script this method sends it, accessing a page which uses this method may cause a client-side scripting error message or a blank page to result.
See Also:
About the BrowserObj class (.NET)