Online Contributors Help

This document explains how to submit WURFL updates using the WURFL-DB public interface. The document assumes that you requested and obtained WURFL contributor credentials from ScientiaMobile.

Logging in

First step is logging in:

Login fields are placed in the right
top corner of the page.

This will bring you to the main panel, i.e. the launching pad for all activities that WURFL contributors are expected to perform, such as: looking for a device profile, fixing device data, adding a new device, download a new wurfl.xml file containing the new contributed data.

While the interface to add data is simple, Contributors are expected to know the conventions to choose consistent WURFL ID strings and place the profile in a sensible hierarchy.
When in doubt, please drop a line to the WURFL Admin and he will be more than happy to help and keep wurfl in good shape.

The following help file will explain in details the WURFL-DB contributor interface and the conventions to be applied when inserting device profile in the system

The WURFL Device Hierarchy

The number one concept that each and every contributor should be intimately familiar with is the fall-back hierarchy. The hierarchy allows new devices to inherit their capability values from similar devices from the same manufacturers. The fall-back mechanism is powerful and has great advantages for the community, since a correct choice of fall-back yields a high-chance that the value of capabilities is inferred correctly. On the other hand, the fall-back is a double-edged sword when relied on as the unique mechanism. Contributors should go in and provide data about devices they know about.
What follows is an explanation of how the hierarchy works. If you are familiar with WURFL already, this is goig to be a quick read. If you are not, please punt your elbows and study the following really carefully.

WURFL XML Structure and Functions

In order to better explain the concepts and the functions introduced with the new system a basic introduction to the structure of the WURFL XML is provided here. The WURFL XML file is basically a flat list of <device> elements, albeit the fall_back mechanism allows WURFL users to regard it as a logical tree, in which elements have different types, as illustrated below (also see picture):

Root (generic)

root (also known as "the generic element") represents the capability of unrecognized HTTP clients. Generic has some special properties: it contains all WURFL capabilities, albeit always set with very conservative values (it is not wise to make assumptions about unrecognized HTTP clients).
This element can be overridden to set values for unrecognized HTTP reuquests (for example, some may want WURFL to assume that an unrecognized request comes from a web browser, and not a mobile device).

Generic mobile (generic_mobile

this element represents the generic unrecognized mobile device. Generic Mobile has some special properties as well: it contains almost all WURFL capabilities, set with very conservative values (it is not wise to make assumptions about unrecognized devices). This is very similar to the root device. The capability definition is repeated to avoid that changes ,ade to the Root element are transferred to mobile devices.

Family

A family is a <device> element that does not represent any specific device, yet its existence is useful to collect the value of capabilities that are common to the devices (or sub-families) falling-back into the family. Nokia Series 40 is a great example of that.

Actual Device Root

A device marked as 'actual device root' represents an actual device which happens to have been elected as the representative of the (possibly few, possibly many) devices by the same name but potentially slightly different set of features. An example of this might be the Nokia70, a popular device that comes in many very similar variations (the version made for Voda has different menus, but is essentially the same phone).

Device Subversion

Finally, a device may represent a device subversion, i.e. a device which is in principle very similar to the some existing "actual device" (see above) and which has been inserted for either capturing the delta of difference with the actual device, or simply to help the UA-String matching heuristics get to the right device when a HTTP request comes in.

The fall-back hierarchy MUST be clear in the mind of each and every contributor

Important note: in the current WURFL XML there is no distinction between nodes, meaning that no attribute will tell if a "device" XML element is the root, a family or a device subversion. The only exception to this is the "actual_device_root" attribute that clearly marks actual devices.

As far as the APIs are concerned, all devices and all fall-backs are created equal. The categorization of devices shown above, though, is important for humans: for humans a capability inherited from the corresponding actual_device is very reliable. The ones inherited from the family are less reliable and the ones inherited from 'generic' or 'generic_mobile' are even less reliable. This meta-information is rendered visually through the use of colors:

Colors are used to tell you where the capability value comes from

As a general rule, contributors are expected to modify existing devices, add totally new "actual root" devices and create firmware subversions falling back into actual_root devices. Contributors will not normally create family of devices, since this could be a disruptive effect on other people's usage of WURFL. If a contributor (or anyone else) feels strongly about the modification of the WURFL family structure, an email with an accuarte description of the issue should be sent to wurfldb at scientiamobile.com. Posting a message on the ScientiaMobile WURFL Forum

Searching the WURFL DB for existing Device Profiles

One of the main activities which contributors (and everyone else) will be performing at all times is to retrieve device profiles in order to browse, edit and modify device information.

Many ways to search for a WURFL device profile.

WURFL DB comes with a reasonably efficient search mechanism that will let you search the repository using a variety of parameters.
Searches can be performed based on a number of reasonable parameters: User-Agent String, WURFL ID, UAProf, Brand, Model and Brand-Model pair.
The following rules also apply:

• Unless otherwise specified, the search will apply to substring, meaning that a search for WURFL ID nokia_6600, will return "nokia_6600_ver1 ", "nokia_6600_ver1_subsymb61" and all of the other IDs matching the initial substring.
• With the exception of the brand-model pair, filling two fields in the search form is not required to produce the intersection of the two queries. This means that searching for a User-Agent String and a WURFL ID will be handled as if either only the UA or only the WURFL ID was used to query the DB (which one is just a detail which will depend on actual implementation)
• UAProf search is an exception and will need to be exact: searching for UAprof substring would be simply confusing

The result of a query will be a list of hits in most cases. The search engine will place "actual device root" profiles at the top in the list of hits.

Looking for User-Agent "NokiaN70"...

Clicking on one of the hits will bring the contributor to the page to browse and edit device information.

Browsing and Editing Device Capabilities

Browsing and editing happens in the same page (see figure below). Background colors in each capability signal the level of confidence that the capability is accurate. A red-like color means that the capability value is inferred from one of the generic devices. As such it is probably not very reliable. On the other hand, yellow indicates that the capability is inferred from a family, which is better than generic. Light green indicates that the value is inferred from a device "uphill" and that device is a actual_device_root. Intense green means that the capability has been added for the current device. As such, the capability value is unlikely to be wrong.

Browsing and editing capabilities for a NokiaN70 (one of it subversions actually)

Within the same interface, editing the capability value is possible and can be done easily. Capabilities are normally either checkboxes (for boolean true/false capabilities) or text fields (for strings and numbers). In some cases, a combo box is provided (capabilities with enumerated types, not that anyone we really introduced the concept of type formally in WURFL....).
Once changes to the group capabilities have been performed, the new data can be submitted with the convinniently labelled "Submit Device Info" button (see figure above).
Of course, the screenshot only refers to capabilities in the "product_info" group. Other groups can be accessed through the simple menu available on the left side of the browser window 8see figure below)

Of course, the system lets one access all groups

So far, we have shown how to find, browse and edit an existing device. What if one wants to introduce a new device?

Creating a new WURFL Device

Adding a new device can be done by clicking on the "Add new device" item in the main menu bar available to contributors (see figure):

Add Device function is available from the main bar

This will get a subscriber to the following simple interface to add the three basic pieces of data WURFL needs to identify the device and place it in the correct device hierarchy:

Create New Device (step 1)

Adding those three fields is a simple, but very error-prone, activity. Adding the wrong fall_back, for example, may lead to an invalid WURFL.

Adding an invalid profile is actually not simple. When a new profile is submitted, the system will check that the fall_back attribute is consistent with the rest of WURFL.
Nevertheless, contributors are expected to know the rules and conventions needed to keep WURFL in good shape.

There is actually a bit of extra support provided to contributors who intend to add a new device profile. The fall_back field will trigger a useful Ajax function to retrieve valid WURFL-ID which match what the contributors has typed up to that point. This greatly helps contributors select the right fall-back (see picture):

Create New Device (step 2): a bit of Ajax will help
contributors select a suitable fall-back ID

In spite of the ajax utility, there are many important aspects of WURFL which contributors are expected to be intimately familiar with:

• When and how to tweak the User-Agent String for a given profile
• How to choose an optimal fall-back attribute for a given profile
• How to choose a WURFL-ID which is consistent with the ones already in WURFL

These aspects are explained in detail in the paragraphs that follow.

The following three paragraphs have paramount importance for all contributors. Contributors are expected to be initimately familiar with them.

Getting the Most out of User-Agent Strings

WURFL relies on User-Agent strings to uniquely identify a device whenever an HTTP request is available.
When a contributor intends to add a new device profile into WURFL, copying the User-Agent string verbatim (letter for letter) into WURFL is often not the best strategy. Contributors are required to have a rough understanding of how the matching mechanisms in WURFL work, and "normalize" the User-Agent string in order to maximise the possibility that a good match is found by the different WURFL APIs.
The rest of this paragraph explains this. The explanation starts with an extremely common case of substring added by the gateway which all contributors should immediately recognize.
Before the mechanisms to manipulate UA strings are explained, the following rule should be observed:

[VERIFY_NEW]: Contributors who intend to add a new device, should verify that the UA string of the new device does not already exist, possibly in a slightly different form.
Apart from the obvious case where the device already exists, variations of the same device may already be available, in which case the new device is better defined as the descendent of that existing device. Alternatively, a contributor may simply want to update the capabilities of the existing device.
In case of doubts about the organization of the fall_back hierarchy, contributors are welcome to contact "wurfldb at scientiamobile.com".

Removing Extra Chars added by the Openwave WAP Gateway: as a heritage from the very first attempt at the mobile Internet, WAP Gateways by a company called Openwave (previously Phone.com and Unwired Planet) add a gateway substring to the value of the User-Agent string in each HTTP request. This string has the format:

 UP.Link/{gateway version number}

(please observe that there is a "space" right before the "UP")
Contributors should observe the following important rule:

[REMOVE_UPLINK]:Contributors who intend to add a new device and are in the presence of UA strings such as:

MOT-A-4A/01.01 UP.Browser/4.1.27a1 UP.Link/5.1.2.16
or
SAMSUNG-SGH-Z400-Vodafone/1.0 SHP/VPP/R5 NetFront/3.3 SMM-MMS/1.2.0 profile/MIDP-2.0 configuration/CLDC-1.1 UP.Link/6.5.0.0.0

should remove the " UP.Link/XXXXX" part from the UA strings and turn them into these (respectively) before adding the new UA in WURFL:

MOT-A-4A/01.01 UP.Browser/4.1.27a1
or
SAMSUNG-SGH-Z400-Vodafone/1.0 SHP/VPP/R5 NetFront/3.3 SMM-MMS/1.2.0 profile/MIDP-2.0 configuration/CLDC-1.1

WURFL APIs will clean the UA Strings whenever the "UP.Link" substring is detected. This will allow the API to attempt perfectly clean matches also in the presence of a WAP gateway.

Matching Algorithms: recent versions of the WURFL API use mainly two algorithm classes to match User-Agent Strings. One which we call Reduction to Initial String (RIS) and Levensthein Distance. Understanding how these two algorithms work is essential to understand the best way to insert the UA string in a new Profile.
RIS (reduction to initial String) is best applied to user-agents which write the unique name of the device in the first part of the String. Examples of such user agents are:

Nokia6600/1.0 SymbianOS/7.0s Series60/2.0 Profile/MIDP-2.0 Configuration/CLDC-1.0
BlackBerry8310/4.2.2 Profile/MIDP-2.0 Configuration/CLDC-1.1 VendorID/179
HTC-P3450-orange/PPC; 240x320; OpVer 23.114.2.741 
                         (compatible; MSIE 6.0; Windows CE; IEMobile 6.12)

Such user ageants have an important aspect in common. The first part of the User-Agent string (marked as bold in the list above) is very significant. If an exact UA match is not found in WURFL, returning the profile of a different device which matches according to RIS still yields a decent chance that the values are OK also for the current device.

In reality, the RIS algorithm used by WURFL is more sophisticated than this. The threshold which indicates how short the initial matching substring can get before RIS fails is calculated dynamically on a case-by-case basis.
A common way to calculate the threshold for a given family of user-agents is to look at the position of the first "slash" ('/'), but this is by no means the only one.

Levensthein Distance (LD): this is a number that measures how far apart two strings are by returning the number of single-char modification one needs to apply to go from one string to the other. For example, LD("Lukas","Luca") = 2.
The LD algorithm gives the best result for all the devices that do not come with a significant initial part. All the User-Agents with an initial "Mozilla/" sub-string are better matched with LD. While RIS has been used for these devices too in the past, reality is that LD works better by enabling WURFL to identify UA strings that are similar enough to the ones contained in WURFL representing similar devices.

HP iPaq 510
Mozilla/4.0 (compatible; MSIE 6.0; Windows CE; IEMobile 6.12) Smartphone; 176x220;
                              HPiPAQ510/1.0
iPhone
Mozilla/5.0 (iPhone; U; CPU like Mac OS X; en) AppleWebKit/420+ (KHTML, like Gecko) 
                              Version/3.0 Mobile/1A538a Safari/419.3
Nokia E50
Mozilla/5.0 (SymbianOS/9.1; U; en-us) AppleWebKit/413 (KHTML, like Gecko) 
                              Safari/413 es50
SonyEricsson W910
Mozilla/4.0 SonyEricssonW910iv/R1BA Browser/NetFront/3.4 Profile/MIDP-2.1
                              Configuration/CLDC-1.1

Nokia N80
Mozilla/5.0 (SymbianOS/9.1; U; en-us) AppleWebKit/413 (KHTML, like Gecko) Safari/413

Also the LD algorithm comes with the concept of threshold (and the threshold is different for each cathegory of device). Some UA strings belonging to very different devices happen to be very close. For this reason, actual threshold are typically set to small values such as 2 or 3.
Knowing the facts discussed so far is important for contributors. Here is how the different situations should be taclled by contributors.

Recognizing RIS User-Agent strings: with experience, contributors are expected to get more and more skilled at "sensing" RIS User-Agents. As a rule of thumb, UA-strings that DO NOT start with the "Mozilla" substrings are likely easily recognised by RIS matching (one important exception are UA-Strings containing "Vodafone", to be discussed later).

The rationale for the Stub approach is to retain the advantage of a catch-all device profile (all Nokia 6680, for example), while opening up for the possibility of modelling more specialised variations of the same device at a later time. To add to that, complete UA String also retain extra information about J2ME-MISP support and other features which the WURFL community may be willing to track at a later stage.

Recognizing LD User-Agent strings: LD user-agent strings begin with "Mozilla". Since there is no standard about the structure of this kind of UAs, the LD algorithm is typically not allowed to wander off to far from the UA string that has been received for matching. Two or three characters is the typical maximum allowance for the LD algorithm before it gives up trying to match apparently similar strings. For example, let us consider the following UA string: Mozilla/5.0 (SymbianOS/9.2; U; Series60/3.1 Nokia5700/3.27; Profile/MIDP-2.0 Configuration/CLDC-1.1 ) AppleWebKit/413 (KHTML, like Gecko) Safari/413. The originating device is obviously a Nokia 5700, but the LD algorithm makes no difference between the "5700" part of the string and the "3.27" part. The implication of this is that letting LD wander more than 2 or 3 chars awar from what it finds in WURFL, greatly increases the chance that a wrong match is found. The solution to the problem is to identify all the cases when similar UAs exist on the net and introduce them all in WURFL. This will make it harder for LD to miss a match:

[RECOGNIZE_LD]:Contributors who intend to add a new device, should identify UA strings such as the following as candidates for LD matching:

Mozilla/5.0 (SymbianOS/9.2; U; Series60/3.1 NokiaE-90-1/07.02.4.1; Profile/MIDP-2.0 Configuration/CLDC-1.1 ) AppleWebKit/413 (KHTML, like Gecko) Safari/413

The right strategy is to adopt the string as it is (applying the [REMOVE_UPLINK] rule may also be necessary)
In cases like this, contributors should also check (typically in their logs) whether different subversions of the same device exist. If they do, such extra UAs should be added in the form of new devices fall-ing back in the first one created. For example, assuming the a new device with the UA above has been introduced, more descendent should be created with the following UA strings:
Mozilla/5.0 (SymbianOS/9.2; U; Series60/3.1 NokiaE90-1/07.22.4.0; Profile/MIDP-2.0 Configuration/CLDC-1.1 ) AppleWebKit/413 (KHTML, like Gecko) Safari/413
Mozilla/5.0 (SymbianOS/9.2; U; Series60/3.1 NokiaE90-1/07.24.0.3; Profile/MIDP-2.0 Configuration/CLDC-1.1 ) AppleWebKit/413 (KHTML, like Gecko) Safari/413
Mozilla/5.0 (SymbianOS/9.2; U; Series60/3.1 NokiaE90-1/08.24.0.3; Profile/MIDP-2.0 Configuration/CLDC-1.1 ) AppleWebKit/413 (KHTML, like Gecko) Safari/413

Adding these UAs is a good way to help LD succeed in recognising the device.

Managing BlackBerry's: BlackBerry's tend to have a very nice RIS structure, such as:
BlackBerry8100/4.2.1 Profile/MIDP-2.0 Configuration/CLDC-1.1 VendorID/102

Alas, BlackBerry's also allow their users to change the UA-String in the device settings to try and fool web applications into believing that they are dealing with Microsot Internet Explorer, a Microsoft SmartPhone or the Openwave Browser.
The Openwave part ("UP.Browser/...." string) is added at the end. As such, it does not conflict with the RIS matching strategy as long as you are using WURFL. The same cannot be said of the first two cases, though:

[RECOGNIZE_BLACKBERRY]:Contributors who intend to add a new device, should identify UA strings such as the following, which are simply BlackBerry's in disguide:
Mozilla/2.0 (compatible; MSIE 3.02; Windows CE; PPC; 240x320) BlackBerry8100/4.2.0 Profile/MIDP-2.0 Configuration/CLDC-1.1 VendorID/100

Mozilla/4.0 (compatible; MSIE 6.0; Windows NT 5.0) BlackBerry8100/4.2.0 Profile/MIDP-2.0 Configuration/CLDC-1.1 VendorID/100

In these cases, no new device should be added to WURFL, since the WURFL API already contains the logic to figure out that these are blackberry's, strip out the offending part and apply RIS as originally planned.
Of course, it is still possible (albeit unlikely) that the second part of the UA is missing. This would mean that that particular RIM device is missing and should be added.

Managing Vodafone-branded devices: As most operators, Vodafone sells branded devices to their customers. What Vodafone does differently from other operator is forcing device manufacturers to also customise device UA strings to accomodate some mysterious and specific needs of the VodafoneLive! platform (that is like Ford or General Motors selling cars that can have a easier drive on the drivaway to Vodafone headquarters, but I digress....). It is not unusual to find UA strings such as the following in one's logs:

 
Vodafone/1.0/HTC_Mercury/1.20.161.6/Mozilla/4.0 (compatible; MSIE 4.01; Windows CE;
              MIDP-2.0 Configuration/CLDC-1.1; PPC; 240x320)

Vodafone/1.0/V702NK/NKJ001 Series60/2.6 Nokia6630/2.39.81 Profile/MIDP-2.0
              Configuration/CLDC-1.1

Vodafone/1.0/V702NK/NKJ001/IMEI/SN356729187623471  Series60/2.6 Nokia6630/2.39.126 
              Profile/MIDP-2.0 Configuration/CLDC-1.1

Vodafone/1.0/SamsungSGHC510V/C510XXGC7/Browser/Openwave/6.2.3

Vodafone/SonyEricssonV800/R1A001 Browser/SEMC-Browser/4.1
              Profile/MIDP-2.0 Configuration/CLDC-1.1

Vodafone/1.0/VS3/01 Browser/Obigo-Browser/3.0 MMS/Obigo-MMS/2.0 Java/Jblend/1.0
              Sync/Panasonic/1.0 Profile/MIDP-2.0 Configuration/CLDC-1.1

Vodafone/1.0/550SH/SHG001 Browser/UP.Browser/7.0.2.1 Profile/MIDP-2.0
              Configuration/CLDC-1.1 Ext-V-Profile/VSCL-2.0.0

SmarTone-Vodafone/SharpSX833/SHS001/1.0 Browser/UP.Browser/7.0.2.1a.474 (GUI)
              Profile/MIDP-2.0 Configuration/CLDC-1.1 Ext-J-Profile/JSCL-1.2.2
              Ext-V-Profile/VSCL-2.0.0

SAMSUNG-SGH-Z520-Vodafone

Vodafone/1.0/Vodafone710

Of particular interest are UA strings such as: Vodafone/1.0/V702NK/NKJ001/IMEI/SN356729187623471, i.e. devices that place their IMEI in the UA string directly.
While LD is a good approach to matching Vodafone devices, the introduction of the IMEI number makes straight LD on the User-Agent string less than ideal. For this reason, the following ule is introduced

[RECOGNIZE_VODAFONE_UAS]:
Vodafone UA strings should be reported "word-by-word" when creating a device profile (LD will be applied). The only exception is the case when the UA contains the substring "SN" followed by digits (between 9 and 15). In this case, contributors should replace each digit with a capital "X". This will help the WURFL-API match the right device regardless of the IMEI number.
For example:
Vodafone/1.0/V702NK/NKJ001/IMEI/SN356729187623471

should become

Vodafone/1.0/V702NK/NKJ001/IMEI/SNXXXXXXXXXXXXXXX

Beware of UA strings which carry the language code: It is not unusual (particularly with Android devices) that the same UA is presented with minor variations given by the language substring.
For example:
Mozilla/5.0 (Linux; U; Android 2.1-update1; da-dk; Nexus One Build/ERE27) AppleWebKit/530.17 (KHTML, like Gecko) Version/4.0 Mobile Safari/530.17
Mozilla/5.0 (Linux; U; Android 2.1-update1; fr-fr; Nexus One Build/ERE27) AppleWebKit/530.17 (KHTML, like Gecko) Version/4.0 Mobile Safari/530.17
Mozilla/5.0 (Linux; U; Android 2.1-update1; de-; Nexus One Build/ERE27) AppleWebKit/530.17 (KHTML, like Gecko) Version/4.0 Mobile Safari/530.17
Mozilla/5.0 (Linux; U; Android 2.1-update1; nb-no; Nexus One Build/ERE27) AppleWebKit/530.17 (KHTML, like Gecko) Version/4.0 Mobile Safari/530.17
Mozilla/5.0 (Linux; U;Android 2.1-update1; en-us; Nexus One Build/ERE27) AppleWebKit/530.17 (KHTML, like Gecko) Version/4.0 Mobile Safari/530.17
Mozilla/5.0 (Linux; U; Android 2.1-update1; hu-hu; Nexus One Build/ERE27) AppleWebKit/530.17 (KHTML, like Gecko) Version/4.0 Mobile Safari/530.17
Mozilla/5.0 (Linux; U; Android 2.1-update1; el-gr; Nexus One Build/ERE27) AppleWebKit/530.17 (KHTML, like Gecko) Version/4.0 Mobile Safari/530.17

WURFL should not be polluted with tens of duplicates which do not add any value to the framework. Always consider that the standard WURFL API is smart enough to match UAs regardless of the language substring.

[NO_LANUGUAGE_DUPLICATE]: Do not add devices which are already available in WURFL "modulo" the language substring

Getting the Most out of the Fall back

The fall-back mechanism is a double-edged sword in the area of Device Description Repositories (DDRs). On one hand, fall-back is a powerful way to assign great default values to the capabilities of many devices. On the other hand, as more device information is collected into the repository, fall-back may give a false sense of security about the validity of the information. Furthermore, changing a capability value in one of the generic devices may break a perfectly working application in subtle ways.
To add to this, the existence of the fall-back mechanism continously triggers the discussion about having some kind of multiple inheritance added to the framework, in order to leverage the fall-back more extensively than it is today, where just one fall-back hierarchy is possible. Unfortunately, adding multiple inheritance would greatly increase the complexity of the WURFL framework without being a definitive solution to the issues that come with the fall-back.
In short, fall-backs should be regarded as a great way to assign default values to capabilities, but it should not represent a replacement for real tested device information.

Contributors are invited to verify as many capabilities as possible for each device, without relying on fall-back.

This paragraph explains how to identify the best fall-back WURFL-ID when a new device profile is created.

"generic", "generic_mobile" and "generic_xhtml" fall-backs: These fall-backs are very minimal and conservative about the capability of each device. generic_xhtml assumes that the device can manage XHTML MP 1.0 content (by now a legacy mark-up). The generic_mobile fall-back should be used when absolutely nothing is known about the device.

In the past, unknown devices would be made fall-back to generic. This should not be done today. Today mobile devices will go through generic_mobile, that's the absolutely hist device in the hierarchy that contributors should indicate as a fall-back.
If a contributors assumes that a device should fall-back to generic, please coordinate with the WURFL DB Admins (wurfldb at scientiamobile.com).

The following table provides an indication of which common microbrowsers support XHTML in some form.
Please observe how the detection of one of these browsers will likely trigger one of the fall-back rules that follow and which are more likely to yield a better set of defaults.
Contibutors should learn the content of the following table by heart.

Of course, the fall_backs provided above are just minimal suggestions for contributors that have no idea about what a reasonable fall_back would be. A little experience may lead to better fall_back values, particularly when a new device is a close relative of an existing one and most software is expected to be the same.
With the advent of SmartPhones, there is an important convention that needs to be applied.

Handling devices with upgraded OS version

It is not unusual that popular versions of certain smartphones are released with updated versions of the Operatying System. This applies to iPhone, Android, BlackBerry and Windows mobile.
The problem with this is that a given device may be available in WURFL with fall-back into a specific OS family (for example, BlackBerry OS 4.6), while a newer version of the same device ships with OS version 5
At this point, contributors are left with a dilemma: should a new devices (falling back into OS 5) be created? or should a subdevice of the 4.6 device be crated?
The answer is not obvious, because WURFL wants the OS version to be correct in each profile, but, at the same time, it is important that devices with a given brand and model are grouped under a common "_ver1$" actual device root.
The convention is to adopt the latter choice. In other words, having one unique brand/model be the root of all devices of that kind is more important than enforcing the fall-back.
The following rules are presented:

The follwoing example (Motorola Milestone) will clarify the situation.
Device Motorola Milestone with the following UA was released at a given moment with OS Android 2.0:

Mozilla/5.0 (Linux; U; Android 2.0; de-de; Milestone Build/SHOLS_U2_01.03.1) 
AppleWebKit/525.10+ (KHTML, like Gecko) Version/3.0.4 Mobile Safari/523.12.2

At a later stage,users were allowed to upgrade to OS 2.1. This left us with two specimen of the same device with different UA strings and different OSes:

Mozilla/5.0 (Linux; U; Android 2.1-update1; en-ca; Milestone Build/SHOLS_U2_02.31.0) 
AppleWebKit/530.17 (KHTML, like Gecko) Version/4.0 Mobile Safari/530.17

The correct way to model this case is the following:

  <device id="mot_milestone_ver1"
       user_agent="Mozilla/5.0 (Linux; U; Android 2.0; de-de;
            Milestone Build/SHOLS_U2_01.03.1)
            AppleWebKit/525.10+ (KHTML, like Gecko)
            Version/3.0.4 Mobile Safari/523.12.2"
       fall_back="generic_android_ver2"
       actual_device_root="true">
    <group id="product_info">
      <capability name="uaprof"
         value="http://uaprof.motorola.com/phoneconfig/motoa853/Profile/motoa853.rdf"/>
      <capability name="model_name" value="Milestone"/>
      <capability name="brand_name" value="Motorola"/>
    </group>
   </device>
     :

  <device id="mot_milestone_ver1_suban21"
       user_agent="Mozilla/5.0 (Linux; U; Android 2.1-update1;
              en-ca; Milestone Build/SHOLS_U2_02.31.0) 
              AppleWebKit/530.17 (KHTML, like Gecko) Version/4.0 Mobile Safari/530.17"
        fall_back="mot_milestone_ver1">
    <group id="product_info">
      <capability name="device_os_version" value="2.1"/>
    </group>

Again, while the example above refers to Android, it is not unusual that RIM BlackBerries and Windows Mobil devices present the same issue

Choosing the right WURFL-ID

From a purely theoretical viewpoint, uniqueness is the only feature required of a WURFL ID. In practice though, using a consistent naming convention helps in tracking a given device in a repository as large as what WURFL has become today.
In this chapter, the naming convention used in WURFL so far is explained. Contributors are expected to stick to it in order to keep the repository tidy and, as much as possible, logically organized.
The following rules are presented:

[BRAND_AND_MODEL]: when a new device is introduced, the most common schema used to build a unique WURFL ID is to use the device brand and model (both in small letters) as the key, concatened through the "_" (undescore) character and with the "_ver1" string appended at the end.

For example, the WURFL ID for the main Nokia 6600 is: nokia_6600_ver1

WURFL IDs terminating with "ver1" are almost always identifying devices with the "actual_device_root" attribute set to true.

[BLACKBERRY_EXCEPTION]: BlackBerry's are handled as exeptions for historical reasons. In the case of a BlackBerry, the brand and the model are not separated by an "_" sign. For ex: blackberry8100_ver1

[SUBVERSION_STRING]: When defining an entry for a firmware subversion of a device, a unique WURFL ID string is creating by adding some firmware subversion string found in the UA string, without any dots (".").
For example:
Nokia6600/1.0 SymbianOS/7.0 Series60/2.1 Profile/MIDP-1.0 Configuration/CLDC-1.0

might have a WURFL ID such as:

nokia_6600_ver1_subsymb7021

Advanced Features

Create New Profile from Device Headers

When access to a device is available, it is possible to snoop the headers using the following URL: db.scientiamobile.com/h (mnemonic: "h" is for headers)

The steps required to snoop headers from a real device are expected to be known to contributors and are described in the following pictured (note: no authentication is required to access this page from a mobile device. www.wurflpro.com is the old DNS for db.scientiamobile.com):

Enter URL in minibrowser and visit header snooping page

Please observe that the UA string in this very example ends with the UP.Link bit added by the WAP Gateway:
HTTP_USER_AGENT: HTC-2125/1.2 Mozilla/4.0 (compatible; MSIE 5.5; Windows CE; Smartphone; 240x320) UP.Link/6.3.1.20.0
In a real situation, the UP.Link part (including the space before it) should be identified and removed by the contributor according to the [REMOVE_UPLINK] rule.

Apply a Patch File

It is now possible to submit complete patch files to WURFLDB.

Contributors are, of course, expected to know what a patch file is. For reference: https://docs.scientiamobile.com/guides/patch-files

Patch files are powerful. Poorly built patch files have the potential to wrack havoc into the WURFLDB, though. For this reason, the process of submitting a patch file goes through two steps. The first one is validation. Every patch file is first validated and, only if the validation succeeds, is the contributor given a chance to submit the data.

Validation involves that the following constraints are respected by the patch file:

• It is well-formed XML
• All the usual conventions for patch files are used
• Device definition that override existing devices must match WURFL-ID, User-Agent String and fall-back
• No new Capability can be introduced through the patch file (i.e. capability must exist in the generic device)
• Device definitions that create new devices must fall-back into an existing device

While the above rules may appear rather strict, they are absolutely essential in order to keep the WURFL consistent and synchronized for all WURFL users. Of course, if a contributor feels strongly about changing the UA-string, WURFL-ID of fall-back in an existing device, they can always contact ScientiaMobile by email (wurfldb at scientiamobile.com) to discuss and get the changes applied to the master, which would solve all the problems.

Once a patch file is validated, contributors are given a chance to submit the patch file, which will then be piped through the usual review by the maintainer. In order to submit a patch file, contributors will simply need to click on the "Upload Patch File" menu button:

Conclusions

Being a WURFL contributors means having a powerful tool to customise the DDR for one's mobile application, while leveraging the contributions of other members in the community. With this great power comes greater responsability. Contributors are required to stick to the WURFL naming and data-entry conventions.

Luca Passani
CTO at ScientiaMobile, Inc.
WURFL Inventor and Maintainer