DeviceAtlas is a commercial device database and API provided by dotMobi, which claims that it is the fastest and most accurate tool for recognizing mobile devices. The DeviceAtlas database is an aggregation of device information from operators,
manufacturers, WURFL, and other sources. It is available with commercial licensing terms that range from a free, single-server developer license to affordable annual fees for two server licenses and negotiable enterprise license terms. See
http://deviceatlas.com/licences for more information about DeviceAtlas licensing.
DeviceAtlas stores device data in JSON format. The device database is one JSON file.
Device characteristics are stored hierarchically, similarly to WURFL, to ensure a compact JSON data file, but the device hierarchy is hidden from API users. Desktop browsers, robots, spiders, proxy servers, and transcoders are all recognized in the DeviceAtlas database.
With a commercial license, the DeviceAtlas database can be customized and extended privately or publicly by contributing device information through a Mobile Web test suite or using the DeviceAtlas web site (http://deviceatlas.com).
The DeviceAtlas web site contains a wealth of device information and reports available to registered users. Site registration is free. The device database is browsable and searchable in the Devices section of the site (http://deviceatlas.com/devices). Figures 4-5, 4-6, 4-7, and 4-8 show what you might see when browsing the DeviceAtlas site.
Figure 4-5 shows what you see when browsing the list of Alcatel mobile devices known to DeviceAtlas.
Figure 4-5. DeviceAtlas browsing of Alcatel mobile device models
Figure 4-6 show what you see when using DeviceAtlas to search results for Pre. This search query finds the device database entry for the Palm Pre mobile device.
Figure 4-6. DeviceAtlas search results for Pre
Figure 4-7 show what you see when using DeviceAtlas to view the device database entry for the Palm Pre. It displays an image of the mobile device and its characteristics.
The web site optionally displays your contributions to the characteristics of this device, as well as characteristics with conflicting values from the original data sources.
Figure 4-7. DeviceAtlas device database listing for Palm Pre
Clicking a characteristic in Figure 4-7 allows registered site users to edit device information. Figure 4-8 shows the DeviceAtlas user interface for editing the screen-height characteristic for the Palm Pre. User-edited device information is moderated before it is included in the public DeviceAtlas database.
Figure 4-8. Editing a device characteristic in DeviceAtlas
The DeviceAtlas device database API is available for Java, .NET, PHP, Python, and Ruby Web runtimes. The object-oriented API provides methods for recognizing a mobile device from the User-Agent header value and obtaining device characteristics individually or as an array. This section describes the installation and use of the DeviceAtlas PHP API.
You can visit http://deviceatlas.com/downloads to download the DeviceAtlas API and documentation; download instructions for the DeviceAtlas device database are provided once a commercial license is obtained from dotMobi.
Follow these steps to install and use the DeviceAtlas database and PHP API:
1. Download the DeviceAtlas API into an accessible location on your Web server.
2. Download the DeviceAtlas JSON database into an accessible location on your Web server.
3. Write PHP code that initializes the DeviceAtlas API.
4. Write PHP code that recognizes a mobile device by User-Agent and obtains characteristic values for the mobile device.
First, you use the DeviceAtlas API to download the latest version of the PHP API from the DeviceAtlas download site. This section describes how to install version 1.3.1 of the PHP API. You install the software distribution into an accessible location on your Web server; this section assumes that you install the PHP API into a directory named deviceatlas. The software distribution contains the PHP API, a sample JSON file, and the API documentation.
a relative path to the JSON device database file (from the second step) to initialize the API. The $tree variable is an internal tree representation of the device database that is passed as a parameter when using the API to identify mobile devices and obtain device characteristics.
Listing 4-6. Code Sample for DeviceAtlas API Initialization // Initialize DeviceAtlas
include 'deviceatlas/Mobi/Mtld/DA/Api.php';
$tree = Mobi_Mtld_DA_Api::getTreeFromFile("deviceatlas/20091028.json");
Fourth, you use the DeviceAtlas API in PHP is to write PHP code that recognizes a mobile device by User-Agent and obtains characteristic values for the mobile device. In the DeviceAtlas API, device recognition and property retrieval are combined into a single method call. DeviceAtlas provides two API methods to obtain all characteristics for a device in a PHP array: Mobi_Mtld_DA_Api::getProperties and
Mobi_Mtld_DA_Api::getPropertiesAsTyped. The code sample that follows illustrates how to use these methods:
$props = Mobi_Mtld_DA_Api::getProperties($tree, $_SERVER['HTTP_USER_AGENT']);
$propsTyped = Mobi_Mtld_DA_Api::getPropertiesAsTyped($tree,
$_SERVER['HTTP_USER_AGENT']);
The $props variable is an array of device characteristic names and string values. The
$propsTyped variable is an array of characteristic names with values typed as string, integer, or boolean, according to the DeviceAtlas device characteristics documentation specified in the next section.
The API also provides methods to retrieve individual property values as untyped strings or values typed as string, integer, or boolean, according to the DeviceAtlas device characteristics documentation. The code sample that follows illustrates how to use these different API calls:
$prop = Mobi_Mtld_DA_Api::getProperty($tree, $_SERVER['HTTP_USER_AGENT'], 'model');
$propBool = Mobi_Mtld_DA_Api::getPropertyAsBoolean($tree, $_SERVER['HTTP_USER_AGENT'], 'mobileDevice');
$propInt= Mobi_Mtld_DA_Api::getPropertyAsInteger($tree, $_SERVER['HTTP_USER_AGENT'], 'displayWidth');
$propString = Mobi_Mtld_DA_Api::getPropertyAsString($tree, $_SERVER['HTTP_USER_AGENT'], 'vendor');
After executing this code sample, $prop and $propString are strings, $propBool is a Boolean value, and $propInt is an integer. In the DeviceAtlas API, untyped characteristic values are always PHP strings.