ScientiaMobile WURFL.js Basic/Standard/Pro Getting Started Guide

Introduction

WURFL.js provides access to ScientiaMobile's cloud-based WURFL Device Description Repository (DDR). With a single JavaScript snippet, developers can detect a device and its capabilities in order to better control, optimize, and track the success of their website.

Quick Start

Once you have signed up for a WURFL.js Basic, Standard, or Pro account, you will simply need to enter the hostnames of the websites from which you intend to use WURFL.js:

Customer Vault WURFL.js

If you do not want to configure a CNAME record for your account, then you can now include the following script referencing wjs.wurflcloud.com/wurfl.js in your markup:

<script src="https://wjs.wurflcloud.com/wurfl.js" crossorigin></script>

The WURFL object is now available to use:

/**
 * Example of pushing WURFL capabilities to google analytics
 */
ga('send', 'pageview', {
    'dimension1': WURFL.complete_device_name,
    'dimension2': WURFL.form_factor,
    'dimension3': WURFL.is_mobile,
    'dimension4': WURFL.is_robot
})

Async loading

WURFL.js dispatches an event called WurflJSDetectionComplete to the document node when it's finished. This allows you to include it in async mode and avoid DOM-blocking content in the document head:

<script src="https://wjs.wurflcloud.com/wurfl.js" crossorigin async></script>

In Javascript you can listen for the event:

document.addEventListener("WurflJSDetectionComplete", function(){
    console.log("WURFL.js is finished:")
    console.log(window.WURFL)
});

For example, the Google Analytics code in the previous example could be fired only after WURFL.js is finished:

document.addEventListener("WurflJSDetectionComplete", function(){
    ga('send', 'pageview', {
        'dimension1': WURFL.complete_device_name,
        'dimension2': WURFL.form_factor,
        'dimension3': WURFL.is_mobile,
        'dimension4': WURFL.is_robot
    })
})

Execution time limit

For certain devices WURFL.js will run a number of tests to identify the device. The tests are usually fast and accurate. However, if you want WURFL.js to spend more time to make the results even more reliable, you can allow more execution time. This is done by appending "?time_limit=" to the script reference. The below example will allow WURFL.js to execute for up to one second:

<script src="https://wjs.wurflcloud.com/wurfl.js?time_limit=1000" crossorigin></script>

Capabilities

A full list of available capabilities for WURFL.js Basic/Standard/Pro can be found here.

Caching

WURFL.js Basic, Standard, and Pro allows clients to cache the WURFL response on the end-user's browser in order to increase overall performance.

When testing, it is possible to disable caching by adding debug=true to the query string.

<script src="https://wjs.wurflcloud.com/wurfl.js?debug=true" crossorigin></script>

Hostnames

Hostnames are required to associate traffic with your account. Under the Associated Hostnames section of your account, you must enter the domains and sub-domains from which you will be accessing WURFL.js. By default, WURFL.js Basic, Standard, and Pro plan 3 hostnames.

DNS CNAME Support

You can name the WURFL.js Basic, Standard, or Pro service as your own by configuring your Domain Name Server (DNS) using CNAME records. Once these CNAME records are entered in the "Associated CNAME Records" section of your account. WURFL.js will honor them.

To set up an associated CNAME record, you must configure a CNAME record that points to wjs.wurflcloud.com with your DNS provider, which may or may not be the same as your web hosting provider.

You can then enter them in the CNAME section from the left navigation menu of your account.

Customer Vault WURFL.js

Note: Your DNS changes may take up to a full day to propagate.

You will be able to refer to the service in the HTML page as (assuming your CNAME entry is wjs.your-domain.com):

<script src="https://wjs.your-domain.com/wurfl.js" crossorigin></script>

HTTPS and SSL Support

HTTPS provides a level of security and trust for users of many commercial services. WURFL.js Basic, Standard, or Pro enables customers to upload their SSL certificates through their customer vault.

Using these certificates, WURFL.js Basic/Standard/Pro can serve multiple hostnames via the CNAME records using HTTPS.

Customer Vault WURFL.js

How to add GTM to Tag Manager

1) Login to Google Tag Manager:

Add New Tag

  • Click “Add new tag”

2) Select the “Custom HTML” option:

Custom HTML

3) Paste the wurfl.js tag in the HTML field:

<script type="text/javascript" src="//wjs.wurflcloud.com/wurfl.js"></script>

WURFL.js Tag

4) Scroll down and click “Triggering” to add a trigger:

Trigger

  • Choose “All Pages”

5) Give the tag a name “wurfl.js” and hit "Save":

Tag Name

6) Preview the changes:

  • Open the Developer Tools - or other way to inspect the DOM. Type “WURFL” in the console and verify that the wurfl capabilities are printed to the console:

Preview

7) Click Submit to create a new version. Give a name and description.

Submit

  • Click "Create".

8) Publish the version to make changes go live.

Add Google Analytics custom dimension snippet to Tagmanager:

1) Create a new custom HTML tag following the steps above.

2) Paste in the snippet to send WURFL data to GA through customer dimensions. Remember to check and change the indexes (please see the following link).

Snippet

3) Add triggering to your needs.

4) Save and publish.

Service Level Agreement (SLA)

WURFL.js Basic/Standard/Pro provides fully dedicated infrastructure for its customers and a Service Level Agreement with a 99.99% uptime target. The definition of the SLA can be found in the license agreement here.

License

2021 ScientiaMobile Incorporated.

The complete WURFL.js Basic/Standard/Pro License can be found here.