blob: 71b2eb760b940388ef6cb251bd81ef8f942633c7 [file] [log] [blame]
Willy Tarreau29b25312016-11-08 14:57:29 +0100151Degrees Device Detection
2--------------------------
3
4You can also include 51Degrees for inbuilt device detection enabling attributes
5such as screen size (physical & pixels), supported input methods, release date,
6hardware vendor and model, browser information, and device price among many
7others. Such information can be used to improve the user experience of a web
8site by tailoring the page content, layout and business processes to the
9precise characteristics of the device. Such customisations improve profit by
10making it easier for customers to get to the information or services they
11need. Attributes of the device making a web request can be added to HTTP
12headers as configurable parameters.
13
14In order to enable 51Degrees download the 51Degrees source code from the
15official github repository :
16
ben51degreesac752ff2017-07-19 16:22:04 +010017 git clone https://git.51Degrees.com/Device-Detection.git -b v3.2.10
Willy Tarreau29b25312016-11-08 14:57:29 +010018
19then run 'make' with USE_51DEGREES and 51DEGREES_SRC set. Both 51DEGREES_INC
20and 51DEGREES_LIB may additionally be used to force specific different paths
21for .o and .h, but will default to 51DEGREES_SRC. Make sure to replace
22'51D_REPO_PATH' with the path to the 51Degrees repository.
23
2451Degrees provide 2 different detection algorithms:
25
26 1. Pattern - balances main memory usage and CPU.
27 2. Trie - a very high performance detection solution which uses more main
28 memory than Pattern.
29
30To make with 51Degrees Pattern algorithm use the following command line.
31
32 $ make TARGET=<target> USE_51DEGREES=1 51DEGREES_SRC='51D_REPO_PATH'/src/pattern
33
34To use the 51Degrees Trie algorithm use the following command line.
35
36 $ make TARGET=<target> USE_51DEGREES=1 51DEGREES_SRC='51D_REPO_PATH'/src/trie
37
38A data file containing information about devices, browsers, operating systems
39and their associated signatures is then needed. 51Degrees provide a free
40database with Github repo for this purpose. These free data files are located
41in '51D_REPO_PATH'/data with the extensions .dat for Pattern data and .trie for
42Trie data.
43
44The configuration file needs to set the following parameters:
45
46 global
47 51degrees-data-file path to the Pattern or Trie data file
48 51degrees-property-name-list list of 51Degrees properties to detect
49 51degrees-property-separator separator to use between values
50 51degrees-cache-size LRU-based cache size (disabled by default)
51
52The following is an example of the settings for Pattern.
53
54 global
55 51degrees-data-file '51D_REPO_PATH'/data/51Degrees-LiteV3.2.dat
56 51degrees-property-name-list IsTablet DeviceType IsMobile
57 51degrees-property-separator ,
58 51degrees-cache-size 10000
59
60HAProxy needs a way to pass device information to the backend servers. This is
61done by using the 51d converter or fetch method, which intercepts the HTTP
62headers and creates some new headers. This is controlled in the frontend
63http-in section.
64
65The following is an example which adds two new HTTP headers prefixed X-51D-
66
67 frontend http-in
68 bind *:8081
69 default_backend servers
70 http-request set-header X-51D-DeviceTypeMobileTablet %[51d.all(DeviceType,IsMobile,IsTablet)]
71 http-request set-header X-51D-Tablet %[51d.all(IsTablet)]
72
73Here, two headers are created with 51Degrees data, X-51D-DeviceTypeMobileTablet
74and X-51D-Tablet. Any number of headers can be created this way and can be
75named anything. 51d.all( ) invokes the 51degrees fetch. It can be passed up to
76five property names of values to return. Values will be returned in the same
77order, seperated by the 51-degrees-property-separator configured earlier. If a
78property name can't be found the value 'NoData' is returned instead.
79
80In addition to the device properties three additional properties related to the
81validity of the result can be returned when used with the Pattern method. The
82following example shows how Method, Difference and Rank could be included as one
83new HTTP header X-51D-Stats.
84
85 frontend http-in
86 ...
87 http-request set-header X-51D-Stats %[51d.all(Method,Difference,Rank)]
88
89These values indicate how confident 51Degrees is in the result that that was
90returned. More information is available on the 51Degrees web site at:
91
92 https://51degrees.com/support/documentation/pattern
93
94The above 51d.all fetch method uses all available HTTP headers for detection. A
95modest performance improvement can be obtained by only passing one HTTP header
96to the detection method with the 51d.single converter. The following example
97uses the User-Agent HTTP header only for detection.
98
99 frontend http-in
100 ...
101 http-request set-header X-51D-DeviceTypeMobileTablet %[req.fhdr(User-Agent),51d.single(DeviceType,IsMobile,IsTablet)]
102
103Any HTTP header could be used inplace of User-Agent by changing the parameter
104provided to req.fhdr.
105
106When compiled to use the Trie detection method the trie format data file needs
107to be provided. Changing the extension of the data file from dat to trie will
108use the correct data.
109
110 global
111 51degrees-data-file '51D_REPO_PATH'/data/51Degrees-LiteV3.2.trie
112
113When used with Trie the Method, Difference and Rank properties are not
114available.
115
116The free Lite data file contains information about screen size in pixels and
117whether the device is a mobile. A full list of available properties is located
118on the 51Degrees web site at:
119
120 https://51degrees.com/resources/property-dictionary
121
122Some properties are only available in the paid for Premium and Enterprise
123versions of 51Degrees. These data sets not only contain more properties but
124are updated weekly and daily and contain signatures for 100,000s of different
125device combinations. For more information see the data options comparison web
126page:
127
128 https://51degrees.com/compare-data-options