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

This document will help you install and configure WURFL IIS on Windows Server 2003,
2008, and 2012. WURFL IIS is an IIS ISAPI plugin that adds selected HTTP headers to
every request received by IIS Server. Added headers will contain values for the WURFL
Static/Virtual Capabilities selected in the configuration file related to the User Agent of the current
request.

Installing the WURFL InFuze Module for IIS
------------------------------------------

WURFL IIS is distributed as a Windows installer package for 64 bit Windows versions.

Once the package is installed, go to your Server Manager -> IIS Manager, select the site you want
to add WURFL IIS to -> ISAPI FIlter -> Add : Filter Name : WURFL IIS, Executable :<br>
`C:\Program Files\Scientiamobile\WURFL ISAPI\wurfl-isapi.dll`
*__Warning:__ Since version 1.8.3.0: the installation of `libwurfl for Windows 1.8.3.0 or greater` is required and the default installation folder is `C:\Program Files\Scientiamobile\WURFLIsapi\` `libwurfl` is provided in your Customer Vault/FileX*


Configuration
-------------

Once the plugin is installed, navigate to your installation folder and edit the `wurfl-conf.xml` configuration file to inject the headers that your web application will need.

### Single site configuration example

Let's assume our IIS Server hosts a single website **www.mywebsite.com**
The `wurfl-conf.xml` configuration file should contain a single `<WurflIIS>` section whose `site` attribute value is the regex matching the site `FQN`.

```xml
<WurflIISServer>

    <WurflIIS name="default" site="www\.mywebsite\.com">

        <WurflRoot>wurfl.zip</WurflRoot>

        <!-- WURFL Updater allows seamless update of WURFL engine with new data downloaded from Scientiamobile. -->
        <!-- Updater configuration must be done after <WurflRoot>, which must be a writable path, and a wurfl.zip file must already be present in order for the updater to check the file.-->
        <!-- Put your personal updater url taken from Scientiamobile customer Vault. -->
        <!-- WURFL Updater url file type and WurflRoot must match (.zip or .xml.gz ) -->
        <!-- Valid values for the updater checking frequency (how often the updater checks for any new WURFL data file -->
        <!-- to be downloaded and used by the engine) are DAILY,WEEKLY  (default value is DAILY) -->
        <!-- Updater log file (wurfl-updater-log.txt) may be found in WURFL Isapi installation folder. -->
        <!-- The folder and WURFL data file must writable by IIS -->
        <!-- <WurflUpdater frequency='DAILY'>https://data.scientiamobile.com/xxxxx/wurfl.zip</WurflUpdater> -->

        <!-- <WurflPatch>patch.xml</WurflPatch> -->
        <!-- <WurflPatch>...</WurflPatch> -->
        <!-- <WurflPatch>...</WurflPatch> -->

        <!-- WURFL Cache: one of the following-->
        <WurflCache params="100000">single_lru</WurflCache>
        <!-- <WurflCache>null</WurflCache> -->

        <!-- By default wurfl static/virtual capability names are mapped to WURFLCAP_[upper(capability name)] http header
            hence for example static capability ux_full_desktop will be mapped to HTTP header
            WURFLCAP_UX_FULL_DESKTOP -->
        <WurflRequestCapability>ux_full_desktop</WurflRequestCapability>
        <WurflRequestCapability>is_tablet</WurflRequestCapability>
        <WurflRequestCapability>is_wireless_device</WurflRequestCapability>

        <!-- You may have a custom HTTP header name specified in the tag attribute "header" -->
        <WurflRequestCapability header="DEVICE_OPERATING_SYSTEM">device_os</WurflRequestCapability>

        <!--
        <WurflRequestCapability>device_os_version</WurflRequestCapability>
        <WurflRequestCapability>pointing_method</WurflRequestCapability>
        <WurflRequestCapability>preferred_markup</WurflRequestCapability>
        <WurflRequestCapability>resolution_height</WurflRequestCapability>
        <WurflRequestCapability>resolution_width</WurflRequestCapability>
        <WurflRequestCapability>xhtml_support_level</WurflRequestCapability>
        <WurflRequestCapability>is_smarttv</WurflRequestCapability>
        <WurflRequestCapability>can_assign_phone_number</WurflRequestCapability>
        <WurflRequestCapability>brand_name</WurflRequestCapability>
        <WurflRequestCapability>model_name</WurflRequestCapability>
        <WurflRequestCapability>marketing_name</WurflRequestCapability>
        <WurflRequestCapability>is_touchscreen</WurflRequestCapability>
        -->

        <!-- Urls blacklist: all urls matching the following regex will be excluded from wurfl headers injection -->
        <!-- <WurflDoNotProcessUrl> -->

            <!-- Excludes all .ico files from processing-->
            <!-- <WurflUrl name="BlackList-Rule-1">.*\.ico</WurflUrl> -->

            <!-- Excludes all files in "img" folder from processing-->
            <!-- <WurflUrl name="BlackList-Rule-2">.*\/img\/.*</WurflUrl> -->

        <!-- </WurflDoNotProcessUrl> -->

        <!-- Urls whitelist: all urls matching the following regex will be injected with wurfl headers -->
                <!-- if no WurflProcessUrl section is present default action is to inject, no need for a catchall rule -->
        <!-- <WurflProcessUrl> -->

            <!-- Includes all .jpg files in processing-->
            <!-- <WurflUrl name="WhiteList-Rule-2">.*\.jpg</WurflUrl> -->

        <!-- </WurflProcessUrl> -->

        <!-- <WurflLogHeaderInjection>true</WurflLogHeaderInjection> -->
        <!-- default -->
        <!-- <WurflLogHeaderInjection>false</WurflLogHeaderInjection> -->

    </WurflIIS>

</WurflIISServer>
```

You can insert as many `<WurflRequestCapability>` tags as you need in your `wurfl-conf.xml` file, with
each static capability (or virtual capability) resulting in a new HTTP header.  A full list of capabilities can be found
[here](https://www.scientiamobile.com/capabilities).

### Multiple sites configuration examples

Let's assume our IIS Server hosts two websites **www.firstwebsite.com** and **www.secondwebsite.com**.
If we want to use different configurations for each website, the `wurfl-conf.xml` configuration file should contain two `<WurflIIS>` sections:

- one with `site` property value = `www\.firstwebsite\.com`
- one with `site` property value = `www\.secondwebsite\.com`

```xml
<WurflIISServer>

    <WurflIIS name="first" site="www\.firstwebsite\.com">
        <WurflRoot>wurfl.zip</WurflRoot>
        .
        .
    </WurflIIS>

    <WurflIIS name="second" site="www\.secondwebsite\.com">
        <WurflRoot>wurfl.zip</WurflRoot>
        .
        .
    </WurflIIS>
</WurflIISServer>
```

Let's assume our IIS Server hosts websites under `com` TLD and `net` TLD.
If we want to use different configurations for each TLD, the `wurfl-conf.xml` configuration file should contain two `<WurflIIS>` sections:

- one with `site` property value = `.*\.com`
- one with `site` property value = `.*\.net`

```xml
<WurflIISServer>

    <WurflIIS name="com" site=".*\.com">
        <WurflRoot>wurfl.zip</WurflRoot>
        .
        .
    </WurflIIS>

    <WurflIIS name="net" site=".*\.net">
        <WurflRoot>wurfl.zip</WurflRoot>
        .
        .
    </WurflIIS>
</WurflIISServer>
```

If we want to use the same configurations for each TLD, the `wurfl-conf.xml` configuration file should contain only one `<WurflIIS>` section:

```xml
<WurflIISServer>

    <WurflIIS name="allsites" site=".*">
        <WurflRoot>wurfl.zip</WurflRoot>
        .
        .
    </WurflIIS>
</WurflIISServer>
```

Configuration Tags details
--------------------------

<div markdown="1">
<table class="table table-bordered table-striped table-hover" markdown="1">
<thead>
    <tr style="background-color:#111;color:#E5E5E5;">
        <th>Tag</th>
        <th>Description</th>
        <th>Availability</th>
    </tr>
</thead>
<tbody>
    <tr>
        <td><strong>&lt;WurflIISServer&gt;</strong></td>
        <td>Aggregates the WURFL engines configurations for local IIS Server<br>
        <strong>Context:</strong>`root`<br>
        <strong>Type:</strong>`mandatory`
        </td>
        <td>1.7.0.1</td>
    </tr>
    <tr>
        <td><strong>&lt;WurflIIS&gt;</strong></td>
        <td>Contains the configuration for a subset (WURFL engine) of the web sites hosted by local IIS Server<br>
        <strong>Type:</strong>`mandatory`<br>
        <strong>Context:</strong>`<WurflIISServer>`<br>
        <strong>Attributes:</strong><br>
        `name`: a symbolic name for the web sites managed by the nested configuration for logging purposes<br>
        `site`: a regex representing web site URLs managed by the nested configuration. WURFL Isapi filter will check the HTTP Request against this regex
        to determine which WURFL engine will manage the incoming HTTP Request.
        </td>
        <td>1.7.0.1</td>
    </tr>
    <tr>
        <td><strong>&lt;WurflRoot&gt;</strong></td>
        <td>Defines the location (path) of the WURFL data file.<br>
        <strong>Type:</strong>`mandatory`<br>
        <strong>Context:</strong>`<WurflIIS>`<br>
        <strong>Value:</strong>: the full path of the WURFL data file<br>
        </td>
        <td>1.6.4</td>
    </tr>
    <tr>
        <td><strong>&lt;WurflUpdater frequency="DAILY"&gt;</strong></td>
        <td>Allows seamless update of the WURFL Engine with new data downloaded from Scientiamobile.</br>
        The tag `<WurflRoot>` must precede it.</br>
        <strong>Type:</strong>`not mandatory`</br>
        <strong>Context:</strong>`<WurflIIS>`</br>
        <strong>Value:</strong>: the `data url` (taken from your personal Scientiamobile Vault account, choosing between
         two data file types: `.zip` or `.xml.gz`)</br>
        Take care that `<WurflRoot>` file type and `<WurflUpdater>` `data url` file type match so you may need to change
          the `<WurflRoot>` file type accordingly.</br>
        <strong>Attributes:</strong>`frequency` (how often the updater checks for any new WURFL data file
        to be downloaded and used by the engine) whose value you can choose between `DAILY` and `WEEKLY` (default value is `DAILY`)</br>
        </br>
        In order to let the Updater perform its activities both the `<WurflRoot>` folder and file must be writable by IIS.</br>
        The `wurfl-updater-log.txt` file in WURFL Isapi installation folder will contains details on Updater activity.
        </td>
        <td>1.8.3</td>
    </tr>
    <tr>
        <td><strong>&lt;WurflPatch&gt;</strong></td>
        <td>Adds one or more custom patch files to the WURFL repository.<br>
        <strong>Type:</strong>`not mandatory`<br>
        <strong>Context:</strong>`<WurflIIS>`<br>
        <strong>Value:</strong>: the full path of patch file<br>
        </td>
        <td>1.6.4</td>
    </tr>
    <tr>
        <td><strong>&lt;WurflEngineTarget&gt;</strong></td>
        <td><b>`This configuration option is deprecated and will be removed in a future release.`</b></td>
        <td>1.6.4</td>
    </tr>
    <tr>
        <td><strong>&lt;WurflCache params="100000"&gt;single_lru&lt;WurflCache&gt;</strong><br>or<br><strong>&lt;WurflCache&gt;null&lt;WurflCache&gt;</strong></td>
        <td>In order to increase performance while processing real HTTP traffic, we suggest setting up an `LRU` cache.
        The `LRU` caching strategy will speed up lookup operations on processed User Agents by keeping them in an LRU map.
        By default the cache will be set to 30000 entries, which accounts for 7 to 10 MB of additional memory usage.
        Specific concerns regarding memory usage apart, users are advised to size their cache generously (100,000 or more) to increase performance.
        For more information, please see [LRU Cache Mechanism](http://en.wikipedia.org/wiki/Cache_algorithms#Least_Recently_Used).<br>
        <strong>Type:</strong>`not mandatory`<br>
        <strong>Context:</strong>`<WurflIIS>`<br>
        </td>
        <td>1.6.4</td>
    </tr>
    <tr>
        <td><strong>&lt;WurflRequestCapability&gt;</strong></td>
        <td>Defines one or more WURFL Static/Virtual Capabilities values to be injected in the
        Request as HTTP headers.<br>
        <strong>Type:</strong>`not mandatory`<br>
        <strong>Context:</strong>`<WurflIIS>`<br>
        </td>
        <td>1.6.4</td>
    </tr>
    <tr>
        <td><strong>&lt;WurflUserAgentPriority&gt;</strong></td>
        <td><b>`This configuration option is deprecated and will be removed in a future release.`</b></td>
        <td>1.6.4</td>
    </tr>
    <tr>
        <td><strong>&lt;WurflLogHeaderInjection&gt;</strong></td>
        <td>Logs header injection activity<br>
        <strong>Type:</strong>`not mandatory`<br>
        <strong>Context:</strong>`<WurflIIS>`<br>
        <strong>Value:</strong>`true`/`false` (default value is `false`)<br>
        </td>
        <td>1.6.4</td>
    </tr>
    <tr>
        <td><strong>&lt;WurflDoNotProcessUrl&gt;</strong></td>
        <td>URLs blacklist section: all URLs matching the contained regex will be excluded from wurfl headers injection.<br>
        <strong>Context:</strong>`<WurflIIS>`
        </td>
        <td>1.7.0.1</td>
    </tr>
    <tr>
        <td><strong>&lt;WurflProcessUrl&gt;</strong></td>
        <td>URLs whitelist section: all URLs matching the contained regex will be injected with wurfl headers.<br>
        <strong>Context:</strong>`<WurflIIS>`
        </td>
        <td>1.7.0.1</td>
    </tr>
    <tr>
        <td><strong>&lt;WurflUrl&gt;</strong></td>
        <td>An url to match<br>
        <strong>Context:</strong>`<WurflProcessUrl>` `<WurflDoNotProcessUrl>`<br>
        <strong>Value:</strong> the regex representing the url<br>
        <strong>Attributes:</strong>`name`: a symbolic name for the URL, for logging purposes<br>
    </td>
        <td>1.7.0.1</td>
    </tr>
</tbody>
</table>
</div>

-------

**&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.