This user guide explains how to set up the 51Degrees.mobi Foundation and the various configuration options. Most questions about the Foundation can be answered in this guide. If you are looking to upgrade from v0.x or v1.x to v2 to make use of our new device data, see section 2.3.

Note: If you edit configuration settings in files other than the web.config file you will need to restart IIS for the changes to become active.

1. Configuration Section
2. fiftyOne Section Element
2.1 Redirect Element
2.1.1 Locations Collection
2.1.2 Dynamic Location URLs
2.2 Log Element
2.3 Detection Element
2.3.1 binaryFiles and xmlFiles Elements
2.4 Detector Module
2.5 .NET 4 Support

1. Configuration Section

The following settings are needed at the top of the web.config file. Alternatively, they (and the rest of the Foundation configuration) can be placed in a file called '51Degrees.mobi.config' in the App_Data folder. This is to allow integration into Content Management Systems that separate the user away from the web.config. This part tells ASP.NET about subsequent configurations in the config and how to handle them. In this instance we are telling .NET to use the FiftyOne.Foundation assembly and classes to process the configuration elements.

2. fiftyOne Section Element

You need to add the following element after the configSections element. These lines control how 51Degrees.mobi responds to mobile devices, where to locate the database of mobile devices, and whether to log events to a file. An example is shown below:

Each element in the fiftyOne section plays an important role in the way devices are detected and redirected. Each element is explained separately in the following paragraphs. None of the elements is mandatory and some elements can be omitted depending on your requirement.

2.1 Redirect Element

This element determines how mobile devices should be redirected. If it is omitted, redirection will be disabled. 51Degrees.mobi will continue to detect mobile devices and update the properties exposed through the Request.Browser collection.

Attributes	Mandatory	Description
mobileHomePageUrl	No (0.1.11.4 onwards)	A URL that will become the 'home page' for mobile devices (instead of the regular web site landing page). This is no longer mandatory as it can be completely replaced with the locations section, explained below. Otherwise it will redirect all mobile devices, including tablets.
firstRequestOnly	No	If set to 'true', only the first request received by the web site is redirected to the mobileHomePageUrl when the site is accessed from a mobile device. This allows developers to allow those using mobile devices to visit the standard site if they wish by placing a link to it within their mobile site. (Defaults to true)
Timeout	No	The number of minutes of inactivity that should occur before the requesting device is treated as making a new request to the web site for the purposes of redirection. If the session is available, the session timeout will be used and will override this value. (Defaults to 20 minutes)
devicesFile	No	A file used to store the details of devices that have previously accessed the web site to determine if they are making a subsequent request. The application pool identity must have read, write and modify access to the file. This setting is needed to ensure multiple worker processes have a consistent view of previous activity. (Random behaviour will be experienced if not specified on web sites with more than one worker process)
mobilePagesRegex	No	A regular expression that - when applied to the current request Path (context.Request. AppRelativeCurrentExecutionFilePath) - will return true if it should be considered a mobile page. Use this attribute to tell redirection about mobile pages derived from base classes such as System.Web.UI.Page. Redirection needs to be aware of mobile pages so that requests to these pages can be ignored and won’t be redirected. To enable automatic redirection on pages other than those in the /Mobile directory, this setting will appear as mobilePagesRegex="~/Mobile/". Any page that derives from System.Web.UI.MobileControls.MobilePage will automatically be treated as a mobile page irrespective of this attribute.
originalUrlAsQueryString	No	(Version 0.1.11.1 onwards) If set to 'true', the redirected URL will have the original requesting URL encoded and included as the origUrl query string parameter in the redirected URL. This will enable the mobile home page to determine the original requested resource, providing the option to display a mobile-friendly version.

Note: The URL defined by mobileHomePageUrl and the LoginUrl exposed through the property FormsAuthentication.LoginUrl will never be redirected. Redirecting these pages may prevent web sites operating as intended. Do not make the Login page the same as the main home page.

2.1.1 Locations Collection

locations is a collection of location elements that can be optionally provided under the redirect element. Location elements are evaluated in order to determine if they should be applied to the request and, if so, what URL should be used for the redirection. For example; a specific redirect location could be defined for tablet devices using the IsTablet capability. The following example shows two location elements. The first redirects tablets while the second is standard mobile device redirection.

The following tables should the attributes available for the location element.

Attributes	Mandatory	Description
name	Yes	(Version 0.1.11.7 onwards) A unique identifier for that location. This name is also used for debugging in the log file.
url	Yes	The URL of the redirect location to use if all the properties in the collection match.
matchExpression	No	Can be used to provide a regular expression which will take the requesting URL as input match segments to be used in place of numeric parameters contained within {} in the URL attribute.

Each location element must have one or more filter (add) properties added to it. All the filter properties need to evaluate to true for the location to be used. The following table provides the attributes used by the add element.

Attributes	Mandatory	Description
property	Yes	A property of HttpRequest, HttpRequest.Browser or device data capability to use when evaluating the matchExpression attributes. See here for a full list of data attributes.
matchExpression	Yes	A regular expression used to evaluate the value of the property.

If no location matches then the mobileHomePageUrl attribute of the redirect element (if provided) will be used if the requesting device is a mobile device.

2.1.2 origUrl Property

The location elements property attribute can also contain the value origUrl. This property will return the value of the original URL requested and can be used to turn redirection on or off based on the content of the URL. The following example could be used to redirect requests to the home page via the URL http://example.com only.

<locations>

  <location name="Home" url="~/Mobile/Default.aspx">

   <add property="IsTablet" matchExpression="true"/>

   <add property="IsMobile" matchExpression="true"/>

   <add property="origUrl" matchExpression="^http://example.com$"/>

  </location>

</locations>

2.1.3 Dynamic Location URLs

The attribute matchExpression of the location element can be used to provide a regular expression that will extract one or more segments from the original URL. These segments can then be used to replace numeric parameter values within the url attribute value.

The following example will match everything from the original URL after the host name and replace the {0} with this value. Therefore the URL http://example.com/AboutUs.aspx would become http://example.com/Tablet/AboutUs.aspx if accessed from a tablet device.

Notice the 'less than' sign < in the regular expression needs to be encoded as &lt;

2.2 log Element

Include this element to log events.

Attributes	Mandatory	Description
logFile	Yes	The location of the log file.
logLevel	No	Values include Debug|Info|Warn|Fatal and control the level of information logged. Defaults to Fatal if not specified.

To disable logging, remove the log element. It is not mandatory.

2.3 detection Element

The detection element replaces the wurfl element used in previous versions of the Foundation (v0.x, v1.x). Due to licencing changes from ScientiaMobile, the 51Degrees.mobi Foundation no longer supports WURFL data and instead uses 51Degrees.mobi Device Data. To convert an existing v1.x installation, Foundation v2.x or greater needs to be downloaded and the wurfl element removed. The latest version can be downloaded here. For more information about 51Degrees.mobi Device Data, including free Lite and paid-for Premium options, click here.

The following settings control where 51Degrees.mobi finds device data and the capabilities to load. The detection element is not mandatory; if the section is missing or the device data is missing or corrupt, the Foundation reverts to an embedded Lite device file included in the DLL.

2.3.1 binaryFiles and xmlFiles

The binaryFiles and xmlFiles elements are used to the tell the Foundation where to find device data files. They both have the same attributes, the only difference is that they are used with the two different file formats. 

Each xml file needs to be added with an 'Add' element. Binary and xml files can be used in any combination.

 

Attributes	Mandatory	Description
name	Yes	Descriptive names of the file for your reference.
filePath	Yes	A relative or absolute path to the data patch file.
enabled	Yes	True if the patch file should be included when the API loads device data. False if it should be ignored.

2.3.2 Premium Device Data Licence Key

To activate Premium Device Data, place the purchased licence key in the a file named with the extension .lic in the applications bin folder. This is the same folder as the FiftyOne.Foundation.dll file.

Alternatvely, you can embed the licence in the source. You will need to download the source from Codeplex. You can then find the required constants in 'FiftyOne.Foundation/Properties/Constants.cs'. You should see this line code:


If the licence key is invalid, 51Degrees.mobi Foundation will not be able to download automatic updates. To find out more about Premium Device Data, click here.

2.4 Detector Module

As of Version 0.1.11.8, this section is required in .NET 2.0 and .NET 3.5 but optional in .NET 4.0. Instead .NET 4.0 may use global.asax instead of web.config to load the correct modules.

This final section of the web.config file tells .NET to include 51Degrees.mobi Foundation whenever processing HTTP Requests, Application Initiation and other significant web events. Without these settings, Foundation won't be able to enhance browser data or redirect to a mobile specific landing page.

Note: These elements have to be placed in the web.config file even if the previous configuration settings were placed in 51Degrees.mobi.config.

IIS 6.0 and Visual Studio

IIS 7.x code

2.5 .NET v4 Support

Under .NET v4 the Foundation can optionally be configured without the need to add modules to the web.config file. The Foundation DLL invokes itself automatically from your site's bin folder. This .NET v4 enhancement simplifies the web.config file and marginally improves performance. The web.config file can continue to be used with HttpModules if required for backwards compatibility, but only one method can be used or unpredictable behaviour may occur.

Two projects files are used to generate different versions of the FiftyOne.Foundation dll.

• FiftyOne.Foundation 4 = .NET v4
• FiftyOne.Foundation = .NET v2 and v3.5

In order to ensure as much common code as possible is used across both the projects, two conditional compilation symbols can be specified. VER2 should be used to compile .NET 2.0 code and VER4 to compile .NET 4.0 code. Use of VER4 enables LINQ and other .NET version 4.0 features to be used for improved performance. Please note that, while the MVC Framework is required to build VER4 from source, MVC is not required to use or host Foundation.

The other two sections (configuration and fiftyOne) in the web.config or 51Degrees.mobi.config should still be included if required.

2.7 Code access security

To avoid errors due to Code Access Security (CAS), the web.config defaults to set trust level to full.

The solution will also work in Medium trust mode. Changes may be required in your code to support Medium trust.

---

Select one of the following headings to read more.

• User Guide
• FAQs
• Operational Summary

<locations>

  <location name="tablet" url="~/Tablet/Default.aspx">

   <add property="is_tablet" matchExpression="true"/>

   <add property="is_wireless_device" matchExpression="true"/>

  </location>

  <location name="mobile" url="~/Mobile/Default.aspx">

   <add property="is_wireless_device" matchExpression="true"/>

</locations>

<locations>

  <location name="tablet" url="~/Tablet/Default.aspx">

   <add property="is_tablet" matchExpression="true"/>

   <add property="is_wireless_device" matchExpression="true"/>

  </location>

  <location name="mobile" url="~/Mobile/Default.aspx">

   <add property="is_wireless_device" matchExpression="true"/>

</locations>