1 | # mobile-detect.js
|
2 |
|
3 | A loose port of [Mobile-Detect](https://github.com/serbanghita/Mobile-Detect) to JavaScript.
|
4 |
|
5 | This script will detect the device by comparing patterns against a given User-Agent string.
|
6 | You can find out information about the device rendering your web page:
|
7 |
|
8 | * mobile or not
|
9 | * if mobile, whether phone or tablet
|
10 | * operating system
|
11 | * [Mobile Grade (A, B, C)](http://jquerymobile.com/gbs/)
|
12 | * specific versions (e.g. WebKit)
|
13 |
|
14 | Current `master` branch is using detection logic from **Mobile-Detect@2.8.12**
|
15 |
|
16 | # Live Demo
|
17 |
|
18 | [@zeno](https://github.com/zeno) created a very nice [live-demo](https://github.com/zeno/mobile-detect-demo).
|
19 | See it in action with your device:
|
20 |
|
21 | **[Demo](http://zeno.github.io/mobile-detect-demo/)**
|
22 |
|
23 | Another Demo/check (though without any styling) can be found [here](http://hgoebl.github.io/mobile-detect.js/check/).
|
24 |
|
25 | # Warning
|
26 |
|
27 | As mentioned later, "User-Agent" based detection is not a reliable solution in most cases, because:
|
28 |
|
29 | * The rules (regular expressions) are constantly out-dated and incomplete
|
30 | * You have to update the detection code continuously
|
31 | * There are other ways to detect how your web application should behave:
|
32 | * feature detection, e.g. [Modernizr](http://modernizr.com/)
|
33 | * [Media Queries](https://developer.mozilla.org/en-US/docs/Web/Guide/CSS/Media_queries), examples at <http://mediaqueri.es/>
|
34 | * Maybe there are some libraries out there (which are probably not free) doing a more reliable job
|
35 |
|
36 | If you still want to (or have to) use this library, you should always **encapsulate it with your own code**,
|
37 | because chances a very high that you have to tweak the behaviour a bit or are not satisfied with the
|
38 | result of mobile-detect.js. **Don't spread usage of MobileDetect all over your own code!** As you can see
|
39 | in the issues, there are some "bugs", feature-requests, pull-requests where people are not so happy
|
40 | how MobileDetect works. But I cannot change its behaviour from version to version, even if this was
|
41 | reasonable from new users' point of view. I hope you show understanding.
|
42 |
|
43 | At least there is a way to monkey-patch the library (see "Extending" below).
|
44 |
|
45 | # Usage
|
46 |
|
47 | ## Browser
|
48 |
|
49 | ```html
|
50 | <script src="mobile-detect.js"></script>
|
51 | <script>
|
52 | var md = new MobileDetect(window.navigator.userAgent);
|
53 | // ... see below
|
54 | </script>
|
55 | ```
|
56 |
|
57 | ## Node.js / Express
|
58 |
|
59 | ```js
|
60 | var MobileDetect = require('mobile-detect'),
|
61 | md = new MobileDetect(req.headers['user-agent']);
|
62 | // ... see below
|
63 | ```
|
64 |
|
65 | ## General
|
66 |
|
67 | ```js
|
68 | var md = new MobileDetect(
|
69 | 'Mozilla/5.0 (Linux; U; Android 4.0.3; en-in; SonyEricssonMT11i' +
|
70 | ' Build/4.1.A.0.562) AppleWebKit/534.30 (KHTML, like Gecko)' +
|
71 | ' Version/4.0 Mobile Safari/534.30');
|
72 |
|
73 | // more typically we would instantiate with 'window.navigator.userAgent'
|
74 | // as user-agent; this string literal is only for better understanding
|
75 |
|
76 | console.log( md.mobile() ); // 'Sony'
|
77 | console.log( md.phone() ); // 'Sony'
|
78 | console.log( md.tablet() ); // null
|
79 | console.log( md.userAgent() ); // 'Safari'
|
80 | console.log( md.os() ); // 'AndroidOS'
|
81 | console.log( md.is('iPhone') ); // false
|
82 | console.log( md.is('bot') ); // false
|
83 | console.log( md.version('Webkit') ); // 534.3
|
84 | console.log( md.versionStr('Build') ); // '4.1.A.0.562'
|
85 | console.log( md.match('playstation|xbox') ); // false
|
86 | ```
|
87 |
|
88 | ## More Info ...
|
89 |
|
90 | There is some documentation generated by JSDoc:
|
91 |
|
92 | <http://hgoebl.github.io/mobile-detect.js/doc/MobileDetect.html>
|
93 |
|
94 | ## Side Effects
|
95 |
|
96 | Script creates the global property `MobileDetect`.
|
97 |
|
98 | ## Modernizr Extension
|
99 |
|
100 | When using [Modernizr](http://modernizr.com/), you can include `mobile-detect-modernizr.js`.
|
101 | It will add the CSS classes `mobile`, `phone`, `tablet` and `mobilegradea` if applicable.
|
102 |
|
103 | You can easily extend it, e.g. `android`, `iphone`, etc.
|
104 |
|
105 | ## Size (bytes)
|
106 |
|
107 | * development: 62001
|
108 | * minified: 34907
|
109 | * minified + gzipped: 14598 (`cat mobile-detect.min.js | gzip -9f | wc -c`)
|
110 |
|
111 | # Installation
|
112 |
|
113 | ## Bower
|
114 |
|
115 | $ bower install hgoebl/mobile-detect.js --save
|
116 |
|
117 | ## Node.js / npm
|
118 |
|
119 | $ npm install mobile-detect --save
|
120 |
|
121 | ## CDN - [jsDelivr](http://www.jsdelivr.com/#!mobile-detect.js)
|
122 |
|
123 | <script src="//cdn.jsdelivr.net/mobile-detect.js/1.0.0/mobile-detect.min.js"></script>
|
124 |
|
125 | ## cdnjs - [cdnjs.com](https://cdnjs.com/libraries/mobile-detect)
|
126 |
|
127 | <script src="//cdnjs.cloudflare.com/ajax/libs/mobile-detect/1.0.0/mobile-detect.min.js"></script>
|
128 |
|
129 | # Extending/Modifying Behaviour
|
130 |
|
131 | Though it is not recommended to rely on internal methods or structures of MobileDetect, you can alter
|
132 | the behaviour by replacing particular internal methods with your own implementations.
|
133 | If you feel like this is the only possibility, then go ahead and have a look at the source code and
|
134 | examples in tests/spec/MobileDetectSpec.js (search for "Extensibility").
|
135 |
|
136 | # Alternatives / Infos
|
137 |
|
138 | Often device detection is the first solution in your mind. Please consider looking for other solutions
|
139 | like media queries and feature detection (e.g. w/ Modernizr). Maybe there are better (simpler, smaller,
|
140 | faster) device detection libraries, so here you have a list (order has no meaning apart from first element):
|
141 |
|
142 | * [Modernizr](http://modernizr.com/)
|
143 | In most cases the better solution: don't use knowledge about device and version, but detect features
|
144 | (touch, canvas, ...)
|
145 | * [Mozilla Hacks - User-Agent detection, history and checklist](https://hacks.mozilla.org/2013/09/user-agent-detection-history-and-checklist/)
|
146 | * [Mobile-Detect](https://github.com/serbanghita/Mobile-Detect)
|
147 | A lightweight PHP class for detecting mobile devices (including tablets).
|
148 | This is the "source" of this JavaScript project and if you use PHP on your server you should use it!
|
149 | * [Detect Mobile Browsers](http://detectmobilebrowsers.com/) Open source mobile phone detection in many languages
|
150 | and for Webservers (Apache, nginx, IIS). mobile-detect.js uses the code of this library as a fallback in case
|
151 | of incomplete detection regular expressions.
|
152 | * [sebarmeli / JS-Redirection-Mobile-Site](https://github.com/sebarmeli/JS-Redirection-Mobile-Site/)
|
153 | JS to handle the redirection to the mobile version of your site
|
154 | * [dmolsen/Detector](https://github.com/dmolsen/Detector)
|
155 | Detector is a simple, PHP- and JavaScript-based browser- and
|
156 | feature-detection library that can adapt to new devices & browsers
|
157 | on its own without the need to pull from a central database of browser information.
|
158 | * [matthewhudson/device.js](https://github.com/matthewhudson/device.js)
|
159 | Conditional CSS and/or JavaScript based on device operating system, orientation and type
|
160 | * [brendanlim/mobile-fu](https://github.com/brendanlim/mobile-fu)
|
161 | Automatically detect mobile requests from mobile devices in your Rails application.
|
162 | * [FormFactor](https://github.com/PaulKinlan/formfactor)
|
163 | FormFactor helps you customize your web app for different form factors, e.g. when you make
|
164 | "the mobile version", "the TV version", etc.
|
165 | * [UAParser.js](http://faisalman.github.com/ua-parser-js/)
|
166 | Lightweight JavaScript-based User-Agent String Parser
|
167 | * [MobileESP - Easily detect mobile web site visitors](http://blog.mobileesp.com/)
|
168 | * [WURFL](http://wurfl.sourceforge.net/)
|
169 | * [Handset and Tablet Detection](http://www.handsetdetection.com/)
|
170 | * [Search on microjs.com](http://microjs.com/#detect)
|
171 |
|
172 | ## Mobile-Usage Statistics
|
173 |
|
174 | If you have to provide statistics about how many and which mobile devices are hitting your web-site, you can
|
175 | generate statistics (data and views) with [hgoebl/mobile-usage](https://github.com/hgoebl/mobile-usage).
|
176 | There are many hooks to customize statistical calculation to your needs.
|
177 |
|
178 |
|
179 | # License
|
180 |
|
181 | MIT-License (see LICENSE file).
|
182 |
|
183 |
|
184 | # Contributing
|
185 |
|
186 | Your contribution is welcome.
|
187 | If you want new devices to be supported, please contribute to
|
188 | [Mobile-Detect](https://github.com/serbanghita/Mobile-Detect) instead.
|
189 |
|
190 | To run generate-script it is necessary to have [Mobile-Detect](https://github.com/serbanghita/Mobile-Detect)
|
191 | as a sibling directory to mobile-detect.js/.
|
192 | (I tried to use `git subtree` but had some problems on Mac OS X - probably my fault...)
|
193 |
|
194 | * fork or clone serbanghita/Mobile-Detect
|
195 | * fork hgoebl/mobile-detect.js
|
196 | * run `npm install`
|
197 | * create branch
|
198 | * make changes and run `grunt` (needs PHP >= 5.4 in your path)
|
199 | * run browser test (tests/SpecRunner.html)
|
200 | * commit, push to your branch
|
201 | * create pull request
|
202 |
|
203 | ## Testing
|
204 |
|
205 | ### Browser
|
206 |
|
207 | Open `tests/SpecRunner.html` in different browsers.
|
208 |
|
209 | ### Node.js
|
210 |
|
211 | $ npm test
|
212 | $ # or
|
213 | $ grunt jasmine_node
|
214 |
|
215 |
|
216 | # Donations
|
217 |
|
218 | If you want, you can donate to [Mobile-Detect](https://github.com/serbanghita/Mobile-Detect).
|
219 |
|
220 |
|
221 | # TODO
|
222 |
|
223 | * Extend RegEx patterns so that test passes
|