# DeviceAtlas Device API Usage Go # This document describes the DeviceAtlas API and how it is used. The DeviceAtlas Device Identification API consists of two libraries. A core library containing all of the main identification logic and a secondary extension library to allow for easier integration into a web application context. ## Library files ## ** DeviceAtlas Enterprise API (deviceatlas-enterprise-java-3.1.9.jar) ** This is the main library and is responsible for loading the data file and provides the logic for device identification. Device identification is achieved by either passing individual identifiers (e.g. User-Agent) or by passing in a Map of HTTP header data along with optional Client-side properties. ** DeviceAtlas Enterprise API Web (deviceatlas-enterprise-java-web-3.1.9.jar) ** This is an extension of the above library to allow passing of a `HttpServletRequest` object. The library will automatically use the necessary headers from the `HttpServletRequest` object to perform the device identification. In a web context, it is recommended to pass the full `HttpServletRequest` object rather than individual User-Agents to the library. ** Third Party Dependencies ** This library does not depend on any third party libraries. ## Data File ## The DeviceAtlas API relies on a device data file to function. The download package contains a full sample data file. For a full list of the available properties please see the [properties](https://deviceatlas.com/properties) page. > **Note:** The data file downloadable from the DeviceAtlas website is only compatible with the production 2.x APIs. It will not work with this API. Please use the provided sample data file instead. ## Client Side Library - Apple Device Identification ## In addition to the server-side API, an optional client-side Javascript library is available. This library is important for two reasons: 1. It facilitates identification of Apple devices. Apple devices are _not_ identifiable using only HTTP User-Agent data. 2. It allows for the collection of dynamic or changing properties. When the client-side library is embedded in a web page it collects additional properties from the client's web browser. This data is then sent back to the server and must be passed to the DeviceAtlas API along with the HTTP headers. The combination of the client data and the server side data allow for accurate identification of Apple devices. The client-side library may be included on a webpage by adding the following snippet: ```Javascript <!-- Adding the DeviceAtlas client side component to get client side properties --> <script type="text/javascript" src="https://cs-cdn.deviceatlas.com/dacs.2.2.beta.js" async></script> ``` By default, the client-side library returns the data via a cookie. If this is present in the `HttpServletRequest` object it will be automatically used. The cookie name is configurable via the `Config` class. Alternatively, the client data may be returned via AJAX and passed to the server side API manually. For additional information, please see the [Client Side Library](https://docs.deviceatlas.com/apis/clientside/latest/README.ClientSide.html) documentation. ## Setup & Usage ## The usage of the DeviceAtlas server side library is straightforward. In all cases, the data file must be loaded before any device identification calls are made. > **Note:** It is highly recommended to ensure the data file is only loaded once. This is particularly important for batch processing and web applications. ### Requirements ### - A C compiler (C++ compiler for the wrapper) - CMake 2.8 (or above). The following compilers have been tested and are able to compile all components: - GCC (4.2 or above (5.x, 7.x and onwards are recommended, the 6.x versions could possibly impact negatively the performances due to optimisations bugs)). - Clang 3.x or above. - TinyCC 0.9 or above. ### Build ### The API is compatible with ASLR with PIE enabled. #### Ubuntu/Debian #### ```shell % sudo apt-get install gcc (or clang) cmake ``` #### RedHat/CentOS #### ```shell % sudo dnf install gcc (or clang) cmake ``` #### MacOS #### ```shell % brew install gcc (or clang ; not necessary if clang from XCode is already installed) cmake ``` #### FreeBSD ### ```shell sudo pkg install gcc<any version> (or llvm<any version>) if another compiler different from the base system is preferred ``` ### Install the API (Optional) ### ```shell % cd <path to the extracted api archive> % sudo make install % sudo ldconfig ``` ### Usage Examples ### The following sections shows how to call the DeviceApi. Please note that exception handling has been omitted for brevity. #### EXAMPLE 1: Basic Usage - Single User-Agent #### ```go // (1) create an instance with default API settings da := device.New() defer da.Free() // (2) load the data file _, err := da.LoadDataFromFile("/path/to/datafile.json") if err != nil { // handle the errors related to loading the data file } // (3) look up device properties var headers map[string]string headers["user-agent"] = "Mozilla/5.0 (Linux; Android 11; SM-G998B) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/87.0.4280.141 Mobile Safari/537.36"; properties, err := da.Detect(headers) if mobileDevice, ok := properties["mobileDevice"]; ok { // do something } ``` #### EXAMPLE 2: Passing Client Side Data #### The data collected by the DeviceAtlas Client-side Library is automatically passed when a `HttpServletRequest` is used. If a `HttpServletRequest` object is not available the client-side data can be passed manually as a second parameter to the `getProperties()` method. ```go ... headers["user-agent"] = "Mozilla/5.0 (Linux; Android 12; SM-G998B) AppleWebKit/537.36 (KHTML, like Gecko) Version/4.0 Chrome/ Mobile Safari/537.36"; headers["daprops"] = "scsVersion:2.1|bcookieSupport:1|bcss.animations:1|bcss.columns:1|bcss.transforms:1|bcss.transitions:1|sdeviceAspectRatio:1795/1010" ... ``` #### Additional Examples #### Please find more complete examples in the /Examples directory. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - _ Copyright (c) DeviceAtlas Limited 2023. 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><a href="README.DeviceApi.html">Device API Usage C</a></li><li><a href="README.ClientHints.html">Client Hints Support</a></li><li><a href="README.CarrierApi.html">Carrier Identification API</a></li><li><a href="README.Upgrade.html">Device API Upgrade</a></li><li><a href="README.Cpp.html">Device API C++</a></li><li><a href="README.Nginx.html">NGINX Module</a></li><li><a href="README.Apache2.html">Apache2 Module</a></li><li><a href="README.JsonConverter.html">Device Identification API C JSONConverter</a></li><li class="disabled"><a href="README.Go-DeviceApi.html">Device API Usage Go</a></li><li><a href="README.Go-Upgrade.html">Device API Upgrade Go</a></li><li><a href="https://docs.deviceatlas.com/apis/clientside/latest/README.ClientSide.html" target="_blank">Client-side component</a></li><li class="divider"></li><li><a href="./ApiDocs/index.html">C ApiDocs</a></li><li><a href="./ApiCppDocs/index.html">C ++ interface ApiDocs</a></li><li><a href="./Go-ApiDocs/carrier.html">Go ApiDocs Carrier</a></li><li><a href="./Go-ApiDocs/device.html">Go ApiDocs Device</a></li></ul></div>