diff options
Diffstat (limited to 'doc/51Degrees-device-detection.txt')
| -rw-r--r-- | doc/51Degrees-device-detection.txt | 174 |
1 files changed, 174 insertions, 0 deletions
diff --git a/doc/51Degrees-device-detection.txt b/doc/51Degrees-device-detection.txt new file mode 100644 index 0000000..2e31274 --- /dev/null +++ b/doc/51Degrees-device-detection.txt @@ -0,0 +1,174 @@ +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://github.com/51Degrees/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 |