Getting Started

Introduction

Welcome to the WURFL Cloud Client. The WURFL Cloud Client is your interface to the WURFL Device Description Repository (DDR) which contains detailed definitions for thousands of mobile devices. With it you can build a mobile web site that functions across all mobile platforms including smart phones, feature phones, tablets, and game consoles. Using the WURFL Cloud Client is simple and straightforward. All that is needed is a few lines of code to query the DDR which will return the latest device definition. By using the device definition you can then generate the appropriate markup to create an optimized mobile experience for your visitors. The WURFL Cloud Client is currently available for Java, PHP, Ruby, and .NET environments.

Assumptions

This document assumes you have a basic working knowledge of current web technologies. You should understand how to set up and build website projects using your platform of choice (Java, .NET, PHP or any other platform for which ScientiaMobile offers a Cloud Client). You can continue to use the development tools you are familiar with. There are no special software tools needed. Using the WURFL Cloud Client does not require that you change the way you develop software. If you are using Eclipse, NetBeans, Zend Studio, or similar IDE you can continue to do so.

System Requirements

The system requirements listed here are the minimum for the WURFL Cloud Client to operate properly. These requirements do not address the capacity of your system to handle incoming user requests. The WURFL Cloud and WURFL Cloud Client have undergone extensive capacity and functional testing and can easily handle very large numbers of requests. All capacity questions concerning your systems should be directed to your IT department.

PHP 5.3+ with "json" extension (normally installed by default).
The "curl" extension is recommended.
  • Java version 1.5
  • Tomcat 5.0
  • .NET Framework 2.0 or higher
  • Ruby 1.9.2
  • Install the following modules:
    • rubygems
    • json
    • rack
  • Node.js 0.8.2 or higher
  • Perl 5.8
  • A PSGI compatible web framework (such as Catalyst, Dancer, Mojo and many others)

Create an Account

A WURFL Cloud account lets you access the most up to date WURFL Device Description Repository. There are four Plans to choose from. Pick the one that best meets your needs.

1. Go to http://www.scientiamobile.com/cloud and click the Sign Up button below the Plan you would like to purchase. The Free, Basic, and Standard plans all use a cookie cacheing method on the device. Premium plans use server side cache. With the Premium version you can look in the cache for a detection of a similar device before going to the WURFL Cloud. Whereas the other plans must go to the WURFL Cloud for every new device request.

Figure 1 - WURFL Cloud Plans

2. Complete the Sign Up form and click the Complete Order button. If you are signing up for the Free Plan you will not need to provide any credit card information.

Important Note: Subscribers to the Free Plan should be aware that the operation of the service involves a substantial investment and that ScientiaMobile offers Free Accounts at a loss as a public service to the hobbyist, non-profit, micro-business, and similar communities. While there is no requirement that you certify you belong to such a community, we request you consider purchasing an account if your website is a significant source of revenue generation.

You are not allowed to open more than one Free Account for yourself in your individual capacity or more than one Free Account for any other person or entity, even if you or such other person or entity operate multiple distinct websites.

Figure 2 - WURFL Cloud Account Form

3. You will receive a confirmation email from ScientiaMobile. It will contain a link to activate your account. Click on the link to activate your account. You will be directed to the Account Settings page.

Figure 3 - WURFL Cloud Account Settings

Account Settings is where you manage your WURFL Cloud Account. The following sections discuss some of the features available through Account Settings.

Select Your Capabilities

Once you have activated your account its time to select the capabilities you want to enable. The table below lists a few of the more popular capabilities used to build mobile websites. The full list of over 550 capabilities is listed on the ScientiaMobile website at: http://www.scientiamobile.com/wurflCapability/.

To select which capabilities are enabled for your Account click on the Capabilities link on the left side of the Account Settings page. The Capabilities page will be displayed. The left side of the page lists all of the available capabilities. The right side lists the capabilities enabled for your account along with Trash and the Save button.

CapabilityTypeDescription
ux_full_desktop Boolean

True if the device is a full desktop web browser

is_wireless_device Boolean True if a device is generally considered wireless. Specifically a mobile phone, PDA, and tablet are considered wireless devices, while a desktop PC or laptop are not.
is_tablet Boolean True if a device is generally considered a tablet.
brand_name String The brand of the device (ex: HTC).
model_name String The model of the device (ex: Incredible).
device_os String The Operating System of the device (ex: Android).
device_os_version String The specific version of the device's Operating System (4.0).
Table 1 - Popular Capabilities
Figure 4 - WURFL Cloud Capabilities Selector

The available capabilities can be searched or filtered. To search type into the Search text box. Capabilities that match what you type appear instantly. Selecting a Group will show the capabilities within that Group.

A description of the capability and what values it may contain is displayed if you place your cursor over the orange question mark icon.

Once you have found a capability you want to enable simply drag and drop it onto the horizontal black bar on the right side of the page. The capability will be placed above the black line. If you go over the number of capabilities allowed within your account an error message will be displayed and the capability will turn red and be placed below the black line as an inactive capability.

Figure 5 - Active Capabilities

To remove a capability select and drag and drop it over the Trash area. A message indicated that the capability was removed will be displayed. If you delete an active capability the first inactive capability will be moved up into the active section.

Figure 6 - Confirmation Message

Once you are satisfied with your selections click the Save button.

Cloud Client Installation

Once you've selected your capabilities the next step is to download the WURFL Cloud Client software. The WURFL Cloud Client is available for most development environments. You can use whichever version you choose. To get the software click on the Download Client Code button for the version you wish to use on the Account Setting page.

After you download the WURFL Cloud Client software you need to configure it and add it to you project. The way that this is done will vary depending on which version of the software you downloaded and what software development tools you use. Below are general instructions for setting up the WURFL Cloud Client software.

Whichever approach you take to build your mobile site you will need your API Key to access the WURFL Cloud.

Figure 7 - API Keys

To access your API Key click API Keys on the left side of the Account Setting page. The API key will be listed in the center of the page.

Extract the contents of the downloaded file to a directory accessible from your web application.

The steps listed here were performed using the Eclipse IDE for Java EE Developers. However, you should be able to use the IDE of your choice.

  1. Extract the contents of the downloaded file
  2. Create a new Web Project
  3. Create a new servlet
  4. Add the WURFL Cloud Client code to the WEB_INF lib folder or to the CLASSPATH.
  1. Create a new ASP.NET project in Visual Studio. You can create any type of ASP.NET project as long as it is compatible with the .NET Frameworks 2.x, 3.x, and 4.0.
  2. Add a reference to the ScientiaMobile.WurflCloud.dll assembly
Extract the contents of the downloaded file to a directory and run:
									$ pip install -r requirements.txt
									$ python setup.py build
									$ python setup.py install
								
Download the latest gem of WURFL Cloud Client for Ruby library from ScientiaMobile.com portal site. Then, run the following command:
									gem install wurfl_cloud_client-0.X.Y.gem
								
Download and extract NodeWurflCloudClient and Libraries folders in the folder where your Node code is. Include the following lines in your code:
									var wurfl_cloud_client = require("./NodeWurflCloudClient/WurflCloudClient");
									var config = require("./NodeWurflCloudClient/Config");
								
Download and extract the latest gem of WURFL Cloud Client for Perl library from ScientiaMobile.com portal site. Then, run the following command:
									$ cd /Net-WURFL-ScientiaMobile/
									$ cpanm .    #(or any other mechanism to install perl module)
								
Optionally, you can install the Plack::Middleware::WURFL::ScientiaMobile module if you want to use the middleware.

Start Coding

Create a new PHP file with the following contents:

									<?php 
									// Include the autoloader - edit this path! 
									require_once '../src/autoload.php'; 
									
									// Create a configuration object  
									$config = new ScientiaMobile\WurflCloud\Config();  
									
									// Set your WURFL Cloud API Key  
									$config->api_key = 'xxxxxx:xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx';   
									
									// Create the WURFL Cloud Client  
									$client = new ScientiaMobile\WurflCloud\Client($config);  
									
									// Detect your device  
									$client->detectDevice();  
									
									// Use the capabilities  
									if ($client->getDeviceCapability('ux_full_desktop')) {  
									    echo "This is a desktop device";  
									} else {  
									    echo "This is a mobile device";
									}
								

Now replace xxxxxx:xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx with your API Key

You can use $client->getDeviceCapability() to get the value of a capability. Note that if you haven't selected the ux_full_desktop capability, you will need to modify the example and use one of your capabilities instead.

Please refer to the downloaded package for complete examples of the WURFL Cloud Client.

In the servlet file add the following import statements:

									import com.scientiamobile.wurflcloud.CloudClientLoader;
									import com.scientiamobile.wurflcloud.CloudClientManager;
									import com.scientiamobile.wurflcloud.device.AbstractDevice;
								

Now, add the following properties:

									private static final String API_KEY = "xxxxxx:xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx";
									private CloudClientManager cloudManager; 
								

Replace xxxxxx:xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx with your API Key in the API_KEY property.

In the servlet init() method insert the following in the try block:

									CloudClientLoader loader = new CloudClientLoader(API_KEY);
									manager = loader.getClientManager();
								

In the doGet(HttpServletRequest request, HttpServletResponse response) method, insert the following code:

									AbstractDevice device = manager.getDeviceFromRequest(request, response);
									Object deviceCapability = device.get("is_wireless_device");
								

Replace is_wireless_device with the capability name that you want to test in the device.get() function call

Test the value returned into deviceCapability to determine how to handle the request.

Please refer to the downloaded package for complete examples which use of the WURFL Cloud Client.

The code snippets provided here are written in C#.NET.

1. Create a new C# class file in the project and call it WurflService.cs

2. In the class add the following namespaces:

									using ScientiaMobile.WurflCloud;
									using ScientiaMobile.WurflCloud.Config;
									using ScientiaMobile.WurflCloud.Device;
								

3. In the class insert the following code:

									public DeviceInfo GetDataByRequest(HttpContextBase context)
									{
										var config = new DefaultCloudClientConfig
										{
											ApiKey = "xxxxxx:xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
										};
	
										var manager = new CloudClientManager(config);
	
										// Grab data
										var info = manager.GetDeviceInfo(context);
										return info;
									}
								

4. Insert your API Key into the ApiKey property of the DefaultCloudClientConfig class added in step 3.

5. Use the Get ("capability_name") method on DeviceInfo to extract and test a request for a particular capability.

Please refer to the downloaded package for complete examples which use of the WURFL Cloud Client.

Create a new JSON-based config file (e.g. "filecache_config.conf") and place your WURFL API Key:

									{
										"api": {
											"version": "v1",
											"key": "xxxxxx:xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
											"server": "api.wurflcloud.com"
										},
										"http": {
											"timeout": 1000,
											"compression": true
										},
										"cache": {
										   "type": "file",
										   "file": "cloud_cache.db",
										   "expiration": 86400
										},
										"misc": {
											"report_interval": 60
										}
									}
								

In your code, add the following import statements:

									from wurfl_cloud import Cloud as WurflCloud
									from wurfl_cloud import utils
								

Initilize the WURFL Library:

									# Create a Wurfl Cloud Config
									config = utils.load_config('filecache_config.conf')
	
									# Create a WURFL Cache Loader
									cache = utils.get_cache(config)
	
									# Create a WURFL Cloud Client
									client = WurflCloud(config, cache)
								

Get device capabilities from HTTP Requests:

									ua = 'Nokia3650/1.0 UP.Browser/6.2' # Presented as an example
									device = self.Client(ua, capabilities=["ux_full_desktop", "model_name", "brand_name"])
								

You can configure the client passing a block to the WurflCloud.configure method

									WurflCloud.configure do |config|
									  config.host = 'api.wurflcloud.com'
									  config.api_key = 'xxxxxx:xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx'
									end
								

To detect a device in Ruby on Rails application, you can use the wurfl_detect_device method including WurflCloud::Helper and passing the current http environment:

									include WurflCloud::Helper
									@device = wurfl_detect_device(env)
								

Then you can use the @device to get its id or its capabilities:

									@device['is_wireless_device']
								

In a ruby on rails application the wurfl_detect_device method is available both in the controllers and in the views

Before you run WurflCloud Client, you will need to define your API Key:

									var api_key = "xxxxxx:xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx";
									var configuration = new config.WurflCloudConfig(api_key);
								

After you have installed and configured the WURFL Client, here's the example code to run the API Request:

									var brand;
									var result_capabilities = {};
									var WURFLCloudClientObject = new wurfl_cloud_client.WurflCloudClient(configuration, HttpRequest, HttpResponse);
										WURFLCloudClientObject.detectDevice(HttpRequest, null, function(err, result_capabilities){
										WURFLCloudClientObject.getDeviceCapability('brand_name', function(error, brand){
											if(error!=null){
												console.log('Error' + error);
											}else{
												console.log('Brand name: ' + brand);
											}
										});
									});
								

You should see the brand name of your device in the console provided that you have selected brand_name in your capabilities section on the Account Settings page.

Example using Dancer without middleware

Here's an example code using Dancer without the middleware code:

									use Dancer;
									use Net::WURFL::ScientiaMobile;
	
									# Create the client
									my $scientiamobile = Net::WURFL::ScientiaMobile->new(
										api_key => 'xxxxxx:xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx',
									);
	
									get '/' => sub {
										# Detect your device
										$scientiamobile->detectDevice(request->env);
	
										# Use the capabilities
										if ($scientiamobile->getDeviceCapability('ux_full_desktop')) {
											return "This is a desktop web browser";
										} else {
											return "This is a mobile device";
										}
									};
								

Example using Dancer with Plack middleware (Optional)

Here's an example code using Dancer with Plack middleware, in your config.yaml, add the following:

									plack_middlewares:
									   -
										  - WURFL::ScientiaMobile
										  - api_key
										  - xxxxxx:xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
								

Then, read back the data in your Dancer's route handler:

									get '/' => sub {
										# Detect your device
										my $scientiamobile = Plack::Middleware::WURFL::ScientiaMobile
											->get_from_env(request->env);
	
										# Use the capabilities
										if ($scientiamobile->getDeviceCapability('ux_full_desktop')) {
											return "This is a desktop web browser";
										} else {
											return "This is a mobile device";
										}
									};
								

You should see the brand name of your device in the console provided that you have selected brand_name in your capabilities section on the Account Settings page.

Testing the WURFL Cloud Client

After building and deploying your project to your test server you can visit it with your desktop web browser. However, nothing can substitute for testing with actual mobile devices as the browsers on these devices can render pages significantly different than your desktop browser.

The URL you use will depend on your development environment.

Assuming that you created a file called mywurfltest.php and placed it in the root directory of your Apache web server you should be able to access it using this URL:

http://localhost/mywurfltest.php

Assuming that:

  • You built an application called WurflCloud and a servlet called client
  • You placed the war file in the webapps directory of Tomcat
  • Your tomcat is listening on port 8080 for inbound HTTP traffic (this is normally the default port for Tomcat out of the box)
  • You should be able to access the servlet at this URL: http://localhost:8080/WurflCloud/client

Assuming that you built and published an application called mywurfltest to IIS you should be able to access it using this URL:

http://localhost/mywurfltest

Web browser demo

										$ cd examples/
										$ python example_web.py 

Now that the server's running, visit http://localhost:8000/ with your web browser.

There is an example Ruby on Rails application in the wurfl_cloud_client_example folder that demonstrates the usage of the WURFL Cloud Client for Ruby. Please refer to the wurfl_cloud.rb initializer and the demo_controller details to see how visitor's devices are detected.

										$ cd wurfl_cloud_client_example/
										$ rails server 

Now that the server's running, visit http://localhost:3000/ with your web browser.

There is an example Node.js application found in the package file.

  • Download and extract all the files in a folder.
  • Inside the exampleApp.js enter your own WURFL Cloud api key.
  • Select "brand_name" and "is_wireless_device" as your capabilities in ScientiaMobile WURFL Cloud website.
  • Run the example application by using this command "node index.js".

Now that the server's running, visit http://localhost:8888/ with your web browser. Choose either Example or Example2, you should see the brand name of your device and whether it is wireless or not.

Here's our quick guide to get Dancer up running with the Perl example code above:

										$ wget -O - http://cpanmin.us | sudo perl - Dancer
										$ dancer -a MyApp
										$ cd MyApp
										$ nano lib/MyApp.pm   # inject the example code from above
										$ bin/app.pl
									

Now that the server's running, visit http://localhost:3000/ with your web browser.

To test that you are correctly handling device capabilities returned by the WURFL Cloud Client without a mobile device you will need to simulate mobile HTTP requests. There are several ways to do this. One way is to use the User-Agent Switcher plugin for the Firefox desktop web browser. Once you have downloaded and installed the plugin it is recommended that you restart Firefox.

Recent versions of Firefox do not automatically display the User-Agent Switcher menu or toolbar button. As a result you may need to add the toolbar icon yourself. To do this select Toolbar Layout from the Options menu.

Figure 8 - Firefox Menu

Locate the Default User Agent icon in the Customize Toolbar window. Click and drag the icon to the toolbar. Click the Done button. The User-Agent Switcher is now ready to use.

Figure 9 - Customize Toolbar Window

To change the user-agent of the browser click the User-Agent Switcher icon and select a user agent from the menu.

Figure 10 - User-Agent Switching Menu

Note: By default the user-agent switcher comes with the user-agent strings of desktop web browsers. To help you to get started here are a few user-agents for a variety of mobile devices:

iPad iOS5 - Mozilla/5.0 (iPad; U; CPU iPhone OS 3_2 like Mac OS X; xx-xx) AppleWebKit/ 531.21.10 (KHTML, like Gecko) Mobile/7D11

iPhone iOS5 - Mozilla/5.0 (iPhone; CPU iPhone OS 5_0 like Mac OS X) AppleWebKit/534.46 (KHTML, like Gecko) Version/5.1 Mobile/9A334 Safari/7534.48.3

Motorola DROID PRO - Mozilla/5.0 (Linux; U; Android 2.2; xx-xx; DROID PRO Build/S275) AppleWebKit/525.10+ (KHTML, like Gecko) Version/3.0.4 Mobile Safari/523.12.2

Nokia N70 (older Symbian device) - NokiaN70

Nokia LUMIA 800 (Windows Phone 7.5) - Mozilla/5.0 (compatible; MSIE 9.0; Windows Phone OS 7.5; Trident/5.0; IEMobile/9.0; NOKIA; Lumia 800)

HTC HERO - Mozilla/5.0 (Linux; U; Android 1.5; xx-xx; hero) AppleWebKit/525.10+ (KHTML, like Gecko) Version/3.0.4 Mobile Safari/523.12.2

Important: By default, the WURFL Cloud uses client-side cookies to cache device information in the browser. As a result you will need to temporarily disable cookies in your desktop web browser to test for different devices. The method to disable cookies varies from browser to browser. Below are instructions for Firefox. For other browsers, please refer to your browsers documentation.

From the Firefox menu select Options.

Figure 11 - Firefox Privacy Options

In the Options window click the Privacy panel.

Select Use custom settings for history from the Firefox will dropdown.

Uncheck Accept cookies from sites and click the OK button.

A second option you can use is GNU Wget which comes in virtually all Linux installations.

Wget is a tool that can retrieve files using HTTP. You can set the user-agent for the request with the -U directive. A wget command would look like this:

wget -O - -U "NokiaN95" http://yourserver/yourapp/yourservletOrHandlerOrPHP

Additional Help

For additional help you can visit the following sites:

ScientiaMobile Forums: http://www.scientiamobile.com/forum/
WURFL on SourceForge: http://wurfl.sourceforge.net/index.php
ScientiaMobile Blog: http://www.scientiamobile.com/blog/post
ScientiaMobile Support: http://www.scientiamobile.com/support