Main Page

From Tera-WURFL

Revision as of 18:26, 11 July 2011 by Kamermans (Talk | contribs)
Jump to: navigation, search

Headerlogo.png

Contents

The improved Tera-WURFL Explorer at http://www.tera-wurfl.com/explore/


BIG NEWS - Tera-WURFL is now part of the ScientiaMobile API Lineup

ScientiaMobile is a joint venture between the WURFL Project and the Tera-WURFL project. Tera-WURFL will still be free and open source, but now we're offering full commercial support, additional features and more accurate data!

Check out the ScientiaMobile Press Release for more details!

Current Version: Tera-WURFL 2.1.5

What is the WURFL Database API (Tera-WURFL)

The WURFL Database API is a PHP & MySQL/MSSQL/MongoDB based library by ScientiaMobile that uses the Wireless Universal Resource File (WURFL) to detect the capabilities of mobile devices. The WURFL website nicely defines the WURFL as follows:

The WURFL is an "ambitious" configuration file that contains info about all known Wireless devices on earth. Of course, new devices are created and released at all times. While this configuration file is bound to be out of date one day after each update, chances are that the WURFL lists all of the WAP devices you can purchase in the nearest shops.

Example applications of the WURFL DBAPI include:

The author of Tera-WURFL is Steve Kamerman, a professional PHP Programmer, MySQL DBA, Flash/Flex Actionscript Developer, Linux Administrator and full time IT Innovator. This project is one of the Official WURFL APIs from ScientiaMobile, and is offered under Free and Open-Source (FOSS) and Commercial licenses. Licenses and professional support may be obtained directly from ScientiaMobile.

Tera-WURFL Project Priorities

  1. High Performance: Tera-WURFL uses a database backend (MySQL4 MySQL5, MSSQL, MongoDB) to store the WURFL data and cache the results of device detections. This database can be shared between many installations of Tera-WURFL, so all your sites can benefit from sharing the same cache. Non-cached lookups on my test system average about 250 devices per second, with cached detections over 1000 per second.
  2. Accurate Detection of Mobile Devices: Uses over a dozen UserAgentMatchers, specifically tailored to their own group of mobile devices to provide unmatched detection accuracy.
  3. Fast Detection of Desktop vs. Mobile Devices: Although detection of mobile devices is good among most of the libraries, they are not very good at desktop browsers. As a result, your desktop users are detected as mobile devices and sent to the wrong site. Tera-WURFL includes a feature called the SimpleDesktop Matching Engine that is used to differentiate between desktop and mobile browsers at an extremely high rate. Additionally, instead of the tens of thousands of unique desktop user agents piling up in your cache, SimpleDesktop uses just one entry in the cache to represent all the desktop browsers.
  4. Usability: Since PHP has such a large base in the small- to medium-sized website arena, there are a large number of new developers. Tera-WURFL has been designed to be easy to use and administer. Once the initial configuration is finished, you can maintain the system completely from its Web Administration Page, including the ability to update the WURFL data via the Internet.

Constant Performance and Accuracy Improvements

Using our in-house analysis and regression testing software built for Tera-WURFL, we are able to quickly perform a deep analysis on the performance and accuracy of both the UserAgentMatchers and the core. This data is then evaluated to identify potential bottlenecks in the system. We are also able to track the internal match confidence that Tera-WURFL has with each device detection and construct aggregate visualizations to determine if there are more new user agents on the Internet that are slipping by the detection system.

Requirements

How does it work?

When a web browser (mobile or non-mobile) visits your site, it sends a User Agent along with the request for your page. The user agent contains information about the type of device and browser that is being used; unfortunately, this information is very limited and often times is not representative of the actual device. The WURFL Project collects these user agents and puts them into an XML file, commonly referred to as the WURFL File. This file also contains detailed information about each device i.e. the screen resolution, audio playback capabilities, streaming video capabilities, J2ME support and so on. This data is constantly updated by WURFL contributors from around the world via the WURFL Device Database. Tera-WURFL takes the data from this WURFL file and puts it into a MySQL database (MSSQL support is experimental) for faster access, and determines which device is the most similar to the one that's requesting your content. The library the returns the capabilities associated with that device to your scripts via a PHP Associative Array. Currently, the WURFL contains 29 groups of capabilities with a total of 531 capabilities.
Here's the logical flow of a typical request:

Device Requests a Page

Someone requests one of your pages from their mobile device. Their User Agent is passed to the Tera-WURFL library for evaluation.

Request is Evaluated

Tera-WURFL takes the requestor's user agent and puts it through a filter to determine which UserAgentMatcher to use on it. Each UserAgentMatcher is specifically designed to best match the device from a group of similar devices using Reduction in String and/or the Levenshtein Distance algorithm.

Capabilities Array is Built

Each device in the WURFL file and WURFL database falls back onto another device, for example the iPhone 3GS has only a handful of capabilities, then it falls back onto the iPhone 3G, which adds to those capabilities and falls back onto the original iPhone, then onto a generic device that contains the default capabilities. Through this method of inheritance, the device entries remain very small in size. In our example, once the User Agent has been matched, the capabilities from this device are stored into the capabilities array, then the next device in its fallback tree (its parent device) is looked up, and its capabilities are add, all the way up to the most generic device.

Results are Cached

The capabilities array is now cached with the User Agent so the next time the device visits the site it will be detected extremely quickly.

Capabilities are Available to the Server

The process is finished and the capabilities are now available for use in your scripts. One common use, for example, is to redirect mobile devices to a mobile version of the site:

<?php
require_once './TeraWurfl.php';
$wurflObj = new TeraWurfl();
$wurflObj->getDeviceCapabilitiesFromAgent();
 
// see if this client is on a wireless device
if($wurflObj->getDeviceCapability("is_wireless_device")){
	header("Location: http://yourwebsite.mobi/");
}
?>

Show a Picture of the Device (optional)

If you have version 2.1.2 or higher, you can show an image of the device (assuming one is available). See the Device Image page for the details.
Here's a usage example:

<?php
require_once 'TeraWurfl.php';
require_once 'TeraWurflUtils/TeraWurflDeviceImage.php';
$wurflObj = new TeraWurfl();
$wurflObj->getDeviceCapabilitiesFromAgent();
$image = new TeraWurflDeviceImage($wurflObj);
/**
 * The location of the device images as they are accessed on the Internet
 * (ex. '/device_pix/', 'http://www.mydomain.com/pictures/')
 * The filename of the image will be appended to this base URL
 */
$image->setBaseURL('/device_pix/');
/**
 * The location of the device images on the local filesystem
 */
$image->setImagesDirectory('/var/www/device_pix/');
/**
 * Get the source URL of the image (ex. '/device_pix/blackberry8310_ver1.gif')
 */
$image_src = $image->getImage();
if($image_src){
	// If and image exists, show it
	$image_html = sprintf('<img src="%s" border="0"/>',$image_src);
	echo $image_html;
}else{
	// If an image is not available, show a message
	echo "No image available";
}
?>

Downloads, Installation, Support

The following pages will guide you through downloading, installing, configuring and extending Tera-WURFL:

Personal tools
Namespaces
Variants
Actions
WURFL DBAPI
Toolbox