diff --git a/README b/README index 79283086b..f48e640eb 100644 --- a/README +++ b/README @@ -220,199 +220,18 @@ disabled by setting USE_POLL="". For example : $ gmake TARGET=tiny USE_POLL="" TARGET_CFLAGS=-fomit-frame-pointer -1.1) DeviceAtlas Device Detection ---------------------------------- +1.1) Device Detection +--------------------- -In order to add DeviceAtlas Device Detection support, you would need to download -the API source code from https://deviceatlas.com/deviceatlas-haproxy-module and -once extracted : +HAProxy supports several device detection modules relying on third party +products. Some of them may provide free code, others free libs, others free +evaluation licenses. Please read about their respective details in the +following files : - $ make TARGET= USE_PCRE=1 USE_DEVICEATLAS=1 DEVICEATLAS_SRC= + doc/DeviceAtlas-device-detection.txt for DeviceAtlas + doc/51Degrees-device-detection.txt for 51Degrees + doc/WURFL-device-detection.txt for Scientiamobile WURFL -Optionally DEVICEATLAS_INC and DEVICEATLAS_LIB may be set to override the path -to the include files and libraries respectively if they're not in the source -directory. - -These are supported DeviceAtlas directives (see doc/configuration.txt) : - - deviceatlas-json-file . - - deviceatlas-log-level (0 to 3, level of information returned by - the API, 0 by default). - - deviceatlas-property-separator (character used to separate the - properties produced by the API, | by default). - -Sample configuration : - - global - deviceatlas-json-file - - ... - frontend - bind *:8881 - default_backend servers - -There are two distinct methods available, one which leverages all HTTP headers -and one which uses only a single HTTP header for the detection. The former -method is highly recommended and more accurate. There are several possible use -cases. - -# To transmit the DeviceAtlas data downstream to the target application - -All HTTP headers via the sample / fetch - - http-request set-header X-DeviceAtlas-Data %[da-csv-fetch(primaryHardwareType,osName,osVersion,browserName,browserVersion,browserRenderingEngine)] - -Single HTTP header (e.g. User-Agent) via the convertor - - http-request set-header X-DeviceAtlas-Data %[req.fhdr(User-Agent),da-csv-conv(primaryHardwareType,osName,osVersion,browserName,browserVersion,browserRenderingEngine)] - -# Mobile content switching with ACL - -All HTTP headers - - acl is_mobile da-csv-fetch(mobileDevice) 1 - -Single HTTP header - - acl device_type_tablet req.fhdr(User-Agent),da-csv-conv(primaryHardwareType) "Tablet" - - -Please find more information about DeviceAtlas and the detection methods at https://deviceatlas.com/resources . - - -1.2) 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 github repository : - - git clone https://github.com/51Degrees/Device-Detection - -then run 'make' with USE_51DEGREES 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 2 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. - -To make with 51Degrees Pattern algorithm use the following command line. - - $ make TARGET= USE_51DEGREES=1 51DEGREES_SRC='51D_REPO_PATH'/src/pattern - -To use the 51Degrees Trie algorithm use the following command line. - - $ make TARGET= USE_51DEGREES=1 51DEGREES_SRC='51D_REPO_PATH'/src/trie - -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. - -The configuration file needs to set the following parameters: - - global - 51degrees-data-file path to the Pattern or Trie 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, seperated 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. - -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 - - -1.3) Scientiamobile WURFL Device Detection -------------------------------- - -Please see doc/WURFL-device-detection.txt 2) How to install it -------------------- diff --git a/doc/51Degrees-device-detection.txt b/doc/51Degrees-device-detection.txt new file mode 100644 index 000000000..1ee912d96 --- /dev/null +++ b/doc/51Degrees-device-detection.txt @@ -0,0 +1,128 @@ +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 github repository : + + git clone https://github.com/51Degrees/Device-Detection + +then run 'make' with USE_51DEGREES 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 2 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. + +To make with 51Degrees Pattern algorithm use the following command line. + + $ make TARGET= USE_51DEGREES=1 51DEGREES_SRC='51D_REPO_PATH'/src/pattern + +To use the 51Degrees Trie algorithm use the following command line. + + $ make TARGET= USE_51DEGREES=1 51DEGREES_SRC='51D_REPO_PATH'/src/trie + +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. + +The configuration file needs to set the following parameters: + + global + 51degrees-data-file path to the Pattern or Trie 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, seperated 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. + +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 diff --git a/doc/DeviceAtlas-device-detection.txt b/doc/DeviceAtlas-device-detection.txt new file mode 100644 index 000000000..4ecb44a4d --- /dev/null +++ b/doc/DeviceAtlas-device-detection.txt @@ -0,0 +1,57 @@ +DeviceAtlas Device Detection +---------------------------- + +In order to add DeviceAtlas Device Detection support, you would need to download +the API source code from https://deviceatlas.com/deviceatlas-haproxy-module and +once extracted : + + $ make TARGET= USE_PCRE=1 USE_DEVICEATLAS=1 DEVICEATLAS_SRC= + +Optionally DEVICEATLAS_INC and DEVICEATLAS_LIB may be set to override the path +to the include files and libraries respectively if they're not in the source +directory. + +These are supported DeviceAtlas directives (see doc/configuration.txt) : + - deviceatlas-json-file . + - deviceatlas-log-level (0 to 3, level of information returned by + the API, 0 by default). + - deviceatlas-property-separator (character used to separate the + properties produced by the API, | by default). + +Sample configuration : + + global + deviceatlas-json-file + + ... + frontend + bind *:8881 + default_backend servers + +There are two distinct methods available, one which leverages all HTTP headers +and one which uses only a single HTTP header for the detection. The former +method is highly recommended and more accurate. There are several possible use +cases. + +# To transmit the DeviceAtlas data downstream to the target application + +All HTTP headers via the sample / fetch + + http-request set-header X-DeviceAtlas-Data %[da-csv-fetch(primaryHardwareType,osName,osVersion,browserName,browserVersion,browserRenderingEngine)] + +Single HTTP header (e.g. User-Agent) via the convertor + + http-request set-header X-DeviceAtlas-Data %[req.fhdr(User-Agent),da-csv-conv(primaryHardwareType,osName,osVersion,browserName,browserVersion,browserRenderingEngine)] + +# Mobile content switching with ACL + +All HTTP headers + + acl is_mobile da-csv-fetch(mobileDevice) 1 + +Single HTTP header + + acl device_type_tablet req.fhdr(User-Agent),da-csv-conv(primaryHardwareType) "Tablet" + + +Please find more information about DeviceAtlas and the detection methods at https://deviceatlas.com/resources . diff --git a/doc/WURFL-device-detection.txt b/doc/WURFL-device-detection.txt index 8b44813f8..c96861513 100644 --- a/doc/WURFL-device-detection.txt +++ b/doc/WURFL-device-detection.txt @@ -1,5 +1,5 @@ Scientiamobile WURFL Device Detection -------------------------------- +------------------------------------- You can also include WURFL for inbuilt device detection enabling attributes.