infuze node.js user guide

WURFL InFuze Module for Node.js: User Guide

This document is about the Node.js platform and how you, a developer or a system administrator, would install and configure the WURFL Module for Node.js on Unix/Linux and Windows systems.

Installing libwurfl

IMPORTANT: Installing libwurfl

In order for the Module to work it is ESSENTIAL that the libwurfl library is installed on your system. libwurfl is provided in your Customer Vault/FileX.

If you have not already installed libwurfl, instructions can be found here. Release notes for each API can be found here.

Installing the Node.js Package

IMPORTANT: The WURFL Node.js Module is available starting from WURFL version 1.5.1.2. This module is being compiled and tested on Node.js v0.10.

Starting from WURFL 1.6.0.0, the Node.js module is dependent on the nan Native Abstractions for Node.js and supports Node.js v0.12. Starting with WURFL 1.6.2.2, this dependency is declared in the package.json and will not need to be installed separately. You can install nan using the official Node Package Manager by typing:

npm install -g --save nan

We provide a wurflinfuze-XX.tgz archive containing all the required files to install our module for Node.js and a README, where XX stands for the currently used WURFL pack version.

In this archive you will also find some JavaScript examples on how to configure and test WURFL through Node.js.

Before installing the WURFL Node.js module make sure that both Node.js version 0.10.26 (or greater) and NPM (the Node.js tool to manage Node modules) are installed on your system.

Installing WURFL Node.js Module on Linux/Unix/MacOSX/Windows systems

As you can see from the official documentation, NPM works in two modes. Local mode is the default in which you can choose where to install the node modules by simply switching directories prior to launching an NPM installation. On the contrary, when NPM is set in global mode (using the -g option), it installs the packages and binaries into the directories specified by the install prefix used at the time when NPM was installed.

Once you have downloaded the Node.js module from your ScientiaMobile account, you can install the WURFL Node.js module using the global mode:

npm install -g nodejs-mod_wurfl-1.8.0.tgz

During the installation process NPM may show warnings regarding unmet dependencies. This is unrelated to WURFL and depends on which version of NPM you are using and how those dependencies are handled by NPM itself.

WURFL Node.js Module's function list

Our module exposes a set of functions to be used to setup WURFL, query WURFL for specific capabilities, get general purpose information, and so on.

WURFL functions

Function Description Availability (WURFL version)
setRoot(path_to_root_xml) This function sets the root wurfl.xml to be used by WURFL to a specific path in your file system. 1.5.1.2
addPatch(path_to_patch_xml) This function adds a patch to WURFL by taking the path to the patch xml file. 1.5.1.2
addRequestedCapability(capability_name) Adds a new capability to the capabilities filter. 1.5.1.2
setEngineTarget(wurfl_engine_target) Sets the WURFL Engine Target to either HIGH_ACCURACY or HIGH_PERFORMANCE. 1.5.1.2
setUserAgentPriority(wurfl_useragent_priority) Sets the WURFL Useragent Priority to use. Use either WURFL_USERAGENT_PRIORITY_OVERRIDE_SIDELOADED_BROWSER_USERAGENT or WURFL_USERAGENT_PRIORITY_USE_PLAIN_USERAGENT. 1.5.2
setCacheProvider(cache_mode, max_useragents, max_devices) This function sets the WURFL Cache provider to be used. Choose "cache_mode" between 0 (no cache), 1 (single LRU cache) or 2 (double LRU cache). If you choose the single LRU cache you also need to pass a "max_useragents" integer which tells how many user agents WURFL can cache. If you choose the double LRU cache instead then you also need to pass a "max_devices" integer which tells how many devices WURFL can cache. 1.5.1.2
load() Loads the WURFL Instance with the previously selected modes (engine target, cache, root xml..). 1.5.1.2
lookupUseragent(useragent) This function is responsible to query WURFL for a device matching the passed "useragent" as a string. It returns a wurfl_device_handle structure. 1.5.1.2
lookupWithHeaderResolverFunction(header_resolver) This function is responsible to query WURFL for a specific device. The header_resolver function passed as a parameter must tell WURFL how to retrieve the header values. It returns a wurfl_device_handle structure. 1.5.1.2
getDevice(device_id) This function is responsible to query WURFL for a specific device matching a specific wurfl device identifier as a string. It returns a wurfl_device_handle structure. 1.5.1.2
getLastLoadTime() This function returns a string describing the timestamp of the latest successful WURFL load. 1.5.1.2
getInfo() This function returns a string describing some information regarding the loaded wurfl.xml database. 1.5.1.2
getEngineTarget() This function returns the selected engine target. 1.5.1.2
getUserAgentPriority() Returns the currently used Useragent Priority as a string. 1.5.2

WURFL functions to be used with a wurfl_device_handle

Function Description Availability (WURFL version)
getDeviceId() This function retrieves the deviceId of a specific wurfl_device_handle as a string. 1.5.1.2
getRootId() This function retrieves the root device identifier of a specific wurfl_device_handle as a string. 1.5.1.2
getOriginalUseragent() Returns the original useragent of this device (as of WURFL database). 1.5.1.2
getNormalizedUseragent() Returns the normalized useragent of this device. 1.5.1.3
isActualDeviceRoot() Tells if this device is a root device in the device hierarchy. 1.5.1.2
hasCapability(cap) Tells if this device has a capability named "cap". 1.5.1.2
hasVirtualCapability(vcap) Tells if this device has a virtual capability named "vcap". 1.5.1.2
getCapability(cap) Gets the capability value of the capability named "cap" as a string. 1.5.1.2
getVirtualCapability(vcap) Gets the virtual capability value of the virtual capability named "vcap" as a string. 1.5.1.2
getCapabilityAsInt(cap) Gets the capability value of the capability named "cap" as an integer. 1.5.1.2
getVirtualCapabilityAsInt(vcap) Gets the virtual capability value of the virtual capability named "vcap" as an integer. 1.5.1.2
getCapabilityAsBool(cap) Gets the capability value of the capability named "cap" as a boolean. 1.5.1.2
getVirtualCapabilityAsBool(vcap) Gets the virtual capability value of the virtual capability named "vcap" as a boolean. 1.5.1.2

IMPORTANT NOTE: For examples on how to use these functions, please take a look at the JavaScript examples provided within the archive.

Testing WURFL Node.js Module on all operating systems

Together with the WURFL Node.js module files, we provide some JavaScript example files, located in the "test" directory, to demonstrate some common uses of the WURFL InFuze module for Node.js.

Assuming that you've installed our WURFL module into /usr/lib/node_modules/nodejs-mod_wurfl open a terminal and type:

 node /usr/lib/node_modules/nodejs-mod_wurfl/test/test_wurfl.js

A node.js server will be spawned listening to any IP address on port 9997. To check out some of your web browser capabilities, for example, just open a browser and go to localhost:9997. The produced output should look like this:

Device ID is: google_chrome
Is this an iOS App? false
Is this an Android App? false
Is this a Windows Phone App? false
Is this request coming from a desktop environment? true
Advertised browser: Chrome
Advertised browser version: 35.0
Advertised device OS: Mac OS X
Advertised device OS version: 10.9.3

We also provide a WurflInFuze.js wrapper which contains useful utility functions, namely:

WurflInFuze.js utility functions

Function Description Availability (WURFL version)
initialize(config, debug) This function is responsible to initialize WURFL with a series of functionalities like the cache mode and a custom capabilities filter. The first parameter "config" is a dictionary in which the keys are the functionalities names and the values are the correspondent specific values. Please refer to test_cli.js test file (included into "test" directory) for a complete example. The second parameter "debug" is a boolean which, if set to true, makes the loading process verbose. 1.5.1.2
addRequestedCapabilities(capabilities) Adds a specific set of capabilities to the capabilities filter. The "capabilities" parameter must be an array of capability names. 1.5.1.2
lookupRequest(headers) This function is useful to get a wurfl_device having passed a list of custom header names and values in the "headers" parameter. This function returns a wurfl_device_handle structure. 1.5.1.2
lookup(obj) This function is the main interface to get a wurfl_device. You can choose to pass three types of objects to this function. Specifically, you can pass a simple user-agent string, or a function which describes how to get the header values from the request object or ultimately a dictionary of header names and values (as for lookupRequest). This function returns a wurfl_device_handle structure. 1.5.1.2

IMPORTANT NOTE: If you decide to use the WurflInFuze.js wrapper you should edit the default_wurfl_root variable, which must point to the wurfl.xml database you are using as well as the required_caps variable, which is a set of specific capabilities filtered by WURFL.

License

2017 ScientiaMobile Incorporated All Rights Reserved.

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.