Installation

From Tera-WURFL

Revision as of 02:04, 8 June 2011 by Kamermans (Talk | contribs)
(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)
Jump to: navigation, search

Contents

Installation

Configuration File

File Permissions

chown -R apache:apache ./data/

Database Configuration

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

See the Configuration File page for more detailed information.

Loading the Tera-WURFL Database

Database Update OK

Total Time: 10.211848974228
Parse Time: 0.43991899490356
Validate Time: 2.7456870079041
Sort Time: 1.3005568981171
Patch Time: 0.44084501266479
Database Time: 3.9245390892029
Cache Rebuild Time: 1.3603019714355
Number of Queries: 294
PHP Memory Usage: 213.19 MB
--------------------------------
WURFL Version: www.wurflpro.com - 2009-08-25 08:15:48 (Tue Aug 25 08:19:41 -0500 2009)
WURFL Devices: 13714
PATCH New Devices: 3036
PATCH Merged Devices: 2

Update Complete!

If there are errors, they are most likely problems connecting to the WURFL site or permission problems trying to write the temporary downloaded file to the DATADIR directory. Also, many users have reported a "memory allocation" error - to fix this look for "OVERRIDE_MEMORY_LIMIT" in the config file. If there are no errors, click on "Return to administration tool".

Web Administration Page

Security

Upgrading Tera-WURFL

Version 1.x to Version 2.x

Tera-WURFL 2 is a complete code-rewrite and has a different database schema. In order to upgrade, you must rename the old Tera-WURFL folder and unzip the new version into the folder you would like to use. It is recommended that you use a new database as well, then delete the old one when you have Tera-WURFL 2 working properly.

Version 2.x to Version 2.x

To upgrade from any 2.x to any other 2.x (i.e. Tera-WURFL 2.0.0 to Tera-WURFL 2.1.0), simply delete the Tera-WURFL folder and unzip the new version's files into the folder you want to use. The databases are backwards compatible, so you can keep your existing data. After the files are in place, go to the Web Administration Page and update the database, then test it by going to the Tera-WURFL test page.

Usage Example

Here is a very simple example:

<?php
// Include the Tera-WURFL file
require_once('./TeraWurfl.php');
 
// instantiate the Tera-WURFL object
$wurflObj = new TeraWurfl();
 
// Get the capabilities of the current client.
$matched = $wurflObj->getDeviceCapabilitiesFromAgent();
 
// see if this client is on a wireless device (or if they can't be identified)
if(!$wurflObj->getDeviceCapability("is_wireless_device")){
	echo "<h2>You should not be here</h2>";
}
 
// see what this device's preferred markup language is
echo "Markup: ".$wurflObj->getDeviceCapability("preferred_markup");
 
// see the display resolution
$width = $wurflObj->getDeviceCapability("resolution_width");
$height = $wurflObj->getDeviceCapability("resolution_height");
echo "<br/>Resolution: $width x $height<br/>";
?>

Available Capabilities

The complete list of capabilities is available at the WURFL Documentation Page or via the ScientiaMobile Capability Browser. If you use $wurflObj->getDeviceCapability("cap_name") you can just use the capability name from the WURFL site, otherwise you can access it directly from the TeraWurfl object's capabilities array like this: $wurflObj->capabilities['group_name']['cap_name']

You can also browse the capabilities of all the mobile devices in the WURFL using the Tera-WURFL Explorer

Troubleshooting

Be sure to head over to the Tera-WURFL Forums to post your questions if there are not answered here!

Submit User Agent for Analysis

If you have gone through the relevant troubleshooting steps below and you're still having trouble with a particular device, you can submit it to us for analysis online at http://www.tera-wurfl.com/ua_submission/. Alternately, if you're using Tera-WURFL 2.1.1 or newer, you can submit your user agents directly from the Web Administration Page.

PHP Problems

Fatal error: Allowed memory size of...

When you try to update the database from the Web Administration Page, you see the following:

Fatal error: Allowed memory size of 67108864 bytes exhausted (tried to allocate 24 bytes) in TeraWurflLoader.php on line 287

This is an indication that PHP on your server does not have access to enough memory (RAM) to process the WURFL file. It takes a large amount of memory to process the wurfl.xml file because the entire file needs to be parsed, sorted, checked for consistency, then loaded into the database. To remedy this problem, edit your TeraWurflConfig.php file. Make sure $OVERRIDE_MEMORY_LIMIT = true and $MEMORY_LIMIT = "768M". On many shared hosts, you will only be allowed to use a small amount of memory per process (typically 64M), which is too small for Tera-WURFL to parse the WURFL file and build the database tables. Here are two typical workarounds:

  1. Install Tera-WURFL at another location, like your development system, and update it from there, then copy its database up to the production environment
  2. Use the WURFL Customizer to remove unused capabilities from the WURFL file, then upload this smaller file to your server and use it to update Tera-WURFL.

Database Problems

Error in DB RIS Query: Thread stack overrun

Fatal error: Uncaught exception 'Exception' with message 'Error in DB RIS Query: Thread stack overrun: 5224 bytes used of a 131072 byte stack, and 128000 bytes needed. Use 'mysqld -O thread_stack=#' to specify a bigger stack..
Query: CALL TeraWurfl_RIS('SonyEricssonK700i/R2AC SEMC-Browser/4.0.2 Profile/MIDP-2.0 Configuration/CLDC-1.1',16,'SonyEricsson') ' in /var/www/html/Tera-Wurfl/DatabaseConnectors/TeraWurflDatabase_MySQL5.php:103 Stack trace: 
#0 /var/www/html/Tera-Wurfl/UserAgentMatchers/UserAgentMatcher.php(63): TeraWurflDatabase_MySQL5->getDeviceFromUA_RIS('SonyEricssonK70...', 16, Object(SonyEricssonUserAgentMatcher)) 
#1 /var/www/html/Tera-Wurfl/UserAgentMatchers/SonyEricssonUserAgentMatcher.php(30): UserAgentMatcher->risMatch('SonyEricssonK70...', 16) 
#2 /var/www/html/Tera-Wurfl/TeraWurfl.php(96): SonyEricssonUserAgentMatcher->applyConclusiveMatch('SonyEricssonK70.. in /var/www/html/Tera-Wurfl/DatabaseConnectors/TeraWurflDatabase_MySQL5.phpon line 103

To fix this problem, edit your MySQL configuration file and increase the size of the thread stack.

Error in DB RIS Query: PROCEDURE TeraWurfl_RIS does not exist

Fatal error: Uncaught exception 'Exception' with message 'Error in DB RIS Query: PROCEDURE TeraWurfl_RIS does not exist. 
Query: CALL TeraWurfl_RIS('SonyEricssonK700i/R2AC SEMC-Browser/4.0.2 Profile/MIDP-2.0 Configuration/CLDC-1.1',16,'SonyEricsson') ' in /var/www/html//Tera-Wurfl/DatabaseConnectors/TeraWurflDatabase_MySQL5.php:103
Stack trace: 
#0 /var/www/html/Tera-Wurfl/UserAgentMatchers/UserAgentMatcher.php(63): TeraWurflDatabase_MySQL5->getDeviceFromUA_RIS('SonyEricssonK70...', 16, Object(SonyEricssonUserAgentMatcher)) 
#1 /var/www/html/Tera-Wurfl/UserAgentMatchers/SonyEricssonUserAgentMatcher.php(30): UserAgentMatcher->risMatch('SonyEricssonK70...', 16) 
#2 /var/www/html/Tera-Wurfl/TeraWurfl.php(96): SonyEricssonUserAgentMatcher->applyConclusiveMatch('SonyEricssonK70...') 
#3 /var/www/html/Tera-Wurfl/TeraWurfl.php(202) in /var/www/html/Tera-Wurfl/DatabaseConnectors/TeraWurflDatabase_MySQL5.phpon line 103

This error indicates that the TeraWurfl_RIS procedure did not get properly created in the MySQL Database. This procedure is dropped and created every time the database is loaded. There are only three reasons for you to get this message:

Other MySQL Problems

To use a MySQL5 Server without using Stored Procedures, use the MySQL4 Database Connector in the configuration file.

Detection Problems

Device Detected Incorrectly

Sometimes Tera-WURFL will incorrectly detect your device. This is most often caused by the RIS Algorithm (Reduction in String).
Here's an example User Agent string from Windows XP, Internet Explorer 6:

Mozilla/4.0 (compatible; MSIE 6.0; Windows NT 5.1; SV1; .NET CLR 1.1.4322; .NET CLR 2.0.50727; .NET CLR 3.0.04506.30; .NET CLR 3.0.04506.648; .NET CLR 3.5.21022; .NET CLR 3.0.4506.2152; .NET CLR 3.5.30729)

The User Agent is reduced by removing one character at a time from the end of the string. In this case, it would eventually be reduced to this:

Mozilla/4.0 (compatible; MSIE 6.0; Windows NT 5.1; SV1;

Each time the string is reduced, the database is checked for a macthing User Agent in the respective UserAgentMatcher table. Often times there are many matching User Agents, and Tera-WURFL will have to arbitrarily choose one of the matching User Agents from the table. Typically, Tera-WURFL will choose the first User Agent in the list that is an actual device as opposed to a categorial device (i.e. iPhone_3G_ver1 instead of Apple_Webkit.)
In order to accurately detect this device, one of the following must happen:

Performance Problems

Updating the WURFL is slow

A typical server will be able to update the database from the WURFL and apply any patches in about 20 seconds. After the WURFL file is processed, the cache is rebuilt be redetecting each User Agent in the TeraWurflCache database table one-by-one. A typical server will redetect the cached entries at a rate of about 100 per second. To see how many devices are in your cache file, go to your Web Administration Page, then click on Settings, Statistics, Log File. Look for the CACHE entry on left side of this page and you will see the number of rows (devices) in the cache. If you divide this number by 100 you will get an estimated time to rebuild the cache; add 20 seconds to it to get the estimated time it will take to update the WURFL file and rebuild the cache. NOTE: it may take longer to update if you are using a slower than average server, or if you are using the MySQL4 or MSSQL Database Connector.
As an example, a cache with 20000 devices in it will take about 220 seconds, or 3 minutes, 40 seconds.

Personal tools
Namespaces
Variants
Actions
WURFL DBAPI
Toolbox