< 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>]]>