Start Trial

WURFL Microservice for AWS Marketplace

Using WURFL Microservice for AWS (Basic, Standard or Professional Edition) will allow you to run your own WURFL-based device detection service in your hosting infrastructure by deploying familiar AWS AMI images. If you are not familiar with AWS and the possibilities of the Amazon Cloud infrastructure, here is a good place to get started.

WURFL Microservice Client API (WM Client)

Given an HTTP Request and a device capability name, the WURFL Client API will return the corresponding property value.

You can integrate the WURFL Microservice Standard, Basic or Pro Edition with major programming languages, including:

WURFL Microservice Architecture

WURFL Microservice Server (WM Server) is a service that exposes its functions to the WURFL Microservice Client API (WM Client). The Client API depends on the availability of the WM server to work.

The following diagram explains the overall architecture of WURFL Microservice as deployed through the AWS Marketplace. The AMI will start an instance of the WM Server. In addition to supporting the REST interface for WM Clients, the service will periodically query ScientiaMobile for updates to the WURFL Device Description Repository to include the profiles of newly released devices and updated API logic.

Note 1: While the WM Client feels like a "standalone API" for most practical purposes, under the hood it requires interaction with the WURFL Microservice HTTP server (running in AWS) which introduces some latency (hugely mitigated by the built-in caching layer in the WM Client itself). For this reason, ScientiaMobile does not refer to the WURFL Microservice Client API (WM Client) as a "WURFL API" (that name is reserved for the WURFL OnSite APIs ).

Note 2: The WM Server needs to have access to ScientiaMobile servers to obtain data and updates to the API logic. In high-security scenarios, access to outside internet-based services may be blocked. In those cases, your firewall may need to be configured to allow traffic between the WM Server and ScientiaMobile: outbound internet access on TCP port 443 and DNS is required.

Note 3: communication between the WM Client API and the WM Server happens through a REST API, but this is totally transparent to users of WURFL Microservice and ScientiaMobile acknowledges this aspect of the WURFL Microservice product for sake of transparency. Unless you have a very specific use-case(s), we strongly discourage you from utilizing the REST Interface directly. Not only does the WM Client provide a caching layer (which delivers much greater performance), but ScientiaMobile reserves the right to modify the internal REST API or even to switch to different non-REST protocols in future versions of the product without notice.

Deploying the AMI and Setting up the WM Client APIs

1. Go to the AWS Marketplace

Searching for WURFL in the searchbox at the top will bring up the three ScientiaMobile listings. Direct links are provided below for your convenience.

Select the right AMI for your needs. The three AMIs only vary based on the capability set each one of them supports (Capabilities = Device Properties):

The three AMIs were designed with different use-cases in mind. Choose the WURFL Microservice version that fits your needs. You can pick Basic, Standard or Professional.

Basic

WURFL Microservice for GO,JAVA,dotNET,NODE.JS,PHP - Basic Edition

Standard

WURFL Microservice for GO,JAVA,dotNET,NODE.JS,PHP - Standard Edition

Professional

WURFL Microservice for GO,JAVA,dotNET,NODE.JS,PHP - Professional Edition

2. Select the Virtual machine instance you want to run your AMI on.

For the purposes of this document, we will pick the Professional edition, but the process is identical for the other versions (AKA "tiers"). Only the number of supported capabilities differs among AMIs.

Capability Sets supported for each of the three tiers:

Once you have chosen which AMI to deploy, click on the orange “Continue to Subscribe” button (we will pick the Standard edition for the purposes of this guide).

In the “Subscribe to this software” section you can review the WURFL Microservice offer, pricing and all documents related to your license. Click on the “Continue to Configuration” button.

On the configuration page you can choose the version of WURFL Microservice. Choose the default selected 2.0 version. Choose the AWS region where the AMI instance will be hosted and the default selected Fulfillment Option (64 bit x86 Amazon Machine Image). Then click on the “Continue to Launch button”.

We are now ready to launch our first AMI instance. To do that, select the “Launch through EC2” item on the “Choose Action” dropdown list.

Then click on the “Launch” button.

You will probably want to manage all your AMIs from the EC2 console, in order to control your AMI usage. In that case, select “Launch through EC2”.

Note: Your choice of EC2 instance should depend on how much traffic you need to process through device detection. As a rule of thumb, using EC2 t2.small (single CPU, 2GB Memory) will allow about 1000 lookups/sec. Actual throughput will be much higher for users of any of the APIs thanks to local caching. While t2.small is sufficient for development and testing, a larger instance such as c3.large is recommended for production.

To launch the WURFL Microservice AMI, you first need to pick an instance type. For the purpose of this tutorial, you can go for the t2.small type and click on the “configure instance details” button (more information on AWS AMI sizes can be found here).

For the purpose of the tutorial, the only data you need to set in this step is “Enable Auto-assign Public IP”. You can skip the add storage and tags steps and click on the “Configure Security Group” tab.

Security group configuration opens ports 80 and 22 by default. Port 80 is used to talk HTTP to the WURFL Microservice HTTP server, while port 22 allows SSH access to the AMI instance.

If for some reason, port 80 is not open by default, you will need to add it by clicking on the “Add Rule” button.

It’s now time to review our instance by clicking on the “Review Instance Launch” button.

( The screenshot that follows was “split” to fit the screen. )

Review your configuration and, if everything looks correct, click on “Launch”.

Click on the “View Instances” button to go to the dashboard that displays running AMIs.

By selecting the row of the newly created WURFL Microservice AMI instance, you’ll have access to the instance details.

Copy the IP address that you see in the “IPv4 Public IP” text field, open a browser and visit the http://<value_of_public_ip_field>/v2/status/json URL address. You should see a small JSON object that vouches for the health of your installation.

Alternatively, you can use curl from a shell terminal: assuming your IP is 3.80.89.147, the following command will confirm that the AMI has been deployed successfully and that the WM Server is up and running.

$ curl  http://3.80.89.147/v2/status/json
{
    "lookup_request": 0,
    "lookup_useragent": 0,
    "lookup_device_id": 0,
    "make_model_requests": 0,
    "server_info_requests": 8,
    "v1_capabilities_requests": 0,
    "not_found_404": 0,
    "server_uptime": 1172
}

if your instance responds with something like this, everything looks good. Your WURFL Microservice server is up and running!

The WM Client API now has a WM server to talk to. More about Client APIs later.

3. Viewing the purchased AMI under your AWS account.

You can acces the newly-created instance from your AWS Dashboard.

You will need to know the Instance IP address (<instance-ip>) to correctly configure your client API options (following step). The address can be found in your AWS dashboard.

Note: The configuration presented here is the simplest possible way to obtain a running instance of WURFL Microservice within AWS. In a real production environment, things are likely to be more complex than this and may involve making multiple instances of the product with a load balancer to distribute traffic and achieve fault tolerance. Discussion of the AWS infrastructure is outside the scope of this document.

4. (Only for first-time WURFL Microservice for AWS users) Install the WM Client API package and import the API in your project to start using it in your application.

WM Client APIs are available for the following supported languages (regardless of the capability set/tier): Go (golang), Java, .NET, Node.js and PHP.

WM Client APIs for the respective languages are provided on the ScientiaMobile public github repository:

You can find the documentation for each API here:

Maven Central, Nuget and NPM also carry the WM Client API libraries for Java, .NET and Node.js respectively.

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.