WURFL OnSite PHP Database API: User Guide

Please Note: With the introduction of WURFL API v1.9.0.0,the OnSite Database API (TeraWURFL) is now legacy. It is strongly recommended that OnSite Database API users migrate to the OnSite PHP API for the best accuracy and performance. Please visit our detailed migration guide for instruction on making the change to the OnSite PHP API.

Requirements

PHP 5.3+

Web Server (the following have been tested):

Apache

lighttpd

NGINX with FastCGI

IIS

HipHop (HHVM) for PHP (must use MySQL 5 with the PDO DB Connector)

Database (one of the following):

MySQL 4 (MySQL4 DB Connector)

MySQL 5 (MySQL5 or PDO DB Connector)

MongoDB (MongoDB DB Connector)

Microsoft SQL Server 2005+ (MSSQL2005 DB Connector)

Note: for MySQL (4 or 5), the PHP MySQLi extension is required.

Installation

To enable WURFL on your application you must register for a free
account on scientiamobile.com and download the latest release from
your File Manager. Once you have downloaded the latest release, you will need to extract the files to be accessible from your PHP enabled webserver.

Copy the file TeraWurflConfig.php.example to TeraWurflConfig.php,
then edit it. Each setting is described in detail in the comments.
The only thing you need to modify is the database info (user, pass,
db, etc) NOTE: By default, the Database API is configured to use MySQL5.x.
If you are using a different database, set the DatabaseConnector
accordingly (see Requirements above).

Note: The WURFL API is closely tied to the wurfl.xml file. New versions
of the wurfl.xml are compatible with old versions of the API by nature,
but the reverse is not true. Old versions of the wurfl.xml are not
guaranteed to be compatible with new versions of the API.

Capability Filtering

In order to reduce memory usage and increase performance, you can specify a
subset of the 500+ WURFL capabilities. You can set the desired capabilities
by editing the $CAPABILITY_FILTER option in TeraWurflConfig.php.

Now, reload the WURFL file and only the capabilities you've specified will
be loaded. Note that because of the virtual capability system, those capabilities
listed above are always loaded, even if they are not specified.

File Permissions

By default, the DATADIR is set to data/. This directory holds the wurfl.xml file,
your patch file(s) and the log file. This directory and everything in it needs
to be accessible (read + write) by the user that runs your webserver. This is
normally apache, www-data, or nobody in Linux.

You can test the configuration by visiting the admin/install.php file in your web
browser.

Database Configuration

The Database API supports MySQL (default), MSSQL 2005+ and MongoDB. Since
MongoDB does not require any specific configuration, the following instructions
only apply to MySQL and can be easily translated to MSSQL.

Create a new database and a user that has a minimum of the following privileges
on the new database:

SELECT

INSERT

UPDATE

DELETE

CREATE

DROP

ALTER

CREATE TMP TABLE

CREATE ROUTINE

ALTER ROUTINE

EXECUTE

In the configuration file, set the DB_HOST, DB_USER, DB_PASS and DB_SCHEMA
to the values that you set when you created the database and user. You can
verify that all credentials are functional by visiting admin/install.php
If the database tables do not exist yet they will be created for you when
you load the WURFL file in the next step.

Your installation page should look similar to:

Loading the WURFL Database

If you are a commercial licensee, go to your account at ScientiaMobile.com and
copy your Direct Download URL, then paste it in your config file in the WURFL_DL_URL
property:

/**
* URL of WURFL File. If you have a ScientiaMobile license, use the Direct Download URL from your account.
* @var String
*/
public static $WURFL_DL_URL = "https://vault.scientiamobile.com/wurfl/xxxxxx/wurfl.zip";

Once you've completed all the steps on the installation page, you can load
the database with the WURFL data. There are two sources that the data can
come from:

Your local WURFL file: This will load the DATADIR/wurfl.xml file into your
database.

The current released WURFL: This will download the current wurfl.xml file
from your ScientiaMobile account and load it into your database.

Note: this option is only available if you are a commercial licensee and
have updated the configuration file with your Direct Download URL.

There will be a delay while the server loads/downloads the WURFL, then you
should see a page similar to:

If there are any errors, they are most likely permission problems trying to
write the temporary downloaded file to the DATADIR directory. Also,
some users have reported a "memory allocation" error, which can be corrected
by increasing OVERRIDE_MEMORY_LIMIT in the config file.

Using the WURFL API

Let's take a look at how you can use the API in your applications. Here's an example of serving different content to different classes of devices:

Virtual Capabilities

Virtual capabilities are an important feature of the WURFL API that
obtain values related to the requesting agent out of the HTTP request
as a whole (as opposed to limiting itself to capabilities that are found
in WURFL).

In order to compute its final returned value, a virtual capability may
look at regular (non-virtual) capabilities as well as other parameters
that can be derived from the HTTP request at run-time. Virtual capabilities
are useful to model aspects of the HTTP Client that are not easily captured
through the finite number of profiles in WURFL.

To get the value of a virtual capability, use the
TeraWurfl::getVirtualCapability() method:

$is_smartphone = $wurflObj->getVirtualCapability('is_smartphone');

Variable Name

Type

Description

is_app

enumerable

Tells you if the Requesting HTTP Client is an App or not.
The control capability is called controlcap_is_app (virtual_capability group) and can have values default, force_true and force_false

is_smartphone

enumerable

This is a virtual capability that will tell you if a device is a Smartphone for some arbitrary (and subject to change) definition of Smartphone by ScientiaMobile.

The virtual capability returns true or false. Patch files can use the is_smartphone control capability to override the value returned by the virtual capability.

Control capability is_smartphone can take value default, force_true and force_false.

is_robot

enumerable

This is a virtual capability that tells you if the HTTP Client is a Bot (robot, crawler or other programmable agent that stalks the web).
Control capability is is_robot (virtual_capability group) and can have values default, force_true and force_false.

is_mobile

enumerable

This is just an ALIAS for is_wireless_device. There's no control capability associated to this virtual capability.

is_full_desktop

enumerable

This is just an ALIAS for ux_full_desktop. There's no control capability associated to this virtual capability.

is_windows_phone

enumerable

Check if device runs any version of Windows Phone OS.

This virtual capability relies on the device_os (product_info group) capability.

is_ios

enumerable

Check if device runs any version of iOS.

This virtual capability relies on the device_os (product_info group) capability.

is_android

enumerable

Check if device runs any version of Android OS.

This virtual capability relies on the device_os (product_info group) capability.

is_touchscreen

enumerable

This virtual capability tells you whether a device has a touch screen. There is no control capability. Mostly an alias for pointing_method == touchscreen (product_info group) capability.

is_largescreen

enumerable

True if the device has a horizontal and vertical screen resolution greater than 480 pixels. Relies on the resolution_width and resolution_height (display group) capabilities.

is_wml_preferred

enumerable

True if the device is better served with WML. Capability relies on preferred_markup (markup group).

is_xhtmlmp_preferred

enumerable

True if the device is better served with XHTML MP (Mobile Profile). Capability relies on preferred_markup (markup group).

is_html_preferred

enumerable

True if the device is better served with HTML. Capability relies on preferred_markup (markup group).

advertised_device_os

string

This virtual capability will infer the name of the Device OS based on user-agent string analysis (and possibly the analysis of other HTTP headers and WURFL capabilities).

advertised_device_os_version

string

This virtual capability will infer the version of the Device OS based on user-agent string analysis (and possibly the analysis of other HTTP headers and WURFL capabilities).

advertised_browser

string

This virtual capability will infer the name of the browser based on user-agent string analysis (and possibly the analysis of other HTTP headers and WURFL capabilities).

advertised_browser_version

string

This virtual capability will infer the version of the browser based on user-agent string analysis (and possibly the analysis of other HTTP headers and WURFL capabilities).

form_factor

enumerable

This virtual capability will return one of the following values that identify a client's form factor: Desktop, Tablet, Smartphone, Feature Phone, Smart-TV, Robot, Other non-Mobile, Other Mobile

complete_device_name

string

Concatenates brand name, model name and marketing name (where available) of a device into a single string.

is_phone

enumerable

This is a virtual capability that will tell you if a device is a mobile phone .

The virtual capability returns true or false. Patch files can use the is_phone control capability to override the value returned by the virtual capability.

Control capability is_phone can take value default, force_true and force_false.

is_app_webview

enumerable

This virtual capability returns true if a HTTP request is from an app based webview.

device_name

string

Concatenates brand name and marketing name of a device into a single string. If marketing name is not available, model name is used instead.

advertised_app_name

string

This virtual capability will return the name of the application that generated the User-Agent or the HTTP request.

IMPORTANT - Decommissioning of MatchMode options

Prior to version 1.9 of the API, users could choose between High Accuracy and High Performance engine optimization options. These options had been introduced years ago to manage the behavior of certain web browsers and their tendency to present "always different" User-Agent strings that would baffle strategies to cache similar WURFL queries in memory. As the problem has been solved by browser vendors, the need to adopt this strategy has diminished and ultimately disappeared (i.e. there was no longer much to be gained with the high-performance mode in most circumstances) and ScientiaMobile elected to "remove" this option to simplify configuration and go in the direction of uniform API behavior in different contexts.
To clarify "remove" in the previous sentence, customers who may find themselves in the unlikely situation of having to analyze significant amounts of legacy web traffic, may still enable the old high-performance internal behavior by enabling the "FAST DESKTOP BROWSER MATCH" option on their engine. Please note that users with the old HIGH PERFORMANCE target engine will not receive an error. The old behavior will not be triggered, though. The default target (corresponding to the old High Accuracy) will be used instead. The WURFL Engine is the API's entry point. The WURFL Engine can be created using a factory method or simply instantiating the class.

NOTICE: All information contained herein is, and remains the property of ScientiaMobile Incorporated
and its suppliers, if any. The intellectual and technical concepts contained herein are proprietary to
ScientiaMobile Incorporated and its suppliers and may be covered by U.S. and Foreign Patents, patents
in process, and are protected by trade secret or copyright law. Dissemination of this information or
reproduction of this material is strictly forbidden unless prior written permission is obtained from
ScientiaMobile Incorporated.