BrowserMap is a JavaScript browser features detection library. It uses modular probes and code snippets that detect specific features of the client; these are then used to detect the client's type and to optimize page rendering or to provide the client with alternate website versions.
In addition, BrowserMap is capable of detecting the device groups a client belongs to. The following groups are provided by default:
smartphone- feature phones / smartphones;tablet- various tablets, based on screen size and the presence of touch capabilities (the touch events Modernizr test is used for this feature);highResolutionDisplay- devices that report a device pixel ratio greater or equal than 2, such as: iPhone 4 and above, iPod Touch gen. 4 and above, iPad 3, Samsung Galaxy S3, etc.;browser- desktop browsers capable of CSS 3D transitions (another Modernizr test is used for this feature)oldBrowser- less modern desktop browsers
A small demo is available at http://devicemap-vm.apache.org/browsermap/index.html.
- extensible probing mechanism;
- on-demand probing with probes' results cache and cache clearing mechanism;
- easy mechanism for overriding pre-defined device groups / adding new device groups;
- three ways of determining the correct URL to which a client should be forwarded, depending on its device group, in order of importance:
- usage of
<link rel="alternate" hreflang="<language_code>" data-bmap-devgroups="<device_group_name_list>" href="<alternate_url>" />tags in BrowserMap enabled pages; - a specific URL defined for each
DeviceGroupJavaScript object added to theBrowserMapJavaScript object (e.g.http://www.example.comforbrowser,http://m.example.comforsmartphone); - modify the current URL to include a
DeviceGroupselector, in case none of the previous two methods has been set up (e.g.http://www.example.com/index.smartphone.htmlfor thesmartphonedevice group);
- usage of
- device group override (by using a combined mechanism of a
GETparameter and cookie storage) so that a client from a certain device group can access the pages designed for a different device group; for clients that do not support cookies, the device group override uses just aGETparameter which can optionally be appended to each URL pointing to a resource from the same domain as the current resource.
The BrowserMap code is organised in two base folders:
libs/browsermap/:bmap.js- this is where theBrowserMapobject is defined (main object used for device detection)bmaputil.js- file containing helper objects and methodsdevicegroups.js- file containing theDeviceGroupsobject descriptions for each identified device groupprobes.js- file containing variousBrowserMapprobes used to detect various browser features that can determine a client's capabilities
libs/externals/:modernizr/modernizr.custom.js- a reduced Modernizr configurationmatchMedia/matchMedia.js- thematchMedia.jspolyfill project written by Paul Irish
In order to have a functional BrowserMap instance, the previous files have to be included in this order:
<script type="text/javascript" src="libs/browsermap/bmaputil.js"></script>
<script type="text/javascript" src="libs/browsermap/bmap.js"></script>
<script type="text/javascript" src="libs/externals/modernizr/modernizr.custom.js"></script>
<script type="text/javascript" src="libs/externals/matchMedia/matchMedia.js"></script>
<script type="text/javascript" src="libs/browsermap/probes.js"></script>
<script type="text/javascript" src="libs/browsermap/devicegroups.js"></script>
A DeviceGroup object has the following attributes:
ranking- determines the order in which, when added to theBrowserMapobject, theDeviceGroups will be matched; a lower ranking means an earlier evaluation (e.g. 0 is evaluated before 10);name- the name of theDeviceGroup; can also act as a URL selector which will be used to createDeviceGroups-specific URLs to which the clients will be forwardeddescription- a string used to store a brief description of theDeviceGrouptestFunction- a test function that must return a boolean value; the test function is used to check if a client matches theDeviceGroupor not; the test function can useBrowserMapprobe functionsisSelector- a boolean flag which is checked to see if aDeviceGroup's name should be used as a selector or not.
To add a DeviceGroup to the BrowserMap object, one can use the BrowserMap.addDeviceGroup(DeviceGroup object) method. The last DeviceGroup added to BrowserMap with the same name as a previously existing DeviceGroup will be the one which will be stored, which can be useful if one tries to override the default DeviceGroups.
BrowserMap's own source files are located in src/main/js.
The main test file is located in src/test/js and the tests are based on QUnit.
The builds are handled with Grunt. In order to build the project you need to install
PhantomJS, Node.js and npm.
Afterwards use npm to globally install grunt-cli and the development dependencies:
npm install -g grunt-cli
npm install -d
The tests can be run with grunt test inside the browsermap folder.
Packaging the app is done with grunt package.
Please file a JIRA issue at https://issues.apache.org/jira/browse/DMAP and use the "browsermap" label.
If you're reporting a bug please provide an accurate description of the problem together with the debug output found on the demo page from http://devicemap-vm.apache.org/browsermap/index.html.