Appendix A. Detecting Browsers with WURFL

WURFL (Wireless Universal Resource File) is an XML file that contains the information needed to identify a wide range of mobile devices. On its own, it doesn't do anything, but if you use one of the many available libraries for it, you can create web apps that can figure out what kind of device has connected to your app.

For example, wurfl-php (http://sourceforge.net/projects/wurfl/files/WURFL%20PHP/) lets you detect what operating system a remote device is running from within a PHP script.

Note

To use WURFL and wurfl-php, you'll need to be running your web app on a hosting provider that supports PHP. You'll also need to understand how to install files and PHP libraries onto your server. In this appendix, I show you how to do this using the Unix or Mac OS X command line. If you are uncomfortable with any of this, but are comfortable working with PHP, contact your hosting provider's support department and ask if they'd be willing to install WURFL and wurfl-php on the server you use. If you're using a shared server, it would give your hosting provider a competitive advantage to offer this feature to all their customers.

Installation

First, download wurfl-php and unzip it somewhere onto your server (in general, it's best to not put libraries in your public web folder, so I'm putting it into the src directory in my home directory). Replace ~/src with the location you want to install it into, and replace wurfl-php-1.1.tar.gz with the name of the file you actually downloaded:

$ mkdir ~/src
$ cd ~/src
$ tar xvfz ~/Downloads/wurfl-php-1.1.tar.gz

Next, download the latest WURFL file (http://sourceforge.net/projects/wurfl/files/WURFL/), copy it into the wurfl-php folder, and gunzip it (see the wurfl-php documentation for tips on using this file in its compressed state). Replace ~/src/wurfl-php-1.1/ with the full path to the directory that was created in the previous step when you extracted the wurfl-php distribution, and replace ~/Downloads/wurfl-latest.xml.gz with the path to the WURFL distribution that you downloaded:

$ cd ~/src/wurfl-php-1.1/
$ cp ~/Downloads/wurfl-latest.xml.gz .
$ gunzip wurfl-latest.xml.gz

Next, download the desktop web browser patch so WURFL doesn't encounter errors when someone visits your page from a desktop browser:

$ curl -O http://wurfl.sourceforge.net/web_browsers_patch.xml

Configuration

Next, create the following wurfl-config file (wurfl-config.xml) in ~/src/wurfl-php-1.1/ (or the directory you created when you extracted wurfl-php):

<?xml version="1.0" encoding="UTF-8"?>
<wurfl-config>
  <wurfl>
    <main-file>wurfl-latest.xml</main-file>
      <patches>
        <patch>web_browsers_patch.xml</patch>
      </patches>
  </wurfl>
  <persistence>
    <provider>file</provider>
      <params>dir=./cache</params>
  </persistence>
</wurfl-config>

Create a cache directory and make sure it's writeable by whichever user runs PHP scripts. If your web server is configured to run your PHP scripts under your user credentials, this step should not be necessary. As with previous examples, replace ~/src/wurfl-php-1.1/ with the location you created earlier. Replace _www with the username that your PHP scripts run under (you will need superuser credentials to run this command):

Note

If in doubt, contact your hosting provider's tech support and explain you want the cache directory to be writeable by your PHP scripts.

$ mkdir ~/src/wurfl-php-1.1/cache
$ sudo chown _www ~/src/wurfl-php-1.1/cache

Testing wurfl-php

Now, in your web directory (such as Sites or public_html), create the following PHP file (name it something like wurfl-test.php). The first time you visit it from your Android device (or any other browser), it will take a long time as it builds the initial cache. After that it should be zippy. Figure A.1, “Output of the sample wurfl-php script.” shows how this would appear in your browser. You can now modify this PHP code to suit your needs.

Figure A.1. Output of the sample wurfl-php script.

Output of the sample wurfl-php script.

Note

Note that I couldn't use, ~ so I had to put in the full path to the WURFL stuff; replace /Users/NAME/src/wurfl-php-1.1/ with the full path to the wurfl-php directory you created earlier.

<html>
<head>
    <meta name="viewport" content="user-scalable=no, width=device-width" />
    <title>WURFL Test</title>
<?php

  define("WURFL_DIR", "/Users/bjepson/src/wurfl-php-1.1/WURFL/");
  define("RESOURCES_DIR", "/Users/bjepson/src/wurfl-php-1.1/");

  require_once WURFL_DIR . 'Application.php';

  $wurflConfigFile = RESOURCES_DIR . 'wurfl-config.xml';
  $wurflConfig = new WURFL_Configuration_XmlConfig($wurflConfigFile);
  $wurflManagerFactory = new WURFL_WURFLManagerFactory($wurflConfig);

  $wurflManager = $wurflManagerFactory->create(); 
  $wurflInfo = $wurflManager->getWURFLInfo();

  $requestingDevice = $wurflManager->getDeviceForHttpRequest($_SERVER);
  $is_android = FALSE;
  if ($requestingDevice->getCapability("device_os") == "Android") {
      $is_android = TRUE;
  }
?>
</head>
<body>
  <?php
    if ($is_android) {
      echo "I spy an Android phone.";
    }
  ?>
  <ul>
    <?php 
      foreach ($requestingDevice->getAllCapabilities() as $key => $value) {
        echo "<li>$key = $value"; 
      } 
    ?>
  </ul>
</body>
</html>
Site last updated on: November 17, 2010 at 11:11:58 AM PST