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.

To enable WURFL InFuze for C# on your application, you must download it from your File Manager.
The WurflInFuze.dll file must be added as a reference to any WURFL project, while the WurflInFuze.Aspnet.Extensions.dll file must be referenced only in ASP.NET projects where you plan to use WURFL InFuze for C#.
For example, you don’t strictly need to reference WurflInFuze.Aspnet.Extensions.dll if you’re using WURFL InFuze for C# from within a Console Application.

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 Web based application , using device detection and accessing WURFL static capabilities and virtual capabilities.

Console Application Usage

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}", 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);

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 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 unfiltered Static Capabilities will return an empty string.

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's 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 Web Application Usage

In your ASP.NET project, add the WurflInFuze.dll and WurflInFuze.Aspnet.Extensions.dll files as a reference.

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 in 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="WURFLInFuze" %>
<%@ Import Namespace="WURFLInFuze.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="WURFLInFuze.Aspnet.Extensions.Config.WURFLConfigurationSection, WurflInFuze.Aspnet.Extensions, Version=1.9.0.0, Culture=neutral, PublicKeyToken=816aeec277aa13b9"/>
  </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 WURFLInFuze;
  using WURFLInFuze.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.LookupRequest(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.LookupUserAgent(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>
  .
  .

You can lookup devices either by passing a plain User-Agent String or the

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.

Static Capability filtering

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="resolution_width,is_smarttv" />
</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 unfiltered Static Capabilities will return an empty string.

WURFL Updater

If you want to keep your wurfl.zip uptodate with Scientiamobile's 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 logpath to set updater log path where you will find detailed logs about the updater activity

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