175 lines
7.8 KiB
Plaintext
175 lines
7.8 KiB
Plaintext
51Degrees Device Detection
|
|
--------------------------
|
|
|
|
You can also include 51Degrees for inbuilt device detection enabling attributes
|
|
such as screen size (physical & pixels), supported input methods, release date,
|
|
hardware vendor and model, browser information, and device price among many
|
|
others. Such information can be used to improve the user experience of a web
|
|
site by tailoring the page content, layout and business processes to the
|
|
precise characteristics of the device. Such customisations improve profit by
|
|
making it easier for customers to get to the information or services they
|
|
need. Attributes of the device making a web request can be added to HTTP
|
|
headers as configurable parameters.
|
|
|
|
In order to enable 51Degrees download the 51Degrees source code from the
|
|
official git repository :
|
|
|
|
- either use the proven stable but frozen 3.2.10 version which
|
|
supports the Trie algorithm :
|
|
|
|
git clone https://git.51Degrees.com/Device-Detection.git -b v3.2.10
|
|
|
|
- use newer 3.2.12.12 version which continues to receive database
|
|
updates and supports a new Hash Trie algorithm, but which is not
|
|
compatible with older Trie databases :
|
|
|
|
git clone https://github.com/51Degrees/Device-Detection.git -b v3.2.12
|
|
|
|
- or use the latest 51Degrees version 4 with 51Degrees Hash algorithm,
|
|
not compatible with older databases :
|
|
|
|
git clone --recurse-submodules https://github.com/51Degrees/device-detection-cxx.git
|
|
|
|
then run 'make' with USE_51DEGREES, optionally 51DEGREES_VER=4 (if using
|
|
51Degrees version 4), and 51DEGREES_SRC set. Both 51DEGREES_INC and
|
|
51DEGREES_LIB may additionally be used to force specific different paths for
|
|
.o and .h, but will default to 51DEGREES_SRC. Make sure to replace
|
|
'51D_REPO_PATH' with the path to the 51Degrees repository.
|
|
|
|
51Degrees provide 4 different detection algorithms:
|
|
|
|
1. Pattern - balances main memory usage and CPU.
|
|
2. Trie - a very high performance detection solution which uses more main
|
|
memory than Pattern.
|
|
3. Hash Trie - replaces Trie, 3x faster, 80% lower memory consumption and
|
|
tuning options.
|
|
4. 51Degrees V4 Hash - only with 51Degrees Device Detection V4.
|
|
|
|
To make with 51Degrees Pattern algorithm use the following command line.
|
|
|
|
$ make TARGET=<target> USE_51DEGREES=1 51DEGREES_SRC='51D_REPO_PATH'/src/pattern
|
|
|
|
To use the 51Degrees Trie algorithm use the following command line.
|
|
|
|
$ make TARGET=<target> USE_51DEGREES=1 51DEGREES_SRC='51D_REPO_PATH'/src/trie
|
|
|
|
To build with the 51Degrees Device Detection V4 use the following command line.
|
|
|
|
$ make TARGET=<target> USE_51DEGREES=1 51DEGREES_VER=4 51DEGREES_SRC='51D_REPO_PATH'/src
|
|
|
|
A data file containing information about devices, browsers, operating systems
|
|
and their associated signatures is then needed. 51Degrees provide a free
|
|
database with Github repo for this purpose. These free data files are located
|
|
in '51D_REPO_PATH'/data with the extensions .dat for Pattern data and .trie for
|
|
Trie data. Free Hash Trie data file can be obtained by signing up for a licence
|
|
key at https://51degrees.com/products/store/on-premise-device-detection.
|
|
If using the 51degrees version 4, the free hash data file is located in
|
|
'51D_REPO_PATH'/device-detection-data with the .hash extension.
|
|
|
|
For HAProxy developers who need to verify that their changes didn't affect the
|
|
51Degrees implementation, a dummy library is provided in the
|
|
"addons/51degrees/dummy" directory. This does not function, but implements the
|
|
API such that the 51Degrees module can be used (but not return any meaningful
|
|
information). To test either Pattern or Hash Trie, or the 51Degrees version 4
|
|
Hash algorithm, build with:
|
|
|
|
$ make TARGET=<target> USE_51DEGREES=1 51DEGREES_SRC=addons/51degrees/dummy/pattern
|
|
or
|
|
$ make TARGET=<target> USE_51DEGREES=1 51DEGREES_SRC=addons/51degrees/dummy/trie
|
|
or
|
|
$ make TARGET=<target> USE_51DEGREES=1 51DEGREES_VER=4 51DEGREES_SRC=addons/51degrees/dummy/v4hash
|
|
|
|
respectively.
|
|
|
|
The configuration file needs to set the following parameters:
|
|
|
|
global
|
|
51degrees-data-file path to the Pattern, Trie or V4 Hash data file
|
|
51degrees-property-name-list list of 51Degrees properties to detect
|
|
51degrees-property-separator separator to use between values
|
|
51degrees-cache-size LRU-based cache size (disabled by default)
|
|
|
|
The following is an example of the settings for Pattern.
|
|
|
|
global
|
|
51degrees-data-file '51D_REPO_PATH'/data/51Degrees-LiteV3.2.dat
|
|
51degrees-property-name-list IsTablet DeviceType IsMobile
|
|
51degrees-property-separator ,
|
|
51degrees-cache-size 10000
|
|
|
|
HAProxy needs a way to pass device information to the backend servers. This is
|
|
done by using the 51d converter or fetch method, which intercepts the HTTP
|
|
headers and creates some new headers. This is controlled in the frontend
|
|
http-in section.
|
|
|
|
The following is an example which adds two new HTTP headers prefixed X-51D-
|
|
|
|
frontend http-in
|
|
bind *:8081
|
|
default_backend servers
|
|
http-request set-header X-51D-DeviceTypeMobileTablet %[51d.all(DeviceType,IsMobile,IsTablet)]
|
|
http-request set-header X-51D-Tablet %[51d.all(IsTablet)]
|
|
|
|
Here, two headers are created with 51Degrees data, X-51D-DeviceTypeMobileTablet
|
|
and X-51D-Tablet. Any number of headers can be created this way and can be
|
|
named anything. 51d.all( ) invokes the 51degrees fetch. It can be passed up to
|
|
five property names of values to return. Values will be returned in the same
|
|
order, separated by the 51-degrees-property-separator configured earlier. If a
|
|
property name can't be found the value 'NoData' is returned instead.
|
|
|
|
In addition to the device properties three additional properties related to the
|
|
validity of the result can be returned when used with the Pattern method. The
|
|
following example shows how Method, Difference and Rank could be included as one
|
|
new HTTP header X-51D-Stats.
|
|
|
|
frontend http-in
|
|
...
|
|
http-request set-header X-51D-Stats %[51d.all(Method,Difference,Rank)]
|
|
|
|
These values indicate how confident 51Degrees is in the result that that was
|
|
returned. More information is available on the 51Degrees web site at:
|
|
|
|
https://51degrees.com/support/documentation/pattern
|
|
|
|
The above 51d.all fetch method uses all available HTTP headers for detection. A
|
|
modest performance improvement can be obtained by only passing one HTTP header
|
|
to the detection method with the 51d.single converter. The following example
|
|
uses the User-Agent HTTP header only for detection.
|
|
|
|
frontend http-in
|
|
...
|
|
http-request set-header X-51D-DeviceTypeMobileTablet %[req.fhdr(User-Agent),51d.single(DeviceType,IsMobile,IsTablet)]
|
|
|
|
Any HTTP header could be used inplace of User-Agent by changing the parameter
|
|
provided to req.fhdr.
|
|
|
|
When compiled to use the Trie detection method the trie format data file needs
|
|
to be provided. Changing the extension of the data file from dat to trie will
|
|
use the correct data.
|
|
|
|
global
|
|
51degrees-data-file '51D_REPO_PATH'/data/51Degrees-LiteV3.2.trie
|
|
|
|
When used with Trie the Method, Difference and Rank properties are not
|
|
available.
|
|
|
|
When using the 51Degrees V4 Hash algorithm, the hash format data file needs
|
|
to be provided as in the following example.
|
|
|
|
global
|
|
51degrees-data-file '51D_REPO_PATH'/device-detection-data/51Degrees-LiteV4.1.hash
|
|
|
|
The free Lite data file contains information about screen size in pixels and
|
|
whether the device is a mobile. A full list of available properties is located
|
|
on the 51Degrees web site at:
|
|
|
|
https://51degrees.com/resources/property-dictionary
|
|
|
|
Some properties are only available in the paid for Premium and Enterprise
|
|
versions of 51Degrees. These data sets not only contain more properties but
|
|
are updated weekly and daily and contain signatures for 100,000s of different
|
|
device combinations. For more information see the data options comparison web
|
|
page:
|
|
|
|
https://51degrees.com/compare-data-options
|