# DeviceAtlas Go API # The DeviceAtlas Go API provides a way to detect devices based on the data found in HTTP headers. Using these headers, the API returns device information such as screen width, screen height, is mobile, vendor, model etc. To see a full list of properties in DeviceAtlas please visit: https://deviceatlas.com/resources/available-properties . ### Data File ### The DeviceAtlas API relies on a device data file to function. DeviceAtlas provides daily data file updates so it is recommended to download the data file on a regular basis. This can be done manually from your account page or automated via the https://deviceatlas.com/getJSON page. For more information please see: https://deviceatlas.com/resources/getting-the-data ## Requirements ## The DeviceAtlas Go API is a wrapper around the DeviceAtlas C API and requires the following: - DeviceAtlas C API - Go (v1.3.1 or later) Go is often available for install via the system package manager. If this is not the case it can be downloaded from the [Go website](https://golang.org/) or [installed from source](https://golang.org/doc/install/source). ## Building the Go API ## There are two steps to build the Go API: 1. Build and install the DeviceAtlas C API library. 2. Build the Go API wrapper itself. ### Step 1: Building the C API library ### The C API library is available for [download](https://deviceatlas.com/resources/download-enterprise-api) with the complilation instructions enclosed in the package or [available online](https://docs.deviceatlas.com/apis/enterprise/c/2.1.2/README.DeviceApi.html). A summary of instructions to build and install the C API library `libda.so` are below: ```sh cd deviceatlas-enterprise-c-{version}/Src cmake . make sudo make install sudo ldconfig /usr/local/lib ``` Note: On Solaris and Illumos, Go only supports 64 bits architectures. For these the C API must be explicitly compiled in 64 bits. ```sh cd deviceatlas-enterprise-c-{version}/Src cmake -DCMAKE_C_FLAGS="-m64" make sudo make install sudo ldconfig /usr/local/lib ``` Note: For Windows based operating systems, please refer to the README.Windows documentation in the C API root folder. ### Step 2: Building the Go API wrapper ### The following commands build the Go API as a static compiled binary file called `deviceatlas.a`. ** Unix operating systems ** ```sh cd deviceatlas-enterprise-go-{version}/ export GOPATH=$PWD go build deviceatlas ``` ** Windows / Powershell ** ```sh > cd deviceatlas-enterprise-go-{version}/ > $env:GOPATH=pwd > go build deviceatlas ``` ** Windows / cmd ** ```sh > cd deviceatlas-enterprise-go-{version}/ > set GOPATH=<absolute path to the go wrapper> > go build deviceatlas ``` ### Additional options ### #### Custom C API Library path #### If the Enterprise C API library (libda.so) is not installed in a system path location, additional environment variables are necessary. 1. CGO_CFLAGS - the path to the C API header files. 2. CGO_LDFLAGS - the path to the C API library ** C API installed in a custom location ** ```sh CGO_CFLAGS="$CGO_CFLAGS -I/custom/path/header/files" \ CGO_LDFLAGS="$CGO_LDFLAGS -L/custom/path/library/files" \ go build deviceatlas ``` ** C API not installed in the system ** ```sh CGO_CFLAGS="$CGO_CFLAGS -I<path to the C API>/Src" \ CGO_LDFLAGS="$CGO_LDFLAGS -L<path to the C API>/Src -Wl,-rpath,<path to the C API>/Src" \ go build deviceatlas ``` Note: On Windows, the PCRE and C API DLLs locations must be present in the PATH environment variable. ## Basic Usage ## The following example code shows DeviceAtlas Go loading the data file and using a property name to find a certain value for a given User-Agent string. ** Load the JSON data file ** ```go package main import ( "deviceatlas" "fmt" ) func main() { var jsonpath string = "/path/to/DeviceAtlas.json" var da *deviceatlas.DaGo da = deviceatlas.New() if _, err := da.LoadDataFromFile(jsonpath); err == nil { // Implementation CODE } else { fmt.Printf("%s\n", err) } da.Free() } ``` ** Look-up the properties for a given User-Agent string ** See the sample code above how to initialize the `da` object. ```go m := make(map[string]string) m["user-agent"] = "Mozilla/5.0 (Linux; Android 5.1.1; SM-G928X Build/LMY47X) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/47.0.2526.83 Mobile Safari/537.36" // Get the properties and iterate through them if props, err := da.Detect(m); err == nil { fmt.Printf("%d properties\n", len(props)) for k, v := range props { fmt.Printf("%s => ", k) fmt.Println(v) } } else { fmt.Printf("%s\n", err) } ``` ** Reload the JSON data file ** Beware the LoadDataFromFile function is meant to be called before or out of multithread context. It is possible to create a new instance of the API and start using it after the load and before destroying the old instance. ```go reload_json() { new_instance := deviceatlas.New() new_instance.LoadDataFromFile(path) // Swap instances old_instance := active_instance active_instance := new_instance old_instance.Free() ...using new_instance from now on... } ``` ## Code Examples ## There are multiple Go command line mini-applications available at the project root level under the `src/examples/` folder. The cli.v1 dependency is required to run the examples. It can be installed via Go. Note that Go in turn requires Git to install dependencies. ```sh go get gopkg.in/urfave/cli.v1 ``` The examples can be compiled to native executables via `go build` tool, or run as a script via the `go run` command. The usage of each example can be displayed via `help` as unique argument. ```sh go run src/examples/example1.go help ``` Note: These examples are meant to be run under a shell so quotes around the input values may be necessary. ### Example 1 ### #### Simple look-up #### Given a User-Agent, `example1.go` will print out DeviceAtlas detected properties and the JSON metadata information. ```sh go run src/examples/example1.go -j <path to json file> -u <user-agent> ``` ### Example 2 ### #### Simple look-up with Client-Side #### Given a User-Agent and a Client-Side, `example2.go` will print out DeviceAtlas detected properties. ```sh go run src/examples/example2.go -j <path to json file> -u <user-agent> -c <client-side> ``` ### Example 3 ### #### Multiple headers look-up #### Given a User-Agent, an optional Client-Side and optional Accept-Language, `example3.go` will print out DeviceAtlas detected properties. ```sh go run src/examples/example3.go -j <path to json file> -u <user-agent> [-c <client-side> -a <accept-language>] ``` ### Example 4 ### #### Concurrent look-ups #### Given a list of User-Agent strings, with one User-Agent string per line, `example4.go` will run several lookups via concurrent goroutines. ```sh go run src/examples/example4.go <path to json file> <user agents file list> ``` ### Web Example ### Starts a HTTP server, initialises Device Atlas, loads the JSON file, and serves content with information detected by DeviceAtlas using HTTP headers. The view will show a HTML page with a section containing the input HTTP headers, as well as another one with the Detected properties. Please note there is a dependency needed to run this example, which can be installed via `go get github.com/braintree/manners`. ```sh go run src/examples/web/web_example.go --json <path to json file> ``` Go to `http://localhost:8180/` or override the default port with the `--port` flag. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - _ Copyright (c) DeviceAtlas Limited 2021. All Rights Reserved. _ https://deviceatlas.com <!-- HTML+JS for document formatting when opened in browser --> <div class="btn-group" id="main-menu" style="float:right"><a class="btn dropdown-toggle" data-toggle="dropdown" href="#">Menu<span class="caret"></span></a><ul class="dropdown-menu"><li><a href="README.html">Main</a></li><li class="disabled"><a href="README.DeviceApi.html">Go API</a></li><li><a href="README.ClientSide.html">Client-side Component</a></li><li class="divider"></li><li><a href="ApiDocs/index.html">DeviceAtlas ApiDocs</a></li></ul></div>