MEDIUM: wurfl: add Scientiamobile WURFL device detection module
WURFL is a high-performance and low-memory footprint mobile device
detection software component that can quickly and accurately detect
over 500 capabilities of visiting devices. It can differentiate between
portable mobile devices, desktop devices, SmartTVs and any other types
of devices on which a web browser can be installed.
In order to add WURFL device detection support, you would need to
download Scientiamobile InFuze C API and install it on your system.
Refer to www.scientiamobile.com to obtain a valid InFuze license.
Any useful information on how to configure HAProxy working with WURFL
may be found in:
doc/WURFL-device-detection.txt
doc/configuration.txt
examples/wurfl-example.cfg
Please find more information about WURFL device detection API detection
at https://docs.scientiamobile.com/documentation/infuze/infuze-c-api-user-guide
diff --git a/doc/WURFL-device-detection.txt b/doc/WURFL-device-detection.txt
new file mode 100644
index 0000000..8b44813
--- /dev/null
+++ b/doc/WURFL-device-detection.txt
@@ -0,0 +1,68 @@
+Scientiamobile WURFL Device Detection
+-------------------------------
+
+You can also include WURFL for inbuilt device detection enabling attributes.
+
+WURFL is a high-performance and low-memory footprint mobile device detection
+software component that can quickly and accurately detect over 500 capabilities
+of visiting devices. It can differentiate between portable mobile devices, desktop devices,
+SmartTVs and any other types of devices on which a web browser can be installed.
+
+In order to add WURFL device detection support, you would need to download Scientiamobile
+InFuze C API and install it on your system. Refer to www.scientiamobile.com to obtain a valid
+InFuze license.
+Compile haproxy as shown :
+
+ $ make TARGET=<target> USE_WURFL=1
+
+Optionally WURFL_DEBUG=1 may be set to increase logs verbosity
+
+These are the supported WURFL directives (see doc/configuration.txt) :
+- wurfl-data-file <path to WURFL data file>
+- wurfl-information-list [<string>] (list of WURFL capabilities,
+ virtual capabilities, property names we plan to use in injected headers)
+- wurfl-information-list-separator <char> (character that will be
+ used to separate values in a response header, ',' by default).
+- wurfl-engine-mode <string> (Sets the WURFL engine target. You can choose
+ between "accuracy" and "performance","performance" by default)
+- wurfl-cache-size <string> (Sets the WURFL caching strategy)
+- wurfl-patch-file [<file path>] (Sets the paths to custom WURFL patch files)
+
+Sample configuration :
+
+ global
+ wurfl-data-file /usr/share/wurfl/wurfl-eval.xml
+
+ wurfl-information-list wurfl_id model_name
+
+ #wurfl-information-list-separator |
+
+ wurfl-engine-mode performance
+ #wurfl-engine-mode accuracy
+
+ ## double LRU cache
+ wurfl-cache-size 100000,30000
+ ## single LRU cache
+ #wurfl-cache-size 100000
+ ## no cache
+ #wurfl-cache-size 0
+
+ #wurfl-patch-file <paths to custom patch files>
+
+ ...
+ frontend
+ bind *:8888
+ default_backend servers
+
+There are two distinct methods available to transmit the WURFL data downstream
+to the target application:
+
+All data listed in wurfl-information-list
+
+ http-request set-header X-WURFL-All %[wurfl-get-all()]
+
+A subset of data listed in wurfl-information-list
+
+ http-request set-header X-WURFL-Properties %[wurfl-get(wurfl_id,is_tablet)]
+
+Please find more information about WURFL and the detection methods at https://www.scientiamobile.com
diff --git a/doc/configuration.txt b/doc/configuration.txt
index 54555aa..01a0764 100644
--- a/doc/configuration.txt
+++ b/doc/configuration.txt
@@ -561,6 +561,12 @@
- 51degrees-property-name-list
- 51degrees-property-separator
- 51degrees-cache-size
+ - wurfl-data-file
+ - wurfl-information-list
+ - wurfl-information-list-separator
+ - wurfl-engine-mode
+ - wurfl-cache-size
+ - wurfl-useragent-priority
* Performance tuning
- max-spread-checks
@@ -990,6 +996,95 @@
Please note that this option is only available when haproxy has been
compiled with USE_51DEGREES.
+wurfl-data-file <file path>
+ The path of the WURFL data file to provide device detection services. The
+ file should be accessible by HAProxy with relevant permissions.
+
+ Please note that this option is only available when haproxy has been compiled
+ with USE_WURFL=1.
+
+wurfl-information-list [<capability>]*
+ A space-delimited list of WURFL capabilities, virtual capabilities, property
+ names we plan to use in injected headers. A full list of capability and
+ virtual capability names is available on the Scientiamobile website :
+
+ https://www.scientiamobile.com/wurflCapability
+
+ Valid WURFL properties are:
+ - wurfl_id Contains the device ID of the matched device.
+
+ - wurfl_root_id Contains the device root ID of the matched
+ device.
+
+ - wurfl_isdevroot Tells if the matched device is a root device.
+ Possible values are "TRUE" or "FALSE".
+
+ - wurfl_useragent The original useragent coming with this
+ particular web request.
+
+ - wurfl_api_version Contains a string representing the currently
+ used Libwurfl API version.
+
+ - wurfl_engine_target Contains a string representing the currently
+ set WURFL Engine Target. Possible values are
+ "HIGH_ACCURACY", "HIGH_PERFORMANCE", "INVALID".
+
+ - wurfl_info A string containing information on the parsed
+ wurfl.xml and its full path.
+
+ - wurfl_last_load_time Contains the UNIX timestamp of the last time
+ WURFL has been loaded successfully.
+
+ - wurfl_normalized_useragent The normalized useragent.
+
+ - wurfl_useragent_priority The user agent priority used by WURFL.
+
+ Please note that this option is only available when haproxy has been compiled
+ with USE_WURFL=1.
+
+wurfl-information-list-separator <char>
+ A char that will be used to separate values in a response header containing
+ WURFL results. If not set that a comma (',') will be used by default.
+
+ Please note that this option is only available when haproxy has been compiled
+ with USE_WURFL=1.
+
+wurfl-patch-file [<file path>]
+ A list of WURFL patch file paths. Note that patches are loaded during startup
+ thus before the chroot.
+
+ Please note that this option is only available when haproxy has been compiled
+ with USE_WURFL=1.
+
+wurfl-engine-mode { accuracy | performance }
+ Sets the WURFL engine target. You can choose between 'accuracy' or
+ 'performance' targets. In performance mode, desktop web browser detection is
+ done programmatically without referencing the WURFL data. As a result, most
+ desktop web browsers are returned as generic_web_browser WURFL ID for
+ performance. If either performance or accuracy are not defined, performance
+ mode is enabled by default.
+
+ Please note that this option is only available when haproxy has been compiled
+ with USE_WURFL=1.
+
+wurfl-cache-size <U>[,<D>]
+ Sets the WURFL caching strategy. Here <U> is the Useragent cache size, and
+ <D> is the internal device cache size. There are three possibilities here :
+ - "0" : no cache is used.
+ - <U> : the Single LRU cache is used, the size is expressed in elements.
+ - <U>,<D> : the Double LRU cache is used, both sizes are in elements. This is
+ the highest performing option.
+
+ Please note that this option is only available when haproxy has been compiled
+ with USE_WURFL=1.
+
+wurfl-useragent-priority { plain | sideloaded_browser }
+ Tells WURFL if it should prioritize use of the plain user agent ('plain')
+ over the default sideloaded browser user agent ('sideloaded_browser').
+
+ Please note that this option is only available when haproxy has been compiled
+ with USE_WURFL=1.
+
3.2. Performance tuning
-----------------------