WURFL InFuze Module for golang : User Guide
=======================================

WURFL InFuze for golang is a GO language module wrapping the WURFL C API and
encapsulating it in two golang types to provide a fast and intuitive
interface. It is compatible on `linux/macos` platforms for `golang 1.7` or higher.

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](https://docs.scientiamobile.com/documentation/infuze/infuze-c-api-user-guide).
Release notes for each API can be found [here](https://docs.scientiamobile.com/documentation/changelog/infuze-api-change-log).


Installation on Linux/MacOS X
-----------------------------

InFuze for golang is available as a binary package. To install it just untar the contents in your GOPATH folder.

```
# cd $GOPATH
# tar xvzf golang-wurfl-1.9.0.0-binary.tar.gz
```

Usage
-----

Here is an example to get started using InFuze for golang:

```
package main

import (
  "fmt"
  "scientiamobile/wurfl"
)

func main() {

 wengine, err = wurfl.Create("/tmp/wurfl.zip", nil, -1, wurfl.WurflCacheProviderDoubleLru, "100000,30000")

 ua := "Dalvik/1.6.0 (Linux; U; Android 4.3; SM-N900T Build/JSS15J)"

 device, err := wengine.Lookup(ua)

 deviceid, err := device.GetDeviceId()

 fmt.Println(deviceid)

 fmt.Println(device.GetCapability("device_os"))
 fmt.Println(device.GetVirtualCapability("is_android"))

 device.Destroy()
 wengine.Destroy()
}
```

Create the wurfl engine once and then lookup UserAgent (or a request directly using `wengine.LookupRequest()`) and get the capabilities and virtual capabilities needed in your implementation (NOTE: virtual capabilities are calculated at runtime).

### <a name="updater"></a>
WURFL Updater
-------------

If you want to keep your `wurfl.zip` uptodate with the ScientiaMobile data release schedule, then you might want to use the Updater features,
available in golang 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):

```
  uerr := wengine.SetUpdaterDataURL(Url)
	if uerr != nil {
		fmt.Printf("SetUpdaterDataUrl returned : %s\n", uerr.Error())
	}
```

Specify which periodicity you would like for update checks:

```
_ = wengine.SetUpdaterDataFrequency(wurfl.WurflUpdaterFrequencyDaily)
```

Then start the updater:

```
uerr = wengine.UpdaterStart()
if uerr != nil {
  fmt.Printf("UpdaterStart returned : %s\n", uerr.Error())
}
```

Updater will run a daily 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.


API Reference
-------------

## <a name="pkg-index"></a>Index
* [Constants](#pkg-constants)
* [type Device](#Device)
  * [func (d *Device) Destroy()](#Device.Destroy)
  * [func (d *Device) GetCapabilities(caps []string) []string](#Device.GetCapabilities)
  * [func (d *Device) GetCapability(cap string) string](#Device.GetCapability)
  * [func (d *Device) GetDeviceID() (string, error)](#Device.GetDeviceID)
  * [func (d *Device) GetMatchType() int](#Device.GetMatchType)
  * [func (d *Device) GetNormalizedUserAgent() (string, error)](#Device.GetNormalizedUserAgent)
  * [func (d *Device) GetOriginalUserAgent() (string, error)](#Device.GetOriginalUserAgent)
  * [func (d *Device) GetRootID() string](#Device.GetRootID)
  * [func (d *Device) GetUserAgent() (string, error)](#Device.GetUserAgent)
  * [func (d *Device) GetVirtualCapability(vcap string) string](#Device.GetVirtualCapability)
  * [func (d *Device) IsRoot() bool](#Device.IsRoot)
* [type Wurfl](#Wurfl)
  * [func Create(Wurflxml string, Patches []string, CapFilter []string, EngineTarget int, CacheProvider int, CacheExtraConfig string) (*Wurfl, error)](#Create)
  * [func (w *Wurfl) Destroy()](#Wurfl.Destroy)
  * [func (w *Wurfl) GetAPIVersion() string](#Wurfl.GetAPIVersion)
  * [func (w *Wurfl) GetAllCaps() []string](#Wurfl.GetAllCaps)
  * [func (w *Wurfl) GetAllVCaps() []string](#Wurfl.GetAllVCaps)
  * [func (w *Wurfl) GetEngineTarget() string](#Wurfl.GetEngineTarget)
  * [func (w *Wurfl) GetInfo() string](#Wurfl.GetInfo)
  * [func (w *Wurfl) GetLastLoadTime() string](#Wurfl.GetLastLoadTime)
  * [func (w *Wurfl) GetUserAgentPriority() string](#Wurfl.GetUserAgentPriority)
  * [func (w *Wurfl) HasCapability(cap string) bool](#Wurfl.HasCapability)
  * [func (w *Wurfl) HasVirtualCapability(vcap string) bool](#Wurfl.HasVirtualCapability)
  * [func (w &ast;Wurfl) LookupDeviceID(DeviceID string) (&ast;Device, error)](#Wurfl.LookupDeviceID)
  * [func (w &ast;Wurfl) LookupDeviceIDWithRequest(DeviceID string, r &ast;http.Request) (&ast;Device, error)](#Wurfl.LookupDeviceIDWithRequest)
  * [func (w &ast;Wurfl) LookupRequest(r *http.Request) (&ast;Device, error)](#Wurfl.LookupRequest)
  * [func (w &ast;Wurfl) LookupUserAgent(ua string) (&ast;Device, error)](#Wurfl.LookupUserAgent)
  * [func (w *Wurfl) SetUpdaterDataFrequency(Frequency int) error](#Wurfl.SetUpdaterDataFrequency)
  * [func (w *Wurfl) SetUpdaterDataURL(DataURL string) error](#Wurfl.SetUpdaterDataURL)
  * [func (w *Wurfl) SetUpdaterLogPath(LogFile string) error](#Wurfl.SetUpdaterLogPath)
  * [func (w *Wurfl) SetUserAgentPriority(prio int)](#Wurfl.SetUserAgentPriority)
  * [func (w *Wurfl) UpdaterRunonce() error](#Wurfl.UpdaterRunonce)
  * [func (w *Wurfl) UpdaterStart() error](#Wurfl.UpdaterStart)
  * [func (w *Wurfl) UpdaterStop() error](#Wurfl.UpdaterStop)




## <a name="pkg-constants"></a>Constants

``` go
const (
    WurflUserAgentPriorityOverrideSideloadedBrowserUserAgent = C.WURFL_USERAGENT_PRIORITY_OVERRIDE_SIDELOADED_BROWSER_USERAGENT
    WurflUserAgentPriorityUsePlainUserAgent                  = C.WURFL_USERAGENT_PRIORITY_USE_PLAIN_USERAGENT
)
```
UserAgent priority possible values

``` go
const (
    WurflCacheProviderNone      = C.WURFL_CACHE_PROVIDER_NONE
    WurflCacheProviderLru       = C.WURFL_CACHE_PROVIDER_LRU
    WurflCacheProviderDoubleLru = C.WURFL_CACHE_PROVIDER_DOUBLE_LRU
)
```
Cache Provider possible values

``` go
const (
    WurflMatchTypeExact           = C.WURFL_MATCH_TYPE_EXACT
    WurflMatchTypeConclusive      = C.WURFL_MATCH_TYPE_CONCLUSIVE
    WurflMatchTypeRecovery        = C.WURFL_MATCH_TYPE_RECOVERY
    WurflMatchTypeCatchall        = C.WURFL_MATCH_TYPE_CATCHALL
    WurflMatchTypeHighPerformance = C.WURFL_MATCH_TYPE_HIGHPERFORMANCE
    WurflMatchTypeNone            = C.WURFL_MATCH_TYPE_NONE
    WurflMatchTypeCached          = C.WURFL_MATCH_TYPE_CACHED
)
```
Match type

``` go
const (
    WurflUpdaterFrequencyDaily  = C.WURFL_UPDATER_FREQ_DAILY
    WurflUpdaterFrequencyWeekly = C.WURFL_UPDATER_FREQ_WEEKLY
)
```
Wurfl updater frequency





## <a name="Device"></a>type Device
``` go
type Device struct {
    Device C.wurfl_device_handle
    Wurfl  C.wurfl_handle
}
```
Device represent internal matched device handle




### <a name="Device.Destroy"></a>func (\*Device) Destroy
``` go
func (d *Device) Destroy()
```
Destroy device handle, should be called when when device attributes
are not needed anymore




### <a name="Device.GetCapabilities"></a>func (\*Device) GetCapabilities
``` go
func (d *Device) GetCapabilities(caps []string) []string
```
GetCapabilities Get a list of Capabilities




### <a name="Device.GetCapability"></a>func (\*Device) GetCapability
``` go
func (d *Device) GetCapability(cap string) string
```
GetCapability Get a single Capability




### <a name="Device.GetDeviceID"></a>func (\*Device) GetDeviceID
``` go
func (d *Device) GetDeviceID() (string, error)
```
GetDeviceID Get wurfl_id string from device handle




### <a name="Device.GetMatchType"></a>func (\*Device) GetMatchType
``` go
func (d *Device) GetMatchType() int
```
GetMatchType Get type of Match occurred in lookup




### <a name="Device.GetNormalizedUserAgent"></a>func (\*Device) GetNormalizedUserAgent
``` go
func (d *Device) GetNormalizedUserAgent() (string, error)
```
GetNormalizedUserAgent Get the Normalized (processed by wurfl api) userAgent




### <a name="Device.GetOriginalUserAgent"></a>func (\*Device) GetOriginalUserAgent
``` go
func (d *Device) GetOriginalUserAgent() (string, error)
```
GetOriginalUserAgent Get the original userAgent of matched device (the one passed to lookup)




### <a name="Device.GetRootID"></a>func (\*Device) GetRootID
``` go
func (d *Device) GetRootID() string
```
GetRootID - Retrieve the root device ID of this device.




### <a name="Device.GetUserAgent"></a>func (\*Device) GetUserAgent
``` go
func (d *Device) GetUserAgent() (string, error)
```
GetUserAgent Get default UserAgent of matched device (might be different from UA passed to lookup)




### <a name="Device.GetVirtualCapability"></a>func (\*Device) GetVirtualCapability
``` go
func (d *Device) GetVirtualCapability(vcap string) string
```
GetVirtualCapability Get Virtual Capability




### <a name="Device.IsRoot"></a>func (\*Device) IsRoot
``` go
func (d *Device) IsRoot() bool
```
IsRoot - true if device is device root




## <a name="Wurfl"></a>type Wurfl
``` go
type Wurfl struct {
    Wurfl C.wurfl_handle
}
```
Wurfl represents internal wurfl infuze handle







### <a name="Create"></a>func Create
``` go
func Create(Wurflxml string, Patches []string, CapFilter []string, CacheProvider int, CacheExtraConfig string) (*Wurfl, error)
```
Create the wurfl engine.

Wurflxml - path to the wurfl.xml/zip file
Patches - slice of paths of patches files to load
CapFilter - list of capabilities used; allow to init engine without loading all 500+ caps
CacheProvider - WurflCacheProviderLru or WurflCacheProviderDoubleLru
CacheExtraConfig - size of single or double lru caches in the form "100000" or "100000,30000"





### <a name="Wurfl.Destroy"></a>func (\*Wurfl) Destroy
``` go
func (w *Wurfl) Destroy()
```
Destroy the wurfl engine




### <a name="Wurfl.GetAPIVersion"></a>func (\*Wurfl) GetAPIVersion
``` go
func (w *Wurfl) GetAPIVersion() string
```
GetAPIVersion returns version of internal InFuze API




### <a name="Wurfl.GetAllCaps"></a>func (\*Wurfl) GetAllCaps
``` go
func (w *Wurfl) GetAllCaps() []string
```
GetAllCaps return all capabilities names




### <a name="Wurfl.GetAllVCaps"></a>func (\*Wurfl) GetAllVCaps
``` go
func (w *Wurfl) GetAllVCaps() []string
```
GetAllVCaps return all virtual capabilities names




### <a name="Wurfl.GetInfo"></a>func (\*Wurfl) GetInfo
``` go
func (w *Wurfl) GetInfo() string
```
GetInfo - get wurfl.xml info




### <a name="Wurfl.GetLastLoadTime"></a>func (\*Wurfl) GetLastLoadTime
``` go
func (w *Wurfl) GetLastLoadTime() string
```
GetLastLoadTime - get last wurfl.xml load time




### <a name="Wurfl.GetUserAgentPriority"></a>func (\*Wurfl) GetUserAgentPriority
``` go
func (w *Wurfl) GetUserAgentPriority() string
```
GetUserAgentPriority - Tells if WURFL is using the plain user agent or the sideloaded browser user agent for device detection




### <a name="Wurfl.HasCapability"></a>func (\*Wurfl) HasCapability
``` go
func (w *Wurfl) HasCapability(cap string) bool
```
HasCapability - HasVirtualCapability return true is the vcap exists




### <a name="Wurfl.HasVirtualCapability"></a>func (\*Wurfl) HasVirtualCapability
``` go
func (w *Wurfl) HasVirtualCapability(vcap string) bool
```
HasVirtualCapability - HasVirtualCapability return true is the vcap exists




### <a name="Wurfl.LookupDeviceID"></a>func (\*Wurfl) LookupDeviceID
``` go
func (w *Wurfl) LookupDeviceID(DeviceID string) (*Device, error)
```
LookupDeviceID : lookup by wurfl_ID and return Device handle




### <a name="Wurfl.LookupDeviceIDWithRequest"></a>func (\*Wurfl) LookupDeviceIDWithRequest
``` go
func (w *Wurfl) LookupDeviceIDWithRequest(DeviceID string, r *http.Request) (*Device, error)
```
LookupDeviceIDWithRequest : lookup by wurfl_ID and request headers and return Device handle




### <a name="Wurfl.LookupRequest"></a>func (\*Wurfl) LookupRequest
``` go
func (w *Wurfl) LookupRequest(r *http.Request) (*Device, error)
```
LookupRequest : Lookup Request and return Device handle




### <a name="Wurfl.LookupUserAgent"></a>func (\*Wurfl) LookupUserAgent
``` go
func (w *Wurfl) LookupUserAgent(ua string) (*Device, error)
```
LookupUserAgent : lookup up useragent and return Device handle




### <a name="Wurfl.SetUpdaterDataFrequency"></a>func (\*Wurfl) SetUpdaterDataFrequency
``` go
func (w *Wurfl) SetUpdaterDataFrequency(Frequency int) error
```
SetUpdaterDataFrequency - set interval of update checks




### <a name="Wurfl.SetUpdaterDataURL"></a>func (\*Wurfl) SetUpdaterDataURL
``` go
func (w *Wurfl) SetUpdaterDataURL(DataURL string) error
```
SetUpdaterDataURL - set your scientiamobile vault https updater url




### <a name="Wurfl.SetUpdaterLogPath"></a>func (\*Wurfl) SetUpdaterLogPath
``` go
func (w *Wurfl) SetUpdaterLogPath(LogFile string) error
```
SetUpdaterLogPath - set path of updater log file




### <a name="Wurfl.SetUserAgentPriority"></a>func (\*Wurfl) SetUserAgentPriority
``` go
func (w *Wurfl) SetUserAgentPriority(prio int)
```
SetUserAgentPriority - Sets which UA wurfl is using (plain or sideloaded)




### <a name="Wurfl.UpdaterRunonce"></a>func (\*Wurfl) UpdaterRunonce
``` go
func (w *Wurfl) UpdaterRunonce() error
```
UpdaterRunonce - start updater process once and wait for termination




### <a name="Wurfl.UpdaterStart"></a>func (\*Wurfl) UpdaterStart
``` go
func (w *Wurfl) UpdaterStart() error
```
UpdaterStart - start the updater thread




### <a name="Wurfl.UpdaterStop"></a>func (\*Wurfl) UpdaterStop
``` go
func (w *Wurfl) UpdaterStop() error
```
UpdaterStop - stop the updater thread








- - -

*<b>`IMPORTANT - Decommissioning of MatchMode options`</b> Prior to version 1.9 of the API, users could choose between `MatchMode.Performance` and `MatchMode.Accuracy` 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.<br>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 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.*


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.