infuze csharp module user guide

WURFL InFuze Module for C# : User Guide

WURFL InFuze for C# is a C# language module wrapping the WURFL C API. InFuze for C# allows to leverage the performance of InFuze C API inside your C# applications without having to write your own binding code.

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. Release notes for each API can be found here.

Warning: The installation of libwurfl for Windows 1.8.3.0 or greater is required
Note: A .Net Framework of at least 4.5.2 is required for installation.

Getting Started

In the next sections we'll see a sample console application as well as an ASP.NET based web application example both using device detection and accessing WURFL static capabilities and virtual capabilities.

Here is a Console Application example to get started using InFuze for C# :

using WURFLInFuze;

namespace WURFLInFuzeSimpleTest
{
    class Program
    {
        static void Main(string[] args)
        {

Create the InMemoryConfigurer object setting the WURFL data file path;

            try
            {
                InMemoryConfigurer configurer = new InMemoryConfigurer()
                    .MainFile("C:\\Program Files\\Scientiamobile\\InFuze\\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).

                manager = WURFLManagerBuilder.Build(configurer);

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

                IDevice device = manager.LookupUserAgent(ua);

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

                String capName = "brand_name";
                Console.WriteLine("Static Capability {0}: {1}", cap_name, 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);

Dispose the device object when you don't need it anymore. This is necessary to release allocated resources for that instance on the WURFL C API side. It sets the C# instance as disposable for the garbage collector too.

                device.Dispose();

Dispose the manager object when you don't need it anymore. As for IDevice object, it is necessary to release allocated resources on the WURFL C API side.

                manager.Dispose();
            }

WURFL will throw a WURFLException in case of failure during the entire process

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

Static Capability filtering In order to reduce memory usage and increase performance, you can specify a subset of the 500+ WURFL static capabilities. You can set capability filters as follows:

    configurer.SelectCapabilities(new String[] { "device_os", "is_tablet" });

WURFL Lookup using HTTP Request

There is an additional method that allows for device detection using HTTP Request (accuracy is improved when HTTP Request's headers are used) :

• System.Web.HttpRequest:

    IDevice device = manager.LookupRequest(httpRequest);

WURFL Cache

By default the WURFL manager starts with a Double LRU in-memory cache to preserve the result of previous detection. It is a two-cache strategy (one going from User-Agent to Device-Id, the other from Device-Id to IDevice instance). The default parameters are 30,000, 10,000 (maximum 30,000 elements for the User-Agent to Device-Id cache and maximum 10,000 elements for the Device-Id to IDevice instance cache)

If you want to modify the cache size, you can do it in InMemoryConfigurer object:

    configurer.SetCacheSize(100000, 30000);

If you want to disable the cache feature:

    configurer.DisableCache();

WURFL Updater

If you want to keep your wurfl.zip uptodate with Scientiamobile data release schedule then you might want to use the 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 choosing from two values : Daily and Weekly (the default value is Daily). Use UpdaterSetLogPath to set updater log path where you will find detailed logs about the updater activity

There are to ways to configure the WURFL Updater:

• using IWURFLManager instance methods:

    manager.UpdaterSetDataUrl("https://data.scientiamobile.com/xxxxx/wurfl.zip");
    manager.UpdaterSetDataFrequency(WurflUpdaterFrequency.WURFL_UPDATER_FREQ_DAILY);
    //manager.UpdaterSetDataFrequency(WurflUpdaterFrequency.WURFL_UPDATER_FREQ_WEEKLY);
    manager.UpdaterSetLogPath("C:\\Temp\\updater.log");
    // start the updater explicitly
    manager.UpdaterStart();

• using InMemoryConfigurer object:

    configurer.UpdaterUrl("https://data.scientiamobile.com/xxxxx/wurfl.zip");
    configurer.UpdaterFrequency(WurflUpdaterFrequency.WURFL_UPDATER_FREQ_DAILY);
    //configurer.UpdaterFrequency(WurflUpdaterFrequency.WURFL_UPDATER_FREQ_WEEKLY);
    configurer.UpdaterLogpath("C:\\Temp\\updater.log");

Note: Using InMemoryConfigurer object you don't need to explicitly start the updater. It will be done automatically when the IWURFLManager instance is created

ASP .NET Application Usage

In an ASP.NET application, the Application_Start method is the place where you perform all one-off initializations. 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, all details are under your control through the InMemoryConfigurer object, exactly as in a Console Application.

It is also possible to specify the WURFL configuration in the web.config file. In this case, you need to 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 user-defined and needs to 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="WURFLInFuze.Aspnet.Extensions.Config.WURFLConfigurationSection, WurflInFuze.Aspnet.Extensions, Version=1.9.0.0, Culture=neutral, PublicKeyToken=816aeec277aa13b9"/>
  </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 WURFLInFuze.Aspnet.Extensions assembly so if you plan to use configuration files in a console application that does batch processing, you must reference the WURFLInFuze.Aspnet.Extensions assembly as well.

Once a WURFL manager object is instantiated, you are ready to lookup Useragent/Request.

Everything works exactly as in the Console Application example from now on.

You can lookup devices either by passing a plain User-Agent String or the whole System.Web.HttpRequest received.

var device = manager.LookupUserAgent(userAgent);

var device = manager.LookupRequest(httpRequest);

Once obtained an IDevice instance, you can access its Static Capabilities and/or Virtual Capabilities.

To get the value of a static capability or virtual capability:

var is_tablet = device.GetCapability("is_tablet");
var isSmartphone = device.GetVirtualCapability("is_smartphone");

The value associated with a capability (static or virtual) is always expressed as a string, even when it logically represents a number or a Boolean.

Don't forget do Dispose the IDevice and IWURFLManager instances when you don't need them anymore.

Capability Filtering

If you opt for configuration, you can do as follows:

<wurfl>
    <mainFile path="~/App_Data/wurfl.zip" />
    <filter caps="resolution_width,is_smarttv" />
</wurfl>

WURFL Updater

You can configure the updater feature as follows

<wurfl>
    <mainFile path="~/App_Data/wurfl.zip" />
    <updater url="https://data.scientiamobile.com/xxxxx/wurfl.zip" frequency="WURFL_UPDATER_FREQ_DAILY" logpath="~/App_Data/updater.log"/>
</wurfl>

The frequency and logpath parameters are not mandatory.

IMPORTANT - Decommissioning of WurflMatchMode options Prior to version 1.9 of the API, users could choose between WurflMatchMode.Performance and WurflMatchMode.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.
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.

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 WurflMatchMode.Performance behavior by set WurflMatchMode.FastDesktopBrowserMatch in their configuration.

Please note that users with the old WurflMatchMode.Performance target engine will not receive an error.
The old behavior will not be triggered, though. The WurflMatchMode.Default target (corresponding to the old WurflMatchMode.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.