.NET Mobile API - User Guide

User Guide

3 additional sections need to be added to the web.config for your web site to use this API. Each is explained here and can be seen in the full example provided with the downloads on the .NET Mobile API product page.

1. Configuration Sections

The following settings are needed at the top of the web.config file. They tell .NET about subsequent configurations in the web.config and how to handle them. In this instance we're telling .NET to use the fiftyOne assembly.

</sectionGroup>

</configSections>

These lines tell .NET about the Mobile API and allow it to make sense of the following section..

2. fiftyOne

Add the following element after the configSections element. These lines control how the Mobile API responds to mobile devices and where to locate the database of mobile devices.

</wurflPatches>

</wurfl>

</fiftyOne>

Toolkit

The toolkit has two optional child elements to control log file handling and device redirection.

Element	Attributes	Mandatory	Description
log	logFile	Yes	The location of the log file.
	logLevel	No	Values include Debug\|Info\|Warn\|Fatal and control the level of information logged. Detauls to Fatal if not specified.
redirect	mobileHomePageUrl	Yes	A url to direct mobile devices to instead of the normal web sites landing page.
	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. (Defaults to true)
	Timeout	No	The number of minutes of inactivity that should occur before the requesting device should be 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 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're making a subsequent request. 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 processes)
	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. 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. Example mobileHomePageUrl=”~/Mobile/Default.aspx” mobilePagesRegex="~/Mobile/" The attributes shown above indicates that pages under the folder ~/Mobile should be considered as optimised for mobile devices even though they are probably derived from System.Web.UI.Page. Therefore any page that is not under ~/Mobile when accessed by a mobile device will be treated as a non-mobile page and redirected to ~/Mobile/Default.aspx. However it a mobile device accesses a page under ~/Mobile no redirection will occur.

WURFL

The following settings control where the API finds wurfl device data, the capabilities to load, and the handling or new devices not contained precisely in the wurfl device database. They appear in the fiftyOne and wurfl section of the web.config.

The following attributes appear in the wurfl element.

Attribute	Mandatory	Description
wurflFilePath	Yes	A relative or absolute path to the main wurfl device data file.
newDevicesURL	No	A URL to a web page that can be informed of new mobile devices. If you'd like to help 51degrees assist the wurfl project in keeping the device database as up to date as possible use the following value. http://devices.51degrees.mobi/new.ashx
newDeviceDetail	No	Controls the HTTP Request header values that are recorded with new device information. Valid values are minimum and maximum. The default is minimum. Minimum will only record the useragent string and any profile information included in the header. Maximum will record all headers that may include personal information associated with the device accessing your web site. It's more helpful to provide all headers but we understand this may not be something you'll be comfortable with so minimum is the default. Profile information will consist of a link to the manufacturers web site and a file that contains UAProf settings for the device. This is one of the 1st places looked at when adding new devices to the device database.

The overhead associated with recording new devices to file or to a URL is kept to a minimum through the use of a low priority thread running outside the standard page handling process.

Patch Files

Additional patch files can be processed when the API is initiated. These are defined in the wurflPatches element as add elements. You can add as many patch files as you like. We suggest using the web_browsers_patch.xml file as this will ensure non mobile browsers are detected accurately. Additionally you will need to specify the file used to record new devices if you wish to ensure these are available when the API reloads device data.

The following attributes are available in each add element.

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

Capabilities

The capabilitiesWhiteList element of the wurfl element determines the capabilities to load from the device database. If this element is emitted and all the capabilities available will be loaded marginally increasing the time to load device data.

The following attributes are available in each add element.

Attribute	Mandatory	Description
capabilityName	Yes	The name of the capability as it appears in the wurfl device database.

3. Detector Module

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

IIS 7.X

<system.webServer>
        
     <modules>
          <add name="Detector" type="FiftyOne.Foundation.Mobile.Detection.DetectorModule, FiftyOne.Foundation"/>
     </modules>
</system.webServer>

IIS 6.0 & Visual Studio

<httpModules>
<add name="Detector" type="FiftyOne.Foundation.Mobile.Detection.DetectorModule, FiftyOne.Foundation"/>
</httpModules>

You may find you'll need to use this API alongside other HttpModules. Ensure the Detector is added to the HttpModules element in addition to the other HttpModules.

Code Access Security

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

Summary

We've tried to explain how the changes to the web.config file work, what they're used for, and how to amend them to suit your requirements. If we've not covered something you'd like to know please ask in our forum.