WURFL OnSite .NET API: User Guide
=================================


Installation
------------

To enable WURFL on your application you must register for a free
account on scientiamobile.com and **download the latest release from
your [File Manager](https://filex.scientiamobile.com/user/index#products/onsite).**<br>
The `Wurfl.dll` file must be added as a reference to any WURFL project, while the `Wurfl.Aspnet.Extensions.dll` file must be referenced only in `ASP.NET` <br>
projects where you plan to use WURFL. For example, you don’t strictly need to reference `Wurfl.Aspnet.Extensions.dll` if you’re using WURFL
from within a `Console Application`.<br>

***Note:** As of version 1.8.1.0 a .NET Framework of at least 4.5.2 is required for installation.*

In your [File Manager](https://filex.scientiamobile.com/user/index#products/onsite) you may find a **wurfl.zip**.
The **wurfl.zip** is a database, or **Device Definition Repository (DDR)**, that holds data about all the devices known to WURFL and it's fundamental to every WURFL based application.

***Note:** The WURFL API is closely tied to the `wurfl.zip` file. New versions
of the `wurfl.zip` are compatible with old versions of the API by nature,
but the reverse is **not** true. Old versions of the `wurfl.zip` are **not**
guaranteed to be compatible with new versions of the API.*

### WURFL OnSite .NET API NuGet package
WURFL OnSite .NET API is available as a [NuGet package] (https://www.nuget.org/packages/WURFL_Official_API/) too.
To install it, run the following command in the **Package Manager Console**

```
Install-Package WURFL_Official_API
```

Getting Started
---------------
WURFL OnSite .NET API bases its operations on two main objects:

- a **WURFL Manager** object implementing the `IWURFLManager` interface.
- a **Device** object implementing the `IDevice` interface.

The **WURFL Manager** object should be instantiated only once in your application.

The **WURFL Manager** object offers several methods (among others) for you to gain access to the
in-memory representation of the **Device Definition Repository (DDR)**.<br>

```
public interface IWURFLManager
{
	.
	.
	IDevice GetDeviceForRequest(String userAgent);
	IDevice GetDeviceForRequest(HttpRequest request);
	IDevice GetDeviceById(String deviceId);
	.
	.
}
```

All of these methods return a **Device** object (implementing the `IDevice` interface) which represents the matched device model.

The **Device** object offers several methods (among others) for you to access the matched device data.

```
public interface IDevice
{
	.
	.
	String GetCapability(String name);
	String GetVirtualCapability(String name);
	IDictionary<String, String> GetCapabilities();
	IDictionary<String, String> GetVirtualCapabilities();
	String Id { get; }
	.
	.
}
```

In the next sections we'll see a sample [Console Application](/documentation/onsite/onsite-Dotnet-api#consoleusage) as well as an [ASP.NET Web based application](/documentation/onsite/onsite-Dotnet-api#aspnetusage)
, using device detection and accessing WURFL static capabilities and virtual capabilities.

<a name="consoleusage"></a>
### Console Application Usage

In your Console Application project, add the `Wurfl.dll` assembly as a reference.

***Note:** Beginning with version 1.8.4, the `System.Web` assembly must be referenced even if you
are building a `Console Application`.*

Add a new class to named **WURFLSimpleTest** to your project with the following code.

```
using WURFL;
using WURFL.Config;

namespace YourNameSpace
{
    class WURFLSimpleTest
    {
        static void Main(string[] args)
        {
```

Create the `InMemoryConfigurer` object setting the WURFL data file path;

```
            try
            {
                InMemoryConfigurer configurer = new InMemoryConfigurer()
                    .MainFile("PATH_TO_YOUR_WURFL.ZIP");

                IWURFLManager manager = null;

```

Create the WURFL manager once and then lookup UserAgent and get `Device-Id`, `Static Capabilities` and
`Virtual Capabilities` needed in your implementation (beware that Virtual Capabilities are calculated at runtime).

For further details about `Virtual Capabilities`, please see [here](/documentation/onsite/onsite-Dotnet-api#virtualcapabilities)

```
                manager = WURFLManagerBuilder.Build(configurer);

                String ua = "Dalvik/1.6.0 (Linux; U; Android 4.3; SM-N900T Build/JSS15J)";

                IDevice device = manager.GetDeviceForRequest(ua);

                Console.WriteLine("Device : {0}", device.Id);

                String capName = "brand_name";
                Console.WriteLine("Static Capability {0}: {1}", capName, device.GetCapability(capName));

                String vcapName = "is_android";
                Console.WriteLine("Virtual Capability {0}: {1}", vcapName, device.GetVirtualCapability(vcapName));
```

You can even ask to the device instance the full list of its Static Capabilities and Virtual Capabilities names and values

```
                Console.WriteLine("--- Device Static Capabilities ---");
                foreach (KeyValuePair<string, string> dCap in device.GetCapabilities())
                    Console.WriteLine("[{0}] = [{1}]", dCap.Key, dCap.Value);

                Console.WriteLine("--- Device Virtual Capabilities ---");
                foreach (KeyValuePair<string, string> vCap in device.GetVirtualCapabilities())
                    Console.WriteLine("[{0}] = [{1}]", vCap.Key, vCap.Value);
			}
```

WURFL will throw `Exceptions` in case of failure during the entire process

```
            catch (Exception e)
            {
                Console.WriteLine("WURFLSimpleTest throws this exception : {0} - {1}", e.GetType(), e.Message);
            }
        }
    }
}
```

**Static Capability filtering**<br>
In order to reduce memory usage and increase performance, you can specify a
subset of the 500+ WURFL static capabilities that will be held by the **WURFL manager** object.

You can set capability filters as follows:

```
    configurer.SelectCapabilities(new String[] { "device_os", "is_tablet" });
```
***Note:** In this case you will be able to access only the `device_os` and `is_tablet` Static Capabilities values of the detected devices.
Looking for other Static Capabilities than whose filtered, will return an empty string.*


**WURFL Cache**<br>
The WURFL manager has an `LRU` in-memory cache to preserve the result of previous detection.

If you want to enable the `LRU cache`, you can do it in `InMemoryConfigurer` object passing it the cache size:

```
    configurer.SetCacheProvider(100000);
```

**WURFL Updater**<br>

Since API version 1.8.1.1, if you want to keep your **wurfl.zip** uptodate with Scientiamobile's data release schedule, then you might want to use
the **WURFL Updater** features.

To configure the `Updater` you need to know your personal `updater url` taken from Scientiamobile customer Vault.
You may configure which periodicity (the `frequency`) you would like for update checks.

To configure the WURFL Updater, add the `Wurfl.Updater` namespace to your application.

```
using Wurfl.Updater;

```

Then, create a WURFLUpdater instance passing it the `manager` instance and your `updater url`

```
   // remember to modify the url below with your personal WURFL updater url
   WURFLUpdater updater = new WURFLUpdater(manager, "https://data.scientiamobile.com/xxxxx/wurfl.zip");
```
***Note:** the path of the **wurfl.zip** specified in the configurer at the moment of **WURFL Manager** creation must be writable from the process/task<br>
that is executing the .NET API, since `WURFLUpdater` will update the file denoted by its path.*

You can invoke the updater in two ways:

- using the **PerformUpdate()** method which performs a single update check and then stop.
```
    updater.PerformUpdate();
```

- using the **PerformPeriodicUpdate()** method which performs update checks with a periodicity you can specify
with the **SetFrequency(frequency)** method,chosing among `MINUTE` `DAILY` `THREE_DAYS` `WEEKLY` (default is `DAILY`).
```
	updater.SetFrequency(Wurfl.Updater.Frequency.WEEKLY);
	updater.PerformPeriodicUpdate();
```

If you want to stop the Periodic Update, invoke the **StopPeriodicUpdate()** method
```
	updater.StopPeriodicUpdate();
```

***Note:** The **WURFL Updater** will check to see if a new version of the wurfl.zip has been released and, if so, download it
and reload the **WURFL manager** with the new version; all while the **WURFL manager** still running and serving requests.*


<a name="aspnetusage"></a>
### ASP.NET Web Application Usage

In your ASP.NET project, add as a reference both the `Wurfl.dll` and `Wurfl.Aspnet.Extensions.dll` assemblies.

In your `App_Code` folder create a class `WurflSampleASPNETApp` which will hold the WURFL manager instance
used for lookups.

```
using WURFL;

public static class WurflSampleASPNETApp
{
    public static IWURFLManager WurflManager;
}
```

In an `ASP.NET` Web application, the `Application_Start` method for your `Global.asax` file
is the place where all one-off initializations will be performed.
Here you can instruct the method to initialiaze the WurflManager instance.

```
  .
  .
<%@ Import Namespace="WURFL" %>
<%@ Import Namespace="WURFL.Aspnet.Extensions.Config" %>
  .
  .
  .
  .

  private void Application_Start(Object sender, EventArgs e)
  {
	try
	{
		WurflSampleASPNETApp.WurflManager = WURFLManagerBuilder.Build(new ApplicationConfigurer());
	}
	catch (Exception ex)
	{
		HttpRuntime.UnloadAppDomain();
		initializationError = ex;
	}
  }
  .
  .
  .
  .
```

The WURFL configuration should be placed in your `web.config` file adding the following directives:

```
<wurfl>
   <mainFile path="~/App_Data/wurfl.zip" />
</wurfl>
```
This instructs the WurflSampleASPNETApp.WurflManager initialization to look for the *wurfl.zip*
file in your application's **App_Data** folder.

The `<wurfl>` section is user-defined and needs to be registered before use.
For this reason, you also need to add the following at the top of your `web.config` file:

```
<configuration>
  <configSections>
     <section name="wurfl" type="WURFL.Aspnet.Extensions.Config.WURFLConfigurationSection,Wurfl.Aspnet.Extensions, Version=1.9.0.0, Culture=neutral" />
  </configSections>
  :
</configuration>
```

With the WURFL manager object instantiated by Application_Start, you are ready to lookup Useragent/Request.

To perform a lookup during your `Default.aspx` page loading, place the following code in ìts `CodeBehind` (the Default.aspx.cs file)

```
  .
  .
  using WURFL;
  using WURFL.Aspnet.Extensions.Config;
  .
  .
  public partial class _Default : System.Web.UI.Page
  {
    public IDevice wurflDevice;
    public String wurflDeviceId;
	public String wurflDeviceBrandName;
	public String wurflDeviceIsAndroid;

    protected void Page_Load(object sender, EventArgs e)
    {
		/**
		* on page load we populate wurflDevice and wurflDeviceId with wurfl detection results
		**/
		wurflDevice = WurflSampleASPNETApp.WurflManager.GetDeviceForRequest(Request);
		wurflDeviceId = wurflDevice.Id;
		wurflDeviceBrandName = wurflDevice.GetCapability("brand_name");
		wurflDeviceIsAndroid = wurflDevice.GetVirtualCapability("is_android");
    }
  }
  .
  .
```

***Note:** You can lookup devices either by passing the whole HttpRequest or the simple User-Agent.
In this last case, you may use the following code*

```
        wurflDevice = WurflSampleASPNETApp.WurflManager.GetDeviceForRequest(Request.UserAgent);
```
***Note:** Using the whole HttpRequest will result in a more precise device lookup*

Now you can show the lookup result in your Default.aspx file

```
  .
  .
  <body>
      <form id="form1" runat="server">
		  <div>
			  WURFL device Id = <%= wurflDeviceId %> <br/>
			  WURFL device Brand Name = <%= wurflDeviceBrandName %> <br/>
			  WURFL device Is Android = <%= wurflDeviceIsAndroid %> <br/>
		  </div>
      </form>
   </body>
  .
  .
```

**Static Capability filtering**<br>
In order to reduce memory usage and increase performance, you can specify a
subset of the 500+ WURFL static capabilities that will be held by the **WURFL manager** object.

You can set capability filters in your `web.config` as follows:

```
<wurfl>
    <mainFile path="~/App_Data/wurfl.zip" />
    <filter caps="device_os,is_tablet" />
</wurfl>
```
***Note:** In this case you will be able to access only the `device_os` and `is_tablet` Static Capabilities values of the detected devices.
Looking for other Static Capabilities than whose filtered, will return an empty string.*

**WURFL Updater**<br>

Since API version 1.8.1.1, if you want to keep your **wurfl.zip** uptodate with Scientiamobile's data release schedule, then you might want to use
the **WURFL Updater** features.

To configure the `Updater` you need to know your personal `updater url` taken from Scientiamobile customer Vault.
You may configure which periodicity (the `frequency`) you would like for update checks.

To configure the WURFL Updater, add the `Wurfl.Updater` namespace to your `Global.asax` file and create a WURFLUpdater instance passing it the **WURFL manager** instance and your `updater url`
```
  .
  .

<%@ Import Namespace="Wurfl.Updater" %>
  .
  .
  .
  .

  private void Application_Start(Object sender, EventArgs e)
  {
      WurflSampleASPNETApp.WurflManager = WURFLManagerBuilder.Build(new ApplicationConfigurer());
      // remember to modify the url below with your personal WURFL updater url
	  WURFLUpdater updater = new WURFLUpdater(WurflSampleASPNETApp.WurflManager, "https://data.scientiamobile.com/xxxxx/wurfl.zip");
  }
  .

```
***Note:** the path of the **wurfl.zip** specified in your `web.config` must be writable from the process/task<br>
that is executing the .NET API, since `WURFLUpdater` will update the file denoted by its path.*

You can invoke the updater in two ways:

- using the **PerformUpdate()** method which performs a single update check and then stop.
```
    updater.PerformUpdate();
```

- using the **PerformPeriodicUpdate()** method which performs update checks with a periodicity you can specify
with the **SetFrequency(frequency)** method,chosing among `MINUTE` `DAILY` `THREE_DAYS` `WEEKLY` (default is `DAILY`).
```
	updater.SetFrequency(Wurfl.Updater.Frequency.WEEKLY);
	updater.PerformPeriodicUpdate();
```

If you want to stop the Periodic Update, invoke the **StopPeriodicUpdate()** method
```
	updater.StopPeriodicUpdate();
```

***Note:** The **WURFL Updater** will check to see if a new version of the wurfl.zip has been released and, if so, download it
and reload the **WURFL manager** with the new version; all while the **WURFL manager** still running and serving requests.*


<a name="virtualcapabilities"></a>
Virtual Capabilities
--------------------
Virtual capabilities are an important feature of the WURFL API that
obtain values related to the requesting agent out of the HTTP request
as a whole (as opposed to limiting itself to static capabilities that are found
in WURFL).

Virtual Capabilities are calculated at runtime; in order to compute its final
returned value, a virtual capability may look at static capabilities as well as parameters
derived from the HTTP request at run-time. Virtual capabilities
are useful to model aspects of the HTTP Client that are not easily captured
through the finite number of profiles in WURFL.

To get the value of a virtual capability:

```
var isSmartphone = device.GetVirtualCapability("is_smartphone");
```
The value associated with a virtual capability is always expressed as a string, even when
it logically represents a number or a Boolean.

<table class="table table-bordered table-striped table-hover" markdown="1">
  <thead>
    <tr style="background-color:#111;color:#E5E5E5;">
      <th>Variable Name</th>
      <th>Type</th>
      <th>Description</th>
  </thead>
  <tbody>
    <tr>
      <td>**is_app**</td>
      <td>enumerable</td>
      <td>Tells you if the Requesting HTTP Client is an App or not.
The control capability is called `controlcap_is_app` (`virtual_capability` group) and can have values `default`, `force_true` and `force_false`
</td>
    </tr>
    <tr>
      <td>**is_smartphone**</td>
      <td>enumerable</td>
      <td>This is a virtual capability that will tell you if a device is a Smartphone for some arbitrary (and subject to change) definition of Smartphone by ScientiaMobile.  

The virtual capability returns true or false.  Patch files can use the `is_smartphone` control capability to override the value returned by the virtual capability.  

Control capability `is_smartphone` can take value `default`, `force_true` and `force_false`.
</td>
    </tr>
    <tr>
      <td>**is_robot**</td>
      <td>enumerable</td>
      <td>This is a virtual capability that tells you if the HTTP Client is a Bot (robot, crawler or other programmable agent that stalks the web).  
Control capability is `is_robot` (`virtual_capability` group) and can have values `default`, `force_true` and `force_false`.
</td>
    </tr>
    <tr>
      <td>**is_mobile**</td>
      <td>enumerable</td>
      <td>This is just an ALIAS for `is_wireless_device`. There&#039;s no control capability associated to this virtual capability.</td>
    </tr>
    <tr>
      <td>**is_full_desktop**</td>
      <td>enumerable</td>
      <td>This is just an ALIAS for `ux_full_desktop`. There&#039;s no control capability associated to this virtual capability.</td>
    </tr>
    <tr>
      <td>**is_windows_phone**</td>
      <td>enumerable</td>
      <td>Check if device runs any version of Windows Phone OS. 

This virtual capability relies on the `device_os` (`product_info` group) capability.</td>
    </tr>
    <tr>
      <td>**is_ios**</td>
      <td>enumerable</td>
      <td>Check if device runs any version of iOS.

This virtual capability relies on the `device_os` (`product_info` group) capability.</td>
    </tr>
    <tr>
      <td>**is_android**</td>
      <td>enumerable</td>
      <td>Check if device runs any version of Android OS. 

This virtual capability relies on the `device_os` (`product_info` group) capability.</td>
    </tr>
    <tr>
      <td>**is_touchscreen**</td>
      <td>enumerable</td>
      <td>This virtual capability tells you whether a device has a touch screen. There is no control capability. Mostly an alias for `pointing_method` == `touchscreen` (`product_info` group) capability.</td>
    </tr>
    <tr>
      <td>**is_largescreen**</td>
      <td>enumerable</td>
      <td>True if the device has a horizontal screen resolution greater than 320 pixels. Relies on the `resolution_width` (`display` group) capability.</td>
    </tr>
    <tr>
      <td>**is_wml_preferred**</td>
      <td>enumerable</td>
      <td>True if the device is better served with WML. Capability relies on `preferred_markup` (`markup` group).</td>
    </tr>
    <tr>
      <td>**is_xhtmlmp_preferred**</td>
      <td>enumerable</td>
      <td>True if the device is better served with XHTML MP (Mobile Profile). Capability relies on `preferred_markup` (markup group).</td>
    </tr>
    <tr>
      <td>**is_html_preferred**</td>
      <td>enumerable</td>
      <td>True if the device is better served with HTML. Capability relies on `preferred_markup` (markup group).</td>
    </tr>
    <tr>
      <td>**advertised_device_os**</td>
      <td>string</td>
      <td>This virtual capability will infer the name of the Device OS based on user-agent string analysis (and possibly the analysis of other HTTP headers and WURFL capabilities).</td>
    </tr>
    <tr>
      <td>**advertised_device_os_version**</td>
      <td>string</td>
      <td>This virtual capability will infer the version of the Device OS based on user-agent string analysis (and possibly the analysis of other HTTP headers and WURFL capabilities).</td>
    </tr>
    <tr>
      <td>**advertised_browser**</td>
      <td>string</td>
      <td>This virtual capability will infer the name of the browser based on user-agent string analysis (and possibly the analysis of other HTTP headers and WURFL capabilities).</td>
    </tr>
    <tr>
      <td>**advertised_browser_version**</td>
      <td>string</td>
      <td>This virtual capability will infer the version of the browser based on user-agent string analysis (and possibly the analysis of other HTTP headers and WURFL capabilities).</td>
    </tr>
    <tr>
      <td>**form_factor**</td>
      <td>enumerable</td>
      <td>This virtual capability will return one of the following values that identify a client&#039;s form factor: `Desktop`, `Tablet`, `Smartphone`, `Feature Phone`, `Smart-TV`, `Robot`, `Other non-Mobile`, `Other Mobile`</td>
    </tr>
    <tr>
      <td>**complete_device_name**</td>
      <td>string</td>
      <td>Concatenates brand name, model name and marketing name (where available) of a device into a single string.</td>
    </tr>
    <tr>
      <td>**is_phone**</td>
      <td>enumerable</td>
      <td>This is a virtual capability that will tell you if a device is a mobile phone .  

The virtual capability returns true or false.  Patch files can use the `is_phone` control capability to override the value returned by the virtual capability.  

Control capability `is_phone` can take value `default`, `force_true` and `force_false`.</td>
    </tr>
    <tr>
      <td>**is_app_webview**</td>
      <td>enumerable</td>
      <td>This virtual capability returns true if a HTTP request is from an app based webview.</td>
    </tr>
    <tr>
      <td>**device_name**</td>
      <td>string</td>
      <td>Concatenates brand name and marketing name of a device into a single string. If marketing name is not available, model name is used instead.</td>
    </tr>
    <tr>
      <td>**advertised_app_name**</td>
      <td>string</td>
      <td>This virtual capability will return the name of the application that generated the User-Agent or the HTTP request.</td>
    </tr>
  </tbody>
</table>

*<b>`IMPORTANT - Decommissioning of MatchMode options`</b> Prior to version 1.9 of the API, users could choose between `MatchMode.Performance` and `MatchMode.Accuracy` engine optimization options.
These options had been introduced years ago to manage the behavior of certain web browsers and their tendency to present "always different" User-Agent strings that would baffle strategies to cache
similar WURFL queries in memory.<br>As the problem has been solved by browser vendors, the need to adopt this strategy has diminished and ultimately disappeared (i.e. there was no longer much to be gained with the performance mode in most circumstances)
and ScientiaMobile elected to "remove" this option to simplify configuration and go in the direction of uniform API behavior in different contexts.
<br><br>When we wrote "remove" in the previous sentence, we were not being totally accurate. Customers who may find themselves in the unlikely situation of having to analyze significant amounts of
legacy web traffic, may still enable the old `MatchMode.Performance` behavior by set `MatchMode.FastDesktopBrowserMatch` in their configuration.
<br><br>Please note that users with the old `MatchMode.Performance` target engine will not receive an error.<br>The old behavior will not be triggered, though. The `MatchMode.Default` target (corresponding to the old `MatchMode.Accuracy`) will be used instead.*


License
-------

2017 ScientiaMobile Incorporated
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.