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
DeviceGroup
JavaScript object added to theBrowserMap
JavaScript object (e.g.http://www.example.com
forbrowser
,http://m.example.com
forsmartphone
); - modify the current URL to include a
DeviceGroup
selector, in case none of the previous two methods has been set up (e.g.http://www.example.com/index.smartphone.html
for thesmartphone
device group);
- usage of
- device group override (by using a combined mechanism of a
GET
parameter 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 aGET
parameter 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 theBrowserMap
object is defined (main object used for device detection)bmaputil.js
- file containing helper objects and methodsdevicegroups.js
- file containing theDeviceGroups
object descriptions for each identified device groupprobes.js
- file containing variousBrowserMap
probes 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.js
polyfill 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 theBrowserMap
object, theDeviceGroup
s 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 createDeviceGroup
s-specific URLs to which the clients will be forwardeddescription
- a string used to store a brief description of theDeviceGroup
testFunction
- a test function that must return a boolean value; the test function is used to check if a client matches theDeviceGroup
or not; the test function can useBrowserMap
probe 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.