WURFL InFuze Module for HAProxy: User Guide
=========================================

This document is aimed at developers and system administrators who intend to install and configure the WURFL InFuze Module for HAProxy on Unix, Linux, and other Unix-based systems.

Installing libwurfl
-------------------

In order for the Module to work it is **ESSENTIAL** that the `libwurfl` library is installed on your system.
`libwurfl` is provided in your Customer Vault/FileX.

If you have not already installed libwurfl,
instructions can be found [here](https://docs.scientiamobile.com/documentation/infuze/infuze-c-api-user-guide).
Release notes for each API can be found [here](https://docs.scientiamobile.com/documentation/changelog/infuze-api-change-log).

Installing HAProxy
------------------

WURFL device detection is included in the HAProxy source code from [release 1.7-dev6](http://www.haproxy.org/download/1.7/src/devel/). You are required to download and compile the
HAProxy source code including WURFL device detection: please refer to the HAProxy documentation for build instructions. You will need the WURFL InFuze C API (libwurfl) installed on your system at compile time
(refer to "Installing libwurfl" above).
To enable WURFL device detection, you will need to add `USE_WURFL=1` to your HAProxy compile command as shown below:

```shell
$ make TARGET=<target> USE_WURFL=1
```

Optionally `WURFL_DEBUG=1` can be set to increase logging verbosity.

Configuration Guide
-------------------

The following are supported WURFL directives (see doc/configuration.txt in your HAProxy source tree):

* 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-cache-size <string> (Sets the WURFL caching strategy)
* wurfl-patch-file [<file path>](Sets the paths to custom WURFL patch files)

Sample configuration file:

```nginx
global
wurfl-data-file /usr/share/wurfl/wurfl-eval.xml

wurfl-information-list wurfl_id model_name is_tablet

#wurfl-information-list-separator |

## 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 WURFL data downstream
to the target application:

All data listed in wurfl-information-list

```nginx
http-request set-header X-WURFL-All %[wurfl-get-all()]
```

A subset of data listed in wurfl-information-list

```nginx
http-request set-header X-WURFL-Properties %[wurfl-get(wurfl_id,is_tablet)]
```

Based on the configuration above, the `X-WURFL-All` header value will result in something like<br>
```
google_chrome_66,Chrome,false
```
(all wurfl informations configured in wurfl-information-list, in the same order as listed, separated by a comma)

whereas the `X-WURFL-Properties` header value will result in something like<br>
```
google_chrome_66,false
```
(only wurfl_id and is_tablet informations, in the same order as listed in `wurfl-get()` call, separated by a comma)

WURFL Properties
----------------

wurfl-information-list configuration directive may include:

**properties**

  - `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 user agent coming with this particular web request
  - `wurfl_api_version`           Contains a string representing the currently used Libwurfl API version
  - `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 user agent.
  - `wurfl_useragent_priority`    The user agent priority used by WURFL.

**Capabilities and virtual capabilities**

Refer to [WURFL capabilities](https://www.scientiamobile.com/capabilities) for all capabilities and virtual capabilities names.


-------

**&copy; 2024 ScientiaMobile Inc.<br>
All Rights Reserved.**

**NOTICE:** All information contained herein is, and remains the property of ScientiaMobile Incorporated
and its suppliers, if any.  The intellectual and technical concepts contained herein are proprietary to
ScientiaMobile Incorporated and its suppliers and may be covered by U.S. and Foreign Patents, patents
in process, and are protected by trade secret or copyright law. Dissemination of this information or
reproduction of this material is strictly forbidden unless prior written permission is obtained from
ScientiaMobile Incorporated.