onsite .net api

WURFL OnSite .NET API: User Guide

Installation

To enable WURFL on your application you need to download the WURFL binaries and data by registering for a free account on scientiamobile.com and download the latest release from your file manager. The wurfl.dll file must be added as a reference to any WURFL project, while the wurfl.aspnet.extensions file must be referenced only in ASP.NET projects where you plan to use WURFL. For example, you don’t strictly need to reference wurfl.aspnet.extensions if you’re using WURFL from within a console application.

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

In an ASP.NET application, the Application_Start method is the place where you perform all one-off initialization. Here's how you can instruct the method to load and cache WURFL data.

public class Global : HttpApplication
{
   public const String WurflDataFilePath = "~/App_Data/wurfl.zip";
   private void Application_Start(Object sender, EventArgs e)
   {
       var wurflDataFile = HttpContext.Current.Server.MapPath(WurflDataFilePath);
       var configurer = new InMemoryConfigurer()
                .MainFile(wurflDataFile);
       var manager = WURFLManagerBuilder.Build(configurer);
       HttpContext.Current.Cache[WurflManagerCacheKey] = manager;
   }
}

As you can see, both file names and cache details are under your control. It is also possible to specify the WURFL data files in the web.config file. In this case, you replace the call to InMemoryConfigurer with ApplicationConfigurer.

var configurer = new ApplicationConfigurer();

An example web.config:

<wurfl>
   <mainFile path="~/..." />
</wurfl>

Note that the <wurfl> section is a user-defined section and needs be registered before use with the .NET infrastructure. For this reason, you also need to add the following at the top of the web.config file:

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

You can use the ASP.NET tilde (~) operator to reference the root of your site when specifying file paths. Note that the ApplicationConfigurer class is defined in the wurfl.aspnet.extensions assembly so if you plan to use configuration files in a console application that does batch processing, then you need to reference the wurfl.aspnet.extensions assembly as well.

Once you have instantiated a WURFL manager object you are ready to begin querying WURFL. The WURFL manager has its own cache holding the entire database of device information. You can reference the WURFL manager using the following code:

var device = WURFLManagerBuilder.Instance.GetDeviceForRequest(userAgent);

A WURFL manager is an object that implements the IWURFLManager interface, as defined below:

public interface IWURFLManager
{
    IDevice GetDeviceForRequest(WURFLRequest wurflRequest);
    IDevice GetDeviceForRequest(WURFLRequest wurflRequest, MatchMode matchMode);
    IDevice GetDeviceForRequest(String userAgent);
    IDevice GetDeviceForRequest(String userAgent, MatchMode matchMode);
    IDevice GetDeviceById(String deviceId);
    IWurflInfo GetWurflInfo();
    MatchMode GetMatchMode();
}

The WURFLManager class offers a few methods for you to gain access to the in-memory representation of the detected device model. You can query for a device in a variety of ways: passing the user agent string, the device ID, or a WURFL specific request object. The WURFL specific request object - the class WURFLRequest - is merely an aggregate of data that includes the user agent string and profile.

All of the methods on the WURFL manager class return an IDevice object which represents the matched device model. The interface has the following structure:

public interface IDevice
{
   string Id { get; }
   string UserAgent { get; }
   string GetCapability(string name);
   IDictionary<string, string> GetCapabilities();
}

public interface IDevice
{
   String Id { get; }
   String UserAgent { get; }
   String NormalizedUserAgent { get; }
   String GetCapability(String name);
   IDictionary<String, String> GetCapabilities();
   IDevice GetDeviceRoot();
   IDevice GetFallbackDevice();
   String GetMatcher();
   String GetMethod();
}

To get the value of a capability:

var is_tablet = device.GetCapability("is_tablet");

If you call the GetCapabilities method you get a dictionary of name/value pairs. The value associated with a capability is always expressed as a string, even when it logically represents a number or a Boolean.

Capability Filtering

In order to reduce memory usage and increase performance, you can specify a subset of the 500+ WURFL capabilities. You can set capability filters in two ways: via configuration or programmatically. If you opt for configuration, you can do as follows:

<wurfl mode="Accuracy">
    <mainFile path="~/App_Data/wurfl-latest.zip" />
    <filter groups="product_info" caps="resolution_width,is_smarttv" />
</wurfl>

In this case, you get all the capabilities in the product_info group, plus the resolution_width and is_smarttv capabilities. Multiple groups can be expressed as comma-separated names. You can achieve the same programmatically by working on the new methods added to the InMemoryConfigurer class:

var configurer = new InMemoryConfigurer()
                .MainFile(wurflDataFile)
                .SelectGroups("product_info") 
                .SelectCapabilities("resolution_width", "is_smarttv");

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 capabilities that are found in WURFL).

In order to compute its final returned value, a virtual capability may look at regular (non-virtual) capabilities as well as other parameters that can be 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");

Variable Name Type Description
is_app enumerable Tells you if the Requesting HTTP Client is an App or not. The control capability is called is_app (virtual_capability group) and can have values default, force_true and force_false
is_smartphone enumerable 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.

is_robot enumerable 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.
is_mobile enumerable This is just an ALIAS for is_wireless_device. There's no control capability associated to this virtual capability.
is_full_desktop enumerable This is just an ALIAS for ux_full_desktop. There's no control capability associated to this virtual capability.
is_windows_phone enumerable Check if device runs any version of Windows Phone OS.

This virtual capability relies on the device_os (product_info group) capability.

is_ios enumerable Check if device runs any version of iOS.

This virtual capability relies on the device_os (product_info group) capability.

is_android enumerable Check if device runs any version of Android OS.

This virtual capability relies on the device_os (product_info group) capability.

is_touchscreen enumerable 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.
is_largescreen enumerable True if the device has a horizontal screen resolution greater than 320 pixels. Relies on the resolution_width (display group) capability.
is_wml_preferred enumerable True if the device is better served with WML. Capability relies on preferred_markup (markup group).
is_xhtmlmp_preferred enumerable True if the device is better served with XHTML MP (Mobile Profile). Capability relies on preferred_markup (markup group).
is_html_preferred enumerable True if the device is better served with HTML. Capability relies on preferred_markup (markup group).
advertised_device_os string 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).
advertised_device_os_version string This virtual capability will infer the name of the Device OS Version based on user-agent string analysis (and possibly the analysis of other HTTP headers and WURFL capabilities).
advertised_browser string 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).
advertised_browser_version string 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).
form_factor enumerable This virtual capability will return one of the following values that identify a client's form factor: Desktop, Tablet, Smartphone, Feature Phone, Smart-TV, Robot, Other non-Mobile, Other Mobile
complete_device_name string Concatenates brand name, model name and marketing name (where available) of a device into a single string.
is_phone enumerable 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.

is_app_webview enumerable This capability returns true if a HTTP request is from an app based webview.
device_name string Concatenates brand name and marketing name of a device into a single string. If marketing name is not available, model name is used instead.

License

2016 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.