infuze python module user guide

PyWURFL - WURFL InFuze Module for Python

PyWURFL is a Python module wrapping the InFuze WURFL C API and encapsulating it in an object oriented manner, to provide a fast, intuitive interface. Both Python2 and Python3 builds are supported.

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.

Setup

PyWURFL is installed and tested using the Python virtualenv and easy_install utilities.

Python development headers and setuptools must also be installed.

On Debian this is done by:

$ apt-get install python-dev python-setuptools

On CentOS this is done by:

$ yum install python-dev python-virtualenv

Please note that in Python3 the virtualenv command has been superseded by pyvenv. Please check your system documentation as needed.

Also, usual C development toolchain must be available.

if needed, virtualenv can be used to create several local Python installations. This can be useful to test your code under different Python versions without polluting the "system" Python interpreter. Please refer to virtualenv documentation.

Installation

PyWURFL is distributed as a Python "egg" and can be installed using easy_install.

Once you have obtained the egg from your file manager and installed the InFuze WURFL library, you can run:

$ easy_install pywurfl-<version>-py<version>-<architecture>-x86_64.egg

Sample Usage

Here is an example to get started using PyWURFL:

#import WURFL module
from pywurfl.wurfl import Wurfl

# build an engine. Please note that the installed wurfl.zip position may change.
# for example, on OsX systems will be in `/usr/local/share/wurfl/wurfl.zip`
# on Linux system will be in `/usr/share/wurfl/wurfl.zip`.
wurfl = Wurfl('/usr/share/wurfl/wurfl.zip')

# lookup an user-agent
UA = "Mozilla/5.0 (Linux; Android 5.0; SAMSUNG SM-G925 Build/LRX21V) AppleWebKit/537.36 (KHTML, like Gecko) SamsungBrowser/4.0 Chrome/44.0.2403.133 Mobile Safari/537.36"
dev = wurfl.parse_useragent(UA)

# retrieve some properties and capabilities values

#device ID:
print("device id =", dev.id)

# some static capabilities:
static_capabilities = ["model_name", "brand_name", "device_os"]

# retrieve the value of a single static capability:
print("get_capability('brand_name') =", dev.get_capability(static_capabilities[0]))

# retrieve the value of many static capabilities at once:
print("get_capabilities(static_capabilities) =", dev.get_capabilities(static_capabilities))

# some virtual capabilities:
virtual_capabilities = ["complete_device_name", "form_factor"]

# retrieve the value of a single virtual capability:
print("get_virtual_capability('complete_device_name') =", dev.get_virtual_capability(virtual_capabilities[0]))

# retrieve the value of many virtual capabilities at once:
print("get_virtual_capabilities(virtual_capabilities) =", dev.get_virtual_capabilities(virtual_capabilities))

# release the device when not needed any more.
dev.release()

Here we create the engine object, then we obtain the device object by lookup on a UserAgent string. Then we get device properties, static, and virtual capabilities values as needed. Please note that virtual capabilities are calculated at runtime, so they might be significantly slower than static capabilities.

By running the above code, you should get an output like:

device id = samsung_sm_g925_ver1
get_capability('brand_name') = SM-G925
get_capabilities(static_capabilities) = {'model_name': 'SM-G925', 'brand_name': 'Samsung', 'device_os': 'Android'}
get_virtual_capability('complete_device_name') = Samsung SM-G925 (Galaxy S6 Edge)
get_virtual_capabilities(virtual_capabilities) = {'form_factor': 'Smartphone', 'complete_device_name': 'Samsung SM-G925 (Galaxy S6 Edge)'}

WURFL Updater

If you want to keep your wurfl.zip up-to-date with the ScientiaMobile data release schedule, then you might want to use the Updater features, available in Python WURFL as follows:

After creating your WURFL engine, set your personal WURFL Snapshot URL (in the form "https://data.scientiamobile.com/xxxxx/wurfl.zip", with "xxxxx" replaced with your personal access token, located in your license account page):

wurfl = Wurfl('wurfl.zip')
try:
    wurfl.set_updater_data_url("https://data.scientiamobile.com/<your access token>/wurfl.zip")
except Exception as exception:
    print("Error while setting updater data URL: ")
    print(exception)

Optionally, specify at which frequency you want to check for updates: (DAILY or WEEKLY, default is DAILY):

wurfl.set_updater_data_frequency(wurfl.UPDATER_FREQUENCIES['DAILY'])

Then start the updater:

try:
    wurfl.updater_start()
except Exception as exception:
    print("Error while starting the updater: ")
    print(exception)

Updater will run a periodic check for the latest release of the wurfl.zip file, download it, and update the running engine to the latest version - all during normal application operations.

The internal updater also supports simple file logging, useful in debugging network problems and the like:

wurfl.set_updater_log_path("updater.log")

Please note also:

  • The WURFL data file and the path where it resides, specified in the WURFL engine construction, MUST have write/rename access: the old data file will be replaced (i.e. a rename operation will be performed) with the updated version upon successful update operation completion, and the directory will be used for temp file creation, etc.

  • ScientiaMobile does not distribute uncompressed XML data files via updater. This means that, if you plan to use the updater, you MUST use the compressed (i.e. a ZIP or a XML.GZ) data file in the engine construction call..

Please note that set_updater_data_frequency() sets how often the updater checks for an updated data file, not how often the engine data file is actually updated.

The WURFL InFuze Updater functionality relies on availability and features of the well-known and widely available curl command-line utility. A check for curl availability is done in the set_updater_data_url() call.

IMPORTANT - Decommissioning of MatchMode options

Prior to version 1.9 of the API, users could choose between Accuracy and Performance engine optimization options. These options had been introduced years ago to manage the behavior of certain web browsers and their tendency to present "always different" User-Agent strings that would baffle strategies to cache similar WURFL queries in memory. As the problem has been solved by browser vendors, the need to adopt this strategy has diminished and ultimately disappeared (i.e. there was no longer much to be gained with the high-performance mode in most circumstances) and ScientiaMobile elected to "remove" this option to simplify configuration and go in the direction of uniform API behavior in different contexts.

When we wrote "remove" in the previous sentence, we were not being totally accurate. Customers who may find themselves in the unlikely situation of having to analyze significant amounts of legacy web traffic, may still enable the old high-performance > internal behavior by enabling the ENGINE_TARGET_FAST_DESKTOP_BROWSER_MATCH option in their engine target configuration, by passing FAST_DESKTOP_BROWSER_MATCH as a parameter when creating the engine:

Wurfl("wurfl.zip", ..., engine_target=constants.ENGINE_TARGETS["FAST_DESKTOP_BROWSER_MATCH"])

Please note that users with the old HIGH PERFORMANCE target engine will not receive an error. The old behavior will not be triggered, though. The default target (corresponding to the old High Accuracy) will be used instead.


© 2017 ScientiaMobile Inc.
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. include('layouts.partials.license-footer')