Start Trial

WURFL Snapshot Generator

Introduction

The Wireless Universal Resource FiLe (WURFL) snapshot is an XML file to be used in conjunction with one of the WURFL 'on premise’ products. The file is typically named wurfl.xml (or .zip, or .gz) and contains all the devices and licensed WURFL capabilities. WURFL APIs typically load the data in wurfl.xml during the initialization phase and will be able to match HTTP requests to a device profile and its capabilities. For this reason, WURFL users may want to update their wurfl.xml file regularly.

ScientiaMobile maintains the database of device information on an ongoing basis, with new devices being added every day to an internal repository of device information. The updated data is not available to WURFL users until ScientiaMobile makes it available (weekly) to its customers in the form of a so-called WURFL snapshot, i.e. the XML serialization of the WURFL device data. All standard APIs will know how to read the XML data available in a snapshot.

Assuming you are a licensee of one of the WURFL on-premise APIs, you have access to recent and past snapshots. Through a tool called Snapshot Generator, you can download updated wurfl.xml files either manually or automatically, either using your own update cycles or relying on the WURFL Updater function of each on-premise API. Thanks to your custom WURFL Snapshot URL, you can download updated versions of the WURFL data that contains the capabilities your organization has licensed from ScientiaMobile.

This document explains the features of the Snapshot Generator.

Applicable Products

The snapshot generator is relevant to users of all on-premise WURFL API products, i.e. WURFL OnSite and WURFL InFuze. These products will need to access a recent snapshot to be able to recognize recently released devices.

Conversely, SaaS WURFL products such as WURFL Microservice and WURFL.js do not require access to the Snapshot Generator, as ScientiaMobile is responsible for ensuring that Clous products always run with the latest and greatest version of device data.

Find Your Snapshot

The Snapshot Generator is available to you and all licensees of any of the on-premise WURFL APIs; it can be found in your customer vault.

You can find the most recent WURFL snapshot by logging into your ScientiaMobile account. Once logged in, your personalized WURFL snapshot will be available under:

My Products -> View Account (for your subscribed product) -> WURFL Snapshot Generator

Each licensed product will display a private direct download URL that can be used to download your custom built WURFL snapshot. The direct download URL has the following format: https://data.scientiamobile.com/xxxxx/wurfl.zip.

Note: xxxxx is your private WURFL snapshot download key that is linked to a specific product and capability set. If you have multiple licenses, you will have multiple WURFL snapshot download keys.

For your convenience, the snapshot is available in both .zip and .gz compressed formats. The “View Archives” link will show you the previous four WURFL snapshots along with their release dates.

Release Frequency

At ScientiaMobile, we update our (internal) WURFL repository on an on-going basis as new devices, browsers and operating system versions are released to the market. The updated data is released to customers weekly (every Sunday EST night) in the form of custom snapshots.

Note: Occasionally, we may release an out-of-band (OOB) snapshot between weekly releases. This is a relatively rare occurrence in case of a high-profile device being released mid-week or in other exception cases. Such OOB snapshot is made available to licensees through the snapshot generator.

While customers are free to choose when to update to a more recent version of the WURFL data, we encourage you to update to the newest WURFL snapshot weekly for maximum device detection accuracy.

Automating WURFL Data Updates

Updating the wurfl.xml file is a prerogative of users, i.e. ScientiaMobile is not forcing users to update the wurfl.xml when a new snapshot is released. You Can choose to update either manually or automatically. As a minimum, we warmly recommend that you update the WURFL file quarterly.

Unless you have specific needs to do things differently, you should enable the WURFL Updater – a feature included with all WURFL APIs – to enable automated downloads of newly released WURFL Snapshots as they become available. ScientiaMobile’s WURFL APIs will reach out to the snapshot generator on a regular basis and check for new WURFL snapshot releases. This feature is called WURFL Updater. Documentation on using the WURFL Updater (along with examples and code snippets for WURFL OnSite and Infuze APIs) are available here.

Direct Downloads

While we recommend using the WURFL Updater feature to keep your WURFL API installation up to date with the latest snapshot releases, there may be cases where you may want to update the file either manually or ad-hoc. In cases where direct access to a snapshot is desired, the direct download links in the “Find Your Snapshot” section will allow you to download the WURFL snapshot.

If you opt for a custom snapshot download mechanism, we recommend using one of the following methods to check for an updated WURFL:

HTTP HEAD Request: You can send an HTTP HEAD request to your direct download URL. The snapshot generator server will return the size of the current snapshot and the last-modified date. Note: Your snapshot (containing your licensed WURFL capabilities) is created “on demand” the first time you visit this link after the weekly snapshot is released. For example, assuming we released a snapshot on Sunday night (the standard schedule) and you request HEAD on the following Tuesday, the last-modified date will be Tuesday, not Sunday.
HTTP If-Modified-Since: If you include the If-Modified-Since HTTP header, the server will only return the snapshot if it is newer than the specified date.
HTTP If-None-Match / ETag: The snapshot generator sends an HTTP ETag header in along with the snapshot. If this ETag is recorded, you can send it back on subsequent requests in the HTTP If-None-Match header, and the snapshot will only be returned if it is different than yours.

The recommended method for automating downloading a WURFL Snapshot using the direct download URL is to use If-Modified-Since. Please note that dates in HTTP headers are in UTC.

Customization

Apart from the previously mentioned .zip and .gz compression options and the availability of the previous four WURFL snapshots, we offer the ability to remove devices older than a device age of your choice from the WURFL snapshot. This allows for a significant reduction in memory footprint.

This is done using the remove_older_than query parameter. The query parameter should be appended to the end of your WURFL snapshot download URL (see the “Find Your Snapshot” section for information on retrieving this URL) and can be used in both WURFL Updater and direct download use-cases. The device age restriction can be specified in either relative terms (eg. 24m for 24 months) or in absolute terms (eg. 2018_march).

For example, if https://data.scientiamobile.com/xxxxx/wurfl.zip is your WURFL snapshot download URL, https://data.scientiamobile.com/xxxxx/wurfl.zip?remove_older_than=24m would remove devices older than two years (24 months).

Note: You may still see devices older than your cut off limit in the downloaded WURFL snapshot. These are devices that are used by the WURFL API for fallback and other detection logic.

Note: The device age restriction is calculated by using the device’s release date.

The remove_older_than support for the WURFL Updater requires a WURFL API version of 1.13.0.0 or higher.