Installation
From Tera-WURFL
Contents |
Installation
- Copy the files into a directory on your webserver that can be accessed from the internet. For the purposes of explaination I will refer to this location as http://yourserver.com/Tera-Wurfl/", with a local directory of "/var/www/Tera-Wurfl/".
- Open a web browser and go to: "http://yourserver.com/Tera-Wurfl/admin/install.php" you should see the Tera-WURFL Installation page with a bunch of errors on it. The next steps will show you how to correct these errors. You can refresh this page to verify that your changes have taken effect.
Configuration File
- Copy the file TeraWurflConfig.php.example to TeraWurflConfig.php, then edit it. Each setting is described in comments and on the Configuration File page. The only thing you NEED to modify is the database info (user, pass, db, etc)
NOTE: By default, Tera-WURFL is configured to use MySQL 5.x. If you are using a different database, set the DatabaseConnector accordingly.
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.
chown -R apache:apache ./data/
- Verify that the permissions errors on the installation page are fixed by refreshing the browser.
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.
- Create a new database for Tera-WURFL 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 config file, set the DB_HOST, DB_USER, DB_PASS and DB_SCHEMA.
- Verify that the database errors on the installation page are fixed by refreshing the browser. If the database tables don't exist yet they will be created for you when you load the WURFL file.
See the Configuration File page for more detailed information.
Loading the Tera-WURFL Database
- If you are satisfied with the results on the installation page, you can load the database with the WURFL data. There are three 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 the official WURFL website and load it into your database.
- The current CVS WURFL: This will download the current unreleased CVS wurfl.xml file from the official WURFL website and load it into your database.
- There will be a delay while the server loads/downloads the WURFL, then you should see something like this:
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
- Verify that the WURFL is loaded by clicking on "Statistics, Settings, Log File". You should see that there is data in your MERGE and INDEX tables. The CACHE table will fill up with cached data as devices access your site, and it will be cleared ONLY if you click on "Clear the device cache" from main administration page.
- Click on "Tera-WURFL test script" to test the installation. You can type in any user agent to search for it in the WURFL. If you have caching enabled (default), the first time you search for a user agent you will see the total number of queries that Tera-WURFL performed to find a match (unless there was no match). If there was a match, the device will be cached and the next time you search for it you will see "Total Queries: 1 (Found in cache)". Tera-WURFL only needed to perform 1 query since the devices full capabilities were cached. If you go back to the admin page and look at the settings, you will see that the CACHE now has a couple rows in it. You can verify the device was cached properly by going to "Cache Browser" from the main page and clicking on your user agent.
Security
- You should delete the admin/install.php file if everything is working ok.
- Protect your 'admin' directory by using a method specific to your web server software. For Apache, this means a .htaccess file would work.
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:
- Install Tera-WURFL at another location, like your development system, and update it from there, then copy its database up to the production environment
- 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:
- You have never updated your database from the Web Administration Page
- Your database user (specified in TeraWurflConfig.php) does not have the required permissions in MySQL
- Your TABLE_PREFIX in TeraWurflConfig.php is empty. This prevents the creation of the stored procedure.
Other MySQL Problems
- If you are using MySQL 4, you must set the Database Connector in TeraWurflConfig.php to MySQL4, NOT the default, MySQL5.
- There are some cases where using a replicated backend MySQL server will result in the Stored Procedures not being propagated to all the servers in the replication group. In this case, Tera-WURFL cannot use the Stored Procedures and must be configured to run without them.
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:
- If it's a new wireless device, it must be added to the WURFL project via http://www.wurflpro.com or the Yahoo WML Mailing List
- If it's a new desktop web browser, the user agent can be added to the web_browsers.xml file at http://wurfl.sourceforge.net by emailing the Yahoo WML Mailing List
- If it's an existing desktop web browser, you can add it to the Tera-WURFL Custom Patch File via the Web Administration Page. To do this, just go to your admin page and click on Generate Patch File, then paste the User Agent into the list and click the Generate Patch File button and go back to the main admin page and click Update WURFL from local file. This will override the entries in the WURFL file and detect the device properly.
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.